PHP Manual

# Manuel PHP

2026-06-27
par:
Frédéric Blanc Traducteur
Vincent Blanchon Traducteur
Pierrick Charron Traducteur
Julien Pauli Traducteur
Mickaël Perraud Relecteur
Guillaume Plessis Traducteur
Yannick Torrès Traducteur
par:
Mehdi Achour
Vincent Briet
Jean-Sébastien Goupil
David Manusset
Damien Seguy

# Copyright

Copyright © 1997 - 2026 par le PHP Documentation Group. Ce document ne peut être redistribué qu'aux termes et aux conditions mentionnés dans la licence Creative Commons Attribution 3.0 ou plus récente. Une copie de la licence Creative Commons Attribution 3.0 est distribuée avec ce manuel. La dernière version est disponible à » http://creativecommons.org/licenses/by/3.0/.

# Manuel PHP

# À propos de ce manuel

PHP, acronyme récursif pour PHP: Hypertext Preprocessor, est un langage de script open source généraliste, largement utilisé, particulièrement adapté au développement web et pouvant être intégré au HTML. Sa syntaxe est empruntée aux langages C, Java et Perl, et est facile à apprendre. Le but principal de ce langage est de permettre aux développeurs web d'écrire des pages générées dynamiquement rapidement, mais il est possible de faire beaucoup plus avec PHP.

Ce manuel est essentiellement une référence des fonctions, mais il contient aussi des informations de référence sur le langage, des explications sur les fonctionnalités principales de PHP et diverses informations supplémentaires.

Ce manuel inclut des informations couvrant les deux versions majeures les plus récentes de PHP (versions 7 et 8). Les informations concernant les extensions qui ne sont plus incluses avec ces versions de PHP et les modifications des fonctions dans les versions antérieures ne sont pas incluses. Des archives des versions plus anciennes du manuel qui documentent les précédentes versions de PHP sont disponibles dans la section "Plus de documentation" sur la » page "Documentation" du site web PHP.

Il est possible de télécharger ce manuel sous divers formats, sur » https://www.php.net/download-docs.php. Plus d'informations sur le développement de ce manuel sont disponibles dans l'appendice À propos du manuel. Pour en savoir plus sur l'histoire de PHP, consulter l'appendice correspondant.

# Auteurs et Contributeurs

Nous mettons en avant les personnes les plus actives dans la préface du manuel mais il y a bien plus de contributeurs qui nous aident actuellement dans notre travail ou qui ont fournis une aide précieuse au projet dans le passé. Il y a beaucoup d'inconnus qui nous ont aidés à travers leurs notes concernant les pages du manuel qui sont continuellement incluses dans le manuel, travail dont nous sommes très reconnaissants. La liste fournie ci-dessous est classée par ordre alphabétique.

# Auteurs et Éditeurs

Les contributeurs suivants ont eu un impact énorme en ajoutant du contenu dans le manuel : Mehdi Achour, Bill Abt, Jouni Ahto, Alexander Aulbach, Stig Bakken, George Peter Banyard, Christoph M. Becker, Daniel Beckham, Friedhelm Betz, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Antony Dovgal, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Nuno Lopes, Hannes Magnusson, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Philip Olson, Richard Quadling, Derick Rethans, Rob Richards, Georg Richter, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Damien Seguy, Masahiro Takagi, Yoshinari Takaoka, Yannick Torres, Jakub Vrana, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar et Andrei Zmievski.

Les contributeurs suivants ont énormément aidé dans l'édition du manuel : Stig Bakken, Peter Cowburn, Gabor Hojtsy, Hartmut Holzgraefe, Philip Olson et Egon Schmid.

# Mainteneurs des notes utilisateurs

Les mainteneurs actuellement les plus actifs sont : Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda et Maciek Sokolewicz.

Ces personnes ont également déployé énormément d'efforts dans le maintien des notes utilisateurs : Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles et Jeroen van Wolffelaar.

# Au moment de commencer

# Qu'est-ce que PHP et que peut-il faire ?

# Qu'est-ce que PHP ?

PHP (officiellement, ce sigle est un acronyme récursif pour PHP Hypertext Preprocessor) est un langage de scripts généraliste et Open Source, spécialement conçu pour le développement d'applications web. Il peut être intégré facilement au HTML.

Bien... mais qu'est-ce que cela veut dire ? Un exemple :

Exemple #1 Exemple d'introduction

    <!DOCTYPE html>
    <html>
    <head>
    <title>Exemple</title>
    </head>
    <body>

    <?php
    echo "Bonjour, je suis un script PHP !";
    ?>

    </body>
    </html>

Au lieu d'utiliser des tonnes de commandes afin d'afficher du HTML (comme en C ou en Perl), les pages PHP contiennent des fragments HTML dont du code qui fait "quelque chose" (dans ce cas, il va afficher "Bonjour, je suis un script PHP !"). Le code PHP est inclus entre une balise de début `<?php` et une balise de fin `?>` qui permettent au serveur web de passer en mode PHP.

Ce qui distingue PHP des langages de script comme le Javascript, est que le code est exécuté sur le serveur, générant ainsi le HTML, qui sera ensuite envoyé au client. Le client ne reçoit que le résultat du script, sans aucun moyen d'avoir accès au code qui a produit ce résultat. Il est même possible de configurer le serveur web afin qu'il analyse tous les fichiers HTML comme des fichiers PHP. Ainsi, il n'y a aucun moyen pour les utilisateurs de savoir que PHP est utilisé.

Le grand avantage de PHP est qu'il est extrêmement simple pour les néophytes, mais offre des fonctionnalités avancées pour les experts. Il ne faut pas se laisser effrayer par la longue liste de fonctionnalités PHP. Avec PHP, presque tout le monde peut commencer rapidement et écrire des scripts simples en un rien de temps.

Bien que le développement de PHP soit orienté vers la programmation pour les sites web, on peut faire bien plus avec PHP. Consulter la section Que peut faire PHP ? ou bien le tutoriel d'introduction pour passer directement à l'apprentissage de la programmation web.

# Que peut faire PHP ?

Tout. PHP est principalement conçu pour servir de langage de script côté serveur, il peut donc faire tout ce qu'un autre programme CGI peut faire, comme collecter des données de formulaire, générer du contenu dynamique, ou gérer des cookies. Mais PHP peut en faire bien plus.

Il y a deux domaines différents où PHP peut s'illustrer.

- Langage de script côté serveur. C'est l'utilisation la plus traditionnelle, et aussi le principal objet de PHP. Trois composants sont nécessaires pour l'exploiter : un analyseur PHP (CGI ou module serveur), un serveur web et un navigateur web. Tout ceci peut fonctionner sur une machine locale juste pour expérimenter la programmation PHP. Voir la section d'installation pour plus d'informations.
- Langage de programmation en ligne de commande. Un script PHP peut être exécuté en ligne de commande, sans l'aide du serveur web et d'un navigateur. Il suffit de disposer de l'exécutable PHP. Cette utilisation est idéale pour les scripts qui sont exécutés régulièrement avec un cron (sous Unix ou macOS) ou le Planificateur de tâches (sous Windows). Ces scripts peuvent aussi être utilisés pour réaliser des opérations sur des fichiers texte. Voir la section sur l'utilisation de PHP en ligne de commande pour plus d'informations.

PHP est utilisable sur la majorité des systèmes d'exploitation, comme Linux, de nombreuses variantes Unix (incluant HP-UX, Solaris et OpenBSD), Microsoft Windows, macOS, RISC OS et d'autres encore. PHP supporte aussi la plupart des serveurs web actuels dont Apache, IIS et bien d'autres. Et ceci inclut tous les serveurs web qui peuvent utiliser le binaire PHP FastCGI, comme lighttpd et nginx. PHP fonctionne sous forme de module, ou comme processeur CGI.

Avec PHP, les développeurs ont le choix du système d'exploitation et du serveur web. De plus, ils ont aussi le choix d'utiliser la programmation procédurale ou objet (OOP), ou encore un mélange des deux.

PHP ne se limite pas à la production de code HTML. Ses capacités incluent la création de types de fichiers riches, tels que des images ou des fichiers PDF, le chiffrement de données et l'envoi d'e-mails. Il peut également facilement générer n'importe quel texte, tel que JSON ou XML. PHP peut générer automatiquement ces fichiers et les enregistrer dans le système de fichiers au lieu de les imprimer, formant ainsi un cache côté serveur pour le contenu dynamique.

Une des forces les plus significatives de PHP est qu'il supporte énormément de bases de données. Écrire une page web faisant appel à une base de données devient terriblement simple, en utilisant une des extensions spécifiques aux bases de données (par exemple pour mysql), ou utilisant une couche d'abstraction comme PDO, ou une connexion à n'importe quelle base de données supportant le standard Open Database Connection via l'extension ODBC. Les autres bases de données peuvent utiliser l'extension cURL ou sockets comme CouchDB.

PHP supporte de nombreux protocoles comme LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (sous Windows) et encore d'autres. Il peut aussi ouvrir des sockets réseau, et interagir avec n'importe quel autre protocole. PHP supporte le format d'échange de données complexes WDDX, permettant de communiquer entre pratiquement tous les langages de programmation web. En termes d'interconnexion, PHP supporte aussi les objets Java, et les utilise de manière transparente comme objets intégrés.

PHP possède des fonctionnalités utiles dans le traitement de texte, incluant les expressions régulières compatibles Perl (PCRE), ainsi que bon nombre d'extensions et d'utilitaires pour analyser et accéder aux documents XML. PHP standardise toutes les extensions XML sur la solide base de libxml2, et étend le jeu de fonctionnalités en ajoutant le support de SimpleXML, XMLReader et XMLWriter.

Beaucoup d'autres extensions existent, catégorisées alphabétiquement et par catégorie. Et enfin, il existe des extensions PECL qui peuvent (ou pas) être documentées dans le manuel PHP, comme » XDebug.

Cette page ne suffit pas pour lister toutes les fonctionnalités et avantages que PHP peut offrir. Consulter la section sur l'installation de PHP et la référence des fonctions pour des explications sur les extensions mentionnées ici.

# Une introduction à PHP

## Sommaire

- La première page PHP
- Trucs pratiques
- Utiliser un formulaire
- Et après ?

Dans cette section, nous voulons illustrer les principes de base de PHP dans une courte introduction. Ce chapitre traite uniquement de création de pages web dynamiques avec PHP, laissant de côté temporairement les autres possibilités de PHP. Voir la section Ce que peut faire PHP pour plus d'informations.

Les pages web qui exploitent PHP sont traitées comme des pages HTML standards, et il est possible de les créer, éditer et effacer de la même façon qu'avec des pages HTML classiques.

# La première page PHP

Ce tutoriel suppose que PHP est déjà installé. Les instructions d'installation sont disponibles sur la » page de téléchargement.

Créer un fichier appelé hello.php avec le contenu suivant :

Exemple #1 Notre premier script PHP : hello.php

    <?php

    echo "Hello World!";

    ?>

Depuis le terminal, il faut se rendre dans le répertoire contenant ce fichier et démarrer un serveur de développement avec la commande suivante :

    php -S localhost:8000

Il faut utiliser un navigateur pour accéder au fichier en utilisant l'URL du serveur web, se terminant avec la référence au fichier `/hello.php`. Selon la commande précédente exécutée, l'URL sera `http://localhost:8000/hello.php`. Si tout est configuré correctement, ce fichier sera analysé par PHP et la sortie "Hello World!" sera affichée dans le navigateur.

PHP peut être intégré dans une page web HTML normale. Cela signifie que, dans le document HTML, il est possible d'écrire des instructions PHP, comme démontré dans l'exemple suivant :

    <!DOCTYPE html>
    <html>
        <head>
            <title>Test PHP</title>
        </head>
        <body>
            <?php echo '<p>Bonjour le monde</p>'; ?>
        </body>
    </html>

Cela produira le résultat suivant :

    <!DOCTYPE html>
    <html>
        <head>
            <title>Test PHP</title>
        </head>
        <body>
            <p>Bonjour le monde</p>
        </body>
    </html>

Ce programme est extrêmement simple et PHP n'est pas nécessaire pour créer une page web comme ceci. Elle ne fait qu'afficher `Bonjour le monde`, grâce à la fonction echo de PHP. Il est à noter que ce fichier n'a pas besoin d'être exécutable ou autre, dans aucun cas. Le serveur sait que ce fichier a besoin d'être interprété par PHP, car l'extension ".php" est utilisée, et le serveur est configuré pour les passer à PHP. Il s'agit d'une page HTML normale qui contient une série de balises spéciales qui permettent de réaliser beaucoup de choses intéressantes.

Le point important de cet exemple était de montrer le format des balises spéciales PHP. Nous avons utilisé ici `<?php` pour indiquer le début de la balise PHP. Puis, nous avons introduit les commandes PHP et refermé les balises PHP avec `?>`. Il est possible de passer du mode PHP au mode HTML et vice-versa, de cette manière, à volonté. Pour plus d'informations, consulter la section du manuel sur la syntaxe basique de PHP.

> Note: Une note sur les retours à la ligne

> Les retours à la ligne ont une signification minime en HTML, cependant, c'est toujours une bonne idée de rendre le HTML aussi joli et propre que possible en y ajoutant des retours à la ligne. Un retour à la ligne suivant immédiatement une balise de fermeture PHP (`?>`) sera supprimé par PHP. Ceci peut être vraiment très utile lors de l'insertion de plusieurs blocs PHP ou fichiers inclus contenant du PHP qui n'est pas supposé afficher quoi que ce soit. En même temps, ce peut être confus. Il est possible d'ajouter un espace après la balise fermante PHP (`?>`) pour forcer l'espace et un retour à la ligne à afficher, ou d'ajouter explicitement un retour à la ligne dans le dernier echo/print du bloc PHP.

> Note: Une note sur les éditeurs de texte

> Il existe de nombreux éditeurs de texte et environnements de développement (IDE) utilisables pour créer, éditer et gérer des applications PHP. Une liste partielle de ces outils est entretenue à l'adresse » PHP Editor's List. Pour recommander un éditeur particulier, il suffit de visiter cette page et de demander au webmestre de l'ajouter. Avoir au minimum un éditeur de texte avec la coloration syntaxique peut être utile.

> Note: Une note sur les traitements de texte

> Les traitements de texte tels que StarOffice Writer, Microsoft Word et Abiword sont de très mauvais choix pour éditer des scripts PHP. Pour utiliser l'un d'entre eux malgré tout pour tester des scripts, il faut s'assurer de sauver les fichiers au format texte seul (plain text) : sinon, PHP ne sera pas capable de lire et d'exécuter ces scripts.

Maintenant que le script PHP précédent fonctionne, c'est le moment de créer le plus célèbre script PHP ! Un appel à la fonction phpinfo() affichera beaucoup d'informations intéressantes sur le système et sa configuration comme les variables pré-définies disponibles, les modules PHP chargés ainsi que la configuration. Prendre le temps de revoir ces informations importantes.

Exemple #2 Récupération des informations du système à partir de PHP

    <?php

    phpinfo();

    ?>

# Trucs pratiques

Réalisons maintenant quelque chose de plus utile. Nous allons vérifier le type de navigateur que le visiteur de notre site utilise. Pour cela, nous allons accéder aux informations que le navigateur du visiteur nous envoie, lors de sa requête HTTP. Cette information est stockée dans une variable. Les variables sont faciles à repérer, car elles commencent toutes par un signe dollar. La variable qui nous intéresse ici est $_SERVER['HTTP_USER_AGENT'].

> Note:

> $_SERVER est une variable spéciale de PHP, qui contient toutes les informations relatives au serveur web. C'est une variable réservée de PHP, et une superglobale. Se reporter aux pages du manuel traitant des Auto-globales (aussi connues sous le nom de super-globales).

Pour afficher cette variable, nous pouvons simplement faire :

Exemple #1 Afficher le contenu d'une variable (élément de tableau)

    <?php

    echo $_SERVER['HTTP_USER_AGENT'];

    ?>

Un résultat possible du script pourra alors être :

    Mozilla/5.0 (Linux) Firefox/112.0

Il y a de nombreux types de variables disponibles en PHP. Dans l'exemple ci-dessus, nous avons affiché un élément d'une variable Tableau (Array). Les tableaux peuvent être très utiles.

$_SERVER est juste une variable qui est automatiquement disponible dans le script. Une liste de toutes les variables qui sont rendues disponibles est fournie dans la section Variables réservées ; il est également possible d'en obtenir une liste complète en lisant l'affichage de la fonction phpinfo() utilisée dans l'exemple de la section précédente.

Il est possible d'ajouter plusieurs commandes PHP dans une balise PHP, et créer de petits blocs de code qui réalisent des opérations plus complexes qu'un simple affichage. Par exemple, si nous voulons vérifier que le navigateur est bien de la famille Firefox, nous pouvons faire cela :

Exemple #2 Exemple utilisant les structures de contrôle et les fonctions

    <?php

    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        echo 'Vous utilisez Firefox.';
    }

    ?>

Le résultat de ce script, avec Firefox, sera :

    Vous utilisez Firefox.

Ici, nous introduisons plusieurs nouveaux concepts. Nous avons une structure if. Les personnes familières avec les syntaxes de base du langage C ne seront pas surprises. Dans le cas contraire, il est recommandé de lire une introduction à PHP et d'assimiler les premiers chapitres, ou bien de consulter le chapitre consacré à la référence du langage.

Le second concept que nous avons introduit est la fonction str_contains(). str_contains() est une fonction intégrée à PHP, qui détermine la présence d'une chaîne donnée dans une autre. Dans notre cas, nous avons recherché la chaîne `"Firefox"` (appelée needle) dans $_SERVER['HTTP_USER_AGENT'] (appelée haystack). Si la chaîne recherchée est trouvée, la fonction retourne `true`. Sinon, elle retourne `false`. Si elle retourne `true`, la structure if s'évalue à `true` et le code entre accolades {} est exécuté. Sinon, le code n'est pas exécuté. Il est recommandé d'expérimenter d'autres exemples, à l'aide de if, else, et d'autres fonctions comme strtoupper() et strlen(). Chaque page de la documentation contient aussi des exemples. En cas de doute sur l'utilisation de ces fonctions, il est recommandé de lire la page du manuel "comment lire une définition de fonction" ainsi que la section sur les fonctions PHP.

Il est maintenant possible de progresser et de montrer comment passer entre les modes PHP et HTML, au milieu d'un bloc PHP :

Exemple #3 Passer du mode PHP au mode HTML et vice-versa

    <?php
    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        ?>
        <h3>str_contains() a retourné true</h3>
        <p>Vous utilisez Firefox</p>
        <?php
    } else {
        ?>
        <h3>str_contains() a retourné false</h3>
        <p>Vous n'utilisez pas Firefox</p>
        <?php
    }
    ?>

Un exemple de résultat obtenu dans ce script est :

    <h3>str_contains() a retourné true</h3>
    <p>Vous utilisez Firefox</p>

Au lieu d'utiliser une commande echo pour afficher du texte, il est possible d'utiliser du code HTML pur. Le point important à noter ici est que la logique de programmation est conservée. Seul un des deux blocs HTML sera affiché, suivant le résultat de la fonction str_contains(). En d'autres termes, cela dépend si la chaîne `Firefox` a été trouvée ou non.

# Utiliser un formulaire

L'un des points forts de PHP est sa capacité à gérer les formulaires. Le concept de base qui est important à comprendre est que tous les champs d'un formulaire seront automatiquement disponibles dans le script PHP d'action. Consulter le chapitre du manuel concernant les variables depuis des sources externes à PHP pour plus d'informations et d'exemples sur la façon d'utiliser les formulaires. Voici un exemple de formulaire HTML :

Exemple #1 Un simple formulaire HTML

    <form action="action.php" method="post">
       <label for="nom">Votre nom :</label>
       <input name="nom" id="nom" type="text">

       <label for="age">Votre âge :</label>
       <input name="age" id="age" type="number">

       <button type="submit">Valider</button>
    </form>

Il n'y a rien de particulier dans ce formulaire. Il est en HTML pur, sans aucune configuration particulière. Lorsque le visiteur remplit le formulaire et clique sur le bouton Valider, le fichier action.php est appelé. Dans ce fichier, il est possible d'écrire le script suivant :

Exemple #2 Afficher des données issues d'un formulaire

    Bonjour, <?php echo htmlspecialchars($_POST['nom']); ?>.
    Tu as <?php echo (int) $_POST['age']; ?> ans.

Voici le résultat possible, selon les valeurs saisies :

    Bonjour, Jean.
    Tu as 29 ans.

Mis à part les parties htmlspecialchars() et `(int)`, ce script ne fait que des choses évidentes. htmlspecialchars() s'assure que tous les caractères spéciaux HTML sont proprement encodés afin d'éviter des injections de balises HTML et de Javascript dans les pages. Pour l'âge, vu que c'est un entier, il est possible de le convertir en un entier. PHP peut également le faire automatiquement en utilisant l'extension filter. Les variables $_POST['nom'] et $_POST['age'] sont automatiquement créées par PHP. Un peu plus tôt dans ce tutoriel, nous avons utilisé la variable $_SERVER, une superglobale. Maintenant, nous avons introduit une autre superglobale $_POST qui contient toutes les données envoyées par la méthode POST. Il est à noter que dans notre formulaire, nous avons choisi la méthode POST. Si nous avions utilisé la méthode GET alors notre formulaire aurait placé ces informations dans la variable $_GET, une autre superglobale. Il est également possible d'utiliser la variable $_REQUEST, pour ne pas se soucier de la source des données. Elle contient un mélange des données de GET, POST et COOKIE.

# Et après ?

Avec ces nouvelles connaissances, il devrait être possible de comprendre l'essentiel du manuel.

En particulier, il est possible d'explorer les fonctionnalités suivantes :

- Lecture et écriture de fichiers avec les fonctions du système de fichiers
- Gestion des envois de fichiers
- Récupération de pages et de fichiers distants avec Curl
- Stockage et analyse de données dans une base de données avec PDO (SQLite peut être utilisé sans avoir à exécuter un serveur de base de données)
- Persistance des données entre les requêtes avec les sessions

Le » dépôt Packagist regorge de bibliothèques et de » frameworks pour toutes les occasions, tous installables via le gestionnaire de paquets Composer.

Pour de l'aide et des conseils de la communauté, voir la » page d'aide.

Pour des podcasts, présentations et autres vidéos, voir le » PeerTube communautaire.

D'autres ressources communautaires utiles incluent les « awesome lists » (répertoires curés de liens) et les « developer roadmaps » (listes de sujets liés).

Lorsqu'il n'est pas évident de savoir par où commencer, il est utile de décomposer le projet ou le problème en parties plus petites, ce qui permet de mieux distinguer ce qui est déjà maîtrisé et ce qui reste à apprendre. La liste peut être aussi détaillée que nécessaire. Par exemple, la construction d'un blog peut se décomposer ainsi :

- Liste et affichage des pages
  - Lecture d'enregistrements (pages) depuis une base de données
- Création de pages
  - Traitement de la soumission de formulaire
  - Écriture d'enregistrements (pages) dans une base de données
- Connexion administrateur
  - Lecture d'enregistrements (utilisateurs) depuis une base de données
  - Gestion des mots de passe
  - Persistance des données (connexion utilisateur) entre les requêtes / pages (sessions)

S'il n'y a rien de particulier à construire, il est possible de chercher des exercices de code comme des katas, des défis et du « code golf ». Même s'ils ne ciblent pas spécifiquement PHP, la plupart devraient être réalisables et mettront probablement à l'épreuve les connaissances et la réflexion.

- Introduction — Qu'est-ce que PHP et que peut-il faire ?
- Une introduction à PHP
  - La première page PHP
  - Trucs pratiques
  - Utiliser un formulaire
  - Et après ?

# Installation et configuration

# Considérations générales sur l'installation

Avant d'installer PHP, il faut savoir ce que l'on souhaite faire avec PHP. Il y a deux cas d'utilisation décrits dans la section Que peut faire PHP ? :

- Sites Web et applications Web (script côté serveur)
- Scripts en ligne de commande

Pour la première tâche, qui est de loin la plus répandue, trois choses sont nécessaires : PHP lui-même, un serveur Web et un navigateur. En fonction du système d'exploitation, il est possible de disposer d'un serveur Web (par exemple Apache sous Linux et macOS ou IIS sous Windows). Il est aussi possible de louer un espace à une société. De cette façon, il n'est pas nécessaire de mettre en place PHP, mais uniquement d'écrire les scripts, les charger sur le serveur et voir le résultat dans le navigateur.

Lors de l'installation de PHP et du serveur soi-même, il y a deux choix. Soit sous la forme d'un module du serveur Web (via une interface directe appelée SAPI). Les serveurs qui supportent cette solution comptent notamment Apache, Microsoft Internet Information Server, Netscape et les serveurs iPlanet. Si PHP ne supporte pas l'interface de module du serveur Web, il est toujours possible de l'utiliser comme processeur CGI ou FastCGI. Cela signifie qu'il faut configurer le serveur pour qu'il utilise l'exécutable CGI de PHP, pour qu'il traite les fichiers PHP sur le serveur.

Pour utiliser PHP en ligne de commande (écrire des scripts de génération d'image hors ligne, par exemple, ou bien traiter des textes en fonction d'informations fournies), un exécutable PHP est nécessaire. Pour plus de détails, consulter la section écrire des applications PHP en ligne de commande. Dans ce cas, il n'est pas nécessaire d'avoir un serveur Web, ni un navigateur.

À partir de maintenant, cette section décrit l'installation de PHP avec un serveur Web sous Unix et Windows, sous forme de module ou d'exécutables CGI.

Les codes source et les distributions binaires de PHP pour Windows sont disponibles à » https://www.php.net/downloads.php.

# Installation sur les systèmes Unix

## Sommaire

- Installation à partir de paquets sur Debian GNU/Linux et distributions similaires
- Installation depuis les paquets sur les distributions GNU/Linux qui utilisent DNF
- Installation à partir de paquets ou de ports sur OpenBSD
- Installation depuis les sources sur les systèmes Unix et macOS
- CGI et configuration en ligne de commande
- Apache 2.x sur les systèmes Unix
- Nginx 1.4.x sur les systèmes Unix
- Lighttpd 1.4 sur les systèmes Unix
- Serveur Web LiteSpeed/Serveur Web OpenLiteSpeed sur les systèmes Unix
- Installation sous Solaris

La plupart des systèmes d'exploitation Unix (et Linux) et des distributions proposent une version empaquetée de PHP et des extensions disponibles via leur système de gestion de paquets. Il y a des sections avec des informations de base sur l'installation de PHP en utilisant ces systèmes.

Pour certaines distributions, il existe également des dépôts tiers de paquets qui incluent généralement une plus grande variété de versions et d'extensions disponibles.

PHP peut également être installé comme un composant de certains serveurs d'applications tiers .

Enfin, PHP peut toujours être installé à partir des distributions sources, ce qui offre la plus grande flexibilité pour choisir les fonctionnalités, les extensions et les API de serveur à activer. Il existe des sections contenant des informations sur la compilation et la configuration de PHP à utiliser avec différentes API de serveur en particulier.

## Installation à partir de paquets sur Debian GNU/Linux et distributions similaires

Bien que PHP puisse être installé à partir du code source, il est également disponible via des paquets provenant de » Debian GNU/Linux. Cela est également vrai pour d'autres distributions basées sur Debian, telles que Ubuntu, Kali Linux et Linux Mint.

Avertissement

Les versions provenant de tiers sont considérées comme non officielles et ne sont pas directement prises en charge par le projet PHP. Tout bogue rencontré doit être signalé au fournisseur de ces versions non officielles, sauf s'il peut être reproduit à l'aide des versions provenant de » la zone de téléchargement officielle.

Les paquets peuvent être installés en utilisant soit la commande apt soit la commande aptitude. Cette page de manuel utilise ces deux commandes de manière interchangeable.

### Utilisation de APT

Tout d'abord, il est à noter que d'autres paquets peuvent être souhaitables, comme `libapache-mod-php` pour l'intégration avec Apache 2, et `php-pear` pour PEAR.

Ensuite, avant d'installer un paquet, il est sage de s'assurer que la liste des paquets est à jour. D'habitude, on le fait en utilisant la commande apt update.

Exemple #1 Exemple d'installation sous Debian avec Apache 2

    # apt install php-common libapache2-mod-php php-cli

APT installera et activera automatiquement le module PHP pour Apache 2, ainsi que toutes ses dépendances. Apache devra être relancé pour que les changements soient effectifs. Par exemple :

Exemple #2 Stopper et démarrer Apache une fois PHP installé

    # /etc/init.d/apache2 stop
    # /etc/init.d/apache2 start

### Un meilleur contrôle de la configuration

Dans l'exemple précédent, PHP a été installé avec juste les composants principaux. Il y a fort à parier que des modules supplémentaires soient nécessaires, tels que MySQL, cURL, GD, etc. Ils peuvent aussi être installés via la commande apt.

Exemple #3 Méthodes pour lister les paquets PHP supplémentaires

    # apt-cache search php
    # apt search php | grep -i mysql
    # aptitude search php

La liste des paquets comprendra un grand nombre de paquets incluant les composants de base de PHP, tels que `php-cgi`, `php-cli`, et `php-dev`, ainsi que de nombreuses extensions PHP. Lors de l'installation des extensions, des paquets supplémentaires seront installés automatiquement si nécessaire pour satisfaire les dépendances de ces paquets.

Exemple #4 Installer PHP avec MySQL et cURL

    # apt install php-mysql php-curl

APT ajoutera automatiquement les bonnes lignes aux fichiers connexes à php.ini, comme /etc/php/7.4/php.ini, /etc/php/7.4/conf.d/*.ini, etc. et selon l'extension, il ajoutera des entrées semblables à `extension=foo.so`. De plus, redémarrer le serveur web (Apache, par exemple) est nécessaire pour que ces changements soient effectifs.

### Problèmes courants

- Si les scripts PHP ne sont pas interprétés par le serveur web, il est probable que PHP n'ait pas été ajouté aux fichiers de configuration du serveur web, c'est-à-dire, sous Debian, /etc/apache2/apache2.conf ou équivalent. Consulter le manuel Debian pour davantage de détails.
- Si une extension a apparemment été installée mais que ses fonctions ne sont pas définies, il faut s'assurer que les lignes adéquates ont été insérées dans les fichiers .ini et/ou que le serveur web a été redémarré après l'installation.

## Installation depuis les paquets sur les distributions GNU/Linux qui utilisent DNF

Tandis que PHP peut être installé depuis les sources, il est également disponible via des paquets sur les systèmes qui utilisent DNF, tels que Red Hat Enterprise Linux, OpenSUSE, Fedora, CentOS, Rocky Linux et Oracle Enterprise Linux.

Avertissement

Les versions provenant de tiers sont considérées comme non officielles et ne sont pas directement prises en charge par le projet PHP. Tout bogue rencontré doit être signalé au fournisseur de ces versions non officielles, sauf s'il peut être reproduit à l'aide des versions provenant de » la zone de téléchargement officielle.

Les paquets peuvent être installés en utilisant la commande dnf.

### Installation des paquets

Pour commencer, il est important de noter que d'autres paquets liés peuvent être souhaités, comme `php-pear` pour » PEAR, ou `php-mysqlnd` pour l'extension MySQL.

Ensuite, avant d'installer un paquet, il est sage de s'assurer que la liste des paquets est à jour. Typiquement, cela se fait en exécutant la commande dnf update.

Exemple #1 Exemple d'installation DNF

    # dnf install php php-common

DNF installera automatiquement la configuration pour PHP pour le serveur web, mais il peut être nécessaire de le redémarrer pour que les changements prennent effet. Par exemple :

Exemple #2 Redémarrage d'Apache une fois PHP installé

    # sudo systemctl restart httpd

### Meilleur contrôle de la configuration

Dans la dernière section, PHP a été installé avec seulement les modules de base. Il est très probable que des modules supplémentaires seront souhaités, tels que MySQL, cURL, GD, etc. Ceux-ci peuvent également être installés via la commande dnf.

Exemple #3 Méthodes pour lister des paquets PHP supplémentaires

    # dnf search php

La liste des paquets inclura un grand nombre de paquets qui comprend des composants PHP de base, tels que `php-cli`, `php-fpm` et `php-devel`, ainsi que de nombreuses extensions PHP. Lorsque des extensions sont installées, des paquets supplémentaires seront automatiquement installés si nécessaire pour satisfaire les dépendances de ces paquets.

Exemple #4 Installation de PHP avec MySQL, GD

    # dnf install php-mysqlnd php-gd

DNF va automatiquement ajouter les lignes appropriées aux différents fichiers liés à php.ini, comme /etc/php/8.3/php.ini, /etc/php/8.3/conf.d/*.ini, etc. et en fonction de l'extension ajoutera des entrées similaires à `extension=foo.so`. Cependant il est nécessaire de redémarrer le serveur web (comme Apache) avant que ces changements prennent effet.

## Installation à partir de paquets ou de ports sur OpenBSD

Cette section contient les notes spécifiques à l'installation de PHP sous » OpenBSD.

### Utilisation des paquets binaires

Cette méthode est la méthode recommandée pour installer PHP sur OpenBSD. C'est aussi la méthode la plus simple. Le paquet core a été séparé des modules et chacun d'entre eux peut être installé et supprimé indépendamment des autres. Les fichiers nécessaires sont sur le CD OpenBSD ou sur le site FTP.

Le paquet principal à installer est php, qui contient le moteur de base (en plus de fpm, gettext et iconv) et pourrait être disponible sous plusieurs versions au choix. Puis, jeter un œil aux paquets de module, comme php-mysqli ou php-imap. Il faut utiliser la commande phpxs pour activer et désactiver ces modules dans le php.ini.

Exemple #1 Exemple d'installation de paquet PHP sous OpenBSD

    # pkg_add php
    # pkg_add php-apache
    # pkg_add php-mysqli
      (installer les bibliothèques PEAR)
    # pkg_add pear

    Suivre les instructions affichées avec chaque paquet !

      (pour supprimer des paquets)
    # pkg_delete php
    # pkg_delete php-apache
    # pkg_delete php-mysqli
    # pkg_delete pear

Lire la page de manuel Unix » packages(7) pour plus de détails sur les paquets binaires d'OpenBSD.

### Utilisation des ports

Il est aussi possible de compiler PHP en utilisant » l'arbre des ports. Cette méthode est recommandée aux utilisateurs expérimentés d'OpenBSD. Le port PHP est divisé en core et extensions. Les extensions génèrent les sous-paquets de tous les modules PHP supportés. Pour ne pas créer certains de ces modules, utiliser le FLAVOR no_*. Par exemple, pour ne pas compiler le module imap, définir le FLAVOR à no_imap.

### Problèmes courants

- Apache et Nginx ne sont plus le serveur par défaut sur OpenBSD, mais ils peuvent être facilement trouvés dans les ports et les packages. Le nouveau serveur par défaut est également appelé 'httpd'.
- L'installation par défaut de httpd fonctionne dans un » contexte chroot(2), qui va limiter l'accès des scripts PHP au dossier /var/www. Il faut donc créer un dossier /var/www/tmp pour que les sessions PHP soient stockées, ou bien utiliser une autre solution de sauvegarde. De plus, les sockets de bases de données doivent être placés dans ce dossier, ou bien utiliser l'interface localhost. Lors de l'utilisation de fonctions de réseau avec des fichiers comme /etc, par exemple /etc/resolv.conf, et /etc/services, il faut les rendre accessibles aussi dans /var/www/etc. Le paquet OpenBSD PEAR installe automatiquement les bons dossiers.
- Le paquet OpenBSD pour l'extension » gd requiert l'installation de Xorg. À moins d'avoir été déjà installé lors de l'installation de base en ajoutant le jeu de fichiers xbase.tgz, cela peut être ajouté après l'installation (voir » OpenBSD FAQ#4).

## Installation depuis les sources sur les systèmes Unix et macOS

Logiciels prérequis pour la compilation :

- » GNU make
- Un compilateur C (à partir de PHP 8.0.0, la compatibilité C99 est requise ; à partir de PHP 8.4.0, la compatibilité C11 est requise)
- Un serveur web
- Tout composant spécifique à un module (tels que les bibliothèques GD, PDF, etc.)

Lorsque la compilation est effectuée directement à partir des sources Git ou après des modifications personnalisées, ces outils supplémentaires peuvent être nécessaires :

- » autoconf:
  - PHP 7.3 et plus récent : 2.68+
  - PHP 7.2: 2.64+
  - PHP 7.1 et plus ancien : 2.59+
- » re2c:
  - PHP 8.3 et plus récent : 1.0.3+
  - PHP 8.2 et plus ancien : 0.13.4+
- » bison:
  - PHP 7.4 et plus récent : 3.0.0+
  - PHP 7.3 et plus ancien : 2.4+ (y compris Bison 3.x)

Pour plus de détails sur les étapes pour compiler PHP à partir des sources, voir le fichier » README.md dans l'archive source.

La configuration et le processus de compilation initial de PHP sont contrôlés par l'utilisation des options de ligne de commande du script configure. Une liste des options disponibles avec de courtes explications peut être affichée en exécutant ./configure --help. Ce manuel documente les différentes options séparément. Les options de base sont disponibles dans l'annexe, tandis que les différentes options spécifiques aux extensions sont décrites sur les pages de référence.

Une fois le script de configuration exécuté, PHP peut être construit en utilisant la commande make. La section Installation des questions fréquemment posées contient plus d'informations sur la gestion des problèmes de compilation.

> Note: Certains systèmes Unix (comme OpenBSD et SELinux) peuvent interdire le mapping de pages à la fois en écriture et exécution pour des raisons de sécurité, ce qui est appelé » PaX MPROTECT ou » protection contre les violations W^X. Ce genre de mappage mémoire est nécessaire pour le support JIT de PCRE, donc soit PHP doit être construit sans le support JIT de PCRE, soit le binaire doit être mis sur liste blanche par tous les moyens fournis par le système.

> Note: La compilation croisée pour ARM avec la chaîne d'outils Android n'est actuellement pas prise en charge.

## CGI et configuration en ligne de commande

Par défaut, PHP est construit comme programme à la fois CLI et CGI, pouvant être utilisé comme processeur CGI. Lors de l'utilisation d'un serveur qui supporte le module PHP, il est en général recommandé d'utiliser cette solution pour des raisons de performances. Cependant, la version CGI permet aux utilisateurs de lancer des pages PHP sous différents identifiants utilisateurs (Unix).

Avertissement

Un serveur déployé en mode CGI s'expose à plusieurs vulnérabilités possibles. Veuillez lire notre section sur la sécurité en mode CGI pour apprendre comment vous protéger contre ces attaques.

### Tests

Si PHP a été compilé comme programme CGI, il est possible de tester le produit en tapant : make test. C'est toujours une bonne chose de tester le résultat d'une compilation. Cela permet de repérer des problèmes entre PHP et la plate-forme, plutôt que d'attendre qu'ils surviennent.

### Utiliser les variables prédéfinies

Certaines variables d'environnement fournies par les serveurs Web ne sont pas disponibles dans les » spécifications CGI/1.1 actuelles. Seules les variables suivantes sont définies, et les autres doivent être considérées comme spécifiques aux serveurs Web : AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL et SERVER_SOFTWARE.

## Apache 2.x sur les systèmes Unix

Cette section contient les notes et conseils d'installation de PHP avec le serveur Apache 2.x sur les systèmes Unix.

Avertissement

Nous ne recommandons pas l'utilisation de PHP dans un environnement threadé MPM, avec Apache 2. Utilisez le mode prefork MPM, qui est le MPM par défaut pour Apache 2.0 et 2.2. Pour savoir pourquoi, lisez l'entrée de la FAQ correspondante à l'utilisation d'Apache 2 dans un environnement threadé MPM.

La » Documentation Apache est la meilleure source d'informations sur le serveur Apache 2.x. La plupart des informations sur les options d'installation d'Apache peut y être trouvée.

La version la plus récente du serveur HTTP Apache peut être obtenue depuis la » page de téléchargement d'Apache, et une version adaptée de PHP depuis les liens ci-dessus. Ce guide couvre uniquement les bases de fonctionnement d'Apache 2.x avec PHP. Pour plus d'informations, lire la » documentation Apache. Les numéros de version sont omis ici, pour s'assurer que les instructions ne soient pas incorrectes. Dans les exemples ci-dessous, 'NN' devra être remplacé par la version spécifique d'Apache à utiliser.

Il y a actuellement 2 versions d'Apache 2.x - 2.4 et 2.2. Il y a plusieurs raisons de choisir l'une plutôt que l'autre ; néanmoins, la version 2.4 est actuellement la dernière version disponible et c'est aussi celle qui est recommandée. Cependant, les instructions contenues dans ce guide devraient fonctionner pour la version 2.4 comme pour la version 2.2. Note : Apache httpd 2.2 est officiellement en fin de vie, il n'y aura plus de développement ni de correctif pour cette version.

1. Télécharger le serveur HTTP Apache depuis le site ci-dessus et le décompresser :

       tar -xzf httpd-2.x.NN.tar.gz

2. De la même façon, télécharger et décompresser les sources de PHP :

       tar -xzf php-NN.tar.gz

3. Compiler et installer Apache. Consulter la documentation sur l'installation d'Apache pour plus de détails quant à la compilation de ce logiciel.

       cd httpd-2_x_NN
       ./configure --enable-so
       make
       make install

4. Maintenant qu'Apache 2.x.NN est disponible sous /usr/local/apache2, le configurer avec le support pour le chargement de modules, ainsi que le MPM prefork standard. Pour tester l'installation, utiliser la procédure normale pour démarrer le serveur Apache, c.-à-d. :

       /usr/local/apache2/bin/apachectl start

   et l'arrêter pour continuer la configuration de PHP :

       /usr/local/apache2/bin/apachectl stop

5. Maintenant, configurer et compiler PHP. Ce sera à ce moment-là où il est possible de personnaliser PHP avec les diverses options disponibles, comme la liste des extensions à activer. Exécuter ./configure --help pour la liste des options disponibles. Dans notre exemple, nous effectuerons une configuration simple, avec Apache 2 et le support MySQL.

   Si Apache a été construit depuis les sources, tel que décrit ci-dessus, l'exemple suivant devrait être correct concernant les chemins vers apxs, mais si Apache a été installé d'une autre façon, il faut prendre en compte les spécificités et ajuster les chemins apxs en conséquence. Il est à noter que suivant les distributions, il peut être nécessaire de renommer apxs en apxs2.

       cd ../php-NN
       ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-pdo-mysql
       make
       make install

   En cas de modification des options de configuration après l'installation, il faut exécuter de nouveau les étapes configure, make et make install. Il suffit alors de redémarrer Apache pour que le nouveau module prenne effet. Une re-compilation d'Apache n'est pas nécessaire.

   Il est à noter que, sauf indications contraires, l'étape "make install" installera également » PEAR, mais aussi divers outils PHP comme phpize, PHP CLI et bien plus encore.

6. Configurer le fichier php.ini.

       cp php.ini-development /usr/local/lib/php.ini

   Il faut éditer le fichier .ini pour définir les options PHP. Pour placer ce fichier dans un autre répertoire, utiliser l'option `--with-config-file-path=/some/path` à l'étape 5.

   En cas d'utilisation du fichier php.ini-production, il faut s'assurer de lire la liste des modifications correspondante car il peut affecter considérablement la façon dont PHP fonctionnera.

7. Éditer le fichier httpd.conf pour charger le module PHP. Le chemin spécifié à droite de la chaîne LoadModule, doit correspondre au chemin système du module PHP. L'étape "make install" ci-dessus devrait avoir réalisé cette opération automatiquement, mais une simple vérification permettra de s'en assurer.

   Pour PHP 8:

       LoadModule php_module modules/libphp.so

   Pour PHP 7:

       LoadModule php7_module modules/libphp7.so

8. Configurer Apache pour analyser certaines extensions comme étant des scripts PHP. Par exemple, laisser Apache passer à PHP les fichiers dont l'extension est `.php`. Au lieu d'utiliser seulement la directive `AddType` d'Apache, nous souhaitons éviter tout risque potentiellement dangereux, lors d'un téléchargement et de la création de fichier comme exploit.php.jpg, d'être exécutés par PHP. En utilisant cet exemple, il est possible d'avoir n'importe quelle extension analysée par PHP. Nous avons ajouté `.php` pour l'exemple.

       <FilesMatch \.php$>
           SetHandler application/x-httpd-php
       </FilesMatch>

   Ou, pour autoriser les fichiers `.php`, `.php2`, `.php3`, `.php4`, `.php5`, `.php6`, et `.phtml` à être analysés par PHP, mais rien d'autre, nous utiliserons ceci :

       <FilesMatch "\.ph(p[2-6]?|tml)$">
           SetHandler application/x-httpd-php
       </FilesMatch>

   Et pour autoriser les fichiers `.phps` à être gérés par le filtre du code source de PHP, et ainsi, être affichés comme code source avec la coloration syntaxique, utiliser ceci :

       <FilesMatch "\.phps$">
           SetHandler application/x-httpd-php-source
       </FilesMatch>

   `mod_rewrite` peut être utilisé pour permettre à n'importe quel fichier `.php` d'être affiché comme code source avec coloration syntaxique, sans pour autant avoir besoin de le renommer ou de le copier avec une extension `.phps` :

       RewriteEngine On
       RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]

   Le filtre de code source PHP ne devrait pas être actif sur des systèmes de production, car il peut exposer du code confidentiel ou des informations sensibles contenues dans le code source.

9. Utiliser la procédure normale pour démarrer le serveur Apache, c.-à-d. :

       /usr/local/apache2/bin/apachectl start

   Ou

       service httpd restart

En ayant suivi les étapes précédentes, le serveur web est maintenant un Apache2 fonctionnel avec le support PHP comme module `SAPI`. Bien sûr, il y a une multitude d'autres options de configuration de disponibles avec Apache et PHP. Pour plus d'informations, entrer la commande ./configure --help dans l'arbre source correspondant.

Apache peut être compilé en mode multithreadé, en sélectionnant le MPM worker, plutôt que le standard MPM prefork. Ceci est fait en ajoutant l'option suivante à l'argument de la commande "./configure", à l'étape 3 ci-dessus :

    --with-mpm=worker

Cela ne devrait pas être entrepris sans être conscients des conséquences, et ayant au moins une juste compréhension de ce que cela implique. La documentation Apache concernant » MPM-Modules apportera d'importantes informations qui permettront de prendre une décision.

> Note:

> La FAQ Apache MultiViews traite de l'utilisation MultiViews avec PHP.

> Note:

> Pour compiler une version multithreadée d'Apache, le système cible doit supporter les threads. Dans ce cas, PHP doit également être construit avec Zend Thread Safety (ZTS). Sous cette configuration, toutes les extensions ne seront pas disponibles. La configuration recommandée est de compiler Apache avec le module MPM prefork par défaut.

## Nginx 1.4.x sur les systèmes Unix

Cette documentation couvre l'installation et la configuration de PHP avec PHP-FPM pour le serveur HTTP Nginx 1.4.x.

Ce guide suppose que Nginx a été compilé à partir des sources et donc tous les binaires et fichiers de configuration se trouvent dans `/usr/local/nginx`. Si ce n'est pas le cas et que Nginx a été obtenu par d'autres moyens, se référer au » Wiki de Nginx pour adapter ce manuel à la configuration utilisée.

Ce guide couvre les bases de la configuration du serveur Nginx afin de parvenir à servir une application PHP sur le port 80. Il est recommandé d'étudier les documentations de Nginx et de PHP-FPM afin d'optimiser l'installation.

Il est à noter que tout au long de cette documentation, les numéros de version ont été remplacés par un "x" pour s'assurer que cette dernière reste correcte dans l'avenir. Penser à les remplacer par le numéro de version approprié.

1. Il est recommandé de consulter la » documentation de Nginx afin de l'installer sur le système.

2. Récupérer et décompresser les sources de PHP :

       tar zxf php-x.x.x

3. Configurer et compiler PHP. Ce sera le moment où il sera possible de personnaliser PHP avec diverses options, comme les extensions à activer. Exécuter ./configure --help pour obtenir une liste des options disponibles. Dans notre exemple, nous effectuerons une configuration simple avec le support PHP-FPM et MySQLi.

       cd ../php-x.x.x
       ./configure --enable-fpm --with-mysqli
       make
       sudo make install

4. Récupérer et déplacer les fichiers de configuration dans les bons dossiers

       cp php.ini-development /usr/local/php/php.ini
       cp /usr/local/etc/php-fpm.d/www.conf.default /usr/local/etc/php-fpm.d/www.conf
       cp sapi/fpm/php-fpm /usr/local/bin

5. Il est important d'empêcher Nginx de passer les requêtes au backend PHP-FPM si le fichier n'existe pas, évitant ainsi les failles par injections arbitraires de scripts.

   Nous pouvons réaliser cela en définissant la directive de configuration cgi.fix_pathinfo à la valeur `0` dans le php.ini.

   Modifier php.ini :

       vim /usr/local/php/php.ini

   Trouver la directive `cgi.fix_pathinfo=` et la modifier comme ceci :

       cgi.fix_pathinfo=0

6. Le fichier php-fpm.conf doit être modifié pour spécifier que php-fpm doit être exécuté avec l'utilisateur www-data et le groupe www-data avant de démarrer le service :

       vim /usr/local/etc/php-fpm.d/www.conf

   Trouver et modifier ce qui suit :

       ; Unix user/group of processes
       ; Note: The user is mandatory. If the group is not set, the default user's group
       ;       will be used.
       user = www-data
       group = www-data

   Le service php-fpm peut maintenant être démarré :

       /usr/local/bin/php-fpm

   Ce guide ne va pas configurer php-fpm plus que cela ; pour la configuration avancée de php-fpm, consulter la documentation.

7. Nginx doit maintenant être configuré pour supporter l'analyse des applications PHP :

       vim /usr/local/nginx/conf/nginx.conf

   Modifier le bloc par défaut afin qu'il puisse servir des fichiers .php :

       location / {
           root   html;
           index  index.php index.html index.htm;
       }

   La prochaine étape permet d'assurer que les fichiers .php soient passés au backend PHP-FPM. Sous le bloc PHP commenté par défaut, entrer :

       location ~* \.php$ {
           fastcgi_index   index.php;
           fastcgi_pass    127.0.0.1:9000;
           include         fastcgi_params;
           fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
           fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
       }

   Redémarrer Nginx.

       sudo /usr/local/nginx/sbin/nginx -s stop
       sudo /usr/local/nginx/sbin/nginx

8. Créer un fichier de test

       rm /usr/local/nginx/html/index.html
       echo "<?php phpinfo(); ?>" >> /usr/local/nginx/html/index.php

   Maintenant, naviguer vers http://localhost. Le phpinfo() devrait maintenant être affiché.

En suivant ces différentes étapes, le résultat devrait être un serveur web Nginx avec le support de PHP comme module `FPM` `SAPI`. Bien entendu, il y a beaucoup plus d'options de configuration disponibles pour Nginx et PHP. Pour plus d'informations, taper ./configure --help dans la source correspondante.

## Lighttpd 1.4 sur les systèmes Unix

Cette section contient des informations spécifiques sur l'installation de PHP avec Lighttpd 1.4 sur les systèmes Unix.

Se reporter à » Lighttpd pour une installation correcte de Lighttpd avant de continuer.

FastCGI est le SAPI préféré pour connecter PHP et Lighttpd. FastCGI est activé automatiquement dans php-cgi.

### Appel de PHP par Lighttpd

Pour configurer Lighttpd afin qu'il se connecte à PHP et appelle le processus FastCGI, il faut éditer le fichier lighttpd.conf. Une connexion par sockets est la solution préférée pour les systèmes locaux.

Exemple #1 Portion du fichier lighttpd.conf

    server.modules += ( "mod_fastcgi" )

    fastcgi.server = ( ".php" =>
      ((
        "socket" => "/tmp/php.socket",
        "bin-path" => "/usr/local/bin/php-cgi",
        "bin-environment" => (
          "PHP_FCGI_CHILDREN" => "16",
          "PHP_FCGI_MAX_REQUESTS" => "10000"
        ),
        "min-procs" => 1,
        "max-procs" => 1,
        "idle-timeout" => 20
      ))
    )

La directive bin-path permet à lighttpd d'appeler le processus FastCGI dynamiquement. PHP appellera les fils suivant la variable d'environnement PHP_FCGI_CHILDREN. La directive `bin-environment` définit l'environnement pour les processus appelés. PHP terminera un processus fils lorsque le nombre de requêtes spécifié par PHP_FCGI_MAX_REQUESTS a été atteint. Les directives `min-procs` et `max-procs` devraient généralement être évitées avec PHP. PHP gère ses propres fils et caches opcode comme APC qui partage uniquement les fils gérés par PHP. Si `min-procs` est défini à quelque chose de supérieur à 1, le nombre total de répondeurs PHP sera multiplié par PHP_FCGI_CHILDREN (2 min-procs * 16 fils, donne 32 répondeurs).

### Appel avec spawn-fcgi

Lighttpd fournit un programme appelé spawn-fcgi afin de rendre plus facile les appels des processus FastCGI.

### Appel de php-cgi

Il est possible d'appeler des processus sans spawn-fcgi, bien que cela demande un peu de travail. La variable d'environnement PHP_FCGI_CHILDREN contrôle le nombre de fils que PHP appelle pour gérer les requêtes entrantes. La variable d'environnement PHP_FCGI_MAX_REQUESTS détermine la durée de vie, en nombre de requêtes, de chaque fils. Voici un script bash simple qui permet d'aider les appels aux répondeurs PHP.

Exemple #2 Appel des répondeurs FastCGI

    #!/bin/sh

    # Localisation du binaire php-cgi
    PHP=/usr/local/bin/php-cgi

    # Localisation du fichier PID
    PHP_PID=/tmp/php.pid

    # Liaison à une adresse
    #FCGI_BIND_ADDRESS=10.0.1.1:10000
    # Liaison à un socket du domaine
    FCGI_BIND_ADDRESS=/tmp/php.sock

    PHP_FCGI_CHILDREN=16
    PHP_FCGI_MAX_REQUESTS=10000

    env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
           PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
           $PHP -b $FCGI_BIND_ADDRESS &

    echo $! > "$PHP_PID"

### Connexion à des instances FCGI distantes

Les instances FastCGI peuvent être appelées sur plusieurs machines distantes afin de répartir les applications.

Exemple #3 Connexion à des instances distantes de php-fastcgi

    fastcgi.server = ( ".php" =>
       (( "host" => "10.0.0.2", "port" => 1030 ),
        ( "host" => "10.0.0.3", "port" => 1030 ))
    )

## Serveur Web LiteSpeed/Serveur Web OpenLiteSpeed sur les systèmes Unix

LiteSpeed PHP est une compilation optimisée de PHP construite pour fonctionner avec les produits LiteSpeed à travers la SAPI LiteSpeed. LSPHP fonctionne comme son propre processus et a son propre binaire autonome, qui peut être utilisé comme un simple binaire en ligne de commande pour exécuter des scripts PHP à partir de la ligne de commande.

LSAPI est une API hautement optimisée qui permet la communication entre LiteSpeed et des moteurs web tiers. Son protocole est similaire à FCGI, mais est plus efficace.

Cette documentation couvrira l'installation et la configuration de PHP avec LSAPI pour un serveur Web LiteSpeed et un serveur Web OpenLiteSpeed.

Ce guide supposera que LSWS ou OLS est installé avec leurs chemins et drapeaux par défaut. Le répertoire d'installation par défaut pour les deux serveurs Web est /usr/local/lsws et les deux peuvent être exécutés à partir du sous-répertoire bin.

Il est à noter que tout au long de cette documentation, les numéros de version ont été remplacés par un `x` pour garantir que cette documentation reste correcte à l'avenir, il convient de les remplacer, si nécessaire, par les numéros de version correspondants.

1. Pour obtenir et installer LiteSpeed Web Server ou OpenLiteSpeed Web Server, consulter la » page d'installation de la documentation de LiteSpeed Web Server ou la » page d'installation de documentation OpenLiteSpeed.

2. Télécharger et décompresser le code source de PHP :

       mkdir /home/php
       cd /home/php
       wget http://us1.php.net/get/php-x.x.x.tar.gz/from/this/mirror
       tar -zxvf php-x.x.x.tar.gz
       cd php-x.x.x

3. Configurer et construire PHP. C'est ici que PHP peut être personnalisé avec diverses options, telles que les extensions qui seront activées. Exécuter ./configure --help pour obtenir une liste des options disponibles. Dans l'exemple, nous utiliserons les options de configuration recommandées par défaut pour LiteSpeed Web Server :

       ./configure ... '--with-litespeed'
       make
       sudo make install

4. Vérifier l'installation de LSPHP

   L'une des façons les plus simples de vérifier si l'installation de PHP a réussi est d'exécuter le code suivant :

       cd /usr/local/lsws/fcgi-bin/
       ./lsphp5 -v

   Cela devrait retourner des informations sur la nouvelle version de PHP :

       PHP 5.6.17 (litespeed) (built: Mar 22 2016 11:34:19)
       Copyright (c) 1997-2014 The PHP Group
       Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies

   Remarquer le `litespeed` entre parenthèses. Cela signifie que le binaire PHP a été construit avec le support LSAPI.

Après avoir suivi les étapes ci-dessus, LiteSpeed / OpenLiteSpeed Web Server devrait maintenant fonctionner avec le support de PHP en tant qu'extension SAPI. Il existe de nombreuses autres options de configuration disponibles pour LSWS / OLS et PHP. Pour plus d'informations, consulter la documentation LiteSpeed sur » PHP.

Utilisation de LSPHP à partir de la ligne de commande :

Le mode de ligne de commande LSPHP (LSAPI + PHP) est utilisé pour traiter les scripts PHP en cours d'exécution sur un serveur distant qui n'a pas nécessairement un serveur web en cours d'exécution. Il est utilisé pour traiter les scripts PHP résidant sur un serveur web local (séparé). Cette configuration est adaptée à la mise à l'échelle du service car le traitement PHP est déchargé vers un serveur distant.

Démarrer lsphp à partir de la ligne de commande sur un serveur distant : LSPHP est un exécutable et peut être démarré manuellement et lié à des adresses IPv4, IPv6 ou des adresses de socket de domaine Unix avec l'option de ligne de commande -b socket_address

Exemples :

Faire en sorte que LSPHP se lie au port 3000 sur toutes les adresses IPv4 et IPv6 :

    /path/to/lsphp -b [::]:3000

Faire en sorte que LSPHP se lie au port 3000 sur toutes les adresses IPv4 :

    /path/to/lsphp -b *:3000

Faire en sorte que LSPHP se lie à l'adresse 192.168.0.2:3000 :

    /path/to/lsphp -b 192.168.0.2:3000

Faire en sorte que LSPHP accepte les requêtes sur le socket de domaine Unix `/tmp/lsphp_manual.sock` :

    /path/to/lsphp -b /tmp/lsphp_manual.sock

Les variables d'environnement peuvent être ajoutées avant l'exécutable LSPHP :

    PHP_LSAPI_MAX_REQUESTS=500 PHP_LSAPI_CHILDREN=35 /path/to/lsphp -b IP_address:port

Actuellement, LiteSpeed PHP peut être utilisé avec LiteSpeed Web Server, OpenLiteSpeed Web Server et Apache mod_lsapi. Pour les étapes de configuration côté serveur, consulter les pages de documentation pour » LiteSpeed Web Server et » OpenLiteSpeed.

LSPHP peut également être installé de plusieurs autres manières.

CentOS: Sur CentOS, LSPHP peut être installé à partir du dépôt LiteSpeed ou du dépôt Remi en utilisant » RPM.

Debian: Sur Debian, LSPHP peut être installé à partir du dépôt LiteSpeed en utilisant » apt.

cPanel: Consulter la » page de documentation respective sur la façon d'installer LSPHP avec cPanel et LSWS/OLS en utilisant EasyApache 4.

Plesk: Plesk peut être utilisé avec LSPHP sur CentOS, CloudLinux, Debian et Ubuntu, pour plus de détails à ce sujet, consulter la » page de documentation respective.

## Installation sous Solaris

Cette section contient les notes et conseils d'installation de PHP sur les systèmes Solaris.

### Logiciels nécessaires

Les installations Solaris sont généralement dépourvues de compilateurs C et de leurs utilitaires. Lire cette FAQ pour savoir pourquoi les versions GNU de certains de ces outils sont nécessaires.

Pour décompresser la distribution PHP, les outils suivants sont nécessaires :

- tar
- gzip ou
- bzip2

Pour compiler PHP, les outils suivants sont nécessaires :

- gcc (recommandé, les autres compilateurs C peuvent aussi fonctionner)
- make
- GNU sed

Pour construire les extensions additionnelles ou modifier le code de PHP, il peut également être nécessaire d'avoir

- re2c
- bison
- m4
- autoconf
- automake

De plus, il faut aussi installer (et peut-être aussi compiler) toutes les bibliothèques nécessaires aux extensions comme MySQL, Oracle, etc.

### Utilisation des paquets

Il est possible de simplifier l'installation Solaris en utilisant pkgadd pour installer la plupart des composants. Le système Image Packaging System (IPS) pour Solaris 11 Express contient également la plupart des composants nécessaires pour l'installation en utilisant la commande pkg.

# Installation sur un système macOS

## Sommaire

- Installation sur macOS en utilisant des packages tiers
- Compiler PHP sur macOS
- Utilisation de PHP embarqué antérieur à macOS Monterey

PHP était inclus avec macOS dans les versions 10 et 11, mais n'est plus inclus depuis la version macOS 12 (Monterey). L'installation sur les versions récentes nécessite soit l'utilisation de packages provenant de sources tierces, soit la compilation à partir du code source.

## Installation sur macOS en utilisant des packages tiers

Il existe quelques versions pré-packagées et pré-compilées de PHP pour macOS. Cela peut être utile pour mettre en place une configuration standard, mais en cas de besoin d'accéder à des fonctionnalités spécifiques (comme un serveur sécurisé, ou un pilote de bases de données exotiques), il faudra compiler PHP et/ou le serveur Web soi-même. Sans être familier avec la compilation et la mise en place d'applications, il est bon de vérifier si quelqu'un d'autre n'a pas déjà réalisé un paquet contenant les fonctionnalités souhaitées.

Une manière simple d'installer PHP sur macOS est d'utiliser le gestionnaire de paquets » Homebrew.

1. Installer Homebrew, en suivant les instructions sur le site web.

2. brew install php

Les ressources alternatives suivantes offrent la possibilité d'installer des paquets et des binaires précompilés pour PHP sous macOS :

- » MacPorts
- » Fink

## Compiler PHP sur macOS

Se référer au guide d'installation sous Unix pour compiler PHP sur macOS.

## Utilisation de PHP embarqué antérieur à macOS Monterey

PHP est embarqué avec macOS depuis macOS X (10.0.0) et antérieur à macOS Monterey (12.0.0). Activer PHP avec le serveur Web par défaut nécessite de décommenter quelques lignes dans le fichier de configuration d'Apache httpd.conf tandis que le mode CGI et/ou CLI sont activés par défaut (accès simple via le terminal).

L'activation de PHP en suivant ces instructions permet de configurer rapidement un environnement local de développement. Il est vivement recommandé de toujours mettre à jour PHP à sa version la plus récente. Comme la plupart des programmes, les nouvelles versions sont créées pour corriger les bogues et ajouter des fonctionnalités et c'est le cas de PHP. Se reporter à la documentation de l'installation de macOS pour plus de détails. Les instructions suivantes sont destinées au débutant, en fournissant juste assez de détails pour mettre en place une configuration par défaut pour travailler. Tous les utilisateurs sont vivement encouragés à compiler et installer une version récente du paquet.

Le type d'installation standard utilise mod_php, et active le mod_php embarqué sur macOS pour le serveur Web Apache (le serveur Web par défaut qui est accessible via les préférences systèmes), en quelques étapes :

1. Trouver et ouvrir le fichier de configuration d'Apache. Par défaut, ce sera : /private/etc/apache2/httpd.conf Utiliser le programme `Finder` ou `Spotlight` pour trouver ce fichier peut s'avérer difficile, sachant que, par défaut, il appartient à l'utilisateur `root`.

   > Note: Une façon de l'ouvrir est d'utiliser un éditeur de texte Unix dans un terminal, par exemple, `nano`, et sachant que le fichier est la propriété de l'utilisateur `root`, il faut utiliser la commande `sudo` pour l'ouvrir (en tant que `root`) ; aussi, il faut entrer la commande suivante dans le `Terminal` (le mot de passe sera demandé) : `sudo nano /private/etc/apache2/httpd.conf` Quelques commandes nano : `^w` (recherche), `^o` (sauvegarde), et `^x` (sortie) où `^` représente la touche Ctrl.

   > Note: Les versions de Mac OS X antérieures à 10.5 fournissent d'anciennes versions de PHP et d'Apache. Aussi, le fichier de configuration d'Apache sur les machines originales peut être /etc/httpd/httpd.conf.

2. Avec un éditeur de texte, décommenter les lignes (en effaçant le caractère #) qui ressemblent aux lignes suivantes (ces 2 lignes ne se trouvent pas au même endroit) :

       # LoadModule php5_module libexec/httpd/libphp5.so

       # AddModule mod_php5.c

   Noter le chemin. Dans le futur, lors de la compilation de PHP, les fichiers ci-dessus doivent être remplacés ou commentés.

3. S'assurer que les extensions désirées soient analysées par PHP (exemples : .php, .html et .inc)

   Sachant que ce comportement a déjà été activé dans le fichier httpd.conf (depuis Mac Panther), une fois PHP activé, les fichiers .php seront automatiquement analysés par PHP.

       <IfModule mod_php5.c>
           # If php is turned on, we respect .php and .phps files.
           AddType application/x-httpd-php .php
           AddType application/x-httpd-php-source .phps

           # Since most users will want index.php to work we
           # also automatically enable index.php
           <IfModule mod_dir.c>
               DirectoryIndex index.html index.php
           </IfModule>
       </IfModule>

   > Note:

   > Avant OS X 10.5 (Leopard), PHP 4 était livré par défaut plutôt que PHP 5. Ainsi, les instructions ci-dessus diffèreront juste en changeant 5 en 4.

4. S'assurer que DirectoryIndex charge le fichier index par défaut. Ceci est également défini dans le fichier httpd.conf. Normalement, les fichiers index.php et index.html sont utilisés. Par défaut, index.php est activé car il est également dans la vérification de PHP ci-dessus. L'ajuster selon les besoins.
5. Définir le chemin vers le fichier php.ini ou utiliser le chemin par défaut. Le chemin par défaut sur macOS est /usr/local/php/php.ini et un appel à la fonction phpinfo() révèlera cette information. Si aucun fichier php.ini n'est utilisé, PHP utilisera toutes les valeurs par défaut. Se reporter à la FAQ sur "trouver le fichier php.ini".
6. Trouver et définir le `DocumentRoot` C'est le dossier principal pour tous les fichiers Web. Les fichiers dans ce dossier seront servis par le serveur Web, et donc, les fichiers PHP seront analysés par PHP avant de les envoyer au navigateur. Le chemin par défaut est /Library/WebServer/Documents mais peut être défini à n'importe quelle valeur dans le fichier httpd.conf. De plus, le dossier DocumentRoot pour les différents utilisateurs est /Users/yourusername/Sites
7. Créer un fichier phpinfo().

   La fonction phpinfo() affiche les informations sur PHP. Créer un fichier dans le DocumentRoot avec le code PHP suivant :

       <?php phpinfo(); ?>

8. Redémarrer Apache et charger le fichier PHP créé précédemment.

   Pour redémarrer, exécuter la commande `sudo apachectl graceful` dans un terminal ou arrêter/démarrer l'option "Personal Web Server" dans les préférences systèmes de macOS. Par défaut, le chargement de fichiers locaux dans le navigateur s'effectue via des URL comme ceci : http://localhost/info.php ou, lors de l'utilisation du DocumentRoot d'un dossier utilisateur, l'URL ressemblera à : http://localhost/~yourusername/info.php

CLI (ou CGI dans les anciennes versions) est nommé php et réside normalement dans /usr/bin/php. Ouvrir un terminal, consulter la section sur la ligne de commande du manuel PHP, et exécuter la commande `php -v` pour vérifier la version PHP de ce binaire. Un appel à la fonction phpinfo() pourra également révéler cette information.

# Installation sur les systèmes Windows

## Sommaire

- Configuration recommandée sur les systèmes Windows
- Installation manuelle des binaires pré-compilés
- Installation pour Apache 2.x sur les systèmes Windows
- Installation avec IIS pour Windows
- Outils tiers pour l'installation de PHP
- Construire à partir des sources
- Exécution de PHP en ligne de commande sur les systèmes Windows

Les versions officielles de PHP sur Windows sont recommandées pour une utilisation en production, mais PHP peut également être compilé à partir des sources.

PHP peut également être installé sur Azure App Services (également connu sous le nom de Microsoft Azure, Windows Azure ou (Windows) Azure Web Apps).

La section d'installation des questions fréquemment posées couvre les problèmes courants d'installation et de configuration.

## Configuration recommandée sur les systèmes Windows

### OpCache

Il est fortement recommandé d'activer OpCache. Cette extension est incluse avec PHP pour Windows. Il compile et optimise les scripts PHP et les met en cache mémoire afin qu'ils ne soient pas compilés chaque fois que la page est chargée.

Définir le php.ini à :

Exemple #1 Configuration recommandée pour OpCache

    opcache.enable=On
    opcache.enable_cli=On

Et redémarrer le serveur web. Pour plus d'informations, voir : Configuration d'OpCache

### WinCache

Il est recommandé d'utiliser WinCache lors de l'utilisation d'IIS, surtout dans un environnement d'hébergement Web partagé ou lors de l'utilisation du stockage de fichiers en réseau (NAS). Toutes les applications PHP bénéficient automatiquement de la fonctionnalité de cache de fichiers de WinCache. Les opérations du système de fichiers sont mises en cache en mémoire. WinCache peut également mettre en cache mémoire des objets de l'utilisateur et les partager entre les processus php.exe ou php-cgi.exe (partager des objets entre les requêtes). De nombreuses applications Web majeures ont un plugin ou une extension ou une option de configuration pour utiliser le cache d'objet de l'utilisateur de WinCache. Si des performances élevées sont nécessaires, utiliser le cache d'objets dans les applications. Voir : » https://pecl.php.net/package/WinCache pour télécharger une DLL WinCache (ou WINCACHE_*.tgz) dans le répertoire des extensions PHP (extension_dir dans le fichier php.ini). Définir le php.ini à :

Exemple #2 Configuration recommandée pour WinCache

    extension=php_wincache.dll
    wincache.fcenabled=1
    wincache.ocenabled=1 ; removed as of wincache 2.0.0.0

Pour plus d'informations, voir : Configuration de WinCache

## Installation manuelle des binaires pré-compilés

### Exigences d'installation

PHP n'est disponible que pour les systèmes 32 bits x86 ou 64 bits x64, et ne fonctionne actuellement pas sur Windows RT ou Windows sur ARM. À partir de la version 8.3.0, PHP nécessite Windows 8 ou Windows Server 2012. Les versions postérieures à 7.2.0 nécessitaient Windows 2008 R2 ou Windows 7. Les versions antérieures à 7.2.0 supportaient Windows 2008 et Vista.

PHP nécessite le runtime Visual C (CRT). De nombreuses autres applications l'exigent également, donc il est probable qu'il soit déjà installé, mais s'il n'est pas présent, le Microsoft Visual C++ Redistributable pour Visual Studio 2022 est adapté à toutes les versions de PHP et peut être » téléchargé depuis Microsoft.

Le CRT x86 doit être téléchargé pour être utilisé avec les builds PHP x86 et le CRT x64 pour les builds PHP x64. Si le CRT est déjà installé, l'installateur affichera un message indiquant qu'il était déjà installé et ne fera aucun changement. L'installateur CRT prend en charge les options de ligne de commande /quiet et /norestart, donc l'installation peut être scriptée.

### Où télécharger les binaires PHP

Les builds Windows peuvent être téléchargés depuis » le site Web PHP Windows. Tous les builds sont optimisés (PGO), et les versions QA et GA sont soigneusement testées.

### Extensions PECL pré-compilées

Les versions Windows préconstruites des extensions PECL sont distribuées sous forme de fichiers DLL sur la page PECL de l'extension.

Les binaires ne sont pas disponibles pour les extensions qui utilisent des fonctionnalités spécifiques à d'autres systèmes, comme Unix, ou dépendent de bibliothèques qui ne sont pas disponibles sur Windows.

### Types de build

Il existe quatre types de builds PHP :

- Thread-Safe (TS) - pour les serveurs web à processus unique, comme Apache avec mod_php

- Non-Thread-Safe (NTS) - pour IIS et d'autres serveurs web FastCGI (Apache avec mod_fastcgi) et recommandé pour les scripts en ligne de commande

- x86 - pour les systèmes 32 bits.

- x64 - pour les systèmes 64 bits.

## Installation pour Apache 2.x sur les systèmes Windows

Cette section contient des notes et des astuces spécifiques aux installations d'Apache 2.x de PHP sur les systèmes Microsoft Windows.

> Note:

> Il convient de lire d'abord les étapes d'installation manuelle !

Il est fortement recommandé de consulter la » documentation d'Apache pour obtenir une compréhension de base du serveur Apache 2.x. Il est également recommandé de lire les » notes spécifiques à Windows pour Apache 2.x avant de continuer ici.

Télécharger la version la plus récente de » Apache 2.x et une version PHP correspondante. Suivre les étapes d'installation manuelle et revenir pour continuer avec l'intégration de PHP et Apache.

Il y a trois façons de configurer PHP pour fonctionner avec Apache 2.x sur Windows. PHP peut être exécuté en tant que gestionnaire, en tant que CGI, ou sous FastCGI.

> Note: Souvenez-vous que lorsque vous ajoutez des valeurs représentants un chemin dans la configuration d'Apache sous Windows, tous les antislash, comme c:\repertoire\fichier.ext, devraient être convertis en slashes, comme c:/repertoire/fichier.ext. Un slash final peut également être nécessaire pour les dossiers.

### Installation en tant que gestionnaire Apache

> Note: Lors de l'utilisation de l'interface SAPI apache2handler, la version Thread Safe (TS) de PHP doit être utilisée.

Pour charger le module PHP pour Apache 2.x, les lignes suivantes dans le fichier de configuration Apache httpd.conf doivent être insérées :

Exemple #1 PHP en tant que gestionnaire Apache 2.x

    # Avant PHP 8.0.0 le nom du module était php7_module
    LoadModule php_module "c:/php/php8apache2_4.dll"
    <FilesMatch \.php$>
        SetHandler application/x-httpd-php
    </FilesMatch>
    # configurer le chemin du php.ini
    PHPIniDir "C:/php"

> Note: Le chemin réel vers PHP doit être substitué à la place de C:/php/ dans les exemples ci-dessus. Il faut s'assurer que le fichier référencé dans la directive `LoadModule` est à l'emplacement spécifié. Utiliser php7apache2_4.dll pour PHP 7, ou php8apache2_4.dll pour PHP 8.

### Exécution de PHP en tant que CGI

Il est fortement recommandé de consulter la » documentation d'Apache CGI pour une compréhension plus complète de l'exécution de CGI sur Apache.

Pour exécuter PHP en tant que CGI, les fichiers php-cgi devront être placés dans un répertoire désigné comme répertoire CGI en utilisant la directive ScriptAlias.

Une ligne `#!` devra être placée dans les fichiers PHP, qui pointent vers l'emplacement du binaire PHP :

Exemple #2 PHP et Apache 2.x en tant que CGI

    #!C:/php/php.exe
    <?php
      phpinfo();
    ?>

Avertissement

Un serveur déployé en mode CGI s'expose à plusieurs vulnérabilités possibles. Veuillez lire notre section sur la sécurité en mode CGI pour apprendre comment vous protéger contre ces attaques.

### Exécution de PHP en tant que FastCGI

Exécuter PHP sous FastCGI présente un certain nombre d'avantages par rapport à l'exécution en tant que CGI. La configuration est assez simple :

Obtenir `mod_fcgid` depuis » https://www.apachelounge.com. Les binaires Win32 sont disponibles en téléchargement sur ce site. Installer le module selon les instructions qui l'accompagneront.

Configurer le serveur web comme indiqué ci-dessous, en prenant soin d'ajuster les chemins pour refléter comment c'est installé dans le système :

Exemple #3 Configurer Apache pour exécuter PHP en tant que FastCGI

    LoadModule fcgid_module modules/mod_fcgid.so
    # Où est le fichier php.ini ?
    FcgidInitialEnv PHPRC        "c:/php"
    <FilesMatch \.php$>
        SetHandler fcgid-script
    </FilesMatch>
    FcgidWrapper "c:/php/php-cgi.exe" .php

Les fichiers avec une extension `.php` seront maintenant exécutés par l'enveloppe PHP FastCGI.

## Installation avec IIS pour Windows

### Installer IIS

Les Services d'informations Internet (Internet Information Services - IIS) sont intégrés à Windows. Sur Windows Server, le rôle IIS peut être ajouté via le Gestionnaire de serveur. La fonctionnalité de rôle CGI doit être incluse. Sur les bureaux Windows, IIS doit être ajouté via l'option Ajout/Suppression de programmes du Panneau de configuration. La documentation Microsoft fournit » des instructions détaillées pour activer IIS. Pour le développement, » IIS/Express peut également être utilisé.

> Note: La version Non-Thread Safe (NTS) de PHP doit être installée lors de l'utilisation du gestionnaire FastCGI avec IIS.

### Configurer PHP avec IIS

Dans le gestionnaire IIS, installer le module FastCGI et ajouter un mappage de gestionnaire pour `.php` au chemin de php-cgi.exe (pas php.exe)

La commande APPCMD peut être utilisée pour scripter la configuration IIS.

### Exemple de script batch

Exemple #1 Ligne de commande pour configurer IIS et PHP

    @echo off

    REM télécharger le fichier .ZIP de la version de PHP depuis http://windows.php.net/downloads/

    REM chemin du répertoire dans lequel le fichier .ZIP de PHP a été décompressé (sans \ final)
    set phppath=c:\php

    REM Efface les gestionnaires PHP actuels
    %windir%\system32\inetsrv\appcmd clear config /section:system.webServer/fastCGI
    REM La commande suivante générera un message d'erreur si PHP n'est pas installé. Cela peut être ignoré.
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /-[name='PHP_via_FastCGI']

    REM Configure le gestionnaire PHP
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI /+[fullPath='%phppath%\php-cgi.exe']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /+[name='PHP_via_FastCGI',path='*.php',verb='*',modules='FastCgiModule',scriptProcessor='%phppath%\php-cgi.exe',resourceType='Unspecified']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /accessPolicy:Read,Script

    REM Configure les variables FastCGI
    %windir%\system32\inetsrv\appcmd set config -section:system.webServer/fastCgi /[fullPath='%phppath%\php-cgi.exe'].instanceMaxRequests:10000
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHPRC',value='%phppath%\php.ini']"

## Outils tiers pour l'installation de PHP

Avertissement

Les versions provenant de tiers sont considérées comme non officielles et ne sont pas directement prises en charge par le projet PHP. Tout bogue rencontré doit être signalé au fournisseur de ces versions non officielles, sauf s'il peut être reproduit à l'aide des versions provenant de » la zone de téléchargement officielle.

» XAMPP, » WampServer, et » Bitnami configurent également des applications PHP pour une utilisation avec Apache sur Windows.

## Construire à partir des sources

Voir les » instructions de construction étape par étape pour compiler avec Visual Studio.

## Exécution de PHP en ligne de commande sur les systèmes Windows

Cette section contient des notes et des astuces spécifiques à l'exécution de PHP en ligne de commande sur Windows.

> Note:

> Il convient de lire les étapes d'installation manuelle en premier !

Avoir PHP qui s'exécute à partir de la ligne de commande peut être effectué sans apporter de modifications à Windows.

    C:\php\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3

Mais il y a quelques étapes faciles à suivre pour simplifier cela. Certaines de ces étapes auraient déjà dû être prises, mais sont répétées ici pour pouvoir fournir une séquence étape par étape complète.

> Note:

> Les deux variables système pré-existantes PATH et PATHEXT sont importantes dans Windows, et il faut faire attention à ne pas les écraser, seulement les ajouter.

- Ajouter l'emplacement de l'exécutable PHP (php.exe, php-win.exe ou php-cli.exe selon la version de PHP et les préférences d'affichage) à la variable d'environnement PATH. Lire la section sur comment ajouter le répertoire PHP approprié à la variable d'environnement PATH dans la entrée FAQ correspondante.

- Ajouter l'extension `.PHP` à la variable d'environnement PATHEXT. Ceci peut être fait en même temps que l'ajout de la variable d'environnement PATH. Suivre les mêmes étapes que décrites dans la FAQ mais modifier la variable d'environnement PATHEXT plutôt que la variable d'environnement PATH.

  > Note:

  > La position dans laquelle le `.PHP` est placé déterminera quel script ou programme est exécuté lorsqu'il y a des noms de fichiers correspondants. Par exemple, placer `.PHP` avant `.BAT` fera exécuter le script, plutôt que le fichier batch, s'il y a un fichier batch avec le même nom.

- Associer l'extension `.PHP` avec un type de fichier. Ceci est fait en exécutant la commande suivante :

      assoc .php=phpfile

- Associer le type de fichier `phpfile` avec l'exécutable PHP approprié. Ceci est fait en exécutant la commande suivante :

      ftype phpfile="C:\php\php.exe" -f "%1" -- %~2

En suivant ces étapes, les scripts PHP pourront être exécutés depuis n'importe quel répertoire sans avoir besoin de taper l'exécutable PHP ou l'extension `.PHP` et tous les paramètres seront fournis au script pour traitement.

L'exemple ci-dessous détaille certains des changements de registre qui peuvent être faits manuellement.

Exemple #1 Changements de registre

    Windows Registry Editor Version 5.00

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php]
    @="phpfile"
    "Content Type"="application/php"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile]
    @="PHP Script"
    "EditFlags"=dword:00000000
    "BrowserFlags"=dword:00000008
    "AlwaysShowExt"=""

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon]
    @="C:\\php\\php-win.exe,0"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell]
    @="Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open]
    @="&Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command]
    @="\"C:\\php\\php.exe\" -f \"%1\" -- %~2"

Avec ces changements, la même commande peut être écrite comme suit :

    "C:\PHP Scripts\script" -arg1 -arg2 -arg3

ou, si le chemin `"C:\PHP Scripts"` est dans la variable d'environnement PATH :

    script -arg1 -arg2 -arg3

> Note:

> Il y a un petit problème si l'on souhaite utiliser cette technique et utiliser les scripts PHP comme filtre en ligne de commande, comme l'exemple ci-dessous :

>     dir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3

> ou

>     dir | script -arg1 -arg2 -arg3

> Le script peut simplement se bloquer et rien ne s'affiche. Pour que cela fonctionne, un autre changement de registre doit être effectué :

>     Windows Registry Editor Version 5.00

>     [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer]
>     "InheritConsoleHandles"=dword:00000001

> Plus d'informations sur ce problème peuvent être trouvées dans cet » article de la base de connaissances Microsoft : 321788. À partir de Windows 10, ce paramètre semble être inversé, rendant l'installation par défaut de Windows 10 supportant automatiquement les gestionnaires de console hérités. Ce » post du forum Microsoft fournit l'explication.

# Installation sur des plateformes de Cloud Computing

## Sommaire

- Azure App Services
- Amazon EC2
- DigitalOcean

PHP s'installe sur le cloud. Vers le cloud PHP !

## Azure App Services

PHP est fréquemment utilisé sur Azure App Services (alias Microsoft Azure, Windows Azure, Azure Web Apps).

Azure App Services gère les pools de serveurs Web Windows pour héberger l'application Web, en tant qu'alternative à la gestion de son propre serveur Web sur ses propres VM de calcul Azure ou d'autres serveurs.

PHP est déjà activé automatiquement pour le site web Azure App Services. Dans le portail Azure, sélectionner le site Web pour choisir la version de PHP à utiliser. Il peut être souhaitable de choisir une version plus récente que la valeur par défaut.

En tant que tel, PHP et les extensions s'exécutent sur Azure App Services tout comme ils le feraient sur d'autres serveurs Windows. Toutefois, l'interface de gestion pour Azure App Services est différente :

- Portail Azure : créer, modifier et supprimer les sites Web. » Portail Azure

- Tableau de bord Kudu : si le site Web a l'URL `nom_du_site.azurewebsites.net`, le tableau de bord Kudu est `https://nom_du_site.scm.azurewebsites.net/`. Le tableau de bord offre un accès aux fonctionnalités de débogage, à la gestion des fichiers et aux extensions du site. Les extensions de site sont un mécanisme Azure permettant d'ajouter des programmes supplémentaires, comme des versions préliminaires de PHP, à un site Web.

- Il n'est pas possible d'utiliser le gestionnaire des services Internet, le gestionnaire de serveur ou RDP.

Il existe également un SDK PHP, qui permet d'utiliser les nombreux services d'Azure à partir du code PHP. Voir » Azure SDK pour PHP.

Pour plus d'informations, voir » Azure PHP Developer Center

### WinCache

WinCache est activé par défaut sur Azure App Services et il est recommandé de le laisser activé. Lors de l'installation d'une version personnalisée de PHP, il faut activer WinCache.

### Build personnalisée de PHP

Il est possible de téléverser sa propre version de PHP dans D:\Home (C:\ n'est pas accessible en écriture). Ensuite, dans le portail Azure, définir SCRIPT_PROCESSOR pour .php sur le chemin d'accès absolu au fichier php-cgi.exe dans la build personnalisée.

## Amazon EC2

Installation de PHP sur » la plateforme cloud EC2.

Voir aussi l'» AWS SDK pour PHP.

## DigitalOcean

DigitalOcean offre les plateformes suivantes pour installer PHP et faire fonctionner une application web sur son infrastructure d'hébergement cloud.

- » Cloudways: Déploiement en un clic des principales applications PHP : WordPress, Magento, Drupal, Laravel, et plus encore.

- » Droplet: Serveurs virtuels pour installer PHP et d'autres logiciels. » Installer une stack LAMP sur un serveur Linux .

- » App Platform: Gérer des infrastructures pour construire, déployer et mettre à l'échelle rapidement des applications. Découvrir comment » faire tourner des applications PHP sur la plateforme App .

- » Functions: Plateforme sans serveur qui permet aux développeurs d'exécuter du code sans provisionner ni gérer de serveurs. PHP est supporté nativement. Découvrir comment » créer des fonctions sans serveur en PHP .

# FastCGI Process Manager (FPM)

## Sommaire

- Installation
- Configuration

FPM (FastCGI Process Manager, gestionnaire de processus FastCGI) est une alternative à l'implémentation PHP FastCGI avec des fonctionnalités supplémentaires utiles pour les sites très fortement chargés.

Ces fonctionnalités incluent :

- Gestion avancée des processus avec stop/start doux (graceful) ;

- Pools qui donnent la possibilité de démarrer des travailleurs avec différents uid/gid/chroot/environnement, écoutant sur différents ports et utilisant différents php.ini (remplace le safe_mode) ;

- Journalisation configurable de stdout et stderr ;

- Redémarrage d'urgence en cas de destruction accidentelle du cache opcode ;

- Support de l'upload accéléré ;

- "slowlog" - journalisation des scripts (pas juste leurs noms, mais leur backtrace PHP également, utilisant ptrace ou équivalent pour lire le execute_data du processus distant) qui s'exécutent de manière anormalement lente ;

- fastcgi_finish_request() - fonction spéciale pour terminer la requête et vider toutes les données tout en continuant d'exécuter une tâche consommatrice (conversion vidéo par exemple) ;

- Naissance de processus fils dynamic/ondemand/static ;

- Informations d'état de base et étendues (similaire à mod_status d'Apache) avec différents formats supportés comme json, xml et openmetrics ;

- Fichier de configuration basé sur php.ini

## Installation

### Compiler depuis les sources

Pour activer FPM dans la construction de PHP, il faut ajouter la ligne `--enable-fpm` à la ligne de configuration.

Il existe de multiples options de configuration pour FPM (toutes optionnelles):

- `--with-fpm-user` - l'utilisateur FPM (défaut - nobody).

- `--with-fpm-group` - le groupe FPM (défaut - nobody).

- `--with-fpm-systemd` - Active l'intégration de systemd (par défaut - no).

- `--with-fpm-acl` - Utiliser POSIX Access Control Lists (par défaut - no).

- `--with-fpm-apparmor` - Active l'intégration d'AppArmor (par défaut - no).

- `--with-fpm-selinux` - Active l'intégration SELinux (par défaut - no).

### Historique

Version | Description
--- | ---
8.2.0 | L'option `--with-fpm-selinux` a été ajoutée.
8.0.0 | L'option `--with-fpm-apparmor` a été ajoutée.

## Configuration

FPM utilise la syntaxe php.ini pour son fichier de configuration - php-fpm.conf ainsi que les fichiers de configuration du pool.

### Liste des directives globales de php-fpm.conf

`pid` chaîne de caractères

  Chemin vers le fichier PID. Par défaut : none.

`error_log` chaîne de caractères

  Chemin vers le fichier de journal. Par défaut : `#INSTALL_PREFIX#/log/php-fpm.log`. Si défini à "syslog", le journal est envoyé vers syslogd au lieu d'être écrit dans un fichier local.

`log_level` chaîne de caractères

  Niveau de journalisation d'erreur. Valeurs possibles : alert, error, warning, notice, debug. Par défaut : notice.

`log_limit` entier

  Limite de journalisation pour les lignes enregistrées qui permet de journaliser des messages de plus de 1024 caractères sans découpage. Valeur par défaut : 1024 Disponible à partir de PHP 7.3.0.

`log_buffering` booléen

  Journalisation expérimentale sans tampon supplémentaire. Valeur par défaut : yes. Disponible à partir de PHP 7.3.0.

`syslog.facility` chaîne de caractères

  Utilisé pour spécifier quel type de programme écrit le message. Valeur par défaut : daemon.

`syslog.ident` chaîne de caractères

  Ajoute au début de chaque message. En cas de multiples instances FPM s'exécutant sur le même serveur, il est possible de changer la valeur par défaut afin qu'elle convienne aux besoins. Valeur par défaut : php-fpm.

`emergency_restart_threshold` entier

  Si ce nombre de processus fils terminent avec un SIGSEGV ou SIGBUS dans l'intervalle de temps précisé dans `emergency_restart_interval`, alors FPM redémarrera. Une valeur de 0 signifie 'Off'. Valeur par défaut : 0 (Off).

`emergency_restart_interval` mixed

  Intervalle de temps utilisé par `emergency_restart_interval` pour déterminer lorsqu'un redémarrage doux doit être lancé. Ceci peut être utile pour contourner des corruptions accidentelles dans la mémoire partagée d'un accélérateur. Unités disponibles : s(econdes), m(inutes), h(eures), ou j(ours). Unité par défaut : secondes. Valeur par défaut : 0 (Off).

`process_control_timeout` mixed

  Temps limite qu'attendront les processus fils pour réagir aux signaux du père. Unités disponibles : s(econdes), m(inutes), h(eures), ou j(ours) Unité par défaut : secondes. Valeur par défaut : 0.

`process.max` entier

  Le nombre maximum de processus que FPM va forker. Ceci a été conçu pour contrôler le nombre global de processus lors de l'utilisation d'un gestionnaire de processus dynamique avec beaucoup de pools. À utiliser avec attention. Valeur par défaut : 0.

`process.priority` entier

  Définit la priorité nice(2) à appliquer au processus principal (uniquement si défini) La valeur peut varier de -19 (priorité haute) à 20 (priorité basse). Valeur par défaut : non défini.

`daemonize` booléen

  Envoie FPM en arrière-plan. Mettre 'no' pour garder FPM au premier plan lors du débogage. Valeur par défaut : yes.

`rlimit_files` entier

  Définit la rlimit pour les descripteurs de fichiers ouverts pour le processus principal. Valeur par défaut : valeur définie par le système.

`rlimit_core` entier

  Définit la taille maximale de rlimit pour le processus principal. Valeur par défaut : 0.

`events.mechanism` chaîne de caractères

  Spécifie le gestionnaire d’événement que FPM va utiliser. Les options suivantes sont disponibles: epoll, kqueue (*BSD), port (Solaris), poll, select. Valeur par défaut : non définie (détection automatique privilégiant epoll et kqueue).

`systemd_interval` entier

  Quand FPM est construit avec le support de systemd, spécifie l'intervalle en seconde, entre les notifications de rapport de santé envoyées à systemd. Définir à 0 pour désactiver. Valeur par défaut : 10.

### Liste des directives de pool

Avec FPM il est possible d'exécuter plusieurs pools de processus avec des paramètres différents. Voici les paramètres qui peuvent être ajustés par pool.

`listen` chaîne de caractères

  L'adresse pour accepter des requêtes FastCGI. Syntaxes valides : 'ip.add.re.ss:port', 'port', '/path/to/unix/socket'. Cette option est obligatoire pour chaque pool.

`listen.backlog` entier

  Affecte listen(2) backlog. Une valeur de `-1` signifie le maximum sur les systèmes BSD. Valeur par défaut : `-1` (FreeBSD ou OpenBSD) ou `511` (Linux et autres plateformes).

`listen.allowed_clients` chaîne de caractères

  Liste des adresses IPv4 ou IPv6 des clients FastCGI autorisés à se connecter. C'est équivalent à la variable d'environnement FCGI_WEB_SERVER_ADDRS dans le système FastCGI original de PHP (5.2.2+). N'a de sens qu'avec un socket tcp en écoute. Chaque adresse doit être séparée par une virgule. Si cette valeur n'est pas précisée, les connexions seront acceptées depuis toute adresse ip. Valeur par défaut : non définie (toute adresse IP acceptée).

`listen.owner` chaîne de caractères

  Affecte les permissions pour le socket Unix si utilisé. Sous Linux, les permissions read/write doivent être affectées pour autoriser des connexions depuis un serveur web. Beaucoup de systèmes dérivés BSD autorisent les connexions quelles que soient les permissions. Valeurs par défaut : user et group sont ceux de l'utilisateur courant, le mode est 0660.

`listen.group` chaîne de caractères

  Voir `listen.owner`.

`listen.mode` chaîne de caractères

  Voir `listen.owner`.

`listen.acl_users` chaîne de caractères

  Quand les listes de contrôle d'accès POSIX sont supportées, il est possible de les définir en utilisant cette option. Quand défini, `listen.owner` et `listen.group` sont ignorés. La valeur est une liste de noms d'utilisateurs séparés par des virgules.

`listen.acl_groups` chaîne de caractères

  Voir `listen.acl_users`. La valeur est une liste de noms de groupes séparés par des virgules.

`listen.setfib` int

  Définit la table de routage associée (FIB). FreeBSD uniquement. Valeur par défaut : `-1`. À partir de PHP 8.2.0.

`user` chaîne de caractères

  Utilisateur Unix des processus FPM. Cette option est obligatoire.

`group` chaîne de caractères

  Groupe Unix des processus FPM. Si non précisé, le groupe de l'utilisateur est utilisé.

`pm` chaîne de caractères

  Choisit comment le gestionnaire de processus va contrôler le nombre de processus fils. Valeurs possibles : `static`, `ondemand`, `dynamic`. Option obligatoire.

  `static` - nombre de processus fils fixés (`pm.max_children`).

  `ondemand` - le processus se réactive à la demande (lorsque demandé, c'est l'opposé de dynamique où `pm.start_servers` sont démarrés lorsque le service démarre). `dynamic` - nombre de processus fils dynamiques basé sur les directives suivantes: `pm.max_children`, `pm.start_servers`, `pm.min_spare_servers`, `pm.max_spare_servers`.
`pm.max_children` entier
  Nombre de processus fils à créer lorsque `pm` est réglé sur `static`. Nombre maximum de processus fils à créer lorsque `pm` est réglé sur `dynamic` ou `ondemand`. Option obligatoire.

  Cette option affecte la limite du nombre de requêtes simultanées qui seront servies. Équivalent à ApacheMaxClients avec mpm_prefork et à PHP_FCGI_CHILDREN dans l'implémentation originale de FastCGI de PHP.

`pm.start_servers` entier

  Nombre de processus fils à créer au démarrage. Utilisé seulement si `pm` est réglé sur `dynamic`. Valeur par défaut : (min_spare_servers + max_spare_servers) / 2.

`pm.min_spare_servers` entier

  Nombre minimum de processus au repos (idle) voulus. Utilisé seulement si `pm` est réglé sur `dynamic`. Obligatoire dans ce cas.

`pm.max_spare_servers` entier

  Nombre maximum de processus au repos (idle) voulus. Utilisé seulement si `pm` est réglé sur `dynamic`. Obligatoire dans ce cas.

`pm.max_spawn_rate` int

  Nombre maximum de taux de génération de processus enfants simultanés. Utilisé seulement si `pm` est défini à `dynamic`. Valeur par défaut : 32

`pm.process_idle_timeout` mixed

  Nombre de secondes après lesquelles un processus inactif sera tué. Utilisé uniquement quand `pm` est défini à `ondemand`. Unités disponibles : s (secondes)(par défaut), m (minutes), h (heures), ou d (jours). Valeur par défaut : 10s.

`pm.max_requests` entier

  Nombre de requêtes que chaque processus fils devrait exécuter avant de renaître. Ceci peut être utile pour contourner des fuites mémoires dans des bibliothèques tierces. Pour un traitement sans fin des requêtes, précisez '0'. Équivalent à PHP_FCGI_MAX_REQUESTS. Par défaut : 0.

`pm.status_listen` string

  L'adresse sur laquelle accepter la demande de statut FastCGI. Cela crée un nouveau pool invisible qui peut traiter les requêtes indépendamment. Ceci est utile si le pool principal est occupé par des requêtes de longue durée car il est toujours possible d'obtenir la page de statut de FPM avant qu'elles ne soient terminées. La syntaxe est la même que pour la directive listen. Valeur par défaut : none.

`pm.status_path` chaîne de caractères

  L'URI vers la page de statut de FPM. Cette valeur doit commencer par une barre oblique (/). Si cette valeur n'est pas définie, aucun URI ne sera reconnu en tant que page de statut. Valeur par défaut : none.

`ping.path` chaîne de caractères

  L'URI de ping pour appeler la page de monitoring de FPM. Si aucune valeur n'est précisée, aucune page de ping ne sera disponible. Ceci pourrait être utilisé pour tester depuis l'extérieur si FPM est toujours disponible et prêt à répondre. Il est à noter que la valeur doit commencer par un slash (/).

`ping.response` chaîne de caractères

  Cette directive est utile pour personnaliser la réponse à une requête de ping. La réponse est formatée comme text/plain avec un code de réponse de 200. Valeur par défaut : pong.

`process.priority` entier

  Spécifier la priorité nice(2) à appliquer au processus de travail (uniquement s'il est défini). La valeur peut varier de -19 (priorité la plus élevée) à 20 (priorité la plus basse). Valeur par défaut: non définie.

`process.dumpable` booléen

  Définit l'indicateur de processus dumpable (PR_SET_DUMPABLE prctl) même si l'utilisateur ou le groupe de processus est différent de l'utilisateur du processus maître. Il permet de créer un core dump du processus et ptrace le processus pour l'utilisateur de pool. Valeur par défaut : no. À partir de PHP 7.0.29, 7.1.17 et 7.2.5.

`prefix` chaîne de caractères

  Spécifier le préfixe pour l'évaluation du chemin

`request_terminate_timeout` mixed

  Le timeout pour servir une requête après lequel le processus concerné sera tué. Cette option devrait être utilisée lorsque l'option 'max_execution_time' n'arrête pas l'exécution du script pour une raison quelconque. Une valeur de '0' signifie 'Off'. Unités disponibles : s(econdes)(défaut), m(inutes), h(eures), ou j(ours). Par défaut : 0.

`request_terminate_timeout_track_finished` bool

  Le timeout défini par request_terminate_timeout n'est pas engagé après un fastcgi_finish_request ou lorsque l'application s'est terminée et que les fonctions internes d'arrêt sont appelées. Cette directive permet d'appliquer la limite de temps sans condition. Valeur par défaut : no. À partir de PHP 7.3.0.

`request_slowlog_timeout` mixed

  Le timeout pour servir une requête dans laquelle la backtrace PHP sera vidée dans le fichier 'slowlog'. Une valeur de '0' signifie 'Off'. Unités disponibles : s(econdes)(défaut), m(inutes), h(eures), ou j(ours). Par défaut : 0.

`request_slowlog_trace_depth` int

  Le niveau de profondeur de la trace de la pile de log slowlog. Valeur par défaut : 20. À partir de PHP 7.2.0.

`slowlog` chaîne de caractères

  Le journal pour les requêtes lentes, par défaut : `#INSTALL_PREFIX#/log/php-fpm.log.slow`.

`rlimit_files` entier

  Affecte la rlimit pour les descripteurs de fichiers ouverts des processus enfants de ce pool. Valeur par défaut : valeur du système.

`rlimit_core` entier

  Affecte la taille maximale de rlimit des processus enfants de ce pool. Valeurs possibles : 'unlimited' ou un entier plus grand ou égal à 0. Valeur par défaut : valeur définie par le système.

`chroot` chaîne de caractères

  Chroot vers ce dossier au démarrage. Cette valeur doit être un chemin absolu. Si cette valeur n'est pas définie, chroot n'est pas utilisé.

`chdir` chaîne de caractères

  Chdir vers ce dossier au démarrage. Cette valeur doit être un chemin absolu. Valeur par défaut : dossier courant ou / si chroot.

`catch_workers_output` booléen

  Redirige stdout et stderr vers le journal d'erreur principal. Si non précisé, stdout et stderr seront redirigés vers /dev/null selon les spécifications FastCGI. Valeur par défaut : no.

`decorate_workers_output` booléen

  Active la décoration de sortie pour les travailleurs de sortie quand catch_workers_output est activé. Valeur par défaut : yes. Disponible à partir de PHP 7.3.0.

`clear_env` booléen

  Nettoie l’environnement des agents FPM. Prévient que des variables d’environnement arbitraires puissent atteindre les processus FPM par le nettoyage de l’environnement de ces agents avant que les variables d’environnement spécifiées dans la configuration du pool ne soient ajoutées. Valeur par défaut : Yes.

`security.limit_extensions` chaîne de caractères

  Limite les extensions que le script principal FPM va être autorisé à analyser. Ceci peut prévenir les erreurs de configuration côté serveur. Il est recommandé de limiter FPM aux extensions .php uniquement pour empêcher des utilisateurs malveillants d'utiliser d'autres extensions pour exécuter du code PHP. Valeur par défaut : .php .phar

`apparmor_hat` string

  Si AppArmor est activé, permet de changer un hat (chapeau). Valeur par défaut : non défini

`access.log` chaîne de caractères

  Le fichier journal d'accès. Valeur par défaut : non définie

`access.format` chaîne de caractères

  Le format du journal d'accès. Valeur par défaut : `"%R - %u %t \"%m %r\" %s"`:

  Options valides
  Placeholder | Description
  --- | ---
  `%%` | Le caractère `%`
  `%C` | %CPU utilisé par la requête. Les formats suivants sont acceptés : `%{user}C` pour la CPU utilisateur uniquement, `%{system}C` pour la CPU système uniquement, `%{total}C` pour la CPU utilisateur + système (par défaut)
  `%d` | Temps pris pour traiter la requête. Les formats suivants sont acceptés pour la précision : `%{seconds}d` (par défaut), `%{milliseconds}d`, `%{microseconds}d`
  `%{name}e` | Une variable d'environnement (identique à $_ENV ou $_SERVER). Un nom de variable doit être spécifié entre accolades pour indiquer le nom de la variable d'environnement. Par exemple, des informations spécifiques au serveur comme `%{REQUEST_METHOD}e` ou `%{SERVER_PROTOCOL}e`, des en-têtes HTTP tels que `%{HTTP_HOST}e` ou `%{HTTP_USER_AGENT}e`
  `%f` | Nom du fichier script
  `%l` | `Content-Length` de la requête (pour les requêtes HTTP POST uniquement)
  `%m` | Méthode HTTP de la requête
  `%M` | Pic de mémoire allouée par PHP. Accepte les formats suivants : `%{bytes}M` (défaut), `%{kilobytes}M` `%{kilo}M`, `%{megabytes}M`, `%{mega}M`
  `%n` | Nom du pool
  `%{name}o` | En-tête de sortie. Le nom de l'en-tête doit être spécifié entre accolades. Par exemple : `%{Content-Type}o`, `%{X-Powered-By}o`, `%{Transfer-Encoding}o`
  `%p` | PID de l'enfant qui a traité la demande
  `%P` | PID du parent de l'enfant qui a traité la demande
  `%q` | Chaîne de requête
  `%Q` | Le caractère `'?'`, ou le lien entre `%q` et `%r`, si la chaîne de requête existe
  `%r` | URI de la requête sans la chaîne de requête, voir `%q` et `%Q`
  `%R` | Adresse IP distante
  `%s` | Statut (code de réponse)
  `%t` | Heure du serveur à laquelle la requête a été reçue. Elle peut accepter un format `strftime(3)` : `%d/%b/%Y:%H:%M:%S %z` (par défaut). Le format `strftime(3)` doit être encapsulé dans une balise `%{<strftime_format>}t`, par exemple, pour une chaîne de temps au format ISO8601, utiliser : `%{%Y-%m-%dT%H:%M:%S%z}t`
  `%T` | Heure à laquelle le log a été écrit (lorsque la requête s'est terminée). Elle peut accepter un format `strftime(3)` : `%d/%b/%Y:%H:%M:%S %z` (par défaut). Le format `strftime(3)` doit être encapsulé dans une balise `%{<strftime_format>}T`, par exemple, pour une chaîne de temps au format ISO8601, utiliser : `%{%Y-%m-%dT%H:%M:%S%z}T`
  `%u` | Utilisateur d'authentification basique, si spécifié dans l'en-tête `Authorization`

`access.suppress_path` array

  Une liste de valeurs request_uri qui devraient être filtrées du journal d'accès. Valeur par défaut : non définie. À partir de PHP 8.2.0.

Il est possible de passer des variables d'environnement additionnelles et mettre à jour les paramètres de PHP d'un pool. Pour ce faire, il faut ajouter les options suivantes au fichier de configuration du pool.

Exemple #1 Passer des variables d'environnement et des paramètres PHP à un pool

    env[HOSTNAME] = $HOSTNAME
    env[PATH] = /usr/local/bin:/usr/bin:/bin
    env[TMP] = /tmp
    env[TMPDIR] = /tmp
    env[TEMP] = /tmp

    php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
    php_flag[display_errors] = off
    php_admin_value[error_log] = /var/log/fpm-php.www.log
    php_admin_flag[log_errors] = on
    php_admin_value[memory_limit] = 32M

Les paramètres PHP passés avec `php_value` ou `php_flag` écraseront leur valeur précédente. Il est à noter que définir disable_functions n'écrasera pas les valeurs concernées précédemment définies dans php.ini, mais rajouteront les valeurs à la suite des anciennes.

Les paramètres définis avec `php_admin_value` et `php_admin_flag` ne peuvent être surchargés via ini_set().

Les paramètres de PHP peuvent être définis dans le serveur web.

Exemple #2 Définit les paramètres PHP dans le fichier nginx.conf

    set $php_value "pcre.backtrack_limit=424242";
    set $php_value "$php_value \n pcre.recursion_limit=99999";
    fastcgi_param  PHP_VALUE $php_value;

    fastcgi_param  PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";

Attention

En raison du fait que ces configurations sont passées à php-fpm comme en-têtes fastcgi, php-fpm ne doit pas être relié directement au web et ainsi y être directement accessible. Sinon, tout le monde pourra altérer les options de configuration de PHP. Voir aussi l'option listen.allowed_clients.

> Note: Les pools ne sont pas un mécanisme de sécurité, car ils ne fournissent pas une séparation totale ; par exemple tous les pools utiliseraient une seule instance OPcache.

# Installation d'extensions PECL

## Sommaire

- Introduction aux installations PECL
- Télécharger des extensions PECL
- Installer une extension PHP sous Windows
- Compilation d'extensions PECL partagées avec la commande pecl
- Compilation des extensions partagées avec phpize
- php-config
- Compilation des extensions PECL statiquement dans PHP

## Introduction aux installations PECL

> Note: L'installeur d'Extensions pour PHP (PHP Installer for Extensions - PIE) est un nouvel outil qui remplacera PECL. Nous recommandons d'utiliser PIE pour installer les extensions. Plus d'informations sur » https://github.com/php/pie

» PECL est un dépôt d'extensions PHP qui sont disponibles via le système de paquet » PEAR. Cette section du manuel a pour but de présenter la manière d'obtenir et d'installer les extensions de PECL.

Ces instructions supposent que `/path/to/php/src/dir/` est le chemin jusqu'aux sources de la distribution PHP, et `extname` est le nom de l'extension PECL. Ajuster les commandes qui suivent en conséquence. Ces instructions supposent aussi une familiarité avec l'utilisation des » commandes pear. Les informations dans le manuel PEAR pour la commande pear sont également applicables à la commande pecl.

Une extension partagée doit être compilée, installée et chargée pour être utilisée. Les méthodes décrites ci-dessous fournissent diverses instructions sur la façon de compiler et d'installer des extensions mais ne les chargent pas automatiquement. Les extensions peuvent être chargées en ajoutant une directive d'extension au fichier php.ini ou à l'aide de la fonction dl().

Lors de la compilation de modules PHP, il est important d'avoir les outils dans leurs versions appropriées, tels que autoconf, automake, libtool, etc. Se référer aux » Instructions pour le Git anonyme, afin de connaître les utilitaires nécessaires, et leurs versions.

## Télécharger des extensions PECL

> Note: L'installeur d'Extensions pour PHP (PHP Installer for Extensions - PIE) est un nouvel outil qui remplacera PECL. Nous recommandons d'utiliser PIE pour installer les extensions. Plus d'informations sur » https://github.com/php/pie

Il existe plusieurs méthodes pour télécharger des extensions PECL :

- La commande pecl install extname télécharge le code des extensions automatiquement, ce qui évite de réaliser un téléchargement particulier.
- » https://pecl.php.net/ Le site Web de PECL contient diverses informations sur les différentes extensions offertes par l'équipe de développement de PHP. Plusieurs informations y sont disponibles incluant les modifications entre les versions, les notes de versions, ce qui est requis pour faire fonctionner l'extension ainsi que d'autres détails similaires.
- pecl download extname Les extensions PECL listées sur le site web de PECL sont disponibles et peuvent être téléchargées et installées en utilisant la » commande pecl. La version spécifique de l'extension peut également être spécifiée.
- git Beaucoup d'extensions PECL demeurent sur GitHub.
- SVN Certaines extensions PECL demeurent sur SVN. Une interface Web est disponible à » https://svn.php.net/pecl/. Pour télécharger directement depuis SVN, la séquence d'instructions ci-dessous peut être utilisée :

      $ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname

- Téléchargements pour Windows : Le projet PHP compile et offre des DLLs Windows pour la plupart des extensions PECL disponibles sur la page du package.

## Installer une extension PHP sous Windows

Il existe deux moyens de charger une extension PHP sous Windows : soit la compiler dans PHP, soit charger une DLL. Charger une extension précompilée est la méthode la plus pratique et la plus recommandée.

Pour charger une extension, son fichier .dll doit être disponible sur le système. Toutes les extensions sont automatiquement et périodiquement compilées par le groupe PHP (voir la section de téléchargements).

Pour compiler une extension dans PHP, se référer à la documentation sur la compilation des sources.

Pour compiler une extension autonome, (c'est-à-dire un fichier DLL), se référer à la documentation sur la compilation des sources. Si le fichier DLL est absent de la distribution PHP et de PECL, il pourrait être nécessaire de le compiler avant de pouvoir l'utiliser.

### Où trouver une extension ?

Les extensions PHP sont généralement appelées php_*.dll (où les astérisques représentent le nom de l'extension) et elles sont rangées dans le dossier PHP\ext.

PHP est livré avec les extensions qui sont les plus utiles à la majorité des utilisateurs. Elles sont appelées des extensions bundled (intégrées).

Cependant, si les extensions intégrées ne fournissent pas la fonctionnalité nécessaire, une extension qui le fait peut être trouvée dans » PECL. Le PHP Extension Community Library (PECL, aussi dit Bibliothèque d'Extensions Communautaires de PHP) est un dépôt pour les extensions PHP, fournissant un répertoire de toutes les extensions connues et des facilités d'hébergement pour le téléchargement et le développement d'extensions PHP.

Si une extension a été développée pour un usage particulier, elle peut être hébergée sur PECL afin que d'autres personnes ayant les mêmes besoins puissent en bénéficier. Un effet secondaire intéressant est que c'est une bonne occasion de recevoir des commentaires, (avec un peu de chance) des remerciements, des rapports de bogues et même des correctifs. Avant de soumettre une extension pour hébergement sur PECL, merci de lire » PECL submit.

### Quelles extensions télécharger ?

Il existe souvent plusieurs versions de chaque DLL :

- Différents numéros de versions (au moins, les deux premiers chiffres doivent être les mêmes)
- Différentes configurations de sécurité de threads
- Différentes architectures de processeurs (x86, x64...)
- Différentes configurations de débogage
- `etc.`

Il est recommandé de choisir les extensions pour qu'elles soient adaptées à la machine serveur sur laquelle PHP est utilisé. Le script suivant va afficher toutes les configurations PHP :

Exemple #1 Appel de la fonction phpinfo()

    <?php
    phpinfo();
    ?>

Ou bien, en ligne de commande :

    drive:\path\to\php\executable\php.exe -i

### Charger une extension

Le moyen le plus courant pour charger une extension PHP est de l'inclure dans le fichier de configuration php.ini. Il est à noter que de nombreuses extensions sont déjà présentes dans le fichier php.ini et qu'il suffit simplement de supprimer le point-virgule pour les activer.

À partir de PHP 7.2.0, le nom de l'extension peut être utilisé à la place du nom de fichier de l'extension. Comme il est indépendant de l'OS et plus facile, en particulier pour les nouveaux arrivants, il devient la manière recommandée de spécifier des extensions à charger. Les noms de fichiers restent pris en charge pour la compatibilité avec les versions antérieures.

    ;extension=php_extname.dll

    extension=php_extname.dll

    ; À partir de PHP 7.2, favoriser :
    extension=extname
    zend_extension=another_extension

Cependant, certains serveurs Web sont déroutants, car ils n'utilisent pas le fichier php.ini rangé avec l'exécutable PHP. Pour en savoir plus sur le véritable php.ini utilisé, il est possible de rechercher son emplacement à l'aide de phpinfo():

    Configuration File (php.ini) Path   C:\WINDOWS

    Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini

Après activation d'une extension, sauvegarder le fichier php.ini, et relancer le serveur Web, puis vérifier à nouveau le fichier phpinfo(). La nouvelle extension devrait y avoir sa section.

### Résolution de problèmes

Si l'extension n'apparaît pas dans phpinfo(), il convient de vérifier les journaux d'événements pour savoir d'où vient le problème.

Si PHP est utilisé en ligne de commande (CLI), l'erreur de chargement de l'extension devrait être lisible directement sur l'écran.

Si PHP est utilisé sur un serveur Web, la position et le format des journaux d'événements varient grandement d'un serveur à l'autre. Lire la documentation du serveur Web pour savoir où ils sont : PHP n'a aucun contrôle sur cet emplacement.

Les problèmes les plus courants sont la localisation du fichier DLL et les DLLs dont il dépend, la valeur de la directive "extension_dir" dans le php.ini et les incohérences de compilations.

Si le problème est une incohérence de compilation, la DLL téléchargée n'est probablement pas la bonne. Il est recommandé d'en télécharger une nouvelle, avec les bonnes configurations du serveur. phpinfo() sera fortement utile.

## Compilation d'extensions PECL partagées avec la commande pecl

PECL facilite la création d'extensions PHP partagées. En utilisant la » commande pecl, procéder comme suit :

    $ pecl install extname

Ceci va télécharger le fichier source de l'extension extname, le compiler et installer le fichier extname.so dans le dossier extension_dir. extname.so doit ensuite être chargé via php.ini.

Par défaut, la commande pecl n'installera pas les paquets marqués comme étant `alpha` ou `beta`. Si aucun paquet `stable` n'est disponible, il est possible d'installer un paquet `beta` en utilisant la commande suivante :

    $ pecl install extname-beta

Il est également possible d'installer une version spécifique en utilisant la commande :

    $ pecl install extname-0.1

> Note:

> Après avoir activé l'extension dans le php.ini, il est requis de relancer le serveur Web afin de la prendre en compte.

## Compilation des extensions partagées avec phpize

Parfois, l'utilisation de l'installeur pecl n'est pas une option. Cela peut être dû à la présence d'un pare-feu ou au fait que l'extension en cours d'installation n'est pas disponible en tant que paquet PECL compatible, comme les extensions non publiées provenant de git. Si une telle extension doit être construite, les outils de construction de niveau inférieur peuvent être utilisés pour effectuer la construction manuellement.

La commande phpize est utilisée pour préparer l'environnement de compilation pour une extension PHP. Dans l'exemple suivant, les sources de l'extension sont dans un dossier appelé extname :

    $ cd extname
    $ phpize
    $ ./configure
    $ make
    # make install

Une installation réussie créera un fichier extname.so et le placera dans le dossier des extensions de PHP. Le php.ini devra être ajusté, et la ligne `extension=extname.so` ajoutée avant de pouvoir utiliser l'extension.

Si le système ne possède pas la commande phpize et que des paquets précompilés (comme des RPM) sont utilisés, il faut s'assurer d'installer également la version de développement appropriée des paquets PHP car elle inclut également la commande phpize ainsi que les en-têtes appropriés pour construire PHP et ses extensions.

Exécuter la commande phpize --help pour afficher des informations d'utilisation supplémentaires.

## php-config

php-config est un petit script shell pour obtenir des informations sur la configuration installée de PHP.

Lors de la compilation des extensions, si plusieurs versions de PHP sont installées, l'installation pour laquelle il faut construire peut être spécifiée en utilisant l'option --with-php-config lors de la configuration, en définissant le chemin du script php-config correspondant.

La liste des options de ligne de commande fournies par le script php-config peut être obtenue en exécutant le script php-config avec l'option -h :

    Usage: /usr/local/bin/php-config [OPTION]
    Options:
      --prefix            [...]
      --includes          [...]
      --ldflags           [...]
      --libs              [...]
      --extension-dir     [...]
      --include-dir       [...]
      --php-binary        [...]
      --php-sapis         [...]
      --configure-options [...]
      --version           [...]
      --vernum            [...]

Options de ligne de commande
Option | Description
--- | ---
--prefix | Préfixe du dossier où PHP est installé, c.-à-d. /usr/local
--includes | Liste des options `-I` avec tous les fichiers inclus
--ldflags | Drapeaux `LD` qui ont été compilés avec PHP
--libs | Bibliothèques additionnelles qui ont été compilées avec PHP
--extension-dir | Dossiers où les extensions sont recherchées par défaut
--include-dir | Préfixe du dossier où les en-têtes de fichiers sont installés par défaut
--php-binary | Chemin complet vers le CLI PHP ou le binaire CGI
--php-sapis | Affiche tous les modules SAPI disponibles
--configure-options | Options de configuration pour recréer la configuration de l'installation courante de PHP
--version | Version de PHP
--vernum | Version de PHP sous la forme d'un entier

## Compilation des extensions PECL statiquement dans PHP

Il peut être nécessaire de construire une extension PECL statiquement dans le binaire PHP. Pour ce faire, les sources de l'extension doivent être placées dans le répertoire /path/to/php/src/dir/ext/, et le système de compilation de PHP doit régénérer son script de configuration.

    $ cd /path/to/php/src/dir/ext
    $ pecl download extname
    $ gzip -d < extname.tgz | tar -xvf -
    $ mv extname-x.x.x extname

Cela générera le dossier suivant :

    /path/to/php/src/dir/ext/extname

À partir de là, PHP doit être forcé à reconstruire le script de configuration, et ensuite il peut être construit normalement :

    $ cd /path/to/php/src/dir
    $ rm configure
    $ ./buildconf --force
    $ ./configure --help
    $ ./configure --with-extname --enable-someotherext --with-foobar
    $ make
    $ make install

> Note: Pour exécuter le script buildconf, autoconf `2.68` et automake `1.4+` seront nécessaires. Les versions plus récentes de autoconf peuvent fonctionner mais ne sont pas supportées.

L'utilisation de --enable-extname ou --with-extname dépend de l'extension. En général, une extension qui ne nécessite pas de bibliothèques externes utilise --enable. Pour s'en assurer, exécuter la commande suivante après buildconf :

    $ ./configure --help | grep extname

# Installation de Composer et des paquets tiers

## Introduction à Composer

» Composer est un gestionnaire de dépendances pour PHP qui permet de définir des paquets de code tiers utilisés par un projet et qui peuvent ensuite être facilement installés et mis à jour. Il exploite les fonctionnalités d'autochargement des classes natives de PHP, les dépôts de paquets PHP tels que » Packagist, et les conventions de disposition et de codage de projet courantes.

Par exemple, si une application ou un site Web PHP doit travailler avec des valeurs UUID, » Le paquet `ramsey/uuid` de Ben Ramsey qui implémente les types d'UUID largement connus et utilisés définis par » RFC 4122 pourrait être utilisé.

Pour résumer, cela est fait en créant un `composer.json` dans le projet, en utilisant Composer pour installer la dernière version du paquet, et en incluant le script d'autoload de Composer pour le rendre disponible au code. La » documentation "Utilisation de base" de Composer va plus en profondeur sur ce sujet.

Exemple #1 `composer.json` qui nécessite un seul paquet

    {
        "require": {
            "ramsey/uuid": "^4.7"
        }
    }

# Installation de PIE et des extensions tierces

## Introduction à PIE

» PIE est une application d'installation pour PHP, qui permet d'installer des extensions tierces pour PHP, qui peuvent ensuite être facilement installées et mises à jour. Elle exploite la partie du référentiel d'extensions PHP de » Packagist pour trouver le code source à compiler pour l'extension, ou un binaire Windows à télécharger, s'il existe. Si elle télécharge le code source, elle sait aussi comment le compiler et l'installer.

Après » l'installation des prérequis et de PIE lui-même, il est ensuite possible d'installer l'extension MongoDB en exécutant la commande suivante en ligne de commande.

Exemple #1 Installer l'extension MongoDB avec PIE

    pie install mongodb/mongodb-extension

La » documentation "PIE Usage" explique cela avec plus de détails.

# Configuration à l'exécution

## Sommaire

- Le fichier de configuration
- Fichiers .user.ini
- Où une directive de configuration peut être modifiée
- Comment modifier la configuration

## Le fichier de configuration

Le fichier de configuration (php.ini) est lu par PHP au démarrage. Si PHP a été compilé en module, le fichier n'est lu qu'une seule fois, au lancement du serveur web. Pour les versions CGI et CLI le fichier est lu à chaque invocation.

Le php.ini est cherché dans ces endroits (et dans cet ordre) :

- L'endroit spécifique du module SAPI (la directive `PHPIniDir` d'Apache 2, l'option de la ligne de commande `-c` en CGI et en CLI)
- La variable d'environnement PHPRC.
- L'endroit où se trouve le fichier `php.ini` peut être défini pour différentes versions de PHP. La racine des clés de registre dépend de l'architecture 32 ou 64 bit de l'OS et de PHP. Pour un OS et PHP 32 bit ou un OS et PHP 64 bit, utiliser `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` pour PHP 32 bit sur un OS 64 bit, utiliser `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]` à la place. Pour une installation avec la même architecture, les clés de registre suivantes sont cherchées dans cet ordre : `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]` et `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]`, où x, y et z signifient les versions majeures, mineures et normales. Pour une architecture 32 bit de PHP sur un OS 64 bit, les clés de registre suivantes sont cherchées dans cet ordre : `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]` et `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]`, où x, y et z signifient les versions majeures, mineures et normales. S'il y a une valeur pour `IniFilePath` dans ces clés, la première trouvée sera utilisée comme endroit où se trouve le fichier `php.ini` (uniquement sous Windows).
- `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` ou `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]`, valeur de `IniFilePath` (uniquement sous Windows).
- Le dossier courant de travail (sauf pour CLI)
- Le dossier du serveur web (pour les modules SAPI), ou le dossier contenant PHP (autrement sous Windows)
- Le dossier Windows (C:\windows ou C:\winnt) (pour Windows), ou l'option de compilation `--with-config-file-path` lors de la compilation

Si le fichier php-SAPI.ini existe (où SAPI utilise SAPI, donc le nom du fichier est par exemple php-cli.ini ou php-apache.ini), il sera utilisé à la place du php.ini. Le nom SAPI peut être déterminé en utilisant la fonction php_sapi_name().

> Note:

> Le serveur web Apache change ce dossier en dossier root au démarrage, ce qui fait que PHP essaye de lire php.ini depuis le système de fichiers racine s'il existe.

Les variables d'environnement peuvent être référencées dans les valeurs de configuration de php.ini comme illustré ci-dessous. À partir de PHP 8.3.0, une valeur de repli peut être spécifiée, qui sera utilisée lorsque la variable référencée n'est pas définie.

Exemple #1 Variables d'environnement dans php.ini

    ; PHP_MEMORY_LIMIT est repris depuis l'environnement
    memory_limit = ${PHP_MEMORY_LIMIT}
    ; Si PHP_MAX_EXECUTION_TIME n'est pas défini, il prendra la valeur de repli 30.
    max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}

Les directives php.ini sont directement documentées, par extensions, sur les pages respectives du manuel de ces extensions. La liste des directives internes est disponible en annexe. Il est probable que toutes les directives PHP ne sont pas documentées dans le manuel. Pour une liste complète des directives disponibles dans la version de PHP utilisée, il convient de lire les commentaires du fichier php.ini. Il est également possible de trouver la » dernière version du php.ini sur Git.

Exemple #2 Extrait du php.ini

    ; tout texte sur une ligne, situé après un point-virgule ";" est ignoré
    [php] ; les marqueurs de section (texte entre crochets) sont aussi ignorés
    ; Les valeurs booléennes peuvent être spécifiées comme ceci :
    ;    true, on, yes
    ; ou false, off, no, none
    register_globals = off
    track_errors = yes

    ; vous pouvez placer les chaînes de caractères entre guillemets
    include_path = ".:/usr/local/lib/php"

    ; Les antislash sont traités comme n'importe quel caractère
    include_path = ".;c:\php\lib"

Il est possible de se référer à des variables .ini depuis des fichiers .ini. Par exemple : `open_basedir = ${open_basedir} ":/new/dir"`.

### Parcourir des répertoires

Il est possible de configurer PHP pour lire les fichiers .ini présents dans un dossier, après la lecture de php.ini. Cela est réglé lors de la compilation avec l'argument --with-config-file-scan-dir. Le dossier à lire peut être modifié lors de l'exécution par la définition de la variable d'environnement PHP_INI_SCAN_DIR.

Il est possible de lire plusieurs dossiers en les séparant avec un séparateur de chemin spécifique à la plateforme (`;` pour Windows, NetWare et RISC OS; `:` pour toutes les autres plateformes; la valeur utilisée par PHP est disponible dans la constante `PATH_SEPARATOR`). Si un dossier vide est fourni dans PHP_INI_SCAN_DIR, PHP lira également le dossier fourni à la compilation via --with-config-file-scan-dir.

Dans chaque répertoire, PHP lira tous les fichiers terminant par `.ini` dans l'ordre alphabétique. Une liste des fichiers qui ont été chargés et dans quel ordre est disponible en appelant la fonction php_ini_scanned_files(), ou en exécutant PHP avec l'option --ini.

    En supposant que PHP est configuré avec --with-config-file-scan-dir=/etc/php.d,
    et que le séparateur de chemin est :...

    $ php
      PHP va charger tous les fichiers présents dans /etc/php.d/*.ini comme fichiers
      de configuration.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
      PHP va charger tous les fichiers présents dans /usr/local/etc/php.d/*.ini
      comme fichiers de configuration.

    $ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
      PHP va charger tous les fichiers présents dans /etc/php.d/*.ini, puis
      /usr/local/etc/php.d/*.ini comme fichiers de configuration.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
      PHP va charger tous les fichiers présents dans /usr/local/etc/php.d/*.ini, puis dans
      /etc/php.d/*.ini comme fichiers de configuration.

## Fichiers .user.ini

PHP inclut la prise en charge des fichiers INI de configuration par répertoire. Ces fichiers sont analysés uniquement par le SAPI CGI/FastCGI. Cette fonctionnalité rend obsolète l'extension PECL `htscanner`. Lors de l'exécution de PHP en tant que module Apache, l'utilisation des fichiers .htaccess produit le même effet.

En plus du fichier php.ini principal, PHP analyse les fichiers INI contenus dans chaque dossier, en commençant par le dossier depuis lequel le fichier PHP courant est appelé, et parcourt les dossiers jusqu'au dossier racine courant (tel que défini par la variable $_SERVER['DOCUMENT_ROOT']). Dans le cas où le fichier PHP est hors de la racine web, seul son dossier est scanné.

Seules les configurations INI avec les modes `INI_PERDIR` et `INI_USER` seront reconnues dans les fichiers INI .user.ini-style.

Deux nouvelles directives INI, user_ini.filename et user_ini.cache_ttl contrôlent l'utilisation des fichiers INI définis par l'utilisateur.

user_ini.filename définit le nom du fichier cherché par PHP dans chaque dossier ; si cette directive est définie à une chaîne vide, PHP n'analysera rien du tout. Par défaut, vaut `.user.ini`.

user_ini.cache_ttl contrôle la durée entre 2 re-lectures des fichiers INI définis par l'utilisateur. Par défaut, vaut 300 secondes (5 minutes).

## Où une directive de configuration peut être modifiée

Ces modes déterminent quand et où une directive PHP peut ou ne peut pas être modifiée, et chaque directive du manuel fait référence à un de ces modes. Par exemple, certaines directives peuvent être modifiées dans un script PHP avec la fonction ini_set(), alors que d'autres ont besoin d'être modifiées dans les fichiers php.ini ou httpd.conf.

Par exemple, la directive output_buffering a le mode `INI_PERDIR` alors elle ne peut pas être modifiée avec la fonction ini_set(). D'un autre côté, la directive display_errors a le mode `INI_ALL`, et peut être modifiée n'importe où, y compris avec la fonction ini_set().

Constantes de mode INI
`INI_USER` (int)
  L'entrée peut être définie dans des scripts utilisateur (comme avec ini_set()) ou dans le registre Windows. L'entrée peut être définie dans .user.ini
`INI_PERDIR` (int)
  L'entrée peut être définie dans php.ini, .htaccess, httpd.conf ou .user.ini
`INI_SYSTEM` (int)
  L'entrée peut être définie dans php.ini ou httpd.conf
`INI_ALL` (int)
  L'entrée peut être définie n'importe où

## Comment modifier la configuration

### Exécuter PHP comme module Apache

Lors de l'utilisation du module Apache, il est aussi possible de changer les paramètres de configuration en utilisant les directives dans les fichiers de configuration d'Apache (httpd.conf) et dans les fichiers .htaccess. Les privilèges "AllowOverride Options" ou "AllowOverride All" sont nécessaires.

Il y a de nombreuses directives Apache qui permettent de modifier la configuration de PHP à partir des fichiers de configuration Apache. Pour une liste des directives qui sont `INI_ALL`, `INI_PERDIR` ou `INI_SYSTEM` se reporter à l'annexe Liste des directives du php.ini.

`php_value` `nom` `valeur`

  Modifie la valeur de la directive spécifiée. Cette instruction n'est utilisable qu'avec les directives PHP de type `INI_ALL` et `INI_PERDIR`. Pour annuler une valeur qui aurait été modifiée au préalable, utiliser la valeur `none`.

  > Note: Ne pas utiliser `php_value` pour configurer des valeurs booléennes. `php_flag` (voir plus bas) doit être utilisée.

`php_flag` `nom` `on|off`

  Cette instruction est utilisée pour activer ou désactiver une option. Cette instruction n'est utilisable qu'avec les directives PHP de type `INI_ALL` et `INI_PERDIR`.

`php_admin_value` `nom` `valeur`

  Cette instruction affecte une valeur à la directive spécifiée. Cette instruction NE peut PAS être utilisée dans un fichier .htaccess. Toute directive de PHP configurée avec le type `php_admin_value` ne peut pas être modifiée en utilisant le fichier .htaccess ou la fonction ini_set(). Pour annuler une valeur qui aurait été modifiée au préalable, utiliser la valeur `none`.

`php_admin_flag` `nom` `on|off`

  Cette directive est utilisée pour activer ou désactiver une option. Cette instruction NE peut PAS être utilisée dans un fichier .htaccess. Toute directive de PHP configurée avec le type `php_admin_flag` ne peut pas être modifiée en utilisant le fichier .htaccess ou par la fonction ini_set().

Exemple #1 Exemple de configuration Apache

    <IfModule mod_php5.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>
    <IfModule mod_php4.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>

Attention

Les constantes PHP n'existent pas en dehors de PHP. Par exemple, dans le fichier httpd.conf, il n'est pas possible d'utiliser des constantes PHP telles que `E_ALL` ou `E_NOTICE` pour spécifier le niveau de rapport d'erreur, car ces constantes n'ont pas de signification pour Apache, et seront remplacées par 0. Utiliser les valeurs numériques à la place. Les constantes peuvent être utilisées dans le php.ini

### Modifier la configuration de PHP via la base de registre Windows

Lors de l'utilisation de PHP sur Windows, la configuration peut être modifiée dossier par dossier en utilisant la base de registres de Windows. Les valeurs de configuration sont stockées avec la clé de registre `HKLM\SOFTWARE\PHP\Per Directory Values`, dans les sous-clés correspondantes aux noms de dossier. Par exemple, la valeur d'une option dans le dossier `c:\inetpub\wwwroot` sera stockée dans la clé `HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot`. La valeur de cette option sera utilisée pour tous les scripts qui fonctionnent dans ce dossier ou ses sous-dossiers. Les valeurs sous la clé doivent avoir le nom d'une directive de configuration PHP, et la valeur correspondante. Les constantes PHP ne sont pas utilisables : il faut mettre la valeur entière. Cependant, seules les valeurs des configurations dans `INI_USER` peuvent être fixées de cette manière, celles dans `INI_PERDIR` ne peuvent l'être, car ces valeurs de configurations sont relues à chaque requête.

### Autres interfaces de configuration de PHP

Suivant la façon dont PHP est exécuté, il est possible de changer certaines valeurs durant l'exécution des scripts en utilisant ini_set(). Voir la documentation de la fonction ini_set() pour plus d'informations.

Pour obtenir une liste complète des options configurées sur le système avec leurs valeurs courantes, il est possible d'exécuter la fonction phpinfo() et de consulter la page résultante. Il est aussi possible d'accéder individuellement aux directives de configuration pendant l'exécution des scripts en utilisant soit la fonction ini_get(), soit la fonction get_cfg_var().

- Considérations générales sur l'installation
- Installation sur les systèmes Unix
  - Installation à partir de paquets sur Debian GNU/Linux et distributions similaires
  - Installation depuis les paquets sur les distributions GNU/Linux qui utilisent DNF
  - Installation à partir de paquets ou de ports sur OpenBSD
  - Installation depuis les sources sur les systèmes Unix et macOS
  - CGI et configuration en ligne de commande
  - Apache 2.x sur les systèmes Unix
  - Nginx 1.4.x sur les systèmes Unix
  - Lighttpd 1.4 sur les systèmes Unix
  - Serveur Web LiteSpeed/Serveur Web OpenLiteSpeed sur les systèmes Unix
  - Installation sous Solaris
- Installation sur un système macOS
  - Installation sur macOS en utilisant des packages tiers
  - Compiler PHP sur macOS
  - Utilisation de PHP embarqué antérieur à macOS Monterey
- Installation sur les systèmes Windows
  - Configuration recommandée sur les systèmes Windows
  - Installation manuelle des binaires pré-compilés
  - Installation pour Apache 2.x sur les systèmes Windows
  - Installation avec IIS pour Windows
  - Outils tiers pour l'installation de PHP
  - Construire à partir des sources
  - Exécution de PHP en ligne de commande sur les systèmes Windows
- Installation sur des plateformes de Cloud Computing
  - Azure App Services
  - Amazon EC2
  - DigitalOcean
- FastCGI Process Manager (FPM)
  - Installation
  - Configuration
- Installation d'extensions PECL
  - Introduction aux installations PECL
  - Télécharger des extensions PECL
  - Installer une extension PHP sous Windows
  - Compilation d'extensions PECL partagées avec la commande pecl
  - Compilation des extensions partagées avec phpize
  - php-config
  - Compilation des extensions PECL statiquement dans PHP
- Introduction à Composer
- Introduction à PIE
- Configuration à l'exécution
  - Le fichier de configuration
  - Fichiers .user.ini
  - Où une directive de configuration peut être modifiée
  - Comment modifier la configuration

# Référence du langage

# La syntaxe de base

## Sommaire

- Balises PHP
- Échappement depuis du HTML
- Séparation des instructions
- Commentaires

## Balises PHP

Lorsque PHP traite un fichier, il reconnaît les balises d'ouverture et de fermeture, `<?php` et `?>`, pour définir les limites de l'exécution du code PHP. Le contenu en dehors des balises est ignoré par l'analyseur PHP, permettant à PHP de s'intégrer de manière transparente dans divers types de documents.

Un caractère d'espace (espace, tabulation, ou nouvelle ligne) doit suivre `<?php` pour assurer une séparation correcte des jetons. Omettre cet espace blanc entraînera une erreur de syntaxe.

PHP inclut également la balise courte echo `<?=`, qui est un raccourci pour `<?php echo`.

Exemple #1 Balises d'ouverture et de fermeture PHP

    1.  <?php echo 'Si vous voulez intégrer du code PHP dans des documents XHTML ou XML, utilisez ces balises'; ?>

    2.  Vous pouvez utiliser la balise courte pour <?= 'écrire ce texte' ?>.
        Est équivalent à <?php echo 'écrire ce texte' ?>.

    3.  <? echo 'ce code est entre des balises courtes, mais ne fonctionnera '.
                'que si short_open_tag est activé'; ?>

Les balises courtes (troisième exemple) sont disponibles par défaut, mais peuvent être désactivées soit via l'option short_open_tag du fichier de configuration php.ini, ou sont désactivées par défaut si PHP est compilé avec l'option --disable-short-tags.

> Note:

> Comme les balises courtes peuvent être désactivées il est recommandé de seulement utiliser les balises normales (`<?php ?>` et `<?= ?>`) pour maximiser la compatibilité.

Si un fichier se termine avec du code PHP, il est préférable de ne pas placer la balise de fermeture à la fin du fichier. Ceci permet d'éviter d'oublier un espace ou une nouvelle ligne après la balise de fermeture de PHP, ce qui causerait des effets non voulus car PHP commencera à afficher la sortie, ce qui n'est souvent pas le cas désiré.

Exemple #2 Fichier contenant uniquement du code PHP

    <?php
    echo "Bonjour le monde\n";

    // ... encore du code

    echo "Dernière instruction\n";

    // le script se termine ici, sans la balise de fermeture PHP

## Échappement depuis du HTML

Tout ce qui se trouve en dehors d'une paire de balises ouvrantes/fermantes est ignoré par l'analyseur PHP, ce qui permet d'avoir des fichiers PHP mixant les contenus. Ceci permet à PHP d'être contenu dans des documents HTML, pour créer par exemple des templates.

Exemple #1 Intégrer du PHP dans du HTML

    <p>Ceci sera ignoré par PHP et affiché au navigateur.</p>
    <?php echo 'Alors que ceci sera analysé par PHP.'; ?>
    <p>Ceci sera aussi ignoré par PHP et affiché au navigateur.</p>

Ceci fonctionne comme prévu parce que lorsque l'interpréteur PHP rencontre la balise fermante ?>, il commence simplement à afficher ce qu'il rencontre (mis à part la nouvelle ligne qui est immédiatement suivie : voir la séparation des instructions) jusqu'à ce qu'il rencontre une autre balise ouvrante même si PHP se trouve au milieu d'une instruction conditionnelle, auquel cas, l'interpréteur va déterminer la condition à prendre en compte avant de prendre une décision sur ce qui doit être affiché. Voir le prochain exemple.

Utilisation de structures avec des conditions

Exemple #2 Échappement avancé en utilisant des conditions

    <?php if ($expression == true): ?>
      Ceci sera affiché si l'expression est vraie.
    <?php else: ?>
      Sinon, ceci sera affiché.
    <?php endif; ?>

Dans cet exemple, PHP va ignorer les blocs où la condition n'est pas remplie, même s'ils sont en dehors des balises ouvrantes/fermantes de PHP. PHP va les ignorer suivant la condition vu que l'interpréteur PHP va passer les blocs contenant ce qui n'est pas rempli par la condition.

Pour afficher de gros blocs de texte, il est plus efficace de sortir du mode d'analyse de PHP plutôt que d'envoyer le texte via la fonction echo ou print.

> Note:

> Si PHP est intégré dans un document XML ou XHTML, la balise PHP standard `<?php ?>` doit être utilisée pour rester conforme aux standards.

## Séparation des instructions

Comme en C ou en Perl, PHP requiert que les instructions soient terminées par un point-virgule à la fin de chaque instruction. La balise fermante d'un bloc de code PHP implique automatiquement un point-virgule ; il n'est donc pas nécessaire d'utiliser un point-virgule pour terminer la dernière ligne d'un bloc PHP. La balise fermante du bloc englobera la ligne suivante, si elle existe.

Exemple #1 Exemple montrant que la balise fermante englobe la nouvelle ligne qui suit

    <?php echo "Du texte"; ?>
    Pas de nouvelle ligne
    <?= "Mais une nouvelle ligne maintenant" ?>

L'exemple ci-dessus va afficher :

    Du textePas de nouvelle ligne
    Mais une nouvelle ligne maintenant

Exemple #2 Exemples d'entrée et de sortie du parseur PHP

    <?php
        echo "Ceci est un test\n";
    ?>

    <?php echo "Ceci est un test\n" ?>

    <?php echo "La dernière balise fermante a été omise\n";

> Note:

> La balise fermante d'un bloc PHP à la fin d'un fichier est optionnelle, et parfois, il est utile de l'omettre lors de l'utilisation de la fonction include ou de la fonction require, car les espaces non désirés n'apparaîtront pas à la fin des fichiers, et ainsi, il sera toujours possible d'ajouter des en-têtes à la réponse plus tard. C'est utile également lors de l'utilisation de l'affichage du buffer pour éviter de voir des espaces blancs ajoutés à la fin des parties générées par les fichiers inclus.

## Commentaires

PHP supporte les commentaires de type C, C++ et Shell Unix (aussi appelé style Perl). Par exemple :

Exemple #1 Commentaires

    <?php
        echo "Ceci est un test\n"; // Ceci est un commentaire sur une seule ligne, style c++
        /* Ceci est un commentaire sur
           plusieurs lignes */
        echo "Ceci est un autre test\n";
        echo "Et un test final\n"; # Ceci est un commentaire style shell sur une seule ligne
    ?>

Les commentaires sur une seule ligne ne commentent que jusqu'à la fin de la ligne du bloc PHP courant. Ceci signifie que le code HTML après `// ... ?>` ou après `# ... ?>` SERA affiché : ?> terminera le mode PHP et retournera en mode HTML, et `//` ou `#` n'influencera pas cela.

Exemple #2 Les commentaires vont jusqu'à la fin de la ligne

    <h1>Ceci est un exemple <?php # echo 'simple';?></h1>
    <p>La ligne ci-dessus affichera 'Ceci est un exemple'.</p>

Les commentaires style 'C' commentent jusqu'à ce que le premier `*/` soit rencontré. Il faut faire attention aux commentaires style 'C' nichés dans de gros blocs lors de la mise en commentaire.

    <?php
     /*
        echo 'Ceci est un test'; /* Ce commentaire posera un problème */
     */
    ?>

# Les types

## Sommaire

- Introduction
- Système de type
- NULL
- Booléen
- Les entiers
- Nombres à virgule flottante
- Chaînes
- Chaînes numériques
- Les tableaux
- Les objets
- Les énumérations
- Les ressources
- Callables
- Mixed
- Void
- Never
- Types de classes relatives
- Type singleton
- Itérables
- Déclarations de type
- Jonglage de type

## Introduction

En PHP, chaque expression a l'un des types intégrés suivants en fonction de sa valeur :

- null
- bool
- int
- float (nombre à virgule flottante)
- string
- array
- object
- callable
- resource

PHP est un langage typé dynamiquement, ce qui signifie que par défaut, il n'est pas nécessaire de spécifier le type d'une variable, car cela sera déterminé au moment de l'exécution. Cependant, il est possible de typer statiquement certains aspects du langage en utilisant les déclarations de type. Différents types pris en charge par le système de types de PHP sont disponibles sur la page du système de types.

Les types limitent le type d'opérations qui peuvent être effectuées sur eux. Cependant, si une expression/variable est utilisée dans une opération que son type ne supporte pas, PHP tentera de jongler de type dans un type compatible avec l'opération. Ce processus dépend du contexte dans lequel la valeur est utilisée. Pour plus d’informations, consulter la section sur le jonglage de type.

Astuce

Les tableaux de comparaison de type peuvent également être utiles, car divers exemples de comparaison entre des valeurs de différents types sont présents.

> Note: Il est possible de forcer l’évaluation d’une expression à un certain type en utilisant un type casting. Une variable peut également être convertie sur place à l’aide de la fonction settype().

Pour vérifier le type et la valeur d'une expression, utiliser la fonction var_dump(). Pour récupérer le type d'une expression, utiliser la fonction get_debug_type(). Toutefois, pour vérifier si une expression est d'un certain type, utiliser plutôt les fonctions `is_type`.

Exemple #1 Types Différents

    <?php
    $a_bool = TRUE;   // un booléen
    $a_str  = "foo";  // une chaîne de caractères
    $a_str2 = 'foo';  // une chaîne de caractères
    $an_int = 12;     // un entier

    echo get_debug_type($a_bool), "\n";
    echo get_debug_type($a_str), "\n";

    // Si c'est un entier, incrément de 4
    if (is_int($an_int)) {
        $an_int += 4;
    }
    var_dump($an_int);

    // Si $a_bool est une chaîne de caractères, on l'affiche
    if (is_string($a_bool)) {
        echo "String: $a_bool";
    }
    ?>

Résultat de l'exemple ci-dessus en PHP 8 :

    bool
    string
    int(16)

> Note: Avant PHP 8.0.0, lorsque le get_debug_type() n’est pas disponible, la fonction gettype() peut être utilisée à la place. Cependant, elle n’utilise pas les noms de type canoniques.

## Système de type

PHP utilise un système de type nominal avec une relation de sous-typage comportementale forte. La relation de sous-typage est vérifiée à la compilation, tandis que la vérification des types est vérifiée dynamiquement au moment de l'exécution.

Le système de type de PHP supporte plusieurs types atomiques qui peuvent être composés ensemble pour créer des types plus complexes. Certains de ces types peuvent être écrits sous forme de déclaration de type.

### Types atomiques

Certains types atomiques sont des types qui sont étroitement intégrés au langage et ne peuvent être reproduits avec des types définis par l'utilisateur.

La liste des types de base est la suivante :

- Types intégrés
  - Types scalaires :
    - type bool
    - type int
    - type float
    - type string
  - type array
  - type object
  - type resource
  - type never
  - type void
  - Types de classes relatives: self, parent, et static
  - Types singletons
    - false
    - true
  - Types unitaires
    - null
- Types définis par l'utilisateur (généralement appelés classes-types)
  - Interfaces
  - Classes
  - Énumérations
- type callable

#### Types scalaires

Une valeur est considérée comme scalaire si elle est de type int, float, string ou bool.

#### Types définis par l'utilisateur

Il est possible de définir des types personnalisés avec des interfaces, des classes et des énumérations. Ceux-ci sont considérés comme des types définis par l'utilisateur, ou types de classe. Par exemple, une classe appelée `Elephant` peut être définie, puis des objets de type `Elephant` peuvent être instanciés, et une fonction peut demander un paramètre de type `Elephant`.

### Types composites

Il est possible de combiner plusieurs types atomiques en des types composites. PHP permet de combiner les types de la manière suivante :

- Intersection de classes-types (interfaces et noms de classes).
- Union de types.

#### Intersection de types

Un type d'intersection accepte des valeurs qui satisfont plusieurs déclarations de type de classe, plutôt qu'une seule. Les types individuels qui forment le type d'intersection sont reliés par le symbole `&`. Par conséquent, un type d'intersection composé des types `T`, `U` et `V` s'écrit `T&U&V`.

#### Types d'union

Un type union accepte des valeurs de plusieurs types différents, plutôt qu'un seul. Les types individuels qui forment le type d'union sont reliés par le symbole `|`. Par conséquent, un type d'union composé des types `T`, `U` et `V` s'écrit `T|U|V`. Si l'un des types est un type d'intersection, il doit être mis entre parenthèses pour être écrit en DNF : `T|(X&Y)`.

### Alias de type

PHP supporte deux alias de type : mixed et iterable qui correspondent au type d'union de `object|resource|array|string|float|int|bool|null` et `Traversable|array` respectivement.

> Note: PHP ne supporte pas les alias de type définis par l'utilisateur.

## NULL

Le type null est le type unité de PHP, c'est-à-dire qu'il n'a qu'une seule valeur: `null`.

Les variables non définies et les variables unset() auront la valeur `null`.

### Syntaxe

Il y a une seule valeur de type null, et c'est la constante insensible à la casse `null`.

    <?php
    $var = NULL;
    ?>

### Transtyper vers `null`

Avertissement

Cette fonctionnalité est OBSOLÈTE à partir de PHP 7.2.0, et SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonctionnalité est fortement déconseillé.

Transtyper une variable vers null en utilisant la syntaxe `(unset) $var` n'effacera pas la variable, ni écrasera sa valeur. Ça ne fera que retourner la valeur `null`.

### Voir aussi

- is_null()
- unset()

## Booléen

Le type bool ne possède que deux valeurs, et est utilisé pour exprimer une valeur de vérité. Il peut être soit `true` soit `false`.

### Syntaxe

Pour spécifier un booléen littéral, utiliser la constante `true` ou `false`. Les deux sont insensibles à la casse.

    <?php

    $foo = true; // assigne la valeur TRUE à $foo

    var_dump($foo); // bool(true)
    ?>

Typiquement, le résultat d'un opérateur qui retourne un booléen est passé ensuite à une structure de contrôle.

    <?php

    $action = "show_version";
    $show_separators = true;

    // == est un opérateur qui teste
    // l'égalité et retourne un booléen
    if ($action == "show_version") {
        echo "La version est 1.23";
    }

    // ceci n'est pas nécessaire...
    if ($show_separators == TRUE) {
        echo "<hr>\n";
    }

    // ...à la place, vous pouvez utiliser, avec la même signification :
    if ($show_separators) {
        echo "<hr>\n";
    }
    ?>

### Conversion en booléen

Pour convertir explicitement une valeur en bool, utiliser le cast `(bool)`. Généralement, cela n'est pas nécessaire car lorsqu'une valeur est utilisée dans un contexte logique, elle sera automatiquement interprétée comme une valeur de type bool. Pour plus d'informations, voir la page Type Juggling.

Lors d'une conversion en booléen, les valeurs suivantes sont considérées comme `false` :

- le booléen `false`, lui-même
- l'entier `0` (zéro)
- les nombres à virgule flottante `0.0` et `-0.0` (zéro)
- la chaîne vide `""`, et la chaîne `"0"`
- un tableau avec aucun élément
- le type unité NULL (incluant les variables non définies)
- les objets internes qui surchargent leur comportement de casting en booléen. Par exemple, les objets GMP représentant la valeur `0`.

Toutes les autres valeurs sont considérées comme `true` (y compris les ressources et `NAN`).

Avertissement

`-1` est considéré comme `true`, comme tous les nombres différents de zéro (négatifs ou positifs) !

Exemple #1 Conversion en booléen

    <?php
    var_dump((bool) "");        // bool(false)
    var_dump((bool) "0");       // bool(false)
    var_dump((bool) 1);         // bool(true)
    var_dump((bool) -2);        // bool(true)
    var_dump((bool) "foo");     // bool(true)
    var_dump((bool) 2.3e5);     // bool(true)
    var_dump((bool) array(12)); // bool(true)
    var_dump((bool) array());   // bool(false)
    var_dump((bool) "false");   // bool(true)
    ?>

## Les entiers

Un entier est un nombre appartenant à l'ensemble ℤ = {..., -2, -1, 0, 1, 2, ...}.

### Voir aussi

- Les nombres à virgule flottante
- Les précisions arbitraires / BCMath
- Les entiers de longueur arbitraire / GMP

### Syntaxe

Les entiers peuvent être spécifiés en notation décimale (base 10), hexadécimale (base 16), octale (base 8), ou binaire (base 2). L'opérateur de négation peut être utilisé pour désigner un entier négatif.

Pour utiliser la notation octale, il faut précéder le nombre d'un `0` (zéro). À partir de PHP 8.1.0, la notation octale peut également être précédée de `0o` ou `0O`. Pour utiliser la notation hexadécimale, il faut précéder le nombre de `0x`. Pour utiliser la notation binaire, il faut précéder le nombre de `0b`.

À partir de PHP 7.4.0, les entiers littéraux peuvent contenir des underscores (`_`) entre les chiffres, pour une meilleure lisibilité des littéraux. Ces underscores sont supprimés par le scanner de PHP.

Exemple #1 Les entiers littéraux

    <?php
    $a = 1234; // un nombre décimal
    $a = 0123; // un nombre octal (équivalent à 83 en décimal)
    $a = 0o123; // un nombre octal (à partir de PHP 8.1.0)
    $a = 0x1A; // un nombre hexadécimal (équivalent à 26 en décimal)
    $a = 0b11111111; // un nombre binaire (équivalent à 255 en décimal)
    $a = 1_234_567; // un nombre décimal (à partir de PHP 7.4.0)
    ?>

Formellement, la structure d'un entier littéral est à partir de PHP 8.1.0 (auparavant, les préfixes octaux `0o` ou `0O` n'étaient pas autorisés, et avant PHP 7.4.0, les underscores n'étaient pas autorisés) :

    decimal     : [1-9][0-9]*(_[0-9]+)*
                | 0

    hexadecimal : 0[xX][0-9a-fA-F]+(_[0-9a-fA-F]+)*

    octal       : 0[oO]?[0-7]+(_[0-7]+)*

    binary      : 0[bB][01]+(_[01]+)*

    integer     : decimal
                | hexadecimal
                | octal
                | binary

La taille d'un entier est dépendante de la plate-forme, cependant, une valeur maximale d'environ 2 milliards est habituelle (cela correspond à 32 bits signés). Les plate-formes 64-bit ont habituellement une valeur maximale d'environ 9E18. PHP ne supporte pas les entiers non-signés. La taille d'un entier peut être déterminée en utilisant la constante `PHP_INT_SIZE`, la valeur maximale, en utilisant la constante `PHP_INT_MAX`, et la valeur minimale en utilisant la constante `PHP_INT_MIN`.

### Débordement d'entier

Si PHP rencontre un nombre supérieur au maximum d'un entier, il sera interprété comme un nombre décimal. De la même façon, une opération qui résulte en un nombre en dehors de l'intervalle du type entier retournera un nombre décimal.

Exemple #2 Dépassement d'entier

    <?php
    $large_number = 50000000000000000000;
    var_dump($large_number);         // float(5.0E+19)

    var_dump(PHP_INT_MAX + 1);       // 32-bit system: float(2147483648)
                                     // 64-bit system: float(9.2233720368548E+18)
    ?>

### Division d'entier

Il n'y a pas d'opérateur de division d'entier en PHP, pour accomplir ceci, utiliser la fonction intdiv(). `1/2` produit le nombre décimal (`0.5`). La valeur peut être transtypée en un entier pour l'arrondir vers zéro, ou en utilisant la fonction round() pour avoir un contrôle plus fin sur la façon dont l'arrondi est exécuté.

Exemple #3 Division

    <?php
    var_dump(25/7);         // float(3.5714285714286)
    var_dump((int) (25/7)); // int(3)
    var_dump(round(25/7));  // float(4)
    ?>

### Conversion en entier

Pour convertir explicitement une valeur en un entier, utiliser le mot-clé `(int)`. Cependant, dans la plupart des cas, ce mot-clé n'est pas nécessaire vu qu'une valeur sera automatiquement convertie si un opérateur, une fonction ou une structure de contrôle demande un entier en guise d'argument. Une valeur peut également être convertie en un entier en utilisant la fonction intval().

Si une resource est convertie vers un entier, alors le résultat sera l'identifiant unique de la resource assigné par PHP à l'exécution.

Voir aussi le transtypage.

#### Depuis un booléen

`false` correspond à `0` (zéro), et `true` correspond à `1` (un).

#### Depuis un nombre à virgule flottante

Lors de la conversion d'un nombre décimal en entier, le nombre est arrondi vers zéro. À partir de PHP 8.1.0, une notification de dépréciation est émise lors de la conversion implicite d'un nombre décimal non-intégral en entier perdant en précision.

Exemple #4 Conversion depuis des nombres flottants

    <?php

    function foo($value): int {
      return $value;
    }

    var_dump(foo(8.1)); // "Deprecated: Implicit conversion from float 8.1 to int loses precision" à partir de PHP 8.1.0
    var_dump(foo(8.1)); // 8 avant PHP 8.1.0
    var_dump(foo(8.0)); // 8 dans les deux cas

    var_dump((int) 8.1); // 8 dans les deux cas
    var_dump(intval(8.1)); // 8 dans les deux cas
    ?>

Si le nombre à virgule flottante est au-delà des limites des entiers (habituellement, `+/- 2.15e+9 = 2^31` sur les plate-formes 32-bit et `+/- 9.22e+18 = 2^63` sur les plate-formes 64-bit), le résultat sera indéfini, sachant que le nombre décimal n'a pas une précision suffisante pour donner un résultat entier exact. Aucune alerte n'est émise lorsque ce comportement survient !

> Note:

> `NaN`, `Inf` et `-Inf` sont toujours égaux à zéro lors d'une conversion en int.

Avertissement

Ne jamais convertir une fraction inconnue en un entier, ceci peut engendrer des résultats inattendus.

    <?php
    echo (int) ( (0.1+0.7) * 10 ); // Affiche 7 !
    ?>

Voir aussi la section sur les alertes concernant la précision des nombres à virgule flottante.

#### Depuis des chaînes de caractères

Si une chaîne est numérique ou numérique de tête alors elle sera transformée en sa valeur entière correspondante, sinon elle sera convertie en zéro (`0`).

#### Depuis NULL

`null` est toujours converti en zéro (`0`).

#### Depuis d'autres types

Attention

Le comportement de la conversion en entier est indéfini pour les autres types. Ne pas se fier à un quelconque comportement observé, sachant qu'il peut changer sans avertissement.

## Nombres à virgule flottante

Les nombres à virgule flottante (aussi connus comme `"floats"`, `"doubles"`, ou `"nombres réels"`) peuvent être spécifiés en utilisant les syntaxes suivantes :

    <?php
    $a = 1.234;
    $b = 1.2e3;
    $c = 7E-10;
    $d = 1_234.567; // à partir de PHP 7.4.0
    ?>

Formellement à partir de PHP 7.4.0 (auparavant, les underscores n'étaient pas autorisés) :

    LNUM          [0-9]+(_[0-9]+)*
    DNUM          ({LNUM}?"."{LNUM}) | ({LNUM}"."{LNUM}?)
    EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})

La taille d'un nombre décimal est dépendante de la plate-forme, cependant, un nombre maximal d'environ 1.8e308 avec une précision sur 14 chiffres est une valeur commune (format 64 bits IEEE).

Avertissement

# Précision des nombres flottants

Les nombres flottants ont une précision limitée. Même s'ils dépendent du système, PHP utilise le format de double précision IEEE 754, qui donnera une erreur maximale relative de l'ordre de 1.11e-16 (due aux arrondis). Les opérations arithmétiques non-élémentaires peuvent donner des erreurs plus importantes et bien sûr les erreurs doivent être prises en compte lorsque plusieurs opérations sont liées.

Aussi, les nombres rationnels exactement représentables sous forme de nombre à virgule flottante en base 10, comme `0.1` ou `0.7`, n'ont pas de représentation exacte comme nombres à virgule flottante en base 2, utilisée en interne, et ce quelle que soit la taille de la mantisse. De ce fait, ils ne peuvent être convertis sans une petite perte de précision. Ceci peut mener à des résultats confus : par exemple, `floor((0.1+0.7)*10)` retournera normalement `7` au lieu de `8` attendu, car la représentation interne sera quelque chose comme `7.9999999999999991118...`.

Ainsi, il ne faut jamais faire confiance aux derniers chiffres d'un nombre flottant, et il ne faut pas non plus comparer l'égalité de 2 nombres flottants directement. Si une plus grande précision est nécessaire, les fonctions mathématiques de précision arbitraire et les fonctions gmp sont disponibles.

Pour une explication "simple", voir le » guide relatif aux nombres à virgule flottante qui est aussi intitulé "Why don't my numbers add up?"

### Convertir en un nombre flottant

#### Depuis des chaînes de caractères

Si une chaîne est numérique ou numérique de tête alors elle sera transformée en sa valeur flottante correspondante, sinon elle sera convertie en zéro (`0`).

#### Depuis d'autres types

Pour les valeurs d'autres types, la conversion est effectuée en convertissant la valeur d'abord en int puis en float. Voir conversion en entier pour plus d'informations.

> Note:

> Comme certains types ont un comportement indéfini lors de la conversion en int, ceci est aussi le cas lors de la conversion en float.

### Comparaison de nombres flottants

Comme dit dans la note ci-dessus, le test d'égalité des valeurs de nombres flottants est problématique, en raison de la façon dont ils sont représentés en interne. Cependant, il existe des façons de réaliser cette comparaison.

Pour tester l'égalité de valeurs de nombres flottants, une borne supérieure de l'erreur relative à l'arrondi est utilisée. Cette valeur est connue comme étant l'epsilon de la machine, ou le `unit roundoff`, et est la différence la plus petite acceptable dans les calculs.

$a et $b sont égaux sur 5 nombres après la virgule.

Exemple #1 Comparaison de nombres flottants

    <?php
    $a = 1.23456789;
    $b = 1.23456780;
    $epsilon = 0.00001;

    if (abs($a - $b) < $epsilon) {
        echo "true";
    }
    ?>

### NaN

Quelques opérations numériques peuvent donner comme résultat une valeur représentée par la constante `NAN`. Ce résultat représente une valeur indéfinie ou non représentable lors de calculs avec des nombres à virgule flottante. Toute comparaison, même stricte de cette valeur avec une autre valeur, y compris cette constante elle-même, sauf si elle est égale à `true`, donnera une valeur de `false`.

En raison du fait que `NAN` représente tout nombre de valeurs différentes, `NAN` ne devrait pas être comparé à d'autres valeurs, y compris cette constante elle-même, et à la place, devrait être vérifié en utilisant la fonction is_nan().

## Chaînes

Une chaîne est une série de caractères, où un caractère est le même qu'un octet. Cela signifie que PHP ne supporte qu'un ensemble de 256 caractères, et n'offre donc pas de support natif de l'Unicode. Voir les détails du type chaîne.

> Note: Sur les versions 32 bits, une chaîne peut être aussi grande que 2 Go (2147483647 octets maximum)

### Syntaxe

Une chaîne littérale peut être spécifiée de quatre manières différentes :

- entre guillemets simples
- entre guillemets doubles
- syntaxe heredoc
- syntaxe nowdoc

#### Entre guillemets simples

La manière la plus simple de spécifier une chaîne est de l'encadrer de guillemets simples (le caractère `'`).

Pour spécifier un guillemet simple littéral, échappez-le avec un antislash (`\`). Pour spécifier un antislash littéral, doublez-le (`\\`). Toutes les autres occurrences de l'antislash seront traitées comme un antislash littéral : cela signifie que les autres séquences d'échappement que l'on pourrait connaître, telles que `\r` ou `\n`, seront sorties littéralement comme spécifié plutôt que d'avoir une signification spéciale.

> Note: Contrairement aux guillemets doubles et syntaxes heredoc, les variables et les séquences d'échappement pour les caractères spéciaux ne seront pas étendues lorsqu'elles se trouvent dans des chaînes entre guillemets simples.

Exemple #1 Variantes de syntaxe

    <?php
    echo 'ceci est une chaîne simple', PHP_EOL;

    echo 'Vous pouvez également avoir des nouvelles intégrées dans
    les chaînes de cette manière, car c'est
    acceptable de le faire.', PHP_EOL;

    // Affiche : Arnold a dit un jour : "Je reviendrai"
    echo 'Arnold a dit un jour : "Je reviendrai"', PHP_EOL;

    // Affiche : Vous avez supprimé C:\*.* ?
    echo 'Vous avez supprimé C:\\*.* ?', PHP_EOL;

    // Affiche : Vous avez supprimé C:\*.* ?
    echo 'Vous avez supprimé C:\*.* ?', PHP_EOL;

    // Affiche : Cela ne s'étendra pas : \n une nouvelle ligne
    echo 'Cela ne s\'étendra pas : \n une nouvelle ligne', PHP_EOL;

    // Affiche : Les variables ne $s\'étendent pas $non plus
    echo 'Les variables ne $s\'étendent pas $non plus', PHP_EOL;
    ?>

#### Entre guillemets doubles

Si la chaîne est encadrée de guillemets doubles (`"`), PHP interprétera les séquences d'échappement suivantes pour les caractères spéciaux :

Caractères échappés
Séquence | Signification
--- | ---
`\n` | retour à la ligne (LF ou 0x0A (10) en ASCII)
`\r` | retour chariot (CR ou 0x0D (13) en ASCII)
`\t` | tabulation horizontale (HT ou 0x09 (9) en ASCII)
`\v` | tabulation verticale (VT ou 0x0B (11) en ASCII)
`\e` | échappement (ESC ou 0x1B (27) en ASCII)
`\f` | saut de page (FF ou 0x0C (12) en ASCII)
`\\` | antislash
`\$` | signe dollar
`\"` | guillemet double
`\[0-7]{1,3}` | Octal : la séquence de caractères correspondant à l'expression régulière `[0-7]{1,3}` est un caractère en notation octale (par exemple, `"\101" === "A"`), qui déborde silencieusement pour s'adapter à un octet (par exemple, `"\400" === "\000"`)
`\x[0-9A-Fa-f]{1,2}` | Hexadécimal : la séquence de caractères correspondant à l'expression régulière `[0-9A-Fa-f]{1,2}` est un caractère en notation hexadécimale (par exemple, `"\x41" === "A"`)
`\u{[0-9A-Fa-f]+}` | Unicode : la séquence de caractères correspondant à l'expression régulière `[0-9A-Fa-f]+` est un point de code Unicode, qui sera sorti dans la chaîne sous la représentation UTF-8 de ce point de code. Les accolades sont requises dans la séquence. Par exemple, `"\u{41}" === "A"`

Comme pour les chaînes entre guillemets simples, échapper tout autre caractère entraînera également l'impression de l'antislash.

La caractéristique la plus importante des chaînes entre guillemets doubles est le fait que les noms de variables seront étendus. Voir l'interpolation de chaînes pour plus de détails.

#### Heredoc

Une troisième manière de délimiter les chaînes est la syntaxe heredoc : `<<<`. Après cet opérateur, un identifiant est fourni, puis une nouvelle ligne. La chaîne elle-même suit, puis le même identifiant à nouveau pour fermer la citation.

L'identifiant de fermeture peut être indenté par des espaces ou des tabulations, auquel cas l'indentation sera supprimée de toutes les lignes dans la chaîne doc. Avant PHP 7.3.0, l'identifiant de fermeture doit commencer dans la première colonne de la ligne.

De plus, l'identifiant de fermeture doit suivre les mêmes règles de nommage que tout autre label en PHP : il doit contenir uniquement des caractères alphanumériques et des soulignés, et doit commencer par un caractère non numérique ou un souligné.

Exemple #2 Exemple de base de Heredoc à partir de PHP 7.3.0

    <?php
    // pas d'indentation
    echo <<<END
          a
         b
        c
    \n
    END;

    // 4 espaces d'indentation
    echo <<<END
          a
         b
        c
        END;

Résultat de l'exemple ci-dessus en PHP 7.3 :

          a
         b
        c

      a
     b
    c

Si l'identifiant de fermeture est indenté plus que n'importe quelle ligne du corps, alors une ParseError sera levée :

Exemple #3 L'identifiant de fermeture ne doit pas être indenté plus que n'importe quelle ligne du corps

    <?php
    echo <<<END
      a
     b
    c
       END;

Résultat de l'exemple ci-dessus en PHP 7.3 :

    Parse error: Invalid body indentation level (expecting an indentation level of at least 3) in example.php on line 4

Si l'identifiant de fermeture est indenté, des tabulations peuvent également être utilisées, cependant, les tabulations et les espaces ne doivent pas être mélangés concernant l'indentation de l'identifiant de fermeture et l'indentation du corps (jusqu'à l'identifiant de fermeture). Dans l'un de ces cas, une ParseError sera levée. Ces contraintes d'espace ont été incluses car le mélange d'espaces et de tabulations pour l'indentation nuit à la lisibilité.

Exemple #4 Indentation différente pour le corps (espaces) identifiant de fermeture

    <?php
    // Tout le code suivant ne fonctionne pas.

    // indentation différente pour le corps (espaces) marqueur de fin (tabulations)
    {
        echo <<<END
         a
            END;
    }

    // mélange d'espaces et de tabulations dans le corps
    {
        echo <<<END
            a
         END;
    }

    // mélange d'espaces et de tabulations dans le marqueur de fin
    {
        echo <<<END
              a
             END;
    }

Résultat de l'exemple ci-dessus en PHP 7.3 :

    Parse error: Invalid indentation - tabs and spaces cannot be mixed in example.php line 8

L'identifiant de fermeture pour la chaîne du corps n'est pas requis pour être suivi d'un point-virgule ou d'un saut de ligne. Par exemple, le code suivant est autorisé à partir de PHP 7.3.0 :

Exemple #5 Continuation d'une expression après un identifiant de fermeture

    <?php
    $values = [<<<END
    a
      b
        c
    END, 'd e f'];
    var_dump($values);

Résultat de l'exemple ci-dessus en PHP 7.3 :

    array(2) {
      [0] =>
      string(11) "a
      b
        c"
      [1] =>
      string(5) "d e f"
    }

Avertissement

Si l'identifiant de fermeture a été trouvé au début d'une ligne, alors peu importe s'il faisait partie d'un autre mot, il peut être considéré comme l'identifiant de fermeture et provoquer une ParseError.

Exemple #6 L'identifiant de fermeture dans le corps de la chaîne tend à provoquer une ParseError

    <?php
    $values = [<<<END
    a
    b
    END ING
    END, 'd e f'];

Résultat de l'exemple ci-dessus en PHP 7.3 :

    Parse error: syntax error, unexpected identifier "ING", expecting "]" in example.php on line 5

Pour éviter ce problème, il est sûr de suivre la règle simple : ne pas choisir un mot qui apparaît dans le corps du texte en tant qu'identifiant de fermeture.

Avertissement

Avant PHP 7.3.0, il est très important de noter que la ligne contenant l' identifiant de fermeture ne doit contenir aucun autre caractère, sauf un point-virgule (`;`). Cela signifie surtout que l'identifiant ne peut pas être indenté, et il ne doit pas y avoir d'espaces ou de tabulations avant ou après le point-virgule. Il est également important de réaliser que le premier caractère avant l'identifiant de fermeture doit être un saut de ligne tel que défini par le système d'exploitation local. C'est `\n` sur les systèmes UNIX, y compris macOS. Le délimiteur de fermeture doit également être suivi d'un saut de ligne.

Si cette règle est enfreinte et que l'identifiant de fermeture n'est pas "propre", il ne sera pas considéré comme un identifiant de fermeture, et PHP continuera à en chercher un. Si un identifiant de fermeture approprié n'est pas trouvé avant la fin du fichier courant, une erreur d'analyse se produira à la dernière ligne.

Exemple #7 Exemple invalide, avant PHP 7.3.0

    <?php
    class foo {
        public $bar = <<<EOT
    bar
        EOT;
    }
    // L'identifiant ne doit pas être indenté
    ?>

Exemple #8 Exemple valide, même avant PHP 7.3.0

    <?php
    class foo {
        public $bar = <<<EOT
    bar
    EOT;
    }
    ?>

Les heredocs contenant des variables ne peuvent pas être utilisés pour initialiser des propriétés de classe.

Le texte heredoc se comporte exactement comme une string entre guillemets doubles, sans les guillemets. Cela signifie que les guillemets dans un heredoc n'ont pas besoin d'être échappés, mais les codes d'échappement mentionnés ci-dessus peuvent toujours être utilisés. Les variables sont développées, mais il faut prendre le même soin lors de l'expression de variables complexes à l'intérieur d'un heredoc que pour les strings.

Exemple #9 Exemple de citation de chaîne heredoc

    <?php
    $str = <<<EOD
    Exemple de chaîne
    s'étendant sur plusieurs lignes
    utilisant la syntaxe heredoc.
    EOD;

    /* Exemple plus complexe, avec des variables. */
    class foo
    {
        var $foo;
        var $bar;

        function __construct()
        {
            $this->foo = 'Foo';
            $this->bar = array('Bar1', 'Bar2', 'Bar3');
        }
    }

    $foo = new foo();
    $name = 'MyName';

    echo <<<EOT
    Mon nom est "$name". Je suis en train d'imprimer $foo->foo.
    Maintenant, j'imprime {$foo->bar[1]}.
    Cela devrait imprimer un 'A' majuscule : \x41
    EOT;
    ?>

L'exemple ci-dessus va afficher :

    Mon nom est "MyName". Je suis en train d'imprimer Foo.
    Maintenant, j'imprime Bar2.
    Cela devrait imprimer un 'A' majuscule : A

Il est également possible d'utiliser la syntaxe heredoc pour passer des données aux arguments de fonction :

Exemple #10 Heredoc dans les exemples d'arguments

    <?php
    var_dump(array(<<<EOD
    foobar!
    EOD
    ));
    ?>

Il est possible d'initialiser des variables statiques et des propriétés/constantes de classe en utilisant la syntaxe heredoc :

Exemple #11 Utilisation d'Heredoc pour initialiser des valeurs statiques

    <?php
    // Variables statiques
    function foo()
    {
        static $bar = <<<LABEL
    Rien ici...
    LABEL;
    }

    // Propriétés/constantes de classe
    class foo
    {
        const BAR = <<<FOOBAR
    Exemple de constante
    FOOBAR;

        public $baz = <<<FOOBAR
    Exemple de propriété
    FOOBAR;
    }
    ?>

L'identifiant d'ouverture du Heredoc peut éventuellement être encadré de guillemets doubles :

Exemple #12 Utilisation de guillemets doubles dans le Heredoc

    <?php
    echo <<<"FOOBAR"
    Bonjour le monde !
    FOOBAR;
    ?>

#### Nowdoc

Les nowdocs sont aux chaînes entre guillemets simples ce que les heredocs sont aux chaînes entre guillemets doubles. Un nowdoc est spécifié de manière similaire à un heredoc, mais aucune interpolation de chaîne n'est effectuée à l'intérieur d'un nowdoc. La construction est idéale pour intégrer du code PHP ou d'autres blocs de texte volumineux sans avoir besoin d'échapper. Il partage certaines caractéristiques avec la construction SGML `<![CDATA[ ]]>`, en ce sens qu'elle déclare un bloc de texte qui n'est pas destiné à être analysé.

Un nowdoc est identifié par la même séquence `<<<` utilisée pour les heredocs, mais l'identifiant qui suit est encadré de guillemets simples, par exemple `<<<'EOT'`. Toutes les règles pour les identifiants heredoc s'appliquent également aux identifiants nowdoc, en particulier celles concernant l'apparence de l'identifiant de fermeture.

Exemple #13 Exemple de citation de chaîne nowdoc

    <?php
    echo <<<'EOD'
    Exemple de chaîne s'étendant sur plusieurs lignes
    utilisant la syntaxe nowdoc. Les barres obliques inverses sont toujours traitées littéralement,
    c'est-à-dire \\ et \'.
    EOD;

L'exemple ci-dessus va afficher :

    Exemple de chaîne s'étendant sur plusieurs lignes
    utilisant la syntaxe nowdoc. Les barres obliques inverses sont toujours traitées littéralement,
    c'est-à-dire \\ et \'.

Exemple #14 Exemple de citation de chaîne nowdoc avec des variables

    <?php
    class foo
    {
        public $foo;
        public $bar;

        function __construct()
        {
            $this->foo = 'Foo';
            $this->bar = array('Bar1', 'Bar2', 'Bar3');
        }
    }

    $foo = new foo();
    $name = 'MyName';

    echo <<<'EOT'
    Mon nom est "$name". Je suis en train d'imprimer $foo->foo.
    Maintenant, j'imprime {$foo->bar[1]}.
    Cela ne devrait pas imprimer un 'A' majuscule : \x41
    EOT;
    ?>

L'exemple ci-dessus va afficher :

    Mon nom est "$name". Je suis en train d'imprimer $foo->foo.
    Maintenant, j'imprime {$foo->bar[1]}.
    Cela ne devrait pas imprimer un 'A' majuscule : \x41

Exemple #15 Exemple de données statiques

    <?php
    class foo {
        public $bar = <<<'EOT'
    bar
    EOT;
    }
    ?>

#### Interpolation de chaînes

Lorsqu'une chaîne est spécifiée entre guillemets doubles ou avec heredoc, des variables peuvent être substituées à l'intérieur.

Il existe deux types de syntaxe : une de base et une avancée. La syntaxe de base est la plus courante et la plus pratique. Elle offre un moyen d'incorporer une variable, une valeur tableau ou une propriété objet dans une chaîne avec un minimum d'effort.

##### Syntaxe de base

Si un signe dollar (`$`) est rencontré, les caractères qui le suivent et qui peuvent être utilisés dans un nom de variable seront interprétés comme tels et substitués.

Exemple #16 Interpolation de chaînes

    <?php
    $juice = "pomme";

    echo "Il a bu un peu de $juice jus." . PHP_EOL;

    ?>

L'exemple ci-dessus va afficher :

    Il a bu un peu de pomme jus.

Formellement, la structure pour la syntaxe de substitution de variable de base est la suivante :

    string-variable::
         variable-name   (offset-or-property)?
       | ${   expression   }

    offset-or-property::
         offset-in-string
       | property-in-string

    offset-in-string::
         [   name   ]
       | [   variable-name   ]
       | [   integer-literal   ]

    property-in-string::
         ->  name

    variable-name::
         $   name

    name::
         [a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*

Avertissement

La syntaxe `${ expression }` est dépréciée depuis PHP 8.2.0, car elle peut être interprétée comme des variables de variables :

    <?php
    const foo = 'bar';
    $foo = 'foo';
    $bar = 'bar';
    var_dump("${foo}");
    var_dump("${(foo)}");
    ?>

Résultat de l'exemple ci-dessus en PHP 8.2 :

    Deprecated: Using ${var} in strings is deprecated, use {$var} instead in file on line 6

    Deprecated: Using ${expr} (variable variables) in strings is deprecated, use {${expr}} instead in file on line 9
    string(3) "foo"
    string(3) "bar"

L'exemple ci-dessus va afficher :

    string(3) "foo"
    string(3) "bar"

La syntaxe d'interpolation de chaîne avancée devrait être utilisée à la place.

> Note: S'il n'est pas possible de former un nom valide, le signe dollar reste tel quel dans la chaîne :

>     <?php
>     echo "Aucune interpolation $  n'a eu lieu\n";
>     echo "Aucune interpolation $\n n'a eu lieu\n";
>     echo "Aucune interpolation $2 n'a eu lieu\n";
>     ?>

> L'exemple ci-dessus va afficher :

>     Aucune interpolation $  n'a eu lieu
>     Aucune interpolation $
>      n'a eu lieu
>     Aucune interpolation $2 n'a eu lieu

Exemple #17 Interpolation de la valeur de la première dimension d'un tableau ou d'une propriété

    <?php
    $juices = array("pomme", "orange", "string_key" => "violet");

    echo "Il a bu un peu de $juices[0] jus.";
    echo PHP_EOL;
    echo "Il a bu un peu de $juices[1] jus.";
    echo PHP_EOL;
    echo "Il a bu un peu de $juices[string_key] jus.";
    echo PHP_EOL;

    class A {
        public $s = "chaîne";
    }

    $o = new A();

    echo "Valeur de l'objet : $o->s.";
    ?>

L'exemple ci-dessus va afficher :

    Il a bu un peu de pomme jus.
    Il a bu un peu de orange jus.
    Il a bu un peu de violet jus.
    Valeur de l'objet : chaîne.

> Note: La clé du tableau doit être non citée, et il n'est donc pas possible de référencer une constante comme clé avec la syntaxe de base. Utiliser la syntaxe avancée à la place.

À partir de PHP 7.1.0, les indices numériques négatifs sont également supportés.

Exemple #18 Indices numériques négatifs

    <?php
    $string = 'chaîne';
    echo "Le caractère à l'indice -2 est $string[-2].", PHP_EOL;
    $string[-3] = 'o';
    echo "Changer le caractère à l'indice -3 en o donne $string.", PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    Le caractère à l'indice -2 est n.
    Changer le caractère à l'indice -3 en o donne strong.

Pour tout ce qui est plus complexe, la syntaxe avancée doit être utilisée.

##### Syntaxe avancée (syntaxe des accolades)

La syntaxe avancée permet l'interpolation de variables avec des accesseurs arbitraires.

Toute variable scalaire, élément de tableau ou propriété d'objet (static ou non) avec une représentation chaîne peut être incluse via cette syntaxe. L'expression est écrite de la même manière que celle qui apparaîtrait en dehors de la chaîne, puis entourée de `{` et `}`. Étant donné que `{` ne peut pas être échappé, cette syntaxe ne sera reconnue que lorsque le `$` suit immédiatement le `{`. Utiliser `{\$` pour obtenir un `{$`. Voici quelques exemples pour clarifier :

Exemple #19 Syntaxe avec des accolades

    <?php
    const DATA_KEY = 'const-key';
    $great = 'fantastique';
    $arr = [
        '1',
        '2',
        '3',
        [41, 42, 43],
        'key' => 'Valeur indexée',
        'const-key' => 'Clé avec un signe moins',
        'foo' => ['foo1', 'foo2', 'foo3']
    ];

    // Ne fonctionnera pas, affiche : This is { fantastic}
    echo "Ceci est { $great}" . PHP_EOL;

    // Fonctionne, affiche : This is fantastic
    echo "Ceci est {$great}" . PHP_EOL;

    // Pour afficher des accolades dans la sortie :
    echo "Ceci est {{$great}}" . PHP_EOL;

    class Square {
        public $width;

        public function __construct(int $width) { $this->width = $width; }
    }

    $square = new Square(5);

    // Fonctionne
    echo "Ce carré mesure {$square->width}00 centimètres de large." . PHP_EOL;

    // Fonctionne, les clés entre guillemets ne fonctionnent qu'avec la syntaxe des accolades
    echo "Cela fonctionne : {$arr['key']}" . PHP_EOL;

    // Fonctionne
    echo "Cela fonctionne : {$arr[3][2]}" . PHP_EOL;

    echo "Cela fonctionne : {$arr[DATA_KEY]}" . PHP_EOL;

    // Lors de l'utilisation de tableaux multidimensionnels, utilisez toujours des accolades autour des tableaux
    // lorsqu'ils sont à l'intérieur de chaînes
    echo "Cela fonctionne : {$arr['foo'][2]}" . PHP_EOL;

    echo "Cela fonctionne : {$obj->values[3]->name}" . PHP_EOL;

    echo "Cela fonctionne : {$obj->$staticProp}" . PHP_EOL;

    // Ne fonctionnera pas, affiche : C:\directory\{fantastic}.txt
    echo "C:\directory\{$great}.txt" . PHP_EOL;

    // Fonctionne, affiche : C:\directory\fantastic.txt
    echo "C:\\directory\\{$great}.txt" . PHP_EOL;
    ?>

> Note: Comme cette syntaxe permet des expressions arbitraires, il est possible d'utiliser des variables variables dans la syntaxe avancée.

#### Accès et modification de chaîne par caractère

Les caractères dans les chaînes peuvent être accédés et modifiés en spécifiant l'offset basé sur zéro du caractère souhaité après la chaîne à l'aide de crochets array, comme dans $str[42]. Pensez à une chaîne comme à un tableau de caractères à cette fin. Les fonctions substr() et substr_replace() peuvent être utilisées pour extraire ou remplacer plus d'un caractère.

> Note: À partir de PHP 7.1.0, les offsets de chaîne négatifs sont également supportés. Ceux-ci spécifient l'offset à partir de la fin de la chaîne. Auparavant, les offsets négatifs émettaient `E_NOTICE` pour la lecture (produisant une chaîne vide) et `E_WARNING` pour l'écriture (laissant la chaîne intacte).

> Note: Avant PHP 8.0.0, les chaînes pouvaient également être accédées en utilisant des accolades, comme dans $str{42}, pour le même objectif. Cette syntaxe des accolades a été dépréciée à partir de PHP 7.4.0 et n'est plus supportée à partir de PHP 8.0.0.

Avertissement

Écrire à un offset hors de portée remplit la chaîne d'espaces. Les types non entiers sont convertis en entier. Un type d'offset illégal émet `E_WARNING`. Seul le premier caractère d'une chaîne assignée est utilisé. À partir de PHP 7.1.0, assigner une chaîne vide génère une erreur fatale. Auparavant, cela assignait un octet NULL.

Avertissement

En interne, les chaînes PHP sont des tableaux d'octets. En conséquence, accéder ou modifier une chaîne à l'aide de crochets de tableau n'est pas sûr pour les multi-octets, et ne devrait être fait qu'avec des chaînes en encodage à un seul octet tel que ISO-8859-1.

> Note: À partir de PHP 7.1.0, appliquer l'opérateur d'index vide sur une chaîne vide génère une erreur fatale. Auparavant, la chaîne vide était silencieusement convertie en tableau.

Exemple #20 Quelques exemples de chaînes

    <?php
    // Obtenez le premier caractère d'une chaîne
    $str = 'Ceci est un test.';
    $first = $str[0];
    var_dump($first);

    // Obtenez le troisième caractère d'une chaîne
    $third = $str[2];
    var_dump($third);

    // Obtenez le dernier caractère d'une chaîne.
    $str = 'Ceci est toujours un test.';
    $last = $str[strlen($str)-1];
    var_dump($last);

    // Modifiez le dernier caractère d'une chaîne
    $str = 'Regardez la mer';
    $str[strlen($str)-1] = 'e';
    var_dump($str);
    ?>

Les offsets de chaîne doivent être des entiers ou des chaînes ressemblant à des entiers, sinon un avertissement sera émis.

Exemple #21 Exemple d'offsets de chaîne illégaux

    <?php
    $str = 'abc';

    $keys = [ '1', '1.0', 'x', '1x' ];

    foreach ($keys as $keyToTry) {
        var_dump(isset($str[$keyToTry]));

        try {
            var_dump($str[$keyToTry]);
        } catch (TypeError $e) {
            echo $e->getMessage(), PHP_EOL;
        }

        echo PHP_EOL;
    }
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    string(1) "b"

    bool(false)
    Cannot access offset of type string on string

    bool(false)
    Cannot access offset of type string on string

    bool(false)

    Warning: Illegal string offset "1x" in Standard input code on line 10
    string(1) "b"

> Note:

> Accéder à des variables d'autres types (à l'exception des tableaux ou objets implémentant les interfaces appropriées) en utilisant `[]` ou `{}` renvoie silencieusement `null`.

> Note:

> Les caractères dans les littéraux de chaîne peuvent être accédés en utilisant `[]` ou `{}`.

> Note:

> Accéder à des caractères dans des littéraux de chaîne en utilisant la syntaxe `{}` a été déprécié dans PHP 7.4. Cela a été supprimé dans PHP 8.0.

### Fonctions et opérateurs utiles

Les chaînes peuvent être concaténées à l'aide de l'opérateur '.' (point). Il est à noter que l'opérateur '+' (addition) ne fonctionnera pas pour cela. Consulter les opérateurs de chaîne pour plus d'informations.

Il existe plusieurs fonctions utiles pour la manipulation des chaînes.

Consulter la section des fonctions de chaîne pour les fonctions générales, et la section des fonctions d'expressions régulières compatibles Perl pour des fonctionnalités avancées de recherche et de remplacement.

Il existe également des fonctions pour les chaînes d'URL, et des fonctions pour chiffrer/déchiffrer des chaînes (Sodium et Hash).

Enfin, consulter également les fonctions de type caractère.

### Conversion en chaîne

Une valeur peut être convertie en chaîne à l'aide du cast `(string)` ou de la fonction strval(). La conversion en chaîne est effectuée automatiquement dans le contexte d'une expression où une chaîne est nécessaire. Cela se produit lors de l'utilisation des fonctions echo ou print, ou lorsque une variable est comparée à une chaîne. Les sections sur Types et Type Juggling clarifieront ce qui suit. Voir également la fonction settype().

Une valeur bool `true` est convertie en la chaîne `"1"`. La bool `false` est convertie en `""` (la chaîne vide). Cela permet une conversion aller-retour entre les valeurs bool et chaîne.

Un int ou float est converti en une chaîne représentant le nombre textuellement (y compris la partie exponentielle pour les float). Les nombres à virgule flottante peuvent être convertis à l'aide de la notation exponentielle (`4.1E+6`).

> Note:

> À partir de PHP 8.0.0, le caractère de la virgule décimale est toujours un point ("`.`"). Avant PHP 8.0.0, le caractère de la virgule décimale est défini dans la locale du script (catégorie LC_NUMERIC). Consulter la fonction setlocale().

Les tableaux sont toujours convertis en la chaîne `"Array"`; de ce fait, echo et print ne peuvent pas à eux seuls afficher le contenu d'un tableau. Pour afficher un seul élément, utiliser une construction telle que `echo $arr['foo']`. Consulter ci-dessous les conseils sur la visualisation de tout le contenu.

Afin de convertir des objets en chaînes, la méthode magique __toString doit être utilisée.

Les ressources sont toujours converties en chaînes avec la structure `"Resource id #1"`, où `1` est le numéro de ressource attribué au resource par PHP à l'exécution. Bien que la structure exacte de cette chaîne ne doive pas être considérée comme fiable et soit sujette à changement, elle sera toujours unique pour une ressource donnée pendant la durée d'exécution d'un script (c'est-à-dire une requête Web ou un processus CLI) et ne sera pas réutilisée. Pour obtenir le type d'une resource, utiliser la fonction get_resource_type().

`null` est toujours converti en une chaîne vide.

Comme indiqué ci-dessus, convertir directement un tableau, un objet ou une resource en chaîne ne fournit pas d'informations utiles sur la valeur au-delà de son type. Consulter les fonctions print_r() et var_dump() pour des moyens plus efficaces d'inspecter le contenu de ces types.

La plupart des valeurs PHP peuvent également être converties en chaînes pour un stockage permanent. Cette méthode est appelée sérialisation et est effectuée par la fonction serialize().

### Détails du type chaîne

La chaîne en PHP est implémentée comme un tableau d'octets et un entier indiquant la longueur du tampon. Elle n'a aucune information sur la façon dont ces octets se traduisent en caractères, laissant cette tâche au programmeur. Il n'y a pas de limitations sur les valeurs que la chaîne peut être composée ; en particulier, les octets de valeur `0` (« octets NUL ») sont autorisés partout dans la chaîne (cependant, quelques fonctions, dites dans ce manuel de ne pas être « sûres pour les binaires », peuvent transmettre les chaînes à des bibliothèques qui ignorent les données après un octet NUL.)

Cette nature du type chaîne explique pourquoi il n'y a pas de type « octet » distinct en PHP – les chaînes prennent ce rôle. Les fonctions qui ne renvoient pas de données textuelles – par exemple, des données arbitraires lues à partir d'une socket réseau – renverront tout de même des chaînes.

Étant donné que PHP ne dicte pas un encodage spécifique pour les chaînes, on pourrait se demander comment les littéraux de chaînes sont encodés. Par exemple, la chaîne `"á"` est-elle équivalente à `"\xE1"` (ISO-8859-1), `"\xC3\xA1"` (UTF-8, forme C), `"\x61\xCC\x81"` (UTF-8, forme D) ou toute autre représentation possible ? La réponse est que la chaîne sera encodée de la manière dont elle est encodée dans le fichier script. Ainsi, si le script est écrit en ISO-8859-1, la chaîne sera encodée en ISO-8859-1 et vice versa. Cependant, cela ne s'applique pas si Zend Multibyte est activé ; dans ce cas, le script peut être écrit dans un encodage arbitraire (qui est explicitement déclaré ou détecté) et ensuite converti dans un certain encodage interne, qui sera ensuite l'encodage utilisé pour les littéraux de chaînes. Il est à noter qu'il y a certaines contraintes sur l'encodage du script (ou sur l'encodage interne, si Zend Multibyte est activé) – cela signifie presque toujours que cet encodage doit être un superset compatible de l'ASCII, tel que UTF-8 ou ISO-8859-1. Il est cependant à noter que les encodages dépendants de l'état où les mêmes valeurs d'octets peuvent être utilisées dans des états de décalage initiaux et non initiaux peuvent poser problème.

Bien sûr, afin d'être utiles, les fonctions qui opèrent sur du texte peuvent devoir faire certaines hypothèses sur la façon dont la chaîne est encodée. Malheureusement, il y a beaucoup de variations à ce sujet dans les fonctions de PHP :

- Certaines fonctions supposent que la chaîne est encodée dans un (tout) encodage à un octet, mais elles n'ont pas besoin d'interpréter ces octets comme des caractères spécifiques. C'est le cas, par exemple, de substr(), strpos(), strlen() ou strcmp(). Une autre façon de penser à ces fonctions est qu'elles opèrent sur des tampons mémoire, c'est-à-dire qu'elles fonctionnent avec des octets et des décalages d'octets.
- D'autres fonctions reçoivent l'encodage de la chaîne, supposant éventuellement un défaut si aucune information de ce type n'est donnée. C'est le cas de htmlentities() et de la majorité des fonctions dans l'extension mbstring.
- D'autres utilisent la locale actuelle (voir setlocale()), mais fonctionnent octet par octet.
- Enfin, elles peuvent simplement supposer que la chaîne utilise un encodage spécifique, généralement UTF-8. C'est le cas de la plupart des fonctions dans l'extension intl et dans l'extension PCRE (dans ce dernier cas, seulement lorsque le modificateur `u` est utilisé).

En fin de compte, cela signifie que l'écriture de programmes corrects utilisant Unicode dépend d'éviter soigneusement les fonctions qui ne fonctionneront pas et qui corrompront très probablement les données, et d'utiliser à la place les fonctions qui se comportent correctement, généralement provenant des extensions intl et mbstring. Cependant, utiliser des fonctions capables de gérer les encodages Unicode n'est que le début. Peu importe les fonctions que le langage fournit, il est essentiel de connaître la spécification Unicode. Par exemple, un programme qui suppose qu'il n'y a que des majuscules et des minuscules fait une hypothèse erronée.

## Chaînes numériques

Une chaîne de caractères PHP string est considérée comme numérique si elle peut être interprétée comme un int ou un float.

Formellement à partir de PHP 8.0.0 :

    WHITESPACES      \s*
    LNUM             [0-9]+
    DNUM             ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
    EXPONENT_DNUM    (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
    INT_NUM_STRING   {WHITESPACES} [+-]? {LNUM} {WHITESPACES}
    FLOAT_NUM_STRING {WHITESPACES} [+-]? ({DNUM} | {EXPONENT_DNUM}) {WHITESPACES}
    NUM_STRING       ({INT_NUM_STRING} | {FLOAT_NUM_STRING})

PHP dispose également d'un concept de chaînes débutant numériquement. Il s'agit simplement d'une chaîne qui commence comme une chaîne numérique suivie de n'importe quel caractère.

> Note:

> Toute chaîne contenant la lettre `E` (insensible à la casse) délimitée par des nombres sera considérée comme un nombre exprimé en notation scientifique. Cela peut produire des résultats inattendus.

> Exemple #1 Comparaisons avec notation scientifique

>     <?php
>     var_dump("0D1" == "000"); // false, "0D1" n'est pas en notation scientifique
>     var_dump("0E1" == "000"); // true, "0E1" est 0 * (10 ^ 1), soit 0
>     var_dump("2E1" == "020"); // true, "2E1" est 2 * (10 ^ 1), soit 20
>     ?>

### Chaînes de caractères utilisées dans des contextes numériques

Lorsqu'une string doit être évaluée comme un nombre (par exemple, opérations arithmétiques, déclaration de type int, etc.), les étapes suivantes sont suivies pour déterminer le résultat :

1. Si la string est numérique, elle est résolue en int si la string est une chaîne numérique entière et entre dans les limites du type int (telles que définies par `PHP_INT_MAX`), sinon elle est résolue en un float.
2. Si le contexte autorise les chaînes débutant numériquement et que la string en est une, elle est résolue en int si la partie initiale de la chaîne string est une chaîne numérique entière et entre dans les limites du type int (telles que définies par `PHP_INT_MAX`), sinon elle est résolue en un float. De plus, une erreur de niveau `E_WARNING` est soulevée.
3. Si la string n'est pas numérique, une TypeError est lancée.

### Comportement antérieur à PHP 8.0.0

Avant PHP 8.0.0, une string était considérée comme numérique seulement si elle avait des espaces blancs en début de chaîne, si elle avait des espaces blancs en fin de chaîne, la chaîne était considérée comme une chaîne débutant numériquement.

Avant PHP 8.0.0, lorsqu'une chaîne de caractères était utilisée dans un contexte numérique, elle effectuait les mêmes étapes que ci-dessus, avec les différences suivantes :

- L'utilisation d'une chaîne de caractères débutant numériquement générait une erreur de type `E_NOTICE` au lieu de `E_WARNING`.
- Si la chaîne de caractères n'était pas numérique, une `E_WARNING` était levée et la valeur `0` était retournée.

Avant PHP 7.1.0, ni `E_NOTICE` ni `E_WARNING` n'étaient levées.

    <?php
    $foo = 1 + "10.5";                // $foo est un float (11.5)
    $foo = 1 + "-1.3e3";              // $foo est un float (-1299)
    $foo = 1 + "bob-1.3e3";           // TypeError à partir de PHP 8.0.0, $foo est un integer (1) auparavant
    $foo = 1 + "bob3";                // TypeError à partir de PHP 8.0.0, $foo est un integer (1) auparavant
    $foo = 1 + "10 Small Pigs";       // $foo est un integer (11) et une E_WARNING est levée à partir de PHP 8.0.0, E_NOTICE auparavant
    $foo = 4 + "10.2 Little Piggies"; // $foo est un float (14.2) et une E_WARNING est levée à partir de PHP 8.0.0, E_NOTICE auparavant
    $foo = "10.0 pigs " + 1;          // $foo est un float (11) et une E_WARNING est levée à partir de PHP 8.0.0, E_NOTICE auparavant
    $foo = "10.0 pigs " + 1.0;        // $foo est un float (11) et une E_WARNING est levée à partir de PHP 8.0.0, E_NOTICE auparavant
    ?>

## Les tableaux

Pour une liste de toutes les fonctions de tableau, voir le chapitre fonctions de tableau dans la documentation.

Un tableau en PHP est en fait une carte ordonnée. Une carte est un type qui associe des valeurs à des clés. Ce type est optimisé pour différentes utilisations ; il peut être considéré comme un tableau, une liste, une table de hachage, un dictionnaire, une collection, une pile, une file d'attente et probablement plus. On peut avoir, comme valeur d'un tableau, d'autres tableaux, multidimensionnels ou non.

La structure de ces données dépasse l'objet de ce manuel, mais au moins un exemple est fourni pour chacun des cas évoqués. Pour plus d'informations, se reporter aux différentes explications sur le sujet que l'on trouve sur le web.

### Syntaxe

#### Syntaxe d'un tableau

Un tableau peut être créé en utilisant la structure de langage array(). Il prend un nombre illimité de paramètres, chacun séparé par une virgule, sous la forme d'une paire `key => value`.

    array(
        key  => value,
        key2 => value2,
        key3 => value3,
        ...
    )

La virgule après le dernier élément d'un tableau est optionnelle et peut ne pas être ajoutée. C'est généralement ce qui est fait pour les tableaux sur une seule ligne, c.-à-d. `array(1, 2)` est préféré à `array(1, 2, )`. Pour les tableaux sur plusieurs lignes, la virgule finale est généralement utilisée, car elle permet d'ajouter plus facilement de nouveaux éléments à la fin.

> Note:

> Une syntaxe de tableau courte existe qui remplace `array()` par `[]`.

Exemple #1 Un tableau simple

    <?php
    $array1 = array(
        "foo" => "bar",
        "bar" => "foo",
    );

    // Utilisant la syntaxe de tableau courte
    $array2 = [
        "foo" => "bar",
        "bar" => "foo",
    ];

    var_dump($array1, $array2);
    ?>

La clé key peut être soit un int, soit une chaîne de caractères. La valeur value peut être de n'importe quel type.

De plus, les modifications de type suivantes surviendront pour la clé key :

- Les chaînes de caractères contenant un entier décimal valide, sauf si le nombre est précédé d'un signe `+` seront modifiées en un type entier. C.-à-d. la clé `"8"` sera effectivement stockée sous l'entier `8`. D'un autre côté, `"08"` ne sera pas modifié, sachant que ce n'est pas un entier décimal valide.
- Les nombres à virgule flottante seront aussi modifiés en entier, ce qui signifie que la partie après la virgule sera tronquée. C.-à-d. la clé `8.7` sera stockée sous l'entier `8`.
- Les booléens seront modifiés en entier également, c.-à-d. la clé `true` sera stockée sous l'entier `1` et la clé `false` sous l'entier `0`.
- La valeur Null sera modifiée en une chaîne vide, c.-à-d. la clé `null` sera stockée sous la chaîne de caractères `""`.
- Les tableaux et les objets ne peuvent pas être utilisés comme clé. Toute tentative en ce sens émettra l'alerte suivante : `Illegal offset type`.

Si plusieurs éléments dans la déclaration d'un tableau utilisent la même clé, seule la dernière sera utilisée, écrasant ainsi toutes les précédentes.

Exemple #2 Exemple sur la modification de type et l'écrasement

    <?php
    $array = array(
        1    => "a",
        "1"  => "b",
        1.5  => "c",
        true => "d",
    );
    var_dump($array);
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      [1]=>
      string(1) "d"
    }

Vu que toutes les clés de l'exemple ci-dessus sont modifiées en l'entier `1`, la valeur sera écrasée sur chaque nouvel élément, et seul le dernier dont la valeur assignée est `"d"` sera conservé.

Les tableaux PHP peuvent contenir des clés de type int et string en même temps, vu que PHP ne distingue pas les tableaux indexés et les tableaux associatifs.

Exemple #3 Exemple avec des clés de type int et string

    <?php
    $array = array(
        "foo" => "bar",
        "bar" => "foo",
        100   => -100,
        -100  => 100,
    );
    var_dump($array);
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      ["foo"]=>
      string(3) "bar"
      ["bar"]=>
      string(3) "foo"
      [100]=>
      int(-100)
      [-100]=>
      int(100)
    }

La clé key est optionnelle. Si elle n'est pas spécifiée, PHP utilisera un incrément de la plus grande clé entière utilisée auparavant.

Exemple #4 Tableaux indexés sans clé

    <?php
    $array = array("foo", "bar", "hello", "world");
    var_dump($array);
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      string(3) "foo"
      [1]=>
      string(3) "bar"
      [2]=>
      string(5) "hello"
      [3]=>
      string(5) "world"
    }

Il est possible de spécifier la clé seulement pour quelques éléments et ne pas la fournir pour d'autres :

Exemple #5 Exemple avec des clés seulement pour quelques éléments

    <?php
    $array = array(
             "a",
             "b",
        6 => "c",
             "d",
    );
    var_dump($array);
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      string(1) "a"
      [1]=>
      string(1) "b"
      [6]=>
      string(1) "c"
      [7]=>
      string(1) "d"
    }

Comme on peut le voir, la dernière valeur `"d"` a été assignée à la clé `7`. Ceci est dû au fait que la dernière clé entière la plus grande utilisée auparavant était `6`.

Exemple #6 Exemple complexe sur la modification de type et l'écrasement

Cet exemple inclut toutes les variations de modification de type de clés et écrasements des éléments.

    <?php
    $array = array(
        1    => 'a',
        '1'  => 'b', // la valeur "a" sera écrasée par "b"
        1.5  => 'c', // la valeur "b" sera écrasée par "c"
        -1 => 'd',
        '01'  => 'e', // comme ceci n'est pas un entier sous forme de chaîne, cela n'écrasera PAS la clé pour 1
        '1.5' => 'f', // comme ceci n'est pas un entier sous forme de chaîne, cela n'écrasera pas la clé pour 1
        true => 'g', // la valeur "c" sera écrasée par "g"
        false => 'h',
        '' => 'i',
        null => 'j', // la valeur "i" sera écrasée par "j"
        'k', // la valeur "k" est assignée à la clé 2. Ceci est dû au fait que la dernière clé entière la plus grande utilisée auparavant était 1
        2 => 'l', // la valeur "k" sera écrasée par "l"
    );
    var_dump($array);
    ?>

L'exemple ci-dessus va afficher :

    array(7) {
      [1]=>
      string(1) "g"
      [-1]=>
      string(1) "d"
      ["01"]=>
      string(1) "e"
      ["1.5"]=>
      string(1) "f"
      [0]=>
      string(1) "h"
      [""]=>
      string(1) "j"
      [2]=>
      string(1) "l"
    }

Exemple #7 Exemple d'index négatif

Lorsqu'une clé entière négative `n` est assignée, PHP prendra soin d'assigner la clé suivante à `n+1`.

    <?php
    $array = [];

    $array[-5] = 1;
    $array[] = 2;

    var_dump($array);
    ?>

L'exemple ci-dessus va afficher :

    array(2) {
      [-5]=>
      int(1)
      [-4]=>
      int(2)
    }

Avertissement

Avant PHP 8.3.0, l'assignation d'une clé entière négative `n` assignait la clé suivante à `0`. L'exemple précédent aurait donc produit :

    array(2) {
      [-5]=>
      int(1)
      [0]=>
      int(2)
    }

#### Accès aux éléments d'un tableau en utilisant la syntaxe à base de crochets

Les éléments d'un tableau peuvent être accédés en utilisant la syntaxe `array[key]`.

Exemple #8 Accès aux éléments d'un tableau

    <?php
    $array = array(
        "foo" => "bar",
        42    => 24,
        "multi" => array(
             "dimensional" => array(
                 "array" => "foo"
             )
        )
    );

    var_dump($array["foo"]);
    var_dump($array[42]);
    var_dump($array["multi"]["dimensional"]["array"]);
    ?>

L'exemple ci-dessus va afficher :

    string(3) "bar"
    int(24)
    string(3) "foo"

> Note:

> Avant PHP 8.0.0, les crochets et accolades pouvaient être utilisés de façon interchangeable pour accéder aux éléments d'un tableau (e.g. `$array[42]` et `$array{42}` feraient tous deux la même chose dans l'exemple ci-dessus). La syntaxe avec les accolades a été rendue obsolète en PHP 7.4.0 et n'est plus supportée à partir de PHP 8.0.0.

Exemple #9 Faire référence à un tableau à la sortie d'une fonction ou d'une méthode

    <?php
    function getArray() {
        return array(1, 2, 3);
    }

    $secondElement = getArray()[1];

    var_dump($secondElement);
    ?>

> Note:

> Une tentative d'accès à une clé d'un tableau qui n'a pas été définie revient à tenter d'accéder à une variable non définie : une alerte de niveau `E_WARNING` sera émise (E_NOTICE avant PHP 8.0.0), et le résultat vaudra `null`.

> Note:

> Faire référence à un tableau à la sortie d'une fonction ou d'une méthode d'une valeur scalaire qui n'est pas une chaîne de caractères génère `null`. Avant PHP 7.4.0, ceci ne générait pas de message d'erreur. À partir de PHP 7.4.0, ceci émet une `E_NOTICE` ; À partir de PHP 8.0.0, ceci émet une `E_WARNING`.

#### Création/modification avec des crochets

Un tableau existant peut être modifié en y assignant explicitement des valeurs.

L'assignation d'une valeur dans un tableau est effectuée en spécifiant la clé, entre crochets. La clé peut également ne pas être renseignée, sous la forme : `[]`.

    $arr[clé] = valeur;
    $arr[] = valeur;
    // clé peut être un entier ou une chaîne de caractères
    // valeur peut être n'importe quel type

Si lors de l'assignation $arr n'existe pas ou est défini à `null` ou `false`, il sera créé ; c'est ainsi une façon détournée de créer un tableau. Cette pratique est cependant découragée car si $arr contient déjà quelques valeurs (c.-à-d. string depuis la variable demandée) alors cette valeur restera en place et `[]` peut attendre un opérateur d'accès sur une chaîne. C'est toujours un meilleur choix que d'initialiser une variable par affectation directe.

> Note: À partir de PHP 7.1.0, l'application de l'opérateur d'index vide sur une chaîne lève une erreur fatale. Auparavant, la chaîne aurait été convertie silencieusement en tableau.

> Note: À partir de PHP 8.1.0, créer un nouveau tableau à partir de `false` est obsolète. Créer un nouveau tableau depuis `null` et les valeurs indéfinies est toujours autorisé.

Pour modifier une valeur en particulier, il convient d'assigner une valeur en spécifiant sa clé. Pour effacer une paire clé/valeur, il convient d'appeler la fonction unset() sur la clé désirée.

Exemple #10 Utilisation des crochets avec les tableaux

    <?php
    $arr = array(5 => 1, 12 => 2);

    $arr[] = 56;    // Identique à $arr[13] = 56;
                    // à cet endroit du script

    $arr["x"] = 42; // Ceci ajoute un nouvel élément au
                    // tableau avec la clé "x"

    unset($arr[5]); // Ceci efface l'élément du tableau

    var_dump($arr);

    unset($arr);    // Ceci efface complètement le tableau

    var_dump($arr);
    ?>

> Note: Si aucune clé n'est spécifiée, la clé sera l'indice entier maximal existant + `1`. Si le tableau ne possède aucun indice entier positif, la clé sera `0`. À partir de PHP 8.3.0, elle peut aussi être un entier négatif.

> Il est à noter que la clé entière maximale pour cette opération n'a pas besoin d'exister dans le tableau au moment de la manipulation. Elle doit seulement avoir existé dans le tableau à un moment ou un autre depuis la dernière fois où le tableau a été ré-indexé. Voici un exemple qui illustre ce principe :

>     <?php
>     // Création d'un tableau simple.
>     $array = array(1, 2, 3, 4, 5);
>     print_r($array);

>     // Maintenant, on efface tous les éléments, mais on conserve le tableau :
>     foreach ($array as $i => $value) {
>         unset($array[$i]);
>     }
>     print_r($array);

>     // Ajout d'un élément (notez que la nouvelle clé est 5, et non 0).
>     $array[] = 6;
>     print_r($array);

>     // Ré-indexation :
>     $array = array_values($array);
>     $array[] = 7;
>     print_r($array);
>     ?>

> L'exemple ci-dessus va afficher :

>     Array
>     (
>         [0] => 1
>         [1] => 2
>         [2] => 3
>         [3] => 4
>         [4] => 5
>     )
>     Array
>     (
>     )
>     Array
>     (
>         [5] => 6
>     )
>     Array
>     (
>         [0] => 6
>         [1] => 7
>     )

#### Déstructuration de tableau

Les tableaux peuvent être déstructurés en utilisant `[]` (à partir de PHP 7.1.0) ou list(). Ces constructions peuvent être utilisées pour déstructurer un tableau en variables distinctes.

Exemple #11 Déstructuration de tableau

    <?php
    $tableau_source = ['foo', 'bar', 'baz'];

    [$foo, $bar, $baz] = $tableau_source;

    echo $foo, PHP_EOL;    // affiche "foo"
    echo $bar, PHP_EOL;    // affiche "bar"
    echo $baz, PHP_EOL;    // affiche "baz"
    ?>

La déstructuration de tableau peut être utilisée dans un `foreach` pour déstructurer un tableau multidimensionnel tout en itérant sur celui-ci.

Exemple #12 Déstructuration de tableau dans un foreach

    <?php
    $tableau_source = [
        [1, 'John'],
        [2, 'Jane'],
    ];

    foreach ($tableau_source as [$id, $name]) {
        echo "{$id}: '{$name}'\n";
    }
    ?>

Les éléments du tableau seront ignorés si la variable n'est pas fournie. Le tableau commence toujours à l'index `0`.

Exemple #13 Ignorer des éléments

    <?php
    $tableau_source = ['foo', 'bar', 'baz'];

    // Assigne l'élément situé à l'indice 2 à la variable $baz
    [, , $baz] = $tableau_source;

    echo $baz;    // Affiche "baz"
    ?>

À partir de PHP 7.1.0, les tableaux associatifs peuvent aussi être déstructurés. Cela permet de sélectionner plus facilement le bon élément dans les tableaux à indexation numérique, car l'index peut être explicitement spécifié.

Exemple #14 Déstructuration de tableau associatif

    <?php
    $tableau_source = ['foo' => 1, 'bar' => 2, 'baz' => 3];

    // Assigne l'élément situé à l'indice 'baz' à la variable $three
    ['baz' => $three] = $tableau_source;

    echo $three, PHP_EOL;    // Affiche "3"

    $tableau_source = ['foo', 'bar', 'baz'];

    // Assigne l'élément situé à l'indice 2 à la variable $baz
    [2 => $baz] = $tableau_source;

    echo $baz, PHP_EOL;    // Affiche "baz"
    ?>

La déstructuration de tableau peut être utilisée pour permuter facilement deux variables.

Exemple #15 Permuter deux variables

    <?php
    $a = 1;
    $b = 2;

    [$b, $a] = [$a, $b];

    echo $a, PHP_EOL;    // Affiche 2
    echo $b, PHP_EOL;    // Affiche 1
    ?>

> Note:

> L'opérateur de décomposition (`...`) n'est pas supporté dans les assignations.

> Note:

> Une tentative d'accès à une clé d'un tableau qui n'a pas été définie revient à tenter d'accéder à une variable non définie : une alerte de niveau `E_WARNING` sera émise (E_NOTICE avant PHP 8.0.0), et le résultat vaudra `null`.

> Note:

> La déstructuration d’une valeur scalaire affecte `null` à toutes les variables.

### Fonctions utiles

Il y a beaucoup de fonctions utiles pour travailler avec les tableaux. Il est recommandé de lire la section de ce manuel sur les fonctions en rapport avec les tableaux.

> Note:

> La fonction unset() permet d'effacer les clés d'un tableau. Il est à noter que le tableau ne sera pas ré-indexé. Pour réaliser un effacement complet et une ré-indexation du tableau, il faut utiliser la fonction array_values().

> Exemple #16 Effacer des éléments intermédiaires

>     <?php
>     $a = array(1 => 'one', 2 => 'two', 3 => 'three');

>     /* produira un tableau comme ceci
>        $a = array(1 => 'one', 3 => 'three');
>        et NON un tableau comme ceci
>        $a = array(1 => 'one', 2 =>'three');
>     */
>     unset($a[2]);
>     var_dump($a);

>     $b = array_values($a);
>     // Maintenant, $b vaut array(0 => 'one', 1 =>'three')
>     var_dump($b);
>     ?>

La structure de contrôle `foreach` existe tout spécialement pour les tableaux. Elle fournit une manière pratique de parcourir un tableau.

### Ce qu'il est possible de faire ou non avec un tableau

#### Pourquoi `$foo[bar]` est incorrect ?

Utiliser toujours des guillemets autour d'un index littéral. Par exemple, `$foo['bar']` est correct, alors que `$foo[bar]` ne l'est pas. Mais pourquoi ? Il est courant de rencontrer ce genre de syntaxe dans d'anciens scripts :

    <?php
    $foo[bar] = 'enemy';
    echo $foo[bar];
    // etc
    ?>

C'est incorrect, mais ça fonctionne. La raison est que ce code a une constante indéfinie (`bar`) plutôt qu'une chaîne de caractères (`'bar'` - il est à noter la présence des guillemets). Cela fonctionne car PHP convertit automatiquement une chaîne nue (une chaîne sans guillemets qui ne correspond à aucun symbole connu) en une chaîne qui la contient. Par exemple, s'il n'y a aucune constante nommée `bar`, alors PHP substituera `'bar'` dans la chaîne et l'utilisera.

Avertissement

La solution de recours qui considère une constante non-définie comme une chaîne de caractères nue est une erreur de niveau `E_NOTICE`. Ceci est obsolète à partir de PHP 7.2.0, et émet une erreur de niveau `E_WARNING`. À partir de PHP 8.0.0, ceci a été retiré et lance une exception Error.

Ceci ne signifie pas qu'il faut toujours mettre la clé entre guillemets. Ne pas utiliser de guillemets avec les clés qui sont des constantes ou des variables, car cela empêcherait PHP de les interpréter.

Exemple #17 Clé entre guillemets

    <?php
    error_reporting(E_ALL);
    ini_set('display_errors', true);
    ini_set('html_errors', false);

    // Tableau simple :
    $array = array(1, 2);
    $count = count($array);

    for ($i = 0; $i < $count; $i++) {
        echo "\nVérification de $i : \n";
        echo "Mauvais : " . $array['$i'] . "\n";
        echo "Bon : " . $array[$i] . "\n";
        echo "Mauvais : {$array['$i']}\n";
        echo "Bon : {$array[$i]}\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    Vérification de 0 :
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Mauvais :
    Bon : 1
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Mauvais :
    Bon : 1

    Vérification de 1 :
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Mauvais :
    Bon : 2
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Mauvais :
    Bon : 2

Plus d'exemples pour expliquer ce comportement :

Exemple #18 Plus d'exemples

    <?php
    // Affichons toutes les erreurs
    error_reporting(E_ALL);

    $arr = array('fruit' => 'apple', 'veggie' => 'carrot');

    // Correct
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr['veggie'], PHP_EOL; // carrot

    // Incorrect. Ceci ne fonctionne pas et lance une erreur PHP
    // on utilise la constante nommée fruit qui est indéfinie
    //
    // Error: Undefined constant "fruit"
    try {
        echo $arr[fruit];
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    // Ceci définit une constante pour expliquer ce qui ne va pas. La valeur 'veggie'
    // est assignée à la constante nommée fruit.
    define('fruit', 'veggie');

    // Noter la différence maintenant
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr[fruit], PHP_EOL;    // carrot

    // Ce qui suit est correct, car c'est dans une chaîne. Les constantes ne sont pas recherchées
    // dans les chaînes, et donc, aucune erreur ne sera émise
    echo "Hello $arr[fruit]", PHP_EOL;      // Hello apple

    // Avec une exception : les accolades autour d'un tableau dans une chaîne permettent
    // aux constantes d'être interprétées
    echo "Hello {$arr[fruit]}", PHP_EOL;    // Hello carrot
    echo "Hello {$arr['fruit']}", PHP_EOL;  // Hello apple

    // La concaténation est une autre solution
    echo "Hello " . $arr['fruit'], PHP_EOL; // Hello apple
    ?>

    <?php
    // Ceci ne fonctionnera pas, et provoquera une erreur d'analyse du type :
    // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
    // Ceci s'applique aussi à l'utilisation des superglobales dans les chaînes
    print "Hello $arr['fruit']";
    print "Hello $_GET['foo']";
    ?>

Comme vu dans la section "syntaxe", ce qui se trouve entre crochets ('`[`' et '`]`') doit être une expression. Ceci signifie que le code ci-dessous fonctionne :

    <?php
    echo $arr[somefunc($bar)];
    ?>

C'est un exemple d'utilisation d'une fonction retournant une valeur qui sera la clé du tableau. PHP comprend également les constantes :

    <?php
    $error_descriptions[E_ERROR]   = "A fatal error has occurred";
    $error_descriptions[E_WARNING] = "PHP issued a warning";
    $error_descriptions[E_NOTICE]  = "This is just an informal notice";
    ?>

Noter que `E_ERROR` est également un identifiant valide, tout comme `bar` dans le premier exemple. Mais le dernier exemple est finalement le même que celui-ci :

    <?php
    $error_descriptions[1] = "A fatal error has occurred";
    $error_descriptions[2] = "PHP issued a warning";
    $error_descriptions[8] = "This is just an informal notice";
    ?>

car `E_ERROR` vaut `1`, etc.

##### Alors, pourquoi est-ce une mauvaise pratique ?

Dans le futur, les développeurs PHP peuvent vouloir ajouter une autre constante ou un autre mot-clé, ou bien une constante dans une autre partie du code qui peut interférer. Par exemple, il est toujours incorrect d'utiliser le mot `empty` et `default`, sachant que ce sont des mots réservés.

> Note: Pour être plus clair, dans une chaîne entourée de guillemets doubles, il est valide de ne pas entourer les index d'un tableau avec des guillemets, et donc, `"$foo[bar]"` est valide. Voir les exemples ci-dessous pour plus de détails mais aussi la section sur l'analyse des variables dans les chaînes.

### Conversion en un tableau

Pour tous les types entier, nombre décimal, chaîne de caractères, booléen et resource, le fait de convertir une valeur en un tableau résulte en un tableau contenant un seul élément dont l'index vaut zéro et la valeur, une valeur scalaire convertie. En d'autres termes, `(array) $scalarValue` est exactement la même chose que `array($scalarValue)`.

Si un objet est converti en un tableau, le résultat sera un tableau dont les éléments sont les propriétés de l'objet. Les clés sont les noms des membres, avec une légère exception : les variables ayant un nom sous forme d'entier sont inaccessibles ; les variables privées auront le nom de la classe ajouté au nom de la variable ; les variables protégées auront un '*' ajouté au nom de la variable. Ces valeurs préfixées ont des octets `NUL` des deux côtés. Les propriétés typées non-initialisées sont silencieusement écartées.

Exemple #19 Conversion en tableau

    <?php
    class A {
        private $B;
        protected $C;
        public $D;
        function __construct()
        {
            $this->{1} = null;
        }
    }
    var_export((array) new A());
    ?>

L'exemple ci-dessus va afficher :

    array (
      '' . "\0" . 'A' . "\0" . 'B' => NULL,
      '' . "\0" . '*' . "\0" . 'C' => NULL,
      'D' => NULL,
      1 => NULL,
    )

Ces octets `NUL` peuvent amener à des résultats inattendus :

Exemple #20 Conversion d'un objet en tableau

    <?php

    class A {
        private $A; // Ceci devient '\0A\0A'
    }

    class B extends A {
        private $A; // Ceci devient '\0B\0A'
        public $AA; // Ceci devient 'AA'
    }

    var_dump((array) new B());
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
      ["BA"]=>
      NULL
      ["AA"]=>
      NULL
      ["AA"]=>
      NULL
    }

Ici, on pourrait penser qu'il y a 2 clés nommées 'AA', alors qu'une est en fait nommée '\0A\0A'.

La conversion de `null` en un tableau résulte en un tableau vide.

### Comparaison

Il est possible de comparer plusieurs tableaux avec la fonction array_diff() ainsi qu'avec les opérateurs de tableaux.

### Déballage des tableaux

Un tableau préfixé par `...` sera déballé sur place lors de la définition du tableau. Seuls les tableaux et les objets qui implémentent Traversable peuvent être déballés. Le déballage de tableau avec `...` est disponible à partir de PHP 7.4.0. C'est aussi appelé l'opérateur de décomposition.

Il est possible de déballer plusieurs fois, et d'ajouter des éléments normaux avant et après l'opérateur `...` :

Exemple #21 Déballage simple de tableau

    <?php
    // Utilisation de la syntaxe de tableau courte.
    // Fonctionne avec array() aussi.
    $arr1 = [1, 2, 3];
    $arr2 = [...$arr1]; // [1, 2, 3]
    $arr3 = [0, ...$arr1]; // [0, 1, 2, 3]
    $arr4 = [...$arr1, ...$arr2, 111]; // [1, 2, 3, 1, 2, 3, 111]
    $arr5 = [...$arr1, ...$arr1]; // [1, 2, 3, 1, 2, 3]

    function getArr() {
      return ['a', 'b'];
    }
    $arr6 = [...getArr(), 'c' => 'd']; // ['a', 'b', 'c' => 'd']

    var_dump($arr1, $arr2, $arr3, $arr4, $arr5, $arr6);
    ?>

Déballer un tableau avec l'opérateur `...` suit les sémantiques de la fonction array_merge(). C'est-à-dire, que les clés ultérieures écrasent les valeurs antérieures et les clés numériques sont renumérotées :

Exemple #22 Déballage de tableau avec clé dupliquée

    <?php
    // clé de type string
    $arr1 = ["a" => 1];
    $arr2 = ["a" => 2];
    $arr3 = ["a" => 0, ...$arr1, ...$arr2];
    var_dump($arr3); // ["a" => 2]

    // clé de type int
    $arr4 = [1, 2, 3];
    $arr5 = [4, 5, 6];
    $arr6 = [...$arr4, ...$arr5];
    var_dump($arr6); // [1, 2, 3, 4, 5, 6]
    // Ce qui correspond à [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6]
    // où les clés entières originales n'ont pas été conservées.
    ?>

> Note:

> Les clés qui ne sont ni des entiers, ni des chaînes lancent une TypeError. De telles clés peuvent uniquement être générées par un objet Traversable.

> Note:

> Avant PHP 8.1, le déballage de tableau qui avait une clé sous forme de chaîne n'est pas supporté :

>     <?php

>     $arr1 = [1, 2, 3];
>     $arr2 = ['a' => 4];
>     $arr3 = [...$arr1, ...$arr2];
>     // Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5

>     $arr4 = [1, 2, 3];
>     $arr5 = [4, 5];
>     $arr6 = [...$arr4, ...$arr5]; // works. [1, 2, 3, 4, 5]
>     ?>

### Exemples

Le type tableau en PHP est vraiment polyvalent. Voici quelques exemples :

Exemple #23 Versatilité d'un tableau

    <?php
    // Ceci
    $a = array( 'color' => 'red',
                'taste' => 'sweet',
                'shape' => 'round',
                'name'  => 'apple',
                 4        // la clé sera 0
              );

    $b = array('a', 'b', 'c');

    var_dump($a, $b);

    // est strictement équivalent à
    $a = array();
    $a['color'] = 'red';
    $a['taste'] = 'sweet';
    $a['shape'] = 'round';
    $a['name']  = 'apple';
    $a[]        = 4;        // la clé sera 0

    $b = array();
    $b[] = 'a';
    $b[] = 'b';
    $b[] = 'c';

    // Après exécution du code ci-dessus, $a sera le tableau
    // array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
    // 'name' => 'apple', 0 => 4), et $b sera le tableau
    // array(0 => 'a', 1 => 'b', 2 => 'c'), ou simplement array('a', 'b', 'c').

    var_dump($a, $b);
    ?>

Exemple #24 Utilisation de array()

    <?php
    // Tableau comme carte de propriétés
    $map = array( 'version'    => 4,
                  'OS'         => 'Linux',
                  'lang'       => 'english',
                  'short_tags' => true
                );
    var_dump($map);

    // clés numériques strictes
    // est identique à array(0 => 7, 1 => 8, ...)
    $array = array( 7,
                    8,
                    0,
                    156,
                    -10
                  );
    var_dump($array);

    $switching = array(         10, // clé = 0
                        5    =>  6,
                        3    =>  7,
                        'a'  =>  4,
                                11, // clé = 6 (l'indice entier maximal est 5)
                        '8'  =>  2, // clé = 8 (entier !)
                        '02' => 77, // clé = '02'
                        0    => 12  // la valeur 10 sera écrasée par la valeur 12
                      );
    var_dump($switching);

    // tableau vide
    $empty = array();
    var_dump($empty);
    ?>

Exemple #25 Collection

    <?php
    $colors = array('rouge', 'bleu', 'verte', 'jaune');

    foreach ($colors as $color) {
        echo "Aimez-vous la couleur $color ?\n";
    }

    ?>

L'exemple ci-dessus va afficher :

    Aimez-vous la couleur rouge ?
    Aimez-vous la couleur bleu ?
    Aimez-vous la couleur verte ?
    Aimez-vous la couleur jaune ?

La modification directe de valeurs d'un array est possible en le passant par référence.

Exemple #26 Modification d'un élément dans la boucle

    <?php
    $colors = array('rouge', 'bleu', 'verte', 'jaune');

    foreach ($colors as &$color) {
        $color = mb_strtoupper($color);
    }
    unset($color); /* On s'assure que les écritures suivantes
    sur $color ne modifient pas le dernier élément du tableau */

    print_r($colors);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => ROUGE
        [1] => BLEU
        [2] => VERTE
        [3] => JAUNE
    )

Cet exemple crée un tableau, dont l'indexation commence à 1.

Exemple #27 Indexation commençant à 1

    <?php
    $firstquarter = array(1 => 'Janvier', 'Février', 'Mars');
    print_r($firstquarter);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [1] => Janvier
        [2] => Février
        [3] => Mars
    )

Exemple #28 Remplissage d'un tableau

    <?php
    // Remplit un tableau avec tous les éléments d'un dossier
    $handle = opendir('.');
    while (false !== ($file = readdir($handle))) {
        $files[] = $file;
    }
    closedir($handle);

    var_dump($files);
    ?>

Les tableaux sont ordonnés. L'ordre peut être modifié en utilisant plusieurs fonctions. Voir la section sur les fonctions sur les tableaux pour plus d'informations. La fonction count() peut être utilisée pour compter le nombre d'éléments d'un tableau.

Exemple #29 Tri d'un tableau

    <?php
    sort($files);
    print_r($files);
    ?>

Sachant que la valeur d'un tableau peut être n'importe quoi, elle peut aussi être un autre tableau. Ceci permet la création de tableaux récursifs et de tableaux multidimensionnels.

Exemple #30 Tableaux récursifs et multidimensionnels

    <?php
    $fruits = array ( "fruits"  => array ( "a" => "orange",
                                           "b" => "banana",
                                           "c" => "apple"
                                         ),
                      "numbers" => array ( 1,
                                           2,
                                           3,
                                           4,
                                           5,
                                           6
                                         ),
                      "holes"   => array (      "first",
                                           5 => "second",
                                                "third"
                                         )
                    );
    var_dump($fruits);

    // Quelques exemples pour retrouver les valeurs dans le tableau ci-dessus
    echo $fruits["holes"][5];    // affiche "second"
    echo $fruits["fruits"]["a"]; // affiche "orange"
    unset($fruits["holes"][0]);  // efface "first"

    // Création d'un tableau multidimensionnel
    $juices["apple"]["green"] = "good";
    var_dump($juices);
    ?>

L'assignation d'un tableau induit toujours la copie des valeurs. Utiliser l'opérateur de référence pour copier un tableau par référence.

Exemple #31 Copier des tableaux

    <?php
    $arr1 = array(2, 3);
    $arr2 = $arr1;
    $arr2[] = 4; // $arr2 est modifié,
                 // $arr1 vaut toujours array(2, 3)

    $arr3 = &$arr1;
    $arr3[] = 4; // maintenant, $arr1 et $arr3 sont identiques

    var_dump($arr1, $arr2, $arr3);
    ?>

## Les objets

### Initialisation des objets

Pour créer un nouvel object, utiliser le mot clé `new` afin d'instancier une classe :

Exemple #1 Construction d'objet

    <?php
    class foo
    {
        function do_foo()
        {
            echo "Doing foo.";
        }
    }

    $bar = new foo;
    $bar->do_foo();
    ?>

Pour une discussion complète, voir le chapitre sur les classes et les objets.

### Conversion en un objet

Si un objet est converti en un objet, il ne sera pas modifié. Si une valeur de n'importe quel type est convertie en un objet, une nouvelle instance de la classe interne stdClass sera créée. Si la valeur est `null`, la nouvelle instance sera vide. Un array se convertit en object avec les propriétés nommées au regard des clés avec leurs valeurs correspondantes. Il est à noter que dans ce cas, avant PHP 7.2.0 les clés numériques ont été inaccessibles à moins d'être itérées.

Exemple #2 Conversion en un objet

    <?php
    $obj = (object) array('1' => 'foo');
    var_dump(isset($obj->{'1'})); // affiche 'bool(true)'

    // Déprécié depuis PHP 8.1
    var_dump(key($obj)); // affiche 'string(1) "1"'
    ?>

Pour toute autre valeur, un membre appelé `scalar` contiendra la valeur.

Exemple #3 Conversion `(object)`

    <?php
    $obj = (object) 'ciao';
    echo $obj->scalar;  // Affiche : 'ciao'
    ?>

## Les énumérations

(PHP 8 >= 8.1.0)

### Les énumérations de base

Les énumérations constituent une couche restrictive au-dessus des classes et des constantes de classe. Elles permettent de définir un ensemble fermé de valeurs possibles pour un type.

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function do_stuff(Suit $s)
    {
        // ...
    }

    do_stuff(Suit::Spades);
    ?>

Pour une description complète, voir le chapitre sur les énumérations.

### Casting

Si une enum est convertie en object, elle n'est pas modifiée. Si une enum est convertie en array, un tableau avec une seule clé `name` (pour les Pure enums) ou un tableau avec les clés `name` et `value` (pour les Backed enums) est créé. Tous les autres types de conversion entraîneront une erreur.

## Les ressources

Une resource est une variable spéciale, contenant une référence vers une ressource externe. Les ressources sont créées et utilisées par des fonctions spéciales. Voir l'appendice pour une liste de toutes ces fonctions ainsi que les types de resource correspondants.

Voir aussi la fonction get_resource_type().

### Conversion en ressource

Sachant qu'une resource représente un fichier ouvert, une connexion à une base de données, une image, etc., la conversion en une ressource n'a pas de sens.

### Libération des ressources

Grâce au système de compteur de référence qui fait partie du Zend Engine, une resource qui n'a plus aucune référence est détectée automatiquement et est libérée par le ramasse-miettes. Pour cette raison, il est rarement nécessaire de libérer la mémoire manuellement.

> Note: Les connexions persistantes aux bases de données sont des exceptions à cette règle. Elles ne sont pas détruites par le ramasse-miettes. Voir la section sur les connexions persistantes pour plus d'informations.

## Callables

Un callable est une référence à une fonction ou une méthode qui est passée à une autre fonction en tant qu'argument. Les callables sont représentés avec la déclaration de type callable.

    <?php
    function foo(callable $callback) {
        $callback();
    }
    ?>

Certaines fonctions acceptent des fonctions de rappel en tant que paramètre, par exemple array_map(), usort(), ou preg_replace_callback().

### Création de callables

Un callable est un type qui représente quelque chose qui peut être invoqué. Les callables peuvent être passés en tant qu'arguments aux fonctions ou méthodes qui attendent un paramètre callback ou ils peuvent être invoqués directement. Le type callable ne peut pas être utilisé comme déclaration de type pour les propriétés. À la place, utiliser une déclaration de type Closure.

Les callables peuvent être créés de plusieurs façons différentes :

- Objet Closure
- Une chaîne de caractères contenant le nom d'une fonction ou d'une méthode
- Un tableau contenant le nom d'une classe ou un object dans l'index 0 et le nom de la méthode dans l'index 1
- Un objet implémentant la méthode magique __invoke()

Un objet Closure peut être créé en utilisant la syntaxe fonction anonyme, la syntaxe fonction fléchée, la syntaxe callable de première classe, ou la méthode Closure::fromCallable().

> Note: La syntaxe callable de première classe est disponible uniquement à partir de PHP 8.1.0.

Exemple #1 Exemple de callback utilisant une Closure

    <?php
    // Utilisant la syntaxe de fonction anonyme
    $double1 = function ($a) {
        return $a * 2;
    };

    // Utilisant la syntaxe callable de première classe
    function double_function($a) {
        return $a * 2;
    }
    $double2 = double_function(...);

    // Utilisant la syntaxe de fonction fléchée
    $double3 = fn($a) => $a * 2;

    // Utilisant la méthode Closure::fromCallable
    $double4 = Closure::fromCallable('double_function');

    // Utilisant la closure comme callback pour
    // doubler la taille de chaque élément dans notre range
    $new_numbers = array_map($double1, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double2, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double3, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double4, range(1, 5));
    print implode(' ', $new_numbers);

    ?>

Résultat de l'exemple ci-dessus en PHP 8.1 :

    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10

Un callable peut également être une string contenant le nom d'une fonction ou une méthode statique. N'importe quelle fonction intégrée ou définie par l'utilisateur peut être utilisée, à l'exception des constructions de langage telles que : array(), echo, empty(), eval(), isset(), list(), print ou unset().

Les méthodes de classes statiques peuvent être utilisées sans instancier un object de cette classe en créant soit un tableau avec le nom de la classe à l'index 0 et le nom de la méthode à l'index 1, ou en utilisant la syntaxe spéciale avec l'opérateur de résolution de portée `::`, comme dans `'ClassName::methodName'`.

Une méthode d'un object instancié peut être un callable lorsqu'elle est fournie sous forme de tableau avec le object à l'index 0 et le nom de la méthode à l'index 1.

La principale différence entre un objet Closure et le type callable est que l'objet Closure est indépendant de la portée et peut toujours être invoqué, alors qu'un type callable peut être dépendant de la portée et ne peut être invoqué directement. Closure est la méthode préférée pour créer des callables.

> Note: Tandis que les objets Closure sont liés à la portée où ils sont créés, les callables référençant des méthodes de classes sous forme de chaînes de caractères ou de tableaux sont résolus dans la portée où ils sont appelés. Pour créer un callable à partir d'une méthode privée ou protégée, qui peut ensuite être invoqué depuis l'extérieur de la classe, utiliser Closure::fromCallable() ou la syntaxe callable de première classe

PHP permet la création de callables qui peuvent être utilisés en tant qu'argument de callback mais qui ne peuvent pas être appelés directement. Il s'agit de callables dépendants du contexte qui référencent une méthode de classe dans la hiérarchie d'héritage d'une classe, par exemple `'parent::method'` ou `["static", "method"]`.

> Note: À partir de PHP 8.2.0, les callables dépendants du contexte sont dépréciés. Il faut supprimer la dépendance au contexte en remplaçant `'parent::method'` par `parent::class . '::method'` ou en utilisant la syntaxe callable de première classe.

Exemple #2 Appel de différents types de callables avec call_user_function()

    <?php

    // Un exemple de fonction de rappel
    function my_callback_function() {
        echo 'hello world!', PHP_EOL;
    }

    // Un exemple de méthode de rappel
    class MyClass {
        static function myCallbackMethod() {
            echo 'Hello World!', PHP_EOL;
        }
    }

    // Type 1: Fonction de rappel simple
    call_user_func('my_callback_function');

    // Type 2: Appel de méthode de classe statique
    call_user_func(['MyClass', 'myCallbackMethod']);

    // Type 3: Appel de méthode d'objet
    $obj = new MyClass();
    call_user_func([$obj, 'myCallbackMethod']);

    // Type 4: Appel de méthode de classe statique
    call_user_func('MyClass::myCallbackMethod');

    // Type 5: Appel de méthode de classe statique en utilisant le mot-clé ::class
    call_user_func([MyClass::class, 'myCallbackMethod']);

    // Type 6: Appel de méthode de classe statique relative
    class A {
        public static function who() {
            echo 'A', PHP_EOL;
        }
    }

    class B extends A {
        public static function who() {
            echo 'B', PHP_EOL;
        }
    }

    call_user_func(['B', 'parent::who']); // obsolète à partir de PHP 8.2.0

    // Type 7: Les objets implémentant __invoke peuvent être utilisés en tant que callables
    class C {
        public function __invoke($name) {
            echo 'Hello ', $name;
        }
    }

    $c = new C();
    call_user_func($c, 'PHP!');
    ?>

L'exemple ci-dessus va afficher :

    hello world!
    Hello World!
    Hello World!
    Hello World!
    Hello World!

    Deprecated: Callables of the form ["B", "parent::who"] are deprecated in script on line 41
    A
    Hello PHP!

> Note: Il est à noter que les fonctions de rappel enregistrées avec des fonctions comme call_user_func() et call_user_func_array() ne seront pas appelées si une exception n'est pas interceptée alors qu'elle a été lancée dans une précédente fonction de rappel.

## Mixed

Le type mixed accepte toutes les valeurs. Il est équivalent au type union `object|resource|array|string|float|int|bool|null`. Disponible à partir de PHP 8.0.0.

mixed est, dans le langage de la théorie des types, le type supérieur. Cela signifie que tous les autres types sont des sous-types de ce type.

## Void

void est une déclaration de type de retour uniquement, indiquant que la fonction ne retourne pas de valeur, mais que la fonction peut quand même se terminer. Il ne peut donc pas faire partie d'une déclaration de type d'union. Disponible à partir de PHP 7.1.0.

> Note: Même si une fonction a un type de retour void, elle retournera toujours une valeur, cette valeur est toujours `null`.

### Ignorer une valeur avec `(void)`

La syntaxe `(void)` peut être utilisée pour ignorer explicitement le résultat d'une expression. Cela permet d'indiquer que l'omission d'une valeur de retour est intentionnelle, en particulier lors de l'appel d'une fonction ou méthode marquée avec l'attribut NoDiscard.

Contrairement aux autres casts, `(void)` ne convertit pas la valeur en un autre type et ne produit pas de valeur. Il s'agit d'une instruction et il ne peut pas être utilisé en tant que partie d'une expression.

Exemple #1 Ignorer une valeur de retour

    <?php
    #[\NoDiscard]
    function process(): bool {
        return true;
    }

    (void) process(); // Ignore explicitement la valeur de retour
    ?>

## Never

never est uniquement un type de retour indiquant que la fonction ne se termine pas. Cela signifie qu'elle appelle exit(), lève une exception, ou est une boucle infinie. Elle ne peut donc pas faire partie d'une déclaration de type union. Disponible à partir de PHP 8.1.0.

never est, dans le langage de la théorie des types, le type vide. Cela signifie qu'il est le sous-type de tous les autres types et qu'il peut remplacer n'importe quel autre type de retour lors de l'héritage.

## Types de classes relatives

Ces déclarations de types ne peuvent être utilisées qu'à l'intérieur des classes.

### self

La valeur doit être un `instanceof` de la même classe que celle dans laquelle la déclaration de type est utilisée.

### parent

La valeur doit être un `instanceof` d'un parent de la classe dans laquelle la déclaration de type est utilisée.

### static

static est un type de retour uniquement qui exige que la valeur retournée soit un `instanceof` de la même classe que celle sur laquelle la méthode est appelée. Disponible à partir de PHP 8.0.0.

## Type singleton

Les types singleton sont ceux qui n'acceptent qu'une seule valeur. PHP prend en charge deux types singleton : false à partir de PHP 8.0.0 et true à partir de PHP 8.2.0.

Avertissement

Avant PHP 8.2.0, le type false ne pouvait être utilisé que dans le cadre d'un type union.

> Note: Il n'est pas possible de définir des types singleton personnalisés. Il convient d'utiliser une énumération à la place.

## Itérables

Un Iterable est un alias de type intégré au moment de la compilation pour `array|Traversable`. Depuis son introduction dans PHP 7.1.0 et avant PHP 8.2.0, iterable était un pseudo-type intégré qui agissait comme l'alias de type susmentionné et peut être utilisé comme une déclaration de type. iterable peut être utilisé dans une boucle `foreach` et avec yield from dans un générateur.

> Note:

> Les fonctions déclarant un type de retour itérable peuvent aussi être des générateurs.

> Exemple #1 Exemple de type de retour itérable d'un générateur

>     <?php

>     function gen(): iterable {
>         yield 1;
>         yield 2;
>         yield 3;
>     }

>     foreach(gen() as $value) {
>         echo $value, "\n";
>     }
>     ?>

## Déclarations de type

Les déclarations de types peuvent être ajoutées aux arguments des fonctions, valeurs de retour, et à partir de PHP 7.4.0, les propriétés de classe, et à partir de PHP 8.3.0, les constantes de classe. Elles assurent que la valeur est du type spécifié au moment de l'appel, sinon une TypeError est lancée.

Chaque type pris en charge par PHP, à l'exception du type resource, peut être utilisé dans une déclaration de type par l'utilisateur. Cette page contient un journal des modifications de la disponibilité des différents types et de la documentation sur leur utilisation dans les déclarations de type.

> Note:

> Lorsqu'une classe implémente une méthode d'interface ou réimplémente une méthode qui a déjà été définie par une classe parente, elle doit être compatible avec la définition susmentionnée. Une méthode est compatible si elle suit les règles de variance.

### Historique

Version | Description
--- | ---
8.3.0 | Ajout du support pour les constantes typées de classe, interface, trait, et enum.
8.2.0 | Ajout du support de type DNF (Forme Normale Disjonctive).
8.2.0 | Ajout du support du type true.
8.2.0 | Les types null et false peuvent désormais être utilisés de manière autonome.
8.1.0 | La prise en charge des types d’intersection a été ajoutée.
8.1.0 | Le renvoi par référence à partir d’une fonction void est désormais déconseillé.
8.1.0 | La prise en charge du type de retour uniquement never a été ajoutée.
8.0.0 | Ajout du support de mixed
8.0.0 | La prise en charge du type de retour uniquement static a été ajoutée.
8.0.0 | La prise en charge des types union a été ajoutée.
7.4.0 | Ajout du support du typage des propriétés de classe.
7.2.0 | Ajout du support pour object.
7.1.0 | Ajout du support pour iterable.
7.1.0 | Ajout du support pour void.
7.1.0 | La prise en charge des types nullable a été ajoutée.

### Notes d'utilisation des types atomiques

Les types atomiques ont un comportement direct avec quelques mises en garde mineures qui sont décrites dans cette section.

#### Types scalaires

Avertissement

Les alias pour les types scalaires (bool, int, float, string) ne sont pas supportés. À la place, ils sont traités comme des noms de classe ou d'interface. Par exemple, utiliser `boolean` comme une déclaration de type nécessite que la valeur soit une `instanceof` de la classe ou interface `boolean`, plutôt que de type bool :

    <?php
        function test(boolean $param) {}
        test(true);
    ?>

Résultat de l'exemple ci-dessus en PHP 8 :

    Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2

    Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
    Stack trace:
    #0 -(3): test(true)
    #1 {main}
      thrown in - on line 2

#### void

> Note:

> Le retour par référence à partir d’une fonction void est obsolète à partir de PHP 8.1.0, car une telle fonction est contradictoire. Auparavant, elle émettait déjà les `E_NOTICE` suivants lorsqu’elle était appelée : Only variable references should be returned by reference.

>     <?php
>     function &test(): void {}
>     ?>

#### Types Callable

Ce type ne peut pas être utilisé comme déclaration de type de propriété de classe.

> Note: Il n’est pas possible de spécifier la signature de la fonction.

#### Déclarations de type sur les paramètres de référence

Si un paramètre passé par référence a une déclaration de type, le type de la variable n’est vérifié qu’à l’entrée de la fonction, au début de l’appel, mais pas lorsque la fonction retourne. Cela signifie qu’une fonction peut modifier le type de la variable passée par référence.

Exemple #1 Paramètre typé passé par référence

    <?php
    function array_baz(array &$param)
    {
        $param = 1;
    }
    $var = [];
    array_baz($var);
    var_dump($var);
    array_baz($var);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(1)

    Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
    Stack trace:
    #0 -(9): array_baz(1)
    #1 {main}
      thrown in - on line 2

### Notes d’utilisation des types composites

Les déclarations de type composite sont soumises à quelques restrictions et effectueront un contrôle de redondance au moment de la compilation pour éviter les bogues simples.

Attention

Avant PHP 8.2.0 et l’introduction des types DNF, il n’était pas possible de combiner les intersections de type avec les unions de type.

#### Types d’unions

Avertissement

Il n’est pas possible de combiner les deux types de singleton `false` et `true` ensemble dans une union de type. Utiliser plutôt bool.

Attention

Avant PHP 8.2.0, comme false et null ne pouvaient pas être utilisés comme types autonomes, une union de type composée uniquement de ces types n’était pas autorisée. Cela comprend les types suivants : false, `false|null` et ?false.

##### Sucre syntaxique de type nullable

Une déclaration de type de base unique peut être marquée comme valeur NULL en faisant précéder le type d’un point d’interrogation (`?`). Ainsi `?T` et `T|null` sont identiques.

> Note: Cette syntaxe est prise en charge à partir de PHP 7.1.0, et est antérieure à la prise en charge généralisée des unions de type.

> Note:

> Il est également possible d’obtenir des arguments nullable en faisant de `null` la valeur par défaut. Ceci n’est pas recommandé, car si la valeur par défaut est modifiée dans une classe enfant, une violation de compatibilité de type sera déclenchée car le type null devra être ajouté à la déclaration de type. Ce comportement est également déprécié à partir de PHP 8.4.

> Exemple #2 Ancienne façon de rendre les arguments nullables

>     <?php
>     class C {}

>     function f(C $c = null) {
>         var_dump($c);
>     }

>     f(new C);
>     f(null);
>     ?>

> L'exemple ci-dessus va afficher :

>     object(C)#1 (0) {
>     }
>     NULL

#### Types dupliqués et redondants

Pour détecter des bogues simples dans les déclarations de type composite, les types redondants qui peuvent être détectés sans effectuer de chargement de classe entraîneront une erreur de compilation. Cela comprend :

- Chaque type résolu par nom ne peut se produire qu’une seule fois. Les types tels que `int|string|INT` ou `Countable&Traversable&COUNTABLE` génèrent une erreur.
- L’utilisation de mixed ou never entraîne une erreur.
- Pour les types d’unions :
  - Si bool est utilisé, false ou true ne peut pas être utilisé en plus.
  - Si object est utilisé, les types de classe ne peuvent pas être utilisés en plus.
  - Si iterable est utilisé, array et Traversable ne peuvent pas être utilisés en plus.
- Pour les types d’intersections :
  - L’utilisation d’un type qui n’est pas un type de classe génère une erreur.
  - L’utilisation de self, parent ou static entraîne une erreur.
- Pour les types DNF :
  - Si un type plus générique est utilisé, le plus restrictif est redondant.
  - Utilisation de deux types d’intersection identiques.

> Note: Cela ne garantit pas que le type est « minimal », car cela nécessiterait de charger tous les types de classe utilisés.

Par exemple, si `A` et `B` sont des alias de classe, alors `A|B` reste une union de type légale, même s'il est possible de réduire à `A` ou `B`. De même, si la classe `B extends A {}`, alors `A|B` est également une union de type légale, même s'il pourrait être réduit au type `A` uniquement.

    <?php
    function foo(): int|INT {} // Non autorisé
    function foo(): bool|false {} // Non autorisé
    function foo(): int&Traversable {} // Non autorisé
    function foo(): self&Traversable {} // Non autorisé

    use A as B;
    function foo(): A|B {} // Non autorisé ("use" fait partie de la résolution de noms)
    function foo(): A&B {} // Non autorisé ("use" fait partie de la résolution de noms)

    class_alias('X', 'Y');
    function foo(): X|Y {} // Autorisé (la redondance n'est connue qu'au moment de l'exécution)
    function foo(): X&Y {} // Autorisé (la redondance n'est connue qu'au moment de l'exécution)
    ?>

### Exemples

Exemple #3 Déclaration de type de classe de base

    <?php
    class C {}
    class D extends C {}

    // Ceci n'étend pas C.
    class E {}

    function f(C $c) {
        echo get_class($c)."\n";
    }

    f(new C);
    f(new D);
    f(new E);
    ?>

Résultat de l'exemple ci-dessus en PHP 8 :

    C
    D

    Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
    Stack trace:
    #0 -(14): f(Object(E))
    #1 {main}
      thrown in - on line 8

Exemple #4 Déclaration de type d’interface de base

    <?php
    interface I { public function f(); }
    class C implements I { public function f() {} }

    // Ceci n'implémente pas I.
    class E {}

    function f(I $i) {
        echo get_class($i)."\n";
    }

    f(new C);
    f(new E);
    ?>

Résultat de l'exemple ci-dessus en PHP 8 :

    C

    Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8
    Stack trace:
    #0 -(13): f(Object(E))
    #1 {main}
      thrown in - on line 8

Exemple #5 Déclaration de type de retour de base

    <?php
    function sum($a, $b): float {
        return $a + $b;
    }

    // À noter qu'un float sera retourné.
    var_dump(sum(1, 2));
    ?>

L'exemple ci-dessus va afficher :

    float(3)

Exemple #6 Renvoi d’un objet

    <?php
    class C {}

    function getC(): C {
        return new C;
    }

    var_dump(getC());
    ?>

L'exemple ci-dessus va afficher :

    object(C)#1 (0) {
    }

Exemple #7 Déclaration de type d’argument nullable

    <?php
    class C {}

    function f(?C $c) {
        var_dump($c);
    }

    f(new C);
    f(null);
    ?>

L'exemple ci-dessus va afficher :

    object(C)#1 (0) {
    }
    NULL

Exemple #8 Déclaration de type de retour nullable

    <?php
    function get_item(): ?string {
        if (isset($_GET['item'])) {
            return $_GET['item'];
        } else {
            return null;
        }
    }
    ?>

Exemple #9 Déclaration de type pour les propriétés de classe

    <?php
    class User {
        public static string $foo = 'foo';

        public int $id;
        public string $username;

        public function __construct(int $id, string $username) {
            $this->id = $id;
            $this->username = $username;
        }
    }
    ?>

### Typage Strict

Par défaut, PHP va convertir les valeurs d'un mauvais type vers le type scalaire attendu tant que possible. Par exemple, une fonction, qui attend comme paramètre une string, à laquelle est passée un int recevra une variable de type string.

Il est possible d'activer le mode de typage strict fichier par fichier. Dans le mode strict, seule une variable correspondant exactement au type attendu dans la déclaration sera acceptée sinon une TypeError sera lancée. La seule exception à cette règle est qu'une valeur de type int peut passer une déclaration de type float.

Avertissement

Les appels aux fonctions depuis des fonctions internes ne seront pas affectés par la déclaration `strict_types`.

Pour activer le mode strict, l'expression `declare` est utilisée avec la déclaration `strict_types` :

> Note:

> Le typage strict s'applique aux appels de fonction effectués depuis l'intérieur d'un fichier dont le typage strict est actif, et non aux fonctions déclarées dans ce fichier. Si un fichier dont le typage strict n'est pas activé effectue un appel à une fonction qui a été définie dans un fichier dont le type strict est actif, la préférence de l'appelant (mode coercitif) sera respectée et la valeur sera forcée.

> Note:

> Le typage strict n'est défini que pour les déclarations de type scalaire.

Exemple #10 Typage strict pour les valeurs d'arguments

    <?php
    declare(strict_types=1);

    function sum(int $a, int $b) {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1.5, 2.5));
    ?>

Résultat de l'exemple ci-dessus en PHP 8 :

    int(3)

    Fatal error: Uncaught TypeError: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4
    Stack trace:
    #0 -(9): sum(1.5, 2.5)
    #1 {main}
      thrown in - on line 4

Exemple #11 Typage coercitif pour les valeurs d'arguments

    <?php
    function sum(int $a, int $b) {
        return $a + $b;
    }

    var_dump(sum(1, 2));

    // Ceux-ci seront convertis en entiers : à noter la sortie ci-dessous !
    var_dump(sum(1.5, 2.5));
    ?>

L'exemple ci-dessus va afficher :

    int(3)
    int(3)

Exemple #12 Typage strict pour les valeurs de retour

    <?php
    declare(strict_types=1);

    function sum($a, $b): int {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1, 2.5));
    ?>

L'exemple ci-dessus va afficher :

    int(3)

    Fatal error: Uncaught TypeError: sum(): Return value must be of type int, float returned in -:5
    Stack trace:
    #0 -(9): sum(1, 2.5)
    #1 {main}
      thrown in - on line 5

## Jonglage de type

PHP ne requiert pas une définition de type explicite dans les déclarations de variables. Dans ce cas, le type d'une variable est déterminé en fonction de la valeur qu'elle stocke. C'est-à-dire, si une string est assignée à la variable $var, alors $var est de type string. Si après une valeur int est assignée à $var, elle sera de type int.

PHP peut tenter de convertir le type d'une valeur en une autre automatiquement dans certains contextes. Les différents contextes qui existent sont :

- Numérique
- String
- Logique
- Intégral et string
- Comparatif
- Fonction

> Note: Quand une valeur a besoin d'être interprétée comme un type différent, la valeur elle-même ne change pas de type.

Pour forcer une variable à être évaluée comme un type particulier, voir la section sur le casting de type. Pour changer le type d'une variable, voir la fonction settype().

### Contextes numériques

Ceci est le contexte lors de l'utilisation d'un opérateur arithmétique.

Dans ce contexte si un des opérandes est un float (ou pas interprétable comme int), les deux opérandes sont interprétés comme des floats, et le résultat sera un float. Sinon, les opérandes sont interprétés comme des ints, et le résultat sera aussi un int. À partir de PHP 8.0.0, si un des opérandes ne peut être interprété, une TypeError est lancée.

### Contextes string

Ceci est le contexte lors de l'utilisation de echo, print, l'interpolation de chaînes de caractères, ou l' opérateur de concaténation pour les chaînes de caractères.

Dans ce contexte la valeur sera interprétée comme une string. Si la valeur ne peut pas être interprétée, une TypeError est levée. Avant PHP 7.4.0, une `E_RECOVERABLE_ERROR` était soulevée.

### Contextes logiques

Ceci est le contexte lors de l'utilisation de déclarations conditionnelles, l'opérateur ternaire, ou un opérateur logique.

Dans ce contexte la valeur sera interprétée comme un bool.

### Contextes intégraux et string

Ceci est le contexte lors de l'utilisation d'un opérateur bit à bit.

Dans ce contexte si tous les opérandes sont de type string alors le résultat sera aussi une string. Sinon, les opérandes seront interprétés comme des ints, et le résultat sera aussi un int. À partir de PHP 8.0.0, si un des opérandes ne peut être interprété, une TypeError est lancée.

### Contextes comparatifs

Ceci est le contexte lors de l'utilisation d'un opérateur de comparaison.

Les conversions de types qui se produisent dans ce contexte sont expliquées dans le tableau Comparaison avec plusieurs types.

### Contextes de fonctions

Ceci est le contexte quand une valeur est passée à un paramètre ou propriété typée ou retournée depuis une fonction qui déclare un type de retour.

Dans ce contexte, la valeur doit être une valeur du type. Il existe deux exceptions, la première est la suivante : si la valeur est de type int et que le type déclaré est float, alors l'entier est converti en nombre à virgule flottante. La seconde est : si le type déclaré est un type scalaire , la valeur est convertible en un type scalaire, et le mode de typage coercitif est actif (par défaut), la valeur peut être convertie en une valeur scalaire acceptée. Voir ci-dessous pour une description de ce comportement.

Avertissement

Les fonctions internes contraignent automatiquement `null` aux types scalaires, ce comportement est OBSOLÈTE à partir de PHP 8.1.0.

#### Typage coercitif avec déclarations de type simples

- Type de déclaration bool : valeur est interprétée comme bool.
- Type de déclaration int : valeur est interprétée comme int si la conversion est bien-définie. Par exemple la chaîne est numérique.
- Type de déclaration float : valeur est interprétée comme float si la conversion est bien-définie. Par exemple la chaîne est numérique.
- Type de déclaration string : valeur est interprétée comme string.

#### Typage coercitif avec unions de type

Lorsque `strict_types` n’est pas activé, les déclarations de type scalaire sont soumises à des contraintes de type implicites limitées. Si le type exact de la valeur ne fait pas partie de l’union, le type cible est choisi dans l’ordre de préférence suivant :

1. int
2. float
3. string
4. bool

Si le type existe dans l'union et que la valeur peut être forcée en ce type en utilisant la sémantique de vérification de type existante de PHP, alors le type est choisi. Sinon, le type suivant est essayé.
Attention

À titre d’exception, si la valeur est une chaîne et que int et float font tous deux partie de l’union, le type préféré est déterminé par la sémantique de chaîne numérique. Par exemple, pour `"42"` int est choisi, tandis que pour `"42.0"` float est choisi.

> Note:

> Les types qui ne font pas partie de la liste de préférences ci-dessus ne sont pas des cibles admissibles à la coercition implicite. En particulier, aucune contrainte implicite aux types null, false, et true ne se produit.

Exemple #1 Exemple de types contraints à un type faisant partie de l'union

    <?php
    // int|string
    42    --> 42          // type exact
    "42"  --> "42"        // type exact
    new ObjectWithToString --> "Résultat de __toString()"
                          // Objet jamais compatible avec int, utilisation d'une string par défaut
    42.0  --> 42          // float compatible avec int
    42.1  --> 42          // float compatible avec int
    1e100 --> "1.0E+100"  // float trop grand pour le type int, utilisation d'une string par défaut
    INF   --> "INF"       // float trop grand pour le type int, utilisation d'une string par défaut
    true  --> 1           // bool compatible avec int
    []    --> TypeError   // tableau non compatible avec int ou string

    // int|float|bool
    "45"    --> 45        // int numérique string
    "45.0"  --> 45.0      // float numérique string

    "45X"   --> true      // string non numérique, bool par défaut
    ""      --> false     // string non numérique, bool par défaut
    "X"     --> true      // string non numérique, bool par défaut
    []      --> TypeError // tableau non compatible avec int, float ou bool
    ?>

### Cast de type

Le casting de type convertit la valeur en un type donné en écrivant le type entre parenthèses avant la valeur à convertir.

Exemple #2 Conversion de type

    <?php
    $foo = 10;          // $foo est un entier
    $bar = (bool) $foo; // $bar est un booléen

    var_dump($bar);
    ?>

Les casts permis sont :

- `(int)` - cast en int
- `(bool)` - cast en bool
- `(float)` - cast en float
- `(string)` - cast en string
- `(array)` - cast en array
- `(object)` - cast en object
- `(unset)` - cast en NULL

Le cast `(void)` est également disponible à partir de PHP 8.5.0, mais il ne s'agit pas d'une conversion de valeur. Il est utilisé en tant qu'instruction pour ignorer explicitement le résultat d'une expression.

Avertissement

`(integer)` est un alias du cast `(int)`. `(boolean)` est un alias du cast `(bool)`. `(binary)` est un alias du cast `(string)`. `(double)` et `(real)` sont des alias du cast `(float)`. Ces casts n'utilisent pas le nom de type canonique et sont obsolètes à partir de PHP 8.5.0.

Avertissement

L'alias de cast `(real)` est obsolète à partir de PHP 7.4.0 et supprimé à partir de PHP 8.0.0.

Avertissement

Le cast `(unset)` a été rendu obsolète à partir de PHP 7.2.0. À noter que le cast `(unset)` est identique à assigner la valeur NULL à une variable ou un appel. Le cast `(unset)` est supprimé à partir de PHP 8.0.0.

Attention

Le cast `(binary)` et le préfixe `b` existent uniquement pour la compatibilité ascendante. Actuellement `(binary)` et `(string)` sont identiques, mais ceci peut changer et il ne faut pas compter dessus.

> Note:

> Les espaces blancs sont ignorés à l'intérieur des parenthèses d'un cast. Ainsi, les deux casts suivants sont équivalents :

>     <?php
>     $foo = (int) $bar;
>     $foo = ( int ) $bar;
>     ?>

Cast de strings littérales et variables en strings binaires :

    <?php
    $binary = (binary) $string;
    $binary = b"binary string";
    ?>

Au lieu de transtyper une variable en une string, il est également possible d'entourer la variable de guillemets doubles.

Exemple #3 Différents mécanismes de conversion

    <?php
    $foo = 10;            // $foo est un entier
    $str = "$foo";        // $str est une chaîne
    $fst = (string) $foo; // $fst est également une chaîne

    // Ceci affiche "Ils sont les mêmes"
    if ($fst === $str) {
        echo "Ils sont les mêmes", PHP_EOL;
    }
    ?>

Ce qui se produira exactement lors d'un transtypage entre certains types n'est pas forcément évident. Pour plus d'informations, voir ces sections :

- Convertir en boolean
- Convertir en integer
- Convertir en float
- Convertir en string
- Convertir en array
- Convertir en object
- Convertir en resource
- Convertir en NULL
- Ignorer une valeur avec `(void)`
- Les tables de comparaison de type

> Note: Comme PHP prend en charge l'indexation dans les strings via des positions en utilisant la même syntaxe que l'indexation des array, l'exemple suivant est valable pour toutes les versions de PHP :

> Exemple #4 Utilisation d'un index de tableau avec une chaîne

>     <?php
>     $a    = 'car'; // $a est une chaîne de caractères
>     $a[0] = 'b';   // $a est toujours une chaîne de caractères
>     echo $a;       // bar
>     ?>

> Voir la section sur l'accès aux chaînes par caractère pour plus d'informations.

# Les variables

## Sommaire

- Essentiel
- Variables prédéfinies
- Portée des variables
- Les variables dynamiques
- Variables externes à PHP

## Essentiel

En PHP, les variables sont représentées par un signe dollar "$" suivi du nom de la variable. Le nom est sensible à la casse.

Un nom de variable valide commence par une lettre (`A-Z`, `a-z`, ou les octets de 128 à 255) ou par un souligné (_), suivi de lettres, chiffres ou soulignés. Exprimé sous la forme d'une expression régulière, cela donne : `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

> Note: PHP ne prend pas en charge les noms de variables Unicode, cependant, certains encodages de caractères (comme UTF-8) encodent les caractères de manière que tous les octets d'un caractère multi-octet soient dans la plage autorisée, ce qui en fait ainsi un nom de variable valide.

> Note: `$this` est une variable spéciale, qui ne peut pas être assignée. Avant PHP 7.1.0, l'affectation indirecte (c.-à-d. en utilisant les variables variables) était impossible.

Astuce

Jetez un oeil sur Guide de nommage de l'espace utilisateur.

Exemple #1 Noms de variables valides

    <?php
    $var = 'Jean';
    $Var = 'Paul';
    echo "$var, $Var";         // affiche "Jean, Paul"

    $_4site = 'pas encore';    // valide : commence par un souligné
    $täyte = 'mansikka';    // valide : 'ä' est ASCII (étendu) 228.

Exemple #2 Noms de variables invalides

    <?php
    $4site = 'pas encore';     // invalide : commence par un nombre

PHP accepte une séquence de n'importe quels octets comme nom de variable. Les noms de variables qui ne respectent pas les règles de nommage mentionnées ci-dessus ne peuvent être accédés que dynamiquement à l'exécution. Voir variables variables pour plus d'informations sur la façon d'y accéder.

Exemple #3 Accéder à des noms de variables inhabituels

    <?php
    ${'nom-invalide'} = 'bar';
    $nom = 'nom-invalide';
    echo ${'nom-invalide'}, " ", $$nom;

L'exemple ci-dessus va afficher :

    bar bar

Par défaut, les variables sont toujours assignées par valeur. C'est-à-dire, lorsqu'une expression est affectée à une variable, la valeur de l'expression est recopiée dans la variable. Cela signifie, par exemple, qu'après avoir assigné la valeur d'une variable à une autre, modifier l'une des variables n'aura pas d'effet sur l'autre. Pour plus de détails sur ce genre d'assignation, se reporter aux expressions.

PHP permet aussi d'assigner les valeurs aux variables par référence. Cela signifie que la nouvelle variable ne fait que référencer (en d'autres termes, "devient un alias de", ou encore "pointe sur") la variable originale. Les modifications de la nouvelle variable affecteront l'ancienne et vice versa.

Pour assigner par référence, il suffit d'ajouter un & (ET commercial) au début de la variable qui est assignée (la variable source). Dans l'exemple suivant, `Mon nom est Pierre` s'affichera deux fois :

    <?php
    $foo = 'Pierre';              // Assigne la valeur 'Pierre' à $foo
    $bar = &$foo;                 // Référence $foo avec $bar.
    $bar = "Mon nom est $bar";  // Modifie $bar...
    echo $bar . PHP_EOL;
    echo $foo . PHP_EOL;          // $foo est aussi modifiée

Une chose importante à noter est que seules les variables peuvent être assignées par référence.

    <?php
    $original = 25;
    $ref1 = &$original;        // assignation valide
    $ref2 = &(24 * 7);         // assignation invalide : référence une expression sans nom

    <?php
    // Noter l'absence de & indiquant un retour par référence dans la déclaration de la fonction.
    // Autrement dit, la fonction ne retourne pas une référence, donc le résultat ne peut pas être assigné par référence.
    function test()
    {
       $original = 25;
       return $original;
    }

    // Note : un avis est émis, mais la valeur sans référence est assignée
    $result1 = &test();        // invalide car test() ne retourne pas une variable par référence.
    var_dump($result1);

    // Cette fonction est définie comme retournant une référence, mais ne retourne pas une variable
    function &test2()
    {
        return 26;             // invalide car la valeur retournée n'est pas une référence à une variable.
    }

    // Note : la valeur sans référence est assignée
    $result2 = &test2();
    var_dump($result2);

Il n'est pas nécessaire de déclarer des variables en PHP, cependant, c'est une très bonne pratique. Accéder à une variable non définie entraînera un `E_WARNING` (avant PHP 8.0.0, `E_NOTICE`). Une variable non définie a une valeur par défaut de `null`. La construction de langage isset() peut être utilisée pour détecter si une variable a déjà été initialisée.

Exemple #4 Valeur par défaut d'une variable non initialisée

    <?php
    // Une variable non initialisée et non référencée (pas de contexte d'utilisation).
    var_dump($unset_var);

L'exemple ci-dessus va afficher :

    Warning: Undefined variable $unset_var in ...
    NULL

PHP permet l'autovivification de tableaux (création automatique de nouveaux tableaux) à partir d'une variable non définie. Ajouter un élément à une variable non définie créera un nouveau tableau et ne générera pas d'avertissement.

Exemple #5 Autovivification d'un tableau à partir d'une variable non définie

    <?php
    $unset_array[] = 'valeur'; // Ne génère pas d'avertissement.
    var_dump($unset_array);

Avertissement

Compter sur la valeur par défaut d'une variable non initialisée est problématique lorsqu'un fichier inclus dans un autre utilise le même nom de variable.

Une variable peut être détruite en utilisant la construction de langage unset().

Pour plus d'informations sur les fonctions liées aux variables, consulter la Référence des fonctions sur les variables.

## Variables prédéfinies

PHP fournit un certain nombre de variables prédéfinies. PHP fournit aussi un jeu de tableaux prédéfinis contenant les variables du serveur (si possible), les variables d'environnement et celles d'entrées. Ces tableaux sont automatiquement disponibles dans chaque portée. Pour cette raison, ils sont dits 'superglobaux'. (il n'y a pas de mécanisme en PHP pour créer de telles variables.) Pour plus de détails voir la liste des superglobales.

> Note: Variables variables

> Les superglobales ne peuvent pas être utilisées comme variables dynamiques dans les fonctions ou les méthodes des classes.

Si certaines variables de variables_order ne sont pas définies, leur tableau prédéfini PHP correspondant est laissé vide.

## Portée des variables

La portée d'une variable est le contexte dans lequel elle est définie. PHP possède une portée de fonction et une portée globale. Toute variable définie en dehors d'une fonction est limitée à la portée globale. Lorsqu'un fichier est inclus, le code qu'il contient hérite de la portée des variables de la ligne où l'inclusion a lieu.

Exemple #1 Exemple de portée de variable globale

    <?php
    $a = 1;
    include 'b.inc'; // La variable $a sera disponible dans b.inc.

Toute variable créée à l'intérieur d'une fonction nommée ou d'une fonction anonyme est limitée à la portée du corps de la fonction. Cependant, les fonctions fléchées lient les variables de la portée parente pour les rendre disponibles dans le corps. Si un fichier est inclus à l'intérieur d'une fonction dans le fichier appelant, les variables contenues dans le fichier appelé seront disponibles comme si elles avaient été définies à l'intérieur de la fonction appelante.

Exemple #2 Exemple de portée de variable locale

    <?php
    $a = 1; // portée globale

    function test()
    {
        var_dump($a); // La variable $a est indéfinie car elle fait référence à une version locale de $a
    }

    test();

L'exemple ci-dessus générera un `E_WARNING` de variable indéfinie (ou un `E_NOTICE` avant PHP 8.0.0). La raison pour cela est que l'instruction echo utilise la variable locale $a, et celle-ci n'a pas été assignée préalablement dans la fonction. Il est à noter que ce concept diffère un petit peu du langage C dans lequel une variable globale est automatiquement accessible dans les fonctions, à moins d'être redéfinie localement dans la fonction. Cela peut poser des problèmes lors de la redéfinition de variables globales localement. En PHP, une variable globale doit être déclarée à l'intérieur de chaque fonction afin de pouvoir être utilisée dans cette fonction.

### Le mot clé `global`

Le mot-clé `global` est utilisé pour lier une variable de la portée globale dans une portée locale. Le mot-clé peut être utilisé avec une liste de variables ou une seule variable. Une variable locale sera créée faisant référence à la variable globale du même nom. Si la variable globale n'existe pas, la variable sera créée dans la portée globale et assignée à `null`.

Exemple #3 Exemple avec `global`

    <?php
    $a = 1;
    $b = 2;

    function somme()
    {
        global $a, $b;

        $b = $a + $b;
    }

    somme();
    echo $b;

L'exemple ci-dessus va afficher :

    3

En déclarant globales les variables $a et $b locales de la fonction somme(), toutes les références à ces variables concerneront les variables globales. Il n'y a aucune limite au nombre de variables globales qui peuvent être manipulées par une fonction.

Une deuxième méthode pour accéder aux variables globales est d'utiliser le tableau associatif prédéfini $GLOBALS. Le précédent exemple peut être réécrit de la manière suivante :

Exemple #4 Les variables globales et $GLOBALS

    <?php
    $a = 1;
    $b = 2;

    function somme()
    {
        $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
    }

    somme();
    echo $b;

Le tableau $GLOBALS est un tableau associatif avec le nom des variables globales comme clé et les valeurs des éléments du tableau comme valeur des variables. Il est à noter que $GLOBALS existe dans tous les contextes, car $GLOBALS est un superglobal. Voici un exemple illustrant la puissance des superglobaux :

Exemple #5 Exemple montrant les superglobales et la portée

    <?php
    function test_superglobal()
    {
        echo $_POST['name'];
    }

> Note: L'utilisation du mot clé `global` à l'extérieur d'une fonction n'est pas une erreur. Il peut être utilisé si le fichier est inclus depuis l'intérieur d'une fonction.

### Utilisation des variables `static`

Une autre caractéristique importante de la portée des variables est la notion de variable static. Une variable statique a une portée locale uniquement, mais elle ne perd pas sa valeur lorsque le script appelle la fonction. Prenons l'exemple suivant :

Exemple #6 Les variables statiques

    <?php
    function test()
    {
        $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

Cette fonction est un peu inutile car à chaque fois qu'elle est appelée, elle initialise $a à `0` et affiche "`0`". L'incrémentation de la variable ($a++) ne sert pas à grand chose, car dès que la fonction est terminée, la variable $a disparaît. Pour faire une fonction de comptage utile, c'est-à-dire qui ne perdra pas la trace du compteur, la variable $a est déclarée comme une variable statique :

Exemple #7 Les variables statiques (2)

    <?php
    function test()
    {
        static $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

Maintenant, la variable $a est initialisée uniquement lors du premier appel à la fonction et, à chaque fois que la fonction `test()` est appelée, elle affichera une valeur de $a incrémentée de 1.

Les variables statiques sont essentielles lors d'appels récursifs à une fonction. La fonction suivante compte récursivement jusqu'à 10, en utilisant la variable $count pour savoir quand il faut s'arrêter :

Exemple #8 Les variables statiques et la récursivité

    <?php
    function test()
    {
        static $count = 0;

        $count++;
        echo $count . PHP_EOL;
        if ($count < 10) {
            test();
        }
        $count--;
    }

    test();

Avant PHP 8.3.0, une variable statique ne pouvait être initialisée qu'en utilisant une expression constante. À partir de PHP 8.3.0, les expressions dynamiques (par exemple, les appels de fonction) sont également autorisées :

Exemple #9 Déclaration de variables statiques

    <?php
    function foo(){
        static $int = 0;          // correct
        static $int = 1+2;        // correct
        static $int = sqrt(121);  // correct à partir de PHP 8.3.0

        $int++;
        echo $int;
    }

Les variables statiques à l'intérieur des fonctions anonymes persistent uniquement au sein de cette instance spécifique de la fonction. Si la fonction anonyme est recréée à chaque appel, la variable statique sera réinitialisée.

Exemple #10 Variables statiques dans les fonctions anonymes

    <?php
    function exampleFunction($input) {
        $result = (static function () use ($input) {
            static $counter = 0;
            $counter++;
            return "Input: $input, Counter: $counter\n";
        });

        return $result();
    }

    // Les appels à exampleFunction recréent la fonction anonyme, donc la variable statique
    // ne conserve pas sa valeur.
    echo exampleFunction('A'); // Affiche : Input: A, Counter: 1
    echo exampleFunction('B'); // Affiche : Input: B, Counter: 1

À partir de PHP 8.1.0, lorsqu'une méthode utilisant des variables statiques est héritée (mais pas surchargée), la méthode héritée partage désormais les variables statiques avec la méthode parente. Cela signifie que les variables statiques dans les méthodes se comportent dorénavant de la même manière que les propriétés statiques.

À partir de PHP 8.3.0, les variables statiques peuvent être initialisées avec des expressions arbitraires. Cela signifie que des appels de méthode, par exemple, peuvent être utilisés pour initialiser des variables statiques.

Exemple #11 Utilisation de variables statiques dans les méthodes héritées

    <?php
    class Foo {
        public static function counter() {
            static $counter = 0;
            $counter++;
            return $counter;
        }
    }
    class Bar extends Foo {}
    var_dump(Foo::counter()); // int(1)
    var_dump(Foo::counter()); // int(2)
    var_dump(Bar::counter()); // int(3), avant PHP 8.1.0 int(1)
    var_dump(Bar::counter()); // int(4), avant PHP 8.1.0 int(2)

### Les références avec les variables `global` et `static`

PHP implémente les modificateurs de variables static et global, en termes de référence. Par exemple, une vraie variable globale est importée dans un contexte de fonction avec `global`. Cette commande crée en fait une référence sur la variable globale. Cela peut mener à des comportements inattendus, par exemple :

    <?php
    function test_global_ref() {
        global $obj;
        $new = new stdClass;
        $obj = &$new;
    }

    function test_global_noref() {
        global $obj;
        $new = new stdClass;
        $obj = $new;
    }

    test_global_ref();
    var_dump($obj);
    test_global_noref();
    var_dump($obj);

L'exemple ci-dessus va afficher :

    NULL
    object(stdClass)#1 (0) {
    }

Un comportement similaire s'applique à la commande `static`. Les références ne sont pas stockées dynamiquement :

    <?php
    function &get_instance_ref() {
        static $obj;

        echo 'Static object: ';
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // Assigne une référence à la variable statique
            $obj = &$new;
        }
        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }
        return $obj;
    }

    function &get_instance_noref() {
        static $obj;

        echo 'Static object: ';
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // Assigne l'objet à la variable statique
            $obj = $new;
        }
        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }
        return $obj;
    }

    $obj1 = get_instance_ref();
    $still_obj1 = get_instance_ref();
    echo "\n";
    $obj2 = get_instance_noref();
    $still_obj2 = get_instance_noref();

L'exemple ci-dessus va afficher :

    Static object: NULL
    Static object: NULL

    Static object: NULL
    Static object: object(stdClass)#3 (1) {
      ["property"]=>
      int(1)
    }

Ces exemples illustrent les problèmes rencontrés lors de l'assignation de référence à des variables statiques, qui sont oubliées lorsque `&get_instance_ref()` est appelé une seconde fois.

## Les variables dynamiques

Il est pratique d'avoir parfois des noms de variables qui sont variables. C'est-à-dire un nom de variable qui est affecté et utilisé dynamiquement. Une variable classique est affectée avec l'instruction suivante :

    <?php
    $a = 'bonjour';
    var_dump($a);

Une variable dynamique prend la valeur d'une variable et l'utilise comme nom d'une autre variable. Dans l'exemple ci-dessous, bonjour peut être utilisé comme le nom d'une variable en utilisant le "$$" précédant la variable. C'est-à-dire :

    <?php
    $a = 'bonjour';
    $$a = 'monde';
    var_dump($bonjour);

À ce niveau, deux variables ont été définies et stockées dans l'arbre des symboles PHP : $a avec comme valeur "bonjour" et $bonjour avec comme valeur "monde". Alors, l'instruction :

    <?php
    $a = 'bonjour';
    $$a = 'monde';
    echo "$a {$$a}";

produira le même affichage que :

    <?php
    $a = 'bonjour';
    $$a = 'monde';
    echo "$a $bonjour";

c'est-à-dire : bonjour monde.

Afin d'utiliser des variables variables avec des tableaux, un problème d'ambiguïté doit être résolu. En effet, si l'analyseur rencontre $$a[1], il doit déterminer si $a[1] devait être utilisé comme une variable, ou si $$a était attendu comme la variable, suivi de l'indice `[1]` de cette variable. La syntaxe pour résoudre cette ambiguïté est la suivante : ${$a[1]} pour le premier cas et ${$a}[1] pour le deuxième.

On peut également accéder aux propriétés d'une classe en utilisant les noms des variables. Le nom de la variable sera résolu en utilisant la portée depuis laquelle l'appel s'effectue. Par exemple, s'il y a une expression de la forme $foo->$bar, alors la portée locale sera examinée pour $bar et sa valeur sera utilisée comme nom pour la propriété de $foo. Ce comportement reste valide si $bar est un tableau.

Les accolades peuvent aussi être utilisées pour clairement délimiter le nom de la propriété. Ceci est utile lors de l'accès à des valeurs d'une propriété qui contient un tableau, lorsque le nom de la propriété est composé de plusieurs parties, ou lorsque le nom de la propriété contient des caractères non valides (par exemple, depuis la fonction json_decode() ou SimpleXML).

Exemple #1 Exemple de propriété variable

    <?php
    class Foo {
        public $bar = 'I am bar.';
        public $arr = ['I am A.', 'I am B.', 'I am C.'];
        public $r   = 'I am r.';
    }

    $foo = new Foo();
    $bar = 'bar';
    $baz = ['foo', 'bar', 'baz', 'quux'];
    echo $foo->$bar . "\n";
    echo $foo->{$baz[1]} . "\n";

    $start = 'b';
    $end   = 'ar';
    echo $foo->{$start . $end} . "\n";

    $arr = 'arr';
    echo $foo->{$arr[1]} . "\n";
    echo $foo->{$arr}[1] . "\n";

L'exemple ci-dessus va afficher :

    I am bar.
    I am bar.
    I am bar.
    I am r.
    I am B.

Avertissement

Il est à noter que les variables dynamiques ne peuvent pas être utilisées avec les tableaux Superglobaux dans une fonction ou une classe. La variable `$this` est aussi une variable spéciale qui ne peut être référencée dynamiquement.

## Variables externes à PHP

### Formulaires HTML (GET et POST)

Lorsqu'un formulaire est envoyé à un script PHP, toutes les variables du formulaire seront automatiquement disponibles dans le script. Il y a peu de façons pour récupérer ces informations, par exemple :

Exemple #1 Exemple avec un formulaire simple

    <form action="foo.php" method="post">
        Nom  :  <input type="text" name="username" /><br />
        Email: <input type="text" name="email" /><br />
        <input type="submit" name="submit" value="Envoie!" />
    </form>

Il n'y a que deux façons d'accéder aux données provenant d'un formulaire HTML. Les méthodes disponibles actuellement sont décrites ci-dessous :

Exemple #2 Accéder simplement à des variables de formulaires POST

    <?php
    echo $_POST['username'];
    echo $_REQUEST['username'];

Utiliser un formulaire de type GET est similaire, hormis le fait que les variables prédéfinies de GET peuvent être utilisées à la place. GET s'applique aussi à la `QUERY_STRING` (les informations disponibles après le '?' dans une URL). De ce fait, par exemple, `http://www.example.com/test.php?id=3` contient les données de GET, qui sont accessibles via $_GET['id']. Voir aussi $_REQUEST.

> Note:

> Les points et les espaces dans les noms de variables sont convertis en underscores. Par exemple, `<input name="a.b" />` deviendra `$_REQUEST["a_b"]`.

PHP comprend aussi les tableaux dans le contexte des formulaires. (voir aussi la FAQ). Par exemple, des variables peuvent être groupées ensemble ou cette fonctionnalité peut être utilisée pour lire des valeurs multiples d'un menu déroulant. Par exemple, voici un formulaire qui se poste lui-même des données, et les affiche :

Exemple #3 Variables de formulaires complexes

    <?php
    if ($_POST) {
        echo '<pre>';
        echo htmlspecialchars(print_r($_POST, true));
        echo '</pre>';
    }
    ?>
    <form action="" method="post">
        Name:  <input type="text" name="personal[name]" /><br />
        Email: <input type="text" name="personal[email]" /><br />
        Beer: <br />
        <select multiple name="beer[]">
            <option value="warthog">Warthog</option>
            <option value="guinness">Guinness</option>
            <option value="stuttgarter">Stuttgarter Schwabenbräu</option>
        </select><br />
        <input type="submit" value="Validez moi !" />
    </form>

> Note: Si le nom d'une variable externe commence par une syntaxe valide pour un tableau, les caractères qui suivent sont silencieusement ignorés. Par exemple : `<input name="foo[bar]baz">` devient `$_REQUEST['foo']['bar']`.

#### Nom de variables IMAGE de type SUBMIT

Lors de la soumission d'un formulaire, il est possible d'utiliser une image au lieu d'un bouton standard, comme ceci :

    <input type="image" src="image.gif" name="sub" />

Lorsque l'utilisateur clique sur cette image, le formulaire associé est envoyé au serveur, avec deux données supplémentaires, sub_x et sub_y. Elles contiennent les coordonnées du clic de l'utilisateur dans l'image. Il est à noter que ces variables sont envoyées par le navigateur avec un point dans leur nom, mais PHP convertit ces points en soulignés.

### Cookies HTTP

PHP supporte les cookies HTTP de manière totalement transparente, comme défini dans la » RFC 6265. Les cookies sont un mécanisme permettant de stocker des données sur la machine cliente à des fins d'identification de l'utilisateur. Il est possible d'établir un cookie grâce à la fonction setcookie(). Les cookies font partie intégrante des en-têtes HTTP et donc la fonction setcookie() doit être appelée avant que le moindre affichage ne soit envoyé au navigateur. C'est la même restriction que pour la fonction header(). Les données contenues dans les cookies sont alors disponibles dans les tableaux de cookies appropriés, comme $_COOKIE mais aussi $_REQUEST. Consulter la page de la documentation sur la fonction setcookie() pour plus de détails ainsi que des exemples.

> Note: À partir de PHP 7.2.34, 7.3.23 et 7.4.11, respectivement, les noms des cookies entrants ne sont plus url-décodés, et ce, pour des raisons de sécurité.

Si plusieurs valeurs peuvent être assignées à un seul cookie, elles peuvent être assignées sous forme de tableau. Par exemple :

    <?php
    setcookie("MyCookie[foo]", 'Test 1', time()+3600);
    setcookie("MyCookie[bar]", 'Test 2', time()+3600);

Cela va créer deux cookies distincts bien que MyCookie soit maintenant un simple tableau dans le script. Si seulement un cookie doit être défini avec plusieurs valeurs, utiliser la fonction serialize() ou explode() sur la première valeur.

Il est à noter qu'un cookie remplace le cookie précédent par un cookie de même nom tant que le chemin ou le domaine sont identiques. Donc, pour une application de panier, il est possible de conserver un compteur et de l'incrémenter au fur et à mesure. C'est-à-dire :

Exemple #4 Exemple avec setcookie()

    <?php
    if (isset($_COOKIE['compte'])) {
        $compte = $_COOKIE['compte'] + 1;
    } else {
        $compte = 1;
    }
    setcookie('compte', $compte, time()+3600);
    setcookie("Panier[$compte]", $item, time()+3600);

### Cas des points dans les noms de variables

Typiquement, PHP ne modifie pas les noms des variables lorsqu'elles sont passées à un script. Cependant, il faut noter que les points (.) ne sont pas autorisés dans les noms de variables PHP. Pour cette raison, il convient d'examiner :

    <?php
    $varname.ext;  /* nom de variable invalide */

Dans ce cas, l'analyseur croit voir la variable nommée $varname, suivie par l'opérateur de concaténation, et suivie encore par la chaîne sans guillemets (une chaîne sans guillemets et qui n'a pas de signification particulière). Visiblement, ce n'est pas ce qu'on attendait...

Pour cette raison, il est important de noter que PHP remplacera automatiquement les points des noms de variables entrantes par des soulignés.

### Détermination du type des variables

Parce que PHP détermine le type des variables et les convertit (généralement) comme il faut, ce n'est pas toujours le type de variable souhaité. PHP inclut des fonctions permettant de déterminer le type d'une variable : gettype(), is_array(), is_float(), is_int(), is_object() et is_string(). Consulter également le chapitre sur les types.

HTTP étant un protocole texte, la plupart, sinon tous, le contenu qui vient dans les tableaux Superglobaux, comme $_POST et $_GET restera en tant que chaînes. PHP n'essaiera pas de convertir des valeurs en un type spécifique. Dans l'exemple ci-dessous, $_GET["var1"] contiendra la chaîne "null" et $_GET["var2"], la chaîne "123".

    /index.php?var1=null&var2=123

### Historique

Version | Description
--- | ---
7.2.34, 7.3.23, 7.4.11 | Les noms des cookies entrants ne sont plus url-décodés, et ce, pour des raisons de sécurité.

# Les constantes

## Sommaire

- Syntaxe
- Constantes prédéfinies
- Constantes magiques

Une constante est un identifiant (un nom) qui représente une valeur simple. Comme son nom le suggère, cette valeur ne peut jamais être modifiée durant l'exécution du script (sauf les constantes magiques, qui ne sont pas vraiment des constantes). Les constantes sont sensibles à la casse. Par convention, les constantes sont toujours en majuscule.

> Note:

> Avant PHP 8.0.0, les constantes définies en utilisant la fonction define() peuvent être insensibles à la casse.

Les noms de constantes suivent les mêmes règles que n'importe quel nom en PHP. Un nom de constante valide commence par une lettre ou un souligné, suivi d'un nombre quelconque de lettres, chiffres ou soulignés. Sous forme d'expression régulière, cela peut s'exprimer comme ceci : `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

Il est possible de définir une constante avec un nom réservé ou même invalide via define(), ces valeurs ne peuvent alors être récupérées qu'avec la fonction constant(). Faire ceci n'est cependant pas recommandé.

Astuce

Jetez un oeil sur Guide de nommage de l'espace utilisateur.

Exemple #1 Noms valides et invalides pour les constantes

    <?php
    // Noms valides
    define("FOO",     "something");
    define("FOO2",    "something else");
    define("FOO_BAR", "something more");

    // Noms invalides
    define("2FOO",    "something");

    // Ce nom est valide, mais évitez-le:
    // PHP peut un jour fournir une constante magique nommée
    // ainsi, ce qui va corrompre vos scripts.
    define("__FOO__", "something");

> Note: Dans cette documentation, une lettre peut être un des caractères suivants : de a à z, de A à Z et tous les caractères ASCII de 128 à 255 (`0x80-0xff`).

Tout comme les superglobals, la portée d'une constante est globale. Les constantes peuvent être accédées depuis partout dans un script sans tenir compte de la portée. Pour plus d'informations sur la portée, consulter la section du manuel sur la portée des variables.

> Note: À partir de PHP 7.1.0, les constantes de classes peuvent définir une visibilité de protégée ou privée, ne les rendant disponibles que dans la portée hiérarchique de la classe où elles ont été définies.

## Syntaxe

Les constantes peuvent être définies en utilisant le mot clé `const` ou en utilisant la fonction define(). Tandis que define() permet de définir une constante pour une expression arbitraire, le mot-clé `const` a des restrictions comme indiqué dans le paragraphe suivant. Une fois qu'une constante est définie, elle ne peut jamais être modifiée, ou détruite.

Lors de l'utilisation du mot-clé `const`, seules les expressions scalaires (bool, int, float et string) et des arrays constants contenant seulement des expressions scalaires sont acceptées. Il est possible de définir des constantes en tant que resource, mais cet usage est déconseillé, car il peut mener à des résultats inattendus.

La valeur d'une constante est accédée simplement en spécifiant son nom. Contrairement aux variables, une constante n'est pas préfixée d'un `$`. Il est aussi possible d'utiliser la fonction constant() pour lire la valeur d'une constante si son nom est obtenu dynamiquement. La fonction get_defined_constants() permet de connaître la liste de toutes les constantes définies.

> Note: Les constantes et les variables globales utilisent deux espaces de noms différents. Ce qui implique que `true` et $TRUE sont généralement différents (en tout cas, ils peuvent avoir des valeurs différentes).

Si une constante indéfinie est utilisée, une Error est levée. Avant PHP 8.0.0, les constantes indéfinies étaient interprétées comme un mot nu de type chaîne de caractères, c.-à-d. (CONSTANT vs "CONSTANT"). Cette solution de repli est dépréciée à partir de PHP 7.2.0, et une erreur de niveau `E_WARNING` était émise lorsque ce cas se produisait. Avant PHP 7.2.0, une erreur de niveau E_NOTICE était émise à la place. Voir également l'entrée du manuel qui explique pourquoi $foo[bar] est faux (sauf si `bar` est une constante). Ceci ne s'applique pas pour les constantes (complètement) qualifiées, qui lèvent toujours une Error si elles ne sont pas définies.

> Note: Pour vérifier qu'une constante est définie, utiliser la fonction defined().

Il y a des différences entre les constantes et les variables :

- Les constantes ne commencent pas par le signe (`$`).
- Les constantes sont définies et accessibles à tout endroit du code, globalement.
- Les constantes ne peuvent pas être redéfinies ou indéfinies une fois qu'elles ont été définies.
- Les constantes peuvent seulement évaluer à des valeurs scalaires ou tableaux.

Exemple #1 Définir une constante

    <?php
      define("CONSTANT", "Bonjour le monde.");
      echo CONSTANT; // affiche "Bonjour le monde."
      echo Constant; // Lève une Error : Undefined constant "Constant"
                     // Avant PHP 8.0.0, affiche "Constant" et émet un avertissement.

Exemple #2 Définir des constantes en utilisant le mot-clé `const`

    <?php
    // Simple valeur scalaire
    const CONSTANT = 'Bonjour le monde !';

    echo CONSTANT . "\n";

    // Expression scalaire
    const ANOTHER_CONST = CONSTANT . '; Au revoir le monde !';
    echo ANOTHER_CONST . "\n";

    const ANIMALS = array('chien', 'chat', 'oiseaux');
    echo ANIMALS[1] . "\n"; // affiche "chat"

    // Tableaux constants
    define('ANIMALS_DEF', array(
        'chien',
        'chat',
        'oiseaux'
    ));
    echo ANIMALS_DEF[1] . "\n"; // affiche "chat"

> Note:

> Contrairement aux constantes définies en utilisant l'instruction define(), les constantes définies en utilisant le mot-clé `const` doivent être déclarées au plus haut niveau du contexte, car elles seront définies au moment de la compilation. Cela signifie qu'elles ne peuvent être déclarées à l'intérieur de fonctions, boucles, instructions `if` ou blocs `try`/`catch`.

### Voir aussi

- Les Constantes de Classe

## Constantes prédéfinies

PHP fournit un grand nombre de constantes prédéfinies à tout script qu'il exécute. Beaucoup de ces constantes, cependant, sont créées par différentes extensions, et ne seront présentes que si ces extensions sont disponibles, soit via un chargement dynamique, soit parce qu'elles ont été compilées avec PHP.

## Constantes magiques

Il y a quelques constantes magiques qui changent suivant l'emplacement où elles sont utilisées. Par exemple, la valeur de `__LINE__` dépend de la ligne où elle est utilisée dans le script. Toutes ces constantes "magiques" sont évaluées au moment de la compilation, contrairement aux constantes classiques, qui sont évaluées au moment de l'exécution. Ces constantes spéciales sont insensibles à la casse et sont les suivantes :

Les constantes magiques de PHP
Nom | Description
--- | ---
`__LINE__` | La ligne courante dans le fichier.
`__FILE__` | Le chemin complet et le nom du fichier courant avec les liens symboliques résolus. Si utilisé pour une inclusion, le nom du fichier inclus est retourné.
`__DIR__` | Le dossier du fichier. Si utilisé dans une inclusion, le dossier du fichier inclus sera retourné. C'est l'équivalent de `dirname(__FILE__)`. Ce nom de dossier ne contiendra pas de slash final, sauf si c'est le dossier racine.
`__FUNCTION__` | Le nom de la fonction, ou `{closure}` pour les fonctions anonymes.
`__CLASS__` | Le nom de la classe courante. Le nom de la classe contient l'espace de noms dans lequel cette classe a été déclarée (c.-à-d. `Foo\Bar`). Lorsqu'elle est utilisée dans une méthode de trait, `__CLASS__` est le nom de la classe dans laquelle le trait est utilisé.
`__TRAIT__` | Le nom du trait. Le nom du trait inclut l'espace de noms dans lequel il a été déclaré (par exemple `Foo\Bar`).
`__METHOD__` | Le nom de la méthode courante.
`__PROPERTY__` | Valide uniquement à l'intérieur d'un hook de propriété. Il est égal au nom de la propriété.
`__NAMESPACE__` | Le nom de l'espace de noms courant.
`ClassName::class` | Le nom entièrement qualifié de la classe.

### Voir aussi

- ::class
- get_class()
- get_object_vars()
- file_exists()
- function_exists()

# Les expressions

Les expressions sont les pièces de construction les plus importantes de PHP. En PHP, presque tout ce qui s'écrit est une expression. La manière la plus simple de définir une expression est : "tout ce qui a une valeur".

Les formes les plus simples d'expressions sont les constantes et les variables. Lorsque l'on écrit `$a = 5`, on assigne la valeur `5` à la variable $a. Bien évidemment, `5` vaut 5 ou, en d'autres termes, `5` est une expression avec pour valeur 5 (dans ce cas, `5` est un entier constant).

Après cette assignation, on peut considérer que $a a pour valeur 5 et donc, écrire `$b = $a`, revient à écrire `$b = 5`. En d'autres termes, $a est une expression avec une valeur de 5. Si tout fonctionne correctement, c'est exactement ce qui arrive.

Un exemple plus complexe concerne les fonctions. Par exemple, considérons la fonction suivante :

    <?php
    function foo ()
    {
        return 5;
    }
    ?>

En supposant une familiarité avec le concept de fonction, (si ce n'est pas le cas, consulter le chapitre concernant les fonctions), on conviendra que `$c = foo()` est équivalent à `$c = 5`, et c'est tout à fait exact. Les fonctions sont des expressions qui ont la valeur de leur "valeur de retour". Si `foo()` renvoie 5, la valeur de l'expression `foo()` est 5. Habituellement, les fonctions ne font pas que renvoyer une valeur constante, mais réalisent des traitements.

Bien sûr, les valeurs en PHP n'ont pas à être des valeurs numériques, comme c'est souvent le cas. PHP supporte quatre types de variables scalaires : les valeurs entières (entier), les nombres à virgule flottante (float), les chaînes de caractères (chaîne de caractères) et les booléens (bool). (une variable scalaire est une variable qui ne peut pas être scindée en morceaux, au contraire des tableaux par exemple). PHP supporte aussi deux types composés : les tableaux et les objets. Chacun de ces types de variables peut être affecté ou renvoyé par une fonction.

PHP va plus loin dans la gestion des expressions, comme le font d'autres langages. PHP est un langage orienté expression, dans le sens où presque tout est une expression. Considérons l'exemple dont nous avons déjà parlé, `$a = 5`. Il est facile de voir qu'il y a deux valeurs qui entrent en jeu ici, la valeur de la constante entière `5` et la valeur de la variable $a qui est mise à jour à la valeur 5. Mais, la vérité est qu'il y a une autre valeur qui entre en jeu ici et c'est la valeur de l'assignation elle-même. L'assignation elle-même est assignée à une valeur, dans ce cas-là 5. En pratique, cela signifie que `$a = 5` est une expression qui a pour valeur 5. Donc, écrire `$b = ($a = 5)` revient à écrire `$a = 5; $b = 5;` (un point-virgule marque la fin d'une instruction). Comme les assignations sont analysées de droite à gauche, il est aussi possible d'écrire `$b = $a = 5`.

Un autre bon exemple du langage orienté expression est la pre-incrémentation et la post-incrémentation, (ainsi que la décrémentation). Les utilisateurs de PHP et ceux de nombreux autres langages sont habitués à la notation `variable++` et `variable--`. Ce sont les opérateurs d'incrémentation et de décrémentation. PHP ajoute les possibilités d'incrémentation et de décrémentation comme c'est le cas dans le langage C. En PHP, comme en C, il y a deux types d'opérateurs d'incrémentation (pre-incrémentation et post-incrémentation). Les deux types d'opérateur d'incrémentation jouent le même rôle (c'est-à-dire qu'ils incrémentent la variable). La différence vient de la valeur de l'opérateur d'incrémentation. L'opérateur de pre-incrémentation, qui s'écrit `++$variable`, évalue la valeur incrémentée (PHP incrémente la variable avant de lire la valeur de cette variable, d'où le nom de pre-incrémentation). L'opérateur de post-incrémentation, qui s'écrit `$variable++` , évalue la valeur de la variable $variable avant de l'incrémenter (PHP incrémente la variable après avoir lu sa valeur, d'où le nom de post-incrémentation).

Un type d'expression très commun est l'expression de comparaison. Ces expressions sont évaluées à `false` ou `true`, respectivement. PHP supporte les opérateurs de comparaison > (plus grand que), >= (plus grand ou égal), == (égal à), != (différent de), < (plus petit que) et <= (plus petit ou égal). Le langage supporte également un ensemble d'opérateurs d'équivalence stricte : === (égal à et du même type) et !== (différent de ou pas du même type). Ces expressions sont utilisées de manière courante dans les instructions conditionnelles, comme l'instruction `if`.

Pour le dernier exemple d'expression, nous allons parler des combinaisons d'opérateurs/assignation. Pour incrémenter la variable $a d'une unité, il suffit d'écrire `$a++` ou `++$a`. Mais pour ajouter la valeur 3 à la variable ? Il est possible d'écrire plusieurs fois `$a++`, mais ce n'est pas la meilleure des méthodes. Une pratique plus courante est d'écrire `$a = $a + 3`. L'expression `$a + 3` correspond à la valeur $a plus 3, et est de nouveau assignée à la variable $a. Donc, le résultat est l'incrémentation de 3 unités de la variable $a. En PHP, comme dans de nombreux autres langages comme le C, il est possible d'écrire cela de manière plus concise, manière qui avec le temps se révélera plus claire et plus rapide à comprendre. Ajouter 3 à la valeur de la variable $a peut s'écrire `$a += 3`. Cela signifie précisément : "on prend la valeur de la variable $a, on ajoute la valeur 3 et on assigne cette valeur à la variable $a". Et pour être plus concis et plus clair, cette expression est plus rapide. La valeur de l'expression `$a += 3`, comme l'assignation d'une valeur quelconque, est la valeur assignée. Il est à noter que ce n'est pas 3, mais la combinaison de la valeur de la variable $a plus la valeur 3. (c'est la valeur qui est assignée à la variable $a). N'importe quel opérateur binaire peut utiliser ce type d'assignation, par exemple `$a -= 5` (soustraction de 5 de la valeur de la variable $a), `$b *= 7` (multiplication de la valeur de la variable $b par 7).

Il y a une autre expression qui peut paraître complexe si elle n'a pas été vue dans d'autres langages, l'opérateur conditionnel ternaire :

    <?php
    $first ? $second : $third
    ?>

Si la valeur de la première sous-expression est vraie (`true`) (différente de 0), alors la deuxième sous-expression est évaluée et constitue le résultat de l'expression conditionnelle. Sinon, c'est la troisième sous-expression qui est évaluée et qui constitue le résultat de l'expression.

Les exemples suivants devraient permettre de mieux comprendre la pre-incrémentation, la post-incrémentation et le concept des expressions en général :

    <?php
    function double($i)
    {
        return $i * 2;
    }

    $b = $a = 5;        /* Assigne la valeur 5 aux variables $a et $b  */
    $c = $a++;          /* Post-incrémentation de la variable $a et assignation de
                           la valeur à la variable $c */
    print "a = {$a}; b = {$b}; c = {$c}" . PHP_EOL;

    $e = $d = ++$b;     /* Pre-incrémentation, et assignation de la valeur aux
                           variables $d et $e  */
    print "b = {$b}; d = {$d}; e = {$e}" . PHP_EOL;

    /* à ce niveau, les variables $d et $e sont égales à 6 */

    $f = double($d++);  /* assignation du double de la valeur de $d à la variable $f ($f vaut 12),
                           puis incrémentation de la valeur de $d  */
    print "d = {$d}; f = {$f}" . PHP_EOL;

    $g = double(++$e);  /* assigne deux fois la valeur de $e après
                           incrémentation, 2*7 = 14 à $g */
    print "e = {$e}; g = {$g}" . PHP_EOL;

    $h = $g += 10;      /* Tout d'abord, $g est incrémentée de 10, et donc $g vaut 24.
                           Ensuite, la valeur de $g, (24) est assignée à la variable $h,
                           qui vaut donc elle aussi 24. */
    print "g = {$g}; h = {$h}" . PHP_EOL;
    ?>

Au début de ce chapitre, nous avons dit que nous allions décrire les différents types d'instructions, et donc, comme promis, nous allons voir que les expressions peuvent être des instructions. Mais attention, toutes les expressions ne sont pas des instructions. Dans ce cas-là, une instruction est de la forme '`expr ;`', c'est-à-dire, une expression suivie par un point-virgule. Dans `$b = $a = 5;`, `$a = 5` est une expression valide, mais ce n'est pas une instruction en elle-même. `$b = $a = 5;` est une instruction valide.

La dernière chose qui mérite d'être mentionnée est la véritable valeur des expressions. Lors de tests sur une variable, dans une boucle conditionnelle par exemple, il n'est pas nécessaire de savoir quelle est la valeur exacte de l'expression. Seul importe de savoir si le résultat signifie `true` ou `false`. Les constantes `true` et `false` (insensible à la casse) sont les deux valeurs possibles pour un booléen. Lorsque nécessaire, une expression est automatiquement convertie en booléen. Consulter la section sur le transtypage pour plus de détails.

PHP propose une implémentation complète et détaillée des expressions, et la documenter entièrement va au-delà de la portée de ce manuel. Les exemples ci-dessus devraient donner une bonne idée de ce qu'est une expression et comment construire des expressions utiles. Dans tout le reste de ce manuel, nous écrirons expr pour indiquer toute expression PHP valide.

# Les opérateurs

## Sommaire

- Priorité des opérateurs
- Arithmétique
- Incrémentation et décrémentation
- Affectation
- Bitwise
- Comparaison
- Contrôle d'erreur
- Exécution
- Logique
- Chaînes de caractères
- Tableaux
- Type
- Fonctionnels

Un opérateur est quelque chose qui prend une ou plusieurs valeurs (ou expressions, dans le jargon de la programmation) et qui produit une autre valeur (donc la construction elle-même devient une expression).

Les opérateurs peuvent être regroupés en fonction du nombre de valeurs qu'ils acceptent. L'opérateur unaire n'opère que sur une seule valeur, par exemple `!` (l'opérateur de négation) ou `++` (l'opérateur d'incrémentation). Le second type, les opérateurs binaires (comme le très célèbre opérateur mathématique `+` ou `-`) contient la plupart des opérateurs supportés par PHP. Enfin, l'opérateur ternaire, `? :`, qui accepte trois valeurs (on peut aussi l'appeler l'opérateur conditionnel).

Une liste complète des opérateurs se trouve dans la section précédence des opérateurs. Cette section explique aussi la précédence des opérateurs et l'associativité, c'est-à-dire les priorités d'exécution des opérateurs.

Une extension PECL permet de surcharger certains opérateurs pour les objets. Pour plus d'informations, voir la section Surcharge d'opérateurs pour les objets.

## La priorité des opérateurs

La priorité des opérateurs spécifie l'ordre dans lequel les valeurs doivent être analysées. Par exemple, dans l'expression `1 + 5 * 3`, le résultat est `16` et non `18`, car la multiplication ("*") a une priorité supérieure par rapport à l'addition ("+"). Des parenthèses peuvent être utilisées pour forcer la priorité, si nécessaire. Par exemple : `(1 + 5) * 3` donnera `18`.

Lorsque les opérateurs ont une priorité égale, leur association décide la façon dont les opérateurs sont groupés. Par exemple, "-" est une association par la gauche, ainsi `1 - 2 - 3` est groupé comme ceci `(1 - 2) - 3` et sera évalué à `-4`. D'un autre côté, "=" est une association par la droite, ainsi, `$a = $b = $c` est groupé comme ceci `$a = ($b = $c)`.

Les opérateurs, dont la priorité est égale, qui ne sont pas associatifs, ne peuvent pas être utilisés entre eux, par exemple, `1 < 2 > 1` est interdit en PHP. L'expression `1 <= 1 == 1` par contre, est autorisée, car l'opérateur `==` a une priorité inférieure à l'opérateur `<=`.

L'associativité a uniquement du sens pour les opérateurs binaires (et ternaires). Les opérateurs unaires sont soit préfixés, soit suffixés ainsi cette notion n'est pas applicable. Par exemple `!!$a` peut uniquement être groupé de la manière suivante `!(!$a)`.

L'utilisation des parenthèses, y compris lorsqu'elles ne sont pas nécessaires, permet de mieux lire le code en effectuant des groupements explicites plutôt qu'imaginer la priorité des opérateurs et leurs associations.

Le tableau qui suit liste les opérateurs par ordre de priorité, avec la priorité la plus élevée en haut. Les opérateurs sur la même ligne ont une priorité équivalente (donc l'associativité décide du groupement).

Priorité des opérateurs
Associativité | Opérateurs | Information additionnelle
--- | --- | ---
(n/a) | `clone` `new` | clone et new
droite | `**` | arithmétique
(n/a) | `+` `-` `++` `--` `~` `(int)` `(float)` `(string)` `(array)` `(object)` `(bool)` `@` | arithmétique (unaire `+` et `-`), incrément/décrément, bit à bit, casting de type et contrôle d'erreur
gauche | `instanceof` | type
(n/a) | `!` | logique
gauche | `*` `/` `%` | arithmétique
gauche | `+` `-` `.` | arithmétique (binaire `+` et `-`), tableau et chaîne de caractères (`.` antérieur à PHP 8.0.0)
gauche | `<<` `>>` | bit à bit
gauche | `.` | chaîne de caractères (à partir de PHP 8.0.0)
gauche | `|>` | pipe
non-associatif | `<` `<=` `>` `>=` | comparaison
non-associatif | `==` `!=` `===` `!==` `<>` `<=>` | comparaison
gauche | `&` | bit à bit et références
gauche | `^` | bit à bit
gauche | `|` | bit à bit
gauche | `&&` | logique
gauche | `||` | logique
droite | `??` | coalescence nulle
non-associatif | `? :` | ternaire (gauche-associatif antérieur à PHP 8.0.0)
droite | `=` `+=` `-=` `*=` `**=` `/=` `.=` `%=` `&=` `|=` `^=` `<<=` `>>=` `??=` | affectation
(n/a) | `yield from` | yield from
(n/a) | `yield` | yield
(n/a) | `print` | print
gauche | `and` | logique
gauche | `xor` | logique
gauche | `or` | logique
(n/a) | `throw` | throw

> Note: Les opérateurs unaires partageant la même ligne que les opérateurs de transtypage (`~`, `@`, et les `+`/`-` unaires) sont prioritaires sur `instanceof`, tandis que `!` l'est moins. Par conséquent, `(int) $x instanceof Foo` est interprété comme `((int) $x) instanceof Foo`, alors que `!$x instanceof Foo` est interprété comme `!($x instanceof Foo)`.

Exemple #1 Associativité

    <?php
    $a = 3 * 3 % 5; // (3 * 3) % 5 = 4
    var_dump($a);

    $a = 1;
    $b = 2;
    $a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
    var_dump($a, $b);
    ?>

L'opérateur ternaire requiert spécifiquement l'utilisation de parenthèses pour lever l'ambiguïté de la priorité.

Exemple #2 Priorité explicite

    <?php
    $a = true ? 0 : (true ? 1 : 2);
    var_dump($a);

    // Ceci n'est plus permis à partir de PHP 8
    // $a = true ? 0 : true ? 1 : 2;
    ?>

La priorité et l'association de l'opérateur ne déterminent que la façon dont les expressions sont groupées ; elles ne spécifient pas l'ordre de l'évaluation. PHP ne spécifie pas (de manière générale) l'ordre dans lequel une expression est évaluée et le code qui suppose un ordre spécifique d'évaluation ne devrait pas exister, car le comportement peut changer entre les différentes versions de PHP ou suivant le code environnant.

Exemple #3 Ordre d'évaluation indéfini

    <?php
    $a = 1;
    echo $a + $a++; // peut afficher 2 ou 3

    $i = 1;
    $array[$i] = $i++; // peut définir l'index 1 ou 2
    ?>

Exemple #4 Priorité de `+`, `-` et `.`

    <?php
    $x = 4;

    // Cette ligne peut entraîner une sortie inattendue :
    echo "x moins un est égal à" . $x-1 . ", en tout cas j'espère\n";

    // la priorité désirée peut être renforcée en utilisant les parenthèses :
    echo "x moins un est égal à" . ($x-1) . ", en tout cas j'espère\n";

    // Ceci n'est pas permis, et lève une TypeError :
    echo (("x moins un est égal à" . $x) - 1) . ", en tout cas j'espère\n";
    ?>

L'exemple ci-dessus va afficher :

    -1, en tout cas j'espère
    -1, en tout cas j'espère
    Fatal error: Uncaught TypeError: Unsupported operand types: string - int

Exemple #5 Avant PHP 8, `+`, `-` et `.` avaient la même priorité

    <?php
    $x = 4;
    // Cette ligne peut entraîner une sortie inattendue :
    echo "x moins un est égal à" . $x-1 . ", en tout cas j'espère\n";

    // parce que c'est évalué comme la ligne suivante (antérieur à PHP 8.0.0) :
    echo (("x moins un est égal à" . $x) - 1) . ", en tout cas j'espère\n";

    // la priorité désirée peut être renforcée en utilisant les parenthèses :
    echo "x moins un est égal à" . ($x-1) . ", en tout cas j'espère\n";

    ?>

L'exemple ci-dessus va afficher :

    -1, en tout cas j'espère
    -1, en tout cas j'espère
    x moins un est égal à 3, en tout cas j'espère

> Note:

> Bien que `=` soit prioritaire sur la plupart des opérateurs, PHP va tout de même exécuter des expressions comme : `if (!$a = foo())`. Dans cette situation, le résultat de `foo()` sera placé dans la variable $a.

> Cela est possible parce que le membre de gauche d'une affectation doit être une variable : l'affectation est donc regroupée avec cette variable plutôt qu'avec l'opérateur préfixe environnant, pourtant plus prioritaire. Il en va de même pour les autres opérateurs préfixes prenant une expression comme opérande, tels que `clone`, les opérateurs de transtypage, `@` et `~` : par exemple, `clone $a = $b` est interprété comme `clone ($a = $b)`, et non `(clone $a) = $b`.

### Historique

Version | Description
--- | ---
8.0.0 | La concaténation de chaînes de caractères (`.`) a désormais une priorité moins élevée que l'addition/soustraction arithmétique (`+` et `-`) et les shifts bit-à-bit gauche/droite (`<<` et `>>`); auparavant ceci avait la même priorité que `+` et `-`, et une priorité plus élevée que `<<` et `>>`.
8.0.0 | L'opérateur ternaire (`? :`) est désormais non associatif ; auparavant, il était gauche-associatif.
7.4.0 | Dépendre de la priorité de la concaténation de chaînes de caractères (`.`) relatif à l'addition/soustraction arithmétique (`+` ou `-`) ou les shifts bit-à-bit gauche/droite (`<<` ou `>>`), c.-à-d. les utiliser ensemble dans une expression sans parenthèse, est obsolète.
7.4.0 | Dépendre de la gauche-associativité de l'opérateur ternaire (`? :`), c.-à-d. l'imbrication de plusieurs opérateurs ternaires qui ne sont pas entre parenthèses, est obsolète.

## Les opérateurs arithmétiques

Les opérateurs arithmétiques fonctionnent comme les opérations élémentaires apprises à l'école.

Opérations élémentaires
Exemple | Nom | Résultat
--- | --- | ---
`+$a` | Identité | Conversion de $a vers int ou float, selon le plus approprié.
`-$a` | Négation | Opposé de $a.
`$a + $b` | Addition | Somme de $a et $b.
`$a - $b` | Soustraction | Différence de $a et $b.
`$a * $b` | Multiplication | Produit de $a et $b.
`$a / $b` | Division | Quotient de $a et $b.
`$a % $b` | Modulo | Reste de $a divisé par $b.
`$a ** $b` | Exponentiation | Résultat de l'élévation de $a à la puissance $b.

L'opérateur de division `/` retourne une valeur float à moins que les deux opérandes ne soient de type int (ou chaînes numériques qui sont converties en int) et que le numérateur soit un multiple du diviseur, auquel cas une valeur entière sera retournée. Pour la division entière, voir intdiv().

Les opérandes du modulo sont convertis en int avant exécution. Pour le modulo sur des nombres décimaux, voir fmod().

Le résultat de l'opération modulo `%` a le même signe que le premier opérande, ainsi le résultat de `$a % $b` aura le signe de $a. Par exemple:

Exemple #1 L'Opérateur Modulo

    <?php

    var_dump(5 % 3);
    var_dump(5 % -3);
    var_dump(-5 % 3);
    var_dump(-5 % -3);

    ?>

L'exemple ci-dessus va afficher :

    int(2)
    int(2)
    int(-2)
    int(-2)

### Voir aussi

- Les fonctions mathématiques

## Opérateurs d'incrémentation et décrémentation

PHP prend en charge les opérateurs de pré- et post-incrémentation et décrémentation. Ces opérateurs unaires permettent d'augmenter ou de diminuer la valeur d'une unité.

Opérateurs d'incrémentation et décrémentation
Exemple | Nom | Résultat
--- | --- | ---
++$a | Pré-incrémente | Incrémente $a de 1, puis retourne $a.
$a++ | Post-incrémente | Retourne $a, puis incrémente $a de 1.
--$a | Pré-décrémente | Décrémente $a de 1, puis retourne $a.
$a-- | Post-décrémente | Retourne $a, puis décrémente $a de 1.

Exemple #1 Exemples d'incrémentation/décrémentation

    <?php
    echo 'Post-incrément:', PHP_EOL;
    $a = 5;
    var_dump($a++);
    var_dump($a);
    echo 'Pré-incrément:', PHP_EOL;
    $a = 5;
    var_dump(++$a);
    var_dump($a);
    echo 'Post-décrément:', PHP_EOL;
    $a = 5;
    var_dump($a--);
    var_dump($a);
    echo 'Pré-décrément:', PHP_EOL;
    $a = 5;
    var_dump(--$a);
    var_dump($a);
    ?>

L'exemple ci-dessus va afficher :

    Post-incrément:
    int(5)
    int(6)
    Pré-incrément:
    int(6)
    int(6)
    Post-décrément:
    int(5)
    int(4)
    Pré-décrément:
    int(4)
    int(4)

Avertissement

Les opérateurs d'incrémentation et de décrémentation n'ont aucun effet sur les valeurs de type bool. Un `E_WARNING` est émis à partir de PHP 8.3.0, car cela convertira implicitement la valeur en int à l'avenir.

L'opérateur de décrémentation n'a aucun effet sur les valeurs de type null. Un `E_WARNING` est émis à partir de PHP 8.3.0, car cela convertira implicitement la valeur en int à l'avenir.

L'opérateur de décrémentation n'a aucun effet sur les chaînes non numériques. Un `E_WARNING` est émis à partir de PHP 8.3.0, car une TypeError sera levée à l'avenir.

> Note:

> Les objets internes qui prennent en charge la surcharge de l'addition et/ou de la soustraction peuvent également être incrémentés et/ou décrémentés. Un tel objet interne est GMP.

### Fonctionnalité d'incrémentation de chaînes PERL

Avertissement

Cette fonctionnalité est obsolète de manière souple à partir de PHP 8.3.0. La fonction str_increment() devrait être utilisée à la place.

Il est possible d'incrémenter une chaîne non numérique dans PHP. La chaîne doit être une chaîne ASCII alphanumérique. Cela incrémente les lettres jusqu'à la lettre suivante, et lorsque la lettre `Z` est atteinte, l'incrément est reporté à la valeur à gauche. Par exemple, `$a = 'Z'; $a++;` transforme $a en `'AA'`.

Exemple #2 Exemple d'incrémentation de chaîne PERL

    <?php
    echo '== Chaînes alphabétiques ==' . PHP_EOL;
    $s = 'W';
    for ($n=0; $n<6; $n++) {
        echo ++$s . PHP_EOL;
    }
    // Les chaînes alphanumériques se comportent différemment
    echo '== Chaînes alphanumériques ==' . PHP_EOL;
    $d = 'A8';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }
    $d = 'A08';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }
    ?>

L'exemple ci-dessus va afficher :

    == Chaînes alphabétiques ==
    X
    Y
    Z
    AA
    AB
    AC
    == Chaînes alphanumériques ==
    A9
    B0
    B1
    B2
    B3
    B4
    A09
    A10
    A11
    A12
    A13
    A14

Avertissement

Si la chaîne alphanumérique peut être interprétée comme une chaîne numérique, elle sera convertie en int ou en float. C'est particulièrement problématique avec les chaînes qui ressemblent à des nombres à virgule flottante écrits en notation exponentielle. La fonction str_increment() ne souffre pas de ces conversions de type implicites.

Exemple #3 Conversion de chaîne alphanumérique en flottant

    <?php
    $s = "5d9";
    var_dump(++$s);
    var_dump(++$s);
    ?>

L'exemple ci-dessus va afficher :

    string(3) "5e0"
    float(6)

Cela est dû au fait que la valeur `"5e0"` est interprétée comme un float et convertie en la valeur `5.0` avant d'être incrémentée.

## Les opérateurs d'affectation

L'opérateur d'affectation le plus simple est le signe "=". Le premier réflexe est de penser que ce signe veut dire "égal à". Ce n'est pas le cas. Il signifie que l'opérande de gauche se voit affecter la valeur de l'expression qui est à droite du signe égal.

La valeur d'une expression d'affectation est la valeur affectée. Par exemple, la valeur de l'expression '`$a = 3`' est la valeur 3. Cela permet d'utiliser des astuces telles que :

Exemple #1 Affectations imbriquées

    <?php
    $a = ($b = 4) + 5;
    // $a est maintenant égal à 9, et $b vaut 4.
    var_dump($a);
    ?>

En plus du simple opérateur d'affectation, il existe des "opérateurs combinés" pour tous les opérateurs arithmétiques, l'union de tableaux et pour les opérateurs sur les chaînes de caractères. Cela permet d'utiliser la valeur d'une variable dans une expression et d'affecter le résultat de cette expression à cette variable. Par exemple :

Exemple #2 Affectations Combinées

    <?php
    $a = 3;
    $a += 5; // affecte la valeur 8 à la variable $a, correspond à l'instruction '$a = $a + 5';
    $b = "Bonjour ";
    $b .= " tout le monde!";  // affecte la valeur "Bonjour tout le monde!" à
                              //  la variable $b
                              //  identique à $b = $b." tout le monde!";

    var_dump($a, $b);
    ?>

On peut noter que l'affectation copie le contenu de la variable originale dans la nouvelle variable (affectation par valeur), ce qui fait que les changements de valeur d'une variable ne modifieront pas la valeur de l'autre. Cela peut se révéler important lors de la copie d'un grand tableau durant une boucle.

Une exception au comportement d'affectation par valeur en PHP est le type object, ceux-ci sont affectés par référence. La copie d'objet doit être explicitement demandée grâce au mot-clé clone.

### Affectation par référence

L'affectation par référence est aussi supportée, au moyen de la syntaxe "$var = &$othervar;". L'affectation par référence signifie que les deux variables pointent vers le même conteneur de donnée, rien n'est copié nulle part.

Exemple #3 Affectation par référence

    <?php
    $a = 3;
    $b = &$a; // $b est une référence à $a

    print "$a\n"; // affiche 3
    print "$b\n"; // affiche 3

    $a = 4; // change $a

    print "$a\n"; // affiche 4
    print "$b\n"; // affiche 4 aussi, car $b est une référence à $a, qui a été
                  // changée
    ?>

L'opérateur new retourne une référence automatiquement, de ce fait, assigner le résultat de new par référence est une erreur.

Exemple #4 Opérateur new par référence

    <?php
    class C {}

    $o = &new C;
    ?>

L'exemple ci-dessus va afficher :

    Parse error: syntax error, unexpected token ";", expecting "("

Plus d'informations sur les références et leurs utilisations possibles peuvent être trouvées dans la section du manuel Les références expliquées.

### Les opérateurs d'affectation arithmétiques

Exemple | Équivalent | Opération
--- | --- | ---
$a += $b | $a = $a + $b | Addition
$a -= $b | $a = $a - $b | Soustraction
$a *= $b | $a = $a * $b | Multiplication
$a /= $b | $a = $a / $b | Division
$a %= $b | $a = $a % $b | Modulo
$a **= $b | $a = $a ** $b | Exponentiation

### Opérateurs d'affectation bits à bits

Exemple | Équivalent | Opération
--- | --- | ---
$a &= $b | $a = $a & $b | Opérateur And
$a |= $b | $a = $a | $b | Opérateur Or
$a ^= $b | $a = $a ^ $b | Opérateur Xor
$a <<= $b | $a = $a << $b | Décalage à gauche
$a >>= $b | $a = $a >> $b | Décalage à droite

### Autres opérateurs d'affectation

Exemple | Équivalent | Opération
--- | --- | ---
$a .= $b | $a = $a . $b | Concaténation d'une chaîne de caractères
$a ??= $b | $a = $a ?? $b | Opérateur de coalescence nul

### Voir aussi

- les opérateurs arithmétiques
- les opérateurs bits à bits
- les opérateurs de coalescence nul

## Opérateurs sur les bits

Les opérateurs sur les bits permettent d'évaluer et de manipuler des bits spécifiques dans un entier.

Les opérateurs sur les bits
Exemple | Nom | Résultat
--- | --- | ---
`$a & $b` | And (Et) | Les bits positionnés à 1 dans $a ET dans $b sont positionnés à 1.
`$a | $b` | Or (Ou) | Les bits positionnés à 1 dans $a OU $b sont positionnés à 1.
`$a ^ $b` | Xor (ou exclusif) | Les bits positionnés à 1 dans $a OU dans $b mais pas dans les deux sont positionnés à 1.
`~ $a` | Not (Non) | Les bits qui sont positionnés à 1 dans $a sont positionnés à 0, et vice-versa.
`$a << $b` | Décalage à gauche | Décale les bits de $a, $b fois sur la gauche (chaque décalage équivaut à une multiplication par 2).
`$a >> $b` | Décalage à droite | Décale les bits de $a, $b fois sur la droite (chaque décalage équivaut à une division par 2).

Le décalage de bits en PHP est arithmétique. Les bits qui sont décalés hors de l'entier sont perdus. Les décalages à gauche font apparaître des zéros à droite, tandis que le bit de signe est décalé à gauche, ce qui signifie que le signe de l'entier n'est pas préservé. Les décalages à droite décalent aussi le bit de signe sur la droite, ce qui signifie que le signe est préservé.

Utiliser des parenthèses pour s'assurer que la précédence voulue est bien appliquée. Par exemple, `$a & $b == true` applique d'abord l'égalité, et ensuite le ET logique, alors que `($a & $b) == true` applique d'abord le ET logique, puis l'égalité.

Si les deux opérandes pour les opérateurs `&`, `|` et `^` sont des chaînes de caractères, alors l'opération sera réalisée sur les valeurs ASCII des caractères et le résultat sera une chaîne de caractères. Dans tous les autres cas, les deux opérandes seront converties en entier et le résultat sera un entier.

Si l'opérande pour l'opérateur `~` est une chaîne de caractères, l'opération sera effectuée sur les caractères ASCII composant la chaîne et le résultat sera une chaîne de caractères. Sinon l'opérande et le résultat seront traités comme des entiers.

Les opérandes et le résultat des opérateurs `<<` et `>>` sont traités comme des entiers.

Le rapport d'erreur de PHP utilise des champs de bits, qui sont une illustration de l'extinction des bits. Pour afficher les erreurs, sauf les notices, les instructions du php.ini sont : `E_ALL & ~E_NOTICE`

         Cela se comprend en comparant avec E_ALL :
         00000000000000000111011111111111
         Puis en prenant la valeur de E_NOTICE...
         00000000000000000000000000001000
         ... et en l'inversant via ~:
         11111111111111111111111111110111
         Finalement, on utilise le ET logique (&) pour lire les bits activés
         dans les deux valeurs :
         00000000000000000111011111110111

Un autre moyen d'arriver à ce résultat est d'utiliser le OU exclusif (`^`), qui cherche les bits qui ne sont activés que dans l'une ou l'autre des valeurs, exclusivement : `E_ALL ^ E_NOTICE`

error_reporting peut aussi être utilisé pour illustrer l'activation de bits. Pour afficher uniquement les erreurs et les erreurs recouvrables, on utilise : `E_ERROR | E_RECOVERABLE_ERROR`

         Cette approche combine E_ERROR
         00000000000000000000000000000001
         et E_RECOVERABLE_ERROR
         00000000000000000001000000000000
         Avec l'opérateur OR (|) pour s'assurer que
         les bits sont activés dans l'une ou l'autre valeur :
         00000000000000000001000000000001

Exemple #1 Opérations sur les bits et les entiers

    <?php
    /*
     * Ignorez cette partie,
     * c'est juste du formatage pour clarifier les résultats
     */

    $format = '(%1$2d = %1$04b) = (%2$2d = %2$04b)'
            . ' %3$s (%4$2d = %4$04b)' . "\n";

    echo <<<EOH
     ---------     ---------  -- ---------
     résultat       valeur        test
     ---------     ---------  -- ---------
    EOH;

    /*
     * Voici les exemples
     */

    $values = array(0, 1, 2, 4, 8);
    $test = 1 + 4;

    echo "\n Bitwise AND \n";
    foreach ($values as $value) {
        $result = $value & $test;
        printf($format, $result, $value, '&', $test);
    }

    echo "\n Bitwise Inclusive OR \n";
    foreach ($values as $value) {
        $result = $value | $test;
        printf($format, $result, $value, '|', $test);
    }

    echo "\n Bitwise Exclusive OR (XOR) \n";
    foreach ($values as $value) {
        $result = $value ^ $test;
        printf($format, $result, $value, '^', $test);
    }
    ?>

L'exemple ci-dessus va afficher :

     ---------     ---------  -- ---------
     résultat       valeur        test
     ---------     ---------  -- ---------
     Bitwise AND
    ( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101)
    ( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101)
    ( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101)
    ( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101)
    ( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101)

     Bitwise Inclusive OR
    ( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101)
    ( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101)
    ( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) | ( 5 = 0101)

     Bitwise Exclusive OR (XOR)
    ( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101)
    ( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101)
    ( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)

Exemple #2 Opération sur les bits et les chaînes

    <?php
    echo 12 ^ 9, PHP_EOL; // Affiche '5'

    echo "12" ^ "9", PHP_EOL; // Affiche le caractère d'effacement (ascii 8)
                     // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

    echo "hallo" ^ "hello", PHP_EOL; // Affiche les valeurs ASCII #0 #4 #0 #0 #0
                            // 'a' ^ 'e' = #4

    echo 2 ^ "3", PHP_EOL; // Affiche 1
                  // 2 ^ ((int) "3") == 1

    echo "2" ^ 3, PHP_EOL; // Affiche 1
                  // ((int) "2") ^ 3 == 1
    ?>

Exemple #3 Décalage de bits sur les entiers

    <?php
    /*
     * Voici quelques exemples
     */

    echo "\n--- Décalages à droite sur des entiers positifs ---\n";

    $val = 4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'copie du bit de signe maintenant à gauche');

    $val = 4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places);

    $val = 4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'des bits sont sortis par la droite');

    $val = 4;
    $places = 4;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'même résultat que ci-dessus : pas de décalage au-delà de 0');

    echo "\n--- Décalages à droite sur des entiers négatifs ---\n";

    $val = -4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'copie du bit de signe maintenant à gauche');

    $val = -4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'des bits sont sortis par la droite');

    $val = -4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'même résultat que ci-dessus : pas de décalage au-delà de -1');

    echo "\n--- Décalages à gauche sur des entiers positifs ---\n";

    $val = 4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'complément de zéros à droite');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 4;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'le bit de signe est sorti');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'des bits sont sortis à gauche');

    echo "\n--- Décalages à gauche sur des entiers négatifs ---\n";

    $val = -4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'complément de zéros à droite');

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'des bits sont sortis à gauche, y compris le bit de signe');

    /*
     * Ignorez cette section
     * Elle contient du code pour le formatage de cet exemple
     */

    function p($res, $val, $op, $places, $note = '') {
        $format = '%0' . (PHP_INT_SIZE * 8) . "b\n";

        printf("Expression : %d = %d %s %d\n", $res, $val, $op, $places);

        echo " Décimal :\n";
        printf("  val=%d\n", $val);
        printf("  res=%d\n", $res);

        echo " Binaire :\n";
        printf('  val=' . $format, $val);
        printf('  res=' . $format, $res);

        if ($note) {
            echo " Note : $note\n";
        }

        echo "\n\n";
    }
    ?>

Résultat de l'exemple ci-dessus sur une machine 32 bits :

    --- Décalages à droite sur des entiers positifs ---
    Expression : 2 = 4 >> 1
     Décimal :
      val=4
      res=2
     Binaire :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000010
     Note : copie du bit de signe maintenant à gauche

    Expression : 1 = 4 >> 2
     Décimal :
      val=4
      res=1
     Binaire :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000001

    Expression : 0 = 4 >> 3
     Décimal :
      val=4
      res=0
     Binaire :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     Note : des bits sont sortis par la droite

    Expression : 0 = 4 >> 4
     Décimal :
      val=4
      res=0
     Binaire :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     Note : même résultat que ci-dessus : pas de décalage au-delà de 0

    --- Décalages à droite sur des entiers négatifs ---
    Expression : -2 = -4 >> 1
     Décimal :
      val=-4
      res=-2
     Binaire :
      val=11111111111111111111111111111100
      res=11111111111111111111111111111110
     Note : copie du bit de signe maintenant à gauche

    Expression : -1 = -4 >> 2
     Décimal :
      val=-4
      res=-1
     Binaire :
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     Note : des bits sont sortis par la droite

    Expression : -1 = -4 >> 3
     Décimal :
      val=-4
      res=-1
     Binaire :
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     Note : même résultat que ci-dessus : pas de décalage au-delà de -1

    --- Décalages à gauche sur des entiers positifs ---
    Expression : 8 = 4 << 1
     Décimal :
      val=4
      res=8
     Binaire :
      val=00000000000000000000000000000100
      res=00000000000000000000000000001000
     Note : complément de zéros à droite

    Expression : 1073741824 = 4 << 28
     Décimal :
      val=4
      res=1073741824
     Binaire :
      val=00000000000000000000000000000100
      res=01000000000000000000000000000000

    Expression : -2147483648 = 4 << 29
     Décimal :
      val=4
      res=-2147483648
     Binaire :
      val=00000000000000000000000000000100
      res=10000000000000000000000000000000
     Note : le bit de signe est sorti

    Expression : 0 = 4 << 30
     Décimal :
      val=4
      res=0
     Binaire :
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     Note : des bits sont sortis à gauche

    --- Décalages à gauche sur des entiers négatifs ---
    Expression : -8 = -4 << 1
     Décimal :
      val=-4
      res=-8
     Binaire :
      val=11111111111111111111111111111100
      res=11111111111111111111111111111000
     Note : complément de zéros à droite

    Expression : -2147483648 = -4 << 29
     Décimal :
      val=-4
      res=-2147483648
     Binaire :
      val=11111111111111111111111111111100
      res=10000000000000000000000000000000

    Expression : 0 = -4 << 30
     Décimal :
      val=-4
      res=0
     Binaire :
      val=11111111111111111111111111111100
      res=00000000000000000000000000000000
     Note : des bits sont sortis à gauche, y compris le bit de signe

Résultat de l'exemple ci-dessus sur une machine 64 bits :

    --- Décalages à droite sur des entiers positifs ---
    Expression : 2 = 4 >> 1
     Décimal :
      val=4
      res=2
     Binaire :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000010
     Note : copie du bit de signe maintenant à gauche

    Expression : 1 = 4 >> 2
     Décimal :
      val=4
      res=1
     Binaire :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000001

    Expression : 0 = 4 >> 3
     Décimal :
      val=4
      res=0
     Binaire :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     Note : des bits sont sortis par la droite

    Expression : 0 = 4 >> 4
     Décimal :
      val=4
      res=0
     Binaire :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     Note : même résultat que ci-dessus : pas de décalage au-delà de 0

    --- Décalages à droite sur des entiers négatifs ---
    Expression : -2 = -4 >> 1
     Décimal :
      val=-4
      res=-2
     Binaire :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111110
     Note : copie du bit de signe maintenant à gauche

    Expression : -1 = -4 >> 2
     Décimal :
      val=-4
      res=-1
     Binaire :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     Note : des bits sont sortis par la droite

    Expression : -1 = -4 >> 3
     Décimal :
      val=-4
      res=-1
     Binaire :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     Note : même résultat que ci-dessus : pas de décalage au-delà de -1

    --- Décalage à gauche sur les entiers positifs ---
    Expression : 8 = 4 << 1
     Décimal :
      val=4
      res=8
     Binaire :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000001000
     Note : complément de zéros à droite

    Expression : 4611686018427387904 = 4 << 60
     Décimal :
      val=4
      res=4611686018427387904
     Binaire :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0100000000000000000000000000000000000000000000000000000000000000

    Expression : -9223372036854775808 = 4 << 61
     Décimal :
      val=4
      res=-9223372036854775808
     Binaire :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=1000000000000000000000000000000000000000000000000000000000000000
     Note : le bit de signe est sorti

    Expression : 0 = 4 << 62
     Décimal :
      val=4
      res=0
     Binaire :
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     Note : des bits sont sortis à gauche

    --- Décalage à gauche sur les entiers négatifs ---
    Expression : -8 = -4 << 1
     Décimal :
      val=-4
      res=-8
     Binaire :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111000
     Note : complément de zéros à droite

    Expression : -9223372036854775808 = -4 << 61
     Décimal :
      val=-4
      res=-9223372036854775808
     Binaire :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1000000000000000000000000000000000000000000000000000000000000000

    Expression : 0 = -4 << 62
     Décimal :
      val=-4
      res=0
     Binaire :
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=0000000000000000000000000000000000000000000000000000000000000000
     Note : des bits sont sortis à gauche, y compris le bit de signe

Avertissement

Utiliser les fonctions de l'extension gmp pour les manipulations sur les bits, lorsque les entiers dépassent `PHP_INT_MAX`.

### Voir aussi

- pack()
- unpack()
- gmp_and()
- gmp_or()
- gmp_xor()
- gmp_testbit()
- gmp_clrbit()

## Opérateurs de comparaison

Les opérateurs de comparaison, comme leur nom l'indique, permettent de comparer deux valeurs. Il est également recommandé de consulter les tables de comparaisons de types, car elles montrent des exemples de beaucoup de types de comparaisons.

Opérateurs de comparaison
Exemple | Nom | Résultat
--- | --- | ---
$a == $b | Égal | `true` si $a est égal à $b après le transtypage.
$a === $b | Identique | `true` si $a est égal à $b et qu'ils sont de même type.
$a != $b | Différent | `true` si $a est différent de $b après le transtypage.
$a <> $b | Différent | `true` si $a est différent de $b après le transtypage.
$a !== $b | Différent | `true` si $a est différent de $b ou bien s'ils ne sont pas du même type.
$a < $b | Plus petit que | `true` si $a est strictement plus petit que $b.
$a > $b | Plus grand que | `true` si $a est strictement plus grand que $b.
$a <= $b | Inférieur ou égal | `true` si $a est plus petit ou égal à $b.
$a >= $b | Supérieur ou égal | `true` si $a est plus grand ou égal à $b.
$a <=> $b | Combiné | Un entier inférieur, égal ou supérieur à zéro lorsque $a est inférieur, égal, ou supérieur à $b respectivement.

Si les deux opérandes sont des chaînes numériques, ou si un opérande est un nombre et l'autre est une chaîne numérique, alors la comparaison sera effectuée numériquement. Ces règles s'appliquent également à l'instruction switch. La conversion de type n'intervient pas lorsque la comparaison est `===` ou `!==` vu que ceci engendre aussi bien une comparaison de type que de valeur.

Avertissement

Antérieur à PHP 8.0.0, si une string est comparée à un nombre ou à une chaîne numérique alors la string sera convertie en un nombre avant d'effectuer la comparaison. Ceci peut mener à des résultats surprenants comme le montre l'exemple suivant :

    <?php
    var_dump(0 == "a");
    var_dump("1" == "01");
    var_dump("10" == "1e1");
    var_dump(100 == "1e2");

    switch ("a") {
    case 0:
        echo "0";
        break;
    case "a":
        echo "a";
        break;
    }
    ?>

Résultat de l'exemple ci-dessus en PHP 7 :

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    0

Résultat de l'exemple ci-dessus en PHP 8 :

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    a

Exemple #1 Opérateurs de comparaison

    <?php
    // Entiers
    echo 1 <=> 1, ' '; // 0
    echo 1 <=> 2, ' '; // -1
    echo 2 <=> 1, ' '; // 1

    // Nombres flottants
    echo 1.5 <=> 1.5, ' '; // 0
    echo 1.5 <=> 2.5, ' '; // -1
    echo 2.5 <=> 1.5, ' '; // 1

    // Chaînes de caractères
    echo "a" <=> "a", ' '; // 0
    echo "a" <=> "b", ' '; // -1
    echo "b" <=> "a", ' '; // 1

    echo "a" <=> "aa", ' '; // -1
    echo "zz" <=> "aa", ' '; // 1

    // Tableaux
    echo [] <=> [], ' '; // 0
    echo [1, 2, 3] <=> [1, 2, 3], ' '; // 0
    echo [1, 2, 3] <=> [], ' '; // 1
    echo [1, 2, 3] <=> [1, 2, 1], ' '; // 1
    echo [1, 2, 3] <=> [1, 2, 4], ' '; // -1

    // Objets
    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 0

    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "c"];
    echo $a <=> $b, ' '; // -1

    $a = (object) ["a" => "c"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 1

    // non seulement les valeurs sont comparées; les clés doivent correspondre
    $a = (object) ["a" => "b"];
    $b = (object) ["b" => "b"];
    echo $a <=> $b, ' '; // 1

    ?>

Pour les différents types, la comparaison est faite en suivant la table suivante (dans l'ordre).

Comparaison avec plusieurs types
Type de l'opérande 1 | Type de l'opérande 2 | Résultat
--- | --- | ---
null ou string | string | Convertit `null` en "", comparaison numérique ou lexicale
bool ou null | N'importe quoi | Convertit les deux côtés en bool, `false` < `true`
object | object | Les classes internes peuvent définir leur propre méthode de comparaison ; différentes classes sont incomparables ; entre objets de même classe voir Comparaison d'objet
chaîne de caractères, resource, entier ou nombre décimal | chaîne de caractères, resource, entier ou nombre décimal | Transforme les chaînes de caractères et les ressources en nombres
array | array | Le tableau avec le moins de membres est plus petit, si la clé de l'opérande 1 n'est pas trouvée dans l'opérande 2, alors les tableaux sont incomparables, sinon la comparaison se fait valeur par valeur (voir l'exemple suivant)
object | N'importe quoi | L'object est toujours plus grand
array | N'importe quoi | Le array est toujours plus grand

Exemple #2 Comparaison Booléen/null

    <?php
    // Booléen et null sont toujours comparés comme des booléens
    var_dump(1 == TRUE);  // TRUE - identique à (bool) 1 == TRUE
    var_dump(0 == FALSE); // TRUE - identique à (bool) 0 == FALSE
    var_dump(100 < TRUE); // FALSE - identique à (bool) 100 < TRUE
    var_dump(-10 < FALSE);// FALSE - identique à (bool) -10 < FALSE
    var_dump(min(-100, -10, NULL, 10, 100)); // NULL - (bool) NULL < (bool) -100 est identique à FALSE < TRUE
    ?>

Exemple #3 Transcription des comparaisons standards des tableaux

    <?php
    // Les tableaux sont comparés comme ceci avec les opérateurs standards de comparaison et l'opérateur combiné
    function standard_array_compare($op1, $op2)
    {
       if (count($op1) < count($op2)) {
          return -1; // $op1 < $op2
       } elseif (count($op1) > count($op2)) {
          return 1; // $op1 > $op2
       }
       foreach ($op1 as $key => $val) {
          if (!array_key_exists($key, $op2)) {
             return 1;
          } elseif ($val < $op2[$key]) {
             return -1;
          } elseif ($val > $op2[$key]) {
             return 1;
          }
       }
       return 0; // $op1 == $op2
    }
    ?>

Avertissement

# Comparaison de nombre à virgule flottante

À cause de la façon dont les nombres à virgule flottante sont représentés en interne, il est déconseillé de tester l'égalité entre deux nombres de type float.

Voir la documentation de float pour plus d'informations.

> Note: Il est important d'être conscient que la manipulation des types n'est pas toujours évidente lors de la comparaison de valeurs de différents types, en particulier comparant des entiers à des booléens ou des entiers à des chaîne de caractèress. Il est par conséquent généralement recommandé d'utiliser les opérateurs de comparaison `===` et `!==` au lieu de `==` et `!=` dans la plupart des cas.

### Valeurs incomparables

Tandis que les comparaisons d'identité (`===` et `!==`) peuvent être appliquées à des valeurs arbitraires, les autres opérateurs de comparaisons devraient seulement être appliqués à des valeurs comparables. Le résultat de la comparaison des valeurs incomparables est indéfini, et ne devrait pas être utilisé.

### Voir aussi

- strcasecmp()
- strcmp()
- opérateur de tableaux
- Types

### L'opérateur ternaire

Un autre opérateur conditionnel est l'opérateur ternaire ("?:").

Exemple #4 Affectation d'une valeur par défaut

    <?php
    // Exemple d'utilisation pour l'opérateur ternaire
    $action = (empty($_POST['action'])) ? 'default' : $_POST['action'];

    // La ligne ci-dessus est identique à la condition suivante :
    if (empty($_POST['action'])) {
       $action = 'default';
    } else {
       $action = $_POST['action'];
    }
    ?>

L'expression `(expr1) ? (expr2) : (expr3)` est évaluée à expr2 si expr1 est évaluée à `true`, et expr3 si expr1 est évaluée à `false`.

Il est possible d'omettre la partie centrale de l'opérateur ternaire. L'expression `expr1 ?: expr3` évalue le résultat de expr1 si expr1 vaut `true`, et expr3 sinon. expr1 n'est évalué qu'une seule fois dans ce cas.

> Note: Il est à noter que l'opérateur ternaire est une expression, et il n'est pas évalué en tant que variable, mais en tant que résultat de l'expression. Il est important de le savoir pour retourner une variable par référence. L'instruction `return $var == 42 ? $a : $b;` dans une fonction retournée par référence ne fonctionnera donc pas et une alerte est émise.

> Note:

> Il est recommandé de ne pas "empiler" les expressions ternaires. Le comportement de PHP lors de l'utilisation de plusieurs opérateurs ternaires qui ne sont pas entre parenthèses en une unique expression est non évident comparé à d'autres langages. En effet, antérieur à PHP 8.0.0, l'expression ternaire était évaluée gauche-associatif, au lieu de droite-associatif comme la plupart des autres langages de programmations. Dépendre de la gauche associativité est obsolète à partir de PHP 7.4.0. À partir de PHP 8.0.0, l'opérateur ternaire est non associatif.

> Exemple #5 Comportement de PHP

>     <?php
>     // À première vue, ce qui suit devrait retourner 'true'
>     echo (true ? 'true' : false ? 't' : 'f');

>     // cependant, l'expression ci-dessus retournera 't' antérieur à PHP 8.0.0
>     // car l'expression ternaire est gauche-associatif

>     // l'expression suivante est une version plus évidente du même code
>     echo ((true ? 'true' : false) ? 't' : 'f');

>     // ici, on peut constater que la première expression est évaluée à 'true',
>     // ce qui fait qu'elle est évaluée à (bool)true, ce qui retourne la branche
>     // 'vraie' de la seconde expression ternaire.
>     ?>

> Note:

> La combinaison de ternaire court (`?:`), cependant, est stable et se comporte de manière raisonnable. Ceci évaluera au premier argument qui évalue à une valeur non-falsy. À noter que des valeurs indéfinies émettront toujours un avertissement.

> Exemple #6 Combinaison de ternaire court

>     <?php
>     echo 0 ?: 1 ?: 2 ?: 3, PHP_EOL; //1
>     echo 0 ?: 0 ?: 2 ?: 3, PHP_EOL; //2
>     echo 0 ?: 0 ?: 0 ?: 3, PHP_EOL; //3
>     ?>

### Opérateur de fusion Null

Un autre opérateur court utile est l'opérateur "??" (ou fusion null).

Exemple #7 Assigner une valeur par défaut

    <?php
    // Exemple d'utilisation pour : Opérateur de fusion Null
    $action = $_POST['action'] ?? 'default';

    // le code ci-dessus est équivalent à cette structure if/else
    if (isset($_POST['action'])) {
        $action = $_POST['action'];
    } else {
        $action = 'default';
    }
    ?>

L'expression `(expr1) ?? (expr2)` retourne expr2 si expr1 est `null`, et expr1 dans les autres cas.

En particulier, cet opérateur n'émet pas de notice ou avertissement si la partie gauche n'existe pas, exactement comme isset(). Ceci est particulièrement utile pour les clés des tableaux.

> Note: Il est à noter que l'opérateur de fusion null est une expression, et qu'il ne s'évalue pas comme une variable, mais comme le résultat d'une expression. Il est important de le savoir pour renvoyer une variable par référence. L'expression `return $foo ?? $bar;` est un retour par référence qui ne fonctionne donc pas et émet un avertissement.

> Note:

> L'opérateur de fusion null a une précédence faible. Ceci signifie qu'en le mélangeant avec d'autres opérateurs (tels que la concaténation de chaînes ou les opérateurs arithmétiques), des parenthèses seront probablement requises.

>     <?php
>     // Émet un avertissement que $name est indéfinie.
>     print 'Mr. ' . $name ?? 'Anonymous';

>     // Affiche "Mr. Anonymous"
>     print 'Mr. ' . ($name ?? 'Anonymous');
>     ?>

> Note:

> Il est à noter que l'opérateur de fusion null permet une imbrication simple :

> Exemple #8 Imbrication de l'opérateur de fusion null

>     <?php

>     $foo = null;
>     $bar = null;
>     $baz = 1;
>     $qux = 2;

>     echo $foo ?? $bar ?? $baz ?? $qux; // affiche 1

>     ?>

## Opérateur de contrôle d'erreur

PHP supporte un opérateur de contrôle d'erreur : l'arobase (`@`). Lorsque cet opérateur est ajouté en préfixe d'une expression PHP, les diagnostics d'erreurs qui peuvent être générés par cette expression seront ignorés.

Si un gestionnaire d'erreur personnalisé est défini avec set_error_handler(), il sera quand même appelé même si le diagnostic a été ignoré.

Avertissement

Avant PHP 8.0.0, le error_reporting() appelé dans le gestionnaire d'erreur personnalisé retournait toujours `0` si l'erreur a été ignorée avec l'opérateur `@`. À partir de PHP 8.0.0, il retourne la valeur de cette expression (bit à bit) : `E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_PARSE`.

Tous les messages d'erreur générés par l'expression sont disponibles dans l'élément `"message"` du tableau retourné par la fonction error_get_last(). Le résultat de la fonction changera à chaque erreur, aussi, il convient de le vérifier souvent.

Exemple #1 Erreur de fichier intentionnelle

    <?php
    $mon_fichier = @file ('non_existent_file') or
        die ("Impossible d'ouvrir le fichier : L'erreur est : '" . error_get_last()['message'] . "'");
    ?>

Exemple #2 L'expression de suppression

    <?php
    // Cela fonctionne avec n'importe quelle expression, pas seulement les fonctions
      $value = @$cache[$key];
    // la ligne ci-dessus n'affichera pas d'alerte si la clé $key du tableau n'existe pas
    ?>

> Note: L'opérateur `@` ne fonctionne qu'avec les expressions. La règle générale est : s'il est possible de prendre la valeur de quelque chose alors, on peut préfixer l'opérateur `@` à celui-ci. Par exemple, il peut être préfixé devant les variables, appels de fonctions, certains appels aux constructions de langages (e.g. include), etc. Il ne peut pas être préfixé devant les définitions de fonctions ou de classes ou structures conditionnelles telles que `if` et `foreach`, etc.

Avertissement

Avant PHP 8.0.0, il était possible pour l'opérateur `@` de désactiver les erreurs critiques qui terminaient l'exécution du script. Par exemple, préfixer `@` à un appel d'une fonction qui n'existe pas, en étant indisponible ou mal orthographiée, entraînait l'arrêt du script sans aucune indication de la raison.

### Voir aussi

- error_reporting()
- Gestion d'Erreur et fonction de Logging

## Opérateur d'exécution

PHP supporte un opérateur d'exécution : guillemets obliques (````). Il est à noter qu'il ne s'agit pas de guillemets simples. PHP essaie d'exécuter le contenu de ces guillemets obliques comme une commande shell. Le résultat sera retourné (c'est-à-dire : il ne sera pas simplement envoyé à la sortie standard, il peut être affecté à une variable). Utiliser les guillemets obliques revient à utiliser la fonction shell_exec().

Exemple #1 Opérateur backtick

    <?php
    $output = `ls -al`;
    echo "<pre>$output</pre>";
    ?>

> Note:

> Cet opérateur est désactivé lorsque la fonction shell_exec() est désactivée.

> Note:

> Contrairement à d'autres langages, les guillemets obliques n'ont pas de signification spéciale dans une chaîne entourée de guillemets doubles.

### Historique

Version | Description
--- | ---
8.5.0 | L’opérateur backtick utilisé comme alias de shell_exec() a été déprécié.

### Voir aussi

- Les fonctions d'exécution système
- popen()
- proc_open()
- Utiliser PHP depuis la ligne de commande

## Les opérateurs logiques

Les opérateurs logiques
Exemple | Nom | Résultat
--- | --- | ---
$a and $b | And (Et) | `true` si $a ET $b valent `true`.
$a or $b | Or (Ou) | `true` si $a OU $b est `true`.
$a xor $b | XOR | `true` si $a OU $b est `true`, mais pas les deux en même temps.
! $a | Not (Non) | `true` si $a n'est pas `true`.
$a && $b | And (Et) | `true` si $a ET $b sont `true`.
$a || $b | Or (Ou) | `true` si $a OU $b est `true`.

La raison pour laquelle il existe deux types de "ET" et de "OU" est qu'ils ont des priorités différentes. Voir le paragraphe précédence d'opérateurs.

Exemple #1 Illustration des opérateurs logiques

    <?php

    // --------------------
    // foo() ne sera jamais appelée, car ces opérateurs sont en court-circuit

    $a = (false && foo());
    $b = (true || foo());
    $c = (false and foo());
    $d = (true or foo());

    // --------------------
    // "||" a une précédence supérieure à "or"

    // Le résultat de l'expression (false || true) est affecté à $e
    // Agit comme : ($e = (false || true))
    $e = false || true;

    // La constante false est affectée à $f avant que l'opération "or" apparaisse
    // Agit comme : (($f = false) or true)
    $f = false or true;

    var_dump($e, $f);

    // --------------------
    // "&&" a une précédence supérieure à "and"

    // Le résultat de l'expression (true && false) est affecté à $g
    // Agit comme : ($g = (true && false))
    $g = true && false;

    // La constante true est affectée à $h avant que l'opération "and" apparaisse
    // Agit comme : (($h = true) and false)
    $h = true and false;

    var_dump($g, $h);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    bool(true)
    bool(false)
    bool(false)
    bool(true)

## Opérateurs de chaînes de caractères

Il y a deux opérateurs de chaînes de caractères string. Le premier est l'opérateur de concaténation ('.'), qui retourne la concaténation de ses deux arguments. Le second est l'opérateur d'affectation concaténant (`.=`). Voir opérateurs d'affectation pour plus de détails.

Exemple #1 Concaténation de chaînes

    <?php
    $a = "Hello ";
    $b = $a . "World!"; // $b contient désormais "Hello World!"
    var_dump($b);

    $a = "Hello ";
    $a .= "World!";     // $a contient désormais "Hello World!"
    var_dump($a);
    ?>

### Voir aussi

- Le type string
- Les fonctions de chaînes de caractères

## Opérateurs de tableaux

Opérateurs de tableaux
Exemple | Nom | Résultat
--- | --- | ---
$a + $b | Union | Union de $a et $b.
$a == $b | Égalité | `true` si $a et $b contiennent les mêmes paires clés/valeurs.
$a === $b | Identique | `true` si $a et $b contiennent les mêmes paires clés/valeurs dans le même ordre et du même type.
$a != $b | Inégalité | `true` si $a n'est pas égal à $b.
$a <> $b | Inégalité | `true` si $a n'est pas égal à $b.
$a !== $b | Non-identique | `true` si $a n'est pas identique à $b.

L'opérateur `+` retourne le tableau de gauche auquel sont ajoutés les éléments du tableau de droite. Pour les clés présentes dans les 2 tableaux, les éléments du tableau de gauche seront utilisés alors que les éléments correspondants dans le tableau de droite seront ignorés.

Exemple #1 L'opérateur d'ajout à un tableau

    <?php
    $a = array("a" => "pomme", "b" => "banane");
    $b = array("a" =>"poire", "b" => "fraise", "c" => "cerise");

    $c = $a + $b; // Union de $a et $b
    echo "Union de \$a et \$b : \n";
    var_dump($c);

    $c = $b + $a; // Union de $b et $a
    echo "Union de \$b et \$a : \n";
    var_dump($c);

    $a += $b; // Union de $a += $b est $a et $b
    echo "Union de \$a += \$b: \n";
    var_dump($a);
    ?>

L'exemple ci-dessus va afficher :

    Union de $a et $b :
    array(3) {
      ["a"]=>
      string(5) "pomme"
      ["b"]=>
      string(6) "banane"
      ["c"]=>
      string(6) "cerise"
    }
    Union de $b et $a :
    array(3) {
      ["a"]=>
      string(5) "poire"
      ["b"]=>
      string(6) "fraise"
      ["c"]=>
      string(6) "cerise"
    }
    Union de $a += $b:
    array(3) {
      ["a"]=>
      string(5) "pomme"
      ["b"]=>
      string(6) "banane"
      ["c"]=>
      string(6) "cerise"
    }

Les éléments d'un tableau sont égaux en termes de comparaison s'ils ont la même clé et la même valeur.

Exemple #2 Comparer des tableaux

    <?php
    $a = array("pomme", "banane");
    $b = array(1 => "banane", "0" => "pomme");

    var_dump($a == $b); // bool(true)
    var_dump($a === $b); // bool(false)
    ?>

### Voir aussi

- Le type array
- Les Fonctions de Tableaux

## Opérateurs de types

`instanceof` est utilisé pour déterminer si une variable PHP est un objet instancié d'une certaine classe :

Exemple #1 Utilisation de `instanceof` avec des classes

    <?php
    class MaClasse
    {
    }
    class PasMaClasse
    {
    }
    $a = new MaClasse;

    var_dump($a instanceof MaClasse);
    var_dump($a instanceof PasMaClasse);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)

`instanceof` peut également être utilisé pour déterminer si une variable est un objet instancié d'une classe qui hérite d'une classe parente :

Exemple #2 Utilisation de `instanceof` avec des classes héritées

    <?php
    class ParentClass
    {
    }
    class MyClass extends ParentClass
    {
    }
    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof ParentClass);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)

Pour vérifier si un objet n'est pas une instance d'une classe, l'opérateur logique `not` peut être utilisé.

Exemple #3 Utilisation de `instanceof` pour vérifier que l'objet n'est pas une instance de la classe

    <?php
    class MyClass
    {
    }
    $a = new MyClass;
    var_dump(!($a instanceof stdClass));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

Et finalement, `instanceof` peut être utilisé pour déterminer si une variable est un objet instancié d'une classe qui implémente une interface :

Exemple #4 Utilisation de `instanceof` pour une interface

    <?php
    interface MyInterface
    {
    }
    class MyClass implements MyInterface
    {
    }
    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof MyInterface);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)

Bien que `instanceof` soit habituellement utilisé avec un nom de classe littéral, il peut également être utilisé avec un autre objet ou une variable de type chaîne de caractères :

Exemple #5 Utilisation de `instanceof` avec d'autres variables

    <?php
    interface MyInterface
    {
    }
    class MyClass implements MyInterface
    {
    }
    $a = new MyClass;
    $b = new MyClass;
    $c = 'MyClass';
    $d = 'NotMyClass';
    var_dump($a instanceof $b); // $b est un objet de la classe MyClass
    var_dump($a instanceof $c); // $c est une chaîne 'MyClass'
    var_dump($a instanceof $d); // $d est une chaîne 'NotMyClass'
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)

instanceof ne lance aucune erreur si la variable testée n'est pas un objet, il retournera simplement `false`. Cependant, les constantes n'étaient pas autorisées antérieurement à PHP 7.3.0.

Exemple #6 Utilisation de `instanceof` pour tester d'autres variables

    <?php
    $a = 1;
    $b = NULL;
    $c = fopen('/tmp/', 'r');
    var_dump($a instanceof stdClass); // $a est un entier
    var_dump($b instanceof stdClass); // $b vaut NULL
    var_dump($c instanceof stdClass); // $c est une ressource
    var_dump(FALSE instanceof stdClass);
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(false)
    bool(false)
    PHP Fatal error:  instanceof expects an object instance, constant given

À partir de PHP 7.3.0, les constantes sont autorisées sur le côté gauche de l'opérateur `instanceof`.

Exemple #7 Utilisation de `instanceof` pour tester des constantes

    <?php
    var_dump(FALSE instanceof stdClass);
    ?>

Résultat de l'exemple ci-dessus en PHP 7.3 :

    bool(false)

À partir de PHP 8.0.0, `instanceof` peut désormais être utilisé avec des expressions arbitraires. L'expression doit être entre parenthèses et produire une string.

Exemple #8 Utilisation de `instanceof` avec une expression arbitraire

    <?php

    class ClassA extends \stdClass {}
    class ClassB extends \stdClass {}
    class ClassC extends ClassB {}
    class ClassD extends ClassA {}

    function getSomeClass(): string
    {
        return ClassA::class;
    }

    var_dump(new ClassA instanceof ('std' . 'Class'));
    var_dump(new ClassB instanceof ('Class' . 'B'));
    var_dump(new ClassC instanceof ('Class' . 'A'));
    var_dump(new ClassD instanceof (getSomeClass()));
    ?>

Résultat de l'exemple ci-dessus en PHP 8 :

    bool(true)
    bool(true)
    bool(false)
    bool(true)

L'opérateur `instanceof` a une variante fonctionnelle avec la fonction is_a().

### Voir aussi

- get_class()
- is_a()

## Opérateurs fonctionnels

PHP 8.5 et versions ultérieures supportent un opérateur qui fonctionne directement sur les callables. L'opérateur `|>`, ou « pipe », accepte un callable à un seul paramètre à droite et lui transmet la valeur de gauche, le résultat étant la valeur renvoyée par le callable. Le callable de droite peut être n'importe quel callable PHP valide : une Closure, un callable de première classe, un objet qui implémente __invoke(), etc.

Cela signifie que les deux lignes suivantes sont logiquement équivalentes.

Exemple #1 En utilisant `|>`

    <?php
    $result = "Hello World" |> strlen(...);
    echo $result, PHP_EOL;

    $result = strlen("Hello World");
    echo $result, PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    11
    11

Pour un seul appel, cela n'est pas particulièrement utile. Cela devient utile lorsque plusieurs appels sont enchaînés. Autrement dit, les deux fragments de code suivants sont logiquement équivalents :

Exemple #2 Enchaînement d'appels |>

    <?php
    $result = "PHP Rocks"
        |> htmlentities(...)
        |> str_split(...)
        |> (fn($x) => array_map(strtoupper(...), $x))
        |> (fn($x) => array_filter($x, fn($v) => $v != 'O'))
    ;
    print_r($result);

    $temp = "PHP Rocks";
    $temp = htmlentities($temp);
    $temp = str_split($temp);
    $temp = array_map(strtoupper(...), $temp);
    $temp = array_filter($temp, fn($v) => $v != 'O');
    $result = $temp;
    print_r($result);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )
    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )

La partie gauche de l'opérateur de pipeline peut être n'importe quelle valeur ou expression. La partie droite peut être n'importe quelle callable PHP valide acceptant un seul paramètre, ou toute expression qui s'évalue à un tel callable. Les fonctions avec plus d'un paramètre obligatoire ne sont pas autorisées et échoueront comme si la fonction était appelée normalement avec des arguments insuffisants. Les fonctions qui prennent une variable par référence ne sont pas autorisées. Si la partie droite ne s'évalue pas à un callable valide, une Error sera levée.

> Note:

> À noter que, pour éviter toute ambiguïté syntaxique, les fonctions fléchées DOIVENT être placées entre parenthèses lorsqu'elles sont utilisées avec un opérateur de pipeline, comme dans les exemples ci-dessus. Ne pas le faire entraînera une erreur fatale.

### Voir aussi

- Closure

# Les structures de contrôle

## Sommaire

- Introduction
- if
- else
- elseif/else if
- Syntaxe alternative
- while
- do-while
- for
- foreach
- break
- continue
- switch
- match
- declare
- return
- require
- include
- require_once
- include_once
- goto

## Introduction

Tous les scripts PHP sont une suite d'instructions. Une instruction peut être une assignation, un appel de fonction, une boucle, une instruction conditionnelle ou bien une instruction qui ne fait rien (une instruction vide). Une instruction se termine habituellement par un point-virgule ("`;`"). De plus, plusieurs instructions peuvent être regroupées en bloc, délimité par des accolades ("`{}`"). Un bloc est considéré comme une instruction. Les différents types d'instructions sont décrits dans ce chapitre.

### Voir aussi

Les éléments suivants sont considérés comme des structures de contrôle même s'ils sont référencés en tant que fonctions dans la documentation.

- list()
- array()
- echo
- eval()
- print

## if

(PHP 4, PHP 5, PHP 7, PHP 8)

L'instruction `if` est une des plus importantes instructions de tous les langages, PHP inclus. Elle permet l'exécution conditionnelle d'une partie de code. Les fonctionnalités de l'instruction `if` sont les mêmes en PHP qu'en C :

    if (expression)
      commandes

Comme nous l'avons vu dans le paragraphe consacré aux expressions, expression est convertie en sa valeur booléenne. Si l'expression vaut `true`, PHP exécutera l'instruction et si elle vaut `false`, l'instruction sera ignorée. Plus de détails sur les valeurs qui valent `false` sont disponibles dans la section Conversion en booléen.

L'exemple suivant affiche la phrase a est plus grand que b si $a est plus grand que $b :

    <?php
    if ($a > $b)
      echo "a est plus grand que b";
    ?>

Souvent, il est nécessaire que plusieurs instructions soient exécutées après un branchement conditionnel. Bien évidemment, il n'est pas obligatoire de répéter l'instruction conditionnelle `if` autant de fois qu'il y a d'instructions à exécuter. À la place, il est possible de rassembler toutes les instructions dans un bloc. L'exemple suivant affiche a est plus grand que b, si $a est plus grand que $b, puis assigne la valeur de $a à la variable $b :

    <?php
    if ($a > $b) {
      echo "a est plus grand que b";
      $b = $a;
    }
    ?>

Il est possible d'imbriquer indéfiniment des instructions `if` dans d'autres instructions `if`, ce qui permet une grande flexibilité dans l'exécution d'une partie de code suivant un grand nombre de conditions.

## else

(PHP 4, PHP 5, PHP 7, PHP 8)

Souvent, il est nécessaire d'exécuter une instruction si une condition est remplie et une autre instruction si cette condition n'est pas remplie. C'est à cela que sert `else`. `else` fonctionne après un `if` et exécute les instructions correspondantes au cas où l'expression du `if` est `false`. Dans l'exemple suivant, ce bout de code affiche a est plus grand que b si la variable $a est plus grande que la variable $b, et a n'est pas plus grand que b sinon :

    <?php
    if ($a > $b) {
      echo "a est plus grand que b";
    } else {
      echo "a n'est pas plus grand que b";
    }
    ?>

Les instructions après le `else` ne sont exécutées que si l'expression du `if` est `false`, et s'il existe des expressions `elseif` - uniquement si elles sont également évaluées à `false` (voir elseif).

> Note: Dangling else

> Dans le cas d'instructions `if`-`else` imbriquées, un `else` est toujours associé avec le `if` le plus proche.

>     <?php
>     $a = false;
>     $b = true;
>     if ($a)
>         if ($b)
>             echo "b";
>     else
>         echo "c";
>     ?>

> Malgré l'indentation (qui n'a pas d'importance en PHP), le `else` est associé avec le `if ($b)`, ainsi cet exemple ne produit pas de sortie. Bien que s'appuyer sur ce comportement soit valide, il est recommandé de l'éviter en utilisant des accolades pour résoudre toute ambiguïté possible.

## elseif/else if

(PHP 4, PHP 5, PHP 7, PHP 8)

`elseif`, comme son nom l'indique, est une combinaison de `if` et de `else`. Comme l'expression `else`, il permet d'exécuter une instruction après un `if` dans le cas où le "premier" if est évalué comme `false`. Mais, à la différence de l'expression `else`, il n'exécutera l'instruction que si l'expression conditionnelle `elseif` est évaluée comme `true`. L'exemple suivant affichera a est plus grand que b, a est égal à b ou a est plus petit que b :

    <?php
    if ($a > $b) {
        echo "a est plus grand que b";
    } elseif ($a == $b) {
        echo "a est égal à b";
    } else {
        echo "a est plus petit que b";
    }
    ?>

Il est possible d'avoir plusieurs `elseif` qui se suivent les uns après les autres, après un `if` initial. Le premier `elseif` qui sera évalué à `true` sera exécuté. En PHP, il est possible d'écrire `else if` en deux mots et son comportement sera identique à celui de `elseif` (en un seul mot). La sémantique des deux expressions est légèrement différente (tout comme en C), mais au bout du compte, le résultat sera exactement le même.

L'expression `elseif` est exécutée seulement si le `if` précédent et tout autre `elseif` précédent sont évalués comme `false`, et que le `elseif` est évalué à `true`.

> Note: À noter que `elseif` et `else if` sont traités de la même façon seulement quand des accolades sont utilisées, comme dans l'exemple ci-dessus. Lors de l'utilisation de ":" pour définir les conditions `if`/`elseif`, l'utilisation de `elseif` en un seul mot devient nécessaire. PHP échouera avec une erreur d'analyse si `else if` est utilisé.

    <?php

    /* Mauvaise méthode : */
    if ($a > $b):
        echo $a." est plus grand que ".$b;
    else if ($a == $b): // ne compilera pas
        echo "La ligne ci-dessus provoque une erreur d'interprétation";
    endif;

    <?php

    /* Bonne méthode : */
    if ($a > $b):
        echo $a." est plus grand que ".$b;
    elseif ($a == $b): // Les deux mots sont collés
        echo $a." égal ".$b;
    else:
        echo $a." n'est ni plus grand ni égal à ".$b;
    endif;

    ?>

## Syntaxe alternative

(PHP 4, PHP 5, PHP 7, PHP 8)

PHP propose une autre manière de rassembler des instructions à l'intérieur d'un bloc, pour les structures de contrôle `if`, `while`, `for`, `foreach` et `switch`. Dans chaque cas, le principe est de remplacer l'accolade d'ouverture par deux points (:) et l'accolade de fermeture par, respectivement, `endif;`, `endwhile;`, `endfor;`, `endforeach;`, ou `endswitch;`.

    <?php if ($a == 5): ?>
    A égal 5
    <?php endif; ?>

Dans l'exemple ci-dessus, le bloc HTML "A égal 5" est inclus à l'intérieur d'un `if` en utilisant cette nouvelle syntaxe. Ce code HTML ne sera affiché que si la variable $a est égale à 5.

Cette autre syntaxe fonctionne aussi avec le `else` et `elseif`. L'exemple suivant montre une structure avec un `if`, un `elseif` et un `else` utilisant cette autre syntaxe :

    <?php
    if ($a == 5):
        echo "a égale 5";
        echo "...";
    elseif ($a == 6):
        echo "a égale 6";
        echo "!!!";
    else:
        echo "a ne vaut ni 5 ni 6";
    endif;
    ?>

> Note:

> Il n'est pas possible d'utiliser différentes syntaxes dans le même bloc de contrôle.

Avertissement

Tout affichage (y compris d'espaces) entre une structure `switch` et le premier `case` va produire une erreur de syntaxe. Par exemple, ceci n'est pas valide :

    <?php switch ($foo): ?>
        <?php case 1: ?>
        // ...
    <?php endswitch; ?>

Alors que ceci est valide, vu que la dernière nouvelle ligne après la structure `switch` est considérée comme faisant partie de la balise de fin `?>` et donc, rien n'est affiché entre `switch` et `case` :

    <?php switch ($foo): ?>
    <?php case 1: ?>
        ...
    <?php endswitch; ?>

Voir aussi while, for, et if pour d'autres exemples.

## while

(PHP 4, PHP 5, PHP 7, PHP 8)

La boucle `while` est le moyen le plus simple d'implémenter une boucle en PHP. Cette boucle se comporte de la même manière qu'en C. L'exemple le plus simple d'une boucle `while` est le suivant :

    while (expression)
        commandes

La signification d'une boucle `while` est très simple. PHP exécute l'instruction tant que l'expression de la boucle `while` est évaluée comme `true`. La valeur de l'expression est vérifiée à chaque début de boucle, et, si la valeur change durant l'exécution de l'instruction, l'exécution ne s'arrêtera qu'à la fin de l'itération (chaque fois que PHP exécute l'instruction, on appelle cela une itération). Si l'expression du `while` est `false` avant la première itération, l'instruction ne sera jamais exécutée.

Comme avec le `if`, il est possible de regrouper plusieurs instructions dans la même boucle `while` en les regroupant à l'intérieur d'accolades ou en utilisant la syntaxe suivante :

    while (expression):
        commandes
        ...
    endwhile;

Les exemples suivants sont identiques et affichent tous les nombres de 1 jusqu'à 10 :

    <?php
    /* exemple 1 */

    $i = 1;
    while ($i <= 10) {
        echo $i++;  /* La valeur affichée est $i avant l'incrémentation
                       (post-incrémentation)  */
    }

    /* exemple 2 */

    $i = 1;
    while ($i <= 10):
        echo $i;
        $i++;
    endwhile;
    ?>

## do-while

(PHP 4, PHP 5, PHP 7, PHP 8)

Les boucles `do-while` ressemblent beaucoup aux boucles `while`, mais l'expression est testée à la fin de chaque itération plutôt qu'au début. La principale différence par rapport à la boucle `while` est que la première itération de la boucle `do-while` est toujours exécutée (l'expression n'est testée qu'à la fin de l'itération), ce qui n'est pas le cas lors de l'utilisation d'une boucle `while` (la condition est vérifiée dès le début de chaque itération, et si elle s'avère `false` dès le début, la boucle sera immédiatement arrêtée).

Il n'y a qu'une syntaxe possible pour les boucles `do-while` :

    <?php
    $i = 0;
    do {
        echo $i;
    } while ($i > 0);
    ?>

La boucle ci-dessus ne va être exécutée qu'une seule fois, car lorsque l'expression est évaluée, elle vaut `false` (car la variable $i n'est pas plus grande que 0) et l'exécution de la boucle s'arrête.

Les utilisateurs familiers du C sont habitués à une utilisation différente des boucles `do-while` , qui permet de stopper l'exécution de la boucle au milieu des instructions, en encapsulant dans un `do-while`(0) l'instruction `break`. Le code suivant montre une utilisation possible :

    <?php
    do {
        if ($i < 5) {
            echo "i n'est pas suffisamment grand";
            break;
        }
        $i *= $factor;
        if ($i < $minimum_limit) {
            break;
        }
       echo "i est bon";

        /* ...traitement de i... */

    } while (0);
    ?>

Il est possible d'utiliser l'opérateur `goto` au lieu de ce bidouillage.

## for

(PHP 4, PHP 5, PHP 7, PHP 8)

Les boucles `for` sont les boucles les plus complexes en PHP. Elles fonctionnent comme les boucles `for` du langage C. La syntaxe des boucles `for` est la suivante :

    for (expr1; expr2; expr3)
        commandes

La première expression (expr1) est évaluée (exécutée), quoi qu'il arrive au début de la boucle.

Au début de chaque itération, l'expression expr2 est évaluée. Si l'évaluation vaut `true`, la boucle continue et les commandes sont exécutées. Si l'évaluation vaut `false`, l'exécution de la boucle s'arrête.

À la fin de chaque itération, l'expression expr3 est évaluée (exécutée).

Les expressions peuvent éventuellement être laissées vides ou peuvent contenir plusieurs expressions séparées par des virgules. Dans expr2, toutes les expressions séparées par une virgule sont évaluées mais le résultat est obtenu depuis la dernière partie. Si l'expression expr2 est laissée vide, cela signifie que c'est une boucle infinie (PHP considère implicitement qu'elle vaut `true`, comme en C). Cela peut être moins inutile qu'il n'y paraît, car il est souvent souhaitable de terminer la boucle par une instruction conditionnelle `break` plutôt que d'utiliser l'expression de vérité de la boucle `for`.

Considérons les exemples suivants. Tous affichent les nombres entiers de 1 à 10 :

    <?php
    /* exemple 1 */

    for ($i = 1; $i <= 10; $i++) {
        echo $i;
    }

    /* exemple 2 */

    for ($i = 1; ; $i++) {
        if ($i > 10) {
            break;
        }
        echo $i;
    }

    /* exemple 3 */

    $i = 1;
    for (; ; ) {
        if ($i > 10) {
            break;
        }
        echo $i;
        $i++;
    }

    /* exemple 4 */

    for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);
    ?>

Bien évidemment, le premier exemple est le plus simple de tous (ou peut-être le quatrième), mais il est aussi possible de penser qu'utiliser une expression vide dans une boucle `for` peut être utile parfois.

PHP supporte aussi la syntaxe alternative suivante pour les boucles `for` :

    for (expr1; expr2; expr3):
        commandes
        ...
    endfor;

Beaucoup de personnes ont l'habitude d'itérer grâce à des tableaux, comme dans l'exemple ci-dessous.

    <?php
    /*
     * Ceci est un tableau avec des données que nous voulons modifier
     * au long de la boucle
     */
    $people = array(
        array('name' => 'Kalle', 'salt' => 856412),
        array('name' => 'Pierre', 'salt' => 215863)
    );

    for($i = 0; $i < count($people); ++$i) {
        $people[$i]['salt'] = mt_rand(000000, 999999);
    }
    ?>

Ce code peut être lent parce qu'il doit calculer la taille du tableau à chaque itération. Étant donné que la taille ne change jamais, il peut facilement être optimisé en utilisant une variable intermédiaire pour stocker la taille au lieu d'appeler de façon répétitive la fonction count() :

    <?php
    $people = array(
        array('name' => 'Kalle', 'salt' => 856412),
        array('name' => 'Pierre', 'salt' => 215863)
    );

    for($i = 0, $size = count($people); $i < $size; ++$i) {
        $people[$i]['salt'] = mt_rand(000000, 999999);
    }
    ?>

## foreach

(PHP 4, PHP 5, PHP 7, PHP 8)

La structure de langage `foreach` fournit une façon simple de parcourir des array et objets Traversable. `foreach` générera une erreur lorsqu'il est utilisé avec une variable contenant un type de données différent ou avec une variable non initialisée.

`foreach` peut éventuellement obtenir la `clé` de chaque élément :

    foreach (iterable_expression as $value) {
        statement_list
    }

    foreach (iterable_expression as $key => $value) {
        statement_list
    }

La première forme passe en revue le tableau `iterable_expression`. À chaque itération, la valeur de l'élément courant est assignée à `$value`.

La seconde forme assignera en plus la clé de l'élément courant à la variable `$key` à chaque itération.

Il est à noter que `foreach` ne modifie pas le pointeur interne du tableau, qui est utilisé par les fonctions telles que current() et key().

Il est possible de personnaliser l'itération sur des objets.

Exemple #1 Utilisations courantes de `foreach`

    <?php

    /* Exemple : valeur uniquement */

    $array = [1, 2, 3, 17];

    foreach ($array as $value) {
        echo "Valeur courante de \$array: $value.\n";
    }

    /* Exemple : clé et valeur */

    $array = [
        "un" => 1,
        "deux" => 2,
        "trois" => 3,
        "dix-sept" => 17
    ];

    foreach ($array as $key => $value) {
        echo "\$array[$key] => $value.\n";
    }

    /* Exemple : tableaux clé-valeur multidimensionnels */
    $grid = [];
    $grid[0][0] = "a";
    $grid[0][1] = "b";
    $grid[1][0] = "y";
    $grid[1][1] = "z";

    foreach ($grid as $y => $row) {
        foreach ($row as $x => $value) {
            echo "Valeur à la position x=$x et y=$y : $value\n";
        }
    }

    /* Exemple : tableaux dynamiques */

    foreach (range(1, 5) as $value) {
        echo "$value\n";
    }
    ?>

> Note:

> `foreach` ne supporte pas la possibilité de supprimer les messages d'erreur en utilisant le `@`.

### Extraction des tableaux imbriqués

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Il est possible d'itérer sur un tableau de tableaux et de décomposer le tableau imbriqué dans des variables de boucle en utilisant soit la déstructuration de tableau via `[]` ou en utilisant la structure de langage list() comme valeur.

> Note: Il est à noter que la déstructuration de tableau via `[]` n'est possible qu'à partir de PHP 7.1.0

Dans les deux exemples suivants, `$a` sera défini sur le premier élément du tableau imbriqué et `$b` contiendra le deuxième élément :

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b]) {
        echo "A: $a; B: $b\n";
    }

    foreach ($array as list($a, $b)) {
        echo "A: $a; B: $b\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    A: 1; B: 2
    A: 3; B: 4

Lorsqu'il y a moins de variables que d'éléments dans le tableau, les éléments restants seront ignorés. De même, les éléments peuvent être ignorés en utilisant une virgule :

    <?php
    $array = [
        [1, 2, 5],
        [3, 4, 6],
    ];

    foreach ($array as [$a, $b]) {
        // Notez qu'il n'y a pas de $c ici.
        echo "$a $b\n";
    }

    foreach ($array as [, , $c]) {
        // Ignorer $a et $b
        echo "$c\n";
    }

    ?>

L'exemple ci-dessus va afficher :

    1 2
    3 4
    5
    6

Une notification sera générée s'il n'y a pas assez d'éléments dans le tableau pour remplir la fonction list() :

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b, $c]) {
        echo "A: $a; B: $b; C: $c\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    Notice: Undefined offset: 2 in example.php on line 7
    A: 1; B: 2; C:

    Notice: Undefined offset: 2 in example.php on line 7
    A: 3; B: 4; C:

### foreach et références

Il est possible de modifier directement les éléments du tableau dans une boucle en précédant `$value` de `&`. Dans ce cas, la valeur sera assignée par référence.

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr est maintenant [2, 4, 6, 8]
    unset($value); // rompre la référence avec le dernier élément
    ?>

Avertissement

La référence à `$value` du dernier élément du tableau demeure même après la boucle `foreach`. Il est recommandé de détruire ces références en utilisant unset(). Sinon, le comportement suivant se produira :

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr est maintenant [2, 4, 6, 8]

    // sans unset($value), $value est toujours une référence au dernier élément : $arr[3]

    foreach ($arr as $key => $value) {
        // $arr[3] sera mis à jour avec chaque valeur de $arr...
        echo "{$key} => {$value} ";
        print_r($arr);
    }
    // ...jusqu'à ce que finalement l'avant-dernière valeur soit copiée sur la dernière valeur
    ?>

L'exemple ci-dessus va afficher :

    0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
    1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
    2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
    3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )

Exemple #2 Itérer sur les valeurs d'un tableau constant par référence

    <?php
    foreach ([1, 2, 3, 4] as &$value) {
        $value = $value * 2;
    }
    ?>

### Voir aussi

- array
- Traversable
- iterable
- list()

## break

(PHP 4, PHP 5, PHP 7, PHP 8)

L'instruction `break` permet de sortir d'une structure `for`, `foreach`, `while`, `do-while` ou `switch`.

`break` accepte un argument numérique optionnel qui indique combien de structures emboîtées doivent être interrompues. La valeur par défaut est `1`, seulement la structure emboîtée immédiate est interrompue.

    <?php
    $arr = array('un', 'deux', 'trois', 'quatre', 'stop', 'cinq');
    foreach ($arr as $val) {
        if ($val == 'stop') {
            break;    /* Vous pourriez aussi utiliser 'break 1;' ici. */
        }
        echo "$val<br />\n";
    }

    /* Utilisation de l'argument optionnel. */

    $i = 0;
    while (++$i) {
        switch ($i) {
            case 5:
                echo "À 5<br />\n";
                break 1;  /* Termine uniquement le switch. */
            case 10:
                echo "À 10 ; arrêt<br />\n";
                break 2;  /* Termine le switch et la boucle while. */
            default:
                break;
        }
    }
    ?>

## continue

(PHP 4, PHP 5, PHP 7, PHP 8)

L'instruction `continue` est utilisée dans une boucle afin d'éluder les instructions de l'itération courante et de continuer l'exécution à la condition de l'évaluation et donc, de commencer la prochaine itération.

> Note: En PHP, la structure `switch` est considérée comme une boucle par `continue`. `continue` se comporte comme `break` (lorsqu'aucun argument n'est passé) mais émettra un avertissement, car il est probable que ceci soit une erreur. Si un `switch` se trouve à l'intérieur d'une boucle, `continue 2` va continuer sur la prochaine itération de la boucle externe.

`continue` accepte un argument numérique optionnel qui indique combien de structures emboîtées doivent être éludées. La valeur par défaut est `1`, ce qui revient à aller directement à la fin de la boucle courante.

    <?php
    $arr = ['zero', 'one', 'two', 'three', 'four', 'five', 'six'];
    foreach ($arr as $key => $value) {
        if (0 === ($key % 2)) { // évite les membres pairs
            continue;
        }
        echo $value . "\n";
    }
    ?>

Les exemples ci-dessus vont afficher :

    one
    three
    five

    <?php
    $i = 0;
    while ($i++ < 5) {
        echo "Extérieur\n";
        while (1) {
            echo "Milieu\n";
            while (1) {
                echo "Intérieur\n";
                continue 3;
            }
            echo "Ceci n'est jamais affiché.\n";
        }
        echo "Ceci non plus.\n";
    }
    ?>

Les exemples ci-dessus vont afficher :

    Extérieur
    Milieu
    Intérieur
    Extérieur
    Milieu
    Intérieur
    Extérieur
    Milieu
    Intérieur
    Extérieur
    Milieu
    Intérieur
    Extérieur
    Milieu
    Intérieur

Oublier le point-virgule après `continue` peut porter à confusion. Voici un exemple de ce qu'il ne faut pas faire :

    <?php
    for ($i = 0; $i < 5; ++$i) {
        if ($i == 2)
            continue
        print "$i\n";
    }
    ?>

On peut s'attendre à ce que le résultat soit :

    0
    1
    3
    4

Historique pour `continue`
Version | Description
--- | ---
7.3.0 | `continue` à l'intérieur d'un `switch` qui tente d'agir comme une déclaration `break` pour `switch` émettra `E_WARNING`.

## switch

(PHP 4, PHP 5, PHP 7, PHP 8)

L'instruction `switch` équivaut à une série d'instructions `if`. En de nombreuses occasions, il est nécessaire de comparer la même variable (ou expression) avec un grand nombre de valeurs différentes, et d'exécuter différentes parties de code suivant la valeur à laquelle elle est égale. C'est exactement à cela que sert l'instruction `switch`.

> Note: Il est à noter que contrairement à d'autres langages, la structure continue s'applique aux structures `switch` et se comporte de la même manière que `break`. Si un `switch` se trouve dans une boucle, et qu'il faut continuer jusqu'à la prochaine itération de la boucle extérieure, il est nécessaire d'utiliser `continue 2`.

> Note:

> Il est à noter que switch/case provoque une comparaison large.

Dans l'exemple suivant, chaque bloc de code est équivalent. L'un utilise une série d'instructions `if` et `elseif`, et l'autre une instruction de type `switch`. Dans chaque cas, la sortie est la même.

Exemple #1 Instruction `switch`

    <?php
    // Ce switch:

    switch ($i) {
        case 0:
            echo "i égal 0";
            break;
        case 1:
            echo "i égal 1";
            break;
        case 2:
            echo "i égal 2";
            break;
    }

    // Équivaut à:

    if ($i == 0) {
        echo "i égal 0";
    } elseif ($i == 1) {
        echo "i égal 1";
    } elseif ($i == 2) {
        echo "i égal 2";
    }
    ?>

Il est important de comprendre que l'instruction `switch` exécute chacune des clauses dans l'ordre. L'instruction `switch` est exécutée ligne par ligne. Au début, aucun code n'est exécuté. Uniquement lorsqu'une instruction `case` est trouvée dont l'expression est évaluée à une valeur qui correspond à la valeur de l'expression `switch`, PHP exécute alors les instructions correspondantes. PHP continue d'exécuter les instructions jusqu'à la fin du bloc d'instructions du `switch`, ou bien dès qu'il trouve l'instruction `break`. Si l'instruction `break` n'est pas utilisée à la fin de l'instruction `case`, PHP continuera à exécuter toutes les instructions qui suivent. Par exemple :

    <?php
    switch ($i) {
        case 0:
            echo "i égal 0";
        case 1:
            echo "i égal 1";
        case 2:
            echo "i égal 2";
    }
    ?>

Dans cet exemple, si $i est égal à 0, PHP va exécuter quand même toutes les instructions qui suivent ! Si $i est égal à 1, PHP exécutera les deux dernières instructions. Et seulement si $i est égal à 2, le résultat escompté sera obtenu, c'est-à-dire, l'affichage de "i égal 2". Donc, l'important est de ne pas oublier l'instruction `break` (même s'il est possible de l'omettre dans certaines circonstances).

Dans une instruction `switch`, une condition n'est évaluée qu'une fois, et le résultat est comparé à chaque `case`. Dans une structure `elseif`, les conditions sont évaluées à chaque comparaison. Si la condition est plus compliquée qu'une simple comparaison, ou bien fait partie d'une boucle, `switch` sera plus rapide.

La liste d'instructions d'un `case` peut être vide, auquel cas PHP utilisera la liste d'instructions du cas suivant.

    <?php
    switch ($i) {
        case 0:
        case 1:
        case 2:
            echo "i est plus petit que 3 mais n'est pas négatif";
            break;
        case 3:
            echo "i égal 3";
    }
    ?>

Un cas spécial est `default`. Ce cas est utilisé lorsque tous les autres cas ont échoué. Par exemple :

    <?php
    switch ($i) {
        case 0:
            echo "i égal 0";
            break;
        case 1:
            echo "i égal 1";
            break;
        case 2:
            echo "i égal 2";
            break;
        default:
           echo "i n'est ni égal à 2, ni à 1, ni à 0.";
    }
    ?>

> Note: Plusieurs cas default lèveront une erreur de niveau `E_COMPILE_ERROR`.

> Note: Techniquement, le cas `default` peut être placé à n'importe quelle position. Il ne sera utilisé que si aucun autre cas ne correspond. Cependant, par convention, il est préférable de le placer à la fin.

Si aucun `case` ne correspond, et qu'il n'y a pas de `default`, alors aucun code ne sera exécuté, tout comme si aucune instruction `if` n'était vraie.

Une valeur de `case` peut être donnée sous forme d'expression. Cependant, cette expression sera évaluée seule, puis comparée de manière approximative à la valeur du `switch`. Cela signifie qu'elle ne peut pas être utilisée pour des évaluations complexes de la valeur du `switch`. Par exemple :

    <?php
    $target = 1;
    $start = 3;

    switch ($target) {
        case $start - 1:
            print "A";
            break;
        case $start - 2:
            print "B";
            break;
        case $start - 3:
            print "C";
            break;
        case $start - 4:
            print "D";
            break;
    }

    // Affiche "B"
    ?>

Pour des comparaisons plus complexes, la valeur `true` peut être utilisée comme valeur de `switch`. Ou, alternativement, des blocs `if`-`else` au lieu de `switch`.

    <?php
    $offset = 1;
    $start = 3;

    switch (true) {
        case $start - $offset === 1:
            print "A";
            break;
        case $start - $offset === 2:
            print "B";
            break;
        case $start - $offset === 3:
            print "C";
            break;
        case $start - $offset === 4:
            print "D";
            break;
    }

    // Affiche "B"
    ?>

La syntaxe alternative pour cette structure de contrôle est la suivante : (pour plus d'informations, voir syntaxes alternatives).

    <?php
    switch ($i):
        case 0:
            echo "i égal 0";
            break;
        case 1:
            echo "i égal 1";
            break;
        case 2:
            echo "i égal 2";
            break;
        default:
            echo "i n'est ni égal à 2, ni à 1, ni à 0";
    endswitch;
    ?>

Il est possible d'utiliser un point-virgule plutôt que deux points après un case, comme ceci :

    <?php
    switch($beer)
    {
        case 'leffe';
        case 'grimbergen';
        case 'guinness';
        case 'jupiler';
            echo 'Bon choix';
            break;
        default;
            echo 'Merci de faire un nouveau choix...';
            break;
    }
    ?>

### Voir aussi

- match

## match

(PHP 8)

L'expression `match` permet d'effectuer une évaluation basée sur le contrôle d'identité d'une valeur. De la même manière qu'une instruction `switch`, une expression `match` a une expression sujet qui est comparée à plusieurs alternatives. Contrairement à `switch`, elle s'évalue à une valeur, comme les expressions ternaires. Contrairement à `switch`, la comparaison est une vérification d'identité (`===`) plutôt qu'un contrôle d'égalité faible (`==`). Les expressions Match sont disponibles à partir de PHP 8.0.0.

Exemple #1 Structure d'une expression `match`

    <?php
    $return_value = match (subject_expression) {
        single_conditional_expression => return_expression,
        conditional_expression1, conditional_expression2 => return_expression,
    };
    ?>

Exemple #2 Utilisation de base des expressions `match`

    <?php
    $food = 'cake';

    $return_value = match ($food) {
        'apple' => 'Cet aliment est une pomme',
        'bar' => 'Cet aliment est une barre',
        'cake' => 'Cet aliment est un gâteau',
    };

    var_dump($return_value);
    ?>

L'exemple ci-dessus va afficher :

    string(26) "Cet aliment est un gâteau"

Exemple #3 Exemple d'utilisation de `match` avec des opérateurs de comparaison

    <?php
    $age = 18;

    $output = match (true) {
        $age < 2 => "Bébé",
        $age < 13 => "Enfant",
        $age <= 19 => "Adolescent",
        $age >= 40 => "Adulte",
        $age > 19 => "Jeune adulte",
    };

    var_dump($output);
    ?>

L'exemple ci-dessus va afficher :

    string(10) "Adolescent"

> Note: Le résultat d'une expression `match` n'a pas besoin d'être utilisé.

> Note: Lorsqu'une expression `match` est utilisée comme une expression autonome, elle doit être terminée par un point-virgule `;`.

L'expression `match` est similaire à une instruction `switch` mais présente quelques différences essentielles:

- Une expression `match` compare les valeurs de manière stricte (`===`) et non de manière faible comme le fait l'instruction switch.
- Une expression `match` renvoie une valeur.
- Les expressions `match` ne passent pas aux cas suivants comme le font les instructions `switch`.
- Une expression `match` doit être exhaustive.

Comme les instructions `switch`, les expressions `match` sont exécutées bras par bras. Au début, aucun code n'est exécuté. Les expressions conditionnelles ne sont évaluées que si toutes les expressions conditionnelles précédentes ne correspondent pas à l'expression de l'objet. Seule l'expression de retour correspondant à l'expression conditionnelle correspondante sera évaluée. Par exemple :

    <?php
    $result = match ($x) {
        foo() => 'value',
        $this->bar() => 'value', // $this->bar() n'est pas appelé si foo() === $x
        $this->baz => beep(), // beep() n'est pas appelé sauf si $x === $this->baz
        // etc.
    };
    ?>

Les bras de l'expression de `match` peuvent contenir plusieurs expressions séparées par une virgule. Il s'agit d'un OU logique et d'une abréviation pour plusieurs bras qui utilisent la même expression comme résultat.

    <?php
    $result = match ($x) {
        // Ce bras
        $a, $b, $c => 5,
        // Est équivalent à ces trois bras :
        $a => 5,
        $b => 5,
        $c => 5,
    };
    ?>

Le motif `default` est un cas particulier. Ce motif correspond à tout ce qui n'a pas été recherché précédemment. Par exemple :

    <?php
    $expressionResult = match ($condition) {
        1, 2 => foo(),
        3, 4 => bar(),
        default => baz(),
    };
    ?>

> Note: L'utilisation de plusieurs motifs par défaut entraînera une erreur `E_FATAL_ERROR`.

Une expression `match` doit être exhaustive. Si l'expression n'est traitée par aucun bras de `match`, une erreur UnhandledMatchError est lancée.

Exemple #4 Exemple d'une expression match non gérée

    <?php
    $condition = 5;

    try {
        match ($condition) {
            1, 2 => foo(),
            3, 4 => bar(),
        };
    } catch (\UnhandledMatchError $e) {
        var_dump($e);
    }
    ?>

L'exemple ci-dessus va afficher :

    object(UnhandledMatchError)#1 (7) {
      ["message":protected]=>
      string(33) "Unhandled match value of type int"
      ["string":"Error":private]=>
      string(0) ""
      ["code":protected]=>
      int(0)
      ["file":protected]=>
      string(9) "/in/ICgGK"
      ["line":protected]=>
      int(6)
      ["trace":"Error":private]=>
      array(0) {
      }
      ["previous":"Error":private]=>
      NULL
    }

### Utilisation d'expressions match pour gérer les contrôles de non-identité

Il est possible d'utiliser une expression `match` pour traiter les cas conditionnels de non-identité en utilisant `true` comme expression sujet.

Exemple #5 Utilisation d'une expression match généralisée pour effectuer des branchements sur des plages d'entiers

    <?php

    $age = 23;

    $result = match (true) {
        $age >= 65 => 'senior',
        $age >= 25 => 'adult',
        $age >= 18 => 'young adult',
        default => 'kid',
    };

    var_dump($result);
    ?>

L'exemple ci-dessus va afficher :

    string(11) "young adult"

Exemple #6 Utilisation d'une expression match généralisée pour effectuer des branchements sur le contenu d'une chaîne de caractères

    <?php

    $text = 'Bienvenue chez nous';

    $result = match (true) {
        str_contains($text, 'Welcome'), str_contains($text, 'Hello') => 'en',
        str_contains($text, 'Bienvenue'), str_contains($text, 'Bonjour') => 'fr',
        // ...
    };

    var_dump($result);
    ?>

L'exemple ci-dessus va afficher :

    string(2) "fr"

## declare

(PHP 4, PHP 5, PHP 7, PHP 8)

L'élément de langage `declare` sert à ajouter des directives d'exécution dans un bloc de code. La syntaxe de `declare` est similaire à la syntaxe des autres structures de contrôle :

    declare (directive)
        commandes

L'expression `directive` permet de contrôler l'intervention du bloc `declare`. Actuellement, seulement trois directives sont reconnues :

- `ticks`
- `encoding`
- `strict_types`

Comme les directives sont gérées lors de la compilation du fichier, seulement les littéraux peuvent être utilisés comme valeur de ces directives. Les variables et constantes ne peuvent pas être utilisées. Pour illustrer :

    <?php
    // Ceci est correct:
    declare(ticks=1);

    // Ceci est incorrect:
    const TICK_VALUE = 1;
    declare(ticks=TICK_VALUE);
    ?>

L'expression `commandes` du bloc de `declare` sera exécutée. Comment elle sera exécutée, et quels effets cela aura, dépend de la directive utilisée dans le bloc `directive`.

La structure `declare` peut aussi être utilisée dans le contexte global. Elle affecte alors tout le code qui la suit (même si le fichier avec `declare` a été inclus après, ça n'affecte pas le fichier parent).

    <?php
    // Ces déclarations sont identiques.

    // Vous pouvez utiliser ceci
    declare(ticks=1) {
        // script entier ici
    }

    // ou ceci
    declare(ticks=1);
    // script entier ici
    ?>

### Ticks

Un tick est un événement qui intervient toutes les N commandes bas niveau tickables, exécutées par l'analyseur dans le bloc de `declare`. La valeur de N est spécifiée par la syntaxe `ticks=N` dans le bloc de directive `declare`.

Toutes les commandes ne sont pas tickables. Typiquement, les expressions de condition et les expressions d'arguments ne sont pas tickables.

Un événement qui intervient à chaque tick est spécifié avec la fonction register_tick_function(). Se reporter à l'exemple ci-dessous pour plus de détails. Il est à noter que plus d'un événement peut intervenir par tick.

Exemple #1 Exemple d'utilisation des ticks

    <?php

    declare(ticks=1);

    // Une fonction appelée à chaque événement tick
    function tick_handler()
    {
        echo "tick_handler() called\n";
    }

    register_tick_function('tick_handler'); // provoque un événement tick

    $a = 1; // provoque un événement tick

    if ($a > 0) {
        $a += 2; // provoque un événement tick
        print $a; // provoque un événement tick
    }

    ?>

Voir aussi register_tick_function() et unregister_tick_function().

### L'encodage

L'encodage d'un script peut être spécifié par script en utilisant la directive `encoding`.

Exemple #2 Déclaration d'un encodage pour un script

    <?php
    declare(encoding='ISO-8859-1');
    // le code
    ?>

Attention

Combinée avec les espaces de nommage, la seule syntaxe valable pour declare est `declare(encoding='...');` où `...` est la valeur de l'encodage. `declare(encoding='...') {}` soulèvera une erreur d'interprétation dans le cas des espaces de nommage.

Voir aussi zend.script_encoding.

## return

(PHP 4, PHP 5, PHP 7, PHP 8)

`return` retourne le contrôle du programme au module appelant. L'exécution reprend alors à l'instruction suivante de l'invocation du module.

Si appelée depuis une fonction, la commande `return` termine immédiatement la fonction et retourne l'argument qui lui est passé. `return` interrompt aussi l'exécution d'une commande eval() ou de scripts.

Si appelée depuis l'environnement global, l'exécution du script est interrompue. Si le script courant était inclus avec la structure include ou require, alors le contrôle est rendu au script appelant. De plus, si le fichier du script courant a été inclus via l'instruction include, alors la valeur retournée sera utilisée comme résultat de l'instruction include. Si `return` est appelée depuis le script principal, alors l'exécution du script s'arrête. Si le script courant est auto_prepend_file ou auto_append_file dans le fichier php.ini, alors l'exécution du script s'arrête.

Pour plus d'informations, voir retourner des valeurs.

> Note: Il est à noter que puisque `return` est une structure de langage, et non une fonction, les parenthèses entourant les arguments ne sont pas nécessaires et leur utilisation est découragée.

> Note: Si aucun paramètre n'est fourni, alors les parenthèses doivent être omises et `null` sera retourné. L'appel de `return` avec des parenthèses mais sans argument résultera en une alerte d'analyse.

À partir de PHP 7.1.0, les déclarations de retour sans argument dans les fonctions qui déclarent un type de retour déclenchent une `E_COMPILE_ERROR`, sauf si le type de retour est void, auquel cas les déclarations de retour avec un argument déclenchent cette erreur.

## require

(PHP 4, PHP 5, PHP 7, PHP 8)

`require` est identique à include mis à part le fait que lorsqu'une erreur survient, il produit également une exception Error (erreur de niveau `E_COMPILE_ERROR` avant PHP 8.0.0), tandis que include ne produira qu'un avertissement (erreur de niveau `E_WARNING`).

Voir la documentation de l'instruction include pour en connaître le fonctionnement.

## include

(PHP 4, PHP 5, PHP 7, PHP 8)

L'expression de langage `include` inclut et exécute le fichier spécifié en argument.

Cette documentation s'applique aussi à l'instruction de langage require.

Les fichiers sont inclus suivant le chemin du fichier fourni ; si aucun n'est fourni, l'include_path sera vérifié. Si le fichier n'est pas trouvé dans l' include_path, `include` vérifiera dans le dossier du script appelant et dans le dossier de travail courant avant d'échouer. L'instruction `include` émettra `E_WARNING` si elle ne peut trouver le fichier ; ce comportement est différent de require, qui émettra `E_ERROR`.

Il est à noter que `include` et `require` vont lever des erreurs supplémentaires de type `E_WARNING`, si le fichier n'est pas accessible, avant de lever une erreur de type `E_WARNING` ou `E_ERROR`, respectivement.

Si un chemin est défini, absolu (commençant par une lettre de lecteur suivie de `\` pour Windows, ou `/` pour Unix/Linux) ou relatif (commençant par . ou ..), l'include_path sera ignoré. Par exemple, si un nom de fichier commence par `../`, PHP cherchera dans le dossier parent pour y trouver le fichier spécifié.

Pour plus d'informations sur la façon dont PHP gère les fichiers inclus ainsi que le chemin d'inclusion, se reporter à la documentation relative à l'include_path.

Lorsqu'un fichier est inclus, le code le composant hérite de la portée des variables de la ligne où l'inclusion apparaît. Toutes les variables disponibles à cette ligne dans le fichier appelant seront disponibles dans le fichier appelé, à partir de ce point. Cependant, toutes les fonctions et classes définies dans le fichier inclus ont une portée globale.

Exemple #1 Exemple avec `include`

    vars.php
    <?php

    $couleur = 'verte';
    $fruit = 'pomme';

    ?>

    test.php
    <?php

    echo "Une $fruit $couleur"; // Une

    include 'vars.php';

    echo "Une $fruit $couleur"; // Une pomme verte

    ?>

Si l'inclusion intervient à l'intérieur d'une fonction, le code inclus sera alors considéré comme faisant partie de la fonction. Cela modifie donc le contexte de variables accessibles. Une exception à cette règle : les constantes magiques sont analysées par l'analyseur avant que l'inclusion n'intervienne.

Exemple #2 Inclusion de fichiers dans une fonction

    <?php

    function foo()
    {
        global $couleur;

        include 'vars.php';

        echo "Une $fruit $couleur";
    }

    /* vars.php est dans le contexte de foo()     *
     * donc $fruit n'est pas disponible hors de   *
     * cette fonction. $couleur l'est, car c'est  *
     * une variable globale                       */

    foo();                      // Une pomme verte
    echo "Une $fruit $couleur"; // Une verte

    ?>

Lorsqu'un fichier est inclus, l'analyse bascule du mode PHP au mode HTML au début du fichier cible, et reprend à la fin de celui-ci. Pour cette raison, tout code du fichier cible devant être exécuté comme du code PHP doit être placé entre des balises PHP de début et de fin valides.

Si les enveloppes d'inclusion d'URL sont activées dans PHP, il est possible de localiser le fichier avec une URL (via HTTP ou bien avec une enveloppe adaptée : voir Liste des protocoles et des gestionnaires supportés pour une liste des protocoles), au lieu d'un simple chemin local. Si le serveur distant interprète le fichier comme du code PHP, des variables peuvent être transmises au serveur distant via l'URL et la méthode GET. Ce n'est pas, à strictement parler, la même chose que d'hériter du contexte de variable. Le fichier inclus est en fait un script exécuté à distance, et son résultat est inclus dans le code courant.

Exemple #3 Utiliser l'instruction `include` via HTTP

    <?php

    /* Cet exemple suppose que www.example.com est configuré pour traiter
     * les fichiers .php et non pas les fichiers .txt. De plus,
     * 'Work' signifie ici que les variables
     * $foo et $bar sont disponibles dans le fichier inclus
     */

    // Ne fonctionne pas : file.txt n'a pas été traité par www.example.com comme du PHP
    include 'http://www.example.com/file.txt?foo=1&bar=2';

    // Ne fonctionne pas : le script cherche un fichier nommé
    // 'file.php?foo=1&bar=2' sur le système local
    include 'file.php?foo=1&bar=2';

    // Réussi
    include 'http://www.example.com/file.php?foo=1&bar=2';
    ?>

Avertissement

# Alerte de sécurité

Un fichier distant peut être traité sur le serveur distant (dépendamment de l'extension du fichier et si le serveur distant exécute PHP ou non) mais il doit toujours produire un script PHP valide parce qu'il sera traité sur le serveur local. Si le fichier du serveur distant doit être traité sur place et affiché seulement, readfile() est une fonction beaucoup plus appropriée. Autrement, il est recommandé de bien faire attention à sécuriser le script distant afin qu'il produise un code valide et désiré.

Voir aussi travailler avec les fichiers distants, fopen() et file() pour des informations relatives.

Gestion du retour : `include` retourne `false` en cas d'erreur et émet un avertissement. Les inclusions réussies retournent `1`, sauf si une valeur de retour est définie par le fichier inclus. Il est possible d'exécuter la structure de langage return à l'intérieur d'un fichier inclus afin de déterminer le processus dans ce fichier, et retourner au script qui l'a appelé. De plus, il est possible de retourner des valeurs depuis des fichiers inclus. Il est possible de récupérer la valeur depuis l'appel au fichier inclus comme depuis une fonction normale. Ce n'est cependant pas possible lors de l'inclusion de fichiers distants, et ce, tant que la sortie du fichier distant n'a pas de balises PHP de début et de fin valides (tout comme pour les fichiers locaux). Il est possible de déclarer les variables nécessaires à l'intérieur de ces balises et elles seront introduites à l'endroit où le fichier a été inclus.

Comme `include` est une structure de langage particulière, les parenthèses ne sont pas nécessaires autour de l'argument. Il faut faire attention lors de la comparaison de la valeur retournée.

Exemple #4 Comparaison de la valeur de retour d'une inclusion

    <?php
    // Ne fonctionne pas, évalué comme include(('vars.php') == TRUE), i.e. include('1')
    if (include('vars.php') == TRUE) {
        echo 'OK';
    }

    // Fonctionne
    if ((include 'vars.php') == TRUE) {
        echo 'OK';
    }
    ?>

Exemple #5 `include` et return

    return.php
    <?php

    $var = 'PHP';

    return $var;

    ?>

    noreturn.php
    <?php

    $var = 'PHP';

    ?>

    testreturns.php
    <?php

    $foo = include 'return.php';

    echo $foo; // affiche 'PHP'

    $bar = include 'noreturn.php';

    echo $bar; // affiche 1

    ?>

`$bar` a la valeur de `1` car l'inclusion était réussie. Il est à noter la différence entre les deux exemples ci-dessus. Le premier utilise la commande return dans le fichier inclus, alors que le second ne le fait pas. Si le fichier ne peut être inclus, `false` est retourné et une erreur de niveau `E_WARNING` est envoyée.

S'il y a des fonctions définies dans le fichier inclus, elles peuvent être utilisées dans le fichier principal si elles sont avant le return ou après. Si le fichier est inclus deux fois, PHP émettra une erreur fatale car les fonctions ont déjà été déclarées. Il est recommandé d'utiliser include_once au lieu de vérifier si le fichier a déjà été inclus et donc de retourner conditionnellement l'inclusion du fichier.

Une autre façon d'inclure un fichier PHP dans une variable est de capturer la sortie en utilisant les fonctions de contrôle de sortie avec `include`. Par exemple :

Exemple #6 Utilisation de la sortie du buffer pour inclure un fichier PHP dans une chaîne

    <?php
    $string = get_include_contents('somefile.php');

    function get_include_contents($filename) {
        if (is_file($filename)) {
            ob_start();
            include $filename;
            return ob_get_clean();
        }
        return false;
    }

    ?>

Pour automatiquement inclure des fichiers dans les scripts, voir également les options de configuration auto_prepend_file et auto_append_file du php.ini.

> Note: Comme ceci est une structure du langage, et non pas une fonction, il n'est pas possible de l'appeler avec les fonctions variables ou arguments nommés.

Voir aussi require, require_once, include_once, get_included_files(), readfile(), virtual(), et include_path.

## require_once

(PHP 4, PHP 5, PHP 7, PHP 8)

L'expression `require_once` est identique à require mis à part que PHP vérifie si le fichier a déjà été inclus, et si c'est le cas, ne l'inclut pas une deuxième fois.

Voir la documentation de include_once pour plus d'informations concernant le comportement de `_once`, et ce qui le différencie des instructions sans `_once`.

## include_once

(PHP 4, PHP 5, PHP 7, PHP 8)

L'expression `include_once` inclut et évalue le fichier spécifié durant l'exécution du script. Le comportement est similaire à include, mais la différence est que si le code a déjà été inclus, il ne le sera pas une seconde fois, et include_once retourne `true`. Comme son nom l'indique, le fichier sera inclus une seule fois.

`include_once` peut être utilisé dans les cas où le même fichier pourrait être inclus et évalué plus d'une fois lors d'une exécution particulière d'un script, et dans ce cas, cela peut aider à éviter des problèmes tels que des redéfinitions de fonctions, des réassignations de valeurs de variables, etc.

Voir la structure include pour plus de détails sur son fonctionnement.

## goto

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Image fournie par » xkcd

L'opérateur `goto` peut être utilisé pour continuer l'exécution du script à un autre point du programme. La cible est spécifiée par une étiquette sensible à la casse, suivie de deux-points, et l'instruction `goto` est ensuite suivie de ce label. `goto` n'est pas totalement sans limitations. L'étiquette cible doit être dans le même contexte et fichier, ce qui signifie qu'il n'est pas possible de changer de méthode ou de fonction, ni de se rendre dans une autre fonction. Il est de même impossible d'entrer dans une structure de boucle ou un `switch`. Il est néanmoins possible d'en sortir, et l'utilisation courante est alors de se servir de `goto` comme un `break` multi-niveaux.

Exemple #1 Exemple avec `goto`

    <?php

    goto a;
    echo 'Foo';

    a:
    echo 'Bar';

    ?>

L'exemple ci-dessus va afficher :

    Bar

Exemple #2 Exemple de boucle avec `goto`

    <?php

    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            if ($j == 17) {
                goto end;
            }
        }
    }
    echo "i = $i";
    end:
    echo 'j a atteint 17';

    ?>

L'exemple ci-dessus va afficher :

    j a atteint 17

Exemple #3 Ce `goto` ne fonctionne pas

    <?php

    goto loop;
    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            loop:
        }
    }
    echo "$i = $i";

    ?>

L'exemple ci-dessus va afficher :

    Fatal error: 'goto' into loop or switch statement is disallowed in
    script on line 2

# Les fonctions

## Sommaire

- Les fonctions définies par l'utilisateur
- Paramètres et arguments de fonction
- Les valeurs de retour
- Fonctions variables
- Fonctions internes
- Fonctions anonymes
- Fonction Fléchée
- Syntaxe callable de première classe

## Les fonctions définies par l'utilisateur

Une fonction est définie en utilisant le mot-clé `function`, un nom, une liste de paramètres (qui peuvent être vides) séparés par des virgules (`,`) entre parenthèses, suivis du corps de la fonction entre accolades, comme suit :

Exemple #1 Déclaration d'une nouvelle fonction nommée `foo`

    <?php
    function foo($arg_1, $arg_2, /* ..., */ $arg_n)
    {
        echo "Exemple de fonction.\n";
        return $retval;
    }

> Note:

> À partir de PHP 8.0.0, la liste de paramètres peut avoir une virgule finale :

>     <?php
>     function foo($arg_1, $arg_2,) { }

Tout code PHP valide peut apparaître à l'intérieur du corps d'une fonction, y compris d'autres fonctions et des définitions de classe.

Les noms de fonctions suivent les mêmes règles que les autres labels en PHP. Un nom de fonction valide commence par une lettre ou un souligné, suivi par un nombre quelconque de lettres, de nombres ou de soulignés. Ces règles peuvent être représentées par l'expression rationnelle suivante : `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

Astuce

Jetez un oeil sur Guide de nommage de l'espace utilisateur.

Les fonctions n'ont pas besoin d'être définies avant d'être utilisées, SAUF lorsqu'une fonction est définie conditionnellement, comme montré dans les deux exemples suivants.

Lorsqu'une fonction est définie de manière conditionnelle, comme dans les exemples ci-dessous, leur définition doit précéder leur utilisation.

Exemple #2 Fonctions conditionnelles

    <?php
    $makefoo = true;

    /* Impossible d'appeler foo() ici,
       car cette fonction n'existe pas.
       Mais nous pouvons utiliser bar() */
    if (function_exists('foo')) {
        foo();
    } else {
        echo "La fonction foo n'existe pas (encore).\n";
    }

    bar();

    if ($makefoo) {
      function foo()
      {
        echo "Je n'existe pas tant que le programme n'est pas passé ici.\n";
      }
    }

    /* Maintenant, nous pouvons appeler foo()
       car $makefoo est évalué à vrai */

    if ($makefoo) foo();

    function bar()
    {
      echo "J'existe dès le début du programme.\n";
    }

Exemple #3 Fonctions dans une autre fonction

    <?php
    function foo()
    {
      function bar()
      {
        echo "Je n'existe pas tant que foo() n'est pas appelé.\n";
      }
    }

    /* Impossible d'appeler bar() ici
       car il n'existe pas. */
    if (function_exists('bar')) {
        bar();
    }

    foo();

    /* Maintenant, nous pouvons appeler bar(),
       car l'utilisation de foo() l'a rendue
       accessible. */

    bar();

Toutes les fonctions et classes en PHP ont une portée globale - elles peuvent être appelées à l'extérieur d'une fonction si elles ont été définies à l'intérieur et vice-versa.

PHP ne supporte pas la surcharge, la destruction et la redéfinition de fonctions déjà déclarées.

> Note: Les noms de fonctions sont insensibles à la casse pour les caractères ASCII `A` à `Z`, et il est généralement admis que les fonctions doivent être appelées avec le nom utilisé dans leur déclaration, y compris la casse.

Les listes variables d'arguments de fonction et les valeurs par défaut d'arguments sont supportées : voir les fonctions de références que sont func_num_args(), func_get_arg(), et func_get_args() pour plus d'informations.

Il est possible d'appeler des fonctions récursives en PHP.

Exemple #4 Fonctions récursives

    <?php
    function recursion($a)
    {
        if ($a < 20) {
            echo "$a\n";
            recursion($a + 1);
        }
    }

    recursion(17);

> Note: Les appels de méthodes/fonctions récursives avec 100-200 degrés de récursivité peuvent remplir la pile et ainsi, terminer le script courant. À noter qu'une récursion infinie est considérée comme une erreur de programmation.

## Paramètres et arguments de fonction

Les paramètres de la fonction sont déclarés dans la signature de la fonction. Des informations peuvent être passées à une fonction en utilisant une liste d'arguments, dont chaque expression est séparée par une virgule. Les arguments seront évalués de gauche à droite, et le résultat est assigné aux paramètres de la fonction, avant que la fonction ne soit effectivement appelée (évaluation immédiate).

PHP supporte le passage d'arguments par valeur (comportement par défaut), le passage par référence, et des valeurs d'arguments par défaut. Une liste variable d'arguments, ainsi que les Arguments Nommés sont également supportés.

> Note:

> À partir de PHP 7.3.0, il est possible d'avoir une virgule finale dans la liste d'arguments pour les appels de fonction :

>     <?php
>     $v = foo(
>         $arg_1,
>         $arg_2,
>     );

À partir de PHP 8.0.0, la liste des arguments de fonction peut inclure une virgule finale, qui sera ignorée. Ceci est particulièrement pratique dans les cas où la liste d'arguments est longue ou contient des noms de variables longs, ce qui rend pratique de lister les paramètres verticalement.

Exemple #1 Liste des paramètres de la fonction avec une virgule finale

    <?php
    function takes_many_args(
        $first_arg,
        $second_arg,
        $a_very_long_argument_name,
        $arg_with_default = 5,
        $again = 'a default string', // Cette virgule finale n'était pas permise avant 8.0.0.
    )
    {
        // ...
    }

### Passage d'arguments par référence

Par défaut, les arguments sont passés à la fonction par valeur (aussi, changer la valeur d'un argument dans la fonction ne change pas sa valeur à l'extérieur de la fonction). Pour que les fonctions puissent changer la valeur des arguments, il faut passer ces arguments par référence.

Pour qu'un argument soit toujours passé par référence, il suffit d'ajouter un '`&`' devant le paramètre dans la déclaration de la fonction :

Exemple #2 Passage des arguments de fonction par référence

    <?php
    function add_some_extra(&$string)
    {
        $string .= ', et un peu plus.';
    }
    $str = 'Ceci est une chaîne';
    add_some_extra($str);
    echo $str; // Affiche : 'Ceci est une chaîne, et un peu plus.'

Il est incorrect de passer une expression constante comme argument à un paramètre qui attend d'être passé par référence.

### Valeurs par défaut des paramètres

Une fonction peut définir des valeurs par défaut pour les paramètres en utilisant une syntaxe similaire à celle de l'affectation d'une variable. La valeur par défaut est utilisée uniquement lorsque l'argument du paramètre n'est pas passé. Il est à noter que passer `null` ne définit pas la valeur par défaut.

Exemple #3 Valeur par défaut des arguments de fonctions

    <?php
    function servir_cafe ($type = "cappuccino")
    {
        return "Servir un $type.\n";
    }
    echo servir_cafe();
    echo servir_cafe(null);
    echo servir_cafe("espresso");

L'exemple ci-dessus va afficher :

    Servir un cappuccino.
    Servir un .
    Servir un espresso.

Les valeurs par défaut des paramètres peuvent être des valeurs scalaires, des tableaus, le type spécial `null`, et à partir de PHP 8.1.0, des objets utilisant la syntaxe new ClassName().

Exemple #4 Utilisation de type non-scalaire comme valeur par défaut

    <?php
    function servir_cafe($types = array("cappuccino"), $coffeeMaker = NULL)
    {
        $device = is_null($coffeeMaker) ? "les mains" : $coffeeMaker;
        return "Préparation d'une tasse de ".join(", ", $types)." avec $device.\n";
    }
    echo servir_cafe();
    echo servir_cafe(array("cappuccino", "lavazza"), "une cafetière");

L'exemple ci-dessus va afficher :

    Préparation d'une tasse de cappuccino avec les mains.
    Préparation d'une tasse de cappuccino, lavazza avec une cafetière.

Exemple #5 Utilisation d'objets comme valeurs par défaut (à partir de PHP 8.1.0)

    <?php
    class DefaultCoffeeMaker {
        public function brew() {
            return 'Faire du café.\n';
        }
    }
    class FancyCoffeeMaker {
        public function brew() {
            return 'Créer un beau café rien que pour vous.\n';
        }
    }
    function makecoffee($coffeeMaker = new DefaultCoffeeMaker)
    {
        return $coffeeMaker->brew();
    }
    echo makecoffee();
    echo makecoffee(new FancyCoffeeMaker);

L'exemple ci-dessus va afficher :

    Faire du café.
    Créer un beau café rien que pour vous.

La valeur par défaut d'un argument doit obligatoirement être une constante, et ne peut être ni une variable, ni un membre de classe, ni un appel de fonction.

Il est à noter que tous les paramètres optionnels doivent être spécifiés après les paramètres obligatoires, sinon ils ne peuvent pas être omis dans les appels. Considérons le code suivant :

Exemple #6 Utilisation incorrecte des paramètres de fonction par défaut

    <?php
    function faireunyaourt ($container = "bol", $flavour)
    {
        return "Préparer un $container de yaourt à la $flavour.\n";
    }

    echo faireunyaourt("framboise");   // "framboise" est $container, pas $flavour

L'exemple ci-dessus va afficher :

    Deprecated: faireunyaourt(): Optional parameter $container declared before required parameter $flavour is implicitly treated as a required parameter in script on line 2

    Fatal error: Uncaught ArgumentCountError: Too few arguments to function faireunyaourt(), 1 passed in script on line 7 and exactly 2 expected in script:2
    Stack trace:
    #0 script(7): faireunyaourt('framboise')
    #1 {main}
      thrown in script on line 2

Maintenant comparons l'exemple précédent avec l'exemple suivant :

Exemple #7 Utilisation correcte des paramètres de fonction par défaut

    <?php
    function faireunyaourt ($flavour, $container = "bol")
    {
        return "Préparer un $container de yaourt à la $flavour.\n";
    }

    echo faireunyaourt ("framboise");   // "framboise" est $flavour

L'exemple ci-dessus va afficher :

    Préparer un bol de yaourt à la framboise.

À partir de PHP 8.0.0, les arguments nommés peuvent être utilisés pour passer outre plusieurs paramètres optionnels.

Exemple #8 Utilisation correcte des paramètres de fonction par défaut

    <?php
    function faireunyaourt($container = "bol", $flavour = "framboise", $style = "Grec")
    {
        return "Préparer un $container de yaourt $style à la $flavour.\n";
    }
    echo faireunyaourt(style: "naturel");

L'exemple ci-dessus va afficher :

    Préparer un bol de yaourt naturel à la framboise.

À partir de PHP 8.0.0, déclarer des paramètres obligatoires après des arguments optionnels est obsolète. Ce problème peut généralement être résolu en abandonnant la valeur par défaut, puisqu'elle ne sera jamais utilisée. Une exception à cette règle concerne les paramètres de la forme `Type $param = null`, où le `null` par défaut rend le type implicitement nullable. Cet usage est déprécié à partir de PHP 8.4.0, et un type nullable explicite doit être utilisé à la place.

Exemple #9 Déclaration des paramètres optionnels après les paramètres obligatoires

    <?php
    function foo($a = [], $b) {}     // Valeur par défaut non utilisée ; déconseillée à partir de PHP 8.0.0
    function foo($a, $b) {}          // Fonctionnellement équivalent, pas d’avertissement de dépréciation

    function bar(A $a = null, $b) {} // À partir de PHP 8.1.0, $a est implicitement requis
                                     // (car il précède un paramètre requis),
                                     // mais implicitement nullable (déconseillé à partir de PHP 8.4.0),
                                     // car la valeur par défaut du paramètre est null
    function bar(?A $a, $b) {}       // Recommandé

> Note: À partir de PHP 7.1.0, l'omission d'un paramètre qui ne spécifie pas une valeur par défaut lance un ArgumentCountError ; dans les versions précédentes, cela levait un avertissement.

> Note: Les arguments passés par référence peuvent avoir une valeur par défaut.

### Liste d'argument à nombre variable

PHP supporte les arguments à nombre variable dans les fonctions définies par l'utilisateur en utilisant le token `...`.

La liste des arguments peut inclure le token `...` pour indiquer que cette fonction accepte un nombre variable d'arguments. Les arguments seront passés dans la variable fournie sous forme d'un tableau:

Exemple #10 Utilisation de `...` pour accéder aux arguments variables

    <?php
    function sum(...$numbers) {
        $acc = 0;
        foreach ($numbers as $n) {
            $acc += $n;
        }
        return $acc;
    }

    echo sum(1, 2, 3, 4);

L'exemple ci-dessus va afficher :

    10

`...` peut aussi être utilisé lors des appels de fonctions pour extraire le tableau ou la variable Traversable ou le littéral dans la liste d'arguments :

Exemple #11 Utilisation de `...` pour fournir des arguments

    <?php
    function add($a, $b) {
        return $a + $b;
    }

    echo add(...[1, 2])."\n";

    $a = [1, 2];
    echo add(...$a);

L'exemple ci-dessus va afficher :

    3
    3

Il est possible de spécifier des paramètres classiques avant le mot clé `...`. Dans ce cas, seuls les arguments finaux qui ne correspondent pas à un argument classique seront ajoutés au tableau généré par `...`.

Il est également possible d'ajouter une déclaration de type avant le jeton `...`. Si ceci est présent, alors tous les arguments capturés par `...` doivent correspondre au type de paramètre.

Exemple #12 Transtypage d'arguments variables

    <?php
    function total_intervals($unit, DateInterval ...$intervals) {
        $time = 0;
        foreach ($intervals as $interval) {
            $time += $interval->$unit;
        }
        return $time;
    }

    $a = new DateInterval('P1D');
    $b = new DateInterval('P2D');
    echo total_intervals('d', $a, $b).' jours';

    // Ceci échouera, car null n'est pas un objet DateInterval.
    echo total_intervals('d', null);

L'exemple ci-dessus va afficher :

    3 jours
    Fatal error: Uncaught TypeError: total_intervals(): Argument #2 must be of type DateInterval, null given, called in script on line 15 and defined in script:2
    Stack trace:
    #0 script(15): total_intervals('d', NULL)
    #1 {main}
      thrown in script on line 2

Pour finir, il est possible de passer des arguments variables par référence en préfixant le mot clé `...` d'un ET commercial (`&`).

### Arguments Nommés

PHP 8.0.0 introduit les arguments nommés comme extension aux paramètres positionnels existants. Les arguments nommés permettent de passer les arguments à une fonction en s'appuyant sur le nom du paramètre, au lieu de la position du paramètre. Ceci documente automatiquement la signification de l'argument, rend l'ordre des arguments indépendant et permet d'ignorer les valeurs par défaut arbitrairement.

Les arguments nommés sont passés en préfixant la valeur avec le nom du paramètre suivi d'un deux-points. Utiliser des mots-clés réservés comme nom de paramètre est autorisé. Le nom du paramètre doit être un identifiant, le spécifiant de façon dynamique n'est pas permis.

Exemple #13 Syntaxe des arguments nommés

    <?php
    myFunction(paramName: $value);
    array_foobar(array: $value);

    // NON supporté.
    function_name($variableStoringParamName: $value);

Exemple #14 Arguments positionnels comparés aux arguments nommés

    <?php
    // Utilisant les arguments positionnels :
    array_fill(0, 100, 50);

    // Utilisant les arguments nommés :
    array_fill(start_index: 0, count: 100, value: 50);

L'ordre dans lequel les arguments nommés sont passés n'importe pas.

Exemple #15 Même exemple que ci-dessus, mais avec un ordre de paramètre différent

    <?php
    array_fill(value: 50, count: 100, start_index: 0);

Les arguments nommés peuvent être combinés avec les arguments positionnels. Auquel cas, les arguments nommés doivent venir après les arguments positionnels. Il est aussi possible de spécifier seulement certains des arguments optionnels d'une fonction, peu importe leur ordre.

Exemple #16 Combiner les arguments nommés avec les arguments positionnels

    <?php
    htmlspecialchars($string, double_encode: false);
    // Identique à
    htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);

Passer le même argument plusieurs fois résulte en une Error exception.

Exemple #17 Erreur déclenchée lorsqu'un argument est passé plusieurs fois au même paramètre nommé

    <?php
    function foo($param) { ... }

    foo(param: 1, param: 2);
    // Error: Named parameter $param overwrites previous argument

    foo(1, param: 2);
    // Error: Named parameter $param overwrites previous argument

À partir de PHP 8.1.0, il est possible d'utiliser des arguments nommés après avoir déballé les arguments. Un argument nommé ne doit pas écraser un argument déjà déballé.

Exemple #18 Utiliser les arguments nommés après le déballage

    <?php
    function foo($a, $b, $c = 3, $d = 4) {
      return $a + $b + $c + $d;
    }
    var_dump(foo(...[1, 2], d: 40)); // 46
    var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46
    var_dump(foo(...[1, 2], b: 20)); // Erreur fatale. Le paramètre nommé $b écrase l'argument précédent.

## Les valeurs de retour

Les valeurs sont renvoyées en utilisant une instruction de retour optionnelle. Tous les types de variables peuvent être renvoyés, tableaux et objets compris. Cela fait que la fonction finit son exécution immédiatement et passe le contrôle à la ligne appelante. Voir return pour plus d'informations.

> Note:

> Si return est omis, la valeur `null` sera retournée.

### Utilisation de return

Exemple #1 Utilisation de return

    <?php
    function carre($num)
    {
        return $num * $num;
    }
    echo carre(4); // Affiche '16'

Une fonction ne peut pas renvoyer plusieurs valeurs en même temps, mais il est possible d'obtenir le même résultat en renvoyant un tableau.

Exemple #2 Retourner un tableau d'une fonction

    <?php
    function petit_nombre()
    {
        return [0, 1, 2];
    }
    // La déconstruction d'un tableau collectera chaque membre du tableau individuellement
    [$zero, $one, $two] = petit_nombre();
    var_dump($zero, $one, $two);

    // Avant PHP 7.1, la seule alternative équivalente est en utilisant la structure de langage list()
    list ($zero, $un, $deux) = petit_nombre();

Pour retourner une référence d'une fonction, il faut utiliser l'opérateur & aussi bien dans la déclaration de la fonction que dans l'assignation de la valeur de retour.

Exemple #3 Retourner une référence d'une fonction

    <?php
    function &retourne_reference()
    {
        return $uneref;
    }

    $newref =& retourne_reference();

Pour plus d'informations sur les références, se référer à l'explication sur les références.

## Fonctions variables

PHP supporte le concept de fonctions variables. Cela signifie que si le nom d'une variable est suivi de parenthèses, PHP recherchera une fonction de même nom et essaiera de l'exécuter. Cela peut servir, entre autres, pour faire des fonctions de rappel, des tables de fonctions...

Les fonctions variables ne peuvent pas fonctionner avec les éléments de langage comme les echo, print, unset(), isset(), empty(), include, require etc. Il est nécessaire d'utiliser une gestion de fonctions personnalisée pour utiliser un de ces éléments de langage comme fonctions variables.

Exemple #1 Exemple de fonction variable

    <?php
    function foo() {
        echo "dans foo()\n";
    }

    function bar($arg = '')
    {
        echo "Dans bar(); l'argument était '$arg'.\n";
    }

    // Ceci est une fonction détournée de echo
    function echoit($string)
    {
        echo $string;
    }

    $func = 'foo';
    $func();        // Appel foo()

    $func = 'bar';
    $func('test');  // Appel bar()

    $func = 'echoit';
    $func('test');  // Appel echoit()

Il est aussi possible d'appeler les méthodes d'un objet en utilisant le système des fonctions variables.

Exemple #2 Exemple de méthode variable

    <?php
    class Foo
    {
        function Variable()
        {
            $name = 'Bar';
            $this->$name(); // Appelle la méthode Bar()
        }

        function Bar()
        {
            echo "C'est Bar";
        }
    }

    $foo = new Foo();
    $funcname = "Variable";
    $foo->$funcname();  // Appelle $foo->Variable()

Lors de l'appel à des méthodes statiques, l'appel de fonction est meilleur que l'opérateur de propriété statique :

Exemple #3 Exemple de méthode variable avec des propriétés statiques

    <?php
    class Foo
    {
        static $variable = 'static property';
        static function Variable()
        {
            echo "Method Variable called\n";
        }
    }

    echo Foo::$variable ."\n"; // Ceci affiche 'static property'. Il est nécessaire d'avoir une $variable dans le contexte.
    $variable = "Variable";
    Foo::$variable();  // Ceci appelle $foo->Variable(), lisant ainsi la $variable depuis le contexte.

L'exemple ci-dessus va afficher :

    static property
    Method Variable called

Exemple #4 callables complexes

    <?php
    class Foo
    {
        static function bar()
        {
            echo "bar\n";
        }
        function baz()
        {
            echo "baz\n";
        }
    }

    $func = array("Foo", "bar");
    $func(); // Affiche "bar"
    $func = array(new Foo, "baz");
    $func(); // Affiche "baz"
    $func = "Foo::bar";
    $func(); // Affiche "bar"

### Voir aussi

- is_callable()
- call_user_func()
- function_exists()
- Les variables variable

## Fonctions internes

PHP dispose de nombreuses fonctions et structures standards. Il y a aussi des fonctions qui requièrent des extensions spécifiques de PHP, sans lesquelles l'erreur fatale `undefined function` sera obtenue. Par exemple, pour utiliser les fonctions d'images, telles que imagecreatetruecolor(), le support de GD dans PHP est nécessaire. Ou bien, pour utiliser mysqli_connect(), l'extension MySQLi est requise. Il y a des fonctions de base qui sont incluses dans toutes les versions de PHP, telles que les fonctions de chaînes de caractères et les fonctions de variables. Utiliser phpinfo() ou get_loaded_extensions() pour savoir quelles sont les extensions qui sont compilées avec PHP. Il est à noter que de nombreuses extensions sont activées par défaut, et que le manuel PHP est compartimenté par extension. Voir les chapitres de configuration, installation ainsi que les détails particuliers à chaque extension, pour savoir comment les mettre en place.

Lire et comprendre le prototype d'une fonction est décrit dans l'annexe Comment lire la définition d'une fonction (prototype). Il est important de comprendre ce qu'une fonction retourne, ou si une fonction travaille directement sur la valeur des paramètres fournis. Par exemple, str_replace() va retourner une chaîne modifiée, tandis que usort() travaille directement sur la variable passée en paramètre. Chaque page du manuel a des informations spécifiques sur chaque fonction, comme le nombre de paramètres, les évolutions de spécifications, les valeurs retournées en cas de succès ou d'échec, et la disponibilité en fonction des versions. Bien connaître ces différences, parfois subtiles, est crucial pour bien programmer en PHP.

> Note: Si les paramètres donnés à une fonction ne sont pas corrects, comme le fait de passer un tableau alors qu'une chaîne de caractères est attendue, la valeur retournée de la fonction est indéfinie. Dans ce cas, la fonction retournera la plupart du temps une valeur `null` mais ce n'est juste qu'une convention et ne peut être considéré comme une certitude. À partir de PHP 8.0.0, une exception TypeError est normalement lancée dans ce cas.

> Note:

> En mode coercitif, les types scalaires des fonctions internes sont nullables par défaut. À partir de PHP 8.1.0, passer `null` à un paramètre de fonction interne qui n'est pas déclaré nullable est déconseillé et émet une notice de dépréciation en mode coercitif pour s'aligner sur le comportement des fonctions définies par l'utilisateur, où les types scalaires doivent être marqués comme nullables explicitement.

> Par exemple, la fonction strlen() attend que le paramètre `$string` soit de type chaîne de caractères et non `null`. Pour des raisons historiques, PHP autorise le passage de `null` pour ce paramètre en mode coercitif. Le paramètre est alors implicitement converti en string, résultant en une valeur `""`. En revanche, une TypeError est émise en mode strict.

>     <?php
>     var_dump(strlen(null));
>     // "Deprecated: Passing null to parameter #1 ($string) of type string is deprecated" as of PHP 8.1.0
>     // int(0)

>     var_dump(str_contains("foobar", null));
>     // "Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated" as of PHP 8.1.0
>     // bool(true)

### Voir aussi

- function_exists()
- l'index des fonctions
- get_extension_funcs()
- dl()

## Fonctions anonymes

Les fonctions anonymes, aussi appelées fermetures ou `closures` permettent la création de fonctions sans préciser leur nom. Elles sont particulièrement utiles comme fonctions de rappel callable, mais leur utilisation n'est pas limitée à ce seul usage.

Les fonctions anonymes sont implémentées en utilisant la classe Closure.

Exemple #1 Exemples avec des fonctions anonymes

    <?php
    echo preg_replace_callback('~-([a-z])~', function ($match) {
        return strtoupper($match[1]);
    }, 'bonjour-le-monde');
    // affiche bonjourLeMonde

Les fonctions anonymes peuvent aussi être utilisées comme valeurs de variables. PHP va automatiquement convertir ces expressions en objets Closure. Assigner une fermeture à une variable est la même chose qu'une affectation classique, y compris pour le point-virgule final.

Exemple #2 Assignation de fonction anonyme à une variable

    <?php
    $greet = function($name) {
        printf("Bonjour %s\r\n", $name);
    };

    $greet('World');
    $greet('PHP');

Les fonctions anonymes peuvent hériter des variables du contexte de leur parent. Ces variables doivent alors être passées dans la construction de langage `use`. À partir de PHP 7.1, ces variables ne doivent pas inclure de superglobals, $this, ou des variables ayant le même nom qu'un paramètre. Une déclaration de type de retour pour la fonction doit être placée après la clause `use`.

Exemple #3 Héritage de variable depuis le contexte parent

    <?php
    $message = 'hello';

    // Pas de "use"
    $example = function () {
        var_dump($message);
    };
    $example();

    // Hérite $message
    $example = function () use ($message) {
        var_dump($message);
    };
    $example();

    // La valeur de la variable héritée est définie lorsque la fonction est
    // définie non quand elle est appelée
    $message = 'world';
    $example();

    // Réinitialisation de la variable message
    $message = 'hello';

    // Héritage par référence
    $example = function () use (&$message) {
        var_dump($message);
    };
    $example();

    // Le changement de valeur dans le contexte parent est reflété lors de
    // l'appel de la fonction.
    $message = 'world';
    $example();

    // Les fonctions anonymes acceptent également des arguments classiques
    $example = function ($arg) use ($message) {
        var_dump($arg . ' ' . $message);
    };
    $example("hello");

    // La déclaration du type de retour vient après la clause use
    $example = function () use ($message): string {
        return "hello $message";
    };
    var_dump($example());

Résultat de l'exemple ci-dessus est similaire à :

    Notice: Undefined variable: message in /example.php on line 6
    NULL
    string(5) "hello"
    string(5) "hello"
    string(5) "hello"
    string(5) "world"
    string(11) "hello world"
    string(11) "hello world"

À partir de PHP 8.0.0, la liste des variables héritées du contexte peut inclure une virgule finale, qui sera ignorée.

L'héritage du contexte parent n'est pas la même chose que les variables de l'environnement global. Les variables globales existent dans le contexte global, qui est le même, quelle que soit la fonction qui s'exécute. Le contexte parent d'une fonction anonyme est la fonction dans laquelle la fonction a été déclarée (pas nécessairement celle qui appelle). Voir l'exemple ci-dessous :

Exemple #4 Fonctions anonymes et contexte

    <?php
    // Un panier d'achat simple, qui contient une liste de produits
    // choisis et la quantité désirée de chaque produit. Il inclut
    // une méthode qui calcule le prix total des éléments dans le panier
    // en utilisant une fonction de rappel anonyme.
    class Panier
    {
        const PRICE_BEURRE  = 1.00;
        const PRICE_LAIT    = 3.00;
        const PRICE_OEUF    = 6.95;

        protected $products = array();

        public function add($product, $quantity)
        {
            $this->products[$product] = $quantity;
        }

        public function getQuantity($product)
        {
            return isset($this->products[$product]) ? $this->products[$product] :
                   FALSE;
        }

        public function getTotal($tax)
        {
            $total = 0.00;

            $callback =
                function ($quantity, $product) use ($tax, &$total)
                {
                    $pricePerItem = constant(__CLASS__ . "::PRICE_" .
                        strtoupper($product));
                    $total += ($pricePerItem * $quantity) * ($tax + 1.0);
                };

            array_walk($this->products, $callback);
            return round($total, 2);
        }
    }

    $mon_panier = new Panier;

    // Ajout d'élément au panier
    $mon_panier->add('beurre', 1);
    $mon_panier->add('lait', 3);
    $mon_panier->add('oeuf', 6);

    // Affichage du prix avec 5.5% de TVA
    print $mon_panier->getTotal(0.055) . "\n";
    // Le résultat sera 54.29

Exemple #5 Liage automatique de `$this`

    <?php
    class Test
    {
        public function testing()
        {
            return function() {
                var_dump($this);
            };
        }
    }

    $object = new Test;
    $function = $object->testing();
    $function();

L'exemple ci-dessus va afficher :

    object(Test)#1 (0) {
    }

Lorsque déclarée dans le contexte d'une classe, la classe courante est automatiquement liée, la rendant `$this` disponible dans le contexte de la fonction. Si ce liage automatique de la classe courante n'est pas souhaité, alors les fonctions anonymes statiques peuvent être utilisées à la place.

### Les fonctions anonymes statiques

Les fonctions anonymes peuvent être déclarées statiquement. Ceci permet de ne pas lier automatiquement la classe courante à la fonction. Les objets peuvent aussi ne pas être liés lors de l'exécution.

Exemple #6 Tentative d'usage de `$this` dans une fonction anonyme statique

    <?php
    class Foo
    {
        function __construct()
        {
            $func = static function() {
                var_dump($this);
            };
            $func();
        }
    };
    new Foo();

L'exemple ci-dessus va afficher :

    Fatal error: Uncaught Error: Using $this when not in object context in script:7
    Stack trace:
    #0 script(9): Foo::{closure:Foo::__construct():6}()
    #1 script(12): Foo->__construct()
    #2 {main}
      thrown in script on line 7

Exemple #7 Tentative de liage d'un objet à une fonction anonyme statique

    <?php
    $func = static function() {
        // corps de la fonction
    };
    $func = $func->bindTo(new stdClass);
    $func();

L'exemple ci-dessus va afficher :

    Warning: Cannot bind an instance to a static closure, this will be an error in PHP 9 in script on line 5

    Fatal error: Uncaught Error: Value of type null is not callable in script:6
    Stack trace:
    #0 {main}
      thrown in script on line 6

### Historique

Version | Description
--- | ---
8.3.0 | Les fermetures créées à partir des méthodes magiques peuvent accepter des paramètres nommés.
7.1.0 | Les fonctions anonymes peuvent ne pas se fermer sur les superglobals, $this, ou toute variable avec le même nom qu'un paramètre.

### Notes

> Note: Il est possible d'utiliser les fonctions func_num_args(), func_get_arg() et func_get_args() dans une fonction anonyme.

## Fonction Fléchée

Les fonctions fléchées ont été introduites en PHP 7.4 en tant que syntaxe plus concise pour les fonctions anonymes.

Les fonctions anonymes comme les fonctions fléchées sont implémentées en utilisant la classe Closure.

Les fonctions fléchées ont la forme basique `fn (argument_list) => expr`.

Les fonctions fléchées supportent les mêmes fonctionnalités que les fonctions anonymes, à l'exception que l'utilisation des variables de la portée parente est automatique.

Quand une variable utilisée dans l'expression est définie dans la portée parente, elle sera implicitement capturée par valeur. Dans l'exemple suivant, les fonctions $fn1 et $fn2 se comportent de façon identique.

Exemple #1 Les fonctions fléchées capturent les variables par valeur automatiquement

    <?php
    $y = 1;

    $fn1 = fn($x) => $x + $y;
    // équivalent à utiliser $y par valeur :
    $fn2 = function ($x) use ($y) {
        return $x + $y;
    };

    var_export($fn1(3));

L'exemple ci-dessus va afficher :

    4

Ceci fonctionne aussi si les fonctions fléchées sont imbriquées :

Exemple #2 Les fonctions fléchées capturent les variables par valeur automatiquement, même imbriquées

    <?php
    $z = 1;
    $fn = fn($x) => fn($y) => $x * $y + $z;
    // Affiche 51
    var_export($fn(5)(10));

Similairement aux fonctions anonymes, la syntaxe des fonctions fléchées permet les signatures de fonction arbitraire, ceci inclut les types de paramètres et de retour, valeur par défaut, variable, aussi bien que le passage et retour par référence. Tous les exemples suivants sont des fonctions fléchées valides :

Exemple #3 Exemples de fonctions fléchées

    <?php
    fn(array $x) => $x;
    static fn($x): int => $x;
    fn($x = 42) => $x;
    fn(&$x) => $x;
    fn&($x) => $x;
    fn($x, ...$rest) => $rest;

Les fonctions fléchées lient les variables par valeur. Ceci est à peu près équivalent à effectuer un `use($x)` pour chaque variable $x utilisée à l'intérieur de la fonction fléchée. Un liage par valeur signifie qu'il n'est pas possible de modifier une valeur de la portée extérieure. Les fonctions anonymes peuvent être utilisées à la place pour des liaisons par référence.

Exemple #4 Valeurs de la portée extérieure ne peuvent pas être modifiées par les fonctions fléchées

    <?php
    $x = 1;
    $fn = fn() => $x++; // N'a aucun effet
    $fn();
    var_export($x);  // Affiche 1

### Historique

Version | Description
--- | ---
7.4.0 | Les fonctions fléchées sont désormais disponibles.

### Notes

> Note: Il est possible d'utiliser func_num_args(), func_get_arg(), et func_get_args() depuis l'intérieur d'une fonction fléchée.

## Syntaxe callable de première classe

La syntaxe de callable de première classe est introduite à partir de PHP 8.1.0, comme une manière de créer des fonctions anonymes depuis des callable. Elle remplace la syntaxe des callables existante utilisant les chaînes et tableaux. L'avantage de cette syntaxe est qu'elle est accessible à l'analyse statique et utilise la portée du point où le callable est acquis.

La syntaxe `CallableExpr(...)` est utilisée pour créer un objet Closure depuis le callable. `CallableExpr` accepte toute expression qui peut être directement appelée dans la grammaire de PHP :

Exemple #1 Syntaxe callable de première classe basique

    <?php
    class Foo {
       public function method() {}
       public static function staticmethod() {}
       public function __invoke() {}
    }
    $obj = new Foo();
    $classStr = 'Foo';
    $methodStr = 'method';
    $staticmethodStr = 'staticmethod';
    $f1 = strlen(...);
    $f2 = $obj(...);  // objet invocable
    $f3 = $obj->method(...);
    $f4 = $obj->$methodStr(...);
    $f5 = Foo::staticmethod(...);
    $f6 = $classStr::$staticmethodStr(...);
    // callable traditionnel utilisant une chaîne, un tableau
    $f7 = 'strlen'(...);
    $f8 = [$obj, 'method'](...);
    $f9 = [Foo::class, 'staticmethod'](...);

> Note:

> Les `...` font partie de la syntaxe et ne sont pas une omission.

`CallableExpr(...)` a les mêmes sémantiques que Closure::fromCallable(). C'est-à-dire, contrairement aux callables utilisant les chaînes et tableaux, `CallableExpr(...)` respecte la portée du point où il est créé :

Exemple #2 Comparaison de portée de `CallableExpr(...)` et des callables traditionnels

    <?php
    class Foo {
        public function getPrivateMethod() {
            return [$this, 'privateMethod'];
        }
        private function privateMethod() {
            echo __METHOD__, "\n";
        }
    }
    $foo = new Foo;
    $privateMethod = $foo->getPrivateMethod();
    $privateMethod();
    // Erreur fatale : Call to private method Foo::privateMethod() from global scope
    // Ceci est dû au fait que l'appel est effectué en dehors de Foo et la visibilité sera vérifiée depuis ce point.

    <?php
    class Foo1 {
        public function getPrivateMethod() {
            // Utilise la portée où le callable est acquis.
            return $this->privateMethod(...); // identique à Closure::fromCallable([$this, 'privateMethod']);
        }
        private function privateMethod() {
            echo __METHOD__, "\n";
        }
    }
    $foo1 = new Foo1;
    $privateMethod = $foo1->getPrivateMethod();
    $privateMethod();  // Foo1::privateMethod

> Note:

> La création d'objets avec cette syntaxe (e.g `new Foo(...)`) n'est pas supportée, car la syntaxe `new Foo()` n'est pas considérée comme un appel.

> Note:

> La syntaxe de callable de première classe ne peut pas être combinée avec l'opérateur nullsafe. Les deux cas suivants entraînent une erreur de compilation :

>     <?php
>     $obj?->method(...);
>     $obj?->prop->method(...);

# Les classes et les objets

## Sommaire

- Introduction
- Syntaxe de base
- Propriétés
- Hooks de propriété
- Constantes de classe
- Auto-chargement de classes
- Constructeurs et destructeurs
- Visibilité
- Héritage
- L'opérateur de résolution de portée (::)
- Statique
- Abstraction de classes
- Interfaces
- Traits
- Classes anonymes
- Surcharge magique
- Parcours d'objets
- Méthodes magiques
- Mot-clé "final"
- Clonage d'objets
- Comparaison d'objets
- Late Static Bindings (Résolution statique à la volée)
- Objets et références
- Sérialisation d'objets
- Covariance et Contravariance
- Objets paresseux
- Modifications en POO (Programmation orientée objet)

## Introduction

PHP inclut un modèle objet complet. Certaines de ses fonctionnalités sont : la visibilité, les classes et méthodes abstraites et finales mais aussi les méthodes magiques, les interfaces, et le clonage.

PHP traite les objets de la même manière que les références ou les gestionnaires, ce qui signifie que chaque variable contient une référence vers l'objet plutôt qu'une copie de l'objet complet. Voir Objets et Références.

Astuce

Jetez un oeil sur Guide de nommage de l'espace utilisateur.

## Syntaxe de base

### class

Une définition de classe basique commence par le mot-clé `class`, suivi du nom de la classe. Suit une paire d'accolades contenant la définition des propriétés et des méthodes appartenant à la classe.

Le nom de la classe peut être quelconque à condition que ce ne soit pas un mot réservé en PHP. À partir de PHP 8.4.0, l'utilisation d'un seul underscore `_` comme nom de classe est obsolète. Un nom de classe valide commence par une lettre ou un underscore, suivi de n'importe quel nombre de lettres, chiffres ou underscores. En tant qu'expression régulière, cela serait exprimé ainsi : `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`.

Une classe peut contenir ses propres constantes, variables (appelées "propriétés" ou "attributs"), et fonctions (appelées "méthodes").

Exemple #1 Définition typique d'une classe

    <?php
    class SimpleClass
    {
        // déclaration d'une propriété
        public $var = 'une valeur par défaut';

        // déclaration des méthodes
        public function displayVar() {
            echo $this->var;
        }
    }
    ?>

La pseudo-variable $this est disponible lorsqu'une méthode est appelée depuis un contexte objet. $this est la valeur de l'objet appelant.

Avertissement

Appeler une méthode non-statique statiquement lance une Error. Avant PHP 8.0.0, ceci générait une notice d'obsolescence, et $this était indéfini.

Exemple #2 Quelques exemples de la pseudo-variable $this

    <?php
    class A
    {
        function foo()
        {
            if (isset($this)) {
                echo '$this is defined (';
                echo get_class($this);
                echo ")\n";
            } else {
                echo "\$this is not defined.\n";
            }
        }
    }

    class B
    {
        function bar()
        {
            A::foo();
        }
    }

    $a = new A();
    $a->foo();

    A::foo();

    $b = new B();
    $b->bar();

    B::bar();
    ?>

Résultat de l'exemple ci-dessus en PHP 7 :

    $this is defined (A)

    Deprecated: Non-static method A::foo() should not be called statically in %s on line 27
    $this is not defined.

    Deprecated: Non-static method A::foo() should not be called statically in %s on line 20
    $this is not defined.

    Deprecated: Non-static method B::bar() should not be called statically in %s on line 32

    Deprecated: Non-static method A::foo() should not be called statically in %s on line 20
    $this is not defined.

Résultat de l'exemple ci-dessus en PHP 8 :

    $this is defined (A)

    Fatal error: Uncaught Error: Non-static method A::foo() cannot be called statically in %s :27
    Stack trace:
    #0 {main}
      thrown in %s on line 27

#### Classes en lecture seule (readonly)

À partir de PHP 8.2.0, une classe peut être marquée avec le modificateur readonly. Marquer une classe comme readonly ajoutera le modificateur readonly à chaque propriété déclarée, et empêchera la création de propriétés dynamiques. En outre, il est impossible d'ajouter leur prise en charge en utilisant l'attribut AllowDynamicProperties. Toute tentative de le faire déclenchera une erreur de compilation.

    <?php
    #[\AllowDynamicProperties]
    readonly class Foo {
    }

    // Erreur fatale : Cannot apply #[AllowDynamicProperties] to readonly class Foo
    ?>

Comme ni les propriétés non typées ni les propriétés statiques ne peuvent être marquées avec le modificateur `readonly`, les classes readonly ne peuvent pas non plus les déclarer :

    <?php
    readonly class Foo
    {
        public $bar;
    }

    // Erreur fatale : Readonly property Foo::$bar must have type
    ?>

    <?php
    readonly class Foo
    {
        public static int $bar;
    }

    // Erreur fatale : Readonly class Foo cannot declare static properties
    ?>

Une classe readonly peut être étendue si, et seulement si, la classe enfant est également une classe readonly.

### Le mot-clé `new`

Pour créer une instance d'une classe, le mot-clé `new` doit être utilisé. Un objet sera alors systématiquement créé, à moins qu'il ait un constructeur défini qui lance une exception en cas d'erreur. Les classes devraient être définies avant l'instanciation (dans certains cas, c'est impératif).

Si une variable string contenant un nom de classe est utilisée avec `new`, une nouvelle instance de cette classe sera créée. Si la classe est dans un espace de noms, son nom pleinement qualifié doit être utilisé.

> Note:

> S'il n'y a pas d'arguments à passer au constructeur de la classe, les parenthèses après le nom de la classe peuvent être omises.

Exemple #3 Création d'une instance

    <?php

    class SimpleClass {
    }

    $instance = new SimpleClass();
    var_dump($instance);

    // Ceci peut également être réalisé avec une variable :
    $className = 'SimpleClass';
    $instance = new $className(); // new SimpleClass()
    var_dump($instance);
    ?>

À partir de PHP 8.0.0, l'utilisation de `new` avec des expressions arbitraires est supportée. Ceci permet des instanciations plus complexes si l'expression produit une string. L'expression doit être entourée de parenthèses.

Exemple #4 Créer une instance en utilisant une expression arbitraire

Dans l'exemple donné, nous montrons plusieurs exemples d'expressions arbitraires valides qui produisent un nom de classe. Ceci montre un appel de fonction, une concaténation de chaînes et la constante `::class`.

    <?php

    class ClassA extends \stdClass {}
    class ClassB extends \stdClass {}
    class ClassC extends ClassB {}
    class ClassD extends ClassA {}

    function getSomeClass(): string
    {
        return 'ClassA';
    }

    var_dump(new (getSomeClass()));
    var_dump(new ('Class' . 'B'));
    var_dump(new ('Class' . 'C'));
    var_dump(new (ClassD::class));
    ?>

Résultat de l'exemple ci-dessus en PHP 8 :

    object(ClassA)#1 (0) {
    }
    object(ClassB)#1 (0) {
    }
    object(ClassC)#1 (0) {
    }
    object(ClassD)#1 (0) {
    }

Dans le contexte de la classe, il est possible de créer un nouvel objet avec `new self` et `new parent`.

Lors de l'assignation d'une instance déjà créée d'une classe à une variable, la nouvelle variable accédera à la même instance que l'objet qui a été assigné. Ce comportement est le même lors du passage d'une instance à une fonction. Une copie d'un objet déjà créé peut être effectuée par clonage.

Exemple #5 Assignation d'un objet

    <?php
    class SimpleClass {
        public string $var;
    }

    $instance = new SimpleClass();

    $assigned   =  $instance;
    $reference  =& $instance;

    $instance->var = '$assigned aura cette valeur';

    $instance = null; // $instance et $reference deviennent null

    var_dump($instance);
    var_dump($reference);
    var_dump($assigned);
    ?>

L'exemple ci-dessus va afficher :

    NULL
    NULL
    object(SimpleClass)#1 (1) {
       ["var"]=>
         string(27) "$assigned aura cette valeur"
    }

Il est possible de créer une instance d'un objet de quelques manières différentes :

Exemple #6 Créer de nouveaux objets

    <?php

    class Test
    {
        public static function getNew()
        {
            return new static();
        }
    }

    class Child extends Test {}

    $obj1 = new Test(); // Par le nom de la classe
    $obj2 = new $obj1(); // À travers la variable contenant un objet
    var_dump($obj1 !== $obj2);

    $obj3 = Test::getNew(); // Par la méthode de classe
    var_dump($obj3 instanceof Test);

    $obj4 = Child::getNew(); // À travers une méthode de classe enfant
    var_dump($obj4 instanceof Child);

    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(true)

Il est possible d'accéder à un membre d'un objet nouvellement créé en une seule expression :

Exemple #7 Accéder à un membre d'un objet nouvellement créé

    <?php
    echo (new DateTime())->format('Y'), PHP_EOL;

    // les parenthèses autour sont optionnelles à partir de PHP 8.4.0
    echo new DateTime()->format('Y'), PHP_EOL;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    2025
    2025

> Note: Avant PHP 7.1, les arguments ne sont pas évalués s'il n'y a pas de fonction constructeur définie.

### Propriétés et méthodes

Les propriétés et méthodes de classe vivent dans des "espaces de noms" séparés, donc il est possible d'avoir une propriété et une méthode avec le même nom. Faire référence à la fois à une propriété et à une méthode utilise la même notation, et le fait qu'une propriété sera accédée ou qu'une méthode sera appelée, dépend seulement du contexte, c'est-à-dire si l'utilisation est un accès variable ou un appel de fonction.

Exemple #8 Accès de propriété contre appel de méthode

    <?php
    class Foo
    {
        public $bar = 'property';

        public function bar() {
            return 'method';
        }
    }

    $obj = new Foo();
    echo $obj->bar, PHP_EOL, $obj->bar(), PHP_EOL;

L'exemple ci-dessus va afficher :

    property
    method

Ceci signifie qu'appeler une fonction anonyme qui a été assignée à une propriété n'est pas possible directement. Au lieu de cela, la propriété doit d'abord être affectée à une variable. Il est possible d'appeler ce genre de propriété directement en la mettant entre parenthèses.

Exemple #9 Appeler une fonction anonyme enregistrée dans une propriété

    <?php
    class Foo
    {
        public $bar;

        public function __construct() {
            $this->bar = function() {
                return 42;
            };
        }
    }

    $obj = new Foo();

    echo ($obj->bar)(), PHP_EOL;

L'exemple ci-dessus va afficher :

    42

### Le mot-clé `extends`

Une classe peut hériter des constantes, méthodes et des propriétés d'une autre classe en utilisant le mot-clé `extends` dans la déclaration. Il n'est pas possible d'étendre plusieurs classes : une classe peut uniquement hériter d'une seule classe de base.

Les constantes, méthodes et propriétés héritées peuvent être redéfinies en les redéclarant avec le même nom que dans la classe parente. Cependant, si la classe parente a défini une méthode ou constante comme final, alors celles-ci ne peuvent pas être redéfinies. Il est possible d'accéder aux méthodes ou propriétés statiques redéfinies en y faisant référence avec l'opérateur parent::.

> Note: À partir de PHP 8.1.0, les constantes peuvent être déclarées comme finales.

Exemple #10 Héritage simple d'une classe

    <?php
    class SimpleClass
    {
        function displayVar()
        {
            echo "Classe parente\n";
        }
    }

    class ExtendClass extends SimpleClass
    {
      // Redéfinition de la méthode parente
      function displayVar()
      {
        echo "Classe étendue\n";
        parent::displayVar();
      }
    }

    $extended = new ExtendClass();
    $extended->displayVar();
    ?>

L'exemple ci-dessus va afficher :

    Classe étendue
    Classe parente

#### Règles de compatibilité de signature

Lors de la surcharge d'une méthode, sa signature doit être compatible avec la méthode parente. Sinon, une erreur fatale est émise, ou, antérieur à PHP 8.0.0, une erreur de niveau `E_WARNING` est générée. Une signature est compatible si elle respecte les règles de variance, rend un paramètre obligatoire optionnel, et seulement si tous les nouveaux paramètres sont optionnels et assouplissent les règles de visibilité. Ceci est connu sous le Principe de Substitution de Liskov (Liskov Substitution Principle), ou simplement LSP. Le constructeur, et les méthodes `private` sont exclus de ces règles de compatibilité des signatures, et par conséquent n'émettront pas d'erreur fatale en cas de signature incompatible.

Exemple #11 Méthodes enfant compatibles

    <?php
    class Base
    {
        public function foo(int $a) {
            echo "Valid\n";
        }
    }
    class Extend1 extends Base
    {
        function foo(int $a = 5)
        {
            parent::foo($a);
        }
    }
    class Extend2 extends Base
    {
        function foo(int $a, $b = 5)
        {
            parent::foo($a);
        }
    }
    $extended1 = new Extend1();
    $extended1->foo();
    $extended2 = new Extend2();
    $extended2->foo(1);

L'exemple ci-dessus va afficher :

    Valid
    Valid

Les exemples suivants démontrent qu'une méthode enfant qui supprime un paramètre, ou rend un paramètre optionnel obligatoire, n'est pas compatible avec la méthode parente.

Exemple #12 Erreur fatale quand une méthode enfant supprime un paramètre

    <?php
    class Base
    {
        public function foo(int $a = 5) {
            echo "Valid\n";
        }
    }
    class Extend extends Base
    {
        function foo()
        {
            parent::foo(1);
        }
    }

Résultat de l'exemple ci-dessus en PHP 8 est similaire à :

    Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13

Exemple #13 Erreur fatale quand une méthode enfant rend un paramètre optionnel obligatoire

    <?php
    class Base
    {
        public function foo(int $a = 5) {
            echo "Valid\n";
        }
    }
    class Extend extends Base
    {
        function foo(int $a)
        {
            parent::foo($a);
        }
    }

Résultat de l'exemple ci-dessus en PHP 8 est similaire à :

    Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13

Avertissement

Renommer un paramètre d'une méthode dans une classe enfant n'est pas une incompatibilité de signature. Cependant, ceci est déconseillé car cela résultera en une Error à l'exécution si les arguments nommés sont utilisés.

Exemple #14 Erreur lors de l'utilisation des arguments nommés et que les paramètres ont été renommés dans une classe enfant

    <?php
    class A {
        public function test($foo, $bar) {}
    }
    class B extends A {
        public function test($a, $b) {}
    }
    $obj = new B;
    // Passe les paramètres selon le contrat de A::test()
    $obj->test(foo: "foo", bar: "bar"); // ERREUR !

Résultat de l'exemple ci-dessus est similaire à :

    Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14
    Stack trace:
    #0 {main}
      thrown in /in/XaaeN on line 14

### ::class

Le mot-clé `class` est également utilisé pour la résolution des noms de classes. Il est possible d'obtenir le nom pleinement qualifié d'une classe `ClassName` en utilisant `ClassName::class`. C'est particulièrement utile avec les classes utilisant des espaces de noms.

Exemple #15 Résolution de nom de classe

    <?php
    namespace NS {
        class ClassName {
        }

        echo ClassName::class;
    }
    ?>

L'exemple ci-dessus va afficher :

    NS\ClassName

> Note:

> La résolution du nom de classe en utilisant `::class` est une transformation lors de la compilation. C'est-à-dire qu'à l'instant où la chaîne du nom de classe est créée aucun autochargement n'a encore eu lieu. Par conséquent, les noms de classes sont étendus même si la classe n'existe pas. Aucune erreur n'est émise dans ce cas-là.

> Exemple #16 Résolution de nom de classe manquante

>     <?php
>     print Does\Not\Exist::class;
>     ?>

> L'exemple ci-dessus va afficher :

>     Does\Not\Exist

À partir de PHP 8.0.0, `::class` peut être utilisé sur les objets. Cette résolution se produit lors de l'exécution, et non lors de la compilation. Ses effets sont les mêmes que d'appeler get_class() sur l'objet.

Exemple #17 Résolution du nom d'un objet

    <?php
    namespace NS {
        class ClassName {
        }

        $c = new ClassName();
        print $c::class;
    }
    ?>

L'exemple ci-dessus va afficher :

    NS\ClassName

### Méthodes et propriétés nullsafe

À partir de PHP 8.0.0, les méthodes et propriétés peuvent aussi être accédées avec l'opérateur "nullsafe" : `?->`. L'opérateur nullsafe fonctionne de la même manière que l'accès de propriétés ou méthodes comme ci-dessus, à l'exception que si l'objet qui est déréférencé est `null` alors `null` sera retourné au lieu de lancer une exception. Si le déréférencement fait partie d'une chaîne, le reste de la chaîne est ignoré.

L'effet est similaire à entourer chaque accès par une vérification avec is_null() d'abord, mais plus compact.

Exemple #18 Opérateur nullsafe

    <?php

    // À partir de PHP 8.0.0, cette ligne:
    $result = $repository?->getUser(5)?->name;

    // Est équivalente au bloc de code suivant :
    if (is_null($repository)) {
        $result = null;
    } else {
        $user = $repository->getUser(5);
        if (is_null($user)) {
            $result = null;
        } else {
            $result = $user->name;
        }
    }
    ?>

> Note:

> L'opérateur nullsafe est mieux utilisé quand null est considéré comme une valeur valide et potentiellement attendu pour une propriété ou valeur de retour d'une méthode. Pour indiquer une erreur, lancer une exception est préférable.

## Propriétés

Les variables au sein d'une classe sont appelées propriétés. On peut également les retrouver sous d'autres dénominations telles que champs, mais pour cette documentation propriété sera utilisé. Elles sont définies en utilisant au moins un modificateur (tel que Visibilité, Statique, ou, à partir de PHP 8.1.0, readonly), suivi optionnellement (sauf pour les propriétés `readonly`), à partir de PHP 7.4, d'une déclaration de type, suivi d'une déclaration classique de variable. Cette déclaration peut comprendre une initialisation, mais celle-ci doit être une valeur constante.

> Note:

> Une manière obsolète de déclarer une propriété de classe est d'utiliser le mot-clé `var` au lieu d'un modificateur.

> Note: Une propriété déclarée sans modificateur de Visibilité sera déclarée comme `public`.

Au sein des méthodes de classes, les propriétés non statiques peuvent être appelées en utilisant la syntaxe `->` (opérateur de l'objet) : $this->property (où `property` est le nom de la propriété). Les propriétés statiques peuvent être appelées en utilisant la syntaxe `::` (deux doubles points) : self::$property. Se reporter à la documentation sur Statique pour plus d'informations sur la différence entre les propriétés statiques et non statiques.

La pseudo-variable $this est disponible au sein de n'importe quelle méthode, lorsque cette méthode est appelée au sein d'un objet. $this est la valeur de l'objet appelant.

Exemple #1 Déclarations de propriétés

    <?php
    class SimpleClass
    {
       public $var1 = 'hello ' . 'world';
       public $var2 = <<<EOD
    hello world
    EOD;
       public $var3 = 1+2;
       // déclarations de propriétés invalides :
       public $var4 = self::myStaticMethod();
       public $var5 = $myVar;

       // Déclarations valides de propriétés :
       public $var6 = myConstant;
       public $var7 = [true, false];
       public $var8 = <<<'EOD'
    hello world
    EOD;

       // Sans modificateur de visibilité :
       static $var9;
       readonly int $var10;
    }
    ?>

> Note:

> Il existe des fonctions diverses qui permettent de gérer des classes et des objets. Voir la référence sur les Fonctions Classes/Objets.

### Déclarations des types

À partir de PHP 7.4.0, les définitions de propriétés peuvent inclure une Déclarations de type, avec l'exception du type callable.

Exemple #2 Exemple de propriétés typées

    <?php

    class User
    {
        public int $id;
        public ?string $name;

        public function __construct(int $id, ?string $name)
        {
            $this->id = $id;
            $this->name = $name;
        }
    }

    $user = new User(1234, null);

    var_dump($user->id);
    var_dump($user->name);

    ?>

L'exemple ci-dessus va afficher :

    int(1234)
    NULL

Les propriétés typées doivent être initialisées avant d'y accéder, sinon, une Error sera émise.

Exemple #3 Accès aux propriétés

    <?php

    class Shape
    {
        public int $numberOfSides;
        public string $name;

        public function setNumberOfSides(int $numberOfSides): void
        {
            $this->numberOfSides = $numberOfSides;
        }

        public function setName(string $name): void
        {
            $this->name = $name;
        }

        public function getNumberOfSides(): int
        {
            return $this->numberOfSides;
        }

        public function getName(): string
        {
            return $this->name;
        }
    }

    $triangle = new Shape();
    $triangle->setName("triangle");
    $triangle->setNumberofSides(3);
    var_dump($triangle->getName());
    var_dump($triangle->getNumberOfSides());

    $circle = new Shape();
    $circle->setName("circle");
    var_dump($circle->getName());
    var_dump($circle->getNumberOfSides());
    ?>

L'exemple ci-dessus va afficher :

    string(8) "triangle"
    int(3)
    string(6) "circle"

    Fatal error: Uncaught Error: Typed property Shape::$numberOfSides must not be accessed before initialization

### Propriétés en lecture seule (readonly)

À partir de PHP 8.1.0, une propriété peut être déclarée avec le modificateur `readonly`, qui empêche la modification de la propriété après l'initialisation. Avant PHP 8.4.0 une propriété `readonly` est implicitement privée-modifiable, et ne peut être écrite que depuis la même classe. À partir de PHP 8.4.0, les propriétés `readonly` sont implicitement `protected(set)`, elles peuvent donc être définies depuis des classes enfants. Cela peut être remplacé explicitement si désiré.

Exemple #4 Exemple de propriétés en lecture seule

    <?php

    class Test {
       public readonly string $prop;

       public function __construct(string $prop) {
           // Initialisation légale.
           $this->prop = $prop;
       }
    }

    $test = new Test("foobar");
    // Lecture légale.
    var_dump($test->prop); // string(6) "foobar"

    // Réaffectation illégale. Peu importe que la valeur assignée soit identique.
    $test->prop = "foobar";
    // Erreur : Cannot modify readonly property Test::$prop
    ?>

> Note:

> Le modificateur de lecture seule ne peut être appliqué qu'aux propriétés typées. Une propriété en lecture seule sans contrainte de type peut être créée en utilisant le type Mixed.

> Note:

> Les propriétés statiques en lecture seule ne sont pas supportées.

Une propriété en lecture seule ne peut être initialisée qu'une seule fois, et seulement depuis la portée dans laquelle elle a été déclarée. Toute autre affectation ou modification de la propriété résultera en une exception Error.

Exemple #5 Initialisation illégale de propriétés en lecture seule

    <?php
    class Test1 {
        public readonly string $prop;
    }

    $test1 = new Test1;
    // Initialisation illégale en dehors de la portée privée.
    $test1->prop = "foobar";
    // Erreur : Cannot initialize readonly property Test1::$prop from global scope
    ?>

> Note:

> Spécifier une valeur par défaut explicite à une propriété en lecture seule n'est pas autorisé, car une propriété en lecture seule avec une valeur par défaut est essentiellement identique à une constante, et par conséquent pas particulièrement utile.

>     <?php

>     class Test {
>         // Erreur fatale : Readonly property Test::$prop cannot have default value
>         public readonly int $prop = 42;
>     }
>     ?>

> Note:

> Les propriétés en lecture seule ne peuvent pas être unset() une fois qu'elles ont été initialisées. Cependant, il est possible de unset une propriété en lecture seule avant son initialisation, depuis la portée où la propriété a été déclarée.

Les modifications ne sont pas nécessairement des affectations simples, tous les exemples suivants résulteront en une exception Error :

    <?php

    class Test {
        public function __construct(
            public readonly int $i = 0,
            public readonly array $ary = [],
        ) {}
    }

    $test = new Test;
    $test->i += 1;
    $test->i++;
    ++$test->i;
    $test->ary[] = 1;
    $test->ary[0][] = 1;
    unset($test->ary[0]);
    $ref =& $test->i;
    $test->i =& $ref;
    byRef($test->i);
    foreach ($test as &$prop);
    ?>

Cependant, les propriétés en lecture seule n'excluent pas la mutabilité intérieure. Les objets (ou ressources) stockés dans les propriétés en lecture seule peuvent toujours être modifiés en interne :

    <?php

    class Test {
        public function __construct(public readonly object $obj) {}
    }

    $test = new Test(new stdClass);
    // Mutation interne légale.
    $test->obj->foo = 1;
    // Réaffectation illégale.
    $test->obj = new stdClass;
    ?>

À partir de PHP 8.3.0, les propriétés en lecture seule peuvent être réinitialisées lors du clonage d'un objet en utilisant la méthode __clone().

Exemple #6 Propriétés en lecture seule et clonage

    <?php
    class Test1 {
        public readonly ?string $prop;

        public function __clone() {
            $this->prop = null;
        }

        public function setProp(string $prop): void {
            $this->prop = $prop;
        }
    }

    $test1 = new Test1;
    $test1->setProp('foobar');

    $test2 = clone $test1;
    var_dump($test2->prop); // NULL
    ?>

### Propriétés Dynamiques

Lors d'une tentative d'assignation à une propriété non existante sur un objet, PHP créera automatiquement une propriété correspondante. Cette propriété créée dynamiquement sera uniquement disponible sur cette instance de classe.

Avertissement

Les propriétés dynamiques sont obsolètes à partir de PHP 8.2.0. Il est recommandé de déclarer la propriété à la place. Pour gérer des noms de propriétés arbitraires, la classe devrait implémenter les méthodes magiques __get() et __set(). Comme dernier recours la classe peut être marquée avec l'attribut `#[\AllowDynamicProperties]`.

## Hooks de propriété

Les hooks de propriété, également connus sous le nom d'"accesseurs de propriété" dans d'autres langages, sont une façon d'intercepter et de remplacer le comportement de lecture et d'écriture d'une propriété. Cette fonctionnalité sert à deux fins :

1. Elle permet d'utiliser directement des propriétés, sans avoir besoin de méthodes get et set, tout en laissant la possibilité d'ajouter un comportement supplémentaire à l'avenir. Cela rend la plupart des méthodes get/set inutiles, même sans utiliser de hooks.
2. Elle permet de définir des propriétés qui décrivent un objet sans stocker directement de valeur.

Il existe deux hooks disponibles sur les propriétés non-statiques : `get` et `set`. Ils permettent de remplacer le comportement de lecture et d'écriture d'une propriété, respectivement. Les hooks sont disponibles pour les propriétés typées et non typées.

Une propriété peut être "backed" ou "virtuelle". Une propriété "backed" est une propriété qui stocke effectivement une valeur. Toute propriété qui n'a pas de hooks est "backed". Une propriété virtuelle est une propriété qui a des hooks et ces hooks n'interagissent pas avec la propriété elle-même. Dans ce cas, les hooks sont effectivement les mêmes que les méthodes, et l'objet n'utilise pas d'espace pour stocker une valeur pour cette propriété.

Les hooks de propriété sont incompatibles avec les propriétés `readonly`. S'il est nécessaire de restreindre l'accès à une opération `get` ou `set` en plus de modifier son comportement, il convient d'utiliser la visibilité asymétrique de propriété.

> Note: Information de version
> Les hooks de propriété ont été introduits en PHP 8.4.

### Syntaxe de base des hooks

La syntaxe générale pour déclarer un hook est la suivante.

Exemple #1 Hooks de propriété (version complète)

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get {
                if ($this->modified) {
                    return $this->foo . ' (modified)';
                }
                return $this->foo;
            }
            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }

    $example = new Example();
    $example->foo = 'changed';
    print $example->foo;
    ?>

La propriété $foo se termine par `{}`, plutôt qu'un point-virgule. Cela indique la présence de hooks. Un hook `get` et un hook `set` sont définis, bien qu'il soit possible de n'en définir qu'un seul. Les deux hooks ont un corps, indiqué par `{}`, qui peut contenir du code arbitraire.

Le hook `set` permet également de spécifier le type et le nom d'une valeur entrante, en utilisant la même syntaxe qu'une méthode. Le type doit être soit le même que le type de la propriété, ou contravariant (plus large) que celui-ci. Par exemple, une propriété de type string pourrait avoir un hook `set` qui accepte un string|Stringable, mais pas un qui n'accepte que array.

Au moins un des hooks fait référence à `$this->foo`, la propriété elle-même. Cela signifie que la propriété sera "backed". Lors de l'appel `$example->foo = 'changed'`, la chaîne fournie sera d'abord convertie en minuscules, puis enregistrée dans la valeur de sauvegarde. Lors de la lecture de la propriété, la valeur précédemment enregistrée peut conditionnellement être complétée avec du texte supplémentaire.

Il y a plusieurs variantes de syntaxe abrégée pour gérer les cas courants.

Si le hook `get` est une simple expression, alors les `{}` peuvent être omis et remplacés par une expression fléchée.

Exemple #2 Expression de propriété get

Cet exemple est équivalent à l'exemple précédent.

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

Si le type du paramètre du hook `set` est le même que le type de la propriété (ce qui est typique), il peut être omis. Dans ce cas, la valeur à définir est automatiquement nommée $value.

Exemple #3 Paramètres par défaut de propriété

Cet exemple est équivalent à l'exemple précédent.

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

Si le hook `set` ne fait que définir une version modifiée de la valeur passée, il peut également être simplifié en une expression fléchée. La valeur à laquelle l'expression est évaluée sera définie sur la valeur de sauvegarde.

Exemple #4 Expression de propriété set

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');
            set => strtolower($value);
        }
    }
    ?>

Cet exemple n'est pas tout à fait équivalent au précédent, car il ne modifie pas non plus `$this->modified`. Si plusieurs instructions sont nécessaires dans le corps du hook, utiliser la version avec des accolades.

Une propriété peut implémenter zéro, un ou les deux hooks selon la situation. Toutes les versions abrégées sont mutuellement indépendantes. C'est-à-dire qu'utiliser un raccourci pour obtenir une longue définition, ou un raccourci pour définir un type explicite, etc., est valide.

Sur une propriété "backed", l'omission d'un hook `get` ou `set` signifie que le comportement de lecture ou d'écriture par défaut sera utilisé.

> Note: Les hooks peuvent être définis lors de l'utilisation de la promotion de propriétés dans le constructeur. Cependant, dans ce cas, les valeurs fournies au constructeur doivent correspondre au type associé à la propriété, indépendamment de ce que le hook `set` pourrait autoriser. Considérez l'exemple suivant :

>     <?php
>     class Example
>     {
>         public function __construct(
>             public private(set) DateTimeInterface $created {
>                 set (string|DateTimeInterface $value) {
>                     if (is_string($value)) {
>                         $value = new DateTimeImmutable($value);
>                     }
>                     $this->created = $value;
>                 }
>             },
>         ) {
>         }
>     }

> En interne, le moteur décompose cela de la manière suivante :

>     <?php
>     class Example
>     {
>         public private(set) DateTimeInterface $created {
>             set (string|DateTimeInterface $value) {
>                 if (is_string($value)) {
>                     $value = new DateTimeImmutable($value);
>                 }
>                 $this->created = $value;
>             }
>         }

>         public function __construct(
>             DateTimeInterface $created,
>         ) {
>             $this->created = $created;
>         }
>     }

> Toute tentative de définir la propriété en dehors du constructeur autorisera soit une string soit une valeur de type DateTimeInterface, mais le constructeur n'autorisera que DateTimeInterface. Cela s'explique par le fait que le type défini pour la propriété (DateTimeInterface) est utilisé comme type de paramètre dans la signature du constructeur, indépendamment de ce que le hook `set` permet. Si ce type de comportement est nécessaire depuis le constructeur, la promotion de propriétés dans le constructeur ne peut pas être utilisée.

### Propriétés virtuelles

Les propriétés virtuelles sont des propriétés qui n'ont pas de valeur de sauvegarde. Une propriété est virtuelle si ni son hook `get` ni son hook `set` ne fait référence à la propriété elle-même en utilisant une syntaxe exacte. C'est-à-dire qu'une propriété nommée `$foo` dont le hook contient `$this->foo` sera sauvegardée. Mais la propriété suivante n'est pas une propriété sauvegardée, et générera une erreur :

Exemple #5 Propriété virtuelle invalide

    <?php
    class Example
    {
        public string $foo {
            get {
                $temp = __PROPERTY__;
                return $this->$temp; // Ne fait pas référence à $this->foo, donc cela ne compte pas.
            }
        }
    }
    ?>

Pour les propriétés virtuelles, si un hook est omis, alors cette opération n'existe pas et essayer de l'utiliser produira une erreur. Les propriétés virtuelles n'occupent pas d'espace mémoire dans un objet. Les propriétés virtuelles sont adaptées pour les propriétés "dérivées", telles que celles qui sont la combinaison de deux autres propriétés.

Exemple #6 Propriété virtuelle

    <?php
    class Rectangle
    {
        // Une propriété virtuelle.
        public int $area {
            get => $this->h * $this->w;
        }

        public function __construct(public int $h, public int $w) {}
    }

    $s = new Rectangle(4, 5);
    print $s->area; // affiche 20
    $s->area = 30; // Erreur, car il n'y a pas d'opération de définition.
    ?>

Définir à la fois un hook `get` et un hook `set` sur une propriété virtuelle est également autorisé.

### Portée

Tous les hooks fonctionnent dans la portée de l'objet modifié. Cela signifie qu'ils ont accès à toutes les méthodes publiques, privées ou protégées de l'objet, ainsi qu'à toutes les propriétés publiques, privées ou protégées, y compris les propriétés qui peuvent avoir leurs propres hooks de propriété. Accéder à une autre propriété depuis un hook ne contourne pas les hooks définis sur cette propriété.

La conséquence la plus notable de cela est que les hooks non triviaux peuvent appeler une méthode arbitrairement complexe s'ils le souhaitent.

Exemple #7 Appel d'une méthode depuis un hook

    <?php
    class Person {
        public string $phone {
            set => $this->sanitizePhone($value);
        }

        private function sanitizePhone(string $value): string {
            $value = ltrim($value, '+');
            $value = ltrim($value, '1');

            if (!preg_match('/\d\d\d\-\d\d\d\-\d\d\d\d/', $value)) {
                throw new \InvalidArgumentException();
            }
            return $value;
        }
    }
    ?>

### Références

Parce que la présence de hooks intercepte le processus de lecture et d'écriture des propriétés, ils posent des problèmes lors de l'acquisition d'une référence à une propriété ou avec une modification indirecte, telle que `$this->arrayProp['key'] = 'value';`. C'est parce que toute tentative de modification de la valeur par référence contournerait un hook de définition s'il en existe un.

Dans le cas rare où il est nécessaire d'obtenir une référence à une propriété pour laquelle des hooks sont définis, le hook `get` peut être préfixé par `&` pour qu'il retourne par référence. Définir à la fois `get` et `&get` sur la même propriété est une erreur de syntaxe.

Définir à la fois les hooks `&get` et `set` sur une propriété "backed" n'est pas autorisé. Comme indiqué ci-dessus, écrire dans la valeur retournée par référence contournerait le hook `set`. Sur les propriétés virtuelles, il n'y a pas de valeur commune nécessaire partagée entre les deux hooks, donc définir les deux est autorisé.

Écrire dans un index d'une propriété de tableau implique également une référence implicite. Pour cette raison, écrire dans une propriété de tableau "backed" avec des hooks définis est autorisé si et seulement si il ne définit qu'un hook `&get`. Sur une propriété virtuelle, écrire dans le tableau retourné par `get` ou `&get` est légal, mais si cela a un impact sur l'objet dépend de l'implémentation du hook.

Surcharger l'intégralité de la propriété de tableau est autorisé, et se comporte de la même manière que toute autre propriété. Ne travailler qu'avec des éléments du tableau nécessite une attention particulière.

### Héritage

#### Hooks finaux

Les hooks peuvent également être déclarés final, auquel cas ils ne peuvent pas être remplacés.

Exemple #8 Hooks finaux

    <?php
    class Utilisateur
    {
        public string $identifiant {
            final set => strtolower($value);
        }
    }

    class Responsable extends Utilisateur
    {
        public string $identifiant {
            // Ceci est autorisé
            get => strtoupper($this->identifiant);

            // Ceci n'est PAS autorisé, car set est final dans le parent.
            set => strtoupper($value);
        }
    }
    ?>

Une propriété peut également être déclarée final. Une propriété finale ne peut pas être redéclarée par une classe enfant de quelque manière que ce soit, ce qui exclut la modification des hooks ou l'élargissement de son accès.

Déclarer des hooks finaux sur une propriété qui est déclarée finale est redondant, et sera silencieusement ignoré. C'est le même comportement que pour les méthodes finales.

Une classe enfant peut définir ou redéfinir des hooks individuels sur une propriété en redéfinissant la propriété et uniquement les hooks qu'elle souhaite remplacer. Une classe enfant peut également ajouter des hooks à une propriété qui n'en avait pas. C'est essentiellement la même chose que si les hooks étaient des méthodes.

Exemple #9 Héritage de hook

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Too small');
                }
                $this->x = $value;
            }
        }
    }
    ?>

Chaque hook remplace les implémentations parentes indépendamment les unes des autres. Si une classe enfant ajoute des hooks, toute valeur par défaut définie sur la propriété est supprimée, et doit être redéclarée. Cela est cohérent avec le fonctionnement de l'héritage sur les propriétés sans hooks.

#### Accès aux hooks parentaux

Un hook dans une classe enfant peut accéder à la propriété de la classe parente en utilisant le mot-clé `parent::$prop`, suivi du hook désiré. Par exemple, `parent::$propName::get()`. Cela peut être lu comme "accéder à la propriété prop définie sur la classe parente, puis exécuter son opération get" (ou set, selon le cas).

Si ce n'est pas accédé de cette manière, le hook de la classe parente est ignoré. Ce comportement est cohérent avec le fonctionnement de toutes les méthodes. Cela offre également un moyen d'accéder au stockage de la classe parente, le cas échéant. S'il n'y a pas de hook sur la propriété parente, son comportement par défaut get/set sera utilisé. Les hooks ne peuvent pas accéder à un autre hook que leur propre parent sur leur propre propriété.

L'exemple ci-dessus pourrait être réécrit comme suit, ce qui permettrait à la classe `Point` d'ajouter son propre hook `set` à l'avenir sans problèmes (dans l'exemple précédent, un hook ajouté à la classe parente serait ignoré dans la classe enfant).

Exemple #10 Accès aux hooks parentaux (set)

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Too small');
                }
                parent::$x::set($value);
            }
        }
    }
    ?>

Un exemple de remplacement uniquement d'un hook get pourrait être :

Exemple #11 Accès aux hooks parentaux (get)

    <?php
    class Strings
    {
        public string $val;
    }

    class CaseFoldingStrings extends Strings
    {
        public bool $uppercase = true;

        public string $val {
            get => $this->uppercase
                ? strtoupper(parent::$val::get())
                : strtolower(parent::$val::get());
        }
    }
    ?>

### Sérialisation

PHP a plusieurs façons différentes de sérialiser un objet, que ce soit pour la consommation publique ou à des fins de débogage. Le comportement des hooks varie en fonction de l'utilisation. Dans certains cas, la valeur de sauvegarde brute d'une propriété sera utilisée, contournant tout hook. Dans d'autres, la propriété sera lue ou écrite "à travers" le hook, comme toute autre action de lecture/écriture normale.

- var_dump(): Utilise la valeur brute
- serialize(): Utilise la valeur brute
- unserialize(): Utilise la valeur brute
- __serialize()/__unserialize(): Logique propre, utilise les hooks get/set
- Conversion en tableau : Utilise la valeur brute
- var_export(): Utilise le hook get
- json_encode(): Utilise le hook get
- JsonSerializable: Logique propre, utilise le hook get
- get_object_vars(): Utilise le hook get
- get_mangled_object_vars(): Utilise la valeur brute

## Constantes de classe

Il est possible de définir des constantes par classes qui restent identiques et non modifiables. La visibilité par défaut des constantes de classe est `public`.

> Note:

> Les constantes de classes peuvent être redéfinies par une classe enfant. À partir de PHP 8.1.0, les constantes de classes ne peuvent pas être redéfinies par une classe enfant si elle a été définie comme finale.

Il est aussi possible pour les interfaces d'avoir des constantes. Voir la documentation des interfaces pour des exemples.

Il est possible de référencer la classe en utilisant une variable. La valeur de la variable ne peut pas être un mot-clé (e.g. `self`, `parent` et `static`).

Il est à noter que les constantes de classe sont allouées une fois par classe, et non pour chaque instance de classe.

À partir de PHP 8.3.0, les constantes de classe peuvent avoir un type scalaire tel que `bool`, `int`, `float`, `string`, ou même `array`. Lorsqu’on utilise `array`, son contenu ne peut contenir que d'autres types scalaires.

Exemple #1 Définition et utilisation d'une constante de classe

    <?php
    class MyClass
    {
        const CONSTANT = 'valeur constante';

        function showConstant() {
            echo  self::CONSTANT . "\n";
        }
    }

    echo MyClass::CONSTANT . "\n";

    $classname = "MyClass";
    echo $classname::CONSTANT . "\n";

    $class = new MyClass();
    $class->showConstant();

    echo $class::CONSTANT."\n";
    ?>

La constante spéciale `::class` permet une résolution de nom de classe pleinement qualifié au moment de la compilation, cela est utile pour les classes dans un espace de noms :

Exemple #2 Exemple d'utilisation de ::class

    <?php
    namespace foo {
        class bar {
        }

        echo bar::class; // foo\bar
    }
    ?>

Exemple #3 Exemple d'expressions pour une constante de classe

    <?php
    const ONE = 1;
    class foo {
        const TWO = ONE * 2;
        const THREE = ONE + self::TWO;
        const SENTENCE = 'The value of THREE is '.self::THREE;
    }
    ?>

Exemple #4 Modificateur de visibilité des constantes de classe, à partir de PHP 7.1.0

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }
    echo Foo::BAR, PHP_EOL;
    echo Foo::BAZ, PHP_EOL;
    ?>

Résultat de l'exemple ci-dessus en PHP 7.1 :

    bar

    Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in …

> Note:

> À partir de PHP 7.1.0, les modificateurs de visibilité sont autorisés sur les constantes de classe.

Exemple #5 Vérification de variance de visibilité des constantes de classe, à partir de PHP 8.3.0

    <?php

    interface MyInterface
    {
        public const VALUE = 42;
    }

    class MyClass implements MyInterface
    {
        protected const VALUE = 42;
    }
    ?>

Résultat de l'exemple ci-dessus en PHP 8.3 :

    Fatal error: Access level to MyClass::VALUE must be public (as in interface MyInterface) …

> Note: À partir de PHP 8.3.0, la variance de visibilité est vérifiée de manière plus stricte. Avant cette version, la visibilité d'une constante de classe pouvait différer de celle de la constante dans l'interface implémentée.

Exemple #6 Syntaxe d'accès dynamique aux constantes de classe, à partir de PHP 8.3.0

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }

    $name = 'BAR';
    echo Foo::{$name}, PHP_EOL; // bar
    ?>

> Note:

> À partir de PHP 8.3.0, les constantes de classe peuvent être récupérées dynamiquement en utilisant une variable.

Exemple #7 Attribution de types aux constantes de classe, à partir de PHP 8.3.0

    <?php

    class MyClass {
        public const bool MY_BOOL = true;
        public const int MY_INT = 1;
        public const float MY_FLOAT = 1.01;
        public const string MY_STRING = 'one';
        public const array MY_ARRAY = [self::MY_BOOL, self::MY_INT, self::MY_FLOAT, self::MY_STRING];
    }

    var_dump(MyClass::MY_BOOL);
    var_dump(MyClass::MY_INT);
    var_dump(MyClass::MY_FLOAT);
    var_dump(MyClass::MY_STRING);
    var_dump(MyClass::MY_ARRAY);
    ?>

Résultat de l'exemple ci-dessus en PHP 8.3 :

    bool(true)
    int(1)
    float(1.01)
    string(3) "one"
    array(4) {
      [0]=>
      bool(true)
      [1]=>
      int(1)
      [2]=>
      float(1.01)
      [3]=>
      string(3) "one"
    }

## Auto-chargement de classes

De nombreux développeurs qui écrivent des applications orientées objet créent un fichier source par définition de classe. Un des plus gros inconvénients de cette méthode est d'avoir à écrire une longue liste d'inclusions de fichier de classes au début de chaque script : une inclusion par classe.

La fonction spl_autoload_register() enregistre un nombre quelconque de chargeurs automatiques, ce qui permet aux classes et aux interfaces d'être automatiquement chargées si elles ne sont pas définies actuellement. En enregistrant des autochargeurs, PHP a une dernière chance de charger la classe ou l'interface avant d'échouer avec une erreur.

Toute construction similaire à une classe peut être autochargée de la même manière. Cela inclut les classes, interfaces, traits et énumérations.

Attention

Avant PHP 8.0.0, il était possible d'utiliser __autoload() pour autocharger les classes et interfaces. Cependant, c'est une alternative moins flexible à spl_autoload_register() et __autoload() est obsolète à partir de PHP 7.2.0, et supprimée à partir de PHP 8.0.0.

> Note:

> spl_autoload_register() peut être appelée plusieurs fois pour enregistrer plusieurs autochargeurs. Lancer une exception depuis une fonction d'autochargement interrompra ce processus et empêchera les fonctions d'autochargement suivantes de s'exécuter. Pour cette raison, lancer des exceptions depuis une fonction d'autochargement est fortement découragé.

Exemple #1 Exemple d'autochargement

Cet exemple tente de charger les classes `MaClasse1` et `MaClasse2`, respectivement depuis les fichiers MaClasse1.php et MaClasse2.php.

    <?php
    spl_autoload_register(function ($class_name) {
        include $class_name . '.php';
    });

    $obj  = new MaClasse1();
    $obj2 = new MaClasse2();
    ?>

Exemple #2 Autre exemple d'autochargement

Cet exemple tente de charger l'interface `ITest`.

    <?php

    spl_autoload_register(function ($name) {
        var_dump($name);
    });

    class Foo implements ITest {
    }

    /*
    string(5) "ITest"

    Fatal error: Interface 'ITest' not found in ...
    */
    ?>

Exemple #3 Utilisation de l'autoloader de Composer

» Composer génère un fichier `vendor/autoload.php` configuré pour charger automatiquement les packages gérés par Composer. En incluant ce fichier, ces packages peuvent être utilisés sans travail supplémentaire.

    <?php
    require __DIR__ . '/vendor/autoload.php';

    $uuid = Ramsey\Uuid\Uuid::uuid7();

    echo "Nouvel UUID généré -> ", $uuid->toString(), "\n";
    ?>

### Voir aussi

- unserialize()
- unserialize_callback_func
- unserialize_max_depth
- spl_autoload_register()
- spl_autoload()
- __autoload()

## Constructeurs et destructeurs

### Constructeur

function __construct(mixed `...$values` = ""): void

PHP permet aux développeurs de déclarer des constructeurs pour les classes. Les classes qui possèdent une méthode constructeur appellent cette méthode à chaque création d'une nouvelle instance de l'objet, ce qui est intéressant pour toutes les initialisations dont l'objet a besoin avant d'être utilisé.

> Note: Les constructeurs parents ne sont pas appelés implicitement si la classe enfant définit un constructeur. Pour utiliser un constructeur parent, il est nécessaire de faire appel à parent::__construct() depuis le constructeur enfant. Si l'enfant ne définit pas un constructeur alors, il peut être hérité de la classe parente, exactement de la même façon qu'une méthode le serait (si elle n'a pas été déclarée comme privée).

Exemple #1 Constructeur lors de l'héritage

    <?php
    class BaseClass {
        function __construct() {
            print "Dans le constructeur de BaseClass\n";
        }
    }

    class SubClass extends BaseClass {
        function __construct() {
            parent::__construct();
            print "Dans le constructeur de SubClass\n";
        }
    }

    class OtherSubClass extends BaseClass {
        // Constructeur hérité de BaseClass
    }

    // Dans le constructeur de BaseClass
    $obj = new BaseClass();

    // Dans le constructeur de BaseClass
    // Dans le constructeur de SubClass
    $obj = new SubClass();

    // Dans le constructeur de BaseClass
    $obj = new OtherSubClass();
    ?>

À la différence des autres méthodes, __construct() est exclue des règles de compatibilité des signatures usuelles quand elle est étendue.

Les constructeurs sont des méthodes ordinaires qui sont appelées lors de l'instanciation de leur objet correspondant. Par conséquent, ils peuvent définir un nombre arbitraire d'arguments, qui peuvent être requis, avoir un type, et peuvent avoir une valeur par défaut. Les arguments d'un constructeur sont appelés en plaçant les arguments dans des parenthèses après le nom de la classe.

Exemple #2 Utiliser les arguments d'un constructeur

    <?php
    class Point {
        protected int $x;
        protected int $y;

        public function __construct(int $x, int $y = 0) {
            $this->x = $x;
            $this->y = $y;
        }
    }

    // Passe les deux paramètres.
    $p1 = new Point(4, 5);
    // Passe uniquement le paramètre requis. $y prendra sa valeur par défaut de 0.
    $p2 = new Point(4);
    // Avec les arguments nommés (à partir de PHP 8.0) :
    $p3 = new Point(y: 5, x: 4);
    ?>

Si une classe n'a pas de constructeur, ou que le constructeur n'a pas d'arguments requis, les parenthèses peuvent être omises.

#### Style ancien des constructeurs

Avant PHP 8.0.0, les classes dans l'espace de noms global interpréteront une méthode qui a le même nom que la classe comme un constructeur de style ancien. Cette syntaxe est obsolète, et résultera en une erreur `E_DEPRECATED` mais appellera quand même cette fonction comme un constructeur. Si __construct() et une méthode du même nom sont définies, __construct() sera appelé.

Les classes dans les espaces de nom, ou toute classe à partir de PHP 8.0.0, une méthode du même nom que la classe n'a jamais de signification particulière.

Toujours utiliser __construct() dans du nouveau code.

#### Promotion du Constructeur

À partir de PHP 8.0.0, les paramètres du constructeur peuvent être promus pour correspondre à une propriété de l'objet. Il est très courant pour les paramètres d'un constructeur d'être assignés à une propriété sans effectuer d'opérations dessus. La promotion du constructeur fournit un raccourci pour ce cas d'utilisation. L'exemple ci-dessus peut être réécrit de la façon suivante.

Exemple #3 Utilisant la promotion de propriété de constructeur

    <?php
    class Point {
        public function __construct(protected int $x, protected int $y = 0) {
        }
    }

Quand un argument de constructeur inclut un modificateur, PHP l'interprétera comme une propriété d'objet et un argument du constructeur, et assigne la valeur de l'argument à la propriété. Le corps du constructeur peut être alors vide ou peut contenir d'autres déclarations. Toutes les déclarations additionnelles seront exécutées après que la valeur de l'argument a été assignée à sa propriété correspondante.

Tous les arguments ne doivent pas être promus. Il est possible de mélanger et assortir les arguments promus et non-promus, dans n'importe quel ordre. Les arguments promus n'ont aucun impact sur du code appelant le constructeur.

> Note:

> Utiliser un modificateur de visibilité (`public`, `protected` ou `private`) est la manière la plus probable d'appliquer la promotion de propriété, mais tout autre modificateur unique (comme `readonly`) aura le même effet.

> Note:

> Les propriétés d'objet ne peuvent être typées callable à cause des ambiguïtés du moteur que ceci introduirait. Ainsi, les arguments promus ne peuvent pas non plus être typés callable. Cependant, toute autre déclaration de type est permise.

> Note:

> Comme les propriétés promues sont à la fois désucrées à une propriété et aussi comme le paramètre d'une fonction, toutes les restrictions de nommage pour les propriétés et les paramètres s'appliquent.

> Note:

> Les attributs placés sur un argument de constructeur promu seront reproduits à la fois sur la propriété et sur l'argument. Les valeurs par défaut sur un argument de constructeur promu ne seront répliquées que sur l'argument et non sur la propriété.

#### New in initializers

À partir de PHP 8.1.0, les objets peuvent être utilisés comme valeur par défaut pour les paramètres, variables statiques, constantes globales et les arguments d'attributs. Les objets peuvent être désormais passés à define().

> Note:

> L'utilisation d'un nom de classe dynamique ou non-string ou une classe anonyme n'est pas permise. L'utilisation du déballage d'arguments n'est pas permise. L'utilisation d'expressions non supportées en tant qu'argument n'est pas permise.

Exemple #4 Utilisation de new dans des initialiseurs

    <?php

    // Tous autorisés :
    static $x = new Foo;

    const C = new Foo;

    function test($param = new Foo) {}

    #[AnAttribute(new Foo)]
    class Test {
        public function __construct(
            public $prop = new Foo,
        ) {}
    }

    // Aucun n'est autorisé (erreur de compilation) :
    function test(
        $a = new (CLASS_NAME_CONSTANT)(), // nom de classe dynamique
        $b = new class {}, // classe anonyme
        $c = new A(...[]), // déballage d'arguments
        $d = new B($abc), // expression de constante non supportée
    ) {}
    ?>

#### Méthode de création statique

PHP supporte uniquement un constructeur unique par classe. Cependant, dans certains cas il peut être désirable de permettre à un objet d'être construit de manière différente avec des entrées différentes. La façon recommandée de faire ceci est en utilisant des méthodes statiques comme une enveloppe du constructeur.

Exemple #5 Utilisant la création via une méthode statique

    <?php
    $some_json_string = '{ "id": 1004, "name": "Elephpant" }';
    $some_xml_string = "<animal><id>1005</id><name>Elephpant</name></animal>";

    class Product {

        private ?int $id;
        private ?string $name;

        private function __construct(?int $id = null, ?string $name = null) {
            $this->id = $id;
            $this->name = $name;
        }

        public static function fromBasicData(int $id, string $name): static {
            $new = new static($id, $name);
            return $new;
        }

        public static function fromJson(string $json): static {
            $data = json_decode($json, true);
            return new static($data['id'], $data['name']);
        }

        public static function fromXml(string $xml): static {
            $data = simplexml_load_string($xml);
            $new = new static();
            $new->id = (int) $data->id;
            $new->name = $data->name;
            return $new;
        }
    }

    $p1 = Product::fromBasicData(5, 'Widget');
    $p2 = Product::fromJson($some_json_string);
    $p3 = Product::fromXml($some_xml_string);

    var_dump($p1, $p2, $p3);

Le constructeur peut être rendu privé ou protégé pour empêcher son appel depuis l'extérieur. Dans ce cas, seule une méthode statique sera capable d'instancier la classe. Puisqu'elles sont dans la même définition de classe, elles ont accès aux méthodes privées, même dans une instance différente de l'objet. Un constructeur privé est optionnel et peut ou non avoir du sens en fonction du cas d'utilisation.

Les trois méthodes statiques publiques démontrent alors des manières différentes d'instancier l'objet.

- `fromBasicData()` prend les paramètres exacts qui sont nécessaires, puis crée l'objet en appelant le constructeur puis retournant le résultat.
- `fromJson()` accepte une chaîne de caractères JSON et fait du pré-traitement sur lui-même pour se convertir dans le format désiré par le constructeur. Elle retourne alors le nouvel objet.
- `fromXml()` accepte une chaîne de caractères XML, fait du pré-traitement, puis crée un objet brut. Le constructeur est appelé, mais comme tous les paramètres sont optionnels la méthode les ignore. Elle assigne alors les valeurs aux propriétés de l'objet directement avant de retourner le résultat.

Dans les trois cas, le mot-clé `static` est traduit en le nom de la classe dont le code y est. Dans ce cas, `Product`.

### Destructeur

function __destruct(): void

PHP possède un concept de destructeur similaire à celui d'autres langages orientés objet, comme le `C++`. La méthode destructeur est appelée dès qu'il n'y a plus de référence sur un objet donné, ou dans n'importe quel ordre pendant la séquence d'arrêt.

Exemple #6 Exemple avec un Destructeur

    <?php

    class MyDestructableClass
    {
        function __construct() {
            print "Dans le constructeur\n";
        }

        function __destruct() {
            print "Destruction de " . __CLASS__ . "\n";
        }
    }

    $obj = new MyDestructableClass();

Tout comme le constructeur, le destructeur parent ne sera pas appelé implicitement par le moteur. Pour exécuter le destructeur parent, il faut appeler explicitement la fonction parent::__destruct() dans le corps du destructeur. Tout comme les constructeurs, une classe enfant peut hériter du destructeur du parent s'il n'en implémente pas un lui-même.

Le destructeur sera appelé même si l'exécution du script est stoppée en utilisant la fonction exit(). Appeler la fonction exit() dans un destructeur empêchera l'exécution des routines d'arrêt restantes.

Si un destructeur crée de nouvelles références à son objet, il ne sera pas appelé une seconde fois lorsque le compteur de références atteint de nouveau zéro ou durant la séquence d'arrêt.

À partir de PHP 8.4.0, lorsque la collecte des cycles se produit pendant l'exécution d'une fibre, les destructeurs des objets programmés pour la collecte sont exécutés dans une fibre distincte, appelée `gc_destructor_fiber`. Si cette fibre est suspendue, une nouvelle fibre sera créée pour exécuter les destructeurs restants. La précédente `gc_destructor_fiber` ne sera plus référencée par le ramasse-miettes et pourra être collectée si elle n'est pas référencée ailleurs. Les objets dont le destructeur est suspendu ne seront pas collectés tant que le destructeur n'a pas terminé ou que la fibre elle-même n'est pas collectée.

> Note:

> Les destructeurs appelés durant l'arrêt du script sont dans une situation où les en-têtes HTTP ont déjà été envoyés. Le dossier de travail dans la phase d'arrêt du script peut être différent avec certaines SAPIs (par exemple Apache).

> Note:

> Tenter de lancer une exception depuis un destructeur (appelé à la fin du script) entraîne une erreur fatale.

## Visibilité

La visibilité d'une propriété, d'une méthode ou (à partir de PHP 7.1.0) d'une constante peut être définie en préfixant sa déclaration avec un mot-clé : `public`, `protected`, ou `private`. Les éléments déclarés comme publics sont accessibles partout. L'accès aux éléments protégés est limité à la classe elle-même, ainsi qu'aux classes qui en héritent et à la classe parente. L'accès aux éléments privés est uniquement réservé à la classe qui les a définis.

### Visibilité des propriétés

Les propriétés des classes peuvent être définies comme publiques, privées ou protégées. Les propriétés déclarées sans explicitement utiliser un mot-clef de visibilité seront automatiquement définies comme publiques.

Exemple #1 Déclaration de propriétés

    <?php
    /**
     * Définition de MyClass
     */
    class MyClass
    {
        public $public = 'Public';
        protected $protected = 'Protected';
        private $private = 'Private';

        function printHello()
        {
            echo $this->public;
            echo $this->protected;
            echo $this->private;
        }
    }

    $obj = new MyClass();
    echo $obj->public; // Fonctionne
    echo $obj->protected; // Erreur fatale
    echo $obj->private; // Erreur fatale
    $obj->printHello(); // Affiche Public, Protected et Private

    /**
     * Définition de MyClass2
     */
    class MyClass2 extends MyClass
    {
        // On peut redéclarer les propriétés publiques ou protégées, mais pas celles privées
        public $public = 'Public2';
        protected $protected = 'Protected2';

        function printHello()
        {
          echo $this->public;
          echo $this->protected;
          echo $this->private;
       }
    }

    $obj2 = new MyClass2();
    echo $obj2->public; // Fonctionne
    echo $obj2->protected; // Erreur fatale
    echo $obj2->private; // Indéfini
    $obj2->printHello(); // Affiche Public2, Protected2 et Undefined (Indéfini)

    ?>

#### Visibilité Asymétrique des Propriétés

À partir de PHP 8.4, les propriétés peuvent également avoir leur visibilité définie de manière asymétrique, avec un champ différent pour la lecture (`get`) et l'écriture (`set`). Plus précisément, la visibilité `set` peut être spécifiée séparément, à condition qu'elle ne soit pas plus permissive que la visibilité par défaut.

Exemple #2 Visibilité Asymétrique des Propriétés

    <?php
    class Book
    {
        public function __construct(
            public private(set) string $title,
            public protected(set) string $author,
            protected private(set) int $pubYear,
        ) {}
    }

    class SpecialBook extends Book
    {
        public function update(string $author, int $year): void
        {
            $this->author = $author; // OK
            $this->pubYear = $year; // Erreur Fatale
        }
    }

    $b = new Book('Comment utiliser PHP', 'Peter H. Peterson', 2024);

    echo $b->title; // Fonctionne
    echo $b->author; // Fonctionne
    echo $b->pubYear; // Erreur Fatale

    $b->title = 'Comment ne pas utiliser PHP'; // Erreur Fatale
    $b->author = 'Pedro H. Peterson'; // Erreur Fatale
    $b->pubYear = 2023; // Erreur Fatale
    ?>

À partir de PHP 8.5, la visibilité `set` peut également être appliquée aux propriétés statiques des classes.

Exemple #3 Visibilité Asymétrique des Propriétés Statiques

    <?php
    class Manager
    {
        public private(set) static int $calls = 0;

        public function doAThing(): string
        {
            self::$calls++;
            // Effectue d'autres opérations.
            return "une chaîne";
        }
    }

    $m = new Manager();

    $m->doAThing(); // Fonctionne
    echo Manager::$calls; // Fonctionne
    Manager::$calls = 5; // Erreur fatale
    ?>

L'exemple ci-dessus va afficher :

    1
    Fatal error: Uncaught Error: Cannot modify private(set) property Manager::$calls from global scope in /some/file.php

Il y a quelques réserves concernant la visibilité asymétrique :

- Seules les propriétés typées peuvent avoir une visibilité `set` séparée.
- La visibilité `set` doit être la même que `get` ou plus restrictive. C'est-à-dire, `public protected(set)` et `protected protected(set)` sont autorisés, mais `protected public(set)` provoquera une erreur de syntaxe.
- Si une propriété est `public`, alors la visibilité principale peut être omise. C'est-à-dire que `public private(set)` et `private(set)` auront le même résultat.
- Une propriété avec une visibilité `private(set)` est automatiquement `final`, et ne peut pas être redéfinie dans une classe enfant.
- Obtenir une référence à une propriété suit la visibilité `set`, pas `get`. Cela est dû au fait qu'une référence peut être utilisée pour modifier la valeur de la propriété.
- De même, essayer d'écrire dans une propriété de tableau implique à la fois une opération `get` et une opération `set` en interne, et suivra donc la visibilité `set`, car c'est toujours la plus restrictive.

> Note: Les espaces ne sont pas autorisés dans la déclaration de visibilité pour la modification. `private(set)` est correct. `private( set )` n'est pas correct et entraînera une erreur d'analyse.

Lorsqu'une classe étend une autre, la classe enfant peut redéfinir toute propriété qui n'est pas `final`. En le faisant, elle peut élargir soit la visibilité principale, soit la visibilité `set`, à condition que la nouvelle visibilité soit la même ou plus large que celle de la classe parente. Cependant, il faut savoir que si une propriété `private` est remplacée, cela ne change pas réellement la propriété de la classe parente, mais crée une nouvelle propriété avec un nom interne différent.

Exemple #4 Héritage des Propriétés Asymétriques

    <?php
    class Book
    {
        protected string $title;
        public protected(set) string $author;
        protected private(set) int $pubYear;
    }

    class SpecialBook extends Book
    {
        public protected(set) string $title; // OK, car la lecture est plus large et l'écriture est la même.
        public string $author; // OK, car la lecture est la même et l'écriture est plus large.
        public protected(set) int $pubYear; // Erreur Fatale. Les propriétés private(set) sont finales.
    }
    ?>

### Visibilité des méthodes

Les méthodes des classes peuvent être définies comme publiques, privées ou protégées. Les méthodes déclarées sans explicitement utiliser un mot-clef de visibilité seront automatiquement définies comme publiques.

Exemple #5 Déclaration de méthodes

    <?php
    /**
     * Définition de MyClass
     */
    class MyClass
    {
        // Déclare un constructeur public
        public function __construct() { }

        // Déclare une méthode publique
        public function MyPublic() { }

        // Déclare une méthode protégée
        protected function MyProtected() { }

        // Déclare une méthode privée
        private function MyPrivate() { }

        // Celle-ci sera publique
        function Foo()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate();
        }
    }

    $myclass = new MyClass;
    $myclass->MyPublic(); // Fonctionne
    $myclass->MyProtected(); // Erreur fatale
    $myclass->MyPrivate(); // Erreur fatale
    $myclass->Foo(); // Public, Protected et Private fonctionnent

    /**
     * Définition de MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Celle-ci sera publique
        function Foo2()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate(); // Erreur fatale
        }
    }

    $myclass2 = new MyClass2;
    $myclass2->MyPublic(); // Fonctionne
    $myclass2->Foo2(); // Public et Protected fonctionnent, non Private

    class Bar
    {
        public function test() {
            $this->testPrivate();
            $this->testPublic();
        }

        public function testPublic() {
            echo "Bar::testPublic\n";
        }

        private function testPrivate() {
            echo "Bar::testPrivate\n";
        }
    }

    class Foo extends Bar
    {
        public function testPublic() {
            echo "Foo::testPublic\n";
        }

        private function testPrivate() {
            echo "Foo::testPrivate\n";
        }
    }

    $myFoo = new Foo();
    $myFoo->test(); // Bar::testPrivate
                    // Foo::testPublic
    ?>

### Visibilité des constantes

À partir de PHP 7.1.0, les constantes de classes peuvent être définies comme publiques, privées ou protégées. Les constantes déclarées sans mot clé de visibilité explicite sont définies en tant que public.

Exemple #6 Déclaration de constantes à partir de PHP 7.1.0

    <?php
    /**
     * Déclarons MyClass
     */
    class MyClass
    {
        // Déclarons une constante public
        public const MY_PUBLIC = 'public';

        // Déclarons une constante protégée
        protected const MY_PROTECTED = 'protected';

        // Déclarons une constante privée
        private const MY_PRIVATE = 'private';

        public function foo()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE;
        }
    }

    $myclass = new MyClass();
    MyClass::MY_PUBLIC; // Fonctionne
    MyClass::MY_PROTECTED; // Erreur fatale
    MyClass::MY_PRIVATE; // Erreur fatale
    $myclass->foo(); // Public, Protégée et Privée fonctionnent

    /**
     * Déclarons MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Celle-ci sera publique
        function foo2()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE; // Erreur fatale
        }
    }

    $myclass2 = new MyClass2;
    echo MyClass2::MY_PUBLIC; // Fonctionne
    $myclass2->foo2(); // Public et Protégée fonctionnent, mais pas Privée
    ?>

### Visibilité depuis d'autres objets

Les objets de mêmes types ont accès aux membres privés et protégés les uns des autres, même s'ils ne sont pas la même instance. Ceci est dû au fait que les détails spécifiques de l'implémentation sont déjà connus en interne par ces objets.

Exemple #7 Accès aux membres privés d'un objet du même type

    <?php
    class Test
    {
        private $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        private function bar()
        {
            echo 'Accès à la méthode privée.';
        }

        public function baz(Test $other)
        {
            // Nous pouvons modifier la propriété privée :
            $other->foo = 'Bonjour';
            var_dump($other->foo);

            // Nous pouvons également appeler la méthode privée :
            $other->bar();
        }
    }

    $test = new Test('test');

    $test->baz(new Test('other'));
    ?>

L'exemple ci-dessus va afficher :

    string(7) "Bonjour"
    Accès à la méthode privée.

## Héritage

L'héritage est un des grands principes de la programmation orientée objet (POO), et PHP l'implémente dans son modèle objet. Ce principe va affecter la manière dont de nombreuses classes sont en relation les unes avec les autres.

Par exemple, lorsqu'une classe est étendue, la classe enfant hérite de toutes les méthodes publiques et protégées, propriétés et constantes de la classe parente. Tant qu'une classe n'écrase pas ces méthodes, elles conservent leur fonctionnalité d'origine.

L'héritage est très utile pour définir et abstraire certaines fonctionnalités communes à plusieurs classes, tout en permettant la mise en place de fonctionnalités supplémentaires dans les classes enfants, sans avoir à réimplémenter en leur sein toutes les fonctionnalités communes.

Les méthodes privées d'une classe parente ne sont pas accessibles à la classe enfant. Par conséquent, les classes enfant peuvent réimplémenter une méthode privée elles-mêmes sans se soucier des règles d'héritage normales. Avant PHP 8.0.0, cependant, les restrictions `final` et `static` étaient appliquées aux méthodes privées. À partir de PHP 8.0.0, l'unique restriction de méthode privée qui est imposée est `private final` sur les constructeurs, car c'est une manière courante pour "désactiver" le constructeur lors de l'utilisation de méthodes factory statiques à la place.

La visibilité des méthodes, propriétés et constantes peut être relaxée, c.-à-d. une méthode `protected` peut être marquée comme `public`, mais elles ne peuvent pas être restreintes, e.g. marquer une propriété `public` comme `private`. Une exception sont les constructeurs, pour lesquels la visibilité peut être restreinte, par exemple un constructeur `public` peut être annoté en tant que `private` dans la classe enfant.

> Note:

> À moins que l'autochargement ne soit utilisé, les classes doivent être connues avant d'être utilisées. Les classes mères doivent être définies avant l'écriture d'un héritage. Cette règle générale s'applique aussi dans le cas d'héritage ou d'implémentation d'interfaces.

> Note:

> Il n'est pas autorisé de redéfinir une propriété en lecture-écriture avec une propriété en lecture seule ou vice versa.

>     <?php

>     class A {
>         public int $prop;
>     }
>     class B extends A {
>         // Illégal : lecture-écriture -> lecture seule
>         public readonly int $prop;
>     }
>     ?>

Exemple #1 Exemple d'héritage

    <?php

    class Foo
    {
        public function printItem($string)
        {
            echo 'Foo: ' . $string . PHP_EOL;
        }

        public function printPHP()
        {
            echo 'PHP est super.' . PHP_EOL;
        }
    }

    class Bar extends Foo
    {
        public function printItem($string)
        {
            echo 'Bar: ' . $string . PHP_EOL;
        }
    }

    $foo = new Foo();
    $bar = new Bar();
    $foo->printItem('baz'); // Affiche : 'Foo: baz'
    $foo->printPHP();       // Affiche : 'PHP est super.'
    $bar->printItem('baz'); // Affiche : 'Bar: baz'
    $bar->printPHP();       // Affiche : 'PHP est super.'

    ?>

### Compatibilité des types de retour avec les classes internes

Avant PHP 8.1, la plupart des classes ou méthodes internes ne déclaraient pas leur type de retour, et tout type de retour était autorisé lors de leur héritage.

À partir de PHP 8.1.0, la plupart des méthodes internes ont commencé à déclarer "provisoirement" leur type de retour, dans ce cas, le type de retour des méthodes doit être compatible avec la classe parent; Dans le cas contraire, une notification de dépréciation est émise. Il est à noter que l'absence d'une déclaration de retour explicite est également considérée comme une erreur de signature, et entraîne donc l'avis de dépréciation.

Si le type de retour ne peut être déclaré pour une méthode de surcharge en raison de problèmes de compatibilité entre versions de PHP, un attribut ReturnTypeWillChange peut être ajouté pour passer sous silence l'avis de dépréciation.

Exemple #2 La méthode surchargée ne déclare pas de type de retour.

    <?php

    class MyDateTime extends DateTime
    {
        public function modify(string $modifier) { return false; }
    }

    // "Deprecated: Return type of MyDateTime::modify(string $modifier) should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" À partir de PHP 8.1.0

Exemple #3 La méthode surchargée déclare un mauvais type de retour.

    <?php

    class MyDateTime extends DateTime
    {
        public function modify(string $modifier): ?DateTime { return null; }
    }

    // "Deprecated: Return type of MyDateTime::modify(string $modifier): ?DateTime should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" À partir de PHP 8.1.0

Exemple #4 La méthode surchargée déclare un mauvais type de retour sans notice de dépréciation.

    <?php

    class MyDateTime extends DateTime
    {
        /**
         * @return DateTime|false
         */
        #[\ReturnTypeWillChange]
        public function modify(string $modifier) { return false; }
    }

    // Aucune notice n'est déclenchée

## L'opérateur de résolution de portée (::)

L'opérateur de résolution de portée (aussi appelé Paamayim Nekudotayim) ou, en termes plus simples, le symbole "double deux-points" (::), fournit un moyen d'accéder à une constante, une propriété statique, ou une méthode statique d'une classe ou de l'une de ses classes parentes. De plus, les propriétés ou méthodes statiques peuvent être redéfinies via la liaison statique tardive.

Lorsque l'on référence ces éléments en dehors de la définition de la classe, il faut utiliser le nom de la classe.

Il est possible de référencer une classe en utilisant une variable. La valeur de la variable ne peut être un mot-clé (e.g. `self`, `parent` et `static`).

Paamayim Nekudotayim pourrait au premier abord sembler être un choix étrange pour nommer un double deux-points. Cependant, au moment de l'écriture du `Zend Engine 0.5` (qui faisait fonctionner PHP 3), c'est le nom qui a été choisi par l'équipe Zend. En fait, cela signifie un double deux-points... en hébreu !

Exemple #1 :: en dehors de la définition de la classe

    <?php
    class MyClass {
        const CONST_VALUE = 'Une valeur constante';
    }

    $classname = 'MyClass';
    echo $classname::CONST_VALUE;

    echo MyClass::CONST_VALUE;
    ?>

Trois mots-clés spéciaux, self, parent, et static sont utilisés pour accéder aux propriétés ou aux méthodes depuis la définition de la classe.

Exemple #2 :: depuis la définition de la classe

    <?php
    class MyClass {
        const CONST_VALUE = 'Une valeur constante';
    }

    class OtherClass extends MyClass
    {
        public static $my_static = 'variable statique';

        public static function doubleColon() {
            echo parent::CONST_VALUE . "\n";
            echo self::$my_static . "\n";
        }
    }

    $classname = 'OtherClass';
    $classname::doubleColon();

    OtherClass::doubleColon();
    ?>

Lorsqu'une classe héritant d'une autre redéfinit une méthode de sa classe parente, PHP n'appellera pas la méthode de la classe parente. Il appartient à la méthode dérivée d'appeler la méthode d'origine en cas de besoin. Cela est également valable pour les définitions des constructeurs et destructeurs, la surcharge, et les définitions de méthodes magiques.

Exemple #3 Appel d'une méthode parente

    <?php
    class MyClass
    {
        protected function myFunc() {
            echo "MyClass::myFunc()\n";
      }
    }

    class OtherClass extends MyClass
    {
        // Surcharge de la définition parente
        public function myFunc() {

          // Mais appel de la méthode parente
          parent::myFunc();
          echo "OtherClass::myFunc()\n";
      }
    }

    $class = new OtherClass();
    $class->myFunc();
    ?>

Voir aussi quelques exemples d'appels statiques.

## Statique

Astuce

Cette page décrit l'utilisation du mot clé `static` qui permet de définir des méthodes et des propriétés statiques. `static` peut aussi être utilisé pour définir des variables statiques, définir des fonctions anonymes statiques et pour des Résolutions statiques à la volée. Se reporter à ces pages pour plus d'informations sur la signification de `static`.

Le fait de déclarer des propriétés ou des méthodes comme statiques permet d'y accéder sans avoir besoin d'instancier la classe. Celles-ci peuvent également être accédées statiquement depuis une instance d'objet.

### Méthodes statiques

Comme les méthodes statiques peuvent être appelées sans qu'une instance d'objet n'ait été créée, la pseudo-variable $this n'est pas disponible dans les méthodes déclarées comme statiques.

Avertissement

Appeler une méthode non-statique statiquement lancera une Error.

Avant PHP 8.0.0, appeler une méthode non-statique statiquement était obsolète, et générait un avertissement `E_DEPRECATED`.

Exemple #1 Exemple avec une méthode statique

    <?php
    class Foo
    {
        public static function aStaticMethod() {
            // ...
        }
    }

    Foo::aStaticMethod();
    $classname = 'Foo';
    $classname::aStaticMethod();
    ?>

### Propriétés statiques

Les propriétés statiques sont accédées en utilisant l' opérateur de résolution de portée (`::`) et ne peuvent pas être accédées à travers l'opérateur objet (`->`).

Il est possible de référencer la classe en utilisant une variable. La valeur de la variable ne peut être un mot-clé (par exemple `self`, `parent` et `static`).

Exemple #2 Exemple avec une propriété statique

    <?php
    class Foo
    {
        public static $my_static = 'foo';

        public function staticValue() {
            return self::$my_static;
        }
    }

    class Bar extends Foo
    {
        public function fooStatic() {
            return parent::$my_static;
        }
    }

    print Foo::$my_static . "\n";

    $foo = new Foo();
    print $foo->staticValue() . "\n";
    print $foo->my_static . "\n";      // "Propriété" my_static non définie

    print $foo::$my_static . "\n";
    $classname = 'Foo';
    print $classname::$my_static . "\n";

    print Bar::$my_static . "\n";
    $bar = new Bar();
    print $bar->fooStatic() . "\n";
    ?>

Résultat de l'exemple ci-dessus en PHP 8 est similaire à :

    foo
    foo

    Notice: Accessing static property Foo::$my_static as non static in /in/V0Rvv on line 23

    Warning: Undefined property: Foo::$my_static in /in/V0Rvv on line 23

    foo
    foo
    foo
    foo

## Abstraction de classes

PHP a des classes, méthodes et propriétés abstraites. Les classes définies comme abstraites ne peuvent pas être instanciées, et toute classe contenant au moins une méthode abstraite ou propriété abstraite doit elle aussi être abstraite. Les méthodes définies comme abstraites se contentent de déclarer la signature de la méthode et d'indiquer si elle est publique ou protégée ; elles ne peuvent pas définir l'implémentation. Les propriétés définies comme abstraites peuvent déclarer une exigence pour le comportement de `get` ou de `set`, et peuvent fournir une implémentation pour l'une de ces opérations, mais pas les deux.

Lors de l'héritage d'une classe abstraite, toutes les méthodes marquées comme abstraites dans la déclaration de la classe parente doivent être définies par la classe enfant et suivre les règles habituelles d'héritage et de compatibilité de signature.

À partir de PHP 8.4, une classe abstraite peut déclarer une propriété abstraite, publique ou protégée. Une propriété abstraite protégée peut être satisfaite par une propriété accessible en lecture/écriture depuis un contexte protégé ou public.

Une propriété abstraite peut être satisfaite soit par une propriété standard, soit par une propriété avec des hooks définis, correspondant à l'opération requise.

Exemple #1 Exemple de méthode abstraite

    <?php

    abstract class AbstractClass
    {
        // Force les classes filles à définir cette méthode
        abstract protected function getValue();
        abstract protected function prefixValue($prefix);

        // méthode commune
       public function printOut()
       {
            print $this->getValue() . "\n";
       }
    }

    class ConcreteClass1 extends AbstractClass
    {
         protected function getValue()
         {
           return "ConcreteClass1";
         }

         public function prefixValue($prefix)
         {
           return "{$prefix}ConcreteClass1";
         }
    }

    class ConcreteClass2 extends AbstractClass
    {
         public function getValue()
         {
           return "ConcreteClass2";
         }

         public function prefixValue($prefix)
         {
           return "{$prefix}ConcreteClass2";
         }
    }

    $class1 = new ConcreteClass1();
    $class1->printOut();
    echo $class1->prefixValue('FOO_'), "\n";

    $class2 = new ConcreteClass2();
    $class2->printOut();
    echo $class2->prefixValue('FOO_'), "\n";

    ?>

L'exemple ci-dessus va afficher :

    ConcreteClass1
    FOO_ConcreteClass1
    ConcreteClass2
    FOO_ConcreteClass2

Exemple #2 Exemple de méthode abstraite

    <?php

    abstract class AbstractClass
    {
        // Une méthode abstraite ne doit que définir les arguments requis
        abstract protected function prefixName($name);

    }

    class ConcreteClass extends AbstractClass
    {

        // Une classe enfant peut définir des arguments optionnels qui ne sont pas présents dans la signature du parent
         public function prefixName($name, $separator = ".")
         {
            if ($name == "Pacman") {
                $prefix = "Mr";
            } elseif ($name == "Pacwoman") {
                $prefix = "Mrs";
            } else {
                $prefix = "";
            }

            return "{$prefix}{$separator} {$name}";
        }
    }

    $class = new ConcreteClass();
    echo $class->prefixName("Pacman"), "\n";
    echo $class->prefixName("Pacwoman"), "\n";

    ?>

L'exemple ci-dessus va afficher :

    Mr. Pacman
    Mrs. Pacwoman

Exemple #3 Exemple de propriété abstraite

    <?php

    abstract class A
    {
        // Les classes dérivées doivent avoir une propriété publiquement accessible en lecture.
        abstract public string $readable {
            get;
        }

        // Les classes dérivées doivent avoir une propriété modifiable en écriture, protégée ou publique.
         abstract protected string $writeable {
             set;
        }

        // Les classes dérivées doivent avoir une propriété symétrique protégée ou publique.
         abstract protected string $both {
             get;
             set;
         }
    }

    class C extends A
    {
        // Cela satisfait l'exigence et rend également la propriété modifiable, ce qui est valide.
        public string $readable;

        // Cela NE satisferait PAS l'exigence, car la propriété n'est pas publiquement accessible en lecture.
        protected string $readable;

        // Cela satisfait exactement l'exigence, donc c'est suffisant.
        // La propriété ne peut être modifiée qu'à partir d'un contexte protégé.
        protected string $writeable {
            set => $value;
        }

        // Cela élargit la visibilité de protégé à public, ce qui est acceptable.
        public string $both;
    }
    ?>

Une propriété abstraite dans une classe abstraite peut fournir des implémentations pour tout hook, mais doit avoir soit `get` soit `set` déclarés mais non définis (comme dans l'exemple ci-dessus).

Exemple #4 Exemple de propriété abstraite avec des hooks

    <?php

    abstract class A
    {
        // Cela fournit une implémentation par défaut (mais substituable) pour set,
        // et exige que les classes dérivées fournissent une implémentation pour get.
        abstract public string $foo {
            get;

            set {
                $this->foo = $value;
            }
        }
    }

    ?>

## Interfaces

Les interfaces d'objets permettent de créer du code qui spécifie quelles méthodes et propriétés une classe doit implémenter, sans avoir à définir comment ces méthodes ou propriétés sont implémentées. Les interfaces partagent un espace de noms avec les classes, traits et énumérations, de sorte qu'elles ne peuvent pas utiliser le même nom.

Les interfaces sont définies de la même façon que pour une classe, mais en utilisant le mot-clé `interface` à la place de `class`, et sans qu'aucune des méthodes n'ait son contenu de spécifié.

De par la nature même d'une interface, toutes les méthodes déclarées dans une interface doivent être publiques.

En pratique les interfaces servent deux rôles complémentaires :

- Permettre aux développeurs de créer des objets de classes différentes qui peuvent être utilisés de façon interchangeable, car elles implémentent la ou les mêmes interfaces. Un exemple commun sont plusieurs services d'accès à des bases de données, plusieurs gestionnaires de paiement ou différentes stratégies de cache. Différentes implémentations peuvent être échangées sans nécessiter des changements dans le code qui les utilise.
- Pour permettre à une fonction ou méthode d'accepter et opérer sur un paramètre qui se conforme à une interface, sans se soucier de quoi d'autre l'objet peut faire ou comment c'est implémenté. Ces interfaces sont souvent nommées `Iterable`, `Cacheable`, `Renderable`, etc. pour décrire la signification de leur comportement.

Les interfaces peuvent définir des méthodes magiques pour obliger les classes implémentant à implémenter ces méthodes.

> Note:

> Bien que cela soit supporté, inclure les constructeurs dans les interfaces est fortement déconseillé. Le faire réduit radicalement la flexibilité des objets implémentant l'interface. De plus, les constructeurs ne sont pas soumis aux règles d'héritage, ce qui peut causer des incohérences et des comportements inattendus.

### `implements`

Pour implémenter une interface, l'opérateur `implements` est utilisé. Toutes les méthodes de l'interface doivent être implémentées dans une classe ; si ce n'est pas le cas, une erreur fatale sera émise. Les classes peuvent implémenter plus d'une interface, en séparant chaque interface par une virgule.

Avertissement

Une classe qui implémente une interface peut utiliser des noms différents pour ses paramètres que l'interface. Cependant, à partir de PHP 8.0, le langage supporte les arguments nommés, ce qui signifie que l'appelant peut dépendre du nom du paramètre dans l'interface. Pour cette raison, il est fortement recommandé que les développeurs utilisent le même nom de paramètre que dans l'interface qui est implémentée.

> Note:

> Les interfaces peuvent être étendues comme des classes, en utilisant l'opérateur extends

> Note:

> La classe implémentant l'interface doit déclarer toutes les méthodes dans l'interface avec une signature compatible. Une classe peut implémenter deux interfaces qui définissent une méthode avec le même nom. Dans ce cas, l'implémentation doit suivre les règles de compatibilité des signatures pour toutes les interfaces. Ainsi, la covariance et la contravariance peuvent être appliquées.

### Les constantes

Les interfaces peuvent contenir des constantes. Les constantes d'interfaces fonctionnent exactement comme les constantes de classe. Avant PHP 8.1.0, elles ne peuvent pas être redéfinies par une classe/interface qui les hérite.

### Propriétés

À partir de PHP 8.4.0, les interfaces peuvent également déclarer des propriétés. Si elles le font, la déclaration doit spécifier si la propriété est lisible, modifiable, ou les deux. La déclaration de l'interface s'applique uniquement à l'accès en lecture et en écriture publics.

Une classe peut satisfaire une propriété d'interface de plusieurs façons. Elle peut définir une propriété publique. Elle peut définir une propriété publique virtuelle qui implémente uniquement le hook correspondant. Ou une propriété en lecture peut être satisfaite par une propriété `readonly`. Cependant, une propriété d'interface qui est modifiable ne peut pas être `readonly`.

Exemple #1 Exemple de propriétés d'interface

    <?php
    interface I
    {
        // Une classe implémentant cette interface DOIT avoir une propriété publiquement lisible,
        // mais que celle-ci soit ou non modifiable publiquement n'est pas restreint.
        public string $readable { get; }

        // Une classe implémentant cette interface DOIT avoir une propriété publiquement modifiable,
        // mais que celle-ci soit ou non lisible publiquement n'est pas restreint.
        public string $writeable { set; }

        // Une classe implémentant cette interface DOIT avoir une propriété qui est à la fois publiquement
        // lisible et publiquement modifiable.
        public string $both { get; set; }
    }

    // Cette classe implémente les trois propriétés comme des propriétés traditionnelles, sans hooks.
    // C'est tout à fait valide.
    class C1 implements I
    {
        public string $readable;

        public string $writeable;

        public string $both;
    }

    // Cette classe implémente les trois propriétés en utilisant uniquement les hooks
    // demandés. Cela est également tout à fait valide.
    class C2 implements I
    {
        private string $written = '';
        private string $all = '';

        // Utilise uniquement un hook get pour créer une propriété virtuelle.
        // Cela satisfait l'exigence "get public".
        // Elle n'est pas modifiable, mais cela n'est pas exigé par l'interface.
        public string $readable { get => strtoupper($this->writeable); }

        // L'interface exige uniquement que la propriété soit modifiable,
        // mais inclure des opérations get est également tout à fait valide.
        // Cet exemple crée une propriété virtuelle, ce qui est acceptable.
        public string $writeable {
            get => $this->written;
            set {
                $this->written = $value;
            }
        }

        // Cette propriété nécessite que la lecture et l'écriture soient possibles,
        // nous devons donc soit implémenter les deux, soit permettre le comportement par défaut.
        public string $both {
            get => $this->all;
            set {
                $this->all = strtoupper($value);
            }
        }
    }
    ?>

### Exemples

Exemple #2 Exemple d'interface

    <?php

    // Déclaration de l'interface 'Template'
    interface Template
    {
        public function setVariable($name, $var);
        public function getHtml($template);
    }

    // Implémentation de l'interface
    // Ceci va fonctionner
    class WorkingTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }

        public function getHtml($template)
        {
            foreach($this->vars as $name => $value) {
                $template = str_replace('{' . $name . '}', $value, $template);
            }

            return $template;
        }
    }

    // Ceci ne fonctionnera pas
    // Erreur fatale : Class BadTemplate contains 1 abstract methods
    // and must therefore be declared abstract (Template::getHtml)
    class BadTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }
    }
    ?>

Exemple #3 Les interfaces extensibles

    <?php
    interface A
    {
        public function foo();
    }

    interface B extends A
    {
        public function baz(Baz $baz);
    }

    // Ceci fonctionnera
    class C implements B
    {
        public function foo()
        {
        }

        public function baz(Baz $baz)
        {
        }
    }

    // Ceci ne fonctionnera pas et entraînera une erreur fatale
    class D implements B
    {
        public function foo()
        {
        }

        public function baz(Foo $foo)
        {
        }
    }
    ?>

Exemple #4 Compatibilité de la variance avec plusieurs interfaces

    <?php
    class Foo {}
    class Bar extends Foo {}

    interface A {
        public function myfunc(Foo $arg): Foo;
    }

    interface B {
        public function myfunc(Bar $arg): Bar;
    }

    class MyClass implements A, B
    {
        public function myfunc(Foo $arg): Bar
        {
            return new Bar();
        }
    }
    ?>

Exemple #5 Héritage de plusieurs interfaces

    <?php
    interface A
    {
        public function foo();
    }

    interface B
    {
        public function bar();
    }

    interface C extends A, B
    {
        public function baz();
    }

    class D implements C
    {
        public function foo()
        {
        }

        public function bar()
        {
        }

        public function baz()
        {
        }
    }
    ?>

Exemple #6 Interfaces avec des constantes

    <?php
    interface A
    {
        const B = 'Constante de l\'interface';
    }

    // Affiche : Constante de l'interface
    echo A::B;

    class B implements A
    {
        const B = 'Constante de classe';
    }

    // Affiche : Constante de classe
    // Avant PHP 8.1.0, ceci ne fonctionnera pas, puisqu'il n'était pas permis
    // de redéfinir des constantes.
    echo B::B;
    ?>

Exemple #7 Les interfaces avec les classes abstraites

    <?php
    interface A
    {
        public function foo(string $s): string;

        public function bar(int $i): int;
    }

    // Une classe abstraite peut implémenter seulement une partie de l'interface.
    // Les classes qui étendent la classe abstraite doivent implémenter le reste.
    abstract class B implements A
    {
        public function foo(string $s): string
        {
            return $s . PHP_EOL;
        }
    }

    class C extends B
    {
        public function bar(int $i): int
        {
            return $i * 2;
        }
    }
    ?>

Exemple #8 Étendant et implémentant simultanément

    <?php

    class One
    {
        /* ... */
    }

    interface Usable
    {
        /* ... */
    }

    interface Updatable
    {
        /* ... */
    }

    // L'ordre des mots-clés ici est important. 'extends' doit venir en premier.
    class Two extends One implements Usable, Updatable
    {
        /* ... */
    }
    ?>

Une interface, avec les déclarations de types, fournit une bonne manière pour s'assurer qu'un objet particulier contient des méthodes particulières. Voir l'opérateur instanceof et les déclarations de type.

## Traits

PHP implémente une manière pour réutiliser du code appelée Traits.

Les traits sont un mécanisme de réutilisation de code dans un langage à héritage simple tel que PHP. Un trait tente de réduire certaines limites de l'héritage simple, en autorisant le développeur à réutiliser librement des jeux de méthodes dans plusieurs classes indépendantes vivant dans des hiérarchies de classes différentes. La sémantique de la combinaison des Traits et des classes est définie de manière à réduire la complexité et à éviter les problèmes typiques associés à l'héritage multiple et aux Mixins.

Un Trait est semblable à une classe, mais il ne sert qu'à grouper des fonctionnalités d'une manière fine et cohérente. Il n'est pas possible d'instancier un Trait en lui-même. C'est un ajout à l'héritage traditionnel, qui permet la composition horizontale de comportements, c'est-à-dire l'application de membres de classe sans nécessiter d'héritage.

Exemple #1 Exemple d'utilisation de Trait

    <?php

    trait TraitA {
        public function sayHello() {
            echo 'Hello';
        }
    }

    trait TraitB {
        public function sayWorld() {
            echo 'World';
        }
    }

    class MyHelloWorld
    {
        use TraitA, TraitB; // Une classe peut utiliser plusieurs traits

        public function sayHelloWorld() {
            $this->sayHello();
            echo ' ';
            $this->sayWorld();
            echo "!\n";
        }
    }

    $myHelloWorld = new MyHelloWorld();
    $myHelloWorld->sayHelloWorld();

    ?>

L'exemple ci-dessus va afficher :

    Hello World!

### Précédence

Une méthode héritée depuis une classe mère est écrasée par une méthode issue d'un Trait. L'ordre de précédence fait en sorte que les méthodes de la classe courante écrasent les méthodes issues d'un Trait, elles-mêmes surchargeant les méthodes héritées.

Exemple #2 Exemple avec l'ordre de précédence

Une méthode héritée depuis la classe de base est écrasée par la méthode insérée dans MyHelloWorld depuis le Trait SayWorld. Le comportement est le même pour les méthodes définies dans la classe MyHelloWorld. L'ordre de précédence fait en sorte que les méthodes de la classe courante écrasent les méthodes du Trait, elles-mêmes surchargeant les méthodes de la classe de base.

    <?php
    class Base {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait SayWorld {
        public function sayHello() {
            parent::sayHello();
            echo 'World!';
        }
    }

    class MyHelloWorld extends Base {
        use SayWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    ?>

L'exemple ci-dessus va afficher :

    Hello World!

Exemple #3 Autre exemple d'ordre de précédence

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hello World!';
        }
    }

    class TheWorldIsNotEnough {
        use HelloWorld;
        public function sayHello() {
            echo 'Hello Universe!';
        }
    }

    $o = new TheWorldIsNotEnough();
    $o->sayHello();
    ?>

L'exemple ci-dessus va afficher :

    Hello Universe!

### Multiples Traits

Une classe peut utiliser de multiples Traits en les déclarant avec le mot-clé `use`, séparés par des virgules.

Exemple #4 Utilisation de plusieurs Traits

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait World {
        public function sayWorld() {
            echo 'World';
        }
    }

    class MyHelloWorld {
        use Hello, World;
        public function sayExclamationMark() {
            echo '!';
        }
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    $o->sayExclamationMark();
    ?>

L'exemple ci-dessus va afficher :

    Hello World!

### Résolution des conflits

Si deux Traits insèrent une méthode avec le même nom, une erreur fatale est levée si le conflit n'est pas explicitement résolu.

Pour résoudre un conflit de nommage entre des Traits utilisés dans la même classe, il faut utiliser l'opérateur `insteadof` pour choisir une des méthodes en conflit.

Puisque ce principe ne permet que d'exclure des méthodes, l'opérateur `as` peut être utilisé pour permettre l'inclusion d'une des méthodes conflictuelles sous un autre nom. Il est à noter que l'opérateur `as` ne renomme pas la méthode et n'affecte pas d'autres méthodes non plus.

Exemple #5 Résolution des conflits

Dans cet exemple, la classe Talker utilise les traits A et B. Comme A et B ont des méthodes conflictuelles, on indique que l'on souhaite utiliser la variante de smallTalk depuis le trait B, et la variante de bigTalk depuis le trait A.

La classe Aliased_Talker utilise l'opérateur `as` pour être capable d'utiliser l'implémentation bigTalk de B sous un alias supplémentaire `talk`.

    <?php
    trait A {
        public function smallTalk() {
            echo 'a';
        }
        public function bigTalk() {
            echo 'A';
        }
    }

    trait B {
        public function smallTalk() {
            echo 'b';
        }
        public function bigTalk() {
            echo 'B';
        }
    }

    class Talker {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
        }
    }

    class Aliased_Talker {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
            B::bigTalk as talk;
        }
    }
    ?>

### Changer la visibilité des méthodes

En utilisant la syntaxe `as`, il est aussi possible d'ajuster la visibilité de la méthode dans la classe qui l'utilise.

Exemple #6 Changer la visibilité des méthodes

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hello World!';
        }
    }

    // Modification de la visibilité de la méthode sayHello
    class MyClass1 {
        use HelloWorld { sayHello as protected; }
    }

    // Utilisation d'un alias lors de la modification de la visibilité
    // La visibilité de la méthode sayHello n'est pas modifiée
    class MyClass2 {
        use HelloWorld { sayHello as private myPrivateHello; }
    }
    ?>

### Traits Composés depuis d'autres Traits

Tout comme les classes peuvent utiliser des traits, d'autres traits le peuvent aussi. Un trait peut donc utiliser d'autres traits et hériter de tout ou d'une partie de ceux-ci.

Exemple #7 Traits Composés depuis d'autres Traits

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait World {
        public function sayWorld() {
            echo 'World!';
        }
    }

    trait HelloWorld {
        use Hello, World;
    }

    class MyHelloWorld {
        use HelloWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    ?>

L'exemple ci-dessus va afficher :

    Hello World!

### Méthodes abstraites dans les Traits

Les traits supportent l'utilisation de méthodes abstraites afin d'imposer des contraintes aux classes sous-jacentes. Les méthodes publiques, protégées, et privées sont supportées. Avant PHP 8.0.0, seules les méthodes publiques et protégées abstraites étaient supportées.

Attention

À partir de PHP 8.0.0, la signature d'une méthode concrète doit suivre les règles de compatibilité des signatures. Auparavant, sa signature pouvait être différente.

Exemple #8 Obligations requises par les méthodes abstraites

    <?php
    trait Hello {
        public function sayHelloWorld() {
            echo 'Hello'.$this->getWorld();
        }
        abstract public function getWorld();
    }

    class MyHelloWorld {
        private $world;
        use Hello;
        public function getWorld() {
            return $this->world;
        }
        public function setWorld($val) {
            $this->world = $val;
        }
    }
    ?>

### Membres statiques dans les Traits

Les traits peuvent définir des variables statiques, méthodes statiques et propriétés statiques.

> Note:

> À partir de PHP 8.1.0, appeler une méthode statique ou accéder à une propriété statique directement sur un trait est obsolète. Les méthodes et propriétés statiques devraient seulement être accédées sur une classe utilisant le trait.

Exemple #9 Variables statiques

    <?php

    trait Counter
    {
        public function inc()
        {
            static $c = 0;
            $c = $c + 1;
            echo "$c\n";
        }
    }

    class C1
    {
        use Counter;
    }

    class C2
    {
        use Counter;
    }

    $o = new C1();
    $o->inc();
    $p = new C2();
    $p->inc();

    ?>

L'exemple ci-dessus va afficher :

    1
    1

Exemple #10 Méthodes statiques

    <?php

    trait StaticExample
    {
        public static function doSomething()
        {
            return 'Doing something';
        }
    }

    class Example
    {
        use StaticExample;
    }

    echo Example::doSomething();

    ?>

L'exemple ci-dessus va afficher :

    Doing something

Exemple #11 Propriétés statiques

Attention

Avant PHP 8.3.0, les propriétés statiques définies dans un trait étaient partagées entre toutes les classes de la même hiérarchie d'héritage utilisant ce trait. À partir de PHP 8.3.0, si une classe enfant utilise un trait avec une propriété statique, celle-ci sera considérée comme distincte de celle définie dans la classe parente.

    <?php

    trait T
    {
        public static $counter = 1;
    }

    class A
    {
        use T;

        public static function incrementCounter()
        {
            static::$counter++;
        }
    }

    class B extends A
    {
        use T;
    }

    A::incrementCounter();

    echo A::$counter, "\n";
    echo B::$counter, "\n";

    ?>

Résultat de l'exemple ci-dessus en PHP 8.3 :

    2
    1

### Propriétés

Les traits peuvent aussi définir des propriétés.

Exemple #12 Définir des propriétés

    <?php

    trait PropertiesTrait
    {
        public $x = 1;
    }

    class PropertiesExample
    {
        use PropertiesTrait;
    }

    $example = new PropertiesExample();
    $example->x;

    ?>

Si un trait définit une propriété, alors la classe ne peut pas définir une propriété de même nom sauf si elle est compatible (même visibilité, type, modificateur readonly, valeur initiale), sinon une erreur fatale est émise.

Exemple #13 Résolution des conflits

    <?php
    trait PropertiesTrait {
        public $same = true;
        public $different1 = false;
        public bool $different2;
        public bool $different3;
    }

    class PropertiesExample {
        use PropertiesTrait;
        public $same = true;
        public $different1 = true; // Erreur fatale
        public string $different2; // Erreur fatale
        readonly protected bool $different3; // Erreur fatale
    }
    ?>

### Constantes

Les traits peuvent, à partir de PHP 8.2.0, aussi définir des constantes.

Exemple #14 Trait définissant une constante

    <?php
    trait ConstantsTrait {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample {
        use ConstantsTrait;
    }

    $example = new ConstantsExample;
    echo $example::FLAG_MUTABLE;
    ?>

L'exemple ci-dessus va afficher :

    1

Si un trait définit une constante, alors une classe ne peut pas définir une constante avec le même nom, à moins qu'elle ne soit compatible (même visibilité, même valeur initiale et caractère final), sinon une erreur fatale est émise.

Exemple #15 Résolution des conflits

    <?php
    trait ConstantsTrait {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample {
        use ConstantsTrait;
        public const FLAG_IMMUTABLE = 5; // Erreur fatale
    }
    ?>

### Méthodes finales

À partir de PHP 8.3.0, le modificateur final peut être appliqué à l'aide de l'opérateur `as` aux méthodes importées depuis les traits. Cela peut être utilisé pour empêcher les classes enfants de surcharger la méthode. Cependant, la classe qui utilise le trait peut toujours surcharger la méthode.

Exemple #16 Définir une méthode provenant d'un trait comme `final`

    <?php

    trait CommonTrait
    {
        public function method()
        {
            echo 'Hello';
        }
    }

    class FinalExampleA
    {
        use CommonTrait {
            CommonTrait::method as final; // Le 'final' empêche les classes enfants de surcharger la méthode
        }
    }

    class FinalExampleB extends FinalExampleA
    {
        public function method() {}
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Fatal error: Cannot override final method FinalExampleA::method() in ...

## Classes anonymes

Les classes anonymes sont utiles lorsque de simples objets uniques ont besoin d'être créés.

    <?php

    // Utilisant une classe explicite
    class Logger
    {
        public function log($msg)
        {
            echo $msg;
        }
    }

    $util->setLogger(new Logger());

    // Utilisant une classe anonyme
    $util->setLogger(new class {
        public function log($msg)
        {
            echo $msg;
        }
    });

On peut leur passer des arguments via le constructeur, elles peuvent étendre d'autres classes, implémenter des interfaces ou utiliser des traits comme avec une classe normale.

    <?php

    class SomeClass {}
    interface SomeInterface {}
    trait SomeTrait {}

    var_dump(new class(10) extends SomeClass implements SomeInterface {
        private $num;

        public function __construct($num)
        {
            $this->num = $num;
        }

        use SomeTrait;
    });

L'exemple ci-dessus va afficher :

    object(class@anonymous)#1 (1) {
      ["Command line code0x104c5b612":"class@anonymous":private]=>
      int(10)
    }

Imbriquer une classe anonyme à l'intérieur d'une autre classe ne donne pas accès aux méthodes ou propriétés privées ou protégées de la classe contenante. Afin d'utiliser des méthodes ou propriétés protégées de la classe contenante, la classe anonyme doit étendre celle-ci. Pour utiliser les propriétés privées de la classe contenante dans la classe anonyme, celles-ci doivent être passées via le constructeur.

    <?php

    class Outer
    {
        private $prop = 1;
        protected $prop2 = 2;

        protected function func1()
        {
            return 3;
        }

        public function func2()
        {
            return new class($this->prop) extends Outer {
                private $prop3;

                public function __construct($prop)
                {
                    $this->prop3 = $prop;
                }

                public function func3()
                {
                    return $this->prop2 + $this->prop3 + $this->func1();
                }
            };
        }
    }

    echo (new Outer)->func2()->func3();

L'exemple ci-dessus va afficher :

    6

Tous les objets créés par la même déclaration de classe anonyme sont des instances de cette même classe.

    <?php
    function anonymous_class()
    {
        return new class {};
    }

    if (get_class(anonymous_class()) === get_class(anonymous_class())) {
        echo 'même classe';
    } else {
        echo 'classe différente';
    }

L'exemple ci-dessus va afficher :

    même classe

> Note:

> Il est à noter que les classes anonymes sont affectées d'un nom par le moteur, comme l'illustre l'exemple suivant. Ce nom doit être considéré comme un détail de mise en œuvre, qui ne doit pas être invoqué.

>     <?php
>     echo get_class(new class {});

> Résultat de l'exemple ci-dessus est similaire à :

>     class@anonymous/in/oNi1A0x7f8636ad2021

### Classes anonymes en lecture seule

À partir de PHP 8.3.0, le modificateur `readonly` peut être appliqué aux classes anonymes.

Exemple #1 Définir une classe anonyme en lecture seule

    <?php
    // Utilisation d'une classe anonyme
    var_dump(new readonly class('[DEBUG]') {
        public function __construct(private string $prefix)
        {
        }

        public function log($msg)
        {
            echo $this->prefix . ' ' . $msg;
        }
    });

## Surcharge magique

La surcharge magique en PHP permet de "créer" dynamiquement des propriétés et des méthodes. Ces entités dynamiques sont traitées via des méthodes magiques établies que l'on peut positionner dans une classe pour divers types d'actions.

Les méthodes magiques de surcharge sont appelées lors de l'interaction avec des propriétés ou des méthodes qui n'ont pas été déclarées ou ne sont pas visibles dans le contexte courant. Le reste de cette section utilise les termes de propriétés inaccessibles et de méthodes inaccessibles pour se référer à cette combinaison de déclaration et de visibilité.

Toutes les méthodes magiques de surcharge doivent être définies comme `public`.

> Note:

> Aucun des arguments de ces méthodes magiques ne peut être passé par référence.

> Note:

> L'interprétation PHP de la surcharge est différente de celle de la plupart des langages orientés objet. La surcharge, habituellement, fournit la possibilité d'avoir plusieurs méthodes portant le même nom mais avec une quantité et des types différents d'arguments.

### Surcharge de propriétés

public function __set(string `$name`, mixed `$value`): void
public function __get(string `$name`): mixed
public function __isset(string `$name`): bool
public function __unset(string `$name`): void

__set() est sollicitée lors de l'écriture de données vers des propriétés inaccessibles (protégées ou privées) ou non existantes.

__get() est appelée pour lire des données depuis des propriétés inaccessibles (protégées ou privées) ou non existantes.

__isset() est sollicitée lorsque isset() ou empty() sont appelées sur des propriétés inaccessibles (protégées ou privées) ou non existantes.

__unset() est invoquée lorsque unset() est appelée sur des propriétés inaccessibles (protégées ou privées) ou non existantes.

L'argument $name est le nom de la propriété avec laquelle on interagit. L'argument $value de la méthode __set() spécifie la valeur à laquelle la propriété $name devrait être définie.

La surcharge de propriétés ne fonctionne que dans les contextes objets. Ces méthodes magiques ne seront pas lancées en contexte statique. Par conséquent, ces méthodes ne devraient pas être déclarées comme statiques. Un avertissement est levé si une des méthodes magiques est déclarée comme statique.

> Note:

> La valeur retournée par __set() est ignorée en raison de la façon dont PHP traite l'opérateur d'affectation. De la même façon, __get() n'est jamais appelée lors d'un enchaînement d'affectation, comme ceci : ``

>      $a = $obj->b = 8;

> Note:

> PHP n'appellera pas une méthode surchargée à partir de la même méthode surchargée. Cela signifie, par exemple, qu'écrire `return $this->foo` à l'intérieur de __get() retournera `null` et lèvera un `E_WARNING` s'il n'y a pas de propriété `foo` définie, plutôt que d'appeler __get() une deuxième fois. Toutefois, les méthodes de surcharge peuvent invoquer d'autres méthodes de surcharge de manière implicite (par exemple, __set() déclenchant __get()).

Exemple #1 Exemple de surcharge de propriétés avec les méthodes __get(), __set(), __isset() et __unset()

    <?php
    class PropertyTest
    {
        /**  Variable pour les données surchargées.  */
        private $data = array();

        /**  La surcharge n'est pas utilisée sur les propriétés déclarées.  */
        public $declared = 1;

        /**  La surcharge n'est lancée que lorsque l'on accède à cette propriété depuis l'extérieur de la classe.  */
        private $hidden = 2;

        public function __set($name, $value)
        {
            echo "Définition de '$name' à la valeur '$value'\n";
            $this->data[$name] = $value;
        }

        public function __get($name)
        {
            echo "Récupération de '$name'\n";
            if (array_key_exists($name, $this->data)) {
                return $this->data[$name];
            }

            $trace = debug_backtrace();
            trigger_error(
                'Propriété non-définie via __get() : ' . $name .
                ' dans ' . $trace[0]['file'] .
                ' à la ligne ' . $trace[0]['line'],
                E_USER_NOTICE);
            return null;
        }

        public function __isset($name)
        {
            echo "Est-ce que '$name' est défini ?\n";
            return isset($this->data[$name]);
        }

        public function __unset($name)
        {
            echo "Effacement de '$name'\n";
            unset($this->data[$name]);
        }

        /**  Ce n'est pas une méthode magique, nécessaire ici que pour l'exemple.  */
        public function getHidden()
        {
            return $this->hidden;
        }
    }

    $obj = new PropertyTest;

    $obj->a = 1;
    echo $obj->a . "\n\n";

    var_dump(isset($obj->a));
    unset($obj->a);
    var_dump(isset($obj->a));
    echo "\n";

    echo $obj->declared . "\n\n";

    echo "Manipulons maintenant la propriété privée nommée 'hidden' :\n";
    echo "'hidden' est visible depuis la classe, donc __get() n'est pas utilisée...\n";
    echo $obj->getHidden() . "\n";
    echo "'hidden' n'est pas visible en dehors de la classe, donc __get() est utilisée...\n";
    echo $obj->hidden . "\n";
    ?>

L'exemple ci-dessus va afficher :

    Définition de 'a' à la valeur '1'
    Récupération de 'a'
    1

    Est-ce que 'a' est défini ?
    bool(true)
    Effacement de 'a'
    Est-ce que 'a' est défini ?
    bool(false)

    1

    Manipulons maintenant la propriété privée nommée 'hidden' :
    'hidden' est visible depuis la classe, donc __get() n'est pas utilisée...
    2
    'hidden' n'est pas visible en dehors de la classe, donc __get() est utilisée...
    Récupération de 'hidden'

    Notice: Propriété non-définie via __get() : hidden dans <file> à la ligne 70 dans <file> à la ligne 29

### Surcharge de méthodes

public function __call(string `$name`, array `$arguments`): mixed
public static function __callStatic(string `$name`, array `$arguments`): mixed

__call() est appelée lorsque l'on invoque des méthodes inaccessibles dans un contexte objet.

__callStatic() est lancée lorsque l'on invoque des méthodes inaccessibles dans un contexte statique.

L'argument $name est le nom de la méthode appelée. L'argument $arguments est un tableau contenant les paramètres passés à la méthode $name.

Exemple #2 Surcharge de méthodes avec __call() et __callStatic()

    <?php
    class MethodTest
    {
        public function __call($name, $arguments)
        {
            // Note : la valeur de $name est sensible à la casse.
            echo "Appel de la méthode '$name' "
                 . implode(', ', $arguments). "\n";
        }

        public static function __callStatic($name, $arguments)
        {
            // Note : la valeur de $name est sensible à la casse.
            echo "Appel de la méthode statique '$name' "
                 . implode(', ', $arguments). "\n";
        }
    }

    $obj = new MethodTest;
    $obj->runTest('dans un contexte objet');

    MethodTest::runTest('dans un contexte statique');
    ?>

L'exemple ci-dessus va afficher :

    Appel de la méthode 'runTest' dans un contexte objet
    Appel de la méthode statique 'runTest' dans un contexte statique

## Parcours d'objets

PHP fournit une manière de définir les objets de manière à ce qu'on puisse parcourir une liste de membres, par exemple avec une structure `foreach`. Par défaut, toutes les propriétés visibles seront utilisées pour le parcours.

Exemple #1 Parcours d'objet simple

    <?php
    class MyClass
    {
      public $var1 = 'valeur 1';
      public $var2 = 'valeur 2';
      public $var3 = 'valeur 3';

      protected $protected = 'variable protégée';
      private   $private   = 'variable privée';

      function iterateVisible() {
         echo "MyClass::iterateVisible:\n";
         foreach ($this as $key => $value) {
             print "$key => $value\n";
         }
      }
    }

    $class = new MyClass();

    foreach($class as $key => $value) {
        print "$key => $value\n";
    }
    echo "\n";

    $class->iterateVisible();

    ?>

L'exemple ci-dessus va afficher :

    var1 => valeur 1
    var2 => valeur 2
    var3 => valeur 3

    MyClass::iterateVisible:
    var1 => valeur 1
    var2 => valeur 2
    var3 => valeur 3
    protected => variable protégée
    private => variable privée

Comme le montre la sortie, l'itération `foreach` a traversé toutes les propriétés visibles qui ont pu être accédées.

### Voir aussi

- Generators
- Iterator
- IteratorAggregate
- SPL Iterators

## Méthodes magiques

Les méthodes magiques sont des méthodes spéciales qui écrasent l'action par défaut de PHP quand certaines actions sont réalisées sur un objet.

Attention

Toutes les méthodes commençant par `__` sont réservées par PHP. Ainsi, il n'est pas recommandé d'utiliser un tel nom de méthode sauf lors de l'écrasage du comportement de PHP.

Les méthodes suivantes sont considérées magiques : __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __serialize(), __unserialize(), __sleep(), __wakeup(), __toString(), __invoke(), __set_state(), __clone(), et __debugInfo().

Avertissement

Toutes les méthodes magiques, à l'exception de __construct(), __destruct(), et __clone(), doivent être déclarées en tant que `public`, sinon une `E_WARNING` est émise. Avant PHP 8.0.0, aucun diagnostic n'était émis pour les méthodes magiques __sleep(), __wakeup(), __serialize(), __unserialize(), et __set_state().

Avertissement

Si des déclarations de types sont utilisées dans la définition d'une méthode magique, elles doivent être identiques à la signature décrite dans ce document. Sinon, une erreur fatale est émise. Avant PHP 8.0.0, aucun diagnostic n'était émis. Cependant, __construct() et __destruct() ne doivent pas déclarer un type de retour ; sinon une erreur fatale est émise.

### __serialize() et __unserialize()

public function __serialize(): array
public function __unserialize(array `$data`): void

serialize() vérifie si la classe a une méthode avec le nom magique __serialize(). Si c'est le cas, cette méthode sera exécutée avant toute sérialisation. Elle doit construire et retourner un tableau associatif de paires clé/valeur qui représente la forme sérialisée de l'objet. Si aucun tableau n'est retourné une TypeError sera lancée.

> Note:

> Si __serialize() et __sleep() sont toutes les deux définies dans le même objet, alors seulement __serialize() sera appelée. __sleep() sera ignorée. Si l'objet implémente l'interface Serializable, la méthode `serialize()` de l'interface sera ignorée et __serialize() sera utilisée à la place.

L'utilisation prévue de __serialize() est de définir une représentation arbitraire de l'objet pour le sérialiser facilement. Les éléments du tableau peuvent correspondre aux propriétés de l'objet mais ceci n'est pas requis.

Inversement, unserialize() vérifie la présence d'une fonction avec le nom magique __unserialize(). Si elle est présente, cette fonction recevra le tableau restauré renvoyé par __serialize(). Elle peut alors restaurer les propriétés de l'objet depuis ce tableau comme approprié.

> Note:

> Si __unserialize() et __wakeup() sont toutes les deux définies dans le même objet, alors seulement __unserialize() sera appelée. __wakeup() sera ignorée.

> Note:

> Cette fonctionnalité est disponible à partir de PHP 7.4.0.

Exemple #1 Serialize et unserialize

    <?php
    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __serialize(): array
        {
            return [
              'dsn' => $this->dsn,
              'user' => $this->username,
              'pass' => $this->password,
            ];
        }

        public function __unserialize(array $data): void
        {
            $this->dsn = $data['dsn'];
            $this->username = $data['user'];
            $this->password = $data['pass'];

            $this->connect();
        }
    }?>

### __sleep() et __wakeup()

Avertissement

Ce mécanisme de sérialisation est doucement obsolète à partir de PHP 8.5.0. Il est maintenu pour la rétrocompatibilité. Cependant, le code nouveau et existant devrait migrer pour utiliser les méthodes magiques __serialize() et __unserialize() à la place.

public function __sleep(): array
public function __wakeup(): void

serialize() vérifie si la classe a une méthode avec le nom magique __sleep(). Si c'est le cas, cette méthode sera exécutée avant toute sérialisation. Elle peut nettoyer l'objet, et elle est supposée retourner un tableau avec les noms de toutes les variables de l'objet qui doivent être sérialisées. Si la méthode ne retourne rien, alors `null` sera sérialisé, et une alerte de type `E_NOTICE` sera émise.

> Note:

> Il n'est pas possible pour __sleep() de retourner des noms de propriétés privées des classes parentes. Le faire résultera en une erreur de niveau `E_NOTICE`. Utiliser __serialize() à la place.

> Note:

> À partir de PHP 8.0.0, retourner une valeur qui n'est pas un tableau depuis __sleep() émet un avertissement. Auparavant une notice était émise.

Le but avoué de __sleep() est de valider des données en attente ou d'effectuer des opérations de nettoyage. De plus, cette fonction est utile si un objet très volumineux n'a pas besoin d'être sauvegardé dans sa totalité.

Réciproquement, la fonction unserialize() vérifie la présence d'une méthode dont le nom est le nom magique __wakeup(). Si elle est présente, cette fonction peut reconstruire toute ressource que l'objet pourrait posséder.

Le but avoué de __wakeup() est de rétablir toute connexion de base de données qui aurait été perdue durant la sérialisation et d'effectuer des tâches de réinitialisation.

Exemple #2 Sleep et wakeup

    <?php
    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __sleep()
        {
            return array('dsn', 'username', 'password');
        }

        public function __wakeup()
        {
            $this->connect();
        }
    }?>

### __toString()

public function __toString(): string

La méthode __toString() détermine comment l'objet doit réagir lorsqu'il est traité comme une chaîne de caractères. Par exemple, ce que `echo $obj;` affichera.

Avertissement

À partir de PHP 8.0.0, la valeur de retour suit les sémantiques standard de PHP, signifiant que la valeur sera convertie en une string si possible et si le typage strict est désactivé.

Un objet Stringable ne sera pas accepté par une déclaration de type string si la déclaration de type strict est activée. Si un tel comportement est souhaité, la déclaration de type doit accepter à la fois Stringable et string via un type union.

À partir de PHP 8.0.0, toute classe qui contient une méthode __toString() implémente aussi implicitement l'interface Stringable, et passera donc les vérifications de types pour cette interface. Implémenter quand même explicitement l'interface est recommandé.

En PHP 7.4, la valeur de retour doit être une string, sinon une Error est lancée.

Antérieurement à PHP 7.4.0, la valeur de retour doit être une string, sinon une `E_RECOVERABLE_ERROR` fatale est émise.

Avertissement

Il était impossible de lancer une exception depuis la méthode __toString() antérieurement à PHP 7.4.0. Cela entraînera une erreur fatale.

Exemple #3 Exemple simple

    <?php
    // Déclaration d'une classe simple
    class ClasseTest
    {
        public $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        public function __toString()
        {
            return $this->foo;
        }
    }

    $class = new ClasseTest('Bonjour');
    echo $class;
    ?>

L'exemple ci-dessus va afficher :

    Bonjour

### __invoke()

function __invoke( `...$values`): mixed

La méthode __invoke() est appelée lorsqu'un script tente d'appeler un objet comme une fonction.

Exemple #4 Exemple avec __invoke()

    <?php
    class CallableClass
    {
        public function __invoke($x)
        {
            var_dump($x);
        }
    }
    $obj = new CallableClass;
    $obj(5);
    var_dump(is_callable($obj));
    ?>

L'exemple ci-dessus va afficher :

    int(5)
    bool(true)

Exemple #5 Exemple avec __invoke()

    <?php
    class Sort
    {
        private $key;

        public function __construct(string $key)
        {
            $this->key = $key;
        }

        public function __invoke(array $a, array $b): int
        {
            return $a[$this->key] <=> $b[$this->key];
        }
    }

    $customers = [
        ['id' => 1, 'first_name' => 'John', 'last_name' => 'Do'],
        ['id' => 3, 'first_name' => 'Alice', 'last_name' => 'Gustav'],
        ['id' => 2, 'first_name' => 'Bob', 'last_name' => 'Filipe']
    ];

    // trier les clients par prénom
    usort($customers, new Sort('first_name'));
    print_r($customers);

    // trier les clients par nom de famille
    usort($customers, new Sort('last_name'));
    print_r($customers);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

    )
    Array
    (
        [0] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

    )

### __set_state()

static function __set_state(array `$properties`): object

Cette méthode statique est appelée pour les classes exportées par la fonction var_export().

Le seul paramètre de cette méthode est un tableau contenant les propriétés exportées sous la forme `['property' => value, ...]`.

Exemple #6 Utilisation de __set_state()

    <?php

    class A
    {
        public $var1;
        public $var2;

        public static function __set_state($an_array)
        {
            $obj = new A;
            $obj->var1 = $an_array['var1'];
            $obj->var2 = $an_array['var2'];
            return $obj;
        }
    }

    $a = new A;
    $a->var1 = 5;
    $a->var2 = 'foo';

    $b = var_export($a, true);
    var_dump($b);
    eval('$c = ' . $b . ';');
    var_dump($c);
    ?>

L'exemple ci-dessus va afficher :

    string(60) "A::__set_state(array(
       'var1' => 5,
       'var2' => 'foo',
    ))"
    object(A)#2 (2) {
      ["var1"]=>
      int(5)
      ["var2"]=>
      string(3) "foo"
    }

> Note: Lors de l'exportation d'un objet, var_export() ne vérifie pas si __set_state() est implémentée par la classe de l'objet, ainsi la réimportation d'objets résultera en une exception Error, si __set_state() n'est pas implémentée. En particulier, cela affecte certaines classes internes. Il est de la responsabilité du programmeur de vérifier que seuls les objets dont la classe implémente __set_state() seront ré-importés.

### __debugInfo()

function __debugInfo(): array

Cette méthode est appelée par var_dump() lors du traitement d'un objet pour récupérer les propriétés qui doivent être affichées. Si la méthode n'est pas définie dans un objet, alors toutes les propriétés publiques, protégées et privées seront affichées.

Exemple #7 Utilisation de __debugInfo()

    <?php
    class C {
        private $prop;

        public function __construct($val) {
            $this->prop = $val;
        }

        public function __debugInfo() {
            return [
                'propSquared' => $this->prop ** 2,
            ];
        }
    }

    var_dump(new C(42));
    ?>

L'exemple ci-dessus va afficher :

    object(C)#1 (1) {
      ["propSquared"]=>
      int(1764)
    }

## Mot-clé "final"

Le mot-clé `final` empêche les classes enfants de redéfinir une méthode, une propriété ou une constante en préfixant la définition avec `final`. Si la classe elle-même est définie comme finale, elle ne pourra pas être étendue.

Exemple #1 Exemple de méthode finale

    <?php
    class BaseClass {
       public function test() {
           echo "BaseClass::test() appelée\n";
       }

       final public function moreTesting() {
           echo "BaseClass::moreTesting() appelée\n";
       }
    }

    class ChildClass extends BaseClass {
       public function moreTesting() {
           echo "ChildClass::moreTesting() appelée\n";
       }
    }
    // Résultat : Fatal error: Cannot override final method BaseClass::moreTesting()
    ?>

Exemple #2 Exemple de classe finale

    <?php
    final class BaseClass {
       public function test() {
           echo "BaseClass::test() appelée\n";
       }

       // Comme la classe est déjà finale, le mot clé final est redondant
       final public function moreTesting() {
           echo "BaseClass::moreTesting() appelée\n";
       }
    }

    class ChildClass extends BaseClass {
    }
    // Résultat : Fatal error: Class ChildClass may not inherit from final class (BaseClass)
    ?>

Exemple #3 Exemple de propriété finale à partir de PHP 8.4.0

    <?php
    class BaseClass {
       final protected string $test;
    }

    class ChildClass extends BaseClass {
        public string $test;
    }
    // Résultat : Fatal error: Cannot override final property BaseClass::$test
    ?>

Exemple #4 Exemple de constantes finales à partir de PHP 8.1.0

    <?php
    class Foo
    {
        final public const X = "foo";
    }

    class Bar extends Foo
    {
        public const X = "bar";
    }

    // Résultat : Fatal error: Bar::X cannot override final constant Foo::X
    ?>

> Note: À partir de PHP 8.0.0, les méthodes privées ne peuvent plus être déclarées finales, à l'exception du constructeur.

> Note: Une propriété déclarée `private(set)` est implicitement `final`.

## Clonage d'objets

Le fait de créer une copie d'un objet possédant exactement les mêmes propriétés n'est pas toujours le comportement que l'on souhaite. Un bon exemple pour illustrer le besoin d'un constructeur de copie : dans le cas d'un objet qui représente une fenêtre GTK et qui contient la ressource représentant cette fenêtre GTK, lors de la création d'une copie, il peut être souhaitable de créer une nouvelle fenêtre avec les mêmes propriétés, mais que le nouvel objet contienne une ressource représentant la nouvelle fenêtre. Un autre exemple est le cas où un objet contient une référence vers un autre objet qu'il utilise et, lors de la réplication de l'objet parent, il est souhaitable de créer une nouvelle instance de cet autre objet afin que la réplique possède sa propre copie séparée.

Une copie d'objet est créée en utilisant le mot-clé `clone` (qui fait appel à la méthode __clone() de l'objet, si possible).

    $copy_of_object = clone $object;

Lorsqu'un objet est cloné, PHP effectue une copie superficielle de toutes les propriétés de l'objet. Toutes les propriétés qui sont des références à d'autres variables demeureront des références.

function __clone(): void

Une fois le clonage effectué, si une méthode __clone() est définie, la méthode __clone() du nouvel objet sera appelée, pour permettre à chaque propriété qui doit l'être d'être modifiée.

Exemple #1 Exemple de duplication d'objets

    <?php
    class SubObject
    {
      static $instances = 0;
      public $instance;

      public function __construct() {
        $this->instance = ++self::$instances;
      }

      public function __clone() {
        $this->instance = ++self::$instances;
      }
    }

    class MyCloneable
    {
      public $object1;
      public $object2;

      function __clone()
      {
        // Force la copie de this->object, sinon
        // il pointera vers le même objet.
        $this->object1 = clone $this->object1;
      }
    }

    $obj = new MyCloneable();

    $obj->object1 = new SubObject();
    $obj->object2 = new SubObject();

    $obj2 = clone $obj;

    print "Objet original :\n";
    print_r($obj);

    print "Objet cloné :\n";
    print_r($obj2);

    ?>

L'exemple ci-dessus va afficher :

    Objet original :
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 1
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )
    Objet cloné :
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 3
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )

Il est possible d'accéder à un membre d'un objet fraîchement cloné dans une seule expression:

Exemple #2 Accès à un membre d'un objet fraîchement cloné

    <?php
    $dateTime = new DateTime();
    echo (clone $dateTime)->format('Y');
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    2016

## Comparaison d'objets

Lors de l'utilisation de l'opérateur de comparaison (`==`), les objets sont comparés de manière simple, à savoir : deux objets sont égaux s'ils ont les mêmes attributs et valeurs (les valeurs sont comparées avec l'opérateur `==`), et qu'ils sont des instances de la même classe.

Lors de l'utilisation de l'opérateur d'identité (`===`), les objets sont identiques uniquement s'ils font référence à la même instance de la même classe.

Un exemple va illustrer ces règles.

Exemple #1 Exemple de comparaison d'objets en PHP

    <?php
    function bool2str($bool)
    {
        if ($bool === false) {
                return 'FALSE';
        } else {
                return 'TRUE';
        }
    }

    function compareObjects(&$o1, &$o2)
    {
        echo 'o1 == o2 : '.bool2str($o1 == $o2)."\n";
        echo 'o1 != o2 : '.bool2str($o1 != $o2)."\n";
        echo 'o1 === o2 : '.bool2str($o1 === $o2)."\n";
        echo 'o1 !== o2 : '.bool2str($o1 !== $o2)."\n";
    }

    class Flag
    {
        public $flag;

        function __construct($flag = true) {
            $this->flag = $flag;
        }
    }

    class OtherFlag
    {
        public $flag;

        function __construct($flag = true) {
            $this->flag = $flag;
        }
    }

    $o = new Flag();
    $p = new Flag();
    $q = $o;
    $r = new OtherFlag();

    echo "Deux instances de la même classe\n";
    compareObjects($o, $p);

    echo "\nDeux références sur le même objet\n";
    compareObjects($o, $q);

    echo "\nInstances de classes différentes\n";
    compareObjects($o, $r);
    ?>

L'exemple ci-dessus va afficher :

    Deux instances de la même classe
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

    Deux références sur le même objet
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : TRUE
    o1 !== o2 : FALSE

    Instances de classes différentes
    o1 == o2 : FALSE
    o1 != o2 : TRUE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

> Note:

> Les extensions peuvent définir leurs propres règles pour leurs comparaisons d'objets (`==`).

## Late Static Bindings (Résolution statique à la volée)

PHP implémente une fonctionnalité appelée `late static binding`, en français la résolution statique à la volée, qui peut être utilisée pour référencer la classe appelée dans un contexte d'héritage statique.

Plus précisément, les résolutions statiques à la volée fonctionnent en enregistrant le nom de la classe dans le dernier "appel non transmis". Dans le cas des appels de méthodes statiques, il s'agit de la classe explicitement nommée (généralement, celle à gauche de l'opérateur `::`) ; dans le cas de méthodes non statiques, il s'agit de la classe de l'objet. Un "appel transmis" est un appel statique déclenché par `self::`, `parent::`, `static::`, ou, tout en haut de la hiérarchie des classes, forward_static_call(). La fonction get_called_class() peut être utilisée pour récupérer une chaîne contenant le nom de la classe appelée, et `static::` introduit sa portée.

Cette fonctionnalité a été baptisée `"late static bindings"`, avec un point de vue interne. `"Late binding"`, littéralement résolution tardive, vient du fait que les éléments `static::` ne seront pas résolus en utilisant la classe où la méthode a été définie, mais celle qui est active durant l'exécution. L'adjectif statique a été ajouté car ce problème s'applique (sans y être limité) aux méthodes statiques.

### Limitations de `self::`

Les références statiques à la classe courante, avec `self::` ou `__CLASS__`, sont résolues en utilisant la classe à laquelle appartiennent les fonctions, celle où elles ont été définies :

Exemple #1 Utilisation de `self::`

    <?php

    class A
    {
        public static function qui()
        {
            echo __CLASS__;
        }
        public static function test()
        {
            self::qui();
        }
    }

    class B extends A
    {
        public static function qui()
        {
             echo __CLASS__;
        }
    }

    B::test();

    ?>

L'exemple ci-dessus va afficher :

    A

### Utilisation de la résolution statique à la volée

La résolution statique à la volée essaie de dépasser cette limitation en introduisant un mot clé qui fait référence à la classe qui a été appelée durant l'exécution. Pour faire simple, ce mot-clé permet le référencement à `B` depuis `test()`, dans l'exemple précédent. Il a été décidé de ne pas introduire de nouveau mot clé, mais plutôt d'utiliser le mot `static` qui était déjà réservé.

Exemple #2 Utilisation simple de `static::`

    <?php

    class A
    {
        public static function qui()
        {
            echo __CLASS__;
        }
        public static function test()
        {
            static::qui(); // Ici, résolution à la volée
        }
    }

    class B extends A
    {
        public static function qui()
        {
             echo __CLASS__;
        }
    }

    B::test();

    ?>

L'exemple ci-dessus va afficher :

    B

> Note:

> Dans les contextes non statiques, la classe appelée sera celle de l'objet. Comme `$this->` essayera d'appeler des méthodes privées depuis le même contexte, utiliser `static::` pourrait donner des résultats différents. Une autre différence est que `static::` ne peut faire référence qu'à des propriétés statiques.

Exemple #3 Utilisation de `static::` dans un contexte non statique

    <?php

    class A
    {
        private function foo()
        {
            echo "Success!\n";
        }
        public function test()
        {
            $this->foo();
            static::foo();
        }
    }

    class B extends A
    {
       /* foo() sera copiée dans B, par conséquent son contexte sera toujours A
        * et l'appel se fera sans problème */
    }

    class C extends A
    {
        private function foo()
        {
            /* La méthode originale est remplacée; le contexte est celui de C */
        }
    }

    $b = new B();
    $b->test();

    $c = new C();
    try {
        $c->test();
    } catch (Error $e) {
        echo $e->getMessage();
    }

    ?>

L'exemple ci-dessus va afficher :

    Success!
    Success!
    Success!
    Call to private method C::foo() from scope A

> Note:

> La résolution des statiques à la volée va s'arrêter à un appel statique complètement résolu. D'un autre côté, les appels statiques en utilisant un mot-clé comme `parent::` ou `self::` vont transmettre l'information appelante.

> Exemple #4 Appel avec ou sans transmission

>     <?php

>     class A
>     {
>         public static function foo()
>         {
>             static::qui();
>         }

>         public static function qui()
>         {
>             echo __CLASS__."\n";
>         }
>     }

>     class B extends A
>     {
>         public static function test()
>         {
>             A::foo();
>             parent::foo();
>             self::foo();
>         }

>         public static function qui()
>         {
>             echo __CLASS__."\n";
>         }
>     }
>     class C extends B
>     {
>         public static function qui()
>         {
>             echo __CLASS__."\n";
>         }
>     }

>     C::test();

>     ?>

> L'exemple ci-dessus va afficher :

>     A
>     C
>     C

## Objets et références

Un des piliers de la POO de PHP est le fait que les "objets sont passés par référence par défaut". Ce n'est pas complètement vrai. Cette section rectifie cette généralisation avec quelques exemples.

Une référence PHP est un alias, qui permet à deux variables différentes de représenter la même valeur. Dans PHP, une variable objet ne contient plus l'objet en lui-même comme valeur. Elle contient seulement un identifiant d'objet, qui permet aux accesseurs d'objets de trouver cet objet. Lorsque l'objet est utilisé comme argument, retourné par une fonction, ou assigné à une autre variable, les différentes variables ne sont pas des alias : elles contiennent des copies de l'identifiant, qui pointent sur le même objet.

Exemple #1 Références et Objets

    <?php
    class A {
        public $foo = 1;
    }

    $a = new A;
    $b = $a;     // $a et $b sont des copies du même identifiant
                 // ($a) = ($b) = <id>
    $b->foo = 2;
    echo $a->foo."\n";

    $c = new A;
    $d = &$c;    // $c et $d sont des références
                 // ($c,$d) = <id>

    $d->foo = 2;
    echo $c->foo."\n";

    $e = new A;

    function foo($obj) {
        // ($obj) = ($e) = <id>
        $obj->foo = 2;
    }

    foo($e);
    echo $e->foo."\n";

    ?>

L'exemple ci-dessus va afficher :

    2
    2
    2

## Sérialiser des objets - des objets en session

serialize() retourne une chaîne de caractères contenant une représentation linéaire de n'importe quelle valeur qui peut être stockée en PHP. unserialize() peut utiliser cette chaîne de caractères pour recréer la valeur originale de la variable à partir de sa représentation linéaire. Utiliser serialize() pour sauvegarder un objet conservera toutes ses variables. Ses méthodes ne seront pas conservées, seul le nom de la classe le sera.

Afin de pouvoir désérialiser (unserialize()) un objet, la classe de l'objet doit être définie, pour permettre sa reconstruction. En d'autres termes, pour un objet de la classe A qui est sérialisé, la représentation linéaire obtenue fera référence à la classe A et contiendra toutes ses variables. Pour pouvoir désérialiser cette représentation linéaire dans un endroit où la classe A n'est pas définie (dans un autre fichier par exemple), il faut redéclarer la classe A avant de procéder à la désérialisation de sa représentation linéaire. Cela peut être fait, par exemple, en incluant le fichier de définition de la classe, ou en utilisant la fonction spl_autoload_register().

    <?php
    // A.php :

      class A {
          public $one = 1;

          public function show_one() {
              echo $this->one;
          }
      }

    // page1.php :

      include "A.php";

      $a = new A;
      $s = serialize($a);
      // enregistre $s quelque part où page2.php peut le retrouver
      file_put_contents('store', $s);

    // page2.php :

      // nous avons besoin de la définition de la classe
      // pour qu'unserialize() fonctionne
      include "A.php";

      $s = file_get_contents('store');
      $a = unserialize($s);

      // appel de show_one() sur l'objet $a, affiche 1
      $a->show_one();
    ?>

Si une application sérialise des objets, il est fortement recommandé, pour son usage futur, que l'application inclue les définitions des classes des objets sérialisés à chaque page. Ne pas faire ainsi pourrait aboutir à un objet désérialisé sans sa définition de classe. PHP donnerait alors à cet objet une classe de type __PHP_Incomplete_Class_Name, qui n'a pas de méthode, et produirait un objet inutile.

Ainsi, dans l'exemple ci-dessus, si $a était enregistré dans la session en ajoutant une clé au tableau superglobal $_SESSION, il est recommandé d'inclure le fichier `A.php` dans toutes les pages, et pas seulement dans page1.php et page2.php.

Il est à noter qu'il est également possible d'utiliser les événements de sérialisation et de désérialisation sur un objet en utilisant les méthodes __sleep() et __wakeup(). L'utilisation de __sleep() permet également de seulement sérialiser une partie des propriétés de l'objet.

## Covariance et Contravariance

En PHP 7.2.0, la contravariance partielle a été introduite en supprimant les restrictions de type sur les paramètres d'une méthode enfant. À partir de PHP 7.4.0, la covariance et la contravariance complètes ont été ajoutées.

La covariance permet à une méthode enfant de retourner un type plus spécifique que le type de retour de sa méthode parente. La contravariance permet à un type de paramètre d'être moins spécifique dans une méthode enfant que dans celui de la méthode parente.

Une déclaration de type est considérée comme plus spécifique dans le cas suivant :

- Un type est retiré d'un type union
- Un type est ajouté à un type d'intersection
- Un type de classe est transformé en un type de classe enfant
- iterable est remplacé par array ou Traversable

Un type de classe est considéré moins spécifique si l'inverse est vrai.

### Covariance

Pour illustrer le fonctionnement de la covariance, une simple classe parente abstraite, Animal est créée. Animal sera étendu par des classes enfants, Cat et Dog.

    <?php

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        abstract public function speak();
    }

    class Dog extends Animal
    {
        public function speak()
        {
            echo $this->name . " barks";
        }
    }

    class Cat extends Animal
    {
        public function speak()
        {
            echo $this->name . " meows";
        }
    }

Il est à noter qu'il n'y a pas de méthodes qui renvoient des valeurs dans cet exemple. Quelques fabriques seront ajoutées et renverront un nouvel objet de classe de type Animal, Cat, ou Dog.

    <?php

    interface AnimalShelter
    {
        public function adopt(string $name): Animal;
    }

    class CatShelter implements AnimalShelter
    {
        public function adopt(string $name): Cat // au lieu de retourner le type de classe Animal, on peut retourner le type de classe Cat
        {
            return new Cat($name);
        }
    }

    class DogShelter implements AnimalShelter
    {
        public function adopt(string $name): Dog // au lieu de retourner le type de classe Animal, on peut retourner le type de classe Dog
        {
            return new Dog($name);
        }
    }

    $kitty = (new CatShelter)->adopt("Ricky");
    $kitty->speak();
    echo "\n";

    $doggy = (new DogShelter)->adopt("Mavrick");
    $doggy->speak();

L'exemple ci-dessus va afficher :

    Ricky meows
    Mavrick barks

### Contravariance

En reprenant l'exemple précédent avec les classes Animal, Cat et Dog, une classe appelée Food et AnimalFood seront incluses, et une méthode eat(AnimalFood $food) est ajoutée à la classe abstraite Animal.

    <?php

    class Food {}

    class AnimalFood extends Food {}

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        public function eat(AnimalFood $food)
        {
            echo $this->name . " eats " . get_class($food);
        }
    }

Afin de voir le comportement de la contravariance, la méthode eat est surchargée dans la classe Dog afin d'autoriser n'importe quel objet de type Food. La classe Cat reste inchangée.

    <?php

    class Dog extends Animal
    {
        public function eat(Food $food) {
            echo $this->name . " eats " . get_class($food);
        }
    }

L'exemple suivant montre le comportement de la contravariance.

    <?php

    $kitty = (new CatShelter)->adopt("Ricky");
    $catFood = new AnimalFood();
    $kitty->eat($catFood);
    echo "\n";

    $doggy = (new DogShelter)->adopt("Mavrick");
    $banana = new Food();
    $doggy->eat($banana);

L'exemple ci-dessus va afficher :

    Ricky eats AnimalFood
    Mavrick eats Food

Mais que se passe-t-il si $kitty essaie de manger (eat()) la banane ($banana) ?

    $kitty->eat($banana);

L'exemple ci-dessus va afficher :

    Fatal error: Uncaught TypeError: Argument 1 passed to Animal::eat() must be an instance of AnimalFood, instance of Food given

### Variation de type des propriétés

Par défaut, les propriétés ne sont ni covariantes ni contravariantes, donc invariantes. Autrement dit, leur type ne peut pas du tout changer dans une classe enfant. La raison en est que les opérations "get" doivent être covariantes, et les opérations "set" doivent être contravariantes. La seule façon pour une propriété de satisfaire ces deux exigences est d'être invariante.

À partir de PHP 8.4.0, avec l'ajout des propriétés abstraites (sur une interface ou une classe abstraite) et propriétés virtuelles, il est possible de déclarer une propriété qui n'a qu'une opération "get" ou "set". En conséquence, les propriétés abstraites ou les propriétés virtuelles qui n'ont que l'opération "get" requise peuvent être covariantes. De même, une propriété abstraite ou une propriété virtuelle qui n'a que l'opération "set" requise peut être contravariante.

Cependant, une fois qu'une propriété a à la fois une opération "get" et "set", elle n'est plus covariante ni contravariante pour une extension future. Autrement dit, elle devient désormais invariante.

Exemple #1 Variation du type des propriétés

    <?php
    class Animal {}
    class Dog extends Animal {}
    class Poodle extends Dog {}

    interface PetOwner
    {
        // Seule l'opération "get" est requise, donc cela peut être covariant.
        public Animal $pet { get; }
    }

    class DogOwner implements PetOwner
    {
        // Cela peut être un type plus restrictif, car le côté "get"
        // retourne toujours un Animal. Cependant, en tant que propriété native,
        // les enfants de cette classe ne peuvent plus changer le type.
        public Dog $pet;
    }

    class PoodleOwner extends DogOwner
    {
        // Ceci N'EST PAS AUTORISÉ, car DogOwner::$pet a à la fois
        // les opérations "get" et "set" définies et requises.
        public Poodle $pet;
    }
    ?>

## Objets paresseux

Un objet paresseux est un objet dont l'initialisation est différée jusqu'à ce que son état soit observé ou modifié. Quelques exemples d'utilisation incluent des composants d'injection de dépendances qui fournissent des services paresseux entièrement initialisés uniquement si nécessaire, des ORMs fournissant des entités paresseuses qui s'hydratent depuis la base de données uniquement lorsqu'elles sont accédées, ou un analyseur JSON qui retarde l'analyse jusqu'à ce que les éléments soient accédés.

Deux stratégies d'objets paresseux sont prises en charge : les objets fantômes (Ghost) et les proxys virtuels (Virtual Proxies), ci-après appelés "fantômes paresseux" et "proxys paresseux". Dans les deux stratégies, l'objet paresseux est attaché à un initialiseur ou une fabrique qui est appelé automatiquement lorsque son état est observé ou modifié pour la première fois. D'un point de vue d'abstraction, les objets paresseux sont indiscernables des non-paresseux : ils peuvent être utilisés sans savoir qu'ils sont paresseux, ce qui permet de les passer et de les utiliser par du code qui n'est pas conscient de la paresse. Les proxys paresseux sont également transparents, mais il faut faire attention lorsque leur identité est utilisée, car le proxy et son instance réelle ont des identités différentes.

> Note: Information de version
> Les objets paresseux ont été introduits en PHP 8.4.

### Création d'objets paresseux

Il est possible de créer une instance paresseuse de n'importe quelle classe définie par l'utilisateur ou de la classe stdClass (d'autres classes internes ne sont pas prises en charge), ou de réinitialiser une instance de ces classes pour la rendre paresseuse. Les points d'entrée pour créer un objet paresseux sont les méthodes ReflectionClass::newLazyGhost() et ReflectionClass::newLazyProxy().

Les deux méthodes acceptent une fonction qui est appelée lorsque l'objet nécessite une initialisation. Le comportement attendu de la fonction varie en fonction de la stratégie utilisée, comme décrit dans la documentation de référence de chaque méthode.

Exemple #1 Création d'un fantôme paresseux

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyGhost(function (Example $object) {
        // Initialise l'objet sur place
        $object->__construct(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Déclenche l'initialisation
    var_dump($lazyObject->prop);
    ?>

L'exemple ci-dessus va afficher :

    lazy ghost object(Example)#3 (0) {
    ["prop"]=>
    uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

Exemple #2 Création d'un proxy paresseux

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyProxy(function (Example $object) {
        // Crée et retourne l'instance réelle
        return new Example(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Déclenche l'initialisation
    var_dump($lazyObject->prop);
    ?>

L'exemple ci-dessus va afficher :

    lazy proxy object(Example)#3 (0) {
      ["prop"]=>
      uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

N'importe quel accès à des propriétés d'un objet paresseux déclenche son initialisation (y compris via ReflectionProperty). Cependant, certaines propriétés peuvent être connues à l'avance et ne devraient pas déclencher l'initialisation lorsqu'elles sont accédées :

Exemple #3 Initialisation des propriétés de manière impatiente

    <?php
    class BlogPost
    {
        public function __construct(
            public int $id,
            public string $title,
            public string $content,
        ) { }
    }

    $reflector = new ReflectionClass(BlogPost::class);

    $post = $reflector->newLazyGhost(function ($post) {
        $data = fetch_from_store($post->id);
        $post->__construct($data['id'], $data['title'], $data['content']);
    });

    // Sans cette ligne, l'appel suivant à ReflectionProperty::setValue() déclencherait
    // l'initialisation.
    $reflector->getProperty('id')->skipLazyInitialization($post);
    $reflector->getProperty('id')->setValue($post, 123);

    // Également, on peut utiliser ceci directement :
    $reflector->getProperty('id')->setRawValueWithoutLazyInitialization($post, 123);

    // L'identifiant peut être accédé sans déclencher l'initialisation
    var_dump($post->id);
    ?>

Les méthodes ReflectionProperty::skipLazyInitialization() et ReflectionProperty::setRawValueWithoutLazyInitialization() offrent des moyens de contourner l'initialisation paresseuse lors de l'accès à une propriété.

### À propos des stratégies d'objets paresseux

Les fantômes paresseux sont des objets qui s'initialisent sur place et, une fois initialisés, sont indiscernables d'un objet qui n'a jamais été paresseux. Cette stratégie est adaptée lorsque nous contrôlons à la fois l'instanciation et l'initialisation de l'objet et est inadaptée si l'une de ces opérations est gérée par une autre partie.

Les proxys paresseux, une fois initialisés, agissent comme des proxys vers une instance réelle : toute opération sur un proxy paresseux initialisé est transmise à l'instance réelle. La création de l'instance réelle peut être déléguée à une autre partie, ce qui rend cette stratégie utile dans les cas où les fantômes paresseux sont inadaptés. Bien que les proxys paresseux soient presque aussi transparents que les fantômes paresseux, il faut faire attention lorsque leur identité est utilisée, car le proxy et son instance réelle ont des identités distinctes.

### Cycle de vie des objets paresseux

Les objets peuvent être rendus paresseux lors de l'instanciation en utilisant ReflectionClass::newLazyGhost() ou ReflectionClass::newLazyProxy(), ou après l'instanciation en utilisant ReflectionClass::resetAsLazyGhost() ou ReflectionClass::resetAsLazyProxy(). Ensuite, un objet paresseux peut être initialisé par l'une des opérations suivantes :

- Interagir avec l'objet d'une manière qui déclenche l'initialisation automatique. Voir déclencheurs d'initialisation.
- Marquer toutes ses propriétés comme non-paresseuses en utilisant ReflectionProperty::skipLazyInitialization() ou ReflectionProperty::setRawValueWithoutLazyInitialization().
- Appeler explicitement ReflectionClass::initializeLazyObject() ou ReflectionClass::markLazyObjectAsInitialized().

Comme les objets paresseux sont initialisés lorsque toutes leurs propriétés sont marquées non-paresseuses, les méthodes ci-dessus ne marqueront pas un objet comme paresseux si aucune propriété ne peut être marquée comme paresseuse.

### Déclencheurs d'initialisation

Les objets paresseux sont conçus pour être entièrement transparents pour leurs consommateurs, de sorte que les opérations normales qui observent ou modifient l'état de l'objet déclencheront automatiquement l'initialisation avant que l'opération ne soit effectuée. Cela inclut, mais sans s'y limiter, les opérations suivantes :

- Lire ou écrire une propriété
- Tester si une propriété est définie ou la supprimer.
- Accéder ou modifier une propriété via ReflectionProperty::getValue(), ReflectionProperty::getRawValue(), ReflectionProperty::setValue(), ou ReflectionProperty::setRawValue().
- Lister les propriétés avec ReflectionObject::getProperties(), ReflectionObject::getProperty(), get_object_vars().
- Itérer les propriétés d'un objet qui n'implémente pas Iterator ou IteratorAggregate en utilisant foreach.
- Sérialiser l'objet avec serialize(), json_encode(), etc.
- Cloner l'objet.

Les appels de méthodes qui n'accèdent pas à l'état de l'objet ne déclencheront pas l'initialisation. De même, les interactions avec l'objet qui invoquent des méthodes magiques ou des fonctions de crochet ne déclencheront pas l'initialisation si ces méthodes ou fonctions n'accèdent pas à l'état de l'objet.

#### Opérations non déclenchantes

Les méthodes ou opérations spécifiques suivantes permettent d'accéder ou de modifier des objets paresseux sans déclencher l'initialisation :

- Marquer les propriétés comme non-paresseuses avec ReflectionProperty::skipLazyInitialization() ou ReflectionProperty::setRawValueWithoutLazyInitialization().
- Récupérer la représentation interne des propriétés en utilisant get_mangled_object_vars() ou en convertissant l'objet en un tableau.
- Utiliser serialize() lorsque `ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE` est défini, sauf si __serialize() ou __sleep() déclenche l'initialisation.
- Appeler ReflectionObject::__toString().
- Utiliser var_dump() ou debug_zval_dump(), sauf si __debugInfo() déclenche l'initialisation

### Séquence d'initialisation

Cette section décrit la séquence d'opérations effectuées lorsqu'une initialisation est déclenchée, en fonction de la stratégie utilisée.

#### Objets fantômes

- L'objet est marqué comme non-paresseux.
- Les propriétés non initialisées avec ReflectionProperty::skipLazyInitialization() ou ReflectionProperty::setRawValueWithoutLazyInitialization() sont définies sur leurs valeurs par défaut, le cas échéant. À ce stade, l'objet ressemble à un objet créé avec ReflectionClass::newInstanceWithoutConstructor(), sauf pour les propriétés déjà initialisées.
- La fonction d'initialisation est ensuite appelée avec l'objet comme premier paramètre. La fonction est censée, mais pas obligée, d'initialiser l'état de l'objet, et doit retourner `null` ou aucune valeur. L'objet n'est plus paresseux à ce stade, donc la fonction peut accéder directement à ses propriétés.

Après l'initialisation, l'objet est indiscernable d'un objet qui n'a jamais été paresseux.

#### Objets proxys

- L'objet est marqué comme non-paresseux.
- Contrairement aux objets fantômes, les propriétés de l'objet ne sont pas modifiées à cette étape.
- La fonction fabrique est appelée avec l'objet comme premier paramètre et doit retourner une instance non-paresseuse d'une classe compatible (voir ReflectionClass::newLazyProxy()).
- L'instance retournée est appelée instance réelle et est attachée au proxy.
- Les valeurs des propriétés du proxy sont jetées comme si unset() était appelé.

Après l'initialisation, l'accès à n'importe quelle propriété sur le proxy donnera le même résultat que l'accès à la propriété correspondante sur l'instance réelle ; tous les accès aux propriétés sur le proxy sont transmis à l'instance réelle, y compris les propriétés déclarées, dynamiques, inexistantes, ou les propriétés marquées avec ReflectionProperty::skipLazyInitialization() ou ReflectionProperty::setRawValueWithoutLazyInitialization().

L'objet proxy lui-même n'est pas remplacé ou substitué par l'instance réelle.

Tandis que la fabrique reçoit le proxy comme premier paramètre, il n'est pas attendu qu'elle le modifie (les modifications sont autorisées mais seront perdues lors de l'étape finale d'initialisation). Cependant, le proxy peut être utilisé pour des décisions basées sur les valeurs des propriétés initialisées, la classe, l'objet lui-même, ou son identité. Par exemple, l'initialiseur pourrait utiliser la valeur d'une propriété initialisée lors de la création de l'instance réelle.

#### Comportement commun

La portée et le contexte $this de la fonction d'initialisation ou de la fabrique restent inchangés, et les contraintes de visibilité habituelles s'appliquent.

Après une initialisation réussie, la fonction d'initialisation ou la fabrique n'est plus référencée par l'objet et peut être libérée si elle n'a pas d'autres références.

Si l'initialisation lève une exception, l'état de l'objet est rétabli à son état pré-initialisation et l'objet est à nouveau marqué comme paresseux. En d'autres termes, tous les effets sur l'objet lui-même sont annulés. Les autres effets secondaires, tels que les effets sur d'autres objets, ne sont pas annulés. Cela empêche l'exposition d'une instance partiellement initialisée en cas d'échec.

### Clonage

Cloner un objet paresseux déclenche son initialisation avant que le clone ne soit créé, résultant en un objet initialisé.

Pour les objets proxys, le proxy et son instance réelle sont clonés, et le clone du proxy est retourné. La méthode `__clone` est appelée sur l'instance réelle, pas sur le proxy. Le proxy cloné et l'instance réelle clonée sont liés comme ils le sont pendant l'initialisation, donc les accès au clone du proxy sont transmis au clone de l'instance réelle.

Ce comportement garantit que le clone et l'objet original maintiennent des états séparés. Les modifications apportées à l'objet original ou à l'état de son initialisateur après le clonage n'affectent pas le clone. Cloner à la fois le proxy et son instance réelle, plutôt que de retourner un clone de l'instance réelle seule, garantit que l'opération de clonage retourne systématiquement un objet de la même classe.

### Destructeurs

Pour les objets paresseux, le destructeur n'est appelé que si l'objet a été initialisé. Pour les proxys, le destructeur n'est appelé que sur l'instance réelle, si elle existe.

Les méthodes ReflectionClass::resetAsLazyGhost() et ReflectionClass::resetAsLazyProxy() peuvent invoquer le destructeur de l'objet réinitialisé.

## Modifications en POO (Programmation orientée objet)

Les changements du modèle objet de PHP sont recensés ici. Plus d'informations et autres notes peuvent être trouvées dans la documentation sur la POO en PHP.

Version | Description
--- | ---
8.4.0 | Ajout : Support pour les hooks de propriété.
8.4.0 | Ajout : Support des objets paresseux.
8.1.0 | Ajout : Support pour le modificateur final pour les constantes de classe. De plus, les constantes d'interfaces peuvent être redéfinies par défaut.
8.0.0 | Ajout : Support de l'opérateur nullsafe ?-> pour accéder aux propriétés et méthodes sur des objets qui peuvent être null.
7.4.0 | Changement : Il est désormais possible de lancer des exceptions au sein de __toString().
7.4.0 | Ajout : Support limité pour la covariance du type de retour et contravariance pour le type d'argument. Le support complet de variance est uniquement disponible si l'autochargement est utilisé. À l'intérieur d'un fichier unique seules les références non-cycliques de type sont possibles.
7.4.0 | Ajout : Il est désormais possible de typer les propriétés de classe.
7.3.0 | Incompatibilité : Le déballage d'argument de Traversables avec des clés non-entieres n'est plus supporté. Ce comportement n'était pas prévu et par conséquent supprimé.
7.3.0 | Incompatibilité : Dans les versions précédentes il était possible de séparer les propriétés statiques en assignant une référence. Ceci a été supprimé.
7.3.0 | Changement : L'opérateur instanceof autorise désormais des littéraux comme premier opérande, dans ce cas le résultat est toujours `false`.
7.2.0 | Obsolète : La méthode __autoload() a été rendue obsolète en faveur de spl_autoload_register().
7.2.0 | Changement : Le nom suivant ne peut pas être utilisé pour nommer des classes, interfaces ou traits : `object`.
7.2.0 | Changement : Une virgule finale peut désormais être ajoutée à la syntaxe use groupée pour les espaces de noms.
7.2.0 | Changement : Élargissement du type des paramètres. Les types des paramètres des méthodes réécrites et d'implémentation d'interface peuvent désormais être omis.
7.2.0 | Changement : Les méthodes abstraites peuvent désormais être réécrites quand une classe abstraite étend une autre classe abstraite.
7.1.0 | Changement : Les noms suivants ne peuvent pas être utilisés pour nommer des classes, interfaces ou traits : `void` et `iterable`.
7.1.0 | Ajout : Il est désormais possible de définir la visibilité des constantes de classe.
7.0.0 | Obsolète : Appel statique à des méthodes qui ne sont pas déclarées comme statique.
7.0.0 | Obsolète : Constructeur style PHP 4. C.à.d. les méthodes qui ont le même nom que la classe dans laquelle elles sont définies.
7.0.0 | Ajout : Déclaration use groupée : les classes, fonctions et constantes qui sont importées depuis un même espace de noms peuvent désormais être groupées ensemble en une seule déclaration use.
7.0.0 | Ajout : Support pour les classes anonymes a été ajouté grâce à `new class`.
7.0.0 | Incompatibilité : Itérer sur un objet non- Traversable aura désormais le même comportement qu'itérer sur les tableaux par référence.
7.0.0 | Changement : La définition de propriétés (compatibles) dans deux traits utilisés ne déclenche plus d'erreur.
5.6.0 | Ajout : La méthode __debugInfo().
5.5.0 | Ajout : La constante magique ::class.
5.5.0 | Ajout : finally pour gérer les exceptions.
5.4.0 | Ajout : traits.
5.4.0 | Changement : Si une classe abstraite définit une signature pour le constructeur , celle-ci sera désormais appliquée.
5.3.3 | Changement : Les méthodes ayant le même nom que le dernier élément dans un espace de noms ne sont plus considérées comme un constructeur. Ce changement n'affecte pas les classes sans espace de noms.
5.3.0 | Changement : Les classes qui implémentent une interface avec des méthodes ayant des valeurs par défaut définies dans leurs prototypes ne sont plus obligées de respecter les valeurs par défaut définies dans l'interface.
5.3.0 | Changement : Il est désormais possible de référencer une classe en utilisant une variable (e.g. : `echo $classname::constant;`). La valeur de la variable ne peut être un mot-clé (e.g. : `self`, `parent` ou `static`).
5.3.0 | Changement : Une erreur de niveau `E_WARNING` est émise si les méthodes magiques de surcharge sont déclarées comme statiques. La visibilité publique est aussi requise.
5.3.0 | Changement : avant 5.3.0, les exceptions lancées dans la fonction __autoload() ne pouvaient être traitées dans un bloc catch et résultaient en une erreur fatale. À présent, les exceptions lancées dans la fonction __autoload peuvent être attrapées dans un bloc catch et traitées. Si une exception personnalisée est lancée, alors sa classe doit être disponible. La fonction __autoload peut être utilisée récursivement pour autocharger la classe d'exception personnalisée.
5.3.0 | Ajout : La méthode __callStatic.
5.3.0 | Ajout : heredoc et nowdoc sont supportées pour définir les constantes de classes et les propriétés. Note : les valeurs heredoc doivent suivre les mêmes règles que les chaîne de caractères entourées de guillemets doubles (e.g. pas de variable au sein).
5.3.0 | Ajout : Résolution Statique Tardive.
5.3.0 | Ajout : La méthode __invoke().
5.2.0 | Changement : La méthode __toString() n'était appelée que lors des appels à echo ou print. Désormais, elle est appelée dans n'importe quel contexte de chaîne de caractères (e.g. dans printf() avec le modificateur `%s`) mais pas dans les autres contextes (e.g. avec le modificateur `%d`). À partir de PHP 5.2.0, convertir un objet sans méthode __toString en chaîne de caractères émet une erreur `E_RECOVERABLE_ERROR`.
5.1.3 | Changement : Dans les versions antérieures de PHP 5, l'utilisation de `var` était considérée comme obsolète et émettait une erreur `E_STRICT`. Ce n'est plus le cas.
5.1.0 | Changement : La méthode statique __set_state() est désormais appelée pour les classes exportées via var_export().
5.1.0 | Ajout : Des méthodes __isset() et __unset().

# Les espaces de noms

## Sommaire

- Introduction
- Espaces de noms
- Sous espace de noms
- Définition de plusieurs espaces de noms dans le même fichier
- Introduction
- Espaces de noms et langage dynamique
- Commande namespace et __NAMESPACE__
- Importation et alias
- Global
- Retour sur l'espace global
- Règles de résolution de noms
- Foire aux questions

## Introduction aux espaces de noms

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Que sont les espaces de noms ? Dans leur définition la plus large, ils représentent un moyen d'encapsuler des éléments. Cela peut être conçu comme un concept abstrait, pour plusieurs raisons. Par exemple, dans un système de fichiers, les dossiers représentent un groupe de fichiers associés et servent d'espace de noms pour les fichiers qu'ils contiennent. Un exemple concret est que le fichier `foo.txt` peut exister dans les deux dossiers `/home/greg` et `/home/other`, mais que les deux copies de `foo.txt` ne peuvent pas co-exister dans le même dossier. De plus, pour accéder au fichier `foo.txt` depuis l'extérieur du dossier `/home/greg`, il faut préciser le nom du dossier en utilisant un séparateur de dossier, tel que `/home/greg/foo.txt`. Le même principe s'applique aux espaces de noms dans le monde de la programmation.

Dans le monde PHP, les espaces de noms sont conçus pour résoudre deux problèmes que rencontrent les auteurs de bibliothèques et d'applications lors de la réutilisation d'éléments tels que des classes ou des bibliothèques de fonctions :

1. Collisions de noms entre le code créé, les classes, fonctions ou constantes internes de PHP, ou celles de bibliothèques tierces.
2. La capacité de faire des alias ou de raccourcir des Noms_Extremement_Long pour aider à la résolution du premier problème, et améliorer la lisibilité du code.

Les espaces de noms PHP fournissent un moyen pour regrouper des classes, interfaces, fonctions ou constantes. Voici un exemple de syntaxe des espaces de noms PHP :

Exemple #1 Exemple de syntaxe des espaces de noms

    <?php
    namespace mon\nom; // Voyez la section "Définition des espaces de noms"

    class MaClasse {}
    function mafonction() {}
    const MACONSTANTE = 1;

    $a = new MaClasse;
    print $a::class . "\n";
    $c = new \mon\nom\MaClasse; // Voyez la section "Espace global"
    print $c::class . "\n";

    $a = strlen('bonjour'); // Voyez la section "Utilisation des espaces de noms : retour
                            // aux fonctions/constantes globales"
    print $a . "\n";

    $d = namespace\MACONSTANTE; // Voyez la section "L'opérateur namespace et la constante __NAMESPACE__"
    print $d . "\n";

    $d = __NAMESPACE__ . '\MACONSTANTE';
    echo constant($d); // Voyez "Espaces de noms et fonctionnalités dynamiques"

> Note: Les noms d'espaces de noms ne sont pas sensibles à la casse.

> Note:

> Les espaces de noms `PHP`, mais aussi les noms composés commençant par ces noms (comme `PHP\Classes`) sont réservés pour l'utilisation interne du langage, et ne doivent pas être utilisés dans le code de l'espace utilisateur.

## Définition des espaces de noms

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Bien que du code PHP valide puisse être contenu dans un espace de noms, seuls les types de code suivants peuvent être affectés par les espaces de noms : les classes (incluant les abstraites, les traits et les enums), les interfaces, les fonctions et les constantes.

Les espaces de noms sont déclarés avec le mot-clé `namespace`. Un fichier contenant un espace de noms doit déclarer l'espace au début du fichier, avant tout autre code, avec une seule exception : le mot clé declare.

Exemple #1 Déclaration d'un espace de noms

    <?php
    namespace MonProjet;

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */ }

> Note: Les noms complètement qualifiés (c.-à-d. les noms commençant avec un antislash) ne sont pas autorisés dans les déclarations d'espaces de noms, car de telles constructions sont interprétées comme des expressions d'espace de noms relatif.

Le seul élément autorisé avant la déclaration d'espace de noms est la commande `declare`, pour définir l'encodage du fichier source. De plus, aucun code non-PHP ne peut précéder la déclaration d'espace de noms, y compris des espaces :

Exemple #2 Erreur de déclaration d'un espace de noms

    <html>
    <?php
    namespace MonProjet; // erreur fatale : le namespace doit être le premier élément du script

De plus, contrairement à d'autres structures PHP, le même espace de noms peut être défini dans plusieurs fichiers, ce qui permet de scinder le contenu d'un espace de noms sur plusieurs fichiers.

## Déclaration d'un sous espace de noms

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Comme pour les fichiers et les dossiers, les espaces de noms sont aussi capables de spécifier une hiérarchie d'espaces de noms. Ainsi, un nom d'espace de noms peut être défini avec ses sous-niveaux :

Exemple #1 Déclaration d'un espace de noms avec hiérarchie

    <?php
    namespace MonProjet\Sous\Niveau;

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }

Dans l'exemple ci-dessus, la constante `MonProjet\Sous\Niveau\CONNEXION_OK`, la classe `MonProjet\Sous\Niveau\Connexion` et la fonction `MonProjet\Sous\Niveau\connecte` sont créées.

## Définition de plusieurs espaces de noms dans le même fichier

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Plusieurs espaces de noms peuvent aussi être déclarés dans le même fichier. Il y a deux syntaxes autorisées.

Exemple #1 Déclaration de plusieurs espaces de noms, syntaxe à combinaison simple

    <?php
    namespace MonProjet;

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }

    namespace AutreProjet;

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }

Cette syntaxe n'est pas recommandée pour combiner des espaces de noms dans un seul fichier. Au lieu de cela, il est recommandé d'utiliser la syntaxe à accolades.

Exemple #2 Déclaration de plusieurs espaces de noms, syntaxe à accolades

    <?php
    namespace MonProjet {

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }
    }

    namespace AutreProjet {

    const CONNEXION_OK = 1;
    class Connexion { /* ... */ }
    function connecte() { /* ... */  }
    }

Il est fortement recommandé, en tant que pratique de codage, de ne pas mélanger plusieurs espaces de noms dans le même fichier. L'utilisation recommandée est de combiner plusieurs scripts PHP dans le même fichier.

Pour combiner plusieurs codes sans espaces de noms dans du code avec espace de noms, seule la syntaxe à accolades est supportée. Le code global doit être encadré par un espace de noms sans nom, tel que celui-ci :

Exemple #3 Déclaration de plusieurs espaces de noms avec un espace sans nom

    <?php
    namespace MonProjet {

    const CONNEXION_OK = 1;
    class Connexion {
        public static function start() {
            print __METHOD__ . "\n";
        }
    }

    function connecte() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // code global
    print strlen("bonjour") . "\n";
    MonProjet\connecte();
    MonProjet\Connexion::start();
    }

Aucun code PHP ne peut exister hors des accolades du namespace, sauf pour ouvrir une nouvelle instruction `declare`.

Exemple #4 Déclaration de plusieurs espaces de noms avec un espace sans nom (2)

    <?php
    declare(strict_types=1);
    namespace MonProjet {

    const CONNEXION_OK = 1;
    class Connexion {
        public static function start() {
            print __METHOD__ . "\n";
        }
    }

    function connecte() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // code global
    print strlen("bonjour") . "\n";
    MonProjet\connecte();
    MonProjet\Connexion::start();
    }

## Utilisation des espaces de noms : introduction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Avant de discuter de l'utilisation des espaces de noms, il est important de comprendre comment PHP devine quel espace de noms le code utilise. Une analogie simple peut être faite entre les espaces de noms de PHP et un système de fichiers. Il y a trois moyens d'accéder à un fichier dans un système de fichiers :

1. Un nom relatif de fichier, tel que `foo.txt`. Cela est résolu en `dossiercourant/foo.txt` où `dossiercourant` est le dossier de travail. Si le dossier courant est `/home/foo`, ce nom se résout en `/home/foo/foo.txt`.
2. Un chemin relatif, tel que `sous-dossier/foo.txt`. Cela se résout en `dossiercourant/sous-dossier/foo.txt`.
3. Un chemin absolu, tel que `/main/foo.txt`. Cela se résout en `/main/foo.txt`.

Le même principe peut être appliqué aux espaces de noms de PHP. Par exemple, on peut faire référence à une classe de trois manières :

1. Un nom sans qualificatif, ou une classe sans préfixe, telle que `$a = new foo();` ou `foo::methodestatique();`. Si le namespace courant est `espacedenomscourant`, ceci se résout en `espacedenomscourant\foo`. Si le namespace est global, soit encore le namespace sans nom, cela devient `foo`. Une mise en garde : les noms sans qualificatif pour les fonctions et les constantes vont être pris dans le namespace global, si la fonction n'est pas définie dans le namespace courant. Voir Utilisation des espaces de noms : retour au namespace global pour les fonctions et les constantes pour plus de détails.
2. Un nom qualifié, ou une classe préfixée telle que `$a = new sousespacedenoms\foo();` ou `sousespacedenoms\foo::methodestatique();`. Si le namespace courant est `espacedenomscourant`, cela devient `espacedenomscourant\sousespacedenoms\foo`. Si le code est global, c'est-à-dire le namespace sans nom, cela devient `sousespacedenoms\foo`.
3. Un nom absolu, ou un nom préfixé avec un opérateur global tel que `$a = new \espacedenomscourant\foo();` ou `\espacedenomscourant\foo::methodestatique();`. Cela fait toujours référence au nom littéral spécifié dans le code : `espacedenomscourant\foo`.

Voici un exemple des trois syntaxes, dans du code réel :

file1.php

    <?php
    namespace Foo\Bar\sousespacedenoms;

    const FOO = 1;
    function foo() {}
    class foo
    {
        static function methodestatique() {}
    }

file2.php

    <?php
    namespace Foo\Bar;
    include 'file1.php';

    const FOO = 2;
    function foo() {}
    class foo
    {
        static function methodestatique() {}
    }

    /* nom non qualifié */
    foo(); // Devient Foo\Bar\foo
    foo::methodestatique(); // Devient Foo\Bar\foo, méthode methodestatique
    echo FOO; // Devient la constante Foo\Bar\FOO

    /* nom qualifié */
    sousespacedenoms\foo(); // Devient la fonction Foo\Bar\sousespacedenoms\foo
    sousespacedenoms\foo::methodestatique(); // devient la classe Foo\Bar\sousespacedenoms\foo,
                                      // méthode methodestatique
    echo sousespacedenoms\FOO; // Devient la constante Foo\Bar\sousespacedenoms\FOO

    /* nom absolu */
    \Foo\Bar\foo(); // Devient la fonction Foo\Bar\foo
    \Foo\Bar\foo::methodestatique(); // Devient la classe Foo\Bar\foo, méthode methodestatique
    echo \Foo\Bar\FOO; // Devient la constante Foo\Bar\FOO

Il est à noter que pour accéder à n'importe quelle classe, fonction ou constante globale, un nom absolu peut être utilisé, tel que \strlen() ou \Exception ou \`INI_ALL`.

Exemple #1 Accès aux classes, fonctions et constantes globales depuis un espace de noms

    <?php
    namespace Foo;

    function strlen() {}
    const INI_ALL = 3;
    class Exception {}

    print \strlen('hi') . "\n"; // appelle la fonction globale strlen
    print \INI_ALL . "\n"; // accès à une constante INI_ALL
    $c = new \Exception('error'); // instancie la classe globale Exception
    print $c::class . "\n";

## Espaces de noms et langage dynamique

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

L'implémentation des espaces de noms de PHP est influencée par sa nature dynamique de langage de programmation. Par conséquent, pour convertir du code tel que le code de l'exemple suivant, en un espace de noms :

Exemple #1 Accès dynamique aux éléments

example1.php:

    <?php
    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function funcname()
    {
        echo __FUNCTION__,"\n";
    }
    const constname = "global";

    $a = 'classname';
    $obj = new $a; // affiche classname::__construct
    $b = 'funcname';
    $b(); // affiche funcname
    echo constant('constname'), "\n"; // affiche global

Il faut utiliser un nom absolu (le nom de la classe, avec son préfixe d'espace de noms). Il est à noter qu'il n'y a pas de différence entre un nom absolu et un nom qualifié dans un nom de classe, de fonction ou de constante dynamique, ce qui fait que l'antislash initial n'est pas nécessaire.

Exemple #2 Accès dynamique à des espaces de noms

    <?php
    namespace nomdelespacedenoms;
    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function funcname()
    {
        echo __FUNCTION__,"\n";
    }
    const constname = "namespaced";

    /* Note que si vous utilisez des guillemets doubles, "\\nomdelespacedenoms\\classname" doit être utilisé */
    $a = '\nomdelespacedenoms\classname';
    $obj = new $a; // affiche nomdelespacedenoms\classname::__construct
    $a = 'nomdelespacedenoms\classname';
    $obj = new $a; // affiche aussi nomdelespacedenoms\classname::__construct
    $b = 'nomdelespacedenoms\funcname';
    $b(); // affiche nomdelespacedenoms\funcname
    $b = '\nomdelespacedenoms\funcname';
    $b(); // affiche aussi nomdelespacedenoms\funcname
    echo constant('\nomdelespacedenoms\constname'), "\n"; // affiche namespaced
    echo constant('nomdelespacedenoms\constname'), "\n"; // affiche aussi namespaced

Il est recommandé de lire la note au sujet de la protection des espaces de noms dans les chaînes.

## La commande namespace et la constante __NAMESPACE__

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP supporte deux moyens pour accéder de manière abstraite aux éléments dans l'espace de noms courant, à savoir la constante magique `__NAMESPACE__` et la commande `namespace`.

La valeur de `__NAMESPACE__` est une chaîne qui contient le nom du namespace courant. Dans l'espace global, sans nom, elle contient une chaîne vide.

Exemple #1 Exemple avec __NAMESPACE__, dans un code avec espace de noms

    <?php
    namespace MonProjet;

    echo '"', __NAMESPACE__, '"'; // affiche "MonProjet"

Exemple #2 Exemple avec __NAMESPACE__, dans un code avec espace de noms global

    <?php
    echo '"', __NAMESPACE__, '"'; // affiche ""

La constante `__NAMESPACE__` est utile pour construire dynamiquement des noms, tels que :

Exemple #3 Utilisation de __NAMESPACE__ pour une construction dynamique de noms

    <?php
    namespace MonProjet;

    function get($classname)
    {
        $a = __NAMESPACE__ . '\\' . $classname;
        return new $a;
    }

La commande `namespace` peut aussi être utilisée pour demander explicitement un élément du namespace courant, ou d'un sous-espace. C'est l'équivalent pour les espaces de noms de l'opérateur `self` des classes.

Exemple #4 l'opérateur namespace, dans un espace de noms

    <?php
    namespace MonProjet;

    use blah\blah as mine; // Voyez "Utilisation des espaces de noms : alias et importation"

    blah\mine(); // appelle la fonction MonProjet\blah\mine()
    namespace\blah\mine(); // appelle la fonction MonProjet\blah\mine()

    namespace\func(); // appelle la fonction MonProjet\func()
    namespace\sub\func(); // appelle la fonction MonProjet\sub\func()
    namespace\cname::method(); // appelle la méthode statique "method" de la classe MonProjet\cname
    $a = new namespace\sub\cname(); // instancie un objet de la classe MonProjet\sub\cname
    $b = namespace\CONSTANT; // assigne la valeur de la constante MonProjet\CONSTANT à $b

Exemple #5 l'opérateur namespace, dans le namespace global

    <?php

    namespace\func(); // appelle la fonction func()
    namespace\sub\func(); // appelle la fonction sub\func()
    namespace\cname::method(); // appelle la méthode statique "method" de la classe cname
    $a = new namespace\sub\cname(); // instancie un objet de la classe sub\cname
    $b = namespace\CONSTANT; // assigne la valeur de la constante CONSTANT à $b

## Utilisation des espaces de noms : importation et alias

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

La capacité de faire référence à un nom absolu avec un alias ou en important un espace de noms est stratégique. C'est un avantage similaire aux liens symboliques dans un système de fichiers.

PHP peut aliaser(/importer) les constantes, fonctions, classes, interfaces, traits, énumérations et les espaces de noms.

Un alias est créé avec l'opérateur `use`. Voici un exemple qui présente les cinq types d'importation :

Exemple #1 importation et alias avec l'opérateur use

    <?php
    namespace foo;
    use My\Full\Classname as Another;

    // Ceci est la même chose que use My\Full\NSname as NSname
    use My\Full\NSname;

    // importation d'une classe globale
    use ArrayObject;

    // importation d'une fonction
    use function My\Full\functionName;

    // alias d'une fonction
    use function My\Full\functionName as func;

    // importation d'une constante
    use const My\Full\CONSTANT;

    $obj = new namespace\Another; // instancie un objet de la classe foo\Another
    $obj = new Another; // instancie un objet de la classe My\Full\Classname
    NSname\subns\func(); // appelle la fonction My\Full\NSname\subns\func
    $a = new ArrayObject(array(1)); // instancie un objet de la classe ArrayObject
    // Sans l'instruction "use ArrayObject" nous aurions instancié un objet de la classe foo\ArrayObject
    func(); // Appelle la fonction My\Full\functionName
    echo CONSTANT; // affiche la valeur de My\Full\CONSTANT

Il est à noter que pour les noms avec chemin (les noms absolus contenant des séparateurs d'espaces, tels que `Foo\Bar`, par comparaison avec les noms globaux, tels que `FooBar`, qui n'en contiennent pas), l'antislash initial n'est pas nécessaire et n'est pas recommandé, car les noms importés doivent être absolus et ne sont pas résolus relativement au namespace courant.

De plus, PHP supporte des raccourcis pratiques, tels que les commandes use multiples.

Exemple #2 importation et alias multiples avec l'opérateur use

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // instancie un objet de la classe My\Full\Classname
    NSname\subns\func(); // appelle la fonction My\Full\NSname\subns\func

L'importation est réalisée à la compilation, ce qui fait que cela n'affecte pas les classes, fonctions et constantes dynamiques.

Exemple #3 Importation et noms d'espaces dynamiques

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // instancie un objet de la classe My\Full\Classname
    $a = 'Another';
    $obj = new $a;      // instancie un objet de la classe Another

De plus, l'importation n'affecte que les noms sans qualification. Les noms absolus restent absolus, et inchangés par un import.

Exemple #4 Importation et noms d'espaces absolus

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // instancie un objet de la classe My\Full\Classname
    $obj = new \Another; // instancie un objet de la classe Another
    $obj = new Another\untruc; // instancie un objet de la classe My\Full\Classname\untruc
    $obj = new \Another\untruc; // instancie un objet de la classe Another\untruc

### Règles de contextes pour l'importation

Le mot-clé `use` doit être déclaré dans le contexte le plus externe d'un fichier (le contexte global) ou alors dans les déclarations d'espace de noms. Ceci car l'importation est effectuée à la compilation et non durant l'exécution, donc on ne peut empiler les contextes. L'exemple qui suit montre des utilisations incorrectes du mot-clé `use`:

Exemple #5 Règles d'importation incorrectes

    <?php
    namespace Languages;

    function toGreenlandic()
    {
        use Languages\Danish;

        // ...
    }

> Note:

> Les règles d'importation sont basées sur les fichiers, ce qui signifie que les fichiers inclus n'hériteront PAS des règles d'importation du fichier parent.

### Déclaration du groupe `use`

Les classes, fonctions et constantes importées depuis le même `namespace` peuvent être regroupées dans une seule instruction `use`.

    <?php

    use some\namespace\ClassA;
    use some\namespace\ClassB;
    use some\namespace\ClassC as C;

    use function some\namespace\fn_a;
    use function some\namespace\fn_b;
    use function some\namespace\fn_c;

    use const some\namespace\ConstA;
    use const some\namespace\ConstB;
    use const some\namespace\ConstC;

    // est équivalent à la déclaration use groupée suivante
    use some\namespace\{ClassA, ClassB, ClassC as C};
    use function some\namespace\{fn_a, fn_b, fn_c};
    use const some\namespace\{ConstA, ConstB, ConstC};

## Espace de noms global

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Sans aucune définition d'espace de noms, toutes les classes et les fonctions sont placées dans le namespace global : comme en PHP avant que les espaces de noms aient été introduits. En préfixant un nom avec un antislash `\`, on peut demander l'utilisation du namespace global, même dans un contexte d'espace de noms spécifique.

Exemple #1 Spécification d'espace de noms global

    <?php
    namespace A\B\C;

    /* Cette fonction est A\B\C\fopen */
    function fopen() {
         /* ... */
         $f = \fopen(...); // appel à fopen global
         return $f;
    }

## Utilisation des espaces de noms : retour sur l'espace global pour les fonctions et les constantes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Dans un espace de noms, lorsque PHP rencontre un nom sans qualification, que ce soit une classe, une fonction ou une constante, il le résout avec différentes priorités. Les noms de classes sont toujours résolus avec le namespace courant. Pour accéder à des classes internes ou à des classes qui ne sont pas dans un espace de noms, il faut les représenter avec leur nom absolu, tel que :

Exemple #1 Accès aux classes globales depuis un espace de noms

    <?php
    namespace A\B\C;
    class Exception extends \Exception {}

    $a = new Exception('hi'); // $a est un objet de la classe A\B\C\Exception
    var_dump($a::class);
    $b = new \Exception('hi'); // $b est un objet de la classe Exception
    var_dump($b::class);

    $c = new ArrayObject; // erreur fatale, classe A\B\C\ArrayObject non trouvée

Pour les fonctions et constantes, PHP va aller les chercher dans l'espace global s'il ne peut les trouver dans le namespace courant.

Exemple #2 Accès aux fonctions et constantes globales dans un espace de noms

    <?php
    namespace A\B\C;

    const E_ERROR = 45;
    function strlen($str)
    {
        return \strlen($str) - 1;
    }

    echo E_ERROR, "\n"; // affiche "45"
    echo INI_ALL, "\n"; // affiche "7" : accès dans le namespace global INI_ALL

    echo strlen('hi'), "\n"; // affiche "1"
    if (is_array('hi')) { // affiche "n'est pas un tableau"
        echo "est un tableau\n";
    } else {
        echo "n'est pas un tableau\n";
    }

## Règles de résolution de noms

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Dans le cadre des règles de résolution, il y a plusieurs définitions importantes :

Définitions pour les espaces de noms
nom non qualifié

  Ceci est un identifiant ne contenant pas un séparateur d'espace de noms. Par exemple : `Foo`

nom qualifié

  Ceci est un identifiant contenant un séparateur d'espace de noms. Par exemple : `Foo\Bar`

Nom absolu

  Ceci est un identifiant qui commence par un séparateur d'espace de noms. Par exemple : `\Foo\Bar`. le namespace `Foo` est aussi un nom absolu.

Nom Relatif

  C'est un identifiant commençant par `namespace`, tel que `namespace\Foo\Bar`.

Les noms sont résolus en suivant les règles suivantes :

1. Les noms absolus sont toujours résolus en le nom sans le séparateur de namespace initial. Par exemple, `\A\B` est résolu en `A\B`.
2. Les noms relatifs sont toujours résolus en remplaçant `namespace` par le namespace courant. Si le nom apparaît dans le namespace global, le préfixe `namespace\` est retiré. Par exemple, `namespace\A` dans le namespace `X\Y` est résolu en `X\Y\A`. Le même nom dans le namespace global est résolu en `A`.
3. Pour les noms qualifiés, le premier segment est traduit en accord avec la table d'importation des class/namespace. Par exemple, si le namespace `A\B\C` est importé comme `C`, le nom `C\D\E` est traduit par `A\B\C\D\E`.
4. Pour les noms qualifiés, si aucune règle d'import ne s'applique, le namespace courant est préfixé au nom. Par exemple le nom `C\D\E` dans le namespace `A\B`, est traduit par `A\B\C\D\E`.
5. Pour les noms non qualifiés, le nom est traduit en lien avec la table courante d'importation pour le type de symbole respectif. Cela signifie qu'un nom ressemblant à une classe est traduit en accord avec la table d'importation des class/namespace, les noms de fonctions en utilisant la table d'importation des fonctions, et les constantes en utilisant la table d'importation des constantes. Par exemple, après `use A\B\C;` un usage tel que `new C()` correspond au nom `A\B\C()`. De la même manière, après `use function A\B\foo;` un usage tel que `foo()` correspond au nom `A\B\foo`.
6. Pour les noms non qualifiés, si aucune règle ne s'applique, et que le nom fait référence à une classe, le namespace courant sert de préfixe. Par exemple `new C()` dans le namespace `A\B` correspond au nom `A\B\C`.
7. Pour les noms non qualifiés, si aucune règle ne s'applique, et que le nom fait référence à une fonction ou une constante, et que le code est en dehors du namespace global, le nom est résolu à l'exécution. Supposons que le code est dans le namespace `A\B`, voici comment un appel à la fonction `foo()` est résolu :
   1. Il recherche une fonction dans le namespace courant : `A\B\foo()`.
   2. Il essaie de trouver et appeler la fonction globale `foo()`.

Exemple #1 Exemples de résolutions d'espaces de noms

    <?php
    namespace A;
    use B\D, C\E as F;

    // appels de fonctions

    foo();      // tente d'appeler la fonction "foo" dans le namespace "A"
                // puis appelle la fonction globale "foo"

    \foo();     // appelle la fonction "foo" définie dans le namespace global

    my\foo();   // appelle la fonction "foo" définie dans le namespace "A\my"

    F();        // tente d'appeler la fonction "F" définie dans l'espace "A"
                // puis tente d'appeler la fonction globale "F"

    // références de classes

    new B();    // crée un objet de la classe "B" définie dans le namespace  "A"
                // si non trouvé, il essaie l'autochargement sur la classe "A\B"

    new D();    // crée un objet de la classe "D" définie dans le namespace  "B"
                // si non trouvé, il essaie l'autochargement sur la classe "B\D"

    new F();    // crée un objet de la classe "E" définie dans le namespace  "C"
                // si non trouvé, il essaie l'autochargement sur la classe "C\E"

    new \B();   // crée un objet de la classe "B" définie dans le namespace global
                // si non trouvé, il essaie l'autochargement sur la classe "B"

    new \D();   // crée un objet de la classe "D" définie dans le namespace global
                // si non trouvé, il essaie l'autochargement sur la classe "D"

    new \F();   // crée un objet de la classe "F" définie dans le namespace global
                // si non trouvé, il essaie l'autochargement sur la classe "F"

    // méthodes statiques et fonctions d'espace de noms d'un autre espace

    B\foo();    // appelle la fonction "foo" du namespace "A\B"

    B::foo();   // appelle la méthode "foo" de la classe "B" définie dans le namespace  "A"
                // si la classe "A\B" n'est pas trouvée, il essaie l'autochargement sur la classe "A\B"

    D::foo();   // appelle la méthode "foo" de la classe "D" définie dans l'espace de noms  "B"
                // si la classe "B\D" n'est pas trouvée, il essaie l'autochargement sur la classe "B\D"

    \B\foo();   // appelle la fonction "foo" de l'espace de noms "B"

    \B::foo();  // appelle la méthode "foo" de la classe "B" située dans l'espace de noms global
                // si la classe "B" n'est pas trouvée, il essaie l'autochargement sur la classe "B"

    // méthodes statiques et fonctions d'espace de noms de l'espace courant

    A\B::foo();   // appelle la méthode "foo" de la classe "B" de l'espace de noms "A\A"
                  // si la classe "A\A\B" n'est pas trouvée, il essaie l'autochargement sur la classe "A\A\B"

    \A\B::foo();  // appelle la méthode "foo" de la classe "B" de l'espace de noms "A"
                  // si la classe "A\B" n'est pas trouvée, il essaie l'autochargement sur la classe "A\B"

## Foire aux questions : ce qu'il faut savoir des espaces de noms

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Cette FAQ est décomposée en deux sections : les questions courantes, et les points particuliers de l'implémentation, qui peuvent être utiles à la compréhension globale.

D'abord, les questions courantes.

1. Si je n'utilise pas d'espaces de noms, est-ce que je dois m'en soucier ?
2. Comment utiliser une classe globale ou interne depuis un espace de noms ?
3. Comment utiliser les classes d'espaces de noms, les fonctions ou les constantes dans leur propre espace ?
4. Comment est-ce qu'un nom comme `\mon\nom` ou `\nom` est résolu ?
5. Comment est-ce qu'un nom tel que `mon\nom` est résolu ?
6. Comment un nom de classe sans qualification, tel que `nom`, est résolu ?
7. Comment une fonction sans qualification ou une constante de nom `nom` est résolue ?

Voici les points particuliers de l'implémentation, qui peuvent être utiles à la compréhension globale.

1. Les noms importés ne doivent pas entrer en conflit avec les classes définies dans le même fichier
2. Les espaces de noms imbriqués sont interdits
3. Les noms d'espaces de noms dynamiques doivent protéger l'antislash
4. Des constantes indéfinies référencées avec un antislash produisent une erreur fatale
5. Impossible de remplacer des constantes spéciales comme `null`, `true` ou `false`

### Si je n'utilise pas d'espaces de noms, est-ce que je dois m'en soucier ?

Non, les espaces de noms n'affectent pas le code existant, d'une manière ou d'une autre, ni le code qui sera produit et qui n'utilise pas les espaces de noms. Il est possible d'écrire ceci :

Exemple #1 Accès à une classe globale de l'extérieur d'un espace de noms

    <?php
    $a = new \stdClass;
    print $a::class;

C'est une fonctionnalité équivalente à :

Exemple #2 Accéder à des classes globales hors d'un espace de noms

    <?php
    $a = new stdClass;
    print $a::class;

### Comment utiliser une classe globale ou interne depuis un espace de noms ?

Exemple #3 Accès aux classes internes depuis un espace de noms

    <?php
    namespace foo;
    $a = new \stdClass;
    print $a::class . "\n";

    function test(?\ArrayObject $parameter_type_example = null) {}

    $a = \FilesystemIterator::CURRENT_AS_FILEINFO;
    print $a . "\n";

    // extension d'une classe interne ou globale
    class MyException extends \Exception {}
    print MyException::class . "\n";

### Comment utiliser les classes d'espaces de noms, les fonctions ou les constantes dans leur propre espace ?

Exemple #4 Accès aux classes, fonctions et constantes internes dans un espace de noms

    <?php
    namespace foo;

    class MaClasse {}

    // utilisation d'une classe dans l'espace de noms courant, sous forme de type de paramètre
    function test(?MaClasse $parameter_type_example = null) {}

    // une autre manière d'utiliser une classe dans l'espace de noms courant comme type de paramètre
    function test2(?\foo\MaClasse $parameter_type_example = null) {}

    // extension d'une classe dans l'espace de noms courant
    class Extended extends MaClasse {}
    print Extended::class . "\n";

    // accès à une fonction globale
    $a = \strlen("test");
    print $a . "\n";

    // accès à une constante globale
    $b = \INI_ALL;
    print $b . "\n";

### Comment est-ce qu'un nom comme `\mon\nom` ou `\nom` est résolu ?

Les noms qui commencent par `\` sont toujours résolus en ce à quoi ils ressemblent, ce qui fait que `\mon\nom` est en fait `mon\nom`, et `\Exception` est `Exception`.

Exemple #5 Noms d'espaces absolus

    <?php
    namespace foo;
    $a = new \mon\nom(); // instancie la classe "mon\nom"
    echo \strlen('hi'); // appelle la fonction "strlen"
    $a = \INI_ALL; // $a reçoit la valeur de la constante "INI_ALL"

### Comment est-ce qu'un nom tel que `mon\nom` est résolu ?

Les noms qui contiennent un antislash mais ne commencent pas par un antislash, comme `mon\nom` peuvent être résolus de deux manières différentes.

S'il y a eu une commande d'importation qui fait un alias de `mon`, alors l'alias importé est appliqué à la place de `mon`, et l'espace de noms devient `mon\nom`.

Sinon, l'espace de noms courant est ajouté avant le chemin de la classe `mon\nom`.

Exemple #6 Noms qualifiés

    <?php
    namespace foo;
    use blah\blah as foo;

    $a = new mon\nom(); // instancie la classe "foo\mon\nom"
    foo\bar::name(); // appelle la méthode statique "name" dans la classe "blah\blah\bar"
    mon\bar(); // appelle la fonction "foo\mon\bar"
    $a = mon\BAR; // affecte à $a la valeur de la constante "foo\mon\BAR"

### Comment un nom de classe sans qualification, tel que `nom`, est résolu ?

Les noms de classes qui ne contiennent pas d'antislash comme `nom` peuvent être résolus de deux manières différentes.

S'il y a une instruction d'importation qui définit un alias pour `nom`, alors l'alias est appliqué.

Sinon, l'espace de noms courant est utilisé et préfixé à `nom`.

Exemple #7 Classes sans qualification

    <?php
    namespace foo;
    use blah\blah as foo;

    $a = new nom(); // instancie la classe "foo\nom"
    foo::nom(); // appelle la méthode statique "nom" dans la classe "blah\blah"

### Comment une fonction sans qualification ou une constante de nom `nom` est résolue ?

Les fonctions et constantes qui n'ont pas d'antislash dans leur nom comme `nom` sont résolues de deux manières différentes :

D'abord, l'espace de noms courant est préfixé à `nom`.

Ensuite, si la constante ou la fonction `nom` n'existe pas dans l'espace de noms courant, la version globale de la constante ou la fonction `nom` est utilisée.

Exemple #8 Fonctions et constantes sans espace de noms

    <?php
    namespace foo;
    use blah\blah as foo;

    const FOO = 1;

    function mon() {
        print __FUNCTION__ . "\n";
    }
    function foo() {
        print __FUNCTION__ . "\n";
    }
    function sort(&$a)
    {
        \sort($a); // Appel de la fonction globale "sort"
        $a = array_flip($a);
        return $a;
    }

    mon(); // appelle "foo\mon"
    print strlen('hi') . "\n"; // appelle la fonction globale "strlen" car "foo\strlen" n'existe pas
    $arr = array(1,3,2);
    $b = sort($arr); // appelle la fonction "foo\sort"
    var_dump($b);
    foo(); // appelle la fonction "foo\foo" : l'importation n'est pas appliquée

    $a = FOO; // assigne à $a la valeur de la constante "foo\FOO" : l'importation n'est pas appliquée
    print $a;
    $b = INI_ALL; // assigne à $b la valeur de la constante "INI_ALL"
    print $b;

### Les noms importés ne doivent pas entrer en conflit avec les classes définies dans le même fichier

La combinaison de scripts suivante est valide :

file1.php

    <?php
    namespace mes\trucs;
    class MaClasse {}

another.php

    <?php
    namespace another;
    class untruc {}

file2.php

    <?php
    namespace mes\trucs;
    include 'file1.php';
    include 'another.php';

    use another\untruc as MaClasse;
    $a = new MaClasse; // instancie la classe "untruc" de l'espace de noms another

Il n'y a pas de conflit de noms, même si la classe `MaClasse` existe dans l'espace de noms `mes\trucs`, car la définition de `MaClasse` est dans un fichier séparé. Cependant, l'exemple suivant produit une erreur fatale à cause d'un conflit de noms, car `MaClasse` est définie dans le même fichier que l'instruction `use`.

    <?php
    namespace mes\trucs;
    use another\untruc as MaClasse;
    class MaClasse {} // erreur fatale: MaClasse est en conflit avec la commande d'importation
    $a = new MaClasse;

### Les espaces de noms imbriqués sont interdits

PHP ne permet pas d'imbriquer des espaces de noms.

    <?php
    namespace mes\trucs {
        namespace nested {
            class foo {}
        }
    }

Cependant, il est facile de simuler des espaces de noms imbriqués, comme ceci :

    <?php
    namespace mes\trucs\nested {
        class foo {}
    }

### Les noms d'espaces de noms dynamiques doivent protéger l'antislash

Il est très important de réaliser que, comme les antislash sont utilisés comme caractères de protection dans les chaînes, il faut toujours les doubler pour pouvoir les utiliser dans une chaîne. Sinon, il y a un risque d'utilisation inattendue :

Exemple #9 Dangers de l'utilisation des espaces de noms dans une chaîne

    <?php
    $a = "dangereux\nom"; // \n est une nouvelle ligne dans une chaîne!
    $obj = new $a;

    $a = 'pas\vraiment\dangereux'; // aucun problème ici
    $obj = new $a;

Dans une chaîne à guillemets simples, la séquence de protection est beaucoup plus sûre à utiliser, mais il est quand même recommandé de toujours protéger les antislashs dans toutes les chaînes comme bonne pratique.

### Des constantes indéfinies référencées avec un antislash produisent une erreur fatale

Toute constante indéfinie qui est sans qualificatif telle que `FOO` va produire une alerte : PHP supposait que `FOO` était la valeur de la constante. Toute constante, qualifiée partiellement ou totalement, qui contient un antislash, produit une erreur fatale si indéfinie.

Exemple #10 Constantes indéfinies

    <?php
    namespace bar;
    $a = FOO; // produit une alerte : constante indéfinie "FOO", qui prend la valeur de "FOO";
    $a = \FOO; // erreur fatale, constante d'espace de noms indéfinie FOO
    $a = Bar\FOO; // erreur fatale, constante d'espace de noms indéfinie bar\Bar\FOO
    $a = \Bar\FOO; // erreur fatale, constante d'espace de noms indéfinie Bar\FOO

### Impossible de remplacer des constantes spéciales comme `null`, `true` ou `false`

Toute tentative dans un espace de noms de remplacer les constantes natives ou spéciales, engendre une erreur fatale.

Exemple #11 Constantes qui ne peuvent être redéfinies

    <?php
    namespace bar;
    const NULL = 0; // erreur fatale;
    const true = 'stupid'; // encore une erreur fatale;
    // etc.

# Les énumérations

## Sommaire

- Aperçu des énumérations
- Énumérations de base
- Énumérations avec valeur de base
- Méthodes d'énumération
- Méthodes statiques d'Enumération
- Constantes d'énumération
- Traits
- Valeurs d'énumération dans les expressions constantes
- Différences avec les objets
- Liste de valeurs
- Sérialisation
- Pourquoi les enums ne sont pas extensibles
- Exemples

## Aperçu des énumérations

(PHP 8 >= 8.1.0)

Les énumérations, ou "Enums", permettent à un développeur de définir un type personnalisé qui est limité à l'une des valeurs parmi un nombre discret de valeurs possibles. Cela peut s'avérer particulièrement utile lors de la définition d'un modèle de domaine, car cela permet de "rendre les états non valides irreprésentables".

Les Enums apparaissent dans de nombreux langages avec une variété de caractéristiques différentes. En PHP, les Enums sont un type d'objet particulier. L'Enum lui-même est une classe, et ses cas possibles sont tous des instances distinctes et uniques de cette classe. Cela signifie que les cas d'Enum sont des objets valides et peuvent être utilisés partout où un objet peut être utilisé, y compris pour les vérifications de type.

L'exemple le plus courant d'énumérations est le type booléen intégré, qui est un type énuméré avec les valeurs légales `true` et `false`. Les énumérations permettent aux développeurs de définir leurs propres énumérations arbitrairement robustes.

## Énumérations de base

Les énumérations sont similaires aux classes et partagent les mêmes espaces de noms que les classes, les interfaces et les traits. Elles sont également autochargeables de la même manière. Une énumération définit un nouveau type, qui possède un nombre fixe et limité de valeurs légales possibles.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

Cette déclaration crée un nouveau type énuméré nommé `Suit`, qui a quatre et seulement quatre valeurs légales : `Suit::Hearts`, `Suit::Diamonds`, `Suit::Clubs`, et `Suit::Spades`. Les variables peuvent être assignées à l'une de ces valeurs légales. Une fonction peut faire l'objet d'une vérification de type par rapport à un type énuméré, auquel cas seules les valeurs de ce type peuvent être transmises.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function pick_a_card(Suit $suit)
    {
        var_dump($suit);
    }

    $val = Suit::Diamonds;

    // OK
    pick_a_card($val);

    // OK
    pick_a_card(Suit::Clubs);

    // TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
    pick_a_card('Spades');

Une énumération peut avoir zéro ou plusieurs définitions de `case`, sans maximum. Une énumération à zéro cas est syntaxiquement valide, mais plutôt inutile.

Pour les cas d'énumération, les mêmes règles syntaxiques s'appliquent que pour n'importe quel label en PHP, voir les Constantes.

Par défaut, les cas ne sont pas intrinsèquement soutenus par une valeur scalaire. C'est-à-dire que `Suit::Hearts` n'est pas égal à `"0"`. Au lieu de cela, chaque cas est soutenu par un objet singleton de ce nom. Cela signifie que :

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    $a = Suit::Spades;
    $b = Suit::Spades;

    if ($a === $b) {
        print "Les couleurs correspondent en utilisant ===\n";
    }

    if ($a instanceof Suit) {
        print "Les couleurs correspondent en utilisant instanceof\n";
    }

    if ($a !== 'Spades') {
        print "La couleur ne correspond pas à la chaîne\n";
    }

Cela signifie également que les valeurs de l'énumération ne sont jamais `<` ou `>` l'une à l'autre, puisque ces comparaisons ne sont pas significatives pour les objets. Ces comparaisons renvoient toujours `false` lorsqu'on travaille avec des valeurs d'énumération.

Ce type de cas, sans données connexes, est appelé "cas pur" ou "Pure Case". Une enum qui ne contient que des cas purs est appelée une Enum pure ou "Pure Enum".

Tous les cas purs sont implémentés en tant qu'instances de leur type d'énumération. Le type d'énumération est représenté en interne comme une classe.

Tous les cas ont une propriété en lecture seule, `name`, qui est le nom sensible à la casse du cas lui-même.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    print Suit::Spades->name;
    // Affiche "Spades"

Il est également possible d'utiliser les fonctions defined() et constant() pour vérifier l'existence ou lire un cas d'énumération si le nom est obtenu dynamiquement. Cette méthode est toutefois déconseillée, car l'utilisation d'une Enum avec valeur de base devrait fonctionner pour la plupart des cas d'utilisation.

## Énumérations avec valeur de base

Par défaut, les cas énumérés n'ont pas d'équivalent scalaire. Il s'agit simplement d'objets singleton. Cependant, il existe de nombreux cas où un cas énuméré doit être capable de faire des allers-retours vers une base de données ou système de stockage de données similaire. Il est donc utile d'avoir un équivalent scalaire intégré (et donc trivialement sérialisable) défini intrinsèquement.

Pour définir un équivalent scalaire pour une énumération, la syntaxe est la suivante :

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

Un cas qui a un équivalent scalaire est appelé un cas avec valeur de base ou "Backed Case", car il est "associé" à une valeur plus simple. Une énumération qui contient uniquement des cas avec valeur de base est appelée "énumération avec valeur de base" ou "Backed Enum". Une Enum avec valeur de base ne peut contenir que des cas avec valeur de base. Une Enum pure ne peut contenir que des cas purs.

Une Enum avec valeur de base peut être avec des valeurs de types `int` ou `string`, et une énumération donnée ne supporte qu'un seul type à la fois (c'est-à-dire pas d'union de `int|string`). Si une énumération est marquée comme ayant un équivalent scalaire, tous les cas doivent avoir un équivalent scalaire unique défini explicitement. Il n'y a pas d'équivalents scalaires auto-générés (par exemple, des entiers séquentiels). Les cas avec valeur de base doivent être uniques ; deux cas enum avec valeur de base ne peuvent pas avoir le même équivalent scalaire. Cependant, une constante peut faire référence à un cas, créant ainsi un alias. Voir Constantes d'énumération.

Les valeurs équivalentes peuvent être une expression scalaire constante. Avant PHP 8.2.0, les valeurs équivalentes devaient être des littéraux ou des expressions littérales. Cela signifie que les constantes et les expressions constantes n'étaient pas supportées. Autrement dit, `1 + 1` était autorisé, mais `1 + SOME_CONST` ne l'était pas.

Les cas avec valeur de base ont une propriété supplémentaire en lecture seule, `value`, qui est la valeur spécifiée dans la définition.

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    print Suit::Clubs->value;
    // Affiche "C"

Afin de garantir que la propriété `value` reste en lecture seule, une variable ne peut pas être assignée en tant que référence à cette propriété. En d'autres termes, l'opération suivante entraîne une erreur :

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $suit = Suit::Clubs;
    $ref = &$suit->value;
    // Fatal Error: Cannot indirectly modify readonly property Suit::$value

Les enums avec valeur de base implémentent une interface interne BackedEnum, qui expose deux méthodes supplémentaires :

- `from(int|string): self` prend un scalaire et renvoie le cas d'Enum correspondant. S'il n'en trouve pas, il lèvera une ValueError. Ceci est principalement utile dans les cas où le scalaire en entrée est fiable et où une valeur d'enum manquante devrait être considérée comme une erreur qui arrête l'application.
- `tryFrom(int|string): ?self` prend un scalaire et renvoie le cas d'Enum correspondant. S'il n'en trouve pas, il retournera `null`. Ceci est principalement utile dans les cas où le scalaire en entrée n'est pas fiable et que l'appelant souhaite implémenter sa propre gestion d'erreur ou sa logique de valeur par défaut.

Les méthodes `from()` et `tryFrom()` suivent les règles standard de typage faible/fort. En mode de typage faible, il est possible de passer un entier ou une chaîne de caractères et le système forcera la valeur en conséquence. Le passage d'un flottant fonctionnera également et sera coercitif. En mode de typage strict, passer un entier à `from()` sur une enum avec valeur de base de type chaîne de caractères (ou vice versa) entraînera une TypeError, tout comme un float dans toutes les circonstances. Tous les autres types de paramètres provoqueront une TypeError dans les deux modes.

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    function get_stuff_from_database($id) {
        return [
            'suit' => 'S',
        ];
    }

    $record = get_stuff_from_database(42);
    print $record['suit'] . "\n";

    $suit = Suit::tryFrom('A') ?? Suit::Spades;
    // Les données invalides retournent null, donc Suit::Spades est utilisé à la place.
    print $suit->value . "\n";

    $suit =  Suit::from('X');
    // Les données invalides lèvent une ValueError : "X" is not a valid backing scalar value for enum Suit
    print $suit->value . "\n";

La définition manuelle d'une méthode `from()` ou `tryFrom()` sur une énumération avec valeur de base entraîne une erreur fatale.

## Méthodes d'énumération

Les Enums (à la fois les Enums pures et les Enums avec valeur de base) peuvent contenir des méthodes et implémenter des interfaces. Si une Enum implémente une interface, alors toute vérification de type pour cette interface acceptera également tous les cas de cette Enum.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit implements Colorful
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;

        // Satisfait le contrat de l'interface.
        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }

        // Ne fait pas partie d'une interface ; pas de problème.
        public function shape(): string
        {
            return "Rectangle";
        }
    }

    function paint(Colorful $c)
    {
       print $c->color() . "\n";
    }

    paint(Suit::Clubs);  // Fonctionne

    print Suit::Diamonds->shape(); // Affiche "Rectangle"

Dans cet exemple, les quatre instances de `Suit` ont deux méthodes, `color()` et `shape()`. En ce qui concerne le code d'appel et les vérifications de type, elles se comportent exactement comme n'importe quelle autre instance d'objet.

Dans le cas d'une Enum avec valeur de base, la déclaration de l'interface suit la déclaration du type de soutien.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit: string implements Colorful
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';

        // Satisfait le contrat de l'interface.
        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }
    }

À l'intérieur d'une méthode, la variable `$this` est définie et fait référence à l'instance du cas.

Les méthodes peuvent être arbitrairement complexes, mais en pratique, elles renvoient généralement une valeur statique ou match sur `$this` pour des résultats différents selon les cas.

Il est à noter que dans ce cas, il serait plus judicieux de définir également un type Enum `SuitColor` avec les valeurs Red et Black et de le renvoyer à la place. Cependant, cela compliquerait cet exemple.

La hiérarchie ci-dessus est logiquement similaire à la structure de classe suivante (bien que ce ne soit pas le code qui s'exécute) :

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    final class Suit implements UnitEnum, Colorful
    {
        public const Hearts = new self('Hearts');
        public const Diamonds = new self('Diamonds');
        public const Clubs = new self('Clubs');
        public const Spades = new self('Spades');

        private function __construct(public readonly string $name) {}

        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }

        public function shape(): string
        {
            return "Rectangle";
        }

        public static function cases(): array
        {
            // Méthode illégale, car la définition manuelle d'une méthode cases() sur une énumération n'est pas autorisée.
            // Voir aussi la section "Liste de valeurs".
        }
    }

Les méthodes peuvent être publiques, privées ou protégées, bien qu'en pratique, privées et protégées sont équivalentes car l'héritage n'est pas autorisé.

## Méthodes statiques d'Enumération

Les énumérations peuvent également avoir des méthodes statiques. L'utilisation de méthodes statiques sur une énumération elle-même est principalement pour les constructeurs alternatifs. Par exemple :

    <?php

    enum Size
    {
        case Small;
        case Medium;
        case Large;

        public static function fromLength(int $cm): self
        {
            return match (true) {
                $cm < 50 => self::Small,
                $cm < 100 => self::Medium,
                default => self::Large,
            };
        }
    }

    var_dump(Size::fromLength(50));

Les méthodes statiques peuvent être publiques, privées ou protégées, bien que privées et protégées sont équivalentes car l'héritage n'est pas autorisé.

## Constantes d'énumération

Les énumérations peuvent inclure des constantes, qui peuvent être publiques, privées ou protégées, bien qu'en pratique, privées et protégées soient équivalentes car l'héritage n'est pas autorisé.

Une constante d'énumération peut faire référence à un cas d'énumération :

    <?php

    enum Size
    {
        case Small;
        case Medium;
        case Large;

        public const Huge = self::Large;
    }

    var_dump(Size::Huge);

## Traits

Les énumérations peuvent s'appuyer sur des traits, qui se comportent de la même manière que les classes. La précondition est que les traits utilisés dans une énumération ne doivent pas contenir de propriétés. Ils ne peuvent inclure que des méthodes, des méthodes statiques et des constantes. Un trait contenant des propriétés entraînera une erreur fatale.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    trait Rectangle
    {
        public function shape(): string
        {
            return "Rectangle";
        }
    }

    enum Suit implements Colorful
    {
        use Rectangle;

        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;

        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }
    }

    $suit = Suit::Spades;
    var_dump($suit->color());
    var_dump($suit->shape());

## Valeurs d'énumération dans les expressions constantes

Les cas étant représentés comme des constantes dans l'énumération elle-même, ils peuvent être utilisés comme des valeurs statiques dans la plupart des expressions constantes : valeurs par défaut des propriétés, valeurs par défaut des variables statiques, valeurs par défaut des paramètres, valeurs constantes globales et de classe. Elles ne peuvent pas être utilisées dans d'autres valeurs de cas de l'enum, mais les constantes normales peuvent faire référence à un cas d'énumération.

Cependant, les appels implicites à des méthodes magiques telles que ArrayAccess sur les enums ne sont pas autorisés dans les définitions statiques ou constantes, car nous ne pouvons pas garantir de manière absolue que la valeur résultante est déterministe ou que l'invocation de la méthode est exempte d'effets secondaires. Les appels de fonction, les appels de méthode et l'accès aux propriétés continuent d'être des opérations non valides dans les expressions constantes.

    <?php

    // Ceci est une définition d'Enum tout à fait valide.
    enum Direction implements ArrayAccess
    {
        case Up;
        case Down;

        public function offsetExists($offset): bool
        {
            return false;
        }

        public function offsetGet($offset): mixed
        {
            return null;
        }

        public function offsetSet($offset, $value): void
        {
            throw new Exception();
        }

        public function offsetUnset($offset): void
        {
            throw new Exception();
        }
    }

    class Foo
    {
        // Ceci est autorisé.
        const DOWN = Direction::Down;

        // Ceci n'est pas autorisé, car le résultat peut ne pas être déterministe.
        const UP = Direction::Up['short'];
        // Erreur fatale : Cannot use [] on enums in constant expression
    }

    // Ceci est tout à fait légal, car ce n'est pas une expression constante.
    $x = Direction::Up['short'];
    var_dump("\$x is " . var_export($x, true));

    $foo = new Foo();

## Différences avec les objets

Bien que les Enums soient construites sur la base de classes et d'objets, elles ne supportent pas toutes les fonctionnalités liées aux objets. En particulier, les cas d'énumérations ne peuvent pas avoir d'état.

- Les constructeurs et les destructeurs sont interdits.
- L'héritage n'est pas supporté. Les Enums ne peuvent pas étendre ou être étendues.
- Les propriétés statiques ou d'objet ne sont pas autorisées.
- Le clonage d'un cas d'énumération n'est pas autorisé, car les cas doivent être des instances singleton.
- Les méthodes magiques, à l'exception de celles énumérées ci-dessous, ne sont pas autorisées.
- Les énumérations doivent toujours être déclarées avant d'être utilisées.

Les fonctionnalités suivantes sont disponibles pour les objets et se comportent de la même manière que pour tout autre objet :

- Méthodes publiques, privées et protégées.
- Méthodes statiques publiques, privées et protégées.
- Constantes publiques, privées et protégées.
- Les Enums peuvent implémenter un nombre quelconque d'interfaces.
- Les enums et les cas peuvent avoir des attributs qui leur sont attachés. Le filtre `TARGET_CLASS` inclut les Enums elles-mêmes. Le filtre cible `TARGET_CLASS_CONST` inclut les cas d'Enum.
- Les méthodes magiques __call, __callStatic, et __invoke
- Les constantes `__CLASS__` et `__FUNCTION__` se comportent normalement

La constante magique `::class` sur un type Enum évalue le nom du type, y compris le namespace, exactement comme pour un objet. La constante magique `::class` sur une instance d'un cas Case évalue également le type Enum, puisqu'il s'agit d'une instance de ce type.

En outre, les cas d'énumération ne peuvent pas être instanciés directement avec `new`, ni avec ReflectionClass::newInstanceWithoutConstructor() de la réflexion. Ces deux méthodes entraîneront une erreur.

    <?php

    $clovers = new Suit();
    // Erreur : Cannot instantiate enum Suit

    $horseshoes = (new ReflectionClass(Suit::class))->newInstanceWithoutConstructor()
    // Erreur : Cannot instantiate enum Suit

## Liste de valeurs

Les Enums pures et les Enums avec valeur de base implémentent toutes deux une interface interne nommée UnitEnum. `UnitEnum` comprend une méthode statique `cases()`. `cases()` renvoie un tableau compact de tous les cas définis dans l'ordre de leur déclaration.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());

    enum SuitBacked: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    var_dump(SuitBacked::cases());

La définition manuelle d'une méthode `cases()` sur un Enum entraînera une erreur fatale.

## Sérialisation

Les énumérations sont sérialisées différemment des objets. En particulier, elles ont un nouveau code de sérialisation, `"E"`, qui spécifie le nom du cas de l'énumération. La routine de désérialisation est alors en mesure d'utiliser ce code pour définir une variable à la valeur singleton existante. Cela garantit que :

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    Suit::Hearts === unserialize(serialize(Suit::Hearts));

    print serialize(Suit::Hearts);
    // E:11:"Suit:Hearts";

Lors de la désérialisation, si un enum et un cas ne peuvent pas être trouvés pour correspondre à une valeur sérialisée, un avertissement sera émis et un `false` sera retourné.

L'option `allowed_classes` de unserialize() n'affecte pas les énumérations.

Si une Enum pure est sérialisée en JSON, une erreur sera générée. Si une Enum avec valeur de base est sérialisée en JSON, elle sera représentée par sa valeur scalaire uniquement, dans le type approprié. Le comportement des deux peut être surchargé en implémentant la méthode JsonSerializable.

Pour print_r(), la sortie d'un cas d'enum est légèrement différente de celle des objets afin de minimiser la confusion.

    <?php

    enum Foo
    {
        case Bar;
    }

    enum Baz: int
    {
        case Beep = 5;
    }

    print_r(Foo::Bar);
    print_r(Baz::Beep);

    /* Produit

    Foo Enum (
        [name] => Bar
    )
    Baz Enum:int {
        [name] => Beep
        [value] => 5
    }
    */

## Pourquoi les enums ne sont pas extensibles

Les classes ont des contrats sur leurs méthodes :

    <?php

    class A {}
    class B extends A {}

    function foo(A $a) {}

    function bar(B $b)
    {
        foo($b);
    }

Ce code est sûr du point de vue du type, car B suit le contrat de A, et par la magie de la co/contra-variance, toute attente que l'on peut avoir à l'égard des méthodes sera préservée, sauf exceptions.

Les enums ont des contrats sur leurs cas, pas sur les méthodes :

    <?php

    enum ErrorCode
    {
        case SOMETHING_BROKE;
    }

    function quux(ErrorCode $errorCode)
    {
        // Quand écrit, ce code semble couvrir tous les cas de figure
        match ($errorCode) {
            ErrorCode::SOMETHING_BROKE => true,
        };
    }

L'instruction match dans la fonction `quux` peut être analysée statiquement pour couvrir tous les cas d'ErrorCode.

Mais imaginons qu'il soit permis d'étendre les enums :

    <?php

    // Code d'expérience de pensée où les enums ne sont pas finaux.
    // À noter : cela ne fonctionnera pas en PHP.
    enum MoreErrorCode extends ErrorCode
    {
        case PEBKAC;
    }

    function fot(MoreErrorCode $errorCode)
    {
        quux($errorCode);
    }

    fot(MoreErrorCode::PEBKAC);

En vertu des règles d'héritage normales, une classe qui en étend une autre passera le contrôle de type.

Le problème serait que l'instruction match dans `quux()` ne couvre plus tous les cas. Parce qu'elle ne connaît pas `MoreErrorCode::PEBKAC`, la correspondance lèvera une exception.

Pour cette raison, les enums sont finaux et ne peuvent pas être étendus.

## Exemples

Exemple #1 Valeurs limitées de base

    <?php

    enum SortOrder
    {
        case Asc;
        case Desc;
    }

    function query($fields, $filter, SortOrder $order = SortOrder::Asc)
    {
         /* ... */
    }

La fonction `query()` peut maintenant être exécutée en sachant que `$order` est garanti d'être soit `SortOrder::Asc` ou `SortOrder::Desc`. Toute autre valeur aurait entraîné une TypeError, donc aucune autre vérification d'erreur ou test n'est nécessaire.

Exemple #2 Valeurs exclusives avancées

    <?php

    enum UserStatus: string
    {
        case Pending = 'P';
        case Active = 'A';
        case Suspended = 'S';
        case CanceledByUser = 'C';

        public function label(): string
        {
            return match ($this) {
                self::Pending => 'Pending',
                self::Active => 'Active',
                self::Suspended => 'Suspended',
                self::CanceledByUser => 'Canceled by user',
            };
        }
    }

    $status = UserStatus::Suspended;
    var_dump($status->label());

Dans cet exemple, le statut d'un utilisateur peut être l'un de, et exclusivement, `UserStatus::Pending`, `UserStatus::Active`, `UserStatus::Suspended`, ou `UserStatus::CanceledByUser`. Une fonction peut typer un paramètre par rapport à `UserStatus` et n'accepter que ces quatre valeurs, un point c'est tout.

Ces quatre valeurs ont une méthode `label()`, qui renvoie une chaîne lisible pour les humains. Cette chaîne est indépendante de la chaîne scalaire équivalente "nom machine", qui peut être utilisée dans, par exemple, un champ de base de données ou un menu déroulant HTML.

    <?php

    enum UserStatus: string
    {
        case Pending = 'P';
        case Active = 'A';
        case Suspended = 'S';
        case CanceledByUser = 'C';

        public function label(): string
        {
            return match ($this) {
                self::Pending => 'Pending',
                self::Active => 'Active',
                self::Suspended => 'Suspended',
                self::CanceledByUser => 'Canceled by user',
            };
        }
    }

    foreach (UserStatus::cases() as $case) {
        printf(
            "<option value=\"%s\">%s</option>\n",
            htmlentities($case->value),
            htmlentities($case->label())
        );
    }

# Erreurs

## Sommaire

- Bases
- Les Erreurs en PHP 7

## Introduction

Malheureusement, peu importe la prudence que nous mettons lors de l'écriture de notre code, les erreurs sont un fait de la vie. PHP signalera des erreurs, des avertissements et des avis pour de nombreux problèmes de syntaxe et d'exécution courants, et savoir comment détecter et manipuler ces erreurs rendra le débogage beaucoup plus facile.

## Bases

PHP signale des erreurs en réponse à un certain nombre de conditions d'erreurs internes. Celles-ci peuvent être utilisées pour indiquer une multitude de problèmes différents, et peuvent être affichées et/ou enregistrées dans l'historique selon les besoins.

Chaque erreur que PHP génère comprend un type. Une liste de ces types d'erreur est disponible, ainsi qu'une brève description de leur comportement et leur cause possible.

### Gestion des erreurs en PHP

Si aucun gestionnaire d'erreur n'est défini, PHP gérera les erreurs qui se produisent selon sa configuration. Quelles erreurs seront signalées et lesquelles seront ignorées est contrôlé par la directive php.ini `error_reporting` ou lors de l'exécution du script en appelant error_reporting(). Il est toutefois fortement recommandé de configurer la directive, car certaines erreurs peuvent se produire avant que l'exécution du script débute.

Dans un environnement de développement, la directive `error_reporting` devrait toujours être configurée avec `E_ALL`, afin d'être informé et de corriger les problèmes relevés par PHP. En production il est possible de configurer la directive avec un niveau moins verbeux tel que `E_ALL & ~E_NOTICE & ~E_DEPRECATED`, mais généralement `E_ALL` reste approprié car il peut fournir des avertissements en avance à des problèmes potentiels.

Comment PHP traite ces erreurs dépend de deux directives php.ini supplémentaires. `display_errors` détermine si le message d'erreur est affiché dans la sortie du script. Ceci devrait toujours être désactivé dans un environnement de production, car le message d'erreur peut contenir des informations confidentielles, telles que les mots de passe de base de données. Cependant il est souvent utile d'activer cette directive lors du développement, car ceci assure un signalement immédiat des problèmes.

En plus d'afficher les erreurs, PHP peut enregistrer les erreurs quand la directive `log_errors` est activée. Toutes les erreurs seront alors enregistrées dans le fichier ou syslog défini par `error_log`. Ceci est extrêmement utile dans un environnement de production, car les erreurs qui se produisent seront enregistrées, et des rapports pourront être générés en s'appuyant sur ces erreurs.

### Gestionnaire d'erreurs d'utilisateur

Si le gestionnaire d'erreur par défaut de PHP ne convient pas, beaucoup de types d'erreurs peuvent être gérés par un gestionnaire d'erreur personnalisé qui peut être défini avec set_error_handler(). Bien que certains types d'erreurs ne puissent pas être gérés de cette manière, ceux qui le peuvent seront gérés de la manière que le script utilisateur juge appropriée : par exemple, ceci peut être utilisé pour afficher une page d'erreur personnalisée à l'utilisateur et signaler l'erreur de façon plus directe qu'en l'enregistrant dans un fichier, comme en envoyant un courriel électronique.

## Les Erreurs en PHP 7

PHP 7 modifie la façon dont la plupart des erreurs sont signalées en PHP. Au lieu d'utiliser le mécanisme traditionnel de gestion d'erreur de PHP 5, la plupart des erreurs sont maintenant signalées en levant une exception Error.

Comme pour les exceptions normales, ces exceptions Error remonteront jusqu'à ce qu'elles atteignent le premier bloc d'attrape `catch` correspondant. S'il n'y a pas de bloc correspondant, le gestionnaire d'exception défini par défaut avec la fonction set_exception_handler() sera appelé. Et s'il n'y a pas de gestionnaire d'exception par défaut, alors l'exception sera convertie en erreur fatale et sera traitée comme une erreur traditionnelle.

Comme la hiérarchie des classes Error n'hérite pas d'Exception, le code qui utilise les blocs d'attrape `catch (Exception $e) { ... }` pour traiter les exceptions non-interceptées en PHP 5 n'interceptera pas ces exceptions Error. Il faudra donc utiliser soit un bloc `catch (Error $e) { ... }`, soit un gestionnaire d'exception défini avec set_exception_handler().

### Hiérarchie Error

- Throwable
  - Error
    - ArithmeticError
      - DivisionByZeroError
    - AssertionError
    - CompileError
      - ParseError
    - TypeError
      - ArgumentCountError
    - ValueError
    - UnhandledMatchError
    - FiberError
    - RequestParseBodyException
  - Exception
    - ...

# Les exceptions

## Sommaire

- Étendre les Exceptions

> Note: Voir aussi la classe Exception

PHP a une gestion des exceptions similaire à ce qu'offrent les autres langages de programmation. Une exception peut être lancée ("`throw`") et attrapée ("`catch`") dans PHP. Le code devra être entouré d'un bloc `try` pour faciliter la saisie d'une exception potentielle. Chaque `try` doit avoir au moins un bloc `catch` ou `finally` correspondant.

Si une exception est lancée et que la portée courante de la fonction n'a pas de bloc `catch`, l'exception "remontera" la pile d'appel de la fonction appelante jusqu'à trouver un bloc `catch` correspondant. Tous les blocs `finally` rencontrés seront exécutés. Si la pile d'appel est déroulée jusqu'à la portée globale sans rencontrer de bloc `catch` correspondant, le programme sera terminé avec une erreur fatale sauf si un gestionnaire global d'exception a été défini.

L'objet lancé doit être une `instanceof` Throwable. Tenter de lancer un objet qui ne l'est pas résultera en une erreur fatale émise par PHP.

À partir de PHP 8.0.0, le mot clé `throw` est une expression et peut être utilisé dans n'importe quel contexte d'expressions. Dans les versions antérieures c'était une déclaration qui devait être sur sa propre ligne.

## `catch`

Un bloc `catch` définit comment réagir à une exception qui a été lancée. Un bloc `catch` définit un ou plusieurs types d'exceptions ou erreurs qu'il peut gérer, et optionnellement une variable dans laquelle assigner l'exception. (Cette variable était requise dans les versions antérieures à PHP 8.0.0) Le premier bloc `catch` qu'une exception ou erreur lancée rencontre et qui correspond au type de l'objet lancé gérera l'objet.

Plusieurs blocs `catch` peuvent être utilisés pour attraper différentes classes d'exceptions. L'exécution normale (lorsqu'aucune exception n'est lancée dans le bloc `try`) continue après le dernier bloc `catch` défini dans la séquence. Les exceptions peuvent être lancées (`throw`) ou relancées dans un bloc `catch`. Sinon, l'exécution continuera après le bloc `catch` qui a été déclenché.

Lorsqu'une exception est lancée, le code suivant le traitement ne sera pas exécuté et PHP tentera de trouver le premier bloc `catch` correspondant. Si une exception n'est pas attrapée, une erreur fatale issue de PHP sera envoyée avec un message "`Uncaught Exception ...`" indiquant que l'exception n'a pu être attrapée à moins qu'un gestionnaire d'exceptions ne soit défini avec la fonction set_exception_handler().

À partir de PHP 7.1.0, un bloc `catch` peut spécifier plusieurs exceptions à l'aide du caractère pipe (`|`). Ceci est utile lorsque différentes exceptions de hiérarchies de classes différentes sont traitées de la même manière.

À partir de PHP 8.0.0, le nom de variable pour l'exception attrapée est optionnel. Si non spécifié, le bloc `catch` sera toujours exécuté mais n'aura pas accès à l'objet lancé.

## `finally`

Un bloc `finally` peut aussi être spécifié après ou à la place des blocs `catch`. Le code à l'intérieur du bloc `finally` sera toujours exécuté après les blocs `try` et `catch`, indépendamment du fait qu'une exception a été lancée, avant de continuer l'exécution normale.

Une interaction notable est entre un bloc `finally` et une déclaration `return`. Si une déclaration `return` est rencontrée à l'intérieur des blocs `try` ou `catch`, le bloc `finally` sera quand même exécuté. De plus, la déclaration `return` est évaluée quand elle est rencontrée, mais le résultat sera retourné après que le bloc `finally` soit exécuté. Additionnellement, si le bloc `finally` contient aussi une déclaration `return` la valeur du bloc `finally` est retournée.

Une autre interaction notable est entre une exception lancée dans un bloc `try`, et une exception lancée dans un bloc `finally`. Si une exception est lancée dans les deux blocs, alors, l'exception lancée dans le bloc `finally` sera celle qui sera propagée, et l'exception lancée dans le bloc `try` sera utilisée comme exception précédente.

## Gestionnaire d'exceptions global

Si une exception est autorisée à remonter jusqu'à la portée globale, elle peut être attrapée par un gestionnaire d'exceptions global s'il a été défini. La fonction set_exception_handler() peut définir une fonction qui sera appelée à la place d'un bloc `catch` si aucun autre bloc n'est invoqué. L'effet est essentiellement identique à entourer le programme entier dans un bloc `try`-`catch` avec cette fonction en tant que `catch`.

## Notes

> Note:

> Les fonctions internes de PHP utilisent principalement l' Error reporting, seules les extensions orientées objet modernes utilisent les exceptions. Quoi qu'il en soit, des erreurs peuvent facilement être traduites en exceptions avec ErrorException. Cependant, cette technique ne fonctionne que pour les erreurs non fatales.

> Exemple #1 Convertir l'error reporting en exceptions

>     <?php
>     function exceptions_error_handler($severity, $message, $filename, $lineno) {
>         throw new ErrorException($message, 0, $severity, $filename, $lineno);
>     }

>     set_error_handler('exceptions_error_handler');

Astuce

La bibliothèque standard PHP (SPL) fournit un bon nombre d'exceptions additionnelles.

## Exemples

Exemple #2 Lancer une exception

    <?php
    function inverse($x) {
        if (!$x) {
            throw new Exception('Division par zéro.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Exception reçue : ',  $e->getMessage(), "\n";
    }

    // On continue l'exécution
    echo "Bonjour le monde !\n";

L'exemple ci-dessus va afficher :

    0.2
    Exception reçue : Division par zéro.
    Bonjour le monde !

Exemple #3 Gestion de l'exception avec un bloc `finally`

    <?php
    function inverse($x) {
        if (!$x) {
            throw new Exception('Division par zéro.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
    } catch (Exception $e) {
        echo 'Exception reçue : ',  $e->getMessage(), "\n";
    } finally {
        echo "Première fin.\n";
    }

    try {
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Exception reçue : ',  $e->getMessage(), "\n";
    } finally {
        echo "Seconde fin.\n";
    }

    // On continue l'exécution
    echo "Bonjour le monde !\n";

L'exemple ci-dessus va afficher :

    0.2
    Première fin.
    Exception reçue : Division par zéro.
    Seconde fin.
    Bonjour le monde !

Exemple #4 Interaction entre le bloc `finally` et `return`

    <?php

    function test() {
        try {
            throw new Exception('foo');
        } catch (Exception $e) {
            return 'catch';
        } finally {
            return 'finally';
        }
    }

    echo test();

L'exemple ci-dessus va afficher :

    finally

Exemple #5 Exception imbriquée

    <?php

    class MyException extends Exception { }

    class Test {
        public function testing() {
            try {
                try {
                    throw new MyException('foo!');
                } catch (MyException $e) {
                    // on la relance
                    throw $e;
                }
            } catch (Exception $e) {
                var_dump($e->getMessage());
            }
        }
    }

    $foo = new Test;
    $foo->testing();

L'exemple ci-dessus va afficher :

    string(4) "foo!"

Exemple #6 Gestion des exceptions de capture multiple

    <?php

    class MyException extends Exception { }

    class MyOtherException extends Exception { }

    class Test {
        public function testing() {
            try {
                throw new MyException();
            } catch (MyException | MyOtherException $e) {
                var_dump(get_class($e));
            }
        }
    }

    $foo = new Test;
    $foo->testing();

L'exemple ci-dessus va afficher :

    string(11) "MyException"

Exemple #7 Omettre la variable attrapée

Seulement permis dans PHP 8.0.0 et ultérieur.

    <?php

    class SpecificException extends Exception {}

    function test() {
        throw new SpecificException('Oopsie');
    }

    try {
        test();
    } catch (SpecificException) {
        print "Une SpecificException a été levée, mais les détails ne nous intéressent pas.";
    }

L'exemple ci-dessus va afficher :

    Une SpecificException a été levée, mais les détails ne nous intéressent pas.

Exemple #8 Throw en tant qu'expression

Seulement permis dans PHP 8.0.0 et ultérieur.

    <?php

    function test() {
        do_something_risky() or throw new Exception("Cela n'a pas fonctionné");
    }

    function do_something_risky() {
        return false; // Simuler un échec
    }

    try {
        test();
    } catch (Exception $e) {
        print $e->getMessage();
    }

L'exemple ci-dessus va afficher :

    Cela n'a pas fonctionné

Exemple #9 Exception dans try et dans finally

    <?php

    try {
        try {
            throw new Exception(message: 'Third', previous: new Exception('Fourth'));
        } finally {
            throw new Exception(message: 'First', previous: new Exception('Second'));
        }
    } catch (Exception $e) {
        var_dump(
            $e->getMessage(),
            $e->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getPrevious()->getMessage(),
        );
    }

L'exemple ci-dessus va afficher :

    string(5) "First"
    string(6) "Second"
    string(5) "Third"
    string(6) "Fourth"

## Étendre les Exceptions

Une classe d'exception définie par l'utilisateur peut être définie en étendant la classe Exception intégrée. Les membres et les propriétés ci-dessous montrent ce qui est accessible dans la classe enfant qui dérive de la classe Exception intégrée.

Exemple #1 La classe d'exception intégrée

    <?php
    class Exception implements Throwable
    {
        protected $message = 'Unknown exception';   // Message d'exception
        private   $string;                          // cache de __toString
        protected $code = 0;                        // code d'exception défini par l'utilisateur
        protected $file;                            // nom de fichier source de l'exception
        protected $line;                            // ligne source de l'exception
        private   $trace;                           // trace de la pile d'exécution
        private   $previous;                        // exception précédente si exception imbriquée

        public function __construct($message = '', $code = 0, ?Throwable $previous = null);

        final private function __clone();           // Inhibe la duplication des exceptions.

        final public function getMessage();        // message de l'exception
        final public function getCode();           // code de l'exception
        final public function getFile();           // nom du fichier source
        final public function getLine();           // ligne source
        final public function getTrace();          // tableau de la trace de la pile d'exécution
        final public function getPrevious();       // l'exception précédente
        final public function getTraceAsString();  // trace sous forme de chaîne de caractères

        // Peut être redéfinie
        public function __toString();               // chaîne formatée pour l'affichage
    }

Si une classe étend la classe Exception intégrée et redéfinit le constructeur, il est fortement recommandé qu'elle appelle également parent::__construct() pour s'assurer que toutes les données disponibles ont été correctement assignées. La méthode __toString() peut être redéfinie pour fournir une sortie personnalisée lorsque l'objet est présenté sous forme de chaîne de caractères.

> Note:

> Les exceptions ne peuvent pas être clonées. Tenter de cloner une Exception entraînera une erreur fatale `E_ERROR`.

Exemple #2 Étendre la classe Exception

    <?php
    /**
     * Définit une classe d'exception personnalisée.
     */
    class MyException extends Exception
    {
        // Redéfinit l'exception pour que le message ne soit pas facultatif.
        public function __construct($message, $code = 0, ?Throwable $previous = null) {
            // du code

            // s'assurer que tout est correctement assigné
            parent::__construct($message, $code, $previous);
        }

        // Représentation personnalisée de l'objet sous forme de chaîne de caractères.
        public function __toString() {
            return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
        }

        public function customFunction() {
            echo "Une fonction personnalisée pour ce type d'exception\n";
        }
    }

    /**
     * Créer une classe pour tester l'exception
     */
    class TestException
    {
        public $var;

        const THROW_NONE    = 0;
        const THROW_CUSTOM  = 1;
        const THROW_DEFAULT = 2;

        function __construct($avalue = self::THROW_NONE) {

            switch ($avalue) {
                case self::THROW_CUSTOM:
                    // Lance une exception personnalisée
                    throw new MyException('1 n\'est pas un paramètre valide', 5);
                    break;

                case self::THROW_DEFAULT:
                    // Lance celle par défaut.
                    throw new Exception('2 n\'est pas autorisé comme paramètre', 6);
                    break;

                default:
                    // Aucune exception, l'objet sera créé.
                    $this->var = $avalue;
                    break;
            }
        }
    }

    echo "# Exemple 1\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (MyException $e) {      // Sera capturée
        echo "MyException capturée\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // Ignoré
        echo "Exception par défaut capturée\n", $e;
    }

    // Poursuite de l'exécution
    var_dump($o); // Null

    echo "\n\n# Exemple 2\n";
    try {
        $o = new TestException(TestException::THROW_DEFAULT);
    } catch (MyException $e) {      // Ne correspond pas à ce type
        echo "MyException capturée\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // Sera capturée
        echo "Exception par défaut capturée\n", $e;
    }

    // Poursuite de l'exécution
    var_dump($o); // Null

    echo "\n\n# Exemple 3\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (Exception $e) {        // Sera capturée
        echo "Exception par défaut capturée\n", $e;
    }

    // Poursuite de l'exécution
    var_dump($o); // Null

    echo "\n\n# Exemple 4\n";
    try {
        $o = new TestException();
    } catch (Exception $e) {        // Sauté, aucune exception
        echo "Exception par défaut capturée\n", $e;
    }

    // Poursuite de l'exécution
    var_dump($o); // TestException

# Fibres

### Aperçu des fibres

(PHP 8 >= 8.1.0)

Les fibres représentent des fonctions interruptibles sur toute la pile. Les fibres peuvent être suspendues à n'importe quel endroit de la pile d'appels, en interrompant l'exécution à l'intérieur de la fibre jusqu'à ce que la fibre soit reprise ultérieurement.

Les fibres mettent en pause l'ensemble de la pile d'exécution, de sorte que l'appelant direct de la fonction n'a pas besoin de modifier la façon dont il invoque la fonction.

L'exécution peut être interrompue n'importe où dans la pile d'appels en utilisant Fiber::suspend() (c'est-à-dire que l'appel à Fiber::suspend() peut se trouver dans une fonction profondément imbriquée ou ne pas exister du tout).

Contrairement aux Generator n'ayant pas de pile, chaque Fiber possède sa propre pile d'appels, ce qui leur permet d'être mises en pause dans des appels de fonctions profondément imbriquées. Une fonction déclarant un point d'interruption (c'est-à-dire appelant Fiber::suspend()) n'a pas besoin de changer son type de retour, contrairement à une fonction utilisant `yield` qui doit retourner une instance de Generator.

Les fibres peuvent être suspendues dans n'importe quel appel de fonction, y compris celles appelées à l'intérieur de la VM PHP, comme les fonctions fournies à array_map() ou les méthodes appelées par `foreach` sur un objet Iterator.

Une fois suspendue, l'exécution de la fibre peut être reprise avec n'importe quelle valeur en utilisant Fiber::resume() ou en levant une exception dans la fibre à l'aide de Fiber::throw(). La valeur est renvoyée (ou l'exception levée) par Fiber::suspend().

> Note: Avant PHP 8.4.0, le changement de fibres pendant l'exécution d'un destructeur d'objet n'était pas autorisé.

Exemple #1 Utilisation de base

    <?php
    $fiber = new Fiber(function (): void {
       $value = Fiber::suspend('fiber');
       echo "Valeur utilisée pour reprendre la fibre: ", $value, PHP_EOL;
    });

    $value = $fiber->start();

    echo "Valeur de la suspension de la fibre: ", $value, PHP_EOL;

    $fiber->resume('test');
    ?>

L'exemple ci-dessus va afficher :

    Valeur de la suspension de la fibre: fiber
    Valeur utilisée pour reprendre la fibre: test

# Les générateurs

## Sommaire

- Résumé sur les générateurs
- Syntaxe d'un Générateur
- Comparaison des générateurs avec les objets Iterator

## Résumé sur les générateurs

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Les générateurs fournissent une façon simple de mettre en place des itérateurs sans le coût ni la complexité du développement d'une classe qui implémente l'interface Iterator.

Un générateur offre un moyen pratique de fournir des données aux boucles `foreach` sans avoir à construire un tableau en mémoire à l'avance, ce qui pourrait amener le programme à dépasser une limite de mémoire ou nécessiter un temps de traitement considérable pour les générer. À la place, une fonction générateur peut être utilisée, qui est identique à une fonction normale, mis à part le fait qu'au lieu de retourner une seule fois, un générateur peut utiliser `yield` autant de fois que nécessaire, afin de fournir les valeurs à parcourir. Comme avec les itérateurs, l'accès aléatoire aux données n'est pas possible.

Un exemple simple de ce mécanisme est la ré-implémentation de la fonction range() sous la forme d'un générateur. La fonction standard range() doit générer un tableau contenant chaque valeur, et le retourner, ce qui peut conduire à des tableaux de taille importante : par exemple, l'appel du code range(0, 1000000) peut consommer nettement plus de 100 Mo de mémoire.

Comme alternative, nous pouvons implémenter un générateur `xrange()`, qui n'aura comme besoin mémoire que la seule création d'un objet Iterator, et devra garder trace en interne du statut courant du générateur, ce qui revient à une consommation mémoire inférieure à 1 Ko.

Exemple #1 Implémentation de la fonction range() sous la forme d'un générateur

    <?php
    function xrange($start, $limit, $step = 1) {
        if ($start <= $limit) {
            if ($step <= 0) {
                throw new LogicException('Step must be positive');
            }

            for ($i = $start; $i <= $limit; $i += $step) {
                yield $i;
            }
        } else {
            if ($step >= 0) {
                throw new LogicException('Step must be negative');
            }

            for ($i = $start; $i >= $limit; $i += $step) {
                yield $i;
            }
        }
    }

    /*
     * Il est à noter que les fonctions range() et xrange() produisent le
     * même affichage, ci-dessous.
     */

    echo 'Nombres impairs à un seul chiffre depuis range() :  ';
    foreach (range(1, 9, 2) as $number) {
        echo "$number ";
    }
    echo "\n";

    echo 'Nombres impairs à un seul chiffre depuis xrange() : ';
    foreach (xrange(1, 9, 2) as $number) {
        echo "$number ";
    }

L'exemple ci-dessus va afficher :

    Nombres impairs à un seul chiffre depuis range() :  1 3 5 7 9
    Nombres impairs à un seul chiffre depuis xrange() : 1 3 5 7 9

### Les objets Generator

Lorsqu'une fonction générateur est appelée, un objet de la classe interne Generator est retourné. Cet objet implémente l'interface Iterator de la même façon qu'un objet itérateur, qui avance uniquement, le ferait, et fournit les méthodes qui peuvent être appelées pour manipuler le statut du générateur, y compris l'envoi des valeurs et leurs retours.

## Syntaxe d'un Générateur

Une fonction générateur ressemble à une fonction normale, sauf qu'au lieu de retourner une valeur, un générateur `yield` retourne autant de valeurs que nécessaire. Toute fonction contenant `yield` est une fonction générateur.

Lorsqu'une fonction générateur est appelée, elle retourne un objet que l'on peut parcourir. Lors du parcours de cet objet (par exemple, via une boucle `foreach`), PHP appellera les méthodes d'itération de l'objet chaque fois qu'il a besoin d'une valeur, puis sauvegarde le statut du générateur lorsqu'il génère une valeur, pour qu'il puisse être repris lorsque la prochaine valeur sera requise.

Lorsqu'il n'y a plus de valeur à fournir, la fonction générateur peut simplement retourner, et le code appelant continuera comme si un tableau n'avait plus de valeur.

> Note:

> Un générateur peut retourner des valeurs, qui peuvent être récupérées en utilisant Generator::getReturn().

### Le mot-clé yield

Le mot clé yield est le cœur d'une fonction générateur. Dans sa forme la plus simple, une instruction yield ressemble à une instruction return, excepté qu'au lieu de stopper l'exécution de la fonction et de retourner, yield fournit une valeur au code parcourant le générateur, et met en pause l'exécution de la fonction générateur.

Exemple #1 Un exemple simple de production de valeurs

    <?php
    function gen_one_to_three() {
        for ($i = 1; $i <= 3; $i++) {
            // $i est préservé entre chaque production de valeur.
            yield $i;
        }
    }

    $generator = gen_one_to_three();
    foreach ($generator as $value) {
        echo "$value\n";
    }

L'exemple ci-dessus va afficher :

    1
    2
    3

> Note:

> En interne, des clés séquentielles entières seront associées avec les valeurs produites, de la même manière que pour un tableau non-associatif.

#### Fourniture de valeurs avec des clés

PHP supporte également les tableaux associatifs, et les générateurs ne sont pas différents. En plus de fournir des valeurs simples, comme nous l'avons vu plus haut, il est aussi possible, en même temps, de fournir une clé.

La syntaxe permettant de produire une paire clé/valeur est similaire à celle utilisée pour définir un tableau associatif ; comme ceci :

Exemple #2 Production d'une paire clé/valeur

    <?php
    /*
     * L'entrée est constituée de champs séparés par un point-virgule,
     * et le premier champ est un ID à utiliser comme clé.
     */

    $input = <<<'EOF'
    1;PHP;Likes dollar signs
    2;Python;Likes whitespace
    3;Ruby;Likes blocks
    EOF;

    function input_parser($input) {
        foreach (explode("\n", $input) as $line) {
            $fields = explode(';', $line);
            $id = array_shift($fields);

            yield $id => $fields;
        }
    }

    foreach (input_parser($input) as $id => $fields) {
        echo "$id:\n";
        echo "    $fields[0]\n";
        echo "    $fields[1]\n";
    }

L'exemple ci-dessus va afficher :

    1:
        PHP
        Likes dollar signs
    2:
        Python
        Likes whitespace
    3:
        Ruby
        Likes blocks

#### Production de valeurs nulles

Yield peut être appelé sans argument pour fournir une valeur nulle avec une clé automatique.

Exemple #3 Production de valeurs nulles

    <?php
    function gen_three_nulls() {
        foreach (range(1, 3) as $i) {
            yield;
        }
    }

    var_dump(iterator_to_array(gen_three_nulls()));

L'exemple ci-dessus va afficher :

    array(3) {
      [0]=>
      NULL
      [1]=>
      NULL
      [2]=>
      NULL
    }

#### Production de valeurs par référence

Les fonctions générateur peuvent produire des valeurs par référence. Ceci se fait de la même façon que le retour par référence depuis des fonctions : en ajoutant un ET commercial (&) au nom de la fonction.

Exemple #4 Production de valeurs par référence

    <?php
    function &gen_reference() {
        $value = 3;

        while ($value > 0) {
            yield $value;
        }
    }

    /*
     * Il est à noter qu'il est possible de changer $number dans la boucle,
     * et, du fait que le générateur fournit des références, $value
     * dans gen_reference() change aussi.
     */
    foreach (gen_reference() as &$number) {
        echo (--$number).'... ';
    }

L'exemple ci-dessus va afficher :

    2... 1... 0...

#### Délégation du générateur via yield from

La délégation du générateur permet d'obtenir les valeurs d'un autre générateur, d'un objet Traversable, ou d'un array en utilisant le mot clé yield from. Le générateur externe va ainsi obtenir toutes les valeurs du générateur interne, de l'objet, ou du tableau tant qu'il n'est pas invalide, après quoi, l'exécution va continuer dans le générateur externe.

Si un générateur est utilisé avec l'expression yield from, l'expression yield from va aussi retourner toute valeur retournée par le générateur interne.

Attention

# Stocker dans un tableau (e.g. avec iterator_to_array())

yield from ne réinitialise pas les clés. Il préserve les clés retournées par l'objet Traversable, ou array. Donc, certaines valeurs peuvent partager une clé commune avec d'autres yield ou yield from, qui, lors de l'insertion dans un tableau, écrasera les anciennes valeurs avec cette clé.

Un cas fréquent où cela est important est iterator_to_array() renvoyant un tableau avec clé par défaut, conduisant à des résultats éventuellement inattendus. iterator_to_array() a un second paramètre `preserve_keys` qui peut être défini sur `false` pour collecter toutes les valeurs en ignorant les clés renvoyées par le Generator.

Exemple #5 yield from avec iterator_to_array()

    <?php
    function inner() {
        yield 1; // clé 0
        yield 2; // clé 1
        yield 3; // clé 2
    }
    function gen() {
        yield 0; // clé 0
        yield from inner(); // clés 0-2
        yield 4; // clé 1
    }
    // met à false le second paramètre pour avoir un tableau [0, 1, 2, 3, 4]
    var_dump(iterator_to_array(gen()));

L'exemple ci-dessus va afficher :

    array(3) {
      [0]=>
      int(1)
      [1]=>
      int(4)
      [2]=>
      int(3)
    }

Exemple #6 Utilisation basique de yield from

    <?php
    function count_to_ten() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        yield 9;
        yield 10;
    }

    function seven_eight() {
        yield 7;
        yield from eight();
    }

    function eight() {
        yield 8;
    }

    foreach (count_to_ten() as $num) {
        echo "$num ";
    }

L'exemple ci-dessus va afficher :

    1 2 3 4 5 6 7 8 9 10

Exemple #7 yield from et les valeurs retournées

    <?php
    function count_to_ten() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        return yield from nine_ten();
    }

    function seven_eight() {
        yield 7;
        yield from eight();
    }

    function eight() {
        yield 8;
    }

    function nine_ten() {
        yield 9;
        return 10;
    }

    $gen = count_to_ten();
    foreach ($gen as $num) {
        echo "$num ";
    }
    echo $gen->getReturn();

L'exemple ci-dessus va afficher :

    1 2 3 4 5 6 7 8 9 10

## Comparaison des générateurs avec les objets Iterator

Le principal avantage des générateurs est leur simplicité. Moins de code doit être écrit que lorsqu'il s'agit d'implémenter une classe Iterator, et il est généralement plus lisible. Par exemple, la fonction et la classe suivante sont équivalentes :

    <?php
    function getLinesFromFile($fileName) {
        if (!$fileHandle = fopen($fileName, 'r')) {
            return;
        }

        while (false !== $line = fgets($fileHandle)) {
            yield $line;
        }

        fclose($fileHandle);
    }

    // contre...

    class LineIterator implements Iterator {
        protected $fileHandle;

        protected $line;
        protected $i;

        public function __construct($fileName) {
            if (!$this->fileHandle = fopen($fileName, 'r')) {
                throw new RuntimeException('Impossible d\'ouvrir le fichier : "' . $fileName . '"');
            }
        }

        public function rewind() {
            fseek($this->fileHandle, 0);
            $this->line = fgets($this->fileHandle);
            $this->i = 0;
        }

        public function valid() {
            return false !== $this->line;
        }

        public function current() {
            return $this->line;
        }

        public function key() {
            return $this->i;
        }

        public function next() {
            if (false !== $this->line) {
                $this->line = fgets($this->fileHandle);
                $this->i++;
            }
        }

        public function __destruct() {
            fclose($this->fileHandle);
        }
    }

Cependant, cette flexibilité a un coût : les générateurs sont des itérateurs n'allant que vers l'avant, et ils ne peuvent pas être ré-initialisés une fois leur parcours commencé. Cela signifie également que le même générateur ne peut pas être utilisé à plusieurs reprises : le générateur devra être reconstruit en appelant une nouvelle fois la fonction générateur.

### Voir aussi

- Itération d'Objet

# Attributs

## Sommaire

- Aperçu des attributs
- Syntaxe des attributs
- Lecture des attributs avec l'API de Reflection
- Déclaration des classes d'attributs

## Aperçu des attributs

(PHP 8)

Les attributs PHP fournissent des métadonnées structurées et lisibles par machine pour les classes, méthodes, fonctions, paramètres, propriétés et constantes. Ils peuvent être inspectés à l'exécution via l'API de réflexion, permettant un comportement dynamique sans modifier le code. Les attributs offrent un moyen déclaratif d'annoter le code avec des métadonnées.

Les attributs permettent de découpler l'implémentation d'une fonctionnalité de son utilisation. Alors que les interfaces définissent une structure en imposant des méthodes, les attributs fournissent des métadonnées sur plusieurs éléments, y compris les méthodes, fonctions, propriétés et constantes. Contrairement aux interfaces, qui imposent l'implémentation de méthodes, les attributs annotent le code sans en modifier la structure.

Les attributs peuvent compléter ou remplacer des méthodes d'interface optionnelles en fournissant des métadonnées plutôt qu'une structure imposée. Prenons une interface `ActionHandler` qui représente une opération dans une application. Certaines implémentations peuvent nécessiter une étape d'initialisation, tandis que d'autres non. Plutôt que d'obliger toutes les classes implémentant `ActionHandler` à définir une méthode `setUp()`, un attribut peut indiquer les besoins en initialisation. Cette approche augmente la flexibilité en permettant d'appliquer les attributs plusieurs fois si nécessaire.

Exemple #1 Implémentation de méthodes optionnelles d'une interface avec des attributs

    <?php
    interface ActionHandler
    {
        public function execute();
    }

    #[Attribute]
    class SetUp {}

    class CopyFile implements ActionHandler
    {
        public string $fileName;
        public string $targetDirectory;

        #[SetUp]
        public function fileExists()
        {
            if (!file_exists($this->fileName)) {
                throw new RuntimeException("Le fichier n'existe pas.");
            }
        }

        #[SetUp]
        public function targetDirectoryExists()
        {
            if (!file_exists($this->targetDirectory)) {
                mkdir($this->targetDirectory);
            } elseif (!is_dir($this->targetDirectory)) {
                throw new RuntimeException("Le répertoire cible $this->targetDirectory n'est pas un répertoire.");
            }
        }

        public function execute()
        {
            copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName));
        }
    }

    function executeAction(ActionHandler $actionHandler)
    {
        $reflection = new ReflectionObject($actionHandler);

        foreach ($reflection->getMethods() as $method) {
            $attributes = $method->getAttributes(SetUp::class);

            if (count($attributes) > 0) {
                $methodName = $method->getName();

                $actionHandler->$methodName();
            }
        }

        $actionHandler->execute();
    }

    $copyAction = new CopyFile();
    $copyAction->fileName = "/tmp/foo.jpg";
    $copyAction->targetDirectory = "/home/user";

    executeAction($copyAction);

## Syntaxe des attributs

La syntaxe des attributs consiste en plusieurs composants clés. Une déclaration d'attribut commence par `#[` et se termine par `]`. À l'intérieur, un ou plusieurs attributs peuvent être listés, séparés par des virgules. Le nom de l'attribut peut être non qualifié, qualifié, ou complètement qualifié, comme décrit dans Utilisation de base des espaces de noms. Les arguments de l'attribut sont optionnels et sont placés entre parenthèses `()`. Les arguments peuvent uniquement être des valeurs littérales ou des expressions constantes. La syntaxe des arguments positionnels et nommés est supportée.

Les noms d'attributs et leurs arguments sont résolus vers une classe, et les arguments sont passés à son constructeur lorsqu'une instance de l'attribut est demandée via l'API de réflexion. Il est donc recommandé d'introduire une classe pour chaque attribut.

Exemple #1 Syntaxe des attributs

    <?php
    // a.php
    namespace MyExample;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
        const VALUE = 'value';

        private $value;

        public function __construct($value = null)
        {
            $this->value = $value;
        }
    }

    // b.php

    namespace Another;

    use MyExample\MyAttribute;

    #[MyAttribute]
    #[\MyExample\MyAttribute]
    #[MyAttribute(1234)]
    #[MyAttribute(value: 1234)]
    #[MyAttribute(MyAttribute::VALUE)]
    #[MyAttribute(array("key" => "value"))]
    #[MyAttribute(100 + 200)]
    class Thing
    {
    }

    #[MyAttribute(1234), MyAttribute(5678)]
    class AnotherThing
    {
    }

## Lecture des attributs avec l'API de Reflection

Pour accéder aux attributs des classes, méthodes, fonctions, paramètres, propriétés et constantes de classe, il convient d'utiliser la méthode getAttributes() fournie par l'API de réflexion. Cette méthode retourne un tableau d'instances de ReflectionAttribute. Ces instances permettent d'interroger le nom de l'attribut, ses arguments, et peuvent être utilisées pour créer une instance de l'attribut représenté.

Séparer la représentation obtenue par réflexion d'un attribut de son instance réelle offre un meilleur contrôle sur la gestion des erreurs, comme l'absence de classe d'attribut, les arguments mal typés ou les valeurs manquantes. Les objets de la classe d'attribut ne sont instanciés qu'après l'appel à ReflectionAttribute::newInstance(), garantissant que la validation des arguments a lieu à ce moment-là.

Exemple #1 Lecture des attributs à l'aide de l'API de Reflection

    <?php

    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing
    {
    }

    function dumpAttributeData($reflection) {
        $attributes = $reflection->getAttributes();

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpAttributeData(new ReflectionClass(Thing::class));

L'exemple ci-dessus va afficher :

    string(11) "MyAttribute"
    array(1) {
      ["value"]=>
      int(1234)
    }
    object(MyAttribute)#3 (1) {
      ["value"]=>
      int(1234)
    }

Plutôt que d'itérer sur tous les attributs d'une instance de réflexion, il est possible de récupérer uniquement ceux d'une classe d'attribut spécifique en passant le nom de la classe d'attribut en argument.

Exemple #2 Lecture d'attributs spécifiques à l'aide de l'API de Reflection

    <?php
    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing
    {
    }

    function dumpMyAttributeData($reflection) {
        $attributes = $reflection->getAttributes(MyAttribute::class);

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpMyAttributeData(new ReflectionClass(Thing::class));

## Déclaration des classes d'attributs

Il est recommandé de définir une classe distincte pour chaque attribut. Dans le cas le plus simple, une classe vide avec la déclaration `#[Attribute]` est suffisante. L'attribut peut être importé depuis le namespace global à l'aide d'une instruction `use`.

Exemple #1 Classe d'attribut simple

    <?php

    namespace Example;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
    }

Pour restreindre les types de déclarations auxquels un attribut peut être appliqué, il convient de passer un masque de bits en premier argument de la déclaration `#[Attribute]`.

Exemple #2 Utilisation de la spécification de la cible pour restreindre l'utilisation des attributs

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
    class MyAttribute
    {
    }

La déclaration de MyAttribute sur un autre type lèvera désormais une exception lors de l'appel à ReflectionAttribute::newInstance()

Les cibles suivantes peuvent être spécifiées:

- `Attribute::TARGET_CLASS`
- `Attribute::TARGET_FUNCTION`
- `Attribute::TARGET_METHOD`
- `Attribute::TARGET_PROPERTY`
- `Attribute::TARGET_CLASS_CONSTANT`
- `Attribute::TARGET_PARAMETER`
- `Attribute::TARGET_ALL`

Par défaut, un attribut ne peut être utilisé qu'une seule fois par déclaration. Pour autoriser un attribut à être répété, il faut le spécifier dans le masque de bits de la déclaration `#[Attribute]` en utilisant le drapeau `Attribute::IS_REPEATABLE`.

Exemple #3 Utilisation de IS_REPEATABLE pour permettre à un attribut d'être utilisé plusieurs fois dans une déclaration

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
    class MyAttribute
    {
    }

# Les références

## Sommaire

- Qu'est-ce qu'une référence ?
- Que font les références ?
- Ce que les références ne sont pas
- Passage par référence
- Retourner des références
- Détruire une référence
- Repérer une référence

## Qu'est-ce qu'une référence ?

En PHP, les références sont un moyen d'accéder au contenu d'une même variable en utilisant plusieurs noms. Les références ne sont pas comme des pointeurs en C : il n'est pas possible d'effectuer d'opération arithmétique de pointeurs sur celles-ci, ce ne sont pas des adresses mémoires, etc. Consulter Ce que les références ne sont pas pour plus d'informations. En fait, les références sont des alias dans la table des symboles. Il est à noter qu'en PHP, le nom d'une variable et son contenu sont deux notions distinctes, ce qui fait que l'on peut donner plusieurs noms au même contenu. On peut faire l'analogie avec les fichiers sous Unix, et leurs noms : les noms des variables sont les entrées dans un répertoire, tandis que le contenu de la variable est le fichier en lui-même. Les références en PHP peuvent alors être considérées comme semblables aux liens sous Unix.

## Que font les références ?

Il existe trois principales utilisations des références : l'assignation par référence, le passage par référence et le retour par référence. Cette section va introduire ces opérations, avec des liens vers plus de précisions.

### Assignation par référence

Dans ce premier cas, les références PHP permettent de faire en sorte que deux variables référencent le même contenu. Par exemple :

    <?php
    $a =& $b;

Cette écriture indique que $a et $b pointent sur le même contenu.

> Note:

> $a et $b sont complètement égales ici : ce n'est pas $a qui pointe sur $b, ou vice-versa. Ce sont bien $a et $b qui pointent sur le même contenu.

> Note:

> Si l'on assigne, passe, ou retourne, une variable indéfinie par référence, elle sera créée automatiquement.

> Exemple #1 Utilisation des références avec des variables indéfinies

>     <?php

>     function foo(&$var) {}

>     foo($a); // $a est "créée" et assignée à NULL

>     $b = array();
>     foo($b['b']);
>     var_dump(array_key_exists('b', $b)); // bool(true)

>     $c = new stdClass();
>     foo($c->d);
>     var_dump(property_exists($c, 'd')); // bool(true)

La même syntaxe peut être utilisée avec les fonctions qui retournent des références :

    <?php
    $foo =& find_var($bar);

Utiliser la même syntaxe avec une fonction qui ne retourne pas par référence génèrera une erreur, comme l'utiliser avec le résultat de l'opérateur new. Bien que les objets soient passés comme des pointeurs, ceci n'est pas identique aux références comme expliqué dans la section les Objets et références.

Avertissement

Si une référence est assignée à une variable déclarée comme `global` dans une fonction, la référence ne sera visible qu'au sein de la fonction. Il est possible d'éviter cela en utilisant le tableau $GLOBALS.

Exemple #2 Référencer des variables globales depuis des fonctions

    <?php
    $var1 = "Variable Exemple";
    $var2 = "";

    function global_references($use_globals)
    {
        global $var1, $var2;

        if (!$use_globals) {
            $var2 =& $var1; // visible uniquement dans la fonction
        } else {
            $GLOBALS["var2"] =& $var1; // visible également dans le contexte global
        }
    }

    global_references(false);
    echo "var2 est défini à '$var2'\n"; // var2 est défini à ''

    global_references(true);
    echo "var2 est défini à '$var2'\n"; // var2 est défini à 'Variable Exemple'

Considérer `global $var;` comme un raccourci pour `$var =& $GLOBALS['var'];`. De ce fait, assigner une autre référence à `$var` modifie uniquement la référence locale de la variable.

> Note:

> Si une valeur est assignée à une variable qui a des références dans une structure `foreach`, les références seront également modifiées.

> Exemple #3 Références et structure foreach

>     <?php
>     $ref = 0;
>     $row =& $ref;

>     foreach (array(1, 2, 3) as $row) {
>         // faites quelque chose
>     }

>     echo $ref; // 3 - le dernier élément du tableau itéré

Même si ce n'est pas strictement une assignation par référence, les expressions créées avec la structure de langage `array()` peuvent aussi se comporter comme telles, en préfixant par `&` l'élément du tableau. Voici un exemple :

    <?php
    $a = 1;
    $b = array(2, 3);

    $arr = array(&$a, &$b[0], &$b[1]);
    $arr[0]++;
    $arr[1]++;
    $arr[2]++;
    /* $a == 2, $b == array(3, 4); */
    var_dump($a);
    var_dump($b);

Il est à noter par contre que les références à l'intérieur des tableaux peuvent s'avérer dangereuses. Utiliser une assignation normale (pas par référence) avec une référence à droite de l'opérateur ne transforme pas la partie gauche de l'assignation en référence, mais les références à l'intérieur des tableaux sont préservées. Ceci s'applique également aux appels de fonctions avec un tableau passé par valeur. Exemple :

    <?php

    /* Assignation de variables scalaires */
    $a = 1;
    $b =& $a;
    $c = $b;
    $c = 7; // $c n'est pas une référence ; pas de changement à $a ou $b
    print "a = {$a}; b = {$b}; c = {$c}\n\n";

    /* Assignation de variables de type tableau */
    $arr = array(1);
    $a =& $arr[0]; // $a et $arr[0] sont des références vers la même valeur
    $arr2 = $arr; // PAS une assignation par référence!
    $arr2[0]++;
    /* $a == 2, $arr == array(2) */
    /* Les contenus de $arr sont changés même si ce n'était pas une référence ! */
    print "a = {$a}\n";
    var_dump($arr);
    var_dump($arr2);

Autrement dit, d'un point de vue des références, le comportement des tableaux est défini élément par élément ; le comportement de chaque élément est indépendant du statut de référence du tableau qui les contient.

### Passage par référence

Le deuxième intérêt des références est de permettre de passer des variables par référence. On réalise ceci en faisant référencer le même contenu par une variable locale à une fonction et par une variable du contexte appelant. Par exemple :

    <?php
    function foo(&$var)
    {
        $var++;
    }

    $a = 5;
    foo($a);
    print $a;

Après l'exécution de cette portion de code, $a vaut 6. Cela provient du fait que, dans la fonction foo, la variable $var pointe sur le même contenu que $a. Pour plus d'informations à ce sujet, consulter la section passage par référence.

### Retour par référence

Le troisième intérêt des références est de permettre le retour de valeurs par référence.

## Ce que les références ne sont pas

Comme nous l'avons vu précédemment, les références ne sont pas des pointeurs. Cela signifie que le script suivant ne fera pas ce à quoi on peut s'attendre :

    <?php
    function foo(&$var)
    {
        $var =& $GLOBALS["baz"];
    }

    foo($bar);

Ici, la variable $var dans la fonction foo sera liée à $bar dans l'appelant, mais elle sera ensuite reliée à $GLOBALS["baz"]. Il n'est pas possible de lier $bar à quelque chose d'autre en utilisant le mécanisme de références, car $bar n'est pas accessible dans la fonction foo (certes, elle est représentée par $var, mais $var ne fait référence qu'à la valeur, et n'a pas de liaison dans la table des symboles de l'appelant). Il est possible d'utiliser le retour par référence pour référencer des variables sélectionnées par la fonction.

## Passage par référence

Il est possible de passer une variable par référence à une fonction, de manière à ce que celle-ci puisse la modifier. La syntaxe est la suivante :

    <?php
    function foo(&$var)
    {
        $var++;
    }

    $a = 5;
    foo($a);
    print $a; // $a vaut 6 maintenant

> Note: Il n'y a pas de signe de référence dans l'appel de la fonction, uniquement sur sa définition. La définition de la fonction en elle-même est suffisante pour passer correctement des arguments par référence.

Les données suivantes peuvent être passées par référence :

- Une variable, comme dans `foo($a)`

- Une référence retournée par une fonction :

      <?php
      function foo(&$var)
      {
          $var++;
          print $var;
      }

      function &bar()
      {
          $a = 5;
          return $a;
      }

      foo(bar());

  Pour plus d'informations, voir les détails dans retour par référence.

Toutes les autres expressions ne devraient pas être passées par référence, car le résultat sera indéfini. Par exemple, les passages par référence suivants sont invalides :

    <?php

    function foo(&$var)
    {
        $var++;
    }

    function bar() // Notez l'absence de &
    {
        $a = 5;
        return $a;
    }

    foo(bar()); // Produit une notice

    foo($a = 5); // Expression, pas une variable
    foo(5); // Produit une erreur fatale

    class Foobar {}

    foo(new Foobar()) // Produit une notice à partir de PHP 7.0.7
                      // Notice: Seules les variables devraient être passées par référence

## Retourner des références

Retourner des références est utile lorsque l'on souhaite utiliser une fonction pour déterminer à quelle variable une référence devrait être liée. Il ne faut pas utiliser le retour par référence pour améliorer les performances, le moteur est suffisamment robuste pour optimiser cela en interne. Il convient de ne retourner des références que lorsqu'il y a de bonnes raisons techniques de le faire. Pour retourner des références, utiliser cette syntaxe :

    <?php
    class Foo
    {
        public $value = 42;

        public function &getValue()
        {
            return $this->value;
        }
    }

    $obj = new Foo();
    $myValue = &$obj->getValue(); // $myValue est une référence de $obj->value, qui vaut 42.
    $obj->value = 2;
    echo $myValue;                // affiche la nouvelle valeur de $obj->value, i.e. 2.

Dans cet exemple, on affecte une valeur à la propriété de l'objet retourné par la fonction getValue, et non à sa copie, comme ce serait le cas si nous n'avions pas utilisé la syntaxe de référence.

> Note: Contrairement au passage de paramètre, ici, il faut utiliser `&` aux deux endroits, à la fois pour indiquer le retour par référence (pas par copie), et pour indiquer l'assignation aussi par référence (pas par copie non plus) pour la variable $myValue.

> Note: Tenter de retourner une référence depuis une fonction avec la syntaxe : `return ($this->value);`, ne fonctionnera pas comme attendu, et retournera le résultat de l'expression, et pas de la variable, par référence. Seules des variables peuvent être retournées par référence depuis une fonction - et rien d'autre.

Pour utiliser la référence retournée, il faut utiliser l'affectation par référence :

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    $collection = &collector();
    // Désormais, la variable $collection est une variable par référence qui référence le tableau static à l’intérieur de la fonction

    $collection[] = 'foo';

    print_r(collector());

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => foo
    )

> Note: Si l'affectation est faite sans le symbole `&`, par exemple `$collection = collector();`, la variable $collection recevra une copie de la valeur, et non la référence retournée par la fonction.

Pour passer la référence retournée à une autre fonction attendant une référence, il est possible d'utiliser la syntaxe suivante :

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    array_push(collector(), 'foo');

> Note: Il est à noter que `array_push(&collector(), 'foo');` ne fonctionnera pas, et résultera en une erreur fatale.

## Détruire une référence

Lorsqu'une référence est détruite, cela ne fait que casser le lien entre le nom de la variable et son contenu. Cela ne signifie pas que le contenu de la variable est détruit. Par exemple :

    <?php
    $a = 1;
    $b =& $a;
    unset($a);
    var_dump($a);
    var_dump($b);

Cet exemple ne détruira pas $b, mais juste $a.

Encore une fois, on peut comparer cette action avec l'appel unlink d'Unix.

## Repérer une référence

De nombreuses syntaxes de PHP sont implémentées via le mécanisme de référence, et tout ce qui a été vu concernant les liaisons entre variables s'applique à ces syntaxes. Certaines constructions, comme le passage d'arguments et le retour par référence, ont été mentionnées plus haut. D'autres constructions qui utilisent les références sont les suivantes :

### Références globales

Lorsqu'une variable est déclarée en tant que global $var, cela crée en fait une référence sur une variable globale. Autrement dit, cela revient au même que :

    <?php
    $var =& $GLOBALS["var"];

Cela signifie aussi que détruire la variable $var n'entraînera pas la destruction de la variable globale.

# Variables prédéfinies

PHP fournit des variables prédéfinies qui représentent des variables externes, des variables d'environnement intégrées et d'autres informations sur l'environnement d'exécution, telles que le nombre et les valeurs des arguments passés au script dans l'environnement CLI.

# Les Superglobales

Les Superglobales — Les variables internes qui sont toujours disponibles, quel que soit le contexte

### Description

Plusieurs variables prédéfinies en PHP sont "superglobales", ce qui signifie qu'elles sont disponibles quel que soit le contexte du script. Il est inutile de faire global $variable; avant d'y accéder dans les fonctions ou les méthodes.

Les variables superglobales sont :

- $GLOBALS
- $_SERVER
- $_GET
- $_POST
- $_FILES
- $_COOKIE
- $_SESSION
- $_REQUEST
- $_ENV

### Notes

> Note: Disponibilité des variables

> Par défaut, toutes les superglobales sont disponibles, et seules les directives de configuration peuvent les rendre indisponibles. Pour plus d'informations, se reporter à la documentation sur l'ordre des variables.

> Note: Variable variables

> Les superglobales ne peuvent pas être utilisées comme variables dynamiques dans une fonction ou une méthode d'une classe.

### Voir aussi

- La portée des variables
- La directive variables_order
- L'extension sur les filtres

# $GLOBALS

(PHP 4, PHP 5, PHP 7, PHP 8)

$GLOBALS — Référence toutes les variables disponibles dans un contexte global

### Description

Un tableau associatif contenant les références sur toutes les variables globales actuellement définies dans le contexte d'exécution global du script. Les noms des variables sont les index du tableau.

### Exemples

Exemple #1 Exemple avec $GLOBALS

    <?php

    function test()
    {
        $foo = "variable locale";

        echo '$foo dans le contexte global : ' . $GLOBALS["foo"] . "\n";
        echo '$foo dans le contexte courant : ' . $foo . "\n";
    }

    $foo = "Exemple de contenu";
    test();

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    $foo dans le contexte global : Exemple de contenu
    $foo dans le contexte courant : variable locale

Avertissement

À partir de PHP 8.1.0, l'accès en écriture au tableau entier $GLOBALS n'est désormais plus supporté :

Exemple #2 Écrire au tableau entier $GLOBALS résultera en une erreur.

    <?php

    // Génère une erreur lors de la compilation :
    $GLOBALS = [];
    $GLOBALS += [];
    $GLOBALS =& $x;
    $x =& $GLOBALS;
    unset($GLOBALS);
    array_pop($GLOBALS);
    // ...et toute autre opération d'écriture/lecture-écriture sur $GLOBALS

    ?>

### Notes

> Note: Ceci est une 'superglobale', ou variable globale automatique. Cela signifie simplement que cette variable est disponible dans tous les contextes du script. Il n'est pas nécessaire de faire global $variable; pour y accéder dans les fonctions ou les méthodes.

> Note: Disponibilité des variables

> Contrairement à toutes les autres superglobales, $GLOBALS a toujours été disponible en PHP.

> Note:

> À partir de PHP 8.1.0, $GLOBALS est désormais une copie en lecture seule du tableau de symbole global. C'est-à-dire que les variables globales ne peuvent pas être modifiées via sa copie. Auparavant, le tableau $GLOBALS était exclu du comportement usuel par-valeur des tableaux PHP et les variables globales pouvaient être modifiées via sa copie.

>     <?php

>     // Avant PHP 8.1.0
>     $a = 1;

>     $globals = $GLOBALS; // Copie par valeur en apparence
>     $globals['a'] = 2;
>     var_dump($a); // int(2)

>     // À partir de PHP 8.1.0
>     // ceci ne modifie plus $a. Le comportement précédent violait la sémantique par valeur.
>     $globals = $GLOBALS;
>     $globals['a'] = 1;

>     // Pour restaurer le comportement précédent, itérer sa copie et réassigner chaque propriété à $GLOBALS.
>     foreach ($globals as $key => $value) {
>         $GLOBALS[$key] = $value;
>     }

>     ?>

# $_SERVER

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SERVER — Variables de serveur et d'exécution

### Description

$_SERVER est un tableau contenant des informations telles que les en-têtes, les chemins et les emplacements de script. Les entrées de cet array sont créées par le serveur web, il n'y a donc aucune garantie que chaque serveur web fournira chacune de ces informations ; les serveurs peuvent en omettre certaines ou en fournir d'autres qui ne sont pas répertoriées ici. Cependant, la plupart de ces variables sont prises en compte dans la spécification » CGI/1.1 et sont susceptibles d'être définies.

> Note: Lorsque PHP est exécuté en ligne de commande, la plupart de ces entrées ne seront pas disponibles ou n'auront aucun sens.

En plus des éléments énumérés ci-dessous, PHP créera des éléments supplémentaires avec des valeurs provenant des en-têtes de requête. Ces entrées seront nommées `HTTP_` suivi du nom de l'en-tête, en majuscules et avec des traits de soulignement au lieu des tirets. Par exemple, l'en-tête `Accept-Language` sera disponible sous la forme `$_SERVER['HTTP_ACCEPT_LANGUAGE']`.

### Indices

'PHP_SELF'
  Le nom du fichier du script en cours d'exécution, par rapport à la racine web. Par exemple, $_SERVER['PHP_SELF'] dans le script situé à l'adresse http://example.com/foo/bar.php sera /foo/bar.php. La constante __FILE__ contient le chemin complet ainsi que le nom du fichier (c.-à-d. inclus) courant. Si PHP fonctionne en ligne de commande, cette variable contient le nom du script.
'argv'
  Tableau des arguments passés au script. Lorsque le script est appelé en ligne de commande, cela donne accès aux arguments, comme en langage C. Lorsque le script est appelé avec la méthode GET, ce tableau contiendra la chaîne de requête.
'argc'
  Contient le nombre de paramètres de la ligne de commande passés au script (si le script fonctionne en ligne de commande).
'GATEWAY_INTERFACE'
  Numéro de révision de l'interface CGI du serveur. Par exemple `'CGI/1.1'`.
'SERVER_ADDR'
  L'adresse IP du serveur sous lequel le script courant est en train d'être exécuté.
'SERVER_NAME'
  Le nom du serveur hôte qui exécute le script courant. Si le script est exécuté sur un hôte virtuel, ce sera la valeur définie pour cet hôte virtuel.

  > Note: Sous Apache 2, `UseCanonicalName = On` et `ServerName` doivent être définis. Sinon, cette valeur reflète le nom d'hôte fourni par le client, qui peut être falsifié. Il n'est pas sûr de se fier à cette valeur dans des contextes dépendants de la sécurité.

'SERVER_SOFTWARE'
  Chaîne d'identification du serveur, qui est donnée dans les en-têtes lors de la réponse aux requêtes.
'SERVER_PROTOCOL'
  Nom et révision du protocole de communication ; par exemple `HTTP/1.0`;
'REQUEST_METHOD'
  Méthode de requête utilisée pour accéder à la page ; par exemple `GET`, `HEAD`, `POST`, `PUT`.

  > Note:

  > Le script PHP se termine après avoir envoyé les en-têtes (c'est-à-dire après avoir produit n'importe quelle sortie sans bufferisation de sortie) si la méthode de la requête était `HEAD`.

'REQUEST_TIME'
  Le timestamp du moment où PHP a commencé à traiter la requête.
'REQUEST_TIME_FLOAT'
  Le timestamp du moment où PHP a commencé à traiter la requête, avec une précision à la microseconde.
'QUERY_STRING'
  La chaîne de requête, si elle existe, qui est utilisée pour accéder à la page.
'DOCUMENT_ROOT'
  La racine sous laquelle le script courant est exécuté, comme défini dans la configuration du serveur.
'HTTPS'
  Défini à une valeur non-vide si le script a été appelé via le protocole HTTPS.
'REMOTE_ADDR'
  L'adresse IP du client qui demande la page courante.
'REMOTE_HOST'
  Le nom de l'hôte à partir duquel l'utilisateur consulte la page courante. La résolution DNS inverse est basée sur la valeur de REMOTE_ADDR.

  > Note: Le serveur Web doit être configuré pour créer cette variable. Par exemple, dans Apache, `HostnameLookups On` doit être défini à l'intérieur de httpd.conf pour qu'il existe. Voir aussi gethostbyaddr().

'REMOTE_PORT'
  Le port utilisé par la machine cliente pour communiquer avec le serveur web.
'REMOTE_USER'
  L'utilisateur authentifié.
'REDIRECT_REMOTE_USER'
  L'utilisateur authentifié si la requête a été redirigée en interne.
'SCRIPT_FILENAME'

  Le chemin absolu vers le fichier contenant le script en cours d'exécution.

  > Note:

  > Si un script est exécuté avec le CLI, avec un chemin relatif, comme file.php ou ../file.php, $_SERVER['SCRIPT_FILENAME'] contiendra le chemin relatif spécifié par l'utilisateur.

'SERVER_ADMIN'
  La valeur donnée à la directive SERVER_ADMIN (pour Apache), dans le fichier de configuration du serveur web. Si le script est exécuté sur un hôte virtuel, ce sera la valeur définie pour cet hôte virtuel.
'SERVER_PORT'
  Le port de la machine serveur utilisé pour les communications. Par défaut, c'est `'80'`. En utilisant SSL, par exemple, il sera remplacé par le numéro de port HTTP sécurisé.

  > Note: Sous Apache 2, `UseCanonicalName = On`, ainsi que `UseCanonicalPhysicalPort = On` doivent être définis pour obtenir le port physique réel, sinon cette valeur peut être falsifiée et elle peut ou non retourner la valeur du port physique. Il n'est pas sûr de se fier à cette valeur dans des contextes dépendants de la sécurité.

'SERVER_SIGNATURE'
  Chaîne contenant le numéro de version du serveur et le nom d'hôte virtuel, qui sont ajoutés aux pages générées par le serveur, si cette option est activée.
'PATH_TRANSLATED'
  Chemin dans le système de fichiers (pas le document-root) jusqu'au script courant, une fois que le serveur a fait une traduction chemin virtuel -> réel.

  > Note: Les utilisateurs d'Apache 2 devraient utiliser `AcceptPathInfo = On` dans leur httpd.conf pour définir PATH_INFO.

'SCRIPT_NAME'
  Contient le nom du script courant. Cela sert lorsque les pages doivent s'appeler elles-mêmes. La constante __FILE__ contient le chemin complet ainsi que le nom du fichier (c.-à-d. inclus) courant.
'REQUEST_URI'
  L'URI qui a été fourni pour accéder à cette page. Par exemple : '`/index.html`'.
'PHP_AUTH_DIGEST'
  Lors de l'utilisation de l'authentification HTTP Digest, cette variable est définie dans l'en-tête `"Authorization"` envoyé par le client (qui doit donc être utilisé pour réaliser la validation appropriée).
'PHP_AUTH_USER'
  Lors de l'utilisation de l'authentification HTTP, cette variable est définie au nom d'utilisateur fourni par le client.
'PHP_AUTH_PW'
  Lors de l'utilisation de l'authentification HTTP, cette variable est définie au mot de passe fourni par l'utilisateur.
'AUTH_TYPE'
  Lors de l'utilisation de l'authentification HTTP, cette variable est définie au type d'identification.
'PATH_INFO'
  Contient les informations sur le nom du chemin fourni par le client concernant le nom du fichier exécutant le script courant, sans la chaîne relative à la requête si elle existe. Actuellement, si le script courant est exécuté via l'URI http://www.example.com/php/path_info.php/some/stuff?foo=bar, alors la variable $_SERVER['PATH_INFO'] contiendra `/some/stuff`.
'ORIG_PATH_INFO'
  Version originale de 'PATH_INFO' avant d'être analysée par PHP.

### Exemples

Exemple #1 Exemple avec $_SERVER

    <?php
    echo $_SERVER['SERVER_NAME'];
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    www.example.com

### Notes

> Note: Ceci est une 'superglobale', ou variable globale automatique. Cela signifie simplement que cette variable est disponible dans tous les contextes du script. Il n'est pas nécessaire de faire global $variable; pour y accéder dans les fonctions ou les méthodes.

### Voir aussi

- L'extension sur les filtres

# $_GET

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_GET — Variables de chaîne de requête

### Description

Un tableau associatif des valeurs passées au script courant via les paramètres d'URL (aussi connu sous le nom de "query string"). Il est à noter que ce tableau est rempli chaque fois qu'une query string est présente, peu importe la méthode de requête HTTP.

### Exemples

Exemple #1 Exemple avec $_GET

    <?php
    echo 'Bonjour ' . htmlspecialchars($_GET["name"]) . '!';
    ?>

En supposant que l'utilisateur a entré `http://example.com/?name=Yannick`.

Résultat de l'exemple ci-dessus est similaire à :

    Bonjour Yannick!

### Notes

> Note: Ceci est une 'superglobale', ou variable globale automatique. Cela signifie simplement que cette variable est disponible dans tous les contextes du script. Il n'est pas nécessaire de faire global $variable; pour y accéder dans les fonctions ou les méthodes.

> Note:

> Les variables $_GET sont passées automatiquement à travers urldecode().

### Voir aussi

- Gestion des variables externes
- L'extension sur les filtres

# $_POST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_POST — Données de formulaire depuis des requêtes HTTP POST

### Description

Un tableau associatif des valeurs passées au script courant via le protocole HTTP et la méthode POST lors de l'utilisation de la chaîne `application/x-www-form-urlencoded` ou `multipart/form-data` comme en-tête HTTP Content-Type dans la requête.

### Exemples

Exemple #1 Exemple avec $_POST

    <?php
    echo 'Bonjour ' . htmlspecialchars($_POST["name"]) . '!';
    ?>

En supposant que l'utilisateur a envoyé une requête POST avec `name=Yannick` dans le corps.

Résultat de l'exemple ci-dessus est similaire à :

    Bonjour Yannick !

### Notes

> Note: Ceci est une 'superglobale', ou variable globale automatique. Cela signifie simplement que cette variable est disponible dans tous les contextes du script. Il n'est pas nécessaire de faire global $variable; pour y accéder dans les fonctions ou les méthodes.

> Note: Pour lire les données POST envoyées avec d'autres types de contenu (par exemple `application/json` ou `application/xml`), php://input doit être utilisé. Contrairement à $_POST, qui ne fonctionne qu'avec `application/x-www-form-urlencoded` et `multipart/form-data`, php://input fournit un accès direct aux données brutes du corps de la requête.

### Voir aussi

- Gestion des variables externes
- L'extension sur les filtres

# $_FILES

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_FILES — Variable de téléversement de fichier via HTTP

### Description

Un array associatif des éléments téléversés au script courant via le protocole HTTP et la méthode POST. La structure de ce tableau est décrite dans la section chargements de fichiers par méthode POST.

### Notes

> Note: Ceci est une 'superglobale', ou variable globale automatique. Cela signifie simplement que cette variable est disponible dans tous les contextes du script. Il n'est pas nécessaire de faire global $variable; pour y accéder dans les fonctions ou les méthodes.

### Voir aussi

- move_uploaded_file() - Déplace un fichier téléchargé
- Gestion des téléchargements de fichiers

# $_REQUEST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_REQUEST — Variables de requête HTTP

### Description

Un tableau associatif qui contient par défaut le contenu des variables $_GET, $_POST et $_COOKIE.

### Notes

> Note: Ceci est une 'superglobale', ou variable globale automatique. Cela signifie simplement que cette variable est disponible dans tous les contextes du script. Il n'est pas nécessaire de faire global $variable; pour y accéder dans les fonctions ou les méthodes.

> Note:

> En ligne de commande, cette variable n'inclut pas les variables argv et argc : elles sont stockées dans le tableau $_SERVER.

> Note:

> Les variables contenues dans $_REQUEST sont fournies au script via les mécanismes d'entrée GET, POST, et COOKIE et donc, peuvent être modifiées par l'utilisateur final ; il ne faut donc pas faire confiance à leur contenu. La présence ainsi que l'ordre de ces variables dans ce tableau sont définis suivant les directives de configuration PHP request_order, et variables_order.

### Voir aussi

- Gestion des variables externes
- L'extension sur les filtres

# $_SESSION

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SESSION — Variables de session

### Description

Un tableau associatif des valeurs stockées dans les sessions, et accessible au script courant. Voir l'extension Sessions pour plus de détails sur comment est utilisée cette variable.

### Notes

> Note: Ceci est une 'superglobale', ou variable globale automatique. Cela signifie simplement que cette variable est disponible dans tous les contextes du script. Il n'est pas nécessaire de faire global $variable; pour y accéder dans les fonctions ou les méthodes.

### Voir aussi

- session_start() - Démarre une nouvelle session ou reprend une session existante

# $_ENV

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_ENV — Variables d'environnement

### Description

Un tableau associatif de variables passé au script courant, via la méthode d'environnement.

Cette variable est importée dans l'espace de noms global de PHP, depuis l'environnement dans lequel l'exécutable PHP fonctionne. De nombreuses valeurs sont fournies par le shell qui exécute PHP, et différents systèmes pouvant disposer de différents shell, même un début de liste serait ici impossible. Se reporter à la documentation du shell utilisé pour connaître une liste de variables pré-définies.

Les autres variables d'environnement incluent les variables CGI, placées ici, indépendamment du fait que PHP fonctionne en tant que CGI ou bien que module du serveur.

### Exemples

Exemple #1 Exemple avec $_ENV

    <?php
    echo 'Mon nom d\'utilisateur est ' .$_ENV["USER"] . '!';
    ?>

En supposant que `"yannick"` exécute ce script

Résultat de l'exemple ci-dessus est similaire à :

    Mon nom d'utilisateur est yannick !

### Notes

> Note: Ceci est une 'superglobale', ou variable globale automatique. Cela signifie simplement que cette variable est disponible dans tous les contextes du script. Il n'est pas nécessaire de faire global $variable; pour y accéder dans les fonctions ou les méthodes.

### Voir aussi

- getenv() - Retourne la valeur d'une seule ou toutes les variables d'environnement
- L'extension sur les filtres

# $_COOKIE

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_COOKIE — Cookies HTTP

### Description

Un tableau associatif de variables, passé au script courant, via des cookies HTTP.

### Exemples

Exemple #1 Exemple avec $_COOKIE

    <?php
    echo 'Bonjour ' . htmlspecialchars($_COOKIE["name"]) . '!';
    ?>

En supposant que le cookie "name" a été défini précédemment

Résultat de l'exemple ci-dessus est similaire à :

    Bonjour Yannick !

### Notes

> Note: Ceci est une 'superglobale', ou variable globale automatique. Cela signifie simplement que cette variable est disponible dans tous les contextes du script. Il n'est pas nécessaire de faire global $variable; pour y accéder dans les fonctions ou les méthodes.

### Voir aussi

- setcookie() - Envoie un cookie
- Gestion des variables externes
- L'extension sur les filtres

# $php_errormsg

(PHP 4, PHP 5, PHP 7)

$php_errormsg — Le dernier message d'erreur

Avertissement

Cette fonctionnalité est OBSOLÈTE à partir de PHP 7.2.0, et SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonctionnalité est fortement déconseillé.

Utiliser error_get_last() à la place.

### Description

$php_errormsg est une variable qui contient le texte de la dernière erreur générée par PHP. Cette variable sera uniquement accessible dans le même contexte d'exécution que celui de la ligne qui a généré l'erreur, et uniquement si la directive de configuration track_errors est activée (elle est désactivée par défaut).

Avertissement

Si un gestionnaire d'erreurs défini par l'utilisateur est actif (set_error_handler()), $php_errormsg ne sera défini que si le gestionnaire d'erreur retourne `false`.

### Historique

Version | Description
--- | ---
8.0.0 | La directive track_errors qui rendait $php_errormsg disponible a été supprimée.
7.2.0 | La directive track_errors qui rendait $php_errormsg disponible a été rendue obsolète.

### Exemples

Exemple #1 Exemple avec $php_errormsg

    <?php
    @strpos();
    echo $php_errormsg;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Wrong parameter count for strpos()

### Voir aussi

- error_get_last() - Récupère la dernière erreur survenue

# $http_response_header

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

$http_response_header — En-têtes de réponse HTTP

Avertissement

Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonctionnalité est fortement déconseillé.

Utiliser http_get_last_response_headers() plutôt.

### Description

Le tableau $http_response_header est similaire à la fonction get_headers(). Lors de l'utilisation de l'enveloppe HTTP, $http_response_header sera rempli avec les en-têtes de réponses HTTP. $http_response_header sera créé avec une portée locale.

### Exemples

Exemple #1 Exemple avec $http_response_header

    <?php
    function get_contents() {
      file_get_contents("http://example.com");
      var_dump($http_response_header); // La variable est remplie dans la portée locale
    }
    get_contents();
    var_dump($http_response_header); // Un appel à get_contents() ne remplit pas la variable en dehors de la portée de la fonction
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(9) {
      [0]=>
      string(15) "HTTP/1.1 200 OK"
      [1]=>
      string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
      [2]=>
      string(29) "Server: Apache/2.2.3 (CentOS)"
      [3]=>
      string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
      [4]=>
      string(27) "ETag: "280100-1b6-80bfd280""
      [5]=>
      string(20) "Accept-Ranges: bytes"
      [6]=>
      string(19) "Content-Length: 438"
      [7]=>
      string(17) "Connection: close"
      [8]=>
      string(38) "Content-Type: text/html; charset=UTF-8"
    }

    Warning: Undefined variable $http_response_header
    NULL

### Voir aussi

- http_get_last_response_headers() - Récupère les derniers en-têtes de réponse HTTP
- http_clear_last_response_headers() - Efface les en-têtes de réponse HTTP stockés

# $argc

(PHP 4, PHP 5, PHP 7, PHP 8)

$argc — Le nombre d'arguments passés au script

### Description

Contient le nombre d'arguments passés au script courant lorsqu'il est exécuté depuis la ligne de commande.

> Note: Le nom du fichier contenant le script est toujours passé en tant qu'argument au script, ainsi la valeur minimale de $argc est `1`.

> Note: Cette variable n'est pas disponible lorsque register_argc_argv est désactivé.

### Exemples

Exemple #1 Exemple avec $argc

    <?php
    var_dump($argc);
    ?>

Lorsque l'on exécute l'exemple avec la commande : php script.php arg1 arg2 arg3

Résultat de l'exemple ci-dessus est similaire à :

    int(4)

### Notes

> Note:

> Également disponible dans $_SERVER['argc'].

### Voir aussi

- getopt() - Lit des options passées dans la ligne de commande
- $argv

# $argv

(PHP 4, PHP 5, PHP 7, PHP 8)

$argv — Tableau d'arguments passés au script

### Description

Contient un tableau de tous les arguments passés au script lorsqu'il est appelé depuis la ligne de commande.

> Note: Le premier argument $argv[0] est toujours le nom qui a été utilisé pour exécuter le script.

> Note: Cette variable n'est pas disponible lorsque register_argc_argv est désactivé.

Avertissement

Pour vérifier si un script est exécuté depuis la ligne de commande, il est recommandé d'utiliser php_sapi_name() plutôt que de vérifier si $argv ou $_SERVER['argv'] est défini.

### Exemples

Exemple #1 Exemple avec $argv

    <?php
    var_dump($argv);
    ?>

Lorsque l'on exécute l'exemple avec la commande : php script.php arg1 arg2 arg3

Résultat de l'exemple ci-dessus est similaire à :

    array(4) {
      [0]=>
      string(10) "script.php"
      [1]=>
      string(4) "arg1"
      [2]=>
      string(4) "arg2"
      [3]=>
      string(4) "arg3"
    }

### Notes

> Note:

> Également disponible dans $_SERVER['argv'].

### Voir aussi

- getopt() - Lit des options passées dans la ligne de commande
- $argc

## Sommaire

- Les Superglobales — Les variables internes qui sont toujours disponibles, quel que soit le contexte
- $GLOBALS — Référence toutes les variables disponibles dans un contexte global
- $_SERVER — Variables de serveur et d'exécution
- $_GET — Variables de chaîne de requête
- $_POST — Données de formulaire depuis des requêtes HTTP POST
- $_FILES — Variable de téléversement de fichier via HTTP
- $_REQUEST — Variables de requête HTTP
- $_SESSION — Variables de session
- $_ENV — Variables d'environnement
- $_COOKIE — Cookies HTTP
- $php_errormsg — Le dernier message d'erreur
- $http_response_header — En-têtes de réponse HTTP
- $argc — Le nombre d'arguments passés au script
- $argv — Tableau d'arguments passés au script

# Exceptions prédéfinies

## Sommaire

- Exception
- ErrorException
- ClosedGeneratorException
- Error
- ArgumentCountError
- ArithmeticError
- AssertionError
- DivisionByZeroError
- CompileError
- ParseError
- TypeError
- ValueError
- UnhandledMatchError
- FiberError
- RequestParseBodyException

Voir aussi les exceptions SPL.

# Exception

(PHP 5, PHP 7, PHP 8)

## Introduction

Exception est la classe de base pour toutes les exceptions utilisateur.

## Synopsis de la classe

class Exception implements Throwable {
/* Propriétés */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Propriétés

message

  Le message de l'exception

code

  Le code de l'exception

file

  Le nom du fichier dans lequel l'exception a été créée

line

  La ligne où l'exception a été créée

previous

  L'exception lancée précédemment

string

  La représentation sous forme de chaîne de la trace de la pile

trace

  La trace de la pile sous forme de tableau

# Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__construct — Construit l'exception

### Description

public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Construit l'exception.

### Liste de paramètres

`message`

  Le message de l'exception à lancer.

`code`

  Le code de l'exception.

`previous`

  L'exception précédente, utilisée pour le chaînage d'exception.

> Note: L'appel du constructeur de la classe Exception à partir d'une sous-classe ignore les arguments par défaut, si les propriétés $code et $message sont déjà définies.

### Notes

> Note:

> Le `message` n'est PAS sûr en binaire.

# Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessage — Récupère le message de l'exception

### Description

final public function Exception::getMessage(): string

Retourne le message de l'exception.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le message de l'exception, sous la forme d'une chaîne de caractères.

### Exemples

Exemple #1 Exemple avec Exception::getMessage()

    <?php
    try {
        throw new Exception("Un message d'erreur");
    } catch(Exception $e) {
        echo $e->getMessage();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Un message d'erreur

### Voir aussi

- Throwable::getMessage() - Récupère le message

# Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPrevious — Retourne le Throwable précédent

### Description

final public function Exception::getPrevious(): ?Throwable

Retourne le Throwable précédent (le troisième paramètre de la méthode Exception::__construct()).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le Throwable précédent si disponible, `null` sinon.

### Exemples

Exemple #1 Exemple avec Exception::getPrevious()

Une boucle, on affiche et on capture les exceptions.

    <?php
    class MyCustomException extends Exception {}

    function doStuff() {
        try {
            throw new InvalidArgumentException("Vous avez fait une erreur !", 112);
        } catch(Exception $e) {
            throw new MyCustomException("Un problème est survenu", 911, $e);
        }
    }

    try {
        doStuff();
    } catch(Exception $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    /home/bjori/ex.php:8 Un problème est survenu (911) [MyCustomException]
    /home/bjori/ex.php:6 Vous avez fait une erreur ! (112) [InvalidArgumentException]

### Voir aussi

- Throwable::getPrevious() - Retourne le Throwable précédent

# Exception::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCode — Récupère le code de l'exception

### Description

final public function Exception::getCode(): int

Retourne le code de l'exception.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code de l'exception, sous la forme d'un entier dans la classe Exception mais aussi sous la forme d'un autre type de données dans les classes héritant de Exception (par exemple, sous la forme d'une chaîne de caractères dans la classe PDOException).

### Exemples

Exemple #1 Exemple avec Exception::getCode()

    <?php
    try {
        throw new Exception("Un message d'erreur", 30);
    } catch(Exception $e) {
        echo "Le code de l'exception est : " . $e->getCode();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Le code de l'exception est : 30

### Voir aussi

- Throwable::getCode() - Récupère le code de l'exception

# Exception::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFile — Récupère le fichier dans lequel l'exception a été créée

### Description

final public function Exception::getFile(): string

Récupère le nom du fichier dans lequel l'exception a été créée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nom du fichier dans lequel l'exception a été créée.

### Exemples

Exemple #1 Exemple avec Exception::getFile()

    <?php
    try {
        throw new Exception;
    } catch(Exception $e) {
        echo $e->getFile();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    /home/bjori/tmp/ex.php

### Voir aussi

- Throwable::getFile() - Récupère le fichier où l'objet a été créé

# Exception::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLine — Récupère la ligne dans laquelle l'exception a été créée

### Description

final public function Exception::getLine(): int

Récupère le numéro de la ligne où l'exception a été créée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le numéro de la ligne où l'exception a été créée.

### Exemples

Exemple #1 Exemple avec Exception::getLine()

    <?php
    try {
        throw new Exception("Un message d'erreur");
    } catch(Exception $e) {
        echo "L'exception a été créée depuis la ligne : " . $e->getLine();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    L'exception a été créée depuis la ligne : 3

### Voir aussi

- Throwable::getLine() - Récupère la ligne où l'objet a été instancié

# Exception::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTrace — Récupère la trace de la pile

### Description

final public function Exception::getTrace(): array

Retourne la trace de la pile de l'exception.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la trace de la pile de l'exception sous la forme d'un tableau.

### Exemples

Exemple #1 Exemple avec Exception::getTrace()

    <?php
    function test() {
     throw new Exception;
    }

    try {
     test();
    } catch(Exception $e) {
     var_dump($e->getTrace());
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### Voir aussi

- Throwable::getTrace() - Récupère la trace d'appels

# Exception::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsString — Récupère la trace de la pile en tant que chaîne

### Description

final public function Exception::getTraceAsString(): string

Retourne la trace de la pile de l'exception, sous la forme d'une chaîne de caractères.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la trace de la pile de l'exception, sous la forme d'une chaîne de caractères.

### Exemples

Exemple #1 Exemple avec Exception::getTraceAsString()

    <?php
    function test() {
        throw new Exception;
    }

    try {
        test();
    } catch(Exception $e) {
        echo $e->getTraceAsString();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### Voir aussi

- Throwable::getTraceAsString() - Récupère la trace d'appels en tant que chaîne de caractères

# Exception::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toString — Représente l'exception sous la forme d'une chaîne

### Description

public function Exception::__toString(): string

Retourne une représentation de l'exception sous forme d'une chaîne de caractères.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation de l'exception, sous la forme d'une chaîne de caractères.

### Exemples

Exemple #1 Exemple avec Exception::__toString()

    <?php
    try {
        throw new Exception("Message d'erreur");
    } catch(Exception $e) {
        echo $e;
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    exception 'Exception' with message 'Message d'erreur' in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Voir aussi

- Throwable::__toString() - Récupère la représentation sous forme de chaîne de caractères de l'objet lancé

# Exception::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__clone — Clone l'exception

### Description

private function Exception::__clone(): void

Les Exceptions ne peuvent pas être clonées, et tenter de le faire va lever une exception Error.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Les exceptions ne sont pas clonables.

### Historique

Version | Description
--- | ---
8.1.0 | Exception::__clone() n'est plus final.

## Sommaire

- Exception::__construct — Construit l'exception
- Exception::getMessage — Récupère le message de l'exception
- Exception::getPrevious — Retourne le Throwable précédent
- Exception::getCode — Récupère le code de l'exception
- Exception::getFile — Récupère le fichier dans lequel l'exception a été créée
- Exception::getLine — Récupère la ligne dans laquelle l'exception a été créée
- Exception::getTrace — Récupère la trace de la pile
- Exception::getTraceAsString — Récupère la trace de la pile en tant que chaîne
- Exception::__toString — Représente l'exception sous la forme d'une chaîne
- Exception::__clone — Clone l'exception

# ErrorException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introduction

Une exception pour les erreurs.

## Synopsis de la classe

class ErrorException extends Exception {
/* Propriétés */
protected int $severity = E_ERROR;
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
public function __construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)
final public function getSeverity(): int
/* Méthodes héritées */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriétés

severity

  La sévérité de l'exception

## Exemples

Exemple #1 Utilisation de set_error_handler() pour changer tous les messages d'erreurs en ErrorException

    <?php

    set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline) {
        if (!(error_reporting() & $errno)) {
            // Ce code d'erreur n'est pas inclus dans error_reporting.
            return;
        }

        if ($errno === E_DEPRECATED || $errno === E_USER_DEPRECATED) {
            // Ne pas lancer d'exception pour les avertissements d'obsolescence, car de nouvelles ou inattendues
            // obsolescences pourraient casser l'application.
            return;
        }

        throw new \ErrorException($errstr, 0, $errno, $errfile, $errline);
    });

    // Désérialiser des données corrompues déclenche un avertissement qui sera converti en
    // ErrorException par le gestionnaire d'erreurs.
    unserialize('broken data');

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Fatal error: Uncaught ErrorException: unserialize(): Error at offset 0 of 11 bytes in test.php:16
    Stack trace:
    #0 [internal function]: {closure}(2, 'unserialize(): ...', 'test.php', 16)
    #1 test.php(16): unserialize('broken data')
    #2 {main}
      thrown in test.php on line 16

# ErrorException::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::__construct — Construit l'exception

### Description

public function ErrorException::__construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)

Construit l'exception.

### Liste de paramètres

`message`

  Le message de l'exception à lancer.

`code`

  Le code de l'exception.

`severity`

  Le degré de sévérité de l'exception.

  > Note:

  > Bien que la gravité puisse être n'importe quelle valeur entier, il est prévu que les constantes d'erreur soient utilisées.

`filename`

  Le fichier depuis lequel l'exception est lancée.

`line`

  Le numéro de ligne depuis laquelle l'exception est lancée.

`previous`

  La précédente exception utilisée pour le chaînage des exceptions.

### Historique

Version | Description
--- | ---
8.0.0 | `filename` et `line` sont désormais nullables. Auparavant, leur valeur par défaut était `__FILE__` et `__LINE__`, respectivement.

# ErrorException::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverity — Récupère la sévérité de l'exception

### Description

final public function ErrorException::getSeverity(): int

Retourne la sévérité de l'exception.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le degré de sévérité de l'exception.

### Exemples

Exemple #1 Exemple avec ErrorException::getSeverity()

    <?php
    try {
        throw new ErrorException("Exception message", 0, E_USER_ERROR);
    } catch(ErrorException $e) {
        echo "La sévérité de l'exception est : " . $e->getSeverity();
        var_dump($e->getSeverity() === E_USER_ERROR);
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    La sévérité de l'exception est : 256
    bool(true)

## Sommaire

- ErrorException::__construct — Construit l'exception
- ErrorException::getSeverity — Récupère la sévérité de l'exception

# La classe ClosedGeneratorException

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

Une ClosedGeneratorException est lancée lorsqu'on essaie de récupérer une valeur d'un Generator fermé.

## Synopsis de la classe

class ClosedGeneratorException extends Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Error

(PHP 7, PHP 8)

## Introduction

Error est la classe de base pour toutes les erreurs internes de PHP.

## Synopsis de la classe

class Error implements Throwable {
/* Propriétés */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Propriétés

message

  Le message d'erreur

code

  Le code d'erreur

file

  Le nom de fichier où l'erreur s'est produite

line

  La ligne où l'erreur s'est produite

previous

  L'exception lancée précédemment

string

  La représentation sous forme de chaîne de la trace de la pile

trace

  La trace de la pile sous forme de tableau

# Error::__construct

(PHP 7, PHP 8)

Error::__construct — Constructeur de l'objet Error

### Description

public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Construit l'erreur.

### Liste de paramètres

`message`

  Le message d'erreur.

`code`

  Le code d'erreur.

`previous`

  Le précédent throwable utilisé pour l'enchaînement d'exceptions.

### Notes

> Note:

> Le `message` n'est PAS sûr en binaire.

# Error::getMessage

(PHP 7, PHP 8)

Error::getMessage — Récupère le message d'erreur

### Description

final public function Error::getMessage(): string

Retourne le message d'erreur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le message d'erreur en tant que chaîne de caractères.

### Exemples

Exemple #1 Exemple de Error::getMessage()

    <?php
    try {
        throw new Error("Un message d'erreur");
    } catch(Error $e) {
        echo $e->getMessage();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Un message d'erreur

### Voir aussi

- Throwable::getMessage() - Récupère le message

# Error::getPrevious

(PHP 7, PHP 8)

Error::getPrevious — Retourne le Throwable précédent

### Description

final public function Error::getPrevious(): ?Throwable

Retourne le Throwable précédent (le troisième paramètre de Error::__construct()).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le Throwable précédent si disponible ou `null` sinon.

### Exemples

Exemple #1 Exemple de Error::getPrevious()

Boucler sur, et afficher, une trace d'erreur

    <?php
    class MyCustomError extends Error {}

    function doStuff() {
        try {
            throw new InvalidArgumentError("You are doing it wrong!", 112);
        } catch(Error $e) {
            throw new MyCustomError("Something happened", 911, $e);
        }
    }

    try {
        doStuff();
    } catch(Error $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    /home/bjori/ex.php:8 Something happened (911) [MyCustomError]
    /home/bjori/ex.php:6 You are doing it wrong! (112) [InvalidArgumentError]

### Voir aussi

- Throwable::getPrevious() - Retourne le Throwable précédent

# Error::getCode

(PHP 7, PHP 8)

Error::getCode — Récupère le code d'erreur

### Description

final public function Error::getCode(): int

Retourne le code d'erreur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code d'erreur en tant que int

### Exemples

Exemple #1 Exemple de Error::getCode()

    <?php
    try {
        throw new Error("Un message d'erreur", 30);
    } catch(Error $e) {
        echo "Le code d'erreur est : " . $e->getCode();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Le code d'erreur est : 30

### Voir aussi

- Throwable::getCode() - Récupère le code de l'exception

# Error::getFile

(PHP 7, PHP 8)

Error::getFile — Récupère le fichier où l'erreur s'est produite

### Description

final public function Error::getFile(): string

Récupère le fichier où l'erreur s'est produite.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nom de fichier où l'erreur s'est produite.

### Exemples

Exemple #1 Exemple de Error::getFile()

    <?php
    try {
        throw new Error;
    } catch(Error $e) {
        echo $e->getFile();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    /home/bjori/tmp/ex.php

### Voir aussi

- Throwable::getFile() - Récupère le fichier où l'objet a été créé

# Error::getLine

(PHP 7, PHP 8)

Error::getLine — Récupère le numéro de ligne où l'erreur s'est produite

### Description

final public function Error::getLine(): int

Récupère le numéro de ligne où l'erreur s'est produite.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le numéro de ligne où l'erreur s'est produite.

### Exemples

Exemple #1 Exemple de Error::getLine()

    <?php
    try {
        throw new Error("Un message d'erreur");
    } catch(Error $e) {
        echo "L'erreur a été créée à la ligne : " . $e->getLine();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    L'erreur a été créée à la ligne : 3

### Voir aussi

- Throwable::getLine() - Récupère la ligne où l'objet a été instancié

# Error::getTrace

(PHP 7, PHP 8)

Error::getTrace — Récupère la trace d'appels

### Description

final public function Error::getTrace(): array

Retourne la trace d'appels.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la trace d'appels en tant que tableau.

### Exemples

Exemple #1 Exemple de Error::getTrace()

    <?php
    function test() {
     throw new Error;
    }

    try {
     test();
    } catch(Error $e) {
     var_dump($e->getTrace());
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### Voir aussi

- Throwable::getTrace() - Récupère la trace d'appels

# Error::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsString — Récupère la trace d'appels en tant que chaîne de caractères

### Description

final public function Error::getTraceAsString(): string

Retourne la trace d'appels en tant que chaîne de caractères.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la trace d'appels en tant que chaîne de caractères.

### Exemples

Exemple #1 Exemple de Error::getTraceAsString()

    <?php
    function test() {
        throw new Error;
    }

    try {
        test();
    } catch(Error $e) {
        echo $e->getTraceAsString();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### Voir aussi

- Throwable::getTraceAsString() - Récupère la trace d'appels en tant que chaîne de caractères

# Error::__toString

(PHP 7, PHP 8)

Error::__toString — Représentation sous forme de chaîne de caractères de l'erreur

### Description

public function Error::__toString(): string

Retourne la représentation sous forme de chaîne de caractères de l'erreur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de caractères de l'erreur.

### Exemples

Exemple #1 Exemple de Error::__toString()

    <?php
    try {
        throw new Error("Some error message");
    } catch(Error $e) {
        echo $e;
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Error: Some error message in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Voir aussi

- Throwable::__toString() - Récupère la représentation sous forme de chaîne de caractères de l'objet lancé

# Error::__clone

(PHP 7, PHP 8)

Error::__clone — Cloner l'erreur

### Description

private function Error::__clone(): void

Une erreur ne peut pas être clonée, cette méthode produit donc une erreur fatale.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Les erreurs ne sont pas clonables.

### Historique

Version | Description
--- | ---
8.1.0 | Error::__clone() n'est plus final.

## Sommaire

- Error::__construct — Constructeur de l'objet Error
- Error::getMessage — Récupère le message d'erreur
- Error::getPrevious — Retourne le Throwable précédent
- Error::getCode — Récupère le code d'erreur
- Error::getFile — Récupère le fichier où l'erreur s'est produite
- Error::getLine — Récupère le numéro de ligne où l'erreur s'est produite
- Error::getTrace — Récupère la trace d'appels
- Error::getTraceAsString — Récupère la trace d'appels en tant que chaîne de caractères
- Error::__toString — Représentation sous forme de chaîne de caractères de l'erreur
- Error::__clone — Cloner l'erreur

# ArgumentCountError

(PHP 7 >= PHP 7.1.0, PHP 8)

## Introduction

ArgumentCountError est lancée quand trop peu d'arguments sont passés à une fonction ou méthode définie par l'utilisateur.

Cette erreur est aussi lancée quand trop d'arguments sont fournis à une fonction interne non variadique.

## Synopsis de la classe

class ArgumentCountError extends TypeError {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# ArithmeticError

(PHP 7, PHP 8)

## Introduction

ArithmeticError est lancée quand une erreur se produit lors d'une opération mathématique. Ces erreurs incluent les tentatives de réaliser un décalage de bits d'un montant négatif, n'importe quel appel à intdiv() qui donnerait lieu à une valeur en dehors des bornes possibles d'un entier.

## Synopsis de la classe

class ArithmeticError extends Error {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# AssertionError

(PHP 7, PHP 8)

## Introduction

AssertionError est lancée quand une assertion faite avec assert() échoue.

## Synopsis de la classe

class AssertionError extends Error {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# DivisionByZeroError

(PHP 7, PHP 8)

## Introduction

DivisionByZeroError est lancée quand un nombre essaye d'être divisé par zéro.

## Synopsis de la classe

class DivisionByZeroError extends ArithmeticError {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# CompileError

(PHP 7 > 7.3.0, PHP 8)

## Introduction

CompileError est lancée pour certaines erreurs de compilation qui, antérieurement, émettaient une erreur fatale.

## Synopsis de la classe

class CompileError extends Error {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# ParseError

(PHP 7, PHP 8)

## Introduction

ParseError est lancée quand une erreur se produit lors de l'analyse de code PHP, comme quand eval() est appelé.

> Note: ParseError étend CompileError à partir de PHP 7.3.0. Antérieurement, elle étendait Error.

## Synopsis de la classe

class ParseError extends CompileError {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# TypeError

(PHP 7, PHP 8)

## Introduction

Une TypeError peut être lancée quand :

- La valeur qui est définie pour une propriété de classe ne correspond pas au type déclaré de la propriété correspondante.
- Le type de l'argument qui est passé à la fonction ne correspond pas à la déclaration du type du paramètre correspondant.
- Une valeur qui est retournée par une fonction ne correspond pas au type de retour déclaré par la fonction.

## Synopsis de la classe

class TypeError extends Error {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Historique

Version | Description
--- | ---
7.1.0 | En mode strict, passer un nombre incorrect d'arguments à une fonction interne de PHP ne lance plus une TypeError générique. À la place, une ArgumentCountError plus spécifique, qui étend TypeError, est levée.

# ValueError

(PHP 8)

## Introduction

Une ValueError est lancée lorsque le type d'un argument est correct mais que sa valeur est incorrecte. Par exemple, si l'on passe un entier négatif alors que la fonction attend un entier positif, ou si l'on passe une chaîne ou un tableau vide alors que la fonction s'attend à ce qu'il ne soit pas vide.

## Synopsis de la classe

class ValueError extends Error {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# UnhandledMatchError

(PHP 8)

## Introduction

Une UnhandledMatchError est lancée lorsque le sujet transmis à une expression match n'est traité par aucun bras de cette même expression.

## Synopsis de la classe

class UnhandledMatchError extends Error {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FiberError

(PHP 8 >= 8.1.0)

## Introduction

L'erreur FiberError est lancée lorsqu'une opération invalide est effectuée sur une fibre (Fiber).

## Synopsis de la classe

final class FiberError extends Error {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
public function __construct()
/* Méthodes héritées */
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FiberError::__construct

(PHP 8 >= 8.1.0)

FiberError::__construct — Constructeur pour empêcher l'instanciation directe

### Description

public function FiberError::__construct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Erreurs / Exceptions

Lance une exception Error lorsqu'elle est appelée.

## Sommaire

- FiberError::__construct — Constructeur pour empêcher l'instanciation directe

# RequestParseBodyException

(PHP 8 >= 8.4.0)

## Introduction

Une RequestParseBodyException est lancée dans request_parse_body() lorsque le corps de la requête est invalide, selon l'en-tête `Content-Type`.

## Synopsis de la classe

class RequestParseBodyException extends Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Interfaces et Classes Prédéfinies

## Sommaire

- Traversable
- Iterator
- IteratorAggregate
- InternalIterator
- Throwable
- Countable
- ArrayAccess
- Serializable
- Closure
- stdClass
- Generator
- Fiber
- WeakReference
- WeakMap
- Stringable
- UnitEnum
- BackedEnum
- SensitiveParameterValue
- __PHP_Incomplete_Class

Voir aussi les Interfaces SPL ainsi que les classes réservées.

# L'interface Traversable

(PHP 5, PHP 7, PHP 8)

## Introduction

Interface permettant de détecter si une classe peut être parcourue en utilisant `foreach`.

L'interface de base est abstraite et ne peut être implémentée seule. Elle doit être implémentée par soit IteratorAggregate, soit Iterator.

## Sommaire de l'Interface

interface Traversable {
}

Cette interface n'a pas de méthode ; son seul but est d'être l'interface de base pour toutes les classes permettant de parcourir des objets.

## Historique

Version | Description
--- | ---
7.4.0 | L'interface Traversable peut désormais être implémentée par des classes abstraites. Les classes étendant celles-ci doivent implémenter soit Iterator ou IteratorAggregate.

## Notes

> Note:

> Les classes internes qui implémentent cette interface peuvent être utilisées dans une structure `foreach` et n'ont pas besoin d'implémenter IteratorAggregate ou Iterator.

> Note:

> Avant PHP 7.4.0, cette interface interne au moteur ne pouvait pas être implémentée dans des scripts PHP. Soit IteratorAggregate ou Iterator doit être utilisé à la place.

# L'interface Iterator

(PHP 5, PHP 7, PHP 8)

## Introduction

Interface pour les itérateurs externes ou les objets capables d'être itérés eux-mêmes en interne.

## Sommaire de l'Interface

interface Iterator extends Traversable {
/* Méthodes */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

## Itérateurs prédéfinis

PHP fournit quelques itérateurs pour certaines tâches. Voir les itérateurs SPL pour une liste complète.

## Exemples

Exemple #1 Exemple simple

Cet exemple montre l'ordre d'appel des méthodes lors d'un appel à l'instruction `foreach` sur un itérateur.

    <?php
    class myIterator implements Iterator {
        private $position = 0;
        private $array = array(
            "premierelement",
            "secondelement",
            "dernierelement",
        );

        public function __construct() {
            $this->position = 0;
        }

        public function rewind(): void {
            var_dump(__METHOD__);
            $this->position = 0;
        }

        #[\ReturnTypeWillChange]
        public function current() {
            var_dump(__METHOD__);
            return $this->array[$this->position];
        }

        #[\ReturnTypeWillChange]
        public function key() {
            var_dump(__METHOD__);
            return $this->position;
        }

        public function next(): void {
            var_dump(__METHOD__);
            ++$this->position;
        }

        public function valid(): bool {
            var_dump(__METHOD__);
            return isset($this->array[$this->position]);
        }
    }

    $it = new myIterator;

    foreach($it as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(18) "myIterator::rewind"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(0)
    string(14) "premierelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(1)
    string(13) "secondelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(2)
    string(14) "dernierelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"

## Voir aussi

Voir aussi l'itération d'objet.

# Iterator::current

(PHP 5, PHP 7, PHP 8)

Iterator::current — Retourne l'élément courant

### Description

public function Iterator::current(): mixed

Retourne l'élément courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Peut retourner tout type.

# Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::key — Retourne la clé de l'élément courant

### Description

public function Iterator::key(): mixed

Retourne la clé de l'élément courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un scalaire en cas de succès, ou `null` si une erreur survient.

### Erreurs / Exceptions

Émet une alerte de type `E_NOTICE` si une erreur survient.

# Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::next — Se déplace sur l'élément suivant

### Description

public function Iterator::next(): void

Se déplace de la position courante à l'élément suivant.

> Note:

> Cette méthode est appelée après chaque boucle `foreach`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Les valeurs retournées seront ignorées.

# Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewind — Replace l'itérateur sur le premier élément

### Description

public function Iterator::rewind(): void

Replace l'itérateur sur le premier élément.

> Note:

> C'est la première méthode appelée lors du départ d'une boucle `foreach`. Elle ne sera pas exécutée après la boucle `foreach`.

> Comme `foreach` appelle toujours rewind() avant de commencer l'itération, avancer manuellement la position de l'itérateur (par exemple via SplFileObject::seek()) sera réinitialisée. Pour itérer sans rembobiner l'itérateur, il est possible de l'encapsuler dans un NoRewindIterator.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Toutes les valeurs retournées sont ignorées.

# Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::valid — Vérifie si la position courante est valide

### Description

public function Iterator::valid(): bool

Cette méthode est appelée après Iterator::rewind() et Iterator::next() pour vérifier si la position courante est valide.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La valeur retournée sera transtypée en booléen, puis évaluée. Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

## Sommaire

- Iterator::current — Retourne l'élément courant
- Iterator::key — Retourne la clé de l'élément courant
- Iterator::next — Se déplace sur l'élément suivant
- Iterator::rewind — Replace l'itérateur sur le premier élément
- Iterator::valid — Vérifie si la position courante est valide

# L'interface IteratorAggregate

(PHP 5, PHP 7, PHP 8)

## Introduction

Interface pour créer un itérateur externe.

## Sommaire de l'Interface

interface IteratorAggregate extends Traversable {
/* Méthodes */
public function getIterator(): Traversable
}

## Exemples

Exemple #1 Exemple simple

    <?php

    class myData implements IteratorAggregate
    {
        public function getIterator(): Traversable
        {
            return new ArrayIterator([
                "clé un" => "valeur un",
                "clé deux" => "valeur deux",
                "clé trois" => "valeur trois"
            ]);
        }
    }

    $obj = new myData();

    foreach($obj as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }

Résultat de l'exemple ci-dessus est similaire à :

    string(7) "clé un"
    string(9) "valeur un"

    string(9) "clé deux"
    string(11) "valeur deux"

    string(10) "clé trois"
    string(12) "valeur trois"

# IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIterator — Retourne un itérateur externe ou un objet traversable

### Description

public function IteratorAggregate::getIterator(): Traversable

Retourne un itérateur externe ou un objet traversable.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une instance d'un objet qui implémente un Iterator ou l'interface Traversable.

### Erreurs / Exceptions

Émet une Exception en cas d'échec.

## Sommaire

- IteratorAggregate::getIterator — Retourne un itérateur externe ou un objet traversable

# La classe InternalIterator

(PHP 8)

## Introduction

Classe facilitant l'implémentation de IteratorAggregate pour les classes internes.

## Synopsis de la classe

final class InternalIterator implements Iterator {
/* Méthodes */
private function __construct()
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# InternalIterator::__construct

(PHP 8)

InternalIterator::__construct — Constructeur privé pour empêcher l'instanciation directe

### Description

private function InternalIterator::__construct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# InternalIterator::current

(PHP 8)

InternalIterator::current — Retourne l'élément courant

### Description

public function InternalIterator::current(): mixed

Retourne l'élément courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'élément courant.

# InternalIterator::key

(PHP 8)

InternalIterator::key — Retourne la clé de l'élément courant

### Description

public function InternalIterator::key(): mixed

Retourne la clé de l'élément courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la clé de l'élément courant.

# InternalIterator::next

(PHP 8)

InternalIterator::next — Passe à l'élément suivant

### Description

public function InternalIterator::next(): void

Déplace la position actuelle vers l'élément suivant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

# InternalIterator::rewind

(PHP 8)

InternalIterator::rewind — Replace l'itérateur sur le premier élément

### Description

public function InternalIterator::rewind(): void

Replace l'itérateur sur le premier élément.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

# InternalIterator::valid

(PHP 8)

InternalIterator::valid — Vérifie si la position actuelle est valide

### Description

public function InternalIterator::valid(): bool

Vérifie que la position actuelle est valide.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne si la position actuelle est valide.

## Sommaire

- InternalIterator::__construct — Constructeur privé pour empêcher l'instanciation directe
- InternalIterator::current — Retourne l'élément courant
- InternalIterator::key — Retourne la clé de l'élément courant
- InternalIterator::next — Passe à l'élément suivant
- InternalIterator::rewind — Replace l'itérateur sur le premier élément
- InternalIterator::valid — Vérifie si la position actuelle est valide

# Throwable

(PHP 7, PHP 8)

## Introduction

Throwable est l'interface de base pour tout objet qui peut être lancé grâce à la déclaration `throw`, ceci inclut Error et Exception.

> Note:

> Les classes PHP ne peuvent pas directement implémenter l'interface Throwable, et doivent à la place étendre Exception.

## Sommaire de l'Interface

interface Throwable extends Stringable {
/* Méthodes */
public function getMessage(): string
public function getCode(): int
public function getFile(): string
public function getLine(): int
public function getTrace(): array
public function getTraceAsString(): string
public function getPrevious(): ?Throwable
public function __toString(): string
/* Méthodes héritées */
public function Stringable::__toString(): string
}

## Historique

Version | Description
--- | ---
8.0.0 | Throwable implémente désormais Stringable.

# Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessage — Récupère le message

### Description

public function Throwable::getMessage(): string

Retourne le message associé avec l'objet lancé.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le message associé avec l'objet lancé.

### Voir aussi

- Exception::getMessage() - Récupère le message de l'exception

# Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCode — Récupère le code de l'exception

### Description

public function Throwable::getCode(): int

Retourne le code d'erreur associé à l'objet lancé.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code de l'exception en tant que entier dans Exception mais éventuellement sous un autre type dans les descendants de Exception (par exemple chaîne de caractères dans PDOException).

### Voir aussi

- Exception::getCode() - Récupère le code de l'exception

# Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFile — Récupère le fichier où l'objet a été créé

### Description

public function Throwable::getFile(): string

Récupère le nom du fichier dans lequel l'objet lancé a été créé.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nom de fichier où l'objet lancé a été créé.

### Voir aussi

- Exception::getFile() - Récupère le fichier dans lequel l'exception a été créée

# Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLine — Récupère la ligne où l'objet a été instancié

### Description

public function Throwable::getLine(): int

Retourne le numéro de ligne où l'objet lancé a été instancié.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le numéro de ligne où l'objet lancé a été instancié.

### Voir aussi

- Exception::getLine() - Récupère la ligne dans laquelle l'exception a été créée

# Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTrace — Récupère la trace d'appels

### Description

public function Throwable::getTrace(): array

Retourne la trace d'appels en tant que tableau.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la trace d'appels en tant que tableau dans le même format que debug_backtrace().

### Voir aussi

- Exception::getTrace() - Récupère la trace de la pile

# Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsString — Récupère la trace d'appels en tant que chaîne de caractères

### Description

public function Throwable::getTraceAsString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la trace d'appels en tant que chaîne de caractères.

### Voir aussi

- Exception::getTraceAsString() - Récupère la trace de la pile en tant que chaîne

# Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPrevious — Retourne le Throwable précédent

### Description

public function Throwable::getPrevious(): ?Throwable

Retourne un Throwable précédent (par exemple, un fourni grâce au troisième paramètre de Exception::__construct()).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le Throwable précédent si disponible ou `null` sinon.

### Voir aussi

- Exception::getPrevious() - Retourne le Throwable précédent

# Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toString — Récupère la représentation sous forme de chaîne de caractères de l'objet lancé

### Description

public function Throwable::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de caractères de l'objet lancé.

### Voir aussi

- Exception::__toString() - Représente l'exception sous la forme d'une chaîne

## Sommaire

- Throwable::getMessage — Récupère le message
- Throwable::getCode — Récupère le code de l'exception
- Throwable::getFile — Récupère le fichier où l'objet a été créé
- Throwable::getLine — Récupère la ligne où l'objet a été instancié
- Throwable::getTrace — Récupère la trace d'appels
- Throwable::getTraceAsString — Récupère la trace d'appels en tant que chaîne de caractères
- Throwable::getPrevious — Retourne le Throwable précédent
- Throwable::__toString — Récupère la représentation sous forme de chaîne de caractères de l'objet lancé

# L'interface Countable

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introduction

Les classes qui implémentent l'interface Countable peuvent être utilisées avec la fonction count().

## Sommaire de l'Interface

interface Countable {
/* Méthodes */
public function count(): int
}

# Countable::count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Countable::count — Compte le nombre d'éléments d'un objet

### Description

public function Countable::count(): int

Cette méthode est exécutée lorsque le `value` pour count() est un objet implémentant Countable.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre compté, sous forme int.

### Exemples

Exemple #1 Exemple avec Countable::count()

    <?php

    class Counter implements Countable
    {
        private $count = 0;

        public function count(): int
        {
            return ++$this->count;
        }
    }

    $counter = new Counter;

    for ($i = 0; $i < 10; ++$i) {
        echo "J'ai été compté " . count($counter) . " fois\n";
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    J'ai été compté 1 fois
    J'ai été compté 2 fois
    J'ai été compté 3 fois
    J'ai été compté 4 fois
    J'ai été compté 5 fois
    J'ai été compté 6 fois
    J'ai été compté 7 fois
    J'ai été compté 8 fois
    J'ai été compté 9 fois
    J'ai été compté 10 fois

## Sommaire

- Countable::count — Compte le nombre d'éléments d'un objet

# L'interface ArrayAccess

(PHP 5, PHP 7, PHP 8)

## Introduction

Interface permettant d'accéder aux objets de la même façon que pour les tableaux.

## Sommaire de l'Interface

interface ArrayAccess {
/* Méthodes */
public function offsetExists(mixed `$offset`): bool
public function offsetGet(mixed `$offset`): mixed
public function offsetSet(mixed `$offset`, mixed `$value`): void
public function offsetUnset(mixed `$offset`): void
}

## Exemples

Exemple #1 Exemple basique

    <?php
    class Obj implements ArrayAccess {
        public $container = [
            "un"    => 1,
            "deux"  => 2,
            "trois" => 3,
        ];

        public function offsetSet($offset, $value): void {
            if (is_null($offset)) {
                $this->container[] = $value;
            } else {
                $this->container[$offset] = $value;
            }
        }

        public function offsetExists($offset): bool {
            return isset($this->container[$offset]);
        }

        public function offsetUnset($offset): void {
            unset($this->container[$offset]);
        }

        public function offsetGet($offset): mixed {
            return isset($this->container[$offset]) ? $this->container[$offset] : null;
        }
    }

    $obj = new Obj;

    var_dump(isset($obj["deux"]));
    var_dump($obj["deux"]);
    unset($obj["deux"]);
    var_dump(isset($obj["deux"]));
    $obj["deux"] = "Une valeur";
    var_dump($obj["deux"]);
    $obj[] = 'Ajout 1';
    $obj[] = 'Ajout 2';
    $obj[] = 'Ajout 3';
    print_r($obj);

Résultat de l'exemple ci-dessus est similaire à :

    bool(true)
    int(2)
    bool(false)
    string(10) "Une valeur"
    Obj Object
    (
        [container] => Array
            (
                [un] => 1
                [trois] => 3
                [deux] => Une valeur
                [0] => Ajout 1
                [1] => Ajout 2
                [2] => Ajout 3
            )

    )

# ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExists — Indique si une position existe dans un tableau

### Description

public function ArrayAccess::offsetExists(mixed `$offset`): bool

Indique si une position existe.

Cette méthode est exécutée lorsque la fonction isset() ou empty() est appliquée à un objet qui implémente l'interface ArrayAccess.

> Note:

> Lors de l'utilisation de empty(), ArrayAccess::offsetGet() est appelé et vérifie si la valeur est vide, uniquement si ArrayAccess::offsetExists() retourne `true`.

### Liste de paramètres

`offset`

  Une position à vérifier.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

> Note:

> La valeur retournée sera transtypée en booléen si une valeur non booléenne est retournée.

### Exemples

Exemple #1 Exemple avec ArrayAccess::offsetExists()

    <?php
    class obj implements ArrayAccess {
        public function offsetSet($offset, $value): void {
            var_dump(__METHOD__);
        }

        public function offsetExists($var): bool {
            var_dump(__METHOD__);
            if ($var == "foobar") {
                return true;
            }
            return false;
        }

        public function offsetUnset($var): void {
            var_dump(__METHOD__);
        }

        #[\ReturnTypeWillChange]
        public function offsetGet($var) {
            var_dump(__METHOD__);
            return "value";
        }
    }

    $obj = new obj;

    echo "Exécute obj::offsetExists()\n";
    var_dump(isset($obj["foobar"]));

    echo "\nExécute obj::offsetExists() et obj::offsetGet()\n";
    var_dump(empty($obj["foobar"]));

    echo "\nExécute obj::offsetExists(), *et non pas* obj:offsetGet() car il n'y a rien à lire\n";
    var_dump(empty($obj["foobaz"]));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Exécute obj::offsetExists()
    string(17) "obj::offsetExists"
    bool(true)

    Exécute obj::offsetExists() et obj::offsetGet()
    string(17) "obj::offsetExists"
    string(14) "obj::offsetGet"
    bool(false)

    Exécute obj::offsetExists(), *et non pas* obj:offsetGet() car il n'y a rien à lire
    string(17) "obj::offsetExists"
    bool(true)

# ArrayAccess::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGet — Position à lire

### Description

public function ArrayAccess::offsetGet(mixed `$offset`): mixed

Retourne la valeur à la position donnée.

Cette méthode est exécutée lorsque l'on vérifie si une position est empty().

### Liste de paramètres

`offset`

  La position à lire.

### Valeurs de retour

Peut retourner n'importe quel type de valeur.

### Notes

> Note:

> Il est possible aux implémentations de cette méthode de retourner par référence. Ceci permet les modifications indirectes des dimensions de l'objet ArrayAccess.

> Une modification directe remplace complètement la valeur dans la dimension du tableau comme dans `$obj[6] = 7`. Une modification indirecte, par contre, ne change qu'une partie de la dimension ou intervient lors de l'assignation par référence vers une autre variable, comme dans `$obj[6][7] = 7` ou encore `$var =& $obj[6]` suivi de l'incrémentation avec `++` et la décrémentation avec `--`.

> Les modifications directes appellent ArrayAccess::offsetSet() alors que les modifications indirectes appellent ArrayAccess::offsetGet(). Dans ce cas, l'implémentation de ArrayAccess::offsetGet() doit retourner une référence sinon un message `E_NOTICE` sera levé.

### Voir aussi

- ArrayAccess::offsetExists() - Indique si une position existe dans un tableau

# ArrayAccess::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSet — Assigne une valeur à une position donnée

### Description

public function ArrayAccess::offsetSet(mixed `$offset`, mixed `$value`): void

Assigne une valeur à une position donnée.

### Liste de paramètres

`offset`

  La position à laquelle assigner une valeur.

`value`

  La valeur à assigner.

### Valeurs de retour

Aucune valeur n'est retournée.

### Notes

> Note:

> Le paramètre `offset` sera défini à `null` si une autre valeur n'est pas disponible, comme dans l'exemple suivant :

>     <?php
>     $arrayaccess[] = "première valeur";
>     $arrayaccess[] = "seconde valeur";
>     print_r($arrayaccess);
>     ?>

> L'exemple ci-dessus va afficher :

>     Array
>     (
>         [0] => première valeur
>         [1] => seconde valeur
>     )

> Note:

> Cette fonction n'est pas appelée dans les assignations par référence et lors de changements indirects de dimensions de tableaux surchargées avec ArrayAccess (indirects dans le sens où ils ne sont pas effectués en changeant la dimension directement, mais en changeant une sous-dimension ou une sous-propriété, ou en assignant la dimension du tableau par référence à une autre variable). À la place, ArrayAccess::offsetGet() est appelée. Cette opération ne fonctionnera que si cette méthode retourne une référence.

# ArrayAccess::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnset — Supprime un élément à une position donnée

### Description

public function ArrayAccess::offsetUnset(mixed `$offset`): void

Supprime un élément à une position donnée.

> Note:

> Cette méthode ne sera pas appelée lors du transtypage en (unset).

### Liste de paramètres

`offset`

  La position à supprimer.

### Valeurs de retour

Aucune valeur n'est retournée.

## Sommaire

- ArrayAccess::offsetExists — Indique si une position existe dans un tableau
- ArrayAccess::offsetGet — Position à lire
- ArrayAccess::offsetSet — Assigne une valeur à une position donnée
- ArrayAccess::offsetUnset — Supprime un élément à une position donnée

# L'interface Serializable

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introduction

Interface permettant de personnaliser la sérialisation.

Les classes implémentant cette interface ne supportent plus __sleep() et __wakeup(). La méthode de sérialisation est appelée chaque fois qu'une instance doit être sérialisée. Elle n'appelle pas __destruct() et ne produit aucun autre effet de bord, sauf si cela est codé dans la méthode. Lorsque les données sont désérialisées, la classe est connue et la méthode unserialize() appropriée est appelée comme constructeur au lieu d'appeler __construct(). S'il est nécessaire d'appeler le constructeur standard, il est possible de le faire dans la méthode.

Avertissement

À partir de PHP 8.1.0, une classe qui implémente Serializable sans aussi implémenter __serialize() et __unserialize() génèrera une notice de dépréciation.

## Sommaire de l'Interface

interface Serializable {
/* Méthodes */
public function serialize(): ?string
public function unserialize(string `$data`): void
}

## Exemples

Exemple #1 Exemple simple

    <?php
    class obj implements Serializable {
        private $data;
        public function __construct() {
            $this->data = "Mes données privées";
        }
        public function serialize() {
            return serialize($this->data);
        }
        public function unserialize($data) {
            $this->data = unserialize($data);
        }
        public function getData() {
            return $this->data;
        }
    }

    $obj = new obj;
    $ser = serialize($obj);

    var_dump($ser);

    $newobj = unserialize($ser);

    var_dump($newobj->getData());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Deprecated: obj implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in script on line 2
    string(44) "C:3:"obj":29:{s:21:"Mes données privées";}"
    string(21) "Mes données privées"

# Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serialize — Représentation linéaire de l'objet

### Description

public function Serializable::serialize(): ?string

Retourne la représentation en chaîne de caractères de l'objet.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation de l'objet en chaîne de caractères, ou bien `null`.

### Erreurs / Exceptions

Émet une Exception si un autre type que chaîne de caractères ou `null` est retourné.

### Voir aussi

- __sleep()
- __serialize()

# Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserialize — Construit un objet

### Description

public function Serializable::unserialize(string `$data`): void

Appelé lors de la désérialisation de l'objet.

> Note:

> Cette méthode se comporte comme un constructeur d'objet. La méthode __construct() ne sera pas appelée après cette méthode.

### Liste de paramètres

`data`

  La représentation en chaîne de l'objet.

### Valeurs de retour

La valeur de retour est ignorée.

### Voir aussi

- __wakeup()
- __unserialize()

## Sommaire

- Serializable::serialize — Représentation linéaire de l'objet
- Serializable::unserialize — Construit un objet

# La classe Closure

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introduction

Classe utilisée pour représenter les fonctions anonymes.

Les fonctions anonymes produisent des objets de ce type. Cette classe a des méthodes qui permettent un contrôle supplémentaire de la fonction anonyme après sa création.

En plus des méthodes précisées ici, cette classe possède aussi une méthode `__invoke`. Ceci pour des raisons de cohérence avec les autres classes qui implémentent la méthode magique d'appel, car cette méthode n'est pas utilisée pour appeler la fonction.

## Synopsis de la classe

final class Closure {
/* Méthodes */
private function __construct()
public static function bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function call(object `$newThis`, mixed `...$args`): mixed
public static function fromCallable(callable `$callback`): Closure
public static function getCurrent(): Closure
}

## Historique

Version | Description
--- | ---
8.4.0 | La sortie de Closure::__debugInfo() inclut désormais le nom, la ligne et le fichier de la fermeture.

## Notes

> Note: Les objets Closure ne peuvent pas être sérialisés car les fermetures peuvent contenir des variables liées et un contexte d'exécution spécifique. Tenter de sérialiser une fermeture lancera une Exception.

# Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__construct — Constructeur empêchant l'instanciation

### Description

private function Closure::__construct()

Cette méthode n'existe que pour interdire l'instanciation directe de la classe Closure. Des objets d'une telle classe sont créés au moyen des fonctions anonymes.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- Fonctions anonymes

# Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bind — Duplique une fermeture avec un nouvel objet lié et un nouveau contexte de classe.

### Description

public static function Closure::bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

Cette méthode est une version statique de Closure::bindTo(). Voir sa documentation pour plus d'informations.

### Liste de paramètres

`closure`

  La fonction anonyme à lier.

`newThis`

  L'objet auquel lier la fonction anonyme, ou `null` pour délier.

`newScope`

  Le contexte de classe à associer à la fermeture, ou 'static' pour conserver le contexte actuel. Si un objet est utilisé, son type sera utilisé. Ceci détermine les accès protégés et privés de l'objet lié. Il n'est pas autorisé de passer (un objet d') une classe interne pour ce paramètre.

### Valeurs de retour

Retourne un nouvel objet Closure, ou `null` en cas d'échec.

### Exemples

Exemple #1 Exemple Closure::bind()

    <?php
    class A {
        private static $sfoo = 1;
        private $ifoo = 2;
    }
    $cl1 = static function() {
        return A::$sfoo;
    };
    $cl2 = function() {
        return $this->ifoo;
    };

    $bcl1 = Closure::bind($cl1, null, 'A');
    $bcl2 = Closure::bind($cl2, new A(), 'A');
    echo $bcl1(), "\n";
    echo $bcl2(), "\n";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    1
    2

### Voir aussi

- fonctions anonymes
- Closure::bindTo() - Duplique la fermeture avec un nouvel objet lié et un nouveau contexte de classe.

# Closure::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindTo — Duplique la fermeture avec un nouvel objet lié et un nouveau contexte de classe.

### Description

public function Closure::bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

Crée et retourne une nouvelle fonction anonyme avec le même corps et les mêmes variables liées que l'originale, mais avec un objet lié qui peut être différent, et un nouveau contexte de classe.

L'objet lié détermine la valeur que `$this` aura dans le corps de la fonction, et le contexte de classe représente une classe qui détermine à quels membres privés et protégés la fonction anonyme aura accès. Autrement dit, les propriétés qui seront visibles seront les mêmes que si la fonction anonyme était une méthode de la classe passée via le paramètre `newScope`.

Les fermetures statiques ne peuvent pas avoir d'objet lié (la valeur du paramètre `newThis` devrait être `null`), mais cette méthode peut néanmoins être utilisée pour changer leur portée de classe.

Cette méthode va vérifier qu'une fermeture non-statique à laquelle on passe un contexte d'objet deviendra liée à cet objet (et ne sera donc plus non-statique), et vice-versa. Dans ce but, les fermetures non-statiques auxquelles on passe un contexte de classe mais `null` comme contexte objet seront rendues statiques, et inversement.

> Note:

> Pour simplement dupliquer la fonction anonyme, il est possible d'utiliser le clonage à la place.

### Liste de paramètres

`newThis`

  L'objet auquel lier la fonction anonyme, ou `null` pour que la fermeture ne soit pas liée.

`newScope`

  Le contexte de classe à associer à la fermeture, ou 'static' pour conserver le contexte actuel. Si un objet est passé, son type sera utilisé. Ceci détermine la visibilité des méthodes protégées et privées de l'objet lié. Il n'est pas autorisé de passer (un objet d') une classe interne pour ce paramètre.

### Valeurs de retour

Retourne la nouvelle fermeture sous la forme d'un objet Closure, ou `null` en cas d'erreur.

### Exemples

Exemple #1 Exemple Closure::bindTo()

    <?php

    class A
    {
        private $val;

        public function __construct($val)
        {
            $this->val = $val;
        }

        public function getClosure()
        {
            // Retourne une fermeture liée à cet objet et ce contexte
            return function() {
                return $this->val;
            };
        }
    }

    $ob1 = new A(1);
    $ob2 = new A(2);

    $cl = $ob1->getClosure();
    echo $cl(), "\n";

    $cl = $cl->bindTo($ob2);
    echo $cl(), "\n";

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    1
    2

### Voir aussi

- Fonctions anonymes
- Closure::bind() - Duplique une fermeture avec un nouvel objet lié et un nouveau contexte de classe.

# Closure::call

(PHP 7, PHP 8)

Closure::call — Lie et appelle la fermeture

### Description

public function Closure::call(object `$newThis`, mixed `...$args`): mixed

Lie temporairement la fermeture (closure) à `newThis`, et l'appelle avec les paramètres donnés.

### Liste de paramètres

`newThis`

  L'objet auquel lier la fermeture pour la durée de l'appel.

`args`

  Zéro ou plusieurs paramètres, qui seront donnés en tant que paramètres à la fermeture.

### Valeurs de retour

Retourne la valeur de retour de la fermeture.

### Exemples

Exemple #1 Exemple de Closure::call()

    <?php
    class Value {
        protected $value;

        public function __construct($value) {
            $this->value = $value;
        }

        public function getValue() {
            return $this->value;
        }
    }

    $three = new Value(3);
    $four = new Value(4);

    $closure = function ($delta) { var_dump($this->getValue() + $delta); };
    $closure->call($three, 4);
    $closure->call($four, 4);
    ?>

L'exemple ci-dessus va afficher :

    int(7)
    int(8)

# Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallable — Convertit un callable en une fermeture

### Description

public static function Closure::fromCallable(callable `$callback`): Closure

Crée et retourne une nouvelle fonction anonyme à partir du `callback` donné en utilisant la portée courante. Cette méthode vérifie que `callback` est appelable dans la portée courante et émet un TypeError si ce n'est pas le cas.

> Note:

> À partir de PHP 8.1.0, la syntaxe callable de première classe a les mêmes sémantiques que cette méthode.

### Liste de paramètres

`callback`

  Le callable à convertir.

### Valeurs de retour

Retourne la nouvelle Closure créée ou émet une TypeError si `callback` n'est pas appelable dans la portée courante.

### Voir aussi

- Fonctions anonymes
- Syntaxe callable de première classe

# Closure::getCurrent

(PHP 8 >= 8.5.0)

Closure::getCurrent — Retourne la closure en cours d'exécution

### Description

public static function Closure::getCurrent(): Closure

Retourne la closure en cours d'exécution. Cette méthode est principalement utile pour implémenter des closures récursives sans avoir besoin de capturer une référence vers la variable de la closure en utilisant le mot-clé `use`.

Cette méthode doit être appelée depuis une closure ; l'appeler en dehors d'un contexte de closure provoquera l'erreur `Error: Current function is not a closure.`

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'instance de Closure en cours d'exécution.

### Erreurs / Exceptions

Lance une Error si elle est appelée en dehors d'un contexte de closure.

### Exemples

Exemple #1 Exemple avec Closure::getCurrent()

Utilisation de Closure::getCurrent() pour implémenter une fonction de Fibonacci récursive :

    <?php
    $fibonacci = function (int $n) {
        if ($n === 0 || $n === 1) {
            return $n;
        }

        $fn = Closure::getCurrent();
        return $fn($n - 1) + $fn($n - 2);
    };

    echo $fibonacci(10); // Affiche : 55
    ?>

Exemple #2 Comparaison avec l'approche traditionnelle

Avant PHP 8.5, implémenter des closures récursives nécessitait de capturer une référence vers la variable de la closure en utilisant le mot-clé `use` :

    <?php
    // Approche traditionnelle (fonctionne toujours en PHP 8.5)
    $fibonacci = function (int $n) use (&$fibonacci) {
        if ($n === 0) return 0;
        if ($n === 1) return 1;
        return $fibonacci($n - 1) + $fibonacci($n - 2);
    };

    echo $fibonacci(10); // Affiche : 55
    ?>

L'approche avec Closure::getCurrent() élimine le besoin de déclarer la variable avec une référence dans la clause `use`, rendant le code plus propre et moins sujet aux erreurs.

## Sommaire

- Closure::__construct — Constructeur empêchant l'instanciation
- Closure::bind — Duplique une fermeture avec un nouvel objet lié et un nouveau contexte de classe.
- Closure::bindTo — Duplique la fermeture avec un nouvel objet lié et un nouveau contexte de classe.
- Closure::call — Lie et appelle la fermeture
- Closure::fromCallable — Convertit un callable en une fermeture
- Closure::getCurrent — Retourne la closure en cours d'exécution

# La classe stdClass

(PHP 4, PHP 5, PHP 7, PHP 8)

## Introduction

Une classe générique vide avec des propriétés dynamiques.

Les objets de cette classe peuvent être instanciés avec l'opérateur new ou créés en utilisant la conversion en objet. Plusieurs fonctions PHP créent également des instances de cette classe, par exemple json_decode(), mysqli_fetch_object() ou PDOStatement::fetchObject().

Bien que n'implémentant pas __get()/__set() cette classe autorise les propriétés dynamiques et ne nécessite pas l'attribut `#[\AllowDynamicProperties]`.

Ce n'est pas une classe de base car PHP n'a pas de concept de classe de base universelle. Cependant, il est possible de créer une classe personnalisée qui étend stdClass et qui hérite ainsi de la fonctionnalité des propriétés dynamiques.

## Synopsis de la classe

#[\AllowDynamicProperties]
class stdClass {
}

Cette classe n'a pas de méthode ni de propriété par défaut.

## Exemples

Exemple #1 Créé à la suite d'une conversion de type en objet

    <?php
    $obj = (object) array('foo' => 'bar');
    var_dump($obj);

L'exemple ci-dessus va afficher :

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Exemple #2 Créé en tant que résultat de json_decode()

    <?php
    $json = '{"foo":"bar"}';
    var_dump(json_decode($json));

L'exemple ci-dessus va afficher :

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Exemple #3 Déclaration de propriétés dynamiques

    <?php
    $obj = new stdClass();
    $obj->foo = 42;
    $obj->{1} = 42;
    var_dump($obj);

L'exemple ci-dessus va afficher :

    object(stdClass)#1 (2) {
      ["foo"]=>
      int(42)
      ["1"]=>
      int(42)
    }

# La classe Generator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

Les objets Generator sont retournés depuis des générateurs.

Attention

Les objets Generator ne peuvent pas être instanciés via le mot clé new.

## Synopsis de la classe

final class Generator implements Iterator {
/* Méthodes */
public function current(): mixed
public function getReturn(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function send(mixed `$value`): mixed
public function throw(Throwable `$exception`): mixed
public function valid(): bool
public function __wakeup(): void
}

## Voir aussi

Voir aussi l'itération d'objet.

# Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::current — Récupère la valeur cédée

### Description

public function Generator::current(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la valeur cédée.

# Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturn — Obtenir la valeur de retour d'un générateur

### Description

public function Generator::getReturn(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la valeur de retour du générateur une fois qu'il a terminé l'exécution.

### Exemples

Exemple #1 Exemple avec Generator::getReturn()

    <?php

    $gen = (function() {
        yield 1;
        yield 2;

        return 3;
    })();

    foreach ($gen as $val) {
        echo $val, PHP_EOL;
    }

    echo $gen->getReturn(), PHP_EOL;

L'exemple ci-dessus va afficher :

    1
    2
    3

# Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::key — Récupère la clé cédée

### Description

public function Generator::key(): mixed

Récupère la clé de la valeur cédée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la clé cédée.

### Exemples

Exemple #1 Exemple avec Generator::key()

    <?php

    function Gen()
    {
        yield 'key' => 'value';
    }

    $gen = Gen();

    echo "{$gen->key()} => {$gen->current()}";

L'exemple ci-dessus va afficher :

    key => value

# Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::next — Reprend l'exécution du générateur

### Description

public function Generator::next(): void

L'appel de Generator::next() a le même effet qu'appeler Generator::send() avec `null` comme argument.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

# Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — Exécute le générateur jusqu'au premier yield inclus

### Description

public function Generator::rewind(): void

Exécute le générateur jusqu'au premier `yield` inclus. Si le générateur est déjà au premier `yield`, aucune action ne sera effectuée. Si le générateur a déjà avancé au-delà d'une expression `yield`, cette méthode lancera une Exception.

> Note:

> Il s'agit de la méthode première appelée lors du démarrage d'une boucle `foreach`. Elle ne sera pas exécutée après les boucles `foreach`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple de Generator::rewind()

    <?php

    function generator(): Generator
    {
        echo "Je suis un générateur !\n";

        for ($i = 1; $i <= 3; $i++) {
            yield $i;
        }
    }

    // Initialiser le générateur
    $generator = generator();

    // Remettre le générateur au début de la première expression yield,
    // si ce n'est pas déjà le cas
    $generator->rewind(); // Je suis un générateur !

    // Rien ne se passe ici ; le générateur est déjà remis à zéro
    $generator->rewind(); // Pas de sortie (NULL)

    // Cela remet le générateur au début de la première expression yield,
    // si ce n'est pas déjà le cas, et itère sur le générateur
    foreach ($generator as $value) {
        // Après avoir renvoyé la première valeur, le générateur reste à
        // la première expression yield jusqu'à ce qu'il reprenne l'exécution et avance à la prochaine yield
        echo $value, PHP_EOL; // 1

        break;
    }

    // Reprendre et remettre à zéro à nouveau. Aucune erreur ne se produit car le générateur n'a pas avancé au-delà du premier yield
    $generator->rewind();

    echo $generator->current(), PHP_EOL; // 1

    // Aucune erreur ne se produit, le générateur est toujours à la première yield
    $generator->rewind();

    // Cela fait avancer le générateur à la deuxième expression yield
    $generator->next();

    try {
        // Cela lancera une exception,
        // car le générateur a déjà avancé à la deuxième yield
        $generator->rewind(); // Erreur fatale : Exception non capturée : Impossible de remettre un générateur qui a déjà été exécuté
    } catch (Exception $e) {
        echo $e->getMessage();
    }

    ?>

L'exemple ci-dessus va afficher :

    Je suis un générateur !
    1
    1
    Impossible de remettre un générateur qui a déjà été exécuté

# Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::send — Envoie une valeur au générateur

### Description

public function Generator::send(mixed `$value`): mixed

Envoie la valeur fournie au générateur comme résultat de l'expression courante `yield`, et reprend l'exécution du générateur.

Si le générateur n'est pas à une expression `yield` lorsque cette méthode est appelée, il va d'abord avancer à la première expression `yield` avant d'envoyer la valeur. Ainsi, il n'est pas nécessaire de démarrer un générateur PHP avec un appel à la méthode Generator::next() (comme c'est le cas en Python).

### Liste de paramètres

`value`

  Valeur à envoyer au générateur. Cette valeur sera la valeur retournée de l'expression `yield` de la position courante du générateur.

### Valeurs de retour

Retourne la valeur cédée.

### Exemples

Exemple #1 Exemple d'utilisation de Generator::send() pour injecter des données

    <?php
    function printer() {
        echo "Je suis une imprimante !".PHP_EOL;
        while (true) {
            $string = yield;
            echo $string.PHP_EOL;
        }
    }

    $printer = printer();
    $printer->send('Bonjour le monde !');
    $printer->send('Au revoir le monde !');
    ?>

L'exemple ci-dessus va afficher :

    Je suis une imprimante !
    Bonjour le monde !
    Au revoir le monde !

# Generator::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throw — Lance une exception dans le générateur

### Description

public function Generator::throw(Throwable `$exception`): mixed

Lance une exception dans le générateur et reprend son exécution. Le comportement sera le même que si l'expression `yield` courante avait été remplacée avec une expression `throw $exception`.

Si le générateur est déjà fermé quand cette méthode est appelée, l'exception sera lancée dans le contexte de l'appelant à la place.

### Liste de paramètres

`exception`

  Exception à lancer dans le générateur.

### Valeurs de retour

Retourne la valeur cédée.

### Exemples

Exemple #1 Lance une exception dans un générateur

    <?php
    function gen() {
        echo "Foo\n";
        try {
            yield;
        } catch (Exception $e) {
            echo "Exception : {$e->getMessage()}\n";
        }
        echo "Bar\n";
    }

    $gen = gen();
    $gen->rewind();
    $gen->throw(new Exception('Test'));
    ?>

L'exemple ci-dessus va afficher :

    Foo
    Exception : Test
    Bar

# Generator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::valid — Vérifie si l'itérateur a été fermé

### Description

public function Generator::valid(): bool

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `false` si l'itérateur a été fermé. Sinon, retourne `true`.

# Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeup — Fonction de rappel de sérialisation

### Description

public function Generator::__wakeup(): void

Lance une exception sachant que les générateurs ne peuvent être sérialisés.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

## Sommaire

- Generator::current — Récupère la valeur cédée
- Generator::getReturn — Obtenir la valeur de retour d'un générateur
- Generator::key — Récupère la clé cédée
- Generator::next — Reprend l'exécution du générateur
- Generator::rewind — Exécute le générateur jusqu'au premier yield inclus
- Generator::send — Envoie une valeur au générateur
- Generator::throw — Lance une exception dans le générateur
- Generator::valid — Vérifie si l'itérateur a été fermé
- Generator::__wakeup — Fonction de rappel de sérialisation

# La classe Fiber

(PHP 8 >= 8.1.0)

## Introduction

Les fibres représentent des fonctions interruptibles sur toute la pile. Les fibres peuvent être suspendues à n'importe quel endroit de la pile d'appels, en interrompant l'exécution à l'intérieur de la fibre jusqu'à ce que la fibre soit reprise ultérieurement.

## Synopsis de la classe

final class Fiber {
/* Méthodes */
public function __construct(callable `$callback`)
public function start(mixed `...$args`): mixed
public function resume(mixed `$value` = `null`): mixed
public function throw(Throwable `$exception`): mixed
public function getReturn(): mixed
public function isStarted(): bool
public function isSuspended(): bool
public function isRunning(): bool
public function isTerminated(): bool
public static function suspend(mixed `$value` = `null`): mixed
public static function getCurrent(): ?Fiber
}

## Voir aussi

Aperçu des fibres

# Fiber::__construct

(PHP 8 >= 8.1.0)

Fiber::__construct — Crée une nouvelle instance de Fibre

### Description

public function Fiber::__construct(callable `$callback`)

### Liste de paramètres

`callback`

  Le callable à invoquer lors du démarrage de la fibre. Les arguments donnés à Fiber::start() seront fournis en tant qu'arguments à la fonction donnée.

# Fiber::start

(PHP 8 >= 8.1.0)

Fiber::start — Démarre l'exécution de la fibre

### Description

public function Fiber::start(mixed `...$args`): mixed

Une liste variadique d'arguments à fournir à la fonction utilisée lors de la construction de la fibre.

Si la fibre a déjà été démarrée lorsque cette méthode est appelée, une erreur FiberError sera émise.

### Liste de paramètres

`args`

  Les arguments à utiliser lors de l'invocation de la fonction donnée au constructeur de la fibre.

### Valeurs de retour

La valeur fournie au premier appel à Fiber::suspend() ou `null` si la fibre retourne. Si la fibre lance une exception avant de se suspendre, elle sera émise lors de l'appel à cette méthode.

# Fiber::resume

(PHP 8 >= 8.1.0)

Fiber::resume — Reprend l'exécution de la fibre avec une valeur

### Description

public function Fiber::resume(mixed `$value` = `null`): mixed

Reprend la fibre en utilisant la valeur donnée comme résultat de l'appel actuel à Fiber::suspend().

Si la fibre n'est pas suspendue lors de l'appel de cette méthode, une FiberError sera émise.

### Liste de paramètres

`value`

  La valeur pour reprendre la fibre. Cette valeur sera la valeur de retour de l'appel Fiber::suspend() en cours.

### Valeurs de retour

La valeur fournie au prochain appel à Fiber::suspend() ou `null` si la fibre retourne. Si la fibre lance une exception avant de se suspendre, elle sera émise lors de l'appel à cette méthode.

# Fiber::throw

(PHP 8 >= 8.1.0)

Fiber::throw — Reprend l'exécution de la fibre avec une exception

### Description

public function Fiber::throw(Throwable `$exception`): mixed

Reprend la fibre en lançant l'exception donnée à partir de l'appel Fiber::suspend() en cours.

Si la fibre n'est pas suspendue lorsque cette méthode est appelée, une exception FiberError sera émise.

### Liste de paramètres

`exception`

  L'exception à lancer dans la fibre à partir de l'appel Fiber::suspend() en cours.

### Valeurs de retour

La valeur fournie au prochain appel à Fiber::suspend() ou `null` si la fibre retourne. Si la fibre lance une exception avant de se suspendre, elle sera émise lors de l'appel à cette méthode.

### Exemples

    <?php

    $fiber = new Fiber(function () {
       try {
           // Suspend l'exécution de la fibre en déclarant un point d'interruption
           Fiber::suspend();
       } catch (Throwable $e) {
           echo $e->getMessage();
       }
    });

    $fiber->start();

    // Reprend l'exécution de la fibre en
    // passant l'Exception à lancer au point d'interruption
    $fiber->throw(new Exception('Message d\'une exception lancée au point d\'interruption courant'));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Message d'une exception lancée au point d'interruption courant

# Fiber::getReturn

(PHP 8 >= 8.1.0)

Fiber::getReturn — Obtient la valeur retournée par la fibre

### Description

public function Fiber::getReturn(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la valeur retournée par le callable fourni à Fiber::__construct(). Si la fibre n'a pas retourné de valeur, soit parce qu'elle n'a pas été lancée, soit parce qu'elle ne s'est pas terminée, soit parce qu'elle a lancé une exception, une FiberError sera lancée.

# Fiber::isStarted

(PHP 8 >= 8.1.0)

Fiber::isStarted — Détermine si la fibre a démarré

### Description

public function Fiber::isStarted(): bool

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` seulement après que la fibre a été démarrée ; sinon `false` est retourné.

# Fiber::isSuspended

(PHP 8 >= 8.1.0)

Fiber::isSuspended — Détermine si la fibre est suspendue

### Description

public function Fiber::isSuspended(): bool

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si la fibre est actuellement suspendue ; sinon `false` est retourné.

# Fiber::isRunning

(PHP 8 >= 8.1.0)

Fiber::isRunning — Détermine si la fibre est en cours d'exécution

### Description

public function Fiber::isRunning(): bool

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` seulement si la fibre est en cours d'exécution. Une fibre est considérée comme étant en cours d'exécution après un appel à Fiber::start(), Fiber::resume(), ou Fiber::throw() qui n'est pas encore retourné. Retourne `false` si la fibre n'est pas en cours d'exécution.

# Fiber::isTerminated

(PHP 8 >= 8.1.0)

Fiber::isTerminated — Détermine si la fibre est terminée

### Description

public function Fiber::isTerminated(): bool

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` seulement après que la fibre se soit terminée, soit en retournant, soit en lançant une exception ; sinon, `false` est retourné.

# Fiber::suspend

(PHP 8 >= 8.1.0)

Fiber::suspend — Suspend l'exécution de la fibre en cours

### Description

public static function Fiber::suspend(mixed `$value` = `null`): mixed

Suspend l'exécution de la fibre en cours. La valeur fournie à cette méthode sera retournée par l'appel à Fiber::start(), Fiber::resume(), ou Fiber::throw() qui a fait basculer l'exécution dans la fibre en cours.

Lorsque la fibre est reprise, cette méthode retourne la valeur fournie à Fiber::resume(). Si la fibre est reprise en utilisant Fiber::throw(), l'exception donnée à cette méthode sera émise lors de l'appel à cette méthode.

Si cette méthode est appelée depuis l'extérieur d'une fibre, une FiberError sera émise.

### Liste de paramètres

`value`

  La valeur à retourner de l'appel à Fiber::start(), Fiber::resume(), ou Fiber::throw() qui a fait basculer l'exécution dans la fibre actuelle.

### Valeurs de retour

La valeur fournie à Fiber::resume().

# Fiber::getCurrent

(PHP 8 >= 8.1.0)

Fiber::getCurrent — Obtient l'instance de Fibre en cours d'exécution

### Description

public static function Fiber::getCurrent(): ?Fiber

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'instance Fiber en cours d'exécution ou `null` si cette méthode est appelée à partir de l'extérieur d'une fibre.

## Sommaire

- Fiber::__construct — Crée une nouvelle instance de Fibre
- Fiber::start — Démarre l'exécution de la fibre
- Fiber::resume — Reprend l'exécution de la fibre avec une valeur
- Fiber::throw — Reprend l'exécution de la fibre avec une exception
- Fiber::getReturn — Obtient la valeur retournée par la fibre
- Fiber::isStarted — Détermine si la fibre a démarré
- Fiber::isSuspended — Détermine si la fibre est suspendue
- Fiber::isRunning — Détermine si la fibre est en cours d'exécution
- Fiber::isTerminated — Détermine si la fibre est terminée
- Fiber::suspend — Suspend l'exécution de la fibre en cours
- Fiber::getCurrent — Obtient l'instance de Fibre en cours d'exécution

# La classe WeakReference

(PHP 7 >= 7.4.0, PHP 8)

## Introduction

Les références faibles permettent au programmeur de conserver une référence à un objet sans en empêcher sa destruction. Elles sont utiles pour implémenter des structures telles que des caches. Si l'objet d'origine a été détruit, `null` sera retourné lors de l'appel de la méthode WeakReference::get(). L'objet d'origine sera détruit lorsque le compteur de références atteint zéro ; la création de références faibles n'augmente pas le `compteur de références` de l'objet référencé.

Les WeakReferences ne peuvent pas être sérialisées.

## Synopsis de la classe

final class WeakReference {
/* Méthodes */
public function __construct()
public static function create(object `$object`): WeakReference
public function get(): ?object
}

## Exemple avec WeakReference

Exemple #1 Utilisation Simple de WeakReference

    <?php

    $obj = new stdClass();
    $weakref = WeakReference::create($obj);

    var_dump($weakref->get());

    unset($obj);

    var_dump($weakref->get());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#1 (0) {
    }
    NULL

## Historique

Version | Description
--- | ---
8.4.0 | La sortie de WeakReference::__debugInfo() inclut désormais l'objet référencé, ou `NULL` si la référence n'est plus valide.

# WeakReference::__construct

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::__construct — Constructeur qui interdit l'initialisation

### Description

public function WeakReference::__construct()

Cette méthode existe seulement pour interdire l'initialisation de la classe WeakReference. Les références faibles doivent être initialisées avec la méthode usine (factory) WeakReference::create().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- WeakReference::create() - Créer une nouvelle référence faible

# WeakReference::create

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::create — Créer une nouvelle référence faible

### Description

public static function WeakReference::create(object `$object`): WeakReference

Crée une nouvelle WeakReference.

### Liste de paramètres

`object`

  L'objet à référencer faiblement.

### Valeurs de retour

Retourne une nouvelle WeakReference, ou l'instance existante s'il y avait déjà une WeakReference vers le même objet.

# WeakReference::get

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::get — Récupère un objet faiblement référencé

### Description

public function WeakReference::get(): ?object

Récupère un objet faiblement référencé. Si l'objet a déjà été détruit, `null` est retourné.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'objet référencé, ou `null` si l'objet a été détruit.

## Sommaire

- WeakReference::__construct — Constructeur qui interdit l'initialisation
- WeakReference::create — Créer une nouvelle référence faible
- WeakReference::get — Récupère un objet faiblement référencé

# La classe WeakMap

(PHP 8)

## Introduction

Un WeakMap est un tableau associatif (ou dictionnaire) qui accepte des objets comme clés. Cependant, contrairement au par ailleurs similaire SplObjectStorage, un objet dans une clé de WeakMap ne contribue pas au nombre de références de l'objet. En d'autres termes, si, à un moment donné, la seule référence restante à un objet est la clé d'un WeakMap, l'objet sera ramassé et supprimé du WeakMap. Son principal cas d'utilisation est la construction de caches de données dérivées d'un objet qui n'ont pas besoin d'être conservées plus longtemps que l'objet.

WeakMap implémente ArrayAccess, Traversable (via IteratorAggregate), et Countable, de sorte que, dans la plupart des cas, il peut être utilisé de la même manière qu'un tableau associatif.

## Synopsis de la classe

final class WeakMap implements ArrayAccess, Countable, IteratorAggregate {
/* Méthodes */
public function count(): int
public function getIterator(): Iterator
public function offsetExists(object `$object`): bool
public function offsetGet(object `$object`): mixed
public function offsetSet(object `$object`, mixed `$value`): void
public function offsetUnset(object `$object`): void
}

## Exemples

Exemple #1 Exemple d'utilisation d'un Weakmap

    <?php
    $wm = new WeakMap();

    $o = new stdClass;

    class A {
        public function __destruct() {
            echo "Dead!\n";
        }
    }

    $wm[$o] = new A;

    var_dump(count($wm));
    echo "Unsetting...\n";
    unset($o);
    echo "Done\n";
    var_dump(count($wm));

L'exemple ci-dessus va afficher :

    int(1)
    Unsetting...
    Dead!
    Done
    int(0)

# WeakMap::count

(PHP 8)

WeakMap::count — Compte le nombre d'entrées actives dans le dictionnaire

### Description

public function WeakMap::count(): int

Compte le nombre d'entrées actives dans le dictionnaire.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre d'entrées actives dans le dictionnaire.

# WeakMap::getIterator

(PHP 8)

WeakMap::getIterator — Récupère un itérateur externe

### Description

public function WeakMap::getIterator(): Iterator

Retourne un itérateur externe.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une instance d'un objet implémentant Iterator ou Traversable

### Erreurs / Exceptions

Lance une Exception en cas d'échec.

# WeakMap::offsetExists

(PHP 8)

WeakMap::offsetExists — Vérifie si un certain objet se trouve dans le dictionnaire

### Description

public function WeakMap::offsetExists(object `$object`): bool

Vérifie si l'objet transmis est référencé dans le dictionnaire.

### Liste de paramètres

`object`

  Objet à vérifier.

### Valeurs de retour

Retourne `true` si l'objet est contenu dans le dictionnaire, `false` sinon.

# WeakMap::offsetGet

(PHP 8)

WeakMap::offsetGet — Retourne la valeur indiquée par un certain objet

### Description

public function WeakMap::offsetGet(object `$object`): mixed

Retourne la valeur indiquée par un certain objet.

### Liste de paramètres

`object`

  Un objet contenu comme clé dans le dictionnaire.

### Valeurs de retour

Renvoie la valeur associée à l'objet passé en argument.

### Erreurs / Exceptions

Lance une Error en cas d'échec.

# WeakMap::offsetSet

(PHP 8)

WeakMap::offsetSet — Met à jour le dictionnaire avec une nouvelle paire clé-valeur

### Description

public function WeakMap::offsetSet(object `$object`, mixed `$value`): void

Met à jour le dictionnaire avec une nouvelle paire clé-valeur. Si la clé existait déjà, l'ancienne valeur est remplacée par la nouvelle.

### Liste de paramètres

`object`

  L'objet servant de clé à la paire clé-valeur.

`value`

  Les données arbitraires servant de valeur à la paire clé-valeur.

### Valeurs de retour

Aucune valeur n'est retournée.

# WeakMap::offsetUnset

(PHP 8)

WeakMap::offsetUnset — Supprime une entrée du dictionnaire

### Description

public function WeakMap::offsetUnset(object `$object`): void

Supprime une entrée du dictionnaire.

### Liste de paramètres

`object`

  L'objet clé à supprimer du dictionnaire.

### Valeurs de retour

Aucune valeur n'est retournée.

## Sommaire

- WeakMap::count — Compte le nombre d'entrées actives dans le dictionnaire
- WeakMap::getIterator — Récupère un itérateur externe
- WeakMap::offsetExists — Vérifie si un certain objet se trouve dans le dictionnaire
- WeakMap::offsetGet — Retourne la valeur indiquée par un certain objet
- WeakMap::offsetSet — Met à jour le dictionnaire avec une nouvelle paire clé-valeur
- WeakMap::offsetUnset — Supprime une entrée du dictionnaire

# L'interface Stringable

(PHP 8)

## Introduction

L'interface Stringable désigne une classe possédant une méthode __toString(). Contrairement à la plupart des interfaces, Stringable est implicitement présente sur toute classe pour laquelle la méthode magique __toString() est définie, et ce bien qu'elle puisse et devrait être déclarée explicitement.

Sa valeur principale est de permettre aux fonctions de vérifier le type par rapport au type d'union `string|Stringable` pour accepter soit une chaîne de caractères primitive, soit un objet pouvant être transtypé en chaîne de caractères.

## Sommaire de l'Interface

interface Stringable {
/* Méthodes */
public function __toString(): string
}

## Exemples

Exemple #1 Exemple simple

Cela utilise la promotion des propriétés du constructeur.

    <?php
    class IPv4Address implements Stringable {
        public function __construct(
            private string $oct1,
            private string $oct2,
            private string $oct3,
            private string $oct4,
        ) {}

        public function __toString(): string {
            return "$this->oct1.$this->oct2.$this->oct3.$this->oct4";
        }
    }

    function showStuff(string|Stringable $value) {
        // Pour un Stringable, cela appellera implicitement __toString().
        print $value;
    }

    $ip = new IPv4Address('123', '234', '42', '9');

    showStuff($ip);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    123.234.42.9

# Stringable::__toString

(PHP 8)

Stringable::__toString — Retourne la représentation de l'objet sous forme de chaîne

### Description

public function Stringable::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation d'un objet sous la forme d'une chaîne de caractères.

### Voir aussi

- __toString()

## Sommaire

- Stringable::__toString — Retourne la représentation de l'objet sous forme de chaîne

# L'interface UnitEnum

(PHP 8 >= 8.1.0)

## Introduction

L'interface UnitEnum est automatiquement appliquée à toutes les énumérations par le moteur. Elle ne peut pas être implémentée par des classes définies par l'utilisateur. Les énumérations ne peuvent pas surcharger ses méthodes, car les implémentations par défaut sont fournies par le moteur. Elle n'est disponible que pour les vérifications de type.

## Sommaire de l'Interface

interface UnitEnum {
/* Méthodes */
public static function cases(): array
}

# UnitEnum::cases

(PHP 8 >= 8.1.0)

UnitEnum::cases — Génère une liste de cas sur une énumération

### Description

public static function UnitEnum::cases(): array

Cette méthode retourne un tableau de tous les cas d'une énumération, dans l'ordre de leur déclaration.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de tous les cas définis de cette énumération, dans l'ordre de la déclaration.

### Exemples

Exemple #1 Utilisation de base

L'exemple suivant illustre la façon dont les cas d'énumération sont retournés.

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      enum(Suit::Hearts)
      [1]=>
      enum(Suit::Diamonds)
      [2]=>
      enum(Suit::Clubs)
      [3]=>
      enum(Suit::Spades)
    }

## Sommaire

- UnitEnum::cases — Génère une liste de cas sur une énumération

# L'interface BackedEnum

(PHP 8 >= 8.1.0)

## Introduction

L'interface BackedEnum est automatiquement appliquée aux énumérations avec valeur de base par le moteur. Elle ne peut pas être implémentée par des classes définies par l'utilisateur. Les énumérations ne peuvent pas surcharger ses méthodes, car les implémentations par défaut sont fournies par le moteur. Elle n'est disponible que pour les vérifications de type.

## Sommaire de l'Interface

interface BackedEnum extends UnitEnum {
/* Méthodes */
public static function from(int|string `$value`): static
public static function tryFrom(int|string `$value`): ?static
/* Méthodes héritées */
public static function UnitEnum::cases(): array
}

# BackedEnum::from

(PHP 8 >= 8.1.0)

BackedEnum::from — Convertit un scalaire en une instance d'enum

### Description

public static function BackedEnum::from(int|string `$value`): static

La méthode from() traduit une string ou un int en un cas Enum correspondant, s'il y en a un. S'il n'y a pas de cas correspondant défini, elle lancera une erreur ValueError.

### Liste de paramètres

`value`

  La valeur scalaire à faire correspondre à un cas d'énumération.

### Valeurs de retour

Une instance de cas de cette énumération.

### Exemples

Exemple #1 Utilisation de base

L'exemple suivant illustre la façon dont les cas d'énumération sont renvoyés.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::from('H');

    var_dump($h);

    $b = Suit::from('B');
    ?>

L'exemple ci-dessus va afficher :

    enum(Suit::Hearts)

    Fatal error: Uncaught ValueError: "B" is not a valid backing value for enum "Suit" in /file.php:15

### Voir aussi

- UnitEnum::cases() - Génère une liste de cas sur une énumération
- BackedEnum::tryFrom() - Associe un scalaire à une instance d'enum ou à null

# BackedEnum::tryFrom

(PHP 8 >= 8.1.0)

BackedEnum::tryFrom — Associe un scalaire à une instance d'enum ou à null

### Description

public static function BackedEnum::tryFrom(int|string `$value`): ?static

La méthode tryFrom() traduit une string ou un int en cas Enum correspondant, s'il y en a un. S'il n'y a pas de cas correspondant défini, elle retournera null.

### Liste de paramètres

`value`

  La valeur scalaire à faire correspondre à un cas d'énumération.

### Valeurs de retour

Une instance de cas de cette énumération, ou null si elle n'a pas été trouvée.

### Exemples

Exemple #1 Utilisation de base

L'exemple suivant illustre la façon dont les cas d'énumération sont renvoyés.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::tryFrom('H');

    var_dump($h);

    $b = Suit::tryFrom('B') ?? Suit::Spades;

    var_dump($b);
    ?>

L'exemple ci-dessus va afficher :

    enum(Suit::Hearts)
    enum(Suit::Spades)

### Voir aussi

- UnitEnum::cases() - Génère une liste de cas sur une énumération
- BackedEnum::from() - Convertit un scalaire en une instance d'enum

## Sommaire

- BackedEnum::from — Convertit un scalaire en une instance d'enum
- BackedEnum::tryFrom — Associe un scalaire à une instance d'enum ou à null

# La classe SensitiveParameterValue

(PHP 8 >= 8.2.0)

## Introduction

La classe SensitiveParameterValue permet d'envelopper des valeurs sensibles pour les protéger contre une exposition accidentelle.

Les valeurs des paramètres ayant l'attribut SensitiveParameter seront automatiquement enveloppées dans un objet SensitiveParameterValue dans les traces d'appels.

## Synopsis de la classe

final class SensitiveParameterValue {
/* Propriétés */
private readonly mixed $value;
/* Méthodes */
public function __construct(mixed `$value`)
public function __debugInfo(): array
public function getValue(): mixed
}

## Propriétés

value

  Valeur sensible à protéger contre une exposition accidentelle.

# SensitiveParameterValue::__construct

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__construct — Construit un nouvel objet SensitiveParameterValue

### Description

public function SensitiveParameterValue::__construct(mixed `$value`)

Construit un objet SensitiveParameterValue contenant une valeur sensible.

### Liste de paramètres

`value`

  Une valeur arbitraire qui devrait être stockée dans l'objet SensitiveParameterValue.

# SensitiveParameterValue::__debugInfo

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__debugInfo — Protège la valeur sensible contre une exposition accidentelle

### Description

public function SensitiveParameterValue::__debugInfo(): array

Retourne un tableau vide pour protéger la valeur sensible contre une exposition accidentelle lors de l'utilisation de var_dump().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau vide.

### Exemples

Exemple #1 Passer un objet SensitiveParameterValue à var_dump()

    <?php
    $s = new \SensitiveParameterValue('secret');

    var_dump($s);
    ?>

L'exemple ci-dessus va afficher :

    object(SensitiveParameterValue)#1 (0) {
    }

# SensitiveParameterValue::getValue

(PHP 8 >= 8.2.0)

SensitiveParameterValue::getValue — Retourne la valeur sensible

### Description

public function SensitiveParameterValue::getValue(): mixed

Retourne la valeur sensible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La valeur sensible.

### Exemples

Exemple #1 Exemple de SensitiveParameterValue::getValue()

    <?php
    $s = new \SensitiveParameterValue('secret');

    echo "La valeur protégée est: ", $s->getValue(), "\n";
    ?>

L'exemple ci-dessus va afficher :

    La valeur protégée est: secret

## Sommaire

- SensitiveParameterValue::__construct — Construit un nouvel objet SensitiveParameterValue
- SensitiveParameterValue::__debugInfo — Protège la valeur sensible contre une exposition accidentelle
- SensitiveParameterValue::getValue — Retourne la valeur sensible

# La classe __PHP_Incomplete_Class

(PHP 4 >=4.0.1, PHP 5, PHP 7, PHP 8)

## Introduction

Créée par unserialize(), lorsque l'on essaie de désérialiser une classe non définie ou une classe non listée dans les `allowed_classes` du tableau `options` de unserialize().

Avant PHP 7.2.0, utiliser is_object() sur la classe __PHP_Incomplete_Class retournait `false`. À partir de PHP 7.2.0, `true` sera retourné.

## Synopsis de la classe

#[\AllowDynamicProperties]
final class __PHP_Incomplete_Class {
}

Cette classe n'a pas de propriétés ou de méthodes par défaut. Lorsqu'elle est créée par unserialize(), en plus de toutes les propriétés et valeurs désérialisées l'objet aura une propriété `__PHP_Incomplete_Class_Name` qui contiendra le nom de la classe désérialisée.

## Historique

Version | Description
--- | ---
8.0.0 | Cette classe est désormais `final`.

## Exemples

Exemple #1 Créée par unserialize()

    <?php

    class MyClass
    {
        public string $property = "myValue";
    }

    $myObject = new MyClass;

    $foo = serialize($myObject);

    // désérialise tous les objets en objets __PHP_Incomplete_Class
    $disallowed = unserialize($foo, ["allowed_classes" => false]);

    var_dump($disallowed);

    // désérialise tous les objets en objet __PHP_Incomplete_Class sauf ceux des classes MyClass2 et MyClass3
    $disallowed2 = unserialize($foo, ["allowed_classes" => ["MyClass2", "MyClass3"]]);

    var_dump($disallowed2);

    // désérialise une classe non définie en objet __PHP_Incomplete_Class
    $undefinedClass = unserialize('O:16:"MyUndefinedClass":0:{}');

    var_dump($undefinedClass);

L'exemple ci-dessus va afficher :

    object(__PHP_Incomplete_Class)#2 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#3 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#4 (1) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(16) "MyUndefinedClass"
    }

# Attributs prédéfinis

## Sommaire

- Attribute
- AllowDynamicProperties
- DelayedTargetValidation
- Deprecated
- NoDiscard
- Override
- ReturnTypeWillChange
- SensitiveParameter

PHP fournit des attributs prédéfinis qui peuvent être utilisés.

# La classe Attribute

(PHP 8)

## Introduction

Les attributs permettent d'ajouter des informations de métadonnées structurées et lisibles par la machine sur les déclarations dans le code: les classes, les méthodes, les fonctions, les paramètres, les propriétés et les constantes de classe peuvent être la cible d'un attribut. Les métadonnées définies par les attributs peuvent ensuite être inspectées au moment de l'exécution à l'aide de l'API de Réflexion. Les attributs peuvent donc être considérés comme un langage de configuration intégré directement dans le code.

## Synopsis de la classe

#[\Attribute]
final class Attribute {
/* Constantes */
const int TARGET_CLASS;
const int TARGET_FUNCTION;
const int TARGET_METHOD;
const int TARGET_PROPERTY;
const int TARGET_CLASS_CONSTANT;
const int TARGET_PARAMETER;
const int TARGET_CONSTANT;
const int TARGET_ALL;
const int IS_REPEATABLE;
/* Propriétés */
public int $flags;
/* Méthodes */
public function __construct(int `$flags` = Attribute::TARGET_ALL)
}

## Constantes pré-définies

Attribute::TARGET_CLASS

Attribute::TARGET_FUNCTION

Attribute::TARGET_METHOD

Attribute::TARGET_PROPERTY

Attribute::TARGET_CLASS_CONSTANT

Attribute::TARGET_PARAMETER

Attribute::TARGET_CONSTANT

Attribute::TARGET_ALL

Attribute::IS_REPEATABLE

## Propriétés

flags

## Historique

Version | Description
--- | ---
8.5.0 | Ajout de `Attribute::TARGET_CONSTANT`.

## Voir aussi

Aperçu des attributs

# Attribute::__construct

(PHP 8)

Attribute::__construct — Construit une nouvelle instance de Attribute

### Description

public function Attribute::__construct(int `$flags` = `Attribute::TARGET_ALL`)

Construit une nouvelle instance de Attribute.

### Liste de paramètres

`flags`

## Sommaire

- Attribute::__construct — Construit une nouvelle instance de Attribute

# La classe AllowDynamicProperties

(PHP 8 >= 8.2.0)

## Introduction

Cet attribut est utilisé pour marquer les classes qui autorisent les propriétés dynamiques.

> Note: Bien que les attributs eux-mêmes ne soient pas hérités, l'effet de l'attribut `AllowDynamicProperties` l'est. Les classes enfants d'une classe marquée avec cet attribut autoriseront également les propriétés dynamiques, même si elles ne déclarent pas explicitement l'attribut.

## Synopsis de la classe

#[\Attribute]
final class AllowDynamicProperties {
/* Méthodes */
public function __construct()
}

## Exemples

Les propriétés dynamiques sont obsolètes à partir de PHP 8.2.0, donc les utiliser sans marquer la classe avec cet attribut émettra un avis d'obsolescence.

Exemple #1 AllowDynamicProperties avec une propriété inexistante

    <?php
    class DefaultBehaviour { }

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties { }

    $o1 = new DefaultBehaviour();
    $o2 = new ClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;
    ?>

Résultat de l'exemple ci-dessus en PHP 8.2 :

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 10

Exemple #2 AllowDynamicProperties avec une propriété inexistante dans une classe héritée

    <?php
    class DefaultBehaviour { }

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties { }

    class InheritedClassAllowsDynamicProperties extends ClassAllowsDynamicProperties { }

    $o1 = new DefaultBehaviour();
    $o2 = new InheritedClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;
    ?>

Résultat de l'exemple ci-dessus en PHP 8.2 :

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 12

## Voir aussi

Aperçu des attributs

# AllowDynamicProperties::__construct

(PHP 8 >= 8.2.0)

AllowDynamicProperties::__construct — Construit une nouvelle instance d'attribut AllowDynamicProperties

### Description

public function AllowDynamicProperties::__construct()

Construit une nouvelle instance de AllowDynamicProperties.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

## Sommaire

- AllowDynamicProperties::__construct — Construit une nouvelle instance d'attribut AllowDynamicProperties

# L'attribut DelayedTargetValidation

(PHP 8 >= 8.5.0)

## Introduction

Cet attribut diffère les erreurs de validation de cible des attributs internes, du moment de la compilation à celui où l'attribut est instancié via l'API de réflexion.

Lorsqu'il est appliqué à une déclaration, toute utilisation invalide d'attributs internes sur la même cible ne déclenche pas d'erreur à la compilation. À la place, la validation est différée et effectuée lorsque l'attribut est instancié via ReflectionAttribute::newInstance().

Cela vise principalement la compatibilité ascendante, permettant à du code d'utiliser des attributs susceptibles d'acquérir de nouvelles cibles valides dans de futures versions de PHP, sans échouer sur les versions plus anciennes.

## Synopsis de la classe

#[\Attribute]
final class DelayedTargetValidation {
}

## Exemples

Exemple #1 Différer la validation d'une cible invalide

    <?php

    class Base {
        protected function foo(): void {}
    }

    class Child extends Base {

        #[\DelayedTargetValidation]
        #[\Override]
        public const NAME = 'child';

        #[\Override]
        protected function foo(): void {}
    }

Sur les versions de PHP où Override n'est pas autorisé sur les constantes de classe, cela ne produit pas d'erreur à la compilation.

Exemple #2 La validation a lieu lors de la réflexion

    <?php

    $reflection = new ReflectionClassConstant(Child::class, 'NAME');

    foreach ($reflection->getAttributes() as $attribute) {
        $attribute->newInstance(); // Peut lever une exception si invalide
    }

Lorsqu'un attribut quelconque appliqué à la même cible (autre que DelayedTargetValidation lui-même) est instancié via la réflexion à l'aide de ReflectionAttribute::newInstance(), la validation de cible est effectuée et une exception peut être levée si l'attribut est utilisé sur une cible non prise en charge.

## Notes

Cet attribut n'affecte que la validation de cible des attributs internes.

Il ne supprime pas la validation fonctionnelle effectuée par ces attributs. Par exemple, Override émettra toujours une erreur si une méthode ne redéfinit pas réellement une méthode parente.

## Voir aussi

- Vue d'ensemble des attributs
- Override

# L'attribut Deprecated

(PHP 8 >= 8.4.0)

## Introduction

Cet attribut est utilisé pour marquer une fonctionnalité comme obsolète. L'utilisation d'une fonctionnalité obsolète entraînera l'émission d'une erreur `E_USER_DEPRECATED`.

## Synopsis de la classe

#[\Attribute]
final class Deprecated {
/* Propriétés */
public readonly ?string $message;
public readonly ?string $since;
/* Méthodes */
public function __construct(?string `$message` = null, ?string `$since` = null)
}

## Propriétés

message

  Un message optionnel expliquant la raison de l'obsolescence et la fonctionnalité de remplacement possible. Sera inclus dans le message d'obsolescence émis.

since

  Une chaîne optionnelle indiquant depuis quand la fonctionnalité est obsolète. Le contenu n'est pas validé par PHP et peut contenir un numéro de version, une date ou toute autre valeur considérée comme appropriée. Sera inclus dans le message d'obsolescence émis.

  Une fonctionnalité qui fait partie de PHP utilisera Major.Minor comme valeur de since, par exemple `'8.4'`.

## Exemples

    <?php

    #[\Deprecated(message: "use safe_replacement() instead", since: "1.5")]
    function unsafe_function()
    {
       echo "This is unsafe", PHP_EOL;
    }

    unsafe_function();

    ?>

La sortie de l'exemple ci-dessus en PHP 8.4 est similaire à :

    Deprecated: Function unsafe_function() is deprecated since 1.5, use safe_replacement() instead in example.php on line 9
    This is unsafe

## Voir aussi

- Aperçu des attributs
- ReflectionFunctionAbstract::isDeprecated()
- ReflectionClassConstant::isDeprecated()
- `E_USER_DEPRECATED`

# Deprecated::__construct

(PHP 8 >= 8.4.0)

Deprecated::__construct — Construit une nouvelle instance de l'attribut Deprecated

### Description

public function Deprecated::__construct(?string `$message` = `null`, ?string `$since` = `null`)

Construit une nouvelle instance de Deprecated.

### Liste de paramètres

`message`

  La valeur de la propriété message.

`since`

  La valeur de la propriété since.

## Sommaire

- Deprecated::__construct — Construit une nouvelle instance de l'attribut Deprecated

# L'attribut NoDiscard

(PHP 8 >= 8.5.0)

## Introduction

Cet attribut peut être utilisé pour indiquer que la valeur de retour d'une fonction ou d'une méthode ne doit pas être ignorée. Si la valeur de retour n'est utilisée d'aucune manière, un avertissement sera émis.

Cela est utile pour les fonctions où ne pas vérifier la valeur de retour est probablement un bogue.

Pour ignorer intentionnellement la valeur de retour d'une telle fonction, il est possible d'utiliser le cast (void) pour supprimer l'avertissement.

> Note: Étant donné que les attributs sont conçus pour être rétrocompatibles, `#[\NoDiscard]` peut être ajouté aux fonctions et méthodes même lorsque PHP 8.4 ou inférieur est supporté, il ne fera simplement rien. Sur PHP 8.5 et supérieur, un avertissement sera émis si le résultat n'est pas utilisé. Pour supprimer l'avertissement sans utiliser `(void)`, qui n'est pas supporté avant PHP 8.5, il est possible d'utiliser une variable comme `$_`.

> Note: `#[\NoDiscard]` s'applique à la déclaration de fonction ou de méthode spécifique sur laquelle il est écrit, et l'avertissement est émis en fonction de la déclaration réellement appelée. Par conséquent, ajouter `#[\NoDiscard]` à une méthode d'interface ou à une méthode abstraite n'émet pas d'avertissement, car la méthode invoquée est la méthode d'implémentation ou de redéfinition. De même, une méthode qui redéfinit une méthode `#[\NoDiscard]` n'émet pas l'avertissement à moins d'être elle-même marquée avec l'attribut. À l'inverse, une méthode importée depuis un trait conserve l'attribut, car la méthode du trait est copiée dans la classe utilisatrice comme si elle y était déclarée.

## Synopsis de la classe

#[\Attribute]
final class NoDiscard {
/* Propriétés */
public readonly ?string $message;
/* Méthodes */
public function __construct(?string `$message` = null)
}

## Propriétés

message
  Un message optionnel expliquant pourquoi la valeur de retour ne doit pas être ignorée.

## Exemples

Exemple #1 Utilisation basique

    <?php

    /**
     * Traite tous les éléments donnés et retourne un tableau avec les résultats de
     * l'opération pour chaque élément. `null` indique un succès et une Exception
     * indique une erreur. Les clés du tableau de résultat correspondent aux clés du tableau $items.
     *
     * @param array<string> $items
     * @return array<null|Exception>
     */
    #[\NoDiscard("as processing might fail for individual items")]
    function bulk_process(array $items): array {
        $results = [];

        foreach ($items as $key => $item) {
            if (\random_int(0, 9999) < 9999) {
                // On prétend faire quelque chose d'utile avec $item,
                // ce qui réussira dans 99,99% des cas.
                echo "Processing {$item}", PHP_EOL;
                $error = null;
            } else {
                $error = new \Exception("Failed to process {$item}.");
            }

            $results[$key] = $error;
        }

        return $results;
    }

    bulk_process($items);

    ?>

La sortie de l'exemple ci-dessus en PHP 8.5 est similaire à :

    Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), as processing might fail for individual items

Exemple #2 Ignorer intentionnellement la valeur de retour

    <?php

    #[\NoDiscard]
    function some_command(): int {
        return 1;
    }

    // Supprimer l'avertissement avec (void) - PHP 8.5+
    (void) some_command();

    // Pour la compatibilité avec les versions de PHP antérieures à 8.5, utiliser une variable temporaire
    $_ = some_command();

    ?>

## Voir aussi

- Vue d'ensemble des attributs

# NoDiscard::__construct

(PHP 8 >= 8.5.0)

NoDiscard::__construct — Construit une nouvelle instance de l'attribut NoDiscard

### Description

public function NoDiscard::__construct(?string `$message` = `null`)

Construit une nouvelle instance de NoDiscard.

### Liste de paramètres

`message`
  La valeur de la propriété message.

## Sommaire

- NoDiscard::__construct — Construit une nouvelle instance de l'attribut NoDiscard

# La classe Override

(PHP 8 >= 8.3.0)

## Introduction

Cet attribut est utilisé pour indiquer qu'une méthode ou propriété est destinée à surcharger une méthode ou propriété d'une classe parente ou qu'elle implémente une méthode ou propriété définie dans une interface.

Si aucune méthode ou propriété portant le même nom n'existe dans une classe parente ou dans une interface implémentée, une erreur de compilation sera émise.

L'attribut ne peut pas être utilisé sur la méthode __construct(), car elle est exclue des vérifications de signature.

## Synopsis de la classe

#[\Attribute]
final class Override {
/* Méthodes */
public function __construct()
}

## Historique

Version | Description
--- | ---
8.5.0 | Override peut désormais être appliqué aux propriétés.

## Exemples

Exemple #1 Usage avec les méthodes

    <?php

    class Base {
        protected function foo(): void {}
    }

    final class Extended extends Base {
        #[\Override]
        protected function boo(): void {}
    }

    ?>

Résultat de l'exemple ci-dessus en PHP 8.3 est similaire à :

    Fatal error: Extended::boo() has #[\Override] attribute, but no matching parent method exists

Exemple #2 Usage avec les propriétés

    <?php

    class Base {
        protected string $foo;
    }

    final class Extended extends Base {
        #[\Override]
        protected string $boo;
    }

    ?>

La sortie de l'exemple ci-dessus en PHP 8.5 est similaire à :

    Fatal error: Extended::$boo has #[\Override] attribute, but no matching parent property exists

## Voir aussi

- Présentation des attributs

# Override::__construct

(PHP 8 >= 8.3.0)

Override::__construct — Construit une nouvelle instance de l'attribut Override

### Description

public function Override::__construct()

Construit une nouvelle instance de Override.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

## Sommaire

- Override::__construct — Construit une nouvelle instance de l'attribut Override

# La classe ReturnTypeWillChange

(PHP 8 >= 8.1.0)

## Introduction

La plupart des méthodes internes non finales exigent désormais que les méthodes de surcharge déclarent un type de retour compatible, sinon un avis d'obsolescence est émis lors de la validation de l'héritage. Cela introduit une phase de type de retour provisoire : le moteur émet un avis d'obsolescence plutôt qu'une erreur fatale lorsque les types de retour sont incompatibles, avant qu'ils ne soient imposés dans une version future. Dans le cas où le type de retour ne peut pas être déclaré pour une méthode de surcharge en raison de problèmes de compatibilité entre les versions de PHP, un attribut `#[\ReturnTypeWillChange]` peut être ajouté pour taire l'avis d'obsolescence.

Avertissement

L'attribut ReturnTypeWillChange supprime les avis d'obsolescence durant la phase de type de retour provisoire uniquement. Il n'a aucun effet lors de la surcharge de méthodes définies dans des classes définies par l'utilisateur. Une fois que les méthodes internes adopteront des types stricts, les incompatibilités dans les signatures des méthodes de surcharge provoqueront une erreur fatale et cet attribut n'aura plus aucun effet.

## Synopsis de la classe

#[\Attribute]
final class ReturnTypeWillChange {
/* Méthodes */
public function __construct()
}

## Voir aussi

Aperçu des attributs

# ReturnTypeWillChange::__construct

(PHP 8 >= 8.1.0)

ReturnTypeWillChange::__construct — Construit une nouvelle instance de l'attribut ReturnTypeWillChange

### Description

public function ReturnTypeWillChange::__construct()

Construit une nouvelle instance de ReturnTypeWillChange.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

## Sommaire

- ReturnTypeWillChange::__construct — Construit une nouvelle instance de l'attribut ReturnTypeWillChange

# L'attribut SensitiveParameter

(PHP 8 >= 8.2.0)

## Introduction

Cet attribut est utilisé pour indiquer qu'un paramètre est sensible et que sa valeur devrait être expurgée s'il est présent dans une trace d'appels.

## Synopsis de la classe

#[\Attribute]
final class SensitiveParameter {
/* Méthodes */
public function __construct()
}

## Exemples

    <?php

    function defaultBehavior(
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    function sensitiveParametersWithAttribute(
        #[\SensitiveParameter]
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    try {
        defaultBehavior('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

    try {
        sensitiveParametersWithAttribute('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

    ?>

Résultat de l'exemple ci-dessus en PHP 8.2 est similaire à :

    Exception: Error! in example.php:7
    Stack trace:
    #0 example.php(19): defaultBehavior('password', 'normal')
    #1 {main}

    Exception: Error! in example.php:15
    Stack trace:
    #0 example.php(25): sensitiveParametersWithAttribute(Object(SensitiveParameterValue), 'normal')
    #1 {main}

## Voir aussi

- Aperçu des attributs
- SensitiveParameterValue

# SensitiveParameter::__construct

(PHP 8 >= 8.2.0)

SensitiveParameter::__construct — Construit une nouvelle instance d'attribut SensitiveParameter

### Description

public function SensitiveParameter::__construct()

Construit une nouvelle instance de SensitiveParameter.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

## Sommaire

- SensitiveParameter::__construct — Construit une nouvelle instance d'attribut SensitiveParameter

# Options et paramètres de contexte

PHP offre diverses options et paramètres de contexte, qui peuvent être utilisés avec tous les systèmes de fichiers et enveloppes de flux. Le contexte est créé avec la fonction stream_context_create(). Les options sont définies avec la fonction stream_context_set_option() et les paramètres, avec la fonction stream_context_set_params().

# Options de contexte des sockets

Options de contexte des sockets — Liste des options de contexte des sockets

### Description

Les options de contexte des sockets sont disponibles pour toutes les enveloppes fonctionnant via les sockets, comme `tcp`, `http` et `ftp`.

### Options

`bindto`

  Utilisé pour spécifier l'adresse IP (soit IPv4 ou IPv6), et/ou le numéro du port que PHP utilisera pour accéder au réseau. La syntaxe est `ip:port` pour les adresses IPv4, et `[ip]:port` pour les adresses IPv6. Le fait de définir l'IP ou le port à `0` permettra au système de choisir lui-même le port et/ou l'IP.

  > Note:

  > Vu que FTP crée 2 sockets de connexion lors d'une opération normale, le numéro du port ne peut être spécifié en utilisant cette option.

`backlog`

  Utilisé pour limiter le nombre de connexions actives dans la liste d'attente du socket.

  > Note:

  > Ceci n'est applicable qu'à la fonction stream_socket_server().

`ipv6_v6only`

  Substitue le système d'exploitation par défaut concernant le mappage d'IPv4 dans IPv6.

  > Note:

  > Ceci est important en particulier lors d'une tentative d'écoute sur les adresses IPv4 séparément alors qu'il existe une liaison sur `[::]`.

  > Ceci n'est applicable qu'à la fonction stream_socket_server().

`so_reuseport`

  Permet plusieurs liaisons d'une même paire ip:port, même à partir de processus distincts.

  > Note:

  > Ceci n'est applicable qu'à la fonction stream_socket_server().

`so_broadcast`

  Permet d'envoyer et de recevoir des données vers/à partir d'adresses de diffusion.

  > Note:

  > Ceci n'est applicable qu'à la fonction stream_socket_server().

`tcp_nodelay`

  Mettre la valeur à `true` définira `SOL_TCP,NO_DELAY=1` correctement, ce qui désactivera l'algorithme TCP Nagle.

### Historique

Version | Description
--- | ---
7.1.0 | Ajout du paramètre `tcp_nodelay`.
7.0.1 | Ajout du paramètre `ipv6_v6only`.

### Exemples

Exemple #1 Exemple d'utilisation du paramètre `bindto`

    <?php
    // Connexion à Internet en utilisant l'IP '192.168.0.100'
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:0',
        ),
    );

    // Connexion à Internet en utilisant l'IP '192.168.0.100' et le port '7000'
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:7000',
        ),
    );

    // Connexion à Internet en utilisant l'adresse IPv6 '2001:db8::1'
    // et le port '7000'
    $opts = array(
        'socket' => array(
            'bindto' => '[2001:db8::1]:7000',
        ),
    );

    // Connexion à Internet en utilisant le port '7000'
    $opts = array(
        'socket' => array(
            'bindto' => '0:7000',
        ),
    );

    // Création du contexte...
    $context = stream_context_create($opts);

    // ...et l'utilise pour récupérer les données
    echo file_get_contents('http://www.example.com', false, $context);

    ?>

# Options de contexte HTTP

Options de contexte HTTP — Liste des options de contexte HTTP

### Description

Options de contexte pour les protocoles `http://` et `https://`.

### Options

`method` string

  `GET`, `POST`, ou n'importe quelle autre méthode HTTP supportée par le serveur distant.

  Par défaut, vaut `GET`.

`header` array ou string

  En-têtes supplémentaires à envoyer lors de la requête. Les valeurs de cette option écraseront les autres valeurs (comme `User-agent:`, `Host:`, et `Authentication:`), même en suivant les redirections `Location:`. Ainsi, il n'est pas recommandé de définir l'en-tête `Host:`, si `follow_location` est activé.

  Une chaîne de caractères doit contenir des paires `Clé : valeur` délimitées par `\r\n`, par exemple : `"Content-Type: application/json\r\nConnection: close"`. Un tableau doit contenir une liste de paires `Clé : valeur`, par exemple : `["Content-Type: application/json", "Connection: close"]`.

`user_agent` string

  Valeur à envoyer avec l'en-tête `User-Agent:`. Cette valeur ne doit être utilisée que si l'agent utilisateur n'est pas spécifié dans l'option de contexte `header` ci-dessus.

  Par défaut, la valeur de l'option de configuration user_agent du fichier php.ini sera utilisée.

`content` string

  Les données supplémentaires à envoyer après les en-têtes. Typiquement utilisées lors des requêtes POST ou PUT.

`proxy` string

  URI de l'adresse du proxy (e.g. `tcp://proxy.example.com:5100`).

`request_fulluri` bool

  Lorsque défini à `true`, l'URI entière sera utilisée lors de la construction de la requête (e.g. `GET http://www.example.com/path/to/file.html HTTP/1.0`). Bien que ce format de demande ne soit pas standard, certains serveurs de proxy le demandent.

  Par défaut, vaut `false`.

`follow_location` int

  Suit les redirections `Location`. À définir à `0` pour désactiver.

  Par défaut, vaut `1`.

`max_redirects` int

  Le nombre maximal de redirections à suivre. La valeur `1` ou inférieure signifie qu'aucune redirection ne sera suivie.

  Par défaut, vaut `20`.

`protocol_version` float

  Version du protocole HTTP.

  Par défaut, vaut `1.1` à partir de PHP 8.0.0 ; antérieur à cette version, la valeur par défaut était `1.0`.

`timeout` float

  Délai maximal d'attente pour la lecture en secondes, sous la forme d'un nombre décimal (e.g. `10.5`).

  Par défaut, la valeur de l'option de configuration default_socket_timeout du fichier php.ini sera utilisée.

`ignore_errors` bool

  Récupère le contenu même lors de la réception d'un code d'échec.

  Par défaut, vaut `false`.

### Exemples

Exemple #1 Récupération d'une page et envoi de données POST

    <?php

    $postdata = http_build_query(
        [
            'var1' => 'du contenu',
            'var2' => 'doh',
        ]
    );

    $opts = [
        'http' => [
            'method'  => 'POST',
            'header'  => 'Content-type: application/x-www-form-urlencoded',
            'content' => $postdata,
        ]
    ];

    $context = stream_context_create($opts);

    $result = file_get_contents('http://example.com/submit.php', false, $context);

    ?>

Exemple #2 Ignore les redirections mais récupère les en-têtes et le contenu

    <?php

    $url = "http://www.example.org/header.php";

    $opts = [
        'http' => [
            'method'        => 'GET',
            'max_redirects' => '0',
            'ignore_errors' => '1',
        ]
    ];

    $context = stream_context_create($opts);
    $stream = fopen($url, 'r', false, $context);

    // informations sur les en-têtes et métadonnées du flux
    var_dump(stream_get_meta_data($stream));

    // données actuelles de $url
    var_dump(stream_get_contents($stream));
    fclose($stream);
    ?>

### Notes

> Note: Options de contexte du flux sous-jacent
> Des options de contexte supplémentaires peuvent être supportées par le transport sous-jacent. Pour les flux `http://`, se référer aux options de contexte du transport `tcp://`. Pour les flux `https://`, se référer aux options de contexte du transport `ssl://`.

> Note: Ligne de statut HTTP
> Lorsque ce gestionnaire de flux suit une redirection, `wrapper_data`, retourné par la fonction stream_get_meta_data() ne doit pas contenir obligatoirement la ligne de statut HTTP qui s'applique à des données de contenu à l'index `0`.

>     array (
>       'wrapper_data' =>
>       array (
>         0 => 'HTTP/1.0 301 Moved Permanently',
>         1 => 'Cache-Control: no-cache',
>         2 => 'Connection: close',
>         3 => 'Location: http://example.com/foo.jpg',
>         4 => 'HTTP/1.1 200 OK',
>         ...

> La première requête retourne une `301` (redirection permanente), ainsi, le gestionnaire de flux suit automatiquement la redirection pour récupérer une réponse `200` (index = `4`).

### Voir aussi

- http://
- Options de contexte des sockets
- Options de contexte SSL

# Options de contexte FTP

Options de contexte FTP — Liste des options de contexte FTP

### Description

Options de contexte pour les protocoles `ftp://` et `ftps://`.

### Options

`overwrite` booléen

  Permet l'écrasement des fichiers existants sur le serveur distant. Ne s'applique qu'en mode écriture.

  Par défaut, `false`.

`resume_pos` entier

  Position dans le fichier à partir de laquelle on commence le transfert. Ne s'applique qu'en mode lecture.

  Par défaut, vaut `0` (Début du fichier).

`proxy` chaîne de caractères

  URI de l'adresse du proxy FTP. Ne s'applique qu'aux opérations de lecture de fichiers. Par exemple : `tcp://squid.example.com:8000`.

### Notes

> Note: Options de contexte du flux sous-jacent
> Des options de contexte supplémentaires peuvent être supportées par le transport sous-jacent. Pour les flux `ftp://`, se référer aux options de contexte du transport `tcp://`. Pour les flux `ftps://`, se référer aux options de contexte du transport `ssl://`.

### Voir aussi

- ftp://
- Options de contexte des sockets
- Options de contexte SSL

# Options de contexte SSL

Options de contexte SSL — Liste des options de contexte SSL

### Description

Options de contexte pour les protocoles `ssl://` et `tls://`.

### Options

`peer_name` string

  Nom du pair à utiliser. Si cette valeur n'est pas définie, alors le nom sera deviné en se basant sur le nom d'hôte utilisé lors de l'ouverture du flux.

`verify_peer` bool

  Nécessite une vérification du certificat SSL utilisé.

  Par défaut, vaut `true`.

`verify_peer_name` bool

  Nécessite la vérification du nom du pair.

  Par défaut, vaut `true`.

`allow_self_signed` bool

  Permet les certificats autosignés. Requiert le paramètre `verify_peer`.

  Par défaut, vaut `false`

`cafile` string

  Endroit où se trouve le fichier de l'autorité du certificat sur le système de fichiers local et qui devra être utilisé avec l'option de contexte `verify_peer` pour identifier le pair distant.

`capath` string

  Si `cafile` n'est pas spécifié ou si le certificat n'a pas été trouvé, une recherche dans le dossier pointé par `capath` sera effectuée afin d'y trouver un certificat valide. `capath` doit être un dossier de certificats correctement hachés.

`local_cert` string

  Chemin vers le certificat local, sur le système de fichiers. Ce doit être un fichier encodé PEM qui contient le certificat et la clé privée. Il peut, optionnellement, contenir la chaîne de certification de l'émetteur. La clé privée peut également être contenue dans un fichier distinct spécifié par `local_pk`.

`local_pk` string

  Chemin d'accès au fichier de clé privée locale sur le système de fichiers dans le cas de fichiers distincts pour le certificat (`local_cert`) et la clé privée.

`passphrase` string

  La phrase de passe avec laquelle le fichier `local_cert` a été encodé.

`verify_depth` int

  Échoue si la chaîne de certification est trop profonde.

  Par défaut, aucune vérification.

`ciphers` string

  Définit la liste des chiffrements. Le format de la chaîne est décrit sur la page » ciphers(1).

  Par défaut, vaut `DEFAULT`.

`capture_peer_cert` bool

  Si défini à `true`, une option de contexte `peer_certificate` sera créée, contenant le certificat du pair.

`capture_peer_cert_chain` bool

  Si défini à `true`, une option de contexte `peer_certificate_chain` sera créée, contenant la chaîne de certification.

`SNI_enabled` bool

  Si vaut `true`, l'indication sur le nom du serveur sera activée. Le fait d'activer SNI permet d'utiliser plusieurs certificats sur la même adresse IP.

`disable_compression` bool

  Si défini, la compression TLS sera désactivée. Cela peut aider à atténuer le vecteur d'attaque CRIME.

`peer_fingerprint` string | array

  Interrompt la connexion lorsque le condensé du certificat distant ne correspond pas au hachage spécifié.

  Lorsqu'une chaîne de caractères est utilisée, la longueur va déterminer l'algorithme de hachage utilisé, soit "md5" (32), soit "sha1" (40).

  Lorsqu'un tableau est utilisé, la clé indique le nom de l'algorithme de hachage, et chaque valeur correspondante représente le condensé attendu.

`security_level` int

  Définit le niveau de sécurité. Si non spécifié, le niveau de sécurité par défaut de la bibliothèque est utilisé. Les niveaux de sécurité sont décrits dans » SSL_CTX_get_security_level(3).

  Disponible à partir de PHP 7.2.0 et OpenSSL 1.1.0.

### Historique

Version | Description
--- | ---
7.2.0 | Ajout de `security_level`. Requiert OpenSSL >= 1.1.0.

### Notes

> Note: Vu que `ssl://` est un protocole sous-jacent pour les enveloppes `https://` et `ftps://`, toutes les options de contexte appliquées à `ssl://` seront également appliquées à `https://` et `ftps://`.

> Note: Afin que SNI (Server Name Indication) soit disponible, PHP doit être compilé avec OpenSSL 0.9.8j ou supérieur. La constante `OPENSSL_TLSEXT_SERVER_NAME` permet de déterminer si SNI est supporté ou non.

### Voir aussi

- Options de contexte des sockets

# Les options du contexte Phar

Les options du contexte Phar — Liste des options du contexte Phar

### Description

Les options de contexte pour l'enveloppe `phar://`.

### Options

`compress` int

  Une des constantes de compression Phar.

`metadata` mixed

  Les méta-données Phar. Voir Phar::setMetadata().

### Voir aussi

- phar://
- Le flux Phar

# Paramètres de contexte

Paramètres de contexte — Liste des paramètres de contexte

### Description

Ces `paramètres` peuvent être définis sur un `contexte`, en utilisant la fonction stream_context_set_params().

### Liste de paramètres

`notification` callable

  Une fonction de rappel (callable), à appeler lorsqu'un événement survient sur le flux.

  Voir la fonction stream_notification_callback pour plus de détails.

# Options de contexte Zip

Options de contexte Zip — Liste des options de contexte Zip

### Description

Les options de contexte Zip sont disponibles pour les enveloppes (wrapper) `zip`.

### Options

`password`

  Utilisé pour spécifier un mot de passe à utiliser pour les archives chiffrées.

### Historique

Version | Description
--- | ---
7.2.0, PECL zip 1.14.0 | Ajout du paramètre `password`.

### Exemples

Exemple #1 Exemple avec une utilisation simple du paramètre `password`

    <?php
    // Lire l'archive chiffrée
    $opts = array(
        'zip' => array(
            'password' => 'secret',
        ),
    );
    // créer le contexte...
    $context = stream_context_create($opts);

    // ...et l'utiliser pour récupérer les données
    echo file_get_contents('zip://test.zip#test.txt', false, $context);

    ?>

# Options de contexte Zlib

Options de contexte Zlib — Liste des options de contexte Zlib

### Description

Les options de contexte Zlib sont disponibles pour les enveloppes `zlib`.

### Options

`level`

  Permet de spécifier le niveau de compression (`0` - `9`).

### Historique

Version | Description
--- | ---
7.3.0 | `level` a été ajouté.

## Sommaire

- Options de contexte des sockets — Liste des options de contexte des sockets
- Options de contexte HTTP — Liste des options de contexte HTTP
- Options de contexte FTP — Liste des options de contexte FTP
- Options de contexte SSL — Liste des options de contexte SSL
- Les options du contexte Phar — Liste des options du contexte Phar
- Paramètres de contexte — Liste des paramètres de contexte
- Options de contexte Zip — Liste des options de contexte Zip
- Options de contexte Zlib — Liste des options de contexte Zlib

# Liste des protocoles et des gestionnaires supportés

PHP dispose de nombreux gestionnaires pour différents types de protocoles de style URL, à utiliser avec les fonctions de manipulation de fichiers telles que fopen(), copy(), file_exists() et filesize(). En plus de ces gestionnaires, il est possible d'écrire des gestionnaires personnalisés et de les enregistrer avec la fonction stream_wrapper_register().

> Note: La syntaxe d'URL utilisée pour décrire un gestionnaire est exclusivement de la forme `scheme://...`. Les syntaxes de la forme `scheme:/` et `scheme:` ne sont pas supportées.

# file://

file:// — Accès au système de fichiers local

### Description

`file://` est l'enveloppe par défaut utilisée avec PHP et représente le système de fichiers local. Lorsqu'un chemin relatif est spécifié (un chemin qui ne commence pas par `/`, `\`, `\\`, ou une lettre de lecteur Windows), le chemin fourni sera appliqué au répertoire de travail actuel. Dans de nombreux cas, il s'agit du répertoire dans lequel le script se trouve, à moins qu'il n'ait été modifié. Avec le CLI SAPI, cela par défaut correspond au répertoire à partir duquel le script a été appelé.

Avec certaines fonctions comme fopen() et file_get_contents(), `include_path` peut éventuellement être analysé pour y trouver les fichiers, si un chemin relatif est fourni.

### Utilisation

- /chemin/vers/fichier.ext
- chemin/relatif/vers/fichier.ext
- fichierDansCwd.ext
- C:/chemin/vers/fichierWindows.ext
- C:\chemin\vers\fichierWindows.ext
- \\smbserver\partage\chemin\vers\fichierWindows.ext
- file:///chemin/vers/fichier.ext

### Options

Résumé de l'enveloppe
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Non
Autorise la lecture | Oui
Autorise l'écriture | Oui
Autorise l'ajout | Oui
Autorise simultanément la lecture et l'écriture | Oui
Support de la fonction stat() | Oui
Support de la fonction unlink() | Oui
Support de la fonction rename() | Oui
Support de la fonction mkdir() | Oui
Support de la fonction rmdir() | Oui

# http://

# https://

http:// -- https:// — Accès aux URLs HTTP(s)

### Description

Permet des accès, en lecture seule, à des fichiers accessibles via HTTP. Par défaut, une requête HTTP 1.0 GET est utilisée. Un en-tête `Host:` est envoyé avec la requête, pour gérer les hôtes virtuels basés sur des noms. Si une version de navigateur a été configurée avec l'option user_agent dans le fichier php.ini ou via le contexte de flux, elle sera aussi incluse dans la requête.

Le flux permet d'accéder au corps (body) de la ressource. Les en-têtes sont stockés dans la variable $http_response_header.

Pour connaître l'URL de la ressource depuis laquelle le document provient (après l'exécution de toutes les redirections), il est nécessaire d'analyser la série d'en-têtes retournés par le flux.

La directive from sera utilisée pour l'en-tête `From:` si elle a été définie, et non écrasée par les Options et paramètres de contexte.

### Utilisation

- http://example.com
- http://example.com/fichier.php?var1=val1&var2=val2
- http://user:password@example.com
- https://example.com
- https://example.com/fichier.php?var1=val1&var2=val2
- https://user:password@example.com

### Options

Résumé de l'enveloppe
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Oui
Autorise la lecture | Oui
Autorise l'écriture | Non
Autorise l'ajout | Non
Autorise la lecture et l'écriture simultanément | N/A
Support de la fonction stat() | Non
Support de la fonction unlink() | Non
Support de la fonction rename() | Non
Support de la fonction mkdir() | Non
Support de la fonction rmdir() | Non

### Exemples

Exemple #1 Détecte la dernière URL après des redirections

    <?php
    $url = 'http://www.example.com/redirecting_page.php';

    $fp = fopen($url, 'r');

    $meta_data = stream_get_meta_data($fp);
    foreach ($meta_data['wrapper_data'] as $response) {

        /* Avons-nous été redirigés ? */
        if (strtolower(substr($response, 0, 10)) == 'location: ') {

            /* mise à jour de $url avec le chemin après redirection */
            $url = substr($response, 10);
        }

    }

    ?>

### Notes

> Note: HTTPS n'est supporté que si l'extension openssl est active.

Les connexions HTTP sont en lecture seule ; l'écriture de données ou la copie de fichier vers une ressource HTTP ne sont pas supportées.

L'envoi de requêtes POST et PUT, par exemple, peut être effectué à l'aide des contextes HTTP.

### Voir aussi

- Options de contexte HTTP
- $http_response_header
- stream_get_meta_data() - Lit les en-têtes et données méta des flux

# ftp://

# ftps://

ftp:// -- ftps:// — Accès aux URLs FTP(s)

### Description

Permet l'accès en lecture aux fichiers existants, et la création de fichiers, via FTP. Si le serveur ne supporte pas FTP en mode passif, la connexion échouera.

Il est possible d'ouvrir des fichiers en lecture ou en écriture, mais pas les deux en même temps. Si le fichier distant existe déjà sur le serveur ftp et qu'une tentative d'ouverture en écriture est faite sans avoir spécifié l'option `overwrite` dans le contexte, la connexion échouera. Pour réécrire des fichiers existants en utilisant ftp, il faut spécifier l'option `overwrite` dans le contexte et ouvrir le fichier en écriture. Il est aussi possible d'utiliser l'extension FTP.

Si la directive from a été définie dans le fichier php.ini, alors cette valeur sera envoyée en tant que mot de passe pour les accès FTP anonymes.

### Utilisation

- ftp://example.com/pub/fichier.txt
- ftp://user:password@example.com/pub/fichier.txt
- ftps://example.com/pub/fichier.txt
- ftps://user:password@example.com/pub/fichier.txt

### Options

Résumé de l'enveloppe
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Oui
Autorise la lecture | Oui
Autorise l'écriture | Oui (nouveaux fichiers/fichiers existants avec le paramètre `overwrite`)
Autorise l'ajout | Oui
Autorise la lecture et l'écriture simultanément | Non
Support de la fonction stat() | filesize(), filemtime(), filetype(), file_exists(), is_file(), et is_dir() uniquement.
Support de la fonction unlink() | Oui
Support de la fonction rename() | Oui
Support de la fonction mkdir() | Oui
Support de la fonction rmdir() | Oui

### Notes

> Note:

> FTPS n'est supporté que lorsque l'extension openssl est active.

> Si le serveur ne supporte pas SSL, alors la connexion passera automatiquement en connexion ftp non chiffrée.

> Note: L'ajout
> L'ajout d'informations à un fichier est possible avec le gestionnaire d'URL `ftp://`.

### Voir aussi

- Options de contexte FTP

# php://

php:// — Accès aux divers flux I/O

### Description

PHP fournit un nombre important de flux I/O qui permettent d'accéder aux flux d'entrée et de sortie de PHP lui-même, aux descripteurs de fichiers d'entrée, de sortie et d'erreur standards, à des flux représentant des fichiers temporaires en mémoire vive ou sur le disque, ainsi qu'à des filtres qui peuvent manipuler d'autres ressources de fichiers pendant la lecture ou l'écriture.

#### php://stdin, php://stdout et php://stderr

php://stdin, php://stdout et php://stderr permettent des accès directs aux flux d'entrée ou de sortie correspondant du processus PHP. Le flux fait référence à une copie du descripteur de fichier, ce qui signifie que si php://stdin est ouvert puis fermé plus tard, seule la copie du descripteur est fermée ; le flux réellement référencé par `STDIN` n'est pas affecté. Il est recommandé d'utiliser uniquement les constantes `STDIN`, `STDOUT` et `STDERR` au lieu d'ouvrir manuellement les flux en utilisant ces enveloppes.

php://stdin est en lecture seule, alors que php://stdout et php://stderr sont en écriture seule.

#### php://input

php://input est un flux en lecture seule qui permet de lire des données brutes depuis le corps de la requête. php://input n'est pas disponible dans les requêtes POST avec `enctype="multipart/form-data"` si l'option enable_post_data_reading est activée.

#### php://output

php://output est un flux en écriture seule, qui permet d'écrire dans le mécanisme de buffer de sortie de la même façon que les fonctions print et echo.

#### php://fd

php://fd permet un accès direct au descripteur de fichier spécifié. Par exemple, php://fd/3 correspond au descripteur de fichier numéro 3.

#### php://memory et php://temp

php://memory et php://temp sont des flux en lecture/écriture qui permettent de stocker des données temporaires dans une enveloppe de fichiers. Une différence entre ces deux flux est que php://memory stockera toujours ses données en mémoire, alors que php://temp utilisera un fichier temporaire une fois que la quantité de données enregistrées aura dépassé une limite prédéfinie (par défaut, 2 Mo). L'emplacement de ce fichier temporaire est déterminé de la même manière que pour la fonction sys_get_temp_dir().

La limite mémoire de php://temp peut être contrôlée en ajoutant `/maxmemory:NN`, où `NN` est la quantité maximale de données à conserver en mémoire avant d'utiliser un fichier temporaire, en octets.

Attention

Certaines extensions PHP peuvent nécessiter un flux IO standard, et peuvent tenter de convertir un flux donné à un flux IO standard. Cette conversion peut échouer pour les flux de mémoire, car la fonction C fopencookie() doit être disponible. Cette fonction C n'est pas disponible sur Windows.

#### php://filter

php://filter est une sorte d'enveloppe prévue pour permettre l'application de filtres sur un flux au moment de son ouverture. Ceci est très pratique avec des fonctions sur des fichiers toutes-en-un comme les fonctions readfile(), file() et file_get_contents(), où il n'existe pas d'autre mécanisme permettant d'appliquer un filtre au flux avant que le contenu ne soit lu.

La cible de php://filter prend les paramètres suivants sous la forme de composantes de son chemin. Plusieurs filtres chaînés peuvent être spécifiés en un seul chemin. Se reporter aux exemples pour une utilisation correcte de ces paramètres.

Paramètres de php://filter
Nom | Description
--- | ---
`resource=<flux à filtrer>` | Ce paramètre est requis. Il spécifie le flux à filtrer.
`read=<liste des filtres à appliquer à la lecture>` | Ce paramètre est optionnel. Un ou plusieurs noms de filtres peuvent être fournis ici, séparés par un caractère pipe (`|`).
`write=<liste des filtres à appliquer à l'écriture>` | Ce paramètre est optionnel. Un ou plusieurs noms de filtres peuvent être fournis ici, séparés par un caractère pipe (`|`).
`<liste de filtres à appliquer à la fois lors de la lecture et de l'écriture>` | Tous les filtres fournis sans être préfixés par `read=` ou `write=` seront appliqués à la fois lors de la lecture et lors de l'écriture.

### Options

Résumé de l'enveloppe (pour `php://filter`, se reporter au résumé de l'enveloppe à filtrer)
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Non
Restreint par allow_url_include | `php://input`, `php://stdin`, `php://memory` et `php://temp` uniquement.
Autorise la lecture | `php://stdin`, `php://input`, `php://fd`, `php://memory` et `php://temp` uniquement.
Autorise l'écriture | `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` et `php://temp` uniquement.
Autorise l'ajout | `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` et `php://temp` uniquement. (Équivalent à de l'écriture)
Autorise à la fois la lecture et l'écriture | `php://fd`, `php://memory` et `php://temp` uniquement.
Support de la fonction stat() | Non. Néanmoins `php://memory` et `php://temp` supportent fstat().
Support de la fonction unlink() | Non
Support de la fonction rename() | Non
Support de la fonction mkdir() | Non
Support de la fonction rmdir() | Non
Support de la fonction stream_select() | `php://stdin`, `php://stdout`, `php://stderr`, `php://fd` et `php://temp` uniquement.

### Exemples

Exemple #1 php://temp/maxmemory

Ce paramètre optionnel permet de configurer la limite mémoire avant que php://temp ne commence à utiliser un fichier temporaire.

    <?php
    // Définit la limite à 5 Mo.
    $fiveMBs = 5 * 1024 * 1024;
    $fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

    fputs($fp, "hello\n");

    // Lit ce que nous venons d'écrire.
    rewind($fp);
    echo stream_get_contents($fp);
    ?>

Exemple #2 php://filter/resource=<flux à filtrer>

Ce paramètre doit être placé à la fin de la spécification de php://filter et doit pointer sur le flux à filtrer.

    <?php
    /* Ceci est équivalent à
      readfile("http://www.example.com");
      vu qu'aucun filtre n'est spécifié */

    readfile("php://filter/resource=http://www.example.com");
    ?>

Exemple #3 php://filter/read=<liste de filtres à appliquer lors de la lecture>

Ce paramètre prend un ou plusieurs noms de filtres séparés par un caractère pipe `|`.

    <?php
    /* Ceci affichera le contenu de
      www.example.com entièrement en majuscules */
    readfile("php://filter/read=string.toupper/resource=http://www.example.com");

    /* Ceci fera la même chose que le précédent,
      mais encodera en plus le résultat en ROT13 */
    readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
    ?>

Exemple #4 php://filter/write=<liste des filtres à appliquer lors de l'écriture>

Ce paramètre prend un ou plusieurs noms de filtres séparés par un caractère pipe `|`.

    <?php
    /* Ceci va filtrer la chaîne "Hello World"
      via le filtre rot13, puis écrire le résultat
      dans le fichier example.txt du dossier courant */
    file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
    ?>

Exemple #5 php://memory et php://temp ne sont pas réutilisables

php://memory et php://temp ne sont pas réutilisables, c.-à-d. après que les flux ont été fermés il n'y a aucun moyen de s'y référer à nouveau.

    <?php
    file_put_contents('php://memory', 'PHP');
    echo file_get_contents('php://memory'); // affiche rien

Exemple #6 php://input pour lire des données JSON depuis le corps de la requête

Cet exemple montre comment lire des données JSON brutes à partir des requêtes POST, PUT et PATCH en utilisant php://input.

    <?php
    $input = file_get_contents("php://input");
    $json_array = json_decode(
      json: $input,
      associative: true,
      flags: JSON_THROW_ON_ERROR
    );

    echo "Données JSON reçues : ";
    print_r($json_array);
    ?>

# zlib://

# bzip2://

# zip://

zlib:// -- bzip2:// -- zip:// — Flux de compression

### Description

compress.zlib:// et compress.bzip2://

zlib: fonctionne comme gzopen(), hormis le fait que le flux peut être utilisé directement avec fread() et les autres fonctions de système de fichiers. Cette notation est obsolète à cause d'ambiguïtés dues aux noms de fichiers contenant des deux points ':'. Utiliser plutôt compress.zlib://.

compress.zlib:// et compress.bzip2:// sont respectivement équivalents à gzopen() et bzopen(), et ils fonctionnent même sur les systèmes qui ne supportent pas fopencookie.

L'extension ZIP fournit l'enveloppe zip:. À partir de PHP 7.2.0 et libzip 1.2.0+, le support des mots de passe pour les archives chiffrées a été ajouté, permettant aux mots de passe d'être fournis par des contextes de flux. Les mots de passe peuvent être définis sur un flux à l'aide de l'option de contexte `'password'`.

### Utilisation

- compress.zlib://file.gz
- compress.bzip2://file.bz2
- zip://archive.zip#dir/file.txt

### Options

Résumé des enveloppes
Attribut | Supporté
--- | ---
Limité par allow_url_fopen | Non
Autorise la lecture | Oui
Autorise l'écriture | Oui (sauf `zip://`)
Autorise l'ajout | Oui (sauf `zip://`)
Autorise la lecture et l'écriture simultanément | Non
Support de la fonction stat() | Non, utiliser l'enveloppe `file://` pour obtenir des informations sur les fichiers compressés.
Support de la fonction unlink() | Non, utiliser l'enveloppe `file://` pour supprimer les fichiers compressés.
Support de la fonction rename() | Non
Support de la fonction mkdir() | Non
Support de la fonction rmdir() | Non

### Voir aussi

- Options de contexte Zlib

# data://

data:// — Données (RFC 2397)

### Description

L'enveloppe de flux data: (» RFC 2397).

### Utilisation

- data://text/plain;base64,

### Options

Résumé de l'enveloppe
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Oui
Restreint par allow_url_include | Oui
Autorise la lecture | Oui
Autorise l'écriture | Non
Autorise l'ajout | Non
Autorise la lecture et l'écriture simultanément | Non
Support de la fonction stat() | Non
Support de la fonction unlink() | Non
Support de la fonction rename() | Non
Support de la fonction mkdir() | Non
Support de la fonction rmdir() | Non

### Exemples

Exemple #1 Affichage d'un contenu data://

    <?php
    // Affiche "I love PHP"
    echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
    ?>

Exemple #2 Récupération du type de média

    <?php
    $fp   = fopen('data://text/plain;base64,', 'r');
    $meta = stream_get_meta_data($fp);

    // Affiche "text/plain"
    echo $meta['mediatype'];
    ?>

# glob://

glob:// — Trouve des noms de fichiers correspondant à un masque donné

### Description

L'enveloppe de flux glob:.

### Utilisation

- glob://

### Options

Résumé de l'enveloppe
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Non
Restreint par allow_url_include | Non
Autorise la lecture | Non
Autorise l'écriture | Non
Autorise l'ajout | Non
Autorise la lecture et l'écriture simultanément | Non
Support de la fonction stat() | Non
Support de la fonction unlink() | Non
Support de la fonction rename() | Non
Support de la fonction mkdir() | Non
Support de la fonction rmdir() | Non

### Exemples

Exemple #1 Utilisation simple

    <?php
    // Boucle sur tous les fichiers *.php du dossier ext/spl/examples/ et
    // affiche le nom du fichier ainsi que sa taille
    $it = new DirectoryIterator("glob://ext/spl/examples/*.php");
    foreach($it as $f) {
        printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
    }
    ?>

    tree.php: 1.0K
    findregex.php: 0.6K
    findfile.php: 0.7K
    dba_dump.php: 0.9K
    nocvsdir.php: 1.1K
    phar_from_dir.php: 1.0K
    ini_groups.php: 0.9K
    directorytree.php: 0.9K
    dba_array.php: 1.1K
    class_tree.php: 1.8K

# phar://

phar:// — Archive PHP

### Description

L'enveloppe de flux phar://. Voir enveloppe de flux Phar pour une description détaillée.

### Utilisation

- phar://

### Options

Résumé de l'enveloppe
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Non
Restreint par allow_url_include | Non
Autorise la lecture | Oui
Autorise l'écriture | Oui
Autorise l'ajout | Non
Autorise la lecture et l'écriture simultanément | Oui
Support de la fonction stat() | Oui
Support de la fonction unlink() | Oui
Support de la fonction rename() | Oui
Support de la fonction mkdir() | Oui
Support de la fonction rmdir() | Oui

### Voir aussi

- Les options du contexte Phar

# ssh2://

ssh2:// — Shell sécurisé 2

### Description

ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// (PECL)

> Note: Cette enveloppe n'est pas activée par défaut
> Pour utiliser l'enveloppe ssh2://, l'extension » SSH2 disponible sur » PECL doit être installée.

En plus d'accepter les identifications traditionnelles via l'URI, l'enveloppe ssh2 réutilisera les connexions ouvertes en passant la ressource de connexion dans la partie hôte de l'URL.

### Utilisation

- ssh2.shell://user:pass@example.com:22/xterm
- ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd
- ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14
- ssh2.sftp://user:pass@example.com:22/path/to/filename

### Options

Résumé de l'enveloppe
Attribut | ssh2.shell | ssh2.exec | ssh2.tunnel | ssh2.sftp | ssh2.scp
--- | --- | --- | --- | --- | ---
Restreint par allow_url_fopen | Oui | Oui | Oui | Oui | Oui
Autorise la lecture | Oui | Oui | Oui | Oui | Oui
Autorise l'écriture | Oui | Oui | Oui | Oui | Non
Autorise l'ajout | Non | Non | Non | Oui (lorsque supporté par le serveur) | Non
Autorise la lecture et l'écriture simultanément | Oui | Oui | Oui | Oui | Non
Support de la fonction stat() | Non | Non | Non | Oui | Non
Support de la fonction unlink() | Non | Non | Non | Oui | Non
Support de la fonction rename() | Non | Non | Non | Oui | Non
Support de la fonction mkdir() | Non | Non | Non | Oui | Non
Support de la fonction rmdir() | Non | Non | Non | Oui | Non

Options de contexte
Nom | Utilisation | Défaut
--- | --- | ---
`session` | ressource ssh2 pré-connectée à réutiliser |
`sftp` | ressource sftp pré-allouée à réutiliser |
`methods` | méthodes d'échange de clés, hostkey, cipher, compression, et MAC, à utiliser |
`callbacks` |  |
`username` | Nom de l'utilisateur pour la connexion |
`password` | Mot de passe à utiliser lors d'une identification par mot de passe |
`pubkey_file` | Nom du fichier contenant la clé publique à utiliser lors de l'identification |
`privkey_file` | Nom du fichier contenant la clé privée à utiliser lors de l'identification |
`env` | Tableau associatif de variables d'environnement à définir |
`term` | Type d'émulation de terminal à demander lors de l'allocation d'un pty |
`term_width` | Largeur du terminal à demander lors de l'allocation d'un pty |
`term_height` | Hauteur du terminal à demander lors de l'allocation d'un pty |
`term_units` | Unités à utiliser avec term_width et term_height | `SSH2_TERM_UNIT_CHARS`

### Exemples

Exemple #1 Ouverture d'un flux depuis une connexion active

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
    ?>

Exemple #2 La variable $session doit rester disponible !

Afin d'utiliser l'enveloppe ssh2.*://$session, la variable de ressource $session doit être conservée. Le code ci-dessous n'aura pas l'effet escompté :

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $connection_string = "ssh2.sftp://$session/";
    unset($session);
    $stream = fopen($connection_string . "path/to/file", 'r');
    ?>

La fonction unset() clôt la session, car la variable $connection_string ne contient pas de référence à la variable $session, mais uniquement une chaîne dérivée. Ceci survient également lorsque la fonction unset() est implicite, lors d'une sortie du scope (comme dans une fonction).

# rar://

rar:// — RAR

### Description

Cette enveloppe prend le chemin encodé URL vers l'archive RAR (relatif ou absolu), puis, optionnellement, un astérisque (`*`), optionnellement suivi d'un signe dièse (`#`), et, toujours optionnellement, un nom d'entrée encodé URL, tel que stocké dans l'archive. Le fait de spécifier un nom d'entrée nécessite la présence du signe dièse ; la présence d'un slash au début du nom de l'entrée est optionnelle.

Cette enveloppe peut ouvrir à la fois des fichiers et des dossiers. Lors de l'ouverture de dossiers, l'astérisque force les noms des dossiers à être retournés non encodés. S'il n'est pas spécifié, ils seront retournés sous la forme encodée URL - ceci permet à l'enveloppe d'être utilisée correctement avec les fonctionnalités internes comme RecursiveDirectoryIterator en présence de noms de fichiers qui semblent être encodés URL.

Si le signe dièse et le nom de l'entrée ne sont pas inclus, la racine de l'archive sera affichée. Cet affichage est différent des dossiers réguliers dans le sens où le flux résultant ne contiendra pas d'information comme la date et heure de modification, puisque la racine du dossier n'est pas stockée comme une entrée individuelle dans l'archive. L'utilisation de cette enveloppe avec RecursiveDirectoryIterator nécessite la présence du signe dièse dans l'URL lors de l'accès à la racine, afin de construire correctement les URLs des fils.

> Note: Cette enveloppe n'est pas activée par défaut
> Pour utiliser l'enveloppe rar://, l'extension » rar disponible sur » PECL doit être installée.

rar:// est disponible à partir de PECL rar 3.0.0

### Utilisation

- rar://<url encoded archive name>[*][#[<url encoded entry name>]]

### Options

Résumé de l'enveloppe
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Non
Restreint par allow_url_include | Non
Autorise la lecture | Oui
Autorise l'écriture | Non
Autorise l'ajout | Non
Autorise la lecture et l'écriture simultanément | Non
Support de la fonction stat() | Oui
Support de la fonction unlink() | Non
Support de la fonction rename() | Non
Support de la fonction mkdir() | Non
Support de la fonction rmdir() | Non

Options de contexte
Nom | Utilisation | Défaut
--- | --- | ---
`open_password` | Le mot de passe utilisé pour chiffrer les en-têtes de l'archive, s'il y en a. WinRAR chiffrera tous les fichiers avec le même mot de passe que les en-têtes lorsque celui-ci est présent, donc, pour les archives avec des en-têtes chiffrés, `file_password` sera ignoré. |
`file_password` | Le mot de passe utilisé pour chiffrer un fichier, s'il y en a. Si les en-têtes sont aussi chiffrés, cette option sera ignorée et le mot de passe de l'option `open_password` sera privilégié. La raison pour laquelle il y a 2 options est le souhait de pouvoir couvrir la possibilité de supporter les archives avec différents mots de passe pour les en-têtes et les fichiers. Il est à noter que si l'en-tête de l'archive n'est pas chiffré, l'option `open_password` sera ignorée et cette option doit être utilisée à la place. |
`volume_callback` | Une fonction de rappel pour déterminer le chemin des volumes manquants. Se reporter à la méthode RarArchive::open() pour plus d'informations. |

### Exemples

Exemple #1 Parcours d'une archive RAR

    <?php

    class MyRecDirIt extends RecursiveDirectoryIterator {
        function current() {
            return rawurldecode($this->getSubPathName()) .
                (is_dir(parent::current())?" [DIR]":"");
        }
    }

    $f = "rar://" . rawurlencode(dirname(__FILE__)) .
        DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';

    $it = new RecursiveTreeIterator(new MyRecDirIt($f));

    foreach ($it as $s) {
        echo $s, "\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    |-allow_everyone_ni [DIR]
    |-file1.txt
    |-file2_אּ.txt
    |-with_streams.txt
    \-אּ [DIR]
      |-אּ\%2Fempty%2E [DIR]
      | \-אּ\%2Fempty%2E\file7.txt
      |-אּ\empty [DIR]
      |-אּ\file3.txt
      |-אּ\file4_אּ.txt
      \-אּ\אּ_2 [DIR]
        |-אּ\אּ_2\file5.txt
        \-אּ\אּ_2\file6_אּ.txt

Exemple #2 Ouverture d'un fichier chiffré (en-tête chiffré)

    <?php
    $stream = fopen("rar://" .
        rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
        'encrypted_headers.rar' . '#encfile1.txt', "r", false,
        stream_context_create(
            array(
                'rar' =>
                    array(
                        'open_password' => 'samplepassword'
                    )
                )
            )
        );
    var_dump(stream_get_contents($stream));
    /* Les dates de création et de dernier accès sont optionnelles avec WinRAR,
     * ce qui explique que la plupart des fichiers ne les aient pas */
    var_dump(fstat($stream));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(26) "Encrypted file 1 contents."
    Array
    (
        [0] => 0
        [1] => 0
        [2] => 33206
        [3] => 1
        [4] => 0
        [5] => 0
        [6] => 0
        [7] => 26
        [8] => 0
        [9] => 1259550052
        [10] => 0
        [11] => -1
        [12] => -1
        [dev] => 0
        [ino] => 0
        [mode] => 33206
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 26
        [atime] => 0
        [mtime] => 1259550052
        [ctime] => 0
        [blksize] => -1
        [blocks] => -1
    )

# ogg://

ogg:// — Flux Audio

### Description

Les fichiers ouverts en lecture avec l'enveloppe ogg:// sont traités comme de l'audio compressé en utilisant le codec `OGG/Vorbis`. De la même façon, les fichiers ouverts en écriture ou en ajout avec l'enveloppe ogg:// sont écrits comme étant des données audio compressées. La fonction stream_get_meta_data(), lorsqu'elle est utilisée sur un fichier `OGG/Vorbis` ouvert en lecture, retournera de nombreux détails concernant ce flux, incluant la balise `vendor`, tous les commentaires `comments` inclus, le nombre de canaux `channels`, le taux d'échantillonnage `rate`, ainsi que la plage du taux d'encodage décrite par : `bitrate_lower`, `bitrate_upper`, `bitrate_nominal` et `bitrate_window`.

ogg:// (PECL)

> Note: Cette enveloppe n'est pas activée par défaut
> Pour utiliser l'enveloppe ogg://, l'extension » OGG/Vorbis disponible sur » PECL doit être installée.

### Utilisation

- ogg://soundfile.ogg
- ogg:///path/to/soundfile.ogg
- ogg://http://www.example.com/path/to/soundstream.ogg

### Options

Résumé de l'enveloppe
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Non
Permet la lecture | Oui
Permet l'écriture | Oui
Permet l'ajout | Oui
Permet la lecture et l'écriture simultanément | Non
Supporte la fonction stat() | Non
Supporte la fonction unlink() | Non
Supporte la fonction rename() | Non
Supporte la fonction mkdir() | Non
Supporte la fonction rmdir() | Non

Options de contexte
Nom | Utilisation | Défaut | Mode
--- | --- | --- | ---
`pcm_mode` | L'encodage PCM à appliquer pendant la lecture, parmi un de ceux-ci : `OGGVORBIS_PCM_U8`, `OGGVORBIS_PCM_S8`, `OGGVORBIS_PCM_U16_BE`, `OGGVORBIS_PCM_S16_BE`, `OGGVORBIS_PCM_U16_LE` et `OGGVORBIS_PCM_S16_LE`. (8 vs 16 bit, signé ou non, gros ou petit `endian`) | OGGVORBIS_PCM_S16_LE | Lecture
`rate` | Taux d'échantillonnage des données entrantes, exprimé en Hz | 44100 | Écriture/Ajout
`bitrate` | Lorsque donné sous la forme d'un entier, le débit fixe pour encoder (de 16000 à 131072). Lorsque donné sous la forme d'un nombre décimal, la qualité de débit variable à utiliser (de -1.0 à 1.0). | 128000 | Écriture/Ajout
`channels` | Le nombre de canaux audio à encoder, typiquement 1 (Mono) ou 2 (Stéréo). Intervalle pouvant aller jusqu'à 16. | 2 | Écriture/Ajout
`comments` | Un tableau de valeurs sous forme de chaînes de caractères à encoder dans la piste d'en-tête. |  | Écriture/Ajout

# expect://

expect:// — Flux d'interactions de processus

### Description

Les flux ouverts avec l'enveloppe expect:// permettent d'accéder à stdin, stdout, et stderr de processus, via PTY.

> Note: Cette enveloppe n'est pas activée par défaut
> Pour utiliser l'enveloppe expect://, l'extension » Expect disponible sur » PECL doit être installée.

expect:// (PECL)

### Utilisation

- expect://command

### Options

Résumé de l'enveloppe
Attribut | Supporté
--- | ---
Restreint par allow_url_fopen | Non
Autorise la lecture | Oui
Autorise l'écriture | Oui
Autorise l'ajout | Oui
Autorise la lecture et l'écriture simultanément | Non
Support de la fonction stat() | Non
Support de la fonction unlink() | Non
Support de la fonction rename() | Non
Support de la fonction mkdir() | Non
Support de la fonction rmdir() | Non

## Sommaire

- file:// — Accès au système de fichiers local
- http:// — Accès aux URLs HTTP(s)
- ftp:// — Accès aux URLs FTP(s)
- php:// — Accès aux divers flux I/O
- zlib:// — Flux de compression
- data:// — Données (RFC 2397)
- glob:// — Trouve des noms de fichiers correspondant à un masque donné
- phar:// — Archive PHP
- ssh2:// — Shell sécurisé 2
- rar:// — RAR
- ogg:// — Flux Audio
- expect:// — Flux d'interactions de processus

- La syntaxe de base
  - Balises PHP
  - Échappement depuis du HTML
  - Séparation des instructions
  - Commentaires
- Les types
  - Introduction
  - Système de type
  - NULL
  - Booléen
  - Les entiers
  - Nombres à virgule flottante
  - Chaînes
  - Chaînes numériques
  - Les tableaux
  - Les objets
  - Les énumérations
  - Les ressources
  - Callables
  - Mixed
  - Void
  - Never
  - Types de classes relatives
  - Type singleton
  - Itérables
  - Déclarations de type
  - Jonglage de type
- Les variables
  - Essentiel
  - Variables prédéfinies
  - Portée des variables
  - Les variables dynamiques
  - Variables externes à PHP
- Les constantes
  - Syntaxe
  - Constantes prédéfinies
  - Constantes magiques
- Les expressions
- Les opérateurs
  - Priorité des opérateurs — La priorité des opérateurs
  - Arithmétique — Les opérateurs arithmétiques
  - Incrémentation et décrémentation — Opérateurs d'incrémentation et décrémentation
  - Affectation — Les opérateurs d'affectation
  - Bitwise — Opérateurs sur les bits
  - Comparaison — Opérateurs de comparaison
  - Contrôle d'erreur — Opérateur de contrôle d'erreur
  - Exécution — Opérateur d'exécution
  - Logique — Les opérateurs logiques
  - Chaînes de caractères — Opérateurs de chaînes de caractères
  - Tableaux — Opérateurs de tableaux
  - Type — Opérateurs de types
  - Fonctionnels — Opérateurs fonctionnels
- Les structures de contrôle
  - Introduction
  - if
  - else
  - elseif/else if
  - Syntaxe alternative
  - while
  - do-while
  - for
  - foreach
  - break
  - continue
  - switch
  - match
  - declare
  - return
  - require
  - include
  - require_once
  - include_once
  - goto
- Les fonctions
  - Les fonctions définies par l'utilisateur
  - Paramètres et arguments de fonction
  - Les valeurs de retour
  - Fonctions variables
  - Fonctions internes
  - Fonctions anonymes
  - Fonction Fléchée
  - Syntaxe callable de première classe
- Les classes et les objets
  - Introduction
  - Syntaxe de base
  - Propriétés
  - Hooks de propriété
  - Constantes de classe
  - Auto-chargement de classes
  - Constructeurs et destructeurs
  - Visibilité
  - Héritage
  - L'opérateur de résolution de portée (::)
  - Statique
  - Abstraction de classes
  - Interfaces
  - Traits
  - Classes anonymes
  - Surcharge magique
  - Parcours d'objets
  - Méthodes magiques
  - Mot-clé "final"
  - Clonage d'objets
  - Comparaison d'objets
  - Late Static Bindings (Résolution statique à la volée)
  - Objets et références
  - Sérialisation d'objets — Sérialiser des objets - des objets en session
  - Covariance et Contravariance
  - Objets paresseux
  - Modifications en POO (Programmation orientée objet)
- Les espaces de noms
  - Introduction — Introduction aux espaces de noms
  - Espaces de noms — Définition des espaces de noms
  - Sous espace de noms — Déclaration d'un sous espace de noms
  - Définition de plusieurs espaces de noms dans le même fichier
  - Introduction — Utilisation des espaces de noms : introduction
  - Espaces de noms et langage dynamique
  - Commande namespace et __NAMESPACE__ — La commande namespace et la constante __NAMESPACE__
  - Importation et alias — Utilisation des espaces de noms : importation et alias
  - Global — Espace de noms global
  - Retour sur l'espace global — Utilisation des espaces de noms : retour sur l'espace global pour les fonctions et les constantes
  - Règles de résolution de noms
  - Foire aux questions — Foire aux questions : ce qu'il faut savoir des espaces de noms
- Les énumérations
  - Aperçu des énumérations
  - Énumérations de base
  - Énumérations avec valeur de base
  - Méthodes d'énumération
  - Méthodes statiques d'Enumération
  - Constantes d'énumération
  - Traits
  - Valeurs d'énumération dans les expressions constantes
  - Différences avec les objets
  - Liste de valeurs
  - Sérialisation
  - Pourquoi les enums ne sont pas extensibles
  - Exemples
- Erreurs
  - Bases
  - Les Erreurs en PHP 7
- Les exceptions
  - Étendre les Exceptions
- Fibres
- Les générateurs
  - Résumé sur les générateurs
  - Syntaxe d'un Générateur
  - Comparaison des générateurs avec les objets Iterator
- Attributs
  - Aperçu des attributs
  - Syntaxe des attributs
  - Lecture des attributs avec l'API de Reflection
  - Déclaration des classes d'attributs
- Les références
  - Qu'est-ce qu'une référence ?
  - Que font les références ?
  - Ce que les références ne sont pas
  - Passage par référence
  - Retourner des références
  - Détruire une référence
  - Repérer une référence
- Variables prédéfinies
  - Les Superglobales — Les variables internes qui sont toujours disponibles, quel que soit le contexte
  - $GLOBALS — Référence toutes les variables disponibles dans un contexte global
  - $_SERVER — Variables de serveur et d'exécution
  - $_GET — Variables de chaîne de requête
  - $_POST — Données de formulaire depuis des requêtes HTTP POST
  - $_FILES — Variable de téléversement de fichier via HTTP
  - $_REQUEST — Variables de requête HTTP
  - $_SESSION — Variables de session
  - $_ENV — Variables d'environnement
  - $_COOKIE — Cookies HTTP
  - $php_errormsg — Le dernier message d'erreur
  - $http_response_header — En-têtes de réponse HTTP
  - $argc — Le nombre d'arguments passés au script
  - $argv — Tableau d'arguments passés au script
- Exceptions prédéfinies
  - Exception
  - ErrorException
  - ClosedGeneratorException — La classe ClosedGeneratorException
  - Error
  - ArgumentCountError
  - ArithmeticError
  - AssertionError
  - DivisionByZeroError
  - CompileError
  - ParseError
  - TypeError
  - ValueError
  - UnhandledMatchError
  - FiberError
  - RequestParseBodyException
- Interfaces et Classes Prédéfinies
  - Traversable — L'interface Traversable
  - Iterator — L'interface Iterator
  - IteratorAggregate — L'interface IteratorAggregate
  - InternalIterator — La classe InternalIterator
  - Throwable
  - Countable — L'interface Countable
  - ArrayAccess — L'interface ArrayAccess
  - Serializable — L'interface Serializable
  - Closure — La classe Closure
  - stdClass — La classe stdClass
  - Generator — La classe Generator
  - Fiber — La classe Fiber
  - WeakReference — La classe WeakReference
  - WeakMap — La classe WeakMap
  - Stringable — L'interface Stringable
  - UnitEnum — L'interface UnitEnum
  - BackedEnum — L'interface BackedEnum
  - SensitiveParameterValue — La classe SensitiveParameterValue
  - __PHP_Incomplete_Class — La classe __PHP_Incomplete_Class
- Attributs prédéfinis
  - Attribute — La classe Attribute
  - AllowDynamicProperties — La classe AllowDynamicProperties
  - DelayedTargetValidation — L'attribut DelayedTargetValidation
  - Deprecated — L'attribut Deprecated
  - NoDiscard — L'attribut NoDiscard
  - Override — La classe Override
  - ReturnTypeWillChange — La classe ReturnTypeWillChange
  - SensitiveParameter — L'attribut SensitiveParameter
- Options et paramètres de contexte
  - Options de contexte des sockets — Liste des options de contexte des sockets
  - Options de contexte HTTP — Liste des options de contexte HTTP
  - Options de contexte FTP — Liste des options de contexte FTP
  - Options de contexte SSL — Liste des options de contexte SSL
  - Les options du contexte Phar — Liste des options du contexte Phar
  - Paramètres de contexte — Liste des paramètres de contexte
  - Options de contexte Zip — Liste des options de contexte Zip
  - Options de contexte Zlib — Liste des options de contexte Zlib
- Liste des protocoles et des gestionnaires supportés
  - file:// — Accès au système de fichiers local
  - http:// — Accès aux URLs HTTP(s)
  - ftp:// — Accès aux URLs FTP(s)
  - php:// — Accès aux divers flux I/O
  - zlib:// — Flux de compression
  - data:// — Données (RFC 2397)
  - glob:// — Trouve des noms de fichiers correspondant à un masque donné
  - phar:// — Archive PHP
  - ssh2:// — Shell sécurisé 2
  - rar:// — RAR
  - ogg:// — Flux Audio
  - expect:// — Flux d'interactions de processus

# Sécurité

# Introduction

PHP est un langage puissant et l'interpréteur, qu'il soit inclus dans le serveur web en tant que module ou bien exécuté en tant que binaire CGI séparé, est capable d'accéder aux fichiers, d'exécuter des commandes, et d'ouvrir des connexions réseaux. Toutes ces propriétés rendent fragile la sécurité d'un serveur web. PHP a été conçu comme un langage beaucoup plus sécurisé pour écrire des programmes CGI que le Perl ou le langage C, et, avec une sélection rigoureuse des options de compilation et d'exécution et de bonnes habitudes de programmation, il permet d'obtenir un équilibre parfait entre liberté et sécurité.

Étant donné qu'il existe de nombreux moyens d'utiliser le langage PHP, il existe de nombreuses directives de configuration permettant d'en contrôler le comportement. Un grand nombre d'options permet d'utiliser PHP dans de nombreuses situations, mais signifie aussi que certaines combinaisons d'options de compilation et d'exécution peuvent fragiliser la sécurité du serveur.

La flexibilité de configuration de PHP est épaulée par la flexibilité du code. PHP peut être utilisé pour construire des applications serveur complètes, avec tous les pouvoirs d'un utilisateur shell, ou il peut être utilisé pour de simples SSI (`server-side includes`) avec peu de risque dans un environnement à sécurité renforcée. La création de cet environnement et sa sécurisation sont largement à la charge du développeur PHP.

Ce chapitre commence par quelques conseils généraux de sécurité, explique les différentes options de configuration et les situations dans lesquelles elles peuvent être utilisées en toute sécurité, puis décrit quelques points à considérer lorsque l'on programme pour différents niveaux de sécurité.

# Considérations générales

Un système complètement sûr est virtuellement impossible, donc, une approche souvent utilisée par les professionnels de la sécurité est d'équilibrer les risques et l'utilisabilité. Si chaque variable fournie par l'utilisateur demandait deux formes de validation biométrique (comme un scan de la rétine et une empreinte digitale), on obtiendrait un système avec un niveau de traçabilité extrêmement élevé. Il faudrait aussi une bonne demi-heure pour remplir un formulaire un peu compliqué, ce qui aurait tendance à encourager les utilisateurs à trouver un moyen de contourner cette sécurité.

La meilleure sécurité est suffisamment discrète pour répondre aux besoins sans ajouter de contraintes insurmontables pour l'utilisateur ni de systèmes trop complexes de programmation. En fait, certaines attaques sur des scripts sont justement des exploitations de systèmes de sécurité trop complexes, qui s'érodent au cours du temps.

Un principe qu'il est bon de retenir : un système est aussi sûr que son maillon le plus faible. Si toutes les transactions sont bien notées, avec l'heure à laquelle elles ont été exécutées, depuis quel emplacement géographique, leur type, etc. mais que l'utilisateur est identifié uniquement par un cookie, la robustesse du lien entre l'utilisateur et le journal des transactions est sévèrement réduite.

Lors des tests d'un site, il faut garder à l'esprit qu'il est impossible de tester toutes les situations, même pour les pages les plus simples. Les valeurs attendues seront toujours complètement différentes des valeurs entrées par un employé mécontent, un hacker qui a des mois devant lui, ou encore le chat de la maison qui marche sur le clavier. C'est pourquoi il est préférable de regarder le code d'un point de vue logique, pour repérer les points où des données inattendues peuvent être injectées, puis de voir comment elles pourront être modifiées, réduites ou amplifiées.

L'Internet est rempli d'individus qui tentent de se faire une renommée en piratant des programmes, en bloquant des sites, en envoyant des contenus inappropriés, ou en rendant les journées « intéressantes » d'une manière ou d'une autre. Peu importe qu'il s'agisse d'un grand portail ou d'un petit site web, tout site peut être la cible de tout quidam avec une connexion. En fait, tout système est une cible potentielle dès qu'il est connecté. Certains programmes de piratage ne font pas dans la demi-mesure, et testent systématiquement des millions d'IP, à la recherche de victimes ; essayez de ne pas en devenir une.

# Binaires CGI

## Sommaire

- Faiblesses connues
- Cas 1 : Seuls les fichiers publics sont servis
- Cas 2 : Utilisation de la directive cgi.force_redirect
- Cas 3 : Utilisation du "doc_root" ou du "user_dir"
- Cas 4 : Exécutable PHP à l'extérieur de l'arborescence du serveur

## Faiblesses connues

Utiliser PHP comme un exécutable CGI est une possibilité pour les cas où l'on ne veut pas l'utiliser comme un module du serveur web (comme Apache), ou bien lorsque l'on souhaite l'utiliser en combinaison avec un gestionnaire CGI complémentaire, afin de créer un environnement de script sécurisé (en utilisant des techniques de chroot ou setuid). Une telle décision signifie habituellement que l'exécutable php sera installé dans le répertoire du serveur web cgi-bin. Le conseil de sécurité CERT » CA-96.11 recommande de ne pas placer d'interpréteurs dans le répertoire cgi-bin. Même si le binaire php peut être utilisé comme interpréteur autonome, PHP est conçu pour prévenir les attaques que cette configuration peut rendre possibles :

- Accès au système de fichiers : http://my.host/cgi-bin/php?/etc/passwd Lorsque la requête est passée dans une url, après le point d'interrogation (`?`), elle est envoyée à l'interpréteur comme une ligne de commande par l'interface CGI. Habituellement, l'interpréteur ouvre le fichier spécifié et l'exécute. Lorsqu'il est invoqué comme exécutable CGI, php refuse d'interpréter les arguments de la ligne de commande.
- Accès à n'importe quel document web sur le serveur : http://my.host/cgi-bin/php/secret/doc.html Le "path information" dans l'url, situé juste après le nom de l'exécutable PHP, /secret/doc.html est utilisé par convention pour spécifier le nom du fichier qui doit être ouvert et interprété par le programme CGI. Habituellement, des directives de configuration du serveur web (pour le serveur Apache : `Action`) sont utilisées pour rediriger des requêtes vers des documents comme http://my.host/secret/script.php vers l'interpréteur PHP. Dans une telle configuration, le serveur web vérifie d'abord s'il a accès au répertoire /secret, et redirige ensuite la requête vers http://my.host/cgi-bin/php/secret/script.php. Malheureusement, si la requête est faite directement sous cette forme, aucune vérification d'accès n'est faite par le serveur web pour le fichier /secret/script.php, mais uniquement pour le fichier /cgi-bin/php. De cette manière, n'importe quel utilisateur qui peut accéder au fichier /cgi-bin/php peut aussi accéder à n'importe quel document protégé sur le serveur web. Avec PHP, les options d'exécution cgi.force_redirect, doc_root et user_dir peuvent être utilisées pour prévenir ce genre d'attaque, si des restrictions d'accès sont appliquées sur les documents du serveur. Voir ci-dessous pour des explications plus complètes sur les différentes combinaisons.

## Cas 1 : Seuls les fichiers publics sont servis

Si le serveur n'a aucun document dont l'accès n'est pas restreint par un mot de passe ou un système de vérification de l'adresse IP, ce type de configuration n'est pas nécessaire. Si le serveur web ne permet pas les redirections, ou s'il n'a aucun besoin de communiquer avec le binaire PHP de manière sécurisée, il est possible d'activer la directive INI cgi.force_redirect. Il faut tout de même s'assurer que les scripts PHP ne dépendent pas d'un appel de manière directe comme http://my.host/cgi-bin/php/dir/script.php, ou de manière indirecte, par redirection, http://my.host/dir/script.php.

Avec Apache, les redirections peuvent être configurées en utilisant les directives `AddHandler` et `Action` (voir ci-dessous).

## Cas 2 : Utilisation de la directive `cgi.force_redirect`

La directive de configuration cgi.force_redirect évite qu'un appel direct à php avec une URL comme http://my.host/cgi-bin/php/secretdir/script.php ne soit possible. À la place, PHP analysera le fichier uniquement s'il y a eu redirection.

Habituellement, la redirection est effectuée grâce aux directives suivantes dans la configuration du serveur Apache :

    Action php-script /cgi-bin/php
    AddHandler php-script .php

Cette option a uniquement été testée avec Apache, et compte sur Apache pour affecter la variable d'environnement non-standard REDIRECT_STATUS pour les requêtes redirigées. Dans le cas où le serveur web ne supporte aucune manière d'indiquer si la requête a été redirigée ou non, cette option de compilation ne pourra pas être utilisée. Il faudra alors utiliser une des autres méthodes d'exploitation de la version binaire CGI de PHP, comme exposé ci-dessous.

## Cas 3 : Utilisation du "doc_root" ou du "user_dir"

Ajouter un contenu interactif, comme des scripts ou des exécutables, dans les répertoires de documents du serveur web, est parfois considéré comme une pratique non-sécurisée. Si, à cause d'une erreur de configuration, le script n'est pas exécuté mais affiché comme une page HTML classique, il peut en résulter une fuite de propriété intellectuelle ou d'informations liées à la sécurité, comme, typiquement, des mots de passe. En conséquence, un bon nombre d'administrateurs préfèrent mettre en place un répertoire spécial pour les scripts, qui soit uniquement accessible par le biais du binaire CGI de PHP, ce qui signifie que tous les fichiers de ce répertoire seront interprétés et jamais affichés tels quels.

De plus, s'il n'est pas possible d'utiliser la méthode qui permet de s'assurer que les requêtes ne sont pas redirigées, comme présentée ci-dessus, il est nécessaire de mettre en place un répertoire de scripts "doc_root" différent du répertoire "document root" du serveur web.

Pour indiquer la racine des scripts PHP, il est possible d'utiliser la directive doc_root dans le fichier de configuration, ou il est possible d'affecter la variable d'environnement PHP_DOCUMENT_ROOT. Si cette information est renseignée, le binaire CGI de PHP construira toujours le nom de fichier à ouvrir avec `doc_root` et le "path information" de la requête, ce qui garantit qu'aucun script ne sera exécuté en dehors du répertoire prédéfini (à l'exception du répertoire désigné par la directive `user_dir` - voir ci-dessous).

Une autre option possible ici est la directive user_dir. Lorsque `user_dir` n'est pas spécifiée, seuls les fichiers contenus dans le répertoire `doc_root` peuvent être ouverts. Ouvrir un fichier possédant l'url http://my.host/~user/doc.php ne correspondra pas à l'ouverture d'un fichier sous le répertoire racine de l'utilisateur, mais à l'ouverture du fichier ~user/doc.php sous le répertoire `doc_root` (oui, un nom de répertoire commençant par un tilde [`~`]).

Si la directive `user_dir` est activée, par exemple à la valeur public_php, une requête du type http://my.host/~user/doc.php ouvrira un fichier appelé doc.php dans le répertoire appelé public_php sous le répertoire racine de l'utilisateur. Si le répertoire racine de l'utilisateur est /home/user, le fichier exécuté sera /home/user/public_php/doc.php.

`user_dir` et `doc_root` sont deux directives totalement indépendantes, et il est donc possible de contrôler l'accès au répertoire "document root" séparément des répertoires "user directory".

## Cas 4 : Exécutable PHP à l'extérieur de l'arborescence du serveur

Une solution extrêmement sécurisée est de mettre l'exécutable PHP à l'extérieur de l'arborescence du serveur web. Dans le répertoire /usr/local/bin, par exemple. Le seul véritable inconvénient de cette méthode est qu'il faudra rajouter une ligne comme celle-ci :

    #!/usr/local/bin/php

au début de chaque fichier contenant des balises PHP. Il faudra aussi rendre les scripts PHP exécutables. En somme, le fichier doit être traité exactement comme tout autre script écrit en Perl ou en sh ou en un autre langage de script qui utilise `#!` comme mécanisme pour lancer l'interpréteur lui-même.

Pour que l'exécutable PHP prenne en compte les variables d'environnement PATH_INFO et PATH_TRANSLATED correctement avec cette configuration, la directive INI cgi.discard_path doit être activée.

# Installé en tant que module Apache

Lorsque PHP est utilisé en tant que module Apache, celui-ci hérite des permissions accordées à l'utilisateur faisant tourner Apache (par défaut, l'utilisateur "nobody"). Ceci a plusieurs impacts sur la sécurité et les autorisations. Par exemple, lors de l'utilisation de PHP pour accéder à une base de données, à moins que la base n'ait un système de droits d'accès interne, il faudra la rendre accessible à l'utilisateur "nobody". Cela signifie qu'un script mal intentionné peut accéder à la base et la modifier, sans identification. Il est même possible qu'un robot accède à une page d'administration, et détruise toutes les bases de données. Il est possible de se protéger contre cela avec les autorisations Apache, ou définir un modèle d'accès propre en utilisant LDAP, des fichiers .htaccess, etc. et inclure ce code dans les scripts PHP.

Souvent, lorsqu'on a établi les droits de l'utilisateur PHP (ici, l'utilisateur Apache) pour minimiser les risques, on s'aperçoit que PHP ne peut plus écrire de fichiers dans les répertoires des utilisateurs. Ou encore, qu'il ne peut plus accéder à, ou modifier, une base de données privée. En somme, les sécurités mises en place empêchent à la fois l'écriture de bons et de mauvais fichiers, en même temps que les bonnes et mauvaises opérations en bases de données.

Arrivé là, une erreur de sécurité fréquente est de donner à l'utilisateur Apache les droits de superadministrateur ("root"), ou d'accroître les possibilités d'Apache d'une quelconque autre façon.

Donner de telles permissions à l'utilisateur Apache est extrêmement dangereux, et pourrait compromettre tout le système ; en conséquence, l'utilisation de sudo, de chroot, ou de toute autre solution permettant de fonctionner en tant que superadministrateur ("root"), ne devrait pas être envisagée par toute personne qui ne soit pas experte en sécurité.

Il existe des solutions plus simples. En utilisant open_basedir, il est possible de contrôler et restreindre les dossiers qui seront accessibles par PHP. Il est également possible de créer des aires de restrictions Apache, pour limiter les activités en provenance du web à des fichiers qui ne soient en rapport ni avec des utilisateurs, ni avec le système.

# Sécurité des Sessions

Il est important d'avoir une utilisation sécurisée des sessions HTTP. La sécurité liée aux sessions est abordée dans le chapitre Sessions et sécurité de la référence Gestion des sessions.

# Sécurité des fichiers

## Sommaire

- Problèmes liés aux octets nuls

PHP est soumis aux règles de sécurité intrinsèques de la plupart des systèmes serveurs : il respecte notamment les droits des fichiers et des dossiers. Une attention particulière doit être portée aux fichiers ou dossiers qui sont accessibles à tout le monde, afin de s'assurer qu'ils ne divulguent pas d'informations critiques.

Puisque PHP a été fait pour permettre aux utilisateurs d'accéder aux fichiers, il est possible de créer un script PHP qui permet de lire des fichiers tels que /etc/passwd, de modifier les connexions ethernet, lancer des impressions de documents, etc. Cela implique notamment qu'il faut s'assurer que les fichiers manipulés par les scripts sont bien ceux qu'il faut.

Dans le script suivant, l'utilisateur indique qu'il souhaite effacer un fichier dans son dossier racine. Nous supposons que PHP est utilisé comme interface web pour gérer les fichiers, et que l'utilisateur Apache est autorisé à effacer les fichiers dans le dossier racine des utilisateurs.

Exemple #1 Une erreur de vérification de variable conduit à un gros problème

    <?php

    // Efface un fichier dans un dossier racine
    $username = $_POST['user_submitted_name'];
    $userfile = $_POST['user_submitted_filename'];
    $homedir  = "/home/$username";

    unlink("$homedir/$userfile");

    echo "Ce fichier a été effacé !";

    ?>

Étant donné que le nom de l'utilisateur et le nom du fichier sont fournis, des intrus peuvent envoyer un nom d'utilisateur et un nom de fichier autres que les leurs, et effacer des documents dans les comptes des autres utilisateurs. Dans ce cas, il est préférable d'utiliser une autre forme d'identification. Il faut considérer ce qui pourrait se passer si les utilisateurs passent `../etc/` et `passwd` comme arguments ! Le code serait exécuté tel que :

Exemple #2 Une attaque du système de fichiers !

    <?php

    // Efface un fichier n'importe où sur le disque dur,
    // où l'utilisateur PHP a accès. Si PHP a un accès root :
    $username = $_POST['user_submitted_name']; // "../etc"
    $userfile = $_POST['user_submitted_filename']; // "passwd"
    $homedir  = "/home/$username"; // "/home/../etc"

    unlink("$homedir/$userfile"); // "/home/../etc/passwd"

    echo "Ce fichier a été effacé !";

    ?>

Il y a deux mesures primordiales à prendre pour éviter ces manœuvres :

- Limiter les permissions de l'utilisateur web PHP.
- Vérifier toutes les variables liées aux chemins et aux fichiers qui sont fournis.

Voici un script renforcé :

Exemple #3 Une vérification renforcée

    <?php

    // Efface un fichier sur le disque où l'utilisateur a le droit d'aller
    $username = $_SERVER['REMOTE_USER']; // utilisation d'un mécanisme d'identification
    $userfile = basename($_POST['user_submitted_filename']);
    $homedir  = "/home/$username";

    $filepath = "$homedir/$userfile";

    if (file_exists($filepath) && unlink($filepath)) {
       $logstring = "$filepath effacé\n";
    } else {
       $logstring = "Échec lors de l'effacement de $filepath\n";
    }

    $fp = fopen("/home/logging/filedelete.log", "a");
    fwrite($fp, $logstring);
    fclose($fp);

    echo htmlentities($logstring, ENT_QUOTES);
    ?>

Cependant, même cette technique n'est pas sans faille. Si le système d'identification permet aux utilisateurs de créer leur propre login, et qu'un utilisateur choisit le login `../etc/`, le système est de nouveau exposé. Pour cette raison, il est possible d'écrire un script renforcé :

Exemple #4 Vérification renforcée de noms de fichiers

    <?php

    $username     = $_SERVER['REMOTE_USER']; // utilisation d'un mécanisme d'identification
    $userfile     = $_POST['user_submitted_filename'];
    $homedir      = "/home/$username";

    $filepath     = "$homedir/$userfile";

    if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
       die("Mauvais utilisateur/nom de fichier");
    }

    // etc.

    ?>

Suivant le système d'exploitation, il faudra protéger un grand nombre de fichiers, notamment les entrées de périphériques, (/dev/ ou COM1), les fichiers de configuration (fichiers /etc/ et `.ini`), les lieux de stockage d'informations (/home/, My Documents), etc. Pour cette raison, il est généralement plus sûr d'établir une politique qui interdit TOUT sauf ce qui est autorisé.

## Problèmes liés aux octets nuls

Comme PHP utilise des fonctions C pour les opérations sous-jacentes, notamment au niveau du système de fichiers, il peut gérer les octets nuls d'une façon inattendue. Sachant que les octets nuls dénotent la fin d'une chaîne de caractères en C, certaines fonctions vont donc considérer ces chaînes jusqu'à la première occurrence d'un octet nul. L'exemple suivant présente un code vulnérable qui montre ce problème :

Exemple #1 Script vulnérable aux octets nuls

    <?php

    $file = $_GET['file']; // "../../etc/passwd\0"
    if (file_exists('/home/wwwrun/' . $file . '.php')) {
       // file_exists retournera true sachant que le fichier /home/wwwrun/../../etc/passwd existe
       include '/home/wwwrun/' . $file . '.php';
       // le fichier /etc/passwd sera inclus
    }
    ?>

Ainsi, toute chaîne utilisée dans des opérations sur le système de fichiers doit toujours être validée proprement. Voici une meilleure solution de l'exemple précédent :

Exemple #2 Validation correcte de l'entrée

    <?php

    $file = $_GET['file'];

    // Liste blanche des valeurs possibles
    switch ($file) {
       case 'main':
       case 'foo':
       case 'bar':
       include '/home/wwwrun/include/' . $file . '.php';
       break;
       default:
       include '/home/wwwrun/include/main.php';
    }

    ?>

# Sécurité des bases de données

## Sommaire

- Schéma de base de données
- Connexions au serveur de base de données
- Modèle de stockage avec chiffrement
- Injection SQL

De nos jours, les bases de données sont des composants incontournables des serveurs web et des applications en ligne, qui fournissent du contenu dynamique. Des données secrètes ou critiques peuvent être stockées dans les bases de données : il est donc important de les protéger efficacement.

Pour lire ou stocker des informations, il faut se connecter au serveur de bases de données, envoyer une requête valide, lire le résultat et refermer la connexion. De nos jours, le langage le plus courant pour ce type de communication est le langage SQL (`Structured Query Language`). Voir comment un pirate peut s'introduire dans une requête SQL.

Comme on peut s'en douter, PHP ne peut pas protéger les bases de données par lui-même. La section suivante présente les notions de base pour protéger les bases de données, lors de la programmation de scripts PHP.

Gardez bien cette règle simple en tête : la défense se fait par couches. Plus il y a de tests pour protéger la base, plus faible sera la probabilité de réussite d'un pirate. En ajoutant à cela un bon schéma de base de données, on obtient une application réussie.

## Schéma de base de données

La première étape est de créer une base de données, à moins d'utiliser une base de données déjà créée. Lorsque la base de données est créée, elle est assignée à un propriétaire, qui a exécuté l'instruction de création. Généralement, seul le propriétaire et le super utilisateur peuvent intervenir avec les tables de cette base, et il faut que ce dernier donne des droits à tous les intervenants qui auront à travailler sur cette base.

Les applications ne doivent jamais se connecter au serveur de bases de données sous le nom du propriétaire ou de l'administrateur, car ces utilisateurs ont des droits très importants, et pourront exécuter n'importe quelle requête, comme la modification de tables, l'effacement de lignes ou même encore, la destruction de la base.

Il est possible de créer différents utilisateurs de bases de données pour chaque aspect de l'application, avec des droits limités aux seules actions planifiées. Il faut alors éviter que le même utilisateur dispose des droits de plusieurs cas d'utilisation. Cela permet que si des intrus obtiennent l'accès à la base avec l'un de ces jeux de droits, ils ne puissent pas affecter toute l'application.

## Connexions au serveur de base de données

Il est recommandé d'établir des connexions au serveur avec le protocole SSL, pour chiffrer les échanges clients/serveur, afin d'améliorer la sécurité. Il est aussi possible d'utiliser un client SSH pour chiffrer la connexion entre les clients et le serveur de bases de données. Si l'une de ces deux protections est mise en place, il sera difficile de surveiller le trafic et de comprendre les informations échangées.

## Modèle de stockage avec chiffrement

Les protocoles SSL/SSH protègent les données qui circulent entre le serveur et le client : SSL/SSH ne protège pas les données une fois dans la base. SSL est un protocole en ligne.

Une fois que le pirate a obtenu l'accès direct à la base de données (en contournant le serveur web), les données sensibles, stockées dans la base sont accessibles directement, à moins que les données de la base ne soient protégées par la base. Chiffrer les données est une bonne solution pour réduire cette menace, mais très peu de bases de données offrent ce type de chiffrement.

Le moyen le plus simple pour contourner ce problème est de créer un logiciel de chiffrement propre, et de l'utiliser dans les scripts PHP. PHP peut aider dans cette tâche grâce aux nombreuses extensions dont il dispose, comme OpenSSL et Sodium, qui connaissent un large éventail de méthodes de chiffrement. Le script PHP va chiffrer les données qui seront stockées, et les déchiffrer lorsqu'elles seront relues. Voir la suite pour des exemples d'utilisation de ce chiffrement.

### Hachage

Dans le cas de données vraiment sensibles, si la représentation originale n'est pas nécessaire (pour affichage, ou comparaison), utiliser un hachage est une bonne solution. L'exemple classique est le stockage de mots de passe dans les bases de données, après les avoir passés par un hachage cryptographique.

Les fonctions password fournissent une bonne façon de hacher les données sensibles et de travailler avec ces empreintes.

La fonction password_hash() est utilisée pour hacher une chaîne donnée en utilisant l'algorithme le plus fort actuellement disponible et la fonction password_verify() vérifie si le mot de passe fourni correspond au hachage stocké en base de données.

Exemple #1 Hacher un champ mot de passe

    <?php

    // stockage du hash du mot de passe
    $query  = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
                pg_escape_string($username),
                password_hash($password, PASSWORD_DEFAULT));
    $result = pg_query($connection, $query);

    // on vérifie si l'utilisateur a soumis le bon mot de passe
    $query = sprintf("SELECT pwd FROM users WHERE name='%s';",
                pg_escape_string($username));
    $row = pg_fetch_assoc(pg_query($connection, $query));

    if ($row && password_verify($password, $row['pwd'])) {
        echo 'Bonjour, ' . htmlspecialchars($username) . '!';
    } else {
        echo 'L\'authentification a échoué pour ' . htmlspecialchars($username) . '.';
    }

    ?>

## Injection SQL

L'injection SQL est une technique où un attaquant exploite les failles dans le code d'application responsable de la création de requêtes SQL dynamiques. L'attaquant peut accéder à des sections privilégiées de l'application, récupérer toutes les informations de la base de données, altérer des données existantes, voire exécuter des commandes dangereuses au niveau système sur l'hôte de la base de données. La vulnérabilité se produit lorsque les développeurs concatènent ou interpolent une entrée arbitraire dans leurs déclarations SQL.

Exemple #1 Séparation des résultats en pages, et créer des superutilisateurs (PostgreSQL)

Dans l'exemple suivant, l'entrée de l'utilisateur est directement interpolée dans la requête SQL, permettant à l'attaquant d'obtenir un compte superutilisateur dans la base de données.

    <?php
    $offset = $_GET['offset']; // Attention, aucune validation!
    $query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
    $result = pg_query($conn, $query);
    ?>

Un utilisateur normal clique sur les boutons 'suivant' et 'précédent', qui sont alors placés dans la variable $offset, encodée dans l'URL. Le script s'attend à ce que la variable $offset soit alors un nombre. Cependant, il est possible de modifier l'URL en ajoutant une nouvelle valeur, au format URL, comme ceci :

    0;
    insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
        select 'crack', usesysid, 't','t','crack'
        from pg_shadow where usename='postgres';
    --

Si cela arrive, le script donnerait un accès super utilisateur à l'attaquant. Il est à noter que la valeur `0;` fournit un décalage valide à la requête originale et la termine correctement.

> Note:

> C'est une technique répandue que de forcer l'analyseur SQL à ignorer le reste de la requête, en utilisant les symboles `--` pour mettre en commentaires.

Un moyen disponible pour accéder aux mots de passe est de contourner la recherche de page. Ce que le pirate doit faire, c'est simplement voir si une variable du formulaire est utilisée dans la requête, et si elle est mal gérée. Ces variables peuvent avoir été configurées dans une page précédente pour être utilisées dans les clauses `WHERE, ORDER BY, LIMIT` et `OFFSET` des requêtes `SELECT`. Si la base de données supporte les commandes `UNION`, le pirate peut essayer d'ajouter une requête entière pour lister les mots de passe dans n'importe quelle table. Utiliser la technique de stocker uniquement des hachages sécurisés des mots de passe au lieu des mots de passe eux-mêmes est fortement recommandé.

Exemple #2 Liste d'articles ... et quelques mots de passe (n'importe quel serveur de bases de données)

    <?php
    $query  = "SELECT id, name, inserted, size FROM products
               WHERE size = '$size'";
    $result = odbc_exec($conn, $query);
    ?>

La partie statique de la requête, combinée avec une autre requête `SELECT`, va révéler les mots de passe :

    '
    union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
    --

Les instructions `UPDATE` et `INSERT` sont également susceptibles de telles attaques.

Exemple #3 Modifier un mot de passe ... et gain de droits ! (n'importe quel serveur de bases de données)

    <?php
    $query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
    ?>

Un internaute fourbe peut envoyer une valeur telle que `' or uid like'%admin%` dans $uid pour modifier le mot de passe utilisateur, ou simplement, utiliser la variable $pwd avec la valeur `hehehe', trusted=100, admin='yes` pour obtenir des droits supplémentaires. La requête devient alors :

    <?php

    // $uid: ' or uid like '%admin%
    $query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%';";

    // $pwd: hehehe', trusted=100, admin='yes
    $query = "UPDATE usertable SET pwd='hehehe', trusted=100, admin='yes' WHERE
    ...;";

    ?>

Bien qu'il reste évident qu'un attaquant doit posséder au moins certaines connaissances sur l'architecture de la base de données pour mener une attaque réussie, obtenir ces informations est souvent très simple. Par exemple, le code peut faire partie d'un logiciel open-source et être disponible publiquement. Ces informations peuvent également être divulguées par un code source fermé - même s'il est codé, obscurci ou compilé - et même par le code de l'application à travers l'affichage de messages d'erreur. D'autres méthodes comprennent l'utilisation de noms de table et de colonne typiques. Par exemple, un formulaire de connexion qui utilise une table 'users' avec des noms de colonnes 'id', 'username' et 'password'.

Exemple #4 Attaque du système d'exploitation de l'hôte de base de données (MSSQL Server)

Un exemple effrayant de la manière dont des commandes de niveau système d'exploitation peuvent être accessibles sur certains hôtes de base de données.

    <?php
    $query  = "SELECT * FROM products WHERE id LIKE '%$prod%'";
    $result = mssql_query($query);
    ?>

Si le pirate injecte la valeur `a%' exec master..xp_cmdshell 'net user test testpass /ADD' --` dans la variable $prod, alors la requête $query devient :

    <?php

    $query  = "SELECT * FROM products
               WHERE id LIKE '%a%'
               exec master..xp_cmdshell 'net user test testpass /ADD' --%'";
    $result = mssql_query($query);

    ?>

MSSQL Server exécute les requêtes SQL en lot, y compris la commande d'ajout d'un nouvel utilisateur à la base de données locale. Si cette application fonctionnait en tant que `sa` et que le service MSSQLSERVER disposait d'un niveau de droits suffisant, le pirate disposerait désormais d'un compte avec accès au serveur.

> Note:

> Certains exemples ci-dessus sont spécifiques à certains serveurs de bases de données, mais cela n'empêche pas des attaques similaires d'être possibles sur d'autres produits. La base de données sera alors vulnérable d'une autre manière.

Image de » xkcd

### Techniques de contournement

La méthode recommandée pour éviter les injections SQL est de lier toutes les données via des requêtes préparées. L'utilisation de requêtes paramétrées n'est pas suffisante pour éviter complètement les injections SQL, mais c'est le moyen le plus facile et le plus sûr de fournir une entrée aux instructions SQL. Toutes les valeurs littérales dynamiques dans les clauses `WHERE`, `SET` et `VALUES` doivent être remplacées par des espaces réservés. Les données réelles seront liées pendant l'exécution et envoyées séparément de la commande SQL.

La liaison de paramètres ne peut être utilisée que pour les données. Les autres parties dynamiques de la requête SQL doivent être filtrées contre une liste connue de valeurs autorisées.

Exemple #5 Éviter les injections SQL en utilisant des requêtes préparées PDO

    <?php
     // La partie SQL dynamique est validée par rapport aux valeurs attendues
     $sortingOrder = $_GET['sortingOrder'] === 'DESC' ? 'DESC' : 'ASC';
     $productId = $_GET['productId'];
     // Le SQL est préparé avec un espace réservé
     $stmt = $pdo->prepare("SELECT * FROM products WHERE id LIKE ? ORDER BY price {$sortingOrder}");
     // La valeur est fournie avec des caractères génériques LIKE
     $stmt->execute(["%{$productId}%"]);
    ?>

Les instructions préparées sont fournies par PDO, par MySQLi, et par d'autres bibliothèques de bases de données.

Les attaques par injection SQL sont principalement basées sur l'exploitation du code qui n'a pas été écrit en tenant compte de la sécurité. Il ne faut jamais faire confiance à une entrée, en particulier côté client, même si elle provient d'une boîte de sélection, d'un champ de saisie masqué ou d'un cookie. Le premier exemple montre qu'une telle requête simple peut causer des désastres.

Une stratégie de défense en profondeur implique plusieurs bonnes pratiques de codage :

- Il ne faut jamais se connecter à la base de données en tant que superutilisateur ou en tant que propriétaire de la base de données. Il convient de toujours utiliser des utilisateurs personnalisés avec des privilèges minimaux.
- Il faut vérifier si l'entrée donnée a le type de données attendu. PHP a une large gamme de fonctions de validation d'entrée, des plus simples trouvées dans Fonctions de variables et dans Fonctions de type de caractères (par exemple is_numeric(), ctype_digit() respectivement) et jusqu'à la prise en charge des Expressions régulières compatibles avec Perl.
- Si l'application s'attend à une entrée numérique, il convient de vérifier les données avec ctype_digit(), de changer silencieusement son type en utilisant settype(), ou d'utiliser sa représentation numérique avec sprintf().
- Si la couche de base de données ne prend pas en charge la liaison de variables, alors il faut mettre chaque valeur fournie par l'utilisateur non numérique entre guillemets avec la fonction d'échappement de chaîne spécifique à la base de données (par exemple mysql_real_escape_string(), sqlite_escape_string(), etc.). Les fonctions génériques comme addslashes() ne sont utiles que dans un environnement très spécifique (par exemple MySQL dans un ensemble de caractères à octets uniques avec NO_BACKSLASH_ESCAPES désactivé), il est donc préférable de les éviter.
- Il est particulièrement important de ne pas divulguer d'informations spécifiques à la base de données, en particulier sur le schéma, que ce soit de manière légale ou illégale. Se référer également à Rapport d'erreurs et Fonctions de gestion et de journalisation des erreurs.

À côté de ces conseils, il est recommandé d'enregistrer les requêtes, soit dans les scripts, soit dans la base elle-même, si elle le supporte. Évidemment, cet enregistrement ne sera pas capable d'empêcher une attaque, mais permettra de retrouver la requête qui a fauté. L'historique n'est pas très utile par lui-même mais au niveau des informations qu'il contient. Plus il y a de détails, mieux c'est.

# Rapport d'erreurs

En termes de sécurité, il y a deux conséquences au rapport d'erreur. D'un côté, cela améliore la sécurité, mais d'un autre, cela la réduit aussi.

Une tactique d'attaque standard consiste à faire faire des erreurs au système, et à analyser les types des erreurs qui sont retournées, ainsi que leur contexte. Cela permet à l'attaquant d'obtenir des informations à propos du serveur, en vue de détecter de possibles faiblesses. Par exemple, si un intrus a glané des informations sur une page dépendant de la soumission préalable d'un formulaire, il peut essayer d'écraser les variables par ses propres valeurs :

Exemple #1 Attaque de variables avec une page HTML personnalisée

    <form method="post" action="attacktarget?username=badfoo&amp;password=badfoo">
    <input type="hidden" name="username" value="badfoo" />
    <input type="hidden" name="password" value="badfoo" />
    </form>

Les erreurs PHP qui sont normalement retournées peuvent être très pratiques pour un développeur qui essaie de déboguer un script, car elles donnent de précieux renseignements tels que la fonction qui a échoué, depuis quel fichier PHP, et même le numéro de la ligne à laquelle l'erreur s'est produite. Toutes ces informations sont exploitables. Il n'est pas rare que les développeurs PHP utilisent les fonctions show_source(), highlight_string(), ou highlight_file() comme outils de débogage, mais sur un site en production, cela peut exposer des variables cachées, des syntaxes non vérifiées, ou d'autres informations critiques. Il est particulièrement dangereux d'exécuter du code de sources connues avec des gestionnaires de débogage inclus, ou de travailler avec des techniques de débogage répandues. Si l'attaquant peut déterminer quelle technique générale est utilisée, il peut tenter une attaque frontale sur une page, en envoyant des chaînes de débogage connues :

Exemple #2 Exploiter des variables classiques de débogage

    <form method="post" action="attacktarget?errors=Y&amp;showerrors=1&amp;debug=1">
    <input type="hidden" name="errors" value="Y" />
    <input type="hidden" name="showerrors" value="1" />
    <input type="hidden" name="debug" value="1" />
    </form>

Indépendamment de la méthode de gestion des erreurs, la possibilité de tester un système pour identifier des erreurs revient à fournir à un attaquant plus d'informations sur le système.

Par exemple, le style même d'une erreur PHP standard indique qu'un système fait tourner PHP. Si un attaquant affiche une page `.html`, et essaye de la tester (pour rechercher des faiblesses connues du système), en lui envoyant des données invalides, il peut déterminer qu'elle a été construite via un script PHP.

Une erreur de fonction peut indiquer si un système supporte une base de données spécifique, ou bien donner des indices quant à la façon dont une page a été conçue ou développée. Cela peut orienter l'intrus vers les ports de cette base de données ou bien vers une attaque liée à cette application. En envoyant des données erronées, par exemple, un pirate peut déterminer l'ordre d'identification dans un script (à partir des numéros de lignes d'erreurs), ou sonder à la recherche de failles qui pourraient être exploitées à différents endroits du script.

Une erreur de fichier, ou une erreur générale de PHP, peut indiquer quelles sont les permissions du serveur web, ainsi que la structure et l'organisation des fichiers. Le code de gestion d'erreurs écrit par le développeur peut aussi aggraver ce problème, en permettant l'exploitation facile d'informations préalablement "cachées".

Il y a trois solutions majeures à ces problèmes : la première est de scruter toutes les fonctions, et d'essayer de traiter toutes les erreurs. La seconde est de totalement désactiver le rapport d'erreur, dès que le script est en production. La troisième est d'utiliser les fonctions de gestion des erreurs de PHP pour créer des gestionnaires d'erreurs personnalisés. En fonction de la politique de sécurité en place, il se peut que ces solutions soient toutes les trois applicables.

Une méthode pour gagner du temps est d'utiliser la fonction error_reporting(), pour aider à sécuriser le code et détecter certaines utilisations dangereuses de variables. En testant le code avant le déploiement avec `E_ALL`, il est possible de rapidement repérer les variables qui ne sont pas protégées. Une fois que le code est prêt à être déployé, il est recommandé soit de désactiver complètement le rapport d'erreur en passant 0 à la fonction error_reporting(), soit de désactiver l'affichage des erreurs en utilisant l'option de configuration `display_errors` de php.ini. En choisissant la seconde solution, il est également recommandé de définir le chemin vers le fichier de journal d'événements en utilisant la directive de configuration `error_log`, et d'activer la directive `log_errors`.

Exemple #3 Détecter des variables non protégées avec E_ALL

    <?php
    if ($username) {
      // Non initialisée ou vérifiée avant utilisation
      $good_login = 1;
    }
    if ($good_login == 1) {
      // Si le test ci-dessus échoue, les valeurs n'ont pas été testées
      readfile ("/données/très/très/sensibles/index.html");
    }
    ?>

# Données transmises par les internautes

La plus grande faiblesse de nombreux programmes PHP ne vient pas du langage en lui-même, mais de son utilisation en omettant les caractéristiques de sécurité. Pour cette raison, il est recommandé de toujours prendre le temps de réfléchir aux implications d'une portion de code donnée, pour mesurer les éventuels dommages qui pourraient être causés si une variable inattendue lui était passée.

Exemple #1 Utilisation dangereuse de variables

    <?php
    // efface un fichier à la racine d'un utilisateur... ou peut-être
    // de quelqu'un d'autre ?
    unlink($evil_var);
    // Enregistre l'accès dans un log... ou peut-être une entrée dans /etc/passwd ?
    fwrite($fp, $evil_var);
    // Exécute une commande triviale... ou rm -rf * ?
    system($evil_var);
    exec($evil_var);
    ?>

Il est vivement recommandé d'examiner minutieusement le code pour s'assurer qu'il n'y a pas de variable envoyée par le client web qui ne soit pas suffisamment vérifiée avant utilisation, en se posant les questions suivantes :

- Est-ce que ce script n'affectera que les fichiers prévus ?
- Est-il possible que des valeurs incohérentes ou inattendues soient exploitées ici ?
- Est-ce que ce script peut être utilisé dans un but différent de celui attendu ?
- Est-ce que ce script peut être utilisé malicieusement, en conjonction avec d'autres ?
- Est-ce que toutes les actions seront correctement historisées ?

En répondant de manière adéquate à ces questions lors de l'écriture des scripts (plutôt qu'après), cela évitera une réécriture inopportune lorsqu'il faudra améliorer leur sécurité. En commençant les projets avec ces recommandations en tête, la sécurité du système ne sera pas garantie, mais elle s'en trouvera améliorée.

Il est recommandé d'améliorer la sécurité en désactivant les paramètres de commodité qui masquent l'origine, la validité ou l'intégrité des données en entrée. La création implicite de variables et l'absence de vérification des entrées peuvent entraîner des vulnérabilités telles que des attaques par injection et des manipulations de données.

Des fonctionnalités comme `register_globals` et `magic_quotes` (toutes deux supprimées à partir de PHP 5.4.0) contribuaient autrefois à ces risques en créant automatiquement des variables à partir des entrées utilisateur et en échappant les données de manière incohérente. Bien qu'elles ne soient plus présentes dans PHP, des risques similaires persistent si la gestion des entrées est mal maîtrisée.

Activer error_reporting(E_ALL) pour aider à détecter les variables non initialisées et à valider les entrées. Utiliser les types stricts (declare(strict_types=1), introduit à partir de PHP 7) pour imposer la sécurité des types, éviter les conversions involontaires et améliorer la sécurité globale.

# Masquer PHP

En général, la sécurité par l'obscurité est une des formes de sécurité les plus faibles. Mais dans certains cas, chaque action, aussi faible soit-elle, concernant la sécurité, est souhaitable.

Quelques astuces permettent de masquer PHP, ce qui peut ralentir un attaquant qui recherche des faiblesses dans le système. En réglant l'option expose_php à `off` dans le fichier php.ini, il est possible de réduire la quantité d'informations disponible.

Une autre astuce est de configurer le serveur web, comme Apache, pour qu'il utilise plusieurs types de fichiers différents avec PHP, soit localement avec un fichier .htaccess, soit dans le fichier de configuration du serveur lui-même. Il est ainsi possible d'utiliser des extensions de fichiers déroutantes comme ceci :

Exemple #1 Masquer PHP avec un autre langage

    # Faire que le code PHP ressemble à un autre langage
    AddType application/x-httpd-php .asp .py .pl

Ou le masquer complètement :

Exemple #2 Masquer PHP avec des types inconnus

    # Faire que le code PHP ressemble à un autre langage qui n'existe pas
    AddType application/x-httpd-php .bop .foo .133t

Il est aussi possible de le cacher sous forme de HTML. Cela a un léger impact négatif sur les performances générales, car tous les fichiers HTML seront aussi analysés et traités par le moteur PHP :

Exemple #3 Utiliser le type HTML pour les extensions PHP

    # Faire que le code PHP ressemble à du html
    AddType application/x-httpd-php .htm .html

Pour que cela fonctionne efficacement, il convient de renommer tous les fichiers PHP avec les extensions ci-dessus. Même si c'est une forme de sécurité du non-dit, c'est une mesure de prévention mineure, avec peu d'inconvénients.

# Être à jour

PHP, comme n'importe quel système de grande taille, est constamment testé et amélioré. Chaque nouvelle version rassemble des modifications majeures et mineures, aussi bien pour renforcer la sécurité, que pour réparer des problèmes de conception et de configuration, ainsi que d'autres points qui peuvent affecter la sécurité et la stabilité globale du système.

Comme pour les autres programmes et langages de scripts systèmes, la meilleure approche est de mettre à jour souvent, et de rester à l'écoute des dernières versions et des modifications qu'elles apportent.

- Introduction
- Considérations générales
- Binaires CGI
  - Faiblesses connues
  - Cas 1 : Seuls les fichiers publics sont servis
  - Cas 2 : Utilisation de la directive cgi.force_redirect
  - Cas 3 : Utilisation du "doc_root" ou du "user_dir"
  - Cas 4 : Exécutable PHP à l'extérieur de l'arborescence du serveur
- Installé en tant que module Apache
- Sécurité des Sessions
- Sécurité des fichiers
  - Problèmes liés aux octets nuls
- Sécurité des bases de données
  - Schéma de base de données
  - Connexions au serveur de base de données
  - Modèle de stockage avec chiffrement
  - Injection SQL
- Rapport d'erreurs
- Données transmises par les internautes
- Masquer PHP
- Être à jour

# Caractéristiques

# Identification HTTP avec PHP

Il est possible d'utiliser la fonction header() pour demander une identification (`"Authentication Required"`) au client, générant ainsi l'apparition d'une fenêtre de demande d'utilisateur et de mot de passe. Une fois que les champs ont été remplis, l'URL sera de nouveau appelée, avec les variables prédéfinies PHP_AUTH_USER, PHP_AUTH_PW et AUTH_TYPE contenant respectivement le nom d'utilisateur, le mot de passe et le type d'identification. Ces variables prédéfinies sont trouvées dans les tableaux $_SERVER. Seule la méthode d'identification simple ("Basic") est supportée. Se reporter à la fonction header() pour plus d'informations.

Voici un exemple de script qui force l'identification du client pour accéder à une page :

Exemple #1 Exemple d'identification HTTP simple

    <?php
    if (!isset($_SERVER['PHP_AUTH_USER'])) {
        header('HTTP/1.1 401 Unauthorized');
        header('WWW-Authenticate: Basic realm="My Realm"');
        echo 'Texte utilisé si le visiteur utilise le bouton d\'annulation';
        exit;
    } else {
        echo "<p>Bonjour, {$_SERVER['PHP_AUTH_USER']}.</p>";
        echo "<p>Votre mot de passe est {$_SERVER['PHP_AUTH_PW']}.</p>";
    }
    ?>

> Note: Compatibilité

> Il faut être bien prudent lors de l'utilisation d'en-têtes HTTP avec PHP. Afin de garantir un maximum de compatibilité entre les navigateurs, le mot clé "Basic" doit être écrit avec un B majuscule, et le texte de présentation doit être placé entre doubles guillemets (pas des simples), et exactement un espace doit précéder le code 401 dans l'en-tête HTTP/1.1 401. Les paramètres d'authentification doivent être séparés par des virgules.

Au lieu d'afficher simplement les variables globales PHP_AUTH_USER et PHP_AUTH_PW, il est préférable de vérifier la validité du nom d'utilisateur et du mot de passe. Par exemple, en envoyant ces informations à une base de données, ou en recherchant dans un fichier dbm.

> Note: Configuration Apache

> PHP utilise la présence de la directive `AuthType` pour déterminer si une identification externe est activée.

Il est cependant à noter que les manipulations ci-dessus n'empêchent pas quiconque contrôle une URL non identifiée de voler les mots de passe des pages protégées, sur le même serveur.

> Note: Comportement des navigateurs
> L'authentification HTTP Basic est vraiment basique, et n'a pas été conçue pour gérer les déconnexions. HTTP étant un protocole sans état, la plupart des navigateurs mettent en cache les identifiants fournis dès qu'un code de statut `2xx` est reçu, et les envoient à chaque requête, jusqu'à la fermeture du navigateur. Il n'existe pas de moyen défini pour qu'un serveur demande une nouvelle saisie des identifiants. Au fil des années, diverses solutions de contournement se sont répandues sur internet, mais elles dépendent toutes de la manière dont les différents navigateurs ont choisi de gérer des cas limites non définis (voire des violations du standard HTTP). Il est préférable d'éviter ces solutions de contournement et de ne pas utiliser l'authentification Basic pour quoi que ce soit de sérieux.

> Note: Configuration IIS
> Afin de rendre fonctionnelle l'authentification HTTP avec un serveur IIS avec la version CGI de PHP, la directive php.ini cgi.rfc2616_headers doit être définie à `0` (la valeur par défaut), et il faut éditer la configuration IIS "`Directory Security`". Cliquer sur "`Edit`" et activer uniquement "`Anonymous Access`", tous les autres champs doivent être laissés non actifs.

# Cookies

PHP supporte les cookies HTTP de manière transparente. Les cookies sont un mécanisme d'enregistrement d'informations sur le client, et de lecture de ces informations. Ce système permet d'identifier et de suivre les visiteurs. Il est possible d'envoyer un cookie avec la fonction setcookie() ou setrawcookie(). Les cookies font partie des en-têtes HTTP, ce qui impose que setcookie() soit appelée avant tout affichage de texte. Ce sont les mêmes limitations que pour header(). Il est possible d'utiliser les fonctions de bufferisation de sortie pour retarder l'affichage du script tant que l'envoi d'un cookie ou d'en-têtes n'a pas été décidé.

Tous les cookies envoyés au serveur par le client seront automatiquement inclus dans un tableau auto-global $_COOKIE si variables_order contient "C". Pour affecter plusieurs valeurs à un seul cookie, il suffit d'ajouter `[]` au nom du cookie.

Pour plus de détails, y compris des notes sur les bogues des navigateurs, voir les fonctions setcookie() et setrawcookie().

# Sessions

Le support des sessions de PHP est un mécanisme pour conserver des données entre différents accès. Cela permet de personnaliser les applications, et d'augmenter l'attrait du site. Toutes les informations sur les sessions sont disponibles dans la section sessions.

# Gestion des chargements de fichiers

## Sommaire

- Chargements de fichiers par méthode POST
- Explication sur les messages d'erreurs de chargement de fichiers
- Erreurs classiques
- Télécharger plusieurs fichiers simultanément
- Chargement par méthode PUT
- Voir aussi

## Chargements de fichiers par méthode POST

Cette fonctionnalité permet aux personnes de télécharger à la fois du texte et des fichiers binaires. Avec les fonctions d'identification et de manipulation de fichiers de PHP, il est possible de définir qui a le droit de télécharger, mais aussi ce qui sera fait du fichier une fois qu'il sera téléchargé.

PHP est capable de recevoir des fichiers émis par un navigateur conforme à la norme RFC-1867.

> Note: Notes de configuration

> Voir aussi les directives file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size et max_input_time dans php.ini

PHP supporte aussi le chargement par la méthode PUT comme dans le navigateur Netscape Composer et Amaya du W3C. Se reporter au chapitre sur le support de la méthode PUT.

Exemple #1 Formulaire de chargement de fichier

Un formulaire de téléchargement de fichiers peut être construit en créant un formulaire spécifique comme ceci :

    <!-- Le type d'encodage des données, enctype, DOIT être spécifié comme ce qui suit -->
    <form enctype="multipart/form-data" action="__URL__" method="POST">
      <!-- MAX_FILE_SIZE doit précéder le champ input de type file -->
      <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
      <!-- Le nom de l'élément input détermine le nom dans le tableau $_FILES -->
      Envoyez ce fichier : <input name="userfile" type="file" />
      <input type="submit" value="Envoyer le fichier" />
    </form>

`__URL__` dans l'exemple précédent doit être remplacé et pointé vers un fichier PHP.

Le champ caché `MAX_FILE_SIZE` (mesuré en octets) doit précéder le champ input de type file et sa valeur représente la taille maximale acceptée du fichier par PHP. Cet élément de formulaire doit toujours être utilisé, car il permet d'informer l'utilisateur que le transfert désiré est trop lourd avant d'atteindre la fin du téléchargement. Gardez à l'esprit que ce paramètre peut être "trompé" du côté du navigateur facilement, aussi ne faites pas confiance à ce dernier, ne s'agissant finalement que d'une fonctionnalité de convenance côté client. Le paramètre PHP (côté serveur) à propos de la taille maximale d'un fichier téléchargé, ne peut, lui, être trompé.

> Note:

> Il faut s'assurer que le formulaire de téléchargement de fichier contienne `enctype="multipart/form-data"`, sinon, le fichier ne sera pas téléchargé.

La variable globale $_FILES va contenir toutes les informations sur le fichier téléchargé. Son contenu est détaillé dans notre exemple ci-dessous. Il est à noter que l'on suppose que le nom de la variable du fichier téléchargé est userfile, tel que défini dans le formulaire ci-dessus, mais peut être n'importe quel nom.

$_FILES['userfile']['name']

  Le nom original du fichier, tel que sur la machine du client web.

$_FILES['userfile']['type']

  Le type MIME du fichier, si le navigateur a fourni cette information. Par exemple, cela pourra être `"image/gif"`. Ce type mime n'est cependant pas vérifié du côté de PHP et, donc, sa valeur ne doit pas être considérée comme acquise.

$_FILES['userfile']['size']

  La taille, en octets, du fichier téléchargé.

$_FILES['userfile']['tmp_name']

  Le nom temporaire du fichier qui sera chargé sur la machine serveur.

$_FILES['userfile']['error']

  Le code d'erreur associé au téléchargement de fichier.

$_FILES['userfile']['full_path']

  Le chemin entier tel que soumis par le navigateur. Cette valeur ne contient pas toujours une vraie hiérarchie de dossier, et il ne faut pas lui faire confiance. Disponible à partir de PHP 8.1.0.

Le fichier téléchargé sera stocké temporairement dans le dossier temporaire du système, à moins qu'un autre dossier soit fourni avec la directive upload_tmp_dir du php.ini. Le dossier par défaut du serveur peut être changé dans l'environnement via la variable TMPDIR. Modifier la valeur de cette variable avec la fonction putenv() dans un script PHP sera sans effet. Cette variable d'environnement peut aussi être utilisée pour s'assurer que d'autres opérations fonctionnent aussi sur les fichiers téléchargés.

Exemple #2 Validation de téléchargement de fichiers

Voir aussi les fonctions is_uploaded_file() et move_uploaded_file() pour plus d'informations. L'exemple suivant va traiter un téléversement de fichier venant d'un formulaire.

    <?php
    $uploaddir = '/var/www/uploads/';
    $uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

    echo '<pre>';
    if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
        echo "Le fichier est valide, et a été téléchargé
               avec succès. Voici plus d'informations :\n";
    } else {
        echo "Attaque potentielle par téléchargement de fichiers.
              Voici plus d'informations :\n";
    }

    echo 'Voici quelques informations de débogage :';
    print_r($_FILES);

    echo '</pre>';

    ?>

Le script PHP qui reçoit le fichier chargé doit pouvoir gérer le fichier de manière appropriée. Il est possible d'utiliser la variable $_FILES['userfile']['size'] pour recaler tous les fichiers qui sont trop gros ou trop petits. Il est possible d'utiliser la variable $_FILES['userfile']['type'] pour écarter les fichiers qui n'ont pas le bon type, mais l'utiliser uniquement pour une série de vérifications, car cette valeur est complètement sous le contrôle du client et n'est pas vérifiée du côté de PHP. Il est possible d'utiliser l'information dans $_FILES['userfile']['error'] et adapter la politique en fonction des codes d'erreur. Quelle que soit la politique choisie, il est recommandé de soit effacer le fichier du dossier temporaire, soit le déplacer.

Si aucun fichier n'est sélectionné dans le formulaire, PHP retournera `0` dans $_FILES['userfile']['size'] et rien du tout dans $_FILES['userfile']['tmp_name'].

Le fichier sera automatiquement effacé du dossier temporaire à la fin du script, s'il n'a pas été déplacé ou renommé.

Exemple #3 Envoi d'un tableau de fichiers

PHP supporte les tableaux en HTML ainsi qu'avec les fichiers.

    <form action="" method="post" enctype="multipart/form-data">
    <p>Images:
    <input type="file" name="pictures[]" />
    <input type="file" name="pictures[]" />
    <input type="file" name="pictures[]" />
    <input type="submit" value="Send" />
    </p>
    </form>

    <?php
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() peut empêcher les attaques "filesystem traversal";
            // une autre validation/nettoyage du nom de fichier peut être appropriée
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "data/$name");
        }
    }
    ?>

La barre de progression de téléchargement peut être implémentée en utilisant la progression du chargement via les sessions.

## Explication sur les messages d'erreurs de chargement de fichiers

PHP retourne un code d'erreur approprié dans le tableau de fichiers. Ce code d'erreur est accessible à l'index `error` du tableau, qui est créé durant le téléchargement par PHP. En d'autres termes, le message d'erreur est accessible dans la variable $_FILES['userfile']['error'].

La valeur de ce code d'erreur est l'une des constantes `UPLOAD_ERR_*`.

## Erreurs classiques

La variable `MAX_FILE_SIZE` ne peut pas spécifier une taille de fichier plus grande que la taille qui a été fixée par upload_max_filesize, dans le php.ini. La valeur par défaut est 2 mégaoctets.

Si une limite de mémoire est activée, une plus grande valeur de memory_limit peut être nécessaire. Il faut s'assurer d'avoir défini une valeur pour memory_limit assez grande.

Si la valeur de max_execution_time est trop petite, le temps d'exécution du script peut excéder cette valeur. Il faut s'assurer d'avoir défini une valeur pour `max_execution_time` assez grande.

> Note: max_execution_time affecte uniquement le temps d'exécution du script. Le temps passé sur l'activité qui apparaît en dehors de l'exécution du script comme les appels systèmes avec la fonction system(), la fonction sleep(), les requêtes sur les bases de données, le temps mis pour effectuer le téléchargement du fichier, etc. n'est pas inclus lors du calcul du temps maximal de l'exécution du script.

Avertissement

max_input_time définit le temps maximal, en secondes, au script pour recevoir les données ; cela inclut le téléchargement du fichier. Pour les fichiers multiples, ou les gros fichiers, ou encore pour les utilisateurs sur des connexions lentes, la valeur par défaut de `60` secondes peut être dépassée.

Si post_max_size est défini de façon trop faible, les gros fichiers ne pourront pas être téléchargés. Il faut s'assurer de définir `post_max_size` avec une taille suffisante.

La configuration de max_file_uploads contrôle le nombre maximum de fichiers qui peuvent être envoyés en une requête. Si le nombre de fichiers envoyés dépasse cette limite, alors $_FILES arrêtera la réception. Par exemple, si max_file_uploads vaut `10`, alors $_FILES ne contiendra jamais plus de 10 entités.

Ne pas valider les fichiers manipulés peut donner l'accès aux utilisateurs à des fichiers sensibles dans d'autres dossiers !

Du fait de la grande diversité des styles de listage de dossier, nous ne pouvons garantir que les fichiers avec des noms exotiques (par exemple, ceux contenant des espaces) seront traités correctement.

Le développeur ne doit pas mixer les champs `input` normaux et les champs de téléchargement dans une même variable (en utilisant un nom d'`input` comme `foo[]`).

## Télécharger plusieurs fichiers simultanément

Le téléchargement de plusieurs fichiers est possible en utilisant des noms différents dans l'attribut `name` de la balise `input`.

Il est aussi possible de télécharger plusieurs fichiers simultanément et d'obtenir les informations sous forme de tableau. Pour cela, il faut utiliser la syntaxe de tableau dans les noms de balises HTML, comme pour les sélections multiples et les boîtes à cocher.

Exemple #1 Télécharger plusieurs fichiers simultanément

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
      Envoyez plusieurs fichiers : <br />
      <input name="userfile[]" type="file" /><br />
      <input name="userfile[]" type="file" /><br />
      <input type="submit" value="Envoyer les fichiers" />
    </form>

Lorsque le formulaire ci-dessus a été envoyé, les tableaux $_FILES['userfile'], $_FILES['userfile']['name'], et $_FILES['userfile']['size'] seront initialisés.

Par exemple, supposons que les fichiers /home/test/review.html et /home/test/xwp.out ont été téléchargés. Dans ce cas, $_FILES['userfile']['name'][0] contient review.html et $_FILES['userfile']['name'][1] contient xwp.out. De même, $_FILES['userfile']['size'][0] va contenir la taille du fichier review.html, etc.

$_FILES['userfile']['name'][0], $_FILES['userfile']['tmp_name'][0], $_FILES['userfile']['size'][0] et $_FILES['userfile']['type'][0] sont aussi créées.

Avertissement

Le paramètre max_file_uploads limite le nombre de fichiers qui peuvent être envoyés en une requête. Il faut vérifier que le formulaire ne tente pas d'envoyer plus de fichiers dans la requête que ne le tolère cette limite.

Exemple #2 Téléverser un dossier entier

Dans les champs de téléversement de fichier HTML, il est possible de téléverser un dossier entier avec l'attribut `webkitdirectory`. Cette fonctionnalité est supportée dans la plupart des navigateurs modernes.

Avec l'information `full_path`, il est possible de stocker les chemins relatifs ou reconstruire la même hiérarchie de dossier sur le serveur.

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
      Envoyez ce dossier :<br />
      <input name="userfile[]" type="file" webkitdirectory multiple />
      <input type="submit" value="Envoyer les fichiers" />
    </form>

Avertissement

L'attribut `webkitdirectory` n'est pas standard et n'est pas actuellement en cours de standardisation. Ceci n'est pas à utiliser sur des sites de production tournés vers le Web : ça ne fonctionnera pas pour tous les utilisateurs. Il peut y avoir de grandes incompatibilités parmi les implémentations et le comportement peut changer dans le futur.

PHP analyse uniquement les informations des chemins relatifs soumis par le navigateur/user-agent et transmet les informations dans le tableau $_FILES. Il n'y a aucune garantie que les valeurs dans le tableau `full_path` contiennent une vraie structure de dossier et l'application PHP ne doit pas faire confiance à cette information.

## Chargement par méthode PUT

PHP supporte la méthode HTTP PUT utilisée par les navigateurs pour y stocker des fichiers sur un serveur. Les requêtes de type PUT sont beaucoup plus simples que les chargements de fichiers en utilisant le type POST, et elles ressemblent à :

    PUT /path/filename.html HTTP/1.1

Normalement, cela signifie que le client distant souhaite sauver les données qui suivent dans le fichier : /path/filename.html de l'arborescence web. Ce n'est évidemment pas très sécurisé de laisser Apache ou PHP écraser n'importe quel fichier de l'arborescence. Pour éviter ceci, il faut d'abord dire au serveur qu'un script PHP donné doit gérer la requête. Avec Apache, il y a une directive pour cela : Script. Elle peut être placée n'importe où dans le fichier de configuration d'Apache. En général, les webmestres la placent dans le bloc `<Directory>`, ou peut-être dans le bloc `<VirtualHost>`. La ligne suivante fera très bien l'affaire :

    Script PUT /put.php

Elle indique à Apache qu'il doit envoyer les requêtes de chargement par méthode PUT au script put.php. Bien entendu, cela présuppose que PHP a été activé pour qu'il prenne en charge les fichiers de type .php, et que PHP est actif. La ressource de destination pour toutes les requêtes PUT de ce script doit être le script lui-même, et non le nom du fichier que le fichier téléchargé doit avoir.

Avec PHP, on pourrait faire quelque chose comme ce qui suit dans le fichier put.php. Ceci va copier le contenu du fichier téléchargé dans le fichier myputfile.ext sur le serveur. Il est probablement souhaitable d'effectuer quelques vérifications et/ou identifier l'utilisateur avant d'effectuer cette copie de fichier.

Exemple #1 Sauvegarde de fichiers HTTP PUT

    <?php
    /* Les données PUT arrivent du flux */
    $putdata = fopen("php://input", "r");

    /* Ouvre un fichier pour écriture */
    $fp = fopen("myputfile.ext", "w");

    /* Lecture des données, 1 Ko à la fois et écriture dans le fichier */
    while ($data = fread($putdata, 1024))
    fwrite($fp, $data);

    /* Fermeture du flux */
    fclose($fp);
    fclose($putdata);
    ?>

## Voir aussi

- Sécurité des fichiers

# Utilisation des fichiers à distance

Aussi longtemps que le support des gestionnaires d'URL ("URL fopen wrapper") est activé dans le php.ini, avec l'option allow_url_fopen, il est possible d'utiliser des URL (HTTP et FTP) avec la majorité des fonctions qui utilisent un nom de fichier comme paramètre. Cela inclut notamment include, include_once, require et require_once (allow_url_include doit être actif pour les utiliser). Se reporter à Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les protocoles supportés par PHP.

Par exemple, il est possible de suivre l'exemple suivant pour ouvrir un fichier sur un serveur web distant, analyser les résultats pour extraire les informations nécessaires, et ensuite les utiliser dans une requête de base de données, ou simplement afficher les informations dans le style du site.

Exemple #1 Connaître le titre d'une page distante

    <?php
    $file = fopen ("http://www.example.com/", "r");
    if (!$file) {
      echo "<p>Impossible de lire la page.\n";
      exit;
    }
    while (!feof ($file)) {
        $line = fgets ($file, 1024);
        /* Cela ne fonctionne que si le titre et ses balises sont sur une seule ligne */
        if (preg_match ("@\<title\>(.*)\</title\>@i", $line, $out)) {
            $title = $out[1];
            break;
        }
    }
    fclose($file);
    ?>

Il est aussi possible d'écrire des fichiers sur un serveur FTP (à condition d'être connecté en tant qu'utilisateur ayant les bons droits d'accès). Seuls de nouveaux fichiers peuvent être créés avec cette méthode ; toute tentative d'écraser un fichier existant fera que l'appel à fopen() échouera.

Pour se connecter avec un utilisateur autre qu'anonyme, il faut spécifier un nom d'utilisateur (et éventuellement le mot de passe) dans l'URL, comme `ftp://user:password@ftp.example.com/path/to/file`. (Il est possible d'utiliser le même type de syntaxe pour accéder aux fichiers via HTTP lorsqu'ils nécessitent une identification simple).

Exemple #2 Stocker des données sur un serveur distant

    <?php
    $file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
    if (!$file) {
      echo "<p>Impossible d'ouvrir le fichier distant pour écriture.\n";
      exit;
    }
    /* Écriture des données. */
    fwrite ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
    fclose ($file);
    ?>

> Note:

> On pourrait avoir l'idée, à partir de l'exemple ci-dessus, d'utiliser la même technique pour écrire dans un fichier de log distant. Malheureusement cela ne fonctionnerait pas car l'appel à fopen() échouera si le fichier distant existe déjà. Pour faire de la journalisation distribuée, il est recommandé de plutôt regarder du côté de syslog().

# Gestion des connexions

Le statut des connexions est conservé en interne par PHP. Il y a quatre états possibles :

- 0 - NORMAL (normal)
- 1 - ABORTED (annulé)
- 2 - TIMEOUT (périmé)
- 3 - ABORTED and TIMEOUT (annulé et périmé)

Lorsqu'un script PHP est en cours d'exécution, l'état est NORMAL. Si le client distant se déconnecte, le statut devient ABORTED. Une déconnexion du client distant est généralement causée par les utilisateurs appuyant sur leur bouton STOP. Si la durée maximale d'exécution de PHP est dépassée, (voir set_time_limit()), le script prend le statut TIMEOUT.

Il est en outre possible de décider si la déconnexion d'un client provoque l'arrêt du script. Il est parfois pratique que les scripts continuent à s'exécuter jusqu'à la fin, même si le client n'est plus là pour recevoir les informations. Cependant, par défaut, le script s'arrêtera dès que le client se déconnecte. Ce comportement peut être modifié avec la directive ignore_user_abort dans le fichier php.ini ou bien avec la directive Apache `php_value ignore_user_abort` du fichier Apache httpd.conf ou avec la fonction ignore_user_abort(). Si PHP n'est pas configuré pour ignorer la déconnexion, et que l'utilisateur se déconnecte, le script sera terminé. La seule exception est si une fonction de fermeture a été enregistrée, avec register_shutdown_function(). Avec une telle fonction, lorsque l'utilisateur interrompt sa requête, à la prochaine exécution du script, PHP va s'apercevoir que le dernier script n'a pas été terminé, et il va déclencher la fonction de fermeture. Cette fonction sera aussi appelée à la fin du script, si celui-ci se termine normalement. Pour pouvoir avoir un comportement différent suivant l'état du script lors de sa finalisation, il est possible d'exécuter des commandes spécifiques à la déconnexion grâce à la commande connection_aborted(). Cette fonction retournera `true` si la connexion a été annulée.

Le script peut aussi être automatiquement interrompu après une certaine durée. Par défaut, le délai est de 30 secondes. Cette valeur peut être changée en utilisant la directive PHP max_execution_time dans le fichier php.ini ou avec la directive `php_value max_execution_time`, dans le fichier Apache httpd.conf ou encore avec la fonction set_time_limit(). Lorsque le délai expire, le script est terminé, et comme pour la déconnexion du client, une fonction de terminaison sera appelée. Dans cette fonction, il est possible de savoir si c'est le délai d'expiration qui a causé la fin du script, en appelant la fonction connection_status(). Cette fonction retournera 2 si le délai d'expiration a été dépassé.

Une chose à noter est que les deux cas ABORTED et TIMEOUT peuvent être actifs en même temps. Ceci est possible si l'on demande à PHP d'ignorer les déconnexions des utilisateurs. PHP va quand même noter le fait que l'utilisateur s'est déconnecté, mais le script va continuer. Puis, lorsqu'il atteint la limite de temps, le script va expirer. À ce moment-là, la fonction connection_status() retournera 3.

# Connexions persistantes aux bases de données

### Qu'est-ce que les connexions persistantes ?

Les connexions persistantes aux bases de données SQL sont des connexions qui ne se referment pas à la fin du script. Lorsqu'une connexion persistante est demandée, PHP vérifie s'il existe déjà une connexion persistante identique (qui aurait été ouverte précédemment) et, si tel est le cas, la réutilise ; sinon, il en crée une nouvelle. Une connexion identique est une connexion ouverte sur le même hôte, avec le même nom d'utilisateur et le même mot de passe (s'ils sont nécessaires).

Il n'y a pas de méthode pour demander une connexion spécifique, ou garantir que l'on obtient une connexion existante ou une toute nouvelle (si toutes les connexions sont utilisées, ou si la requête est servie par un autre processus, qui a un ensemble de connexions séparé).

Cela signifie qu'il n'est pas possible d'utiliser les connexions persistantes PHP pour, par exemple :

- assigner une session de base de données spécifique à un utilisateur web spécifique
- créer une grande transaction à travers plusieurs requêtes
- initier une requête sur une demande et collecter les résultats sur une autre

Les connexions persistantes ne donnent aucune fonctionnalité qui n'était pas possible avec des connexions non persistantes.

### Requêtes Web

Il existe deux façons pour le serveur web d'utiliser PHP pour générer des pages web :

La première est d'utiliser PHP comme un CGI (Common Gateway Interface). Lorsque PHP fonctionne de cette manière, une instance de l'interpréteur PHP est créée puis détruite pour chaque page demandée. Étant donné que cet interpréteur est détruit après chaque requête, toutes les ressources acquises (comme une connexion à une base SQL), sont purement et simplement détruites. Dans ce cas, il n'y a rien à gagner à utiliser des connexions persistantes - elles ne persistent tout simplement pas.

La deuxième méthode, de loin la plus prisée, est d'exécuter PHP-FPM, ou PHP sous la forme d'un module sur un serveur multiprocessus, ce qui revient à dire : Apache. Ces configurations ont généralement un processus (le parent) qui coordonne un ensemble de processus fils, qui servent les fichiers. Lorsque les requêtes parviennent depuis un client, elles sont transmises à un fils disponible. Cela signifie que si un client fait une deuxième requête, il peut être servi par un processus fils différent du premier. Une fois qu'une connexion persistante est ouverte, toute requête ultérieure servie par le même processus fils peut réutiliser la connexion déjà établie vers le serveur SQL.

> Note:

> Il est possible de vérifier quelle méthode les requêtes web utilisent en vérifiant la valeur de "Server API" dans la sortie de phpinfo() ou la valeur de `PHP_SAPI`, exécutée depuis une requête web.

> Si la valeur de Server API est "Apache 2 Handler" ou "FPM/FastCGI", alors les connexions persistantes seront utilisées entre les requêtes servies par le même worker. Pour toute autre valeur, les connexions persistantes ne persisteront pas après chaque requête.

### Processus en ligne de commande

Comme PHP en ligne de commande utilise un nouveau processus pour chaque script, les connexions persistantes ne sont pas partagées entre les scripts en ligne de commande, donc il n'y a aucun intérêt à les utiliser dans des scripts transitoires tels que les crons ou les commandes. Cependant, elles peuvent être utiles si, par exemple, l'on écrit un serveur d'applications de longue durée qui sert de nombreuses requêtes ou tâches et que chacune peut avoir besoin de sa propre connexion à la base de données.

### Pourquoi les utiliser ?

Les connexions persistantes sont utiles si le coût de création d'une liaison vers le serveur SQL est élevé. Que ce coût soit réellement élevé ou pas ceci dépend de nombreux facteurs : le type de base de données, cette base est-elle sur le même serveur ou pas, quelle est la charge du serveur de base de données, etc. Si le temps de connexion est long, les connexions persistantes seront bien utiles, car une fois ouverte par un processus fils, la connexion est réutilisable sans avoir à se reconnecter. Avec 20 processus fils, il suffit d'avoir 20 connexions persistantes ouvertes, une par fils.

### Inconvénients potentiels : limites de connexion

Il est à noter que les connexions persistantes ont quelques inconvénients lors de l'hébergement d'une base de données dont le nombre maximal de connexion risque d'être atteint par les connexions persistantes. Si la base de données a une limite de 16 connexions simultanées, et que lors d'une session serveur chargée, 17 processus fils tentent de se connecter, l'un d'entre eux ne pourra pas. S'il y a des bogues dans les scripts qui empêchent les connexions de se fermer (comme des boucles infinies), la base de données avec seulement 16 connexions peut être rapidement submergée.

Les connexions persistantes augmenteront généralement le nombre de connexions ouvertes à un moment donné parce que les travailleurs inactifs conserveront les connexions pour les requêtes précédentes qu'ils ont servies. Si un grand nombre de travailleurs est lancé pour gérer un afflux de requêtes, les connexions qu'ils ont ouvertes resteront jusqu'à ce que le travailleur soit tué ou que le serveur de base de données ferme la connexion.

Il faut s'assurer que le nombre maximal de connexions autorisées par le serveur de base de données est supérieur au nombre maximal de travailleurs de requêtes web (plus toute autre utilisation telle que les crons ou les connexions administratives).

Vérifier la documentation de la base de données pour des informations sur la gestion des connexions abandonnées ou inactives (timeouts). Des timeouts longs peuvent augmenter considérablement le nombre de connexions persistantes ouvertes à un moment donné.

### Inconvénients potentiels : Maintien de l'état de connexion

Certaines extensions de base de données effectuent un nettoyage automatique lorsque la connexion est réutilisée ; d'autres laissent cette tâche à la discrétion du développeur d'application. En fonction de l'extension de base de données choisie et de la conception de l'application, un nettoyage manuel peut être nécessaire avant la fin du script. Les modifications qui peuvent laisser les connexions dans un état inattendu incluent :

- Base de données sélectionnée / par défaut
- Verrous de table
- Transactions non commises
- Tables temporaires
- Paramètres ou fonctionnalités spécifiques à la connexion telles que le profilage

Les verrous de table et les transactions qui ne sont pas nettoyés ou fermés peuvent entraîner le blocage indéfini d'autres requêtes et/ou provoquer des modifications inattendues lors de la réutilisation ultérieure de la connexion.

Avoir la mauvaise base de données sélectionnée entraînera la réutilisation de la connexion incapable d'exécuter les requêtes suivantes comme prévu (ou de les exécuter sur la mauvaise base de données si les schémas sont suffisamment similaires).

Si les tables temporaires ne sont pas nettoyées, les requêtes suivantes ne pourront pas recréer la même table.

Il est possible d'implémenter le nettoyage en utilisant des destructeurs de classe ou register_shutdown_function(). Il est également possible d'envisager des proxies de mise en pool de connexions dédiés qui incluent cela dans leur fonctionnalité.

### Derniers mots

Étant donné leur comportement et les inconvénients potentiels décrits ci-dessus, il est recommandé de ne pas utiliser les connexions persistantes sans une réflexion approfondie. Elles ne devraient pas être utilisées sans mettre en œuvre des modifications supplémentaires dans l'application et une configuration soigneuse du serveur de base de données et du serveur web et/ou PHP-FPM.

Considérez des solutions alternatives telles que l'investigation et la correction des causes des surcoûts de création de connexion (par exemple, la désactivation des recherches DNS inverses sur le serveur de base de données), ou des proxies de mise en pool de connexions dédiés.

Pour les API web à fort volume, envisagez d'utiliser des runtimes alternatifs ou des serveurs d'applications de longue durée.

### Voir aussi

- ibase_pconnect()
- oci_pconnect()
- odbc_pconnect()
- pfsockopen()
- pg_connect()
- MySQLi et les connexions persistantes
- Gestion de connexions PDO

# Utiliser PHP en ligne de commande

## Sommaire

- Différences avec les autres SAPIs
- Options
- Utilisation
- Flux I/O
- Shell Interactif
- Serveur web interne
- Configurations INI

## Introduction

Le but premier de CLI SAPI est le développement d'applications shell avec PHP. Les différences entre le CLI SAPI et les autres SAPI sont expliquées dans ce chapitre. Il est important de mentionner que CLI et CGI sont des SAPI différents malgré le fait qu'ils puissent partager la majeure partie de leurs comportements.

Le CLI SAPI est activé par défaut en utilisant l'option --enable-cli, mais il est possible de le désactiver en utilisant l'option --disable-cli lors de l'exécution de la commande ./configure.

Le nom, l'emplacement et l'existence des binaires CLI/CGI vont dépendre de la façon dont PHP est installé sur le système. Par défaut, en exécutant make, les deux binaires CGI et CLI sont compilés et nommés respectivement sapi/cgi/php-cgi et sapi/cli/php dans le répertoire source PHP. On remarquera que les deux se nomment php. Ce qui se passe ensuite pendant le make install dépend de la ligne de configuration. Si un module SAPI, apxs par exemple, a été choisi pendant la configuration, ou que l'option --disable-cgi a été activée, le CLI est copié dans {PREFIX}/bin/php pendant le make install sinon, le CGI sera placé ici. Si, par exemple, --with-apxs figure dans la ligne de configuration, le CLI est copié dans {PREFIX}/bin/php pendant le make install. Pour forcer l'installation du binaire CGI, lancez make install-cli après le make install. Sinon, il est aussi possible de spécifier --disable-cgi dans la ligne de configuration.

> Note:

> Du fait que les deux options --enable-cli et --enable-cgi sont activées par défaut, avoir simplement --enable-cli dans la ligne de configuration n'implique pas nécessairement que le CLI soit renommé en {PREFIX}/bin/php pendant le make install.

Le binaire CLI est distribué dans le dossier principal sous le nom de php.exe sous Windows. La version CGI est distribuée sous le nom de php-cgi.exe. De plus, un fichier php-win.exe est distribué si PHP est configuré en utilisant l'option de configuration --enable-cli-win32. Ce fichier fait la même chose que la version CLI, sauf qu'il n'affiche rien et qu'il ne fournit pas de console.

> Note: Quel SAPI est installé ?

> À partir d'un terminal, lancer php -v indiquera si php est en version CGI ou CLI. Il est aussi possible de consulter la fonction php_sapi_name() et la constante `PHP_SAPI`.

> Note:

> Une page `man` de manuel Unix est disponible en tapant man php dans l'interpréteur de commande.

## Différences avec les autres SAPIs

Les différences les plus notables entre le CLI SAPI et les SAPI sont :

- Contrairement au CGI SAPI, aucun en-tête HTTP n'est écrit dans le résultat.

  Bien que le CGI SAPI fournisse un moyen de supprimer les en-têtes HTTP, il n'est pas possible d'activer les en-têtes HTTP dans le CLI SAPI.

  CLI est lancé en mode silencieux par défaut, bien que les options -q et --no-header soient gardées pour rester compatible avec les anciennes versions CGI.

  Il ne change pas le répertoire courant en celui du script. (les options -C et --no-chdir sont gardées par souci de compatibilité)

  Messages d'erreurs en texte brut (pas de formatage HTML).

- Il y a plusieurs directives du php.ini qui sont redéfinies par le CLI SAPI, car elles n'ont pas de sens en environnement shell :

  Directives php.ini redéfinies
  Directive | Valeur par défaut pour CLI SAPI | Commentaire
  --- | --- | ---
  html_errors | `false` | Par défaut à `false`, vu qu'il peut être bien difficile de lire des messages d'erreur sur un terminal lorsqu'ils sont noyés dans des balises HTML non-interprétées.
  implicit_flush | `true` | Dans un terminal, il est généralement souhaitable que tout affichage en provenance de print, echo et autres, soit immédiatement affiché, et non pas placé dans un buffer quelconque. Néanmoins, il est toujours possible d'utiliser la bufferisation de sortie pour retarder un affichage, ou bien en manipuler le contenu une dernière fois.
  max_execution_time | 0 (sans limite) | PHP dans un terminal est susceptible d'être utilisé pour des tâches bien plus diverses que dans des scripts web, et vu que cela prend généralement beaucoup de temps, ce paramètre sera défini par défaut à 0 permettant ainsi d'être illimité.
  register_argc_argv | `true` | La définition à `true` de cette directive signifie que les scripts exécutés via le SAPI CLI auront toujours accès à argc (représentant le nombre d'arguments passés à l'application) et argv (le tableau contenant les arguments passés). Les variables PHP $argc et $argv sont automatiquement définies et remplies avec les valeurs appropriées, lors de l'utilisation du SAPI CLI. Ces valeurs peuvent également être trouvées dans la variable $_SERVER, par exemple : $_SERVER['argv']. Avertissement La présence de $argv ou $_SERVER['argv'] n'est pas une indication fiable qu'un script est exécuté depuis la ligne de commande, car ces variables peuvent être définies dans d'autres contextes lorsque register_argc_argv est activé. La valeur retournée par php_sapi_name() devrait être vérifiée à la place.
      <?php

      if (php_sapi_name() === 'cli') {
          echo "Ce script est exécuté depuis la ligne de commande !\n";
      }
  Avertissement Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonctionnalité est fortement déconseillé.
  output_buffering | `false` | Même si cette configuration INI est codée en dur à `false`, les fonctions relatives à l'affichage du buffer sont disponibles.
  max_input_time | `false` | Le PHP CLI ne supporte pas GET, POST et le téléchargement de fichiers.

  > Note:

  > Ces directives ne peuvent pas être initialisées avec d'autres valeurs dans le fichier php.ini ou par une autre méthode. C'est une limitation, car ces valeurs par défaut s'appliquent une fois que tous les autres fichiers de configuration ont été analysés. Cependant, ces valeurs peuvent être modifiées durant l'exécution (ce qui n'est pas logique pour certaines directives, comme register_argc_argv).

  > Note:

  > Il est recommandé de définir ignore_user_abort pour les scripts en ligne de commande. Voir la fonction ignore_user_abort() pour plus d'informations.

- Pour faciliter le travail en environnement shell, plusieurs constantes sont définies pour les flux I/O.

- Le CLI SAPI ne transforme pas le dossier courant en dossier d'exécution du script.

  Exemple #1 Exemple montrant la différence avec le SAPI CGI :

      <?php
      // Un test simple : affiche le dossier d'exécution
      echo getcwd(), "\n";
      ?>

  Lors de l'utilisation de la version CGI, l'affichage sera :

      $ pwd
      /tmp

      $ php -q autre_dossier/test.php
      /tmp/autre_dossier

  Cela montre clairement que PHP modifie le dossier courant, et utilise le dossier du script exécuté.

  En utilisant le CLI SAPI, on obtient :

      $ pwd
      /tmp

      $ php -f autre_dossier/test.php
      /tmp

  Cela donne beaucoup plus de souplesse lors de la rédaction de scripts shell avec PHP.

  > Note:

  > Le CGI SAPI se comporte de la même façon que le CLI SAPI, en lui passant l'option -C, lorsqu'il est invoqué en ligne de commande.

## Options de ligne de commande

La liste des options de ligne de commande fournies par PHP est disponible à n'importe quel moment en exécutant PHP avec l'option -h :

    Usage: php [options] [-f] <file> [--] [args...]
       php [options] -r <code> [--] [args...]
       php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
       php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
       php [options] -- [args...]
       php [options] -a

      -a               Run interactively
      -c <path>|<file> Look for php.ini file in this directory
      -n               No php.ini file will be used
      -d foo[=bar]     Define INI entry foo with value 'bar'
      -e               Generate extended information for debugger/profiler
      -f <file>        Parse and execute <file>.
      -h               This help
      -i               PHP information
      -l               Syntax check only (lint)
      -m               Show compiled in modules
      -r <code>        Run PHP <code> without using script tags <?..?>
      -B <begin_code>  Run PHP <begin_code> before processing input lines
      -R <code>        Run PHP <code> for every input line
      -F <file>        Parse and execute <file> for every input line
      -E <end_code>    Run PHP <end_code> after processing all input lines
      -H               Hide any passed arguments from external tools.
      -S <addr>:<port> Run with built-in web server.
      -t <docroot>     Specify document root <docroot> for built-in web server.
      -s               Output HTML syntax highlighted source.
      -v               Version number
      -w               Output source with stripped comments and whitespace.

      args...          Arguments passed to script. Use -- args when first argument
                       starts with - or script is read from stdin

      --ini            Show configuration file names

      --rf <name>      Show information about function <name>.
      --rc <name>      Show information about class <name>.
      --re <name>      Show information about extension <name>.
      --rz <name>      Show information about Zend extension <name>.
      --ri <name>      Show configuration for extension <name>.

Options de ligne de commande
Option | Option longue | Description
--- | --- | ---
-a | --interactive | Lance PHP de façon interactive. Pour plus d'informations, se reporter à la documentation concernant le shell interactif.
-b | --bindpath | Lie le chemin pour les externes, en mode serveur FASTCGI (CGI uniquement).
-C | --no-chdir | Ne pas aller dans le dossier du script (CGI uniquement).
-q | --no-header | Mode silencieux. Supprime la sortie des en-têtes HTTP (CGI uniquement).
-T | --timing | Mesure le temps d'exécution du script, répété count fois (CGI uniquement).
-c | --php-ini | Spécifie le nom du dossier dans lequel se trouve le fichier php.ini, ou encore spécifie un fichier de configuration (`INI`) directement (qui ne s'appelle pas obligatoirement php.ini) :
    $ php -c /custom/directory/ mon_script.php

    $ php -c /custom/directory/custom-file.ini mon_script.php
Si cette option n'est pas spécifiée, php.ini est recherché dans les endroits par défaut.
-n | --no-php-ini | Ignore totalement php.ini.
-d | --define | Définit une valeur personnalisée pour n'importe quelle directive de configuration du fichier php.ini. La syntaxe est :
     -d configuration_directive[=value]
Exemple #1 Exemple d'utilisation de `-d` pour définir une directive INI
    # L'omission de la valeur conduit à donner la valeur de "1"
    $ php -d max_execution_time
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(1) "1"

    # Passer une valeur vide conduit à donner la valeur de ""
    php -d max_execution_time=
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(0) ""

    # La directive de configuration sera n'importe quelle valeur passée après le caractère '='
    $  php -d max_execution_time=20
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(2) "20"
    $  php
            -d max_execution_time=doesntmakesense
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(15) "doesntmakesense"
-e | --profile-info | Génère des informations étendues pour le profilage et le débogage.
-f | --file | Analyse et exécute le fichier spécifié. L'option -f est facultative, et peut être omise. Le seul nom du fichier est suffisant.
-h et -? | --help et --usage | Affiche des informations sur la liste courante des options de la ligne de commande, ainsi que leur description.
-i | --info | Appelle la fonction phpinfo(), et affiche le résultat. Si PHP ne fonctionne pas correctement, il est recommandé d'utiliser la commande php -i et de voir s'il n'y a pas d'erreurs affichées avant ou après la table d'information. N'oubliez pas que le résultat de cette option, lors de l'utilisation du mode CGI, est au format HTML, et donc de taille conséquente.
-l | --syntax-check | Vérifie la syntaxe mais n'exécute pas le code PHP donné. L'entrée provenant de l'entrée standard sera traitée si aucun nom de fichier n'est spécifié, sinon chaque fichier spécifié sera vérifié. En cas de réussite, le message `No syntax errors detected in <filename>` (Littéralement, aucune erreur de syntaxe n'a été détectée dans le fichier) est affiché sur la sortie standard. En cas d'erreur, le message `Errors parsing <filename>` (Littéralement, erreur d'analyse dans le fichier filename) est affiché, en plus des messages d'erreurs détectés par l'analyseur lui-même. Si des erreurs sont trouvées dans les fichiers spécifiés (ou l'entrée standard), le code de retour du shell est défini à `-1`, sinon le code de retour du shell est défini à `0`. Cette option ne détecte pas les erreurs fatales (par exemple les fonctions non définies) qui nécessitent l'exécution du code. Note: Antérieur à PHP 8.3.0, il n'était possible de spécifier qu'un seul nom de fichier à vérifier. Note: Cette option ne fonctionne pas avec l'option -r.
-m | --modules | Exemple #2 Affichage des modules internes (et chargés) de PHP et Zend
    $ php -m
    [PHP Modules]
    xml
    tokenizer
    standard
    session
    posix
    pcre
    overload
    mysql
    mbstring
    ctype

    [Zend Modules]
> -r | --run | Permet l'exécution de PHP directement dans la ligne de commande. Les balises de PHP (`<?php` et `?>`) ne sont pas nécessaires, et causeront une erreur d'analyse si elles sont présentes. Note: Une attention toute particulière doit être portée lors de l'utilisation de cette option de PHP, pour qu'il n'y ait pas de collision avec les substitutions de variables en ligne de commande, réalisées par le shell. Exemple #3 Erreur de syntaxe lors de l'utilisation de doubles guillemets
>     $ php -r "$foo = get_defined_constants();"
>     PHP Parse error:  syntax error, unexpected '=' in Command line code on line 1

>     Parse error: syntax error, unexpected '=' in Command line code on line 1
> Le problème ici est que le shell (sh/bash) effectue une substitution de variables, même avec les guillemets doubles `"`. Puisque la variable $foo n'est probablement pas définie dans le shell, elle est remplacée par rien, ce qui fait que le code passé à PHP pour l'exécution est :
>     $ php -r " = get_defined_constants();"
> La solution de ce problème est d'utiliser les guillemets simples `'`. Les variables de ces chaînes ne seront pas substituées par leurs valeurs par le shell. Exemple #4 Utilisation de guillemets simples pour éviter une substitution par le shell
>     $ php -r '$foo = get_defined_constants(); var_dump($foo);'
>     array(370) {
>       ["E_ERROR"]=>
>       int(1)
>       ["E_WARNING"]=>
>       int(2)
>       ["E_PARSE"]=>
>       int(4)
>       ["E_NOTICE"]=>
>       int(8)
>       ["E_CORE_ERROR"]=>
>       [...]
Si un shell différent de sh/bash est utilisé, d'autres problèmes pourront être rencontrés - si approprié, un rapport de bogues pourra être ouvert à » https://github.com/php/php-src/issues. Il est toujours très facile d'avoir des problèmes en essayant d'inclure des variables shell dans le code, ou d'utiliser les antislashs pour la protection. Considérez-le comme un avertissement ! Note: -r est disponible avec le CLI SAPI mais pas avec le SAPI CGI. Note: Cette option est seulement utilisée pour des choses simples. Ainsi, quelques directives de configuration (par exemple auto_prepend_file et auto_append_file) sont ignorées dans ce mode.
-B | --process-begin | Code PHP à exécuter avant le traitement de stdin.
-R | --process-code | Code PHP à exécuter pour chaque ligne en entrée. Il y a deux variables spéciales de disponibles dans ce mode : $argn et $argi. $argn doit contenir la ligne PHP traitée à ce moment donné, tandis que $argi doit contenir le numéro de la ligne.
-F | --process-file | Fichier PHP à exécuter pour chaque ligne en entrée.
-E | --process-end | Code PHP à exécuter après avoir effectué l'entrée. Exemple #5 Exemple d'utilisation des options -B, -R et -E pour compter le nombre de lignes d'un projet.
    $ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
    Total Lines: 37328
-S | --server | Démarre le serveur web interne.
-t | --docroot | Spécifie la racine des documents pour le serveur web interne.
-s | --syntax-highlight et --syntax-highlighting | Affiche le code avec la colorisation syntaxique. Cette option utilise le mécanisme interne pour analyser le fichier, et écrire au format HTML une version colorisée du code source. Il est à noter que cette option ne fait que générer un bloc HTML, avec les balises HTML `<code> [...] </code>`, sans en-têtes HTML. Note: Cette option ne fonctionne pas avec l'option -r.
-v | --version | Exemple #6 Utilisation de l'option -v pour récupérer le nom du SAPI ainsi que la version de PHP et de Zend
    $ php -v
    PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07)
    Copyright (c) 1997-2009 The PHP Group
    Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies
-w | --strip | Affiche la source sans les commentaires ni les espaces. Note: Cette option ne fonctionne pas avec l'option -r.
| --ini | Affiche les noms des fichiers de configuration et des dossiers analysés. Il est également possible de passer `--ini=diff` pour afficher les différences entre les fichiers de configuration chargés et la configuration par défaut. Exemple #7 Exemple avec `--ini`
    $ php --ini
    Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
    Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
    Scan for additional .ini files in: (none)
    Additional .ini files parsed:      (none)
Note: L'option `--ini=diff` n'est pas disponible avant PHP 8.5.0.
--rf | --rfunction | Affiche des informations sur la fonction donnée ou la méthode d'une classe (c.-à-d. nombre et nom des paramètres). Cette option n'est disponible que si PHP a été compilé avec le support Reflection. Exemple #8 Exemple avec `--rf`
    $ php --rf var_dump
    Function [ <internal> public function var_dump ] {

      - Parameters [2] {
        Parameter #0 [ <required> $var ]
        Parameter #1 [ <optional> $... ]
      }
    }
--rc | --rclass | Affiche des informations sur la classe donnée (liste des constantes, propriétés et méthodes). Cette option n'est disponible que si PHP a été compilé avec le support Reflection. Exemple #9 Exemple avec `--rc`
    $ php --rc Directory
    Class [ <internal:standard> class Directory ] {

      - Constants [0] {
      }

      - Static properties [0] {
      }

      - Static methods [0] {
      }

      - Properties [0] {
      }

      - Methods [3] {
        Method [ <internal> public method close ] {
        }

        Method [ <internal> public method rewind ] {
        }

        Method [ <internal> public method read ] {
        }
      }
    }
--re | --rextension | Affiche les informations sur l'extension donnée (liste les options du php.ini, les fonctions définies, les constantes et les classes). Cette option n'est disponible que si PHP a été compilé avec le support Reflection. Exemple #10 Exemple avec `--re`
    $ php --re json
    Extension [ <persistent> extension #19 json version 1.2.1 ] {

      - Functions {
        Function [ <internal> function json_encode ] {
        }
        Function [ <internal> function json_decode ] {
        }
      }
    }
--rz | --rzendextension | Affiche les informations de configuration pour l'extension Zend fournie (les mêmes informations que celles retournées par la fonction phpinfo()).
--ri | --rextinfo | Affiche les informations de configuration pour l'extension donnée (les mêmes informations retournées par la fonction phpinfo()). Les informations de configurations internes sont disponibles en utilisant le nom d'extension "main". Exemple #11 Exemple avec `--ri`
    $ php --ri date

    date

    date/time support => enabled
    "Olson" Timezone Database Version => 2009.20
    Timezone Database => internal
    Default timezone => Europe/Oslo

    Directive => Local Value => Master Value
    date.timezone => Europe/Oslo => Europe/Oslo
    date.default_latitude => 59.930972 => 59.930972
    date.default_longitude => 10.776699 => 10.776699
    date.sunset_zenith => 90.583333 => 90.583333
    date.sunrise_zenith => 90.583333 => 90.583333

> Note:

> Les options `-rBRFEH`, `--ini` et `--r[fcezi]` ne sont disponibles qu'en mode CLI.

## Exécution de fichiers PHP

Il y a 3 façons différentes d'appeler le CLI SAPI avec du code PHP à exécuter :

1. Indiquer à PHP d'exécuter un fichier donné :

       php mon_script.php

       php -f mon_script.php

   Les deux méthodes (en utilisant -f ou pas) exécutent le script contenu dans le fichier mon_script.php. Notez qu'il n'existe pas de restriction sur les fichiers pouvant être exécutés ; en particulier, il n'est pas nécessaire que l'extension du fichier soit `.php`.

2. Donner du code PHP à exécuter directement en ligne de commande.

       php -r 'print_r(get_defined_constants());'

   Une attention particulière doit alors être apportée aux variables d'environnement, qui seront remplacées, et aux guillemets, qui ont des significations spéciales en ligne de commande.

   > Note:

   > Lire l'exemple attentivement, il n'y a ni balise d'ouverture, ni balise de fermeture ! L'option -r rend caduque l'utilisation de celles-ci, et les ajouter conduirait alors à une erreur d'analyse syntaxique.

3. Alimenter l'entrée standard en code PHP (`stdin`).

   Cela donne la possibilité de créer dynamiquement du code PHP, puis de le fournir à PHP, et enfin, de le traiter à nouveau en shell. Voici un exemple fictif :

       $ some_application | some_filter | php | sort -u > final_output.txt

Il n'est pas possible de combiner ces trois modes d'exécution.

Comme toute application shell, l'exécutable PHP accepte des arguments ; cependant, le script PHP peut aussi en recevoir. Le nombre d'arguments pouvant être passés au script n'est pas limité par PHP (le shell a une limite en termes de nombre de caractères qui peuvent être passés. Généralement, cette limite ne sera pas atteinte). Les arguments passés au script seront transmis via la variable tableau $argv. Le premier index (zéro) contient toujours le nom du script appelé depuis la ligne de commande. Il est à noter que, si le code est exécuté en ligne en utilisant l'option de ligne de commande -r, la valeur de $argv[0] sera `"Standard input code"`; antérieur à PHP 7.2.0, c'était un tiret (`"-"`) à la place. Cela est aussi vrai si le code est exécuté via un pipe depuis `STDIN`.

Une seconde variable globale, $argc, contient le nombre d'éléments du tableau $argv (et non pas le nombre d'arguments passés au script).

Tant que les arguments passés au script ne commencent pas par le caractère `-`, il n'y a rien de spécial à surveiller. Le fait de passer des arguments au script qui commencent par `-` pose des problèmes car PHP va penser qu'il doit les interpréter. Pour éviter cela, utiliser le séparateur `--`. Après cet argument, tous les arguments suivants seront passés au script sans être modifiés ou analysés par PHP.

    # Cela ne va pas exécuter le code, mais afficher l'aide de PHP
    $ php -r 'var_dump($argv);' -h
    Usage: php [options] [-f] <file> [args...]
    [...]

    # Cela va passer l'argument '-h' au script, et éviter que PHP ne le traite
    $ php -r 'var_dump($argv);' -- -h
    array(2) {
      [0]=>
      string(1) "-"
      [1]=>
      string(2) "-h"
    }

Cependant, il y a une autre méthode pour utiliser PHP en script shell ; la première ligne du script devra être `#!/usr/bin/php` (à remplacer par le chemin vers le binaire PHP CLI sur le système sous-jacent). Le reste du fichier doit contenir le code PHP normal, compris entre les balises ouvrantes/fermantes. Après avoir mis les droits d'exécution sur le script (chmod +x test), il peut être exécuté comme un script shell ou perl habituel :

Exemple #1 Exécute un script PHP en tant que script shell

    #!/usr/bin/php
    <?php
    var_dump($argv);
    ?>

En supposant que ce fichier s'appelle test, dans le dossier courant, il est alors possible de faire ceci :

    $ chmod +x test
    $ ./test -h -- foo
    array(4) {
       [0]=>
       string(6) "./test"
       [1]=>
       string(2) "-h"
       [2]=>
       string(2) "--"
       [3]=>
       string(3) "foo"
    }

Comme on peut le voir, dans ce cas, il n'est pas nécessaire de faire attention lors du passage de paramètres qui commencent par `-` au script.

L'exécutable PHP peut être utilisé pour exécuter des scripts indépendants du serveur web. Sur un système Unix, il est recommandé d'ajouter la ligne spéciale en début de script, de le rendre exécutable de manière que le système sache quel programme doit exécuter le script. Sous Windows, il est possible d'associer l'exécutable php.exe avec le double-clic sur les fichiers d'extension `.php`, ou bien de faire un fichier batch pour exécuter le script grâce à PHP. La première ligne utilisée dans le monde Unix ne perturbera pas l'exécution sous Windows, ce qui rend les scripts facilement portables. Un exemple complet est disponible ci-dessous :

Exemple #2 Script prévu pour être exécuté en ligne de commande (script.php)

    #!/usr/bin/php
    <?php

    if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
    ?>

    C'est une ligne de commande à une option.

      Utilisation :
      <?php echo $argv[0]; ?> <option>

      <option> peut être un mot que vous souhaitez afficher.
      Avec les options --help, -help, -h,
      et -?, vous obtiendrez cette aide.

    <?php
    } else {
        echo $argv[1];
    }
    ?>

Le script ci-dessus inclut la première ligne spéciale indiquant que ce fichier doit être exécuté par PHP. Nous travaillons ici avec la version CLI, aussi, aucun en-tête HTTP ne sera affiché.

Le programme commence par vérifier que l'argument requis est spécifié (en plus du nom du script, qui est aussi compté). S'il n'est pas présent, ou si l'argument est --help, -help, -h ou -?, un message d'aide sera affiché, en utilisant $argv[0] pour afficher dynamiquement le nom du script tel qu'entré dans la ligne de commande. Sinon, l'argument est affiché tel qu'il a été entré dans le terminal.

Pour exécuter le script ci-dessus sous Unix, il faut le rendre exécutable, puis l'appeler avec une commande comme : script.php echothis ou script.php -h. Sous Windows, il est possible de faire un fichier batch pour cela :

Exemple #3 Fichier batch pour exécuter un script PHP en ligne de commande (script.bat)

    @echo OFF
    "C:\php\php.exe" script.php %*

En supposant que le programme ci-dessus est nommé script.php, et que l'exécutable CLI php.exe se trouve dans C:\php\php.exe, ce fichier batch l'exécutera avec les options qui lui sont passées : script.bat echothis ou script.bat -h.

Voir aussi l'extension Readline, qui dispose de nombreuses fonctions pour améliorer la convivialité des applications PHP en ligne de commande.

Sous Windows, PHP peut être configuré pour fonctionner sans avoir besoin de fournir les extensions C:\php\php.exe ou `.php`, tel que décrit dans la ligne de commande PHP sous Microsoft Windows.

> Note:

> Sous Windows, il est recommandé d'exécuter PHP sous un compte utilisateur. Lorsque PHP est exécuté sous un service réseau, certaines opérations peuvent échouer, car "Aucun lien entre les noms de compte et les identifiants de sécurité n'est réalisé".

## Flux d'entrée/sortie

Le CLI SAPI définit quelques constantes pour les flux I/O pour rendre la programmation en ligne de commande plus facile.

Constantes spécifiques CLI
Constante | Description
--- | ---
`STDIN` | Un flux déjà ouvert vers `stdin`. Ceci évite de l'ouvrir explicitement avec
    <?php
    $stdin = fopen('php://stdin', 'r');
    ?>
Pour lire une seule ligne depuis `stdin`, il est possible d'utiliser
    <?php
    $line = trim(fgets(STDIN)); // lit une ligne depuis STDIN
    fscanf(STDIN, "%d\n", $number); // lit des nombres depuis STDIN
    ?>
`STDOUT` | Un flux déjà ouvert vers `stdout`. Ceci évite de l'ouvrir explicitement avec
    <?php
    $stdout = fopen('php://stdout', 'w');
    ?>
`STDERR` | Un flux déjà ouvert vers `stderr`. Ceci évite de l'ouvrir explicitement avec
    <?php
    $stderr = fopen('php://stderr', 'w');
    ?>

Ainsi, il n'est pas nécessaire d'ouvrir un flux spécifique pour, par exemple, `stderr` mais il suffit d'utiliser la constante correspondante à ce flux :

    php -r 'fwrite(STDERR, "stderr\n");'

Il n'est pas nécessaire de clore explicitement ces flux, sachant qu'ils le seront automatiquement par PHP à la fin du script.

> Note:

> Ces constantes ne sont pas disponibles lors d'une lecture d'un script PHP depuis `stdin`.

## Shell Interactif

Le CLI SAPI fournit un shell interactif lors de l'utilisation de l'option -a si PHP a été compilé avec l'option --with-readline. À partir de PHP 7.1.0, le shell interactif est également disponible sur Windows, si l'extension readline est activée.

En utilisant le shell interactif, il est possible de taper du code PHP et qu'il soit exécuté directement.

Exemple #1 Exécution de code en utilisant le shell interactif

    $ php -a
    Interactive shell

    php > echo 5+8;
    13
    php > function addTwo($n)
    php > {
    php { return $n + 2;
    php { }
    php > var_dump(addtwo(2));
    int(4)
    php >

Le shell interactif fournit également une autocomplétion des fonctions, des constantes, des noms de classes, des variables, des appels aux méthodes statiques et des constantes de classes en utilisant la touche de tabulation. À partir de PHP 8.4.0, le chemin vers le fichier d'historique peut être défini en utilisant la variable d'environnement PHP_HISTFILE.

Exemple #2 Auto-complétion en utilisant la touche de tabulation

Le fait de presser deux fois la touche de tabulation lorsqu'il y a plusieurs complétions possibles affichera une liste de ces complétions :

    php > strp[TAB][TAB]
    strpbrk   strpos    strptime
    php > strp

Lorsqu'il n'y a qu'une seule complétion possible, presser la touche de tabulation une seule fois complétera le reste sur la même ligne :

    php > strpt[TAB]ime(

La complétion fonctionnera aussi pour les noms qui ont été définis lors de la session courante du shell interactif :

    php > $fooThisIsAReallyLongVariableName = 42;
    php > $foo[TAB]ThisIsAReallyLongVariableName

Le shell interactif stocke l'historique et peut y accéder en utilisant les touches haut et bas. L'historique est sauvegardé dans le fichier ~/.php_history.

Le CLI SAPI fournit 2 directives du php.ini : `cli.pager` et `cli.prompt`. La directive `cli.pager` permet la définition d'un programme externe (comme less) à utiliser comme pager pour la sortie au lieu d'afficher directement sur l'écran. La directive `cli.prompt` autorise la modification du prompte `php >`.

Il est également possible de définir des directives du php.ini dans un shell interactif en utilisant des notations raccourcies.

Exemple #3 Définition de directives du php.ini dans un shell interactif

La définition de la directive `cli.prompt` :

    php > #cli.prompt=hello world :>
    hello world :>

En utilisant des backticks, il est possible d'exécuter du code PHP dans le prompte :

    php > #cli.prompt=`echo date('H:i:s');` php >
    15:49:35 php > echo 'hi';
    hi
    15:49:43 php > sleep(2);
    15:49:45 php >

Définition du pager à less :

    php > #cli.pager=less
    php > phpinfo();
    (sortie affichée avec less)
    php >

La directive `cli.prompt` supporte quelques séquences d'échappement :

Séquences d'échappement de `cli.prompt`
Séquence : | Description :
--- | ---
`\e` | utilisé pour ajouter des couleurs au prompte. Exemple : `\e[032m\v \e[031m\b \e[34m\> \e[0m`
`\v` | La version de PHP.
`\b` | Indique dans quel bloc de PHP nous nous trouvons. Par exemple, `/*` permet d'indiquer que nous sommes dans un commentaire multilignes. Le scope externe est représenté par `php`.
`\>` | Indique le caractère utilisé pour le prompte. Par défaut, ce sera `>`, mais peut être modifié lorsque le shell se trouve dans un bloc indéterminé ou dans une chaîne de caractères. Les caractères possibles sont : `' " { ( >`

> Note:

> Les fichiers inclus via auto_prepend_file et auto_append_file sont analysés dans ce mode, mais avec quelques restrictions - c.-à-d. les fonctions doivent avoir été définies avant l'appel.

## Mode interactif

Si l'extension readline n'est pas disponible, antérieur à PHP 8.1.0, invoquer le CLI SAPI avec l'option -a fournit le mode interactif. Dans ce mode, un script PHP complet est supposé être donné via STDIN, et après l'interruption avec ``CTRL` +`D`` (POSIX) ou ``CTRL` +`Z`` suivi de +`ENTER` (Windows), ce script sera évalué. Ceci est basiquement identique à invoquer le CLI SAPI sans l'option -a.

À partir de PHP 8.1.0, invoquer le CLI SAPI avec l'option -a échoue, si l'extension readline n'est pas disponible.

## Serveur web interne

Avertissement

Ce serveur web est prévu pour aider dans le développement des applications. Il peut également être utile pour les tests, et pour les démonstrations d'applications qui sont exécutées dans des environnements contrôlés. Mais par contre, il n'a pas été conçu pour être un serveur web complet. Aussi, il ne devrait pas être utilisé dans un réseau public.

Le CLI SAPI fournit un serveur web interne.

Le serveur web s'exécute sur un seul processus single-threaded, les applications PHP seront retardées/suspendues si une requête est bloquée.

Les requêtes URI sont servies depuis le dossier de travail courant où PHP a été démarré, à moins que l'option -t ne soit utilisée pour spécifier explicitement un document racine. Si une requête URI ne spécifie pas un fichier, alors le fichier index.php ou le fichier index.html du dossier courant sera retourné. Si aucun de ces fichiers n'existe, la recherche d'un fichier index.php et index.html se poursuivra dans le dossier parent et ainsi de suite jusqu'à ce qu'un de ces fichiers ne soit trouvé ou que le dossier racine ne soit atteint. Si un fichier index.php ou index.html est trouvé, il sera retourné et $_SERVER['PATH_INFO'] sera défini comme la dernière partie de l'URI. Sinon, un code réponse 404 sera retourné.

Si un fichier PHP est fourni dans la ligne de commande lorsque le serveur web est démarré, il sera traité comme un script "routeur". Le script sera exécuté au début de chaque requête HTTP. Si ce script retourne `false`, alors la ressource demandée est retournée telle quelle. Sinon, la sortie du script est retournée au navigateur.

Les types MIME standards sont retournés pour les fichiers avec les extensions : `.3gp`, `.apk`, `.avi`, `.bmp`, `.css`, `.csv`, `.doc`, `.docx`, `.flac`, `.gif`, `.gz`, `.gzip`, `.htm`, `.html`, `.ics`, `.jpe`, `.jpeg`, `.jpg`, `.js`, `.kml`, `.kmz`, `.m4a`, `.mov`, `.mp3`, `.mp4`, `.mpeg`, `.mpg`, `.odp`, `.ods`, `.odt`, `.oga`, `.ogg`, `.ogv`, `.pdf`, `.png`, `.pps`, `.pptx`, `.qt`, `.svg`, `.swf`, `.tar`, `.text`, `.tif`, `.txt`, `.wav`, `.webm`, `.wmv`, `.xls`, `.xlsx`, `.xml`, `.xsl`, `.xsd`, `.zip` .

À partir de PHP 7.4.0, le serveur web intégré peut être configuré pour bifurquer plusieurs travailleurs afin de tester du code nécessitant plusieurs requêtes concurrentes au serveur web intégré. Définissez la variable d'environnement PHP_CLI_SERVER_WORKERS sur le nombre de travailleurs souhaité avant de démarrer le serveur.

> Note: Cette fonctionnalité n'est pas prise en charge sur Windows.

> Note: Pour des informations sur l'utilisation et les options de PHP en ligne de commande, exécuter php --help ou man php. Toutes les options ne s'appliquent pas lors de l'exécution du serveur web.

Avertissement

Cette fonctionnalité expérimentale n'est pas destinée à une utilisation en production. En général, le Serveur Web intégré n'est pas destiné à une utilisation en production.

Exemple #1 Démarrage du serveur web

    $ cd ~/public_html
    $ php -S localhost:8000

Le terminal affichera :

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit

Après des requêtes URI sur http://localhost:8000/ et http://localhost:8000/myscript.html, le terminal affichera quelque chose comme :

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit.
    [Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read

Noter qu'antérieur à PHP 7.4.0, les ressources statiques en lien symbolique ne sont pas accessibles sous Windows, tant que le script routeur ne le gère pas.

Exemple #2 Démarrage avec un dossier racine spécifique

    $ cd ~/public_html
    $ php -S localhost:8000 -t foo/

Le terminal affichera :

    PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
    Listening on localhost:8000
    Document root is /home/me/public_html/foo
    Press Ctrl-C to quit

Exemple #3 Utilisation d'un script routeur

Dans cet exemple, le fait de demander des images les affichera, mais les requêtes pour les fichiers HTML afficheront "Bienvenue chez PHP !".

    <?php
    // router.php
    if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
        return false;    // retourne la requête telle quelle.
    } else {
        echo "<p>Bienvenue chez PHP !</p>";
    }
    ?>

    $ php -S localhost:8000 router.php

Exemple #4 Vérification de l'utilisation CLI du serveur Web

Pour ré-utiliser un script router du framework lors du développement avec le CLI du serveur web et ensuite, continuer de l'utiliser avec un serveur web de production :

    <?php
    // router.php
    if (php_sapi_name() == 'cli-server') {
        /* Activation de la route statique et retourne FALSE */
    }
    /* on continue avec les opérations d'un index.php normal */
    ?>

    $ php -S localhost:8000 router.php

Exemple #5 Gestion des types de fichiers non supportés

Pour servir une ressource statique pour laquelle le type MIME n'est pas géré par le CLI du serveur web, utiliser ceci :

    <?php
    // router.php
    $path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
    if ($path["extension"] == "el") {
        header("Content-Type: text/x-script.elisp");
        readfile($_SERVER["SCRIPT_FILENAME"]);
    }
    else {
        return FALSE;
    }
    ?>

    $ php -S localhost:8000 router.php

Exemple #6 Accès au CLI du serveur web depuis une machine distante

Il est possible de rendre le serveur web accessible sur le port 8000 pour toutes les interfaces avec :

    $ php -S 0.0.0.0:8000

Avertissement

Le serveur web intégré ne devrait pas être utilisé sur un réseau public.

## Configurations INI

Options de configuration CLI SAPI
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
cli_server.color | "0" | `INI_ALL` |

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

`cli_server.color` bool

  Active le serveur web de développement interne à utiliser la coloration ANSI du code dans la sortie du terminal.

# Ramasse-miettes (Garbage Collection)

## Sommaire

- Bases sur le comptage des références
- Nettoyage de Cycles
- Considérations sur les performances

Cette section explique les mérites du nouveau mécanisme ramasse-miettes (aussi appelé GC, du terme anglais Garbage Collection) fourni à partir de PHP 5.3.

## Bases sur le comptage des références

Une variable PHP est stockée en interne dans un conteneur appelé "zval". Un conteneur zval contient, outre le type de la variable et sa valeur, deux informations supplémentaires. La première se nomme "is_ref" et est une valeur booléenne qui indique si une variable fait partie d'une référence ou non. Grâce à cette information, le moteur de PHP sait différencier les variables normales des références. Comme PHP autorise le programmeur à utiliser des références, au moyen de l'opérateur &, un conteneur zval possède aussi un mécanisme de comptage des références afin d'optimiser l'utilisation de la mémoire. Cette seconde information, appelée "refcount", contient le nombre de variables (aussi appelées symboles) qui pointent vers ce conteneur zval. Tous les symboles sont stockés dans une table de symboles, et il y a une table par espace de visibilité (scope). Il y a un espace global pour le script principal (celui appelé par exemple via le navigateur) et un espace par fonction ou méthode.

Un conteneur zval est créé lorsqu'une nouvelle variable est créée avec une valeur constante, par exemple :

Exemple #1 Création d'un nouveau conteneur zval

    <?php
    $a = "new string";
    ?>

Dans ce cas, le nouveau symbole `a` est créé dans le scope courant, et un nouveau conteneur est créé avec comme type string et comme valeur `new string`. Le bit "is_ref" est mis par défaut à `false` car aucune référence n'a été créée par le programmeur. Le compteur de références "refcount" est mis à `1` car il n'y a qu'un seul symbole qui utilise ce conteneur. Il est à noter que les références (c.-à-d. "is_ref" est `true`) avec "refcount" `1`, sont traitées comme si elles n'étaient pas des références (c.-à-d. comme si "is_ref" était `false`). Si » Xdebug est installé, il est possible d'afficher cette information en appelant xdebug_debug_zval().

Exemple #2 Affichage des informations zval

    <?php
    $a = "new string";
    xdebug_debug_zval('a');
    ?>

L'exemple ci-dessus va afficher :

    a: (refcount=1, is_ref=0)='new string'

Assigner cette variable à un autre symbole va incrémenter le refcount.

Exemple #3 Incrémentation du refcount d'une zval

    <?php
    $a = "new string";
    $b = $a;
    xdebug_debug_zval( 'a' );
    ?>

L'exemple ci-dessus va afficher :

    a: (refcount=2, is_ref=0)='new string'

Le refcount vaut `2` ici, car le même conteneur est lié à la fois à a et à b. PHP est suffisamment intelligent pour ne pas dupliquer le conteneur lorsque ce n'est pas nécessaire. Les conteneurs sont détruits lorsque leur "refcount" atteint zéro. Le "refcount" est décrémenté de un lorsque n'importe quel symbole lié à un conteneur sort du scope (ex. : lorsque la fonction se termine) ou lorsqu'un symbole est déalloué (ex. : par l'appel de unset()). L'exemple qui suit le démontre :

Exemple #4 Décrémentation du refcount d'une zval

    <?php
    $a = "new string";
    $c = $b = $a;
    xdebug_debug_zval( 'a' );
    $b = 42;
    xdebug_debug_zval( 'a' );
    unset( $c );
    xdebug_debug_zval( 'a' );
    ?>

L'exemple ci-dessus va afficher :

    a: (refcount=3, is_ref=0)='new string'
    a: (refcount=2, is_ref=0)='new string'
    a: (refcount=1, is_ref=0)='new string'

Si, maintenant, nous appelons `unset($a);`, le conteneur zval, incluant le type et la valeur, va être supprimé de la mémoire.

### Types composés

Les choses se compliquent dans le cas de types composés comme array et object. À la différence des valeurs scalar, les array et object stockent leurs propriétés dans une table de symboles qui leur est propre. Ceci signifie que l'exemple qui suit crée trois conteneurs zval :

Exemple #5 Création d'une zval array

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    xdebug_debug_zval( 'a' );
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=1, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42
    )

Ou graphiquement

Les trois conteneurs zval sont : a, meaning, et number. Les mêmes règles s'appliquent pour l'incrémentation et la décrémentation des "refcounts". Ci-après, nous ajoutons un autre élément au tableau, et nous renseignons sa valeur avec le contenu d'un élément déjà existant du tableau :

Exemple #6 Ajout d'un élément déjà existant au tableau

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    xdebug_debug_zval( 'a' );
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=2, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42,
       'life' => (refcount=2, is_ref=0)='life'
    )

Ou graphiquement

La sortie Xdebug que nous voyons indique que l'ancien et le nouvel élément du tableau pointent maintenant tous deux vers un conteneur zval dont le "refcount" vaut `2`. Même si la sortie XDebug montre deux conteneurs zval avec comme valeur 'life', ils sont les mêmes. La fonction xdebug_debug_zval() ne montre pas cela, mais cela pourrait être constaté en affichant aussi le pointeur de mémoire.

Supprimer un élément du tableau est assimilable à la suppression d'un symbole depuis un espace. Ce faisant, le "refcount" du conteneur vers lequel l'élément du tableau pointe est décrémenté. Une fois encore, s'il atteint zéro, le conteneur zval est supprimé de la mémoire. Voici un exemple qui le démontre :

Exemple #7 Suppression d'un élément de tableau

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    unset( $a['meaning'], $a['number'] );
    xdebug_debug_zval( 'a' );
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    a: (refcount=1, is_ref=0)=array (
       'life' => (refcount=1, is_ref=0)='life'
    )

Maintenant, les choses deviennent intéressantes si nous ajoutons le tableau comme élément de lui-même. Nous faisons cela dans l'exemple qui suit, en utilisant un opérateur de référence pour éviter que PHP ne crée une copie :

Exemple #8 Ajout du tableau comme référence à lui-même en tant qu'élément

    <?php
    $a = array( 'one' );
    $a[] =& $a;
    xdebug_debug_zval( 'a' );
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    a: (refcount=2, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=2, is_ref=1)=...
    )

Ou graphiquement

On peut voir que la variable tableau (a) tout comme le second élément (1) pointent désormais vers un conteneur dont le "refcount" vaut `2`. Les "..." sur l'affichage indiquent une récursion, qui, dans ce cas, signifie que le "..." pointe sur le tableau lui-même.

Comme précédemment, supprimer une variable supprime son symbole, et le refcount du conteneur sur lequel il pointait est décrémenté. Donc, si nous supprimons la variable $a après avoir exécuté le code ci-dessus, le compteur de références du conteneur sur lequel pointent $a et l'élément "1" sera décrémenté de un, passant de "2" à "1". Ceci peut être représenté par :

Exemple #9 Suppression de $a

    (refcount=1, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=1, is_ref=1)=...
    )

Ou graphiquement

### Problèmes de nettoyage

Bien qu'il n'y ait plus aucun symbole dans l'espace de variables courant qui pointe vers cette structure, elle ne peut être nettoyée, car l'élément "1" du tableau pointe toujours vers ce même tableau. Comme il n'y a plus aucun symbole externe pointant vers cette structure, l'utilisateur ne peut pas la nettoyer manuellement ; il y a donc une fuite de mémoire. Heureusement, PHP va détruire cette structure à la fin de la requête, mais avant cette étape, la mémoire n'est pas libérée. Cette situation se produit souvent lors de l'implémentation d'un algorithme d'analyse ou d'autres idées où l'on a un enfant qui pointe vers son parent. La même chose peut bien entendu se produire avec les objets, et c'est même plus probable, puisqu'ils sont toujours implicitement utilisés par "référence".

Ceci peut ne pas être gênant si cela n'arrive qu'une ou deux fois, mais s'il y a des milliers, ou même des millions, de ces fuites mémoires, alors cela risque évidemment de devenir un problème important. C'est particulièrement problématique pour les scripts qui durent longtemps, comme les démons pour lesquels la requête ne termine pour ainsi dire jamais, ou encore dans de grosses suites de tests unitaires. Ce dernier cas a été rencontré en lançant les tests unitaires du composant Template de la bibliothèque eZ Components. Dans certains cas, la suite de tests nécessitait plus de 2Go de mémoire, que le serveur de test n'avait pas vraiment à disposition.

## Nettoyage de Cycles

Traditionnellement, les mécanismes de comptage de références, comme utilisés auparavant dans PHP, ne savent pas gérer les fuites mémoires dues à des références circulaires ; cependant à partir de PHP 5.3.0, un algorithme synchrone issu de l'analyse » Concurrent Cycle Collection in Reference Counted Systems est utilisé pour répondre à ce problème particulier.

Une explication complète du fonctionnement de l'algorithme irait un peu au-delà du cadre de cette section, mais nous allons ici présenter les principes de base. Avant tout, nous allons établir quelques règles de base. Si un refcount est incrémenté, le conteneur est toujours utilisé, donc pas nettoyé. Si le refcount est décrémenté et atteint zéro, le conteneur zval peut être supprimé et la mémoire libérée. Premièrement, ceci signifie que les cycles perturbateurs ne peuvent être créés que lorsque le refcount est décrémenté vers une valeur différente de zéro. Ensuite, dans un cycle problématique, il est possible de détecter les déchets en vérifiant s'il est possible ou non de décrémenter leur refcount de un, en vérifiant ensuite quelles zvals ont un refcount à zéro.

Pour éviter d'avoir à appeler la routine de nettoyage à chaque décrémentation de refcount possible, l'algorithme place toutes les zval racines dans un "tampon de racines" (en les marquant en "violet"). Il s'assure aussi que chaque racine n'apparaisse qu'une seule fois dans le tampon. Le mécanisme de nettoyage n'intervient alors que lorsque le tampon est plein. Voir l'étape A sur la figure ci-dessus.

À l'étape B, l'algorithme lance une recherche sur toutes les racines possibles, afin de décrémenter de une unité les refcounts de toutes les zvals qu'il trouve, en faisant bien attention de ne pas décrémenter deux fois le refcount de la même zval (en les marquant comme "grises"). À l'étape C, l'algorithme relance une recherche sur toutes les racines possibles et scrute la valeur de refcount de chaque zval. S'il trouve un refcount à zéro, la zval est marquée comme "blanche" (bleu sur la figure). S'il trouve une valeur supérieure à zéro, il annule la décrémentation du refcount en refaisant une recherche à partir de ce nœud, et les marque comme "noires" à nouveau. Dans la dernière étape, D, l'algorithme parcourt tout le tampon des racines et les supprime, tout en scrutant chaque zval ; toute zval marquée comme "blanche" à l'étape précédente sera alors supprimée de la mémoire.

Maintenant que le fonctionnement global de l'algorithme est connu, nous allons voir comment il a été intégré dans PHP. Par défaut, le ramasse-miettes de PHP est activé. Il existe cependant une option de php.ini pour changer cela : zend.enable_gc.

Lorsque le ramasse-miettes est activé, l'algorithme de recherche des cycles décrit ci-dessus est exécuté à chaque fois que le tampon est plein. Le tampon de racines a une taille fixée à 10.000 racines (ce paramètre est changeable grâce à `GC_THRESHOLD_DEFAULT` dans `Zend/zend_gc.c` dans le code source de PHP, une recompilation est donc nécessaire). Si le ramasse- miettes est désactivé, la recherche des cycles l'est aussi. Cependant, les racines possibles seront toujours enregistrées dans le tampon, ceci ne dépend pas de l'activation du ramasse-miettes.

Si le tampon est plein alors que le mécanisme de nettoyage est désactivé, les racines ne seront plus enregistrées. Ces racines ne seront donc jamais analysées par l'algorithme, et si elles faisaient partie de références circulaires, elles ne seront jamais nettoyées, et elles causeront des fuites de mémoire.

La raison pour laquelle les racines possibles sont enregistrées dans le tampon même si le mécanisme est désactivé est qu'il aurait été trop coûteux de vérifier l'activation éventuelle du mécanisme à chaque tentative d'ajout d'une racine dans le tampon. Le mécanisme de ramasse-miettes et d'analyse peut, lui, être très coûteux en temps.

En plus de pouvoir changer la valeur du paramètre de configuration zend.enable_gc, il est aussi possible d'activer ou désactiver le mécanisme de ramasse-miettes en appelant les fonctions gc_enable() ou gc_disable() respectivement. Utiliser ces fonctions aura le même effet que de modifier le paramètre de configuration. Il est aussi possible de forcer l'exécution du ramasse-miettes à un moment donné dans le script, même si le tampon n'est pas encore complètement plein. Utiliser pour cela la fonction gc_collect_cycles(), qui retournera le nombre de cycles alors collectés.

Il est possible de prendre le contrôle en désactivant le ramasse-miettes ou en le forçant à passer à un moment donné car certaines parties de l'application pourraient être fortement dépendantes du temps de traitement, auquel cas il peut être souhaitable que le ramasse-miettes ne se lance pas. Bien entendu, en désactivant le ramasse-miettes pour certaines parties de l'application, on prend le risque de créer des fuites de mémoire, puisque certaines racines probables pourraient ne pas être enregistrées dans le tampon mémoire de taille limitée. En conséquence, il est généralement recommandé de déclencher manuellement le processus grâce à gc_collect_cycles() juste avant l'appel à gc_disable(), pour libérer de la mémoire. Ceci laissera un tampon vidé, et il y aura plus d'espace pour des racines probables lorsque le mécanisme sera désactivé.

## Considérations sur les performances

Nous avons déjà vu dans les sections précédentes que la collecte des racines probables avait un impact très léger sur les performances, mais c'est lorsque l'on compare PHP 5.2 à PHP 5.3. Même si l'enregistrement des racines probables est plus lent que de ne pas les enregistrer du tout, comme dans PHP 5.2, d'autres améliorations apportées par PHP 5.3 font que cette opération ne se ressent pas au niveau des performances.

Il y a principalement deux niveaux pour lesquels les performances sont affectées. Le premier est l'empreinte mémoire réduite, et le second est le délai à l'exécution, lorsque le mécanisme de nettoyage effectue son opération de libération de mémoire. Nous allons étudier ces deux axes.

### Empreinte mémoire réduite

Avant tout, la raison principale de l'implémentation du mécanisme de collecte des déchets est la réduction de la mémoire consommée, en nettoyant les références circulaires lorsque les conditions requises sont remplies. Avec PHP, ceci arrive dès que le tampon de racines est plein, ou lorsque la fonction gc_collect_cycles() est appelée. Sur le graphe ci-après, nous affichons l'utilisation mémoire du script suivant, avec PHP 5.2 et avec PHP 5.3, en excluant la mémoire obligatoire que PHP consomme pour lui-même au démarrage.

Exemple #1 Exemple d'utilisation mémoire

    <?php
    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    $baseMemory = memory_get_usage();

    for ( $i = 0; $i <= 100000; $i++ )
    {
        $a = new Foo;
        $a->self = $a;
        if ( $i % 500 === 0 )
        {
            echo sprintf( '%8d: ', $i ), memory_get_usage() - $baseMemory, "\n";
        }
    }
    ?>

Dans cet exemple quelque peu académique, nous créons un objet possédant un attribut le référençant lui-même. Lorsque la variable $a dans le script est réassignée à l'itération suivante, une fuite mémoire apparaitra. Dans ce cas, les deux conteneurs zval fuient (la zval de l'objet et celle de l'attribut), mais une seule racine possible est trouvée : la variable qui a été supprimée. Lorsque le tampon de racines est plein après 10.000 itérations (avec un total de 10.000 racines possibles), le mécanisme de collecte des déchets entre en jeu et libère la mémoire associée à ces racines probables. Cela se voit très clairement sur les graphes d'utilisation mémoire de PHP 5.3. Après chaque 10.000 itérations, le mécanisme se déclenche et libère la mémoire associée aux variables circulairement référencées. Le mécanisme en question n'a pas énormément de travail dans cet exemple, parce que la structure qui a fui est extrêmement simple. Le diagramme montre que l'utilisation maximale de mémoire de PHP 5.3 est d'environ 9Mo, là où elle n'arrête pas d'augmenter avec PHP 5.2.

### Ralentissements durant l'exécution

Le second point où le mécanisme de collecte des déchets (GC) affecte les performances est lorsqu'il est exécuté pour libérer la mémoire "gaspillée". Pour quantifier cet impact, nous modifions légèrement le script précédent afin d'avoir un nombre d'itérations plus élevé et de supprimer la collecte de l'usage mémoire intermédiaire. Le second script est reproduit ci-dessous :

Exemple #2 Impact de GC sur les performances

    <?php
    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    for ( $i = 0; $i <= 1000000; $i++ )
    {
        $a = new Foo;
        $a->self = $a;
    }

    echo memory_get_peak_usage(), "\n";
    ?>

Nous allons lancer ce script 2 fois, une fois avec zend.enable_gc à on, et une fois à off:

Exemple #3 Lancement du script ci-dessus

    time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php
    # and
    time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php

Sur ma machine, la première commande semble durer tout le temps 10,7 secondes, alors que la seconde commande prend environ 11,4 secondes. Cela correspond à un ralentissement de 7% approximativement. Cependant, la quantité totale de mémoire utilisée par le script est réduite de 98%, passant de 931Mo à 10Mo. Ce benchmark n'est pas très scientifique ou même représentatif d'applications réelles, mais il démontre concrètement en quoi le mécanisme de collecte des déchets peut être utile au niveau de la consommation mémoire. Le bon point est que le ralentissement est toujours de 7%, dans le cas particulier de ce script, alors que la mémoire préservée sera de plus en plus importante au fur et à mesure que des références circulaires apparaitront durant l'exécution.

### Statistiques internes du GC de PHP

Il est possible d'obtenir quelques informations supplémentaires concernant le mécanisme de collecte des déchets interne à PHP. Mais pour cela, il faut recompiler PHP avec le support du benchmarking et de la collecte de données. Il est nécessaire de renseigner la variable d'environnement `CFLAGS` avec `-DGC_BENCH=1` avant de lancer `./configure` avec les options souhaitées. L'exemple suivant démontre cela :

Exemple #4 Recompiler PHP pour activer le support du benchmark du GC

    export CFLAGS=-DGC_BENCH=1
    ./config.nice
    make clean
    make

Lorsque le code du script ci-dessus est ré-exécuté avec le binaire PHP fraichement reconstruit, le résultat suivant devrait apparaître après l'exécution :

Exemple #5 Statistiques GC

    GC Statistics
    -------------
    Runs:               110
    Collected:          2072204
    Root buffer length: 0
    Root buffer peak:   10000

          Possible            Remove from  Marked
            Root    Buffered     buffer     grey
          --------  --------  -----------  ------
    ZVAL   7175487   1491291    1241690   3611871
    ZOBJ  28506264   1527980     677581   1025731

Les statistiques les plus intéressantes sont affichées dans le premier bloc. On voit ici que le mécanisme de collecte des déchets a été déclenché 110 fois, et qu'au total ce sont plus de 2 millions d'allocations mémoire qui ont été libérées durant ces 110 passages. Dès lors que le mécanisme est intervenu au moins une fois, le pic du buffer racine est toujours de 10000.

### Conclusion

De manière générale, la collecte des déchets de PHP ne causera un ralentissement que lorsque l'algorithme de collecte de cycles tournera, ce qui signifie que dans les scripts normaux (plus courts), il ne devrait pas du tout y avoir d'impact sur les performances.

Cependant, lorsque le mécanisme de collecte de cycles sera déclenché dans des scripts normaux, la réduction de l'empreinte mémoire permettra l'exécution parallèle d'un nombre plus important de ces scripts, puisque moins de mémoire sera utilisée au total.

Les avantages se sentent plus nettement dans le cas de scripts démons ou devant tourner longtemps. Ainsi, pour les applications » PHP-GTK qui tournent souvent plus longtemps que des scripts pour le Web, le nouveau mécanisme devrait réduire significativement les fuites mémoire sur le long terme.

# DTrace Traçage dynamique

## Sommaire

- Introduction à PHP et DTrace
- Utiliser PHP et DTrace
- Utiliser SystemTap avec les sondes statiques DTrace de PHP
- Utilisation de bpftrace avec les sondes statiques DTrace de PHP

## Introduction à PHP et DTrace

DTrace est un framework de traçage toujours disponible, à faible surcoût, disponible sur plusieurs plateformes, incluant Solaris, macOS, Oracle Linux et BSD. DTrace peut tracer le comportement du système d'exploitation et l'exécution des programmes utilisateurs. Il peut afficher les valeurs des arguments et être utilisé pour déduire des statistiques de performance. Les sondes sont contrôlées par des scripts créés par l'utilisateur et écrits dans le langage de script DTrace D. Cela permet une analyse efficace des points de données.

Les sondes PHP qui ne sont pas activement surveillées par le script DTrace D de l'utilisateur ne contiennent pas de code instrumenté, il n'y a donc pas de dégradation des performances lors de l'exécution normale de l'application. Les sondes qui sont surveillées ont un coût de fonctionnement assez faible pour généralement permettre la surveillance de DTrace sur les systèmes de production.

PHP incorpore des sondes de "Traçage Statique Défini par l'Utilisateur" (USDT) qui sont déclenchées au moment de l'exécution. Par exemple, lorsqu'un script D surveille la sonde `function-entry` de PHP, alors, chaque fois qu'une fonction du script PHP est appelée, cette sonde est déclenchée et le code d'action du script D associé est exécuté. Ce code d'action pourrait, par exemple, imprimer les arguments de la sonde tels que l'emplacement du fichier source de la fonction PHP. L'action peut également regrouper des données comme le nombre de fois où chaque fonction est appelée.

Seules les sondes PHP USDT sont décrites ici. Se référer à la documentation externe générale et spécifique au système d'exploitation pour voir comment DTrace peut être utilisé pour tracer des fonctions arbitraires, et comment il peut être utilisé pour tracer le comportement du système d'exploitation. Il est à noter que toutes les fonctionnalités de DTrace ne sont pas disponibles dans toutes les implémentations de DTrace.

Les sondes DTrace statiques dans PHP peuvent alternativement être utilisées avec la fonction SystemTap sur certaines distributions Linux.

## Utiliser PHP et DTrace

PHP peut être configuré avec les sondes statiques DTrace sur les plateformes qui supportent le traçage dynamique DTrace.

### Configurer PHP pour les sondes statiques de DTrace

Se référer à la documentation spécifique de la plateforme externe pour activer le support DTrace du système d'exploitation. Par exemple, sur Oracle Linux démarrez un noyau UEK3 et faites :

    # modprobe fasttrap
    # chmod 666 /dev/dtrace/helper

Au lieu d'utiliser `chmod`, il est possible d'utiliser une règle de paquetage ACL pour limiter l'accès au périphérique à un utilisateur spécifique.

Construire PHP avec le paramètre de configuration `--enable-dtrace`:

    # ./configure --enable-dtrace ...
    # make
    # make install

Cela rend les sondes statiques disponibles dans le cœur de PHP. Toutes les extensions PHP qui fournissent leurs propres sondes doivent être construites séparément en tant qu'extensions partagées.

Pour activer les sondes, définissez la variable d'environnement USE_ZEND_DTRACE=1 pour les processus PHP ciblés.

### Sondes statiques DTrace dans le cœur de PHP

Les sondes statiques suivantes sont disponibles dans PHP
Nom de la sonde | Description de la sonde | Arguments de la sonde
--- | --- | ---
`request-startup` | Se déclenche lorsqu'une requête démarre. | char *file, char *request_uri, char *request_method
`request-shutdown` | Se déclenche lorsqu'une requête s'arrête. | char *file, char *request_uri, char *request_method
`compile-file-entry` | Se déclenche lorsque la compilation d'un script commence. | char *compile_file, char *compile_file_translated
`compile-file-return` | Se déclenche lorsque la compilation d'un script se termine. | char *compile_file, char *compile_file_translated
`execute-entry` | Se déclenche lorsqu'un tableau d'opcodes doit être exécuté. Par exemple, il se déclenche lors d'appels de fonction, d'inclusions et de reprises de générateur. | char *request_file, int lineno
`execute-return` | Se déclenche après l'exécution d'un tableau d'opcodes. | char *request_file, int lineno
`function-entry` | Se déclenche lorsque le moteur de PHP entre dans une fonction PHP ou un appel de méthode. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`function-return` | Se déclenche lorsque le moteur PHP revient d'une fonction PHP ou d'un appel de méthode. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`exception-thrown` | Se déclenche lorsqu'une exception est émise. | char *classname
`exception-caught` | Se déclenche lorsqu'une exception est attrapée. | char *classname
`error` | Se déclenche lorsqu'une erreur survient, quel que soit le niveau de error_reporting. | char *errormsg, char *request_file, int lineno

Les extensions PHP peuvent également disposer de sondes statiques supplémentaires.

### Liste des sondes statiques DTrace de PHP

Pour lister les sondes disponibles, démarrez un processus PHP puis exécutez :

    # dtrace -l

Le résultat sera similaire à celui qui suit :

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
        4   php15271               php               dtrace_compile_file compile-file-entry
        5   php15271               php               dtrace_compile_file compile-file-return
        6   php15271               php                        zend_error error
        7   php15271               php  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
        8   php15271               php     zend_throw_exception_internal exception-thrown
        9   php15271               php                 dtrace_execute_ex execute-entry
       10   php15271               php           dtrace_execute_internal execute-entry
       11   php15271               php                 dtrace_execute_ex execute-return
       12   php15271               php           dtrace_execute_internal execute-return
       13   php15271               php                 dtrace_execute_ex function-entry
       14   php15271               php                 dtrace_execute_ex function-return
       15   php15271               php              php_request_shutdown request-shutdown
       16   php15271               php               php_request_startup request-startup

Les valeurs de la colonne Provider sont `php` et l'identifiant du processus PHP en cours d'exécution.

Si le serveur web Apache est en cours d'exécution, le nom du module peut être, par exemple, libphp5.so, et il y aurait plusieurs blocs de listes, un par processus Apache en cours d'exécution.

La colonne Fonction fait référence à l'implémentation interne en C de PHP, où chaque fournisseur est situé.

Si un processus PHP n'est pas en cours d'exécution, aucune sonde PHP ne sera affichée.

### DTrace avec un exemple PHP

Cet exemple montre les bases du langage de script DTrace D.

Exemple #1 all_probes.d pour tracer toutes les sondes statiques PHP avec DTrace

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::compile-file-entry
    {
        printf("PHP compile-file-entry\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::compile-file-return
    {
        printf("PHP compile-file-return\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::error
    {
        printf("PHP error\n");
        printf("  errormsg                  %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
    }

    php*:::exception-caught
    {
        printf("PHP exception-caught\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::exception-thrown
    {
        printf("PHP exception-thrown\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::execute-entry
    {
        printf("PHP execute-entry\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::execute-return
    {
        printf("PHP execute-return\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::function-entry
    {
        printf("PHP function-entry\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::function-return
    {
        printf("PHP function-return\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::request-shutdown
    {
        printf("PHP request-shutdown\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

    php*:::request-startup
    {
        printf("PHP request-startup\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

Ce script utilise l'option `-Z` de dtrace, ce qui lui permet d'être exécuté lorsqu'il n'y a aucun processus PHP en cours d'exécution. Si cette option était omise, le script se terminerait immédiatement parce qu'il sait qu'aucune des sondes à surveiller n'existe.

Le script trace tous les points de sonde statiques de PHP pendant la durée d'un script PHP en cours d'exécution. Exécutez le script D :

    # ./all_probes.d

Exécutez un script ou une application PHP. Le script D de surveillance affichera les arguments de chaque sonde au fur et à mesure qu'elle se déclenche.

Lorsque la surveillance est terminée, le script D peut être interrompu par une commande ``CTRL`+`C``

Sur les machines multi-CPU, l'ordre des sondes peut ne pas être séquentiel. Cela dépend du CPU qui a traité les sondes, et de la façon dont les threads migrent d'un CPU à l'autre. L'affichage des horodatages des sondes permet de réduire la confusion, par exemple :

    php*:::function-entry
    {
          printf("%lld: PHP function-entry ", walltimestamp);
          [ . . .]
    }

### Voir aussi

- OCI8 et le traçage dynamique DTrace

## Utiliser SystemTap avec les sondes statiques DTrace de PHP

Sur certaines distributions Linux, l'utilitaire de traçage SystemTap peut être utilisé pour tracer les sondes statiques DTrace de PHP. Ceci est disponible avec PHP 5.4.20 et PHP 5.5.

### Installer PHP avec SystemTap

Installez le paquet de développement SDT de SystemTap :

    # yum install systemtap-sdt-devel

Installer PHP avec les sondes DTrace activées :

    # ./configure --enable-dtrace ...
    # make

### Liste des sondes statiques avec SystemTap

Les sondes statiques dans PHP peuvent être listées en utilisant stap:

    # stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'

Cela produit :

    process("sapi/cli/php").provider("php").mark("compile__file__entry")
    process("sapi/cli/php").provider("php").mark("compile__file__return")
    process("sapi/cli/php").provider("php").mark("error")
    process("sapi/cli/php").provider("php").mark("exception__caught")
    process("sapi/cli/php").provider("php").mark("exception__thrown")
    process("sapi/cli/php").provider("php").mark("execute__entry")
    process("sapi/cli/php").provider("php").mark("execute__return")
    process("sapi/cli/php").provider("php").mark("function__entry")
    process("sapi/cli/php").provider("php").mark("function__return")
    process("sapi/cli/php").provider("php").mark("request__shutdown")
    process("sapi/cli/php").provider("php").mark("request__startup")

### SystemTap avec un exemple PHP

Exemple #1 all_probes.stp pour tracer toutes les sondes statiques PHP avec SystemTap

    probe process("sapi/cli/php").provider("php").mark("compile__file__entry") {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("compile__file__return") {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("error") {
        printf("Probe error\n");
        printf("  errormsg %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
    }
    probe process("sapi/cli/php").provider("php").mark("exception__caught") {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("exception__thrown") {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("execute__entry") {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("execute__return") {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("function__entry") {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("function__return") {
        printf("Probe function__return: %s\n", user_string($arg1));
        printf(" function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("request__shutdown") {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }
    probe process("sapi/cli/php").provider("php").mark("request__startup") {
        printf("Probe request__startup\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }

Le script ci-dessus va tracer tous les points de sonde statique de PHP pendant toute la durée de l'exécution d'un script PHP :

    # stap -c 'sapi/cli/php test.php' all_probes.stp

## Utilisation de bpftrace avec les sondes statiques DTrace de PHP

Sur les distributions Linux dont le noyau supporte eBPF, l'utilitaire bpftrace peut s'attacher directement aux sondes USDT DTrace de PHP, sans nécessiter SystemTap.

### Installation de bpftrace

Il faut installer bpftrace avec le gestionnaire de paquets de la distribution. Par exemple, sur Oracle Linux, RHEL ou Fedora :

    # dnf install bpftrace

Ou, sur Debian ou Ubuntu :

    # apt install bpftrace

Les exemples ci-dessous supposent que le binaire PHP cible est installé dans /usr/bin/php.

Les mêmes sondes USDT sont également exposées par les autres SAPI compilées à partir du même arbre de sources, donc la cible de la sonde peut aussi être le module Apache (libphp.so) ou le binaire du gestionnaire de processus FastCGI (php-fpm) ; il faut substituer le chemin approprié ou s'attacher par PID avec `-p` si nécessaire.

Il faut s'assurer que le binaire cible est compilé avec DTrace et que la variable d'environnement est correctement configurée. Voir Configurer PHP pour les sondes statiques DTrace pour les détails.

Les sondes statiques de PHP peuvent être listées en utilisant bpftrace :

    # bpftrace -l 'usdt:/usr/bin/php:php:*'

Ce qui affiche :

    usdt:/usr/bin/php:php:compile__file__entry
    usdt:/usr/bin/php:php:compile__file__return
    usdt:/usr/bin/php:php:error
    usdt:/usr/bin/php:php:exception__caught
    usdt:/usr/bin/php:php:exception__thrown
    usdt:/usr/bin/php:php:execute__entry
    usdt:/usr/bin/php:php:execute__return
    usdt:/usr/bin/php:php:function__entry
    usdt:/usr/bin/php:php:function__return
    usdt:/usr/bin/php:php:request__shutdown
    usdt:/usr/bin/php:php:request__startup

Exemple #1 all_probes.bt pour tracer toutes les sondes statiques de PHP avec bpftrace

    #!/usr/bin/env bpftrace

    usdt:/usr/bin/php:php:compile__file__entry
    {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:compile__file__return
    {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:error
    {
        printf("Probe error\n");
        printf("  errormsg %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
    }
    usdt:/usr/bin/php:php:exception__caught
    {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:exception__thrown
    {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:execute__entry
    {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:execute__return
    {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:function__entry
    {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:function__return
    {
        printf("Probe function__return\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:request__shutdown
    {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }
    usdt:/usr/bin/php:php:request__startup
    {
        printf("Probe request__startup\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }

Le script ci-dessus tracera tous les points de sonde statiques du cœur de PHP pendant toute la durée d'exécution d'un script PHP. bpftrace nécessite les privilèges root :

    # USE_ZEND_DTRACE=1 bpftrace -c '/usr/bin/php test.php' all_probes.bt

Pour tracer un processus PHP déjà en cours d'exécution (par exemple, un worker php-fpm ou un processus Apache chargeant libphp.so), il faut s'attacher par PID :

    # bpftrace -p $PID all_probes.bt

Le chemin cible `usdt:` dans le script doit correspondre au binaire du processus en cours ; il faut ajuster `usdt:/usr/bin/php` au binaire php-fpm ou à libphp.so selon le cas.

- Identification HTTP avec PHP
- Cookies
- Sessions
- Gestion des chargements de fichiers
  - Chargements de fichiers par méthode POST
  - Explication sur les messages d'erreurs de chargement de fichiers
  - Erreurs classiques
  - Télécharger plusieurs fichiers simultanément
  - Chargement par méthode PUT
  - Voir aussi
- Utilisation des fichiers à distance
- Gestion des connexions
- Connexions persistantes aux bases de données
- Utilisation des lignes de commande — Utiliser PHP en ligne de commande
  - Différences avec les autres SAPIs
  - Options — Options de ligne de commande
  - Utilisation — Exécution de fichiers PHP
  - Flux I/O — Flux d'entrée/sortie
  - Shell Interactif
  - Serveur web interne
  - Configurations INI
- Ramasse-miettes (Garbage Collection)
  - Bases sur le comptage des références
  - Nettoyage de Cycles
  - Considérations sur les performances
- DTrace Traçage dynamique
  - Introduction à PHP et DTrace
  - Utiliser PHP et DTrace
  - Utiliser SystemTap avec les sondes statiques DTrace de PHP
  - Utilisation de bpftrace avec les sondes statiques DTrace de PHP

# Référence des fonctions

Astuce

Voir aussi Catégorie/Liste des extensions.

# Affecte le comportement de PHP

# APC User Cache

# Introduction

APCu est un tableau associatif stocké en mémoire pour PHP. Les clés sont de type chaîne de caractères et les valeurs sont des variables PHP de tout type. APCu ne gère que la mise en cache de variables de l'espace utilisateur.

Le cache APCu est par processus sous Windows, donc lors de l'utilisation d'un SAPI basé sur les processus (plutôt que sur les threads), il ne sera pas partagé entre différents processus.

APCu, c'est APC sans la mise en cache du code opération.

La première version est 4.0.0, ce fut un embranchement logiciel de la tête de la branche maître d'APC de l'époque. La prise en charge de PHP 7 est disponible à partir d'APCu 5.0.0. La prise en charge de PHP 8 est disponible à partir d'APCu 5.1.19.

# Installation/Configuration

## Sommaire

- Installation
- Configuration à l'exécution

## Installation

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/apcu.

Astuce

PHP 7 a un module séparé (» apcu-bc) pour des raisons de rétrocompatibilité avec APC.

En mode rétrocompatibilité, APCu enregistre les fonctions APC applicables avec des prototypes rétrocompatibles.

Lorsqu'une fonction APC accepte le paramètre `cache_type`, ce dernier est ignoré par la version rétrocompatible de la fonction et omis du prototype de la version APCu.

Avertissement

À partir de PHP 8.0.0, apcu-bc n'est plus accepté.

> Note: Avec Windows, APCu a besoin d'un chemin temporaire dans lequel le serveur web est autorisé à écrire. Il vérifie successivement les variables d'environnement TMP, TEMP et USERPROFILE dans cet ordre et termine en essayant le répertoire WINDOWS si aucune de ces variables n'a été définie.

> Note: Pour plus de détails techniques approfondis sur l'implémentation, consulter le » fichier TECHNOTES fourni par les développeurs .

Les sources d'APCu sont disponibles » ici.

## Configuration à l'exécution

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

Bien que les réglages par défaut d'APCu fonctionnent correctement sur de nombreuses installations, il est utile de penser à ajuster ces paramètres de configuration.

Une question importante pour la configuration d'APCu est quelle est la taille adéquate qui doit être allouée dans la mémoire à APCu. La directive ini qui contrôle ce paramètre est `apc.shm_size`. Le paragraphe ci-dessous est important pour répondre à cette question.

Une fois le serveur lancé, le script `apc.php`, disponible avec l'extension, peut être copié dans le répertoire racine du serveur web et exécuté par le navigateur. Ce script fournit une analyse détaillée du fonctionnement interne d'APCu. Si la bibliothèque GD est activée dans PHP alors le script peut afficher des graphiques pertinents.

Si APCu fonctionne, le nombre de `Cache full count` (à gauche) affichera le nombre de fois où le cache a atteint sa capacité maximale et a dû évacuer des entrées pour libérer de la mémoire. Pendant l'évacuation, si `apc.ttl` a été spécifié, APCu essaiera d'abord de supprimer les entrées expirées, c'est-à-dire les entrées dont le TTL a expiré ou les entrées qui n'ont pas de TTL défini et qui n'ont pas été consultées au cours des dernières `apc.ttl` secondes. Si `apc.ttl` n'a pas été défini ou si la suppression des entrées expirées n'a pas libéré suffisamment d'espace, APCu effacera l'intégralité du cache.

Le nombre d'évictions devrait être minimal dans un cache bien configuré. Si le cache est constamment rempli et donc libéré de force, le brassage résultant aura des effets préjudiciables sur les performances du script. Le moyen le plus simple de réduire ce nombre est d'allouer plus de mémoire à APCu.

Lorsque APCu est compilé avec mmap (Memory Mapping), il n'utilisera qu'un seul segment de mémoire, contrairement au cas où APCu est construit avec SHM (SysV Shared Memory) qui utilise plusieurs segments de mémoire. MMAP n'a pas de limite maximale comme SHM dans `/proc/sys/kernel/shmmax`. En général, l'utilisation de MMAP est recommandée car il réclame la mémoire plus vite lorsque le serveur web est redémarré et réduit l'impact sur l'allocation de mémoire au démarrage.

Options de configuration d'APCu
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
apc.enabled | 1 | `INI_SYSTEM` |
apc.shm_segments | 1 | `INI_SYSTEM` |
apc.shm_size | "32M" | `INI_SYSTEM` |
apc.entries_hint | 512 * apc.shm_size | `INI_SYSTEM` | Antérieurement à APCu 5.1.25, la valeur par défaut était 4096
apc.ttl | 0 | `INI_SYSTEM` |
apc.gc_ttl | 3600 | `INI_SYSTEM` |
apc.mmap_file_mask | NULL | `INI_SYSTEM` |
apc.slam_defense | 0 | `INI_SYSTEM` |
apc.enable_cli | 0 | `INI_SYSTEM` |
apc.use_request_time | 0 | `INI_ALL` | Antérieurement à APCu 5.1.19, la valeur par défaut était `1`.
apc.serializer | "php" | `INI_SYSTEM` | Antérieurement à APCu 5.1.15, la valeur par défaut était `"default"`.
apc.coredump_unmap | 0 | `INI_SYSTEM` |
apc.preload_path | NULL | `INI_SYSTEM` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`apc.enabled` bool
  `apc.enabled` peut être mis à 0 pour désactiver APC. Cela peut s'avérer utile lorsqu'APC est compilé statiquement dans PHP puisqu'il n'y a pas d'autre moyen de le désactiver (lorsque APC est compilé en tant que DSO, la ligne `extension` dans le fichier `php.ini` peut simplement être mise en commentaire).
`apc.shm_segments` int
  Le nombre de segments de mémoire partagée à allouer au cache de compilation. Si APC manque de mémoire partagée mais que `apc.shm_size` est mis à la valeur maximale autorisée par le système, alors augmenter cette valeur peut empêcher APC d'épuiser sa mémoire.
`apc.shm_size` string
  La taille de chaque segment de mémoire partagée donnée en notation abrégée comme indiqué dans cette FAQ. Par défaut, certains systèmes (dont la plupart des variantes de BSD) ont une limite très basse pour la taille d'un segment de mémoire partagée.
`apc.entries_hint` int
  Un "indice" sur le nombre de variables distinctes qui peuvent être stockées. Mettre à zéro ou, dans le doute, omettre.
`apc.ttl` int
  Considérer que les entrées de cache sans TTL explicite sont expirées si elles n'ont pas été consultées depuis autant de secondes. En effet, cela permet à ces entrées d'être opportunément supprimées lors d'une insertion dans le cache, ou avant une suppression complète. Il est à noter que parce que la suppression est opportuniste, les entrées peuvent toujours être lisibles même si elles sont plus anciennes que `apc.ttl` secondes. Ce paramètre n'a aucun effet sur les entrées de cache pour lesquelles un TTL explicite est spécifié.
`apc.gc_ttl` int
  Le nombre de secondes pendant lesquelles une entrée de cache peut rester sur la liste de collecte des ordures après avoir été retirée ou invalidée. Les entrées sont éligibles à la suppression si leur nombre de références est zéro, ou si elles dépassent cette limite de temps. Si défini à `0`, le nettoyage basé sur le temps est désactivé, et les entrées ne sont supprimées que lorsque leur nombre de références tombe à zéro.
`apc.mmap_file_mask` string
  Si APCu a été compilé avec l'option MMAP en utilisant `--enable-mmap`, ce paramètre reçoit le masque de fichier de type mktemp à passer au module mmap pour déterminer si la région de la mémoire utilisant mmap sera sauvegardée par le biais d'un fichier ou par celui de la mémoire partagée. Dans le cas où la sauvegarde se fait par le biais d'un fichier, le masque sera de la forme `/tmp/apc.XXXXXX` (avec exactement 6 `X`). Pour utiliser shm_open/mmap de la norme POSIX, le masque doit contenir `.shm`, comme dans l'exemple suivant : `/apc.shm.XXXXXX`. Ce paramètre peut être défini par `/dev/zero` pour utiliser l'interface `/dev/zero` du noyau avec une mémoire utilisant mmap anonymement. Laisser ce paramètre indéfini forcera un mmap anonyme.
`apc.slam_defense` bool
  Au démarrage ou lors de la modification d'un fichier dans un serveur très occupé, plusieurs processus peuvent entrer en compétition pour mettre en cache un même fichier en même temps. Configurer `apc.slam_defense` sur `1` peut aider à empêcher plusieurs processus de mettre en cache le même fichier simultanément en introduisant un mécanisme de probabilité. Si la même clé est tentée d'être mise en cache dans un court laps de temps par différents processus, elle saute la mise en cache pour le processus actuel pour atténuer les éventuels problèmes de mise en cache.
`apc.enable_cli` int
  Principalement utilisé pour les tests et le débogage. Définir ce paramètre permet d'activer APC dans la version CLI de PHP. En temps normal, il n'est pas idéal de créer, alimenter et détruire le cache APC à chaque requête CLI. Cependant, dans de nombreux scénarios de test il est utile de pouvoir activer facilement APC dans la version CLI de PHP.
`apc.serializer` string
  Ce paramètre permet à APC d'utiliser un sérialiseur tiers.
`apc.coredump_unmap` bool
  Active la gestion par APC de signaux, tels que SIGSEGV, qui provoquent l'écriture de fichiers core dump lorsqu'ils sont reçus. Quand ces signaux sont reçus, APC essaiera de désallouer le segment de mémoire partagée réservé à mmap dans le but de l'exclure du fichier core dump. Cette option peut améliorer la stabilité du système lorsque des signaux fatals sont reçus et qu'APC est configuré avec un long segment de mémoire partagée.
  Avertissement

  Cette option est potentiellement dangereuse. Désallouer un segment de mémoire partagée utilisé par mmap dans le gestionnaire de signaux fatals peut causer un comportement imprévisible si une erreur fatale survient.

  > Note: Bien que certains noyaux puissent fournir la possibilité d'ignorer de nombreux types de mémoire partagée lorsqu'ils génèrent un fichier core dump, ces implémentations peuvent aussi ignorer d'importants segments de mémoire partagée tels que le tableau de bord d'Apache.

`apc.preload_path` string
  Optionnel, définit un chemin vers le répertoire où APC chargera les données du cache au démarrage.
`apc.use_request_time` bool
  Utilise l'heure de début de la requête SAPI pour la durée de vie (TTL).

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`APC_ITER_ALL` (int)
`APC_ITER_ATIME` (int)
`APC_ITER_CTIME` (int)
`APC_ITER_DEVICE` (int)
`APC_ITER_DTIME` (int)
`APC_ITER_FILENAME` (int)
`APC_ITER_INODE` (int)
`APC_ITER_KEY` (int)
`APC_ITER_MD5` (int)
`APC_ITER_MEM_SIZE` (int)
`APC_ITER_MTIME` (int)
`APC_ITER_NONE` (int)
`APC_ITER_NUM_HITS` (int)
`APC_ITER_REFCOUNT` (int)
`APC_ITER_TTL` (int)
`APC_ITER_TYPE` (int)
`APC_ITER_VALUE` (int)
`APC_LIST_ACTIVE` (int)
`APC_LIST_DELETED` (int)

# APCu Fonctions

# apcu_add

(PECL apcu >= 4.0.0)

apcu_add — Met en cache une nouvelle variable dans le dépôt de données

### Description

function apcu_add(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Met en cache une variable dans le dépôt de données, seulement si elle n'a pas été déjà stockée.

> Note: Contrairement à de nombreux autres mécanismes dans PHP, les variables stockées utilisant apcu_add() persisteront entre les requêtes (jusqu'à ce que leurs valeurs soient retirées du cache).

### Liste de paramètres

`key`
  Stocke la variable en utilisant ce nom de clé. Chaque clé est unique dans le cache, essayer d'utiliser apcu_add() pour stocker une donnée avec une valeur du paramètre `key` déjà existante n'écrasera pas la donnée existante mais retournera `false`. (C'est l'unique différence entre les fonctions apcu_add() et apcu_store().)
`var`
  La variable à stocker.
`ttl`
  Durée de vie; stocke la variable `var` dans le cache pour une durée de `ttl` secondes. Après l'expiration de `ttl`, la variable stockée sera retirée du cache (à la prochaine requête). Si aucune valeur n'est passée à `ttl` (ou si la valeur de `ttl` est `0`), la variable persistera jusqu'à ce qu'elle soit retirée manuellement du cache, ou, sinon, cesse d'exister dans le cache (vidage, redémarrage, etc.).
`values`
  Les noms sont fournis par les clés du tableau `values`, les variables par les valeurs.

### Valeurs de retour

Retourne `true` si une variable a effectivement été ajoutée au cache, `false` sinon. La seconde syntaxe retourne un tableau avec les clés erronées.

### Exemples

Exemple #1 Un exemple avec apcu_add()

    <?php
    $bar = 'BAR';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    $bar = 'NEVER GETS SET';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    ?>

L'exemple ci-dessus va afficher :

    string(3) "BAR"
    string(3) "BAR"

### Voir aussi

- apcu_store() - Met en cache une variable dans le dépôt de données
- apcu_fetch() - Récupère une variable stockée dans le cache
- apcu_delete() - Retire une variable stockée du cache

# apcu_cache_info

(PECL apcu >= 4.0.0)

apcu_cache_info — Récupère les informations mises en cache dans le dépôt de données d'APCu

### Description

function apcu_cache_info(bool `$limited` = `false`): array|false

Récupère les informations et les méta-données mises en cache dans le dépôt de données d'APCu.

### Liste de paramètres

`limited`
  Si la valeur de `limited` est `true`, la valeur retournée exclura la liste individuelle des entrées du cache. Cela est utile lorsqu'une optimisation des appels à des fins statistiques est tentée.

### Valeurs de retour

Tableau des données (et méta-données) mises en cache, ou `false` si une erreur survient

> Note: apcu_cache_info() émettra un avertissement s'il est incapable de retrouver les données du cache APCu. Cela se produit typiquement lorsqu'APCu n'est pas activé.

### Historique

Version | Description
--- | ---
PECL apcu 3.0.11 | Le paramètre `limited` a été introduit.
PECL apcu 3.0.16 | L'option "`filehits`" pour le paramètre `cache_type` a été introduite.

### Exemples

Exemple #1 Un exemple avec apcu_cache_info()

    <?php
    print_r(apcu_cache_info());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [num_slots] => 2000
        [ttl] => 0
        [num_hits] => 9
        [num_misses] => 3
        [start_time] => 1123958803
        [cache_list] => Array
            (
                [0] => Array
                    (
                        [filename] => /path/to/apcu_test.php
                        [device] => 29954
                        [inode] => 1130511
                        [type] => file
                        [num_hits] => 1
                        [mtime] => 1123960686
                        [creation_time] => 1123960696
                        [deletion_time] => 0
                        [access_time] => 1123962864
                        [ref_count] => 1
                        [mem_size] => 677
                    )
                [1] => Array (...itère pour chaque fichier mis en cache)
    )

### Voir aussi

- Directives de configuration d'APCu
- APCUIterator::getTotalSize() - Retourne la taille totale du cache
- APCUIterator::getTotalHits() - Retourne le nombre total d'accès au cache
- APCUIterator::getTotalCount() - Retourne le compte total

# apcu_cas

(PECL apcu >= 4.0.0)

apcu_cas — Met à jour une ancienne valeur avec une nouvelle

### Description

function apcu_cas(string `$key`, int `$old`, int `$new`): bool

apcu_cas() remplace une valeur entière déjà existante, si la valeur du paramètre `old` correspond à celle actuellement stockée, par la valeur du paramètre `new`.

### Liste de paramètres

`key`
  La clé de la valeur à remplacer.
`old`
  L'ancienne valeur (la valeur actuellement stockée).
`new`
  La nouvelle valeur.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Un exemple avec apcu_cas()

    <?php
    apcu_store('foobar', 2);
    echo '$foobar = 2', PHP_EOL;
    echo '$foobar == 1 ? 2 : 1 = ', (apcu_cas('foobar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
    echo '$foobar == 2 ? 1 : 2 = ', (apcu_cas('foobar', 2, 1) ? 'ok' : 'fail'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;

    echo '$f__bar == 1 ? 2 : 1 = ', (apcu_cas('f__bar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;

    apcu_store('perfection', 'xyz');
    echo '$perfection == 2 ? 1 : 2 = ', (apcu_cas('perfection', 2, 1) ? 'ok' : 'epic fail'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    $foobar = 2
    $foobar == 1 ? 2 : 1 = fail
    $foobar == 2 ? 1 : 2 = ok
    $foobar = 1
    $f__bar == 1 ? 2 : 1 = fail
    $perfection == 2 ? 1 : 2 = epic fail
    $foobar = 1

### Voir aussi

- apcu_dec() - Décrémente un nombre stocké
- apcu_store() - Met en cache une variable dans le dépôt de données

# apcu_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cache — Efface le cache APCu

### Description

function apcu_clear_cache(): bool

Efface le cache.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours la valeur `true`.

### Voir aussi

- apcu_cache_info() - Récupère les informations mises en cache dans le dépôt de données d'APCu

# apcu_dec

(PECL apcu >= 4.0.0)

apcu_dec — Décrémente un nombre stocké

### Description

function apcu_dec(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Décrémente une valeur entière stockée.

### Liste de paramètres

`key`
  La clé de la valeur qui doit être décrémentée.
`step`
  Le pas de décrémentation ou la valeur à soustraire.
`success`
  Optionnel, passe la valeur booléenne succès ou échec à la variable référencée.
`ttl`
  Durée de vie à utiliser si la fonction insère une nouvelle variable (au lieu de décrémenter une variable existante).

### Valeurs de retour

Retourne la valeur courante associée à la clé `key` en cas de succès, ou `false` si une erreur survient

### Exemples

Exemple #1 Un exemple avec apcu_dec()

    <?php
    echo "Let's do something with success", PHP_EOL;

    apcu_store('anumber', 42);

    echo apcu_fetch('anumber'), PHP_EOL;

    echo apcu_dec('anumber'), PHP_EOL;
    echo apcu_dec('anumber', 10), PHP_EOL;
    echo apcu_dec('anumber', 10, $success), PHP_EOL;

    var_dump($success);

    echo "Now, let's fail", PHP_EOL, PHP_EOL;

    apcu_store('astring', 'foo');

    $ret = apcu_dec('astring', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Let's do something with success
    42
    41
    31
    21
    bool(true)
    Now, let's fail

    bool(false)
    bool(false)

### Voir aussi

- apcu_inc() - Incrémente un nombre stocké

# apcu_delete

(PECL apcu >= 4.0.0)

apcu_delete — Retire une variable stockée du cache

### Description

function apcu_delete(mixed `$key`): mixed

Retire une variable stockée du cache.

### Liste de paramètres

`key`
  Le paramètre `key` peut être soit une string pour une seule clé, soit un array de chaînes de caractères pour plusieurs clés, soit un object de la classe APCUIterator.

### Valeurs de retour

Si le paramètre `key` est un tableau, alors la valeur retournée est le tableau indexé des clés. Sinon la valeur `true` est retournée en cas de succès, ou `false` en cas d'échec.

### Exemples

Exemple #1 Un exemple avec apcu_delete()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    apcu_delete('foo');
    // c'est clairement inutile sous cette forme

    // Autrement efface plusieurs clés.
    apcu_delete(['foo', 'bar', 'baz']);

    // Ou utilise un Itérateur avec une expression régulière.
    apcu_delete(new APCUIterator('#^myprefix_#'));
    ?>

### Voir aussi

- apcu_store() - Met en cache une variable dans le dépôt de données
- apcu_fetch() - Récupère une variable stockée dans le cache
- apcu_clear_cache() - Efface le cache APCu
- APCUIterator

# apcu_enabled

(PECL apcu >= 4.0.3)

apcu_enabled — Vérifie si APCu est utilisable dans l'environnement courant

### Description

function apcu_enabled(): bool

Vérifie si APCu est utilisable dans l'environnement courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la valeur `true` si APCu est utilisable dans l'environnement courant, ou `false` sinon.

# apcu_entry

(PECL apcu >= 5.1.0)

apcu_entry — Récupère atomiquement ou génère une entrée de cache

### Description

function apcu_entry(string `$key`, callable `$callback`, int `$ttl` = 0): mixed

Tente de récupérer atomiquement la valeur indexée par la clé `key` dans le cache. Si elle ne peut pas être récupérée, la fonction passée à `callback` est appelée, avec pour unique argument `key`. La valeur de retour de l'appel est ensuite mise en cache avec le paramètre optionnel `ttl`, puis le résultat est retourné.

> Note: Lorsque le contrôle entre dans apcu_entry() le verrou du cache est acquis de façon exclusive. Il est libéré lorsque le contrôle quitte apcu_entry() : plus précisément, le corps de la fonction passée à `callback` devient une section critique, ce qui interdit à deux processus d'exécuter la même partie du code concurrentiellement. En outre, il interdit l'exécution concurrentielle de toute autre fonction APCu, puisqu'elle acquerra le même verrou.

Avertissement

La seule fonction APCu qui peut être appelée en toute sécurité par `callback` est apcu_entry().

### Liste de paramètres

`key`
  Clé d'une entrée de cache.
`callback`
  Un paramètre de type callable qui prend `key` pour unique argument et retourne la valeur à mettre en cache.
`ttl`
  Durée de vie; stocke le retour de `callback` en cache pour une durée de `ttl` secondes. Après l'expiration de `ttl`, l'entrée stockée sera retirée du cache (à la prochaine requête). Si aucune valeur n'est passée au paramètre `ttl` (ou si la valeur de `ttl` est `0`), la variable persistera jusqu'à ce qu'elle soit retirée manuellement du cache, ou, sinon, cesse d'exister dans le cache (vidage, redémarrage, etc.).

### Valeurs de retour

Retourne la valeur mise en cache.

### Exemples

Exemple #1 Un exemple avec apcu_entry()

    <?php
    $config = apcu_entry("config", function($key) {
     return [
       "fruit" => apcu_entry("config.fruit", function($key){
         return [
           "apples",
           "pears"
         ];
       }),
       "people" => apcu_entry("config.people", function($key){
         return [
          "bob",
          "joe",
          "niki"
         ];
       })
     ];
    });

    var_dump($config);
    ?>

L'exemple ci-dessus va afficher :

    array(2) {
      ["fruit"]=>
      array(2) {
        [0]=>
        string(6) "apples"
        [1]=>
        string(5) "pears"
      }
      ["people"]=>
      array(3) {
        [0]=>
        string(3) "bob"
        [1]=>
        string(3) "joe"
        [2]=>
        string(4) "niki"
      }
    }

### Voir aussi

- apcu_store() - Met en cache une variable dans le dépôt de données
- apcu_fetch() - Récupère une variable stockée dans le cache
- apcu_delete() - Retire une variable stockée du cache

# apcu_exists

(PECL apcu >= 4.0.0)

apcu_exists — Vérifie si une entrée existe

### Description

function apcu_exists(string|array `$keys`): bool|array

Vérifie si une ou plusieurs entrées APCu existent.

### Liste de paramètres

`keys`
  Une string ou un array de chaînes de caractères qui contient les clés.

### Valeurs de retour

Retourne la valeur `true` si la clé existe, ou `false` sinon. Ou bien, si un array a été passé à `keys`, alors la valeur retournée est un tableau contenant toutes les clés existantes, ou un tableau vide si aucune n'existe.

### Exemples

Exemple #1 Un exemple avec apcu_exists()

    <?php
    $fruit  = 'apple';
    $veggie = 'carrot';

    apcu_store('foo', $fruit);
    apcu_store('bar', $veggie);

    if (apcu_exists('foo')) {
        echo "Foo exists: ";
        echo apcu_fetch('foo');
    } else {
        echo "Foo does not exist";
    }

    echo PHP_EOL;
    if (apcu_exists('baz')) {
        echo "Baz exists.";
    } else {
        echo "Baz does not exist";
    }

    echo PHP_EOL;

    $ret = apcu_exists(array('foo', 'donotexist', 'bar'));
    var_dump($ret);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Foo exists: apple
    Baz does not exist
    array(2) {
      ["foo"]=>
      bool(true)
      ["bar"]=>
      bool(true)
    }

### Voir aussi

- apcu_cache_info() - Récupère les informations mises en cache dans le dépôt de données d'APCu
- apcu_fetch() - Récupère une variable stockée dans le cache

# apcu_fetch

(PECL apcu >= 4.0.0)

apcu_fetch — Récupère une variable stockée dans le cache

### Description

function apcu_fetch(mixed `$key`, bool `&$success` = ?): mixed

Récupère une entrée du cache.

### Liste de paramètres

`key`
  La clé `key` utilisée pour stocker la valeur (avec apcu_store()). Si un tableau est passé alors chaque élément est récupéré et retourné.
`success`
  Défini par la valeur `true` en cas de succès et `false` en cas d'échec.

### Valeurs de retour

La variable ou le tableau de variables stocké en cas de succès; `false` en cas d'échec.

### Historique

Version | Description
--- | ---
PECL apcu 3.0.17 | Le paramètre `success` a été ajouté.

### Exemples

Exemple #1 Un exemple avec apcu_fetch()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

L'exemple ci-dessus va afficher :

    string(3) "BAR"

### Voir aussi

- apcu_store() - Met en cache une variable dans le dépôt de données
- apcu_delete() - Retire une variable stockée du cache
- APCUIterator

# apcu_inc

(PECL apcu >= 4.0.0)

apcu_inc — Incrémente un nombre stocké

### Description

function apcu_inc(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Incrémente un nombre stocké.

### Liste de paramètres

`key`
  La clé de la valeur qui doit être incrémentée.
`step`
  Le pas d'incrémentation ou la valeur à ajouter.
`success`
  Optionnel, passe la valeur booléenne succès ou échec à la variable référencée.
`ttl`
  Durée de vie à utiliser si la fonction insère une nouvelle variable (au lieu d'incrémenter une variable existante).

### Valeurs de retour

Retourne la valeur courante associée à la clé `key` en cas de succès, ou `false` si une erreur survient

### Exemples

Exemple #1 Un exemple avec apcu_inc()

    <?php
    echo "Let's do something with success", PHP_EOL;

    apcu_store('anumber', 42);

    echo apcu_fetch('anumber'), PHP_EOL;

    echo apcu_inc('anumber'), PHP_EOL;
    echo apcu_inc('anumber', 10), PHP_EOL;
    echo apcu_inc('anumber', 10, $success), PHP_EOL;

    var_dump($success);

    echo "Now, let's fail", PHP_EOL, PHP_EOL;

    apcu_store('astring', 'foo');

    $ret = apcu_inc('astring', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Let's do something with success
    42
    43
    53
    63
    bool(true)
    Now, let's fail

    bool(false)
    bool(false)

### Voir aussi

- apcu_dec() - Décrémente un nombre stocké

# apcu_key_info

(PECL apcu >= 4.0.2)

apcu_key_info — Retourne des informations détaillées sur la clé de cache

### Description

function apcu_key_info(string `$key`): ?array

Retourne des informations détaillées sur la clé de cache.

### Liste de paramètres

`key`
  Nom de la clé.

### Valeurs de retour

Un tableau contenant des informations détaillées sur la clé de cache, ou la valeur `null` si la clé n'existe pas.

### Exemples

Exemple #1 Un exemple avec apcu_key_info()

    <?php
    apcu_add('a','b');
    var_dump(apcu_key_info('a'));
    ?>

L'exemple ci-dessus va afficher :

    array(7) {
      ["hits"]=>
      int(0)
      ["access_time"]=>
      int(1606701783)
      ["mtime"]=>
      int(1606701783)
      ["creation_time"]=>
      int(1606701783)
      ["deletion_time"]=>
      int(0)
      ["ttl"]=>
      int(0)
      ["refs"]=>
      int(0)
    }

### Voir aussi

- apcu_store() - Met en cache une variable dans le dépôt de données
- apcu_fetch() - Récupère une variable stockée dans le cache
- apcu_delete() - Retire une variable stockée du cache

# apcu_sma_info

(PECL apcu >= 4.0.0)

apcu_sma_info — Retourne des informations sur l'allocation de mémoire partagée d'APCu

### Description

function apcu_sma_info(bool `$limited` = `false`): array|false

Retourne des informations sur l'allocation de mémoire partagée d'APCu.

### Liste de paramètres

`limited`
  Lorsque la valeur `false` est passée (par défaut) à ce paramètre, la fonction apcu_sma_info() retourne des informations détaillées sur chaque segment.

### Valeurs de retour

Un tableau de données sur l'allocation de mémoire partagée ; `false` en cas d'échec.

### Exemples

Exemple #1 Un exemple avec apcu_sma_info()

    <?php
    print_r(apcu_sma_info());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [num_seg] => 1
        [seg_size] => 31457280
        [avail_mem] => 31448408
        [block_lists] => Array
            (
                [0] => Array
                    (
                        [0] => Array
                            (
                                [size] => 31448408
                                [offset] => 8864
                            )

                    )

            )

    )

### Voir aussi

- Directives de configuration d'APCu

# apcu_store

(PECL apcu >= 4.0.0)

apcu_store — Met en cache une variable dans le dépôt de données

### Description

function apcu_store(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_store(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Met en cache une variable dans le dépôt de données.

> Note: Contrairement à de nombreux autres mécanismes dans PHP, les variables stockées utilisant apcu_store() persisteront entre les requêtes (jusqu'à ce que leurs valeurs soient retirées du cache).

### Liste de paramètres

`key`
  Stocke la variable en utilisant ce nom de clé. Chaque clé est unique dans le cache, stocker une seconde valeur avec le même paramètre `key` écrasera la valeur originale.
`var`
  La variable à stocker.
`ttl`
  Durée de vie; stocke la variable `var` dans le cache pour une durée de `ttl` secondes. Après l'expiration de `ttl`, la variable stockée sera retirée du cache (à la prochaine requête). Si aucune valeur n'est passée au paramètre `ttl` (ou si la valeur de `ttl` est `0`), la variable persistera jusqu'à ce qu'elle soit retirée manuellement du cache, ou, sinon, elle échouera à sortir du cache (lors d'un effacement, redémarrage, etc.).
`values`
  Les noms sont fournis par les clés du tableau `values`, les variables par les valeurs.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient. La seconde syntaxe retourne un tableau avec les clés erronées.

### Exemples

Exemple #1 Un exemple avec apcu_store()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

L'exemple ci-dessus va afficher :

    string(3) "BAR"

### Voir aussi

- apcu_add() - Met en cache une nouvelle variable dans le dépôt de données
- apcu_fetch() - Récupère une variable stockée dans le cache
- apcu_delete() - Retire une variable stockée du cache

## Sommaire

- apcu_add — Met en cache une nouvelle variable dans le dépôt de données
- apcu_cache_info — Récupère les informations mises en cache dans le dépôt de données d'APCu
- apcu_cas — Met à jour une ancienne valeur avec une nouvelle
- apcu_clear_cache — Efface le cache APCu
- apcu_dec — Décrémente un nombre stocké
- apcu_delete — Retire une variable stockée du cache
- apcu_enabled — Vérifie si APCu est utilisable dans l'environnement courant
- apcu_entry — Récupère atomiquement ou génère une entrée de cache
- apcu_exists — Vérifie si une entrée existe
- apcu_fetch — Récupère une variable stockée dans le cache
- apcu_inc — Incrémente un nombre stocké
- apcu_key_info — Retourne des informations détaillées sur la clé de cache
- apcu_sma_info — Retourne des informations sur l'allocation de mémoire partagée d'APCu
- apcu_store — Met en cache une variable dans le dépôt de données

# La classe APCUIterator

(PECL apcu >= 5.0.0)

## Introduction

La classe APCUIterator facilite le parcours des caches APCu de grandes tailles. Cela est utile car elle permet de les parcourir par étapes, tout en récupérant un nombre défini d'entrées par instance de verrouillage. Ainsi, cela libère les verrous de cache pour d'autres activités au lieu de bloquer tout le cache pour récupérer 100 entrées (par défaut). D'autre part, le filtrage par expressions régulières est plus efficace car leur manipulation a été déplacée au niveau du C.

## Synopsis de la classe

class APCUIterator implements Iterator {
/* Méthodes */
public function __construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)
public function current(): mixed
public function getTotalCount(): int
public function getTotalHits(): int
public function getTotalSize(): int
public function key(): string
public function next(): bool
public function rewind(): void
public function valid(): bool
}

# APCUIterator::__construct

(PECL apcu >= 5.0.0)

APCUIterator::__construct — Construit un objet itérateur de la classe APCUIterator

### Description

public function APCUIterator::__construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)

Construit un object de la classe APCUIterator.

### Liste de paramètres

`search`
  Soit une expression régulière PCRE qui filtre le nom des clés APCu, donnée sous la forme d'une chaîne de caractères. Soit un tableau de chaîne de caractères contenant des noms de clés APCu. Ou, bien éventuellement, la valeur `null`, pour sauter l'étape de recherche.
`format`
  Le format souhaité, configuré avec une ou plusieurs des constantes prédéfinies APC_ITER_*.
`chunk_size`
  La taille d'un tronçon. La valeur de ce paramètre doit être plus grande que 0. La valeur par défaut est 100.
`list`
  Le type de liste. Le paramètre peut prendre soit la valeur `APC_LIST_ACTIVE` soit la valeur `APC_LIST_DELETED`.

### Exemples

Exemple #1 Un exemple avec APCUIterator::__construct()

    <?php
    foreach (new APCUIterator('/^counter\./') as $counter) {
        echo "$counter[key]: $counter[value]\n";
        apc_dec($counter['key'], $counter['value']);
    }
    ?>

### Voir aussi

- apcu_exists() - Vérifie si une entrée existe
- apcu_cache_info() - Récupère les informations mises en cache dans le dépôt de données d'APCu

# APCUIterator::current

(PECL apcu >= 5.0.0)

APCUIterator::current — Retourne l'élément courant

### Description

public function APCUIterator::current(): mixed

Retourne l'élément courant de la liste de APCUIterator.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'élément courant en cas de succès ou bien la valeur `false` s'il n'y a plus d'éléments, ou en cas d'échec.

### Voir aussi

- APCUIterator::next() - Déplace le pointeur sur l'élément suivant
- Iterator::current() - Retourne l'élément courant

# APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCount — Retourne le compte total

### Description

public function APCUIterator::getTotalCount(): int

Retourne le compte total.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le compte total.

### Voir aussi

- APCUIterator::getTotalHits() - Retourne le nombre total d'accès au cache
- APCUIterator::getTotalSize() - Retourne la taille totale du cache
- apcu_cache_info() - Récupère les informations mises en cache dans le dépôt de données d'APCu

# APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHits — Retourne le nombre total d'accès au cache

### Description

public function APCUIterator::getTotalHits(): int

Retourne le nombre total d'accès au cache.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre total d'accès au cache en cas de succès ou `false` en cas d'échec.

### Voir aussi

- APCUIterator::getTotalCount() - Retourne le compte total
- APCUIterator::getTotalSize() - Retourne la taille totale du cache
- apcu_cache_info() - Récupère les informations mises en cache dans le dépôt de données d'APCu

# APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSize — Retourne la taille totale du cache

### Description

public function APCUIterator::getTotalSize(): int

Retourne la taille totale du cache.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La taille totale du cache.

### Voir aussi

- APCUIterator::getTotalCount() - Retourne le compte total
- APCUIterator::getTotalHits() - Retourne le nombre total d'accès au cache
- apc_cache_info()

# APCUIterator::key

(PECL apcu >= 5.0.0)

APCUIterator::key — Retourne la clé de l'élément courant

### Description

public function APCUIterator::key(): string

Retourne la clé de l'élément courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la clé en cas de succès ou `false` en cas d'échec.

### Voir aussi

- APCUIterator::current() - Retourne l'élément courant
- Iterator::key() - Retourne la clé de l'élément courant

# APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::next — Déplace le pointeur sur l'élément suivant

### Description

public function APCUIterator::next(): bool

Déplace le pointeur de l'itérateur sur l'élément suivant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- APCUIterator::current() - Retourne l'élément courant
- APCUIterator::rewind() - Repositionne l'itérateur sur le premier élément
- Iterator::next() - Se déplace sur l'élément suivant

# APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewind — Repositionne l'itérateur sur le premier élément

### Description

public function APCUIterator::rewind(): void

Repositionne l'itérateur sur le premier élément.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- APCUIterator::next() - Déplace le pointeur sur l'élément suivant
- Iterator::next() - Se déplace sur l'élément suivant

# APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::valid — Vérifie si la position courante est valide

### Description

public function APCUIterator::valid(): bool

Vérifie si la position courante de l'itérateur est valide.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la valeur `true` si la position courante de l'itérateur est valide, sinon retourne `false`.

### Voir aussi

- APCUIterator::current() - Retourne l'élément courant
- Iterator::valid() - Vérifie si la position courante est valide

## Sommaire

- APCUIterator::__construct — Construit un objet itérateur de la classe APCUIterator
- APCUIterator::current — Retourne l'élément courant
- APCUIterator::getTotalCount — Retourne le compte total
- APCUIterator::getTotalHits — Retourne le nombre total d'accès au cache
- APCUIterator::getTotalSize — Retourne la taille totale du cache
- APCUIterator::key — Retourne la clé de l'élément courant
- APCUIterator::next — Déplace le pointeur sur l'élément suivant
- APCUIterator::rewind — Repositionne l'itérateur sur le premier élément
- APCUIterator::valid — Vérifie si la position courante est valide

- Installation/Configuration
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- APCu Fonctions
  - apcu_add — Met en cache une nouvelle variable dans le dépôt de données
  - apcu_cache_info — Récupère les informations mises en cache dans le dépôt de données d'APCu
  - apcu_cas — Met à jour une ancienne valeur avec une nouvelle
  - apcu_clear_cache — Efface le cache APCu
  - apcu_dec — Décrémente un nombre stocké
  - apcu_delete — Retire une variable stockée du cache
  - apcu_enabled — Vérifie si APCu est utilisable dans l'environnement courant
  - apcu_entry — Récupère atomiquement ou génère une entrée de cache
  - apcu_exists — Vérifie si une entrée existe
  - apcu_fetch — Récupère une variable stockée dans le cache
  - apcu_inc — Incrémente un nombre stocké
  - apcu_key_info — Retourne des informations détaillées sur la clé de cache
  - apcu_sma_info — Retourne des informations sur l'allocation de mémoire partagée d'APCu
  - apcu_store — Met en cache une variable dans le dépôt de données
- APCUIterator — La classe APCUIterator
  - APCUIterator::__construct — Construit un objet itérateur de la classe APCUIterator
  - APCUIterator::current — Retourne l'élément courant
  - APCUIterator::getTotalCount — Retourne le compte total
  - APCUIterator::getTotalHits — Retourne le nombre total d'accès au cache
  - APCUIterator::getTotalSize — Retourne la taille totale du cache
  - APCUIterator::key — Retourne la clé de l'élément courant
  - APCUIterator::next — Déplace le pointeur sur l'élément suivant
  - APCUIterator::rewind — Repositionne l'itérateur sur le premier élément
  - APCUIterator::valid — Vérifie si la position courante est valide

# Componere

# Introduction

Componere (latin, anglais : compose) cible les environnements de production et fournit une API pour la composition de classes, le patching et la conversion de type.

##### Composition:

Componere\Definition est utilisée pour définir (ou redéfinir) une classe à l'exécution; La classe peut ensuite être enregistrée, et dans le cas d'une redéfinition, elle remplace la classe d'origine tant que Componere\Definition existe.

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

##### Patching:

Componere\Patch est utilisée pour changer la classe d'une instance spécifique d'un objet à l'exécution; Le patch reste appliqué tant que Componere\Patch existe, et peut être révoqué explicitement.

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

##### Conversion de type:

Les fonctions de conversion de type Componere\ peuvent effectuer des conversions parmi les types compatibles définis par l'utilisateur; Où compatible signifie que Type est sous ou sur le type de `object`.

function Componere\cast(string `$type`, object `$object`): object
function Componere\cast_by_ref(string `$type`, object `$object`): object

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

La Reflection est requise

## Installation

Le code source et les versions de Componere sont disponibles sur » github

# La classe Componere\Abstract\Definition

(Componere 2 >= 2.1.0)

## Introduction

La classe abstraite finale représente une entrée de classe, et ne devrait pas être utilisée par le développeur.

## Synopsis de la classe

final abstract class Componere\Abstract\Definition {
/* Méthodes */
public function addInterface(string `$interface`): Definition
public function addMethod(string `$name`, Componere\Method `$method`): Definition
public function addTrait(string `$trait`): Definition
public function getReflector(): ReflectionClass
}

# Componere\Abstract\Definition::addInterface

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addInterface — Ajoute une interface

### Description

public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition

Ajoute l'interface donnée à la définition courante

### Liste de paramètres

`interface`
  Le nom insensible à la casse d'une interface

### Valeurs de retour

La définition courante

### Exceptions

Avertissement

Lancera une RuntimeException si la Definition a été enregistrée

# Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethod — Ajoute une méthode

### Description

public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition

Crée ou remplace une méthode sur la définition courante.

### Liste de paramètres

`name`
  Le nom insensible à la casse d'une méthode
`method`
  Une Componere\Method non précédemment ajoutée à une autre Definition

### Valeurs de retour

La Definition courante

### Exceptions

Avertissement

Lancera une RuntimeException si la Definition a été enregistrée

Avertissement

Lancera une RuntimeException si la méthode a été ajoutée à une autre Definition

# Componere\Abstract\Definition::addTrait

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addTrait — Ajoute un trait

### Description

public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition

Utilise le trait pour la définition courante

### Liste de paramètres

`trait`
  Le nom insensible à la casse d'un trait

### Valeurs de retour

La définition courante

### Exceptions

Avertissement

Lancera une RuntimeException si la Definition a été enregistrée

# Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflector — Reflection

### Description

public function Componere\Abstract\Definition::getReflector(): ReflectionClass

Crée ou retourne une ReflectionClass

### Valeurs de retour

Une ReflectionClass pour la définition courante (mise en cache)

## Sommaire

- Componere\Abstract\Definition::addInterface — Ajoute une interface
- Componere\Abstract\Definition::addMethod — Ajoute une méthode
- Componere\Abstract\Definition::addTrait — Ajoute un trait
- Componere\Abstract\Definition::getReflector — Reflection

# La classe Componere\Definition

(Componere 2 >= 2.1.0)

## Introduction

La classe Definition permet au développeur de construire et d'enregistrer un type à l'exécution.

Une définition remplace une classe existante, la classe existante sera restaurée lorsque la définition sera détruite.

## Synopsis de la classe

final class Componere\Definition extends Componere\Abstract\Definition {
/* Constructeurs */
public function __construct(string `$name`)
public function __construct(string `$name`, string `$parent`)
public function __construct(string `$name`, array `$interfaces`)
public function __construct(string `$name`, string `$parent`, array `$interfaces`)
/* Méthodes */
public function addConstant(string `$name`, Componere\Value `$value`): Definition
public function addProperty(string `$name`, Componere\Value `$value`): Definition
public function register(): void
public function isRegistered(): bool
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Méthodes héritées */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Definition::__construct

(Componere 2 >= 2.1.0)

Componere\Definition::__construct — Constructeurs de Definition

### Description

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

### Liste de paramètres

`name`
  Un nom de classe insensible à la casse
`parent`
  Un nom de classe insensible à la casse
`interfaces`
  Un tableau de noms de classes insensibles à la casse

### Exceptions

Avertissement

Lance une InvalidArgumentException si une tentative est faite pour remplacer une classe interne

Avertissement

Lance une InvalidArgumentException si une tentative est faite pour remplacer une interface

Avertissement

Lance une InvalidArgumentException si une tentative est faite pour remplacer un trait

Avertissement

Lance une RuntimeException si une des classes dans `interfaces` ne peut être trouvée

Avertissement

Lance une RuntimeException si une des classes dans `interfaces` n'est pas une interface

# Componere\Definition::addConstant

(Componere 2 >= 2.1.0)

Componere\Definition::addConstant — Ajoute une constante

### Description

public function Componere\Definition::addConstant(string `$name`, Componere\Value `$value`): Definition

Déclare une constante de classe sur la définition actuelle

### Liste de paramètres

`name`
  Le nom sensible à la casse de la constante
`value`
  La valeur de la constante, ne doit pas être indéfinie ou statique

### Valeurs de retour

La définition actuelle

### Exceptions

Avertissement

Lance une RuntimeException si la Definition a été enregistrée

Avertissement

Lance une RuntimeException si `name` est déjà déclaré comme une constante

Avertissement

Lance une RuntimeException si `value` est statique

Avertissement

Lance une RuntimeException si `value` est indéfinie

# Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addProperty — Ajoute une propriété

### Description

public function Componere\Definition::addProperty(string `$name`, Componere\Value `$value`): Definition

Déclare une propriété de classe sur la définition actuelle

### Liste de paramètres

`name`
  Le nom sensible à la casse de la propriété
`value`
  La valeur par défaut de la propriété.

### Valeurs de retour

La définition actuelle

### Exceptions

Avertissement

Lance une RuntimeException si la Definition a été enregistrée

Avertissement

Lance une RuntimeException si `name` est déjà déclaré comme propriété

# Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::register — Inscription

### Description

public function Componere\Definition::register(): void

Inscrit la définition actuelle

### Exceptions

Avertissement

Lance une RuntimeException si la Definition a été enregistrée

# Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegistered — Détection d'état

### Description

public function Componere\Definition::isRegistered(): bool

Détecte l'état d'enregistrement de cette Définition

### Valeurs de retour

Renvoie true si cette Définition est enregistrée

# Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosure — Renvoie la fermeture

### Description

public function Componere\Definition::getClosure(string `$name`): Closure

Renvoie une fermeture pour la méthode spécifiée par le nom

### Liste de paramètres

`name`
  Le nom insensible à la casse de la méthode

### Valeurs de retour

Une fermeture liée à la portée correcte

### Exceptions

Avertissement

Lance une RuntimeException si la Definition a été enregistrée

Avertissement

Lance une RuntimeException si `name` n'a pas pu être trouvé

# Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosures — Renvoie des fermetures

### Description

public function Componere\Definition::getClosures(): array

Renvoie un tableau de fermetures

### Valeurs de retour

Renvoie toutes les méthodes sous forme d'un tableau d'objets Fermeture liés à la portée correcte

### Exceptions

Avertissement

Lance une RuntimeException si la Definition a été enregistrée

## Sommaire

- Componere\Definition::__construct — Constructeurs de Definition
- Componere\Definition::addConstant — Ajoute une constante
- Componere\Definition::addProperty — Ajoute une propriété
- Componere\Definition::register — Inscription
- Componere\Definition::isRegistered — Détection d'état
- Componere\Definition::getClosure — Renvoie la fermeture
- Componere\Definition::getClosures — Renvoie des fermetures

# La classe Componere\Patch

(Componere 2 >= 2.1.0)

## Introduction

La classe Patch permet au développeur de changer le type d'une instance à l'exécution sans enregistrer une nouvelle Définition

Lorsqu'un Patch est détruit, il est révoqué, de sorte que les instances qui ont été patchées pendant la durée de vie du Patch sont restaurées à leur type formel.

## Synopsis de la classe

final class Componere\Patch extends Componere\Abstract\Definition {
/* Constructeurs */
public function __construct(object `$instance`)
public function __construct(object `$instance`, array `$interfaces`)
/* Méthodes */
public function apply(): void
public function revert(): void
public function isApplied(): bool
public function derive(object `$instance`): Patch
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Méthodes héritées */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Patch::__construct

(Componere 2 >= 2.1.0)

Componere\Patch::__construct — Construction de patch

### Description

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

### Liste de paramètres

`instance`
  La cible de ce patch
`interfaces`
  Un tableau insensible à la casse de noms de classes

### Exceptions

Avertissement

Lance une RuntimeException si une classe dans `interfaces` ne peut pas être trouvée

Avertissement

Lance une RuntimeException si une classe dans `interfaces` n'est pas une interface

# Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::apply — Applique

### Description

public function Componere\Patch::apply(): void

Applique le patch courant

# Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revert — Restaure

### Description

public function Componere\Patch::revert(): void

Restaure le patch courant

# Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isApplied — Détection d'état

### Description

public function Componere\Patch::isApplied(): bool

# Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::derive — Dérivation de patch

### Description

public function Componere\Patch::derive(object `$instance`): Patch

Dérive un Patch pour l'`instance` donnée

### Liste de paramètres

`instance`
  La cible pour le patch dérivé

### Valeurs de retour

Un Patch pour `instance` dérivé du Patch courant

### Exceptions

Avertissement

Lance une InvalidArgumentException si `instance` n'est pas compatible

# Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosure — Renvoie une fermeture

### Description

public function Componere\Patch::getClosure(string `$name`): Closure

Renvoie une fermeture pour la méthode spécifiée par le nom

### Liste de paramètres

`name`
  Le nom insensible à la casse de la méthode

### Valeurs de retour

Une fermeture liée au bon contexte et au bon objet

### Exceptions

Avertissement

Lance une RuntimeException si `name` ne peut pas être trouvé

# Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosures — Renvoie des fermetures

### Description

public function Componere\Patch::getClosures(): array

Renvoie un tableau de fermetures

### Valeurs de retour

Renvoie toutes les méthodes sous forme d'un tableau d'objets Fermeture liés au bon contexte et au bon objet

## Sommaire

- Componere\Patch::__construct — Construction de patch
- Componere\Patch::apply — Applique
- Componere\Patch::revert — Restaure
- Componere\Patch::isApplied — Détection d'état
- Componere\Patch::derive — Dérivation de patch
- Componere\Patch::getClosure — Renvoie une fermeture
- Componere\Patch::getClosures — Renvoie des fermetures

# La classe Componere\Method

(Componere 2 >= 2.1.0)

## Introduction

Une Method représente une fonction avec des drapeaux d'accessibilité modifiables

## Synopsis de la classe

final class Componere\Method {
/* Constructeur */
public function __construct(Closure `$closure`)
/* Méthodes */
public function setPrivate(): Method
public function setProtected(): Method
public function setStatic(): Method
public function getReflector(): ReflectionMethod
}

# Componere\Method::__construct

(Componere 2 >= 2.1.0)

Componere\Method::__construct — Construction de méthode

### Description

public function Componere\Method::__construct(Closure `$closure`)

### Liste de paramètres

`closure`

# Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivate — Modification de l'accessibilité

### Description

public function Componere\Method::setPrivate(): Method

### Valeurs de retour

La méthode actuelle

### Exceptions

Avertissement

Lance une RuntimeException si le niveau d'accès a déjà été défini

# Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtected — Modification de l'accessibilité

### Description

public function Componere\Method::setProtected(): Method

### Valeurs de retour

La méthode actuelle

### Exceptions

Avertissement

Lance une RuntimeException si le niveau d'accès a déjà été défini

# Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStatic — Modification de l'accessibilité

### Description

public function Componere\Method::setStatic(): Method

### Valeurs de retour

La méthode actuelle

# Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflector — Reflection

### Description

public function Componere\Method::getReflector(): ReflectionMethod

Crée ou retourne une ReflectionMethod

### Valeurs de retour

Une ReflectionMethod pour la méthode actuelle (mise en cache)

## Sommaire

- Componere\Method::__construct — Construction de méthode
- Componere\Method::setPrivate — Modification de l'accessibilité
- Componere\Method::setProtected — Modification de l'accessibilité
- Componere\Method::setStatic — Modification de l'accessibilité
- Componere\Method::getReflector — Reflection

# La classe Componere\Value

(Componere 2 >= 2.1.0)

## Introduction

La classe Value représente une variable PHP de tous types, y compris indéfinie

## Synopsis de la classe

final class Componere\Value {
/* Constructeur */
public function __construct(mixed `$default` = ?)
/* Méthodes */
public function setPrivate(): Value
public function setProtected(): Value
public function setStatic(): Value
public function isPrivate(): bool
public function isProtected(): bool
public function isStatic(): bool
public function hasDefault(): bool
}

# Componere\Value::__construct

(Componere 2 >= 2.1.0)

Componere\Value::__construct — Construction de Value

### Description

public function Componere\Value::__construct(mixed `$default` = ?)

### Liste de paramètres

`default`

### Exceptions

Avertissement

Lance une InvalidArgumentException si `default` n'a pas une valeur adaptée

# Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivate — Modification d'accessibilité

### Description

public function Componere\Value::setPrivate(): Value

### Valeurs de retour

La valeur actuelle

### Exceptions

Avertissement

Lance une RuntimeException si le niveau d'accès a déjà été défini

# Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtected — Modification d'accessibilité

### Description

public function Componere\Value::setProtected(): Value

### Valeurs de retour

La valeur actuelle

### Exceptions

Avertissement

Lance une RuntimeException si le niveau d'accès a déjà été défini

# Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStatic — Modification d'accessibilité

### Description

public function Componere\Value::setStatic(): Value

### Valeurs de retour

La valeur actuelle

# Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivate — Détection d'accessibilité

### Description

public function Componere\Value::isPrivate(): bool

# Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtected — Détection d'accessibilité

### Description

public function Componere\Value::isProtected(): bool

# Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStatic — Détection d'accessibilité

### Description

public function Componere\Value::isStatic(): bool

# Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefault — Interaction de valeur

### Description

public function Componere\Value::hasDefault(): bool

## Sommaire

- Componere\Value::__construct — Construction de Value
- Componere\Value::setPrivate — Modification d'accessibilité
- Componere\Value::setProtected — Modification d'accessibilité
- Componere\Value::setStatic — Modification d'accessibilité
- Componere\Value::isPrivate — Détection d'accessibilité
- Componere\Value::isProtected — Détection d'accessibilité
- Componere\Value::isStatic — Détection d'accessibilité
- Componere\Value::hasDefault — Interaction de valeur

# Fonctions de Componere

# Componere\cast

(Componere 2 >= 2.1.2)

Componere\cast — Conversion de type

### Description

function Componere\cast(string `$type`, object `$object`): object

### Liste de paramètres

`type`
  Un type défini par l'utilisateur
`object`
  Un objet avec un type défini par l'utilisateur compatible avec Type

### Valeurs de retour

Un object de type Type, converti depuis `object`

### Erreurs / Exceptions

Avertissement

Lance une InvalidArgumentException si le type de `object` est ou est dérivé d'une classe interne

Avertissement

Lance une InvalidArgumentException si Type est une interface

Avertissement

Lance une InvalidArgumentException si Type est un trait

Avertissement

Lance une InvalidArgumentException si Type est abstrait

Avertissement

Lance une InvalidArgumentException si Type n'est pas compatible avec le type de `object`

### Voir aussi

- Componere\cast_by_ref

# Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_ref — Conversion de type

### Description

function Componere\cast_by_ref(string `$type`, object `$object`): object

### Liste de paramètres

type
  Un type défini par l'utilisateur
`object`
  Un objet avec un type défini par l'utilisateur compatible avec Type

### Valeurs de retour

Un object de type Type, converti depuis `object`, où les membres sont des références aux membres de `object`

### Erreurs / Exceptions

Avertissement

Lance une InvalidArgumentException si le type de `object` est ou est dérivé d'une classe interne

Avertissement

Lance une InvalidArgumentException si Type est une interface

Avertissement

Lance une InvalidArgumentException si Type est un trait

Avertissement

Lance une InvalidArgumentException si Type est abstrait

Avertissement

Lance une InvalidArgumentException si Type n'est pas compatible avec le type de `object`

### Voir aussi

- Componere\cast

## Sommaire

- Componere\cast — Conversion de type
- Componere\cast_by_ref — Conversion de type

- Installation/Configuration
  - Pré-requis
  - Installation
- Componere\Abstract\Definition — La classe Componere\Abstract\Definition
  - Componere\Abstract\Definition::addInterface — Ajoute une interface
  - Componere\Abstract\Definition::addMethod — Ajoute une méthode
  - Componere\Abstract\Definition::addTrait — Ajoute un trait
  - Componere\Abstract\Definition::getReflector — Reflection
- Componere\Definition — La classe Componere\Definition
  - Componere\Definition::__construct — Constructeurs de Definition
  - Componere\Definition::addConstant — Ajoute une constante
  - Componere\Definition::addProperty — Ajoute une propriété
  - Componere\Definition::register — Inscription
  - Componere\Definition::isRegistered — Détection d'état
  - Componere\Definition::getClosure — Renvoie la fermeture
  - Componere\Definition::getClosures — Renvoie des fermetures
- Componere\Patch — La classe Componere\Patch
  - Componere\Patch::__construct — Construction de patch
  - Componere\Patch::apply — Applique
  - Componere\Patch::revert — Restaure
  - Componere\Patch::isApplied — Détection d'état
  - Componere\Patch::derive — Dérivation de patch
  - Componere\Patch::getClosure — Renvoie une fermeture
  - Componere\Patch::getClosures — Renvoie des fermetures
- Componere\Method — La classe Componere\Method
  - Componere\Method::__construct — Construction de méthode
  - Componere\Method::setPrivate — Modification de l'accessibilité
  - Componere\Method::setProtected — Modification de l'accessibilité
  - Componere\Method::setStatic — Modification de l'accessibilité
  - Componere\Method::getReflector — Reflection
- Componere\Value — La classe Componere\Value
  - Componere\Value::__construct — Construction de Value
  - Componere\Value::setPrivate — Modification d'accessibilité
  - Componere\Value::setProtected — Modification d'accessibilité
  - Componere\Value::setStatic — Modification d'accessibilité
  - Componere\Value::isPrivate — Détection d'accessibilité
  - Componere\Value::isProtected — Détection d'accessibilité
  - Componere\Value::isStatic — Détection d'accessibilité
  - Componere\Value::hasDefault — Interaction de valeur
- Fonctions de Componere
  - Componere\cast — Conversion de type
  - Componere\cast_by_ref — Conversion de type

# Gestion des erreurs et des journaux

# Introduction

Voici des fonctions gérant les erreurs et les journaux. Elles permettent de définir ses propres règles de gestion des erreurs, mais aussi la façon dont les erreurs sont enregistrées ; ceci afin de répondre aux besoins particuliers.

Avec les fonctions de journal, il est possible d'envoyer des messages directement à d'autres machines (ou des e-mails, ou via une passerelle vers pager), vers les journaux d'événements du système, etc., ainsi, il est possible de sélectionner les messages et surveiller les parties les plus importantes des applications et des sites web.

Les fonctions sur le rapport d'erreurs permettent de personnaliser le degré et le type d'erreurs souhaités, allant de simples notifications à des fonctions personnalisées appelées lorsque des erreurs surviennent.

# Installation/Configuration

## Sommaire

- Configuration à l'exécution

## Configuration à l'exécution

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

Options de configuration pour la gestion d'erreurs
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
error_reporting | NULL | `INI_ALL` |
fatal_error_backtraces | "1" | `INI_ALL` | Disponible à partir de PHP 8.5.0
display_errors | "1" | `INI_ALL` |
display_startup_errors | "1" | `INI_ALL` | Antérieur à PHP 8.0.0, la valeur par défaut était `"0"`.
log_errors | "0" | `INI_ALL` |
log_errors_max_len | "1024" | `INI_ALL` | Sans effet à partir de PHP 8.0.0, supprimé à partir de PHP 8.1.0.
ignore_repeated_errors | "0" | `INI_ALL` |
ignore_repeated_source | "0" | `INI_ALL` |
report_memleaks | "1" | `INI_ALL` | Obsolète à partir de PHP 8.5.0
track_errors | "0" | `INI_ALL` | Obsolète à partir de PHP 7.2.0, supprimée à partir de PHP 8.0.0.
html_errors | "1" | `INI_ALL` |
xmlrpc_errors | "0" | `INI_SYSTEM` |
xmlrpc_error_number | "0" | `INI_ALL` |
docref_root | "" | `INI_ALL` |
docref_ext | "" | `INI_ALL` |
error_prepend_string | NULL | `INI_ALL` |
error_append_string | NULL | `INI_ALL` |
error_log | NULL | `INI_ALL` |
error_log_mode | 0o644 | `INI_ALL` | Disponible à partir de PHP 8.2.0.
syslog.facility | "LOG_USER" | `INI_SYSTEM` | Disponible à partir de PHP 7.3.0.
syslog.filter | "no-ctrl" | `INI_ALL` | Disponible à partir de PHP 7.3.0.
syslog.ident | "php" | `INI_SYSTEM` | Disponible à partir de PHP 7.3.0.

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`error_reporting` int

  Fixe le niveau d'erreur. Ce paramètre est un entier, représentant un champ de bits. Ajouter les valeurs suivantes pour choisir le niveau que l'on désire, telles que décrites dans la section Constantes pré-définies, et dans le fichier php.ini. Pour modifier cette configuration durant l'exécution du script, utiliser la fonction error_reporting(). Voir aussi la directive display_errors.

  La valeur par défaut est `E_ALL`.

  Antérieur à PHP 8.0.0, la valeur par défaut était : ``E_ALL` & ~`E_NOTICE` & ~`E_STRICT` & ~`E_DEPRECATED``. Ceci signifie que les diagnostics de niveau `E_NOTICE`, `E_STRICT` et `E_DEPRECATED` n'étaient pas affichés.

  > Note: Les constantes PHP en dehors de PHP

  > L'utilisation des constantes PHP en dehors de PHP, comme dans le fichier httpd.conf, n'a pas de signification utile, donc dans ces cas, des valeurs entières sont nécessaires. Et depuis que les niveaux d'erreurs ont été ajoutés, la valeur maximale (pour `E_ALL`) devrait changer. Donc, à la place de `E_ALL`, utiliser plutôt une valeur plus grande pour couvrir tous les octets, une valeur numérique comme `2147483647` (incluant toutes les erreurs, et non juste les erreurs de type `E_ALL`).

`fatal_error_backtraces` bool
  Contrôle si les erreurs fatales doivent inclure une trace. Les erreurs fatales sont `E_ERROR`, `E_CORE_ERROR`, `E_COMPILE_ERROR`, `E_USER_ERROR`, `E_RECOVERABLE_ERROR`, et `E_PARSE`.
`display_errors` string

  Cette directive détermine si les erreurs doivent être affichées à l'écran dans la sortie, ou si elles doivent être cachées à l'utilisateur.

  - `Off` : n'affiche aucune erreur.
  - `On` ou `stdout` : affiche les erreurs vers `stdout`. C'est la valeur par défaut.
  - `stderr` : affiche les erreurs vers `stderr`. Effectif uniquement pour les SAPI `CLI`, `phpdbg` et `CGI`.
  Le fichier `php.ini-development` fourni définit cette valeur à `On` ; `php.ini-production` la définit à `Off`.

  > Note: C'est une directive nécessaire en développement, mais qui ne doit jamais être utilisée sur un système en production. (e.g. systèmes connectés à Internet).

  > Note:

  > Bien que display_errors puisse être défini en cours d'exécution (avec la fonction ini_set()), il n'aura aucun effet si le script a des erreurs fatales, car l'action désirée au moment de l'exécution ne sera pas exécutée.

`display_startup_errors` bool

  Même si display_errors est activé, des erreurs peuvent survenir lors de la séquence de démarrage de PHP, et ces erreurs sont cachées. Avec cette option, il est possible de les afficher, ce qui est recommandé pour le débogage. En dehors de ce cas, il est fortement recommandé de laisser display_startup_errors à off.

`log_errors` bool

  Indique si les messages d'erreur générés par les scripts devraient être journalisés dans le journal d'erreurs du serveur ou dans error_log. Cette fonction est spécifique aux serveurs.

  > Note:

  > Il est recommandé d'utiliser l'historique d'erreur, plutôt que d'afficher les erreurs sur les sites de production.

`log_errors_max_len` int

  Configure la taille maximale des erreurs qui seront enregistrées dans l'historique, en octets. Dans les informations de error_log, l'origine est ajoutée. La valeur par défaut est de 1024. 0 signifie qu'il n'y a pas de limite de taille. Cette longueur est appliquée pour enregistrer dans l'historique les erreurs, afficher les erreurs et également à $php_errormsg mais pas pour les appels explicites aux fonctions comme error_log().

  Lorsqu'un entier est utilisé, sa valeur est mesurée en octets. Vous pouvez également utiliser la notation sténographique comme décrit dans cette entrée de la FAQ..
`ignore_repeated_errors` bool

  Ne pas enregistrer des messages répétitifs. Les erreurs répétées doivent survenir au même moment, à la même ligne et depuis le même fichier de script, à moins que ignore_repeated_source soit défini à `true`.

`ignore_repeated_source` bool

  Ignore la source du message lors des messages répétés. Lorsqu'on a configuré cette option à On, ne seront pas enregistrées les erreurs répétées provenant de fichiers et lignes de code différents.

`report_memleaks` bool
  Si ce paramètre est défini à On (par défaut), il affichera un rapport de fuite mémoire détectée par le gestionnaire de mémoire Zend. Ce rapport sera envoyé à stderr sur les plateformes Posix. Sous Windows, il sera envoyé au débogueur en utilisant OutputDebugString() et pourra être lu avec des outils comme » DbgView. Ce paramètre n'a d'effet que lors d'une compilation de débogage, et si error_reporting inclut `E_WARNING` dans sa liste autorisée.
  Avertissement

  Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonctionnalité est fortement déconseillé.

`track_errors` bool

  Si cette option est activée, le dernier message d'erreur sera placé dans la variable $php_errormsg.

`html_errors` bool

  Si activé, les messages d'erreur incluront les balises HTML. Le format des erreurs HTML produira des messages cliquables qui redirigeront l'utilisateur vers une page décrivant l'erreur ou la fonction qui a causé l'erreur. Ces références sont affectées par docref_root et docref_ext.

  Si désactivé, le message d'erreur sera rendu en texte plein.

`xmlrpc_errors` bool

  Si activé, désactive le rapport normal d'erreur et formate les erreurs comme des messages d'erreur XML-RPC.

`xmlrpc_error_number` int

  Utilisé comme valeur de l'élément XML-RPC faultcode.

`docref_root` string

  Le nouveau format d'erreur contient une référence à une page décrivant l'erreur, ou la fonction ayant causé l'erreur. Pour le manuel, il est possible de télécharger ce dernier dans la langue, et configurer cette option pour qu'elle pointe sur lui. Si la copie du manuel est accessible à `"/manual/"`, il est possible de simplement utiliser `docref_root=/manual/`. De plus, il faut configurer `docref_ext` pour qu'elle corresponde aux extensions du manuel. `docref_ext=.html`. Il est possible d'utiliser des références externes. Par exemple, il est possible d'utiliser `docref_root=http://manual/en/` ou `docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon&url=http%3A%2F%2Fwww.php.net%2F"`

  La plupart du temps, l'on utilise l'option docref_root avec un slash à la fin (`"/"`). Mais ce n'est pas obligatoire, comme le montre le second exemple ci-dessus.

  > Note:

  > Cette directive est destinée à aider dans le développement en rendant facile la consultation de la description d'une fonction. Ne jamais l'utiliser sur un système de production (e.g. système connecté à Internet).

`docref_ext` string

  Voir aussi docref_root.

  > Note:

  > La valeur de docref_ext doit commencer par un point `"."`.

`error_prepend_string` string

  La chaîne à placer avant les messages d'erreur. Seulement utilisé quand le message d'erreur est affiché à l'écran. L'usage principal est de pouvoir ajouter du balisage HTML additionnel avant le message d'erreur.

`error_append_string` string

  La chaîne à placer après les messages d'erreur. Seulement utilisé quand le message d'erreur est affiché à l'écran. L'usage principal est de pouvoir ajouter du balisage HTML additionnel après le message d'erreur.

`error_log` string

  Nom du fichier où seront enregistrées les erreurs. Le fichier doit être accessible en écriture par l'utilisateur exécutant le serveur web. Si la valeur spéciale `syslog` est utilisée, les erreurs seront envoyées au système d'historique du serveur. Sous Unix, cela correspond à syslog(3) et sous Windows à l'historique d'événement. Voir aussi : syslog(). Si cette directive n'est pas fixée, les erreurs sont envoyées au journal d'erreurs SAPI. Par exemple, s'il s'agit d'une erreur de journal dans Apache ou `stderr` dans CLI. Voir aussi la fonction error_log().

`error_log_mode` int

  Mode de fichier pour le fichier défini pour error_log.

`syslog.facility` string

  Spécifie le type de programme qui consigne le message. Uniquement efficace si error_log est défini sur "syslog".

`syslog.filter` string

  Spécifie le type de filtre pour filtrer les messages consignés. Les caractères autorisés sont passés non modifiés ; tous les autres sont écrits dans leur représentation hexadécimale préfixée avec `\x`.

  - `all` – la chaîne consignée sera séparée lors des caractères de retour à la ligne, et tous les caractères sont transmis sans altérations
  - `ascii` – la chaîne consignée sera séparée lors des caractères de retour à la ligne, et tout caractère 7-bit ASCII non imprimable sera échappé
  - `no-ctrl` – la chaîne consignée sera séparée lors des caractères de retour à la ligne, et les caractères non imprimables seront échappés
  - `raw` – tous les caractères sont passés au système de consignation sans altérations, sans séparations aux retours à la ligne (identique à PHP antérieur à 7.3)
  Ce paramètre affectera la consignation via error_log défini à "syslog" et les appels à syslog().

  > Note:

  > Le type de filtre `raw` est disponible à partir de PHP 7.3.8 et PHP 7.4.0.

  Cette directive n'est pas supportée sur Windows.
`syslog.ident` string

  Spécifie la chaîne d'identité qui est ajoutée à chaque message. Uniquement efficace si error_log est défini sur "syslog".

# Constantes pré-définies

Les constantes listées ici sont toujours disponibles dans PHP.

Les constantes suivantes (soit la valeur numérique correspondante, soit leur nom symbolique) sont utilisées comme un masque de bits pour spécifier les erreurs à signaler. Il est possible d'utiliser les opérateurs binaires pour combiner ces valeurs ou masquer certains types d'erreurs.

Astuce

Les noms des constantes peuvent être utilisés dans php.ini au lieu des valeurs numériques brutes auxquelles elles correspondent. Cependant, seuls les opérateurs `|`, `~`, `^`, `!`, `&` sont compris dans php.ini.

Avertissement

Il n'est pas possible d'utiliser les noms symboliques en dehors de PHP. Par exemple, dans httpd.conf la valeur calculée du masque de bits doit être utilisée à la place.

`E_ERROR` (int)
  Erreurs fatales lors de l'exécution. Celles-ci indiquent des erreurs dont il est impossible de se remettre, comme un problème d'allocation de mémoire. L'exécution du script est arrêtée. Valeur de la constante : `1`
`E_WARNING` (int)
  Avertissements lors de l'exécution (erreurs non fatales). L'exécution du script n'est pas interrompue. Valeur de la constante : `2`
`E_PARSE` (int)
  Erreurs d'analyse au moment de la compilation. Les erreurs d'analyse devraient uniquement être générées par l'analyseur syntaxique. Valeur de la constante : `4`
`E_NOTICE` (int)
  Notifications d'exécution. Indiquent que le script a rencontré quelque chose qui pourrait signaler une erreur, mais qui pourrait aussi se produire normalement lors de l'exécution d'un script. Valeur de la constante : `8`
`E_CORE_ERROR` (int)
  Erreurs fatales qui surviennent lors du démarrage initial de PHP. C'est comme un `E_ERROR`, sauf qu'il est généré par le cœur de PHP. Valeur de la constante : `16`
`E_CORE_WARNING` (int)
  Avertissements (erreurs non fatales) qui surviennent lors du démarrage initial de PHP. C'est comme un `E_WARNING`, sauf qu'il est généré par le cœur de PHP. Valeur de la constante : `32`
`E_COMPILE_ERROR` (int)
  Erreurs fatales de compilation. C'est comme un `E_ERROR`, sauf qu'il est généré par le moteur de script Zend. Valeur de la constante : `64`
`E_COMPILE_WARNING` (int)
  Avertissements de compilation (erreurs non fatales). C'est comme un `E_WARNING`, sauf qu'il est généré par le moteur de script Zend. Valeur de la constante : `128`
`E_DEPRECATED` (int)
  Avis de dépréciation à l'exécution. Activer ceci pour recevoir des avertissements concernant du code qui ne fonctionnera plus dans les futures versions. Valeur de la constante : `8192`
`E_USER_ERROR` (int)
  Message d'erreur généré par l'utilisateur. Cela ressemble à un `E_ERROR`, sauf qu'il est généré dans le code PHP en utilisant la fonction PHP trigger_error(). Valeur de la constante : `256`
  Avertissement

  L'utilisation de cette constante avec trigger_error() est dépréciée à partir de PHP 8.4.0. Il est recommandé de soit `throw` une Exception ou d'appeler exit() à la place.

`E_USER_WARNING` (int)
  Message d'avertissement généré par l'utilisateur. Cela ressemble à un `E_WARNING`, sauf qu'il est généré dans le code PHP en utilisant la fonction PHP trigger_error(). Valeur de la constante : `512`
`E_USER_NOTICE` (int)
  Message de notification généré par l'utilisateur. Cela ressemble à un `E_NOTICE`, sauf qu'il est généré dans le code PHP en utilisant la fonction PHP trigger_error(). Valeur de la constante : `1024`
`E_USER_DEPRECATED` (int)
  Message de dépréciation généré par l'utilisateur. Cela ressemble à un `E_DEPRECATED`, sauf qu'il est généré dans le code PHP en utilisant la fonction PHP trigger_error(). Valeur de la constante : `16384`
`E_STRICT` (int)
  Suggestions d'exécution émises par PHP concernant le code exécuté pour garantir la compatibilité future. Valeur de la constante : `2048`
  Avertissement

  Ce niveau d'erreur n'est pas utilisé, et est déprécié à partir de PHP 8.4.0.

`E_RECOVERABLE_ERROR` (int)
  "Exceptions" de l'ancien moteur correspondant à une erreur fatale rattrapable. Semblable à Error mais doit être capturée via un gestionnaire d'erreurs défini par l'utilisateur (voir set_error_handler()). Si elle n'est pas gérée, cela se comporte comme `E_ERROR`. Valeur de la constante : `4096`

  > Note: Ce niveau d'erreur est effectivement inutilisé, le seul cas où cela peut se produire est lorsque l'interprétation d'un objet en tant que bool échoue. Cela ne peut se produire que pour des objets internes. L'exemple le plus courant, antérieur à PHP 8.4.0, est l'utilisation d'une instance GMP dans une condition.

`E_ALL` (int)
  Masque de bits qui contient toutes les erreurs, avertissements et notifications. Valeur de la constante : `30719`
  Avertissement

  Avant PHP 8.4, la valeur de la constante était : `32767`.

# Exemples

Ci-dessous, se trouve un exemple de gestion des erreurs par PHP. Il y est défini un gestionnaire d'erreur, qui enregistre les informations dans un fichier (au format XML), et envoie un courriel au développeur si l'erreur est critique.

Exemple #1 Gestion d'erreurs avancées en PHP

    <?php
    // Nous allons faire notre propre gestion
    error_reporting(0);

    // Fonction spéciale de gestion des erreurs
    function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars)
    {
        // Date et heure de l'erreur
        $dt = date("Y-m-d H:i:s (T)");

        // Définit un tableau associatif avec les chaînes d'erreur
        // En fait, les seuls niveaux qui nous intéressent
        // sont E_WARNING, E_NOTICE, E_USER_ERROR,
        // E_USER_WARNING et E_USER_NOTICE
        $errortype = array (
                    E_ERROR              => 'Erreur',
                    E_WARNING            => 'Alerte',
                    E_PARSE              => 'Erreur d\'analyse',
                    E_NOTICE             => 'Note',
                    E_CORE_ERROR         => 'Erreur du noyau',
                    E_CORE_WARNING       => 'Alerte du noyau',
                    E_COMPILE_ERROR      => 'Erreur de compilation',
                    E_COMPILE_WARNING    => 'Alerte de compilation',
                    E_USER_ERROR         => 'Erreur spécifique',
                    E_USER_WARNING       => 'Alerte spécifique',
                    E_USER_NOTICE        => 'Note spécifique',
                    E_STRICT             => 'Note d\'exécution',
                    E_RECOVERABLE_ERROR  => 'Erreur fatale rattrapable'
                    );
        // Les niveaux qui seront enregistrés
        $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);

        $err = "<errorentry>\n";
        $err .= "\t<datetime>" . $dt . "</datetime>\n";
        $err .= "\t<errornum>" . $errno . "</errornum>\n";
        $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
        $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
        $err .= "\t<scriptname>" . $filename . "</scriptname>\n";
        $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";

        if (in_array($errno, $user_errors)) {
            $err .= "\t<vartrace>".wddx_serialize_value($vars,"Variables")."</vartrace>\n";
        }
        $err .= "</errorentry>\n\n";

        // pour tester
        // echo $err;

        // sauvegarde de l'erreur, et mail si c'est critique
        error_log($err, 3, "/usr/local/php4/error.log");
        if ($errno == E_USER_ERROR) {
            mail("phpdev@example.com","Critical User Error",$err);
        }
    }

    function distance($vect1, $vect2)
    {
        if (!is_array($vect1) || !is_array($vect2)) {
            trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
            return NULL;
        }

        if (count($vect1) != count($vect2)) {
            trigger_error("Vectors need to be of the same size", E_USER_ERROR);
            return NULL;
        }

        for ($i=0; $i<count($vect1); $i++) {
            $c1 = $vect1[$i]; $c2 = $vect2[$i];
            $d = 0.0;
            if (!is_numeric($c1)) {
                trigger_error("Coordinate $i in vector 1 is not a number, using zero",
                                E_USER_WARNING);
                $c1 = 0.0;
            }
            if (!is_numeric($c2)) {
                trigger_error("Coordinate $i in vector 2 is not a number, using zero",
                                E_USER_WARNING);
                $c2 = 0.0;
            }
            $d += $c2*$c2 - $c1*$c1;
        }
        return sqrt($d);
    }

    $old_error_handler = set_error_handler("userErrorHandler");

    // constante non définie, qui génère une alerte
    $t = I_AM_NOT_DEFINED;

    // définition de quelques vecteurs
    $a = array (2, 3, "foo");
    $b = array (5.5, 4.3, -1.6);
    $c = array (1, -3);

    // génère une erreur utilisateur
    $t1 = distance ($c, $b)."\n";

    // génère une erreur utilisateur
    $t2 = distance ($b, "i am not an array")."\n";

    // Génère une alerte
    $t3 = distance ($a, $b)."\n";

    ?>

# Fonctions sur la gestion des erreurs

# Voir aussi

Voir aussi la fonction syslog().

# debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtrace — Génère une trace de la pile d'appels

### Description

function debug_backtrace(int `$options` = `DEBUG_BACKTRACE_PROVIDE_OBJECT`, int `$limit` = 0): array

debug_backtrace() génère un contexte de débogage PHP.

### Liste de paramètres

`options`

  Ce paramètre est un masque d'options suivantes :

  Options pour la fonction debug_backtrace()
  DEBUG_BACKTRACE_PROVIDE_OBJECT | Si l'on doit ou non peupler l'index "object".
  DEBUG_BACKTRACE_IGNORE_ARGS | Si l'on doit ou non omettre l'index "args" et donc tous les arguments de la fonction/méthode pour économiser de la mémoire.

  > Note:

  > Il existe quatre combinaisons possibles :

  > Options de debug_backtrace()
  > `debug_backtrace()` | Alimente les deux index
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT)`
  > `debug_backtrace(~DEBUG_BACKTRACE_PROVIDE_OBJECT)` | Omet l'index `"object"` et remplit l'index `"args"`.
  > `debug_backtrace(0)`
  > `debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)` | Omet à la fois l'index `"object"` et l'index `"args"`.
  > `debug_backtrace(~DEBUG_BACKTRACE_PROVIDE_OBJECT | DEBUG_BACKTRACE_IGNORE_ARGS)`
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT|DEBUG_BACKTRACE_IGNORE_ARGS)` | Remplit l'index `"object"` et omet l'index `"args"`.

`limit`

  Ce paramètre peut être utilisé pour limiter le nombre de trames dans la pile retournée. Par défaut (`limit`=`0`), la fonction retourne toutes les trames de la pile.

### Valeurs de retour

Retourne un tableau de tableaux associatifs. Les éléments de retour possibles sont les suivants :

Éléments possibles de retour de la fonction debug_backtrace()
Nom | Type | Description
--- | --- | ---
function | chaîne de caractères | Le nom de la fonction courante. Voir aussi __FUNCTION__.
line | entier | Le numéro de la ligne courante. Voir aussi __LINE__.
file | chaîne de caractères | Le nom du fichier courant. Voir aussi __FILE__.
class | chaîne de caractères | Le nom de la classe courante. Voir aussi __CLASS__.
object | objet | L'objet courant si `DEBUG_BACKTRACE_PROVIDE_OBJECT` est fourni.
type | chaîne de caractères | Le type d'appel courant. Si une méthode est appelée, "->" est retourné. Si une méthode statique est appelée, "::" est retourné. Si une fonction est appelée, rien ne sera retourné.
args | tableau | Si à l'intérieur d'une fonction, ceci liste des arguments. Si dans un fichier inclus, ceci liste des fichiers inclus. Sauf si `DEBUG_BACKTRACE_IGNORE_ARGS` est fourni.

### Exemples

Exemple #1 Exemple avec debug_backtrace()

    <?php
    // filename: /tmp/a.php

    function a_test($str)
    {
      echo "\nHi: $str";
      var_dump(debug_backtrace());
    }

    a_test('friend');
    ?>

    <?php
    // filename: /tmp/b.php
    include_once '/tmp/a.php';
    ?>

Résultat de l'exécution de /tmp/b.php :

    Hi: friend
    array(2) {
      [0]=>
        array(4) {
          ["file"] => string(10) "/tmp/a.php"
          ["line"] => int(10)
          ["function"] => string(6) "a_test"
          ["args"]=>
            array(1) {
              [0] => &string(6) "friend"
            }
        }
      [1]=>
        array(4) {
          ["file"] => string(10) "/tmp/b.php"
          ["line"] => int(2)
          ["args"] =>
            array(1) {
              [0] => string(10) "/tmp/a.php"
            }
          ["function"] => string(12) "include_once"
        }
    }

### Voir aussi

- trigger_error() - Déclenche une erreur utilisateur
- debug_print_backtrace() - Affiche la pile d'exécution PHP

# debug_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtrace — Affiche la pile d'exécution PHP

### Description

function debug_print_backtrace(int `$options` = 0, int `$limit` = 0): void

debug_print_backtrace() affiche la pile d'exécution de PHP. Elle affiche les appels aux fonctions, les fichiers inclus/requis par include/require ainsi que les appels à eval().

### Liste de paramètres

`options`

  Ce paramètre est un masque d'options suivantes :

  Options pour debug_print_backtrace()
  DEBUG_BACKTRACE_IGNORE_ARGS | Si l'on doit omettre l'index "args" et ainsi, tous les arguments de la méthode/fonction pour préserver la mémoire.

`limit`

  Ce paramètre peut être utilisé pour limiter le nombre de trames de la pile à afficher. Par défaut (`limit`=`0`), toutes les trames de la pile seront affichées.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec debug_print_backtrace()

    <?php
    // fichier include.php

    function a() {
        b();
    }

    function b() {
        c();
    }

    function c(){
        debug_print_backtrace();
    }

    a();

    ?>

    <?php
    // fichier test.php
    // C'est le fichier à exécuter

    include 'include.php';
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    #0  c() called at [/tmp/include.php:10]
    #1  b() called at [/tmp/include.php:6]
    #2  a() called at [/tmp/include.php:17]
    #3  include(/tmp/include.php) called at [/tmp/test.php:3]

### Voir aussi

- debug_backtrace() - Génère une trace de la pile d'appels

# error_clear_last

(PHP 7, PHP 8)

error_clear_last — Enlève l'erreur la plus récente

### Description

function error_clear_last(): void

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Efface l'erreur la plus récente, la rendant irrécupérable via error_get_last().

### Exemples

Exemple #1 Un exemple de error_clear_last()

    <?php
    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());

    @$a = $b;

    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    NULL
    NULL
    array(4) {
      ["type"]=>
      int(8)
      ["message"]=>
      string(21) "Undefined variable: b"
      ["file"]=>
      string(9) "%s"
      ["line"]=>
      int(6)
    }
    NULL

### Voir aussi

- Constantes d'erreurs

# error_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_last — Récupère la dernière erreur survenue

### Description

function error_get_last(): ?array

Récupère la dernière erreur survenue.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif décrivant la dernière erreur avec les clés "type", "message", "file" et "line". Si l'erreur a été causée par une fonction interne à PHP, le message commencera par le nom de cette fonction. Retourne `null` s'il n'y a actuellement aucune erreur.

### Exemples

Exemple #1 Exemple avec error_get_last()

    <?php
    echo $a;
    print_r(error_get_last());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [type] => 8
        [message] => Undefined variable: a
        [file] => C:\WWW\index.php
        [line] => 2
    )

### Voir aussi

- Constantes d'erreur
- Variable $php_errormsg
- error_clear_last() - Enlève l'erreur la plus récente
- Directive `display_errors`
- Directive `html_errors`
- Directive `xmlrpc_errors`

# error_log

(PHP 4, PHP 5, PHP 7, PHP 8)

error_log — Envoie un message d'erreur vers le gestionnaire d'erreurs défini

### Description

function error_log(
string `$message`,
int `$message_type` = 0,
?string `$destination` = `null`,
?string `$additional_headers` = `null`
): bool

Envoie un message d'erreur au journal d'événements du serveur web ou à un fichier.

### Liste de paramètres

`message`

  Le message d'erreur qui doit être stocké.

`message_type`

  Spécifie la destination du message d'erreur. Les types possibles de messages sont :

  Types de journalisation de error_log()
  0 | `message` est envoyé au journal d'événements système de PHP, en utilisant le mécanisme de journalisation du système d'exploitation ou un fichier, en fonction de la configuration de la directive error_log. C'est l'option par défaut.
  1 | `message` est envoyé par email à l'adresse `destination`. C'est le seul type qui utilise le quatrième paramètre `additional_headers`.
  2 | N'est plus une option.
  3 | `message` est ajouté au fichier `destination`. Aucune nouvelle ligne (retour chariot) n'est automatiquement ajoutée à la fin de la chaîne `message`.
  4 | `message` est envoyé directement au gestionnaire de journalisation SAPI.

`destination`

  La destination. Cela dépend du paramètre `message_type` décrit ci-dessus.

`additional_headers`

  Les en-têtes supplémentaires. Ils sont utilisés lorsque le paramètre `message_type` est défini à `1`. Ce type de message utilise la même fonction interne que la fonction mail().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient. Si `message_type` est zéro, alors cette fonction retourne toujours `true`, peu importe si l'erreur a pu être enregistrée dans le journal d'événements.

### Historique

Version | Description
--- | ---
8.0.0 | `destination` et `additional_headers` sont désormais nullables.

### Exemples

Exemple #1 Exemples avec error_log()

    <?php
    // Envoie une notification par le journal du serveur web,
    // si la connexion à la base de données est impossible.
    if (!Ora_Logon($username, $password)) {
      error_log("Base Oracle indisponible !", 0);
    }

    // Indiquer à l'administrateur, par email, qu'il n'y a plus de FOO
    if (!($foo = allocate_new_foo())) {
      error_log("Aya!, Il ne reste plus de FOO disponibles !", 1,
      "operateur@example.com");
    }

    // D'autres manières d'appeler error_log():
    error_log("Grosse bourde !", 3, "/var/tmp/mes-erreurs.log");
    ?>

### Notes

Avertissement

La fonction error_log() n'est pas sûre pour les données binaires. Le paramètre `message` sera tronqué par un caractère nul.

Astuce

Le paramètre `message` ne doit pas contenir de caractère nul. Il est à noter que le paramètre `message` peut être envoyé vers un fichier, un mail, syslog, etc. Il convient d'utiliser les fonctions appropriées de conversion/échappement, base64_encode(), rawurlencode() ou addslashes() avant d'appeler la fonction error_log().

# error_reporting

(PHP 4, PHP 5, PHP 7, PHP 8)

error_reporting — Fixe le niveau de rapport d'erreurs PHP

### Description

function error_reporting(?int `$error_level` = `null`): int

error_reporting() modifie la directive error_reporting pendant l'exécution du script. PHP possède plusieurs niveaux d'erreurs, utiliser cette fonction configure ce niveau pendant la durée (d'exécution) du script. Si le paramètre optionnel `error_level` n'est pas défini, error_reporting() retournera uniquement le niveau de rapport d'erreurs courant.

### Liste de paramètres

`error_level`

  Le nouveau niveau error_reporting. Il peut être un champ de bits ou une combinaison de constantes. L'utilisation des constantes est vivement recommandée pour assurer une compatibilité maximale avec les futures versions. Au fur et à mesure que de nouveaux niveaux d'erreurs sont créés, les valeurs évoluent, c'est pourquoi les anciennes valeurs n'ont plus forcément la même signification.

  Les constantes représentant les niveaux d'erreurs disponibles et la signification de ces niveaux d'erreurs est décrite dans le manuel sur les constantes prédéfinies.

### Valeurs de retour

Retourne le niveau d'error_reporting, avant qu'il ne soit changé en `error_level`.

> Note: L'opérateur de contrôle d'erreur `@` modifie le `error_level` pendant la gestion des erreurs.

### Historique

Version | Description
--- | ---
8.0.0 | `error_level` est désormais nullable.

### Exemples

Exemple #1 Exemple avec error_reporting()

    <?php

    // Désactiver le rapport d'erreurs
    error_reporting(0);

    // Rapporte les erreurs d'exécution de script
    error_reporting(E_ERROR | E_WARNING | E_PARSE);

    // Rapporter les E_NOTICE peut vous aider à améliorer vos scripts
    // (variables non initialisées, variables mal orthographiées ...)
    error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);

    // Rapporte toutes les erreurs à part les E_NOTICE
    // C'est la configuration par défaut de php.ini
    error_reporting(E_ALL & ~E_NOTICE);

    // Rapporte toutes les erreurs PHP
    error_reporting(E_ALL);

    // Rapporte toutes les erreurs PHP
    error_reporting(-1);

    // Même chose que error_reporting(E_ALL);
    ini_set('error_reporting', E_ALL);

    ?>

### Notes

Astuce

En passant la valeur `-1`, toutes les erreurs possibles seront affichées, même lors de l'ajout d'autres niveaux et constantes dans les futures versions de PHP. Ce comportement est équivalent à fournir la constante `E_ALL`.

### Voir aussi

- La directive display_errors
- La directive html_errors
- La directive xmlrpc_errors
- L'opérateur de contrôle d'erreur
- ini_set() - Modifie la valeur d'une option de configuration

# get_error_handler

(PHP 8 >= 8.5.0)

get_error_handler — Renvoie la fonction de gestion d'erreur définie par l'utilisateur

### Description

function get_error_handler(): ?callable

Renvoie la fonction de gestion d'erreur définie par l'utilisateur, si une a été définie.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la fonction de gestion d'erreur définie. Si le gestionnaire par défaut est utilisé, `null` est renvoyé.

Le gestionnaire retourné est la valeur callable exacte qui a été passée à set_error_handler() pour la définir.

### Exemples

Exemple #1 Exemple de get_error_handler()

    <?php

    $handler = function (int $errno, string $errstr, ?string $errfile, ?int $errline) {
         echo "Error: " . $errstr . "\n";
    };

    var_dump(get_error_handler()); // NULL

    set_error_handler($handler);

    var_dump(get_error_handler() === $handler); // bool(true)

    ?>

### Notes

Astuce

Avant PHP 8.5.0, cette fonctionnalité peut être fournie par le polyfill suivant :

    <?php
    if (!function_exists('get_error_handler')) {
        function noop_error_handler() {
        }
        function get_error_handler(): ?callable {
            $handler = set_error_handler('noop_error_handler');
            restore_error_handler();
            return $handler;
        }
    }
    ?>

### Voir aussi

- error_reporting() - Fixe le niveau de rapport d'erreurs PHP
- set_error_handler() - Spécifie une fonction utilisateur comme gestionnaire d'erreurs
- restore_error_handler() - Réactive l'ancienne fonction de gestion des erreurs
- trigger_error() - Déclenche une erreur utilisateur
- constantes de niveau d'erreur

# get_exception_handler

(PHP 8 >= 8.5.0)

get_exception_handler — Renvoie la fonction de gestion d'exception définie par l'utilisateur

### Description

function get_exception_handler(): ?callable

Renvoie la fonction de gestion d'exception définie par l'utilisateur, si une a été définie.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la fonction de gestion d'exception définie. Si aucune n'est définie, `null` est renvoyé.

Le gestionnaire retourné est la fonction de rappel exacte qui a été passée à set_exception_handler() pour la définir.

### Exemples

Exemple #1 Exemple de get_exception_handler()

    <?php

    $handler = function (Throwable $ex) {
         echo "Exception: " . $ex::class . ": " . $ex->getMessage() . "\n";
    };

    var_dump(get_exception_handler()); // NULL

    set_exception_handler($handler);

    var_dump(get_exception_handler() === $handler); // bool(true)

    ?>

### Notes

Astuce

Avant PHP 8.5.0, cette fonctionnalité pouvait être fournie par le polyfill suivant :

    <?php
    if (!function_exists('get_exception_handler')) {
        function noop_exception_handler() {
        }
        function get_exception_handler(): ?callable {
            $handler = set_exception_handler('noop_exception_handler');
            restore_exception_handler();
            return $handler;
        }
    }
    ?>

### Voir aussi

- set_exception_handler() - Définit une fonction utilisateur de gestion d'exceptions
- restore_exception_handler() - Réactive l'ancienne fonction de gestion d'exceptions
- restore_error_handler() - Réactive l'ancienne fonction de gestion des erreurs
- error_reporting() - Fixe le niveau de rapport d'erreurs PHP
- Exceptions

# restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handler — Réactive l'ancienne fonction de gestion des erreurs

### Description

function restore_error_handler(): true

Utilisée après avoir modifié la fonction de gestion des erreurs, grâce à set_error_handler(), restore_error_handler() permet de réutiliser l'ancienne version de gestion des erreurs (qui peut être la fonction PHP par défaut, ou une autre fonction utilisateur).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `true`.

### Exemples

Exemple #1 Exemple avec restore_error_handler()

Si unserialize() cause une erreur, alors le gestionnaire d'erreurs original est restauré.

    <?php
    function unserialize_handler($errno, $errstr)
    {
    echo "Valeur incorrectement sérialisée.\n";
    }

    $serialized = 'foo';
    set_error_handler('unserialize_handler');
    $original = unserialize($serialized);
    restore_error_handler();
    ?>

L'exemple ci-dessus va afficher :

    Valeur incorrectement sérialisée.

### Voir aussi

- error_reporting() - Fixe le niveau de rapport d'erreurs PHP
- set_error_handler() - Spécifie une fonction utilisateur comme gestionnaire d'erreurs
- get_error_handler() - Renvoie la fonction de gestion d'erreur définie par l'utilisateur
- restore_exception_handler() - Réactive l'ancienne fonction de gestion d'exceptions
- trigger_error() - Déclenche une erreur utilisateur

# restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handler — Réactive l'ancienne fonction de gestion d'exceptions

### Description

function restore_exception_handler(): true

restore_exception_handler() est utilisé, après le changement de la fonction de gestion d'exceptions avec la fonction set_exception_handler(), pour revenir à l'ancien gestionnaire d'exceptions (qui peut être la fonction interne ou une fonction définie par l'utilisateur).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `true`.

### Exemples

Exemple #1 Exemple avec restore_exception_handler()

    <?php
        function exception_handler_1(Exception $e)
        {
            echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
        }

        function exception_handler_2(Exception $e)
        {
            echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
        }

        set_exception_handler('exception_handler_1');
        set_exception_handler('exception_handler_2');

        restore_exception_handler();

        throw new Exception('Ceci utilise le premier gestionnaire d\'exception...');
    ?>

L'exemple ci-dessus va afficher :

    [exception_handler_1] Ceci utilise le premier gestionnaire d'exception...

### Voir aussi

- set_exception_handler() - Définit une fonction utilisateur de gestion d'exceptions
- get_exception_handler() - Renvoie la fonction de gestion d'exception définie par l'utilisateur
- set_error_handler() - Spécifie une fonction utilisateur comme gestionnaire d'erreurs
- restore_error_handler() - Réactive l'ancienne fonction de gestion des erreurs
- error_reporting() - Fixe le niveau de rapport d'erreurs PHP

# set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — Spécifie une fonction utilisateur comme gestionnaire d'erreurs

### Description

function set_error_handler(?callable `$callback`, int `$error_levels` = `E_ALL`): ?callable

set_error_handler() choisit la fonction utilisateur `callback` pour gérer les erreurs dans un script.

Cette fonction peut être utilisée pour définir des gestionnaires d'erreurs personnalisés pendant l'exécution, par exemple dans des applications qui ont besoin de nettoyer des fichiers/données lorsqu'une erreur critique se produit ou lorsqu'une erreur est déclenchée en réponse à certaines conditions (à l'aide de la fonction trigger_error()).

Il faut se rappeler que la fonction standard de traitement des erreurs de PHP est alors complètement ignorée pour les erreurs de types spécifiés par `error_levels` à moins que la fonction de rappel retourne `false`. Les paramètres de la fonction error_reporting() n'auront aucun effet et le gestionnaire d'erreurs sera appelé quoi qu'il arrive. Cependant, il est toujours possible de lire la valeur actuelle de error_reporting et de faire réagir la fonction de gestion des erreurs en conséquence.

Il est à noter que c'est la responsabilité du gestionnaire d'erreurs d'arrêter l'exécution du script si nécessaire en appelant la fonction exit(). Si la fonction du gestionnaire d'erreurs retourne, l'exécution du script se poursuivra avec l'instruction suivante après celle qui a causé l'erreur.

Les types d'erreur suivants ne peuvent pas être gérés avec cette fonction : `E_ERROR`, `E_PARSE`, `E_CORE_ERROR`, `E_CORE_WARNING`, `E_COMPILE_ERROR`, `E_COMPILE_WARNING` indépendamment d'où elles sont levées, ainsi que la plupart des `E_STRICT` du fichier dans lequel set_error_handler() est appelé.

Si une erreur survient avant que le script ne soit exécuté (par exemple un téléversement de fichier), le gestionnaire d'erreurs personnalisé ne pourra pas être appelé, car il n'est pas encore enregistré.

### Liste de paramètres

`callback`

  Si `null` est fournie le gestionnaire est réinitialisé à son statut par défaut. Sinon, le gestionnaire est une fonction de rappel avec la signature suivante :

  function handler(
  int `$errno`,
  string `$errstr`,
  string `$errfile` = ?,
  int `$errline` = ?,
  array `$errcontext` = ?
  ): bool
  `errno`
    Le premier paramètre `errno`, sera passé le niveau d'erreur, sous la forme d'un entier.
  `errstr`
    Le second paramètre `errstr`, sera passé le message d'erreur, sous forme de chaîne.
  `errfile`
    Si la fonction de rappel accepte un troisième paramètre, `errfile`, il sera passé le nom du fichier dans lequel l'erreur a été identifiée, sous forme de chaîne.
  `errline`
    Si la fonction de rappel accepte un quatrième paramètre, `errline`, il sera passé le numéro de ligne à laquelle l'erreur a été identifiée, sous la forme d'un entier.
  `errcontext`
    Si la fonction de rappel accepte un cinquième paramètre, `errcontext`, il sera passé comme un tableau qui pointe sur la table des symboles actifs à l'instant où l'erreur est survenue. En d'autres termes, `errcontext` contient un tableau avec toutes les variables qui existaient lorsque l'erreur a été déclenchée. Les gestionnaires d'erreurs utilisateur ne doivent pas modifier le contexte d'erreur.
    Avertissement

    Ce paramètre est OBSOLÈTE à partir de PHP 7.2.0, et SUPPRIMÉ à partir de PHP 8.0.0. Si la fonction définit ce paramètre sans valeur par défaut, une erreur de "too few arguments" sera levée lors de son appel.

  Si la fonction retourne `false`, alors le gestionnaire d'erreurs normal continue.

`error_levels`

  Sert de masque pour appeler la fonction `callback` de la même façon que l'option de configuration error_reporting contrôle les erreurs qui sont affichées. Sans le masque, `callback` sera appelé pour toutes les erreurs, quelle que soit la valeur de error_reporting.

### Valeurs de retour

Retourne le dernier gestionnaire d'erreurs (s'il existe) sous forme de callable. Si le gestionnaire d’erreurs interne est utilisé, `null` est retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `errcontext` a été supprimé, et ne sera plus passé aux fermetures utilisateur.
7.2.0 | `errcontext` est devenu obsolète. L'usage de ce paramètre émet une notice `E_DEPRECATED`.

### Exemples

Exemple #1 Gestionnaire d'erreurs avec set_error_handler() et trigger_error()

L'exemple ci-dessous illustre l'interception d'erreurs internes avec génération d'erreur et son exploitation dans une fonction utilisateur :

    <?php
    // Gestionnaire d'erreurs
    function myErrorHandler($errno, $errstr, $errfile, $errline)
    {
       if (!(error_reporting() & $errno)) {
            // Ce code d'erreur n'est pas inclus dans error_reporting(), donc il continue
            // jusqu'au gestionnaire d'erreur standard de PHP
            return false;
        }

        // $errstr doit peut-être être échappé :
        $errstr = htmlspecialchars($errstr);

        switch ($errno) {
        case E_USER_ERROR:
            echo "<b>Mon ERREUR</b> [$errno] $errstr<br />\n";
            echo "  Erreur fatale sur la ligne $errline dans le fichier $errfile";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Arrêt...<br />\n";
            exit(1);

        case E_USER_WARNING:
            echo "<b>Mon ALERTE</b> [$errno] $errstr<br />\n";
            break;

        case E_USER_NOTICE:
            echo "<b>Mon AVERTISSEMENT</b> [$errno] $errstr<br />\n";
            break;

        default:
            echo "Type d'erreur inconnu : [$errno] $errstr<br />\n";
            break;
        }

        /* Ne pas exécuter le gestionnaire interne de PHP */
        return true;
    }

    // Fonction pour tester la gestion d'erreur
    function scale_by_log($vect, $scale)
    {
        if (!is_numeric($scale) || $scale <= 0) {
            trigger_error("log(x) pour x <= 0 est indéfini, valeur utilisée : scale = $scale", E_USER_ERROR);
        }

        if (!is_array($vect)) {
            trigger_error("Type d'entrée incorrect, tableau de valeurs attendu", E_USER_WARNING);
            return null;
        }

        $temp = array();
        foreach($vect as $pos => $value) {
            if (!is_numeric($value)) {
                trigger_error("La valeur à la position $pos n'est pas un nombre, utilisation 0 (zéro)", E_USER_NOTICE);
                $value = 0;
            }
            $temp[$pos] = log($scale) * $value;
        }
        return $temp;
      }

    // Configuration du gestionnaire d'erreurs
    $old_error_handler = set_error_handler("myErrorHandler");

    // Génération de quelques erreurs. Commençons par créer un tableau
    echo "vector a\n";
    $a = array(2, 3, "foo", 5.5, 43.3, 21.11);
    print_r($a);

    // Générons maintenant un second tableau
    echo "----\nvector b - a notice (b = log(PI) * a)\n";
    /* La valeur à la position $pos n'est pas un nombre, utilisation 0 (zéro) */
    $b = scale_by_log($a, M_PI);
    print_r($b);

    // Ceci est un problème, nous avons utilisé une chaîne au lieu d'un tableau
    echo "----\nvector c - a warning\n";
    /* Type d'entrée incorrect, tableau de valeurs attendu */
    $c = scale_by_log("non un tableau", 2.3);
    var_dump($c); // NULL

    // Ceci est une erreur critique : le logarithme de zéro ou d'un nombre négatif est indéfini
    echo "----\nvector d - fatal error\n";
    /* log(x) pour x <= 0 est indéfini, valeur utilisée : scale = $scale" */
    $d = scale_by_log($a, -2.5);
    var_dump($d); // Jamais atteint
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    vector a
    Array
    (
        [0] => 2
        [1] => 3
        [2] => foo
        [3] => 5.5
        [4] => 43.3
        [5] => 21.11
    )
    ----
    vector b - a notice (b = log(PI) * a)
    <b>Mon AVERTISSEMENT</b> [1024] La valeur à la position 2 n'est pas un nombre, utilisation 0 (zéro)<br />
    Array
    (
        [0] => 2.2894597716988
        [1] => 3.4341896575482
        [2] => 0
        [3] => 6.2960143721717
        [4] => 49.566804057279
        [5] => 24.165247890281
    )
    ----
    vector c - a warning
    <b>Mon ALERTE</b> [512] Type d'entrée incorrect, tableau de valeurs attendu<br />
    NULL
    ----
    vector d - fatal error
    <b>Mon ERREUR</b> [256] log(x) pour x <= 0 est indéfini, valeur utilisée : scale = -2.5<br />
      Erreur fatale sur la ligne 36 dans le fichier trigger_error.php, PHP 5.2.1 (Linux)<br />
    Arrêt...<br />

### Voir aussi

- ErrorException
- error_reporting() - Fixe le niveau de rapport d'erreurs PHP
- restore_error_handler() - Réactive l'ancienne fonction de gestion des erreurs
- get_error_handler() - Renvoie la fonction de gestion d'erreur définie par l'utilisateur
- trigger_error() - Déclenche une erreur utilisateur
- Constantes de niveau d'erreur

# set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handler — Définit une fonction utilisateur de gestion d'exceptions

### Description

function set_exception_handler(?callable `$callback`): ?callable

set_exception_handler() définit le gestionnaire d'exceptions par défaut si une exception n'est pas attrapée dans un bloc try/catch. L'exécution sera stoppée après l'appel à la fonction `callback`.

### Liste de paramètres

`callback`

  La fonction à appeler quand une exception non attrapée se produit. Cette fonction de gestion doit accepter un paramètre, qui sera l'objet Throwable qui a été levé. Les classes Error et Exception implémentent l'interface Throwable. Ceci est la signature du gestionnaire :

  function handler(Throwable `$ex`): void

  `null` peut être passé à la place, pour ré-initialiser ce gestionnaire en son statut initial.

### Valeurs de retour

Retourne le gestionnaire précédemment défini ou `null` en cas d'erreur. Si aucun gestionnaire n'a été précédemment défini, `null` est également retourné.

### Exemples

Exemple #1 Exemple avec set_exception_handler()

    <?php
    function exception_handler(Throwable $exception) {
      echo "Exception non attrapée : " , $exception->getMessage(), "\n";
    }

    set_exception_handler('exception_handler');

    throw new Exception('Uncaught Exception');
    echo "Non exécuté\n";
    ?>

### Voir aussi

- get_exception_handler() - Renvoie la fonction de gestion d'exception définie par l'utilisateur
- restore_exception_handler() - Réactive l'ancienne fonction de gestion d'exceptions
- restore_error_handler() - Réactive l'ancienne fonction de gestion des erreurs
- error_reporting() - Fixe le niveau de rapport d'erreurs PHP
- Les exceptions

# trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — Déclenche une erreur utilisateur

### Description

function trigger_error(string `$message`, int `$error_level` = `E_USER_NOTICE`): true

trigger_error() est utilisée pour déclencher une erreur utilisateur. Elle peut aussi être utilisée en conjonction avec un gestionnaire d'erreurs interne, ou un gestionnaire d'erreurs utilisateur qui a été choisi comme gestionnaire d'erreurs avec set_error_handler().

trigger_error() est pratique lorsqu'il faut générer une réponse particulière lors de l'exécution.

### Liste de paramètres

`message`

  Le message d'erreur désigné pour cette erreur. Il est limité en longueur à 1024 octets. Tout caractère après les 1024 premiers octets sera ignoré.

`error_level`

  Le type d'erreur désigné pour cette erreur. Cela ne fonctionne qu'avec la famille de constantes `E_USER_*` et sera par défaut `E_USER_NOTICE`.

  Avertissement

  Passer `E_USER_ERROR` comme `error_level` est désormais obsolète. Lancez une Exception ou appelez exit() à la place.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Cette fonction lance une ValueError si le `error_level` n'est pas l'un des `E_USER_ERROR`, `E_USER_WARNING`, `E_USER_NOTICE`, `E_USER_DEPRECATED`.

### Historique

Version | Description
--- | ---
8.4.0 | Passer `E_USER_ERROR` comme `error_level` est désormais obsolète. Lancez une Exception ou appelez exit() à la place.
8.4.0 | La fonction a désormais un type de retour true au lieu de bool.
8.0.0 | La fonction lance désormais une ValueError si un `error_level` invalide est spécifié. Auparavant, elle retournait `false`.

### Exemples

Exemple #1 Exemple avec trigger_error()

Voir set_error_handler() pour un exemple plus conséquent.

    <?php
    $password = $_POST['password'] ?? '';
    if ($password === '') {
      trigger_error("Using an empty password is unsafe", E_USER_WARNING);
    }
    $hash = password_hash($password, PASSWORD_DEFAULT);
    ?>

### Notes

Avertissement

Les entités HTML contenues dans le paramètre `message` ne sont pas échappées. Il convient d'utiliser la fonction htmlentities() sur le message si l'erreur doit être affichée dans un navigateur.

### Voir aussi

- error_reporting() - Fixe le niveau de rapport d'erreurs PHP
- set_error_handler() - Spécifie une fonction utilisateur comme gestionnaire d'erreurs
- restore_error_handler() - Réactive l'ancienne fonction de gestion des erreurs
- Les constantes de niveau d'erreur
- L’attribut Deprecated

# user_error

(PHP 4, PHP 5, PHP 7, PHP 8)

user_error — Alias de trigger_error()

### Description

Cette fonction est un alias de : trigger_error().

## Sommaire

- debug_backtrace — Génère une trace de la pile d'appels
- debug_print_backtrace — Affiche la pile d'exécution PHP
- error_clear_last — Enlève l'erreur la plus récente
- error_get_last — Récupère la dernière erreur survenue
- error_log — Envoie un message d'erreur vers le gestionnaire d'erreurs défini
- error_reporting — Fixe le niveau de rapport d'erreurs PHP
- get_error_handler — Renvoie la fonction de gestion d'erreur définie par l'utilisateur
- get_exception_handler — Renvoie la fonction de gestion d'exception définie par l'utilisateur
- restore_error_handler — Réactive l'ancienne fonction de gestion des erreurs
- restore_exception_handler — Réactive l'ancienne fonction de gestion d'exceptions
- set_error_handler — Spécifie une fonction utilisateur comme gestionnaire d'erreurs
- set_exception_handler — Définit une fonction utilisateur de gestion d'exceptions
- trigger_error — Déclenche une erreur utilisateur
- user_error — Alias de trigger_error

- Installation/Configuration
  - Configuration à l'exécution
- Constantes pré-définies
- Exemples
- Fonctions sur la gestion des erreurs
  - debug_backtrace — Génère une trace de la pile d'appels
  - debug_print_backtrace — Affiche la pile d'exécution PHP
  - error_clear_last — Enlève l'erreur la plus récente
  - error_get_last — Récupère la dernière erreur survenue
  - error_log — Envoie un message d'erreur vers le gestionnaire d'erreurs défini
  - error_reporting — Fixe le niveau de rapport d'erreurs PHP
  - get_error_handler — Renvoie la fonction de gestion d'erreur définie par l'utilisateur
  - get_exception_handler — Renvoie la fonction de gestion d'exception définie par l'utilisateur
  - restore_error_handler — Réactive l'ancienne fonction de gestion des erreurs
  - restore_exception_handler — Réactive l'ancienne fonction de gestion d'exceptions
  - set_error_handler — Spécifie une fonction utilisateur comme gestionnaire d'erreurs
  - set_exception_handler — Définit une fonction utilisateur de gestion d'exceptions
  - trigger_error — Déclenche une erreur utilisateur
  - user_error — Alias de trigger_error

# Interface de fonction étrangère (Foreign Function Interface)

# Introduction

Cette extension permet de charger des bibliothèques partagées (.DLL ou .so), l'appel à des fonctions C et l'accès à des structures de données C à partir de PHP, sans avoir à connaître l'API d'extension Zend, et sans avoir à apprendre un troisième langage "intermédiaire". L'API publique est implémentée sous la forme d'une classe unique FFI avec plusieurs méthodes statiques (certaines d'entre elles peuvent être appelées dynamiquement), et des méthodes d'objet surchargées, qui effectuent l'interaction réelle avec les données C.

Attention

L'extension FFI est dangereuse, car elle permet de s'interfacer avec le système à un niveau très bas. Elle ne doit être utilisée que par des développeurs ayant une connaissance pratique du langage C et des API C utilisées. Pour minimiser les risques, l'utilisation de l'API FFI peut être restreinte avec la directive php.ini ffi.enable.

> Note: L'extension FFI ne rend pas obsolète l'API d'extension classique de PHP; elle est simplement fournie pour l'interfaçage ad-hoc avec des fonctions et des structures de données C.

Astuce

Actuellement, l'accès aux structures de données FFI est significativement (environ 2 fois) plus lent que l'accès aux tableaux et objets natifs de PHP. Par conséquent, il n'est pas utile d'utiliser l'extension FFI pour la vitesse; cependant, il peut être judicieux de l'utiliser pour réduire la mémoire.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

Cette extension nécessite que la » bibliothèque libffi soit installée.

## Installation

Pour activer l'extension FFI, PHP doit être configuré avec --with-ffi.

Les utilisateurs de Windows doivent inclure php_ffi.dll dans php.ini pour activer l'extension FFI.

## Configuration à l'exécution

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

FFI Options de configuration
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
ffi.enable | "preload" | `INI_SYSTEM` |
ffi.preload | "" | `INI_SYSTEM` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`ffi.enable` string
  Permet d'activer (`"true"`) ou de désactiver (`"false"`) l'utilisation de l'API FFI, ou de la restreindre uniquement à l'interface CLI SAPI et aux fichiers préchargés (`"preload"`). Les restrictions de l'API FFI n'affectent que la classe FFI, mais pas les fonctions surchargées des objets FFI\CData. Cela signifie qu'il est possible de créer certains objets FFI\CData dans des fichiers préchargés, puis de les utiliser directement dans des scripts PHP.
`ffi.preload` string
  Permet le préchargement des liaisons FFI au démarrage, ce qui n'est pas possible avec FFI::load() si opcache.preload_user est défini. Cette directive accepte une liste de noms de fichiers délimitée par `DIRECTORY_SEPARATOR`. Les liaisons préchargées sont accessibles en appelant FFI::scope().

# Exemples

## Sommaire

- Utilisation basique de FFI
- Fonctions de rappels
- Un exemple complet de PHP/FFI/preloading

## Utilisation basique de FFI

Avant de plonger dans les détails de l'API FFI, jetons un coup d'œil à quelques exemples démontrant la simplicité d'utilisation de l'API FFI pour les tâches courantes.

> Note: Certains de ces exemples requièrent libc.so.6 et ne fonctionneront donc pas sur les systèmes où cette bibliothèque n'est pas disponible.

Exemple #1 Appel d'une fonction à partir d'une bibliothèque partagée

    <?php
    // crée un objet FFI, en chargeant la libc et en exportant la fonction printf()
    $ffi = FFI::cdef(
        "int printf(const char *format, ...);", // Déclaration C régulière
        "libc.so.6");
    // appelle la fonction printf() de C
    $ffi->printf("Hello %s!\n", "world");
    ?>

L'exemple ci-dessus va afficher :

    Hello world!

> Note: Il est à noter que certaines fonctions C nécessitent des conventions d'appel spécifiques, par exemple `__fastcall`, `__stdcall` ou `,__vectorcall`.

Exemple #2 Appel d'une fonction, retournant une structure par l'intermédiaire d'un argument

    <?php
    // crée la liaison gettimeofday()
    $ffi = FFI::cdef("
        typedef unsigned int time_t;
        typedef unsigned int suseconds_t;

        struct timeval {
            time_t      tv_sec;
            suseconds_t tv_usec;
        };

        struct timezone {
            int tz_minuteswest;
            int tz_dsttime;
        };

        int gettimeofday(struct timeval *tv, struct timezone *tz);
    ", "libc.so.6");
    // crée les structures de données C
    $tv = $ffi->new("struct timeval");
    $tz = $ffi->new("struct timezone");
    // appelle la fonction gettimeofday() de C
    var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz)));
    // accède aux champs de la structure de données C
    var_dump($tv->tv_sec);
    // imprime toute la structure de données C
    var_dump($tz);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(0)
    int(1555946835)
    object(FFI\CData:struct timezone)#3 (2) {
      ["tz_minuteswest"]=>
      int(0)
      ["tz_dsttime"]=>
      int(0)
    }

Exemple #3 Accès aux variables C existantes

    <?php
    // crée un objet FFI, en chargeant la libc et en exportant la variable errno
    $ffi = FFI::cdef(
        "int errno;", // Déclaration C régulière
        "libc.so.6");
    // imprime la valeur errno de C
    var_dump($ffi->errno);
    ?>

L'exemple ci-dessus va afficher :

    int(0)

Exemple #4 Création et modification de variables C

    <?php
    // crée une nouvelle variable C de type int
    $x = FFI::new("int");
    var_dump($x->cdata);

    // affectation simple
    $x->cdata = 5;
    var_dump($x->cdata);

    // affectation composée
    $x->cdata += 2;
    var_dump($x->cdata);
    ?>

L'exemple ci-dessus va afficher :

    int(0)
    int(5)
    int(7)

Exemple #5 Travailler avec des tableaux C

    <?php
    // crée une structure de données en C
    $a = FFI::new("long[1024]");
    // modification de la structure comme avec un tableau PHP normal
    for ($i = 0; $i < count($a); $i++) {
        $a[$i] = $i;
    }
    var_dump($a[25]);
    $sum = 0;
    foreach ($a as $n) {
        $sum += $n;
    }
    var_dump($sum);
    var_dump(count($a));
    var_dump(FFI::sizeof($a));
    ?>

L'exemple ci-dessus va afficher :

    int(25)
    int(523776)
    int(1024)
    int(8192)

Exemple #6 Travailler avec des enums en C

    <?php
    $a = FFI::cdef('typedef enum _zend_ffi_symbol_kind {
        ZEND_FFI_SYM_TYPE,
        ZEND_FFI_SYM_CONST = 2,
        ZEND_FFI_SYM_VAR,
        ZEND_FFI_SYM_FUNC
    } zend_ffi_symbol_kind;
    ');
    var_dump($a->ZEND_FFI_SYM_TYPE);
    var_dump($a->ZEND_FFI_SYM_CONST);
    var_dump($a->ZEND_FFI_SYM_VAR);
    ?>

L'exemple ci-dessus va afficher :

    int(0)
    int(2)
    int(3)

## Fonctions de rappels

Il est possible d'assigner une fermeture PHP à une variable native de type pointeur de fonction ou de la passer comme argument de fonction :

Exemple #1 Assignation d'une Closure PHP à un pointeur de fonction C

    <?php
    $zend = FFI::cdef("
        typedef int (*zend_write_func_t)(const char *str, size_t str_length);
        extern zend_write_func_t zend_write;
    ");

    echo "Hello World 1!\n";

    $orig_zend_write = clone $zend->zend_write;
    $zend->zend_write = function($str, $len) {
        global $orig_zend_write;
        $orig_zend_write("{\n\t", 3);
        $ret = $orig_zend_write($str, $len);
        $orig_zend_write("}\n", 2);
        return $ret;
    };
    echo "Hello World 2!\n";
    $zend->zend_write = $orig_zend_write;
    echo "Hello World 3!\n";
    ?>

L'exemple ci-dessus va afficher :

    Hello World 1!
    {
            Hello World 2!
    }
    Hello World 3!

Bien que cela fonctionne, cette fonctionnalité n'est pas supportée par toutes les plateformes libffi, n'est pas efficace et entraîne des fuites de ressources à la fin de la requête.
Astuce

Il est donc recommandé de minimiser l'utilisation des fonctions de rappels PHP.

## Un exemple complet de PHP/FFI/preloading

php.ini

    ffi.enable=preload
    opcache.preload=preload.php

preload.php

    <?php
    FFI::load(__DIR__ . "/dummy.h");
    opcache_compile_file(__DIR__ . "/dummy.php");
    ?>

dummy.h

    #define FFI_SCOPE "DUMMY"
    #define FFI_LIB "libc.so.6"

    int printf(const char *format, ...);

dummy.php

    <?php
    final class Dummy {
        private static $ffi = null;
        function __construct() {
            if (is_null(self::$ffi)) {
                self::$ffi = FFI::scope("DUMMY");
            }
        }
        function printf($format, ...$args) {
           return (int) self::$ffi->printf($format, ...$args);
        }
    }
    ?>

test.php

    <?php
    $d = new Dummy();
    $d->printf("Hello %s!\n", "world");
    ?>

# Interface principale vers le code C et les données

(PHP 7 >= 7.4.0, PHP 8)

## Introduction

Les objets de cette classe sont créés par les méthodes de fabrique FFI::cdef(), FFI::load() ou FFI::scope(). Les variables C définies sont disponibles en tant que propriétés de l'instance FFI, et les fonctions C définies sont disponibles comme méthodes de l'instance FFI. Les types C déclarés peuvent être utilisés pour créer de nouvelles structures de données C en utilisant FFI::new() et FFI::type().

L'analyse des définitions FFI et le chargement des bibliothèques partagées peuvent prendre beaucoup de temps. Il n'est pas utile de le faire à chaque requête HTTP dans un environnement Web. Cependant, il est possible de précharger les définitions FFI et les bibliothèques au démarrage de PHP, et d'instancier les objets FFI lorsque c'est nécessaire. Les fichiers d'en-tête peuvent être étendus avec des définitions `FFI_SCOPE` spéciales (par exemple `#define FFI_SCOPE "foo"`; la portée par défaut est "C") et ensuite chargés par FFI::load() pendant le préchargement. Cela conduit à la création d'une liaison persistante, qui sera disponible pour toutes les requêtes suivantes par l'intermédiaire de FFI::scope(). Se reporter à l'exemple complet PHP/FFI/preloading pour plus de détails.

Il est possible de précharger plus d'un fichier d'en-tête C dans la même portée.

## Synopsis de la classe

final class FFI {
/* Constantes */
public const int __BIGGEST_ALIGNMENT__;
/* Méthodes */
public static function addr(FFI\CData `&$ptr`): FFI\CData
public static function alignof(FFI\CData|FFI\CType `&$ptr`): int
public static function arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType
public function cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData
public static function cdef(string `$code` = "", ?string `$lib` = `null`): FFI
public static function free(FFI\CData `&$ptr`): void
public static function isNull(FFI\CData `&$ptr`): bool
public static function load(string `$filename`): ?FFI
public static function memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int
public static function memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void
public static function memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void
public function new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData
public static function scope(string `$name`): FFI
public static function sizeof(FFI\CData|FFI\CType `&$ptr`): int
public static function string(FFI\CData `&$ptr`, ?int `$size` = `null`): string
public function type(string `$type`): ?FFI\CType
public static function typeof(FFI\CData `&$ptr`): FFI\CType
}

## Constantes pré-définies

`FFI::__BIGGEST_ALIGNMENT__`

# FFI::addr

(PHP 7 >= 7.4.0, PHP 8)

FFI::addr — Crée un pointeur non géré vers des données C

### Description

public static function FFI::addr(FFI\CData `&$ptr`): FFI\CData

Crée un pointeur non géré vers les données C représentées par l'élément FFI\CData. La source `ptr` doit survivre au pointeur résultant. Cette fonction est principalement utile pour transmettre des arguments à des fonctions C par le biais d'un pointeur.

### Liste de paramètres

`ptr`
  Le gestionnaire du pointeur vers une structure de données C.

### Valeurs de retour

Retourne l'objet FFI\CData fraîchement créé.

# FFI::alignof

(PHP 7 >= 7.4.0, PHP 8)

FFI::alignof — Récupère l'alignement

### Description

public static function FFI::alignof(FFI\CData|FFI\CType `&$ptr`): int

Récupère l'alignement de l'objet FFI\CData ou FFI\CType donné.

### Liste de paramètres

`ptr`
  Le gestionnaire de la donnée ou du type C.

### Valeurs de retour

Retourne l'alignement de l'objet FFI\CData ou FFI\CType donné.

# FFI::arrayType

(PHP 7 >= 7.4.0, PHP 8)

FFI::arrayType — Construit dynamiquement un nouveau type de tableau C

### Description

public static function FFI::arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType

Construit dynamiquement un nouveau type de tableau C avec des éléments de type défini par `type`, et des dimensions spécifiées par `dimensions`. Dans l'exemple suivant `$t1` et `$t2` sont des types de tableaux équivalents :

    <?php
    $t1 = FFI::type("int[2][3]");
    $t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
    ?>

### Liste de paramètres

`type`
  Une déclaration C valide comme string, ou une instance de FFI\CType qui a déjà été créée.
`dimensions`
  Les dimensions du type comme array.

### Valeurs de retour

Retourne l'objet FFI\CType fraîchement créé.

# FFI::cast

(PHP 7 >= 7.4.0, PHP 8)

FFI::cast — Effectue une conversion de type C

### Description

public function FFI::cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData

FFI::cast() crée un nouvel objet FFI\CData qui fait référence à la même structure de données C, mais qui est associée à un type différent. L'objet résultant ne possède pas les données C et la source `ptr` doit survivre au résultat. Le type C peut être spécifié en tant que string avec n'importe quelle déclaration de type C valide ou en tant qu'objet FFI\CType, créé auparavant. N'importe quel type déclaré pour l'instance est autorisé.

### Liste de paramètres

`type`
  Une déclaration C valide comme string, ou une instance de FFI\CType qui a déjà été créée.
`ptr`
  Le gestionnaire du pointeur d'une structure de données C.

### Valeurs de retour

Retourne l'objet FFI\CData fraîchement créé.

### Historique

Version | Description
--- | ---
8.3.0 | L'appel statique de FFI::cast() est désormais obsolète.

# FFI::cdef

(PHP 7 >= 7.4.0, PHP 8)

FFI::cdef — Crée un nouvel objet FFI

### Description

public static function FFI::cdef(string `$code` = "", ?string `$lib` = `null`): FFI

Crée un nouvel objet FFI.

### Liste de paramètres

`code`
  Une chaîne de caractères contenant une séquence de déclarations en langage C ordinaire (types, structures, fonctions, variables, etc). En fait, cette chaîne peut être copiée-collée à partir de fichiers d'en-tête C.

  > Note: Les directives du préprocesseur C ne sont pas supportées, c'est-à-dire `#include`, `#define` et les macros CPP ne fonctionnent pas.

`lib`
  Le nom d'un fichier de bibliothèque partagée, à charger et à lier avec les définitions.

  > Note: Si `lib` est omis ou `null`, les plates-formes supportant `RTLD_DEFAULT` tentent de rechercher les symboles déclarés dans `code` dans la portée globale. Les autres systèmes ne parviendront pas à résoudre ces symboles.

### Valeurs de retour

Retourne l'objet FFI fraîchement créé.

### Historique

Version | Description
--- | ---
8.3.0 | Les fonctions C retournant `void` renvoient un null PHP au lieu de FFI\CType::TYPE_VOID.
8.0.0 | `lib` est désormais nullable.

# FFI::free

(PHP 7 >= 7.4.0, PHP 8)

FFI::free — Libère une structure de données non gérée

### Description

public static function FFI::free(FFI\CData `&$ptr`): void

Libère manuellement une structure de données non gérée créée précédemment.

### Liste de paramètres

`ptr`
  Le gestionnaire du pointeur non géré d'une structure de données C.

### Valeurs de retour

Aucune valeur n'est retournée.

# FFI::isNull

(PHP 7 >= 7.4.0, PHP 8)

FFI::isNull — Vérifie si un objet FFI\CData est un pointeur null

### Description

public static function FFI::isNull(FFI\CData `&$ptr`): bool

Vérifie si un objet FFI\CData est un pointeur null.

### Liste de paramètres

`ptr`
  Le gestionnaire du pointeur vers une structure de données C.

### Valeurs de retour

Retourne si un objet FFI\CData est un pointeur null.

# FFI::load

(PHP 7 >= 7.4.0, PHP 8)

FFI::load — Charge les déclarations C à partir d'un fichier d'en-tête C

### Description

public static function FFI::load(string `$filename`): ?FFI

Charge les déclarations C à partir d'un fichier d'en-tête C. Il est possible de spécifier les bibliothèques partagées qui doivent être chargées, en utilisant des définitions spéciales `FFI_LIB` dans le fichier d'en-tête C chargé.

### Liste de paramètres

`filename`
  Le nom d'un fichier d'en-tête C. Les directives du préprocesseur C ne sont pas supportées, c'est-à-dire `#include`, `#define` et les macros CPP ne fonctionnent pas, sauf dans les cas particuliers énumérés ci-dessous. Le fichier d'en-tête devrait contenir une déclaration `#define` pour la variable `FFI_SCOPE`, par exemple : `#define FFI_SCOPE "MYLIB"`. Se reporter à l'introduction de la classe pour plus de détails. Le fichier d'en-tête peut contenir une déclaration `#define` pour la variable `FFI_LIB` pour spécifier la bibliothèque qu'elle expose. S'il s'agit d'une bibliothèque système, seul le nom du fichier est requis, par exemple : `#define FFI_LIB "libc.so.6"`. S'il s'agit d'une bibliothèque personnalisée, un chemin relatif est requis, par exemple : `#define FFI_LIB "./mylib.so"`.

### Valeurs de retour

Retourne l'objet FFI fraîchement créé, ou `null` en cas d'échec.

### Historique

Version | Description
--- | ---
8.3.0 | FFI::load() est désormais autorisé dans les scripts de préchargement lorsque l'utilisateur système actuel est le même que celui défini dans la directive de configuration `opcache.preload_user`.

### Voir aussi

- FFI::scope() - Instancie un objet FFI avec les déclarations C analysées lors du préchargement

# FFI::memcmp

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcmp — Comparaison des zones de mémoire

### Description

public static function FFI::memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int

Compare les `size` octets provenant des zones de mémoire `ptr1` et `ptr2`. `ptr1` et `ptr2` peuvent être des structures de données natives (FFI\CData) ou strings PHP.

### Liste de paramètres

`ptr1`
  Début d'une zone de mémoire.
`ptr2`
  Le début d'une autre zone de mémoire.
`size`
  Le nombre d'octets à comparer.

### Valeurs de retour

Retourne une valeur inférieure à `0` si le contenu de la zone de mémoire commençant à `ptr1` est considéré comme inférieur au contenu de la zone de mémoire commençant à `ptr2`, une valeur supérieure à `0` si le contenu de la première zone de mémoire est considéré comme supérieur à celui de la seconde, et `0` s'ils sont égaux.

# FFI::memcpy

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcpy — Copie d'une zone de mémoire dans une autre

### Description

public static function FFI::memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void

Copie `size` octets de la zone de mémoire `from` vers la zone de mémoire `to`.

### Liste de paramètres

`to`
  La zone de mémoire cible de la copie.
`from`
  La zone de mémoire source de la copie.
`size`
  Le nombre d'octets à copier.

### Valeurs de retour

Aucune valeur n'est retournée.

# FFI::memset

(PHP 7 >= 7.4.0, PHP 8)

FFI::memset — Remplit une zone de mémoire

### Description

public static function FFI::memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void

Remplit `size` octets de la zone de mémoire pointée par `ptr` avec l'octet donné `value`.

### Liste de paramètres

`ptr`
  Début de la zone de mémoire à remplir.
`value`
  L'octet à remplir.
`size`
  Le nombre d'octets à remplir.

### Valeurs de retour

Aucune valeur n'est retournée.

# FFI::new

(PHP 7 >= 7.4.0, PHP 8)

FFI::new — Crée une structure de données C

### Description

public function FFI::new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData

Crée une structure de données native du type C donné. N'importe quel type déclaré pour l'instance est autorisé.

### Liste de paramètres

`type`
  `type` est une déclaration C valide comme string, ou une instance de FFI\CType qui a déjà été créée.
`owned`
  Création de données gérées ou non gérées. Les données gérées vivent avec l'objet FFI\CData retourné, et sont libérées lorsque la dernière référence à cet objet est libérée par le comptage de références ordinaire de PHP ou le ramasse-miettes. Les données non gérées doivent être libérées en appelant FFI::free(), lorsqu'elles ne sont plus nécessaires.
`persistent`
  Allouer la structure de données C de manière permanente sur le tas du système (en utilisant malloc()), ou sur le tas des requêtes PHP (en utilisant emalloc()).

### Valeurs de retour

Retourne l'objet FFI\CData fraîchement créé, ou `null` en cas d'échec.

### Historique

Version | Description
--- | ---
8.3.0 | L'appel statique de FFI::new() est désormais obsolète.

# FFI::scope

(PHP 7 >= 7.4.0, PHP 8)

FFI::scope — Instancie un objet FFI avec les déclarations C analysées lors du préchargement

### Description

public static function FFI::scope(string `$name`): FFI

Instancie un objet FFI avec les déclarations C analysées lors du préchargement.

La méthode FFI::scope() peut être appelée sans risque plusieurs fois pour la même portée. Plusieurs références à la même portée peuvent être chargées en même temps.

### Liste de paramètres

`name`
  Le nom de la portée définie par une définition `FFI_SCOPE` spéciale.

### Valeurs de retour

Retourne l'objet FFI fraîchement créé.

### Voir aussi

- FFI::load() - Charge les déclarations C à partir d'un fichier d'en-tête C

# FFI::sizeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::sizeof — Récupère la taille des données ou des types C

### Description

public static function FFI::sizeof(FFI\CData|FFI\CType `&$ptr`): int

Retourne la taille de l'objet FFI\CData ou FFI\CType.

### Liste de paramètres

`ptr`
  Le gestionnaire de la donnée ou du type C.

### Valeurs de retour

Taille de la zone de mémoire pointée par `ptr`.

# FFI::string

(PHP 7 >= 7.4.0, PHP 8)

FFI::string — Crée une chaîne PHP à partir d'une zone de mémoire

### Description

public static function FFI::string(FFI\CData `&$ptr`, ?int `$size` = `null`): string

Crée une string PHP à partir de `size` octets de la zone mémoire pointée par `ptr`.

### Liste de paramètres

`ptr`
  Le début de la zone de mémoire à partir de laquelle créer une string.
`size`
  Le nombre d'octets à copier dans string. Si `size` est omis ou `null`, `ptr` doit être un pointeur vers une chaîne de `char` C à terminaison nulle.

### Valeurs de retour

La string PHP fraîchement créée.

### Historique

Version | Description
--- | ---
8.0.0 | `size` est désormais nullable ; auparavant, sa valeur par défaut était `0`.

# FFI::type

(PHP 7 >= 7.4.0, PHP 8)

FFI::type — Crée un objet FFI\CType à partir d'une déclaration C

### Description

public function FFI::type(string `$type`): ?FFI\CType

Cette fonction crée et retourne un objet FFI\CType pour la string donnée contenant une déclaration de type C. N'importe quel type déclaré pour l'instance est autorisé.

### Liste de paramètres

`type`
  Une déclaration C valide comme string.

### Valeurs de retour

Retourne l'objet FFI\CType fraîchement créé, ou `null` en cas d'échec.

### Historique

Version | Description
--- | ---
8.3.0 | L'appel statique de FFI::type() est désormais obsolète.

# FFI::typeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::typeof — Récupère le FFI\CType de FFI\CData

### Description

public static function FFI::typeof(FFI\CData `&$ptr`): FFI\CType

Récupère l'objet FFI\CType représentant le type de l'objet FFI\CData donné.

### Liste de paramètres

`ptr`
  Le gestionnaire du pointeur vers une structure de données C.

### Valeurs de retour

Retourne l'objet FFI\CType représentant le type de l'objet FFI\CData donné.

## Sommaire

- FFI::addr — Crée un pointeur non géré vers des données C
- FFI::alignof — Récupère l'alignement
- FFI::arrayType — Construit dynamiquement un nouveau type de tableau C
- FFI::cast — Effectue une conversion de type C
- FFI::cdef — Crée un nouvel objet FFI
- FFI::free — Libère une structure de données non gérée
- FFI::isNull — Vérifie si un objet FFI\CData est un pointeur null
- FFI::load — Charge les déclarations C à partir d'un fichier d'en-tête C
- FFI::memcmp — Comparaison des zones de mémoire
- FFI::memcpy — Copie d'une zone de mémoire dans une autre
- FFI::memset — Remplit une zone de mémoire
- FFI::new — Crée une structure de données C
- FFI::scope — Instancie un objet FFI avec les déclarations C analysées lors du préchargement
- FFI::sizeof — Récupère la taille des données ou des types C
- FFI::string — Crée une chaîne PHP à partir d'une zone de mémoire
- FFI::type — Crée un objet FFI\CType à partir d'une déclaration C
- FFI::typeof — Récupère le FFI\CType de FFI\CData

# Gestionnaire de données C

(PHP 7 >= 7.4.0, PHP 8)

## Introduction

Les objets FFI\CData peuvent être utilisés de différentes manières, comme des données PHP normales :

- Les données C de type scalaire peuvent être lues et assignées via la propriété $cdata, par exemple. `$x = FFI::new('int'); $x->cdata = 42;`
- Les champs de type struct et union peuvent être accédés comme des propriétés d'objets PHP ordinaires, par exemple `$cdata->field`
- Les éléments d'un tableau C sont accessibles comme les éléments d'un tableau PHP, par exemple. `$cdata[$offset]`
- Les tableaux C peuvent être itérés en utilisant des instructions `foreach`.
- Les tableaux C peuvent être utilisés comme arguments de count().
- Les pointeurs C peuvent être déréférencés comme des tableaux, par exemple `$cdata[0]`
- Les pointeurs C peuvent être comparés à l'aide d'opérateurs de comparaison ordinaires (`<`, `<=`, `==`, `!=`, `>=`, `>`).
- Les pointeurs C peuvent être incrémentés et décrémentés à l'aide des opérations ordinaires `+`/`-`/`++`/`--`, par exemple `$cdata += 5`
- Les pointeurs C peuvent être soustraits d'un autre à l'aide d'opérations ordinaires `-`.
- Les pointeurs C vers des fonctions peuvent être appelés comme une fermeture PHP classique, par exemple `$cdata()`
- Toute donnée C peut être dupliquée en utilisant l'opérateur clone, par exemple `$cdata2 = clone $cdata;`
- Toutes les données C peuvent être visualisées à l'aide de var_dump(), print_r(), etc.
- FFI\CData peut maintenant être attribué à des structures et des champs à partir de PHP 8.3.0.

> Note: Les limitations notables sont que les instances de FFI\CData ne supportent pas les fonctions isset(), empty() et unset(), et que les structs et unions C enveloppés n'implémentent pas Traversable.

## Synopsis de la classe

namespace FFI;
final class CData {
}

## Historique

Version | Description
--- | ---
8.3.0 | FFI\CData peut maintenant être attribué à des structures et des champs.

# Gestionnaire de type C

(PHP 7 >= 7.4.0, PHP 8)

## Introduction

## Synopsis de la classe

namespace FFI;
final class CType {
/* Constantes */
public const int TYPE_VOID;
public const int TYPE_FLOAT;
public const int TYPE_DOUBLE;
public const int TYPE_LONGDOUBLE;
public const int TYPE_UINT8;
public const int TYPE_SINT8;
public const int TYPE_UINT16;
public const int TYPE_SINT16;
public const int TYPE_UINT32;
public const int TYPE_SINT32;
public const int TYPE_UINT64;
public const int TYPE_SINT64;
public const int TYPE_ENUM;
public const int TYPE_BOOL;
public const int TYPE_CHAR;
public const int TYPE_POINTER;
public const int TYPE_FUNC;
public const int TYPE_ARRAY;
public const int TYPE_STRUCT;
public const int ATTR_CONST;
public const int ATTR_INCOMPLETE_TAG;
public const int ATTR_VARIADIC;
public const int ATTR_INCOMPLETE_ARRAY;
public const int ATTR_VLA;
public const int ATTR_UNION;
public const int ATTR_PACKED;
public const int ATTR_MS_STRUCT;
public const int ATTR_GCC_STRUCT;
public const int ABI_DEFAULT;
public const int ABI_CDECL;
public const int ABI_FASTCALL;
public const int ABI_THISCALL;
public const int ABI_STDCALL;
public const int ABI_PASCAL;
public const int ABI_REGISTER;
public const int ABI_MS;
public const int ABI_SYSV;
public const int ABI_VECTORCALL;
/* Méthodes */
public function getAlignment(): int
public function getArrayElementType(): FFI\CType
public function getArrayLength(): int
public function getAttributes(): int
public function getEnumKind(): int
public function getFuncABI(): int
public function getFuncParameterCount(): int
public function getFuncParameterType(int `$index`): FFI\CType
public function getFuncReturnType(): FFI\CType
public function getKind(): int
public function getName(): string
public function getPointerType(): FFI\CType
public function getSize(): int
public function getStructFieldNames(): array
public function getStructFieldOffset(string `$name`): int
public function getStructFieldType(string `$name`): FFI\CType
}

## Constantes pré-définies

`FFI\CType::TYPE_VOID`
`FFI\CType::TYPE_FLOAT`
`FFI\CType::TYPE_DOUBLE`
`FFI\CType::TYPE_LONGDOUBLE`
`FFI\CType::TYPE_UINT8`
`FFI\CType::TYPE_SINT8`
`FFI\CType::TYPE_UINT16`
`FFI\CType::TYPE_SINT16`
`FFI\CType::TYPE_UINT32`
`FFI\CType::TYPE_SINT32`
`FFI\CType::TYPE_UINT64`
`FFI\CType::TYPE_SINT64`
`FFI\CType::TYPE_ENUM`
`FFI\CType::TYPE_BOOL`
`FFI\CType::TYPE_CHAR`
`FFI\CType::TYPE_POINTER`
`FFI\CType::TYPE_FUNC`
`FFI\CType::TYPE_ARRAY`
`FFI\CType::TYPE_STRUCT`
`FFI\CType::ATTR_CONST`
`FFI\CType::ATTR_INCOMPLETE_TAG`
`FFI\CType::ATTR_VARIADIC`
`FFI\CType::ATTR_INCOMPLETE_ARRAY`
`FFI\CType::ATTR_VLA`
`FFI\CType::ATTR_UNION`
`FFI\CType::ATTR_PACKED`
`FFI\CType::ATTR_MS_STRUCT`
`FFI\CType::ATTR_GCC_STRUCT`
`FFI\CType::ABI_DEFAULT`
`FFI\CType::ABI_CDECL`
`FFI\CType::ABI_FASTCALL`
`FFI\CType::ABI_THISCALL`
`FFI\CType::ABI_STDCALL`
`FFI\CType::ABI_PASCAL`
`FFI\CType::ABI_REGISTER`
`FFI\CType::ABI_MS`
`FFI\CType::ABI_SYSV`
`FFI\CType::ABI_VECTORCALL`

# FFI\CType::getAlignment

(PHP 8 >= 8.1.0)

FFI\CType::getAlignment — Description

### Description

public function FFI\CType::getAlignment(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getArrayElementType

(PHP 8 >= 8.1.0)

FFI\CType::getArrayElementType — Description

### Description

public function FFI\CType::getArrayElementType(): FFI\CType

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getArrayLength

(PHP 8 >= 8.1.0)

FFI\CType::getArrayLength — Description

### Description

public function FFI\CType::getArrayLength(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getAttributes

(PHP 8 >= 8.1.0)

FFI\CType::getAttributes — Description

### Description

public function FFI\CType::getAttributes(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getEnumKind

(PHP 8 >= 8.1.0)

FFI\CType::getEnumKind — Description

### Description

public function FFI\CType::getEnumKind(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getFuncABI

(PHP 8 >= 8.1.0)

FFI\CType::getFuncABI — Description

### Description

public function FFI\CType::getFuncABI(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getFuncParameterCount

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterCount — Récupérer le nombre de paramètres d'un type de fonction

### Description

public function FFI\CType::getFuncParameterCount(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre de paramètres du type de fonction sous-jacent. Si le type sous-jacent n'est pas une fonction, une FFI\Exception est levée.

# FFI\CType::getFuncParameterType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterType — Récupérer le type d’un paramètre de fonction

### Description

public function FFI\CType::getFuncParameterType(int `$index`): FFI\CType

Retourne le type d’un paramètre pour le type de fonction sous-jacent.

### Liste de paramètres

`index`
  Index du paramètre de la fonction, basé sur zéro.

### Valeurs de retour

Retourne le type d’un paramètre pour le type de fonction sous-jacent. Si le type sous-jacent n’est pas une fonction, ou si l’index fourni est en dehors de la plage des paramètres de la fonction, une FFI\Exception est levée.

# FFI\CType::getFuncReturnType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncReturnType — Description

### Description

public function FFI\CType::getFuncReturnType(): FFI\CType

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getKind

(PHP 8 >= 8.1.0)

FFI\CType::getKind — Description

### Description

public function FFI\CType::getKind(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getName

(PHP 7 >= 7.4.0, PHP 8)

FFI\CType::getName — Description

### Description

public function FFI\CType::getName(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getPointerType

(PHP 8 >= 8.1.0)

FFI\CType::getPointerType — Description

### Description

public function FFI\CType::getPointerType(): FFI\CType

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getSize

(PHP 8 >= 8.1.0)

FFI\CType::getSize — Description

### Description

public function FFI\CType::getSize(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getStructFieldNames

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldNames — Description

### Description

public function FFI\CType::getStructFieldNames(): array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# FFI\CType::getStructFieldOffset

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldOffset — Description

### Description

public function FFI\CType::getStructFieldOffset(string `$name`): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`name`

### Valeurs de retour

# FFI\CType::getStructFieldType

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldType — Description

### Description

public function FFI\CType::getStructFieldType(string `$name`): FFI\CType

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`name`

### Valeurs de retour

## Sommaire

- FFI\CType::getAlignment — Description
- FFI\CType::getArrayElementType — Description
- FFI\CType::getArrayLength — Description
- FFI\CType::getAttributes — Description
- FFI\CType::getEnumKind — Description
- FFI\CType::getFuncABI — Description
- FFI\CType::getFuncParameterCount — Récupérer le nombre de paramètres d'un type de fonction
- FFI\CType::getFuncParameterType — Récupérer le type d’un paramètre de fonction
- FFI\CType::getFuncReturnType — Description
- FFI\CType::getKind — Description
- FFI\CType::getName — Description
- FFI\CType::getPointerType — Description
- FFI\CType::getSize — Description
- FFI\CType::getStructFieldNames — Description
- FFI\CType::getStructFieldOffset — Description
- FFI\CType::getStructFieldType — Description

# Exceptions FFI

(PHP 7 >= 7.4.0, PHP 8)

## Introduction

## Synopsis de la classe

namespace FFI;
class Exception extends Error {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Exceptions de l'analyseur syntaxique FFI

(PHP 7 >= 7.4.0, PHP 8)

## Introduction

## Synopsis de la classe

namespace FFI;
final class ParserException extends FFI\Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Exemples
  - Utilisation basique de FFI
  - Fonctions de rappels
  - Un exemple complet de PHP/FFI/preloading
- FFI — Interface principale vers le code C et les données
  - FFI::addr — Crée un pointeur non géré vers des données C
  - FFI::alignof — Récupère l'alignement
  - FFI::arrayType — Construit dynamiquement un nouveau type de tableau C
  - FFI::cast — Effectue une conversion de type C
  - FFI::cdef — Crée un nouvel objet FFI
  - FFI::free — Libère une structure de données non gérée
  - FFI::isNull — Vérifie si un objet FFI\CData est un pointeur null
  - FFI::load — Charge les déclarations C à partir d'un fichier d'en-tête C
  - FFI::memcmp — Comparaison des zones de mémoire
  - FFI::memcpy — Copie d'une zone de mémoire dans une autre
  - FFI::memset — Remplit une zone de mémoire
  - FFI::new — Crée une structure de données C
  - FFI::scope — Instancie un objet FFI avec les déclarations C analysées lors du préchargement
  - FFI::sizeof — Récupère la taille des données ou des types C
  - FFI::string — Crée une chaîne PHP à partir d'une zone de mémoire
  - FFI::type — Crée un objet FFI\CType à partir d'une déclaration C
  - FFI::typeof — Récupère le FFI\CType de FFI\CData
- FFI\CData — Gestionnaire de données C
- FFI\CType — Gestionnaire de type C
  - FFI\CType::getAlignment — Description
  - FFI\CType::getArrayElementType — Description
  - FFI\CType::getArrayLength — Description
  - FFI\CType::getAttributes — Description
  - FFI\CType::getEnumKind — Description
  - FFI\CType::getFuncABI — Description
  - FFI\CType::getFuncParameterCount — Récupérer le nombre de paramètres d'un type de fonction
  - FFI\CType::getFuncParameterType — Récupérer le type d’un paramètre de fonction
  - FFI\CType::getFuncReturnType — Description
  - FFI\CType::getKind — Description
  - FFI\CType::getName — Description
  - FFI\CType::getPointerType — Description
  - FFI\CType::getSize — Description
  - FFI\CType::getStructFieldNames — Description
  - FFI\CType::getStructFieldOffset — Description
  - FFI\CType::getStructFieldType — Description
- FFI\Exception — Exceptions FFI
- FFI\ParserException — Exceptions de l'analyseur syntaxique FFI

# OPcache

# Introduction

OPcache améliore les performances de PHP en stockant le bytecode des scripts pré-compilés en mémoire partagée, faisant ainsi qu'il n'est plus nécessaire à PHP de charger et d'analyser les scripts à chaque demande.

Cette extension est embarquée avec PHP 5.5.0 et suivants, et est » disponible via PECL pour les versions 5.2, 5.3 et 5.4 de PHP.

# Installation/Configuration

## Sommaire

- Installation
- Configuration à l'exécution

## Installation

OPcache peut seulement être compilé comme une extension partagée. Si on a désactivé la compilation des extensions par défaut avec --disable-all, il faut compiler PHP avec l'option --enable-opcache pour que OPcache soit disponible.

Une fois compilé, il est possible d'utiliser la directive de configuration zend_extension pour charger l'extension OPcache dans PHP. Ceci peut être réalisé avec `zend_extension=/full/path/to/opcache.so` sur les plateformes non-Windows, et `zend_extension=C:\path\to\php_opcache.dll` sur Windows.

> Note: Pour utiliser OPcache avec » Xdebug, il faut charger OPcache avant Xdebug.

### Configuration php.ini recommandée

La configuration suivante est généralement recommandée, vu qu'elle fournit un bon gain en termes de performance :

    opcache.memory_consumption=128
    opcache.interned_strings_buffer=8
    opcache.max_accelerated_files=4000
    opcache.revalidate_freq=60
    opcache.fast_shutdown=1 ; antérieur à PHP 7.2.0
    opcache.enable_cli=1

Il est possible que l'on veuille également désactiver opcache.save_comments et activer opcache.enable_file_override, cependant, à noter qu'il faut tester le code avant de l'utiliser en production, sachant qu'il peut casser des frameworks et des applications, en particulier dans le cas où les annotations des commentaires de documentations sont utilisées.

Sur Windows, opcache.file_cache_fallback devrait être activé, et opcache.file_cache devrait être définie à un dossier écrivable déjà existant.

Une liste complète de directives de configuration supportées par OPcache est également disponible.

## Configuration à l'exécution

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

Options de configuration d'OPcache
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
opcache.enable | 1 | `INI_ALL` |
opcache.enable_cli | 0 | `INI_SYSTEM` | Entre PHP 7.1.2 et 7.1.6 inclusivement, la valeur par défaut était de 1
opcache.memory_consumption | "128" | `INI_SYSTEM` |
opcache.interned_strings_buffer | "8" | `INI_SYSTEM` |
opcache.max_accelerated_files | "10000" | `INI_SYSTEM` |
opcache.max_wasted_percentage | "5" | `INI_SYSTEM` |
opcache.use_cwd | 1 | `INI_SYSTEM` |
opcache.validate_timestamps | 1 | `INI_ALL` |
opcache.revalidate_freq | "2" | `INI_ALL` |
opcache.revalidate_path | 0 | `INI_ALL` |
opcache.save_comments | 1 | `INI_SYSTEM` |
opcache.fast_shutdown | 0 | `INI_SYSTEM` | Supprimé en PHP 7.2.0.
opcache.enable_file_override | 0 | `INI_SYSTEM` |
opcache.optimization_level | "0x7FFEBFFF" | `INI_SYSTEM` | Modifié depuis 0x7FFFBFFF en PHP 7.3.0
opcache.inherited_hack | 1 | `INI_SYSTEM` | Supprimé en PHP 7.3.0
opcache.dups_fix | 0 | `INI_ALL` |
opcache.blacklist_filename | "" | `INI_SYSTEM` |
opcache.max_file_size | 0 | `INI_SYSTEM` |
opcache.consistency_checks | 0 | `INI_ALL` | Désactivé à partir de PHP 8.1.18 et 8.2.5. Supprimé à partir de PHP 8.3.0.
opcache.force_restart_timeout | "180" | `INI_SYSTEM` |
opcache.error_log | "" | `INI_SYSTEM` |
opcache.log_verbosity_level | 1 | `INI_SYSTEM` |
opcache.record_warnings | 0 | `INI_SYSTEM` | Disponible à partir de PHP 8.0.0.
opcache.preferred_memory_model | "" | `INI_SYSTEM` |
opcache.protect_memory | 0 | `INI_SYSTEM` |
opcache.mmap_base | `null` | `INI_SYSTEM` |
opcache.restrict_api | "" | `INI_SYSTEM` |
opcache.file_update_protection | "2" | `INI_ALL` |
opcache.huge_code_pages | 0 | `INI_SYSTEM` |
opcache.lockfile_path | "/tmp" | `INI_SYSTEM` |
opcache.opt_debug_level | 0 | `INI_SYSTEM` | Disponible à partir de PHP 7.1.0
opcache.file_cache | NULL | `INI_SYSTEM` |
opcache.file_cache_only | 0 | `INI_SYSTEM` |
opcache.file_cache_consistency_checks | 1 | `INI_SYSTEM` |
opcache.file_cache_fallback | 1 | `INI_SYSTEM` | Windows uniquement.
opcache.validate_permission | 0 | `INI_SYSTEM` | Disponible à partir de PHP 7.0.14
opcache.validate_root | 0 | `INI_SYSTEM` | Disponible à partir de PHP 7.0.14
opcache.preload | "" | `INI_SYSTEM` | Disponible à partir de PHP 7.4.0
opcache.preload_user | "" | `INI_SYSTEM` | Disponible à partir de PHP 7.4.0
opcache.cache_id | "" | `INI_SYSTEM` | Windows uniquement. Disponible à partir de PHP 7.4.0
opcache.jit | "disable" | `INI_ALL` | Disponible à partir de PHP 8.0.0. Avant PHP 8.4.0, la valeur par défaut était "tracing"
opcache.jit_buffer_size | 0 | `INI_SYSTEM` | Disponible à partir de PHP 8.0.0
opcache.jit_debug | 0 | `INI_ALL` | Disponible à partir de PHP 8.0.0
opcache.jit_bisect_limit | 0 | `INI_ALL` | Disponible à partir de PHP 8.0.0
opcache.jit_prof_threshold | "0.005" | `INI_ALL` | Disponible à partir de PHP 8.0.0
opcache.jit_max_root_traces | "1024" | `INI_SYSTEM` | Disponible à partir de PHP 8.0.0
opcache.jit_max_side_traces | "128" | `INI_SYSTEM` | Disponible à partir de PHP 8.0.0
opcache.jit_max_exit_counters | "8192" | `INI_SYSTEM` | Disponible à partir de PHP 8.0.0
opcache.jit_hot_loop | "61" | `INI_SYSTEM` | Disponible à partir de PHP 8.0.0. Avant PHP 8.5.0, la valeur par défaut était 64
opcache.jit_hot_func | "127" | `INI_SYSTEM` | Disponible à partir de PHP 8.0.0
opcache.jit_hot_return | "8" | `INI_SYSTEM` | Disponible à partir de PHP 8.0.0
opcache.jit_hot_side_exit | "8" | `INI_SYSTEM` | Disponible à partir de PHP 8.0.0
opcache.jit_blacklist_root_trace | "16" | `INI_ALL` | Disponible à partir de PHP 8.0.0
opcache.jit_blacklist_side_trace | "8" | `INI_ALL` | Disponible à partir de PHP 8.0.0
opcache.jit_max_loop_unrolls | "8" | `INI_ALL` | Disponible à partir de PHP 8.0.0
opcache.jit_max_recursive_calls | "2" | `INI_ALL` | Disponible à partir de PHP 8.0.0
opcache.jit_max_recursive_returns | "2" | `INI_ALL` | Disponible à partir de PHP 8.0.0
opcache.jit_max_polymorphic_calls | "2" | `INI_ALL` | Disponible à partir de PHP 8.0.0

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`opcache.enable` bool
  Active le cache d'opcode. Lorsqu'il est désactivé, le code n'est ni optimisé, ni mis en cache. Le paramétrage de `opcache.enable` ne peut être activé pendant l'exécution via la fonction ini_set(), il ne peut être que désactivé. Tenter de l'activer dans un script va générer une alerte.
`opcache.enable_cli` bool
  Active le cache d'opcode pour la version CLI de PHP.
`opcache.memory_consumption` int
  La taille de la mémoire partagée utilisée par OPcache, en mégaoctets. La valeur minimale permissible est `"8"`, qui est forcé si une valeur plus petite est définie.
`opcache.interned_strings_buffer` int
  La quantité de mémoire utilisée pour stocker des chaînes internes, en mégaoctets. La valeur maximale est de 32767 sur les architectures 64 bits, et de 4095 sur les architectures 32 bits.

  > Note: Avant PHP 8.4.0, la valeur maximale était de 4095 mégaoctets sur toutes les architectures.

`opcache.max_accelerated_files` int
  Le nombre maximal de clés (et donc, de scripts) dans la table de hachage d'OPcache. La valeur actuellement utilisée sera le premier nombre du jeu des nombres premiers `{ 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793 }` qui est plus grand ou égal que la valeur configurée. La valeur minimale est 200. La valeur maximale est 100000 dans PHP < 5.5.6, et 1000000 dans les versions ultérieures. Les valeurs hors de cet intervalle sont fixées à l'intervalle autorisé.
`opcache.max_wasted_percentage` int
  Le pourcentage maximum de mémoire gaspillée autorisée avant qu'un redémarrage ne soit programmé, s'il n'y a pas assez de mémoire disponible. La valeur maximale permissible est `"50"`, qui est forcé si une valeur plus grande est définie.
`opcache.use_cwd` bool
  Si activé, OPcache ajoute le dossier de travail courant à la clé du script, éliminant ainsi les collisions possibles entre les fichiers dont le nom de base est identique. Le fait de désactiver cette fonctionnalité améliore les performances, mais peut casser les applications existantes.
`opcache.validate_timestamps` bool

  Si activé, OPcache va vérifier les mises à jour des scripts toutes les opcache.revalidate_freq secondes. Lorsque cette directive est désactivée, il faut réinitialiser OPcache manuellement via la fonction opcache_reset(), la fonction opcache_invalidate() ou en redémarrant le serveur Web pour que les modifications du système de fichiers prennent effet.

  > Note: OPcache peut toujours valider l'horodatage d'un fichier lors de la compilation si les options opcache.file_update_protection ou opcache.max_file_size sont définies sur des valeurs non nulles.

`opcache.revalidate_freq` int
  La fréquence de vérification du timestamp du script afin de détecter les possibles mises à jour, en secondes. La valeur `0` fera qu'OPcache vérifiera les mises à jour à chaque requête. Cette directive de configuration est ignorée si opcache.validate_timestamps est désactivé.
`opcache.revalidate_path` bool
  Si désactivé, les fichiers en cache existant utilisant le même include_path seront réutilisés. Aussi, si un fichier avec le même nom est quelque part ailleurs dans le include_path, il ne sera pas trouvé.
`opcache.save_comments` bool
  Si désactivé, tous les commentaires de documentation seront supprimés du cache opcode afin de réduire la taille du code optimisé. La désactivation de cette directive peut casser des applications et des frameworks qui s'appuient sur l'analyse des commentaires pour les annotations, comme Doctrine, Zend Framework 2 et PHPUnit.
`opcache.fast_shutdown` bool
  Si activé, une séquence d'arrêt rapide sera utilisée, qui ne libère pas chaque bloc alloué, mais s'appuie sur le gestionnaire de mémoire Zend Engine pour désallouer le jeu entier des variables de requêtes, en masse. Cette directive a été supprimée dans PHP 7.2.0. Une variante de la séquence d'arrêt rapide a été intégrée dans PHP et sera automatiquement utilisée si possible.
`opcache.enable_file_override` bool
  Lorsqu'activé, le cache opcode sera vérifié pour savoir si un fichier a déjà été mis en cache lorsque les fonctions file_exists(), is_file() et is_readable() sont appelées. Ceci peut accroître les performances des applications qui vérifient l'existence et la lisibilité des scripts PHP, mais risque de retourner des données périmées si opcache.validate_timestamps est désactivé.
`opcache.optimization_level` int
  Un masque de bits qui contrôle quelles passes d'optimisation sont exécutées. La valeur par défaut est `0x7FFEBFFF`, qui active toutes les optimisations sûres. Désactiver des optimisations ou activer des optimisations non sûres est surtout utile pour déboguer/développer l'optimiseur. Chaque bit dans le masque de bits active une passe d'optimisation spécifique :

  Masque de bits des passes d'optimisation
  Bit | Nom de la passe | Description | Défaut
  --- | --- | --- | ---
  0 | PASS_1 | Optimisations peephole simples | Activé
  1 | PASS_2 | Inutilisé (a été fusionné dans PASS_1) | Activé
  2 | PASS_3 | Optimisation de saut simple | Activé
  3 | PASS_4 | Optimisation des appels | Activé
  4 | PASS_5 | Optimisation basée sur le graphe de flux de contrôle | Activé
  5 | PASS_6 | Optimisation basée sur l'analyse de flux de données | Activé
  6 | PASS_7 | Indique si le graphe d'appels doit être utilisé pour les optimisations SSA | Activé
  7 | PASS_8 | Propagation conditionnelle de constantes creuses | Activé
  8 | PASS_9 | Optimisation des variables temporaires | Activé
  9 | PASS_10 | Suppression des opcodes NOP | Activé
  10 | PASS_11 | Compactage des littéraux | Activé
  11 | PASS_12 | Pré-calcul de la taille de la pile d'appels | Activé
  12 | PASS_13 | Suppression des variables inutilisées | Activé
  13 | PASS_14 | Élimination du code mort | Activé
  14 | PASS_15 | Collecte et substitution des déclarations de constantes (non sûr) | Désactivé
  15 | PASS_16 | Inlining de fonctions triviales (partie de l'optimisation des appels) | Activé
  16 | (Drapeau) | Ignorer la possibilité de surcharge d'opérateur (non sûr) | Désactivé

  > Note: Optimisations sûres vs non sûres
  > Les optimisations sûres (activées par défaut) préservent le comportement exact du code PHP tout en améliorant les performances. Elles incluent l'élimination du code mort, le repliement de constantes et l'optimisation des sauts. Les optimisations non sûres (désactivées par défaut) peuvent altérer le comportement dans des cas particuliers :

  > - Bit 14 : Collecte des constantes. Les constantes sont substituées à la compilation, ignorant l'ordre de déclaration à l'exécution :

  >       <?php
  >       echo getA();         // Affiche : "hello" au lieu de lancer une Error
  >       const A = "hello";
  >       function getA() { return A; }

  > - Bit 16 : Ignorer la surcharge d'opérateur. Non sûr lors de l'utilisation de classes avec `do_operation` (par exemple GMP, BCMath) dans des opérations arithmétiques. Avec des déclarations de type, l'optimiseur peut appliquer les mêmes optimisations en toute sécurité.

`opcache.inherited_hack` bool
  Cette directive de configuration est ignorée.
`opcache.dups_fix` bool
  Ce hack ne doit être activé que comme solution de contournement des erreurs "Cannot redeclare class".
`opcache.blacklist_filename` string
  L'endroit de stockage du fichier gérant la liste noire OPcache. Un fichier de liste noire est un fichier texte contenant des noms de fichiers qui ne doivent pas être accélérés ; un par ligne. Les jokers sont autorisés, et les préfixes peuvent également être fournis. Les lignes commençant par un point-virgule sont vues comme des commentaires et seront donc ignorées. Un fichier de liste noire simple ressemble à ceci :

      ; Correspond à un fichier spécifique.
      /var/www/broken.php
      ; Un préfixe qui correspond à tous les fichiers qui commencent par x.
      /var/www/x
      ; Une correspondance avec un joker.
      /var/www/*-broken.php

`opcache.max_file_size` int
  La taille maximale du fichier pouvant être mis en cache, en octets. Si vaut `0`, tous les fichiers pourront être mis en cache.
`opcache.consistency_checks` int
  Si la valeur est différente de zéro, OPcache va vérifier la somme de contrôle du cache toutes les N requêtes, où N est la valeur de cette directive de configuration. Ceci ne doit être activé que lors du débogage, sachant qu'il impacte fortement les performances.

  > Note: Désactivé à partir de PHP 8.1.18 et 8.2.5. Supprimé à partir de PHP 8.3.0.

`opcache.force_restart_timeout` int
  La durée à attendre pour le début d'un redémarrage programmé, si le cache n'est pas activé, en secondes. Si ce délai d'attente est atteint, alors OPcache imagine que quelque chose se passe mal, et va tuer les processus gérant les verrous sur le cache pour permettre un redémarrage. Si opcache.log_verbosity_level vaut 2 ou plus, un avertissement sera enregistré dans le journal d'événements des erreurs lorsque ce comportement survient. Cette directive n'est pas supportée sur Windows.
`opcache.error_log` string
  Le log d'erreurs pour les erreurs OPcache. Une chaîne vide sera vue comme `stderr`, et les erreurs seront envoyées vers la sortie d'erreurs standard (qui sera le log des erreurs du serveur Web dans la plupart des cas).
`opcache.log_verbosity_level` int
  Le niveau de verbosité des logs. Par défaut, seules les erreurs fatales (niveau 0) et les erreurs (niveau 1) seront enregistrées. Les autres niveaux disponibles sont les alertes (niveau 2), les messages d'information (niveau 3), et les messages de débogage (niveau 4).
`opcache.record_warnings` bool
  Si cette option est activée, OPcache enregistrera les avertissements de compilation et les rejouera lors du prochain include, même s'il est servi depuis le cache.
`opcache.preferred_memory_model` string
  Le modèle de mémoire préféré pour OPcache, à utiliser. Si laissé vide, OPcache va choisir le modèle le plus approprié, ce qui est la meilleure façon de faire dans la plupart des cas. Les valeurs possibles sont `mmap`, `shm`, `posix` et `win32`.
`opcache.protect_memory` bool
  Protège la mémoire partagée des écritures inattendues pendant l'exécution des scripts. Ceci est utile uniquement pour du débogage interne.
`opcache.mmap_base` string
  La base utilisée pour les segments de mémoire partagée sous Windows. Tous les processus PHP doivent lier la mémoire partagée dans le même espace d'adresse. L'utilisation de cette directive permet de corriger les erreurs "Unable to reattach to base address".
`opcache.restrict_api` string
  Autorise l'appel aux fonctions de l'API d'OPcache uniquement depuis des scripts PHP dont le chemin commence par une chaîne spécifique. La valeur par défaut, "", signifie "aucune restriction".
`opcache.file_update_protection` string
  Empêche la mise en cache des fichiers datant moins que ce nombre de secondes. Ceci protège de la mise en cache des fichiers incomplètement mis à jour. Si toutes les mises à jour de fichiers sont atomiques, les performances peuvent être augmentées en le définissant à `0`. Cela permettra de mettre en cache les fichiers immédiatement.
`opcache.huge_code_pages` bool
  Active ou désactive la copie de code PHP (segment de texte) dans des HUGE PAGES. Ceci devrait améliorer les performances, mais nécessite une configuration appropriée du système d'exploitation. Disponible sur Linux à partir de PHP 7.0.0, et sur FreeBSD à partir de PHP 7.4.0.
`opcache.lockfile_path` string
  Chemin absolu utilisé pour enregistrer les lockfiles partagés (pour *nix uniquement)
`opcache.opt_debug_level` string
  Produit un vidage opcode pour déboguer les différentes étapes d'optimisation. 0x10000 affichera les opcodes tels que le compilateur les produit avant qu'aucune optimisation ne se produise alors que 0x20000 affichera les codes optimisés.
`opcache.file_cache` string
  Active et définit le répertoire de cache de second niveau. Ceci devrait améliorer les performances quand la mémoire SHM est pleine, au redémarrage du serveur ou réinitialisation de SHM. La valeur par défaut "" désactive la mise en cache basée sur les fichiers.
`opcache.file_cache_only` bool
  Active ou désactive la mise en cache de l'opcode dans la mémoire partagée.

  > Note: Avant PHP 8.1.0, désactiver cette directive avec un fichier de cache déjà rempli nécessite le vidage manuel du cache.

`opcache.file_cache_consistency_checks` bool
  Active ou désactive la validation de la somme de contrôle lorsque le script est chargé à partir du cache de fichiers.
`opcache.file_cache_fallback` bool
  Implique opcache.file_cache_only=1 pour un certain processus qui a échoué à se rattacher à la mémoire partagée (pour Windows uniquement). Le cache de fichiers activé explicitement est requis.
  Attention

  Désactiver cette option de configuration peut empêcher les processus de démarrer, et est donc découragé.

`opcache.validate_permission` bool
  Valide les permissions des fichiers mises en cache par rapport à l'utilisateur actuel.
`opcache.validate_root` bool
  Empêche la collision de noms dans les environnements `chroot`és. Ceci devrait être activé dans tous les environnements `chroot`és pour empêcher l'accès aux fichiers en-dehors du chroot.
`opcache.preload` string
  Spécifie un script PHP qui sera compilé et exécuté lors du démarrage du serveur, et qui peut précharger d'autres fichiers, soit grâce à include ou en utilisant la fonction opcache_compile_file(). Toutes les entités (par exemple fonctions et classes) définies dans ces fichiers seront disponibles aux requêtes prêtes à l'emploi, jusqu'à ce que le serveur soit éteint.

  > Note: Le préchargement n'est pas supporté sur Windows.

`opcache.preload_user` string
  Permet au préchargement d'être exécuté en tant qu'utilisateur système spécifié. Ceci est utile pour les serveurs qui démarrent en tant que root avant de passer à un utilisateur système non privilégié. Le préchargement en tant que root n'est pas autorisé par défaut pour des raisons de sécurité, sauf si cette directive est explicitement définie sur `root`. À partir de PHP 8.3.0, cette directive n'a plus besoin d'être définie afin d'autoriser le préchargement lors de l'exécution en tant que root avec CLI SAPI ou phpdbg SAPI.
`opcache.cache_id` string

  Sur Windows, tous les processus exécutant le même PHP SAPI sous le même compte utilisateur ayant le même ID de cache partagent une instance unique d'OPcache. La valeur de l'ID de cache peut être choisie librement.

  Astuce

  Pour IIS, des pools d'applications différentes peuvent avoir leur propre instance OPcache en utilisant la variable d'environnement APP_POOL_ID comme `opcache.cache_id`.

`opcache.jit` string|int
  Pour un usage typique, cette option accepte une des quatre valeurs de chaîne suivantes :
  - `disable`: Désactivé complètement, ne peut pas être activé lors du runtime.
  - `off`: Désactivé, mais peut être activé lors du runtime.
  - `tracing`/`on`: Utilise le tracing JIT. Activé par défaut et recommandé pour la plupart des utilisateurs.
  - `function`: Utilise le function JIT.

  Pour un usage avancé, cette option accepte un entier à 4 chiffres `CRTO`, où les chiffres signifient :

  `C` (Drapeaux d'optimisation spécifiques au CPU)
    - `0`: Désactive les optimisations spécifiques au CPU.
    - `1`: Active l'usage d'AVX, si le CPU le supporte.
  `R` (allocation de registre)
    - `0`: N'accomplit aucune allocation de registres
    - `1`: Accomplit des allocations de registres au niveau d'un bloc.
    - `2`: Accomplit des allocations de registres globales.
  `T` (trigger/déclencheur)
    - `0`: Compile toutes les fonctions lors du chargement du script.
    - `1`: Compile les fonctions lors de leur première exécution.
    - `2`: Profile les fonctions lors de la première requête et compile les fonctions les plus chaudes juste après.
    - `3`: Profile à la volée et compile les fonctions chaudes.
    - `4`: Actuellement inutilisé.
    - `5`: Utilise le tracing JIT. Profile à la volée et compile les traces pour les segments de code chaud.
  `O` (niveau d'optimisation)
    - `0`: Pas de JIT.
    - `1`: JIT minimal (appelle les handlers standard de la VM).
    - `2`: Inline les handlers de la VM.
    - `3`: Utilise l'inférence de type.
    - `4`: Utilise un graphe d'appel.
    - `5`: Optimise le script entier.
  Le mode `"tracing"` correspond à `CRTO = 1254`, le mode `"function"` correspond à `CRTO = 1205`.
`opcache.jit_buffer_size` int
  La quantité de mémoire partagée réservée pour du code compilé JIT. Une valeur de zéro désactive le JIT. Lorsqu'un entier est utilisé, sa valeur est mesurée en octets. Vous pouvez également utiliser la notation sténographique comme décrit dans cette entrée de la FAQ..
`opcache.jit_debug` int
  Un masque de bits spécifiant quelle sortie de débogage de JIT activer Pour les valeurs possibles, consulter » zend_jit.h (voir les définitions de macro commençant par `ZEND_JIT_DEBUG`).
`opcache.jit_bisect_limit` int
  Option de débogage qui désactive la compilation JIT après la compilation d'un certain nombre de fonctions. Ceci peut être utile pour bissecter la source d'une mauvaise compilation JIT. Remarque : cette option ne fonctionne que lorsque le déclencheur JIT est défini à 0 (compilation au chargement du script) ou 1 (compilation à la première exécution), par exemple, `opcache.jit=1215`. Voir plus dans l'option opcache.jit.
`opcache.jit_prof_threshold` float
  Lors de l'utilisation du mode de déclencheur "profile les fonctions lors de la première requête", cette limite détermine si une fonction est considérée chaude. Le nombre d'appels à la fonction divisé par le nombre d'appels à toutes les fonctions doit être supérieur à cette limite. Par exemple, une limite de 0.005 signifie qu'une fonction qui correspond à plus de 0.5% de tous les appels sera compilée JIT.
`opcache.jit_max_root_traces` int
  Nombre maximal de traces racines (root traces). La trace racine est un flux d'exécution prenant d'abord un chemin à travers le code, qui est une unité de la compilation JIT. JIT ne compilera pas de nouveau code s'il atteint cette limite.
`opcache.jit_max_side_traces` int
  Nombre maximal de traces adjacentes (side traces) qu'une trace racine peut avoir. La trace adjacente est un autre flux d'exécution qui ne suit pas le chemin de la trace racine compilée. Les traces adjacentes appartenant à la même trace racine ne seront pas compilées si elles atteignent cette limite.
`opcache.jit_max_exit_counters` int
  Nombre maximal de compteurs de sortie de trace adjacente. Ceci limite le nombre total de traces adjacentes qu'il peut y avoir, à travers toutes les traces racines.
`opcache.jit_hot_loop` int
  Après combien d'itérations une boucle est considérée chaude. L'intervalle de valeurs valides est `[0,255]` ; pour tout paramètre hors de cette plage, par exemple -1 ou 256, la valeur par défaut sera utilisée à la place. Spécialement, une valeur nulle désactivera le JIT pour tracer et compiler toutes les boucles.

  > Note: Il est recommandé de définir ce paramètre comme un nombre premier, afin d'éviter qu'il ne soit un multiple du nombre d'itérations des boucles.

`opcache.jit_hot_func` int
  Après combien d'appels une fonction est considérée chaude. La plage de valeurs valides est `[0,255]` ; pour tout paramètre hors de cette plage, par exemple -1 ou 256, la valeur par défaut sera utilisée à la place. Spécialement, une valeur nulle désactivera le JIT pour tracer et compiler toutes les fonctions.
`opcache.jit_hot_return` int
  Après combien de retours un retour est considéré chaud. La plage de valeurs valides est `[0,255]` ; pour tout paramètre hors de cette plage, par exemple -1 ou 256, la valeur par défaut sera utilisée à la place. Spécialement, une valeur nulle désactivera le JIT pour tracer et compiler tous les retours.
`opcache.jit_hot_side_exit` int
  Après combien de sorties une sortie adjacente est considérée chaude. La plage de valeurs valides est `[0,255]` ; pour tout paramètre hors de cette plage, par exemple -1 ou 256, la valeur par défaut sera utilisée à la place. Spécialement, une valeur nulle désactivera le JIT pour tracer et compiler toutes les sorties latérales.
`opcache.jit_blacklist_root_trace` int
  Nombre maximal de tentatives de compilation d'une trace racine avant que celle-ci ne soit exclue.
`opcache.jit_blacklist_side_trace` int
  Nombre maximal de tentatives de compilation d'une trace adjacente avant que celle-ci ne soit exclue.
`opcache.jit_max_loop_unrolls` int
  Nombre maximal de tentatives pour dérouler une boucle dans une trace adjacente, tentant d'atteindre la trace racine et de fermer la boucle extérieure.
`opcache.jit_max_recursive_calls` int
  Nombre maximal d'appels récursifs déroulés dans une boucle.
`opcache.jit_max_recursive_returns` int
  Nombre maximal de retours récursifs déroulés dans une boucle.
`opcache.jit_max_polymorphic_calls` int
  Nombre maximal de tentatives pour inliner un appel polymorphe (dynamique ou méthode). Les appels au-dessus de cette limite sont traités comme mégamorphes et ne sont pas inlinés.

# Preloading

À partir de PHP 7.4.0, PHP peut être configuré pour précharger des scripts dans l'opcache lorsque le moteur démarre. Toutes les fonctions, classes, interfaces ou traits (mais pas les constantes) de ces fichiers deviendront alors disponibles globalement pour toutes les requêtes sans avoir besoin d'être explicitement incluses. Cela échange la commodité et les performances (car le code est toujours disponible) contre l'utilisation de la mémoire de base. Cela nécessite également de redémarrer le processus PHP pour effacer les scripts préchargés, ce qui signifie que cette fonctionnalité n'est pratique qu'en production, pas dans un environnement de développement.

Il est à noter que le compromis optimal entre les performances et la mémoire peut varier en fonction de l'application. "Tout précharger" peut être la stratégie la plus simple, mais pas nécessairement la meilleure. De plus, le préchargement n'est utile que lorsqu'il y a un processus persistant d'une requête à une autre. Cela signifie que bien que cela puisse fonctionner dans un script CLI si l'opcache est activé, c'est généralement inutile. L'exception est lors de l'utilisation du préchargement sur les bibliothèques FFI.

> Note: Le préchargement n'est pas supporté sur Windows.

La configuration du préchargement implique deux étapes, et nécessite que l'opcache soit activé. Tout d'abord, définir la valeur opcache.preload dans php.ini :

    opcache.preload=preload.php

preload.php est un fichier arbitraire qui sera exécuté une fois au démarrage du serveur (PHP-FPM, mod_php, etc.) et chargera du code en mémoire persistante. Dans les serveurs qui démarrent en tant que root avant de passer à un utilisateur système non privilégié, ou si PHP est exécuté en tant que root (non recommandé), la valeur opcache.preload_user peut spécifier l'utilisateur système pour exécuter le préchargement. L'exécution du préchargement en tant que root n'est pas autorisée par défaut. Définir `opcache.preload_user=root` pour l'autoriser explicitement.

Dans le script preload.php, tout fichier référencé par include, include_once, require, require_once, ou opcache_compile_file() va être analysé et stocké dans la mémoire persistante. Dans l'exemple suivant, tous les fichiers .php du répertoire src seront préchargés, sauf s'ils sont un fichier `Test`.

    <?php
    $directory = new RecursiveDirectoryIterator(__DIR__ . '/src');
    $fullTree = new RecursiveIteratorIterator($directory);
    $phpFiles = new RegexIterator($fullTree, '/.+((?<!Test)+\.php$)/i', RecursiveRegexIterator::GET_MATCH);

    foreach ($phpFiles as $key => $file) {
        require_once $file[0];
    }
    ?>

include et opcache_compile_file() fonctionneront tous les deux, mais ont des implications différentes pour la façon dont le code est géré.

- include va exécuter le code du fichier, tandis que opcache_compile_file() ne le fera pas. Cela signifie que seul le premier supporte la déclaration conditionnelle (les fonctions déclarées à l'intérieur d'un bloc if).
- Parce que include va exécuter le code, les fichiers inclus de manière imbriquée seront également analysés et leurs déclarations préchargées.
- opcache_compile_file() peut charger des fichiers dans n'importe quel ordre. C'est-à-dire que si a.php définit la classe `A` et b.php définit la classe `B` qui étend `A`, alors opcache_compile_file() peut charger ces deux fichiers dans n'importe quel ordre. Lors de l'utilisation de include, cependant, a.php doit être inclus en premier.
- Dans les deux cas, si un script ultérieur inclut un fichier qui a déjà été préchargé, alors son contenu sera toujours exécuté, mais les symboles qu'il définit ne seront pas redéfinis. L'utilisation de include_once n'empêchera pas le fichier d'être inclus une seconde fois. Il peut être nécessaire de charger un fichier à nouveau pour inclure les constantes globales définies en lui, car elles ne sont pas gérées par le préchargement.

Quelle approche est la meilleure dépend donc du comportement souhaité. Avec du code qui utiliserait autrement un chargement automatique, opcache_compile_file() permet une plus grande flexibilité. Avec du code qui serait autrement chargé manuellement, include sera plus robuste.

# Fonctions OPcache

# opcache_compile_file

(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_file — Compile et met en cache un script PHP sans l'exécuter

### Description

function opcache_compile_file(string `$filename`): bool

Cette fonction compile un script PHP et l'ajoute au cache d'opcode sans l'exécuter. Ceci peut être utilisé pour remplir un cache après un redémarrage de serveur en précachant les fichiers qui vont être amenés à être utilisés.

### Liste de paramètres

`filename`
  Le chemin vers le fichier PHP à compiler et mettre en cache.

### Valeurs de retour

Retourne `true` si `filename` a été compilé avec succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si `filename` ne peut être chargé ou compilé, une erreur de type `E_WARNING` est renvoyée. Il est possible d'utiliser @ pour la supprimer.

### Voir aussi

- opcache_invalidate() - Invalide un script mis en cache

# opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configuration — Récupère les informations de configuration du cache

### Description

function opcache_get_configuration(): array|false

Cette fonction retourne les informations de configuration de l'instance de cache.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau d'informations, incluant ini, liste noire et version.

### Erreurs / Exceptions

Si `opcache.restrict_api` est utilisé et que le chemin courant est en violation avec les règles, une alerte de niveau E_WARNING sera émise ; aucune information de statut ne sera retournée.

### Voir aussi

- opcache_get_status() - Récupère les informations de statut du cache

# opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_status — Récupère les informations de statut du cache

### Description

function opcache_get_status(bool `$include_scripts` = `true`): array|false

Cette fonction retourne les informations de statut de l'instance du cache en mémoire. Elle ne renvoie pas d'informations sur le cache de fichiers.

### Liste de paramètres

`include_scripts`
  Inclut les informations spécifiques aux scripts

### Valeurs de retour

Retourne un tableau d'informations, optionnellement contenant un script spécifique d'informations de statut, ou `false` si une erreur survient.

### Erreurs / Exceptions

Si `opcache.restrict_api` est utilisé, et que le chemin courant est en violation avec les règles, une alerte E_WARNING sera émise ; aucune information de statut ne sera retournée.

### Historique

Version | Description
--- | ---
PHP 8.3.0 | `opcache_get_status()['scripts'][n]['revalidate']` contient désormais un timestamp Unix indiquant quand la prochaine revalidation du timestamp des scripts est prévue, comme dicté par la directive INI `opcache.revalidate_freq`.

### Exemples

Exemple #1 Un exemple de opcache_get_status()

    <?php
    var_dump(opcache_get_status());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(9) {
      'opcache_enabled' =>
      bool(true)
      'cache_full' =>
      bool(false)
      'restart_pending' =>
      bool(false)
      'restart_in_progress' =>
      bool(false)
      'memory_usage' =>
      array(4) {
        'used_memory' =>
        int(9167936)
        'free_memory' =>
        int(125049792)
        'wasted_memory' =>
        int(0)
        'current_wasted_percentage' =>
        double(0)
      }
      'interned_strings_usage' =>
      array(4) {
        'buffer_size' =>
        int(8388608)
        'used_memory' =>
        int(2593616)
        'free_memory' =>
        int(5794992)
        'number_of_strings' =>
        int(10358)
      }
      'opcache_statistics' =>
      array(13) {
        'num_cached_scripts' =>
        int(0)
        'num_cached_keys' =>
        int(0)
        'max_cached_keys' =>
        int(16229)
        'hits' =>
        int(0)
        'start_time' =>
        int(1733310010)
        'last_restart_time' =>
        int(0)
        'oom_restarts' =>
        int(0)
        'hash_restarts' =>
        int(0)
        'manual_restarts' =>
        int(0)
        'misses' =>
        int(0)
        'blacklist_misses' =>
        int(0)
        'blacklist_miss_ratio' =>
        double(0)
        'opcache_hit_rate' =>
        double(0)
      }
      'scripts' =>
      array(0) {
      }
      'jit' =>
      array(7) {
        'enabled' =>
        bool(false)
        'on' =>
        bool(false)
        'kind' =>
        int(5)
        'opt_level' =>
        int(4)
        'opt_flags' =>
        int(6)
        'buffer_size' =>
        int(0)
        'buffer_free' =>
        int(0)
      }
    }

### Voir aussi

- opcache_get_configuration() - Récupère les informations de configuration du cache

# opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidate — Invalide un script mis en cache

### Description

function opcache_invalidate(string `$filename`, bool `$force` = `false`): bool

Cette fonction invalide un script particulier depuis le cache opcode. Si le paramètre `force` n'est pas défini ou vaut `false`, le script ne sera invalidé que si la date/heure de modification du script est plus récente que l'opcode en cache. Cette fonction n'invalide que le cache en mémoire et non le cache fichier.

### Liste de paramètres

`filename`
  Le chemin vers le script à invalider.
`force`
  Si vaut `true`, le script sera invalidé indépendamment du fait que l'invalidation soit nécessaire ou non.

### Valeurs de retour

Retourne `true` si le cache opcode pour le `filename` a été invalidé, ou s'il n'y avait rien à invalider, ou bien `false` si le cache opcode est désactivé.

### Voir aussi

- opcache_compile_file() - Compile et met en cache un script PHP sans l'exécuter
- opcache_reset() - Réinitialise le contenu du cache opcode

# opcache_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cached — Indique si un script est dans le cache d'OPCache

### Description

function opcache_is_script_cached(string `$filename`): bool

Cette fonction vérifie si un script PHP a été mis dans le cache d'OPCache. Ceci peut être utilisé pour détecter facilement le « réchauffement » du cache pour un script particulier. Cette fonction ne vérifie que le cache en mémoire, pas le cache des fichiers. Pour vérifier le cache des fichiers, utiliser opcache_is_script_cached_in_file_cache().

### Liste de paramètres

`filename`
  Le chemin vers le script PHP à vérifier.

### Valeurs de retour

Retourne `true` si `filename` est présent dans le cache en mémoire d'OPCache, `false` sinon.

### Voir aussi

- opcache_compile_file() - Compile et met en cache un script PHP sans l'exécuter
- opcache_is_script_cached_in_file_cache() - Indique si un script est dans le cache de fichiers d'OPCache

# opcache_is_script_cached_in_file_cache

(PHP 8 >= 8.5.0)

opcache_is_script_cached_in_file_cache — Indique si un script est dans le cache de fichiers d'OPCache

### Description

function opcache_is_script_cached_in_file_cache(string `$filename`): bool

Cette fonction vérifie si un script PHP a été mis dans le cache d'OPCache. Ceci peut être utilisé pour détecter facilement le « réchauffement » du cache pour un script particulier. Cette fonction ne vérifie que le cache de fichiers, pas le cache en mémoire. Pour vérifier le cache en mémoire, utiliser opcache_is_script_cached().

### Liste de paramètres

`filename`
  Le chemin vers le script PHP à vérifier.

### Valeurs de retour

Retourne `true` si `filename` est présent dans le cache d'OPCache, `false` sinon.

### Voir aussi

- opcache_compile_file() - Compile et met en cache un script PHP sans l'exécuter
- opcache_is_script_cached() - Indique si un script est dans le cache d'OPCache

# opcache_jit_blacklist

(PHP 8 >= 8.4.0)

opcache_jit_blacklist — Ajoute une fonction à la liste noire de la compilation JIT

### Description

function opcache_jit_blacklist( Closure `$closure` ): void

Cette fonction ajoute une fonction particulière à la liste noire pour empêcher sa compilation JIT lorsque le Tracing JIT est utilisé. La fonction est spécifiée en utilisant une Closure.

Avertissement

Toutes les parties de la fonction qui ont déjà été compilées par JIT ne sont pas affectées et resteront compilées par JIT.

### Liste de paramètres

`closure`
  La fonction à ajouter à la liste noire, représentée comme un callable de première classe. Il est également possible de passer une fonction anonyme, auquel cas la fonction anonyme elle-même est ajoutée à la liste noire.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple simple avec opcache_jit_blacklist()

    <?php
    function foo() {
        $x = 1;
        $x += 0;
        ++$x;
        var_dump($x);
    }
    opcache_jit_blacklist(foo(...));
    foo();
    ?>

### Voir aussi

- opcache_invalidate() - Invalide un script mis en cache
- opcache_reset() - Réinitialise le contenu du cache opcode

# opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_reset — Réinitialise le contenu du cache opcode

### Description

function opcache_reset(): bool

Cette fonction réinitialise le cache opcode dans sa globalité. Après l'appel à la fonction opcache_reset(), tous les scripts seront rechargés et réanalysés lors de leurs prochains appels. Cette fonction ne réinitialise que le cache en mémoire, pas le cache des fichiers.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si le cache opcode a été réinitialisé, ou `false` si le cache opcode est désactivé ou si le redémarrage est en attente ou en cours (voir opcache_get_status()).

### Voir aussi

- opcache_invalidate() - Invalide un script mis en cache
- opcache_get_status() - Récupère les informations de statut du cache

## Sommaire

- opcache_compile_file — Compile et met en cache un script PHP sans l'exécuter
- opcache_get_configuration — Récupère les informations de configuration du cache
- opcache_get_status — Récupère les informations de statut du cache
- opcache_invalidate — Invalide un script mis en cache
- opcache_is_script_cached — Indique si un script est dans le cache d'OPCache
- opcache_is_script_cached_in_file_cache — Indique si un script est dans le cache de fichiers d'OPCache
- opcache_jit_blacklist — Ajoute une fonction à la liste noire de la compilation JIT
- opcache_reset — Réinitialise le contenu du cache opcode

- Installation/Configuration
  - Installation
  - Configuration à l'exécution
- Preloading
- Fonctions OPcache
  - opcache_compile_file — Compile et met en cache un script PHP sans l'exécuter
  - opcache_get_configuration — Récupère les informations de configuration du cache
  - opcache_get_status — Récupère les informations de statut du cache
  - opcache_invalidate — Invalide un script mis en cache
  - opcache_is_script_cached — Indique si un script est dans le cache d'OPCache
  - opcache_is_script_cached_in_file_cache — Indique si un script est dans le cache de fichiers d'OPCache
  - opcache_jit_blacklist — Ajoute une fonction à la liste noire de la compilation JIT
  - opcache_reset — Réinitialise le contenu du cache opcode

# Surcharge d'opérateurs pour les objets

# Introduction

Cette extension définit et implémente la surcharge d'opérateurs pour les objets. Elle permet de définir comment un objet réagit lorsqu'un opérateur lui est appliqué.

Un exemple est la création d'un objet de type collection dont l'opérateur d'addition est surchargé pour permettre d'ajouter des éléments à la collection ou d'additionner deux collections ensemble.

Un autre exemple est la création d'une classe de chaîne améliorée dont l'opérateur de multiplication est surchargé pour permettre de répéter la chaîne un certain nombre de fois.

# Installation/Configuration

## Sommaire

- Installation

## Installation

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/operator.

Les utilisateurs Windows peuvent télécharger les binaires précompilés depuis le site » PECL.

Les versions d'operator sont hébergées par PECL et le code source par » github.

# Méthodes magiques de surcharge d'opérateurs

L'extension de surcharge d'opérateurs permet de définir comment un objet réagit aux opérateurs. Cela se fait en implémentant les méthodes magiques suivantes :

Opérateurs arithmétiques :

- `$a::__add($b)`
- `$a::__sub($b)`
- `$a::__mul($b)`
- `$a::__div($b)`
- `$a::__mod($b)`
- `$a::__pow($b)`

Opérateurs d'affectation :

- `$a::__assign($b)`
- `$a::__assign_add($b)`
- `$a::__assign_sub($b)`
- `$a::__assign_mul($b)`
- `$a::__assign_div($b)`
- `$a::__assign_mod($b)`
- `$a::__assign_pow($b)`
- `$a::__assign_bw_and($b)`
- `$a::__assign_bw_or($b)`
- `$a::__assign_bw_xor($b)`
- `$a::__assign_sl($b)`
- `$a::__assign_sr($b)`
- `$a::__assign_concat($b)`

Opérateurs sur les bits :

- `$a::__bw_and($b)`
- `$a::__bw_or($b)`
- `$a::__bw_xor($b)`
- `$a::__bw_not()`
- `$a::__sl($b)`
- `$a::__sr($b)`

Opérateurs de comparaison :

- `$a::__is_equal($b)`
- `$a::__is_not_equal($b)`
- `$a::__is_identical($b)`
- `$a::__is_not_identical($b)`
- `$a::__is_smaller($b)`
- `$a::__is_smaller_or_equal($b)`
- `$a::__is_greater($b)`
- `$a::__is_greater_or_equal($b)`
- `$a::__spaceship($b)`

Opérateurs d'incrémentation et de décrémentation :

- `$a::__pre_inc()`
- `$a::__post_inc()`
- `$a::__pre_dec()`
- `$a::__post_dec()`

Opérateurs de chaînes :

- `$a::__concat($b)`

## Exemples de surcharge d'opérateurs

Ce qui suit est la classe utilisée pour les tests de l'extension de surcharge d'opérateurs. Elle surcharge tous les opérateurs qu'il est possible de surcharger à des fins de test.

Exemple #1 Classe complète pour la surcharge d'opérateurs

    <?php
    class OperatorOverloading {
        protected mixed $value;

        //region Méthodes magiques standards
        public function __get(string $name)
        {
            return $this->value;
        }

        public function __set(string $name, mixed $value)
        {
            $this->value = $value;
        }

        public function __construct(mixed $init = null)
        {
            $this->value = $init;
        }
        //endregion

        //region Opérateurs arithmétiques
        public function __add(mixed $val): int|float
        {
            return $this->value + $val;
        }

        public function __div(mixed $val): int|float
        {
            return $this->value / $val;
        }

        public function __mod(mixed $val): int
        {
            return $this->value % $val;
        }

        public function __mul(mixed $val): int|float
        {
            return $this->value * $val;
        }

        public function __pow(mixed $val): int|float
        {
            return $this->value ** $val;
        }

        public function __sub(mixed $val): int|float
        {
            return $this->value - $val;
        }
        //endregion

        //region Opérateurs d'affectation
        public function __assign(mixed $val): mixed
        {
            return $this->value = $val;
        }

        public function __assign_add(mixed $val): mixed
        {
            return $this->value += $val;
        }

        public function __assign_bw_and(mixed $val): mixed
        {
            return $this->value &= $val;
        }

        public function __assign_bw_or(mixed $val): mixed
        {
            return $this->value |= $val;
        }

        public function __assign_concat(mixed $val): string
        {
            return $this->value .= $val;
        }

        public function __assign_div(mixed $val): mixed
        {
            return $this->value /= $val;
        }

        public function __assign_mod(mixed $val): mixed
        {
            return $this->value %= $val;
        }

        public function __assign_mul(mixed $val): mixed
        {
            return $this->value *= $val;
        }

        public function __assign_pow(mixed $val): mixed
        {
            return $this->value **= $val;
        }

        public function __assign_sl(mixed $val): mixed
        {
            return $this->value <<= $val;
        }

        public function __assign_sr(mixed $val): mixed
        {
            return $this->value >>= $val;
        }

        public function __assign_sub(mixed $val): mixed
        {
            return $this->value -= $val;
        }
        //endregion

        //region Opérateurs sur les bits
        public function __bw_and(mixed $val): int
        {
            return $this->value & $val;
        }

        public function __bw_not(): int|string
        {
            return ~$this->value;
        }

        public function __bw_or(mixed $val): int
        {
            return $this->value | $val;
        }

        public function __bw_xor(mixed $val): int
        {
            return $this->value ^ $val;
        }

        public function __sl(mixed $val): int
        {
            return $this->value << $val;
        }

        public function __sr(mixed $val): int
        {
            return $this->value >> $val;
        }
        //endregion

        //region Opérateurs de comparaison
        public function __is_equal(mixed $val): bool
        {
            return $this->value == $val;
        }

        public function __is_greater(mixed $val): bool
        {
            return $this->value > $val;
        }

        public function __is_greater_or_equal(mixed $val): bool
        {
            return $this->value >= $val;
        }

        public function __is_identical(mixed $val): bool
        {
            return $this->value === $val;
        }

        public function __is_not_equal(mixed $val): bool
        {
            return $this->value != $val;
        }

        public function __is_not_identical(mixed $val): bool
        {
            return $this->value !== $val;
        }

        public function __is_smaller(mixed $val): bool
        {
            return $this->value < $val;
        }

        public function __is_smaller_or_equal(mixed $val): bool
        {
            return $this->value <= $val;
        }

        public function __spaceship(mixed $val): int
        {
            return $this->value <=> $val;
        }
        //endregion

        //region Opérateurs d'incrémentation/décrémentation
        public function __post_dec(): mixed
        {
            return $this->value--;
        }

        public function __post_inc(): mixed
        {
            return $this->value++;
        }

        public function __pre_dec(): mixed
        {
            return --$this->value;
        }

        public function __pre_inc(): mixed
        {
            return ++$this->value;
        }
        //endregion

        //region Opérateurs de chaînes
        public function __concat(mixed $val): string
        {
            return $this->value . $val;
        }
        //endregion

    }

En utilisant la classe ci-dessus, il est possible de surcharger les opérateurs comme suit :

    <?php
    $a = new OperatorOverloading(5);
    var_dump($a + 10);
    var_dump($a - 10);
    $b = new OperatorOverloading("Hello");
    var_dump($b . " World");

L'exemple ci-dessus va afficher :

    int(15)
    int(-5)
    string(11) "Hello World"

- Installation/Configuration
  - Installation
- Méthodes magiques de surcharge d'opérateurs

# Bufferisation de sortie

# Introduction

Les fonctions de bufferisation de sortie permettent de contrôler quand les données sont envoyées par le script. Cela peut être utile dans certaines situations, notamment si l'on doit envoyer des en-têtes au navigateur après avoir envoyé des données. Ces fonctions n'affectent pas les en-têtes envoyés par la fonction header() ou les cookies envoyés par setcookie(). Seules les fonctions telles que echo et les données entre blocs PHP sont affectées.

# Installation/Configuration

## Sommaire

- Configuration à l'exécution

## Configuration à l'exécution

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

Options de configuration des buffers de sortie
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
output_buffering | `"0"` | `INI_PERDIR` |
output_handler | `null` | `INI_PERDIR` |
implicit_flush | `"0"` | `INI_ALL` |
url_rewriter.tags | `"form="` | `INI_ALL` | À partir de PHP 7.1.0, ce paramètre INI n'a d'effet que sur output_add_rewrite_var(). Antérieur à PHP 7.1.0, ce paramètre INI activait la prise en charge transparente de l'ID de session (voir session.trans_sid_tags).
url_rewriter.hosts | `$_SERVER['HTTP_HOST']` est utilisé par défaut. | `INI_ALL` | Disponible à partir de PHP 7.1.0

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`output_buffering` bool/int

  La mise en mémoire tampon de la sortie pour tous les fichiers peut être activée en définissant cette directive sur `"On"`. Pour limiter la taille du tampon, un nombre/quantité correspondant au nombre maximal d'octets autorisés peut être utilisé à la place de `"On"` pour la valeur de cette directive. Par exemple, `output_buffering=4096`.

`output_handler` string

  La sortie des scripts peut être redirigée vers une fonction. Par exemple, en définissant `output_handler` sur mb_output_handler(), le codage des caractères sera converti de manière transparente vers le codage spécifié. La configuration de n'importe quel gestionnaire de sortie active automatiquement la mise en mémoire tampon de la sortie.

  > Note:

  > mb_output_handler() et ob_iconv_handler() ne peuvent pas être utilisés ensemble, et ob_gzhandler() et zlib.output_compression ne peuvent pas être utilisés avec l'un des éléments suivants : mb_output_handler(), ob_gzhandler(), zlib.output_compression, le gestionnaire 'URL-Rewriter' (voir session.use_trans_sid et output_add_rewrite_var()).

  > Note:

  > Seules les fonctions internes peuvent être utilisées avec cette directive. Pour les fonctions utilisateurs, utiliser ob_start().

`implicit_flush` bool

  `false` par défaut. En changeant cette valeur pour `true` on indique à PHP que le buffer de sortie doit être vidé automatiquement après chaque fonction d'affichage. Cela revient à appeler la fonction flush() après chaque appel à toute fonction produisant une sortie (comme print ou echo) et chaque bloc HTML.

  Lorsqu'on utilise PHP en environnement web, activer cette option a de sérieuses implications et généralement, cela n'est conseillé que pour les débogages. Cette valeur est par défaut à `true` lorsque PHP fonctionne en mode `CLI SAPI`.

  Voir aussi ob_implicit_flush().

`url_rewriter.tags` string
  `url_rewriter.tags` spécifie les balises HTML et les attributs dans lesquels les URLs sont réécrites par les valeurs de output_add_rewrite_var(). Par défaut, c'est `"form="`. Ajouter `"form="` ou n'importe quel attribut `form` ajoutera un élément `input` caché dans le `form` avec un attribut de nom et de valeur pour chaque paire nom-valeur transmise à output_add_rewrite_var().
  Attention

  Ajouter la même balise plus d'une fois à `url_rewriter.tags` utilisera uniquement la première occurrence pendant le processus de réécriture d'URL.

  > Note: Antérieur à PHP 7.1.0, url_rewriter.tags était utilisé pour spécifier session.trans_sid_tags.

`url_rewriter.hosts` string
  `url_rewriter.hosts` spécifie les hôtes qui sont réécrits pour inclure les valeurs de la fonction output_add_rewrite_var(). Par défaut `$_SERVER['HTTP_HOST']`. Plusieurs hôtes peuvent être spécifiés séparés par une virgule, aucun espace n'est autorisé entre les hôtes. Par exemple : `php.net,wiki.php.net,bugs.php.net`

# Constantes pré-définies

Les constantes listées ici sont toujours disponibles dans PHP.

Indicateurs d'état transmis au gestionnaire de sortie

Les indicateurs suivants sont transmis au deuxième paramètre (`phase`) du gestionnaire de sortie défini par ob_start() sous forme de masque de bits :

`PHP_OUTPUT_HANDLER_START` (int)

  Indique que la mise en mémoire tampon de sortie a commencé.

`PHP_OUTPUT_HANDLER_WRITE` (int)

  Indique que la mémoire tampon de sortie est en train d'être vidée, et qu'elle contient des données à envoyer.

`PHP_OUTPUT_HANDLER_FLUSH` (int)

  Indique que la mémoire tampon a été vidée.

`PHP_OUTPUT_HANDLER_CLEAN` (int)

  Indique que la mémoire tampon de sortie a été nettoyée.

`PHP_OUTPUT_HANDLER_FINAL` (int)

  Indique que c'est l'opération finale de mise en mémoire tampon de la sortie.

`PHP_OUTPUT_HANDLER_CONT` (int)

  Indique que la mémoire tampon a été vidée, mais que la mise en mémoire tampon de la sortie continue.

  C'est un alias de la constante `PHP_OUTPUT_HANDLER_WRITE`.

`PHP_OUTPUT_HANDLER_END` (int)

  Indique que la mise en mémoire tampon de la sortie est terminée.

  C'est un alias de la constante `PHP_OUTPUT_HANDLER_FINAL`.

Indicateurs de contrôle du tampon de sortie

Les indicateurs suivants peuvent être transmis au troisième paramètre (`flags`) du gestionnaire de sortie défini par ob_start() sous forme de masque de bits :

`PHP_OUTPUT_HANDLER_CLEANABLE` (int)

  Contrôle si un tampon de sortie créé par la fonction ob_start() peut être nettoyé par ob_clean(). Cet indicateur ne contrôle pas le comportement de ob_end_clean() ou ob_get_clean().

`PHP_OUTPUT_HANDLER_FLUSHABLE` (int)

  Contrôle si un tampon de sortie créé par la fonction ob_start() peut être envoyé à la sortie standard par ob_flush(). Cet indicateur ne contrôle pas le comportement de ob_end_flush() ou ob_get_flush().

`PHP_OUTPUT_HANDLER_REMOVABLE` (int)

  Contrôle si un tampon de sortie créé par la fonction ob_start() peut être supprimé avant la fin du script ou lors de l'appel de ob_end_clean(), ob_end_flush(), ob_get_clean() ou ob_get_flush().

`PHP_OUTPUT_HANDLER_STDFLAGS` (int)

  Le jeu par défaut des drapeaux pour le tampon de sortie ; actuellement, équivalent à `PHP_OUTPUT_HANDLER_CLEANABLE` | `PHP_OUTPUT_HANDLER_FLUSHABLE` | `PHP_OUTPUT_HANDLER_REMOVABLE`.

Indicateurs d'état du gestionnaire de sortie

Les indicateurs suivants font partie du masque de bits `flags` retourné par ob_get_status() :

`PHP_OUTPUT_HANDLER_STARTED` (int)

  Indique que le gestionnaire de sortie a été appelé.

`PHP_OUTPUT_HANDLER_DISABLED` (int)

  Indique que le gestionnaire de sortie est désactivé. Cet indicateur est défini lorsque le gestionnaire de sortie retourne `false` ou échoue lors du traitement du tampon. Avant PHP 8.4.0, ce drapeau pouvait être défini lors du démarrage d'un tampon de sortie.

`PHP_OUTPUT_HANDLER_PROCESSED` (int)

  Indique que le gestionnaire de sortie a traité avec succès le tampon. Disponible à partir de PHP 8.4.0.

# Bufferisation de sortie

La bufferisation de sortie est le stockage tamponné (temporaire) de la sortie avant qu'elle ne soit lavée (envoyée et supprimée) au navigateur (dans un contexte web) ou au shell (en ligne de commande). Tant que la bufferisation de sortie est active, aucune sortie n'est envoyée par le script, au lieu de cela, la sortie est stockée dans un tampon interne.

## Effets de la bufferisation sur PHP

PHP dépend de l'infrastructure logicielle/matérielle sous-jacente lors du vidage de tampon de la sortie. La bufferisation implémentée par les consoles en ligne de commande (par exemple, en mode ligne) ou les serveurs web et les navigateurs dans un contexte web (par exemple, entièrement bufferisé) affectent quand la sortie est affichée à l'utilisateur final. Certains de ces effets peuvent être éliminés en ajustant finement les paramètres du serveur et/ou en alignant les tailles des tampons des différentes couches.

## Contrôle de la bufferisation de sortie en PHP

PHP apporte un tampon de sortie utilisateur entièrement bufferisé avec des fonctions pour démarrer, manipuler et désactiver le tampon (la plupart des fonctions ob_*), et deux fonctions pour laver les tampons système sous-jacents (flush() et ob_implicit_flush()). Certaines de ces fonctionnalités peuvent être définies et/ou configurées en utilisant les paramètres php.ini appropriés.

## Cas d'utilisation

La bufferisation de sortie est généralement utile dans des situations où la sortie bufferisée est modifiée ou inspectée, ou elle est utilisée plus d'une fois dans une requête ; ou lorsque le vidage de tampon contrôlé de la sortie est désiré. Les cas d'utilisation spécifiques incluent :

- mettre en cache le résultat de scripts de calcul/temps intensifs par exemple en générant des pages `HTML` statiques
- réutiliser la sortie générée en l'affichant, en la sauvegardant dans un fichier et/ou en l'envoyant par email
- laver la `head` d'une page `HTML` séparée du `body` permet aux navigateurs de charger des ressources externes pendant que le script exécute des processus potentiellement plus longs (par exemple, accès à une base de données/fichier, connexion réseau externe). Ceci est utile uniquement si le code d'état `HTTP` ne peut pas changer après l'envoi des en-têtes
- extraire des informations de fonctions qui produiraient autrement une sortie (par exemple phpinfo())
- contrôler la sortie de code tiers en modifiant/utilisant des parties (par exemple, extraire des données, remplacer des mots/phrases, ajouter des balises `HTML` manquantes), ou en la supprimant entièrement dans certaines conditions (par exemple, erreurs)
- Polyfiller certaines fonctionnalités de serveur web indisponibles (par exemple, compresser ou encoder la sortie)

# Laver les tampons système

PHP apporte deux façons de vider (envoyer et supprimer le contenu) les tampons système : à travers l'appel de flush() et en activant le vidage de tampon implicite avec ob_implicit_flush() ou le paramètre implicit_flush de php.ini.

## Comportement de vidage de tampon de sortie

Avec le vidage de tampon implicite désactivé, PHP ne lave la sortie que lorsque flush() est appelée ou lorsque le script se termine.

Avec le vidage de tampon implicite activé, PHP tentera de laver après chaque bloc de code produisant de la sortie. La sortie dans ce contexte est des données de longueur non nulle qui sont :

- hors des balises `<?php ?>`
- affichées par des constructions de langage et des fonctions dont le but explicite est d'afficher des variables ou des chaînes fournies par l'utilisateur telles que echo, print, printf(), var_dump(), var_export(), vprintf()
- affichées par des fonctions dont le but est de collecter et de produire des données/informations sur le script en cours ou PHP telles que debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info()
- affichées par PHP sur une exception non capturée ou une erreur non gérée (sous réserve des paramètres de display_errors et error_reporting)
- tout ce qui est écrit dans `php://output`

> Note: Afficher des chaînes vides ou envoyer des en-têtes n'est pas considéré comme une sortie et ne déclenchera pas d'opération de vidage de tampon.

Avertissement

Si le vidage de tampon implicite est activé, les caractères de contrôle (par exemple `"\n"`, `"\r"`, `"\0"`) déclencheront également un vidage de tampon.

## Limitations

Cette fonctionnalité ne peut pas laver les tampons de sortie de niveau utilisateur. Pour les utiliser ensemble, les tampons de sortie de niveau utilisateur doivent être lavés avant de laver les tampons système pour que PHP produise une sortie.

Avertissement

Appeler flush() ou activer le vidage de tampon implicite peut interférer avec les gestionnaires de sortie des tampons de sortie de niveau utilisateur qui définissent et envoient des en-têtes dans un contexte web (par exemple ob_gzhandler()) en envoyant des en-têtes avant que ces gestionnaires ne le fassent.

La mise en tampon mise en œuvre par le logiciel/matériel sous-jacent ne peut pas être remplacée par PHP et doit être prise en compte lors de l'utilisation des fonctions de contrôle des tampons de PHP. Vérifier les paramètres de mise en tampon des serveurs web/navigateurs/consoles et travailler avec ceux-ci peut atténuer les problèmes potentiels. Travailler dans un contexte web, soit les paramètres de mise en tampon du serveur web ou la mise en tampon du script pourrait être ajustée pour fonctionner en tandem alors que travailler autour des stratégies de mise en tampon de divers navigateurs peut être réalisé en ajustant la mise en tampon dans le script PHP. Sur les consoles qui implémentent la mise en tampon de ligne, les caractères de nouvelle ligne pourraient être insérés aux endroits appropriés avant de vider la sortie.

## Différences de vidage selon le SAPI

Même si le vidage de tampon est implémenté par chaque SAPI de manière légèrement différente, ces implémentations tombent dans l'une des deux catégories :

- Les SAPIs utilisés dans un contexte web videront d'abord les en-têtes suivis de la sortie. `Apache2Handler`, `CGI`, `FastCGI` et `FPM` sont de tels SAPIs
- d'autres SAPIs tels que `CLI` et `embed` videront la sortie uniquement

# Tampons de sortie au niveau utilisateur

## Sommaire

- Quelle sortie est bufferisée ?
- Imbrication des tampons de sortie
- Taille du tampon
- Opérations autorisées sur les tampons
- Gestionnaires de sortie
- Travailler avec les gestionnaires de sortie
- Drapeaux passés aux gestionnaires de sortie
- Valeurs de retour des gestionnaires de sortie

La bufferisation de sortie au niveau utilisateur de PHP peut être commencée, manipulée et terminée depuis le code PHP. Chacun de ces tampons inclut un tampon de sortie et une fonction de gestion de sortie associée.

## Quelle sortie est bufferisée ?

Les tampons de sortie au niveau utilisateur de PHP bufferisent toute la sortie après leur démarrage jusqu'à ce qu'ils soient désactivés ou que le script se termine. La sortie dans le contexte des tampons de sortie au niveau utilisateur de PHP est tout ce que PHP afficherait ou enverrait au navigateur. En termes pratiques, la sortie est toute donnée de longueur non nulle qui est :

- hors des balises `<?php ?>`
- affichées par des constructions de langage et des fonctions dont le but explicite est d'afficher des variables ou des chaînes fournies par l'utilisateur telles que echo, print, printf(), var_dump(), var_export(), vprintf()
- affichées par des fonctions dont le but est de collecter et de produire des données/informations sur le script en cours ou PHP telles que debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info()
- affichées par PHP sur une exception non capturée ou une erreur non gérée (sous réserve des paramètres de display_errors et error_reporting)
- tout ce qui est écrit dans `php://output`

> Note: Les données écrites directement dans `stdout` ou passées à une fonction SAPI avec une fonctionnalité similaire ne seront pas capturées par les tampons de sortie au niveau utilisateur. Cela inclut l'écriture de données dans `stdout` avec fwrite() ou l'envoi d'en-têtes avec header() ou setcookie().

## Démarrer un tampon de sortie

Les tampons de sortie au niveau utilisateur peuvent être démarrés en utilisant la fonction ob_start() ou en définissant les paramètres output_buffering et output_handler de php.ini. Tant l'un que l'autre peuvent créer des tampons de sortie, ob_start() est plus flexible car il accepte des fonctions définies par l'utilisateur comme gestionnaires de sortie et les opérations autorisées sur le tampon (flush, clean, remove) peuvent être définies également. Les tampons de sortie démarrés avec ob_start() seront actifs à partir de la ligne où la fonction a été appelée, tandis que ceux démarrés avec output_buffering bufferiseront la sortie à partir de la première ligne du script.

PHP est également livré avec un gestionnaire de sortie intégré `"URL-Rewriter"` qui démarre son propre tampon de sortie et ne permet que deux instances de celui-ci à fonctionner en même temps (une pour la réécriture d'URL au niveau utilisateur et une pour le support transparent des identifiants de session). Ces tampons peuvent être démarrés en appelant la fonction output_add_rewrite_var() et/ou en activant le paramètre session.use_trans_sid de php.ini.

L'extension `zlib` a son propre tampon de sortie qui peut être activé en utilisant le paramètre zlib.output_compression de php.ini.

> Note: Tant que `"URL-Rewriter"` est spécial en ce qu'il ne permet que deux instances de celui-ci à fonctionner en même temps, tous les tampons de sortie au niveau utilisateur utilisent les mêmes tampons sous-jacents utilisés par ob_start() avec leur fonctionnalité implémentée par une fonction de gestion de sortie personnalisée. En tant que tel, toute leur fonctionnalité peut être émulée par du code utilisateur.

## Imbrication des tampons de sortie

Si un tampon de sortie est actif lorsqu'un nouveau tampon est démarré, le nouveau tampon sera imbriqué à l'intérieur du tampon précédemment actif. Le tampon interne se comportera de la même manière, que ce soit imbriqué ou non, mais la sortie bufferisée par celui-ci ne sera pas bufferisée par le tampon externe. Seule la sortie vidée par le tampon interne sera bufferisée par le tampon externe.

La plupart des fonctions `ob_*` ne fonctionnent qu'avec le tampon de sortie actif (le dernier démarré) donc seul le tampon actif peut être vidé, nettoyé et désactivé. Les fonctions qui fonctionnent avec d'autres tampons sont ob_list_handlers() qui retourne la liste de tous les gestionnaires de sortie en cours d'utilisation et ob_get_status() qui peut retourner des informations sur le tampon actif uniquement ou sur tous les tampons en cours d'utilisation.

Appeler ob_get_level() ou ob_get_status() retournera le niveau d'imbrication du tampon de sortie actif.

Attention

La valeur pour les niveaux identiques entre ob_get_level() et ob_get_status() diffère d'un. Pour ob_get_level() le premier niveau est `1`, tandis que pour ob_get_status() le premier niveau est `0`.

## Taille du tampon

Les tailles des tampons de sortie sont exprimées par des entiers et représentent le nombre d'octets que le tampon peut stocker sans vidage de tampon. Lorsque la taille de la sortie dans le tampon dépasse la taille du tampon, le contenu du tampon est envoyé au gestionnaire de sortie, sa valeur de retour est lavée et le tampon est vidé.

Avec l'exception de `"URL-Rewriter"`, la taille des tampons de sortie peut être définie lorsque le tampon est démarré. Si défini à `0`, le tampon de sortie est uniquement limité par la mémoire disponible pour PHP. Si défini à `1`, le tampon est lavé après chaque bloc de code produisant une sortie de longueur non nulle.

La taille des tampons de sortie peut être récupérée en appelant ob_get_status().

Les tampons de sortie démarrés avec ob_start() auront leur taille de tampon définie à la valeur entière passée au deuxième paramètre `chunk_size` de la fonction. Si omis, il est défini à `0`.

Le tampon de sortie démarré avec output_buffering défini à `"On"` aura sa taille de tampon définie à `0`. Si défini à un entier, la taille du tampon correspondra à ce nombre.

La taille du tampon de sortie de `"URL-Rewriter"` est définie à `0`, donc il est uniquement limité par la mémoire disponible pour PHP.

La taille du tampon de sortie de `zlib` est contrôlée par le paramètre zlib.output_compression de php.ini. Si défini à `"On"`, la taille du tampon sera `"16K"`/`16384`. Si défini à un entier, la taille du tampon correspondra à ce nombre en octets.

## Opérations autorisées sur les tampons

Les opérations autorisées sur les tampons peuvent être contrôlées en passant un des drapeaux de contrôle de tampon au troisième paramètre `flags` de ob_start(). Si omis, toutes les opérations sont autorisées par défaut. Si `0` est utilisé à la place, le tampon ne peut pas être lavé, nettoyé ou désactivé mais son contenu peut toujours être récupéré.

`PHP_OUTPUT_HANDLER_CLEANABLE` permet à ob_clean() de nettoyer le contenu du tampon.

Avertissement

L'absence du drapeau `PHP_OUTPUT_HANDLER_CLEANABLE` n'empêchera pas ob_end_clean() ou ob_get_clean() de nettoyer le contenu du tampon.

`PHP_OUTPUT_HANDLER_FLUSHABLE` permet à ob_flush() de vider le contenu du tampon.

Avertissement

L'absence du drapeau `PHP_OUTPUT_HANDLER_FLUSHABLE` n'empêchera pas ob_end_flush() ou ob_get_flush() de vider le contenu du tampon.

`PHP_OUTPUT_HANDLER_REMOVABLE` permet à ob_end_clean(), ob_end_flush(), ob_get_clean() ou ob_get_flush() de désactiver le tampon.

`PHP_OUTPUT_HANDLER_STDFLAGS`, la combinaison des trois drapeaux, permet à chacune des trois opérations d'être effectuée sur le tampon.

## Laver, accéder et nettoyer le contenu du tampon

Laver envoie et supprime le contenu du tampon actif. Les tampons de sortie sont lavés lorsque la taille de la sortie dépasse la taille du tampon, le script se termine ou ob_flush(), ob_end_flush(), ou ob_get_flush() est appelé.

Attention

Appeler ob_end_flush() ou ob_get_flush() désactivera le tampon actif.

Attention

Laver les tampons va laver la valeur de retour du gestionnaire de sortie qui peut différer du contenu du tampon. Par exemple, utiliser ob_gzhandler() va compresser la sortie et laver la sortie compressée.

Le contenu du tampon actif peut être récupéré en appelant ou ob_get_flush().

Si seule la longueur du contenu du tampon est nécessaire, ob_get_length() ou ob_get_status() va retourner la longueur du contenu en octets.

Attention

Appeler ob_get_clean() ou ob_get_flush() désactivera le tampon actif après avoir retourné son contenu.

Le contenu du tampon actif peut être nettoyé en appelant ob_clean(), ob_end_clean() ou ob_get_clean().

Attention

Appeler ob_end_clean() ou ob_get_clean() désactivera le tampon actif.

## Désactiver les tampons

Les tampons de sortie peuvent être désactivés en appelant ob_end_clean(), ob_end_flush(), ob_get_flush() ou ob_get_clean().

Avertissement

Les tampons de sortie démarrés sans le drapeau `PHP_OUTPUT_HANDLER_REMOVABLE` ne peuvent pas être désactivés et généreront une `E_NOTICE`.

Chaque tampon de sortie qui n'a pas été désactivé à la fin du script ou lorsque exit() est appelé sera lavé et désactivé par le processus de terminaison de PHP. Les tampons seront lavés et désactivés dans l'ordre inverse de leur démarrage. Le dernier tampon démarré sera le premier, le premier tampon démarré sera le dernier à être lavé et désactivé.

Attention

Si le vidage de tampon du contenu du tampon n'est pas désiré, un gestionnaire de sortie personnalisé doit être utilisé pour empêcher le vidage de tampon lors de la fermeture.

## Gestionnaires de sortie

Les gestionnaires de sortie sont des callables associés aux tampons de sortie qui sont invoqués en appelant ob_clean(), ob_flush(), ob_end_flush(), ob_get_flush(), ob_end_clean(), ob_get_clean() ou pendant le processus de terminaison de PHP.

> Note: Le processus de terminaison va vider les valeurs de retour des gestionnaires de sortie

Si omis ou `null` lors du démarrage du tampon de sortie le gestionnaire de sortie interne `"gestionnaire de sortie par défaut"` sera utilisé qui retourne le contenu du tampon non modifié lorsqu'il est invoqué. Les gestionnaires de sortie peuvent être utilisés pour retourner une version modifiée du contenu du tampon et/ou avoir des effets secondaires (par exemple, envoyer des en-têtes).

PHP arrive avec deux gestionnaires de sortie internes : `"default output handler"` et `"URL-Rewriter"` (qui est intégré dans son propre tampon de sortie et seulement jusqu'à deux instances de celui-ci peuvent être démarrées).

L'extension groupé inclut quatre gestionnaires de sortie supplémentaires : mb_output_handler(), ob_gzhandler(), ob_iconv_handler(), ob_tidyhandler().

## Travailler avec les gestionnaires de sortie

Lorsque invoqués, les gestionnaires de sortie reçoivent le contenu du tampon et un masque indiquant l'état de la bufferisation de sortie.

function handler ( string `$buffer` , int `$phase` = ?): string

`buffer`
  Le contenu du tampon.
`phase`
  Un masque de bits des constantes `PHP_OUTPUT_HANDLER_*` .

Avertissement

Appeler l'une des fonctions suivantes depuis un gestionnaire de sortie résultera en une erreur fatale : ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

> Note: Si le `PHP_OUTPUT_HANDLER_DISABLED` d'un gestionnaire est défini, le gestionnaire ne sera pas invoqué en appelant ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() ou pendant le processus de terminaison de PHP. Avant PHP 8.4.0, ce drapeau n'avait aucun effet lors de l'appel de la fonction ob_clean() ou ob_flush().

> Note: Le répertoire de travail du script peut changer à l'intérieur de la fonction d'arrêt sous certains serveurs web, par exemple Apache ou le serveur web intégré.

## Drapeaux passés aux gestionnaires de sortie

Le masque de bits passé au deuxième paramètre `phase` du gestionnaire de sortie fournit des informations sur l'invocation du gestionnaire.

> Note: Le masque de bits peut inclure plus d'un drapeau et l'opérateur `&` doit être utilisé pour vérifier si un drapeau est défini.

Avertissement

La valeur de `PHP_OUTPUT_HANDLER_WRITE` et son alias `PHP_OUTPUT_HANDLER_CONT` est `0` donc si elle est définie ne peut être déterminée qu'en utilisant un opérateur d'égalité (`==` ou `===`).

Les drapeaux suivants sont définis dans une phase spécifique du cycle de vie du gestionnaire : `PHP_OUTPUT_HANDLER_START` est défini lorsqu'un gestionnaire est invoqué pour la première fois. `PHP_OUTPUT_HANDLER_FINAL` ou son alias `PHP_OUTPUT_HANDLER_END` est défini lorsqu'un gestionnaire est invoqué pour la dernière fois, c'est-à-dire qu'il est désactivé. Ce drapeau est également défini lorsque les tampons sont désactivés par le processus de terminaison de PHP.

Les drapeaux suivants sont définis par une invocation spécifique du gestionnaire : `PHP_OUTPUT_HANDLER_FLUSH` est défini lorsqu'un gestionnaire est invoqué en appelant ob_flush(). `PHP_OUTPUT_HANDLER_WRITE` ou son alias `PHP_OUTPUT_HANDLER_CONT` est défini lorsque la taille de son contenu est égale ou dépasse la taille du tampon et que le gestionnaire est invoqué pendant que le tampon est automatiquement lavé. `PHP_OUTPUT_HANDLER_CLEAN` est défini lorsqu'un gestionnaire est invoqué en appelant ob_clean(), ob_end_clean() ou ob_get_clean(). Lorsque ob_end_clean() ou ob_get_clean() est appelé, `PHP_OUTPUT_HANDLER_FINAL` est également défini.

> Note: Lorsque ob_end_flush() ou ob_get_flush() est appelé, `PHP_OUTPUT_HANDLER_FINAL` est défini mais `PHP_OUTPUT_HANDLER_FLUSH` ne l'est pas.

## Valeurs de retour des gestionnaires de sortie

La valeur de retour du gestionnaire de sortie est internement coercée en une chaîne suivant les sémantiques de type PHP standard, avec deux exceptions : les arrays et les booléens.

Les tableaux sont convertis en la chaîne `"Array"` mais le message d'avertissement `"Conversion d'un tableau en chaîne"` n'est pas déclenché.

Si le gestionnaire de sortie retourne `false` le contenu du tampon est retourné. Si le gestionnaire retourne `true` une chaîne vide est retournée.

> Note: Si un gestionnaire retourne `false` ou lance une exception son drapeau `PHP_OUTPUT_HANDLER_DISABLED` est défini.

## Exceptions lancées dans les gestionnaires de sortie

Si une exception non capturée est lancée dans un gestionnaire de sortie le programme se termine et le gestionnaire est invoqué par le processus de terminaison après quoi le message d'erreur `"Uncaught Exception"` est retourné.

Si l'exception non capturée est lancée dans un gestionnaire invoqué par ob_flush(), ob_end_flush() ou ob_get_flush(), le contenu du tampon est lavé avant le message d'erreur.

Si une exception non capturée est lancée dans un gestionnaire de sortie pendant la terminaison, le gestionnaire est terminé et ni le contenu du tampon ni le message d'erreur ne sont lavés.

> Note: Si un gestionnaire lance une exception son drapeau `PHP_OUTPUT_HANDLER_DISABLED` est défini.

## Erreurs levées dans les gestionnaires de sortie

Si une erreur non fatale est levée dans un gestionnaire de sortie le programme continue son exécution.

Si une erreur non fatale est levée dans un gestionnaire invoqué par ob_flush(), ob_end_flush() ou ob_get_flush(), le tampon vide certaines données en fonction de la valeur de retour du gestionnaire. Si le gestionnaire retourne `false` le tampon et le message d'erreur sont lavés. Si le gestionnaire retourne autre chose, la valeur de retour du gestionnaire est lavée mais pas le message d'erreur.

> Note: Si un gestionnaire retourne `false` son drapeau `PHP_OUTPUT_HANDLER_DISABLED` est défini.

Si une erreur fatale est levée dans un gestionnaire de sortie le programme se termine et le gestionnaire est invoqué par le processus de terminaison après quoi le message d'erreur est lavé.

Si l'erreur fatale est levée dans un gestionnaire invoqué par ob_flush(), ob_end_flush() ou ob_get_flush(), le contenu du tampon est lavé avant le message d'erreur.

Si une erreur fatale est levée dans un gestionnaire de sortie pendant la terminaison le programme se termine sans laver le contenu du tampon ou le message d'erreur.

## Sortie dans les gestionnaires de sortie

Dans des circonstances spécifiques, la sortie produite dans le gestionnaire est lavée avec le contenu du tampon. Cette sortie n'est pas ajoutée au tampon et ne fait pas partie de la chaîne retournée par ob_get_flush().

Durant les opérations de vidage de tampon (appel de ob_flush(), ob_end_flush(), ob_get_flush() et pendant la terminaison) si la valeur de retour d'un gestionnaire est `false` le contenu du tampon est lavé suivi de la sortie. Si le gestionnaire n'est pas invoqué pendant la terminaison le gestionnaire lançant une exception ou l'appel de exit() résulte dans le même comportement.

> Note: Si un gestionnaire retourne `false` son drapeau `PHP_OUTPUT_HANDLER_DISABLED` est défini.

## Drapeaux d'état des gestionnaires de sortie

Les drapeaux d'état des gestionnaires du masque de bits `flags` du tampon sont définis à chaque invocation du gestionnaire de sortie et font partie du masque de bits `flags` retourné par ob_get_status(). Si le gestionnaire exécute avec succès et ne retourne pas `false`, `PHP_OUTPUT_HANDLER_STARTED` et `PHP_OUTPUT_HANDLER_PROCESSED` sont définis. Si le gestionnaire retourne `false` ou lance une exception pendant l'exécution, `PHP_OUTPUT_HANDLER_STARTED` et `PHP_OUTPUT_HANDLER_DISABLED` sont définis.

> Note: Si `PHP_OUTPUT_HANDLER_DISABLED` d'un gestionnaire est défini, le gestionnaire ne sera pas invoqué en appelant ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() ou pendant le processus de terminaison de PHP. Avant PHP 8.4.0, ce drapeau n'avait aucun effet lors de l'appel de la fonction ob_clean() ou ob_flush().

# Exemples

## Sommaire

- Utilisation simple
- Utilisation de la réécriture de sortie

## Utilisation simple

Exemple #1 Exemple de bufferisation de sortie

    <?php

    ob_start();
    echo "Bonjour\n";

    setcookie("cookiename", "cookiedata");

    ob_end_flush();

    ?>

Dans l'exemple ci-dessus, l'instruction echo est stockée dans un buffer jusqu'à l'appel de la fonction ob_end_flush(). Dans le même temps, l'appel à setcookie() a réussi à créer un cookie, sans générer d'erreur. (Normalement, les en-têtes doivent être envoyés au navigateur avant les données).

## Utilisation de la réécriture de sortie

À partir de PHP 7.1.0, output_add_rewrite_var(), output_reset_rewrite_vars() utilisent un tampon de sortie dédié. C'est-à-dire qu'elles n'utilisent pas de tampon de sortie trans sid.

Exemple #1 Exemple de réécriture de la sortie

    <?php
    // Ce code fonctionne avec PHP 7.1.0, 7.0.10, 5.6.25 et supérieur.

    // HTTP_HOST est l'hôte cible par défaut. Définir manuellement pour que l'exemple de code fonctionne.
    $_SERVER['HTTP_HOST'] = 'php.net';

    // La réécriture de la sortie ne peut réécrire que les formulaires. Ajouter a=href.
    // Les balises peuvent être spécifiées tag_name=url_attr, par ex. img=src,iframe=src
    // Aucun espace autorisé entre les paramètres.
    // La balise form est une balise spéciale qui ajoute un champ caché.
    ini_set('url_rewriter.tags','a=href,form=');
    var_dump(ini_get('url_rewriter.tags'));

    // Ceci est ajouté à l'URL et au formulaire
    output_add_rewrite_var('test', 'value');
    ?>
    <a href="//php.net/index.php?bug=1234">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post">
     <input type="text" name="title" />
    </form>

L'exemple ci-dessus va afficher :

    <a href="//php.net/?bug=1234&test=value">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post"><input type="hidden" name="test" value="value" />
     <input type="text" name="title" />
    </form>

À partir de PHP 7.1.0, les fonctions de réécriture de sortie ont leurs propres paramètres INI, url_rewriter.tags et url_rewriter.hosts.

# Fonctions de bufferisation de sortie

# Voir aussi

Voir aussi header() et setcookie().

# flush

(PHP 4, PHP 5, PHP 7, PHP 8)

flush — Vide les tampons de sortie du système

### Description

function flush(): void

Vide les tampons d'écriture système de PHP et du backend utilisé par PHP (par exemple : CGI, un serveur web). Dans un environnement en ligne de commande, flush() tentera de vider uniquement le contenu des tampons, tandis que dans un contexte web, les en-têtes et le contenu des tampons sont vidés.

> Note: flush() peut ne pas pouvoir contourner le schéma de mise en mémoire tampon du serveur web et n'a aucun effet sur une mise en mémoire tampon côté client dans le navigateur.

> Note: Cette fonction n'a aucun effet sur les gestionnaires de sortie de niveau utilisateur tels que ceux démarrés par ob_start() ou output_add_rewrite_var().

Avertissement

flush() peut interférer avec les gestionnaires de sortie qui définissent et envoient des en-têtes dans un contexte web (par exemple, ob_gzhandler()) en envoyant des en-têtes avant que ces gestionnaires ne puissent le faire.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.4.0 | L'envoi des en-têtes sans corps réussira désormais en FastCGI.

### Voir aussi

- ob_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif.
- ob_clean() - Nettoyer (effacer) le contenu du tampon de sortie actif.
- ob_end_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif
- ob_end_clean() - Effacez (nettoyez) le contenu du tampon de sortie actif et désactivez-le.

# ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_clean — Nettoyer (effacer) le contenu du tampon de sortie actif.

### Description

function ob_clean(): bool

Cette fonction appelle le gestionnaire de sortie (avec le drapeau `PHP_OUTPUT_HANDLER_CLEAN`), ignore sa valeur de retour et nettoie (efface) le contenu du tampon de sortie actif.

Cette fonction ne désactive pas le tampon de sortie actif comme le font ob_end_clean() ou ob_get_clean().

ob_clean() échouera sans un tampon de sortie actif démarré avec le drapeau `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si la fonction échoue, elle génère une `E_NOTICE`.

### Voir aussi

- ob_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif.
- ob_end_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif
- ob_end_clean() - Effacez (nettoyez) le contenu du tampon de sortie actif et désactivez-le.

# ob_end_clean

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_clean — Effacez (nettoyez) le contenu du tampon de sortie actif et désactivez-le.

### Description

function ob_end_clean(): bool

Cette fonction appelle le gestionnaire de sortie (avec les drapeaux `PHP_OUTPUT_HANDLER_CLEAN` et `PHP_OUTPUT_HANDLER_FINAL`), ignore sa valeur de retour, ignore le contenu du tampon de sortie actif et désactive ce dernier.

ob_end_clean() échouera sans un tampon de sortie actif démarré avec le drapeau `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_end_clean() supprimera le contenu du tampon de sortie actif même s'il a été démarré sans le drapeau `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si la fonction échoue, elle génère une `E_NOTICE`.

### Exemples

L'exemple suivant montre une manière simple de se débarrasser du contenu du tampon de sortie actif :

Exemple #1 Exemple avec ob_end_clean()

    <?php
    ob_start();
    echo 'Texte qui ne sera pas affiché.';
    ob_end_clean();
    ?>

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie
- ob_get_contents() - Retourne le contenu du tampon de sortie
- ob_clean() - Nettoyer (effacer) le contenu du tampon de sortie actif.
- ob_get_clean() - Obtient le contenu du tampon de sortie actif et désactive-le
- ob_end_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif

# ob_end_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_flush — Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif

### Description

function ob_end_flush(): bool

Cette fonction appelle le gestionnaire de sortie (avec le drapeau `PHP_OUTPUT_HANDLER_FINAL`), vide (envoie) sa valeur de retour, ignore le contenu du tampon de sortie actif et désactive ce dernier.

ob_end_flush() échouera sans un tampon de sortie actif démarré avec le drapeau `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_end_flush() videra (enverra) la valeur de retour du gestionnaire de sortie même si le tampon de sortie actif a été démarré sans le drapeau `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si la fonction échoue, elle génère une `E_NOTICE`.

### Exemples

Exemple #1 Exemple avec ob_end_flush()

L'exemple ci-dessous montre une méthode simple pour vider tous les tampons :

    <?php
    while (@ob_end_flush());
    ?>

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie
- ob_get_contents() - Retourne le contenu du tampon de sortie
- ob_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif.
- ob_get_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif, renvoie le contenu du tampon de sortie actif et le désactive.
- ob_end_clean() - Effacez (nettoyez) le contenu du tampon de sortie actif et désactivez-le.

# ob_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flush — Vide (envoie) la valeur de retour du gestionnaire de sortie actif.

### Description

function ob_flush(): bool

Cette fonction appelle le gestionnaire de sortie (avec le drapeau `PHP_OUTPUT_HANDLER_FLUSH`), vide (envoie) sa valeur de retour et ignore le contenu du tampon de sortie actif.

Cette fonction ne désactive pas le tampon de sortie actif comme le font ob_end_flush() ou ob_get_flush().

ob_flush() échouera sans un tampon de sortie actif démarré avec le drapeau `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si la fonction échoue, elle génère une `E_NOTICE`.

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie
- ob_get_contents() - Retourne le contenu du tampon de sortie
- ob_end_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif
- ob_get_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif, renvoie le contenu du tampon de sortie actif et le désactive.
- ob_clean() - Nettoyer (effacer) le contenu du tampon de sortie actif.

# ob_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_clean — Obtient le contenu du tampon de sortie actif et désactive-le

### Description

function ob_get_clean(): string|false

Cette fonction appelle le gestionnaire de sortie (avec les drapeaux `PHP_OUTPUT_HANDLER_CLEAN` et `PHP_OUTPUT_HANDLER_FINAL`), ignore sa valeur de retour, retourne le contenu du tampon de sortie actif et désactive ce dernier.

ob_get_clean() échouera sans un tampon de sortie actif démarré avec le drapeau `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_get_clean() supprimera le contenu du tampon de sortie actif même s'il a été démarré sans le drapeau `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le contenu du tampon de sortie actif en cas de succès ou `false` en cas d'échec.

Attention

ob_get_clean() renverra false mais ne générera pas de `E_NOTICE` s'il n'y a pas de tampon de sortie actif.

### Erreurs / Exceptions

Si la fonction échoue, elle génère une `E_NOTICE`.

### Exemples

Exemple #1 Exemple avec ob_get_clean()

    <?php

    ob_start();

    echo "Bonjour le monde !";

    $out = ob_get_clean();
    $out = strtolower($out);

    var_dump($out);
    ?>

L'exemple ci-dessus va afficher :

    string(18) "bonjour le monde !"

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie
- ob_get_contents() - Retourne le contenu du tampon de sortie
- ob_clean() - Nettoyer (effacer) le contenu du tampon de sortie actif.
- ob_end_clean() - Effacez (nettoyez) le contenu du tampon de sortie actif et désactivez-le.
- ob_get_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif, renvoie le contenu du tampon de sortie actif et le désactive.

# ob_get_contents

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_get_contents — Retourne le contenu du tampon de sortie

### Description

function ob_get_contents(): string|false

Retourne le contenu du tampon de sortie sans l'effacer.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le contenu du tampon de sortie sans l'effacer ou `false`, si la temporisation de sortie n'est pas activée.

### Exemples

Exemple #1 Exemple avec ob_get_contents()

    <?php

    ob_start();

    echo "Bonjour ";

    $out1 = ob_get_contents();

    echo "le monde !";

    $out2 = ob_get_contents();

    ob_end_clean();

    var_dump($out1, $out2);
    ?>

L'exemple ci-dessus va afficher :

    string(8) "Bonjour "
    string(18) "Bonjour le monde !"

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie
- ob_get_length() - Retourne la longueur du contenu du tampon de sortie

# ob_get_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flush — Vide (envoie) la valeur de retour du gestionnaire de sortie actif, renvoie le contenu du tampon de sortie actif et le désactive.

### Description

function ob_get_flush(): string|false

Cette fonction appelle le gestionnaire de sortie (avec le drapeau `PHP_OUTPUT_HANDLER_FINAL`), envoie (vide) sa valeur de retour, renvoie le contenu du tampon de sortie actif et désactive le tampon de sortie actif.

ob_get_flush() échouera sans un tampon de sortie actif démarré avec le drapeau `PHP_OUTPUT_HANDLER_REMOVABLE`.

ob_get_flush() videra (enverra) la valeur de retour du gestionnaire de sortie même si le tampon de sortie actif a été démarré sans le drapeau `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le contenu du tampon de sortie actif en cas de succès ou `false` en cas d'échec.

### Erreurs / Exceptions

En cas d'échec de la fonction, elle génère une `E_NOTICE`.

### Exemples

Exemple #1 Exemple avec ob_get_flush()

    <?php
    //Utilisation de output_buffering=On
    print_r(ob_list_handlers());

    //Sauvegarde du tampon dans un fichier
    $buffer = ob_get_flush();
    file_put_contents('buffer.txt', $buffer);

    print_r(ob_list_handlers());
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => default output handler
    )
    Array
    (
    )

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie
- ob_get_contents() - Retourne le contenu du tampon de sortie
- ob_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif.
- ob_end_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif
- ob_get_clean() - Obtient le contenu du tampon de sortie actif et désactive-le

# ob_get_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_length — Retourne la longueur du contenu du tampon de sortie

### Description

function ob_get_length(): int|false

Retourne la longueur du contenu du tampon de sortie, en octets.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la longueur du contenu du tampon de sortie, en octets, si la temporisation est activée, et `false` sinon.

### Exemples

Exemple #1 Exemple avec ob_get_length()

    <?php

    ob_start();

    echo "Bonjour ";

    $len1 = ob_get_length();

    echo "le monde";

    $len2 = ob_get_length();

    ob_end_clean();

    echo $len1 . ", " . $len2;
    ?>

L'exemple ci-dessus va afficher :

    8, 16

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie
- ob_get_contents() - Retourne le contenu du tampon de sortie

# ob_get_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_level — Retourne le nombre de niveaux d'imbrications du système de temporisation de sortie

### Description

function ob_get_level(): int

Retourne le nombre de niveaux d'imbrications du système de temporisation de sortie.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de niveaux d'imbrications du système de temporisation de sortie, et zéro s'il n'est pas actif.

Attention

La valeur pour les niveaux identiques entre ob_get_level() et ob_get_status() diffère d'un. Pour ob_get_level(), le premier niveau est `1`. Tandis que pour ob_get_status(), le premier niveau est `0`.

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie
- ob_get_status() - Lit le statut du tampon de sortie
- ob_get_contents() - Retourne le contenu du tampon de sortie

# ob_get_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_status — Lit le statut du tampon de sortie

### Description

function ob_get_status(bool `$full_status` = `false`): array

ob_get_status() retourne les informations sur le statut du tampon d'affichage de haut niveau ou de tous les tampons d'affichage si `full_status` est défini à `true`.

### Liste de paramètres

`full_status`

  `true` pour retourner tous les tampons d'affichage. Si vaut `false` ou non défini, seul le statut du tampon d'affichage de haut niveau sera retourné.

### Valeurs de retour

Si le paramètre `full_status` est omis ou égal à `false`, un simple tableau contenant des informations sur l'état du niveau de sortie actif est retourné.

Si le paramètre `full_status` est égal à `true`, un tableau avec un élément pour chaque niveau de tampon de sortie actif est retourné. Le niveau de sortie est utilisé comme clé du tableau de niveau supérieur et chaque élément du tableau est lui-même un autre tableau contenant des informations sur un niveau de sortie actif.

Un tableau vide est retourné si la mise en mémoire tampon de sortie n'est pas activée.

Éléments retournés par la fonction ob_get_status()
Clé | Valeur
--- | ---
name | Nom du gestionnaire de sortie actif (voir les valeurs de retour de ob_list_handlers() pour plus de détails)
type | `0` (gestionnaire interne) ou `1` (gestionnaire fourni par l'utilisateur)
flags | Masque de bits des indicateurs définis par la fonction ob_start(), le type de gestionnaire de sortie (voir ci-dessus) et l'état du processus de mise en mémoire tampon ( `PHP_OUTPUT_HANDLER_*` constantes). Si le gestionnaire a traité avec succès le tampon et n'a pas retourné `false`, `PHP_OUTPUT_HANDLER_STARTED` et `PHP_OUTPUT_HANDLER_PROCESSED` seront définis. Si le gestionnaire a échoué lors du traitement du tampon ou a retourné `false`, `PHP_OUTPUT_HANDLER_STARTED` et `PHP_OUTPUT_HANDLER_DISABLED` seront définis.
level | Niveau d'imbrication de la sortie (à partir de zéro). Il est à noter que la valeur retournée pour le même niveau par la fonction ob_get_level() est décalée d'un. Le premier niveau est `0` pour ob_get_status(), et `1` pour ob_get_level().
chunk_size | Taille du fragment en octets. Définie par la fonction ob_start() ou output_buffering s'il est activé et sa valeur est définie sur un entier positif
buffer_size | Taille du tampon de sortie en octets
buffer_used | Taille des données dans le tampon de sortie en octets (la même que la valeur de retour entière de ob_get_length())

### Exemples

Exemple #1 Tableau retourné lorsque le paramètre `full_status` est égal à `false`

    Array
    (
        [name] => URL-Rewriter
        [type] => 0
        [flags] => 112
        [level] => 2
        [chunk_size] => 0
        [buffer_size] => 16384
        [buffer_used] => 1024
    )

Exemple #2 Tableau retourné lorsque le paramètre `full_status` est égal à `true`

    Array
    (
        [0] => Array
            (
                [name] => default output handler
                [type] => 0
                [flags] => 112
                [level] => 1
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 2048
            )

        [1] => Array
            (
                [name] => URL-Rewriter
                [type] => 0
                [flags] => 112
                [level] => 2
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 1024
            )

    )

### Voir aussi

- ob_get_level() - Retourne le nombre de niveaux d'imbrications du système de temporisation de sortie
- ob_list_handlers() - Liste les gestionnaires d'affichage utilisés
- ob_get_length() - Retourne la longueur du contenu du tampon de sortie
- ob_start() - Enclenche la temporisation de sortie

# ob_implicit_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_implicit_flush — Active/désactive l'envoi implicite

### Description

function ob_implicit_flush(bool `$enable` = `true`): void

ob_implicit_flush() active/désactive l'envoi implicite. Le vidage implicite entraînera une opération de vidage après chaque bloc de code produisant une sortie, de sorte que des appels explicites à flush() ne seront plus nécessaires.

> Note: Afficher des chaînes vides ou envoyer des en-têtes n'est pas considéré comme une sortie et ne déclenchera pas d'opération de vidage.

> Note: Cette fonction n'a aucun effet sur les gestionnaires de sortie de niveau utilisateur, tels que ceux démarrés par ob_start() ou output_add_rewrite_var().

### Liste de paramètres

`enable`

  `true` pour activer, `false` sinon.

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | `enable` attend une valeur bool désormais ; auparavant, un int était attendu.

### Voir aussi

- flush() - Vide les tampons de sortie du système
- ob_start() - Enclenche la temporisation de sortie
- ob_end_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif

# ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlers — Liste les gestionnaires d'affichage utilisés

### Description

function ob_list_handlers(): array

Liste les gestionnaires d'affichage utilisés.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau avec le gestionnaire d'affichage en cours d'utilisation (s'il existe).

Si output_buffering est activé et qu'aucun output_handler n'est défini, ou si aucune fonction de rappel ou `null` n'a été passé à ob_start(), `"default output handler"` est renvoyé. Activer output_buffering et définir un output_handler équivaut à passer une fonction interne (intégrée) à ob_start().

Si un callable a été passé à ob_start(), le nom complètement qualifié du callable est renvoyé. Si le callable est un objet implémentant __invoke(), le nom complètement qualifié de la méthode __invoke() de l'objet est renvoyé. Si le callable est une Closure, `"Closure::__invoke"` est renvoyé.

### Exemples

Exemple #1 Exemple avec ob_list_handlers()

    <?php
    // utilisation output_buffering=On, sans output_handler défini
    var_dump(ob_list_handlers());
    ob_end_flush();

    // aucun rappel ou null
    ob_start();
    var_dump(ob_list_handlers());
    ob_end_flush();

    // Fonction anonyme
    ob_start(function($string) { return $string; });
    var_dump(ob_list_handlers());
    ob_end_flush();

    // fonction fléchée
    ob_start(fn($string) => $string);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // callable de première classe
    $firstClassCallable = userDefinedFunction(...);

    ob_start([$firstClassCallable, '__invoke']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // fonction interne (intégrée)
    ob_start('print_r');
    var_dump(ob_list_handlers());
    ob_end_flush();

    // fonction définie par l'utilisateur
    function userDefinedFunction($string, $flags) { return $string; };

    ob_start('userDefinedFunction');
    var_dump(ob_list_handlers());
    ob_end_flush();

    class MyClass {
        public static function staticHandle($string) {
            return $string;
        }

        public static function handle($string) {
            return $string;
        }

        public function __invoke($string) {
            return $string;
        }
    }

    // classe et méthode statique
    ob_start(['MyClass','staticHandle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // objet et méthode non statique
    ob_start([new MyClass,'handle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // objet invoquable
    ob_start(new MyClass);
    var_dump(ob_list_handlers());
    ob_end_flush();
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(7) "print_r"
    }
    array(1) {
      [0]=>
      string(19) "userDefinedFunction"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(21) "MyClass::staticHandle"
    }
    array(1) {
      [0]=>
      string(15) "MyClass::handle"
    }
    array(1) {
      [0]=>
      string(17) "MyClass::__invoke"
    }

### Voir aussi

- ob_end_clean() - Effacez (nettoyez) le contenu du tampon de sortie actif et désactivez-le.
- ob_end_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif
- ob_get_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif, renvoie le contenu du tampon de sortie actif et le désactive.
- ob_start() - Enclenche la temporisation de sortie

# ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — Enclenche la temporisation de sortie

### Description

function ob_start(?callable `$callback` = `null`, int `$chunk_size` = 0, int `$flags` = `PHP_OUTPUT_HANDLER_STDFLAGS`): bool

Cette fonction active la mise en mémoire tampon de la sortie. Lorsque la mise en mémoire tampon est active, aucune sortie n'est envoyée depuis le script ; au lieu de cela, la sortie est stockée dans une mémoire tampon interne. Consulter Quelle sortie est bufferisée ? pour savoir exactement quelles sorties sont concernées.

Les tampons de sortie sont empilables, c'est-à-dire ob_start() peut être appelée pendant qu'un autre tampon est actif. Si plusieurs tampons de sortie sont actifs, la sortie est filtrée séquentiellement à travers chacun d'eux dans l'ordre d'emboîtement. Consulter Imbrication des tampons de sortie pour plus de détails.

Consulter Tampons de sortie au niveau utilisateur pour une description détaillée des tampons de sortie.

### Liste de paramètres

`callback`

  Un `callback` callable optionnel peut être spécifié. Il peut également être contourné en passant `null`.

  `callback` est invoqué lorsque le tampon de sortie est vidé (envoyé), nettoyé, ou lorsque le tampon de sortie est vidé à la fin du script.

  La signature du `callback` est la suivante :

  function handler(string `$buffer`, int `$phase` = ?): string
  `buffer`
    Contenu du buffer de sortie.
  `phase`
    Masque de bits des constantes `PHP_OUTPUT_HANDLER_*` . Consulter Drapeaux passés aux gestionnaires de sortie pour plus de détails.

  Si `callback` renvoie `false`, le contenu du tampon est renvoyé. Consulter Valeurs de retour des gestionnaires de sortie pour plus de détails.

  Avertissement

  Appeler l'une des fonctions suivantes à partir d'un gestionnaire de sortie entraînera une erreur fatale : ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

  Consulter Gestionnaires de sortie et Travailler avec les gestionnaires de sortie pour plus de détails sur les `callback`s (gestionnaires de sortie).

`chunk_size`

  Si le paramètre optionnel `chunk_size` est passé, la mémoire tampon sera vidée après tout bloc de code résultant en une sortie qui fait que la longueur de la mémoire tampon égale ou dépasse `chunk_size`. La valeur par défaut `0` signifie que toute la sortie est mise en mémoire tampon jusqu'à ce que la mémoire tampon soit désactivée. Consulter Taille du tampon pour plus de détails.

`flags`

  Le paramètre `flags` est un masque qui contrôle les opérations qui peuvent être effectuées sur le tampon de sortie. Par défaut, il autorise le tampon de sortie à être nettoyé, envoyé et supprimé, ce qui peut être défini explicitement avec les indicateurs de contrôle de la mémoire tampon . Consulter Opérations autorisées sur les tampons pour plus de détails.

  Chaque drapeau contrôle l'accès à un jeu de fonctions, tel que décrit ci-dessous :

  Constante | Fonctions
  --- | ---
  `PHP_OUTPUT_HANDLER_CLEANABLE` | ob_clean(),
  `PHP_OUTPUT_HANDLER_FLUSHABLE` | ob_flush(),
  `PHP_OUTPUT_HANDLER_REMOVABLE` | ob_end_clean(), ob_end_flush() et ob_get_clean(). ob_get_flush().

  > Note: Avant PHP 8.4.0, le paramètre flags pouvait définir les drapeaux d'état du gestionnaire de sortie également.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de gestion de sortie avec fonction de rappel

    <?php

    function rappel($buffer)
    {
      // remplace toutes les pommes par des carottes
      return (str_replace("pommes de terre", "carottes", $buffer));
    }

    ob_start("rappel");

    ?>
    <html>
    <body>
    <p>C'est comme comparer des carottes et des pommes de terre.</p>
    </body>
    </html>
    <?php

    ob_end_flush();

    ?>

L'exemple ci-dessus va afficher :

    <html>
    <body>
    <p>C'est comme comparer des carottes et des carottes.</p>
    </body>
    </html>

Exemple #2 Crée un tampon de sortie ineffaçable

    <?php

    ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

    ?>

### Voir aussi

- ob_get_contents() - Retourne le contenu du tampon de sortie
- ob_end_clean() - Effacez (nettoyez) le contenu du tampon de sortie actif et désactivez-le.
- ob_end_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif
- ob_implicit_flush() - Active/désactive l'envoi implicite
- ob_gzhandler() - Fonction de rappel pour la compression automatique des tampons
- ob_iconv_handler() - Gestionnaire de sortie pour maîtriser le jeu de caractères de sortie
- mb_output_handler() - Fonction de traitement des affichages
- ob_tidyhandler() - Fonction de rappel ob_start pour réparer le buffer

# output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_add_rewrite_var — Ajoute une règle de réécriture d'URL

### Description

function output_add_rewrite_var(string `$name`, string `$value`): bool

Cette fonction démarre le gestionnaire de tampon de sortie `'URL-Rewriter'` s'il n'est pas actif, stocke les paramètres `name` et `value`, et lorsque le tampon est vidé, réécrit les URLs et les formulaires en fonction des paramètres ini applicables. Les appels ultérieurs à cette fonction stockeront toutes les paires nom/valeur supplémentaires jusqu'à ce que le gestionnaire soit désactivé.

Lorsque le tampon de sortie est vidé (en appelant ob_flush(), ob_end_flush(), ob_get_flush() ou à la fin du script), le gestionnaire `'URL-Rewriter'` ajoute les paires nom/valeur en tant que paramètres de requête aux URLs dans les attributs des balises HTML et ajoute des champs cachés aux formulaires en fonction des valeurs des directives de configuration url_rewriter.tags et url_rewriter.hosts.

Chaque paire nom/valeur ajoutée au gestionnaire `'URL-Rewriter'` est ajoutée aux URLs et/ou formulaires même si cela résulte en des paramètres de requête d'URL dupliqués ou des éléments avec les mêmes attributs de nom.

> Note: Une fois que le gestionnaire `'URL-Rewriter'` a été désactivé, il ne peut pas être redémarré.

Avertissement

Antérieur à PHP 8.4.0, les hôtes à réécrire étaient définis dans session.trans_sid_hosts à la place de url_rewriter.hosts.

### Liste de paramètres

`name`

  Le nom de la variable.

`value`

  La valeur de la variable.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.1.0 | À partir de PHP 7.1.0, un tampon de sortie dédié est utilisé, url_rewriter.tags est utilisé uniquement pour les fonctions de sortie et url_rewriter.hosts est disponible. Antérieur à PHP 7.1.0, les variables de réécriture définies par output_add_rewrite_var() partageaient un tampon de sortie avec la prise en charge transparente de l'ID de session (voir session.trans_sid_tags).

### Exemples

Exemple #1 Exemple avec output_add_rewrite_var()

    <?php
    ini_set('url_rewriter.tags', 'a=href,form=');

    output_add_rewrite_var('var', 'value');

    // Quelques liens
    echo '<a href="file.php">link</a>
    <a href="http://example.com">link2</a>';

    // un formulaire
    echo '<form action="script.php" method="post">
    <input type="text" name="var2" />
    </form>';

    print_r(ob_list_handlers());
    ?>

L'exemple ci-dessus va afficher :

    <a href="file.php?var=value">link</a>
    <a href="http://example.com">link2</a>

    <form action="script.php" method="post">
    <input type="hidden" name="var" value="value" />
    <input type="text" name="var2" />
    </form>

    Array
    (
        [0] => URL-Rewriter
    )

### Voir aussi

- output_reset_rewrite_vars() - Annule la réécriture d'URL
- ob_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif.
- ob_list_handlers() - Liste les gestionnaires d'affichage utilisés
- url_rewriter.tags
- url_rewriter.hosts

# output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_reset_rewrite_vars — Annule la réécriture d'URL

### Description

function output_reset_rewrite_vars(): bool

Cette fonction supprime toutes les variables de réécriture précédemment définies par la fonction output_add_rewrite_var().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.1.0 | Avant PHP 7.1.0, les variables de réécriture définies par output_add_rewrite_var() utilisaient la même mémoire tampon de sortie du module de session trans sid. À partir de PHP 7.1.0, la mémoire tampon de sortie dédiée est utilisée et output_reset_rewrite_vars() supprime uniquement les vars de réécriture définies par output_add_rewrite_var().

### Exemples

Exemple #1 Exemple avec output_reset_rewrite_vars()

    <?php
    ini_set('url_rewriter.tags', 'a=href');

    output_add_rewrite_var('var', 'value');

    echo '<a href="file.php">link</a>';
    ob_flush();

    output_reset_rewrite_vars();
    echo '<a href="file.php">link</a>';
    ?>

L'exemple ci-dessus va afficher :

    <a href="file.php?var=value">link</a>
    <a href="file.php">link</a>

### Voir aussi

- output_add_rewrite_var() - Ajoute une règle de réécriture d'URL
- ob_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif.
- ob_list_handlers() - Liste les gestionnaires d'affichage utilisés
- url_rewriter.tags
- url_rewriter.hosts
- session.trans_sid_tags
- session.trans_sid_hosts

## Sommaire

- flush — Vide les tampons de sortie du système
- ob_clean — Nettoyer (effacer) le contenu du tampon de sortie actif.
- ob_end_clean — Effacez (nettoyez) le contenu du tampon de sortie actif et désactivez-le.
- ob_end_flush — Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif
- ob_flush — Vide (envoie) la valeur de retour du gestionnaire de sortie actif.
- ob_get_clean — Obtient le contenu du tampon de sortie actif et désactive-le
- ob_get_contents — Retourne le contenu du tampon de sortie
- ob_get_flush — Vide (envoie) la valeur de retour du gestionnaire de sortie actif, renvoie le contenu du tampon de sortie actif et le désactive.
- ob_get_length — Retourne la longueur du contenu du tampon de sortie
- ob_get_level — Retourne le nombre de niveaux d'imbrications du système de temporisation de sortie
- ob_get_status — Lit le statut du tampon de sortie
- ob_implicit_flush — Active/désactive l'envoi implicite
- ob_list_handlers — Liste les gestionnaires d'affichage utilisés
- ob_start — Enclenche la temporisation de sortie
- output_add_rewrite_var — Ajoute une règle de réécriture d'URL
- output_reset_rewrite_vars — Annule la réécriture d'URL

- Installation/Configuration
  - Configuration à l'exécution
- Constantes pré-définies
- Bufferisation de sortie
- Laver les tampons système
- Tampons de sortie au niveau utilisateur
  - Quelle sortie est bufferisée ?
  - Imbrication des tampons de sortie
  - Taille du tampon
  - Opérations autorisées sur les tampons
  - Gestionnaires de sortie
  - Travailler avec les gestionnaires de sortie
  - Drapeaux passés aux gestionnaires de sortie
  - Valeurs de retour des gestionnaires de sortie
- Exemples
  - Utilisation simple
  - Utilisation de la réécriture de sortie
- Fonctions de bufferisation de sortie
  - flush — Vide les tampons de sortie du système
  - ob_clean — Nettoyer (effacer) le contenu du tampon de sortie actif.
  - ob_end_clean — Effacez (nettoyez) le contenu du tampon de sortie actif et désactivez-le.
  - ob_end_flush — Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif
  - ob_flush — Vide (envoie) la valeur de retour du gestionnaire de sortie actif.
  - ob_get_clean — Obtient le contenu du tampon de sortie actif et désactive-le
  - ob_get_contents — Retourne le contenu du tampon de sortie
  - ob_get_flush — Vide (envoie) la valeur de retour du gestionnaire de sortie actif, renvoie le contenu du tampon de sortie actif et le désactive.
  - ob_get_length — Retourne la longueur du contenu du tampon de sortie
  - ob_get_level — Retourne le nombre de niveaux d'imbrications du système de temporisation de sortie
  - ob_get_status — Lit le statut du tampon de sortie
  - ob_implicit_flush — Active/désactive l'envoi implicite
  - ob_list_handlers — Liste les gestionnaires d'affichage utilisés
  - ob_start — Enclenche la temporisation de sortie
  - output_add_rewrite_var — Ajoute une règle de réécriture d'URL
  - output_reset_rewrite_vars — Annule la réécriture d'URL

# Options PHP et informations PHP

# Introduction

Ces fonctions donnent accès à de nombreuses informations sur PHP lui-même, comme les configurations d'exécution, les extensions chargées, les versions, etc. On trouvera aussi des fonctions pour modifier des options, ainsi que la star des fonctions PHP phpinfo().

# Installation/Configuration

## Sommaire

- Configuration à l'exécution

## Configuration à l'exécution

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

Options de configuration
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
assert.active | "1" | `INI_ALL` | Obsolète à partir de PHP 8.3.0
assert.bail | "0" | `INI_ALL` | Obsolète à partir de PHP 8.3.0
assert.warning | "1" | `INI_ALL` | Obsolète à partir de PHP 8.3.0
assert.callback | NULL | `INI_ALL` | Obsolète à partir de PHP 8.3.0
assert.quiet_eval | "0" | `INI_ALL` | Supprimé à partir de PHP 8.0.0
assert.exception | "1" | `INI_ALL` | Antérieur à PHP 8.0.0, la valeur par défaut est `"0"` Obsolète à partir de PHP 8.3.0
enable_dl | "1" | `INI_SYSTEM` | Cette fonctionnalité obsolète sera certainement supprimée dans le futur.
max_execution_time | "30" | `INI_ALL` |
max_input_time | "-1" | `INI_PERDIR` |
max_input_nesting_level | "64" | `INI_PERDIR` |
max_input_vars | 1000 | `INI_PERDIR` |
zend.enable_gc | "1" | `INI_ALL` |
zend.max_allowed_stack_size | "0" | `INI_SYSTEM` | Disponible à partir de PHP 8.3.0.
zend.reserved_stack_size | "0" | `INI_SYSTEM` | Disponible à partir de PHP 8.3.0.
fiber.stack_size |  | `INI_ALL` | Disponible à partir de PHP 8.1.0.

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`assert.active` bool

  Active les évaluations de type assert(). zend.assertions devrait être utilisé à la place pour contrôler le comportement de assert().

  Avertissement

  Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonctionnalité est fortement déconseillé.

`assert.bail` bool

  Termine le script si une assertion échoue.

  Avertissement

  Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonctionnalité est fortement déconseillé.

`assert.warning` bool

  Émet une alerte PHP pour chaque assertion qui échoue.

  Avertissement

  Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonctionnalité est fortement déconseillé.

`assert.callback` string

  Fonction définie par le programmeur, à appeler pour chaque assertion échouée.

  Avertissement

  Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonctionnalité est fortement déconseillé.

`assert.quiet_eval` bool
  Avertissement

  Cette fonctionnalité a été SUPPRIMÉE à partir de PHP 8.0.0.

  Utilise la configuration courante de error_reporting() durant les évaluations d'assertions. Si activée, aucune erreur n'est affichée (error_reporting(0) implicite) durant l'évaluation. Si désactivée, les erreurs sont affichées en fonction de la configuration de error_reporting()

`assert.exception` bool

  Lève une exception AssertionError lors d'une assertion échouée.

`enable_dl` bool

  Cette directive permet d'activer ou de désactiver le chargement dynamique d'extension PHP avec la fonction PHP dl().

  La raison principale pour désactiver ce système est la sécurité. Avec le chargement dynamique, il est possible de passer outre les restrictions imposées par open_basedir.

`max_execution_time` int

  Fixe le temps maximal d'exécution d'un script, en secondes. Cela permet d'éviter que des scripts en boucles infinies saturent le serveur. La configuration par défaut est de `30` secondes. Lorsque PHP fonctionne depuis la ligne de commande, la valeur par défaut est `0`.

  Sur les systèmes non-Windows, le temps d'exécution maximum n'est pas affecté par des appels systèmes tels que sleep(). Se reporter à la fonction set_time_limit() pour plus de détails.

  Le serveur web peut avoir d'autres configurations de la durée limite d'exécution qui peuvent également interrompre PHP. Apache a une directive `Timeout` et IIS a une fonction CGI pour cela. Par défaut, elles valent toutes les deux 300 secondes. Se reporter à la documentation du serveur web pour plus de détails.

`max_input_time` int

  Cette option spécifie la durée maximale pour analyser les données d'entrée, comme POST et GET. Cette durée est mesurée depuis le moment où PHP est invoqué sur le serveur jusqu'au début de l'exécution du script. La valeur par défaut est `-1`, ce qui veut dire que max_execution_time est utilisé à la place. Régler la valeur à `0` pour permettre une exécution illimitée.

`max_input_nesting_level` int

  Définit la profondeur maximale des variables d'entrées (c.-à-d. $_GET, $_POST..)

`max_input_vars` int

  Le nombre de variables d'entrée pouvant être acceptées (cette limite est appliquée aux variables superglobales $_GET, $_POST et $_COOKIE, séparément). L'utilisation de cette directive permet de limiter les possibilités d'attaque par déni de service utilisant des collisions d'hachages. S'il y a plus de variables en entrée que le nombre spécifié par cette directive, une alerte de type `E_WARNING` sera émise, et les variables en trop seront supprimées de la requête.

`zend.enable_gc` bool

  Active ou désactive la collecte des références circulaires.

`zend.max_allowed_stack_size` int

  La quantité maximale de mémoire de pile native (stack) autorisée par le système d’exploitation pour le programme. Tenter de consommer plus que le système ne le permet aboutit généralement à un plantage brutal, sans informations de débogage facilement disponibles. Pour faciliter le débogage, le moteur déclenche une Error avant que cela ne se produise (lorsque le programme utilise plus de zend.max_allowed_stack_size-zend.reserved_stack_size octets de pile).

  La récursion dans le code défini par l’utilisateur ne consomme pas de pile native. Cependant, les fonctions internes et les méthodes magiques, elles, consomment bien de la pile native. Une récursion très profonde impliquant ces fonctions peut faire que le programme épuise toute la mémoire de pile disponible.

  Les valeurs possibles pour ce paramètre sont :

  - `0` : Détecter automatiquement la mémoire de pile native maximale que le système d’exploitation autorise pour le programme. C’est la valeur par défaut. Lorsque la détection est impossible, une valeur par défaut du système est utilisée.
  - `-1` : Désactive la vérification de la taille de la pile dans le moteur.
  - Entier positif : Une taille fixe, en octets. Définir cette valeur trop élevée revient au même que de désactiver la vérification de la taille de la pile.

  Comme la taille de pile des fibers est déterminée par fiber.stack_size, la valeur de ce paramètre est utilisée à la place de zend.max_allowed_stack_size lors de la vérification de l’utilisation de la pile pendant l’exécution d’une Fiber.

  > Note:

  > Ceci n’a aucun lien avec les dépassements de tampon de la pile (stack buffer overflows), et n’est pas une fonctionnalité de sécurité.

`zend.reserved_stack_size` int

  La taille réservée de la pile, en octets. Celle-ci est soustraite de la taille de pile maximale autorisée, comme une marge de sécurité, lors de la vérification de la taille de la pile.

  Les valeurs possibles pour ce paramètre sont :

  - `0` : Détecter automatiquement une taille raisonnable.
  - Entier positif : Une taille fixe, en octets.
`fiber.stack_size` int

  La taille de la pile native, en octets, allouée à chaque Fiber.

  La valeur par défaut est de 1 Mio sur les systèmes dont la taille des pointeurs est inférieure à 8 octets, ou de 2 Mio sinon.

# Constantes pré-définies

Les constantes listées ici sont toujours disponibles dans PHP.

Constantes | Description
--- | ---
Constantes prédéfinies de phpcredits()
`CREDITS_GROUP` (int) | Une liste des développeurs principaux
`CREDITS_GENERAL` (int) | Crédits généraux. Design du langage, concepts, auteurs de PHP et module SAPI.
`CREDITS_SAPI` (int) | Une liste des API de serveurs, et leurs auteurs.
`CREDITS_MODULES` (int) | Une liste des extensions de PHP, et leurs auteurs
`CREDITS_DOCS` (int) | Les crédits de l'équipe de documentation
`CREDITS_FULLPAGE` (int) | Généralement utilisé combiné avec d'autres options. Cette option indique qu'une page HTML complète doit être générée.
`CREDITS_QA` (int) | Les crédits pour le groupe d'assurance qualité.
`CREDITS_ALL` (int) | Tous les crédits. C'est l'équivalent de : `CREDITS_DOCS | CREDITS_GENERAL | CREDITS_GROUP | CREDITS_MODULES | CREDITS_QA | CREDITS_FULLPAGE`. Elle génère une page HTML complète et autonome. C'est la valeur par défaut.

Constantes | Description
--- | ---
Constantes de phpinfo()
`INFO_GENERAL` (int) | La ligne de configuration, le chemin du php.ini, la date de compilation, le système et plus encore.
`INFO_CREDITS` (int) | Crédits de PHP. Voir aussi phpcredits().
`INFO_CONFIGURATION` (int) | Valeurs locales et serveurs des directives PHP. Voir aussi ini_get().
`INFO_MODULES` (int) | Les modules chargés et leurs configurations respectives.
`INFO_ENVIRONMENT` (int) | Les variables d'environnement, qui sont aussi disponibles dans $_ENV.
`INFO_VARIABLES` (int) | Toutes les variables prédéfinies : `EGPCS` (Environnement, GET, POST, Cookie, Server).
`INFO_LICENSE` (int) | La licence PHP. Voir aussi la » FAQ de la licence.
`INFO_ALL` (int) | Affiche toutes les valeurs citées ci-dessus. C'est la valeur par défaut.

Constantes | Description
--- | ---
Constantes mode INI
`INI_USER` (int) | Cette entrée peut être définie dans les scripts utilisateur (comme avec ini_set()) ou dans le registre Windows. L'entrée peut être définie dans le fichier .user.ini.
`INI_PERDIR` (int) | Cette entrée peut être définie dans le fichier php.ini, .htaccess, httpd.conf ou .user.ini.
`INI_SYSTEM` (int) | Cette entrée peut être définie dans le fichier php.ini ou httpd.conf.
`INI_ALL` (int) | Cette entrée peut être définie n'importe où.

Les constantes d'assertions servent avec la fonction assert_options().

Constantes | Description
--- | ---
Constantes d'assert()
`ASSERT_ACTIVE` (int) | Active l'évaluation assert(). Avertissement Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonctionnalité est fortement déconseillé.
`ASSERT_CALLBACK` (int) | Fonction de rappel des assertions échouées. Avertissement Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonctionnalité est fortement déconseillé.
`ASSERT_BAIL` (int) | Termine l'exécution des assertions échouées. Avertissement Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonctionnalité est fortement déconseillé.
`ASSERT_EXCEPTION` (int) | Lance une AssertionError pour chaque assertion échouée. Avertissement Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonctionnalité est fortement déconseillé.
`ASSERT_WARNING` (int) | Émet une alerte PHP pour chaque assertion échouée. Avertissement Cette fonctionnalité est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonctionnalité est fortement déconseillé.
`ASSERT_QUIET_EVAL` (int) | Désactive le `error_reporting` durant l'évaluation des expressions d'assertion. Avertissement Cette fonctionnalité a été SUPPRIMÉE à partir de PHP 8.0.0.

Les constantes suivantes ne sont disponibles que si le système d'hébergement est sur Windows, et peut donner des informations sur les versions, qui permettront de détecter la présence de fonctionnalités. Elles sont disponibles à partir de PHP 5.3.0.

Constantes | Description
--- | ---
Constantes particulières à Windows
`PHP_WINDOWS_VERSION_MAJOR` (int) | La version majeure de Windows, qui peut être `4` (NT4/Me/98/95), `5` (XP/2003 R2/2003/2000) ou `6` (Vista/2008/7/8/8.1).
`PHP_WINDOWS_VERSION_MINOR` (int) | La version mineure de Windows, qui peut être `0` (Vista/2008/2000/NT4/95), `1` (XP), `2` (2003 R2/2003/XP x64), `10` (98) ou `90` (ME).
`PHP_WINDOWS_VERSION_BUILD` (int) | Le numéro de compilation de Windows (par exemple, Windows Vista avec SP1 a le numéro 6001)
`PHP_WINDOWS_VERSION_PLATFORM` (int) | La plate-forme que PHP utilise actuellement : cette valeur peut être `2` sur Windows Vista/XP/2000/NT4, Server 2008/2003 et sur Windows ME/98/95 cette valeur est `1`.
`PHP_WINDOWS_VERSION_SP_MAJOR` (int) | La version majeure du paquet de service installé : cette valeur vaut `0` si aucun paquet de service n'est disponible. Par exemple, Windows XP avec le paquet de service 3 donne la valeur `3` à cette constante.
`PHP_WINDOWS_VERSION_SP_MINOR` (int) | La version mineure du paquet de service installé. Cette valeur est `0` si aucun paquet de service n'est installé.
`PHP_WINDOWS_VERSION_SUITEMASK` (int) | Le masque est un champ de bits qui permet de connaître la présence de différentes fonctionnalités de Windows. Voir la table ci-dessous pour connaître les différents champs.
`PHP_WINDOWS_VERSION_PRODUCTTYPE` (int) | Cette constante contient la valeur utilisée pour déterminer la valeur des constantes `PHP_WINDOWS_NT_*`. Cette valeur peut être l'une des constantes `PHP_WINDOWS_NT_*`, indiquant le type de plate-forme.
`PHP_WINDOWS_NT_DOMAIN_CONTROLLER` (int) | Le contrôleur de domaine.
`PHP_WINDOWS_NT_SERVER` (int) | Un serveur système (p. ex. `Server 2008/2003/2000`). Il est à noter que si c'est un contrôleur de domaine, il est indiqué dans `PHP_WINDOWS_NT_DOMAIN_CONTROLLER`.
`PHP_WINDOWS_NT_WORKSTATION` (int) | Un poste de travail (p. ex. `Vista/XP/2000/NT4`)

La table ci-dessous présente les fonctionnalités qui peuvent être vérifiées dans le champ de bit de la constante `PHP_WINDOWS_VERSION_SUITEMASK`.

Champs du masque Windows
Bits | Description
--- | ---
`0x00000004` | Les composants Microsoft BackOffice sont installés.
`0x00000400` | Windows Server 2003, Web Edition est installé.
`0x00004000` | Windows Server 2003, Compute Cluster Edition est installé.
`0x00000080` | Windows Server 2008 Datacenter, Windows Server 2003, Datacenter Edition ou Windows 2000 Datacenter Server est installé.
`0x00000002` | Windows Server 2008 Enterprise, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server, ou Windows NT Server 4.0 Enterprise Edition est installé.
`0x00000040` | Windows XP Embedded est installé.
`0x00000200` | Windows Vista Home Premium, Windows Vista Home Basic, ou Windows XP Home Edition est installé.
`0x00000100` | Remote Desktop est supporté, mais une seule session interactive est supportée. Cette valeur est présente, à moins que le système ne fonctionne en mode serveur d'application.
`0x00000001` | Microsoft Small Business Server a été installé sur le système, mais a été mis à jour vers une nouvelle version de Windows.
`0x00000020` | Microsoft Small Business Server est installé avec la licence cliente restreinte.
`0x00002000` | Windows Storage Server 2003 R2 ou Windows Storage Server 2003 est installé.
`0x00000010` | Terminal Services est installé. Cette valeur est toujours activée. Si cette valeur est activée, mais `0x00000100` ne l'est pas, alors le système fonctionne en mode de serveur d'application.
`0x00008000` | Windows Home Server est installé.

# Fonctions sur les options et les informations de PHP

# assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assert — Vérifie une assertion

### Description

function assert(mixed `$assertion`, Throwable|string|null `$description` = `null`): bool

assert() permet de définir des attentes : des assertions qui prennent effet dans les environnements de développement et de test, mais qui sont optimisées pour ne pas avoir de coût en production.

Les assertions peuvent être utilisées pour aider au débogage. Un cas d'utilisation pour les assertions est de servir de vérifications de cohérence pour des préconditions qui devraient toujours être `true`, et si elles ne sont pas respectées, cela indique des erreurs de programmation. Un autre cas d'utilisation est de garantir la présence de certaines fonctionnalités telles que des fonctions d'extension ou certaines limites et fonctionnalités du système.

Comme les assertions peuvent être configurées pour être éliminées, elles ne doivent pas être utilisées pour des opérations normales en cours d'exécution, telles que des vérifications des paramètres d'entrée. En règle générale, le code doit se comporter comme prévu même si la vérification des assertions est désactivée.

assert() vérifiera que l'attente donnée dans `assertion` est satisfaite. Si ce n'est pas le cas et donc que le résultat est `false`, elle prendra l'action appropriée en fonction de la configuration de assert().

Le comportement de assert() est dicté par les paramètres INI suivants :

Assert Options de configuration
Nom | Défaut | Description | Historique
--- | --- | --- | ---
zend.assertions | `1` | `1` : génère et exécute le code (mode développement) `0` : génère le code mais l'évite au moment de l'exécution `-1` : ne génère pas le code (mode production) |
assert.active | `true` | Si `false`, assert() ne vérifie pas l'attente et retourne toujours `true`, sans condition. | Déprécié à partir de PHP 8.3.0.
assert.callback | `null` | Une fonction définie par l'utilisateur à appeler lorsqu'une assertion échoue. Sa signature devrait être : function assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void | Antérieur à PHP 8.0.0, la signature de la fonction de rappel devrait être : function assert_callback( string `$file`, int `$line`, string `$assertion`, string `$description` = ? ): void Déprécié à partir de PHP 8.3.0.
assert.exception | `true` | Si `true`, lancera une AssertionError si l'attente n'est pas respectée. | Déprécié à partir de PHP 8.3.0.
assert.bail | `false` | Si `true`, interrompra l'exécution du script PHP si l'attente n'est pas respectée. | Déprécié à partir de PHP 8.3.0.
assert.warning | `true` | Si `true`, émettra un `E_WARNING` si l'attente n'est pas respectée. Ce paramètre INI est inefficace si assert.exception est activé. | Déprécié à partir de PHP 8.3.0.

### Liste de paramètres

`assertion`

  Ceci est une expression quelconque qui retourne une valeur, qui sera exécutée et dont le résultat sera utilisé pour indiquer si l'assertion a réussi ou échoué.

  Avertissement

  Antérieur à PHP 8.0.0, si `assertion` était une string, elle était interprétée comme du code PHP et exécutée via eval(). Cette chaîne était transmise à la fonction de rappel en tant que troisième argument. Ce comportement était OBSOLÈTE dans PHP 7.2.0, et est SUPPRIMÉ à partir de PHP 8.0.0

`description`

  Si `description` est une instance de Throwable, elle sera lancée uniquement si `assertion` est exécutée et échoue.

  > Note:

  > À partir de PHP 8.0.0, cela est fait avant d'appeler la fonction de rappel d'assertion éventuellement définie

  > Note:

  > À partir de PHP 8.0.0, l'objet objet sera lancé indépendamment de la configuration de assert.exception.

  > Note:

  > À partir de PHP 8.0.0, le paramètre assert.bail n'a aucun effet dans ce cas.

  Si `description` est une chaîne de caractères, ce message sera utilisé si une exception ou un avertissement est émis. Une description optionnelle, qui sera incluse dans le message d'échec si l'`assertion` échoue.

  Si `description` est omis. Une description par défaut équivalente au code source de l'appel de assert() est créée au moment de la compilation.

### Valeurs de retour

assert() renverra toujours `true` si au moins l'une des conditions suivantes est vraie :

- `zend.assertions=0`
- `zend.assertions=-1`
- `assert.active=0`
- `assert.exception=1`
- `assert.bail=1`
- Un objet d'exception personnalisé est passé à `description`.

Si aucune des conditions n'est vraie, assert() renverra `true` si `assertion` est vrai, et `false` sinon.

### Historique

Version | Description
--- | ---
8.3.0 | Toutes les configurations INI `assert.` sont devenues dépréciées.
8.0.0 | La fonction assert() n'évaluera plus les arguments de type string, au lieu de cela, ils seront traités comme tout autre argument. `assert($a == $b)` devrait être utilisé à la place du `assert('$a == $b')`. La directive `assert.quiet_eval` php.ini et la constante `ASSERT_QUIET_EVAL` ont également été supprimées, car elles n'auraient plus aucun effet.
8.0.0 | Si `description` est une instance de Throwable, l'objet est lancé si l'assertion échoue, indépendamment de la valeur de assert.exception.
8.0.0 | Si `description` est une instance de Throwable, aucune fonction de rappel utilisateur n'est appelée même si elle est définie.
8.0.0 | Déclarer une fonction qui s'appelle `assert()` à l'intérieur d'un espace de noms n'est plus autorisé, et génère une `E_COMPILE_ERROR`.
7.3.0 | Déclarer une fonction qui s'appelle `assert()` à l'intérieur d'un espace de noms est devenue dépréciée. De telles déclarations génèrent désormais une `E_DEPRECATED`.
7.2.0 | L'utilisation d'une chaîne de caractères en tant qu'`assertion` est devenue dépréciée. Ceci émet désormais une notice `E_DEPRECATED` quand assert.active et zend.assertions sont tous les deux définis à `1`.

### Exemples

Exemple #1 Exemple d'assert()

    <?php
    assert(1 > 2);
    echo 'Hi!';
    ?>

Si les assertions sont activées (`zend.assertions=1`) l'exemple ci-dessus afficherait :

    Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'assert(1 > 2)')
    #1 {main}
      thrown in example.php on line 2

Si les assertions sont désactivées (`zend.assertions=0` ou `zend.assertions=-1`) l'exemple ci-dessus afficherait :

    Hi!

Exemple #2 Utilisation d'un message personnalisé

    <?php
    assert(1 > 2, "Expected one to be greater than two");
    echo 'Hi!';
    ?>

Si les assertions sont activées, l'exemple ci-dessus afficherait :

    Fatal error: Uncaught AssertionError: Expected one to be greater than two in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'Expected one to...')
    #1 {main}
      thrown in example.php on line 2

Si les assertions sont désactivées, l'exemple ci-dessus afficherait :

    Hi!

Exemple #3 Utilisation d'une classe d'exception personnalisée

    <?php
          class ArithmeticAssertionError extends AssertionError {}

          assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
          echo 'Hi!';

Si les assertions sont activées, l'exemple ci-dessus afficherait :

    Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4
    Stack trace:
    #0 {main}
      thrown in example.php on line 4

Si les assertions sont désactivées, l'exemple ci-dessus affichera :

    Hi!

### Voir aussi

- assert_options() - Définit/récupère différentes options d'assertions

# assert_options

(PHP 4, PHP 5, PHP 7, PHP 8)

assert_options — Définit/récupère différentes options d'assertions

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.3.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function assert_options(int `$option`, mixed `$value` = ?): mixed

assert_options() permet de modifier les diverses options de la fonction assert(), ou simplement connaître la configuration actuelle.

> Note: L'utilisation de assert_options() est déconseillée en faveur de définir et récupérer les directives php.ini zend.assertions et assert.exception avec ini_set() et ini_get(), respectivement.

### Liste de paramètres

`option`

  Options d'assertions
  Option | Directive | Valeur par défaut | Description
  --- | --- | --- | ---
  ASSERT_ACTIVE | assert.active | 1 | Active l'évaluation de la fonction assert()
  ASSERT_EXCEPTION | assert.exception | 1 | Lance une AssertionError pour chaque assertion échouée
  ASSERT_WARNING | assert.warning | 1 | Génère une alerte PHP pour chaque assertion fausse
  ASSERT_BAIL | assert.bail | 0 | Termine l'exécution en cas d'assertion fausse
  ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | Désactive le rapport d'erreur durant l'évaluation d'une assertion. Supprimée à partir de PHP 8.0.0
  ASSERT_CALLBACK | assert.callback | (`null`) | Fonction de rappel utilisateur, pour le traitement des assertions fausses

`value`

  Une nouvelle valeur, optionnelle, pour l'option.

  La fonction de rappel définie via `ASSERT_CALLBACK` ou assert.callback devrait avoir la signature suivante :

  function assert_callback(
  string `$file`,
  int `$line`,
  ?string `$assertion`,
  string `$description` = ?
  ): void
  `file`
    Le fichier assert() a été appelé.
  `line`
    La ligne où assert() a été appelé.
  `assertion`
    Antérieur à PHP 8.0.0, le premier paramètre de la fonction assert() était l'assertion passée, mais seulement lorsque l'assertion était fournie sous forme de chaîne de caractères. (Si l'assertion était une condition booléenne, ce paramètre était une chaîne vide.) À partir de PHP 8.0.0, ce paramètre est toujours `null`.
  `description`
    La description qui a été fournie à assert().

### Valeurs de retour

Retourne la valeur originale de l'option.

### Erreurs / Exceptions

Si `option` n'est pas une option valide, une ValueError est lancée.

### Historique

Version | Description
--- | ---
8.3.0 | assert_options() est désormais obsolète.
8.0.0 | Si `option` n'est pas une option valide, une ValueError est désormais lancée. Auparavant, `false` était retourné.

### Exemples

Exemple #1 Exemple avec assert_options()

    <?php
    // Ceci est notre fonction pour gérer les
    // erreurs d'assertion
    function assert_failure($file, $line, $assertion, $message)
    {
        echo "L'assertion $assertion dans $file à la ligne $line a échoué : $message";
    }

    // Ceci est notre fonction de test
    function test_assert($parameter)
    {
        assert(is_bool($parameter));
    }

    // Définit nos options d'assertion
    assert_options(ASSERT_ACTIVE,   true);
    assert_options(ASSERT_BAIL,     true);
    assert_options(ASSERT_WARNING,  false);
    assert_options(ASSERT_CALLBACK, 'assert_failure');

    // Une assertion qui doit échouer
    test_assert(1);

    // Ceci n'est jamais atteint, car ASSERT_BAIL
    // vaut true
    echo 'Jamais atteint';
    ?>

### Voir aussi

- assert() - Vérifie une assertion

# cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_title — Retourne le titre du processus courant

### Description

function cli_get_process_title(): ?string

Retourne le titre du processus courant, tel que défini par la fonction cli_set_process_title(). Il est à noter que ce titre peut être légèrement différent de celui affiché via les commandes ps et top, suivant le système sous-jacent.

Cette fonction n'est disponible qu'en mode CLI.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le titre du processus courant, sous la forme d'une chaîne de caractères, ou `null` si une erreur survient.

### Erreurs / Exceptions

Une alerte de niveau `E_WARNING` sera générée si le système sous-jacent n'est pas supporté.

### Exemples

Exemple #1 Exemple avec cli_get_process_title()

    <?php
    echo "Titre du processus : " . cli_get_process_title() . "\n";
    ?>

### Voir aussi

- cli_set_process_title() - Définit le titre du processus

# cli_set_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_set_process_title — Définit le titre du processus

### Description

function cli_set_process_title(string `$title`): bool

Définit le titre du processus visible avec des outils comme top et ps. Cette fonction n'est disponible qu'en mode CLI.

### Liste de paramètres

`title`
  Le nouveau titre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Une alerte de niveau `E_WARNING` sera générée si le système sous-jacent n'est pas supporté.

### Historique

Version | Description
--- | ---
8.5.0 | cli_set_process_title() émet désormais une alerte `E_WARNING` lorsque le titre du processus défini est trop long ; auparavant, le titre était tronqué.

### Exemples

    <?php
    $title = "Mon super script PHP";
    $pid = getmypid(); // il est possible d'utiliser ceci pour voir le titre du processus dans ps

    if (!cli_set_process_title($title)) {
        echo "Impossible de définir le titre du processus pour le PID $pid...\n";
        exit(1);
    } else {
        echo "Le titre du processus '$title' pour le PID $pid a bien été défini !\n";
        sleep(5);
    }
    ?>

### Voir aussi

- cli_get_process_title() - Retourne le titre du processus courant

# dl

(PHP 4, PHP 5, PHP 7, PHP 8)

dl — Charge une extension PHP à la volée

### Description

function dl(string `$extension_filename`): bool

Charge l'extension PHP `extension_filename` à la volée.

La fonction extension_loaded() permet de vérifier qu'une extension est chargée ou non. Cette fonction travaille aussi bien avec les extensions natives qu'avec les extensions dynamiquement chargées (via le php.ini ou dl()).

Avertissement

Cette fonction n'est disponible que pour les SAPI CLI et intégrés, et le SAPI CGI lorsqu'il est exécuté à partir de la ligne de commande.

### Liste de paramètres

`extension_filename`

  Ce paramètre est seulement le nom de fichier de l'extension, qui dépend de la plate-forme. Par exemple l'extension sockets (si compilée comme module partagé, et non par défaut), sera appelée sockets.so sous Unix, et php_sockets.dll sous Windows.

  Le dossier à partir duquel sont chargées les extensions dépend de la plate-forme :

  Windows - S'il n'est pas explicitement indiqué dans le fichier php.ini, l'extension est chargée depuis C:\php5\ par défaut.

  Unix - S'il n'est pas explicitement indiqué dans le fichier php.ini, le dossier des extensions dépend de

  - Si PHP a été compilé avec l'option `--enable-debug` ou non
  - Si PHP a été compilé avec le support de ZTS (`Zend Thread Safety`) ou non
  - de la constante interne `ZEND_MODULE_API_NO` (version interne de module d'API Zend, qui est en réalité la date à laquelle une modification importante de l'API a été faite, par exemple `20010901`)
  En prenant ces paramètres en considération, le dossier des extensions vaut alors `<install-dir>/lib/php/extensions/ <debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO`, p. ex. /usr/local/php/lib/php/extensions/debug-non-zts-20010901 ou /usr/local/php/lib/php/extensions/no-debug-zts-20010901.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient. Si la fonctionnalité de chargement de module n'est pas disponible, ou a été désactivée (en désactivant la directive enable_dl dans le php.ini) une `E_ERROR` sera émise et l'exécution du script sera stoppée. Si la fonction dl() échoue parce que la bibliothèque n'a pu être trouvée, dl() retourne `false` et émet un message d'alerte `E_WARNING`.

### Exemples

Exemple #1 Exemples avec dl()

    <?php
    // Chargement pour toutes plates-formes
    if (!extension_loaded('sqlite')) {
        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
            dl('php_sqlite.dll');
        } else {
            dl('sqlite.so');
        }
    }

    // Ou utiliser la constante PHP_SHLIB_SUFFIX
    if (!extension_loaded('sqlite')) {
        $prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
        dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
    }
    ?>

### Notes

> Note:

> dl() est sensible à la casse sur les plates-formes Unix.

### Voir aussi

- Directives de chargement d'extensions
- extension_loaded() - Détermine si une extension est chargée ou non

# extension_loaded

(PHP 4, PHP 5, PHP 7, PHP 8)

extension_loaded — Détermine si une extension est chargée ou non

### Description

function extension_loaded(string `$extension`): bool

Détermine si une extension est chargée ou non.

### Liste de paramètres

`extension`

  Le nom de l'extension. Ce paramètre n'est pas sensible à la casse.

  Il est possible de connaître le nom des différentes extensions PHP en utilisant la fonction phpinfo() ou bien si l'on utilise la version `CGI` ou `CLI` de PHP, il est possible d'utiliser l'option de ligne de commande `-m` pour afficher toutes les extensions disponibles :

      $ php -m
      [PHP Modules]
      xml
      tokenizer
      standard
      sockets
      session
      posix
      pcre
      overload
      mysql
      mbstring
      ctype

      [Zend Modules]

### Valeurs de retour

Retourne `true` si l'extension `extension` a été chargée, `false` sinon.

### Exemples

Exemple #1 Exemple avec extension_loaded()

    <?php
    if (!extension_loaded('gd')) {
        if (!dl('gd.so')) {
            exit;
        }
    }
    ?>

### Voir aussi

- get_loaded_extensions() - Retourne la liste de tous les modules compilés et chargés
- get_extension_funcs() - Liste les fonctions d'une extension
- phpinfo() - Affiche de nombreuses informations sur la configuration de PHP
- dl() - Charge une extension PHP à la volée
- function_exists() - Indique si une fonction est définie

# gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cycles — Force le passage du collecteur de mémoire

### Description

function gc_collect_cycles(): int

Force le passage du collecteur de mémoire.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de cycles collectés.

### Historique

Version | Description
--- | ---
8.5.0 | La valeur de retour n'inclut plus les chaînes et les ressources qui ont été collectées indirectement à travers les cycles.

### Voir aussi

- Le collecteur

# gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disable — Désactive le collecteur de références circulaires

### Description

function gc_disable(): void

Désactive le collecteur de références circulaires, en configuration zend.enable_gc à `0`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- Le collecteur

# gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enable — Active le collecteur de références circulaires

### Description

function gc_enable(): void

Active le collecteur de références circulaires, en définissant zend.enable_gc à `1`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- Le collecteur

# gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabled — Retourne le statut du collecteur de références circulaires

### Description

function gc_enabled(): bool

Retourne le statut du collecteur de références circulaires.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si le collecteur est actif, et `false` sinon.

### Exemples

Exemple #1 Exemple avec gc_enabled()

    <?php
    if(gc_enabled()) gc_collect_cycles();
    ?>

### Voir aussi

- Le collecteur

# gc_mem_caches

(PHP 7, PHP 8)

gc_mem_caches — Récupère de la mémoire utilisée par le gestionnaire de mémoire de Zend Engine

### Description

function gc_mem_caches(): int

Récupère de la mémoire utilisée par le gestionnaire de mémoire de Zend Engine.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre d'octets libérés.

### Voir aussi

- Ramasse-miettes (Garbage Collection)

# gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_status — Récupère les informations à propos du ramasse-miettes

### Description

function gc_status(): array

Récupère les informations à propos de l'état actuel du ramasse-miettes.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif avec les éléments suivants :

- `"runs"`
- `"collected"`
- `"threshold"`
- `"roots"`
- `"running"`
- `"protected"`
- `"full"`
- `"buffer_size"`
- `"application_time"`
- `"collector_time"`
- `"destructor_time"`
- `"free_time"`

### Historique

Version | Description
--- | ---
8.3.0 | gc_status() retourne désormais les champs additionnels suivants : `"running"`, `"protected"`, `"full"`, `"buffer_size"`, `"application_time"`, `"collector_time"`, `"destructor_time"`, et `"free_time"`.

### Exemples

Exemple #1 Utilisation de gc_status()

    <?php

    // créer l'arbre d'objets qui nécessite la collection du ramasse-miettes
    $a = new stdClass();
    $a->b = [];
    for ($i = 0; $i < 100000; $i++) {
        $b = new stdClass();
        $b->a = $a;
        $a->b[] = $b;
    }
    unset($a);
    unset($b);
    gc_collect_cycles();

    var_dump(gc_status());

Résultat de l'exemple ci-dessus est similaire à :

    array(4) {
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["roots"]=>
      int(0)
    }

Résultat de l'exemple ci-dessus en PHP 8.3 est similaire à :

    array(12) {
      ["running"]=>
      bool(false)
      ["protected"]=>
      bool(false)
      ["full"]=>
      bool(false)
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["buffer_size"]=>
      int(131072)
      ["roots"]=>
      int(0)
      ["application_time"]=>
      float(0.031182458)
      ["collector_time"]=>
      float(0.020106291)
      ["destructor_time"]=>
      float(0)
      ["free_time"]=>
      float(0.003707167)
    }

### Voir aussi

- Ramasse-miettes (Garbage Collection)

# get_cfg_var

(PHP 4, PHP 5, PHP 7, PHP 8)

get_cfg_var — Retourne la valeur d'une option de PHP

### Description

function get_cfg_var(string `$option`): string|array|false

Retourne la valeur de l'option `option` de configuration PHP.

get_cfg_var() ne retourne pas les options qui ont été choisies lors de la compilation de PHP, ni ne lit dans le fichier de configuration d'Apache.

Pour vérifier si le système utilise le fichier de configuration, essayez de lire la valeur de cfg_file_path. Si cette valeur est disponible, alors le fichier de configuration est utilisé.

### Liste de paramètres

`option`

  Le nom de l'option de configuration.

### Valeurs de retour

Retourne la valeur courante de l'option PHP `option` ou bien `false` si une erreur survient.

### Voir aussi

- ini_get() - Lit la valeur d'une option de configuration
- ini_get_all() - Lit toutes les valeurs de configuration

# get_current_user

(PHP 4, PHP 5, PHP 7, PHP 8)

get_current_user — Retourne le nom du possesseur du script courant

### Description

function get_current_user(): string

Retourne le nom du possesseur du script courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nom de l'utilisateur, sous la forme d'une chaîne de caractères.

### Exemples

Exemple #1 Exemple avec get_current_user()

    <?php
    echo 'Propriétaire du script courant : ' . get_current_user();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Propriétaire du script courant : SYSTEM

### Voir aussi

- getmyuid() - Retourne l'UID du propriétaire du script actuel
- getmygid() - Retourne le GID du propriétaire du script
- getmypid() - Retourne le numéro de processus courant de PHP
- getmyinode() - Retourne l'inode du script
- getlastmod() - Retourne la date de dernière modification de la page

# get_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constants — Retourne la liste des constantes et leurs valeurs

### Description

function get_defined_constants(bool `$categorize` = `false`): array

Retourne les noms et valeurs des constantes déjà définies. Cela inclut les constantes créées par les extensions, et celles créées avec la fonction define().

### Liste de paramètres

`categorize`

  Permet à cette fonction de retourner un tableau multidimensionnel avec les catégories en tant que clés de la première dimension et les constantes ainsi que leurs valeurs dans la seconde dimension.

      <?php
      define("MY_CONSTANT", 1);
      print_r(get_defined_constants(true));
      ?>

  Résultat de l'exemple ci-dessus est similaire à :

      Array
      (
          [Core] => Array
              (
                  [E_ERROR] => 1
                  [E_WARNING] => 2
                  [E_PARSE] => 4
                  [E_NOTICE] => 8
                  [E_CORE_ERROR] => 16
                  [E_CORE_WARNING] => 32
                  [E_COMPILE_ERROR] => 64
                  [E_COMPILE_WARNING] => 128
                  [E_USER_ERROR] => 256
                  [E_USER_WARNING] => 512
                  [E_USER_NOTICE] => 1024
                  [E_ALL] => 2047
                  [TRUE] => 1
              )

          [pcre] => Array
              (
                  [PREG_PATTERN_ORDER] => 1
                  [PREG_SET_ORDER] => 2
                  [PREG_OFFSET_CAPTURE] => 256
                  [PREG_SPLIT_NO_EMPTY] => 1
                  [PREG_SPLIT_DELIM_CAPTURE] => 2
                  [PREG_SPLIT_OFFSET_CAPTURE] => 4
                  [PREG_GREP_INVERT] => 1
              )

          [user] => Array
              (
                  [MY_CONSTANT] => 1
              )

      )

### Valeurs de retour

Retourne un tableau de constantes au format "nom de la constante" => "valeur de la constante", optionnellement groupées par le nom de l'extension ayant enregistré la constante.

### Exemples

Exemple #1 Exemple avec get_defined_constants()

    <?php
    print_r(get_defined_constants());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [E_ERROR] => 1
        [E_WARNING] => 2
        [E_PARSE] => 4
        [E_NOTICE] => 8
        [E_CORE_ERROR] => 16
        [E_CORE_WARNING] => 32
        [E_COMPILE_ERROR] => 64
        [E_COMPILE_WARNING] => 128
        [E_USER_ERROR] => 256
        [E_USER_WARNING] => 512
        [E_USER_NOTICE] => 1024
        [E_ALL] => 2047
        [TRUE] => 1
    )

### Voir aussi

- defined() - Vérifie si une constante avec le nom donné existe
- constant() - Retourne la valeur d'une constante
- get_loaded_extensions() - Retourne la liste de tous les modules compilés et chargés
- get_defined_functions() - Liste toutes les fonctions définies
- get_defined_vars() - Liste toutes les variables définies

# get_extension_funcs

(PHP 4, PHP 5, PHP 7, PHP 8)

get_extension_funcs — Liste les fonctions d'une extension

### Description

function get_extension_funcs(string `$extension`): array|false

Retourne le nom des fonctions définies dans le module `extension`.

### Liste de paramètres

`extension`

  Le nom du module.

  > Note:

  > Ce paramètre doit être en minuscule.

### Valeurs de retour

Retourne un tableau contenant toutes les fonctions, ou `false` si `extension` n'est pas une extension valide.

### Exemples

Exemple #1 Affiche toutes les fonctions XML

    <?php
    print_r(get_extension_funcs("xml"));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => xml_parser_create
        [1] => xml_parser_create_ns
        [2] => xml_set_object
        [3] => xml_set_element_handler
        [4] => xml_set_character_data_handler
        [5] => xml_set_processing_instruction_handler
        [6] => xml_set_default_handler
        [7] => xml_set_unparsed_entity_decl_handler
        [8] => xml_set_notation_decl_handler
        [9] => xml_set_external_entity_ref_handler
        [10] => xml_set_start_namespace_decl_handler
        [11] => xml_set_end_namespace_decl_handler
        [12] => xml_parse
        [13] => xml_parse_into_struct
        [14] => xml_get_error_code
        [15] => xml_error_string
        [16] => xml_get_current_line_number
        [17] => xml_get_current_column_number
        [18] => xml_get_current_byte_index
        [19] => xml_parser_free
        [20] => xml_parser_set_option
        [21] => xml_parser_get_option
    )

### Voir aussi

- get_loaded_extensions() - Retourne la liste de tous les modules compilés et chargés
- ReflectionExtension::getFunctions() - Récupère les fonctions d'une extension

# get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_path — Lit la valeur de la directive de configuration include_path

### Description

function get_include_path(): string|false

Lit la valeur de la directive de configuration include_path.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le chemin, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec get_include_path()

    <?php
    echo get_include_path();

    // Ou utiliser ini_get()
    echo ini_get('include_path');
    ?>

### Voir aussi

- ini_get() - Lit la valeur d'une option de configuration
- restore_include_path() - Restaure la valeur de la directive de configuration include_path
- set_include_path() - Modifie la valeur de la directive de configuration include_path
- include - include

# get_included_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_included_files — Retourne un tableau avec les noms des fichiers qui sont inclus dans un script

### Description

function get_included_files(): array

Retourne un tableau contenant les noms de tous les fichiers qui ont été ajoutés au script avec les fonctions include, include_once, require ou require_once.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau contenant les noms de tous les fichiers.

Le script en cours est considéré comme fichier inclus, il sera donc listé avec les autres fichiers dont il est fait référence avec include et les fonctions assimilées.

Les fichiers inclus ou requis plusieurs fois ne s'affichent qu'une fois dans le tableau retourné.

### Exemples

Exemple #1 Exemple avec get_included_files()

    <?php
    // Ce fichier est abc.php

    include 'test1.php';
    include_once 'test2.php';
    require 'test3.php';
    require_once 'test4.php';

    $included_files = get_included_files();

    foreach ($included_files as $filename) {
        echo "$filename\n";
    }

    ?>

L'exemple ci-dessus va afficher :

    /path/to/abc.php
    /path/to/test1.php
    /path/to/test2.php
    /path/to/test3.php
    /path/to/test4.php

### Voir aussi

- include - include
- include_once - include_once
- require - require
- require_once - require_once
- get_required_files() - Alias de get_included_files

# get_loaded_extensions

(PHP 4, PHP 5, PHP 7, PHP 8)

get_loaded_extensions — Retourne la liste de tous les modules compilés et chargés

### Description

function get_loaded_extensions(bool `$zend_extensions` = `false`): array

Retourne un tableau contenant les noms de tous les modules compilés et chargés par l'application PHP courante.

### Liste de paramètres

`zend_extensions`

  Retourne uniquement les extensions Zend. Par défaut vaut `false` et ne liste que les extensions PHP classiques comme mysqli par exemple.

### Valeurs de retour

Retourne un tableau indexé des noms de tous les modules.

### Exemples

Exemple #1 Exemple avec get_loaded_extensions()

    <?php
    print_r(get_loaded_extensions());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Core
        [1] => date
        [2] => libxml
        [3] => pcre
        [4] => sqlite3
        [5] => zlib
        [6] => ctype
        [7] => dom
        [8] => fileinfo
        [9] => filter
        [10] => hash
        [11] => json
        [12] => mbstring
        [13] => SPL
        [14] => PDO
        [15] => session
        [16] => posix
        [17] => Reflection
        [18] => standard
        [19] => SimpleXML
        [20] => pdo_sqlite
        [21] => Phar
        [22] => tokenizer
        [23] => xml
        [24] => xmlreader
        [25] => xmlwriter
        [26] => gmp
        [27] => iconv
        [28] => intl
        [29] => bcmath
        [30] => sodium
        [31] => Zend OPcache
    )

### Voir aussi

- get_extension_funcs() - Liste les fonctions d'une extension
- extension_loaded() - Détermine si une extension est chargée ou non
- dl() - Charge une extension PHP à la volée
- phpinfo() - Affiche de nombreuses informations sur la configuration de PHP

# get_magic_quotes_gpc

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_gpc — Retourne la configuration actuelle de l'option magic_quotes_gpc

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.4.0, et a été SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function get_magic_quotes_gpc(): false

Retourne toujours `false`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `false`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction a été supprimée.
7.4.0 | Cette fonction est obsolète.

### Voir aussi

- addslashes() - Ajoute des antislashs dans une chaîne
- stripslashes() - Supprime les antislashs d'une chaîne
- get_magic_quotes_runtime() - Retourne la configuration actuelle de l'option magic_quotes_runtime
- ini_get() - Lit la valeur d'une option de configuration

# get_magic_quotes_runtime

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_runtime — Retourne la configuration actuelle de l'option magic_quotes_runtime

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.4.0, et a été SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function get_magic_quotes_runtime(): false

Retourne toujours `false`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `false`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction a été supprimée.
7.4.0 | Cette fonction est obsolète.

### Voir aussi

- get_magic_quotes_gpc() - Retourne la configuration actuelle de l'option magic_quotes_gpc

# get_required_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_required_files — Alias de get_included_files()

### Description

Cette fonction est un alias de : get_included_files().

# get_resources

(PHP 7, PHP 8)

get_resources — Retourne les ressources actives

### Description

function get_resources(?string `$type` = `null`): array

Retourne un tableau de toutes les ressources resource actuellement actives, optionnellement filtré par le type de ressource.

> Note: Cette fonction est destinée à des fins de débogage et de test. Elle n'est pas censée être utilisée dans des environnements de production, et surtout pas pour accéder ou même manipuler des ressources qui ne sont normalement pas accessibles (par exemple, la ressource de flux sous-jacente des instances de SplFileObject).

### Liste de paramètres

`type`

  Si défini, get_resources() ne retourne que les ressources du type donné. Une liste des types de ressources est disponible.

  Si chaîne de caractères `Unknown` est fourni pour le type, dans ce cas là seulement les ressources dont le type est inconnu seront retournées.

  Si omis, toutes les ressources seront retournées.

### Valeurs de retour

Retourne un tableau des ressources actuellement actives, indexé par le numéro de la ressource.

### Historique

Version | Description
--- | ---
8.0.0 | `type` est désormais nullable.

### Exemples

Exemple #1 get_resources() non-filtré

    <?php
    $fp = tmpfile();
    var_dump(get_resources());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }

Exemple #2 get_resources() filtré

    <?php
    $fp = tmpfile();
    var_dump(get_resources('stream'));
    var_dump(get_resources('curl'));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }
    array(0) {
    }

### Voir aussi

- get_loaded_extensions() - Retourne la liste de tous les modules compilés et chargés
- get_defined_constants() - Retourne la liste des constantes et leurs valeurs
- get_defined_functions() - Liste toutes les fonctions définies
- get_defined_vars() - Liste toutes les variables définies

# getenv

(PHP 4, PHP 5, PHP 7, PHP 8)

getenv — Retourne la valeur d'une seule ou toutes les variables d'environnement

### Description

function getenv(?string `$name` = `null`, bool `$local_only` = `false`): string|array|false

Retourne la valeur d'une seule ou toutes les variables d'environnement.

Il est possible de voir une liste complète des variables d'environnement en utilisant la fonction phpinfo(). Il est possible de trouver la signification de chacune d'entre elles en consultant la » RFC 3875, en particulier la section 4.1 "Request Meta-Variables".

### Liste de paramètres

`name`

  Le nom de la variable en tant que chaîne de caractères ou `null`.

`local_only`

  Lorsqu'il est défini sur `true`, seules les variables d'environnement locales sont renvoyées, définies par le système d'exploitation ou putenv. Cela n'a d'effet que lorsque `name` est une chaîne de caractères.

### Valeurs de retour

Retourne la valeur de la variable d'environnement `name`, ou `false` si la variable d'environnement `name` n'existe pas. Si `name` est omis, toutes les variables d'environnement sont retournées en tant qu'un tableau associatif.

### Historique

Version | Description
--- | ---
8.0.0 | Le `name` est désormais nullable.
7.1.0 | `name` peut désormais être omis pour récupérer un tableau associatif de toutes les variables d'environnement.
7.0.9 | Le paramètre `local_only` a été ajouté.

### Exemples

Exemple #1 Exemple avec getenv()

    <?php
    // Exemple d'utilisation de getenv()
    $ip = getenv('REMOTE_ADDR');

    // Ou utiliser simplement une Superglobale ($_SERVER ou $_ENV)
    $ip = $_SERVER['REMOTE_ADDR'];

    // Obtenir en toute sécurité la valeur d'une variable d'environnement,
    // ignorant si elle a été définie par un SAPI ou a été modifiée avec putenv
    $ip = getenv('REMOTE_ADDR', true) ?: getenv('REMOTE_ADDR')
    ?>

### Notes

Avertissement

Si PHP est exécuté dans un SAPI tel que Fast CGI, cette fonction retournera toujours la valeur d'une variable d'environnement définie par le SAPI, même si putenv() a été utilisé pour définir une variable d'environnement locale avec le même nom. Le paramètre `local_only` doit être utilisé pour retourner les valeurs de variables d'environnements définies localement.

### Voir aussi

- putenv() - Fixe la valeur d'une variable d'environnement
- apache_getenv() - Lit une variable de processus Apache
- Superglobales

# getlastmod

(PHP 4, PHP 5, PHP 7, PHP 8)

getlastmod — Retourne la date de dernière modification de la page

### Description

function getlastmod(): int|false

Retourne la date de dernière modification du script principal en exécution.

Pour récupérer la date de la dernière modification d'un fichier différent, il convient d'utiliser la fonction filemtime().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la date de dernière modification de la page. La valeur retournée est un timestamp UNIX, utilisable comme paramètre avec la fonction date(). Retourne `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec getlastmod()

    <?php
    // affiche par exemple 'Dernière modification: April 20 2004 20:43:59.'
    echo "Dernière modification : " . date ("F d Y H:i:s.", getlastmod());
    ?>

### Voir aussi

- date() - Formate un horodatage Unix
- getmyuid() - Retourne l'UID du propriétaire du script actuel
- getmygid() - Retourne le GID du propriétaire du script
- get_current_user() - Retourne le nom du possesseur du script courant
- getmyinode() - Retourne l'inode du script
- getmypid() - Retourne le numéro de processus courant de PHP
- filemtime() - Lit la date de dernière modification du fichier

# getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygid — Retourne le GID du propriétaire du script

### Description

function getmygid(): int|false

Retourne le GID du propriétaire du script.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le GID du propriétaire du script courant, ou `false` si une erreur survient.

### Voir aussi

- getmyuid() - Retourne l'UID du propriétaire du script actuel
- getmypid() - Retourne le numéro de processus courant de PHP
- get_current_user() - Retourne le nom du possesseur du script courant
- getmyinode() - Retourne l'inode du script
- getlastmod() - Retourne la date de dernière modification de la page

# getmyinode

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyinode — Retourne l'inode du script

### Description

function getmyinode(): int|false

Retourne l'inode du script courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'inode du script courant, sous la forme d'un entier, ou `false` si une erreur survient.

### Voir aussi

- getmygid() - Retourne le GID du propriétaire du script
- getmyuid() - Retourne l'UID du propriétaire du script actuel
- getmypid() - Retourne le numéro de processus courant de PHP
- get_current_user() - Retourne le nom du possesseur du script courant
- getlastmod() - Retourne la date de dernière modification de la page

# getmypid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmypid — Retourne le numéro de processus courant de PHP

### Description

function getmypid(): int|false

Retourne le numéro de processus courant de PHP.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le numéro de processus courant de PHP, ou `false` si une erreur survient.

### Notes

Avertissement

Les identifiants de processus ne sont pas uniques, et forment une source d'entropie faible. Il est recommandé de ne pas utiliser les pid pour assurer la sécurité d'un système.

### Voir aussi

- getmygid() - Retourne le GID du propriétaire du script
- getmyuid() - Retourne l'UID du propriétaire du script actuel
- get_current_user() - Retourne le nom du possesseur du script courant
- getmyinode() - Retourne l'inode du script
- getlastmod() - Retourne la date de dernière modification de la page

# getmyuid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyuid — Retourne l'UID du propriétaire du script actuel

### Description

function getmyuid(): int|false

Retourne l'UID du propriétaire du script actuel.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'identifiant du propriétaire du script actuel (UID) ou `false` en cas d'erreur.

### Voir aussi

- getmygid() - Retourne le GID du propriétaire du script
- getmypid() - Retourne le numéro de processus courant de PHP
- get_current_user() - Retourne le nom du possesseur du script courant
- getmyinode() - Retourne l'inode du script
- getlastmod() - Retourne la date de dernière modification de la page

# getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getopt — Lit des options passées dans la ligne de commande

### Description

function getopt(string `$short_options`, array `$long_options` = [], int `&$rest_index` = `null`): array|false

getopt() lit les options passées dans la ligne de commande.

### Liste de paramètres

`short_options`
  Chaque caractère dans cette chaîne sera utilisé en tant que caractères optionnels et devra correspondre aux options passées, commençant par un tiret simple (`-`). Par exemple, une chaîne optionnelle `"x"` correspondra à l'option `-x`. Seuls a-z, A-Z et 0-9 sont autorisés.
`long_options`
  Un tableau d'options. Chaque élément de ce tableau sera utilisé comme option et devra correspondre aux options passées, commençant par un tiret double (`--`). Par exemple, un élément `longopts` `"opt"` correspondra à l'option `--opt`.
`rest_index`
  Si le paramètre `rest_index` est présent, alors l'index où l'analyse des arguments s'est arrêtée sera écrit dans cette variable.

Le paramètre `short_options` peut contenir les éléments suivants :

- Caractères individuels (n'accepte pas de valeur)
- Caractères suivis par un deux-points (le paramètre nécessite une valeur)
- Caractères suivis par deux deux-points (valeur optionnelle)

Les valeurs optionnelles sont les premiers arguments après la chaîne. Si une valeur est requise, peu importe que la valeur soit suivie d'un espace ou non. Voir la note.

> Note: Les valeurs optionnelles n'acceptent pas l'espace comme séparateur.

Le tableau de valeurs `long_options` peut contenir :

- Chaîne (le paramètre n'accepte aucune valeur)
- Chaîne suivie d'un deux-points (le paramètre nécessite une valeur)
- Chaîne suivie de deux deux-points (valeur optionnelle)

> Note:

> Le format des paramètres `short_options` et `long_options` est identique ; la seule différence est que `long_options` prend un tableau en option (où chaque élément est une option) alors que `short_options` prend une chaîne (où chaque caractère est une option).

### Valeurs de retour

Cette fonction retourne un tableau d'options/arguments, ou `false` si une erreur survient.

> Note:

> L'analyse des options s'arrêtera lorsque la première mauvaise option sera trouvée, et tout ce qui suivra sera ignoré.

### Historique

Version | Description
--- | ---
7.1.0 | Ajout du paramètre `rest_index`.

### Exemples

Exemple #1 Exemple avec getopt() : les bases

    <?php
    // Script example.php
    $options = getopt("f:hp:");
    var_dump($options);
    ?>

    shell> php example.php -fvalue -h

L'exemple ci-dessus va afficher :

    array(2) {
      ["f"]=>
      string(5) "value"
      ["h"]=>
      bool(false)
    }

Exemple #2 Second exemple avec getopt() : Introduction aux options longues

    <?php
    // Script example.php
    $shortopts  = "";
    $shortopts .= "f:";  // Valeur requise
    $shortopts .= "v::"; // Valeur optionnelle
    $shortopts .= "abc"; // Ces options n'acceptent pas de valeur

    $longopts  = array(
        "required:",     // Valeur requise
        "optional::",    // Valeur optionnelle
        "option",        // Aucune valeur
        "opt",           // Aucune valeur
    );
    $options = getopt($shortopts, $longopts);
    var_dump($options);
    ?>

    shell> php example.php -f "value for f" -v -a --required value --optional="optional value" --option

L'exemple ci-dessus va afficher :

    array(6) {
      ["f"]=>
      string(11) "value for f"
      ["v"]=>
      bool(false)
      ["a"]=>
      bool(false)
      ["required"]=>
      string(5) "value"
      ["optional"]=>
      string(14) "optional value"
      ["option"]=>
      bool(false)
    }

Exemple #3 Troisième exemple avec getopt() : Passage de plusieurs options

    <?php
    // Script example.php
    $options = getopt("abc");
    var_dump($options);
    ?>

    shell> php example.php -aaac

L'exemple ci-dessus va afficher :

    array(2) {
      ["a"]=>
      array(3) {
        [0]=>
        bool(false)
        [1]=>
        bool(false)
        [2]=>
        bool(false)
      }
      ["c"]=>
      bool(false)
    }

Exemple #4 Exemple de getopt() : Utilisant `rest_index`

    <?php
    // Script example.php
    $rest_index = null;
    $opts = getopt('a:b:', [], $rest_index);
    $pos_args = array_slice($argv, $rest_index);
    var_dump($pos_args);

    shell> php example.php -a 1 -b 2 -- test

L'exemple ci-dessus va afficher :

    array(1) {
      [0]=>
      string(4) "test"
    }

### Voir aussi

- $argv

# getrusage

(PHP 4, PHP 5, PHP 7, PHP 8)

getrusage — Retourne le niveau d'utilisation des ressources

### Description

function getrusage(int `$mode` = 0): array|false

C'est une interface à la fonction système getrusage(2). Elle retourne un tableau associatif contenant les informations renvoyées par cet appel système.

### Liste de paramètres

`mode`

  Si `mode` est égal à 1, getrusage() sera appelé avec le paramètre `RUSAGE_CHILDREN`.

### Valeurs de retour

Retourne un tableau associatif contenant les données retournées depuis l'appel système. Toutes les entrées sont accessibles en utilisant leurs noms de champs documentés. Retourne `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec getrusage()

    <?php
    $dat = getrusage();
    echo $dat["ru_oublock"];       // nombre d'opérations de bloc de sortie
    echo $dat["ru_inblock"];       // nombre d'opérations de bloc d'entrée
    echo $dat["ru_msgsnd"];        // nombre de messages IPC envoyés
    echo $dat["ru_msgrcv"];        // nombre de messages IPC reçus
    echo $dat["ru_maxrss"];        // taille maximale du groupe de résidents
    echo $dat["ru_ixrss"];         // taille de la mémoire partagée intégrale
    echo $dat["ru_idrss"];         // taille intégrale des données non partagées
    echo $dat["ru_minflt"];        // nombre de pages récupérées (faute de page mineure)
    echo $dat["ru_majflt"];        // nombre de défauts de page (faute de page majeure)
    echo $dat["ru_nsignals"];      // nombre de signaux reçus
    echo $dat["ru_nvcsw"];         // nombre de changements de contexte volontaires
    echo $dat["ru_nivcsw"];        // nombre de changements de contexte involontaires
    echo $dat["ru_nswap"];         // taille de la mémoire swap
    echo $dat["ru_utime.tv_usec"]; // temps utilisateur utilisé (en microsecondes)
    echo $dat["ru_utime.tv_sec"];  // temps utilisateur utilisé (en secondes)
    echo $dat["ru_stime.tv_usec"]; // temps système utilisé (en microsecondes)
    echo $dat["ru_stime.tv_sec"]; // temps système utilisé (en secondes)
    ?>

### Notes

> Note:

> Sous Windows, la fonction getrusage() ne va retourner que les membres suivants :

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`
> - `"ru_majflt"` (seulement si `mode` vaut `RUSAGE_SELF`)
> - `"ru_maxrss"` (seulement si `mode` vaut `RUSAGE_SELF`)

> Si getrusage() est appelé avec le paramètre `mode` valant `1` (`RUSAGE_CHILDREN`), alors l'utilisation de la ressource pour les threads est collectée (ce qui signifie que, en interne, la fonction est appelée avec `RUSAGE_THREAD`).

> Note:

> Sous BeOS 2000, seuls les membres suivants sont retournés :

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`

### Voir aussi

- La page de manuel getrusage(2) du système

# ini_alter

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_alter — Alias de ini_set()

### Description

Cette fonction est un alias de : ini_set().

# ini_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_get — Lit la valeur d'une option de configuration

### Description

function ini_get(string `$option`): string|false

Retourne la valeur de l'option de configuration `option` en cas de succès.

### Liste de paramètres

`option`

  Le nom de l'option de configuration.

### Valeurs de retour

Retourne la valeur de l'option de configuration `option` en cas de succès, ou une chaîne de caractères vide pour les valeurs `null`. Retourne `false` si l'option de configuration n'existe pas.

### Exemples

Exemple #1 Exemples avec ini_get()

    <?php

    /*
    Notre fichier php.ini contient les directives suivantes :

    display_errors = On
    opcache.enable_cli = Off
    post_max_size = 8M
    */

    echo 'display_errors = ' . ini_get('display_errors') . "\n";
    echo 'opcache.enable_cli = ' . (int) ini_get('opcache.enable_cli') . "\n";
    echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
    echo 'post_max_size + 1 = ' . (rtrim(ini_get('post_max_size'), 'KMG') + 1) . "\n";
    echo 'post_max_size in bytes = ' . ini_parse_quantity(ini_get('post_max_size'));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    display_errors = 1
    opcache.enable_cli = 0
    post_max_size = 8M
    post_max_size+1 = 9
    post_max_size in bytes = 8388608

### Notes

> Note: Lecture de valeurs booléennes

> Une directive de configuration ayant la valeur de `off` sera retournée sous la forme d'une chaîne vide ou "0" alors que la valeur `on` retournera "`1`". Cette fonction peut également retourner la valeur littérale du fichier INI.

> Note: Lors de la lecture des tailles de mémoire

> Plusieurs directives traitant de taille mémoire, comme upload_max_filesize, sont stockées dans le fichier php.ini avec une notation courte. ini_get() retourne la chaîne exacte stockée dans le fichier php.ini et NON PAS son équivalent entier. Appliquer des opérations arithmétiques classiques sur ces valeurs ne conduira à rien de bon. La fonction ini_parse_quantity() peut être utilisée pour convertir la notation abrégée en octets.

> Note:

> ini_get() ne peut pas lire les options ini de type "array" tel que `pdo.dsn.*`, et retourne `false` dans ce cas.

### Voir aussi

- get_cfg_var() - Retourne la valeur d'une option de PHP
- ini_get_all() - Lit toutes les valeurs de configuration
- ini_parse_quantity() - Renvoie la taille interprétée à partir de la syntaxe abrégée ini
- ini_restore() - Restaure la valeur de l'option de configuration
- ini_set() - Modifie la valeur d'une option de configuration

# ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_all — Lit toutes les valeurs de configuration

### Description

function ini_get_all(?string `$extension` = `null`, bool `$details` = `true`): array|false

Retourne toutes les valeurs de configuration.

### Liste de paramètres

`extension`

  Un nom d'extension, optionnel. Si non-`null` ou différent de la chaîne de caractères `core`, cette fonction retournera uniquement les options spécifiques à cette extension.

`details`

  Récupère les détails, ou uniquement la valeur courante de chaque configuration. Par défaut, vaut `true` (récupère les détails).

### Valeurs de retour

Retourne un tableau associatif dont les clés sont les noms des directives. Retourne `false` et lève une erreur de niveau `E_WARNING` si l'`extension` n'existe pas.

Lorsque le paramètre `details` vaut `true` (défaut), le tableau contiendra les valeurs `global_value` (définies dans le fichier php.ini), `local_value` (définie éventuellement avec la fonction ini_set() ou via un .htaccess), et `access` (le degré d'accès).

Lorsque le paramètre `details` vaut `false`, la valeur sera la valeur courante de l'option.

Voir le manuel pour plus d'informations sur la signification du degré d'accès.

> Note:

> Il est possible pour une directive d'avoir plusieurs degrés d'accès, et c'est la raison pour laquelle `access` montre les valeurs du masque appropriées.

### Exemples

Exemple #1 Exemple avec ini_get_all()

    <?php
    print_r(ini_get_all("pcre"));
    print_r(ini_get_all());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [pcre.backtrack_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

        [pcre.recursion_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

    )
    Array
    (
        [allow_call_time_pass_reference] => Array
            (
                [global_value] => 0
                [local_value] => 0
                [access] => 6
            )

        [allow_url_fopen] => Array
            (
                [global_value] => 1
                [local_value] => 1
                [access] => 4
            )

        ...

    )

Exemple #2 Désactive le paramètre `details`

    <?php
    print_r(ini_get_all("pcre", false)); // Ajouté en PHP 5.3.0
    print_r(ini_get_all(null, false)); // Ajouté en PHP 5.3.0
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [pcre.backtrack_limit] => 100000
        [pcre.recursion_limit] => 100000
    )
    Array
    (
        [allow_call_time_pass_reference] => 0
        [allow_url_fopen] => 1
        ...
    )

### Notes

> Note:

> ini_get_all() ignore les options ini "array" telles que `pdo.dsn.*`.

### Voir aussi

- Comment modifier la configuration
- ini_get() - Lit la valeur d'une option de configuration
- ini_restore() - Restaure la valeur de l'option de configuration
- ini_set() - Modifie la valeur d'une option de configuration
- get_loaded_extensions() - Retourne la liste de tous les modules compilés et chargés
- phpinfo() - Affiche de nombreuses informations sur la configuration de PHP
- ReflectionExtension::getINIEntries() - Récupère les entrées ini de l'extension

# ini_parse_quantity

(PHP 8 >= 8.2.0)

ini_parse_quantity — Renvoie la taille interprétée à partir de la syntaxe abrégée ini

### Description

function ini_parse_quantity(string `$shorthand`): int

Renvoie la taille interprétée en octets en cas de succès à partir d'une syntaxe abrégée ini.

### Liste de paramètres

`shorthand`

  La syntaxe abrégée ini à interpréter, doit être un nombre suivi d'un multiplicateur optionnel. Les multiplicateurs suivants sont supportés : `k`/`K` (`1024`), `m`/`M` (`1048576`), `g`/`G` (`1073741824`). Le nombre peut être un décimal, hexadécimal (préfixé par `0x` ou `0X`), octal (préfixé par `0o`, `0O` ou `0`) ou binaire (préfixé par `0b` ou `0B`)

### Valeurs de retour

Renvoie la taille interprétée en octets en tant qu'entier.

### Erreurs / Exceptions

Si la valeur ne peut pas être interprétée, ou si un multiplicateur invalide est utilisé, un `E_WARNING` est émis.

### Exemples

Exemple #1 Quelques exemples de ini_parse_quantity()

    <?php

    var_dump(ini_parse_quantity('1024'));
    var_dump(ini_parse_quantity('1024M'));
    var_dump(ini_parse_quantity('512K'));
    var_dump(ini_parse_quantity('0xFFk'));
    var_dump(ini_parse_quantity('0b1010k'));
    var_dump(ini_parse_quantity('0o1024'));
    var_dump(ini_parse_quantity('01024'));
    var_dump(ini_parse_quantity('Foobar'));
    var_dump(ini_parse_quantity('10F'));

    ?>

L'exemple ci-dessus va afficher :

    int(1024)
    int(1073741824)
    int(524288)
    int(261120)
    int(10240)
    int(532)
    int(532)

    Warning: Invalid quantity "Foobar": no valid leading digits, interpreting as "0" for backwards compatibility
    int(0)

    Warning: Invalid quantity "10F": unknown multiplier "F", interpreting as "10" for backwards compatibility
    int(10)

### Voir aussi

- ini_get() - Lit la valeur d'une option de configuration

# ini_restore

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_restore — Restaure la valeur de l'option de configuration

### Description

function ini_restore(string `$option`): void

Restaure la valeur originale de l'option de configuration `option`.

### Liste de paramètres

`option`

  Le nom de l'option de configuration.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ini_restore()

    <?php
    $setting = 'html_errors';

    echo 'Valeur courante de \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_set($setting, ini_get($setting) ? 0 : 1);
    echo 'Nouvelle valeur de \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_restore($setting);
    echo 'Valeur originale de \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    Valeur courante de 'html_errors': 1
    Nouvelle valeur de 'html_errors': 0
    Valeur originale de 'html_errors': 1

### Voir aussi

- ini_get() - Lit la valeur d'une option de configuration
- ini_get_all() - Lit toutes les valeurs de configuration
- ini_set() - Modifie la valeur d'une option de configuration

# ini_set

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_set — Modifie la valeur d'une option de configuration

### Description

function ini_set(string `$option`, string|int|float|bool|null `$value`): string|false

Change la valeur de l'option de configuration `option` et lui donne celle de `value`. La valeur de l'option de configuration sera modifiée durant toute l'exécution du script et pour ce script spécifiquement. Elle reprendra sa valeur par défaut dès la fin du script.

### Liste de paramètres

`option`

  Les options disponibles ne peuvent pas toutes être modifiées avec ini_set(). La liste de toutes les options disponibles se trouve dans l'annexe.

`value`

  La nouvelle valeur pour l'option.

### Valeurs de retour

Retourne l'ancienne valeur en cas de succès, `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | `value` accepte désormais tout type de scalaire (y compris `null`). Auparavant, seules les valeurs de type chaîne de caractères étaient acceptées.

### Exemples

Exemple #1 Définit une option de configuration

    <?php
    echo ini_get('display_errors');

    if (!ini_get('display_errors')) {
        ini_set('display_errors', '1');
    }

    echo ini_get('display_errors');
    ?>

### Voir aussi

- get_cfg_var() - Retourne la valeur d'une option de PHP
- ini_get() - Lit la valeur d'une option de configuration
- ini_get_all() - Lit toutes les valeurs de configuration
- ini_restore() - Restaure la valeur de l'option de configuration
- Comment modifier la configuration

# memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usage — Retourne la quantité de mémoire maximale allouée par PHP

### Description

function memory_get_peak_usage(bool `$real_usage` = `false`): int

Retourne la quantité de mémoire maximale, en octets, qui a été allouée au script PHP.

### Liste de paramètres

`real_usage`

  Définir à `true` pour récupérer la taille réelle de la mémoire allouée par le système. Si ce paramètre n'est pas défini ou vaut `false`, seule la mémoire utilisée par `emalloc()` sera retournée.

### Valeurs de retour

Retourne la quantité de mémoire, en octets.

### Voir aussi

- memory_get_usage() - Indique la quantité de mémoire utilisée par PHP
- memory_reset_peak_usage() - Réinitialise l'utilisation maximale de la mémoire
- memory_limit

# memory_get_usage

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

memory_get_usage — Indique la quantité de mémoire utilisée par PHP

### Description

function memory_get_usage(bool `$real_usage` = `false`): int

Retourne la quantité de mémoire allouée à PHP à cet instant.

### Liste de paramètres

`real_usage`

  Définir à `true` pour récupérer la taille totale de la mémoire allouée par le système. Si ce paramètre n'est pas défini ou vaut `false`, seule la mémoire utilisée sera retournée.

> Note:

> PHP ne peut suivre que la mémoire allouée par `emalloc()`

### Valeurs de retour

Retourne la quantité de mémoire, en octets.

### Exemples

Exemple #1 Exemple avec memory_get_usage()

    <?php
    // Ceci n'est qu'un exemple. Les chiffres ci-dessous
    // différeront suivant les systèmes et les configurations

    echo memory_get_usage() . "\n"; // 36640

    $a = str_repeat("Hello", 4242);

    echo memory_get_usage() . "\n"; // 57960

    unset($a);

    echo memory_get_usage() . "\n"; // 36744

    ?>

### Voir aussi

- memory_get_peak_usage() - Retourne la quantité de mémoire maximale allouée par PHP
- memory_limit

# memory_reset_peak_usage

(PHP 8 >= 8.2.0)

memory_reset_peak_usage — Réinitialise l'utilisation maximale de la mémoire

### Description

function memory_reset_peak_usage(): void

Réinitialise l'utilisation maximale de la mémoire retournée par la fonction memory_get_peak_usage().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple de memory_reset_peak_usage()

    <?php

    var_dump(memory_get_peak_usage());

    $a = str_repeat("Hello", 424242);
    var_dump(memory_get_peak_usage());

    unset($a);
    memory_reset_peak_usage();

    $a = str_repeat("Hello", 2424);
    var_dump(memory_get_peak_usage());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(422440)
    int(2508672)
    int(399208)

### Voir aussi

- memory_get_peak_usage() - Retourne la quantité de mémoire maximale allouée par PHP

# php_ini_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_file — Récupère le chemin d'un fichier php.ini chargé

### Description

function php_ini_loaded_file(): string|false

Vérifie si un fichier php.ini est chargé, et récupère son chemin.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le chemin du fichier php.ini chargé, ou `false` si aucun n'a été chargé.

### Exemples

Exemple #1 Exemple avec php_ini_loaded_file()

    <?php
    $inipath = php_ini_loaded_file();

    if ($inipath) {
        echo 'php.ini chargé : ' . $inipath;
    } else {
        echo 'Aucun fichier php.ini n\'a été chargé';
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    php.ini chargé : /usr/local/php/php.ini

### Voir aussi

- php_ini_scanned_files() - Retourne la liste des fichiers .ini analysés dans les dossiers de configuration supplémentaires
- phpinfo() - Affiche de nombreuses informations sur la configuration de PHP
- Le fichier de configuration

# php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_files — Retourne la liste des fichiers .ini analysés dans les dossiers de configuration supplémentaires

### Description

function php_ini_scanned_files(): string|false

php_ini_scanned_files() retourne une liste de noms de fichiers de configuration analysés après php.ini. Cette liste est au format CSV. Les dossiers examinés sont définis par une option de configuration lors de la compilation, et optionnellement par une variable d'environnement lors de l'exécution : plus d'informations sont disponibles dans le guide d'installation.

Les fichiers de configuration retournés incluent le chemin entier.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères où les fichiers .ini sont séparés par des virgules en cas de succès. Chaque virgule est suivie d'un retour à la ligne. Si la directive de configuration --with-config-file-scan-dir n'a pas été définie et que la variable d'environnement PHP_INI_SCAN_DIR n'est pas définie, `false` est retourné. Si c'était défini et que le dossier était vide, une chaîne vide est retournée. Si un fichier est méconnaissable, le fichier sera quand même inclus dans la chaîne de caractères retournée mais entraînera également une erreur PHP. Cette erreur PHP sera visible à la fois au moment de la compilation et lors de l'utilisation de php_ini_scanned_files().

### Exemples

Exemple #1 Un exemple de liste retournée par php_ini_scanned_files()

    <?php
    if ($filelist = php_ini_scanned_files()) {
        if (strlen($filelist) > 0) {
            $files = explode(',', $filelist);

            foreach ($files as $file) {
                echo "<li>" . trim($file) . "</li>\n";
            }
        }
    }
    ?>

### Voir aussi

- ini_set() - Modifie la valeur d'une option de configuration
- phpinfo() - Affiche de nombreuses informations sur la configuration de PHP
- php_ini_loaded_file() - Récupère le chemin d'un fichier php.ini chargé

# php_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_name — Retourne le type d'interface utilisée entre le serveur web et PHP

### Description

function php_sapi_name(): string|false

Retourne une chaîne en minuscule qui décrit le type d'interface (l'API, SAPI serveur) que PHP utilise. Par exemple, en PHP CLI, cette chaîne sera "cli" tandis qu'avec Apache, elle pourra avoir plusieurs valeurs différentes suivant le SAPI exact utilisé. Les valeurs possibles sont listées ci-dessous.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le type de l'interface, sous la forme d'une chaîne de caractères en minuscule, ou `false` si une erreur survient.

Voici une liste non exhaustive des valeurs possibles : `apache`, `apache2handler`, `cgi` (jusqu'en PHP 5.3), `cgi-fcgi`, `cli`, `cli-server`, `embed`, `fpm-fcgi`, `litespeed`, `phpdbg`.

### Exemples

Exemple #1 Exemple avec php_sapi_name()

Cet exemple cherche la sous-chaîne `cgi` car elle peut également valoir `cgi-fcgi`.

    <?php
    $sapi_type = php_sapi_name();
    if (substr($sapi_type, 0, 3) == 'cgi') {
        echo "Vous utilisez CGI PHP\n";
    } else {
        echo "Vous n'utilisez pas CGI PHP\n";
    }
    ?>

### Notes

> Note: Une approche alternative

> La constante PHP `PHP_SAPI` a une valeur identique à php_sapi_name().

Astuce

# Un comportement inattendu

Le SAPI défini ne doit pas être ambigu, car par exemple, au lieu de `apache`, il peut être défini à `apache2handler`.

### Voir aussi

- PHP_SAPI

# php_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_uname — Retourne les informations sur le système d'exploitation

### Description

function php_uname(string `$mode` = "a"): string

php_uname() retourne une description sur le système d'exploitation sur lequel tourne PHP. C'est la même chaîne que celle que l'on voit en haut du phpinfo(). Pour juste savoir le nom du système d'exploitation, il est préférable d'utiliser la constante `PHP_OS`, en gardant à l'esprit que cette constante contient le nom du système sur lequel PHP a été compilé.

Sur certaines vieilles plate-formes Unix, il n'est pas possible de déterminer les informations courantes de l'OS, auquel cas cette fonction se contente de retourner le nom de l'OS sur lequel PHP a été compilé. Cela n'arrivera que si la bibliothèque `uname()` n'existe pas ou ne fonctionne pas.

### Liste de paramètres

`mode`

  `mode` est un seul caractère qui définit quelles seront les informations à retourner :

  - `'a'` : C'est la valeur par défaut. Retourne les mêmes informations que les modes individuels `'s'`, `'n'`, `'r'`, `'v'`, `'m'` séparées par des espaces.

  - `'s'`: nom du système d'exploitation. Par exemple, `FreeBSD`.
  - `'n'`: nom de l'hôte. Par exemple, `localhost.example.com`.
  - `'r'`: nom de la version. Par exemple, `5.1.2-RELEASE`.
  - `'v'`: information sur la version. Varie énormément suivant le système d'exploitation.
  - `'m'`: type de la machine. Par exemple, `i386`.

### Valeurs de retour

Retourne la description, sous la forme d'une chaîne de caractères.

### Historique

Version | Description
--- | ---
8.4.0 | Lève une exception ValueError lorsqu'un `mode` invalide est spécifié.

### Exemples

Exemple #1 Exemples avec php_uname()

    <?php
    echo php_uname();
    echo PHP_OS;

    /* Affichages possibles :
    Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
    Linux

    FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
    FreeBSD

    Windows NT XN1 5.1 build 2600
    WINNT
    */

    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
        echo 'Le serveur tourne sous Windows !';
    } else {
        echo 'Le serveur ne tourne pas sous Windows !';
    }

    ?>

Il existe aussi des constantes PHP pré-définies liées qui peuvent s'avérer utiles, par exemple :

Exemple #2 Exemples avec quelques constantes liées au système

    <?php
    // *nix
    echo DIRECTORY_SEPARATOR; // /
    echo PHP_SHLIB_SUFFIX;    // so
    echo PATH_SEPARATOR;      // :

    // Win*
    echo DIRECTORY_SEPARATOR; // \
    echo PHP_SHLIB_SUFFIX;    // dll
    echo PATH_SEPARATOR;      // ;
    ?>

### Voir aussi

- phpversion() - Retourne le numéro de la version courante de PHP
- php_sapi_name() - Retourne le type d'interface utilisée entre le serveur web et PHP
- phpinfo() - Affiche de nombreuses informations sur la configuration de PHP

# phpcredits

(PHP 4, PHP 5, PHP 7, PHP 8)

phpcredits — Affiche les crédits de PHP

### Description

function phpcredits(int `$flags` = `CREDITS_ALL`): true

Affiche la liste des développeurs PHP, des modules, etc. Elle génère le code HTML approprié pour insérer les informations dans une page.

### Liste de paramètres

`flags`

  Pour générer une page personnalisée sur les crédits, il faut utiliser le paramètre `flags`.

  Paramètres prédéfinis de phpcredits()
  Nom | Description
  --- | ---
  CREDITS_ALL | Tous les crédits, équivalent à : `CREDITS_DOCS` + `CREDITS_GENERAL` + `CREDITS_GROUP` + `CREDITS_MODULES` + `CREDITS_FULLPAGE`. La fonction génère alors une page HTML complète.
  CREDITS_DOCS | Les crédits du groupe de documentation
  CREDITS_FULLPAGE | En général, ce paramètre est utilisé avec d'autres constantes. Il indique que la page ainsi générée doit être une page HTML complète, avec toutes les balises nécessaires.
  CREDITS_GENERAL | Crédits Généraux : conception et design du langage, auteurs de PHP et du module SAPI.
  CREDITS_GROUP | Une liste des développeurs principaux
  CREDITS_MODULES | Une liste des extensions de PHP, et leurs auteurs
  CREDITS_SAPI | Une liste des API serveur pour PHP et leurs auteurs

### Valeurs de retour

Retourne toujours `true`.

### Exemples

Exemple #1 Exemple avec phpcredits()

    <?php
    phpcredits(CREDITS_GENERAL);
    ?>

Exemple #2 Affiche les développeurs principaux ainsi que le groupe de documentation

    <?php
    phpcredits(CREDITS_GROUP | CREDITS_DOCS | CREDITS_FULLPAGE);
    ?>

Exemple #3 Affiche tous les crédits

    <html>
     <head>
      <title>Ma page de crédits</title>
     </head>
     <body>
    <?php
    // Un peu de votre code
    phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
    // Encore un peu de votre code
    ?>
     </body>
    </html>

### Notes

> Note:

> La fonction phpcredits() affiche du texte plein au lieu du HTML lorsqu'elle est utilisée en mode CLI.

### Voir aussi

- phpversion() - Retourne le numéro de la version courante de PHP
- phpinfo() - Affiche de nombreuses informations sur la configuration de PHP

# phpinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

phpinfo — Affiche de nombreuses informations sur la configuration de PHP

### Description

function phpinfo(int `$flags` = `INFO_ALL`): true

Affiche de nombreuses informations sur PHP, concernant sa configuration courante : options de compilation, extensions, version, informations sur le serveur, et l'environnement (lorsqu'il est compilé comme module), environnement PHP, informations sur le système, chemins, valeurs générales et locales de configuration, en-têtes HTTP et la licence PHP.

Comme tous les systèmes sont configurés différemment, phpinfo() sert généralement à vérifier la configuration ainsi que les variables prédéfinies, pour une plate-forme donnée.

phpinfo() est un bon outil de débogage, car il affiche le contenu de toutes les variables EGPCS (Environnement, GET, POST, Cookie, Serveur).

### Liste de paramètres

`flags`

  L'affichage peut être personnalisé en utilisant une ou plusieurs des constantes suivantes. Elles sont combinables avec l' opérateur sur les bits ou , et doivent être passées dans le paramètre `flags`. Il est aussi possible de additionner ces constantes.

  Options de phpinfo()
  Nom de la constante | Valeur | Description
  --- | --- | ---
  INFO_GENERAL | 1 | La ligne de configuration, le chemin du php.ini, la date de compilation, le serveur web, le système, etc.
  INFO_CREDITS | 2 | Les crédits de PHP. Voir aussi phpcredits().
  INFO_CONFIGURATION | 4 | Valeurs courantes locales et générales des directives PHP. Voir aussi la fonction ini_get().
  INFO_MODULES | 8 | Modules chargés et leur configuration spécifique. Voir aussi la fonction get_loaded_extensions().
  INFO_ENVIRONMENT | 16 | Informations sur les variables d'environnement, qui sont disponibles dans la variable $_ENV.
  INFO_VARIABLES | 32 | Affiche toutes les variables prédéfinies, issues de l'environnement, la méthode GET, la méthode POST, les cookies et le serveur.
  INFO_LICENSE | 64 | La licence PHP. Voir aussi » la FAQ de la licence.
  INFO_ALL | -1 | Affiche toutes les informations susmentionnées.

### Valeurs de retour

Retourne toujours `true`.

### Exemples

Exemple #1 Exemple avec phpinfo()

    <?php

    // Affiche toutes les informations, comme le ferait INFO_ALL
    phpinfo();

    // Affiche uniquement le module d'information.
    // phpinfo(8) fournirait les mêmes informations.
    phpinfo(INFO_MODULES);

    ?>

### Notes

> Note:

> Dans les versions antérieures à PHP 5.5, une partie des informations affichées sont désactivées si la directive expose_php est configurée avec la valeur `off`. Cela inclut les logos PHP et Zend, ainsi que les crédits.

> Note:

> phpinfo() affiche du texte au lieu d'HTML lorsque l'on utilise la version CLI.

### Voir aussi

- phpversion() - Retourne le numéro de la version courante de PHP
- phpcredits() - Affiche les crédits de PHP
- ini_get() - Lit la valeur d'une option de configuration
- ini_set() - Modifie la valeur d'une option de configuration
- get_loaded_extensions() - Retourne la liste de tous les modules compilés et chargés
- les variables prédéfinies

# phpversion

(PHP 4, PHP 5, PHP 7, PHP 8)

phpversion — Retourne le numéro de la version courante de PHP

### Description

function phpversion(?string `$extension` = `null`): string|false

Retourne le numéro de la version courante de PHP.

### Liste de paramètres

`extension`

  Un nom d'extension, optionnel.

### Valeurs de retour

Retourne la version actuelle de PHP en tant que string. Si un argument string est fourni au paramètre `extension`, phpversion() retourne la version de cette extension, ou `false` s'il n'y a pas d'information de version associée ou que cette extension n'est pas activée.

### Historique

Version | Description
--- | ---
8.0.0 | `extension` est désormais nullable.

### Exemples

Exemple #1 Exemple avec phpversion()

    <?php

    // affiche le numéro de version courante du PHP.
    echo 'Version PHP courante : ' . phpversion();

    // affiche e.g. '1.22.3' ou rien du tout si cette extension n'est pas active
    echo phpversion('tidy');
    ?>

Exemple #2 Exemple avec `PHP_VERSION_ID`

    <?php

    /**
     * PHP_VERSION_ID est défini comme un nombre, où plus le nombre est élevé,
     * plus la version de PHP utilisée est récente. Il est défini comme dans
     * l'expression ci-dessus :
     *
     * $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
     *
     * Maintenant, avec PHP_VERSION_ID, nous pouvons vérifier les fonctionnalités
     * que cette version de PHP peut avoir, ce qui évite d'utiliser version_compare()
     * à chaque fois que l'on vérifie si la version de PHP actuelle peut ne pas
     * prendre en charge une fonctionnalité.
     *
     * Par exemple, nous pouvons ici définir les constantes PHP_*_VERSION qui ne
     * sont pas disponibles dans les versions à partir de 5.2.7.
     */

    if (PHP_VERSION_ID < 50207) {
        define('PHP_MAJOR_VERSION',   $version[0]);
        define('PHP_MINOR_VERSION',   $version[1]);
        define('PHP_RELEASE_VERSION', $version[2]);

        // etc.

    }

    ?>

### Notes

> Note:

> Cette information est aussi disponible via la constante prédéfinie `PHP_VERSION`. Plus d'informations sur les versions, avec les constantes `PHP_VERSION_*`.

> Note:

> Certaines extensions peuvent définir leur propre numéro de version. Cependant, la plupart des extensions incluses utiliseront la version de PHP comme numéro de version.

### Voir aussi

- les constantes PHP_VERSION
- version_compare() - Compare deux chaînes de version au format des versions PHP
- phpinfo() - Affiche de nombreuses informations sur la configuration de PHP
- phpcredits() - Affiche les crédits de PHP
- zend_version() - Lit la version courante du moteur Zend

# putenv

(PHP 4, PHP 5, PHP 7, PHP 8)

putenv — Fixe la valeur d'une variable d'environnement

### Description

function putenv(string `$assignment`): bool

Ajoute `assignment` à l'environnement serveur. Cette valeur n'existera que durant la vie de la requête courante, et l'environnement initial sera restauré lorsque le script sera terminé.

### Liste de paramètres

`assignment`

  La configuration, comme `"FOO=BAR"`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Modification d'une variable d'environnement

    <?php
    putenv("UNIQID=$uniqid");
    ?>

### Voir aussi

- getenv() - Retourne la valeur d'une seule ou toutes les variables d'environnement
- apache_setenv() - Modifie une variable de processus Apache

# restore_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

restore_include_path — Restaure la valeur de la directive de configuration include_path

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.4.0, et a été SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function restore_include_path(): void

Restaure la valeur de la directive de configuration include_path à sa valeur originale de début de script, telle qu'inscrite dans le php.ini.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction a été supprimée.
7.4.0 | Cette fonction est obsolète.

### Exemples

Exemple #1 Exemple avec restore_include_path()

    <?php

    echo get_include_path();  // .:/usr/local/lib/php

    set_include_path('/inc');

    echo get_include_path();  // /inc

    restore_include_path();

    // Ou utiliser ini_restore()
    ini_restore('include_path');

    echo get_include_path();  // .:/usr/local/lib/php

    ?>

### Voir aussi

- ini_restore() - Restaure la valeur de l'option de configuration
- get_include_path() - Lit la valeur de la directive de configuration include_path
- set_include_path() - Modifie la valeur de la directive de configuration include_path
- include - include

# set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_path — Modifie la valeur de la directive de configuration include_path

### Description

function set_include_path(string `$include_path`): string|false

Modifie la valeur de la directive de configuration include_path, pour la durée du script en cours.

### Liste de paramètres

`include_path`

  La nouvelle valeur pour la directive de configuration include_path

### Valeurs de retour

Retourne l'ancienne valeur de include_path en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec set_include_path()

    <?php
    set_include_path('/usr/lib/pear');

    // Ou utiliser ini_set()
    ini_set('include_path', '/usr/lib/pear');
    ?>

Exemple #2 Ajout dans le chemin d'inclusion

En utilisant la constante `PATH_SEPARATOR`, il est possible d'étendre le chemin d'inclusion au vu du système.

Dans cet exemple, nous ajoutons /usr/lib/pear à la fin de l'actuel `include_path`.

    <?php
    $path = '/usr/lib/pear';
    set_include_path(get_include_path() . PATH_SEPARATOR . $path);
    ?>

### Voir aussi

- ini_set() - Modifie la valeur d'une option de configuration
- get_include_path() - Lit la valeur de la directive de configuration include_path
- restore_include_path() - Restaure la valeur de la directive de configuration include_path
- include - include

# set_time_limit

(PHP 4, PHP 5, PHP 7, PHP 8)

set_time_limit — Fixe le temps maximum d'exécution d'un script

### Description

function set_time_limit(int `$seconds`): bool

Fixe le délai d'expiration d'un script, en secondes. Si cette limite est atteinte, le script s'interrompt, et renvoie une erreur fatale. La valeur par défaut est 30 secondes ou, si c'est le cas, la valeur de la directive `max_execution_time` définie dans le php.ini.

Lorsqu'elle est appelée, set_time_limit() remet le compteur à zéro. En d'autres termes, si la limite par défaut est à 30 secondes, et qu'après 25 secondes d'exécution du script l'appel `set_time_limit(20)` est fait, alors le script tournera pendant un total de 45 secondes avant de finir.

### Liste de paramètres

`seconds`

  Le temps maximal d'exécution, en secondes. S'il vaut `0`, aucune limite n'est imposée.

### Valeurs de retour

Retourne `true` en cas de succès, ou `false` si une erreur survient.

### Notes

> Note:

> La fonction set_time_limit() et la directive de configuration max_execution_time n'affectent que le temps d'exécution du script lui-même. Tout temps passé en dehors du script, comme un appel système utilisant system(), des opérations sur les flux, les requêtes sur base de données, etc. n'est pas pris en compte lors du calcul de la durée maximale d'exécution du script. Ceci est faux sous Windows où le temps mesuré est le temps réel.

### Voir aussi

- max_execution_time
- max_input_time

# sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dir — Retourne le chemin du répertoire utilisé pour les fichiers temporaires

### Description

function sys_get_temp_dir(): string

Retourne le chemin du répertoire PHP où sont enregistrés les fichiers temporaires par défaut.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le chemin du répertoire temporaire.

### Exemples

Exemple #1 Exemple avec sys_get_temp_dir()

    <?php
    // Création d'un fichier temporaire dans le dossier
    // des fichiers temporaires, en utilisant la fonction sys_get_temp_dir()
    $temp_file = tempnam(sys_get_temp_dir(), 'Tux');

    echo $temp_file;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    C:\Windows\Temp\TuxA318.tmp

### Voir aussi

- tmpfile() - Crée un fichier temporaire
- tempnam() - Crée un fichier avec un nom unique

# version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compare — Compare deux chaînes de version au format des versions PHP

### Description

function version_compare(string `$version1`, string `$version2`, ?string `$operator` = `null`): int|bool

version_compare() compare les deux versions de PHP standardisées.

version_compare() remplace dans un premier temps `_`, `-` et `+` par un point (`.`) dans les chaînes de version et insère aussi des points avant et après tout caractère non-numérique pour que, par exemple, '4.3.5RC1' devienne '4.3.5.RC.1'. Puis, elle compare les morceaux en allant de gauche à droite. Si une part contient des caractères alphabétiques, ils sont gérés dans l'ordre suivant : `any string not found in this list` < `dev` < `alpha` = `a` < `beta` = `b` < `RC` = `rc` < `#` < `pl` = `p`. De cette façon, il est possible de comparer non seulement des versions de différents niveaux, comme '4.1' et '4.1.2', mais aussi des versions de développement de PHP, à n'importe quel stade.

### Liste de paramètres

`version1`

  Premier numéro de version.

`version2`

  Second numéro de version.

`operator`

  Un opérateur optionnel. Les opérateurs possibles sont : `<`, `lt`, `<=`, `le`, `>`, `gt`, `>=`, `ge`, `==`, `=`, `eq`, `!=`, `<>`, `ne` respectivement.

  Ce paramètre est sensible à la casse, les valeurs doivent donc être en minuscules.

### Valeurs de retour

Par défaut, version_compare() retourne `-1` si la première version est inférieure à la seconde, `0` si elles sont égales, et `1` si la seconde est inférieure à la première.

Lorsque l'on utilise le paramètre optionnel `operator`, la fonction retourne `true` si la relation est celle spécifiée par l'opérateur, `false` sinon.

### Exemples

Les exemples ci-dessous utilisent la constante `PHP_VERSION`, sachant qu'elle contient la valeur de la version de PHP utilisée pour exécuter le code.

Exemple #1 Exemple avec version_compare()

    <?php
    if (version_compare(PHP_VERSION, '7.0.0') >= 0) {
        echo 'J\'ai au moins la version 7.0.0 de PHP ; ma version : ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
        echo 'J\'ai au moins la version 5.3.0 de PHP ; ma version : ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '>=')) {
        echo 'J\'ai au moins la version 5.0.0 de PHP ; ma version : ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '<')) {
        echo 'J\'utilise encore PHP 4 ; ma version : ' . PHP_VERSION . "\n";
    }
    ?>

### Notes

> Note:

> La constante `PHP_VERSION` contient la version courante de PHP.

> Note:

> Il est à noter que les versions intermédiaires, comme `5.3.0-dev`, sont considérées comme inférieures à leurs versions finales (telle que 5.3.0).

> Note:

> Les chaînes spéciales de version comme `alpha` et `beta` sont sensibles à la casse. Les chaînes de version issues de sources arbitraires qui n'adhèrent pas au standard PHP doivent être mises en minuscule en utilisant la fonction strtolower() avant d'appeler la fonction version_compare().

### Voir aussi

- phpversion() - Retourne le numéro de la version courante de PHP
- php_uname() - Retourne les informations sur le système d'exploitation
- function_exists() - Indique si une fonction est définie

# zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_id — Retourne un identifiant unique du thread courant

### Description

function zend_thread_id(): int

Cette fonction retourne un identifiant unique pour le thread courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'identifiant du thread, sous la forme d'un entier.

### Exemples

Exemple #1 Exemple avec zend_thread_id()

    <?php
    $thread_id = zend_thread_id();

    echo 'ID du thread courant : ' . $thread_id;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    ID du thread courant : 7864

### Notes

> Note:

> Cette fonction n'est disponible que si PHP a été compilé avec le support ZTS (`Zend Thread Safety`) et le mode de débogage (`--enable-debug`).

# zend_version

(PHP 4, PHP 5, PHP 7, PHP 8)

zend_version — Lit la version courante du moteur Zend

### Description

function zend_version(): string

Retourne une chaîne contenant le numéro de version du moteur d'analyse Zend actuellement en cours d'utilisation.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le numéro de la version du moteur Zend, sous la forme d'une chaîne de caractères.

### Exemples

Exemple #1 Exemple avec zend_version()

    <?php
    echo "Version du moteur Zend : " . zend_version();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Version du moteur Zend : 2.2.0

### Voir aussi

- phpinfo() - Affiche de nombreuses informations sur la configuration de PHP
- phpcredits() - Affiche les crédits de PHP
- phpversion() - Retourne le numéro de la version courante de PHP

## Sommaire

- assert — Vérifie une assertion
- assert_options — Définit/récupère différentes options d'assertions
- cli_get_process_title — Retourne le titre du processus courant
- cli_set_process_title — Définit le titre du processus
- dl — Charge une extension PHP à la volée
- extension_loaded — Détermine si une extension est chargée ou non
- gc_collect_cycles — Force le passage du collecteur de mémoire
- gc_disable — Désactive le collecteur de références circulaires
- gc_enable — Active le collecteur de références circulaires
- gc_enabled — Retourne le statut du collecteur de références circulaires
- gc_mem_caches — Récupère de la mémoire utilisée par le gestionnaire de mémoire de Zend Engine
- gc_status — Récupère les informations à propos du ramasse-miettes
- get_cfg_var — Retourne la valeur d'une option de PHP
- get_current_user — Retourne le nom du possesseur du script courant
- get_defined_constants — Retourne la liste des constantes et leurs valeurs
- get_extension_funcs — Liste les fonctions d'une extension
- get_include_path — Lit la valeur de la directive de configuration include_path
- get_included_files — Retourne un tableau avec les noms des fichiers qui sont inclus dans un script
- get_loaded_extensions — Retourne la liste de tous les modules compilés et chargés
- get_magic_quotes_gpc — Retourne la configuration actuelle de l'option magic_quotes_gpc
- get_magic_quotes_runtime — Retourne la configuration actuelle de l'option magic_quotes_runtime
- get_required_files — Alias de get_included_files
- get_resources — Retourne les ressources actives
- getenv — Retourne la valeur d'une seule ou toutes les variables d'environnement
- getlastmod — Retourne la date de dernière modification de la page
- getmygid — Retourne le GID du propriétaire du script
- getmyinode — Retourne l'inode du script
- getmypid — Retourne le numéro de processus courant de PHP
- getmyuid — Retourne l'UID du propriétaire du script actuel
- getopt — Lit des options passées dans la ligne de commande
- getrusage — Retourne le niveau d'utilisation des ressources
- ini_alter — Alias de ini_set
- ini_get — Lit la valeur d'une option de configuration
- ini_get_all — Lit toutes les valeurs de configuration
- ini_parse_quantity — Renvoie la taille interprétée à partir de la syntaxe abrégée ini
- ini_restore — Restaure la valeur de l'option de configuration
- ini_set — Modifie la valeur d'une option de configuration
- memory_get_peak_usage — Retourne la quantité de mémoire maximale allouée par PHP
- memory_get_usage — Indique la quantité de mémoire utilisée par PHP
- memory_reset_peak_usage — Réinitialise l'utilisation maximale de la mémoire
- php_ini_loaded_file — Récupère le chemin d'un fichier php.ini chargé
- php_ini_scanned_files — Retourne la liste des fichiers .ini analysés dans les dossiers de configuration supplémentaires
- php_sapi_name — Retourne le type d'interface utilisée entre le serveur web et PHP
- php_uname — Retourne les informations sur le système d'exploitation
- phpcredits — Affiche les crédits de PHP
- phpinfo — Affiche de nombreuses informations sur la configuration de PHP
- phpversion — Retourne le numéro de la version courante de PHP
- putenv — Fixe la valeur d'une variable d'environnement
- restore_include_path — Restaure la valeur de la directive de configuration include_path
- set_include_path — Modifie la valeur de la directive de configuration include_path
- set_time_limit — Fixe le temps maximum d'exécution d'un script
- sys_get_temp_dir — Retourne le chemin du répertoire utilisé pour les fichiers temporaires
- version_compare — Compare deux chaînes de version au format des versions PHP
- zend_thread_id — Retourne un identifiant unique du thread courant
- zend_version — Lit la version courante du moteur Zend

- Installation/Configuration
  - Configuration à l'exécution
- Constantes pré-définies
- Fonctions sur les options et les informations de PHP
  - assert — Vérifie une assertion
  - assert_options — Définit/récupère différentes options d'assertions
  - cli_get_process_title — Retourne le titre du processus courant
  - cli_set_process_title — Définit le titre du processus
  - dl — Charge une extension PHP à la volée
  - extension_loaded — Détermine si une extension est chargée ou non
  - gc_collect_cycles — Force le passage du collecteur de mémoire
  - gc_disable — Désactive le collecteur de références circulaires
  - gc_enable — Active le collecteur de références circulaires
  - gc_enabled — Retourne le statut du collecteur de références circulaires
  - gc_mem_caches — Récupère de la mémoire utilisée par le gestionnaire de mémoire de Zend Engine
  - gc_status — Récupère les informations à propos du ramasse-miettes
  - get_cfg_var — Retourne la valeur d'une option de PHP
  - get_current_user — Retourne le nom du possesseur du script courant
  - get_defined_constants — Retourne la liste des constantes et leurs valeurs
  - get_extension_funcs — Liste les fonctions d'une extension
  - get_include_path — Lit la valeur de la directive de configuration include_path
  - get_included_files — Retourne un tableau avec les noms des fichiers qui sont inclus dans un script
  - get_loaded_extensions — Retourne la liste de tous les modules compilés et chargés
  - get_magic_quotes_gpc — Retourne la configuration actuelle de l'option magic_quotes_gpc
  - get_magic_quotes_runtime — Retourne la configuration actuelle de l'option magic_quotes_runtime
  - get_required_files — Alias de get_included_files
  - get_resources — Retourne les ressources actives
  - getenv — Retourne la valeur d'une seule ou toutes les variables d'environnement
  - getlastmod — Retourne la date de dernière modification de la page
  - getmygid — Retourne le GID du propriétaire du script
  - getmyinode — Retourne l'inode du script
  - getmypid — Retourne le numéro de processus courant de PHP
  - getmyuid — Retourne l'UID du propriétaire du script actuel
  - getopt — Lit des options passées dans la ligne de commande
  - getrusage — Retourne le niveau d'utilisation des ressources
  - ini_alter — Alias de ini_set
  - ini_get — Lit la valeur d'une option de configuration
  - ini_get_all — Lit toutes les valeurs de configuration
  - ini_parse_quantity — Renvoie la taille interprétée à partir de la syntaxe abrégée ini
  - ini_restore — Restaure la valeur de l'option de configuration
  - ini_set — Modifie la valeur d'une option de configuration
  - memory_get_peak_usage — Retourne la quantité de mémoire maximale allouée par PHP
  - memory_get_usage — Indique la quantité de mémoire utilisée par PHP
  - memory_reset_peak_usage — Réinitialise l'utilisation maximale de la mémoire
  - php_ini_loaded_file — Récupère le chemin d'un fichier php.ini chargé
  - php_ini_scanned_files — Retourne la liste des fichiers .ini analysés dans les dossiers de configuration supplémentaires
  - php_sapi_name — Retourne le type d'interface utilisée entre le serveur web et PHP
  - php_uname — Retourne les informations sur le système d'exploitation
  - phpcredits — Affiche les crédits de PHP
  - phpinfo — Affiche de nombreuses informations sur la configuration de PHP
  - phpversion — Retourne le numéro de la version courante de PHP
  - putenv — Fixe la valeur d'une variable d'environnement
  - restore_include_path — Restaure la valeur de la directive de configuration include_path
  - set_include_path — Modifie la valeur de la directive de configuration include_path
  - set_time_limit — Fixe le temps maximum d'exécution d'un script
  - sys_get_temp_dir — Retourne le chemin du répertoire utilisé pour les fichiers temporaires
  - version_compare — Compare deux chaînes de version au format des versions PHP
  - zend_thread_id — Retourne un identifiant unique du thread courant
  - zend_version — Lit la version courante du moteur Zend

# Débogueur PHP interactif

# Introduction

Implémenté en tant que module SAPI, phpdbg peut exercer un contrôle complet sur l'environnement sans impacter la fonctionnalité ou les performances du code.

phpdbg vise à être une plateforme de débogage légère, puissante et facile à utiliser pour PHP. Il offre les fonctionnalités suivantes :

- Débogage pas à pas
- Point d'arrêt flexible (méthode de classe, fonction, fichier:ligne, adresse, opcode)
- Accès facile à PHP avec eval() intégré
- Une API utilisateur
- SAPI Agnostique - Facilement intégrable
- Support de fichier de configuration PHP
- Super Globales JIT - Définissez les vôtres !!
- Le support readline en option - Opération confortable du terminal
- Opération facile - Voir l'aide :)

Options en ligne de commande
Option | Argument d'exemple | Description
--- | --- | ---
-c | -c/my/php.ini | Définit le fichier php.ini à charger
-d | -dmemory_limit=4G | Définit une directive php.ini
-n |  | Désactive le php.ini par défaut
-q |  | Supprime la bannière de bienvenue
-v |  | Active la sortie oplog
-b |  | Désactive la couleur
-i | -imy.init | Définit le fichier .phpdbginit
-I |  | Ignore le .phpdbginit par défaut
-O | -Omy.oplog | Définit le fichier de sortie oplog
-r |  | Exécute le contexte d'exécution
-rr |  | Exécute le contexte d'exécution et quitte après l'exécution (sans respecter les points d'arrêt)
-e |  | Génère des informations étendues pour le débogueur/profiler
-E |  | Active l'évaluation pas à pas avec eval, attention !
-s | -s=, -s=foo | Lit le code à exécuter depuis stdin avec un délimiteur optionnel
-S | -Scli | Surcharge le nom SAPI, attention !
-l | -l4000 | Met en place le port de la console distante
-a | -a192.168.0.3 | Met en place l'adresse de liaison de la console distante
-x |  | Active la sortie xml (au lieu de la sortie texte normale)
-p | -p, -p=func, -p* | Affiche les opcodes et quitte
-h |  | Affiche l'aperçu de l'aide
-V |  | Affiche le numéro de version
-- | -- arg1 arg2 | Utilisé pour délimiter les arguments phpdbg et php $argv; ajoutez tout argument $argv après

# Installation/Configuration

## Sommaire

- Configuration à l'exécution

## Configuration à l'exécution

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

Options de configuration de phpdbg
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
phpdbg.eol | 2 | `INI_ALL` | Supprimée à partir de PHP 8.1.0
phpdbg.path |  | 6 | Supprimée à partir de PHP 8.1.0

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

`phpdbg.eol` mixed

  Le type de fin de ligne à utiliser pour la sortie. Pour définir la valeur, l'un des alias de chaîne doit être utilisé.

  int Value | string Alias
  --- | ---
  `0` | `CRLF`, `crlf`, `DOS`, `dos`
  `1` | `LF`, `lf`, `UNIX`, `unix`
  `2` | `CR`, `cr`, `MAC`, `mac`

`phpdbg.path` string

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`PHPDBG_VERSION` (string)
`PHPDBG_FILE` (int)
  Supprimé à partir de PHP 7.3.0.
`PHPDBG_METHOD` (int)
  Supprimé à partir de PHP 7.3.0.
`PHPDBG_LINENO` (int)
  Supprimé à partir de PHP 7.3.0.
`PHPDBG_FUNC` (int)
  Supprimé à partir de PHP 7.3.0.
`PHPDBG_COLOR_PROMPT` (int)
`PHPDBG_COLOR_NOTICE` (int)
`PHPDBG_COLOR_ERROR` (int)

# Fonctions phpdbg

# phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_file — Insère un point d'arrêt dans une ligne d'un fichier

### Description

function phpdbg_break_file(string `$file`, int `$line`): void

Insère un point d'arrêt à la ligne `line` dans le fichier `file`.

### Liste de paramètres

`file`
  Le nom du fichier.
`line`
  Le numéro de la ligne.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- phpdbg_break_function() - Insère un point d'arrêt à l'entrée d'une fonction
- phpdbg_break_method() - Insère un point d'arrêt à l'entrée d'une méthode
- phpdbg_break_next() - Insère un point d'arrêt au prochain opcode
- phpdbg_clear() - Supprime tous les points d'arrêt

# phpdbg_break_function

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_function — Insère un point d'arrêt à l'entrée d'une fonction

### Description

function phpdbg_break_function(string `$function`): void

Insère un point d'arrêt à l'entrée de la fonction `function`.

### Liste de paramètres

`function`
  Le nom de la fonction.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- phpdbg_break_file() - Insère un point d'arrêt dans une ligne d'un fichier
- phpdbg_break_method() - Insère un point d'arrêt à l'entrée d'une méthode
- phpdbg_break_next() - Insère un point d'arrêt au prochain opcode
- phpdbg_clear() - Supprime tous les points d'arrêt

# phpdbg_break_method

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_method — Insère un point d'arrêt à l'entrée d'une méthode

### Description

function phpdbg_break_method(string `$class`, string `$method`): void

Insère un point d'arrêt à l'entrée de la méthode `method` de la classe `class`.

### Liste de paramètres

`class`
  Le nom de la classe.
`method`
  Le nom de la méthode.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- phpdbg_break_file() - Insère un point d'arrêt dans une ligne d'un fichier
- phpdbg_break_function() - Insère un point d'arrêt à l'entrée d'une fonction
- phpdbg_break_next() - Insère un point d'arrêt au prochain opcode
- phpdbg_clear() - Supprime tous les points d'arrêt

# phpdbg_break_next

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_next — Insère un point d'arrêt au prochain opcode

### Description

function phpdbg_break_next(): void

Insère un point d'arrêt au prochain opcode.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- phpdbg_break_file() - Insère un point d'arrêt dans une ligne d'un fichier
- phpdbg_break_function() - Insère un point d'arrêt à l'entrée d'une fonction
- phpdbg_break_method() - Insère un point d'arrêt à l'entrée d'une méthode
- phpdbg_clear() - Supprime tous les points d'arrêt

# phpdbg_clear

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_clear — Supprime tous les points d'arrêt

### Description

function phpdbg_clear(): void

Supprime tous les points d'arrêt qui ont été définis, soit via une des fonctions phpdbg_break_*(), ou interactivement via la console.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- phpdbg_break_file() - Insère un point d'arrêt dans une ligne d'un fichier
- phpdbg_break_function() - Insère un point d'arrêt à l'entrée d'une fonction
- phpdbg_break_method() - Insère un point d'arrêt à l'entrée d'une méthode
- phpdbg_break_next() - Insère un point d'arrêt au prochain opcode

# phpdbg_color

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_color — Définit la couleur de certains éléments

### Description

function phpdbg_color(int `$element`, string `$color`): void

Définit la couleur `color` pour l'élément `element`.

### Liste de paramètres

`element`
  Une des constantes `PHPDBG_COLOR_*`.
`color`
  Le nom de la couleur. Peut être `white`, `red`, `green`, `yellow`, `blue`, `purple`, `cyan` ou `black`, et, optionnellement, avec les compléments `-bold` ou `-underline` ; par exemple `white-bold` ou `green-underline`.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- phpdbg_prompt() - Définit l'invite de commande

# phpdbg_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog — Finit un oplog

### Description

function phpdbg_end_oplog(array `$options` = []): ?array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`options`

### Valeurs de retour

# phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_exec — Tente de définir le contexte d'exécution

### Description

function phpdbg_exec(string `$context`): string|bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`context`

### Valeurs de retour

Si le contexte d'exécution a été défini précédemment, il sera retourné. Si le contexte d'exécution n'a pas été défini, `true` sera retourné. Si une erreur est survenue pendant la définition du contexte, `false` sera retourné et une erreur de niveau `E_WARNING` sera émise.

# phpdbg_get_executable

(PHP 7, PHP 8)

phpdbg_get_executable — Renvoie un exécutable

### Description

function phpdbg_get_executable(array `$options` = []): array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`options`

### Valeurs de retour

# phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_prompt — Définit l'invite de commande

### Description

function phpdbg_prompt(string `$string`): void

Définit l'invite de commande pour la chaîne `string`.

### Liste de paramètres

`string`
  La chaîne à utiliser comme invite de commande.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- phpdbg_color() - Définit la couleur de certains éléments

# phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog — Commence un oplog

### Description

function phpdbg_start_oplog(): void

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

## Sommaire

- phpdbg_break_file — Insère un point d'arrêt dans une ligne d'un fichier
- phpdbg_break_function — Insère un point d'arrêt à l'entrée d'une fonction
- phpdbg_break_method — Insère un point d'arrêt à l'entrée d'une méthode
- phpdbg_break_next — Insère un point d'arrêt au prochain opcode
- phpdbg_clear — Supprime tous les points d'arrêt
- phpdbg_color — Définit la couleur de certains éléments
- phpdbg_end_oplog — Finit un oplog
- phpdbg_exec — Tente de définir le contexte d'exécution
- phpdbg_get_executable — Renvoie un exécutable
- phpdbg_prompt — Définit l'invite de commande
- phpdbg_start_oplog — Commence un oplog

- Installation/Configuration
  - Configuration à l'exécution
- Constantes pré-définies
- Fonctions phpdbg
  - phpdbg_break_file — Insère un point d'arrêt dans une ligne d'un fichier
  - phpdbg_break_function — Insère un point d'arrêt à l'entrée d'une fonction
  - phpdbg_break_method — Insère un point d'arrêt à l'entrée d'une méthode
  - phpdbg_break_next — Insère un point d'arrêt au prochain opcode
  - phpdbg_clear — Supprime tous les points d'arrêt
  - phpdbg_color — Définit la couleur de certains éléments
  - phpdbg_end_oplog — Finit un oplog
  - phpdbg_exec — Tente de définir le contexte d'exécution
  - phpdbg_get_executable — Renvoie un exécutable
  - phpdbg_prompt — Définit l'invite de commande
  - phpdbg_start_oplog — Commence un oplog

# runkit7

# Introduction

L'extension runkit7 fournit des moyens pour modifier les constantes, les fonctions définies par l'utilisateur et les classes définies par l'utilisateur. Elle fournit également des variables superglobales personnalisées.

Ce paquet est un fork du paquet » runkit fournissant un support PHP 7.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

Modifier les constantes, fonctions, classes et méthodes ainsi que les superglobales personnalisées fonctionne avec toutes les versions de PHP 7. Aucune exigence spéciale n'est nécessaire.

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/runkit7.

Les binaires Windows (les fichiers DLL) pour cette extension PECL sont disponibles sur le site web PECL.

## Configuration à l'exécution

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

Options de configuration de Runkit
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
runkit.superglobal | "" | `INI_PERDIR` |
runkit.internal_override | "0" | `INI_SYSTEM` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`runkit.superglobal` string
  Une liste séparée par des virgules de noms de variables à traiter comme des superglobales. Cette valeur doit être définie dans le fichier php.ini du système, mais peut fonctionner dans des contextes de configuration perdir en fonction du SAPI.

  Exemple #1 Superglobales personnalisées avec runkit.superglobal=_FOO,_BAR dans php.ini

      <?php
      function show_values() {
        echo "Foo is $_FOO\n";
        echo "Bar is $_BAR\n";
        echo "Baz is $_BAZ\n";
      }

      $_FOO = 'foo';
      $_BAR = 'bar';
      $_BAZ = 'baz';

      /* Affiche foo et bar, mais pas baz */
      show_values();
      ?>

`runkit.internal_override` bool
  Active la possibilité de modifier/renommer/supprimer des fonctions internes.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`RUNKIT7_IMPORT_FUNCTIONS` (int)
  Le drapeau runkit7_import() indique que les fonctions normales doivent être importées du fichier spécifié.
`RUNKIT7_IMPORT_CLASS_METHODS` (int)
  Le drapeau runkit7_import() indique que les méthodes de classe doivent être importées du fichier spécifié.
`RUNKIT7_IMPORT_CLASS_CONSTS` (int)
  Le drapeau runkit7_import() indique que les constantes de classe doivent être importées du fichier spécifié.
`RUNKIT7_IMPORT_CLASS_PROPS` (int)
  Le drapeau runkit7_import() indique que les propriétés de classe standard doivent être importées du fichier spécifié.
`RUNKIT7_IMPORT_CLASS_STATIC_PROPS` (int)
  Le drapeau runkit7_import() indique que les propriétés statiques de classe doivent être importées du fichier spécifié. Disponible depuis Runkit 1.0.1.
`RUNKIT7_IMPORT_CLASSES` (int)
  Le drapeau runkit7_import() représente un OU binaire des constantes `RUNKIT7_IMPORT_CLASS_*`.
`RUNKIT7_IMPORT_OVERRIDE` (int)
  Le drapeau runkit7_import() indique que si une des fonctions, méthodes, constantes, ou propriétés importées existent déjà, elles doivent être remplacées par les nouvelles définitions. Si ce drapeau n'est pas défini, alors toutes les définitions importées qui existent déjà seront ignorées.
`RUNKIT7_ACC_RETURN_REFERENCE` (int)
  Inclure ce drapeau pour faire en sorte que la fonction ou la méthode créée ou redéfinie retourne une référence.
`RUNKIT7_ACC_PUBLIC` (int)
  Le drapeau pour runkit7_method_add() et runkit7_method_redefine() pour rendre la méthode publique.
`RUNKIT7_ACC_PROTECTED` (int)
  Le drapeau pour runkit7_method_add() et runkit7_method_redefine() pour rendre la méthode protégée.
`RUNKIT7_ACC_PRIVATE` (int)
  Le drapeau pour runkit7_method_add() et runkit7_method_redefine() pour rendre la méthode privée.
`RUNKIT7_ACC_STATIC` (int)
  Le drapeau pour runkit7_method_add() et runkit7_method_redefine() pour rendre la méthode statique.
`RUNKIT7_FEATURE_MANIPULATION` (int)
  Égale à un si la manipulation en temps d'exécution est activée, et 0 sinon.
`RUNKIT7_FEATURE_SUPERGLOBALS` (int)
  Égale à 1 si les superglobales personnalisées sont activées, et 0 sinon.
`RUNKIT7_FEATURE_SANDBOX` (int)
  Toujours 0, il est impraticable d'implémenter la fonctionnalité de bac à sable en php 7.

# Fonctions de runkit7

# runkit7_constant_add

(PECL runkit7 >= Unknown)

runkit7_constant_add — Similaire à define(), mais permet de définir dans les définitions de classe également

### Description

function runkit7_constant_add(string `$constant_name`, mixed `$value`, int `$newVisibility` = ?): bool

### Liste de paramètres

`constant_name`
  Le nom de la constante à déclarer. Soit une chaîne pour indiquer une constante globale, soit `classname::constname` pour indiquer une constante de classe.
`value`
  NULL, Bool, Long, Double, String, Array, ou Resource à stocker dans la nouvelle constante.
`newVisibility`
  La visibilité de la constante, pour les constantes de classe. Public par défaut. L'une des constantes `RUNKIT7_ACC_*`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- define() - Définit une constante
- runkit7_constant_redefine() - Redéfinit une constante déjà définie
- runkit7_constant_remove() - Enlève/Supprime une constante déjà définie

# runkit7_constant_redefine

(PECL runkit7 >= Unknown)

runkit7_constant_redefine — Redéfinit une constante déjà définie

### Description

function runkit7_constant_redefine(string `$constant_name`, mixed `$value`, int `$new_visibility` = ?): bool

### Liste de paramètres

`constant_name`
  La constante à redéfinir. Soit le nom d'une constante globale, soit `classname::constname` indiquant une constante de classe.
`value`
  La valeur à assigner à la constante.
`new_visibility`
  La nouvelle visibilité de la constante, pour les constantes de classe. Par défaut inchangé. L'une des constantes `RUNKIT7_ACC_*`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- runkit7_constant_add() - Similaire à define(), mais permet de définir dans les définitions de classe également
- runkit7_constant_remove() - Enlève/Supprime une constante déjà définie

# runkit7_constant_remove

(PECL runkit7 >= Unknown)

runkit7_constant_remove — Enlève/Supprime une constante déjà définie

### Description

function runkit7_constant_remove(string `$constant_name`): bool

### Liste de paramètres

`constant_name`
  Le nom de la constante à enlever. Soit le nom d'une constante globale, soit `classname::constname` indiquant une constante de classe.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- define() - Définit une constante
- runkit7_constant_add() - Similaire à define(), mais permet de définir dans les définitions de classe également
- runkit7_constant_redefine() - Redéfinit une constante déjà définie

# runkit7_function_add

(PECL runkit7 >= Unknown)

runkit7_function_add — Ajoute une nouvelle fonction, similaire à create_function()

### Description

function runkit7_function_add(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_add(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Liste de paramètres

`function_name`
  Le nom de la fonction à créer
`argument_list`
  La liste des arguments séparés par des virgules
`code`
  Le code composant la fonction
`closure`
  Une closure qui définit la fonction
`return_by_reference`
  Si la fonction doit retourner par référence
`doc_comment`
  Le commentaire de documentation de la fonction
`return_type`
  Le type de retour de la fonction
`is_strict`
  Si la fonction doit se comporter comme si elle était déclarée dans un fichier avec `strict_types=1`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Un exemple de runkit7_function_add()

    <?php
    runkit7_function_add('testme','$a,$b','echo "The value of a is $a\n"; echo "The value of b is $b\n";');
    testme(1,2);
    ?>

L'exemple ci-dessus va afficher :

    The value of a is 1
    The value of b is 2

### Voir aussi

- create_function() - Crée une fonction dynamiquement en évaluant une chaîne de code
- runkit7_function_redefine() - Remplace une définition de fonction par une nouvelle implémentation
- runkit7_function_copy() - Copie une fonction vers un nouveau nom de fonction
- runkit7_function_rename() - Change un nom de fonction
- runkit7_function_remove() - Supprime une définition de fonction
- runkit7_method_add() - Ajoute dynamiquement une nouvelle méthode à une classe donnée

# runkit7_function_copy

(PECL runkit7 >= Unknown)

runkit7_function_copy — Copie une fonction vers un nouveau nom de fonction

### Description

function runkit7_function_copy(string `$source_name`, string `$target_name`): bool

### Liste de paramètres

`source_name`
  Le nom de la fonction existante
`target_name`
  Le nom de la nouvelle fonction vers laquelle copier la définition

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Un exemple de runkit7_function_copy()

    <?php
    function original() {
      echo "In a function\n";
    }
    runkit7_function_copy('original','duplicate');
    original();
    duplicate();
    ?>

L'exemple ci-dessus va afficher :

    In a function
    In a function

### Voir aussi

- runkit7_function_add() - Ajoute une nouvelle fonction, similaire à create_function
- runkit7_function_redefine() - Remplace une définition de fonction par une nouvelle implémentation
- runkit7_function_rename() - Change un nom de fonction
- runkit7_function_remove() - Supprime une définition de fonction

# runkit7_function_redefine

(PECL runkit7 >= Unknown)

runkit7_function_redefine — Remplace une définition de fonction par une nouvelle implémentation

### Description

function runkit7_function_redefine(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_redefine(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

> Note: Par défaut, seulement les fonctions définies par l'utilisateur peuvent être supprimées, renommées ou modifiées. Afin de surcharger des fonctions internes, vous devez activer la configuration `runkit.internal_override` dans le fichier php.ini du système entier.

### Liste de paramètres

`function_name`
  Le nom de la fonction à redéfinir
`argument_list`
  La nouvelle liste d'arguments à accepter par la fonction
`code`
  Le code de la nouvelle implémentation
`closure`
  Une closure qui définit la fonction
`return_by_reference`
  Si la fonction doit retourner par référence
`doc_comment`
  Le commentaire de documentation de la fonction
`return_type`
  Le type de retour de la fonction
`is_strict`
  Si la fonction se comporte comme si elle était déclarée dans un fichier avec `strict_types=1`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Un exemple de runkit7_function_redefine()

    <?php
    function testme() {
      echo "Original Testme Implementation\n";
    }
    testme();
    runkit7_function_redefine('testme','','echo "New Testme Implementation\n";');
    testme();
    ?>

L'exemple ci-dessus va afficher :

    Original Testme Implementation
    New Testme Implementation

### Voir aussi

- runkit7_function_add() - Ajoute une nouvelle fonction, similaire à create_function
- runkit7_function_copy() - Copie une fonction vers un nouveau nom de fonction
- runkit7_function_rename() - Change un nom de fonction
- runkit7_function_remove() - Supprime une définition de fonction
- runkit7_method_redefine() - Change dynamiquement le code de la méthode donnée

# runkit7_function_remove

(PECL runkit7 >= Unknown)

runkit7_function_remove — Supprime une définition de fonction

### Description

function runkit7_function_remove(string `$function_name`): bool

> Note: Par défaut, seulement les fonctions définies par l'utilisateur peuvent être supprimées, renommées ou modifiées. Afin de surcharger des fonctions internes, vous devez activer la configuration `runkit.internal_override` dans le fichier php.ini du système entier.

### Liste de paramètres

`function_name`
  Le nom de la fonction à supprimer

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- runkit7_function_add() - Ajoute une nouvelle fonction, similaire à create_function
- runkit7_function_copy() - Copie une fonction vers un nouveau nom de fonction
- runkit7_function_redefine() - Remplace une définition de fonction par une nouvelle implémentation
- runkit7_function_rename() - Change un nom de fonction

# runkit7_function_rename

(PECL runkit7 >= Unknown)

runkit7_function_rename — Change un nom de fonction

### Description

function runkit7_function_rename(string `$source_name`, string `$target_name`): bool

> Note: Par défaut, seulement les fonctions définies par l'utilisateur peuvent être supprimées, renommées ou modifiées. Afin de surcharger des fonctions internes, vous devez activer la configuration `runkit.internal_override` dans le fichier php.ini du système entier.

### Liste de paramètres

`source_name`
  Le nom de la fonction existante
`target_name`
  Le nouveau nom de la fonction

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- runkit7_function_add() - Ajoute une nouvelle fonction, similaire à create_function
- runkit7_function_copy() - Copie une fonction vers un nouveau nom de fonction
- runkit7_function_redefine() - Remplace une définition de fonction par une nouvelle implémentation
- runkit7_function_remove() - Supprime une définition de fonction

# runkit7_import

(PECL runkit7 >= Unknown)

runkit7_import — Procède à l'importation d'un fichier PHP en important les définitions de fonctions et de classes, en les écrasant si nécessaire

Avertissement

Cette fonctionnalité a été supprimée dans PECL runkit7 4.0.0.

### Description

function runkit7_import(string `$filename`, int `$flags` = ?): bool

Similaire à include. Cependant, tout code se trouvant en dehors d'une fonction ou d'une classe est simplement ignoré. De plus, en fonction de la valeur de `flags`, toute fonction ou classe déjà existante dans l'environnement d'exécution actuel peut être automatiquement écrasée par ses nouvelles définitions.

### Liste de paramètres

`filename`
  Le nom du fichier à partir duquel importer les définitions de fonctions et de classes
`flags`
  Une opération bit à bit OU de la famille de constantes `RUNKIT7_IMPORT_*`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# runkit7_method_add

(PECL runkit7 >= Unknown)

runkit7_method_add — Ajoute dynamiquement une nouvelle méthode à une classe donnée

### Description

function runkit7_method_add(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_add(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Liste de paramètres

`class_name`
  La classe à laquelle cette méthode sera ajoutée
`method_name`
  Le nom de la méthode à ajouter
`argument_list`
  La liste des arguments séparés par des virgules pour la nouvelle méthode
`code`
  Le code à évaluer lorsque `method_name` est appelé
`closure`
  Une closure qui définit la méthode.
`flags`
  Le type de méthode à créer, peut être `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` ou `RUNKIT7_ACC_PRIVATE` optionnellement combiné via une opération bit à bit OU avec `RUNKIT7_ACC_STATIC`
`doc_comment`
  Le commentaire de documentation de la méthode.
`return_type`
  Le type de retour de la méthode.
`is_strict`
  Si la méthode se comporte comme si elle était déclarée dans un fichier avec `strict_types=1`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de runkit7_method_add()

    <?php
    class Example {
        function foo() {
            echo "foo!\n";
        }
    }

    // Créer un objet Example
    $e = new Example();

    // Ajoute une nouvelle méthode publique
    runkit7_method_add(
        'Example',
        'add',
        '$num1, $num2',
        'return $num1 + $num2;',
        RUNKIT7_ACC_PUBLIC
    );

    // ajoute 12 + 4
    echo $e->add(12, 4);
    ?>

L'exemple ci-dessus va afficher :

    16

### Voir aussi

- runkit7_method_copy() - Copie une méthode d'une classe vers une autre
- runkit7_method_redefine() - Change dynamiquement le code de la méthode donnée
- runkit7_method_remove() - Supprime dynamiquement la méthode donnée
- runkit7_method_rename() - Change dynamiquement le nom de la méthode donnée
- runkit7_function_add() - Ajoute une nouvelle fonction, similaire à create_function

# runkit7_method_copy

(PECL runkit7 >= Unknown)

runkit7_method_copy — Copie une méthode d'une classe vers une autre

### Description

function runkit7_method_copy(
string `$destination_class`,
string `$destination_method_name`,
string `$source_class`,
string `$source_method_name` = ?
): bool

### Liste de paramètres

`destination_class`
  La classe de destination pour la méthode copiée
`destination_method_name`
  Le nom de la méthode de destination
`source_class`
  La classe source de la méthode à copier
`source_method_name`
  Le nom de la méthode à copier de la classe source. Si ce paramètre est omis la valeur de `destination_method_name` est supposée.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de runkit7_method_copy()

    <?php
    class Foo {
        function example() {
            return "foo!\n";
        }
    }

    class Bar {
        // aucune méthode initialement
    }

    // copie l'example() de la classe Foo vers la classe Bar, en tant que baz()
    runkit7_method_copy('Bar', 'baz', 'Foo', 'example');

    // afficher la fonction copiée
    echo Bar::baz();
    ?>

L'exemple ci-dessus va afficher :

    foo!

### Voir aussi

- runkit7_method_add() - Ajoute dynamiquement une nouvelle méthode à une classe donnée
- runkit7_method_redefine() - Change dynamiquement le code de la méthode donnée
- runkit7_method_remove() - Supprime dynamiquement la méthode donnée
- runkit7_method_rename() - Change dynamiquement le nom de la méthode donnée
- runkit7_function_copy() - Copie une fonction vers un nouveau nom de fonction

# runkit7_method_redefine

(PECL runkit7 >= Unknown)

runkit7_method_redefine — Change dynamiquement le code de la méthode donnée

### Description

function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Liste de paramètres

`class_name`
  La classe dans laquelle redéfinir la méthode
`method_name`
  Le nom de la méthode à redéfinir
`argument_list`
  La liste des arguments séparés par des virgules pour la méthode redéfinie
`code`
  Le nouveau code à évaluer lorsque `method_name` est appelé
`closure`
  Une closure qui définit la méthode.
`flags`
  La méthode redéfinie peut être `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` ou `RUNKIT7_ACC_PRIVATE` optionnellement combiné via une opération bit à bit OU avec `RUNKIT7_ACC_STATIC`
`doc_comment`
  Le commentaire de documentation de la méthode.
`return_type`
  Le type de retour de la méthode.
`is_strict`
  Si la méthode se comporte comme si elle était déclarée dans un fichier avec `strict_types=1`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de runkit7_method_redefine()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // créer un objet Example
    $e = new Example();

    // affiche Example::foo() (avant la redéfinition)
    echo "Before: " . $e->foo();

    // Redéfinit la méthode 'foo'
    runkit7_method_redefine(
        'Example',
        'foo',
        '',
        'return "bar!\n";',
        RUNKIT7_ACC_PUBLIC
    );

    // affiche Example::foo() (après la redéfinition)
    echo "After: " . $e->foo();
    ?>

L'exemple ci-dessus va afficher :

    Before: foo!
    After: bar!

### Voir aussi

- runkit7_method_add() - Ajoute dynamiquement une nouvelle méthode à une classe donnée
- runkit7_method_copy() - Copie une méthode d'une classe vers une autre
- runkit7_method_remove() - Supprime dynamiquement la méthode donnée
- runkit7_method_rename() - Change dynamiquement le nom de la méthode donnée
- runkit7_function_redefine() - Remplace une définition de fonction par une nouvelle implémentation

# runkit7_method_remove

(PECL runkit7 >= Unknown)

runkit7_method_remove — Supprime dynamiquement la méthode donnée

### Description

function runkit7_method_remove(string `$class_name`, string `$method_name`): bool

> Note: Cette fonction ne peut être utilisée pour manipuler la méthode en cours d'utilisation (ou chaînée).

### Liste de paramètres

`class_name`
  La classe dans laquelle supprimer la méthode
`method_name`
  Le nom de la méthode à supprimer

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de runkit7_method_remove()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }

        function bar() {
            return "bar!\n";
        }
    }

    // Supprime la méthode 'foo'
    runkit7_method_remove(
        'Example',
        'foo'
    );

    echo implode(' ', get_class_methods('Example'));

    ?>

L'exemple ci-dessus va afficher :

    bar

### Voir aussi

- runkit7_method_add() - Ajoute dynamiquement une nouvelle méthode à une classe donnée
- runkit7_method_copy() - Copie une méthode d'une classe vers une autre
- runkit7_method_redefine() - Change dynamiquement le code de la méthode donnée
- runkit7_method_rename() - Change dynamiquement le nom de la méthode donnée
- runkit7_function_remove() - Supprime une définition de fonction

# runkit7_method_rename

(PECL runkit7 >= Unknown)

runkit7_method_rename — Change dynamiquement le nom de la méthode donnée

### Description

function runkit7_method_rename(string `$class_name`, string `$source_method_name`, string `$target_method_name`): bool

> Note: Cette fonction ne peut être utilisée pour manipuler la méthode en cours d'utilisation (ou chaînée).

### Liste de paramètres

`class_name`
  La classe dans laquelle renommer la méthode
`source_method_name`
  Le nom de la méthode à renommer
`target_method_name`
  Le nouveau nom à donner à la méthode renommée

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de runkit7_method_rename()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // Renomme la méthode 'foo' en 'bar'
    runkit7_method_rename(
        'Example',
        'foo',
        'bar'
    );

    // affiche la fonction renommée
    echo (new Example)->bar();
    ?>

L'exemple ci-dessus va afficher :

    foo!

### Voir aussi

- runkit7_method_add() - Ajoute dynamiquement une nouvelle méthode à une classe donnée
- runkit7_method_copy() - Copie une méthode d'une classe vers une autre
- runkit7_method_redefine() - Change dynamiquement le code de la méthode donnée
- runkit7_method_remove() - Supprime dynamiquement la méthode donnée
- runkit7_function_rename() - Change un nom de fonction

# runkit7_object_id

(PECL runkit7 >= Unknown)

runkit7_object_id — Renvoie l'identifiant d'objet pour un objet donné

### Description

function runkit7_object_id(object `$obj`): int

Cette fonction est équivalente à spl_object_id().

Cette fonction renvoie un identifiant unique pour l'objet. L'identifiant d'objet est unique pour la durée de vie de l'objet. Une fois l'objet détruit, son identifiant peut être réutilisé pour d'autres objets. Ce comportement est similaire à spl_object_hash().

### Liste de paramètres

`obj`
  Un objet quelconque.

### Valeurs de retour

Un identifiant entier qui est unique pour chaque objet actuellement existant et est toujours le même pour chaque objet.

### Notes

> Note: Lorsqu'un objet est détruit, son identifiant peut être réutilisé pour d'autres objets.

### Voir aussi

- spl_object_id() - Retourne le gestionnaire d'objet entier pour un objet donné

# runkit7_superglobals

(PECL runkit7 >= Unknown)

runkit7_superglobals — Renvoie un tableau indexé numériquement des superglobales enregistrées

### Description

function runkit7_superglobals(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un tableau indexé numériquement des superglobales enregistrées. c'est-à-dire _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES

### Voir aussi

- Variable Scope

# runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspect — Renvoie des informations sur la valeur passée avec les types de données, les comptes de référence, etc

### Description

function runkit7_zval_inspect(string `$value`): array

### Liste de paramètres

`value`
  La valeur pour laquelle renvoyer la représentation

### Valeurs de retour

Le tableau retourné par cette fonction contient les éléments suivants :

- `address`
- `refcount` (optionnel)
- `is_ref` (optionnel)
- `type`

### Exemples

Exemple #1 Exemple de runkit7_zval_inspect()

    <?php

    $var = new DateTime();
    var_dump(runkit7_zval_inspect($var));

    $var = 1;
    var_dump(runkit7_zval_inspect($var));
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["refcount"]=>
      int(2)
      ["is_ref"]=>
      bool(false)
      ["type"]=>
      int(8)
    }

    array(2) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["type"]=>
      int(4)
    }

### Voir aussi

- References Explained
- » References Explained (by Derick Rethans)

## Sommaire

- runkit7_constant_add — Similaire à define(), mais permet de définir dans les définitions de classe également
- runkit7_constant_redefine — Redéfinit une constante déjà définie
- runkit7_constant_remove — Enlève/Supprime une constante déjà définie
- runkit7_function_add — Ajoute une nouvelle fonction, similaire à create_function
- runkit7_function_copy — Copie une fonction vers un nouveau nom de fonction
- runkit7_function_redefine — Remplace une définition de fonction par une nouvelle implémentation
- runkit7_function_remove — Supprime une définition de fonction
- runkit7_function_rename — Change un nom de fonction
- runkit7_import — Procède à l'importation d'un fichier PHP en important les définitions de fonctions et de classes, en les écrasant si nécessaire
- runkit7_method_add — Ajoute dynamiquement une nouvelle méthode à une classe donnée
- runkit7_method_copy — Copie une méthode d'une classe vers une autre
- runkit7_method_redefine — Change dynamiquement le code de la méthode donnée
- runkit7_method_remove — Supprime dynamiquement la méthode donnée
- runkit7_method_rename — Change dynamiquement le nom de la méthode donnée
- runkit7_object_id — Renvoie l'identifiant d'objet pour un objet donné
- runkit7_superglobals — Renvoie un tableau indexé numériquement des superglobales enregistrées
- runkit7_zval_inspect — Renvoie des informations sur la valeur passée avec les types de données, les comptes de référence, etc

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Fonctions de runkit7
  - runkit7_constant_add — Similaire à define(), mais permet de définir dans les définitions de classe également
  - runkit7_constant_redefine — Redéfinit une constante déjà définie
  - runkit7_constant_remove — Enlève/Supprime une constante déjà définie
  - runkit7_function_add — Ajoute une nouvelle fonction, similaire à create_function
  - runkit7_function_copy — Copie une fonction vers un nouveau nom de fonction
  - runkit7_function_redefine — Remplace une définition de fonction par une nouvelle implémentation
  - runkit7_function_remove — Supprime une définition de fonction
  - runkit7_function_rename — Change un nom de fonction
  - runkit7_import — Procède à l'importation d'un fichier PHP en important les définitions de fonctions et de classes, en les écrasant si nécessaire
  - runkit7_method_add — Ajoute dynamiquement une nouvelle méthode à une classe donnée
  - runkit7_method_copy — Copie une méthode d'une classe vers une autre
  - runkit7_method_redefine — Change dynamiquement le code de la méthode donnée
  - runkit7_method_remove — Supprime dynamiquement la méthode donnée
  - runkit7_method_rename — Change dynamiquement le nom de la méthode donnée
  - runkit7_object_id — Renvoie l'identifiant d'objet pour un objet donné
  - runkit7_superglobals — Renvoie un tableau indexé numériquement des superglobales enregistrées
  - runkit7_zval_inspect — Renvoie des informations sur la valeur passée avec les types de données, les comptes de référence, etc

# Opérations utilisateurs pour Zend

# Introduction

L'extension uopz - User Operations for Zend (NdT : les opérations utilisateurs pour Zend) - expose les fonctionnalités du moteur Zend, normalement utilisées au moment de la compilation et de l'exécution, afin de permettre la modification des structures internes que représentent le code PHP, et pour le code utilisateur d'interagir avec la VM.

uopz supporte les activités suivantes :

- Surcharge d'opcodes incluant ZEND_EXIT et ZEND_NEW
- Sauvegarde et restauration des fonctions et méthodes
- Renommage des fonctions et des méthodes
- Copie des fonctions et des méthodes
- Suppression des fonctions et des méthodes
- Re-définition des constantes globales et de classe
- Suppression des constantes globales et de classe
- Composition et modification de classes à l'exécution

> Note:

> Toutes les activités supportées sont compatibles avec opcache.

Attention

PECL uopz 6.1.1 n'est pas compatible avec Xdebug >= 2.9.4. Les versions ultérieures de uopz ne sont pas compatibles avec Xdebug < 2.9.4.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

À partir de uopz 5.0 PHP 7.0 est nécessaire. À partir de uopz 5.1, PHP 7.1+ est nécessaire.

## Installation

Les versions d'uopz sont hébergées par PECL et le code source par » github ; la façon la plus simple de l'installer est de passer par l'installation via PECL : » https://pecl.php.net/package/uopz.

Les utilisateurs de Windows peuvent télécharger les binaires depuis le site web de » PECL.

À partir de uopz 5.0.0, l'extension doit être chargée en tant qu' extension. Antérieur à cette version, elle doit être chargée comme une zend_extension.

## Configuration à l'exécution

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

uopz Options de configuration
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
uopz.disable | "0" | `INI_SYSTEM` | Disponible à partir de uopz 5.0.2
uopz.exit | "0" | `INI_SYSTEM` | Disponible à partir de uopz 6.0.1
uopz.overloads | "1" | `INI_SYSTEM` | Disponible à partir de uopz 2.0.2. Supprimé à partir de uopz 5.0.0.

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`uopz.disable` bool

  Si activé, uopz devrait ne plus avoir d'effet sur le moteur.

`uopz.exit` bool

  Autoriser ou non l'exécution des codes d'opération (opcodes) de sortie. Ce paramètre peut être dérogé lors de l'exécution en appelant uopz_allow_exit().

`uopz.overloads` bool

  Active la possibilité d'utiliser uopz_overload().

> Note: Lors de l'exécution avec OPcache activé, il peut être nécessaire de désactiver toutes les optimisations OPcache (`opcache.optimization_level=0`).

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Les opcodes suivants sont définis comme des constantes par uopz avant 5.0.0 :

`ZEND_EXIT` (int)
  Invoque exit() et die() ; réceptionne aucun argument. Retourne `true` pour sortir, `false` pour continuer
`ZEND_NEW` (int)
  Invoqué par la construction d'un objet, reçoit l'objet de la classe créée comme seul argument
`ZEND_THROW` (int)
  Invoqué par la structure throw, reçoit l'exception de la classe émise comme seul argument
`ZEND_FETCH_CLASS` (int)
  Invoqué lors d'une composition, reçoit la classe, le nom de la classe récupérée comme seul argument
`ZEND_ADD_TRAIT` (int)
  Invoqué lors d'une composition, reçoit la classe dans laquelle le trait sera ajouté, comme premier argument, et le nom du trait comme second argument
`ZEND_ADD_INTERFACE` (int)
  Invoqué lors d'une composition, reçoit la classe dans laquelle l'interface sera ajoutée comme premier argument, et le nom de l'interface comme second argument
`ZEND_INSTANCEOF` (int)
  Invoqué par l'opérateur instanceof, reçoit l'objet a vérifier comme premier argument, et le nom de la classe dont l'objet appartient comme second argument

Les constantes suivantes contrôlent le comportement de la VM après qu'un gestionnaire utilisateur ne soit appelé ; soyez extrêmement prudent ! Ces constantes sont supprimées à partir de uopz 5.0.0.

`ZEND_USER_OPCODE_CONTINUE` (int)
  Avance d'un opcode, et continue
`ZEND_USER_OPCODE_ENTER` (int)
  Entre dans un nouvel op_array sans récursion
`ZEND_USER_OPCODE_LEAVE` (int)
  Retourne l'op_array appelé dans le même exécuteur
`ZEND_USER_OPCODE_DISPATCH` (int)
  Dispatche le gestionnaire opcode original
`ZEND_USER_OPCODE_DISPATCH_TO` (int)
  Distribue à un gestionnaire spécifique
`ZEND_USER_OPCODE_RETURN` (int)
  Sort de l'exécuteur (retourne à la fonction)

Les modificateurs suivants sont enregistrés comme constantes par uopz

`ZEND_ACC_PUBLIC` (int)
  Marque une fonction comme publique, le comportement par défaut
`ZEND_ACC_PROTECTED` (int)
  Marque une fonction comme protégée
`ZEND_ACC_PRIVATE` (int)
  Marque une fonction comme privée
`ZEND_ACC_STATIC` (int)
  Marque une fonction comme statique
`ZEND_ACC_FINAL` (int)
  Marque une fonction comme finale
`ZEND_ACC_ABSTRACT` (int)
  Marque une fonction comme abstraite
`ZEND_ACC_CLASS` (int)
  Enregistrement pour la consistence, l'entrée par défaut d'une classe. Supprimée à partir de uopz 5.0.0.
`ZEND_ACC_INTERFACE` (int)
  Marque la classe comme étant une interface. Supprimée à partir de uopz 5.0.0.
`ZEND_ACC_TRAIT` (int)
  Marque la classe comme étant trait. Supprimée à partir de uopz 5.0.0.
`ZEND_ACC_FETCH` (int)
  Utilisé pour récupérer seulement les drapeaux. Supprimée à partir de uopz 5.0.0.

# Fonctions Uopz

# uopz_add_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_add_function — Ajoute une fonction ou une méthode inexistante

### Description

function uopz_add_function(string `$function`, Closure `$handler`, int `&$flags` = ZEND_ACC_PUBLIC): bool
function uopz_add_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `&$flags` = ZEND_ACC_PUBLIC,
int `&$all` = `true`
): bool

Ajoute une fonction ou une méthode inexistante.

### Liste de paramètres

`class`

  Le nom de la classe.

`function`

  Le nom de la fonction ou de la méthode.

`handler`

  La Closure qui définit la nouvelle fonction ou méthode.

`flags`

  Les drapeaux à définir pour la nouvelle fonction ou méthode.

`all`

  Si toutes les classes qui descendent de `class` seront également affectées.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

uopz_add_function() lance une RuntimeException si la fonction ou la méthode à ajouter existe déjà.

### Exemples

Exemple #1 Utilisation basique de uopz_add_function()

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    foo();
    ?>

L'exemple ci-dessus va afficher :

    bar

### Voir aussi

- uopz_del_function() - Supprime une fonction ou une méthode précédemment ajoutée
- uopz_set_return() - Apporte une valeur de retour pour une fonction existante

# uopz_allow_exit

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_allow_exit — Permet de contrôler l'opcode exit désactivé

### Description

function uopz_allow_exit(bool `$allow`): void

Par défaut, uopz désactive l'opcode exit, donc les appels à exit() sont pratiquement ignorés. uopz_allow_exit() permet de contrôler ce comportement.

### Liste de paramètres

`allow`

  Autoriser ou non l'exécution des opcodes exit.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple de uopz_allow_exit()

    <?php
    exit(1);
    echo 1;
    uopz_allow_exit(true);
    exit(2);
    echo 2;
    ?>

L'exemple ci-dessus va afficher :

    1

### Notes

Attention

OPcache optimise le code mort après une sortie inconditionnelle.

### Voir aussi

- uopz_get_exit_status() - Renvoie le dernier statut de sortie défini

# uopz_backup

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_backup — Sauvegarde une fonction

Avertissement

Cette fonction a été SUPPRIMEE dand PECL uopz 5.0.0.

### Description

function uopz_backup(string `$function`): void
function uopz_backup(string `$class`, string `$function`): void

Sauvegarde une fonction à l'exécution.

### Liste de paramètres

`class`

  Le nom de la classe contenant la fonction à sauvegarder

`function`

  Le nom de la fonction

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec uopz_backup()

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

# uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_compose — Compose une classe

Avertissement

Cette fonction a été SUPPRIMEE dand PECL uopz 5.0.0.

### Description

function uopz_compose(
string `$name`,
array `$classes`,
array `$methods` = ?,
array `$properties` = ?,
int `$flags` = ?
): void

Crée une nouvelle classe de nom spécifié, qui implémente, étend ou utilise toutes les classes fournies.

### Liste de paramètres

`name`

  Un nom de classe valide

`classes`

  Un tableau de classes, d'interfaces ou de noms trait

`methods`

  Un tableau associatif de méthodes ; les valeurs sont soit des closures, soit des [modifiers => closure]

`properties`

  Un tableau associatif de propriétés, ayant comme clés les noms, et comme valeurs, les modificateurs

`flags`

  Type d'entrée ; par défaut, ZEND_ACC_CLASS

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec uopz_compose()

    <?php
    class myClass {}
    trait myTrait {}
    interface myInterface {}

    uopz_compose(
        Composed::class, [
            myClass::class,
            myTrait::class,
            myInterface::class
        ], [
        "__construct" => function() {
            /* ... */
        }
    ]);

    var_dump(
     class_uses(Composed::class),
     class_parents(Composed::class),
     class_implements(Composed::class));
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["myTrait"]=>
      string(7) "myTrait"
    }
    array(1) {
      ["myClass"]=>
      string(7) "myClass"
    }
    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_copy

(PECL uopz 1 >= 1.0.4, PECL uopz 2)

uopz_copy — Copie une fonction

Avertissement

Cette fonction a été SUPPRIMEE dand PECL uopz 5.0.0.

### Description

function uopz_copy(string `$function`): Closure
function uopz_copy(string `$class`, string `$function`): Closure

Copie une fonction à partir de son nom.

### Liste de paramètres

`class`

  Le nom de la classe contenant la fonction à copier

`function`

  Le nom de la fonction

### Valeurs de retour

Une closure pour la fonction spécifiée.

### Exemples

Exemple #1 Exemple avec uopz_copy()

    <?php
    $strtotime = uopz_copy('strtotime');

    uopz_function("strtotime", function($arg1, $arg2) use($strtotime) {
        /* on peut appeler la fonction strtotime original depuis ici */
        var_dump($arg1);
    });

    var_dump(strtotime('dummy'));
    ?>

L'exemple ci-dessus va afficher :

    string(5) "dummy"

# uopz_del_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_del_function — Supprime une fonction ou une méthode précédemment ajoutée

### Description

function uopz_del_function(string `$function`): bool
function uopz_del_function(string `$class`, string `$function`, int `&$all` = `true`): bool

Supprime une fonction ou une méthode précédemment ajoutée.

### Liste de paramètres

`class`

  Le nom de la classe.

`function`

  Le nom de la fonction ou de la méthode.

`all`

  Si toutes les classes qui descendent de `class` seront également affectées.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

uopz_del_function() lance une RuntimeException si la fonction ou la méthode à supprimer n'a pas été ajoutée par uopz_add_function().

### Exemples

Exemple #1 Utilisation basique de uopz_del_function()

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    var_dump(function_exists('foo'));
    uopz_del_function('foo');
    var_dump(function_exists('foo'));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)

### Voir aussi

- uopz_add_function() - Ajoute une fonction ou une méthode inexistante
- uopz_unset_return() - Supprime une valeur de retour précédemment définie pour une fonction

# uopz_delete

(PECL uopz 1, PECL uopz 2)

uopz_delete — Supprime une fonction

Avertissement

Cette fonction a été SUPPRIMEE dand PECL uopz 5.0.0.

### Description

function uopz_delete(string `$function`): void
function uopz_delete(string `$class`, string `$function`): void

Supprime une fonction ou une méthode.

### Liste de paramètres

`class`

`function`

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec uopz_delete()

    <?php
    uopz_delete("strlen");

    echo strlen("Hello World");
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4

Exemple #2 Exemple avec uopz_delete() et une classe

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_delete(My::class, "strlen");

    echo My::strlen("Hello World");
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    PHP Fatal error: Call to undefined method My::strlen() in /path/to/script.php on line 10

# uopz_extend

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_extend — Etend une classe à l'exécution

### Description

function uopz_extend(string `$class`, string `$parent`): bool

Etend la classe `class` en utilisant la classe `parent`.

### Liste de paramètres

`class`

  Le nom de la classe à étendre

`parent`

  Le nom de la classe parent

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

À partir de PHP 7.4.0, uopz_extend() émet une RuntimeException, si OPcache est activé, et l'entrée de classe de `class` ou `parent` (si dans un trait) est immutable.

### Exemples

Exemple #1 Exemple avec uopz_extend()

    <?php
    class A {}
    class B {}

    uopz_extend(A::class, B::class);

    var_dump(class_parents(A::class));
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["B"]=>
      string(1) "B"
    }

# uopz_flags

(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_flags — Récupère ou défini les drapeaux d'une fonction ou d'une classe

### Description

function uopz_flags(string `$function`, int `$flags` = PHP_INT_MAX): int
function uopz_flags(string `$class`, string `$function`, int `$flags` = PHP_INT_MAX): int

Récupère ou défini les drapeaux d'une classe ou de l'entrée d'une fonction à l'exécution.

### Liste de paramètres

`class`

  Le nom de la classe

`function`

  Le nom de la fonction. Si `class` est fournie et qu'une chaîne de caractères vide est passée comme `function`, uopz_flags() récupère ou définit les drapeaux de l'entrée de classe.

`flags`

  Un jeu valide de drapeaux ZEND_ACC_ flags. Si omis, uopz_flags() agit comme un récupérateur.

### Valeurs de retour

Si des drapeaux ont été définis, retourne les anciens drapeaux, sinon, retourne les drapeaux courants

### Erreurs / Exceptions

À partir de PHP 7.4.0, si le paramètre `flags` est fourni uopz_flags() émet une RuntimeException, si OPcache est activé, et l'entrée de classe de `class` ou l'entrée de fonction `function` est immutable.

### Historique

Version | Description
--- | ---
PECL uopz 5.0.0 | Le paramètre `flags` est désormais optionnel. Auparavant, `ZEND_ACC_FETCH` devait être passé pour utiliser uopz_flags() en tant que récupérateur.

### Exemples

Exemple #1 Exemple avec uopz_flags()

    <?php
    class Test {
        public function method() {
            return __CLASS__;
        }
    }

    $flags = uopz_flags("Test", "method");

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));

    var_dump(uopz_flags("Test", "method", $flags|ZEND_ACC_STATIC|ZEND_ACC_PRIVATE));

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(false)
    int(1234567890)
    bool(true)
    bool(true)

Exemple #2 Transformer une Classe finale en non-finale

    <?php
    final class MyClass
    {
    }

    $flags = uopz_flags(MyClass::class, '');
    uopz_flags(MyClass::class, '', $flags & ~ZEND_ACC_FINAL);
    var_dump((new ReflectionClass(MyClass::class))->isFinal());
    ?>

L'exemple ci-dessus va afficher :

    bool(false)

# uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_function — Crée une fonction à l'exécution

Avertissement

Cette fonction a été SUPPRIMEE dand PECL uopz 5.0.0.

### Description

function uopz_function(string `$function`, Closure `$handler`, int `$modifiers` = ?): void
function uopz_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `$modifiers` = ?
): void

Crée une fonction à l'exécution.

### Liste de paramètres

`class`

  Le nom de la classe qui doit recevoir la nouvelle fonction

`function`

  Le nom de la fonction

`handler`

  La closure de la fonction

`modifiers`

  Les modificateurs de la fonction ; par défaut, copié ou ZEND_ACC_PUBLIC

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec uopz_function()

    <?php
    uopz_function("my_strlen", function($arg) {
        return strlen($arg);
    });
    echo my_strlen("Hello World");
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    11

Exemple #2 Exemple avec uopz_function() et une classe

    <?php
    class My {}

    uopz_function(My::class, "strlen", function($arg) {
        return strlen($arg);
    }, ZEND_ACC_STATIC);

    echo My::strlen("Hello World");
    ?>

L'exemple ci-dessus va afficher :

    11

# uopz_get_exit_status

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_get_exit_status — Renvoie le dernier statut de sortie défini

### Description

function uopz_get_exit_status(): mixed

Renvoie le dernier statut de sortie défini, c'est-à-dire la valeur passée à exit().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction renvoie le dernier statut de sortie, ou `null` si exit() n'a pas été appelée.

### Exemples

Exemple #1 Exemple de uopz_get_exit_status()

    <?php
    exit(123);
    echo uopz_get_exit_status();?>

L'exemple ci-dessus va afficher :

    123

### Notes

Attention

OPcache optimise le code mort après une sortie inconditionnelle.

### Voir aussi

- uopz_allow_exit() - Permet de contrôler l'opcode exit désactivé

# uopz_get_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_hook — Renvoie le hook précédemment défini sur une fonction ou une méthode

### Description

function uopz_get_hook(string `$function`): Closure
function uopz_get_hook(string `$class`, string `$function`): Closure

Renvoie le hook précédemment défini sur une fonction ou une méthode.

### Liste de paramètres

`class`

  Le nom de la classe.

`function`

  Le nom de la fonction ou de la méthode.

### Valeurs de retour

Renvoie le hook précédemment défini sur une fonction ou une méthode, ou `null` si aucun hook n'a été défini.

### Exemples

Exemple #1 Utilisation basique de uopz_get_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    var_dump(uopz_get_hook('foo'));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(Closure)#2 (0) {
    }

### Voir aussi

- uopz_set_hook() - Définit le hook à exécuter lors de l'entrée dans une fonction ou une méthode
- uopz_unset_hook() - Supprime le hook précédemment défini sur une fonction ou une méthode

# uopz_get_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_mock — Renvoie la simulation actuelle d'une classe

### Description

function uopz_get_mock(string `$class`): mixed

Renvoie la simulation actuelle de `class`.

### Liste de paramètres

`class`

  Le nom de la classe simulée.

### Valeurs de retour

Soit une chaîne contenant le nom de la simulation, soit un objet, soit `null` si aucune simulation n'a été définie.

### Exemples

Exemple #1 Exemple de uopz_get_mock()

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    echo uopz_get_mock(A::class);
    ?>

L'exemple ci-dessus va afficher :

    mockA

### Voir aussi

- uopz_set_mock() - Utilise une simulation au lieu d'une classe pour de nouveaux objets
- uopz_unset_mock() - Supprime la simulation précédemment définie

# uopz_get_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_property — Renvoie la valeur d'une propriété de classe ou d'instance

### Description

function uopz_get_property(string `$class`, string `$property`): mixed
function uopz_get_property(object `$instance`, string `$property`): mixed

Renvoie la valeur d'une propriété de classe statique, si `class` est donné, ou la valeur d'une propriété d'instance, si `instance` est donné.

### Liste de paramètres

`class`

  Le nom de la classe.

`instance`

  L'instance de l'objet.

`property`

  Le nom de la propriété.

### Valeurs de retour

Renvoie la valeur de la propriété de classe ou d'instance, ou `null` si la propriété n'est pas définie.

### Exemples

Exemple #1 Utilisation basique de uopz_get_property()

    <?php
    class Foo {
        private static $staticBar = 10;
        private $bar = 100;
    }
    $foo = new Foo;
    var_dump(uopz_get_property('Foo', 'staticBar'));
    var_dump(uopz_get_property($foo, 'bar'));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(10)
    int(100)

### Voir aussi

- uopz_set_property() - Définit la valeur d'une propriété de classe existante ou d'instance

# uopz_get_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_return — Renvoie une valeur de retour précédemment définie pour une fonction

### Description

function uopz_get_return(string `$function`): mixed
function uopz_get_return(string `$class`, string `$function`): mixed

Renvoie la valeur de retour de la `function` précédemment définie par uopz_set_return().

### Liste de paramètres

`class`

  Le nom de la classe contenant la fonction

`function`

  Le nom de la fonction

### Valeurs de retour

La valeur de retour ou la Closure précédemment définie.

### Exemples

Exemple #1 Exemple de uopz_get_return()

    <?php
    uopz_set_return("strlen", 42);
    echo uopz_get_return("strlen");
    ?>

L'exemple ci-dessus va afficher :

    42

# uopz_get_static

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_static — Renvoie les variables statiques d'une fonction ou d'une méthode

### Description

function uopz_get_static(string `$class`, string `$function`): array
function uopz_get_static(string `$function`): array

Renvoie les variables statiques d'une fonction ou d'une méthode.

### Liste de paramètres

`class`

  Le nom de la classe.

`function`

  Le nom de la fonction ou de la méthode.

### Valeurs de retour

Renvoie un array associatif de noms de variables mappés à leurs valeurs actuelles en cas de succès, ou `null` si la fonction ou la méthode n'existe pas.

À partir de PHP 8.3.0, les initialisateurs statiques sont soit calculés lors de la compilation, ou si cela n'est pas possible, uniquement lorsque la fonction ou la méthode est exécutée pour la première fois, auquel cas la valeur de la variable statique est rapportée comme `null` avant la première invocation.

### Exemples

Exemple #1 Utilisation basique de uopz_get_static()

    <?php
    function foo() {
        static $bar = 'baz';
    }
    var_dump(uopz_get_static('foo'));
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }

### Voir aussi

- ReflectionFunctionAbstract::getStaticVariables() - Récupère les variables statiques
- uopz_set_static() - Définit les variables statiques dans la portée d'une fonction ou d'une méthode

# uopz_implement

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_implement — Implémente une interface à l'exécution

### Description

function uopz_implement(string `$class`, string `$interface`): bool

Implémente l'interface `interface` dans la classe `class`.

### Liste de paramètres

`class`

`interface`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

À partir de PHP 7.4.0, uopz_implement() émet une RuntimeException, si OPcache est activé, et l'entrée de classe de `class` est immutable.

### Exemples

Exemple #1 Exemple avec uopz_implement()

    <?php
    interface myInterface {}

    class myClass {}

    uopz_implement(myClass::class, myInterface::class);

    var_dump(class_implements(myClass::class));
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overload — Surcharge un opcode VM

Avertissement

Cette fonction a été SUPPRIMEE dand PECL uopz 5.0.0.

### Description

function uopz_overload(int `$opcode`, Callable `$callable`): void

Surcharge l'`opcode` spécifié avec une fonction définie par l'utilisateur.

### Liste de paramètres

`opcode`

  Un opcode valide ; voir les constantes pour plus de détails sur les codes supportés

`callable`

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec uopz_overload()

    <?php
    uopz_overload(ZEND_EXIT, function(){});

    exit();
    echo "Hello World";
    ?>

L'exemple ci-dessus va afficher :

    Hello World

# uopz_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_redefine — Re-défini une constante

### Description

function uopz_redefine(string `$constant`, mixed `$value`): bool
function uopz_redefine(string `$class`, string `$constant`, mixed `$value`): bool

Re-défini la constante `constant` fournie, en `value`.

### Liste de paramètres

`class`

  Le nom de la classe contenant la constante

`constant`

  Le nom de la constante

`value`

  La nouvelle valeur de la constante ; doit être un type valide pour une constante

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec uopz_redefine()

    <?php
    define("MY", 100);

    uopz_redefine("MY", 1000);

    echo MY;
    ?>

L'exemple ci-dessus va afficher :

    1000

# uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_rename — Renomme une fonction à l'exécution

Avertissement

Cette fonction a été SUPPRIMEE dand PECL uopz 5.0.0.

### Description

function uopz_rename(string `$function`, string `$rename`): void
function uopz_rename(string `$class`, string `$function`, string `$rename`): void

Renomme la fonction `function` en `rename`.

> Note:

> Si les deux fonctions existent, leurs noms seront inversés.

### Liste de paramètres

`class`

  Le nom de la classe contenant la fonction

`function`

  Le nom d'une fonction existante

`rename`

  Le nouveau nom de la fonction

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec uopz_rename()

    <?php
    uopz_rename("strlen", "original_strlen");

    echo original_strlen("Hello World");
    ?>

L'exemple ci-dessus va afficher :

    11

Exemple #2 Exemple avec uopz_rename() et une classe

    <?php
    class My {
        public function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_rename(My::class, "strlen", "original_strlen");

    echo My::original_strlen("Hello World");
    ?>

L'exemple ci-dessus va afficher :

    11

# uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restore — Restaure une fonction sauvegardée

Avertissement

Cette fonction a été SUPPRIMEE dand PECL uopz 5.0.0.

### Description

function uopz_restore(string `$function`): void
function uopz_restore(string `$class`, string `$function`): void

Restaure une fonction sauvegardée.

### Liste de paramètres

`class`

  Le nom de la classe contenant la fonction à restaurer

`function`

  Le nom de la fonction

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec uopz_restore()

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    uopz_restore('fgets');
    fgets();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Warning: fgets() expects at least 1 parameter, 0 given in /path/to/script.php on line 8

# uopz_set_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_hook — Définit le hook à exécuter lors de l'entrée dans une fonction ou une méthode

### Description

function uopz_set_hook(string `$function`, Closure `$hook`): bool
function uopz_set_hook(string `$class`, string `$function`, Closure `$hook`): bool

Définit un hook à exécuter lors de l'entrée dans une fonction ou une méthode.

### Liste de paramètres

`class`

  Le nom de la classe.

`function`

  Le nom de la fonction ou de la méthode.

`hook`

  Une fermeture à exécuter lors de l'entrée dans la fonction ou la méthode.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Utilisation basique de uopz_set_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    ?>

L'exemple ci-dessus va afficher :

    barfoo

### Voir aussi

- uopz_get_hook() - Renvoie le hook précédemment défini sur une fonction ou une méthode
- uopz_unset_hook() - Supprime le hook précédemment défini sur une fonction ou une méthode

# uopz_set_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_mock — Utilise une simulation au lieu d'une classe pour de nouveaux objets

### Description

function uopz_set_mock(string `$class`, mixed `$mock`): void

Si `mock` est une chaîne contenant le nom d'une classe alors elle sera instanciée à la place de `class`. `mock` peut aussi être un objet.

> Note:

> Seul l'accès dynamique aux propriétés et méthodes utilisera l'objet `mock`. L'accès statique utilise toujours la `class` originale. Voir l'exemple ci-dessous.

### Liste de paramètres

`class`

  Le nom de la classe à simuler.

`mock`

  La simulation à utiliser sous forme de chaîne contenant le nom de la classe à utiliser ou un objet. Si une chaîne est passée, elle doit être le nom de la classe entièrement qualifié. Il est recommandé d'utiliser la constante magique `::class` dans ce cas.

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
PECL uopz 6.0.0 | Simuler les membres statiques n'est plus supporté par cette fonction. uopz_redefine() et uopz_set_return(), ou Componere peuvent être utilisés à la place.

### Exemples

Exemple #1 Exemple de uopz_set_mock()

    <?php
    class A {
        public function who() {
            echo "A";
        }
    }

    class mockA {
        public function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    (new A)->who();
    ?>

L'exemple ci-dessus va afficher :

    mockA

Exemple #2 Exemple de uopz_set_mock()

    <?php
    class A {
        public function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                public function who() {
                                    echo "mockA";
                                }
                            });
    (new A)->who();
    ?>

L'exemple ci-dessus va afficher :

    mockA

Exemple #3 uopz_set_mock() et membres statiques

Depuis uopz 6.0.0, la simulation des membres statiques n'est plus supportée.

    <?php
    class A {
        const CON = 'A';
        public static function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                const CON = 'mockA';
                                public static function who() {
                                    echo "mockA";
                                }
                            });
    echo A::CON, PHP_EOL;
    A::who();
    ?>

L'exemple ci-dessus va afficher :

    A
    A

L'exemple ci-dessus affiche avec uopz 5:

    mockA
    mockA

### Voir aussi

- uopz_get_mock() - Renvoie la simulation actuelle d'une classe
- uopz_unset_mock() - Supprime la simulation précédemment définie

# uopz_set_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_property — Définit la valeur d'une propriété de classe existante ou d'instance

### Description

function uopz_set_property(string `$class`, string `$property`, mixed `$value`): void
function uopz_set_property(object `$instance`, string `$property`, mixed `$value`): void

Définit la valeur d'une propriété de classe statique existante, si `class` est donné, ou la valeur d'une propriété d'instance (peu importe si la propriété d'instance existe déjà), si `instance` est donné.

### Liste de paramètres

`class`

  Le nom de la classe.

`instance`

  L'instance de l'objet.

`property`

  Le nom de la propriété.

`value`

  La valeur à assigner à la propriété.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Utilisation basique de uopz_set_property()

    <?php
    class Foo {
       private static $staticBar;
       private $bar;
       public static function testStaticBar() {
          return self::$staticBar;
       }
       public function testBar() {
          return $this->bar;
       }
    }
    $foo = new Foo;
    uopz_set_property('Foo', 'staticBar', 10);
    uopz_set_property($foo, 'bar', 100);
    var_dump(Foo::testStaticBar());
    var_dump($foo->testBar());
    ?>

L'exemple ci-dessus va afficher :

    int(10)

### Voir aussi

- uopz_get_property() - Renvoie la valeur d'une propriété de classe ou d'instance

# uopz_set_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_return — Apporte une valeur de retour pour une fonction existante

### Description

function uopz_set_return(string `$function`, mixed `$value`, bool `$execute` = `false`): bool
function uopz_set_return(
string `$class`,
string `$function`,
mixed `$value`,
bool `$execute` = `false`
): bool

Définit la valeur de retour de la `function` à `value`. Si `value` est une fermeture et que `execute` est défini, la fermeture sera exécutée à la place de la fonction d'origine. Il est possible d'appeler la fonction d'origine depuis la fermeture.

> Note:

> Cette fonction remplace uopz_rename().

### Liste de paramètres

`class`

  Le nom de la classe contenant la fonction

`function`

  Le nom d'une fonction existante

`value`

  La valeur que la fonction doit renvoyer. Si une fermeture est fournie et que le drapeau d'exécution est défini, la fermeture sera exécutée à la place de la fonction d'origine.

`execute`

  Si true, et qu'une fermeture a été fournie en tant que valeur, la fermeture sera exécutée à la place de la fonction d'origine.

### Valeurs de retour

True en cas de succès, sinon false.

### Exemples

Exemple #1 Exemple de uopz_set_return()

    <?php
    uopz_set_return("strlen", 42);
    echo strlen("Banana");
    ?>

L'exemple ci-dessus va afficher :

    42

Exemple #2 Exemple de uopz_set_return()

    <?php
    uopz_set_return("strlen", function($str) { return strlen($str) * 2; }, true );
    echo strlen("Banana");
    ?>

L'exemple ci-dessus va afficher :

    12

Exemple #3 Exemple de uopz_set_return() avec une classe

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }
    uopz_set_return(My::class, "strlen", function($str) { return strlen($str) * 2; }, true );
    echo My::strlen("Banana");
    ?>

L'exemple ci-dessus va afficher :

    12

# uopz_set_static

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_set_static — Définit les variables statiques dans la portée d'une fonction ou d'une méthode

### Description

function uopz_set_static(string `$function`, array `$static`): void
function uopz_set_static(string `$class`, string `$function`, array `$static`): void

Définit les variables statiques dans la portée d'une fonction ou d'une méthode.

### Liste de paramètres

`class`

  Le nom de la classe.

`function`

  Le nom de la fonction ou de la méthode.

`static`

  Le tableau associatif de noms de variables mappés à leurs valeurs.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple d'utilisation de uopz_set_static()

    <?php
    function foo() {
        static $bar = 'baz';
        var_dump($bar);
    }
    uopz_set_static('foo', ['bar' => 'qux']);
    foo();
    ?>

L'exemple ci-dessus va afficher :

    string(3) "qux"

### Voir aussi

- uopz_get_static() - Renvoie les variables statiques d'une fonction ou d'une méthode

# uopz_undefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_undefine — Supprime une constante

### Description

function uopz_undefine(string `$constant`): bool
function uopz_undefine(string `$class`, string `$constant`): bool

Supprime une constante à l'exécution.

### Liste de paramètres

`class`

  Le nom de la classe contenant la `constant`

`constant`

  Le nom d'une constante existante

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec uopz_undefine()

    <?php
    define("MY", true);

    uopz_undefine("MY");

    var_dump(defined("MY"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)

# uopz_unset_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_hook — Supprime le hook précédemment défini sur une fonction ou une méthode

### Description

function uopz_unset_hook(string `$function`): bool
function uopz_unset_hook(string `$class`, string `$function`): bool

Supprime le hook précédemment défini sur une fonction ou une méthode.

### Liste de paramètres

`class`

  Le nom de la classe.

`function`

  Le nom de la fonction ou de la méthode.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Utilisation basique de uopz_unset_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    echo PHP_EOL;
    uopz_unset_hook('foo');
    foo();
    ?>

L'exemple ci-dessus va afficher :

    barfoo
    foo

### Voir aussi

- uopz_set_hook() - Définit le hook à exécuter lors de l'entrée dans une fonction ou une méthode
- uopz_get_hook() - Renvoie le hook précédemment défini sur une fonction ou une méthode

# uopz_unset_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_mock — Supprime la simulation précédemment définie

### Description

function uopz_unset_mock(string `$class`): void

Supprime la simulation précédemment définie pour `class`.

### Liste de paramètres

`class`

  Le nom de la classe simulée.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Une RuntimeException est lancée, si aucune simulation n'a été précédemment définie pour `class`.

### Exemples

Exemple #1 Exemple de uopz_unset_mock()

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    uopz_unset_mock(A::class);
    A::who();
    ?>

L'exemple ci-dessus va afficher :

    A

### Voir aussi

- uopz_set_mock() - Utilise une simulation au lieu d'une classe pour de nouveaux objets
- uopz_get_mock() - Renvoie la simulation actuelle d'une classe

# uopz_unset_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_return — Supprime une valeur de retour précédemment définie pour une fonction

### Description

function uopz_unset_return(string `$function`): bool
function uopz_unset_return(string `$class`, string `$function`): bool

Supprime la valeur de retour de la `function` précédemment définie par uopz_set_return().

### Liste de paramètres

`class`

  Le nom de la classe contenant la fonction

`function`

  Le nom de la fonction

### Valeurs de retour

True en cas de succès

### Exemples

Exemple #1 Exemple de uopz_unset_return()

    <?php
    uopz_set_return("strlen", 42);
    $len = strlen("Banana");
    uopz_unset_return("strlen");
    echo $len + strlen("Banana");
    ?>

L'exemple ci-dessus va afficher :

    48

## Sommaire

- uopz_add_function — Ajoute une fonction ou une méthode inexistante
- uopz_allow_exit — Permet de contrôler l'opcode exit désactivé
- uopz_backup — Sauvegarde une fonction
- uopz_compose — Compose une classe
- uopz_copy — Copie une fonction
- uopz_del_function — Supprime une fonction ou une méthode précédemment ajoutée
- uopz_delete — Supprime une fonction
- uopz_extend — Etend une classe à l'exécution
- uopz_flags — Récupère ou défini les drapeaux d'une fonction ou d'une classe
- uopz_function — Crée une fonction à l'exécution
- uopz_get_exit_status — Renvoie le dernier statut de sortie défini
- uopz_get_hook — Renvoie le hook précédemment défini sur une fonction ou une méthode
- uopz_get_mock — Renvoie la simulation actuelle d'une classe
- uopz_get_property — Renvoie la valeur d'une propriété de classe ou d'instance
- uopz_get_return — Renvoie une valeur de retour précédemment définie pour une fonction
- uopz_get_static — Renvoie les variables statiques d'une fonction ou d'une méthode
- uopz_implement — Implémente une interface à l'exécution
- uopz_overload — Surcharge un opcode VM
- uopz_redefine — Re-défini une constante
- uopz_rename — Renomme une fonction à l'exécution
- uopz_restore — Restaure une fonction sauvegardée
- uopz_set_hook — Définit le hook à exécuter lors de l'entrée dans une fonction ou une méthode
- uopz_set_mock — Utilise une simulation au lieu d'une classe pour de nouveaux objets
- uopz_set_property — Définit la valeur d'une propriété de classe existante ou d'instance
- uopz_set_return — Apporte une valeur de retour pour une fonction existante
- uopz_set_static — Définit les variables statiques dans la portée d'une fonction ou d'une méthode
- uopz_undefine — Supprime une constante
- uopz_unset_hook — Supprime le hook précédemment défini sur une fonction ou une méthode
- uopz_unset_mock — Supprime la simulation précédemment définie
- uopz_unset_return — Supprime une valeur de retour précédemment définie pour une fonction

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Fonctions Uopz
  - uopz_add_function — Ajoute une fonction ou une méthode inexistante
  - uopz_allow_exit — Permet de contrôler l'opcode exit désactivé
  - uopz_backup — Sauvegarde une fonction
  - uopz_compose — Compose une classe
  - uopz_copy — Copie une fonction
  - uopz_del_function — Supprime une fonction ou une méthode précédemment ajoutée
  - uopz_delete — Supprime une fonction
  - uopz_extend — Etend une classe à l'exécution
  - uopz_flags — Récupère ou défini les drapeaux d'une fonction ou d'une classe
  - uopz_function — Crée une fonction à l'exécution
  - uopz_get_exit_status — Renvoie le dernier statut de sortie défini
  - uopz_get_hook — Renvoie le hook précédemment défini sur une fonction ou une méthode
  - uopz_get_mock — Renvoie la simulation actuelle d'une classe
  - uopz_get_property — Renvoie la valeur d'une propriété de classe ou d'instance
  - uopz_get_return — Renvoie une valeur de retour précédemment définie pour une fonction
  - uopz_get_static — Renvoie les variables statiques d'une fonction ou d'une méthode
  - uopz_implement — Implémente une interface à l'exécution
  - uopz_overload — Surcharge un opcode VM
  - uopz_redefine — Re-défini une constante
  - uopz_rename — Renomme une fonction à l'exécution
  - uopz_restore — Restaure une fonction sauvegardée
  - uopz_set_hook — Définit le hook à exécuter lors de l'entrée dans une fonction ou une méthode
  - uopz_set_mock — Utilise une simulation au lieu d'une classe pour de nouveaux objets
  - uopz_set_property — Définit la valeur d'une propriété de classe existante ou d'instance
  - uopz_set_return — Apporte une valeur de retour pour une fonction existante
  - uopz_set_static — Définit les variables statiques dans la portée d'une fonction ou d'une méthode
  - uopz_undefine — Supprime une constante
  - uopz_unset_hook — Supprime le hook précédemment défini sur une fonction ou une méthode
  - uopz_unset_mock — Supprime la simulation précédemment définie
  - uopz_unset_return — Supprime une valeur de retour précédemment définie pour une fonction

# Windows Cache pour PHP

# Introduction

L'extension Windows Cache pour PHP est un accélérateur PHP qui est utilisé pour augmenter la vitesse des applications PHP sous Windows et Windows Server. Une fois l'extension Windows Cache activée et chargée par le moteur PHP, les applications PHP peuvent tirer parti des fonctionnalités sans aucune modification de code.

L'extension Windows Cache comprend 5 types de caches. Ce qui suit décrit le but de chaque type de cache et les avantages qu'il procure.

- Cache d'Opcode PHP - PHP est un moteur de traitement de script, qui lit un flux d'entrée de données qui contient du texte et / ou des instructions PHP et produit un autre flux de données, le plus souvent au format HTML. Cela signifie que sur un serveur Web le moteur PHP lit, analyse, compile et exécute un script PHP à chaque fois qu'il est demandé par un client Web. Les opérations de lecture, d'analyse et de compilation ajoutent une charge supplémentaire sur le processeur (CPU) et sur le système de fichiers, ce qui affecte la performance globale d'une application web PHP. Le cache de bytecode PHP (Opcode) est utilisé pour stocker le bytecode du script compilé dans la mémoire partagée pour qu'il puisse être ré-utilisé par le moteur PHP lors des exécutions suivantes du même script.

  Support pour le cache d'Opcode a été retiré dans `Wincache 2.0.0`, tous les utilisateurs qui souhaitent avoir un opcache devraient utiliser l'extension OPcache qui est incluse avec PHP.

- Cache de fichiers - Même avec le cache d'opcode PHP activé, le moteur PHP doit accéder aux fichiers de script sur un système de fichiers. Lorsque les scripts PHP sont stockés sur le système de fichiers d'un ordinateur distant, les opérations sur ces fichiers introduisent une surcharge importante des performances. L'extension de Cache Windows pour PHP inclut un cache de fichier qui est utilisé pour stocker le contenu des fichiers de scripts PHP dans la mémoire partagée, ce qui réduit le nombre d'opérations effectuées par le moteur PHP sur le système de fichiers.

- Cache de résolution des chemins de fichier - Les scripts PHP incluent ou fonctionnent très souvent avec des fichiers en utilisant des chemins relatifs. Chaque chemin de fichier doit être normalisé en un chemin de fichier absolu par le moteur PHP. Quand une application PHP utilise de nombreux fichiers PHP et y accède par des chemins relatifs, l'opération de résolution des chemins peut impacter négativement les performances de l'application. L'extension de Cache Windows pour PHP fournit un cache de résolution des chemins de fichier, qui est utilisé pour stocker les correspondances entre les chemins de fichier relatifs et absolus, réduisant ainsi le nombre de résolutions que le moteur PHP devra effectuer.

- Cache utilisateur (disponible depuis la version 1.1.0) - Les scripts PHP peuvent tirer profit du cache de mémoire partagée en utilisant l'API de cache utilisateur. Les objets PHP et les variables peuvent être stockées dans le cache utilisateur et réutilisés lors des requêtes suivantes. Ce cache peut être utilisé pour améliorer les performances des scripts PHP et pour partager les données entre plusieurs processus PHP.

- Gestionnaire de session (disponible depuis la version 1.1.0) - Le gestionnaire de session WinCache peut être utilisé pour stocker les données de session PHP dans le cache de la mémoire partagée. Cela évite des opérations sur le système de fichiers pour la lecture et l'écriture des données de session, ce qui améliore les performances lorsqu'un montant important de données est stocké dans la session PHP.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Script de statistiques WinCache
- WinCache Session Handler
- WinCache Functions Reroutes

## Pré-requis

L'extension est actuellement uniquement supportée sur les configurations suivantes :

Windows OS:

- Windows XP SP3 avec IIS 5.1 et l'» Extension FastCGI
- Windows Server 2003 avec IIS 6.0 et l'» Extension FastCGI
- Windows Vista SP1 avec IIS 7.0 et le module FastCGI
- Windows Server 2008 avec IIS 7.0 et le module FastCGI
- Windows 7 avec IIS 7.5 et le module FastCGI
- Windows Server 2008 R2 avec IIS 7.5 et le module FastCGI

PHP:

- PHP 5.2.X, Non-thread-safe build
- PHP 5.3 X86, Non-thread-safe VC9 build

> Note: L'extension WinCache peut uniquement être utilisée lorsque IIS est configuré pour exécuter PHP via FastCGI.

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/wincache.

Il y a deux packages pour cette extension: un package est pour les versions PHP 5.2.X, et l'autre package est pour PHP 5.3.X. Choisissez le package approprié à la version PHP utilisée.

Pour installer et activer l'extension, suivez ces étapes :

1. Décompressez le package dans un endroit temporaire.

2. Copiez le fichier php_wincache.dll dans le dossier d'extensions PHP. En général, ce dossier se nomme "ext" et est situé dans le même dossier avec tous les fichiers binaires PHP. Par exemple : C:\Program Files\PHP\ext.

3. Avec un éditeur de texte, ouvrez le fichier php.ini, qui se trouve généralement dans le même dossier que tous les fichiers binaires PHP. Par exemple : C:\Program Files\PHP\php.ini.

4. Ajouter la ligne suivante à la fin du fichier php.ini : `extension = php_wincache.dll`.

5. Enregistrez et fermez le fichier php.ini.

6. Redémarrez le pool d'application IIS pour que PHP récupère les changements de configuration. Pour vérifier que l'extension a été activée, créez un fichier nommé phpinfo.php contenant un appel à la fonction phpinfo.

7. Sauvez le fichier phpinfo.php dans le répertoire racine d'un site Web IIS qui utilise PHP, puis ouvrez un navigateur et faites une requête sur http://localhost/phpinfo.php. Cherchez une section appelée `wincache` dans la page retournée. Si l'extension est activée, alors la sortie de phpinfo listera les paramètres de configuration fournis par WinCache.

> Note: Ne pas oublier de supprimer le fichier phpinfo.php du répertoire racine après avoir vérifié que l'extension a été activée.

## Configuration à l'exécution

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

Le tableau suivant répertorie et explique les paramètres de configuration fournis par l'extension WinCache :

Options de configuration WinCache
Nom | Défaut | Minimum | Maximum | Modifiable | Historique
--- | --- | --- | --- | --- | ---
wincache.fcenabled | "1" | "0" | "1" | `INI_ALL` | Disponible depuis WinCache 1.0.0
wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0
wincache.fcachesize | "24" | "5" | "255" | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0
wincache.fcndetect | "1" | "0" | "1" | `INI_SYSTEM` | Disponible depuis WinCache 1.1.0
wincache.maxfilesize | "256" | "10" | "2048" | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0
wincache.ocenabled | "1" | "0" | "1" | `INI_ALL` | Disponible depuis WinCache 1.0.0. Supprimé depuis 2.0.0.0
wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0. Supprimé depuis 2.0.0.0
wincache.ocachesize | "96" | "15" | "255" | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0. Supprimé depuis 2.0.0.0
wincache.filecount | "4096" | "1024" | "16384" | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0
wincache.chkinterval | "30" | "0" | "300" | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0
wincache.ttlmax | "1200" | "0" | "7200" | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0
wincache.enablecli | 0 | 0 | 1 | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0
wincache.ignorelist | NULL | NULL | NULL | `INI_ALL` | Disponible depuis WinCache 1.0.0
wincache.namesalt | NULL | NULL | NULL | `INI_SYSTEM` | Disponible depuis WinCache 1.0.0
wincache.ucenabled | 1 | 0 | 1 | `INI_SYSTEM` | Disponible depuis WinCache 1.1.0
wincache.ucachesize | 8 | 5 | 85 | `INI_SYSTEM` | Disponible depuis WinCache 1.1.0
wincache.scachesize | 8 | 5 | 85 | `INI_SYSTEM` | Disponible depuis WinCache 1.1.0
wincache.rerouteini | NULL | NULL | NULL | `INI_SYSTEM` | Disponible depuis WinCache 1.2.0. Retiré dans la version 1.3.7
wincache.reroute_enabled | 1 | 0 | 1 | `INI_SYSTEM`|`INI_PERDIR` | Disponible depuis WinCache 1.3.7
wincache.srwlocks | 1 | 0 | 1 | `INI_SYSTEM` | Disponible depuis WinCache 1.3.6.3. Supprimé depuis la version 2.0.0.0
wincache.filemapdir | NULL | NULL | NULL | `INI_SYSTEM` | Disponible depuis WinCache 1.3.7.4

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`wincache.fcenabled` bool
  Active ou désactive la fonctionnalité de cache de fichiers.
`wincache.fcenabledfilter` string
  Définit une liste séparée par des virgules, d'identificateurs de site Web IIS où le cache de fichiers doit être activé ou désactivé. Ce paramètre fonctionne en conjonction avec `wincache.fcenabled` : Si `wincache.fcenabled` est réglé à 1, alors les sites listés dans `wincache.fcenabledfilter` auront le cache de fichiers désactivé; si `wincache.fcenabled` est réglé à 0, alors les sites listés dans `wincache.fcenabledfilter` auront le cache de fichiers activé.
`wincache.fcachesize` int
  Définit la taille maximale de mémoire (en mégaoctets) qui est allouée pour le cache de fichiers. Si la taille totale de tous les fichiers en cache dépasse la valeur spécifiée dans ce paramètre, alors la plupart des fichiers périmés seront retirés du cache de fichiers.
`wincache.fcndetect` bool
  Active ou désactive les notifications de détection de modification de fichier. Si la notification est supportée, alors elle sera utilisée pour rafraîchir l'opcode ainsi que les entrées du fichier présentes dans le cache aussitôt la modification correspondante des fichiers effectuée sur le système de fichiers. Si la notification n'est pas supportée, par exemple lors de l'utilisation de fichiers partagés par le réseau, alors Wincache vérifiera les modifications de fichiers à intervalle régulier spécifié par le paramètre `wincache.chkinterval`.
`wincache.maxfilesize` int
  Définit la taille maximale autorisée (en kilo-octets) pour un fichier unique qui sera mis en cache. Si un fichier a une taille supérieure à la valeur spécifiée, le fichier ne sera pas mis en cache. Ce paramètre s'applique à la mémoire cache de fichier seulement.
`wincache.ocenabled` bool
  Avertissement

  Cette option a été SUPPRIMEE depuis la version 2.0.0.0

  Active ou désactive la fonctionnalité de cache opcode
`wincache.ocenabledfilter` string
  Avertissement

  Cette option a été SUPPRIMEE depuis la version 2.0.0.0

  Définit une liste séparée par des virgules, d'identificateurs de site Web IIS où le cache opcode doit être activé ou désactivé. Ce paramètre fonctionne en conjonction avec `wincache.ocenabled` : Si `wincache.ocenabled` est réglé à 1, alors les sites listés dans `wincache.ocenabledfilter` auront le cache opcode désactivé; si `wincache.ocenabled` est réglé à 0, alors les sites listés dans `wincache.ocenabledfilter` auront le cache opcode activé.
`wincache.ocachesize` int
  Avertissement

  Cette option a été SUPPRIMEE depuis la version 2.0.0.0

  Définit la taille maximale de mémoire (en mégaoctets) qui est allouée pour le cache opcode. Si la taille du cache opcode dépasse la valeur spécifiée, alors l'opcode le plus ancien sera retiré du cache. Il est à noter que la taille du cache d'opcode doit être au moins 3 fois plus grande que la taille du cache de fichiers. Si ce n'est pas le cas la taille du cache opcode sera automatiquement augmentée.
`wincache.filecount` int
  Définit combien de fichiers sont censés être mis en cache par l'extension, de sorte à ce qu'un montant de mémoire suffisant soit alloué au démarrage. Si le nombre de fichiers excède la valeur spécifiée, WinCache ré-allouera plus de mémoire comme demandé.
`wincache.chkinterval` int
  Définit la fréquence (en secondes) à laquelle l'extension vérifiera les changements de fichier de façon à rafraîchir le cache. Mettre cette option à 0 permet de désactiver le rafraîchissement du cache. Les changements de fichiers ne seront pas reflétés dans le cache à moins que l'entrée de cache soit supprimée par le récupérateur, que le pool d'applications IIS soit recyclé, ou que la fonction wincache_refresh_if_changed soit appelée.
`wincache.ttlmax` int
  Définit le temps de vie maximale (en secondes) pour une entrée de cache sans être utilisée. Définir ce paramètre à 0 désactive le récupérateur de cache, de façon à ce que les entrées du cache ne soient jamais supprimées du cache pendant la durée de vie du processus de travail IIS.
`wincache.enablecli` bool
  Définit si le cache est activé lorsque PHP fonctionne en ligne de commande (CLI) .
`wincache.ignorelist` string

  Définit une liste de fichiers qui ne doivent pas être mis en cache par l'extension. La liste des fichiers est spécifiée en utilisant des noms de fichiers uniquement, séparés par le symbole pipe - "|".

  Exemple #1 `wincache.ignorelist` exemple

      wincache.ignorelist = "index.php|misc.php|admin.php"

`wincache.namesalt` string
  Définit une chaîne qui sera utilisée lors du nommage des objets spécifiques à l'extension qui seront stockés dans la mémoire partagée. Ce paramètre est utilisé afin d'éviter les conflits qui peuvent être provoqués si d'autres applications dans un processus de travail IIS tentent d'accéder à la mémoire partagée. La longueur de la chaîne namesalt ne peut être supérieure à 8 caractères.
`wincache.ucenabled` bool
  Active ou désactive la fonctionnalité de cache utilisateur.
`wincache.ucachesize` int
  Définit la taille maximale de mémoire (en mégaoctets) qui est allouée pour le cache utilisateur. Si la taille totale des variables stockées dans le cache utilisateur dépasse la valeur spécifiée, alors les plus anciennes variables seront retirées du cache.
`wincache.scachesize` int
  Définit la taille maximale de mémoire, en méga-octets, à allouer pour le cache de la session. Si la taille totale des données stockées dans le cache de la session excède la valeur spécifiée, alors les données les plus anciennes seront supprimées du cache.
`wincache.rerouteini` string
  Avertissement

  Cette option a été SUPPRIMEE depuis la version 1.3.7. Voir `wincache.reroute_enabled` pour des fonctionnalités similaires depuis la version 1.3.7.

  Indique un chemin absolu ou relatif vers le fichier reroute.ini contenant une liste de fonctions PHP dont les implémentations devraient être remplacées par les équivalents Wincache. Si un chemin relatif est passé, il est supposé relatif au fichier php-cgi.exe.
`wincache.reroute_enabled` bool
  Active ou désactive le reroutage de certaines fonctions d'entrées sorties sur des fichiers au travers du cache fichier
`wincache.srwlocks` bool
  Avertissement

  Cette option a été SUPPRIMEE depuis la version 2.0.0.0

  Active ou désactive l'utilisation de verrous partagés en lecture écriture. Le désactiver peut être utile lorsque surviennent des problèmes d'interblocage dans WinCache.
`wincache.filemapdir` string
  Spécifie un chemin absolu vers un dossier où WinCache va stocker les fichiers temporaires utilisés pour les segments de mémoire partagés. Ce dossier doit être sur la machine locale et non sur un système de fichier en réseau. Si le dossier n'est pas précisé, WinCache va utiliser le Windows System Page File pour tous les segments de mémoire partagés.

## Script de statistiques WinCache

Le package d'installation pour WinCache inclut un script PHP, wincache.php, qui peut être utilisé pour obtenir des informations et des statistiques sur le cache.

Si l'extension WinCache a été installée via l'installeur de Microsoft Web Platform, alors ce script se trouve dans %SystemDrive%\Program Files\IIS\Windows Cache for PHP\. Sur une version 64 bits du système d'exploitation Windows Server, le script se trouve dans %SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP. Si l'extension a été installée manuellement, alors le fichier wincache.php sera situé dans le même dossier à partir duquel le contenu du package d'installation a été extrait.

Pour utiliser wincache.php, copiez-le dans le dossier racine d'un site Web ou dans n'importe quel sous-dossier. Pour protéger le script, ouvrez-le dans n'importe quel éditeur et remplacez les valeurs des constantes USERNAME et PASSWORD. Si n'importe quel autre authentification IIS est activée sur le serveur, alors suivez les instructions dans les commentaires :

Exemple #1 Configuration de l'authentification pour wincache.php

    <?php
    /**
     * ======================== CONFIGURATION SETTINGS ==============================
     * If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
     * If you use authentication then replace the default password.
     */
    define('USE_AUTHENTICATION', 1);
    define('USERNAME', 'wincache');
    define('PASSWORD', 'wincache');

    /**
     * The Basic PHP authentication will work only when IIS is configured to support
     * Anonymous Authentication' and nothing else. If IIS is configured to support/use
     * any other kind of authentication like Basic/Negotiate/Digest etc, this will not work.
     * In that case use the array below to define the names of users in your
     * domain/network/workgroup which you want to grant access to.
     */
    $user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');

    /**
     * If the array contains string 'all', then all the users authenticated by IIS
     * will have access to the page. Uncomment the below line and comment above line
     * to grant access to all users who gets authenticated by IIS.
     */
    /* $user_allowed = array('all'); */

    /** ===================== END OF CONFIGURATION SETTINGS ========================== */
    ?>

> Note: Protégez toujours le script wincache.php en utilisant soit le mécanisme d'authentification intégré ou le mécanisme d'authentification du serveur. Laisser ce script non protégé peut compromettre la sécurité de l'application web et du serveur.

## WinCache Session Handler

Le gestionnaire de session WinCache (disponible depuis WinCache 1.1.0) peut être utilisé pour configurer PHP pour stocker les données de session dans la mémoire partagée du cache de session. L'utilisation de la mémoire partagée au lieu de la session par défaut aide à améliorer les performances des applications PHP qui stockent de grandes quantités de données dans des objets de session. Le cache de session Wincache utilise des fichiers basés sur la mémoire partagée, ce qui assure que les données de session ne seront pas perdues lors du recyclage de la file d'attente des applications IIS.

Pour configurer PHP pour utiliser le gestionnaire de session WinCache mettez le paramètre session.save_handler du fichier php.ini à wincache. Par défaut, l'endroit où sont stockés les fichiers temporaires sous Windows est utilisé pour stocker les données de session. Pour changer cet endroit, utiliser la directive session.save_path.

Exemple #1 Activer le gestionnaire de session WinCache

    session.save_handler = wincache
    session.save_path = C:\inetpub\temp\session\

## WinCache Functions Reroutes

NOTE: wincache.rerouteini a été retiré avec WinCache 1.3.7.0. Cela a été remplacé par le reroutage automatique de fonction. Voir : wincache.reroute_enabled

Les fonctionnalités WinCache de re routages de fonctions (disponibles depuis WinCache 1.2.0, retirée depuis WinCache 1.3.7.0) peuvent être utilisées pour remplacer des fonctions PHP natives par leur équivalent optimisé pour des cas particuliers. L'extension Wincache inclut des implémentations de fonctions PHP optimisées pour Windows, notamment dans les cas d'accès réseau ou système de fichiers. Les fonctions suivantes sont concernées :

- file_exists
- file_get_contents
- readfile
- is_readable
- is_writable
- is_dir
- realpath
- filesize

Pour configurer le re routage de fonctions avec Wincache, utiliser le fichier reroute.ini inclus dans le paquet. Copiez-le dans le dossier où se trouve php.ini. Après, ajoutez wincache.rerouteini dans php.ini et précisez le chemin absolu ou relatif vers reroute.ini.

Exemple #1 Activation des fonctionnalités de re routage des fonctions de WinCache

    wincache.rerouteini = C:\PHP\reroute.ini

> Note: Si activé, il est recommandé d'augmenter la taille du cache des fichiers. Ceci peut être fait en utilisant le paramètre wincache.fcachesize.

Le fichier reroute.ini contient la correspondance entre la fonction PHP native et l'équivalent Wincache. Chaque ligne dans le fichier définit une correspondance. Voici la syntaxe:

`<PHP function name>:[<number of function parameters>]=<wincache function name>`

Un exemple de fichier est donné plus bas. Dans cet exemple, les appels aux fonctions PHP file_get_contents() seront remplacés par wincache_file_get_contents() seulement si le nombre de paramètres passés à la fonction est inférieur ou égal à deux. C'est utile de préciser le nombre de paramètres lorsque la fonction de remplacement n'est pas conçue pour tous les utiliser.

Exemple #2 Reroute.ini

    [FunctionRerouteList]
    file_exists=wincache_file_exists
    file_get_contents:2=wincache_file_get_contents
    readfile:2=wincache_readfile
    is_readable=wincache_is_readable
    is_writable=wincache_is_writable
    is_writeable=wincache_is_writable
    is_file=wincache_is_file
    is_dir=wincache_is_dir
    realpath=wincache_realpath
    filesize=wincache_filesize

# Fonctions WinCache

# wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — Extrait des informations sur les fichiers mis en cache dans le cache de fichiers

### Description

function wincache_fcache_fileinfo(bool `$summaryonly` = `false`): array|false

Extrait des informations sur le contenu du cache de fichiers et son utilisation.

### Liste de paramètres

`summaryonly`

  Si le tableau retourné doit contenir des informations sur chaque entrée du cache en plus du résumé sur les fichiers du cache.

### Valeurs de retour

Tableau de méta-données sur le cache de fichier ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants :

- `total_cache_uptime` - Temps d'activité total en secondes du cache de fichiers
- `total_file_count` - Nombre total de fichiers actuellement dans le cache de fichiers
- `total_hit_count` - Nombre de fois où les fichiers ont été servis à partir du cache du fichiers
- `total_miss_count` - Nombre de fois que les fichiers n'ont pas été trouvés dans le cache de fichiers

- `file_entries` - Tableau contenant les informations sur tous les fichiers mis en cache:

  - `file_name` - Nom et chemin absolu du fichier en cache
  - `add_time` - Temps en secondes depuis que le fichier a été ajouté au cache de fichiers
  - `use_time` - Temps en secondes depuis que le fichier a été consulté dans le cache de fichier
  - `last_check` - Temps en secondes depuis la dernière vérification de modifications
  - `hit_count` - Nombre de fois que le fichier a été servi à partir du cache
  - `file_size` - Taille en bytes du fichier caché

### Exemples

Exemple #1 Un exemple de wincache_fcache_fileinfo()

    <pre>
    <?php
    print_r(wincache_fcache_fileinfo());
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (   [total_cache_uptime] => 3234
        [total_file_count] => 5
        [total_hit_count] => 0
        [total_miss_count] => 1
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 1
                        [use_time] => 0
                        [last_check] => 1
                        [hit_count] => 1
                        [file_size] => 2435
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Voir aussi

- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_ocache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_ocache_meminfo() - Extrait des informations sur l'utilisation du cache opcode
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache
- wincache_scache_meminfo() - Récupère des informations sur l'utilisation de la mémoire du cache

# wincache_fcache_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfo — Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.

### Description

function wincache_fcache_meminfo(): array|false

Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Tableau de méta-données sur l'utilisation de la mémoire du cache de fichiers ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants:

- `memory_total` - Quantité de mémoire en octets allouée pour le cache de fichiers
- `memory_free` - Quantité de mémoire libre en octets disponible pour le cache de fichiers
- `num_used_blks` - Nombre de blocs mémoire utilisés par le cache de fichiers
- `num_free_blks` - Nombre de blocs mémoire libres disponibles pour le cache de fichiers
- `memory_overhead` - Quantité de mémoire en bytes utilisée pour la structure interne du cache de fichiers

### Exemples

Exemple #1 Un exemple de wincache_fcache_meminfo()

    <pre>
    <?php
    print_r(wincache_fcache_meminfo());
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 131339120
        [num_used_blks] => 361
        [num_free_blks] => 3
        [memory_overhead] => 5856
    )

### Voir aussi

- wincache_fcache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_ocache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_ocache_meminfo() - Extrait des informations sur l'utilisation du cache opcode
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache
- wincache_scache_meminfo() - Récupère des informations sur l'utilisation de la mémoire du cache

# wincache_lock

(PECL wincache >= 1.1.0)

wincache_lock — Acquière un verrou exclusif sur une clé donnée

### Description

function wincache_lock(string `$key`, bool `$isglobal` = `false`): bool

Obtient un verrou exclusif sur une clé donnée. L'exécution du script courant sera bloqué tant que le verrou ne pourra pas être obtenu. Une fois le verrou obtenu, les autres scripts tentant de requérir le verrou en utilisant la même clé seront bloqués, tant que le script courant n'aura pas libéré le verrou en utilisant la fonction wincache_unlock().

Avertissement

L'utilisation de la fonction wincache_lock() et de la fonction wincache_unlock() peut conduire à des verrous morts lors de l'exécution de scripts PHP sur des environnements multiprocessus, comme FastCGI. N'utiliser pas ces fonctions à moins d'être absolument certain d'en avoir besoin. Pour la majorité des opérations sur le cache utilisateur, il n'est pas nécessaire de les utiliser.

### Liste de paramètres

`key`

  Nom de la clé du cache dont nous souhaitons obtenir un verrou.

`isglobal`

  Contrôle si le contexte du verrou est local ou au niveau système. Les verrous locaux ont un contexte au niveau applicatif dans le cas de l'utilisation sous IIS Fast CGI ou au niveau de tous les processus PHP qui ont le même identifiant parent de processus.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec wincache_lock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // obtient un verrou exclusif
        ftruncate($fp, 0); // tronque le fichier
        fwrite($fp, "On écrit quelque chose ici\n");
        wincache_unlock(“lock_txt_lock”); // libère le verrou
    } else {
        echo "Impossible d'obtenir le verrou !";
    }
    fclose($fp);
    ?>

### Voir aussi

- wincache_unlock() - Libère un verrou exclusif sur une clé donnée
- wincache_ucache_set() - Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache
- wincache_ucache_get() - Récupère une variable stockée dans le cache utilisateur
- wincache_ucache_delete() - Supprime les variables du cache utilisateur
- wincache_ucache_clear() - Supprime le contenu d'une entrée du cache utilisateur
- wincache_ucache_exists() - Vérifie si une variable existe dans le cache utilisateur
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache

# wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfo — Extrait des informations sur les fichiers mis en cache dans le cache opcode

### Description

function wincache_ocache_fileinfo(bool `$summaryonly` = `false`): array|false

Extrait des informations sur le contenu du cache opcode et son utilisation.

Avertissement

Cette fonction a été SUPPRIMÉE à partir de PHP 7.0.0.

### Liste de paramètres

`summaryonly`

  Contrôle si le tableau retourné doit contenir des informations sur les entrées individuelles du cache en plus du résumé sur le cache opcode.

### Valeurs de retour

Tableau de méta-données sur le cache opcode ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants:

- `total_cache_uptime` - Temps d'activité total en secondes du cache opcode
- `total_file_count` - Nombre total de fichiers actuellement dans le cache opcode
- `total_hit_count` - Nombre total de fois où l'opcode compilé a été servi par le cache
- `total_miss_count` - Nombre de fois où l'opcode compilé n'a pas été trouvé dans le cache
- `is_local_cache` - true si les méta-données du cache sont pour une instance de cache local, false si les méta-données sont pour le cache global.

- `file_entries` - Tableau contenant les informations sur tous les fichiers mis en cache:

  - `file_name` - Nom de fichier absolu du fichier en cache
  - `add_time` - Temps en secondes depuis l'ajout du fichier dans le cache opcode
  - `use_time` - Temps en secondes depuis la consultation du fichier dans le cache opcode
  - `last_check` - Temps en secondes depuis où le fichier a été vérifié pour les modifications
  - `hit_count` - Nombre de fois où le fichier a été servi par le cache
  - `function_count` - Nombre de fonctions dans le cache
  - `class_count` - Nombre de classes dans le cache

### Exemples

Exemple #1 Un exemple de wincache_ocache_fileinfo()

    <pre>
    <?php
    print_r(wincache_ocache_fileinfo());
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Voir aussi

- wincache_fcache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_ocache_meminfo() - Extrait des informations sur l'utilisation du cache opcode
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache
- wincache_scache_meminfo() - Récupère des informations sur l'utilisation de la mémoire du cache

# wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfo — Extrait des informations sur l'utilisation du cache opcode

### Description

function wincache_ocache_meminfo(): array|false

Extrait des informations sur l'utilisation de la mémoire par le cache opcode.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Tableau de méta-données sur l'utilisation de la mémoire cache opcode ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants :

- `memory_total` - Quantité de mémoire en octets, allouée pour le cache opcode
- `memory_free` - Quantité de mémoire libre en octets, disponible pour le cache opcode
- `num_used_blks` - Nombre de blocs mémoire utilisés par le cache opcode
- `num_free_blks` - Nombre de blocs mémoire libres disponibles pour le cache opcode
- `memory_overhead` - Quantité de mémoire en octets utilisée pour la structure interne du cache opcode

Avertissement

Cette fonction a été SUPPRIMÉE à partir de PHP 7.0.0.

### Exemples

Exemple #1 Un exemple de wincache_ocache_meminfo()

    <pre>
    <?php
    print_r(wincache_ocache_meminfo());
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 112106972
        [num_used_blks] => 15469
        [num_free_blks] => 4
        [memory_overhead] => 247600
    )

### Voir aussi

- wincache_fcache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_ocache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache
- wincache_scache_meminfo() - Récupère des informations sur l'utilisation de la mémoire du cache

# wincache_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changed — Actualise les entrées du cache pour les fichiers mis en cache

### Description

function wincache_refresh_if_changed(array `$files` = NULL): bool

Actualise les entrées du cache pour les fichiers dont les noms ont été passés dans les arguments d'entrée. Si aucun argument n'est précisé, alors, actualise toutes les entrées du cache.

### Liste de paramètres

`files`

  Tableau de noms de fichiers pour les fichiers qui ont besoin d'être actualisés. Un chemin de fichier absolu ou relatif peut être utilisé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

WinCache effectue des contrôles réguliers sur les fichiers mis en cache pour veiller à ce que, si un fichier a changé, l'entrée correspondante dans la mémoire cache soit mise à jour. Par défaut, cette vérification est effectuée toutes les 30 secondes. Si par exemple un script PHP met à jour un autre script PHP où les configurations de l'application sont stockées, alors il peut arriver qu'après les changements de configuration soient sauvés, l'application utilise toujours les anciens paramètres pour quelque temps jusqu'à ce que le cache soit actualisé. Dans ce cas, il est préférable d'actualiser le cache juste après que le fichier a été modifié. L'exemple qui suit montre comment cela peut être effectué.

Exemple #1 Un exemple de wincache_refresh_if_changed()

    <?php
    $filename = 'C:\inetpub\wwwroot\config.php';
    $handle = fopen($filename, 'w+');
    if ($handle === FALSE) die('Failed to open file '.$filename.' for writing');
    fwrite($handle, '<?php $setting=something; ?>');
    fclose($handle);
    wincache_refresh_if_changed(array($filename));
    ?>

### Voir aussi

- wincache_fcache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_ocache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_ocache_meminfo() - Extrait des informations sur l'utilisation du cache opcode
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur

# wincache_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfo — Récupère des informations du cache sur un chemin de fichier résolu

### Description

function wincache_rplist_fileinfo(bool `$summaryonly` = `false`): array|false

Récupère des informations sur une cartographie en cache entre des chemins relatifs de fichiers et leurs correspondances en chemins absolus.

### Liste de paramètres

`summaryonly`

### Valeurs de retour

Un tableau de données méta contenant le contenu du cache d'un chemin de fichier résolu ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants :

- `total_file_count` - nombre total de chemins de fichiers stockés dans le cache

- `rplist_entries` - un tableau contenant les informations sur les chemins de fichier présents en cache :

  - `resolve_path` - chemin vers le fichier
  - `subkey_data` - chemin absolu correspondant

### Exemples

Exemple #1 Exemple avec wincache_rplist_fileinfo()

    <pre>
    <?php
    print_r(wincache_rplist_fileinfo());
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (
        [total_file_count] => 5
        [rplist_entries] => Array
            (
                [1] => Array
                    (
                        [resolve_path] => checkcache.php
                        [subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
                    )

                [2] => Array (...iterates for each cached file)
            )
    )

### Voir aussi

- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_fcache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_ocache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_ocache_meminfo() - Extrait des informations sur l'utilisation du cache opcode
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache
- wincache_scache_meminfo() - Récupère des informations sur l'utilisation de la mémoire du cache

# wincache_rplist_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfo — Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu

### Description

function wincache_rplist_meminfo(): array|false

Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de données méta qui décrit l'utilisation de la mémoire par le cache de chemin de fichier résolu. ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants :

- `memory_total` - nombre total de mémoire, en octets, allouée au cache de chemins de fichiers résolus
- `memory_free` - mémoire libre, en octets, disponible pour le cache de chemins de fichiers résolus
- `num_used_blks` - blocs mémoires utilisés par le cache de chemins de fichiers résolus
- `num_free_blks` - nombre de blocs mémoires de libre pour le cache des chemins de fichiers résolus
- `memory_overhead` - mémoire, en octets, utilisée pour la structure interne du cache des chemins de fichiers résolus

### Exemples

Exemple #1 Exemple avec wincache_rplist_meminfo()

    <pre>
    <?php
    print_r(wincache_rplist_meminfo());
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (
        [memory_total] => 9437184
        [memory_free] => 9416744
        [num_used_blks] => 23
        [num_free_blks] => 1
        [memory_overhead] => 416
    )

### Voir aussi

- wincache_fcache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_ocache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_ocache_meminfo() - Extrait des informations sur l'utilisation du cache opcode
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache
- wincache_scache_meminfo() - Récupère des informations sur l'utilisation de la mémoire du cache

# wincache_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_info — Récupère des informations sur des fichiers mis en cache

### Description

function wincache_scache_info(bool `$summaryonly` = `false`): array|false

Récupère des informations sur le contenu du cache et son utilisation.

### Liste de paramètres

`summaryonly`

  Contrôle si le tableau retourné doit contenir des informations sur des entrées individuelles du cache en plus du résumé du cache.

### Valeurs de retour

Un tableau de données méta sur le cache pour cette session ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants :

- `total_cache_uptime` - durée total (en secondes) d'activation du cache
- `total_item_count` - nombre total d'éléments contenus actuellement dans le cache
- `is_local_cache` - `true` si les méta-données du cache sont pour une instance de cache locale, `false` si elles sont pour un cache global
- `total_hit_count` - nombre total de fois que les données ont été servies depuis le cache
- `total_miss_count` - nombre total de fois que les données n'ont pas été trouvées dans le cache

- `scache_entries` - un tableau contenant les informations sur les éléments mis en cache :

  - `key_name` - nom de la clé utilisé pour stocker les données
  - `value_type` - type de la valeur stockée
  - `use_time` - durée, en secondes, depuis le dernier accès du fichier depuis le cache opcode
  - `last_check` - durée, en secondes, depuis la dernière fois où le fichier a été vérifié afin de détection des modifications
  - `ttl_seconds` - durée restante avant suppression des données du cache, 0 signifiant qu'elles ne seront jamais supprimées
  - `age_seconds` - l'âge des données dans le cache (i.e. depuis leurs insertions)
  - `hitcount` - nombre de fois que les données ont été servies depuis le cache

### Exemples

Exemple #1 Exemple avec wincache_scache_info()

    <pre>
    <?php
    print_r(wincache_scache_info());
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [scache_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Voir aussi

- wincache_fcache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_ocache_meminfo() - Extrait des informations sur l'utilisation du cache opcode
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_meminfo() - Récupère des informations sur l'utilisation de la mémoire du cache

# wincache_scache_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfo — Récupère des informations sur l'utilisation de la mémoire du cache

### Description

function wincache_scache_meminfo(): array|false

Récupère des informations sur l'utilisation mémoire du cache.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de données méta sur l'utilisation de la mémoire du cache ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants :

- `memory_total` - mémoire, en octets, allouée au cache
- `memory_free` - mémoire disponible, en octets, pour le cache
- `num_used_blks` - nombre de blocs mémoires utilisés par le cache
- `num_free_blks` - nombre de blocs mémoires disponibles pour le cache
- `memory_overhead` - mémoire, en octets, utilisé par les structures internes du cache

### Exemples

Exemple #1 Exemple avec wincache_scache_meminfo()

    <pre>
    <?php
    print_r(wincache_scache_meminfo());
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Voir aussi

- wincache_fcache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_ocache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache

# wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — Ajoute une nouvelle variable au cache utilisateur

### Description

function wincache_ucache_add(string `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Ajoute une variable au cache utilisateur, uniquement si elle n'existe pas déjà dans le cache. La variable restera dans le cache tant que le délai d'expiration n'est pas atteint ou qu'elle n'est effacée par la fonction wincache_ucache_delete() ou la fonction wincache_ucache_clear().

### Liste de paramètres

`key`

  Stocke la variable en utilisant le nom `key`. Si une variable correspondant à la même clé est déjà présente dans le cache, la fonction échouera et retournera `false`. Le paramètre `key` est sensible à la casse. Pour écraser cette valeur, si `key` est présent, utiliser plutôt la fonction wincache_ucache_set(). `key` peut également être un tableau de paires nom => valeur où les noms seront utilisés comme clés. Ce format peut être utilisé pour ajouter de multiples valeurs dans le cache en une seule opération.

`value`

  La valeur de la variable à stocker. Le paramètre `Value` supporte tous les types de données, sauf les ressources, comme des pointeurs de fichiers. Ce paramètre sera ignoré si le premier argument est un tableau. De façon général, il convient de passer la valeur `null` au paramètre `value` lors de l'utilisation d'un tableau pour le paramètre `key`. Si le paramètre `value` est un objet, ou un tableau contenant des objets, alors les objets seront sérialisés. Se reporter à la fonction __sleep() pour plus de détails sur la sérialisation d'objets.

`values`

  Tableau associatif de clés et de valeurs.

`ttl`

  Durée de vie de la variable dans le cache, en secondes. Après la durée spécifiée par le paramètre `ttl`, la variable stockée sera supprimée du cache. Ce paramètre prend, comme valeur par défaut, zéro (`0`), ce qui signifie que la variable restera dans le cache tant qu'elle n'est pas explicitement effacée en utilisant la fonction wincache_ucache_delete() ou la fonction wincache_ucache_clear().

### Valeurs de retour

Si le paramètre `key` est une chaîne de caractères, la fonction retourne `true` en cas de succès, `false` si une erreur survient.

Si le paramètre `key` est un tableau, la fonction retourne :

- Si toutes les paires nom => valeur du tableau peuvent être définies, la fonction retournera un tableau vide ;
- Si toutes les paires nom => valeur du tableau ne peuvent être définies, la fonction retournera `false` ;
- Si certaines peuvent être définies, et d'autres non, la fonction retournera un tableau de paires nom => valeur n'ayant pû être définies dans le cache utilisateur.

### Exemples

Exemple #1 Exemple avec wincache_ucache_add() et le paramètre `key` sous forme de chaîne de caractères

    <?php
    $bar = 'BAR';
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_get('foo'));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    string(3) "BAR"

Exemple #2 Exemple avec wincache_ucache_add() et le paramètre `key` sous forme d'un tableau

    <?php
    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_get('Blue'));
    ?>

L'exemple ci-dessus va afficher :

    array(0) { }
    array(4) {
      ["green"]=> int(-1)
      ["Blue"]=> int(-1)
      ["yellow"]=> int(-1)
      ["cyan"]=> int(-1)
    }
    string(1) "6"

### Voir aussi

- wincache_ucache_set() - Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache
- wincache_ucache_get() - Récupère une variable stockée dans le cache utilisateur
- wincache_ucache_delete() - Supprime les variables du cache utilisateur
- wincache_ucache_clear() - Supprime le contenu d'une entrée du cache utilisateur
- wincache_ucache_exists() - Vérifie si une variable existe dans le cache utilisateur
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- __sleep()

# wincache_ucache_cas

(PECL wincache >= 1.1.0)

wincache_ucache_cas — Compare la variable avec son ancienne valeur et lui assigne une nouvelle valeur

### Description

function wincache_ucache_cas(string `$key`, int `$old_value`, int `$new_value`): bool

Compare la variable associée avec la clé `key` avec la valeur `old_value` et si elle correspond, lui assigne la nouvelle valeur `new_value`.

### Liste de paramètres

`key`

  La clé `key` utilisé pour stocker la variable dans le cache. `key` est sensible à la casse.

`old_value`

  L'ancienne valeur de la variable pointée par le paramètre `key` dans le cache utilisateur. La valeur doit être de type `long`, sinon, la fonction retournera `false`.

`new_value`

  La nouvelle valeur qui sera assignée à la variable pointée par la clé `key` si la correspondance a été trouvée. La valeur doit être de type `long`, sinon, la fonction retournera `false`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec wincache_ucache_cas()

    <?php
    wincache_ucache_set('counter', 2922);
    var_dump(wincache_ucache_cas('counter', 2922, 1));
    var_dump(wincache_ucache_get('counter'));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    int(1)

### Voir aussi

- wincache_ucache_inc() - Incrémente la valeur associée à une clé
- wincache_ucache_dec() - Décrémente la valeur associée à une clé

# wincache_ucache_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clear — Supprime le contenu d'une entrée du cache utilisateur

### Description

function wincache_ucache_clear(): bool

Supprime toutes les valeurs stockées dans le cache utilisateur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec wincache_ucache_clear()

    <?php
    wincache_ucache_set('green', 1);
    wincache_ucache_set('red', 2);
    wincache_ucache_set('orange', 4);
    wincache_ucache_set('blue', 8);
    wincache_ucache_set('cyan', 16);
    $array1 = array('green', 'red', 'orange', 'blue', 'cyan');
    var_dump(wincache_ucache_get($array1));
    var_dump(wincache_ucache_clear());
    var_dump(wincache_ucache_get($array1));
    ?>

L'exemple ci-dessus va afficher :

    array(5) { ["green"]=> int(1)
               ["red"]=> int(2)
               ["orange"]=> int(4)
               ["blue"]=> int(8)
               ["cyan"]=> int(16) }
    bool(true)
    bool(false)

### Voir aussi

- wincache_ucache_set() - Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache
- wincache_ucache_add() - Ajoute une nouvelle variable au cache utilisateur
- wincache_ucache_delete() - Supprime les variables du cache utilisateur
- wincache_ucache_get() - Récupère une variable stockée dans le cache utilisateur
- wincache_ucache_exists() - Vérifie si une variable existe dans le cache utilisateur
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur

# wincache_ucache_dec

(PECL wincache >= 1.1.0)

wincache_ucache_dec — Décrémente la valeur associée à une clé

### Description

function wincache_ucache_dec(string `$key`, int `$dec_by` = 1, bool `&$success` = ?): mixed

Décrémente de 1 ou `dec_by` de la valeur associée avec la clé `key`.

### Liste de paramètres

`key`

  La clé `key` utilisée pour stocker la variable dans le cache. Le paramètre `key` est sensible à la casse.

`dec_by`

  La valeur utilisée pour décrémenter la variable associée à la clé `key`. Si l'argument est un nombre à virgule flottante, il sera arrondi à l'entier le plus proche. La variable associée avec la clé `key` doit être de type `long`, sinon, la fonction retournera `false`.

`success`

  Sera définie à `true` en cas de succès, `false` si une erreur survient.

### Valeurs de retour

Retourne la valeur décrémentée en cas de succès, `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec wincache_ucache_dec()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_dec('counter', 2923, $success));
    var_dump($success);
    ?>

L'exemple ci-dessus va afficher :

    int(2922)
    bool(true)

### Voir aussi

- wincache_ucache_inc() - Incrémente la valeur associée à une clé
- wincache_ucache_cas() - Compare la variable avec son ancienne valeur et lui assigne une nouvelle valeur

# wincache_ucache_delete

(PECL wincache >= 1.1.0)

wincache_ucache_delete — Supprime les variables du cache utilisateur

### Description

function wincache_ucache_delete(mixed `$key`): bool

Supprime les éléments pointés par la clé `key` du cache utilisateur.

### Liste de paramètres

`key`

  La clé `key` utilisée pour stocker la variable dans le cache. Le paramètre `key` est sensible à la casse. `key` peut être un tableau de clés.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Si le paramètre `key` est un tableau, alors la fonction retournera `false` si un des éléments du tableau n'a pu être supprimé du cache utilisateur, sinon, elle retournera un tableau contenant toutes les clés ayant été supprimées avec succès.

### Exemples

Exemple #1 Exemple avec wincache_ucache_delete() et le paramètre `key` sous forme de chaîne de caractères

    <?php
    wincache_ucache_set('foo', 'bar');
    var_dump(wincache_ucache_delete('foo'));
    var_dump(wincache_ucache_exists('foo'));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)

Exemple #2 Exemple avec wincache_ucache_delete() et le paramètre `key` sous forme d'un tableau

    <?php
    $array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('green', 'blue', 'yellow', 'cyan');
    var_dump(wincache_ucache_delete($array2));
    ?>

L'exemple ci-dessus va afficher :

    array(4) { [0]=> string(5) "green"
               [1]=> string(4) "blue"
               [2]=> string(6) "yellow"
               [3]=> string(4) "cyan" }

Exemple #3 Exemple avec wincache_ucache_delete() et le paramètre `key` sous la forme d'un tableau où quelques éléments n'ont pas pu être supprimés

    <?php
    $array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('orange', 'red', 'yellow', 'cyan');
    var_dump(wincache_ucache_delete($array2));
    ?>

L'exemple ci-dessus va afficher :

    array(2) { [0]=> string(6) "yellow"
               [1]=> string(4) "cyan" }

### Voir aussi

- wincache_ucache_set() - Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache
- wincache_ucache_add() - Ajoute une nouvelle variable au cache utilisateur
- wincache_ucache_get() - Récupère une variable stockée dans le cache utilisateur
- wincache_ucache_clear() - Supprime le contenu d'une entrée du cache utilisateur
- wincache_ucache_exists() - Vérifie si une variable existe dans le cache utilisateur
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur

# wincache_ucache_exists

(PECL wincache >= 1.1.0)

wincache_ucache_exists — Vérifie si une variable existe dans le cache utilisateur

### Description

function wincache_ucache_exists(string `$key`): bool

Vérifie si une variable dont la clé est `key` existe ou non dans le cache utilisateur.

### Liste de paramètres

`key`

  La clé `key` utilisée pour stocker la variable dans le cache. Le paramètre `key` est sensible à la casse.

### Valeurs de retour

Retourne `true` si la variable dont la clé est `key` existe, `false` sinon.

### Exemples

Exemple #1 Exemple avec wincache_ucache_exists()

    <?php
    if (!wincache_ucache_exists('green'))
        wincache_ucache_set('green', 1);
    var_dump(wincache_ucache_exists('green'));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- wincache_ucache_set() - Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache
- wincache_ucache_add() - Ajoute une nouvelle variable au cache utilisateur
- wincache_ucache_get() - Récupère une variable stockée dans le cache utilisateur
- wincache_ucache_clear() - Supprime le contenu d'une entrée du cache utilisateur
- wincache_ucache_delete() - Supprime les variables du cache utilisateur
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur

# wincache_ucache_get

(PECL wincache >= 1.1.0)

wincache_ucache_get — Récupère une variable stockée dans le cache utilisateur

### Description

function wincache_ucache_get(mixed `$key`, bool `&$success` = ?): mixed

Récupère une variable stockée dans le cache utilisateur.

### Liste de paramètres

`key`

  La clé `key` utilisée pour stocker la variable dans le cache. Le paramètre `key` est sensible à la casse. `key` peut être un tableau de clés. Dans ce cas, la valeur retournée sera un tableau de valeurs de chaque élément du tableau `key`. Si un objet ou un tableau contenant des objets est retourné, alors les objets seront désérialisés. Se reporter à la fonction __wakeup() pour plus de détails sur la désérialisation des objets.

`success`

  Sera définie à `true` en cas de succès, `false` si une erreur survient.

### Valeurs de retour

Si le paramètre `key` est une chaîne de caractères, la fonction retournera la valeur de la variable stockée avec cette clé. Le paramètre `success` sera défini à `true` en cas de succès, et à `false` si une erreur survient.

Si le paramètre `key` est un tableau, le paramètre `success` sera toujours défini à `true`. Le tableau retourné (paires de nom => valeur) contiendra uniquement les paires nom => valeur pour lesquelles la récupération depuis le cache utilisateur a été un succès. Si aucune des clés du tableau ne correspond à des entrées du cache utilisateur, un tableau vide sera retourné.

### Exemples

Exemple #1 Exemple avec wincache_ucache_get() et le paramètre `key` sous forme de chaîne de caractères

    <?php
    wincache_ucache_add('color', 'blue');
    var_dump(wincache_ucache_get('color', $success));
    var_dump($success);
    ?>

L'exemple ci-dessus va afficher :

    string(4) "blue"
    bool(true)

Exemple #2 Exemple avec wincache_ucache_get() et le paramètre `key` sous forme d'un tableau

    <?php
    $array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('green', 'Blue', 'yellow', 'cyan');
    var_dump(wincache_ucache_get($array2, $success));
    var_dump($success);
    ?>

L'exemple ci-dessus va afficher :

    array(4) { ["green"]=> string(1) "5"
               ["Blue"]=> string(1) "6"
               ["yellow"]=> string(1) "7"
               ["cyan"]=> string(1) "8" }
    bool(true)

### Voir aussi

- wincache_ucache_add() - Ajoute une nouvelle variable au cache utilisateur
- wincache_ucache_set() - Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache
- wincache_ucache_delete() - Supprime les variables du cache utilisateur
- wincache_ucache_clear() - Supprime le contenu d'une entrée du cache utilisateur
- wincache_ucache_exists() - Vérifie si une variable existe dans le cache utilisateur
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- __wakeup()

# wincache_ucache_inc

(PECL wincache >= 1.1.0)

wincache_ucache_inc — Incrémente la valeur associée à une clé

### Description

function wincache_ucache_inc(string `$key`, int `$inc_by` = 1, bool `&$success` = ?): mixed

Incrémente, de 1 ou de la valeur du paramètre `inc_by`, la valeur associée avec la clé `key`.

### Liste de paramètres

`key`

  La clé `key` utilisée pour stocker la variable dans le cache. Le paramètre `key` est sensible à la casse.

`inc_by`

  La valeur utilisée pour incrémenter la variable associée à la clé `key`. Si l'argument est un nombre à virgule flottante, elle sera arrondie à l'entier le plus proche. La variable associée à la clé `key` doit être de type `long`, sinon la fonction échouera et retournera `false`.

`success`

  Sera défini à `true` en cas de succès, `false` si une erreur survient.

### Valeurs de retour

Retourne la valeur incrémentée en cas de succès, `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec wincache_ucache_inc()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_inc('counter', 2921, $success));
    var_dump($success);
    ?>

L'exemple ci-dessus va afficher :

    int(2922)
    bool(true)

### Voir aussi

- wincache_ucache_dec() - Décrémente la valeur associée à une clé
- wincache_ucache_cas() - Compare la variable avec son ancienne valeur et lui assigne une nouvelle valeur

# wincache_ucache_info

(PECL wincache >= 1.1.0)

wincache_ucache_info — Récupère des informations sur des données stockées dans le cache utilisateur

### Description

function wincache_ucache_info(bool `$summaryonly` = `false`, string `$key` = NULL): array|false

Récupère des informations sur des données stockées dans le cache utilisateur.

### Liste de paramètres

`summaryonly`

  Contrôle si le tableau résultant doit contenir les informations sur des entrées individuelles en plus du résumé du cache utilisateur.

`key`

  La clé de l'entrée du cache utilisateur. Si spécifiée, alors le tableau résultant contiendra des informations uniquement sur cette entrée du cache. Si non spécifiée, et le paramètre `summaryonly` est défini à `false`, alors le tableau résultant contiendra des informations sur toutes les entrées du cache.

### Valeurs de retour

Un tableau de données méta sur le cache utilisateur ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants :

- `total_cache_uptime` - durée, en secondes, depuis l'activation de ce cache utilisateur
- `total_item_count` - nombre total d'éléments contenus dans le cache utilisateur
- `is_local_cache` - `true` si les données méta du cache sont pour une instance locale du cache, `false` si elles sont pour le cache global
- `total_hit_count` - nombre de fois que les données ont été servies depuis le cache
- `total_miss_count` - nombre de fois que les données n'ont pu être trouvées dans le cache

- `ucache_entries` - un tableau contenant les informations sur les éléments mis en cache :

  - `key_name` - nom de la clé utilisée pour stocker les données
  - `value_type` - type de valeur stockée pour cette clé
  - `use_time` - durée, en secondes, depuis laquelle le fichier a été accédé dans le cache opcode
  - `last_check` - durée, en secondes, depuis laquelle le fichier a été vérifié pour y détecter les modifications
  - `is_session` - indique si la donnée est une variable de session
  - `ttl_seconds` - durée de vie de la donnée dans le cache ; 0 signifie indéfiniment
  - `age_seconds` - durée depuis laquelle la donnée a été ajoutée dans le cache
  - `hitcount` - nombre de fois que la donnée a été servie depuis le cache

### Exemples

Exemple #1 Exemple avec wincache_ucache_info()

    <?php
    wincache_ucache_get('green');
    wincache_ucache_set('green', 2922);
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    print_r(wincache_ucache_info());
    ?>

L'exemple ci-dessus va afficher :

    Array
    ( ["total_cache_uptime"] => int(0)
      ["is_local_cache"] => bool(false)
      ["total_item_count"] => int(1)
      ["total_hit_count"] => int(3)
      ["total_miss_count"] => int(1)
      ["ucache_entries"] => Array(1)
        ( [1] => Array(6)
          (
            ["key_name"] => string(5) "green"
            ["value_type"] => string(4) "long"
            ["is_session"] => int(0)
            ["ttl_seconds"] => int(0)
            ["age_seconds"] => int(0)
            ["hitcount"] => int(3)
           )
        )
    )

### Voir aussi

- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_ocache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_ocache_meminfo() - Extrait des informations sur l'utilisation du cache opcode
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache
- wincache_scache_meminfo() - Récupère des informations sur l'utilisation de la mémoire du cache

# wincache_ucache_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfo — Récupère des informations sur l'utilisation mémoire du cache utilisateur

### Description

function wincache_ucache_meminfo(): array|false

Récupère des informations sur l'utilisation mémoire du cache utilisateur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Tableau de données méta sur l'utilisation mémoire du cache utilisateur ou `false` si une erreur survient

Le tableau retourné par cette fonction contient les éléments suivants :

- `memory_total` - quantité de mémoire, en octets, allouée au cache utilisateur
- `memory_free` - quantité de mémoire libre, en octets, disponible pour le cache utilisateur
- `num_used_blks` - nombre de blocs mémoire utilisés par le cache utilisateur
- `num_free_blks` - nombre de blocs mémoire libres disponible depuis le cache utilisateur
- `memory_overhead` - quantité de mémoire, en octets, utilisé pour la structure interne du cache utilisateur

### Exemples

Exemple #1 Exemple avec wincache_ucache_meminfo()

    <pre>
    <?php
    print_r(wincache_ucache_meminfo());
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Voir aussi

- wincache_fcache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_fcache_meminfo() - Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_ocache_fileinfo() - Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_rplist_fileinfo() - Récupère des informations du cache sur un chemin de fichier résolu
- wincache_rplist_meminfo() - Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_refresh_if_changed() - Actualise les entrées du cache pour les fichiers mis en cache
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache
- wincache_scache_meminfo() - Récupère des informations sur l'utilisation de la mémoire du cache

# wincache_ucache_set

(PECL wincache >= 1.1.0)

wincache_ucache_set — Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache

### Description

function wincache_ucache_set(mixed `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_set(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Ajoute une variable au cache utilisateur. Écrase une variable si elle existe déjà dans le cache. La variable ainsi créée ou mise à jour restera dans le cache utilisateur tant que le délai d'expiration n'est pas atteint ou tant qu'elle n'est pas supprimée avec la fonction wincache_ucache_delete() ou la fonction wincache_ucache_clear().

### Liste de paramètres

`key`

  Stocke la variable en utilisant la clé `key`. Si une variable utilisant la même clé `key` est déjà présente, la fonction écrasera la précédente valeur avec la nouvelle. Le paramètre `key` est sensible à la casse. `key` peut également être un tableau de paires nom => valeur où les noms seront utilisés comme clés. Ceci peut être utile pour ajouter plusieurs valeurs dans le cache en une seule opération.

`value`

  Valeur de la variable à stocker. Le paramètre `Value` supporte tous les types de données, sauf les ressources, comme les pointeurs de fichiers. Ce paramètre est ignoré si le premier argument est un tableau. Il est de convention de passer la valeur `null` comme valeur du paramètre `value` lors de l'utilisation d'un tableau dans le paramètre `key`. Si le paramètre `value` est un objet, ou un tableau contenant des objets, alors tous les objets seront sérialisés. Se reporter à la fonction __sleep() pour plus de détails sur la sérialisation d'objets.

`values`

  Tableau associatif de clés et de valeurs.

`ttl`

  Durée de vie de la variable dans le cache, en secondes. Après la durée spécifiée par le paramètre `ttl`, la variable stockée sera effacée du cache utilisateur. Ce paramètre prend par défaut la valeur zéro (`0`), ce qui signifie que la variable restera dans le cache tant qu'elle ne sera pas explicitement supprimée en appelant la fonction wincache_ucache_delete() ou la fonction wincache_ucache_clear().

### Valeurs de retour

Si `key` est une chaîne de caractères, la fonction retournera `true` en cas de succès, `false` si une erreur survient.

Si `key` est un tableau, la fonction retournera :

- Si toutes les paires nom => valeur du tableau ont pu être définies, la fonction retournera un tableau vide.
- Si toutes les paires nom => valeur du tableau n'ont pu être définies, la fonction retournera `false`.
- Si quelques paires ont été définies, et d'autres non, la fonction retournera un tableau de paires nom => valeur qui n'ont pas pu être définies dans le cache utilisateur.

### Exemples

Exemple #1 Exemple avec wincache_ucache_set() et le paramètre `key` sous forme de chaîne de caractères

    <?php
    $bar = 'BAR';
    var_dump(wincache_ucache_set('foo', $bar));
    var_dump(wincache_ucache_get('foo'));
    $bar1 = 'BAR1';
    var_dump(wincache_ucache_set('foo', $bar1));
    var_dump(wincache_ucache_get('foo'));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    string(3) "BAR"
    bool(true)
    string(3) "BAR1"

Exemple #2 Exemple avec wincache_ucache_set() et le paramètre `key` sous forme de tableau

    <?php
    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_get('Blue'));
    ?>

L'exemple ci-dessus va afficher :

    array(0) {}
    array(0) {}
    string(1) "6"

### Voir aussi

- wincache_ucache_add() - Ajoute une nouvelle variable au cache utilisateur
- wincache_ucache_get() - Récupère une variable stockée dans le cache utilisateur
- wincache_ucache_delete() - Supprime les variables du cache utilisateur
- wincache_ucache_clear() - Supprime le contenu d'une entrée du cache utilisateur
- wincache_ucache_exists() - Vérifie si une variable existe dans le cache utilisateur
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- __sleep()

# wincache_unlock

(PECL wincache >= 1.1.0)

wincache_unlock — Libère un verrou exclusif sur une clé donnée

### Description

function wincache_unlock(string `$key`): bool

Libère un verrou exclusif qui a été obtenu sur une clé donnée en utilisant la fonction wincache_lock(). Si un autre processus est en attente de ce verrou, pour cette clé, il obtiendra le verrou.

Avertissement

L'utilisation des fonctions wincache_lock() et wincache_unlock() peut provoquer des verrous morts lors de l'exécution de scripts PHP dans un environnement multiprocessus comme FastCGI. Il ne faut pas utiliser ces fonctions à moins d'être sûr d'en avoir besoin. Pour la majorité des opérations sur le cache utilisateur, il n'est pas nécessaire de les utiliser.

### Liste de paramètres

`key`

  Nom de la clé du cache pour laquelle le verrou doit être libéré.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec wincache_unlock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // Pose d'un verrou exclusif
        ftruncate($fp, 0); // on vide le fichier
        fwrite($fp, "On écrit quelque chose ici\n");
        wincache_unlock(“lock_txt_lock”); // On libère le verrou
    } else {
        echo "Impossible d'obtenir le verrou !";
    }
    fclose($fp);
    ?>

### Voir aussi

- wincache_lock() - Acquière un verrou exclusif sur une clé donnée
- wincache_ucache_set() - Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache
- wincache_ucache_get() - Récupère une variable stockée dans le cache utilisateur
- wincache_ucache_delete() - Supprime les variables du cache utilisateur
- wincache_ucache_clear() - Supprime le contenu d'une entrée du cache utilisateur
- wincache_ucache_exists() - Vérifie si une variable existe dans le cache utilisateur
- wincache_ucache_meminfo() - Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_info() - Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_scache_info() - Récupère des informations sur des fichiers mis en cache

## Sommaire

- wincache_fcache_fileinfo — Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
- wincache_fcache_meminfo — Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
- wincache_lock — Acquière un verrou exclusif sur une clé donnée
- wincache_ocache_fileinfo — Extrait des informations sur les fichiers mis en cache dans le cache opcode
- wincache_ocache_meminfo — Extrait des informations sur l'utilisation du cache opcode
- wincache_refresh_if_changed — Actualise les entrées du cache pour les fichiers mis en cache
- wincache_rplist_fileinfo — Récupère des informations du cache sur un chemin de fichier résolu
- wincache_rplist_meminfo — Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
- wincache_scache_info — Récupère des informations sur des fichiers mis en cache
- wincache_scache_meminfo — Récupère des informations sur l'utilisation de la mémoire du cache
- wincache_ucache_add — Ajoute une nouvelle variable au cache utilisateur
- wincache_ucache_cas — Compare la variable avec son ancienne valeur et lui assigne une nouvelle valeur
- wincache_ucache_clear — Supprime le contenu d'une entrée du cache utilisateur
- wincache_ucache_dec — Décrémente la valeur associée à une clé
- wincache_ucache_delete — Supprime les variables du cache utilisateur
- wincache_ucache_exists — Vérifie si une variable existe dans le cache utilisateur
- wincache_ucache_get — Récupère une variable stockée dans le cache utilisateur
- wincache_ucache_inc — Incrémente la valeur associée à une clé
- wincache_ucache_info — Récupère des informations sur des données stockées dans le cache utilisateur
- wincache_ucache_meminfo — Récupère des informations sur l'utilisation mémoire du cache utilisateur
- wincache_ucache_set — Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache
- wincache_unlock — Libère un verrou exclusif sur une clé donnée

# Compilation sous Windows

## Sommaire

- Prérequis
- Compiler et construire
- Vérifier la construction

## Prérequis

Pour compiler l'extension WinCache, il faudra:

1. le code source de PHP
2. un environnement de compilation PHP
3. le code source de WinCache

Pour compléter les deux premières étapes, suivez le guide étape par étape » Compiler PHP sous Windows.

Pour obtenir le code source de WinCache, suivez les instructions décrites dans Télécharger des extensions PECL.

## Compiler et construire

Les étapes suivantes décrivent comment compiler et construire WinCache sous Windows:

1. Ouvrez une invite de commande utilisée pour compiler PHP

2. Allez dans le dossier racine où les sources de PHP sont présentes

3. Lancez la commande :

       cscript.exe win32\build\buildconf.js

4. Lancez la commande :

       configure.bat --help

   La sortie contiendra une nouvelle option `--enable-wincache`.

5. Lancez la commande :

       configure.js [all options used to build PHP] --enable-wincache

   `--enable-wincache` est la seule option supplémentaire requise pour s'assurer que l'extension WinCache se compile correctement. Cette option permet de construire WinCache et le lier statiquement avec la DLL de PHP. Pour construire l'extension comme une DLL externe, utiliser l'option `--enable-wincache=shared`.

6. Lancez la commande :

       nmake

## Vérifier la construction

Les étapes suivantes décrivent comment vérifier que WinCache a été construit correctement :

1. Allez dans le dossier où les fichiers PHP sont construits.

2. Lancez la commande :

       php.exe -n -d extension=php_wincache.dll -re wincache

   Si WinCache a été construit correctement, la sortie de cette commande listera les directives INI et les fonctions supportées par WinCache.

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Script de statistiques WinCache
  - WinCache Session Handler
  - WinCache Functions Reroutes
- Fonctions WinCache
  - wincache_fcache_fileinfo — Extrait des informations sur les fichiers mis en cache dans le cache de fichiers
  - wincache_fcache_meminfo — Extrait des informations sur l'utilisation de la mémoire du cache de fichiers.
  - wincache_lock — Acquière un verrou exclusif sur une clé donnée
  - wincache_ocache_fileinfo — Extrait des informations sur les fichiers mis en cache dans le cache opcode
  - wincache_ocache_meminfo — Extrait des informations sur l'utilisation du cache opcode
  - wincache_refresh_if_changed — Actualise les entrées du cache pour les fichiers mis en cache
  - wincache_rplist_fileinfo — Récupère des informations du cache sur un chemin de fichier résolu
  - wincache_rplist_meminfo — Récupère des informations sur l'utilisation de la mémoire par le cache de chemin de fichier résolu
  - wincache_scache_info — Récupère des informations sur des fichiers mis en cache
  - wincache_scache_meminfo — Récupère des informations sur l'utilisation de la mémoire du cache
  - wincache_ucache_add — Ajoute une nouvelle variable au cache utilisateur
  - wincache_ucache_cas — Compare la variable avec son ancienne valeur et lui assigne une nouvelle valeur
  - wincache_ucache_clear — Supprime le contenu d'une entrée du cache utilisateur
  - wincache_ucache_dec — Décrémente la valeur associée à une clé
  - wincache_ucache_delete — Supprime les variables du cache utilisateur
  - wincache_ucache_exists — Vérifie si une variable existe dans le cache utilisateur
  - wincache_ucache_get — Récupère une variable stockée dans le cache utilisateur
  - wincache_ucache_inc — Incrémente la valeur associée à une clé
  - wincache_ucache_info — Récupère des informations sur des données stockées dans le cache utilisateur
  - wincache_ucache_meminfo — Récupère des informations sur l'utilisation mémoire du cache utilisateur
  - wincache_ucache_set — Ajoute une variable au cache utilisateur et écrase la variable si elle existe déjà dans le cache
  - wincache_unlock — Libère un verrou exclusif sur une clé donnée
- Compilation sous Windows
  - Prérequis
  - Compiler et construire
  - Vérifier la construction

# Profilage hiérarchique

# Introduction

XHProf est un profileur hiérarchique et instrumental léger. Lors de la phase de collecte de données, il garde trace des nombres d'appels et des métriques inclusives pour les arcs dans le graphique dynamique d'appels d'un programme. Il calcule des métriques exclusives lors de la phase de rapport/envoi, comme la durée accumulée, le temps CPU, ainsi que l'utilisation de mémoire. Un profil de fonction peut être décomposé par fonctions appelantes ou appelées. XHProf gère les fonctions récursives en détectant les cycles dans le graphique d'appels lors de la collecte des données, et évite les cycles en donnant des noms uniques dépendant de la profondeur lors des invocations récursives.

XHProf inclut une interface utilisateur HTML simple (écrite en PHP). Le navigateur web permet ainsi de consulter le résultat du profilage de façon simple, ainsi que de partager les résultats. Une image du graphique d'appels est également fournie.

Les rapports XHProf peuvent souvent être utiles pour comprendre la structure du code exécuté. La nature hiérarchique des rapports peut être utilisée pour déterminer, par exemple, la chaîne d'appels ayant conduit à l'appel d'une fonction particulière.

XHProf permet de comparer deux exécutions (i.e. rapports différentiels) ou d'agréger des données issues de plusieurs exécutions. Les rapports différentiels et agrégés, tout comme les rapports d'exécution unique, offrent une vue plate ainsi qu'une vue hiérarchique du profilage.

Il est possible de trouver plus d'informations sur la page » facebook de xhprof.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

Bien qu'elle ne soit pas requise, xhprof inclut une interface écrite en PHP. Elle est utilisée pour sauvegarder et afficher les données de profilage de manière exploitable, où la lecture s'effectue directement via un navigateur web. Ainsi, un serveur web PHP rendra probablement l'utilisation de xhprof plus conviviale.

Il existe également un fork de l'interface GUI sur » http://github.com/preinheimer/xhprof

## Installation

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/xhprof

## Configuration à l'exécution

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

Options de configuration Xhprof
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
xhprof.output_dir | "" | `INI_ALL` |

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

`xhprof.output_dir` string

  Dossier utilisé par l'implémentation par défaut de l'interface iXHProfRuns (nommément, la classe XHProfRuns_Default) pour stocker les exécutions de XHProf.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`XHPROF_FLAGS_NO_BUILTINS` (int)
  Utilisée pour ne pas tenir compte de toutes les fonctions internes.
`XHPROF_FLAGS_CPU` (int)
  Utilisée pour ajouter les informations de profilage CPU dans la sortie.
`XHPROF_FLAGS_MEMORY` (int)
  Utilisée pour ajouter les informations de profilage de la mémoire dans la sortie.

# Exemples

Exemple #1 Exemple avec Xhprof et la GUI optionnelle

Cet exemple démarre et stoppe le profilage, puis utilise l'interface GUI fournie pour sauvegarder et analyser les résultats. En d'autres termes, le code de l'extension en elle-même s'arrête après l'appel à la fonction xhprof_disable().

    <?php
    xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);

    for ($i = 0; $i <= 1000; $i++) {
        $a = $i * $i;
    }

    $xhprof_data = xhprof_disable();

    $XHPROF_ROOT = "/tools/xhprof/";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_lib.php";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_runs.php";

    $xhprof_runs = new XHProfRuns_Default();
    $run_id = $xhprof_runs->save_run($xhprof_data, "xhprof_testing");

    echo "http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing

# Fonctions Xhprof

# xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disable — Stoppe le profilage xhprof

### Description

function xhprof_disable(): ?array

Stoppe le profilage, et retourne les données xhprof correspondant à son exécution.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de données xhprof, issues de son exécution. Retourne `null` si le profilage n’est pas activé.

### Exemples

Exemple #1 Exemple avec xhprof_disable()

    <?php
    xhprof_enable();

    $foo = strlen("foo bar");

    $xhprof_data = xhprof_disable();

    print_r($xhprof_data);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [main()==>strlen] => Array
            (
                [ct] => 1
                [wt] => 279
            )

        [main()==>xhprof_disable] => Array
            (
                [ct] => 1
                [wt] => 9
            )

        [main()] => Array
            (
                [ct] => 1
                [wt] => 610
            )

    )

# xhprof_enable

(PECL xhprof >= 0.9.0)

xhprof_enable — Démarre le profilage xhprof

### Description

function xhprof_enable(int `$flags` = 0, array `$options` = ?): void

Démarre le profilage xhprof.

### Liste de paramètres

`flags`

  Drapeaux optionnels pour ajouter des informations supplémentaires au profilage. Voir les constantes XHprof pour plus d'informations sur ces drapeaux, comme `XHPROF_FLAGS_MEMORY` pour activer le profilage de la mémoire.

`options`

  Un tableau d'options optionnelles, par exemple l'option 'ignored_functions' pour spécifier des fonctions à ignorer durant le profilage.

### Valeurs de retour

`null`

### Historique

Version | Description
--- | ---
PECL xhprof 0.9.2 | Le paramètre optionnel `options` a été ajouté.

### Exemples

Exemple #1 Exemple avec xhprof_enable()

    <?php
    // 1. profilage du temps écoulé + mémoire + CPU ; et on ignore les fonctions internes
    xhprof_enable(XHPROF_FLAGS_NO_BUILTINS | XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);

    // 2. profilage du temps écoulé ; on ignore les fonctions call_user_func* lors du profilage
    xhprof_enable(
        0,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));

    // 3. profilage du temps écoulé ainsi que de la mémoire ; on ignore les fonctions call_user_func* lors du profilage
    xhprof_enable(
        XHPROF_FLAGS_MEMORY,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));
    ?>

### Voir aussi

- xhprof_disable() - Stoppe le profilage xhprof
- xhprof_sample_enable() - Démarre le profilage en mode échantillonnage
- memory_get_usage() - Indique la quantité de mémoire utilisée par PHP
- getrusage() - Retourne le niveau d'utilisation des ressources

# xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — Stoppe le profilage xhprof sur échantillon

### Description

function xhprof_sample_disable(): ?array

Stoppe le profilage xhprof sur échantillon et retourne les informations de profilage.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de données de l'échantillon xhprof, issues de son exécution. Retourne `null` si le profilage n’est pas activé.

### Exemples

Exemple #1 Exemple avec xhprof_sample_disable()

    <?php
    xhprof_sample_enable();

    for ($i = 0; $i <= 10000; $i++) {
        $a = strlen($i);
        $b = $i * $a;
        $c = rand();
    }

    $xhprof_data = xhprof_sample_disable();

    print_r($xhprof_data);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [1272935300.800000] => main()
        [1272935300.900000] => main()
    )

# xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — Démarre le profilage en mode échantillonnage

### Description

function xhprof_sample_enable(): void

Démarre le profilage en mode échantillonnage, ce qui correspond à une version plus légère de la fonction xhprof_enable(). L'intervalle d'échantillonnage est de 0.1 seconde, et les échantillons enregistrent la pile complète des fonctions appelées. La principale utilité de cette fonction est lorsque l'on souhaite diagnostiquer et surveiller les performances sans pour autant consommer trop de ressources.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`null`

### Voir aussi

- xhprof_sample_disable() - Stoppe le profilage xhprof sur échantillon
- xhprof_enable() - Démarre le profilage xhprof
- memory_get_usage() - Indique la quantité de mémoire utilisée par PHP
- getrusage() - Retourne le niveau d'utilisation des ressources

## Sommaire

- xhprof_disable — Stoppe le profilage xhprof
- xhprof_enable — Démarre le profilage xhprof
- xhprof_sample_disable — Stoppe le profilage xhprof sur échantillon
- xhprof_sample_enable — Démarre le profilage en mode échantillonnage

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Exemples
- Fonctions Xhprof
  - xhprof_disable — Stoppe le profilage xhprof
  - xhprof_enable — Démarre le profilage xhprof
  - xhprof_sample_disable — Stoppe le profilage xhprof sur échantillon
  - xhprof_sample_enable — Démarre le profilage en mode échantillonnage

# Yac

# Introduction

Yac (Yet Another cache), est un cache de données utilisateur en mémoire partagée, sans verrou, pouvant être utilisé pour remplacer APC.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/yac.

Les binaires Windows (les fichiers DLL) pour cette extension PECL sont disponibles sur le site web PECL.

## Configuration à l'exécution

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

Options de configuration Yac
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
yac.compress_threshold | -1 | `INI_SYSTEM` |
yac.debug | 0 | `INI_ALL` |
yac.enable | 1 | `INI_SYSTEM` |
yac.enable_cli | 0 | `INI_SYSTEM` |
yac.keys_memory_size | 4M | `INI_SYSTEM` |
yac.serializer | php | `INI_SYSTEM` |
yac.values_memory_size | 64M | `INI_SYSTEM` |

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

`yac.compress_threshold` int

`yac.debug` int

`yac.enable` int

`yac.enable_cli` int

`yac.keys_memory_size` string

`yac.serializer` string

`yac.values_memory_size` string

## Types de ressources

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`YAC_VERSION` (string)
`YAC_MAX_KEY_LEN` (int)
  Longueur maximale que la clé peut faire ; 48 octets.
`YAC_MAX_VALUE_RAW_LEN` (int)
`YAC_MAX_RAW_COMPRESSED_LEN` (int)
`YAC_SERIALIZER_PHP` (int)
  Utilise le sérialisateur de PHP comme sérialisateur
`YAC_SERIALIZER_JSON` (int)
  Utilise Json comme sérialisateur (nécessite l'option --enable-json)
`YAC_SERIALIZER_IGBINARY` (int)
  Utilise igbinary comme sérialisateur (nécessite l'option --enable-igbinary)
`YAC_SERIALIZER_MSGPACK` (int)
  Utilise msgpack comme sérialisateur (nécessite l'option --enable-msgpack)
`YAC_SERIALIZER` (string)
  Le sérialisateur que YAC doit utiliser

# La classe Yac

(PECL yac >= 1.0.0)

## Introduction

## Synopsis de la classe

class Yac {
/* Propriétés */
protected $_prefix;
/* Méthodes */
public function __construct(string `$prefix` = "")
public function add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function delete(string|array `$keys`, int `$ttl` = ?): bool
public function dump(int `$$num`): mixed
public function flush(): bool
public function get(string|array `$key`, int `&$cas` = `null`): mixed
public function __get(string `$key`): mixed
public function info(): array
public function set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function __set(string `$keys`, mixed `$value`): mixed
}

## Propriétés

_prefix

# Yac::add

(PECL yac >= 1.0.0)

Yac::add — Stocke un élément dans le cache

### Description

public function Yac::add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Ajoute un élément dans le cache.

### Liste de paramètres

`keys`

  chaîne de caractères ; la clé

`value`

  Tout type de valeur PHP peut être stocké, à l'exception d'une resource.

`ttl`

  Délai d'expiration.

### Valeurs de retour

booléen, `true` en cas de succès, `false` si une erreur survient.

> Note:

> La méthode Yac::add() peut échouer si le verrou ne peut être obtenu, aussi, pour que l'élément soit stocké proprement, il est recommandé d'écrire le code comme ceci :

> Exemple #1 Permet de s'assurer que l'élément est stocké

>     while(!$yac->set("key", "value"));

# Yac::__construct

(PECL yac >= 1.0.0)

Yac::__construct — Constructeur

### Description

public function Yac::__construct(string `$prefix` = "")

Le préfixe est utilisé pour préfixer les clés ; cela permet d'éviter les conflits entre plusieurs applications.

### Liste de paramètres

`prefix`

  chaîne de caractères ; le préfixe

### Erreurs / Exceptions

Lance une Exception si Yac n'est pas activé. Lance une Exception si `prefix` excède la longueur maximale de clé de 48 (`YAC_MAX_KEY_LEN`) octets.

# Yac::delete

(PECL yac >= 1.0.0)

Yac::delete — Supprime un ou plusieurs éléments du cache

### Description

public function Yac::delete(string|array `$keys`, int `$ttl` = ?): bool

Supprime un ou plusieurs éléments du cache.

### Liste de paramètres

`keys`

  La clé ou un tableau de plusieurs clés à supprimer

`ttl`

  Si le délai est défini, l'opération de suppression va marquer les éléments pour qu'ils soient invalides au bout de ttl secondes.

### Valeurs de retour

# Yac::dump

(PECL yac >= 1.0.0)

Yac::dump — Extrait les valeurs du cache

### Description

public function Yac::dump(int `$$num`): mixed

Extrait les valeurs stockées dans le cache

### Liste de paramètres

`num`

  Nombre maximal d'éléments à retourner

### Valeurs de retour

Les éléments extraits.

# Yac::flush

(PECL yac >= 1.0.0)

Yac::flush — Supprime toutes les valeurs mises en cache

### Description

public function Yac::flush(): bool

Supprime toutes les valeurs mises en cache.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une valeur booléenne, toujours `true`.

# Yac::get

(PECL yac >= 1.0.0)

Yac::get — Récupère un élément du cache

### Description

public function Yac::get(string|array `$key`, int `&$cas` = `null`): mixed

Récupère un élément du cache.

### Liste de paramètres

`key`

  chaîne de caractères ; la clé, ou un tableau de plusieurs clés.

`cas`

  Si différent de `null`, ce devra être le cas de l'élément récupéré.

### Valeurs de retour

Le ou les éléments, `false` si une erreur survient.

# Yac::__get

(PECL yac >= 1.0.0)

Yac::__get — Récupère un élément du cache

### Description

public function Yac::__get(string `$key`): mixed

Récupère un élément du cache.

### Liste de paramètres

`key`

  chaîne de caractères ; la clé

### Valeurs de retour

L'élément en cas de succès, `null` si une erreur survient.

# Yac::info

(PECL yac >= 1.0.0)

Yac::info — Statut du cache

### Description

public function Yac::info(): array

Récupère le statut du cache système.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau contenant les éléments suivants : "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used"

# Yac::set

(PECL yac >= 1.0.0)

Yac::set — Stocke une valeur dans le cache

### Description

public function Yac::set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Ajoute un élément dans le cache ; si la clé existe déjà, elle sera écrasée.

### Liste de paramètres

`keys`

  chaîne de caractères ; la clé

`value`

  Tout type de valeur que PHP peut stocker, à l'exception d'une resource.

`ttl`

  Durée d'expiration

### Valeurs de retour

La valeur stockée

# Yac::__set

(PECL yac >= 1.0.0)

Yac::__set — Stocke un élément dans le cache

### Description

public function Yac::__set(string `$keys`, mixed `$value`): mixed

Stocke un élément dans le cache

### Liste de paramètres

`keys`

  chaîne de caractères ; la clé

`value`

  Tout type de valeur PHP peut être stockée, à l'exception d'une resource

### Valeurs de retour

La valeur stockée

## Sommaire

- Yac::add — Stocke un élément dans le cache
- Yac::__construct — Constructeur
- Yac::delete — Supprime un ou plusieurs éléments du cache
- Yac::dump — Extrait les valeurs du cache
- Yac::flush — Supprime toutes les valeurs mises en cache
- Yac::get — Récupère un élément du cache
- Yac::__get — Récupère un élément du cache
- Yac::info — Statut du cache
- Yac::set — Stocke une valeur dans le cache
- Yac::__set — Stocke un élément dans le cache

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Yac — La classe Yac
  - Yac::add — Stocke un élément dans le cache
  - Yac::__construct — Constructeur
  - Yac::delete — Supprime un ou plusieurs éléments du cache
  - Yac::dump — Extrait les valeurs du cache
  - Yac::flush — Supprime toutes les valeurs mises en cache
  - Yac::get — Récupère un élément du cache
  - Yac::__get — Récupère un élément du cache
  - Yac::info — Statut du cache
  - Yac::set — Stocke une valeur dans le cache
  - Yac::__set — Stocke un élément dans le cache

- APCu — APC User Cache
  - Installation/Configuration
  - Constantes pré-définies
  - APCu Fonctions
  - APCUIterator — La classe APCUIterator
- Componere
  - Installation/Configuration
  - Componere\Abstract\Definition — La classe Componere\Abstract\Definition
  - Componere\Definition — La classe Componere\Definition
  - Componere\Patch — La classe Componere\Patch
  - Componere\Method — La classe Componere\Method
  - Componere\Value — La classe Componere\Value
  - Fonctions de Componere
- Gestion des erreurs — Gestion des erreurs et des journaux
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions sur la gestion des erreurs
- FFI — Interface de fonction étrangère (Foreign Function Interface)
  - Installation/Configuration
  - Exemples
  - FFI — Interface principale vers le code C et les données
  - FFI\CData — Gestionnaire de données C
  - FFI\CType — Gestionnaire de type C
  - FFI\Exception — Exceptions FFI
  - FFI\ParserException — Exceptions de l'analyseur syntaxique FFI
- OPcache
  - Installation/Configuration
  - Preloading
  - Fonctions OPcache
- Surcharge d'opérateurs — Surcharge d'opérateurs pour les objets
  - Installation/Configuration
  - Méthodes magiques de surcharge d'opérateurs
- Contrôle de l'affichage — Bufferisation de sortie
  - Installation/Configuration
  - Constantes pré-définies
  - Bufferisation de sortie
  - Laver les tampons système
  - Tampons de sortie au niveau utilisateur
  - Exemples
  - Fonctions de bufferisation de sortie
- Options PHP et informations PHP
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions sur les options et les informations de PHP
- phpdbg — Débogueur PHP interactif
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions phpdbg
- runkit7
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions de runkit7
- uopz — Opérations utilisateurs pour Zend
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Uopz
- WinCache — Windows Cache pour PHP
  - Installation/Configuration
  - Fonctions WinCache
  - Compilation sous Windows
- Xhprof — Profilage hiérarchique
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions Xhprof
- Yac
  - Installation/Configuration
  - Constantes pré-définies
  - Yac — La classe Yac

# Manipulation audio

# Gestion Audio OpenAL

# Introduction

Plate-forme indépendante pour la gestion de l'audio. Requiert la bibliothèque » OpenAL.

# Installation/Configuration

## Sommaire

- Installation
- Types de ressources

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/openal.

Aucune bibliothèque DLL pour cette extension PECL n'est actuellement disponible. Reportez-vous à la section Compilation sous Windows.

## Types de ressources

Cette extension définit quatre types de ressource : Open AL(Device) - Retournée par openal_device_open(), Open AL(Context) - Retournée par openal_context_create(), Open AL(Buffer) - Retournée par openal_buffer_create(), et Open AL(Source) - Retournée par openal_source_create().

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`ALC_FREQUENCY` (int)
  Attribut de contexte
`ALC_REFRESH` (int)
  Attribut de contexte
`ALC_SYNC` (int)
  Attribut de contexte
`AL_FREQUENCY` (int)
  Configuration du buffer
`AL_BITS` (int)
  Configuration du buffer
`AL_CHANNELS` (int)
  Configuration du buffer
`AL_SIZE` (int)
  Configuration du buffer
`AL_BUFFER` (int)
  Configuration de la source/de l'écoute (Entier)
`AL_SOURCE_RELATIVE` (int)
  Configuration de la source/de l'écoute (Entier)
`AL_SOURCE_STATE` (int)
  Configuration de la source/de l'écoute (Entier)
`AL_PITCH` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_GAIN` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_MIN_GAIN` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_MAX_GAIN` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_MAX_DISTANCE` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_ROLLOFF_FACTOR` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_CONE_OUTER_GAIN` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_CONE_INNER_ANGLE` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_CONE_OUTER_ANGLE` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_REFERENCE_DISTANCE` (int)
  Configuration de la source/de l'écoute (Nombre à virgule flottante)
`AL_POSITION` (int)
  Configuration de la source/de l'écoute (Nombre vectoriel à virgule flottante)
`AL_VELOCITY` (int)
  Configuration de la source/de l'écoute (Nombre vectoriel à virgule flottante)
`AL_DIRECTION` (int)
  Configuration de la source/de l'écoute (Nombre vectoriel à virgule flottante)
`AL_ORIENTATION` (int)
  Configuration de la source/de l'écoute (Nombre vectoriel à virgule flottante)
`AL_FORMAT_MONO8` (int)
  Format PCM
`AL_FORMAT_MONO16` (int)
  Format PCM
`AL_FORMAT_STEREO8` (int)
  Format PCM
`AL_FORMAT_STEREO16` (int)
  Format PCM
`AL_INITIAL` (int)
  État de la Source
`AL_PLAYING` (int)
  État de la Source
`AL_PAUSED` (int)
  État de la Source
`AL_STOPPED` (int)
  État de la Source
`AL_LOOPING` (int)
  État de la Source
`AL_TRUE` (int)
  Valeur booléenne reconnue par OpenAL
`AL_FALSE` (int)
  Valeur booléenne reconnue par OpenAL

# Fonctions OpenAL

# openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_create — Génère un buffer OpenAL

### Description

function openal_buffer_create(): resource

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

openal_buffer_create() retourne une ressource Open AL(Buffer) ou `false` en cas d'erreur.

### Voir aussi

- openal_buffer_loadwav() - Charge un fichier .wav dans le buffer
- openal_buffer_data() - Charge un buffer avec des données

# openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_data — Charge un buffer avec des données

### Description

function openal_buffer_data(
resource `$buffer`,
int `$format`,
string `$data`,
int `$freq`
): bool

### Liste de paramètres

`buffer`
  Une ressource Open AL(Buffer) (précédemment créée par openal_buffer_create()).
`format`
  Format du paramètre `data`, un parmi ceux-là : `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` et `AL_FORMAT_STEREO16`.
`data`
  Bloc de données binaires audio dans le format spécifié `format` et `freq`.
`freq`
  Fréquence des données `data`, en Hz.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_buffer_loadwav() - Charge un fichier .wav dans le buffer
- openal_stream() - Démarre le streaming d'une source

# openal_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroy — Détruit un buffer OpenAL

### Description

function openal_buffer_destroy(resource `$buffer`): bool

### Liste de paramètres

`buffer`
  Une ressource Open AL(Buffer) (précédemment créée par openal_buffer_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_buffer_create() - Génère un buffer OpenAL

# openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — Récupère les propriétés du buffer OpenAL

### Description

function openal_buffer_get(resource `$buffer`, int `$property`): int|false

### Liste de paramètres

`buffer`
  Une ressource Open AL(Buffer) (précédemment créée par openal_buffer_create()).
`property`
  Une propriété spécifique, une parmi celles-ci : `AL_FREQUENCY`, `AL_BITS`, `AL_CHANNELS` et `AL_SIZE`.

### Valeurs de retour

Retourne une valeur entière appropriée à la demande `property` ou `false` si une erreur survient.

### Voir aussi

- openal_buffer_create() - Génère un buffer OpenAL

# openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — Charge un fichier .wav dans le buffer

### Description

function openal_buffer_loadwav(resource `$buffer`, string `$wavfile`): bool

### Liste de paramètres

`buffer`
  Une ressource Open AL(Buffer) (précédemment créée par openal_buffer_create()).
`wavfile`
  Chemin vers le fichier .wav sur le système de fichiers local.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_buffer_data() - Charge un buffer avec des données
- openal_stream() - Démarre le streaming d'une source

# openal_context_create

(PECL openal >= 0.1.0)

openal_context_create — Crée un contexte de traitement audio

### Description

function openal_context_create(resource `$device`): resource

### Liste de paramètres

`device`
  Une ressource Open AL(Device) (précédemment créée par openal_device_open()).

### Valeurs de retour

Retourne une ressource Open AL(Context) ou `false` en cas d'erreur.

### Voir aussi

- openal_device_open() - Initialise une interface audio OpenAL
- openal_context_destroy() - Détruit un contexte

# openal_context_current

(PECL openal >= 0.1.0)

openal_context_current — Rend courant le contexte spécifié

### Description

function openal_context_current(resource `$context`): bool

### Liste de paramètres

`context`
  Une ressource Open AL(Context) (précédemment créée par openal_context_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_context_create() - Crée un contexte de traitement audio

# openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — Détruit un contexte

### Description

function openal_context_destroy(resource `$context`): bool

### Liste de paramètres

`context`
  Une ressource Open AL(Context) (précédemment créée par openal_context_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_context_create() - Crée un contexte de traitement audio

# openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — Traite le contexte spécifié

### Description

function openal_context_process(resource `$context`): bool

### Liste de paramètres

`context`
  Une ressource Open AL(Context) (précédemment créée par openal_context_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_context_create() - Crée un contexte de traitement audio
- openal_context_current() - Rend courant le contexte spécifié
- openal_context_suspend() - Suspend le contexte spécifié

# openal_context_suspend

(PECL openal >= 0.1.0)

openal_context_suspend — Suspend le contexte spécifié

### Description

function openal_context_suspend(resource `$context`): bool

### Liste de paramètres

`context`
  Une ressource Open AL(Context) (précédemment créée par openal_context_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_context_create() - Crée un contexte de traitement audio
- openal_context_current() - Rend courant le contexte spécifié
- openal_context_process() - Traite le contexte spécifié

# openal_device_close

(PECL openal >= 0.1.0)

openal_device_close — Ferme un périphérique OpenAL

### Description

function openal_device_close(resource `$device`): bool

### Liste de paramètres

`device`
  Une ressource Open AL(Device) (précédemment créée par openal_device_open()) à fermer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_device_open() - Initialise une interface audio OpenAL

# openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — Initialise une interface audio OpenAL

### Description

function openal_device_open(string `$device_desc` = ?): resource

### Liste de paramètres

`device_desc`
  openal_device_open() ouvre un périphérique audio optionnellement spécifié par le paramètre `device_desc`. Si le paramètre `device_desc` n'est pas spécifié, le premier périphérique audio disponible sera utilisé.

### Valeurs de retour

Retourne une ressource Open AL(Device) ou `false` en cas d'erreur.

### Voir aussi

- openal_device_close() - Ferme un périphérique OpenAL
- openal_context_create() - Crée un contexte de traitement audio

# openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_get — Récupère une propriété d'auditeur

### Description

function openal_listener_get(int `$property`): mixed

### Liste de paramètres

`property`
  La propriété à récupérer, une parmi celles-ci : `AL_GAIN` (nombre décimal), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) et `AL_ORIENTATION` (array(float,float,float)).

### Valeurs de retour

Retourne un nombre décimal ou un tableau de nombres à virgule flottante ou `false` si une erreur survient.

### Voir aussi

- openal_listener_set() - Définit une propriété d'auditeur

# openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_set — Définit une propriété d'auditeur

### Description

function openal_listener_set(int `$property`, mixed `$setting`): bool

### Liste de paramètres

`property`
  La propriété à définir, une parmi celles-ci : `AL_GAIN` (nombre décimal), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) et `AL_ORIENTATION` (array(float,float,float)).
`setting`
  La valeur à définir, soit un nombre décimal, soit un tableau de nombres à virgule flottante appropriés.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_listener_get() - Récupère une propriété d'auditeur

# openal_source_create

(PECL openal >= 0.1.0)

openal_source_create — Génère une ressource de source

### Description

function openal_source_create(): resource

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une ressource Open AL(Source) ou `false` en cas d'erreur.

### Voir aussi

- openal_source_set() - Définit une propriété de la source
- openal_source_play() - Démarre la lecture de la source
- openal_source_destroy() - Détruit une ressource de source

# openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroy — Détruit une ressource de source

### Description

function openal_source_destroy(resource `$source`): bool

### Liste de paramètres

`source`
  Une ressource Open AL(Source) (précédemment créée par openal_source_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_source_create() - Génère une ressource de source

# openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — Récupère une propriété de source OpenAL

### Description

function openal_source_get(resource `$source`, int `$property`): mixed

### Liste de paramètres

`source`
  Une ressource Open AL(Source) (précédemment créée par openal_source_create()).
`property`
  Propriété à récupérer, une parmi celles-ci : `AL_SOURCE_RELATIVE` (entier), `AL_SOURCE_STATE` (entier), `AL_PITCH` (nombre décimal), `AL_GAIN` (nombre décimal), `AL_MIN_GAIN` (nombre décimal), `AL_MAX_GAIN` (nombre décimal), `AL_MAX_DISTANCE` (nombre décimal), `AL_ROLLOFF_FACTOR` (nombre décimal), `AL_CONE_OUTER_GAIN` (nombre décimal), `AL_CONE_INNER_ANGLE` (nombre décimal), `AL_CONE_OUTER_ANGLE` (nombre décimal), `AL_REFERENCE_DISTANCE` (nombre décimal), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).

### Valeurs de retour

Retourne le type associé avec la propriété récupérée ou `false` si une erreur survient.

### Voir aussi

- openal_source_create() - Génère une ressource de source
- openal_source_set() - Définit une propriété de la source
- openal_source_play() - Démarre la lecture de la source

# openal_source_pause

(PECL openal >= 0.1.0)

openal_source_pause — Marque une pause dans la source

### Description

function openal_source_pause(resource `$source`): bool

### Liste de paramètres

`source`
  Une ressource Open AL(Source) (précédemment créée avec openal_source_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_source_stop() - Arrête la lecture de la source
- openal_source_play() - Démarre la lecture de la source
- openal_source_rewind() - Revient en arrière dans la source

# openal_source_play

(PECL openal >= 0.1.0)

openal_source_play — Démarre la lecture de la source

### Description

function openal_source_play(resource `$source`): bool

### Liste de paramètres

`source`
  Une ressource Open AL(Source) (précédemment créée par openal_source_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_source_stop() - Arrête la lecture de la source
- openal_source_pause() - Marque une pause dans la source
- openal_source_rewind() - Revient en arrière dans la source

# openal_source_rewind

(PECL openal >= 0.1.0)

openal_source_rewind — Revient en arrière dans la source

### Description

function openal_source_rewind(resource `$source`): bool

### Liste de paramètres

`source`
  Une ressource Open AL(Source) (précédemment créée par openal_source_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_source_stop() - Arrête la lecture de la source
- openal_source_pause() - Marque une pause dans la source
- openal_source_play() - Démarre la lecture de la source

# openal_source_set

(PECL openal >= 0.1.0)

openal_source_set — Définit une propriété de la source

### Description

function openal_source_set(resource `$source`, int `$property`, mixed `$setting`): bool

### Liste de paramètres

`source`
  Une ressource Open AL(Source) (précédemment créée par openal_source_create()).
`property`
  La propriété à définir, une parmi celles-ci : `AL_BUFFER` (OpenAL(Source)), `AL_LOOPING` (booléen), `AL_SOURCE_RELATIVE` (entier), `AL_SOURCE_STATE` (entier), `AL_PITCH` (nombre décimal), `AL_GAIN` (nombre décimal), `AL_MIN_GAIN` (nombre décimal), `AL_MAX_GAIN` (nombre décimal), `AL_MAX_DISTANCE` (nombre décimal), `AL_ROLLOFF_FACTOR` (nombre décimal), `AL_CONE_OUTER_GAIN` (nombre décimal), `AL_CONE_INNER_ANGLE` (nombre décimal), `AL_CONE_OUTER_ANGLE` (nombre décimal), `AL_REFERENCE_DISTANCE` (nombre décimal), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).
`setting`
  La valeur à assigner à la propriété spécifiée par le paramètre `property`. Se référer à la description de la propriété `property` pour une description des valeurs attendues.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_source_create() - Génère une ressource de source
- openal_source_get() - Récupère une propriété de source OpenAL
- openal_source_play() - Démarre la lecture de la source

# openal_source_stop

(PECL openal >= 0.1.0)

openal_source_stop — Arrête la lecture de la source

### Description

function openal_source_stop(resource `$source`): bool

### Liste de paramètres

`source`
  Une ressource Open AL(Source) (précédemment créée par openal_source_create()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- openal_source_play() - Démarre la lecture de la source
- openal_source_pause() - Marque une pause dans la source
- openal_source_rewind() - Revient en arrière dans la source

# openal_stream

(PECL openal >= 0.1.0)

openal_stream — Démarre le streaming d'une source

### Description

function openal_stream(resource `$source`, int `$format`, int `$rate`): resource|false

### Liste de paramètres

`source`
  Une ressource Open AL(Source) (précédemment créée par openal_source_create()).
`format`
  Le format du paramètre `data`, un parmi ceux-là : `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` et `AL_FORMAT_STEREO16`.
`rate`
  La fréquence des données à streamer, en Hz.

### Valeurs de retour

Retourne une ressource de streaming ou `false` si une erreur survient.

### Voir aussi

- openal_source_create() - Génère une ressource de source
- fwrite() - Écrit un fichier en mode binaire

## Sommaire

- openal_buffer_create — Génère un buffer OpenAL
- openal_buffer_data — Charge un buffer avec des données
- openal_buffer_destroy — Détruit un buffer OpenAL
- openal_buffer_get — Récupère les propriétés du buffer OpenAL
- openal_buffer_loadwav — Charge un fichier .wav dans le buffer
- openal_context_create — Crée un contexte de traitement audio
- openal_context_current — Rend courant le contexte spécifié
- openal_context_destroy — Détruit un contexte
- openal_context_process — Traite le contexte spécifié
- openal_context_suspend — Suspend le contexte spécifié
- openal_device_close — Ferme un périphérique OpenAL
- openal_device_open — Initialise une interface audio OpenAL
- openal_listener_get — Récupère une propriété d'auditeur
- openal_listener_set — Définit une propriété d'auditeur
- openal_source_create — Génère une ressource de source
- openal_source_destroy — Détruit une ressource de source
- openal_source_get — Récupère une propriété de source OpenAL
- openal_source_pause — Marque une pause dans la source
- openal_source_play — Démarre la lecture de la source
- openal_source_rewind — Revient en arrière dans la source
- openal_source_set — Définit une propriété de la source
- openal_source_stop — Arrête la lecture de la source
- openal_stream — Démarre le streaming d'une source

- Installation/Configuration
  - Installation
  - Types de ressources
- Constantes pré-définies
- Fonctions OpenAL
  - openal_buffer_create — Génère un buffer OpenAL
  - openal_buffer_data — Charge un buffer avec des données
  - openal_buffer_destroy — Détruit un buffer OpenAL
  - openal_buffer_get — Récupère les propriétés du buffer OpenAL
  - openal_buffer_loadwav — Charge un fichier .wav dans le buffer
  - openal_context_create — Crée un contexte de traitement audio
  - openal_context_current — Rend courant le contexte spécifié
  - openal_context_destroy — Détruit un contexte
  - openal_context_process — Traite le contexte spécifié
  - openal_context_suspend — Suspend le contexte spécifié
  - openal_device_close — Ferme un périphérique OpenAL
  - openal_device_open — Initialise une interface audio OpenAL
  - openal_listener_get — Récupère une propriété d'auditeur
  - openal_listener_set — Définit une propriété d'auditeur
  - openal_source_create — Génère une ressource de source
  - openal_source_destroy — Détruit une ressource de source
  - openal_source_get — Récupère une propriété de source OpenAL
  - openal_source_pause — Marque une pause dans la source
  - openal_source_play — Démarre la lecture de la source
  - openal_source_rewind — Revient en arrière dans la source
  - openal_source_set — Définit une propriété de la source
  - openal_source_stop — Arrête la lecture de la source
  - openal_stream — Démarre le streaming d'une source

- OpenAL — Gestion Audio OpenAL
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions OpenAL

# Services d'identification

# Radius

# Introduction

Ce paquet est basé sur la bibliothèque libradius (`Remote Authentication Dial In User Service`) de FreeBSD. Il permet aux clients d'effectuer des identifications et de la comptabilité par le biais de requêtes réseau sur des serveurs distants.

Cette extension PECL supporte tout le protocole Radius Authentication complet pour l'authentification (» RFC 2865) et Radius Accounting (» RFC 2866). Ce paquet est disponible pour Unix (testé sous FreeBSD et Linux) mais aussi pour Windows.

> Note: Une description de libradius peut être trouvée » ici. Une description détaillée du fichier de configuration peut être trouvée » ici.

# Installation/Configuration

## Sommaire

- Installation

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/radius.

# Constantes pré-définies

## Sommaire

- RADIUS Options
- Types de paquets RADIUS
- Types d'attribut RADIUS
- Types d'attribut RADIUS spécifique au vendeur

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`RADIUS_MPPE_KEY_LEN` (int)
  La longueur maximale des clés MPPE.

## RADIUS Options

Plusieurs fonctions RADIUS acceptent des options sous forme de masque d'octets. Les constantes représentant ces options sont listées ci-dessous.

`RADIUS_OPTION_SALT` (int)
  Lorsque définie, cette option fera que la valeur de l'attribut sera chiffrée salt.
`RADIUS_OPTION_TAGGED` (int)
  Lorsque définie, cette option fera que la valeur de l'attribut proviendra du paramètre tag.

## Types de paquets RADIUS

Les paquets RADIUS, qu'ils soient demandés ou obtenus en réponse, incluent toujours un type. Cette constante est fournie pour rendre plus simple la spécification d'un type lors de l'utilisation de la fonction radius_create_request(), et lors d'une comparaison du résultat avec la fonction radius_send_request().

`RADIUS_ACCESS_REQUEST` (int)
  Un Access-Request, utilisé pour authentifier un utilisateur sur un serveur RADIUS. Les paquets Access-Request doivent inclure un attribut `RADIUS_NAS_IP_ADDRESS`, ou un attribut `RADIUS_NAS_IDENTIFIER` mais aussi inclure un attribut `RADIUS_USER_PASSWORD`, et un attribut `RADIUS_CHAP_PASSWORD` ou bien un attribut `RADIUS_STATE`, et doivent inclure un attribut `RADIUS_USER_NAME`.
`RADIUS_ACCESS_ACCEPT` (int)
  Une réponse Access-Accept à un paquet Access-Request indique que le serveur RADIUS a authentifié l'utilisateur avec succès.
`RADIUS_ACCESS_REJECT` (int)
  Une réponse Access-Reject à un paquet Access-Request indique que le serveur RADIUS n'a pas réussi à authentifier l'utilisateur.
`RADIUS_ACCESS_CHALLENGE` (int)
  Une réponse Access-Challenge à un paquet Access-Request indique que le serveur RADIUS requiert plus d'informations d'un autre paquet Access-Request avant d'authentifier l'utilisateur.
`RADIUS_ACCOUNTING_REQUEST` (int)
  Un paquet Accounting-Request, utilisé pour transmettre des informations de comptabilité pour un service du serveur RADIUS.
`RADIUS_ACCOUNTING_RESPONSE` (int)
  Une réponse Accounting-Response à un paquet Accounting-Request.
`RADIUS_COA_REQUEST` (int)
  Un paquet CoA-Request, envoyé depuis un serveur RADIUS pour indiquer que les autorisations ont changé dans la session utilisateur. Une réponse doit être émise sous la forme d'un CoA-ACK ou d'un CoA-NAK. Cette constante est disponible depuis PECL radius 1.3.0 et suivants.
`RADIUS_COA_ACK` (int)
  Un paquet CoA-ACK, envoyé au serveur RADIUS pour indiquer que les autorisations utilisateurs ont été mises à jour. Cette constante est disponible depuis PECL radius 1.3.0 et suivants.
`RADIUS_COA_NAK` (int)
  Un paquet CoA-NAK, envoyé au serveur RADIUS pour indiquer que les autorisations utilisateurs n'ont pas pu être mises à jour. Cette constante est disponible depuis PECL radius 1.3.0 et suivants.
`RADIUS_DISCONNECT_REQUEST` (int)
  Un paquet Disconnect-Request, envoyé depuis le serveur RADIUS pour indiquer que la session utilisateur doit être close. Cette constante est disponible depuis PECL radius 1.3.0 et suivants.
`RADIUS_DISCONNECT_ACK` (int)
  Un paquet Disconnect-ACK, envoyé au serveur RADIUS pour indiquer que la session utilisateur s'est terminée. Cette constante est disponible depuis PECL radius 1.3.0 et suivants.
`RADIUS_DISCONNECT_NAK` (int)
  Un paquet Disconnect-NAK, envoyé au serveur RADIUS pour indiquer que la session utilisateur n'a pas pu se terminer. Cette constante est disponible depuis PECL radius 1.3.0 et suivants.

## Types d'attribut RADIUS

Ces constantes définissent des types d'attribut RADIUS qui peuvent être utilisées avec les fonctions radius_put_addr(), radius_put_attr(), radius_put_int() et radius_put_string().

`RADIUS_USER_NAME` (int)
  L'attribut User-Name. La valeur de l'attribut doit être une chaîne de caractères contenant le nom de l'utilisateur désirant s'authentifier, et peut être définie en utilisant la fonction radius_put_attr().
`RADIUS_USER_PASSWORD` (int)
  L'attribut User-Password. La valeur de l'attribut doit être une chaîne de caractères contenant le mot de passe de l'utilisateur, et peut être définie en utilisant la fonction radius_put_attr(). Cette valeur sera brouillée pendant la transmission tel que décrit à la » section 5.2 de la RFC 2865.
`RADIUS_CHAP_PASSWORD` (int)
  L'attribut Chap-Password. La valeur de l'attribut doit être une chaîne contenant le premier octet (qui est l'identifiant CHAP), puis une sous-séquence de 16 octets contenant le hash MD5 de l'identifiant CHAP, le mot de passe en clair, et la valeur du challenge CHAP, le tout, concaténés. Il est à noter que la valeur du challenge CHAP doit aussi être envoyée séparément dans l'attribut `RADIUS_CHAP_CHALLENGE`.

  Exemple #1 Utilisation des mots de passe CHAP

      <?php
      // D'abord, nous créons un gestionnaire d'authentification et une requête.
      $radh = radius_auth_open();
      radius_add_server($radh, $server, $port, $secret, 3, 3);
      radius_create_request($radh, RADIUS_ACCESS_REQUEST);

      // Supposons que $password contient le mot de passe en clair :

      // Génération du challenge.
      $challenge = mt_rand();

      // Spécifie un identifiant CHAP.
      $ident = 1;

      // Ajout de l'attribut Chap-Password.
      $cp = hash('md5', pack('Ca*', $ident, $password.$challenge), true);
      radius_put_attr($radh, RADIUS_CHAP_PASSWORD, pack('C', $ident).$cp);

      // Ajout de l'attribut Chap-Challenge.
      radius_put_attr($radh, RADIUS_CHAP_CHALLENGE, $challenge);

      /* A partir d'ici, nous pouvons ajouter les autres attributs
       * et appeler la fonction radius_send_request(). */
      ?>

`RADIUS_NAS_IP_ADDRESS` (int)
  L'attribut NAS-IP-Address. La valeur de l'attribut attendue est l'adresse IP du client RADIUS encodée sous la forme d'un entier, qui peut être définie en utilisant la fonction radius_put_addr().
`RADIUS_NAS_PORT` (int)
  L'attribut NAS-Port. La valeur de l'attribut attendue est le port physique de l'utilisateur sur le client RADIUS, encodé sous la forme d'un entier, qui peut être définie en utilisant la fonction radius_put_int().
`RADIUS_SERVICE_TYPE` (int)
  L'attribut Service-Type. La valeur de l'attribut indique le type de service que l'utilisateur requiert, et doit être un entier, qui peut être défini en utilisant la fonction radius_put_int().

  Des constantes sont fournies pour représenter les valeurs possibles de cet attribut. Les voici :

  - `RADIUS_LOGIN`
  - `RADIUS_FRAMED`
  - `RADIUS_CALLBACK_LOGIN`
  - `RADIUS_CALLBACK_FRAMED`
  - `RADIUS_OUTBOUND`
  - `RADIUS_ADMINISTRATIVE`
  - `RADIUS_NAS_PROMPT`
  - `RADIUS_AUTHENTICATE_ONLY`
  - `RADIUS_CALLBACK_NAS_PROMPT`
`RADIUS_FRAMED_PROTOCOL` (int)

  L'attribut Framed-Protocol. La valeur de l'attribut attendue est un entier, indiquant le framing à utiliser pour l'accès, et peut être définie en utilisant la fonction radius_put_int(). Les valeurs possibles pour cet attribut sont :

  - `RADIUS_PPP`
  - `RADIUS_SLIP`
  - `RADIUS_ARAP`
  - `RADIUS_GANDALF`
  - `RADIUS_XYLOGICS`
`RADIUS_FRAMED_IP_ADDRESS` (int)
  L'attribut Framed-IP-Address. La valeur attendue est une adresse du réseau utilisateur encodée sous la forme d'un entier, qui peut être définie en utilisant la fonction radius_put_addr() et récupérée en utilisant la fonction radius_cvt_addr().
`RADIUS_FRAMED_IP_NETMASK` (int)
  L'attribut Framed-IP-Netmask. La valeur attendue est un netmask du réseau utilisateur, encodé sous la forme d'un entier, qui peut être définie en utilisant la fonction radius_put_addr() et récupérée en utilisant la fonction radius_cvt_addr().
`RADIUS_FRAMED_ROUTING` (int)
  L'attribut Framed-Routing. La valeur attendue est un entier indiquant la méthode de routage pour l'utilisateur, qui peut être définie en utilisant la fonction radius_put_int().

  Valeurs possibles :

  - `0` : Aucun routage
  - `1` : Envoi des paquets de routage
  - `2` : Ecoute des paquets de routage
  - `3` : Envoi et écoute
`RADIUS_FILTER_ID` (int)
  L'attribut Filter-ID. La valeur attendue est une implémentation spécifique, humainement lisible, de chaînes de filtres, qui peuvent être définies en utilisant la fonction radius_put_attr().
`RADIUS_FRAMED_MTU` (int)
  L'attribut Framed-MTU. La valeur attendue est un entier, indiquant le MTU à configurer pour l'utilisateur, et peut être définie en utilisant la fonction radius_put_int().
`RADIUS_FRAMED_COMPRESSION` (int)

  L'attribut Framed-Compression. La valeur attendue est un entier, indiquant le protocole de compression à utiliser, et peut être définie en utilisant la fonction radius_put_int(). Valeurs possibles :

  - `RADIUS_COMP_NONE` : Aucune compression
  - `RADIUS_COMP_VJ` : Compression de l'en-tête VJ TCP/IP
  - `RADIUS_COMP_IPXHDR` : Compression de l'en-tête IPX
  - `RADIUS_COMP_STAC_LZS` : Compression Stac-LZS (ajouté en PECL radius 1.3.0b2)
`RADIUS_LOGIN_IP_HOST` (int)
  L'attribut Login-IP-Host. La valeur attendue est l'adresse IP de connexion de l'utilisateur, encodée sous la forme d'un entier, qui peut être défini en utilisant la fonction radius_put_addr().
`RADIUS_LOGIN_SERVICE` (int)
  L'attribut Login-Service. La valeur attendue est un entier indiquant le service sur lequel l'utilisateur se connecte sur l'hôte d'identification. La valeur peut être convertie en un entier PHP via la fonction radius_cvt_int().
`RADIUS_LOGIN_TCP_PORT` (int)
  L'attribut Login-TCP-Port. La valeur attendue est un entier indiquant le port sur lequel l'utilisateur se connecte sur l'hôte d'identification. La valeur peut être convertie en un entier PHP via la fonction radius_cvt_int().
`RADIUS_REPLY_MESSAGE` (int)
  L'attribut Reply-Message. La valeur attendue est une chaîne de caractères contenant un texte qui peut être affiché à l'utilisateur en réponse à une requête d'accès.
`RADIUS_CALLBACK_NUMBER` (int)
  L'attribut Callback-Number. La valeur attendue est une chaîne de caractères contenant la chaîne de numérotation à utiliser pour la fonction de rappel.
`RADIUS_CALLBACK_ID` (int)
  L'attribut Callback-Id. La valeur attendue est une chaîne contenant le nom de l'implémentation spécifique de la place à appeler.
`RADIUS_FRAMED_ROUTE` (int)
  L'attribut Framed-Route. La valeur attendue est une chaîne contenant un jeu de routes d'implémentation spécifique à configurer pour l'utilisateur.
`RADIUS_FRAMED_IPX_NETWORK` (int)
  L'attribut Framed-IPX-Network. La valeur attendue est un entier contenant le réseau IPX à configurer pour l'utilisateur, ou `0xFFFFFFFE` pour indiquer que le client RADIUS doit sélectionner le réseau, et peut être accédé via la fonction radius_cvt_int().
`RADIUS_STATE` (int)
  L'attribut State. La valeur attendue est une chaîne contenant l'implémentation définie incluse dans un Access-Challenge depuis un serveur qui doit être inclus dans la sous-séquence Access-Request, et peut être défini en utilisant la fonction radius_put_attr().
`RADIUS_CLASS` (int)
  L'attribut Class. La valeur attendue est une chaîne arbitraire incluant le message d'un Access-Accept qui doit être envoyé au serveur de comptes dans les messages Accounting-Request, et peut être défini via la fonction radius_put_attr().
`RADIUS_VENDOR_SPECIFIC` (int)
  L'attribut Vendor-Specific. En général, les valeurs de l'attribut du vendeur doivent être définies en utilisant les fonctions radius_put_vendor_addr(), radius_put_vendor_attr(), radius_put_vendor_int() et radius_put_vendor_string(), plutôt que directement. Cette constante est utile lors de l'interprétation des attributs spécifiques du vendeur dans les réponses d'un serveur RADIUS ; lorsqu'un attribut spécifique du vendeur est reçu, la fonction radius_get_vendor_attr() doit être utilisée pour accéder à l'identifiant du vendeur, le type d'attribut et la valeur de l'attribut.
`RADIUS_SESSION_TIMEOUT` (int)
  Timeout de la session
`RADIUS_IDLE_TIMEOUT` (int)
  Durée d'expiration
`RADIUS_TERMINATION_ACTION` (int)
  Action de termination
`RADIUS_CALLED_STATION_ID` (int)
  Identifiant de la station appelée
`RADIUS_CALLING_STATION_ID` (int)
  Identifiant de la station appelante
`RADIUS_NAS_IDENTIFIER` (int)
  Identifiant NAS
`RADIUS_PROXY_STATE` (int)
  Statut du Proxy
`RADIUS_LOGIN_LAT_SERVICE` (int)
  Service d'identification LAT
`RADIUS_LOGIN_LAT_NODE` (int)
  Noeud d'identification LAT
`RADIUS_LOGIN_LAT_GROUP` (int)
  Groupe d'identification LAT
`RADIUS_FRAMED_APPLETALK_LINK` (int)
  Lien framé Appletalk
`RADIUS_FRAMED_APPLETALK_NETWORK` (int)
  Réseau framé Appletalk
`RADIUS_FRAMED_APPLETALK_ZONE` (int)
  Zone framée Appletalk
`RADIUS_CHAP_CHALLENGE` (int)
  Challenge
`RADIUS_NAS_PORT_TYPE` (int)

  Type du port NAS :

  - `RADIUS_ASYNC`
  - `RADIUS_SYNC`
  - `RADIUS_ISDN_SYNC`
  - `RADIUS_ISDN_ASYNC_V120`
  - `RADIUS_ISDN_ASYNC_V110`
  - `RADIUS_VIRTUAL`
  - `RADIUS_PIAFS`
  - `RADIUS_HDLC_CLEAR_CHANNEL`
  - `RADIUS_X_25`
  - `RADIUS_X_75`
  - `RADIUS_G_3_FAX`
  - `RADIUS_SDSL`
  - `RADIUS_ADSL_CAP`
  - `RADIUS_ADSL_DMT`
  - `RADIUS_IDSL`
  - `RADIUS_ETHERNET`
  - `RADIUS_XDSL`
  - `RADIUS_CABLE`
  - `RADIUS_WIRELESS_OTHER`
  - `RADIUS_WIRELESS_IEEE_802_11`
`RADIUS_PORT_LIMIT` (int)
  Limite du port
`RADIUS_LOGIN_LAT_PORT` (int)
  Port d'identification LAT
`RADIUS_CONNECT_INFO` (int)
  Information de connexion
`RADIUS_ACCT_STATUS_TYPE` (int)

  Type de statut du compte :

  - `RADIUS_START`
  - `RADIUS_STOP`
  - `RADIUS_ACCOUNTING_ON`
  - `RADIUS_ACCOUNTING_OFF`
`RADIUS_ACCT_DELAY_TIME` (int)
  Délai maximal d'identification
`RADIUS_ACCT_INPUT_OCTETS` (int)
  Octets d'entrée d'identification
`RADIUS_ACCT_OUTPUT_OCTETS` (int)
  Octets de sortie d'identification
`RADIUS_ACCT_SESSION_ID` (int)
  Identifiant de session d'identification
`RADIUS_ACCT_AUTHENTIC` (int)

  Identification authentique, un parmi :

  - `RADIUS_AUTH_RADIUS`
  - `RADIUS_AUTH_LOCAL`
  - `RADIUS_AUTH_REMOTE`
`RADIUS_ACCT_SESSION_TIME` (int)
  Durée de la session d'identification
`RADIUS_ACCT_INPUT_PACKETS` (int)
  Paquets d'entrée d'identification
`RADIUS_ACCT_OUTPUT_PACKETS` (int)
  Paquets de sortie d'identification
`RADIUS_ACCT_TERMINATE_CAUSE` (int)

  Cause de la fin de l'identification, un parmi :

  - `RADIUS_TERM_USER_REQUEST`
  - `RADIUS_TERM_LOST_CARRIER`
  - `RADIUS_TERM_LOST_SERVICE`
  - `RADIUS_TERM_IDLE_TIMEOUT`
  - `RADIUS_TERM_SESSION_TIMEOUT`
  - `RADIUS_TERM_ADMIN_RESET`
  - `RADIUS_TERM_ADMIN_REBOOT`
  - `RADIUS_TERM_PORT_ERROR`
  - `RADIUS_TERM_NAS_ERROR`
  - `RADIUS_TERM_NAS_REQUEST`
  - `RADIUS_TERM_NAS_REBOOT`
  - `RADIUS_TERM_PORT_UNNEEDED`
  - `RADIUS_TERM_PORT_PREEMPTED`
  - `RADIUS_TERM_PORT_SUSPENDED`
  - `RADIUS_TERM_SERVICE_UNAVAILABLE`
  - `RADIUS_TERM_CALLBACK`
  - `RADIUS_TERM_USER_ERROR`
  - `RADIUS_TERM_HOST_REQUEST`
`RADIUS_ACCT_MULTI_SESSION_ID` (int)
  Identifiant d'une session multiple d'identification
`RADIUS_ACCT_LINK_COUNT` (int)
  Nombre de liens d'identification

Constantes de type de service
`RADIUS_LOGIN`
`RADIUS_FRAMED`
`RADIUS_CALLBACK_LOGIN`
`RADIUS_CALLBACK_FRAMED`
`RADIUS_OUTBOUND`
`RADIUS_ADMINISTRATIVE`
`RADIUS_NAS_PROMPT`
`RADIUS_AUTHENTICATE_ONLY`
`RADIUS_CALLBACK_NAS_PROMPT`

Framed-Protocol Constants
`RADIUS_PPP`
`RADIUS_SLIP`
`RADIUS_ARAP`
`RADIUS_GANDALF`
`RADIUS_XYLOGICS`

Framed-Compression Constants
`RADIUS_COMP_NONE`
`RADIUS_COMP_VJ`
`RADIUS_COMP_IPXHDR`
`RADIUS_COMP_STAC_LZS`

NAS Port Type Constants
`RADIUS_ASYNC`
`RADIUS_SYNC`
`RADIUS_ISDN_SYNC`
`RADIUS_ISDN_ASYNC_V120`
`RADIUS_ISDN_ASYNC_V110`
`RADIUS_VIRTUAL`
`RADIUS_PIAFS`
`RADIUS_HDLC_CLEAR_CHANNEL`
`RADIUS_X_25`
`RADIUS_X_75`
`RADIUS_G_3_FAX`
`RADIUS_SDSL`
`RADIUS_ADSL_CAP`
`RADIUS_ADSL_DMT`
`RADIUS_IDSL`
`RADIUS_ETHERNET`
`RADIUS_XDSL`
`RADIUS_CABLE`
`RADIUS_WIRELESS_OTHER`
`RADIUS_WIRELESS_IEEE_802_11`

Accounting Status Type Constants
`RADIUS_START`
`RADIUS_STOP`
`RADIUS_ACCOUNTING_ON`
`RADIUS_ACCOUNTING_OFF`

Accounting Authentic Constants
`RADIUS_AUTH_RADIUS`
`RADIUS_AUTH_LOCAL`
`RADIUS_AUTH_REMOTE`

Accounting Terminate Cause Constants
`RADIUS_TERM_USER_REQUEST`
`RADIUS_TERM_LOST_CARRIER`
`RADIUS_TERM_LOST_SERVICE`
`RADIUS_TERM_IDLE_TIMEOUT`
`RADIUS_TERM_SESSION_TIMEOUT`
`RADIUS_TERM_ADMIN_RESET`
`RADIUS_TERM_ADMIN_REBOOT`
`RADIUS_TERM_PORT_ERROR`
`RADIUS_TERM_NAS_ERROR`
`RADIUS_TERM_NAS_REQUEST`
`RADIUS_TERM_NAS_REBOOT`
`RADIUS_TERM_PORT_UNNEEDED`
`RADIUS_TERM_PORT_PREEMPTED`
`RADIUS_TERM_PORT_SUSPENDED`
`RADIUS_TERM_SERVICE_UNAVAILABLE`
`RADIUS_TERM_CALLBACK`
`RADIUS_TERM_USER_ERROR`
`RADIUS_TERM_HOST_REQUEST`

## Types d'attribut RADIUS spécifique au vendeur

`RADIUS_VENDOR_MICROSOFT` (int)

  Attributs spécifiques à Microsoft (» RFC 2548) :

  - `RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP_ERROR`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_1`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_2`
  - `RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
  - `RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
  - `RADIUS_MICROSOFT_MS_RAS_VENDOR`
  - `RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
  - `RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
  - `RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
  - `RADIUS_MICROSOFT_MS_BAP_USAGE`
  - `RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
  - `RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
  - `RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
  - `RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
  - `RADIUS_MICROSOFT_MS_RAS_VERSION`
  - `RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
  - `RADIUS_MICROSOFT_MS_FILTER`
  - `RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
  - `RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
  - `RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
  - `RADIUS_MICROSOFT_MS_CHAP2_PW`
  - `RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`
`RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP_ERROR`
`RADIUS_MICROSOFT_MS_CHAP_PW_1`
`RADIUS_MICROSOFT_MS_CHAP_PW_2`
`RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
`RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
`RADIUS_MICROSOFT_MS_RAS_VENDOR`
`RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
`RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
`RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
`RADIUS_MICROSOFT_MS_BAP_USAGE`
`RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
`RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
`RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
`RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
`RADIUS_MICROSOFT_MS_RAS_VERSION`
`RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
`RADIUS_MICROSOFT_MS_FILTER`
`RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
`RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
`RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
`RADIUS_MICROSOFT_MS_CHAP2_PW`
`RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`

# Exemples

Comment commencer ?

- récupérez une ressource radius
- configurez la bibliothèque
- créez la requête
- ajoutez les attributs
- envoyez la requête
- récupérer les attributs
- fermez la ressource radius (optionnel)

Regardez également aux exemples fournis avec ce paquet.

Le paquet contient un exemple de script PHP. Ce script montre une identification avec radius, en utilisant PAP ou CHAP (md5). Si l'on effectue une identification via Microsoft Radius servers, alors il est possible d'utiliser CHAP (md5). Pour s'identifier avec Microsoft Servers, il faut utiliser MS-CHAPv1 ou MS-CHAPv2, mais c'est plus compliqué, car on doit avoir md4, sha1 et des pour générer les bonnes données. L'exemple fourni montre toutes les méthodes d'identification, incluant MS-CHAPv1 et MS-CHAPv2. Pour faire en sorte que MS-CHAP fonctionne, il faut activer les extensions mcrypt et mhash, à partir de la version 1.2 de ce paquet, l'extension mcrypt n'est plus nécessaire.

# Fonctions Radius

# radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_open — Crée une ressource Radius pour les comptes

### Description

function radius_acct_open(): resource

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une ressource en cas de succès ou `false` si une erreur survient. Cette fonction n'échoue que s'il y a un manque de mémoire.

### Exemples

Exemple #1 Exemple avec radius_acct_open()

    <?php
    $res = radius_acct_open ()
        or die ("Impossible de créer la ressource");
    print "La ressource a été créée avec succès";
    ?>

# radius_add_server

(PECL radius >= 1.1.0)

radius_add_server — Ajoute un serveur

### Description

function radius_add_server(
resource `$radius_handle`,
string `$hostname`,
int `$port`,
string `$secret`,
int `$timeout`,
int `$max_tries`
): bool

radius_add_server() peut être utilisé plusieurs fois, et il peut être utilisé avec la fonction radius_config(). Tout au plus, 10 serveurs peuvent être spécifiés. Lorsque plusieurs serveurs sont fournis, ils sont essayés à la façon `round-robin` tant qu'une réponse valide n'est pas reçue, ou tant que la limite `max_tries` de chaque serveur n'est pas atteinte.

### Liste de paramètres

`radius_handle`
`hostname`
  Le paramètre `hostname` spécifie l'hôte serveur, soit en tant que nom de domaine qualifié, soit en tant qu'adresse IP.
`port`

  Le `port` spécifie le port UDP à contacter sur le serveur. Si le port donné vaut `0`, la bibliothèque recherchera le service `radius/udp` ou `radacct/udp` dans la base de données des services du réseau et utilisera le port s'y trouvant. Si aucune entrée n'est trouvée, la bibliothèque utilisera les ports Radius standards, 1812 pour l'identification et 1813 pour les comptes.

`secret`
  Le secret partagé pour l'hôte serveur est passé au paramètre `secret`. Le protocole Radius ignore tout mais garde les 128 premiers octets du secret partagé.
`timeout`
  Le délai limite pour recevoir les réponses du serveur est passé au paramètre `timeout`, sous la forme de secondes.
`max_tries`
  Le nombre maximal de requêtes répétées à faire avant d'échouer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec radius_add_server()

    <?php
    if (!radius_add_server($res, 'radius.example.com', 1812, 'testing123', 3, 3)) {
        echo 'Erreur Radius :' . radius_strerror($res). "\n<br>";
        exit;
    }
    ?>

### Voir aussi

- radius_config() - Demande à la bibliothèque de lire un fichier de configuration donné

# radius_auth_open

(PECL radius >= 1.1.0)

radius_auth_open — Crée une ressource Radius pour l'identification

### Description

function radius_auth_open(): resource

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une ressource en cas de succès ou `false` si une erreur survient. Cette fonction n'échoue que s'il y a un manque de mémoire.

### Exemples

Exemple #1 Exemple avec radius_auth_open()

    <?php
    $radh = radius_auth_open()
        or die ("Impossible de créer la ressource");
    echo "La ressource a été créée avec succès";
    ?>

# radius_close

(PECL radius >= 1.1.0)

radius_close — Libère toutes les ressources Radius

### Description

function radius_close(resource `$radius_handle`): bool

Il n'est pas nécessaire d'appeler cette fonction car PHP libère toutes les ressources à la fin de chaque demande.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# radius_config

(PECL radius >= 1.1.0)

radius_config — Demande à la bibliothèque de lire un fichier de configuration donné

### Description

function radius_config(resource `$radius_handle`, string `$file`): bool

Avant toute demande Radius, la bibliothèque doit connaître le serveur à contacter. La manière simple de configurer la bibliothèque est d'appeler la fonction radius_config(). radius_config() demande à la bibliothèque de lire un fichier de configuration dont le format est décrit sur la page » radius.conf.

### Liste de paramètres

`radius_handle`
`file`
  Le chemin vers le fichier de configuration est passé en tant qu'argument à la fonction radius_config(). La bibliothèque peut également être configurée en appelant la fonction radius_add_server().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- radius_add_server() - Ajoute un serveur

# radius_create_request

(PECL radius >= 1.1.0)

radius_create_request — Crée une demande de compte ou d'identification

### Description

function radius_create_request(resource `$radius_handle`, int `$type`): bool

Une demande Radius consiste en du code spécifiant une demande spécifique, ainsi que zéro ou plusieurs attributs qui fournissent des informations supplémentaires. Pour commencer à construire une nouvelle demande, appelez la fonction radius_create_request().

> Note: Attention : Il faut appeler cette fonction avant de passer n'importe quel attribut !

### Liste de paramètres

`radius_handle`
`type`
  Le type est `RADIUS_ACCESS_REQUEST` ou `RADIUS_ACCOUNTING_REQUEST`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec radius_create_request()

    <?php
    if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
        echo 'Erreur Radius :' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Voir aussi

- radius_send_request() - Envoie une requête et attend une réponse

# radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addr — Convertit des données brutes en adresse IP

### Description

function radius_cvt_addr(string `$data`): string

Convertit des données brutes en adresse IP

### Liste de paramètres

`data`
  Données d'entrée

### Valeurs de retour

Retourne l'adresse IP.

### Exemples

Exemple #1 Exemple avec radius_cvt_addr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Erreur lors de la récupération des attributs : %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_IP_ADDRESS:
            $ip = radius_cvt_addr($data);
            echo "IP : $ip<br>\n";
            break;

        case RADIUS_FRAMED_IP_NETMASK:
            $mask = radius_cvt_addr($data);
            echo "MASQUE : $mask<br>\n";
            break;
        }
    }
    ?>

### Voir aussi

- radius_cvt_int() - Convertit des données brutes en entier
- radius_cvt_string() - Convertit des données brutes en chaîne de caractères

# radius_cvt_int

(PECL radius >= 1.1.0)

radius_cvt_int — Convertit des données brutes en entier

### Description

function radius_cvt_int(string `$data`): int

Convertit des données brutes en entier

### Liste de paramètres

`data`
  Données d'entrée.

### Valeurs de retour

Retourne l'entier, récupéré depuis les données.

### Exemples

Exemple #1 Exemple avec radius_cvt_int()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Erreur lors de la récupération des attributs : %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_MTU:
            $mtu = radius_cvt_int($data);
            echo "MTU : $mtu<br>\n";
            break;
        }
    }
    ?>

### Voir aussi

- radius_cvt_addr() - Convertit des données brutes en adresse IP
- radius_cvt_string() - Convertit des données brutes en chaîne de caractères

# radius_cvt_string

(PECL radius >= 1.1.0)

radius_cvt_string — Convertit des données brutes en chaîne de caractères

### Description

function radius_cvt_string(string `$data`): string

Convertit des données brutes en chaîne de caractères

### Liste de paramètres

`data`
  Données d'entrée

### Valeurs de retour

Retourne la chaîne, récupérée depuis les données.

### Exemples

Exemple #1 Exemple avec radius_cvt_string()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Erreur lors de la récupération des attributs : %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FILTER_ID:
            $id = radius_cvt_string($data);
            echo "Filtre ID : $id<br>\n";
            break;
        }
    }
    ?>

### Voir aussi

- radius_cvt_addr() - Convertit des données brutes en adresse IP
- radius_cvt_int() - Convertit des données brutes en entier

# radius_demangle

(PECL radius >= 1.2.0)

radius_demangle — Déchiffre des données déformées

### Description

function radius_demangle(resource `$radius_handle`, string `$mangled`): string

Quelques données (mots de passe, clés MS-CHAPv1 MPPE) sont déformées pour des raisons de sécurité et doivent être déchiffrées avant de pouvoir les utiliser.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`mangled`
  Les données déformées à déchiffrer

### Valeurs de retour

Retourne la chaîne déchiffrée ou `false` si une erreur survient.

# radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_key — Dérive les clés mppe depuis des données

### Description

function radius_demangle_mppe_key(resource `$radius_handle`, string `$mangled`): string

Lors de l'utilisation de MPPE avec MS-CHAPv2, les clés reçues et envoyées sont déformées (voir la » RFC 2548), cependant, cette fonction est inutile, car il n'existe pas et n'existera probablement pas d'implémentation de PPTP-MPPE dans PHP.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`mangled`
  Les données déformées à déchiffrer

### Valeurs de retour

Retourne la chaîne ou `false` si une erreur survient.

# radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — Extrait un attribut

### Description

function radius_get_attr(resource `$radius_handle`): mixed

Comme les demandes Radius, chaque réponse doit contenir zéro ou plusieurs attributs. Après la réception d'une réponse avec succès par la fonction radius_send_request(), ces attributs peuvent être extraits un par un en utilisant la fonction radius_get_attr(). À chaque appel de radius_get_attr(), le prochain attribut est récupéré depuis la réponse courante.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.

### Valeurs de retour

Retourne un tableau associatif contenant le type de l'attribut ainsi que les données ou un numéro d'erreur <= 0.

### Exemples

Exemple #1 Exemple avec radius_get_attr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf("Erreur lors de la récupération de l'attribut : %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Attribut récupéré :%d %d octets %s\n", $attr, strlen($data), bin2hex($data));
    }
    ?>

### Voir aussi

- radius_put_attr() - Attache un attribut binaire
- radius_get_vendor_attr() - Extrait un attribut spécifique au vendeur
- radius_put_vendor_attr() - Attache un attribut binaire à un vendeur spécifique
- radius_send_request() - Envoie une requête et attend une réponse

# radius_get_tagged_attr_data

(PECL radius >= 1.3.0)

radius_get_tagged_attr_data — Extrait les données d'un attribut

### Description

function radius_get_tagged_attr_data(string `$data`): string|false

Si un attribut contenant un tag a été retourné depuis la fonction radius_get_attr(), radius_get_tagged_attr_data() va retourner les données depuis cet attribut.

### Liste de paramètres

`data`
  L'attribut contenant un tag à décoder.

### Valeurs de retour

Retourne les données de l'attribut ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec radius_get_tagged_attr_data()

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Erreur lors de la récupération de l'attribut : %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Récupération de l'attribut contenant le tag %d et la valeur %s\n", $tag, $value);
    }
    ?>

### Voir aussi

- radius_get_attr() - Extrait un attribut
- radius_get_tagged_attr_tag() - Extrait le tag depuis un attribut

# radius_get_tagged_attr_tag

(PECL radius >= 1.3.0)

radius_get_tagged_attr_tag — Extrait le tag depuis un attribut

### Description

function radius_get_tagged_attr_tag(string `$data`): int|false

Si un attribut contenant un tag a été retourné depuis la fonction radius_get_attr(), radius_get_tagged_attr_data() va retourner le tag depuis l'attribut.

### Liste de paramètres

`data`
  L'attribut à décoder.

### Valeurs de retour

Retourne le tag depuis l'attribut ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec radius_get_tagged_attr_tag()

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Erreur lors de la récupération de l'attribut : %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Récupération de l'attribut contenant le tag %d et la valeur %s\n", $tag, $value);
    }
    ?>

### Voir aussi

- radius_get_attr() - Extrait un attribut
- radius_get_tagged_attr_data() - Extrait les données d'un attribut

# radius_get_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attr — Extrait un attribut spécifique au vendeur

### Description

function radius_get_vendor_attr(string `$data`): array|false

Si radius_get_attr() retourne `RADIUS_VENDOR_SPECIFIC`, radius_get_vendor_attr() peut être appelé pour déterminer le vendeur.

### Liste de paramètres

`data`
  Données d'entrée.

### Valeurs de retour

Retourne un tableau associatif contenant le type de l'attribut, le vendeur ainsi que les données, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec radius_get_vendor_attr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Erreur lors de la récupération de l'attribut : %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Attribut récupéré :%d %d octets %s\n", $attr, strlen($data), bin2hex($data));
        if ($attr == RADIUS_VENDOR_SPECIFIC) {

            $resv = radius_get_vendor_attr($data);
            if (is_array($resv)) {
                $vendor = $resv['vendor'];
                $attrv = $resv['attr'];
                $datav = $resv['data'];
                printf("Récupération du vendeur de l'attribut :%d %d octets %s\n", $attrv, strlen($datav), bin2hex($datav));
            }

        }
    }
    ?>

### Voir aussi

- radius_get_attr() - Extrait un attribut
- radius_put_vendor_attr() - Attache un attribut binaire à un vendeur spécifique

# radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addr — Attache une adresse IP en tant qu'attribut

### Description

function radius_put_addr(
resource `$radius_handle`,
int `$type`,
string `$addr`,
int `$options` = 0,
int `$tag` = ?
): bool

Attache une adresse IP à la requête RADIUS courante.

> Note: Une requête doit être créée via la fonction radius_create_request() avant que cette fonction puisse être appelée.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`type`
  Le type d'attribut.
`addr`
  Une adresse IPv4 ; par exemple `10.0.0.1`.
`options`
  Un masqe d'options d'attribut. Les options disponibles incluent `RADIUS_OPTION_TAGGED` et `RADIUS_OPTION_SALT`.
`tag`
  L'attribut tag. Ce paramètre est ignoré tant que l'option `RADIUS_OPTION_TAGGED` est défini.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL radius 1.3.0 | Les paramètres `options` et `tag` ont été ajoutés.

# radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attr — Attache un attribut binaire

### Description

function radius_put_attr(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attache un attribut binaire à la requête RADIUS courante.

> Note: Une requête doit être créée via la fonction radius_create_request() avant que cette fonction puisse être appelée.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`type`
  Le type d'attribut.
`value`
  La valeur de l'attribut, qui sera traité comme une chaîne binaire brute.
`options`
  Un masqe d'options d'attribut. Les options disponibles incluent `RADIUS_OPTION_TAGGED` et `RADIUS_OPTION_SALT`.
`tag`
  L'attribut tag. Ce paramètre est ignoré tant que l'option `RADIUS_OPTION_TAGGED` est défini.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL radius 1.3.0 | Les paramètres `options` et `tag` ont été ajoutés.

### Exemples

Exemple #1 Exemple avec radius_put_attr()

    <?php
    mt_srand(time());
    $chall = mt_rand();
    $chapval = hash('md5', pack('Ca*',1 , 'sepp' . $chall));
    $pass = pack('CH*', 1, $chapval);
    if (!radius_put_attr($res, RADIUS_CHAP_PASSWORD, $pass)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Voir aussi

- radius_get_attr() - Extrait un attribut
- radius_get_vendor_attr() - Extrait un attribut spécifique au vendeur
- radius_put_vendor_attr() - Attache un attribut binaire à un vendeur spécifique

# radius_put_int

(PECL radius >= 1.1.0)

radius_put_int — Attache un attribut entier

### Description

function radius_put_int(
resource `$radius_handle`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attache un attribut entier à la requête RADIUS courante.

> Note: Une requête doit être créée via la fonction radius_create_request() avant que cette fonction puisse être appelée.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`type`
  Le type d'attribut.
`value`
  La valeur de l'attribut.
`options`
  Un masqe d'options d'attribut. Les options disponibles incluent `RADIUS_OPTION_TAGGED` et `RADIUS_OPTION_SALT`.
`tag`
  L'attribut tag. Ce paramètre est ignoré tant que l'option `RADIUS_OPTION_TAGGED` est défini.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL radius 1.3.0 | Les paramètres `options` et `tag` ont été ajoutés.

### Exemples

Exemple #1 Exemple avec radius_put_int()

    <?php
    if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) {
       echo 'Erreur Radius :' . radius_strerror($res). "\n<br />";
       exit;
    }
    ?>

### Voir aussi

- radius_put_string() - Attache un attribut chaîne de caractères
- radius_put_vendor_int() - Attache un attribut entier à un vendeur spécifique
- radius_put_vendor_string() - Attache un attribut sous la forme d'une chaîne à un vendeur spécifique

# radius_put_string

(PECL radius >= 1.1.0)

radius_put_string — Attache un attribut chaîne de caractères

### Description

function radius_put_string(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attache un attribut sous forme de chaîne à la requête RADIUS courante. En général, la fonction radius_put_attr() est plus utile pour cela, car elle est sécurisée au niveau binaire.

> Note: Une requête doit être créée via la fonction radius_create_request() avant que cette fonction puisse être appelée.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`type`
  Le type d'attribut.
`value`
  La valeur de l'attribut. Cette valeur est attendue par la bibliothèque sous-jacente comme devant se terminer par `null` ; aussi, ce paramètre n'est pas sécurisé binairement.
`options`
  Un masqe d'options d'attribut. Les options disponibles incluent `RADIUS_OPTION_TAGGED` et `RADIUS_OPTION_SALT`.
`tag`
  L'attribut tag. Ce paramètre est ignoré tant que l'option `RADIUS_OPTION_TAGGED` est défini.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL radius 1.3.0 | Les paramètres `options` et `tag` ont été ajoutés.

### Exemples

Exemple #1 Exemple avec radius_put_string()

    <?php
    if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
        echo 'Erreur Radius :' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Voir aussi

- radius_put_int() - Attache un attribut entier
- radius_put_vendor_int() - Attache un attribut entier à un vendeur spécifique
- radius_put_vendor_string() - Attache un attribut sous la forme d'une chaîne à un vendeur spécifique

# radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addr — Attache une adresse IP spécifique à un vendeur

### Description

function radius_put_vendor_addr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$addr`
): bool

Attache une adresse IP spécifique au vendeur pour la requête RADIUS courante.

> Note: Une requête doit être créée via la fonction radius_create_request() avant que cette fonction puisse être appelée.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`vendor`
  L'identifiant du vendeur.
`type`
  Le type d'attribut.
`addr`
  Une adresse IPv4 ; par exemple `10.0.0.1`.
`options`
  Un masqe d'options d'attribut. Les options disponibles incluent `RADIUS_OPTION_TAGGED` et `RADIUS_OPTION_SALT`.
`tag`
  L'attribut tag. Ce paramètre est ignoré tant que l'option `RADIUS_OPTION_TAGGED` est défini.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL radius 1.3.0 | Les paramètres `options` et `tag` ont été ajoutés.

# radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attr — Attache un attribut binaire à un vendeur spécifique

### Description

function radius_put_vendor_attr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attache un attribut binaire spécifique au vendeur pour la requête courante RADIUS.

> Note: Une requête doit être créée via la fonction radius_create_request() avant que cette fonction puisse être appelée.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`vendor`
  L'identifiant du vendeur.
`type`
  Le type d'attribut.
`value`
  La valeur de l'attribut, qui sera traité comme une chaîne binaire brute.
`options`
  Un masqe d'options d'attribut. Les options disponibles incluent `RADIUS_OPTION_TAGGED` et `RADIUS_OPTION_SALT`.
`tag`
  L'attribut tag. Ce paramètre est ignoré tant que l'option `RADIUS_OPTION_TAGGED` est défini.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL radius 1.3.0 | Les paramètres `options` et `tag` ont été ajoutés.

### Exemples

Exemple #1 Exemple avec radius_put_vendor_attr()

    <?php
    if (!radius_put_vendor_attr($res, RADIUS_VENDOR_MICROSOFT, RAD_MICROSOFT_MS_CHAP_CHALLENGE, $challenge)) {
        echo 'Erreur Radius :' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Voir aussi

- radius_get_vendor_attr() - Extrait un attribut spécifique au vendeur

# radius_put_vendor_int

(PECL radius >= 1.1.0)

radius_put_vendor_int — Attache un attribut entier à un vendeur spécifique

### Description

function radius_put_vendor_int(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attache un attribut spécifique au vendeur à la requête courante RADIUS.

> Note: Une requête doit être créée via la fonction radius_create_request() avant que cette fonction puisse être appelée.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`vendor`
  L'identifiant du vendeur.
`type`
  Le type d'attribut.
`value`
  La valeur de l'attribut.
`options`
  Un masqe d'options d'attribut. Les options disponibles incluent `RADIUS_OPTION_TAGGED` et `RADIUS_OPTION_SALT`.
`tag`
  L'attribut tag. Ce paramètre est ignoré tant que l'option `RADIUS_OPTION_TAGGED` est défini.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL radius 1.3.0 | Les options `options` et `tag` ont été ajoutées.

### Voir aussi

- radius_put_vendor_string() - Attache un attribut sous la forme d'une chaîne à un vendeur spécifique

# radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_string — Attache un attribut sous la forme d'une chaîne à un vendeur spécifique

### Description

function radius_put_vendor_string(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attache un attribut spécifique au vendeur à la requête courante RADIUS. En général, radius_put_vendor_attr() est une fonction plus pratique pour attacher des attributs, sachant qu'elle est sécurisée au niveau binaire.

> Note: Une requête doit être créée via la fonction radius_create_request() avant que cette fonction puisse être appelée.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.
`vendor`
  L'identifiant du vendeur.
`type`
  Le type d'attribut.
`value`
  La valeur de l'attribut. Cette valeur est attendue par la bibliothèque sous-jacente comme se terminant par `null` ; aussi, ce paramètre n'est pas sécurisé au niveau binaire.
`options`
  Un masqe d'options d'attribut. Les options disponibles incluent `RADIUS_OPTION_TAGGED` et `RADIUS_OPTION_SALT`.
`tag`
  L'attribut tag. Ce paramètre est ignoré tant que l'option `RADIUS_OPTION_TAGGED` est défini.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL radius 1.3.0 | Les paramètres `options` et `tag` ont été ajoutés.

### Voir aussi

- radius_put_vendor_int() - Attache un attribut entier à un vendeur spécifique

# radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticator — Retourne l'authentificateur de requête

### Description

function radius_request_authenticator(resource `$radius_handle`): string

L'authentificateur de requête est nécessaire pour le déchiffrement des données comme les mots de passe et les clés de chiffrement.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.

### Valeurs de retour

Retourne l'authentificateur de requête en tant que chaîne de caractères ou `false` si une erreur survient.

### Voir aussi

- radius_demangle() - Déchiffre des données déformées

# radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attr — Chiffre une valeur en utilisant un Salt

### Description

function radius_salt_encrypt_attr(resource `$radius_handle`, string `$data`): string|false

Applique l'algorithme RADIUS salt à la valeur fournie.

En général, ceci est fait automatiquement en fournissant l'option `RADIUS_OPTION_SALT` à la fonction définissant l'attribut, mais cette fonction peut être utilisée si une construction de requête bas niveau est requise.

### Liste de paramètres

`data`
  Les données à chiffrer avec un salt.

### Valeurs de retour

Retourne les données chiffrées en utilisant un salt ou `false` si une erreur survient.

### Voir aussi

- radius_put_addr() - Attache une adresse IP en tant qu'attribut
- radius_put_attr() - Attache un attribut binaire
- radius_put_int() - Attache un attribut entier
- radius_put_string() - Attache un attribut chaîne de caractères

# radius_send_request

(PECL radius >= 1.1.0)

radius_send_request — Envoie une requête et attend une réponse

### Description

function radius_send_request(resource `$radius_handle`): int

Après qu'une demande Radius ait été construite, elle est envoyée grâce à la fonction radius_send_request().

La fonction radius_send_request() envoie la requête et attend une réponse valide, essayant à nouveau, suivant la méthode `round-robin` autant que nécessaire.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.

### Valeurs de retour

Si une réponse valide est reçue, radius_send_request() retourne le code Radius qui spécifie le type de réponse. C'est, typiquement, `RADIUS_ACCESS_ACCEPT`, `RADIUS_ACCESS_REJECT` ou `RADIUS_ACCESS_CHALLENGE`. Si aucune réponse valide n'est reçue, radius_send_request() retournera `false`.

### Voir aussi

- radius_create_request() - Crée une demande de compte ou d'identification

# radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — Retourne le secret partagé

### Description

function radius_server_secret(resource `$radius_handle`): string

Le secret partagé est nécessaire pour le rétablissement des données comme les mots de passe et les clés de chiffrement.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.

### Valeurs de retour

Retourne le secret partagé du serveur en tant que chaîne de caractères ou `false` si une erreur survient.

# radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — Retourne un message d'erreur

### Description

function radius_strerror(resource `$radius_handle`): string

Si une fonction Radius échoue, alors, elle enregistre un message d'erreur. Ce message d'erreur peut être récupéré avec cette fonction.

### Liste de paramètres

`radius_handle`
  La ressource RADIUS.

### Valeurs de retour

Retourne un message d'erreur en tant que chaîne de caractères.

## Sommaire

- radius_acct_open — Crée une ressource Radius pour les comptes
- radius_add_server — Ajoute un serveur
- radius_auth_open — Crée une ressource Radius pour l'identification
- radius_close — Libère toutes les ressources Radius
- radius_config — Demande à la bibliothèque de lire un fichier de configuration donné
- radius_create_request — Crée une demande de compte ou d'identification
- radius_cvt_addr — Convertit des données brutes en adresse IP
- radius_cvt_int — Convertit des données brutes en entier
- radius_cvt_string — Convertit des données brutes en chaîne de caractères
- radius_demangle — Déchiffre des données déformées
- radius_demangle_mppe_key — Dérive les clés mppe depuis des données
- radius_get_attr — Extrait un attribut
- radius_get_tagged_attr_data — Extrait les données d'un attribut
- radius_get_tagged_attr_tag — Extrait le tag depuis un attribut
- radius_get_vendor_attr — Extrait un attribut spécifique au vendeur
- radius_put_addr — Attache une adresse IP en tant qu'attribut
- radius_put_attr — Attache un attribut binaire
- radius_put_int — Attache un attribut entier
- radius_put_string — Attache un attribut chaîne de caractères
- radius_put_vendor_addr — Attache une adresse IP spécifique à un vendeur
- radius_put_vendor_attr — Attache un attribut binaire à un vendeur spécifique
- radius_put_vendor_int — Attache un attribut entier à un vendeur spécifique
- radius_put_vendor_string — Attache un attribut sous la forme d'une chaîne à un vendeur spécifique
- radius_request_authenticator — Retourne l'authentificateur de requête
- radius_salt_encrypt_attr — Chiffre une valeur en utilisant un Salt
- radius_send_request — Envoie une requête et attend une réponse
- radius_server_secret — Retourne le secret partagé
- radius_strerror — Retourne un message d'erreur

- Installation/Configuration
  - Installation
- Constantes pré-définies
  - RADIUS Options
  - Types de paquets RADIUS
  - Types d'attribut RADIUS
  - Types d'attribut RADIUS spécifique au vendeur
- Exemples
- Fonctions Radius
  - radius_acct_open — Crée une ressource Radius pour les comptes
  - radius_add_server — Ajoute un serveur
  - radius_auth_open — Crée une ressource Radius pour l'identification
  - radius_close — Libère toutes les ressources Radius
  - radius_config — Demande à la bibliothèque de lire un fichier de configuration donné
  - radius_create_request — Crée une demande de compte ou d'identification
  - radius_cvt_addr — Convertit des données brutes en adresse IP
  - radius_cvt_int — Convertit des données brutes en entier
  - radius_cvt_string — Convertit des données brutes en chaîne de caractères
  - radius_demangle — Déchiffre des données déformées
  - radius_demangle_mppe_key — Dérive les clés mppe depuis des données
  - radius_get_attr — Extrait un attribut
  - radius_get_tagged_attr_data — Extrait les données d'un attribut
  - radius_get_tagged_attr_tag — Extrait le tag depuis un attribut
  - radius_get_vendor_attr — Extrait un attribut spécifique au vendeur
  - radius_put_addr — Attache une adresse IP en tant qu'attribut
  - radius_put_attr — Attache un attribut binaire
  - radius_put_int — Attache un attribut entier
  - radius_put_string — Attache un attribut chaîne de caractères
  - radius_put_vendor_addr — Attache une adresse IP spécifique à un vendeur
  - radius_put_vendor_attr — Attache un attribut binaire à un vendeur spécifique
  - radius_put_vendor_int — Attache un attribut entier à un vendeur spécifique
  - radius_put_vendor_string — Attache un attribut sous la forme d'une chaîne à un vendeur spécifique
  - radius_request_authenticator — Retourne l'authentificateur de requête
  - radius_salt_encrypt_attr — Chiffre une valeur en utilisant un Salt
  - radius_send_request — Envoie une requête et attend une réponse
  - radius_server_secret — Retourne le secret partagé
  - radius_strerror — Retourne un message d'erreur

- Radius
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions Radius

# Extensions spécifiques à la ligne de commande

# GNU Readline

# Introduction

Les fonctions readline implémentent une interface de la bibliothèque GNU readline. Ce sont des fonctions qui fournissent des lignes de commandes éditables. Un exemple est fourni montrant comment Bash permet d'utiliser les flèches pour insérer des caractères ou scroller dans l'historique des commandes. De par la nature de cette bibliothèque, il ne faudrait pas en avoir besoin dans les applications Web mais par contre, cela peut être très utile lors de l'écriture de scripts utilisés depuis la ligne de commande.

À partir de PHP 7.1.0 cette extension est supportée sur Windows.

Attention

L'extension readline n'est pas thread-safe ! Par conséquent l'usage de celle-ci avec n'importe quel SAPI qui est véritablement thread-safe (comme Apache mod_winnt) est fortement déconseillé.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

Pour utiliser les fonctions readline, il faut installer libreadline. Il est possible de trouver libreadline sur la page d'accueil du projet GNU Readline, à » https://tiswww.case.edu/php/chet/readline/rltop.html. Il est maintenu par Chet Ramey, qui est également l'auteur de Bash.

Il est possible d'également utiliser ces fonctions avec la bibliothèque libedit, un remplacement non-GPL de la bibliothèque readline. La bibliothèque libedit est sous licence BSD et disponible en téléchargement sur » http://www.thrysoee.dk/editline/.

## Installation

Pour utiliser ces fonctions, il faut compiler la version CGI ou CLI de PHP avec le support readline. Il faut aussi utiliser l'option de compilation --with-readline[=DIR]. Pour utiliser le remplacement readline de libedit, configurez PHP --with-libedit[=DIR].

Sur Windows cette extension est disponible par défaut à partir de PHP 7.1.0.

## Configuration à l'exécution

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

Options de configuration Readline
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
cli.pager | "" | `INI_ALL` |
cli.prompt | "\\b \\> " | `INI_ALL` |

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

`cli.pager` string
  Outil externe pour afficher la sortie depuis la ligne de commande.
`cli.prompt` string
  Prompt de la ligne de commande.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`READLINE_LIB` (string)
  La bibliothèque utilisée pour le support de readline ; actuellement soit `readline` soit `libedit`.

# Fonctions Readline

# readline

(PHP 4, PHP 5, PHP 7, PHP 8)

readline — Lit une ligne

### Description

function readline(?string `$prompt` = `null`): string|false

Lit une seule ligne saisie par l'utilisateur. Il faut ajouter cette ligne à l'historique soi-même, avec la fonction readline_add_history().

### Liste de paramètres

`prompt`
  Il est possible de spécifier une chaîne de caractères à utiliser comme prompt à l'utilisateur.

### Valeurs de retour

Retourne une chaîne de caractères depuis l'utilisateur. La ligne retournée a été débarrassée du caractère final de nouvelle ligne. S'il n'y a plus de données à lire, alors `false` est retourné.

### Exemples

Exemple #1 Exemple avec readline()

    <?php
    // Lit 3 commandes de l'utilisateur
    for ($i=0; $i < 3; $i++) {
            $line = readline("Commande : ");
            readline_add_history($line);
    }

    // Liste l'historique
    print_r(readline_list_history());

    // Liste les variables
    print_r(readline_info());
    ?>

# readline_add_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_add_history — Ajoute une ligne à l'historique

### Description

function readline_add_history(string `$prompt`): true

Ajoute une ligne à l'historique.

### Liste de paramètres

`prompt`
  La ligne à ajouter à l'historique.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.5.0 | Le type de retour est maintenant `true`, auparavant il était bool.

# readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_install — Initialise l'interface et le terminal de rappel de readline, affiche le prompt et retourne immédiatement

### Description

function readline_callback_handler_install(string `$prompt`, callable `$callback`): true

Définit une interface de rappel pour readline, affiche le `prompt` et retourne immédiatement. Appeler cette fonction deux fois sans effacer au préalable l'interface de rappel précédente effacera automatiquement et proprement l'ancienne interface.

La fonctionnalité de rappel est très utile lorsque combinée à la fonction stream_select() permettant l'interconnexion IO / entrée utilisateur, à la différence de readline().

### Liste de paramètres

`prompt`
  Le message de prompt.
`callback`
  La fonction `callback` prend un paramètre : l'entrée utilisateur retournée.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.5.0 | Le type de retour est maintenant `true`, auparavant il était bool.

### Exemples

Exemple #1 Exemple d'interface de rappel de Readline

    <?php
    function rl_callback($ret)
    {
        global $c, $prompting;

        echo "Vous avez entré : $ret\n";
        $c++;

        if ($c > 10) {
            $prompting = false;
            readline_callback_handler_remove();
        } else {
            readline_callback_handler_install("[$c] Entrer quelque chose : ", 'rl_callback');
        }
    }

    $c = 1;
    $prompting = true;

    readline_callback_handler_install("[$c] Entrer quelque chose : ", 'rl_callback');

    while ($prompting) {
        $w = NULL;
        $e = NULL;
        $n = stream_select($r = array(STDIN), $w, $e, null);
        if ($n && in_array(STDIN, $r)) {
            // lit un caractère, appellera la fonction de callback lorsqu'une nouvelle ligne est entrée
            readline_callback_read_char();
        }
    }

    echo "Le prompt est désactivé. Tout a été effectué.\n";
    ?>

### Voir aussi

- readline_callback_handler_remove() - Efface un gestionnaire de rappel readline
- readline_callback_read_char() - Lit un caractère et informe l'interface de rappel readline
- stream_select() - Surveille la modification d'un ou plusieurs flux

# readline_callback_handler_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_remove — Efface un gestionnaire de rappel readline

### Description

function readline_callback_handler_remove(): bool

Efface un gestionnaire de rappel installé précédemment et restaure les paramètres du terminal.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si un gestionnaire de rappel précédemment installé a été effacé ou `false` s'il n'a pas été trouvé.

### Exemples

Voir la fonction readline_callback_handler_install() pour un exemple concernant l'utilisation de l'interface de rappel readline.

### Voir aussi

- readline_callback_handler_install() - Initialise l'interface et le terminal de rappel de readline, affiche le prompt et retourne immédiatement
- readline_callback_read_char() - Lit un caractère et informe l'interface de rappel readline

# readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_char — Lit un caractère et informe l'interface de rappel readline

### Description

function readline_callback_read_char(): void

Lit un caractère de l'entrée utilisateur. Lorsqu'une ligne est reçue, la fonction informe l'interface de rappel readline installée en utilisant readline_callback_handler_install() qu'une ligne est prête à être entrée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Voir la fonction readline_callback_handler_install() pour un exemple concernant l'utilisation de l'interface de rappel readline.

### Voir aussi

- readline_callback_handler_install() - Initialise l'interface et le terminal de rappel de readline, affiche le prompt et retourne immédiatement
- readline_callback_handler_remove() - Efface un gestionnaire de rappel readline

# readline_clear_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_clear_history — Efface l'historique

### Description

function readline_clear_history(): true

Efface l'historique.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.5.0 | Le type de retour est maintenant `true`, auparavant il était bool.

# readline_completion_function

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_completion_function — Enregistre une fonction de complétion

### Description

function readline_completion_function(callable `$callback`): bool

Enregistre une nouvelle fonction de complétion. C'est la même fonctionnalité que lors de l'utilisation de la touche de tabulation sous Bash.

### Liste de paramètres

`callback`
  Il faut fournir le nom d'une fonction qui accepte un nom partiel de commande, et retourne un tableau de correspondances possibles.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# readline_info

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_info — Lit ou modifie diverses variables internes de readline

### Description

function readline_info(?string `$var_name` = `null`, int|string|bool|null `$value` = `null`): mixed

Lit/modifie diverses variables internes.

### Liste de paramètres

`var_name`
  Un nom de variable.
`value`
  Si fourni, ce sera la nouvelle valeur à définir.

### Valeurs de retour

Appelée sans paramètre, readline_info() retourne un tableau contenant les valeurs des paramètres de Readline. Les éléments seront indexés par les clés suivantes : `"done"`, `"end"`, `"erase_empty_line"`, `"library_version"`, `"line_buffer"`, `"mark"`, `"pending_input"`, `"point"`, `"prompt"`, `"readline_name"` et `"terminal_name"`. Le tableau ne contiendra que les éléments qui sont pris en charge par la bibliothèque utilisée pour construire l'extension readline.

Si appelée avec un ou deux paramètres, l'ancienne valeur est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | `var_name` et `value` sont désormais nullable.

# readline_list_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_list_history — Liste l'historique

### Description

function readline_list_history(): array

Liste l'historique.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau avec la liste de toutes les lignes de commandes de l'historique. Les éléments sont indexés numériquement, à partir de `0`.

# readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_line — Informe readline que le curseur est passé à une nouvelle ligne

### Description

function readline_on_new_line(): void

Informe readline que le curseur est passé à une nouvelle ligne.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Notes

> Note: Cette fonction n'est disponible que si elle est supportée par la bibliothèque readline sous-jacente. Elle n'est pas supportée sur Windows.

# readline_read_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_read_history — Lit l'historique

### Description

function readline_read_history(?string `$filename` = `null`): bool

Lit une ligne de l'historique depuis le fichier `filename`.

### Liste de paramètres

`filename`
  Chemin vers le fichier contenant l'historique des commandes.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `filename` est désormais nullable.

# readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplay — Demande à readline de refaire l'affichage

### Description

function readline_redisplay(): void

Demande à readline de refaire l'affichage.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

# readline_write_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_write_history — Écrit dans l'historique

### Description

function readline_write_history(?string `$filename` = `null`): bool

Écrit l'historique dans le fichier `filename`.

### Liste de paramètres

`filename`
  Chemin vers le fichier à sauvegarder.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `filename` est désormais nullable.

## Sommaire

- readline — Lit une ligne
- readline_add_history — Ajoute une ligne à l'historique
- readline_callback_handler_install — Initialise l'interface et le terminal de rappel de readline, affiche le prompt et retourne immédiatement
- readline_callback_handler_remove — Efface un gestionnaire de rappel readline
- readline_callback_read_char — Lit un caractère et informe l'interface de rappel readline
- readline_clear_history — Efface l'historique
- readline_completion_function — Enregistre une fonction de complétion
- readline_info — Lit ou modifie diverses variables internes de readline
- readline_list_history — Liste l'historique
- readline_on_new_line — Informe readline que le curseur est passé à une nouvelle ligne
- readline_read_history — Lit l'historique
- readline_redisplay — Demande à readline de refaire l'affichage
- readline_write_history — Écrit dans l'historique

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Fonctions Readline
  - readline — Lit une ligne
  - readline_add_history — Ajoute une ligne à l'historique
  - readline_callback_handler_install — Initialise l'interface et le terminal de rappel de readline, affiche le prompt et retourne immédiatement
  - readline_callback_handler_remove — Efface un gestionnaire de rappel readline
  - readline_callback_read_char — Lit un caractère et informe l'interface de rappel readline
  - readline_clear_history — Efface l'historique
  - readline_completion_function — Enregistre une fonction de complétion
  - readline_info — Lit ou modifie diverses variables internes de readline
  - readline_list_history — Liste l'historique
  - readline_on_new_line — Informe readline que le curseur est passé à une nouvelle ligne
  - readline_read_history — Lit l'historique
  - readline_redisplay — Demande à readline de refaire l'affichage
  - readline_write_history — Écrit dans l'historique

- Readline — GNU Readline
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Readline

# Extensions sur l'archivage et la compression

# Bzip2

# Introduction

Les fonctions bzip2 sont utilisées pour lire et écrire de façon transparente les fichiers compressés bzip2 (.bz2).

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Types de ressources

## Pré-requis

Cette extension utilise les fonctions » bzip2 de la bibliothèque écrite par Julian Seward. Ce module nécessite bzip2/libbzip2, version >= 1.0.x.

## Installation

Le support bzip2 par PHP n'est pas activé par défaut. Il faut utiliser l'option de configuration --with-bz2[=DIR] lors de la compilation de PHP pour l'activer.

## Types de ressources

Cette extension définit un type de ressource : un pointeur de fichier identifiant le fichier bz2.

# Exemples

Cet exemple ouvre un fichier temporaire et y écrit une chaîne de test, puis, affiche le contenu de ce fichier.

Exemple #1 Petit exemple avec bzip2

    <?php

    $filename = "/tmp/testfile.bz2";
    $str = "Ceci est une chaîne de test.\n";

    // Ouvre un fichier en écriture
    $bz = bzopen($filename, "w");

    // Écrit une chaîne
    bzwrite($bz, $str);

    // Ferme le fichier
    bzclose($bz);

    // Ouvre le fichier en lecture
    $bz = bzopen($filename, "r");

    // Lit 10 caractères
    echo bzread($bz, 10);

    // Affiche jusqu'à la fin du fichier (ou les 1024 prochains caractères) et le ferme
    echo bzread($bz);

    bzclose($bz);

    ?>

# Bzip2 Fonctions

# bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzclose — Ferme un fichier bzip2

### Description

function bzclose(resource `$bz`): bool

bzclose() ferme le fichier bzip2 représenté par le pointeur `bz`.

### Liste de paramètres

`bz`
  Le pointeur de fichier. Il doit être valide et doit pointer vers un fichier ouvert avec succès par la fonction bzopen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- bzopen() - Ouvre un fichier compressé avec bzip2

# bzcompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcompress — Compresse une chaîne avec bzip2

### Description

function bzcompress(string `$data`, int `$block_size` = 4, int `$work_factor` = 0): string|int

bzcompress() compresse la chaîne `data` et retourne les données ainsi encodées.

### Liste de paramètres

`data`
  La chaîne à compresser.
`block_size`
  Spécifie la taille de bloc utilisée durant la compression et doit être un nombre de 1 à 9, sachant que 9 représente la meilleure compression, mais qu'elle utilise plus de ressources pour ce faire.
`work_factor`
  Contrôle le comportement de la compression dans les pires cas de données hautement répétitives. Cette valeur peut aller de 0 à 250 (0 est une valeur spéciale). Quelle que soit la valeur de `work_factor`, le résultat sera le même.

### Valeurs de retour

La chaîne compressée ou un numéro d'erreur si une erreur survient.

### Exemples

Exemple #1 Compression de données

    <?php
    $str = "donnée simple";
    $bzstr = bzcompress($str, 9);
    echo $bzstr;
    ?>

### Voir aussi

- bzdecompress() - Décompresse une chaîne bzip2

# bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompress — Décompresse une chaîne bzip2

### Description

function bzdecompress(string `$data`, bool `$use_less_memory` = `false`): string|int|false

bzdecompress() décompresse la chaîne `data`, contenant des données compressées bzip2.

### Liste de paramètres

`data`
  La chaîne à décompresser.
`use_less_memory`
  Si ce paramètre vaut `true`, un autre algorithme de décompression sera utilisé : il consomme moins de mémoire (le maximum demandé tombe autour de 2300 ko), mais fonctionne globalement à la moitié de la vitesse. Se reporter à la » documentation bzip2 pour plus de détails sur cette fonctionnalité.

### Valeurs de retour

La chaîne décompressée, ou `false`, ou un numéro d'erreur si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Le type de `use_less_memory` a été modifié de int à bool. Auparavant, la valeur par défaut était `0`.

### Exemples

Exemple #1 Décompression d'une chaîne

    <?php
    $start_str = "phrase à compresser";
    $bzstr = bzcompress($start_str);

    echo "Chaîne compressée : ";
    echo $bzstr;
    echo "\n<br />\n";

    $str = bzdecompress($bzstr);
    echo "Chaîne décompressée : ";
    echo $str;
    echo "\n<br />\n";
    ?>

### Voir aussi

- bzcompress() - Compresse une chaîne avec bzip2

# bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrno — Retourne le code d'erreur bzip2

### Description

function bzerrno(resource `$bz`): int

bzerrno() retourne le code d'erreur du fichier bz2 représenté par le pointeur `bz`.

### Liste de paramètres

`bz`
  Le pointeur de fichier. Il doit être valide et doit pointer vers un fichier ouvert avec succès avec la fonction bzopen().

### Valeurs de retour

Retourne le code d'erreur sous la forme d'un entier.

### Voir aussi

- bzerror() - Retourne le numéro et le message d'erreur bzip2 dans un tableau
- bzerrstr() - Retourne le message d'erreur bzip2

# bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerror — Retourne le numéro et le message d'erreur bzip2 dans un tableau

### Description

function bzerror(resource `$bz`): array

bzerror() retourne un tableau associatif avec le numéro et le message d'erreur du fichier bz2 représenté par le pointeur `bz`.

### Liste de paramètres

`bz`
  Le pointeur de fichier. Il doit être valide et doit pointer vers un fichier ouvert avec succès par la fonction bzopen().

### Valeurs de retour

Retourne un tableau associatif, avec le code d'erreur dans l'entrée `errno`, et le message d'erreur dans l'entrée `errstr`.

### Exemples

Exemple #1 Exemple avec bzerror()

    <?php
    $error = bzerror($bz);

    echo $error["errno"];
    echo $error["errstr"];
    ?>

### Voir aussi

- bzerrno() - Retourne le code d'erreur bzip2
- bzerrstr() - Retourne le message d'erreur bzip2

# bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstr — Retourne le message d'erreur bzip2

### Description

function bzerrstr(resource `$bz`): string

bzerrstr() retourne le message d'erreur du fichier bz2 représenté par le pointeur `bz`.

### Liste de paramètres

`bz`
  Le pointeur de fichier. Il doit être valide et doit pointer vers un fichier ouvert avec succès par la fonction bzopen().

### Valeurs de retour

Retourne une chaîne contenant le message d'erreur.

### Voir aussi

- bzerrno() - Retourne le code d'erreur bzip2
- bzerror() - Retourne le numéro et le message d'erreur bzip2 dans un tableau

# bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflush — Ne fait rien

### Description

function bzflush(resource `$bz`): bool

Cette fonction est censée forcer l'écriture de toutes les données bzip2 mises en tampon pour le pointeur de fichier représenté par `bz`, mais est implémentée comme une fonction nulle dans libbz2, et donc ne fait rien.

### Liste de paramètres

`bz`
  Le pointeur de fichier. Il doit être valide et doit pointer vers un fichier ouvert avec succès par la fonction bzopen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- bzread() - Lecture binaire d'un fichier bzip2
- bzwrite() - Écriture binaire dans un fichier bzip2

# bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopen — Ouvre un fichier compressé avec bzip2

### Description

function bzopen(string|resource `$file`, string `$mode`): resource|false

bzopen() ouvre un fichier bzip2 (.bz2) en écriture ou en lecture.

### Liste de paramètres

`file`
  Le nom du fichier à ouvrir ou une ressource de flux existante.
`mode`
  Les modes `'r'` (pour lecture), et `'w'` (pour écriture) sont supportés. Toute autre valeur fera que la fonction bzopen() retournera `false`.

### Valeurs de retour

Si l'ouverture échoue, bzopen() retourne `false`, sinon, elle retourne un pointeur vers le fichier ouvert.

### Exemples

Exemple #1 Exemple avec bzopen()

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Impossible d'ouvrir le fichier $file pour lecture");

    bzclose($bz);

    ?>

### Voir aussi

- bzclose() - Ferme un fichier bzip2

# bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzread — Lecture binaire d'un fichier bzip2

### Description

function bzread(resource `$bz`, int `$length` = 1024): string|false

bzread() lit depuis le pointeur de fichier bzip2 donné.

La lecture s'arrête lorsque `length` octets (non compressés) ont été lus ou si la fin du fichier est atteinte, le premier des deux qui survient.

### Liste de paramètres

`bz`
  Le pointeur de fichier. Il doit être valide et doit pointer vers un fichier ouvert avec succès par la fonction bzopen().
`length`
  Si non spécifié, bzread() lira 1024 octets (non compressés) à la fois. Un maximum de 8192 octets non compressés sera lu à la fois.

### Valeurs de retour

Retourne les données non compressées ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec bzread()

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Impossible d'ouvrir le fichier $file");

    $decompressed_file = '';
    while (!feof($bz)) {
      $decompressed_file .= bzread($bz, 4096);
    }
    bzclose($bz);

    echo "Le contenu du fichier $file est : <br />\n";
    echo $decompressed_file;

    ?>

### Voir aussi

- bzwrite() - Écriture binaire dans un fichier bzip2
- feof() - Teste la fin du fichier
- bzopen() - Ouvre un fichier compressé avec bzip2

# bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwrite — Écriture binaire dans un fichier bzip2

### Description

function bzwrite(resource `$bz`, string `$data`, ?int `$length` = `null`): int|false

bzwrite() écrit le contenu de la chaîne `data` dans le fichier bzip2 représenté par `bz`.

### Liste de paramètres

`bz`
  Le pointeur de fichier. Il doit être valide et doit pointer vers un fichier ouvert avec succès par la fonction bzopen().
`data`
  Les données écrites.
`length`
  Si fourni, l'écriture s'arrêtera après que `length` octets (non compressés) ont été écrits ou que la fin de `data` est atteinte, selon ce qui survient en premier.

### Valeurs de retour

Retourne le nombre d'octets écrits ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `length` est désormais nullable.

### Exemples

Exemple #1 Exemple avec bzwrite()

    <?php
    $str = "donnée non-compressée";
    $bz = bzopen("/tmp/foo.bz2", "w");
    bzwrite($bz, $str, strlen($str));
    bzclose($bz);
    ?>

### Voir aussi

- bzread() - Lecture binaire d'un fichier bzip2
- bzopen() - Ouvre un fichier compressé avec bzip2

## Sommaire

- bzclose — Ferme un fichier bzip2
- bzcompress — Compresse une chaîne avec bzip2
- bzdecompress — Décompresse une chaîne bzip2
- bzerrno — Retourne le code d'erreur bzip2
- bzerror — Retourne le numéro et le message d'erreur bzip2 dans un tableau
- bzerrstr — Retourne le message d'erreur bzip2
- bzflush — Ne fait rien
- bzopen — Ouvre un fichier compressé avec bzip2
- bzread — Lecture binaire d'un fichier bzip2
- bzwrite — Écriture binaire dans un fichier bzip2

- Installation/Configuration
  - Pré-requis
  - Installation
  - Types de ressources
- Exemples
- Bzip2 Fonctions
  - bzclose — Ferme un fichier bzip2
  - bzcompress — Compresse une chaîne avec bzip2
  - bzdecompress — Décompresse une chaîne bzip2
  - bzerrno — Retourne le code d'erreur bzip2
  - bzerror — Retourne le numéro et le message d'erreur bzip2 dans un tableau
  - bzerrstr — Retourne le message d'erreur bzip2
  - bzflush — Ne fait rien
  - bzopen — Ouvre un fichier compressé avec bzip2
  - bzread — Lecture binaire d'un fichier bzip2
  - bzwrite — Écriture binaire dans un fichier bzip2

# LZF

# Introduction

LZF est un algorithme de compression très rapide, idéal pour économiser de l'espace disque sans trop de perte de temps. Il peut être optimisé pour la vitesse ou pour la compression au moment de la compilation. Cette extension utilise la bibliothèque » liblzf créée par Marc Lehmann.

# Installation/Configuration

## Sommaire

- Installation

## Installation

Cette extension » PECL n'est pas intégrée à PHP. Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/lzf.

Pour utiliser ces fonctions, il faut compiler PHP avec le support lzf en utilisant l'option de configuration --with-lzf[=DIR]. Il est également possible de passer l'option --enable-lzf-better-compression pour optimiser LZF d'un point de vue d'espace au détriment de la vitesse.

Les utilisateurs de Windows doivent activer la bibliothèque php_lzf.dll dans le php.ini pour pouvoir utiliser ces fonctions.

# Fonctions LZF

# lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — Compression LZF

### Description

function lzf_compress(string `$data`): string

lzf_compress() compresse les données `data` en utilisant l'encodage LZF.

### Liste de paramètres

`data`
  La chaîne de caractères à compresser.

### Valeurs de retour

Retourne les données compressées ou `false` si une erreur survient.

### Voir aussi

- lzf_decompress() - Décompression LZF

# lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — Décompression LZF

### Description

function lzf_decompress(string `$data`): string

lzf_decompress() décompresse les données `data` en utilisant l'encodage LZF.

### Liste de paramètres

`data`
  La chaîne compressée.

### Valeurs de retour

Retourne les données décompressées ou `false` si une erreur survient.

### Voir aussi

- lzf_compress() - Compression LZF

# lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — Détermine le mode d'optimisation de l'extension LZF

### Description

function lzf_optimized_for(): int

Détermine le mode d'optimisation de l'extension LZF.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne 1 si LZF a été optimisé pour la vitesse, 0 pour la compression.

## Sommaire

- lzf_compress — Compression LZF
- lzf_decompress — Décompression LZF
- lzf_optimized_for — Détermine le mode d'optimisation de l'extension LZF

- Installation/Configuration
  - Installation
- Fonctions LZF
  - lzf_compress — Compression LZF
  - lzf_decompress — Décompression LZF
  - lzf_optimized_for — Détermine le mode d'optimisation de l'extension LZF

# Phar

# Introduction

L'extension phar fournit un moyen de mettre une application PHP complète dans un fichier unique appelé un "phar" (PHP Archive) pour une installation et une configuration aisées. En plus de ce service, l'extension fournit aussi une classe d'abstraction de format de fichier pour créer et manipuler des fichiers tar et zip à travers la classe PharData, tout comme PDO fournit une interface unifiée pour accéder à des bases de données différentes. Mais à l'inverse de PDO, qui ne peut pas transposer les données d'une base à l'autre, Phar a la possibilité de convertir des fichiers tar, zip et phar avec une simple ligne de code. Regardez Phar::convertToExecutable() pour avoir un exemple.

Qu'est-ce que phar? Les archives phar sont en fait un moyen pratique de grouper plusieurs fichiers en un seul. Ainsi, une archive phar permet de distribuer une application PHP complète dans un fichier unique et de l'exécuter à partir de ce fichier sans pour autant l'extraire sur le disque. De plus, des archives phar peuvent être exécutées par PHP aussi facilement que n'importe quel autre fichier, aussi bien en ligne de commande que via un serveur web. Phar est une sorte de clé USB pour les applications PHP.

Phar implémente cette fonctionnalité via un flux. Normalement, pour utiliser un fichier externe à partir d'un script PHP, il faut utiliser la fonction include:

Exemple #1 Utiliser un fichier externe

    <?php
     include '/chemin/vers/le/fichier/externe.php';
     ?>

On peut considérer que PHP traduit en fait `/chemin/vers/le/fichier/externe.php` en un flux `file:///chemin/vers/le/fichier/externe.php`, et qu'il utilise de façon cachée les fonctions de flux de fichiers plats pour accéder à des fichiers locaux.

Pour utiliser un fichier nommé `fichier.php` contenu dans une archive phar `/chemin/vers/monphar.phar`, la syntaxe est quasi similaire à la syntaxe `file://` ci-dessus.

Exemple #2 Utiliser un fichier contenu dans une archive phar

    <?php
     include 'phar:///chemin/vers/monphar.phar/fichier.php';
     ?>

En fait, on peut traiter une archive phar comme s'il s'agissait d'un disque externe, en utilisant n'importe laquelle des fonctions relatives à fopen(), opendir() et mkdir() pour lire, changer ou créer des nouveaux fichiers ou répertoires au sein de l'archive phar. Cela permet à des applications PHP complètes d'être distribuées dans un seul fichier et d'être exécutées à partir de celui-ci

L'utilisation la plus courante d'une archive phar est de distribuer une application complète en un seul fichier. Par exemple, l'installeur PEAR qui est inclus avec les versions de PHP est distribué grâce à une archive phar. Pour utiliser l'archive phar ainsi distribuée, celle-ci peut être exécutée via la ligne de commande ou via un navigateur web.

Les archives phar peuvent être distribuées sous forme de fichiers `tar`, de fichiers `zip` ou de fichiers `phar` spécialement conçus pour l'extension phar. Chaque format de fichier a ses avantages et ses inconvénients. Les fichiers zip et tar peuvent être extraits par n'importe quel outil tiers qui peut lire le format, mais requièrent l'extension phar pour être exécutés par PHP. Le format de fichier phar est unique et dédié à l'extension phar et peut être créé uniquement par celle-ci ou par le paquet PEAR » PHP_Archive, mais a l'avantage de ne pas nécessiter l'installation de l'extension phar pour que l'application empaquetée puisse être exécutée.

En d'autres mots, même avec l'extension phar désactivée, il est possible d'exécuter ou d'inclure une archive basée sur phar. Accéder à des fichiers individuels au sein d'une archive phar n'est possible qu'avec l'extension phar à moins que l'archive phar n'ait été créée par PHP_Archive.

L'extension phar est aussi capable de convertir une archive phar à partir d'un tar vers un fichier zip ou phar en une seule commande :

Exemple #3 Convertir une archive phar au format tar

    <?php
     $phar = new Phar('monphar.phar');
     $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // produit monphar.phar.tar.gz
     ?>

Phar peut compresser des fichiers individuels ou une archive entière en utilisant la compression gzip ou bzip2, et peut vérifier l'intégrité de l'archive automatiquement en utilisant des fonctions de signature MD5, SHA-1, SHA-256 ou SHA-512.

Enfin, l'extension phar est orientée sécurité, elle désactive par défaut les accès en écriture sur les archives phar exécutables et requiert la désactivation au niveau système du paramètre `phar.readonly` du php.ini pour créer ou modifier des archives phar. Des archives tar et zip sans le marqueur exécutable peuvent toujours être créées ou modifiées en utilisant la classe PharData.

Si l'on crée des applications dans le but de les distribuer, il est recommandé de lire Comment créer des archives Phar. Pour davantage d'informations sur les différences entre les formats de fichier que phar supporte, il est recommandé de lire Phar, Tar et Zip.

Lors de l'utilisation des applications phar, il y a des astuces très utiles dans Comment utiliser des archives Phar.

Le mot `phar` est la contraction de `PHP` et de `Archive` et est grandement inspiré du mot `jar` (Java Archive) familier aux développeurs Java.

L'implémentation des archives Phar est basée sur le paquet PEAR » PHP_Archive, et les détails d'implémentations sont les mêmes, bien que l'extension Phar soit plus puissante. En plus, celle-ci permet à la plupart des applications PHP d'être exécutées sans modification alors que les archives basées sur PHP_Archive requièrent souvent beaucoup de modifications pour fonctionner.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Il est possible d'éventuellement souhaiter activer les extensions zlib et bzip2 pour tirer parti du support phar compressé. De plus, pour exploiter les signatures OpenSSL, l'extension OpenSSL doit être activée.

Si zend.multibyte est activé, zend.detect_unicode doit aussi être activé.

## Installation

L'extension Phar est intégrée dans PHP, et activée par défaut. Pour désactiver le support de Phar, utiliser l'option de configuration --disable-phar.

Phar peut aussi être installé depuis l'extension PECL pour les versions précédentes de PHP, la » page PECL de Phar contient plus d'informations et l'historique.

## Configuration à l'exécution

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

Options de configuration pour le système de fichiers
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
phar.readonly | "1" | `INI_ALL` |
phar.require_hash | "1" | `INI_ALL` |
phar.cache_list | "" | `INI_SYSTEM` |

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

`phar.readonly` bool

  Cette option désactive la création ou la modification des archives Phar en utilisant le flux `phar` ou le support en écriture sur les objets Phar. Ce paramètre devrait toujours être activé sur des machines de production, car le support en écriture sur les archives phar pourrait mener à la création de virus basés sur PHP en cas d'utilisation conjuguée avec des vulnérabilités communes.

  > Note:

  > Ce paramètre ne peut être désactivé que dans php.ini pour des raisons de sécurité. Si `phar.readonly` est désactivé dans php.ini, l'utilisateur peut activer `phar.readonly` dans un script ou le désactiver plus tard. Si `phar.readonly` est activé dans php.ini, un script pourrait "réactiver" sans danger la variable INI, mais ne pourrait pas la désactiver.

`phar.require_hash` bool

  Cette option forcera toutes les archives Phar ouvertes à contenir un type de signature (à ce jour MD5, SHA1, SHA256, SHA512 et OpenSSL sont supportés), et toute archive Phar ne contenant pas de signature sera rejetée.

  > Note:

  > Ce paramètre ne peut être désactivé que dans php.ini. Si `phar.require_hash` est désactivé dans php.ini, l'utilisateur peut activer `phar.require_hash` dans un script ou le désactiver plus tard. Si `phar.require_hash` est activé dans php.ini, un script pourrait "réactiver" sans danger la variable INI, mais ne pourrait pas la désactiver.

  > Ce paramètre n'affecte pas la lecture des fichiers tar avec la classe PharData.

  Attention

  `phar.require_hash` ne fournit pas de sécurité en soi, c'est uniquement une mesure contre l'exécution accidentelle d'archives Phar corrompues, car quiconque peut trafiquer le Phar peut facilement corriger la signature après.

`phar.cache_list` string

  Permet aux correspondances d'archives phar d'être traitées au démarrage du serveur web, augmentant de ce fait les performances d'accès aux fichiers contenus dans une archive phar et les rendant très proche d'un accès à des fichiers d'une installation classique sur disque.

  Exemple #1 Exemple d'utilisation de phar.cache_list

      dans php.ini (windows):
      phar.cache_list =C:\chemin\vers\phar1.phar;C:\chemin\vers\phar2.phar
      dans php.ini (unix):
      phar.cache_list =/chemin/vers/phar1.phar:/chemin/vers/phar2.phar

## Types de ressources

L'extension Phar fournit le flux `phar`, qui permet l'accès de façon transparente aux fichiers contenus dans un phar. Pour davantage d'information, lisez le format de fichier Phar

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Les constantes de compression Phar
Constante | Valeur | Description
--- | --- | ---
`Phar::NONE` (int) | 0x00000000 | aucune compression
`Phar::COMPRESSED` (int) | 0x0000F000 | masque de bits pouvant être utilisé avec les drapeaux de fichier pour déterminer si une compression est utilisée
`Phar::GZ` (int) | 0x00001000 | compression zlib (gzip)
`Phar::BZ2` (int) | 0x00002000 | compression bzip2

Les constantes de format de fichier Phar
Constante | Valeur | Description
--- | --- | ---
`Phar::PHAR` (int) | 1 | format de fichier phar
`Phar::TAR` (int) | 2 | format de fichier tar
`Phar::ZIP` (int) | 3 | format de fichier zip

Les constantes de signature Phar
Constante | Valeur | Description
--- | --- | ---
`Phar::MD5` (int) | 0x0001 | signature avec l'algorithme md5
`Phar::SHA1` (int) | 0x0002 | signature avec l'algorithme sha1
`Phar::SHA256` (int) | 0x0003 | signature avec l'algorithme sha256 (requiert l'extension hash)
`Phar::SHA512` (int) | 0x0004 | signature avec l'algorithme sha512 (requiert l'extension hash)
`Phar::OPENSSL` (int) | 0x0010 | signature avec une paire de clé privée/publique OpenSSL. C'est une véritable signature à clé asymétrique.
`Phar::OPENSSL_SHA256` (int) |  |
`Phar::OPENSSL_SHA512` (int) |  |

Les constantes d'écrasement de mime Phar webPhar
Constante | Valeur | Description
--- | --- | ---
`Phar::PHP` (int) | 0 | utilisée pour renseigner le paramètre d'écrasement mime de Phar::webPhar() et faire en sorte que l'extension soit parsée comme un fichier PHP
`Phar::PHPS` (int) | 1 | utilisée pour renseigner le paramètre d'écrasement mime de Phar::webPhar() et faire en sorte que l'extension soit parsée comme un fichier PHP via highlight_file()

# Utiliser les archives Phar

## Sommaire

- Utiliser les archives Phar : Introduction
- Utiliser les archives Phar : le flux phar
- Utiliser les archives Phar : les classes Phar et PharData

## Utiliser les archives Phar : Introduction

Les archives Phar sont identiques dans le concept aux archives JAR de Java, mais sont conçues plus spécifiquement pour les besoins et la flexibilité des applications PHP. Une archive Phar est utilisée pour distribuer une application PHP complète ou une bibliothèque sous forme d'un fichier unique. Une application sous forme d'archive Phar est utilisée exactement de la même façon que n'importe quelle autre application PHP :

    php applicationsympa.phar

L'utilisation d'une bibliothèque sous forme d'archive Phar est la même que n'importe quelle autre bibliothèque PHP :

    <?php
    include 'bibliothequesympa.phar';
    ?>

Le flux `phar` fournit le cœur de l'extension phar, et est décrit en détails ici. Le flux phar permet l'accès aux fichiers contenus dans une archive phar via les fonctions standards de fichier fopen(), opendir(), et toute autre fonctionnant sur des fichiers normaux. Le flux `phar` supporte toutes les opérations de lecture/écriture à la fois sur les fichiers et sur les répertoires.

    <?php
    include 'phar://bibliothequesympa.phar/fichier/interne.php';
    header('Content-type: image/jpeg');
    // les phars peuvent être atteints via le chemin complet ou via des alias
    echo file_get_contents('phar:///chemin/complet/vers/bibliothequesympa.phar/images/wow.jpg');
    ?>

La classe Phar implémente des fonctionnalités avancées pour accéder aux fichiers et créer des archives phar. La classe Phar est décrite en détails ici.

    <?php
    try {
        // ouvre un phar existant
        $p = new Phar('bibliothequesympa.phar', 0);
        // Phar étend la classe DirectoryIterator de SPL
        foreach (new RecursiveIteratorIterator($p) as $file) {
            // $file est une classe PharFileInfo et hérité de SplFileInfo
            echo $file->getFileName() . "\n";
            echo file_get_contents($file->getPathName()) . "\n"; // affiche le contenu;
        }
        if (isset($p['fichier/interne.php'])) {
            var_dump($p['fichier/interne.php']->getMetadata());
        }

        // crée un nouveau phar - phar.readonly doit être à 0 dans php.ini
        // phar.readonly est activé par défaut pour des raisons de sécurité.
        // Sur des serveurs de production, les Phars n'ont pas besoin d'être créés,
        // juste d'être exécutés.
        if (Phar::canWrite()) {
            $p = new Phar('nouveauphar.tar.phar', 0, 'nouveauphar.tar.phar');
            // On crée une archive Phar basée sur tar, compressée par gzip (.tar.gz)
            $p = $p->convertToExecutable(Phar::TAR, Phar::GZ);

            // crée une transaction - rien n'est écrit dans nouveauphar.phar
            // jusqu'à ce que stopBuffering() ne soit appelé, bien qu'un stockage temporaire soit requis
            $p->startBuffering();
            // ajoute tous les fichiers de /chemin/vers/leprojet dans le phar avec le préfixe "projet"
            $p->buildFromIterator(new RecursiveIteratorIterator(new RecursiveDirectoryIterator('/chemin/vers/leprojet')), '/chemin/vers/');

            // ajoute un nouveau fichier en utilisant l'API d'accès par tableau
            $p['fichier1.txt'] = 'Information';
            $fp = fopen('grosfichier.dat', 'rb');
            // copie toutes les données du flux
            $p['data/grosfichier.dat'] = $fp;

            if (Phar::canCompress(Phar::GZ)) {
                $p['data/grosfichier.dat']->compress(Phar::GZ);
            }

            $p['images/wow.jpg'] = file_get_contents('images/wow.jpg');
            // toute valeur peut être sauvegardée comme métadonnée spécifique au fichier
            $p['images/wow.jpg']->setMetadata(array('mime-type' => 'image/jpeg'));
            $p['index.php'] = file_get_contents('index.php');
            $p->setMetadata(array('bootstrap' => 'index.php'));

            // sauvegarde l'archive phar sur le disque
            $p->stopBuffering();
        }
    } catch (Exception $e) {
        echo 'N\'a pas pu ouvrir le Phar: ', $e;
    }
    ?>

D'autre part, la vérification du contenu du fichier phar peut être faite en utilisant un des algorithme de signature symétrique (MD5, SHA1, SHA256 et SHA512 si ext/hash est activée) et en utilisant la signature asymétrique par clé publique/privée d'OpenSSL. Pour tirer parti de la signature OpenSSL, il faut générer une paire de clés publique/privée et utiliser la clé privée pour signer avec Phar::setSignatureAlgorithm(). En plus, la clé publique, extraite en utilisant ce code :

    <?php
    $public = openssl_get_publickey(file_get_contents('private.pem'));
    $pkey = '';
    openssl_pkey_export($public, $pkey);
    ?>

doit être sauvegardée à part de l'archive phar qu'elle vérifie. Si l'archive phar est sauvegardée en tant que `/chemin/vers/mon.phar`, la clé publique doit être sauvegardée en tant que `/chemin/vers/mon.phar.pubkey`, sans quoi phar ne sera pas capable de vérifier la signature OpenSSL.

La classe Phar fournit aussi trois méthodes statiques, Phar::webPhar(), Phar::mungServer() et Phar::interceptFileFuncs() qui sont cruciales pour empaqueter des applications PHP visant à être utilisée sur un système de fichiers classique ou en tant qu'application web. Phar::webPhar() implémente un contrôleur qui route les appels HTTP vers le bon endroit de l'archive phar. Phar::mungServer() est utilisé pour modifier les valeurs du tableau $_SERVER pour dire aux applications d'utiliser ces valeurs. Phar::interceptFileFuncs() dit à Phar d'intercepter les appels à fopen(), file_get_contents(), opendir(), et à toutes les fonctions basées sur stat (file_exists(), is_readable(), etc) et route tous les chemins relatifs vers les bons endroits de l'archive phar.

Par exemple, empaqueter une version de la célèbre application phpMyAdmin dans une archive phar nécessite juste ce simple script et, dès lors, `phpMyAdmin.phar.tar.php` peut être accédé comme un fichier classique à partir du serveur web, après avoir modifié le couple utilisateur/motdepasse :

    <?php
    @unlink('phpMyAdmin.phar.tar.php');
    copy('phpMyAdmin-2.11.3-english.tar.gz', 'phpMyAdmin.phar.tar.php');
    $a = new Phar('phpMyAdmin.phar.tar.php');
    $a->startBuffering();
    $a["phpMyAdmin-2.11.3-english/config.inc.php"] = '<?php
    /* Servers configuration */
    $i = 0;

    /* Server localhost (config:root) [1] */
    $i++;
    $cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
    $cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
    $cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
    $cfg[\'Servers\'][$i][\'compress\'] = false;
    $cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
    $cfg[\'Servers\'][$i][\'user\'] = \'root\';
    $cfg[\'Servers\'][$i][\'password\'] = \'\';

    /* End of servers configuration */
    if (strpos(PHP_OS, \'WIN\') !== false) {
        $cfg[\'UploadDir\'] = getcwd();
    } else {
        $cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
        @mkdir(\'/tmp/pharphpmyadmin\');
        @chmod(\'/tmp/pharphpmyadmin\', 0777);
    }';
    $a->setStub('<?php
    Phar::interceptFileFuncs();
    Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
    echo "phpMyAdmin is intended to be executed from a web browser\n";
    exit -1;
    __HALT_COMPILER();
    ');
    $a->stopBuffering();
    ?>

## Utiliser les archives Phar : le flux phar

Le flux Phar supporte totalement fopen() pour les lectures/écritures (pas les concaténations), unlink(), stat(), fstat(), fseek(), rename(), et les opérations de flux sur les répertoires opendir(), et rmdir() et mkdir().

La compression et les métadonnées individuelles par fichier peuvent aussi être manipulées au sein de l'archive Phar en utilisant les contextes de flux :

    <?php
    $context = stream_context_create(array('phar' =>
                                        array('compress' => Phar::GZ)),
                                        array('metadata' => array('user' => 'cellog')));
    file_put_contents('phar://mon.phar/unfichier.php', 0, $context);
    ?>

Le flux `phar` n'agit pas sur les fichiers distants et ne peut pas considérer les fichiers distants, etc. même si les options INI allow_url_fopen et allow_url_include sont désactivées.

Bien qu'il soit possible de créer des archives phar de zéro en utilisant juste les opérations sur les flux, il est préférable d'utiliser la fonctionnalité incluse dans la classe Phar. Le flux est mieux utilisé pour les opérations de lecture.

## Utiliser les archives Phar : les classes Phar et PharData

La classe Phar supporte la lecture et la manipulation des archives Phar, ainsi que l'itération à travers la fonctionnalité héritée de la classe RecursiveDirectoryIterator. Avec le support de l'interface ArrayAccess, les fichiers contenus dans une archive Phar peuvent être accédés comme s'ils étaient membres d'un tableau associatif.

La classe PharData étend la classe Phar, et permet la création et la modification d'archives tar et zip non exécutables (données) même si `phar.readonly`=1 dans php.ini. Ainsi, PharData::setAlias() et PharData::setStub() sont toutes deux désactivées car les concepts d'alias et de conteneur sont restreints aux archives phar exécutables.

Il est important de noter que quand une archive Phar est créée, le chemin complet doit être passé au constructeur de l'objet Phar. Un chemin relatif empêcherait l'initialisation.

En supposant que `$p` est un objet initialisé de cette façon :

    <?php
    $p = new Phar('/chemin/vers/monphar.phar', 0, 'monphar.phar');
    ?>

Une archive Phar vide sera créée en tant que `/chemin/vers/monphar.phar`, ou si `/chemin/vers/monphar.phar` existe déjà, il sera ouvert de nouveau. Le terme `monphar.phar` démontre le concept d'un alias qui peut être utilisé pour référencer `/chemin/vers/monphar.phar` dans des URL comme ceci :

    <?php
    // ces deux appels à file_get_contents() sont équivalents si
    // /chemin/vers/monphar.phar a un alias explicite de "monphar.phar"
    // dans son manifeste, ou si le phar a été initialisé avec l'instantiation de
    // l'objet Phar de l'exemple précédent
    $f = file_get_contents('phar:///chemin/vers/monphar.phar/nimportequoi.txt');
    $f = file_get_contents('phar://monphar.phar/nimportequoi.txt');
    ?>

Avec l'objet Phar `$p` nouvellement créé, les choses suivantes sont possibles :

- `$a = $p['fichier.php']` crée une PharFileInfo qui réfère au contenu de `phar://monphar.phar/fichier.php`
- `$p['fichier.php'] = $v` crée un nouveau fichier (`phar://monphar.phar/fichier.php`), ou écrase un fichier existant au sein de `monphar.phar`. `$v` peut être soit une chaîne ou un pointeur vers un fichier ouvert, dans quel cas le contenu du fichier sera utilisé pour créer le nouveau fichier. À noter que `$p->addFromString('fichier.php', $v)` est équivalent en termes de fonctionnalité au cas ci-dessus. Il est aussi possible d'ajouter le contenu d'un fichier avec `$p->addFile('/chemin/vers/fichier.php', 'fichier.php')`. Enfin, un répertoire vide peut être créé avec `$p->addEmptyDir('vide')`.
- `isset($p['fichier.php'])` peut être utilisé pour déterminer si `phar://monphar.phar/fichier.php` existe au sein de `monphar.phar`.
- `unset($p['fichier.php'])` efface `phar://monphar.phar/fichier.php` de `monphar.phar`.

De plus, l'objet Phar est le seul moyen d'accéder aux métadonnées spécifiques de Phar, via Phar::getMetadata(), et c'est aussi le seul moyen de régler ou de récupérer le conteneur du chargeur de l'archive Phar via Phar::getStub() et Phar::setStub(). De plus, la compression pour l'archive Phar entière peut être manipulée seulement via la classe Phar.

La liste complète des fonctionnalités de l'objet Phar est documentée ci-dessous.

La classe PharFileInfo étend la classe SplFileInfo et ajoute plusieurs méthodes pour manipuler les métadonnées spécifiques à Phar d'un fichier contenu dans un Phar, telles que manipuler la compression ou les métadonnées.

# Créer des archives Phar

## Sommaire

- Créer des archives Phar : Introduction

## Créer des archives Phar : Introduction

Sera entièrement écrit plus tard. Avant de lire ceci, soyez sûr de lire Comment utiliser des archives Phar.

Se documenter sur Phar::buildFromIterator() et les spécificités des choix de format de fichier disponibles pour les archives peut être un bon début. Une bonne compréhension de ce qu'est et de ce que fait un conteneur (stub) est cruciale pour la création d'archive phar, ce qui fait de Phar::setStub() et Phar::createDefaultStub() également un bon point de départ. Si l'on distribue des applications web, il est important de connaître Phar::webPhar() et la méthode associée Phar::mungServer(). Toute application qui accède à ses propres fichiers devrait aussi considérer l'utilisation de Phar::interceptFileFuncs().

# Qu'est-ce qui fait d'un phar un phar et pas un tar ou un zip ?

## Sommaire

- Les constituants de toutes les archives Phar, indépendamment du format de fichier
- Le conteneur de fichier Phar
- Comparaison entre Phar, Tar et Zip
- Les phars basés sur Tar
- Les phars basés sur Zip
- Le format de fichier Phar
- Drapeaux "bitmappés" globaux du Phar
- Définition des entrées du manifeste Phar
- Phar Signature format

## Les constituants de toutes les archives Phar, indépendamment du format de fichier

Toutes les archives Phar contiennent de trois à quatre sections:

1. Un conteneur

2. Un manifeste décrivant le contenu

3. Le contenu du fichier

4. Une signature (facultative) pour vérifier l'intégrité (uniquement avec le format de fichier phar)

## Le conteneur de fichier Phar

Un conteneur Phar est un simple fichier PHP. Le conteneur minimal contient :

    <?php __HALT_COMPILER();

Un conteneur doit contenir au moins le jeton `__HALT_COMPILER();` en guise de conclusion. Typiquement, un conteneur comportera les fonctionnalités de chargement suivantes :

    <?php
    Phar::mapPhar();
    include 'phar://monphar.phar/index.php';
    __HALT_COMPILER();

Il n'y a aucune restriction sur le contenu d'un conteneur Phar, si ce n'est le besoin d'être conclu par `__HALT_COMPILER();`. Le tag fermant PHP ``

    ?>

peut être inclus ou omis, mais il ne peut y avoir plus d'un espace entre le `;` et le tag fermant `

    ?>

` sans quoi l'extension phar ne sera pas capable de lire le manifeste de l'archive.

Dans une archive phar basée sur tar ou zip, le conteneur est stocké dans le fichier `.phar/stub.php`. Le conteneur par défaut des archives Phar basées sur phar contient approximativement 7ko de code pour extraire le contenu du phar et l'exécuter. Regardez la fonction Phar::createDefaultStub() pour davantage de détails.

L'alias phar est stocké, dans le cas d'une archive phar basée sur tar ou zip, dans le fichier `.phar/alias.txt` en tant que texte plein.

## Comparaison entre Phar, Tar et Zip

Quels sont les avantages et les inconvénients de chacun des trois formats supportés par l'extension phar ? Ce tableau tente de répondre à cette question.

Tableau comparatif : Phar, Tar et Zip
Fonctionnalité | Phar | Tar | Zip
--- | --- | --- | ---
Format de fichier standard | Non | Oui | Oui
Peut être exécuté sans l'extension Phar [1] | Oui | Non | Non
Compression par fichier | Oui | Non | Oui
Compression pour toute l'archive | Oui | Oui | Non
Validation par signature de toute l'archive | Oui | Oui | Oui
Support d'applications spécifiquement Web | Oui | Oui | Oui
Métadonnées par fichier | Oui | Oui | Oui
Métadonnées pour toute l'archive | Oui | Oui | Oui
Création/modification d'archive [2] | Oui | Oui | Oui
Support complet de toutes les fonctions de flux | Oui | Oui | Oui
Peut être créée/modifiée même si phar.readonly=1 [3] | Non | Oui | Oui

Astuce

[1] PHP ne peut accéder directement au contenu d'une archive Phar sans que l'extension Phar soit installée si elle utilise un `conteneur` qui extrait le contenu de l'archive phar. Le conteneur créé par Phar::createDefaultStub() extrait l'archive phar et exécute son contenu à partir d'un répertoire temporaire si aucune extension phar n'est trouvée.

Astuce

[2] Tous les accès en écriture nécessitent que `phar.readonly` soit désactivé dans le php.ini ou directement via la ligne de commande.

Astuce

[3] Seules les archives tar ou zip sans `.phar` dans leur nom et sans conteneur exécutable `.phar/stub.php` peuvent être créées si phar.readonly=1.

## Les phars basés sur Tar

Les archives basées sur le format de fichier tar sont conformes au format moderne USTAR. Le design des en-têtes du fichier tar le rend plus efficace que le format de fichier zip et aussi efficace que le format de fichier phar quand il s'agit d'accéder aux données. Les noms de fichiers sont limités à 255 octets, y compris le chemin complet au sein de l'archive phar basée sur tar. Ces archives peuvent être intégralement compressées au format gzip ou bzip2 tout en restant exécutables par l'extension Phar.

Il y a un support limité pour lire les tarballs dans le format pax interchange, mais tous les en-têtes pax reconnus (actuellement, typeflag `x` et `g`) sont silencieusement ignorés. Il y a aussi un support limité pour les GNU Tar Archives; actuellement, les en-têtes `././@LongLink` sont résolus.

Pour compresser une archive entière, utiliser Phar::compress(). Pour décompresser une archive entière, utiliser Phar::decompress().

## Les phars basés sur Zip

Les archives basées sur le format de fichier zip supportent de nombreuses fonctionnalités incluses dans le format zip. Les métadonnées par fichier ou sur toute l'archive sont stockées dans les commentaires du fichier zip et de l'archive zip en tant que chaîne de caractères sérialisée. Les commentaires zip déjà existants seront lus sans problème en tant que chaîne. Les lectures/écritures compressées sont supportées par la compression zlib DEFLATE, et uniquement les lectures compressées par la compression bzip2. Il n'y a pas de limite sur le nombre de fichiers au sein d'une archive phar basée sur zip. Les répertoires vides sont stockés dans l'archive zip comme des fichiers avec un slash final, comme `mon/repertoire/`

## Le format de fichier Phar

Le format de fichier phar est composé de conteneur/manifeste/contenu/signature, et stocke les informations cruciales de ce qui est contenu dans l'archive phar dans son `manifeste`.

Le manifeste Phar est un format hautement optimisé qui permet la spécification fichier par fichier de la compression, des permissions et même des métadonnées utilisateur tels que l'utilisateur ou le groupe propriétaire. Toutes les valeurs de plus d'un octet sont stockées sous forme petit-boutiste, à l'exception de la version de l'API qui est stockée pour des raisons historiques en 3 morceaux grand-boutistes.

Tous les drapeaux non utilisés sont réservés pour un usage futur et ne doivent pas être utilisés pour stocker des informations personnalisées. Utiliser les métadonnées par fichier pour stocker des métadonnées personnalisées sur des fichiers particuliers.

Le format de fichier basique du manifeste d'une archive Phar est le suivant :

Format global du manifeste Phar
Taille en octets | Description
--- | ---
4 octets | Longueur du manifeste en octets (limitée à 1 Mo)
4 octets | Nombre de fichiers dans le Phar
2 octets | Version de l'API du manifeste Phar (à ce jour 1.0.0)
4 octets | Drapeaux "bitmappés" globaux du Phar
4 octets | Longueur de l'alias Phar
?? | L'alias Phar (longueur basée sur la valeur précédente)
4 octets | Longueur des métadonnées Phar (`0` si aucune)
?? | métadonnées Phar sérialisées, stockées dans un format serialize()
au moins 24 * nombre d'octets des entrées | Entrées pour chaque fichier

## Drapeaux "bitmappés" globaux du Phar

Voici les drapeaux "bitmappés" actuellement reconnus par l'extension Phar pour le bitmap plein global de Phar :

Valeurs de bitmap reconnues
Valeur | Description
--- | ---
`0x00010000` | Si présent, le Phar contient une signature de vérification
`0x00001000` | Si présent, le Phar contient au moins 1 fichier qui est compressé grâce à zlib DEFLATE
`0x00002000` | Si présent, le Phar contient au moins 1 fichier qui est compressé grâce à bzip2

## Définition des entrées du manifeste Phar

Chaque fichier du manifeste contient les informations suivantes :

Entrée du manifeste Phar
Taille en octets | Description
--- | ---
4 octets | Longueur du nom de fichier en octets
?? | Nom de fichier (longueur basée sur la valeur précédente)
4 octets | Taille du fichier décompressé en octets
4 octets | Timestamp Unix du fichier
4 octets | Taille du fichier compressé en octets
4 octets | Somme de contrôle CRC32 du contenu décompressé du fichier
4 octets | Drapeaux bitmappés spécifiques au fichier
4 octets | Longueur des métadonnées du fichier sérialisées (`0` si aucune)
?? | métadonnées du fichier sérialisées, stockées dans un format serialize()

À noter qu'à partir de l'API 1.1.1, les répertoires vides sont stockés comme des noms de fichier avec un slash final comme `mon/repertoire/`

Les valeurs reconnues de drapeaux bitmappés spécifiques au fichier sont :

Valeurs reconnues de bitmap
Valeur | Description
--- | ---
`0x000001FF` | Ces bits sont réservés pour définir des permissions spécifiques au fichier. Celles-ci sont utilisées pour fstat() et peuvent être utilisées pour recréer les permissions souhaitées en cas d'extraction.
`0x00001000` | Si présent, le fichier est compressé grâce à zlib DEFLATE
`0x00002000` | Si présent, le fichier est compressé grâce à bzip2

## Phar Signature format

Les Phar qui contiennent une signature ont toujours la signature ajoutée à la fin du Phar, après le chargeur, le manifeste et le contenu. Les types de signature supportés à ce jour sont MD5, SHA1, SHA256, SHA512, et OPENSSL.

Format de signature
Longueur en octets | Description
--- | ---
variant | La signature actuelle, 20 octets pour une SHA1, 16 octets pour une MD5, 32 octets pour une SHA256, et 64 octets pour une SHA512. La longueur d'une signature OPENSSL dépend de la taille de la clé privée.
4 octets | Les drapeaux de signature. `0x0001` est utilisé pour définir une signature MD5, `0x0002` pour une SHA1, `0x0003` pour une SHA256 et `0x0004` pour une SHA512. Le support des signatures SHA256 et SHA512 est disponible à partir de la version 1.1.0 de l'API. `0x0010` est utilisé pour définir une signature OPENSSL, qui est disponible à partir de la version 1.1.1 de l'API, si OpenSSL est disponible.
4 octets | `GBMB` magique utilisé pour définir la présence d'une signature.

# La classe Phar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Introduction

La classe Phar fournit une interface de haut niveau pour accéder et créer des archives phar.

## Synopsis de la classe

class Phar extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Constantes héritées */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Constantes */
const int BZ2;
const int GZ;
const int NONE;
const int PHAR;
const int TAR;
const int ZIP;
const int COMPRESSED;
const int PHP;
const int PHPS;
const int MD5;
const int OPENSSL;
const int OPENSSL_SHA256;
const int OPENSSL_SHA512;
const int SHA1;
const int SHA256;
const int SHA512;
/* Méthodes */
public function __construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
final public static function apiVersion(): string
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
final public static function canCompress(int `$compression` = 0): bool
final public static function canWrite(): bool
public function compress(int `$compression`, ?string `$extension` = `null`): ?Phar
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function count(int `$mode` = `COUNT_NORMAL`): int
final public static function createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string
public function decompress(?string `$extension` = `null`): ?Phar
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function getAlias(): ?string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getModified(): bool
public function getPath(): string
public function getSignature(): array|false
public function getStub(): string
final public static function getSupportedCompression(): array
final public static function getSupportedSignatures(): array
public function getVersion(): string
public function hasMetadata(): bool
final public static function interceptFileFuncs(): void
public function isBuffering(): bool
public function isCompressed(): int|false
public function isFileFormat(int `$format`): bool
final public static function isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool
public function isWritable(): bool
final public static function loadPhar(string `$filename`, ?string `$alias` = `null`): bool
final public static function mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool
final public static function mount(string `$pharPath`, string `$externalPath`): void
final public static function mungServer(array `$variables`): void
public function offsetExists(string `$localName`): bool
public function offsetGet(string `$localName`): SplFileInfo
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
final public static function running(bool `$returnPhar` = `true`): string
public function setAlias(string `$alias`): true
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function startBuffering(): void
public function stopBuffering(): void
final public static function unlinkArchive(string `$filename`): true
final public static function webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void
public function __destruct()
/* Méthodes héritées */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

## Historique

Version | Description
--- | ---
8.4.0 | Ajout de la prise en charge de l'extension de timestamp Unix pour les archives basées sur Zip.
8.0.0 | Les métadonnées ne sont plus désérialisées lors de l’ouverture de l’archive, mais leur désérialisation est différée jusqu’à l’appel de Phar::getMetadata().

## Notes

Attention

Antérieur à PHP 8.0.0, les métadonnées étaient désérialisées lors de l’ouverture de l’archive, ce qui pouvait entraîner des failles de sécurité. À partir de PHP 8.0.0, les métadonnées ne sont désérialisées que lors de l’appel à Phar::getMetadata(), lequel offre des options permettant de restreindre la désérialisation pour des raisons de sécurité.

# Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addEmptyDir — Ajoute un répertoire vide à l'archive phar

### Description

public function Phar::addEmptyDir(string `$directory`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Grâce à cette méthode, un répertoire vide est créé avec le chemin `dirname`. Cette méthode est identique à ZipArchive::addEmptyDir().

### Liste de paramètres

`directory`

  Le nom du répertoire vide à créer dans l'archive phar

### Valeurs de retour

pas de valeur de retour, une exception est levée en cas d'échec.

### Exemples

Exemple #1 Un exemple avec Phar::addEmptyDir()

    <?php
    try {
        $a = new Phar('/chemin/vers/phar.phar');

        $a->addEmptyDir('/chemin/complet/vers/fichier');
        // démontre comment le fichier est stocké
        $b = $a['chemin/complet/vers/fichier']->isDir();
    } catch (Exception $e) {
        // traite les erreurs ici
    }
    ?>

### Voir aussi

- PharData::addEmptyDir() - Ajoute un répertoire vide à l'archive tar/zip
- Phar::addFile() - Ajoute un fichier du système de fichiers à l'archive phar
- Phar::addFromString() - Ajoute un fichier depuis une chaîne de caractères à l'archive phar

# Phar::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFile — Ajoute un fichier du système de fichiers à l'archive phar

### Description

public function Phar::addFile(string `$filename`, ?string `$localName` = `null`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Grâce à cette méthode, tout fichier ou URL peut être ajouté à l'archive phar. Si le second paramètre optionnel `localName` est une chaîne de caractères, le fichier sera stocké dans l'archive de ce nom, sinon le paramètre `filename` est utilisé comme chemin vers lequel stocker l'archive. Les URL doivent avoir un nom local, sans quoi une exception est levée. Cette méthode est identique à ZipArchive::addFile().

### Liste de paramètres

`filename`

  Chemin absolu ou relatif vers un fichier du disque à ajouter à l'archive phar.

`localName`

  Chemin où le fichier sera stocké dans l'archive.

### Valeurs de retour

Pas de valeur de retour, une exception est levée en cas d'échec.

### Historique

Version | Description
--- | ---
8.0.0 | `localName` est désormais nullable.

### Exemples

Exemple #1 Un exemple avec Phar::addFile()

    <?php
    try {
        $a = new Phar('/chemin/vers/phar.phar');

        $a->addFile('/chemin/complet/vers/fichier');
        // démontre comment le fichier est stocké
        $b = $a['chemin/complet/vers/fichier']->getContent();

        $a->addFile('/chemin/complet/vers/fichier', 'mon/fichier.txt');
        $c = $a['mon/fichier.txt']->getContent();

        // démontre l'utilisation d'URL
        $a->addFile('http://www.exemple.com', 'exemple.html');
    } catch (Exception $e) {
        // traite les erreurs ici
    }
    ?>

### Notes

> Note: Phar::addFile(), Phar::addFromString() et Phar::offsetSet() enregistre une nouvelle archive phar à chaque fois qu'elles sont appelées. Si les performances sont une préoccupation, Phar::buildFromDirectory() ou Phar::buildFromIterator() devraient être utilisé à la place.

### Voir aussi

- Phar::offsetSet() - Met le contenu d'un fichier interne à l'archive à l'identique du contenu d'un fichier externe
- PharData::addFile() - Ajoute un fichier du système de fichiers à l'archive tar/zip
- Phar::addFromString() - Ajoute un fichier depuis une chaîne de caractères à l'archive phar
- Phar::addEmptyDir() - Ajoute un répertoire vide à l'archive phar

# Phar::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFromString — Ajoute un fichier depuis une chaîne de caractères à l'archive phar

### Description

public function Phar::addFromString(string `$localName`, string `$contents`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Grâce à cette méthode, toute chaîne peut être ajoutée à l'archive phar. Le fichier sera stocké dans l'archive avec `localname` en tant que chemin. Cette méthode est identique à ZipArchive::addFromString().

### Liste de paramètres

`localName`

  Chemin dans lequel le fichier sera stocké dans l'archive.

`contents`

  Le contenu de fichier à stocker

### Valeurs de retour

Pas de valeur de retour, une exception est levée en cas d'échec.

### Exemples

Exemple #1 Un exemple avec Phar::addFromString()

    <?php
    try {
        $a = new Phar('/chemin/vers/phar.phar');

        $a->addFromString('chemin/vers/fichier.txt', 'mon fichier simple');
        $b = $a['chemin/vers/fichier.txt']->getContent();

        // pour ajouter du contenu à partir d'un descripteur de flux pour des gros fichiers, utiliser offsetSet()
        $c = fopen('/chemin/vers/grosfichier.bin');
        $a['grosfichier.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // traite les erreurs ici
    }
    ?>

### Notes

> Note: Phar::addFile(), Phar::addFromString() et Phar::offsetSet() enregistre une nouvelle archive phar à chaque fois qu'elles sont appelées. Si les performances sont une préoccupation, Phar::buildFromDirectory() ou Phar::buildFromIterator() devraient être utilisé à la place.

### Voir aussi

- Phar::offsetSet() - Met le contenu d'un fichier interne à l'archive à l'identique du contenu d'un fichier externe
- PharData::addFromString() - Ajoute un fichier à partir d'une chaîne de caractères à l'archive tar/zip
- Phar::addFile() - Ajoute un fichier du système de fichiers à l'archive phar
- Phar::addEmptyDir() - Ajoute un répertoire vide à l'archive phar

# Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::apiVersion — Retourne la version de l'API

### Description

final public static function Phar::apiVersion(): string

Retourne la version de l'API du format de fichier phar qui sera utilisée pour la création de phars. L'extension Phar supporte la lecture des versions d'API 1.0.0 et supérieures. L'API version 1.1.0 est requise pour les hachages SHA-256 et SHA-512, et l'API version 1.1.1 est requise pour stocker des répertoires vides.

### Liste de paramètres

### Valeurs de retour

La version de l'API, par exemple `"1.0.0"`.

### Exemples

Exemple #1 Un exemple avec Phar::apiVersion()

    <?php
    echo Phar::apiVersion();
    ?>

L'exemple ci-dessus va afficher :

    1.1.1

# Phar::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromDirectory — Construit une archive phar à partir des fichiers d'un répertoire

### Description

public function Phar::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Remplit une archive phar à partir du contenu d'un répertoire. Le second paramètre, optionnel, est une expression rationnelle (pcre) utilisée pour exclure des fichiers. Tout fichier dont le nom satisfait l'expression rationnelle sera inclus, les autres seront exclus. Pour un contrôle plus fin, utiliser Phar::buildFromIterator().

### Liste de paramètres

`directory`

  Le chemin absolu ou relatif vers le répertoire contenant tous les fichiers à ajouter à l'archive.

`pattern`

  Une expression rationnelle optionnelle utilisée pour filtrer la liste des fichiers. Seuls les fichiers dont le nom satisfait l'expression rationnelle seront inclus dans l'archive.

### Valeurs de retour

Phar::buildFromDirectory() retourne un tableau associatif faisant correspondre le chemin interne du fichier avec le chemin complet sur le système de fichiers.

### Erreurs / Exceptions

Cette méthode lève une exception BadMethodCallException quand elle est incapable d'instancier l'itérateur de répertoire interne, ou une exception PharException s'il y a eu des erreurs lors de la sauvegarde de l'archive.

### Historique

Version | Description
--- | ---
8.1.0 | Phar::buildFromDirectory() ne retourne plus `false`.

### Exemples

Exemple #1 Un exemple avec Phar::buildFromDirectory()

    <?php
    // crée avec l'alias "projet.phar"
    $phar = new Phar('projet.phar', 0, 'projet.phar');
    // ajoute des fichiers dans le projet
    $phar->buildFromDirectory(dirname(__FILE__) . '/projet');
    $phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php'));

    $phar2 = new Phar('projet2.phar', 0, 'projet2.phar');
    // ajoute tous les fichiers dans le projet, mais juste les fichiers .php
    $phar->buildFromDirectory(dirname(__FILE__) . '/projet', '/\.php$/');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

### Voir aussi

- Phar::buildFromIterator() - Construit une archive phar à partir d'un itérateur

# Phar::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromIterator — Construit une archive phar à partir d'un itérateur

### Description

public function Phar::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Remplit une archive phar à partir d'un itérateur. Deux styles d'itérateur sont supportés : les itérateurs qui font correspondre le nom de fichier au sein du phar avec le nom d'un fichier sur le disque, et les itérateurs comme DirectoryIterator qui retournent des objets SplFileInfo. Pour les itérateurs qui retournent des objets SplFileInfo, le second paramètre est obligatoire.

### Liste de paramètres

`iterator`

  Un itérateur qui associe un fichier avec une position, ou bien retourne des objets SplFileInfo.

`baseDirectory`

  Pour les itérateurs qui retournent des objets SplFileInfo, la portion de chemin absolu de chaque fichier qu'il faut supprimer lors de l'ajout à l'archive phar.

### Valeurs de retour

Phar::buildFromIterator() retourne un tableau associatif qui associe la représentation interne du fichier à un chemin absolu dans le système.

### Erreurs / Exceptions

Cette méthode émet une exception UnexpectedValueException quand l'itérateur retourne des valeurs fausses, telles qu'une clé entière à la place d'une chaîne ; une exception BadMethodCallException quand un itérateur basé sur SplFileInfo est passé sans paramètre `baseDirectory`, ou une exception PharException s'il y a eu des erreurs lors de la sauvegarde de l'archive phar.

### Historique

Version | Description
--- | ---
8.1.0 | Phar::buildFromIterator() ne retourne plus `false` désormais.
8.0.0 | `baseDirectory` est désormais nullable.

### Exemples

Exemple #1 Exemple avec Phar::buildFromIterator() et SplFileInfo

Pour la plupart des archives phar, l'archive reflète l'arborescence d'un répertoire, et le second style est le plus utile. Par exemple, pour créer une archive phar contenant les fichiers de l'arborescence du répertoire :

    /chemin/vers/projet/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         file1.php
                         file2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

Ce code peut être utilisé pour ajouter à l'archive "projet.phar" :

    <?php
    // crée avec l'alias "projet.phar"
    $phar = new Phar('projet.phar', 0, 'projet.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/chemin/vers/projet')),
        '/chemin/vers/projet');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

Le fichier projet.phar peut alors être utilisé immédiatement. Phar::buildFromIterator() ne règle pas les paramètres tels que la compression ou les métadonnées ; ceci peut cependant être fait après avoir créé l'archive phar.

Il est intéressant de noter que Phar::buildFromIterator() peut aussi être utilisé pour copier les éléments d'une archive phar existante, car l'objet Phar hérite de DirectoryIterator :

    <?php
    // crée avec l'alias "projet.phar"
    $phar = new Phar('projet.phar', 0, 'projet.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/chemin/vers/unautrephar.phar')),
        'phar:///chemin/vers/unautrephar.phar/chemin/vers/projet');
    $phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php'));
    ?>

Exemple #2 Exemple avec Phar::buildFromIterator() et d'autres itérateurs

La seconde forme d'itérateur peut être utilisée avec n'importe quel itérateur qui retourne une correspondance clé => valeur, tels que ArrayIterator :

    <?php
    // crée avec l'alias "projet.phar"
    $phar = new Phar('projet.phar', 0, 'projet.phar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'interne/fichier.php' => dirname(__FILE__) . '/unfichier.php',
            'unautre/fichier.jpg' => fopen('/chemin/vers/grosfichier.jpg', 'rb'),
         )));
    $phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php'));
    ?>

### Voir aussi

- Phar::buildFromDirectory() - Construit une archive phar à partir des fichiers d'un répertoire

# Phar::canCompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canCompress — Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2

### Description

final public static function Phar::canCompress(int `$compression` = 0): bool

Cette méthode doit être utilisée pour déterminer si la compression est possible avant de charger une archive phar qui contient des fichiers compressés.

### Liste de paramètres

`compression`

  `Phar::GZ` et `Phar::BZ2` peuvent être utilisées pour déterminer si la compression est possible avec respectivement zlib ou bzip2.

### Valeurs de retour

`true` si la compression/décompression est disponible, `false` sinon.

### Exemples

Exemple #1 Un exemple avec Phar::canCompress()

    <?php
    if (Phar::canCompress()) {
        echo file_get_contents('phar://pharcompresse.phar/interne/fichier.txt');
    } else {
        echo 'compression non disponible';
    }
    ?>

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- Phar::convertToExecutable() - Convertit une archive phar vers un autre format de fichier d'archive phar exécutable
- Phar::convertToData() - Convertit une archive phar en un fichier non-exécutable

# Phar::canWrite

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canWrite — Détermine si l'extension phar supporte la création et l'écriture des phars

### Description

final public static function Phar::canWrite(): bool

Cette méthode statique détermine si l'accès en écriture a été désactivé dans le php.ini du système via la variable INI phar.readonly.

### Liste de paramètres

### Valeurs de retour

`true` si l'accès en écriture est possible, `false` sinon.

### Exemples

Exemple #1 Un exemple avec Phar::canWrite()

    <?php
    if (Phar::canWrite()) {
        file_put_contents('phar://monphar.phar/fichier.txt', 'coucou');
    }
    ?>

### Voir aussi

- phar.readonly
- Phar::isWritable() - Retourne true si l'archive phar peut être modifiée

# Phar::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compress — Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2

### Description

public function Phar::compress(int `$compression`, ?string `$extension` = `null`): ?Phar

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Dans le cas des archives phar basées sur tar ou sur phar, cette méthode compresse l'archive complète en utilisant la compression gzip ou bzip2. Le fichier qui en résulte peut être traité avec la commande gzip/bzip2, ou accédé directement et de façon transparente avec l'extension Phar.

Dans le cas des archives phar basées sur Zip, cette méthode échoue en lançant une exception. L'extension zlib doit être activée pour compresser avec gzip, tandis que l'extension bzip2 doit être activée pour compresser avec bzip2. Comme avec toutes les fonctionnalités qui modifient le contenu d'un phar, la variable INI phar.readonly doit être à off pour fonctionner.

En plus, cette méthode renomme automatiquement l'archive, en ajoutant à son nom `.gz`, `.bz2` ou en enlevant l'extension si `Phar::NONE` est passée pour supprimer la compression. Sinon, une extension de fichier peut aussi être spécifiée en utilisant le second paramètre.

### Liste de paramètres

`compression`

  La compression doit être soit `Phar::GZ`, soit `Phar::BZ2` pour bénéficier de la compression, ou bien `Phar::NONE` pour éliminer la compression.

`extension`

  Par défaut, l'extension est `.phar.gz` ou `.phar.bz2` pour compresser les archives phar, et `.phar.tar.gz` ou `.phar.tar.bz2` pour compresser les archives tar. Pour décompresser, les extensions par défaut sont `.phar` et `.phar.tar`.

### Valeurs de retour

Retourne un objet Phar, ou `null` en cas d'échec.

### Erreurs / Exceptions

Lève une exception BadMethodCallException si la variable INI phar.readonly est à on, si l'extension zlib n'est pas disponible, ou si l'extension bzip2 n'est pas activée.

### Historique

Version | Description
--- | ---
8.0.0 | `extension` est désormais nullable.

### Exemples

Exemple #1 Un exemple avec Phar::compress()

    <?php
    $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
    $p['monfichier.txt'] = 'salut';
    $p['monfichier2.txt'] = 'salut';
    $p1 = $p->compress(Phar::GZ); // copie vers /chemin/vers/mon.phar.gz
    $p2 = $p->compress(Phar::BZ2); // copie vers /chemin/vers/mon.phar.bz2
    $p3 = $p2->compress(Phar::NONE); // exception: /chemin/vers/mon.phar existe déjà
    ?>

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- PharData::compress() - Compresse l'archive tar/zip complète en utilisant la compression Gzip ou Bzip2
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::decompress() - Décompresse l'archive tar complète
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante

# Phar::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compressFiles — Compresse tous les fichiers de l'archive Phar courante

### Description

public function Phar::compressFiles(int `$compression`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Pour les archives phar basées sur tar, cette méthode lève une exception BadMethodCallException car la compression de fichier individuelle au sein d'une archive tar n'est pas supportée par le format de fichier. Utiliser Phar::compress() pour compresser une archive phar basée sur tar en entier.

Pour les extensions phar basées sur Zip, cette méthode compresse tous les fichiers de l'archive Phar en utilisant la compression spécifiée. Les extensions zlib ou bzip2 doivent être activées pour tirer parti de cette fonctionnalité. De plus, si un ou des fichiers ont déjà été compressés en utilisant la compression bzip2/zlib, l'extension adéquate doit être activée pour décompresser les fichiers avant de les recompresser. Comme avec toutes les fonctionnalités qui modifient le contenu d'un phar, la variable INI phar.readonly doit être à off pour fonctionner.

### Liste de paramètres

`compression`

  La compression doit être soit `Phar::GZ`, soit `Phar::BZ2` pour bénéficier de la compression, ou bien `Phar::NONE` pour éliminer la compression.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Lève une exception BadMethodCallException si la variable INI phar.readonly est à on, si l'extension zlib n'est pas disponible, ou si un ou des fichiers ont été compressés avec l'algorithme bzip2 et que l'extension bzip2 n'est pas activée.

### Exemples

Exemple #1 Un exemple avec Phar::compressFiles()

    <?php
    $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
    $p['monfichier.txt'] = 'salut';
    $p['monfichier2.txt'] = 'salut';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

L'exemple ci-dessus va afficher :

    string(14) "monfichier.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "monfichier2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(14) "monfichier.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "monfichier2.txt"
    int(4096)
    bool(false)
    bool(true)

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::decompress() - Décompresse l'archive tar complète

# Phar::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__construct — Construit un objet d'archive Phar

### Description

public function Phar::__construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)

### Liste de paramètres

`filename`

  Le chemin vers une archive Phar existante ou à créer. Le nom du fichier doit contenir l'extension .phar.

`flags`

  Les drapeaux à passer à la classe parente RecursiveDirectoryIterator.

`alias`

  Alias avec lequel on doit faire référence à l'archive lors de l'appel aux fonctionnalités de flux.

### Erreurs / Exceptions

Lève une exception BadMethodCallException si la méthode est appelée deux fois, ou UnexpectedValueException si l'archive ne peut pas être ouverte.

### Exemples

Exemple #1 Un exemple avec Phar::__construct()

    <?php
    try {
        $p = new Phar('/chemin/vers/mon.phar', FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::KEY_AS_FILENAME,
                      'mon.phar');
    } catch (UnexpectedValueException $e) {
        die('Ne peut pas ouvrir mon.phar');
    } catch (BadMethodCallException $e) {
        echo 'techniquement, ça ne peut pas arriver';
    }
    // ça fonctionne maintenant
    echo file_get_contents('phar://mon.phar/exemple.txt');
    // et ça fonctionne comme si nous avions tapé
    echo file_get_contents('phar:///chemin/vers/mon.phar/exemple.txt');
    ?>

# Phar::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToData — Convertit une archive phar en un fichier non-exécutable

### Description

public function Phar::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

Convertit une archive phar exécutable en un fichier tar ou zip. Pour rendre le tar ou le zip non exécutable, le conteneur phar et l'alias phar sont supprimés de l'archive nouvellement créée.

Si aucun changement n'est spécifié, cette méthode émet une exception BadMethodCallException si l'archive est dans le format de fichier phar. Pour les archives basées sur tar ou zip, cette méthode convertit l'archive en une archive non exécutable.

En cas de succès, la méthode crée une nouvelle archive sur le disque et retourne un objet PharData. L'ancienne archive n'est pas supprimée du disque, ce qui devrait être fait manuellement à la fin du procédé.

### Liste de paramètres

`format`

  Ce doit être l'un des formats `Phar::TAR` ou `Phar::ZIP`. Si ce paramètre est `null`, le format de fichier actuel sera conservé.

`compression`

  Ce doit être `Phar::NONE` pour aucune compression globale, `Phar::GZ` pour une compression basée sur zlib et `Phar::BZ2` pour une compression basée sur bzip2.

`extension`

  Ce paramètre est utilisé pour écraser l'extension par défaut d'une archive convertie. À noter que `.phar` ne peut pas être utilisé dans le nom de fichier d'une archive tar ou zip non-exécutable.

  Si on convertit vers une archive basée sur tar, les extensions par défaut sont `.tar`, `.tar.gz`, et `.tar.bz2` selon la compression spécifiée. Pour les archives phar basées sur zip, l'extension par défaut est `.zip`.

### Valeurs de retour

La méthode retourne un objet PharData en cas de succès, ou `null` en cas d'échec.

### Erreurs / Exceptions

Cette méthode émet une exception BadMethodCallException si elle n'est pas capable de compresser, si une méthode de compression inconnue a été spécifiée ou si l'archive demandée a été mise en tampon avec Phar::startBuffering() sans être conclue avec Phar::stopBuffering(), et émet une exception PharException si un quelconque problème a été rencontré pendant la phase de création de l'archive.

### Historique

Version | Description
--- | ---
8.0.0 | `format`, `compression`, et `extension` sont désormais nullable.

### Exemples

Exemple #1 Un exemple avec Phar::convertToData()

Utilisons Phar::convertToData():

    <?php
    try {
        $tarphar = new Phar('monphar.phar.tar');
        // notez bien que monphar.phar.tar n'est *pas* effacé
        // on convertit vers le format de fichier tar non exécutable
        // crée monphar.tar
        $tar = $tarphar->convertToData();
        // on convertit vers le format de fichier zip non exécutable et crée monphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // crée monphar.tbz
        $tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // crée monphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // émet une exception
    } catch (Exception $e) {
        // on traite les erreurs ici
    }
    ?>

### Voir aussi

- Phar::convertToExecutable() - Convertit une archive phar vers un autre format de fichier d'archive phar exécutable
- PharData::convertToExecutable() - Convertit une archive tar/zip non-exécutable en une archive phar exécutable
- PharData::convertToData() - Convertit une archive phar en une archive tar ou zip non-exécutable

# Phar::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToExecutable — Convertit une archive phar vers un autre format de fichier d'archive phar exécutable

### Description

public function Phar::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Cette méthode est utilisée pour convertir une archive phar vers un autre format de fichier. Par exemple, elle peut être utilisée pour créer une archive phar basée sur tar en partant d'une archive phar basée sur zip ou à partir d'une archive phar exécutable basée sur le format de fichier phar. De plus, elle peut aussi être utilisée pour appliquer une compression globale à une archive basée sur tar ou sur phar.

Si aucun changement n'est précisé, cette méthode lève une exception BadMethodCallException.

En cas de succès, la méthode crée une nouvelle archive sur le disque et retourne un objet Phar. L'ancienne archive n'est pas supprimée du disque, ce qui devrait être fait manuellement à la fin du procédé.

### Liste de paramètres

`format`

  Ce doit être l'un des formats `Phar::PHAR`, `Phar::TAR`, ou `Phar::ZIP`. Si ce paramètre est `null`, le format de fichier actuel sera conservé.

`compression`

  Ce doit être `Phar::NONE` pour aucune compression globale, `Phar::GZ` pour une compression basée sur zlib et `Phar::BZ2` pour une compression basée sur bzip2.

`extension`

  Ce paramètre est utilisé pour écraser l'extension par défaut d'une archive convertie. À noter que toutes les archives phar basées sur zip ou sur tar doivent comporter `.phar` dans leur extension pour être traitées comme une archive phar.

  Si on convertit vers une archive basée sur phar, les extensions par défaut sont `.phar`, `.phar.gz`, ou `.phar.bz2` selon la compression spécifiée. Pour les archives phar basées sur tar, les extensions par défaut sont `.phar.tar`, `.phar.tar.gz`, et `.phar.tar.bz2`. Pour les archives phar basées sur zip, l'extension par défaut est `.phar.zip`.

### Valeurs de retour

La méthode retourne un objet Phar en cas de succès, ou `null` en cas d'échec.

### Erreurs / Exceptions

Cette méthode lève une exception BadMethodCallException si elle n'est pas capable de compresser, si une méthode de compression inconnue a été spécifiée ou si l'archive demandée a été mise en tampon avec Phar::startBuffering() sans être conclue avec Phar::stopBuffering(), lève une exception UnexpectedValueException si le support en écriture a été désactivé et lève une exception PharException si un quelconque problème a été rencontré pendant la phase de création de l'archive.

### Historique

Version | Description
--- | ---
8.0.0 | `format`, `compression`, et `extension` sont désormais nullable.

### Exemples

Exemple #1 Un exemple avec Phar::convertToExecutable()

Utilisons Phar::convertToExecutable() :

    <?php
    try {
        $tarphar = new Phar('monphar.phar.tar');
        // on le convertit vers le format de fichier phar
        // notez bien que monphar.phar.tar n'est *pas* effacé
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // crée monphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // crée monphar.phar.tgz
        $compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // on traite les erreurs ici
    }
    ?>

### Voir aussi

- Phar::convertToData() - Convertit une archive phar en un fichier non-exécutable
- PharData::convertToExecutable() - Convertit une archive tar/zip non-exécutable en une archive phar exécutable
- PharData::convertToData() - Convertit une archive phar en une archive tar ou zip non-exécutable

# Phar::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::copy — Copie un fichier appartenant à une archive vers un autre fichier de la même archive

### Description

public function Phar::copy(string `$from`, string `$to`): true

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Copie un fichier appartenant à une archive vers un nouveau fichier de la même archive. C'est une alternative orientée objet à l'utilisation de copy() avec un flux phar.

### Liste de paramètres

`from`

`to`

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Lève une exception UnexpectedValueException si le fichier source n'existe pas, si le fichier destination existe déjà, si l'accès en écriture est désactivé, si ouvrir l'un ou l'autre des fichiers échoue, si la lecture du fichier source échoue, ou lève une exception PharException si l'écriture des changements dans le phar échoue.

### Exemples

Exemple #1 Exemple avec Phar::copy()

Cet exemple montre comment utiliser Phar::copy() et la comparaison en terme de performance avec l'équivalent utilisant le flux phar. La différence principale entre les deux méthodes concerne la gestion des erreurs. Toutes les méthodes Phar lèvent des exceptions, là où les fonctions de flux utilisent trigger_error().

    <?php

    try {
        $phar = new Phar('monphar.phar');

        $phar['a'] = 'salut';
        $phar->copy('a', 'b');

        echo $phar['b']; // Affiche "phar://monphar.phar/b"
    } catch (Exception $e) {
        // Traite les erreurs
    }

    // l'équivalent en termes de flux du code ci-dessus
    // des E_WARNING sont retournés plutôt que des exceptions
    copy('phar://monphar.phar/a', 'phar//monphar.phar/c');
    echo file_get_contents('phar://monphar.phar/c'); // Affiche "salut"

    ?>

# Phar::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::count — Retourne le nombre d'entrées (fichiers) dans l'archive Phar

### Description

public function Phar::count(int `$mode` = `COUNT_NORMAL`): int

### Liste de paramètres

`mode`

  `mode` est une valeur entière spécifiant le mode de comptage à utiliser. Par défaut, il est défini à `COUNT_NORMAL`, qui ne compte que le nombre d'éléments dans l'archive qui n'ont pas été supprimés ou cachés. Lorsqu'il est défini à `COUNT_RECURSIVE`, il compte tous les éléments de l'archive, y compris ceux qui ont été supprimés ou cachés.

### Valeurs de retour

Le nombre de fichiers contenus dans le phar, ou `0` (le nombre zéro) si aucun.

### Exemples

Exemple #1 Un exemple avec Phar::count()

    <?php
    // on s'assure que le phar n'existe pas
    @unlink('lenouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/lenouveauphar.phar', 0, 'lenouveauphar.phar');
    } catch (Exception $e) {
        echo 'Ne peut pas créer le phar:', $e;
    }
    echo 'Le nouveau phar a ' . $p->count() . " entrées\n";
    $p['file.txt'] = 'salut';
    echo 'Le nouveau phar a ' . $p->count() . " entrées\n";
    ?>

L'exemple ci-dessus va afficher :

    Le nouveau phar a 0 entrées
    Le nouveau phar a 1 entrées

# Phar::createDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::createDefaultStub — Crée un conteneur de chargement d'une archive Phar

### Description

final public static function Phar::createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string

Cette méthode est destinée à la création de conteneurs spécifiques au format de fichier phar et n'est pas conçue pour être utilisée avec des archives phar basées sur tar ou sur zip.

Les archives Phar contiennent un chargeur ou un conteneur écrit en PHP qui est exécuté quand l'archive est exécutée soit par une inclusion

    <?php
    include 'monphar.phar';
    ?>

ou par une simple exécution :

    php monphar.phar

Cette méthode fournit un moyen simple et facile de créer un conteneur qui lancera un fichier de démarrage à partir de l'archive phar. En plus, des fichiers différents peuvent être spécifiés pour exécuter l'archive à partir de la ligne de commande ou d'un serveur web. Le conteneur de chargement appelle alors Phar::interceptFileFuncs() pour permettre l'empaquetage facile d'applications PHP accédant au système de fichiers. Si l'extension phar n'est pas présente, le conteneur de chargement extraira l'archive phar vers un répertoire temporaire et traitera les fichiers. Une fonction d'extinction effacera les fichiers temporaires à la fin.

### Liste de paramètres

`index`

  Chemin relatif au sein de l'archive phar à exécuter en cas d'accès à partir de la ligne de commande

`webIndex`

  Chemin relatif au sein de l'archive phar à exécuter en cas d'accès à partir d'un navigateur

### Valeurs de retour

Retourne une chaîne de caractères contenant un conteneur de chargement personnalisé qui permet à l'archive Phar créée de fonctionner avec ou sans l'extension Phar d'activée.

### Erreurs / Exceptions

Lève une exception UnexpectedValueException si un des paramètres est plus long que 400 octets.

### Historique

Version | Description
--- | ---
8.0.0 | `index` et `webIndex` sont désormais nullable.

### Exemples

Exemple #1 Exemple avec Phar::createDefaultStub()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // traite les erreurs
    }
    ?>

### Voir aussi

- Phar::setStub() - Utilisé pour spécifier le chargeur PHP ou le conteneur de chargement d'une archive Phar
- Phar::getStub() - Retourne le chargeur PHP ou le conteneur de chargement d'une archive Phar

# Phar::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompress — Décompresse l'archive tar complète

### Description

public function Phar::decompress(?string `$extension` = `null`): ?Phar

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Pour les archives phar basées sur tar et sur phar, cette méthode décompresse l'archive complète.

Pour les archives phar basées sur Zip, cette méthode échoue et lève une exception. L'extension zlib doit être active pour décompresser une archive compressée grâce à gzip, et l'extension bzip2 doit être active pour décompresser une archive compressée grâce à bzip2. Comme avec toutes les fonctionnalités qui modifient le contenu d'un phar, la variable INI phar.readonly doit être à off pour fonctionner.

De plus, cette méthode change automatiquement l'extension de l'archive, `.phar` par défaut pour les archives phar, ou `.phar.tar` pour les archives phar basées sur tar. Sinon, une extension de fichier peut aussi être spécifiée en utilisant le second paramètre.

### Liste de paramètres

`extension`

  Pour décompresser, les extensions de fichier par défaut sont `.phar` et `.phar.tar`. Utiliser ce paramètre pour spécifier une autre extension de fichier. À noter que toutes les archives phar exécutables doivent contenir `.phar` dans leur nom de fichier.

### Valeurs de retour

Un objet Phar est retourné en cas de succès, ou `null` en cas d'échec.

### Erreurs / Exceptions

Lève une exception BadMethodCallException si la variable INI phar.readonly est à on, si l'extension zlib n'est pas disponible, ou si l'extension bzip2 n'est pas activée.

### Historique

Version | Description
--- | ---
8.0.0 | `extension` est désormais nullable.

### Exemples

Exemple #1 Un exemple avec Phar::decompress()

    <?php
    $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar.gz');
    $p['monfichier.txt'] = 'salut';
    $p['monfichier2.txt'] = 'salut';
    $p3 = $p2->decompress(); // crée /chemin/vers/mon.phar
    ?>

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- PharData::compress() - Compresse l'archive tar/zip complète en utilisant la compression Gzip ou Bzip2
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante

# Phar::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompressFiles — Décompresse tous les fichiers de l'archive Phar courante

### Description

public function Phar::decompressFiles(): true

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Pour les archives phar basées sur tar, cette méthode lève une exception BadMethodCallException, car la compression individuelle des fichiers au sein d'une archive tar n'est pas supportée par le format de fichier. Utiliser Phar::compress() pour compresser en archive phar basée sur tar en entier.

Pour les archives phar basées sur Zip ou sur phar, cette méthode décompresse tous les fichiers de l'archive Phar. Les extensions zlib ou bzip2 doivent être activées pour tirer parti de cette fonctionnalité si n'importe lequel des fichiers est compressé en utilisant la compression bzip2/zlib. Comme avec toutes les fonctionnalités qui modifient le contenu d'un phar, la variable INI phar.readonly doit être à off pour fonctionner.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Lève une exception BadMethodCallException si la variable INI phar.readonly est à on, si l'extension zlib n'est pas disponible ou si un des fichiers est compressé en utilisant la compression bzip2 et que l'extension bzip2 n'est pas activée.

### Exemples

Exemple #1 Un exemple avec Phar::decompressFiles()

    <?php
    $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
    $p['monfichier.txt'] = 'salut';
    $p['monfichier2.txt'] = 'salut';
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->decompressFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

L'exemple ci-dessus va afficher :

    string(14) "monfichier.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "monfichier2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(14) "monfichier.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "monfichier2.txt"
    bool(false)
    bool(false)
    bool(false)

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::decompress() - Décompresse l'archive tar complète

# Phar::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::delMetadata — Efface les méta-données globales du phar

### Description

public function Phar::delMetadata(): true

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Efface les méta-données globales du phar

### Liste de paramètres

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Lève une exception PharException si des erreurs apparaissent pendant l'écriture sur le disque.

### Exemples

Exemple #1 Un exemple avec Phar::delMetaData()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        var_dump($phar->getMetadata());
        $phar->setMetadata("salut");
        var_dump($phar->getMetadata());
        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // traite les erreurs
    }
    ?>

L'exemple ci-dessus va afficher :

    NULL
    string(5) "salut"
    NULL

### Voir aussi

- Phar::getMetadata() - Retourne les méta-données de l'archive phar
- Phar::setMetadata() - Fixe les métadonnées de l'archive phar
- Phar::hasMetadata() - Détermine si le phar a ou non des méta-données

# Phar::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::delete — Efface un fichier au sein d'une archive phar

### Description

public function Phar::delete(string `$localName`): true

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Efface un fichier au sein d'une archive phar. C'est l'équivalent fonctionnel de l'appel à unlink() dans un contexte de flux, comme décrit dans l'exemple suivant...

### Liste de paramètres

`localName`

  Chemin du fichier à effacer au sein de l'archive.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Lève une exception PharException si des erreurs apparaissent pendant l'écriture sur le disque.

### Exemples

Exemple #1 Un exemple avec Phar::delete()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->delete('efface/moi.php');
        // c'est équivalent à :
        unlink('phar://monphar.phar/efface/moi.php');
    } catch (Exception $e) {
        // traite les erreurs
    }
    ?>

### Voir aussi

- PharData::delete() - Efface un fichier au sein de l'archive tar/zip
- Phar::unlinkArchive() - Efface complètement une archive phar du disque et de la mémoire

# Phar::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__destruct — Détruit un objet archive Phar

### Description

public function Phar::__destruct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# Phar::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::extractTo — Extrait le contenu d'une archive phar vers un répertoire

### Description

public function Phar::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Extrait tous les fichiers d'une archive phar vers le disque. Les fichiers et les dossiers extraits conservent les permissions à l'identique de l'intérieur de l'archive. Les paramètres optionnels permettent un éventuel contrôle sur quel fichier est extrait et si des fichiers déjà existants sur le disque peuvent être écrasés. Le second paramètre `files` peut être soit le nom d'un fichier ou d'un répertoire, soit un tableau de noms de fichiers et de répertoires à extraire. Par défaut, cette méthode n'écrasant pas les fichiers existants, le troisième paramètre peut être passé à `true` pour activer l'écrasement de fichiers. Cette méthode est similaire à ZipArchive::extractTo().

### Liste de paramètres

`directory`

  Chemin d'accès vers lequel extraire les fichiers `files`

`files`

  Le nom d'un fichier ou d'un répertoire ou un tableau de fichiers/répertoires à extraire, `null` pour ignorer ce paramètre

`overwrite`

  Le passer à `true` pour activer l'écrasement des fichiers existants

### Valeurs de retour

retourne `true` en cas de succès, mais il est plus sûr de vérifier si des exceptions sont levées, et de considérer que tout s'est bien passé si aucune n'est levée.

### Erreurs / Exceptions

Lève une exception PharException si des erreurs apparaissent pendant l'écriture sur le disque.

### Exemples

Exemple #1 Exemple avec Phar::extractTo()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->extractTo('/chemin/complet'); // extrait tous les fichiers
        $phar->extractTo('/autre/chemin', 'fichier.txt'); // extrait seulement fichier.txt
        $phar->extractTo('/ce/chemin',
            array('fichier1.txt', 'fichier2.txt')); // extrait seulement 2 fichiers
        $phar->extractTo('/troisieme/chemin', null, true); // extrait tous les fichiers, en écrasant
    } catch (Exception $e) {
        // traite les erreurs
    }
    ?>

### Notes

> Note: Les systèmes de fichiers NTFS Windows ne supportent pas certain caractères dans le noms de fichier, à savoir `<|>*?":`. Les noms de fichiers avec un point trainant ne sont également pas supporté. Contrairement à certains outils d'extraction, cette méthode ne remplace pas ces caractères avec un tiret bas, mais échoue à extraire de tel fichiers.

### Voir aussi

- PharData::extractTo() - Extrait le contenu d'une archive tar/zip vers un répertoire

# Phar::getAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::getAlias — Récupère l'alias pour Phar

### Description

public function Phar::getAlias(): ?string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'alias ou `null` s'il n'y a pas d'alias.

# Phar::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getMetadata — Retourne les méta-données de l'archive phar

### Description

public function Phar::getMetadata(array `$unserializeOptions` = []): mixed

Récupère les méta-données de l'archive. Celles-ci peuvent être n'importe quelle variable PHP pouvant être sérialisée.

Attention

L’accès aux métadonnées déclenche la désérialisation, ce qui peut entraîner l’exécution de code PHP arbitraire. Ne pas utiliser cette fonctionnalité sur des archives phar non fiables, ou configurer le paramètre `unserializeOptions` de manière sécurisée.

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

N'importe quelle variable PHP pouvant être sérialisée et qui est stockée comme méta-donnée de l'archive Phar, ou `null` si aucune méta-donnée n'est stockée.

### Historique

Version | Description
--- | ---
8.0.0 | Le paramètre `unserializeOptions` a été ajouté.

### Exemples

Exemple #1 Un exemple avec Phar::getMetadata()

    <?php
    // on s'assure que le phar n'existe pas
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.php'] = '<?php echo "salut";';
        $p->setMetadata(array('bootstrap' => 'fichier.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Ne peut pas modifier le phar :', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["bootstrap"]=>
      string(11) "fichier.php"
    }

### Voir aussi

- Phar::setMetadata() - Fixe les métadonnées de l'archive phar
- Phar::delMetadata() - Efface les méta-données globales du phar
- Phar::hasMetadata() - Détermine si le phar a ou non des méta-données

# Phar::getModified

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getModified — Indique si le fichier phar a été modifié

### Description

public function Phar::getModified(): bool

Détermine si une archive phar a eu soit un fichier interne effacé ou si le contenu d'un fichier a changé d'une façon ou d'une autre.

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

`true` si le phar a été modifié depuis son ouverture, `false` sinon.

# Phar::getPath

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Phar::getPath — Récupère le chemin absolu de l'archive Phar sur le disque

### Description

public function Phar::getPath(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# Phar::getSignature

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getSignature — Retourne la signature MD5/SHA1/SHA256/SHA512 d'une archive Phar

### Description

public function Phar::getSignature(): array|false

Retourne la signature de vérification d'une archive phar sous forme d'une chaîne de caractères hexadécimale.

### Liste de paramètres

### Valeurs de retour

Un tableau avec la signature de l'archive ouverte avec le `hash` en guise de clé et "`MD5`", "`SHA-1`", "`SHA-256`" ou "`SHA-512`" comme `hash_type`. Cette signature est un hachage calculé à partir du contenu de l'archive entière ; elle peut être utilisée pour vérifier l'intégrité de l'archive. Une signature valide est absolument requise pour toutes les archives phar exécutables si la variable INI phar.require_hash vaut `true`. S'il n'y a pas de signature, la fonction retourne `false`

# Phar::getStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getStub — Retourne le chargeur PHP ou le conteneur de chargement d'une archive Phar

### Description

public function Phar::getStub(): string

Les archives phar contiennent un chargeur, ou conteneur (`stub`), écrit en PHP qui est exécuté quand l'archive elle-même est exécutée soit par inclusion :

    <?php
    include 'monphar.phar';
    ?>

soit par simple exécution :

    php monphar.phar

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères avec le contenu du conteneur de chargement (`stub`) de l'archive phar courante.

### Erreurs / Exceptions

Lève une exception RuntimeException s'il n'est pas possible de lire le conteneur de chargement de l'archive Phar.

### Exemples

Exemple #1 Exemple avec Phar::getStub()

    <?php
    $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
    echo $p->getStub();
    echo "==SUIVANT==\n";
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('monphar.phar');
    include 'phar://monphar.phar/demarrage.php';
    __HALT_COMPILER(); ?>");
    echo $p->getStub();
    ?>

L'exemple ci-dessus va afficher :

    <?php __HALT_COMPILER(); ?>
    ==SUIVANT==
    <?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('monphar.phar');
    include 'phar://monphar.phar/demarrage.php';
    __HALT_COMPILER(); ?>

### Voir aussi

- Phar::setStub() - Utilisé pour spécifier le chargeur PHP ou le conteneur de chargement d'une archive Phar
- Phar::createDefaultStub() - Crée un conteneur de chargement d'une archive Phar

# Phar::getSupportedCompression

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::getSupportedCompression — Retourne un tableau des algorithmes de compression supportés

### Description

final public static function Phar::getSupportedCompression(): array

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

Retourne un tableau contenant l'un des algorithmes `Phar::GZ` ou `Phar::BZ2`, selon la disponibilité de l'extension zlib ou de l'extension bz2.

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::decompress() - Décompresse l'archive tar complète
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante

# Phar::getSupportedSignatures

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::getSupportedSignatures — Retourne un tableau des types de signature supportés

### Description

final public static function Phar::getSupportedSignatures(): array

Retourne un tableau des types de signature supportés

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

Retourne un tableau contenant un ou plusieurs des types `MD5`, `SHA-1`, `SHA-256`, `SHA-512`.

### Voir aussi

- Phar::getSignature() - Retourne la signature MD5/SHA1/SHA256/SHA512 d'une archive Phar
- Phar::setSignatureAlgorithm() - Fixe et applique l'algorithme de signature d'un phar

# Phar::getVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getVersion — Retourne les informations de version de l'archive Phar

### Description

public function Phar::getVersion(): string

Retourne la version de l'API d'une archive Phar ouverte.

### Liste de paramètres

### Valeurs de retour

La version de l'API de l'archive ouverte. À ne pas confondre avec la version d'API que l'extension phar chargée utilisera pour créer de nouveaux phar. Chaque archive Phar a la version d'API codée en dur dans son manifeste. Pour davantage d'information, regardez le format de fichier Phar.

### Voir aussi

- Phar::apiVersion() - Retourne la version de l'API

# Phar::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::hasMetadata — Détermine si le phar a ou non des méta-données

### Description

public function Phar::hasMetadata(): bool

Détermine si le phar a ou non des méta-données.

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

Retourne `true` si des méta-données sont présentes, `false` sinon.

### Exemples

Exemple #1 Un exemple avec Phar::hasMetadata()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        var_dump($phar->hasMetadata());
        $phar->setMetadata(array('deschoses' => 'salut'));
        var_dump($phar->hasMetadata());
        $phar->delMetadata();
        var_dump($phar->hasMetadata());
    } catch (Exception $e) {
        // traite les erreurs
    }
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(false)

### Voir aussi

- Phar::getMetadata() - Retourne les méta-données de l'archive phar
- Phar::setMetadata() - Fixe les métadonnées de l'archive phar
- Phar::delMetadata() - Efface les méta-données globales du phar

# Phar::interceptFileFuncs

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::interceptFileFuncs — Informe phar qu'il doit intercepter les fonctions de fichiers

### Description

final public static function Phar::interceptFileFuncs(): void

Informe phar d'intercepter fopen(), readfile(), file_get_contents(), opendir() et toutes les fonctions relatives à stat. Si n'importe laquelle de ces fonctions est appelée depuis l'archive phar avec un chemin relatif, l'appel est modifié pour accéder à un fichier au sein de l'archive. Les chemins absolus sont supposés être des tentatives de chargement de fichiers externes à partir du système de fichiers.

Cette fonction rend possible l'exécution d'applications PHP conçues pour être lancées en dehors d'un disque dur, en tant qu'application phar.

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec Phar::interceptFileFuncs()

    <?php
    Phar::interceptFileFuncs();
    include 'phar://' . __FILE__ . '/fichier.php';
    ?>

En supposant que ce phar est nommé `/chemin/vers/monphar.phar` et qu'il contient `fichier.php` et `fichier2.txt`, si `fichier.php` contient ce code :

Exemple #2 Un exemple avec Phar::interceptFileFuncs()

    <?php
    echo file_get_contents('fichier2.txt');
    ?>

Normalement, PHP chercherait dans le répertoire courant le fichier nommé `fichier2.txt`, c'est-à-dire dans le répertoire de fichier.php ou le répertoire courant de l'utilisateur de la ligne de commande. Phar::interceptFileFuncs() dit à PHP de considérer `phar:///chemin/vers/monphar.phar/` comme répertoire courant et ainsi ouvre dans l'exemple ci-dessus le fichier `phar:///chemin/vers/monphar.phar/fichier2.txt`.

# Phar::isBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::isBuffering — Détermine si les opérations d'écriture du Phar sont mises en tampons ou sont directement inscrites sur le disque

### Description

public function Phar::isBuffering(): bool

Cette méthode peut être utilisée pour déterminer si un Phar sauvera ses changements immédiatement sur le disque ou si un appel à la fonction Phar::stopBuffering() est nécessaire pour inscrire les modifications.

La mise en tampon de l'écriture du Phar se fait par archive ; la mise en tampon de l'archive Phar `foo.phar` n'affecte en rien les changements faits sur l'archive Phar `bar.phar`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si les opérations d'écriture sont mises en tampons, `false` sinon.

### Exemples

Exemple #1 Un exemple avec Phar::isBuffering()

    <?php
    $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
    $p2 = new Phar('pharexistant.phar');
    $p['fichier1.txt'] = 'salut';
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>
    =2=
    <?php
    $p->startBuffering();
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    $p->stopBuffering();
    ?>
    =3=
    <?php
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(false)
    =2=
    bool(true)
    bool(false)
    =3=
    bool(false)
    bool(false)

### Voir aussi

- Phar::startBuffering() - Démarre la mise en tampon d'écritures Phar, ne modifie pas l'objet Phar sur le disque
- Phar::stopBuffering() - Arrête la mise en tampon des écritures Phar et provoque l'écriture sur le disque

# Phar::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isCompressed — Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)

### Description

public function Phar::isCompressed(): int|false

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc). Les archives phar basées sur Zip ne peuvent pas être compressées en tant que fichier, et cette méthode retournera toujours `false` si une archive phar basée sur Zip est interrogée.

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

`Phar::GZ`, `Phar::BZ2` ou `false`.

### Exemples

Exemple #1 Exemple avec Phar::isCompressed()

    <?php
    try {
        $phar1 = new Phar('monphar.zip.phar');
        var_dump($phar1->isCompressed());
        $phar2 = new Phar('monpharnoncompresse.tar.phar');
        var_dump($phar2->isCompressed());
        $phar2->compress(Phar::GZ);
        var_dump($phar2->isCompressed() == Phar::GZ);
    } catch (Exception $e) {
    }
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(false)
    bool(true)

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- Phar::decompress() - Décompresse l'archive tar complète
- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés

# Phar::isFileFormat

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isFileFormat — Retourne `true` si l'archive phar est basée sur le format de fichier tar/phar/zip selon le paramètre

### Description

public function Phar::isFileFormat(int `$format`): bool

### Liste de paramètres

`format`

  Soit `Phar::PHAR`, soit `Phar::TAR`, soit `Phar::ZIP` pour tester le format de fichier de l'archive.

### Valeurs de retour

Retourne `true` si l'archive phar utilise le format de fichier spécifié en paramètre

### Erreurs / Exceptions

Une exception PharException est levée si le paramètre est un format de fichier inconnu.

### Voir aussi

- Phar::convertToExecutable() - Convertit une archive phar vers un autre format de fichier d'archive phar exécutable
- Phar::convertToData() - Convertit une archive phar en un fichier non-exécutable

# Phar::isValidPharFilename

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::isValidPharFilename — Détermine si le nom de fichier spécifié est un nom de fichier valide pour une archive phar

### Description

final public static function Phar::isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool

Détermine si le nom de fichier spécifié est un nom de fichier valide pour une archive phar, qui sera reconnue comme telle par l'extension phar. Ceci peut être utilisé pour tester un nom sans avoir à instancier une archive phar et à attraper l'inévitable Exception qui sera levée si un nom de fichier non valide est spécifié.

### Liste de paramètres

`filename`

  Le nom ou le chemin complet vers une archive phar non encore créée

`executable`

  Ce paramètre détermine si le nom de fichier doit être traité comme celui d'une archive phar exécutable ou comme une archive de données non exécutable.

### Valeurs de retour

Retourne `true` si le nom de fichier est valide, `false` sinon.

# Phar::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isWritable — Retourne `true` si l'archive phar peut être modifiée

### Description

public function Phar::isWritable(): bool

Cette méthode retourne `true` si `phar.readonly` est à `0` et que l'archive phar actuelle sur le disque n'est pas en lecture seule.

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

Retourne `true` si l'archive phar peut être modifiée

### Voir aussi

- Phar::canWrite() - Détermine si l'extension phar supporte la création et l'écriture des phars
- PharData::isWritable() - Vérifie si l'archive tar/zip peut être modifiée

# Phar::loadPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::loadPhar — Charge n'importe quelle archive phar avec un alias

### Description

final public static function Phar::loadPhar(string `$filename`, ?string `$alias` = `null`): bool

Cette méthode peut être utilisée pour lire le contenu d'une archive Phar externe. C'est principalement utile pour assigner un alias à un phar de telle façon que les références ultérieures au phar puissent être faites à l'aide d'un alias plus court ou pour charger des archives Phar qui contiennent seulement des données et qui ne sont pas destinées à être exécutées/incluses dans des scripts PHP.

### Liste de paramètres

`filename`

  le chemin relatif ou absolu vers l'archive phar à ouvrir

`alias`

  L'alias qui pourra être utilisé pour se référer à l'archive phar. Il est à noter que de nombreuses archives phar spécifient un alias explicite au sein de l'archive phar, et une exception PharException sera levée si un nouvel alias est spécifié dans ce cas.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Une exception PharException est levée si un alias est passé alors que l'archive phar a déjà un alias explicite

### Exemples

Exemple #1 Un exemple avec Phar::loadPhar()

Phar::loadPhar peut être utilisée n'importe où pour charger une archive phar externe alors que Phar::mapPhar devrait être utilisée dans un conteneur de chargement pour un Phar.

    <?php
    try {
        Phar::loadPhar('/chemin/vers/phar.phar', 'mon.phar');
        echo file_get_contents('phar://mon.phar/fichier.txt');
    } catch (PharException $e) {
        echo $e;
    }
    ?>

### Voir aussi

- Phar::mapPhar() - Lit le phar exécuté et charge son manifeste

# Phar::mapPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::mapPhar — Lit le phar exécuté et charge son manifeste

### Description

final public static function Phar::mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool

Cette méthode statique peut être utilisée seulement au sein du conteneur de chargement d'une archive Phar pour initialiser le phar quand il est exécuté directement ou quand il est inclus dans un autre script.

### Liste de paramètres

`alias`

  L'alias qui peut être utilisé dans l'URL `phar://` pour se référer à l'archive plutôt que d'utiliser son chemin complet.

`offset`

  Variable inutilisée, présente par souci de compatibilité avec la bibliothèque PHP_Archive de PEAR.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Une exception PharException est levée si la méthode n'est pas appelée directement au sein de l'exécution de PHP, si aucun jeton __HALT_COMPILER(); n'est trouvé dans le fichier source actuel ou si le fichier ne peut pas être ouvert en lecture.

### Exemples

Exemple #1 Exemple avec Phar::mapPhar()

mapPhar ne doit être utilisé qu'au sein du conteneur de chargement d'un phar. Utiliser loadPhar pour charger un phar externe en mémoire.

Voici un exemple de conteneur de chargement Phar qui utilise mapPhar.

    <?php
    function __autoload($class)
    {
        include 'phar://mon.phar/' . str_replace('_', '/', $class) . '.php';
    }
    try {
        Phar::mapPhar('mon.phar');
        include 'phar://mon.phar/demarrage.php';
    } catch (PharException $e) {
        echo $e->getMessage();
        die('Ne peut pas initialiser le Phar');
    }
    __HALT_COMPILER();

### Voir aussi

- Phar::loadPhar() - Charge n'importe quelle archive phar avec un alias

# Phar::mount

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mount — Monte un chemin ou un fichier externe à un emplacement virtuel au sein de l'archive phar

### Description

final public static function Phar::mount(string `$pharPath`, string `$externalPath`): void

Tout comme le concept unix de montage d'un périphérique externe à un endroit de l'arborescence, Phar::mount() permet de se référer à des fichiers et des répertoires externes comme s'ils étaient à l'intérieur de l'archive.

### Liste de paramètres

`pharPath`

  Le chemin interne au sein de l'archive phar à utiliser en tant que point de montage. Doit être un chemin relatif dans l'archive phar, et ne doit pas déjà exister.

`externalPath`

  Un chemin ou une URL vers un fichier ou un répertoire externe à monter au sein de l'archive

### Valeurs de retour

Aucun retour. Une exception PharException est levée en cas d'échec.

### Erreurs / Exceptions

Lève une exception PharException si un problème est rencontré lors du montage.

### Exemples

Exemple #1 Un exemple avec Phar::mount()

L'exemple suivant présente l'accès à un fichier de configuration externe comme s'il était un chemin au sein de l'archive phar.

Tout d'abord, le code au sein de l'archive phar :

    <?php
    $configuration = simplexml_load_string(file_get_contents(
        Phar::running(false) . '/config.xml'));
    ?>

Ensuite le code externe utilisé pour monter le fichier de configuration :

    <?php
    // on commence par configurer l'association entre le fichier config.xml abstrait
    // et celui sur le disque
    Phar::mount('phar://config.xml', '/home/example/config.xml');
    // on lance maintenant l'application
    include '/chemin/vers/archive.phar';
    ?>

Une autre méthode est de mettre le code de montage au sein du conteneur de chargement de l'archive phar. Voici un exemple pour configurer un fichier de configuration par défaut si aucune configuration utilisateur n'est faite :

    <?php
    // on commence par configurer l'association entre le fichier config.xml abstrait
    // et celui sur le disque
    if (defined('EXTERNAL_CONFIG')) {
        Phar::mount('config.xml', EXTERNAL_CONFIG);
        if (file_exists(__DIR__ . '/extra_config.xml')) {
            Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
        }
    } else {
        Phar::mount('config.xml', 'phar://' . __FILE__ . '/default_config.xml');
        Phar::mount('extra.xml', 'phar://' . __FILE__ . '/default_extra.xml');
    }
    // on lance maintenant l'application
    include 'phar://' . __FILE__ . '/index.php';
    __HALT_COMPILER();
    ?>

... et le code externe pour charger cette archive phar :

    <?php
    define('EXTERNAL_CONFIG', '/home/exemple/config.xml');
    // on lance maintenant l'application
    include '/chemin/vers/archive.phar';
    ?>

# Phar::mungServer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mungServer — Définit une liste de maximum 4 variables $_SERVER qui doivent être modifiées lors de l'exécution

### Description

final public static function Phar::mungServer(array `$variables`): void

Phar::mungServer() doit être appelée seulement dans le conteneur de chargement d'une archive phar.

Définit une liste de maximum 4 variables $_SERVER qui doivent être modifiées lors de l'exécution. Les variables qui peuvent être modifiées pour effacer les traces de l'exécution phar sont `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` et `SCRIPT_FILENAME`.

Seule, cette méthode ne fait rien. Elle prend effet seulement quand elle est combinée à Phar::webPhar() et seulement si le fichier demandé est un fichier PHP à parser. Il est à noter que les variables `PATH_INFO` et `PATH_TRANSLATED` sont toujours modifiées.

Les valeurs de départ des variables qui sont modifiées sont stockées dans le tableau SERVER avec le préfixe `PHAR_` et donc par exemple `SCRIPT_NAME` sera stockée en tant que `PHAR_SCRIPT_NAME`.

### Liste de paramètres

`variables`

  un tableau contenant n'importe laquelle de ces chaînes de caractères. `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` et `SCRIPT_FILENAME` en tant qu'indices de chaînes de caractères. Les autres valeurs déclenchent une exception et Phar::mungServer() est sensible à la casse.

### Valeurs de retour

Aucun retour.

### Erreurs / Exceptions

Lève une exception UnexpectedValueException si un quelconque problème est trouvé dans les données passées.

### Exemples

Exemple #1 Un exemple avec Phar::mungServer()

    <?php
    // exemple de conteneur
    Phar::mungServer(array('REQUEST_URI'));
    Phar::webPhar();
    __HALT_COMPILER();
    ?>

### Voir aussi

- Phar::webPhar() - Redirige une requête depuis un navigateur web à un fichier interne dans l'archive phar
- Phar::setStub() - Utilisé pour spécifier le chargeur PHP ou le conteneur de chargement d'une archive Phar

# Phar::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetExists — Détermine si un fichier existe dans le phar

### Description

public function Phar::offsetExists(string `$localName`): bool

C'est une implémentation de l'interface ArrayAccess qui permet la manipulation directe du contenu d'une archive Phar en utilisant les crochets d'accès au tableau.

offsetExists() est appelé comme isset() est appelé.

### Liste de paramètres

`localName`

  Le nom de fichier (en chemin relatif) à chercher dans le Phar.

### Valeurs de retour

Retourne `true` si le fichier existe dans le phar, `false` sinon.

### Exemples

Exemple #1 Un exemple avec Phar::offsetExists()

    <?php
    $p = new Phar(dirname(__FILE__) . '/mon.phar', 0, 'mon.phar');
    $p['premierfichier.txt'] = 'premier fichier';
    $p['secondfichier.txt'] = 'second fichier';
    // les lignes suivantes font appel à offsetExists() de façon indirecte
    var_dump(isset($p['premierfichier.txt']));
    var_dump(isset($p['pasla.txt']));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)

### Voir aussi

- Phar::offsetGet() - Obtient un objet PharFileInfo à partir d'un fichier
- Phar::offsetSet() - Met le contenu d'un fichier interne à l'archive à l'identique du contenu d'un fichier externe
- Phar::offsetUnset() - Efface un fichier d'un phar

# Phar::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetGet — Obtient un objet PharFileInfo à partir d'un fichier

### Description

public function Phar::offsetGet(string `$localName`): SplFileInfo

C'est une implémentation de l'interface ArrayAccess qui permet la manipulation directe du contenu d'une archive Phar en utilisant les crochets d'accès au tableau. Phar::offsetGet() est utilisé pour extraire des fichiers d'une archive Phar.

### Liste de paramètres

`localName`

  Le nom de fichier (en chemin relatif) à chercher dans le Phar.

### Valeurs de retour

Un objet PharFileInfo est retourné et peut être utilisé pour parcourir le contenu d'un fichier ou pour récupérer des informations sur le fichier courant.

### Erreurs / Exceptions

Cette méthode émet une exception BadMethodCallException si le fichier n'existe pas dans l'archive Phar.

### Exemples

Exemple #1 Exemple avec Phar::offsetGet()

Comme avec toutes les classes qui implémentent l'interface ArrayAccess, Phar::offsetGet() est automatiquement appelée quand les crochets d'accès à un tableau sont utilisés (`[]`).

    <?php
    $p = new Phar(dirname(__FILE__) . '/monphar.phar', 0, 'monphar.phar');
    $p['existe.txt'] = "le fichier existe\n";
    try {
        // appelle automatiquement offsetGet()
        echo $p['existe.txt'];
        echo $p['nexistepas.txt'];
    } catch (BadMethodCallException $e) {
        echo $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    le fichier existe
    Entry nexistepas.txt does not exist

### Voir aussi

- Phar::offsetExists() - Détermine si un fichier existe dans le phar
- Phar::offsetSet() - Met le contenu d'un fichier interne à l'archive à l'identique du contenu d'un fichier externe
- Phar::offsetUnset() - Efface un fichier d'un phar

# Phar::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetSet — Met le contenu d'un fichier interne à l'archive à l'identique du contenu d'un fichier externe

### Description

public function Phar::offsetSet(string `$localName`, resource|string `$value`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

C'est une implémentation de l'interface ArrayAccess qui permet la manipulation directe du contenu d'une archive Phar en utilisant les crochets d'accès au tableau. offsetSet est utilisé pour modifier un fichier existant ou pour ajouter un nouveau fichier à l'archive Phar.

### Liste de paramètres

`localName`

  Le nom de fichier (en chemin relatif) à chercher dans le Phar.

`value`

  Contenu du fichier.

### Valeurs de retour

Aucune valeur de retour.

### Erreurs / Exceptions

Si phar.readonly est à `1`, une exception BadMethodCallException est levée, car modifier un Phar n'est permis que quand phar.readonly est à `0`. Une exception PharException est levée s'il y a eu un problème lors de l'écriture des changements de l'archive Phar sur le disque.

### Exemples

Exemple #1 Un exemple avec Phar::offsetSet()

offsetSet ne doit pas être accédé directement, mais plutôt via l'opérateur d'accès au tableau, `[]`.

    <?php
    $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
    try {
        // appelle offsetSet
        $p['fichier.txt'] = 'Salut';
    } catch (Exception $e) {
        echo 'Ne peut pas modifier fichier.txt:', $e;
    }
    ?>

### Notes

> Note: Phar::addFile(), Phar::addFromString() et Phar::offsetSet() enregistre une nouvelle archive phar à chaque fois qu'elles sont appelées. Si les performances sont une préoccupation, Phar::buildFromDirectory() ou Phar::buildFromIterator() devraient être utilisé à la place.

### Voir aussi

- Phar::offsetExists() - Détermine si un fichier existe dans le phar
- Phar::offsetGet() - Obtient un objet PharFileInfo à partir d'un fichier
- Phar::offsetUnset() - Efface un fichier d'un phar

# Phar::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetUnset — Efface un fichier d'un phar

### Description

public function Phar::offsetUnset(string `$localName`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

C'est une implémentation de l'interface ArrayAccess qui permet la manipulation directe du contenu d'une archive Phar en utilisant les crochets d'accès au tableau. offsetUnset est utilisé pour supprimer un fichier existant et est appelé par la fonction unset().

### Liste de paramètres

`localName`

  Le nom de fichier (en chemin relatif) à chercher dans le Phar.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Si phar.readonly est à `1`, une exception BadMethodCallException est levée, car modifier un Phar n'est permis que quand phar.readonly est à `0`. Une exception PharException est levée s'il y a eu un problème lors de l'écriture des changements de l'archive Phar sur le disque.

### Exemples

Exemple #1 Un exemple avec Phar::offsetUnset()

    <?php
    $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
    try {
        // efface fichier.txt de mon.phar en appelant offsetUnset
        unset($p['fichier.txt']);
    } catch (Exception $e) {
        echo 'Ne peut pas effacer fichier.txt: ', $e;
    }
    ?>

### Voir aussi

- Phar::offsetExists() - Détermine si un fichier existe dans le phar
- Phar::offsetGet() - Obtient un objet PharFileInfo à partir d'un fichier
- Phar::offsetSet() - Met le contenu d'un fichier interne à l'archive à l'identique du contenu d'un fichier externe
- Phar::unlinkArchive() - Efface complètement une archive phar du disque et de la mémoire
- Phar::delete() - Efface un fichier au sein d'une archive phar

# Phar::running

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::running — Retourne le chemin complet sur le disque ou l'URL phar complète de l'archive phar couramment exécutée

### Description

final public static function Phar::running(bool `$returnPhar` = `true`): string

Retourne le chemin complet de l'archive phar exécutée. C'est bien entendu utilisé un peu comme la constante magique `__FILE__` et a des effets uniquement au sein d'une archive phar en train d'être exécutée.

Dans le conteneur de chargement d'une archive, Phar::running() retourne `""`. Utiliser simplement `__FILE__` pour accéder au phar courant au sein d'un conteneur de chargement.

### Liste de paramètres

`returnPhar`

  Si `false`, le chemin complet sur le disque vers le phar est retourné. Si `true`, une URL phar complète est retournée.

### Valeurs de retour

Retourne le chemin de fichier si valide, sinon une chaîne vide.

### Exemples

Exemple #1 Un exemple avec Phar::running()

Pour l'exemple suivant, on suppose que le fichier phar est `/chemin/vers/mon.phar`.

    <?php
    $a = Phar::running(); // $a vaut "phar:///chemin/vers/mon.phar"
    $b = Phar::running(false); // $b vaut "/chemin/vers/mon.phar"
    ?>

# Phar::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::setAlias — Fixe l'alias de l'archive Phar

### Description

public function Phar::setAlias(string `$alias`): true

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Fixe l'alias de l'archive Phar et l'écrit en tant qu'alias permanent de cette archive phar. Un alias peut être utilisé à l'intérieur d'une archive phar pour s'assurer que l'utilisation du flux `phar` pour accéder à des fichiers internes fonctionnera toujours quel que soit l'emplacement de l'archive phar sur le système de fichiers. Une alternative consiste à se fier à l'interception de include faite par Phar ou d'utiliser Phar::interceptFileFuncs() et d'utiliser des chemins relatifs.

### Liste de paramètres

`alias`

  Une petite chaîne avec laquelle on se référera à cette archive lors des accès avec le flux `phar`.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Une exception UnexpectedValueException est levée quand l'accès en écriture est désactivé et une exception PharException est levée si l'alias est déjà utilisé ou si un problème a été rencontré lors de l'écriture des changements sur le disque.

### Historique

Version | Description
--- | ---
8.4.0 | Phar::setAlias() a maintenant un type de retour provisoire de type true.

### Exemples

Exemple #1 Un exemple avec Phar::setAlias()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->setAlias('monp.phar');
    } catch (Exception $e) {
        // traite les erreurs
    }
    ?>

### Voir aussi

- Phar::__construct() - Construit un objet d'archive Phar
- Phar::interceptFileFuncs() - Informe phar qu'il doit intercepter les fonctions de fichiers

# Phar::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::setDefaultStub — Utilisé pour fixer le chargeur PHP ou le conteneur de chargement d'une archive Phar en tant que chargeur par défaut

### Description

public function Phar::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Cette méthode est un raccourci qui combine les fonctionnalités de Phar::createDefaultStub() et de Phar::setStub().

### Liste de paramètres

`index`

  Chemin relatif au sein de l'archive phar à exécuter si lancée à partir de la ligne de commande

`webIndex`

  Chemin relatif au sein de l'archive phar à exécuter si lancée à partir d'un navigateur

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Une exception UnexpectedValueException est levée si phar.readonly est activée dans le php.ini. Une exception PharException est levée si des problèmes sont rencontrés lors de l'écriture des changements sur disque.

### Historique

Version | Description
--- | ---
8.4.0 | Phar::setDefaultStub() a maintenant un type de retour provisoire de true.
8.0.0 | `webIndex` est désormais nullable.

### Exemples

Exemple #1 Un exemple avec Phar::setDefaultStub()

    <?php
    try {
        $phar = new Phar('monphar.phar');
        $phar->setDefaultStub('cli.php', 'web/index.php');
        // est identique à :
        // $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // traite les erreurs
    }
    ?>

### Voir aussi

- Phar::setStub() - Utilisé pour spécifier le chargeur PHP ou le conteneur de chargement d'une archive Phar
- Phar::createDefaultStub() - Crée un conteneur de chargement d'une archive Phar

# Phar::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setMetadata — Fixe les métadonnées de l'archive phar

### Description

public function Phar::setMetadata(mixed `$metadata`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Phar::setMetadata() doit être utilisée pour stocker des données personnalisées qui décrivent l'archive phar, en tant qu'entité à part entière. PharFileInfo::setMetadata() doit être utilisée pour les métadonnées spécifiques aux fichiers. Les métadonnées peuvent diminuer les performances de chargement d'une archive phar si les données sont importantes.

Une utilisation possible des métadonnées est la spécification des fichiers à utiliser au sein de l'archive pour la lancer, ou l'emplacement d'un fichier de manifeste comme le fichier package.xml de » PEAR. De façon générale, toute donnée utile qui décrit l'archive phar peut être stockée.

### Liste de paramètres

`metadata`

  Toute variable PHP contenant des informations à stocker et qui décrit l'archive phar

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Un exemple avec Phar::setMetadata()

    <?php
    // on s'assure que le phar n'existe pas déjà
    @unlink('nouveau.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveau.phar', 0, 'nouveau.phar');
        $p['fichier.php'] = '<?php echo "salut"';
        $p->setMetadata(array('chargeur' => 'fichier.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Ne peut pas créer/modifier le phar :', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["chargeur"]=>
      string(11) "fichier.php"
    }

### Voir aussi

- Phar::getMetadata() - Retourne les méta-données de l'archive phar
- Phar::delMetadata() - Efface les méta-données globales du phar
- Phar::hasMetadata() - Détermine si le phar a ou non des méta-données

# Phar::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithm — Fixe et applique l'algorithme de signature d'un phar

### Description

public function Phar::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Fixe et applique l'algorithme de signature d'un phar. L'algorithme de signature doit être `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, ou `Phar::OPENSSL`.

Il est à noter que toutes les archives phar exécutables ont une signature créée automatiquement, `SHA1` par défaut. Les archives de données basées sur tar ou sur zip (créées avec la classe PharData) doivent avoir leur signature créée et assignée explicitement via Phar::setSignatureAlgorithm().

### Liste de paramètres

`algo`

  Un des algorithmes `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, ou `Phar::OPENSSL`

`privateKey`

  Le contenu d'une clé privée OpenSSL, telle qu'extraite d'un certificat ou d'un fichier de clé OpenSSL :

      <?php
      $private = openssl_get_privatekey(file_get_contents('private.pem'));
      $pkey = '';
      openssl_pkey_export($private, $pkey);
      $p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
      ?>

  Se reporter à l'introduction de phar pour les instructions de nommage et de placement du fichier de clé publique.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Lève une exception UnexpectedValueException pour de nombreuses erreurs et une exception PharException si des problèmes surviennent durant l'écriture des changements sur le disque.

### Historique

Version | Description
--- | ---
8.0.0 | `privateKey` est désormais nullable.

### Voir aussi

- Phar::getSupportedSignatures() - Retourne un tableau des types de signature supportés
- Phar::getSignature() - Retourne la signature MD5/SHA1/SHA256/SHA512 d'une archive Phar

# Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStub — Utilisé pour spécifier le chargeur PHP ou le conteneur de chargement d'une archive Phar

### Description

public function Phar::setStub(resource|string `$stub`, int `$length` = -1): true

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Cette méthode est utilisée pour ajouter un chargeur PHP à une nouvelle archive Phar, ou pour remplacer le conteneur de chargement d'une archive Phar existante.

Le conteneur de chargement d'une archive Phar est utilisé quand une archive est incluse directement comme dans cet exemple :

    <?php
    include 'monphar.phar';
    ?>

ou par simple exécution :

    php monphar.phar

Le chargeur n'est pas utilisé quand un fichier est inclus via le flux `phar` comme ceci :

    <?php
    include 'phar://monphar.phar/unfichier.php';
    ?>

### Liste de paramètres

`stub`

  Une chaîne ou une resource de flux ouvert à utiliser comme conteneur exécutable pour cette archive phar.

`length`
  Longueur de `stub` en octets.
  Avertissement

  Passer l'argument `length` avec une resource dans le premier argument est OBSOLÈTE à partir de PHP 8.3.0. Il faut utiliser `$phar->setStub(stream_get_contents($resource))` à la place.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Une exception UnexpectedValueException est levée si phar.readonly est activé dans le php.ini. Une exception PharException est levée si des problèmes sont rencontrés lors de l'écriture des changements sur le disque.

### Historique

Version | Description
--- | ---
8.4.0 | Le type de retour est maintenant `true`, auparavant il était bool.
8.3.0 | Appeler Phar::setStub() avec une resource et une `length` est désormais obsolète. De tels appels devraient être remplacés par : `$phar->setStub(stream_get_contents($resource));`

### Exemples

Exemple #1 Un exemple avec Phar::setStub()

    <?php

    try {
        $p = new Phar(dirname(__FILE__) . '/nouveau.phar', 0, 'nouveau.phar');
        $p['a.php'] = '<?php var_dump("Salut");';
        $p->setStub('<?php var_dump("Premier"); Phar::mapPhar("nouveau.phar"); __HALT_COMPILER(); ?>');
        include 'phar://nouveau.phar/a.php';
        var_dump($p->getStub());

        $p['b.php'] = '<?php var_dump("Tout le monde");';
        $p->setStub('<?php var_dump("Second"); Phar::mapPhar("nouveau.phar"); __HALT_COMPILER(); ?>');
        include 'phar://nouveau.phar/b.php';
        var_dump($p->getStub());
    } catch (Exception $e) {
        echo 'Erreur lors de l\'écriture de nouveau.phar: ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    string(5) "Salut"
    string(79) "<?php var_dump("Premier"); Phar::mapPhar("nouveau.phar"); __HALT_COMPILER(); ?>"
    string(13) "Tout le monde"
    string(78) "<?php var_dump("Second"); Phar::mapPhar("nouveau.phar"); __HALT_COMPILER(); ?>"

### Voir aussi

- Phar::getStub() - Retourne le chargeur PHP ou le conteneur de chargement d'une archive Phar
- Phar::createDefaultStub() - Crée un conteneur de chargement d'une archive Phar

# Phar::startBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::startBuffering — Démarre la mise en tampon d'écritures Phar, ne modifie pas l'objet Phar sur le disque

### Description

public function Phar::startBuffering(): void

Bien que techniquement inutile, la méthode Phar::startBuffering() peut fournir un gain de performance lors de la création ou la modification d'une archive Phar avec un grand nombre de fichiers. D'ordinaire, chaque fois qu'un fichier au sein de l'archive Phar est créé ou modifié, l'archive Phar entière est recréée en incluant les changements. De cette manière, l'archive sera toujours à jour vis à vis des opérations qui y sont appliquées.

Alors que ceci peut paraître inutile lors de la création d'une archive Phar simple, ça prend tout son sens lors de l'écriture en une fois de l'archive Phar entière. De même, il est souvent nécessaire de faire une série de changements et de s'assurer qu'ils sont tous possibles avant d'écrire sur le disque, un peu comme les transactions des bases de données relationnelles. Les fonctions Phar::startBuffering()/Phar::stopBuffering() sont disponibles dans ce but.

La mise en tampon Phar s'effectue par archive, le tampon actif pour l'archive Phar `foo.phar` n'affecte pas les changements faits à l'archive Phar `bar.phar`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Un exemple avec Phar::startBuffering()

    <?php
    // on s'assure que le phar n'existe pas déjà
    @unlink('nouveau.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveau.phar', 0, 'nouveau.phar');
    } catch (Exception $e) {
        echo 'Ne peut pas créer le phar:', $e;
    }
    echo 'Le nouveau phar a ' . $p->count() . " entrées\n";
    $p->startBuffering();
    $p['fichier.txt'] = 'salut';
    $p['fichier2.txt'] = 'jolie';
    $p['fichier2.txt']->setCompressedGZ();
    $p['fichier3.txt'] = 'môme';
    $p['fichier3.txt']->setMetadata(42);
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://monphar.phar/' . str_replace('_', '/', $class) . '.php';
    }
    Phar::mapPhar('monphar.phar');
    include 'phar://monphar.phar/demarrage.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    ?>

### Voir aussi

- Phar::stopBuffering() - Arrête la mise en tampon des écritures Phar et provoque l'écriture sur le disque
- Phar::isBuffering() - Détermine si les opérations d'écriture du Phar sont mises en tampons ou sont directement inscrites sur le disque

# Phar::stopBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::stopBuffering — Arrête la mise en tampon des écritures Phar et provoque l'écriture sur le disque

### Description

public function Phar::stopBuffering(): void

Phar::stopBuffering() est utilisée en conjonction avec la méthode Phar::startBuffering(). Phar::startBuffering() peut fournir un gain de performance lors de la création ou la modification d'une archive Phar avec un grand nombre de fichiers. D'ordinaire, chaque fois qu'un fichier au sein de l'archive Phar est créé ou modifié, l'archive Phar entière est recréée en incluant les changements. De cette manière, l'archive sera toujours à jour vis à vis des opérations qui y sont appliquées.

Alors que ceci peut paraître inutile lors de la création d'une archive Phar simple, ça prend tout son sens lors de l'écriture en une fois de l'archive Phar entière. De même, il est souvent nécessaire de faire une série de changements et de s'assurer qu'ils sont tous possibles avant d'écrire sur le disque, un peu comme les transactions des bases de données relationnelles. Les fonctions Phar::startBuffering()/Phar::stopBuffering() sont disponibles dans ce but.

La mise en tampon Phar s'effectue par archive, le tampon actif pour l'archive Phar `foo.phar` n'affecte pas les changements faits à l'archive Phar `bar.phar`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Une exception PharException est levée si des problèmes sont rencontrés lors de l'écriture des changements sur le disque.

### Exemples

Exemple #1 Un exemple Phar::stopBuffering()

    <?php
    $p = new Phar(dirname(__FILE__) . '/nouveau.phar', 0, 'nouveau.phar');
    $p['fichier1.txt'] = 'salut';
    $p->startBuffering();
    var_dump($p->getStub());
    $p->setStub("<?php
    function __autoload(\$class)
    {
        include 'phar://nouveau.phar/' . str_replace('_', '/', \$class) . '.php';
    }
    Phar::mapPhar('nouveau.phar');
    include 'phar://nouveau.phar/demarrage.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    var_dump($p->getStub());
    ?>

L'exemple ci-dessus va afficher :

    string(24) "<?php __HALT_COMPILER();"
    string(187) "<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('nouveau.phar');
    include 'phar://nouveau.phar/demarrage.php';
    __HALT_COMPILER();"

### Voir aussi

- Phar::startBuffering() - Démarre la mise en tampon d'écritures Phar, ne modifie pas l'objet Phar sur le disque
- Phar::isBuffering() - Détermine si les opérations d'écriture du Phar sont mises en tampons ou sont directement inscrites sur le disque

# Phar::unlinkArchive

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::unlinkArchive — Efface complètement une archive phar du disque et de la mémoire

### Description

final public static function Phar::unlinkArchive(string `$filename`): true

Efface complètement une archive phar du disque et de la mémoire

### Liste de paramètres

`filename`

  Le chemin sur le disque vers l'archive phar.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Une exception PharException est levée si des pointeurs sont ouverts vers des fichiers de l'archive phar, ou si des objets Phar, PharData, ou PharFileInfo réfèrent à l'archive phar.

### Exemples

Exemple #1 Un exemple avec Phar::unlinkArchive()

    <?php
    // utilisation simple
    Phar::unlinkArchive('/chemin/vers/mon.phar');

    // un exemple plus commun :
    $p = new Phar('mon.phar');
    $fp = fopen('phar://mon.phar/fichier.txt', 'r');
    // cela crée 'mon.phar.gz'
    $gp = $p->compress(Phar::GZ);
    // enlève toutes les références à l'archive
    unset($p);
    fclose($fp);
    // efface maintenant toute trace de l'archive
    Phar::unlinkArchive('mon.phar');
    ?>

### Voir aussi

- Phar::delete() - Efface un fichier au sein d'une archive phar
- Phar::offsetUnset() - Efface un fichier d'un phar

# Phar::webPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::webPhar — Redirige une requête depuis un navigateur web à un fichier interne dans l'archive phar

### Description

final public static function Phar::webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void

Phar::webPhar() sert comme Phar::mapPhar() pour les phars orientés web. Cette méthode parse $_SERVER['REQUEST_URI'] et route les requêtes d'un navigateur vers un fichier interne à l'archive. Cela simule un serveur web, en routant des requêtes vers le bon fichier, en envoyant les bons en-têtes et analysant le fichier PHP comme il convient. Combinée avec Phar::mungServer() et Phar::interceptFileFuncs(), n'importe quelle application web peut être utilisée sans changement à partir de l'archive phar.

Phar::webPhar() doit être appelé uniquement à partir du conteneur de chargement d'une archive phar (lisez ceci pour en savoir davantage sur les conteneurs).

### Liste de paramètres

`alias`

  L'alias qui peut être utilisé dans l'URL `phar://` pour se référer à l'archive, plutôt que son chemin complet.

`index`

  L'emplacement au sein de l'archive de l'index de répertoire.

`fileNotFoundScript`

  L'emplacement du script à exécuter quand un fichier n'est pas trouvé. Ce script doit envoyer des en-têtes HTTP 404 corrects.

`mimeTypes`

  Un tableau faisant correspondre des extensions de fichier supplémentaires à des types MIME. Si les correspondances par défaut suffisent, passez un tableau vide. Par défaut, ces correspondances sont les suivantes :

      <?php
      $mimes = array(
          'phps' => Phar::PHPS, // passage vers highlight_file()
          'c' => 'text/plain',
          'cc' => 'text/plain',
          'cpp' => 'text/plain',
          'c++' => 'text/plain',
          'dtd' => 'text/plain',
          'h' => 'text/plain',
          'log' => 'text/plain',
          'rng' => 'text/plain',
          'txt' => 'text/plain',
          'xsd' => 'text/plain',
          'php' => Phar::PHP, // parse en tant que PHP
          'inc' => Phar::PHP, // parse en tant que PHP
          'avi' => 'video/avi',
          'bmp' => 'image/bmp',
          'css' => 'text/css',
          'gif' => 'image/gif',
          'htm' => 'text/html',
          'html' => 'text/html',
          'htmls' => 'text/html',
          'ico' => 'image/x-ico',
          'jpe' => 'image/jpeg',
          'jpg' => 'image/jpeg',
          'jpeg' => 'image/jpeg',
          'js' => 'application/x-javascript',
          'midi' => 'audio/midi',
          'mid' => 'audio/midi',
          'mod' => 'audio/mod',
          'mov' => 'movie/quicktime',
          'mp3' => 'audio/mp3',
          'mpg' => 'video/mpeg',
          'mpeg' => 'video/mpeg',
          'pdf' => 'application/pdf',
          'png' => 'image/png',
          'swf' => 'application/shockwave-flash',
          'tif' => 'image/tiff',
          'tiff' => 'image/tiff',
          'wav' => 'audio/wav',
          'xbm' => 'image/xbm',
          'xml' => 'text/xml',
      );
      ?>

`rewrite`

  La fonction de ré-écriture prend comme seul paramètre une chaîne et doit retourner une chaîne de caractères ou `false`.

  Lors de l'utilisation de fast-cgi ou cgi, le paramètre passé à la fonction est la valeur de la variable $_SERVER['PATH_INFO']. Sinon, le paramètre passé à la fonction est la valeur de la variable $_SERVER['REQUEST_URI'].

  Si une chaîne est retournée, elle sera utilisée dans le chemin interne du fichier. Si `false` est retourné, alors webPhar() enverra un code HTTP 403.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Lève une exception PharException quand le fichier interne ne peut pas être ouvert ou si l'appel est fait en dehors d'un conteneur. Si une valeur de tableau non valide est passée dans `mimeTypes` ou si une fonction de rappel invalide est passée au paramètre `rewrite`, alors une exception UnexpectedValueException est levée.

### Historique

Version | Description
--- | ---
8.0.0 | `fileNotFoundScript` et `rewrite` sont désormais nullable.

### Exemples

Exemple #1 Exemple avec Phar::webPhar()

Dans l'exemple ci-dessous, le phar créé affichera `Salut tout le monde` si quelqu'un appelle `/monphar.phar/index.php` ou `/monphar.phar`, et affichera la source de `index.phps` si `/monphar.phar/index.phps` est appelé.

    <?php
    // l'archive phar est créée :
    try {
        $phar = new Phar('monphar.phar');
        $phar['index.php'] = '<?php echo "Salut tout le monde"; ?>';
        $phar['index.phps'] = '<?php echo "Salut tout le monde"; ?>';
        $phar->setStub('<?php
    Phar::webPhar();
    __HALT_COMPILER(); ?>');
    } catch (Exception $e) {
        // on traite les erreurs ici
    }
    ?>

### Voir aussi

- Phar::mungServer() - Définit une liste de maximum 4 variables $_SERVER qui doivent être modifiées lors de l'exécution
- Phar::interceptFileFuncs() - Informe phar qu'il doit intercepter les fonctions de fichiers

## Sommaire

- Phar::addEmptyDir — Ajoute un répertoire vide à l'archive phar
- Phar::addFile — Ajoute un fichier du système de fichiers à l'archive phar
- Phar::addFromString — Ajoute un fichier depuis une chaîne de caractères à l'archive phar
- Phar::apiVersion — Retourne la version de l'API
- Phar::buildFromDirectory — Construit une archive phar à partir des fichiers d'un répertoire
- Phar::buildFromIterator — Construit une archive phar à partir d'un itérateur
- Phar::canCompress — Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::canWrite — Détermine si l'extension phar supporte la création et l'écriture des phars
- Phar::compress — Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::compressFiles — Compresse tous les fichiers de l'archive Phar courante
- Phar::__construct — Construit un objet d'archive Phar
- Phar::convertToData — Convertit une archive phar en un fichier non-exécutable
- Phar::convertToExecutable — Convertit une archive phar vers un autre format de fichier d'archive phar exécutable
- Phar::copy — Copie un fichier appartenant à une archive vers un autre fichier de la même archive
- Phar::count — Retourne le nombre d'entrées (fichiers) dans l'archive Phar
- Phar::createDefaultStub — Crée un conteneur de chargement d'une archive Phar
- Phar::decompress — Décompresse l'archive tar complète
- Phar::decompressFiles — Décompresse tous les fichiers de l'archive Phar courante
- Phar::delMetadata — Efface les méta-données globales du phar
- Phar::delete — Efface un fichier au sein d'une archive phar
- Phar::__destruct — Détruit un objet archive Phar
- Phar::extractTo — Extrait le contenu d'une archive phar vers un répertoire
- Phar::getAlias — Récupère l'alias pour Phar
- Phar::getMetadata — Retourne les méta-données de l'archive phar
- Phar::getModified — Indique si le fichier phar a été modifié
- Phar::getPath — Récupère le chemin absolu de l'archive Phar sur le disque
- Phar::getSignature — Retourne la signature MD5/SHA1/SHA256/SHA512 d'une archive Phar
- Phar::getStub — Retourne le chargeur PHP ou le conteneur de chargement d'une archive Phar
- Phar::getSupportedCompression — Retourne un tableau des algorithmes de compression supportés
- Phar::getSupportedSignatures — Retourne un tableau des types de signature supportés
- Phar::getVersion — Retourne les informations de version de l'archive Phar
- Phar::hasMetadata — Détermine si le phar a ou non des méta-données
- Phar::interceptFileFuncs — Informe phar qu'il doit intercepter les fonctions de fichiers
- Phar::isBuffering — Détermine si les opérations d'écriture du Phar sont mises en tampons ou sont directement inscrites sur le disque
- Phar::isCompressed — Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::isFileFormat — Retourne true si l'archive phar est basée sur le format de fichier tar/phar/zip selon le paramètre
- Phar::isValidPharFilename — Détermine si le nom de fichier spécifié est un nom de fichier valide pour une archive phar
- Phar::isWritable — Retourne true si l'archive phar peut être modifiée
- Phar::loadPhar — Charge n'importe quelle archive phar avec un alias
- Phar::mapPhar — Lit le phar exécuté et charge son manifeste
- Phar::mount — Monte un chemin ou un fichier externe à un emplacement virtuel au sein de l'archive phar
- Phar::mungServer — Définit une liste de maximum 4 variables $_SERVER qui doivent être modifiées lors de l'exécution
- Phar::offsetExists — Détermine si un fichier existe dans le phar
- Phar::offsetGet — Obtient un objet PharFileInfo à partir d'un fichier
- Phar::offsetSet — Met le contenu d'un fichier interne à l'archive à l'identique du contenu d'un fichier externe
- Phar::offsetUnset — Efface un fichier d'un phar
- Phar::running — Retourne le chemin complet sur le disque ou l'URL phar complète de l'archive phar couramment exécutée
- Phar::setAlias — Fixe l'alias de l'archive Phar
- Phar::setDefaultStub — Utilisé pour fixer le chargeur PHP ou le conteneur de chargement d'une archive Phar en tant que chargeur par défaut
- Phar::setMetadata — Fixe les métadonnées de l'archive phar
- Phar::setSignatureAlgorithm — Fixe et applique l'algorithme de signature d'un phar
- Phar::setStub — Utilisé pour spécifier le chargeur PHP ou le conteneur de chargement d'une archive Phar
- Phar::startBuffering — Démarre la mise en tampon d'écritures Phar, ne modifie pas l'objet Phar sur le disque
- Phar::stopBuffering — Arrête la mise en tampon des écritures Phar et provoque l'écriture sur le disque
- Phar::unlinkArchive — Efface complètement une archive phar du disque et de la mémoire
- Phar::webPhar — Redirige une requête depuis un navigateur web à un fichier interne dans l'archive phar

# La classe PharData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

## Introduction

La classe PharData fournit une interface de haut niveau pour accéder et créer des archives tar et zip non exécutables. Du fait que ces archives ne contiennent pas de conteneur et qu'elles ne puissent être exécutées par l'extension phar, il est possible de créer et de manipuler des fichiers zip et tar normaux en utilisant la classe PharData même si le paramètre `phar.readonly` du php.ini est à `1`.

## Synopsis de la classe

class PharData extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Constantes héritées */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Méthodes */
public function __construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
public function compress(int `$compression`, ?string `$extension` = `null`): ?PharData
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function decompress(?string `$extension` = `null`): ?PharData
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function isWritable(): bool
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
public function setAlias(string `$alias`): bool
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function __destruct()
/* Méthodes héritées */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharData::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addEmptyDir — Ajoute un répertoire vide à l'archive tar/zip

### Description

public function PharData::addEmptyDir(string `$directory`): void

Avec cette méthode, un répertoire vide est créé avec le chemin `dirname`. Cette méthode est identique à ZipArchive::addEmptyDir().

### Liste de paramètres

`directory`

  Le nom du répertoire vide à créer dans l'archive phar

### Valeurs de retour

aucune valeur de retour, une exception est levée en cas d'échec.

### Exemples

Exemple #1 Un exemple avec PharData::addEmptyDir()

    <?php
    try {
        $a = new PharData('/chemin/vers/mon.tar');

        $a->addEmptyDir('/chemin/complet/vers/fichier');
        // montre comment le fichier est stocké
        $b = $a['chemin/complet/vers/fichier']->isDir();
    } catch (Exception $e) {
        // les erreurs sont traitées ici
    }
    ?>

### Voir aussi

- Phar::addEmptyDir() - Ajoute un répertoire vide à l'archive phar
- PharData::addFile() - Ajoute un fichier du système de fichiers à l'archive tar/zip
- PharData::addFromString() - Ajoute un fichier à partir d'une chaîne de caractères à l'archive tar/zip

# PharData::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFile — Ajoute un fichier du système de fichiers à l'archive tar/zip

### Description

public function PharData::addFile(string `$filename`, ?string `$localName` = `null`): void

Avec cette méthode, n'importe quel fichier ou URL peut être ajouté à l'archive tar/zip. Si le second paramètre optionnel `localname` est spécifié, le fichier sera stocké dans l'archive avec ce nom, sans quoi le paramètre `file` est utilisé comme chemin vers lequel stocker le fichier au sein de l'archive. Les URL doivent avoir un nom local sans quoi une exception est levée. Cette méthode est identique à ZipArchive::addFile().

### Liste de paramètres

`filename`

  Chemin relatif ou absolu vers un fichier du disque à ajouter à l'archive phar.

`localName`

  Chemin vers lequel le fichier sera stocké au sein de l'archive.

### Valeurs de retour

aucune valeur de retour, une exception est levée en cas d'échec.

### Historique

Version | Description
--- | ---
8.0.0 | `localName` est désormais nullable.

### Exemples

Exemple #1 Un exemple avec PharData::addFile()

    <?php
    try {
        $a = new PharData('/chemin/vers/mon.tar');

        $a->addFile('/chemin/complet/vers/fichier');
        // montre comment le fichier est stocké
        $b = $a['chemin/complet/vers/fichier']->getContent();

        $a->addFile('/chemin/complet/vers/fichier', 'mon/fichier.txt');
        $c = $a['mon/fichier.txt']->getContent();

        // montre l'utilisation des URLs
        $a->addFile('http://www.exemple.com', 'exemple.html');
    } catch (Exception $e) {
        // les erreurs sont traitées ici
    }
    ?>

### Notes

> Note: PharData::addFile(), PharData::addFromString() et PharData::offsetSet() enregistre une nouvelle archive phar à chaque fois qu'elles sont appelées. Si les performances sont une préoccupation, PharData::buildFromDirectory() ou PharData::buildFromIterator() devraient être utilisé à la place.

### Voir aussi

- PharData::offsetSet() - Remplit un fichier au sein de l'archive tar/zip avec le contenu d'un fichier externe ou d'une chaîne de caractères
- Phar::addFile() - Ajoute un fichier du système de fichiers à l'archive phar
- PharData::addFromString() - Ajoute un fichier à partir d'une chaîne de caractères à l'archive tar/zip
- PharData::addEmptyDir() - Ajoute un répertoire vide à l'archive tar/zip

# PharData::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFromString — Ajoute un fichier à partir d'une chaîne de caractères à l'archive tar/zip

### Description

public function PharData::addFromString(string `$localName`, string `$contents`): void

Ajoute une chaîne de caractères à l'archive tar/zip. Le fichier sera stocké dans l'archive avec le chemin `localname`. Cette méthode est identique à ZipArchive::addFromString().

### Liste de paramètres

`localName`

  Chemin vers lequel le fichier sera stocké au sein de l'archive.

`contents`

  Le contenu du fichier à stocker

### Valeurs de retour

Aucune valeur de retour, une exception est levée en cas d'échec.

### Exemples

Exemple #1 Exemple avec PharData::addFromString()

    <?php
    try {
        $a = new PharData('/chemin/vers/mon.tar');

        $a->addFromString('chemin/vers/fichier.txt', 'mon fichier simple');
        $b = $a['chemin/vers/fichier.txt']->getContent();

        // pour ajouter du contenu à partir d'un gestionnaire de flux pour des gros fichiers, utiliser offsetSet()
        $c = fopen('/chemin/vers/grosfichier.bin');
        $a['grosfichier.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // les erreurs sont traitées ici
    }
    ?>

### Notes

> Note: Phar::addFile(), Phar::addFromString() et Phar::offsetSet() enregistre une nouvelle archive phar à chaque fois qu'elles sont appelées. Si les performances sont une préoccupation, Phar::buildFromDirectory() ou Phar::buildFromIterator() devraient être utilisé à la place.

### Voir aussi

- PharData::offsetSet() - Remplit un fichier au sein de l'archive tar/zip avec le contenu d'un fichier externe ou d'une chaîne de caractères
- Phar::addFromString() - Ajoute un fichier depuis une chaîne de caractères à l'archive phar
- PharData::addFile() - Ajoute un fichier du système de fichiers à l'archive tar/zip
- PharData::addEmptyDir() - Ajoute un répertoire vide à l'archive tar/zip

# PharData::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromDirectory — Construit une archive tar/zip à partir des fichiers d'un répertoire

### Description

public function PharData::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

Remplit une archive tar/zip à partir du contenu d'un répertoire. Le second paramètre optionnel est une expression rationnelle (pcre) utilisée pour exclure des fichiers. N'importe quel fichier dont le nom satisfait sera inclus, tous les autres seront exclus. Pour un contrôle plus fin, utiliser PharData::buildFromIterator().

### Liste de paramètres

`directory`

  Le chemin relatif ou absolu vers le répertoire contenant tous les fichiers à ajouter à l'archive.

`pattern`

  Une expression rationnelle optionnelle qui est utilisée pour filtrer la liste des fichiers. Seuls les fichiers dont le nom satisfait l'expression seront inclus dans l'archive.

### Valeurs de retour

Phar::buildFromDirectory() retourne un tableau associatif faisant correspondre un chemin de fichier interne vers un chemin complet sur le système de fichiers, ou `false` si une erreur survient.

### Erreurs / Exceptions

Cette méthode soulève une exception BadMethodCallException quand elle est incapable d'instancier les itérateurs internes de répertoire, ou une exception PharException si des erreurs ont été rencontrées lors de l'enregistrement de l'archive phar.

### Historique

Version | Description
--- | ---
8.1.0 | PharData::buildFromDirectory() ne retourne plus `false`.

### Exemples

Exemple #1 Un exemple avec PharData::buildFromDirectory()

    <?php
    $phar = new PharData('projet.tar');
    // ajoute tous les fichiers au projet
    $phar->buildFromDirectory(dirname(__FILE__) . '/projet');

    $phar2 = new PharData('projet2.zip');
    // ajoute tous les fichiers au projet en n'incluant que les fichiers php
    $phar2->buildFromDirectory(dirname(__FILE__) . '/projet', '/\.php$/');
    ?>

### Voir aussi

- Phar::buildFromDirectory() - Construit une archive phar à partir des fichiers d'un répertoire
- PharData::buildFromIterator() - Construit une archive tar ou zip à partir d'un itérateur

# PharData::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromIterator — Construit une archive tar ou zip à partir d'un itérateur

### Description

public function PharData::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

Remplit une archive tar ou zip à partir d'un itérateur. Deux styles d'itérateurs sont supportés, les itérateurs qui font correspondre le chemin de fichier au sein de l'archive avec le chemin sur le disque et les itérateurs comme DirectoryIterator qui retournent des objets SplFileInfo. Pour les itérateurs qui retournent des objets SplFileInfo, le second paramètre est requis.

### Liste de paramètres

`iterator`

  N'importe quel itérateur qui fait correspondre de façon associative un fichier tar/zip ou qui retourne des objets SplFileInfo

`baseDirectory`

  Pour les itérateurs qui retournent des objets SplFileInfo, la partie du chemin complet vers le fichier à enlever lors de l'ajout à l'archive tar/zip

### Valeurs de retour

PharData::buildFromIterator() retourne un tableau associatif faisant correspondre un chemin de fichier interne avec un chemin complet vers le fichier sur le système de fichiers.

### Erreurs / Exceptions

Cette méthode retourne une exception UnexpectedValueException quand l'itérateur retourne des valeurs incorrectes, comme une clé entière plutôt qu'une chaîne, une exception BadMethodCallException quand un itérateur basé sur SplFileInfo est passé sans paramètre `baseDirectory`, ou une exception PharException si des erreurs ont été rencontrées lors de la sauvegarde de l'archive phar.

### Historique

Version | Description
--- | ---
8.1.0 | PharData::buildFromIterator() ne retourne plus `false` désormais.
8.0.0 | `baseDirectory` est désormais nullable.

### Exemples

Exemple #1 Exemple avec PharData::buildFromIterator() et SplFileInfo

Pour la plupart de l'archive tar/zip, l'archive reflétera la structure de répertoire actuelle et le second style est le plus utile. Par exemple, pour créer une archive tar/zip contenant les fichiers contenant la structure de répertoire ci-dessous :

    /chemin/vers/projet/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         fichier1.php
                         fichier2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

Ce code peut être utilisé pour ajouter des fichiers à l'archive "projet.tar" tar :

    <?php
    $phar = new PharData('projet.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/chemin/vers/projet')),
        '/chemin/vers/projet');
    ?>

Le fichier `projet.tar` peut alors être utilisé immédiatement. PharData::buildFromIterator() ne règle pas les paramètres tels que la compression, les métadonnées, ce qui peut être fait après avoir créé l'archive tar/zip.

À noter que Phar::buildFromIterator() peut aussi être utilisé pour copier le contenu d'une archive phar, tar ou zip existante, car l'objet PharData est dérivé de DirectoryIterator :

    <?php
    $phar = new PharData('projet.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/chemin/vers/unautrephar.phar')),
        'phar:///chemin/vers/unautrephar.phar/chemin/vers/projet');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

Exemple #2 Exemple avec PharData::buildFromIterator() et d'autres itérateurs

La seconde forme d'itérateur peut être utilisée avec n'importe quel itérateur qui retourne une association clé => valeur, tel que ArrayIterator :

    <?php
    $phar = new PharData('projet.tar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'interne/fichier.php' => dirname(__FILE__) . '/unfichier.php',
            'unautre/fichier.jpg' => fopen('/chemin/vers/grosfichier.jpg', 'rb'),
         )));
    ?>

### Voir aussi

- Phar::buildFromIterator() - Construit une archive phar à partir d'un itérateur

# PharData::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compress — Compresse l'archive tar/zip complète en utilisant la compression Gzip ou Bzip2

### Description

public function PharData::compress(int `$compression`, ?string `$extension` = `null`): ?PharData

Pour les archives tar, cette méthode compresse l'archive entière en utilisant la compression gzip ou bzip2. Le fichier qui en résulte peut être manipulé avec la commande gunzip/bunzip, ou être accédé directement et de façon transparente avec l'extension Phar.

Pour les archives zip, cette méthode échoue en levant une exception. L'extension zlib doit être activée pour compresser avec gzip, l'extension bzip2 doit être activée pour compresser avec bzip2.

De plus, cette méthode renomme automatiquement l'archive, en la suffixant par `.gz`, `.bz2` ou en enlevant l'extension si `Phar::NONE` est spécifié pour enlever la compression. Sinon, une extension de fichier peut être spécifiée avec le second paramètre.

### Liste de paramètres

`compression`

  La compression doit être `Phar::GZ` ou `Phar::BZ2` pour appliquer une compression, ou `Phar::NONE` pour l'enlever.

`extension`

  Par défaut, l'extension est `.tar.gz` ou `.tar.bz2` pour compresser un tar, et `.tar` pour décompresser.

### Valeurs de retour

Un objet PharData est retourné en cas de succès, `null` en cas d'échec.

### Erreurs / Exceptions

Soulève une exception BadMethodCallException si l'extension zlib n'est pas disponible, ou si l'extension bzip2 n'est pas activée.

### Historique

Version | Description
--- | ---
8.0.0 | `extension` est désormais nullable.

### Exemples

Exemple #1 Un exemple avec PharData::compress()

    <?php
    $p = new PharData('/chemin/vers/mon.tar');
    $p['monfichier.txt'] = 'salut';
    $p['monfichier2.txt'] = 'salut';
    $p1 = $p->compress(Phar::GZ); // copie vers /chemin/vers/mon.tar.gz
    $p2 = $p->compress(Phar::BZ2); // copie vers /chemin/vers/mon.tar.bz2
    $p3 = $p2->compress(Phar::NONE); // exception : /chemin/vers/mon.tar existe déjà
    ?>

### Voir aussi

- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2

# PharData::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compressFiles — Compresse tous les fichiers de l'archive tar/zip courante

### Description

public function PharData::compressFiles(int `$compression`): void

Pour les archives basées sur tar, cette méthode soulève une exception BadMethodCallException car la compression individuelle des fichiers d'une archive tar n'est pas supportée par ce format de fichiers. Utiliser PharData::compress() pour compresser une archive basée sur tar complète.

Pour les archives basées sur Zip, cette méthode compresse tous les fichiers de l'archive en utilisant la compression spécifiée. Les extensions zlib ou bzip2 doivent être activées pour tirer parti de cette fonctionnalité. De plus, si au moins un fichier est déjà compressé en utilisant la compression bzip2/zlib, l'extension adéquate doit être activée pour décompresser les fichiers avant de les re-compresser.

### Liste de paramètres

`compression`

  La compression doit être `Phar::GZ` ou `Phar::BZ2` pour appliquer une compression, ou `Phar::NONE` pour l'enlever.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Soulève une exception BadMethodCallException si la variable INI phar.readonly est à on, si l'extension zlib n'est pas disponible ou si au moins un fichier est compressé via bzip2 et que l'extension bzip2 n'est pas activée.

### Exemples

Exemple #1 Un exemple avec PharData::compressFiles()

    <?php
    $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
    $p['monfichier.txt'] = 'salut';
    $p['monfichier2.txt'] = 'salut';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

L'exemple ci-dessus va afficher :

    string(14) "monfichier.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "monfichier2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(14) "monfichier.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "monfichier2.txt"
    int(4096)
    bool(false)
    bool(true)

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- PharData::decompressFiles() - Décompresse tous les fichiers de l'archive zip courante
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- PharData::compress() - Compresse l'archive tar/zip complète en utilisant la compression Gzip ou Bzip2
- PharData::decompress() - Décompresse l'archive Phar entière

# PharData::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__construct — Construit un objet d'archive tar ou zip non-exécutable

### Description

public function PharData::__construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)

### Liste de paramètres

`filename`

  Chemin vers une archive tar/zip existante ou à créer

`flags`

  Drapeaux à passer à la classe parente Phar RecursiveDirectoryIterator.

`alias`

  L'alias de l'archive Phar à utiliser lors des appels aux fonctionnalités de flux.

`format`

  Une des constantes de format de fichier disponible dans la classe Phar.

### Erreurs / Exceptions

Soulève une exception BadMethodCallException si appelée deux fois, une exception UnexpectedValueException si l'archive phar ne peut pas être ouverte.

### Exemples

Exemple #1 Un exemple avec PharData::__construct()

    <?php
    try {
        $p = new PharData('/chemin/vers/mon.tar', Phar::CURRENT_AS_FILEINFO | Phar::KEY_AS_FILENAME);
    } catch (UnexpectedValueException $e) {
        die('Ne peut pas ouvrir mon.tar');
    } catch (BadMethodCallException $e) {
        echo 'techniquement, ça ne peut pas arriver';
    }
    echo file_get_contents('phar:///chemin/vers/mon.tar/exemple.txt');
    ?>

# PharData::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToData — Convertit une archive phar en une archive tar ou zip non-exécutable

### Description

public function PharData::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

Cette méthode est utilisée pour convertir une archive non exécutable tar ou zip en un autre format non-exécutable.

Si aucun changement n'est demandé, cette méthode soulève une exception BadMethodCallException. Cette méthode doit être utilisée pour convertir une archive tar au format zip et vice-versa. Bien qu'il soit possible de changer la compression d'une archive tar avec cette méthode, il est préférable d'utiliser la méthode PharData::compress() pour rester cohérent au niveau de la logique.

En cas de succès, cette méthode crée une nouvelle archive sur le disque et retourne un objet PharData. L'ancienne archive n'est pas effacée du disque, ceci devant être fait manuellement une fois le traitement terminé.

### Liste de paramètres

`format`

  Le format doit être `Phar::TAR` ou `Phar::ZIP`. S'il vaut `null`, le format de fichier actuel sera conservé.

`compression`

  La compression doit être `Phar::NONE` pour éviter la compression de l'archive complète, `Phar::GZ` pour la compression basée sur zlib, et `Phar::BZ2` pour la compression basée sur bzip.

`extension`

  Ce paramètre est utilisé pour écraser l'extension de fichier par défaut de l'archive convertie. Notez que `.phar` ne peut pas être utilisé n'importe où dans le nom de fichier d'une archive tar ou zip non-exécutable.

  En cas de conversion vers une archive phar basée sur tar, les extensions par défaut sont `.tar`, `.tar.gz` et `.tar.bz2` selon la compression spécifiée. Pour les archives basées sur zip, l'extension par défaut est `.zip`.

### Valeurs de retour

Cette méthode retourne un objet PharData en cas de succès, ou `null` en cas d'échec.

### Erreurs / Exceptions

Cette méthode soulève une exception BadMethodCallException quand elle est incapable de compresser, quand une méthode de compression inconnue a été spécifiée, quand l'archive demandée est mise en tampon avec Phar::startBuffering() et qu'elle n'a pas été conclue avec Phar::stopBuffering(), et soulève une exception PharException si un quelconque problème est rencontré lors de la création du phar.

### Historique

Version | Description
--- | ---
8.0.0 | `format`, `compression`, et `extension` sont désormais nullable.

### Exemples

Exemple #1 Un exemple avec PharData::convertToData()

Utilisons PharData::convertToData():

    <?php
    try {
        $tarphar = new PharData('monphar.tar');
        // notez que monphar.tar n'est *pas* effacé
        // le convertir au format tar non-exécutable
        // crée monphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // crée monphar.tbz
        $tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // crée monphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // soulève une exception
    } catch (Exception $e) {
        // les erreurs sont traitées ici
    }
    ?>

### Voir aussi

- Phar::convertToExecutable() - Convertit une archive phar vers un autre format de fichier d'archive phar exécutable
- Phar::convertToData() - Convertit une archive phar en un fichier non-exécutable
- PharData::convertToExecutable() - Convertit une archive tar/zip non-exécutable en une archive phar exécutable

# PharData::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToExecutable — Convertit une archive tar/zip non-exécutable en une archive phar exécutable

### Description

public function PharData::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Cette méthode est utilisée pour convertir une archive tar ou zip non-exécutable en une archive phar exécutable. N'importe lequel des trois formats de fichier (phar, tar ou zip) peut être utilisé et la compression de l'archive complète est aussi possible.

Si aucun changement n'est demandé, cette méthode soulève une exception BadMethodCallException.

En cas de succès, cette méthode crée une nouvelle archive sur le disque et retourne un objet Phar. L'ancienne archive n'est pas effacée du disque, ceci devant être fait manuellement une fois le traitement terminé.

### Liste de paramètres

`format`

  Le format doit être `Phar::PHAR`, `Phar::TAR` ou `Phar::ZIP`. S'il vaut `null`, le format de fichier actuel sera conservé.

`compression`

  La compression doit être `Phar::NONE` pour éviter la compression de l'archive complète, `Phar::GZ` pour la compression basée sur zlib, et `Phar::BZ2` pour la compression basée sur bzip.

`extension`

  Ce paramètre est utilisé pour écraser l'extension de fichier par défaut de l'archive convertie. Notez que toutes les archives basées sur tar et sur zip doivent contenir `.phar` dans leur extension de fichier pour pouvoir être traitées comme des archives phar.

  En cas de conversion vers une archive basée sur phar, les extensions par défaut sont `.phar`, `.phar.gz` ou `.phar.bz2` selon la compression spécifiée. Pour les archives phar basées sur tar, les extensions par défaut sont `.phar.tar`, `.phar.tar.gz` et `.phar.tar.bz2`. Pour les archives phar basées sur zip, l'extension par défaut est `.phar.zip`.

### Valeurs de retour

Cette méthode retourne un objet Phar en cas de succès, ou `null` en cas d'échec

### Erreurs / Exceptions

Cette méthode soulève une exception BadMethodCallException quand elle est incapable de compresser, quand une méthode de compression inconnue a été spécifiée, quand l'archive demandée est mise en tampon avec Phar::startBuffering() et qu'elle n'a pas été conclue avec Phar::stopBuffering(), soulève une exception UnexpectedValueException si le support en écriture est désactivé, et soulève une exception PharException si des problèmes ont été rencontrés lors de la création du phar.

### Historique

Version | Description
--- | ---
8.0.0 | `format`, `compression`, et `localName` sont désormais nullable.

### Exemples

Exemple #1 Un exemple avec PharData::convertToExecutable()

Utilisons PharData::convertToExecutable() :

    <?php
    try {
        $tarphar = new PharData('monphar.tar');
        // le convertit au format de fichier phar
        // notez que monphar.tar n'est *pas* effacé
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // crée monphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // crée monphar.phar.tgz
        $compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // les erreurs sont traitées ici
    }
    ?>

### Voir aussi

- Phar::convertToExecutable() - Convertit une archive phar vers un autre format de fichier d'archive phar exécutable
- Phar::convertToData() - Convertit une archive phar en un fichier non-exécutable
- PharData::convertToData() - Convertit une archive phar en une archive tar ou zip non-exécutable

# PharData::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::copy — Copie un fichier interne à l'archive tar/zip vers un autre fichier au sein de la même archive

### Description

public function PharData::copy(string `$from`, string `$to`): true

Copie un fichier interne à l'archive tar/zip vers un autre fichier au sein de la même archive. C'est une alternative orientée objet à l'utilisation de copy() avec le gestionnaire de flux phar.

### Liste de paramètres

`from`

`to`

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

lève une exception UnexpectedValueException si le fichier source n'existe pas, si le fichier de destination existe déjà, si le support en écriture est désactivé, si l'ouverture d'un des deux fichiers échoue ou si la lecture du fichier source échoue ; ou lève une exception PharException si l'écriture des changements de l'archive phar échoue.

### Exemples

Exemple #1 Un exemple avec PharData::copy()

Cet exemple montre l'utilisation de PharData::copy() et de son équivalent en termes de gestionnaire de flux. La différence principale entre les deux façons de faire concerne la gestion des erreurs. Toutes les méthodes PharData soulèvent des exceptions, alors que le gestionnaire de flux utilise trigger_error().

    <?php

    try {
        $phar = new PharData('monphar.tar');
        $phar['a'] = 'salut';
        $phar->copy('a', 'b');
        echo $phar['b']; // Affiche "phar://monphar.tar/b"
    } catch (Exception $e) {
        // On traite les erreurs
    }

    // l'équivalent en termes de flux de l'exemple ci-dessus.
    // des E_WARNING sont lancés en cas d'erreur à la place d'exceptions.
    copy('phar://monphar.tar/a', 'phar//monphar.tar/c');
    echo file_get_contents('phar://monphar.tar/c'); // Affiche "salut"
    ?>

# PharData::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompress — Décompresse l'archive Phar entière

### Description

public function PharData::decompress(?string `$extension` = `null`): ?PharData

Décompresse l'archive entière, si c'est une archive tar.

Pour les archives Zip, cette méthode échoue et lève une exception. L'extension zlib doit être activée pour décompresser une archive compressée avec gzip et l'extension bzip2 doit être disponible pour décompresser une archive compressée avec bzip2.

De plus, cette méthode renomme automatiquement l'extension de fichier de l'archive, `.tar` par défaut. Sinon, une extension de fichier peut être spécifiée avec le paramètre `extension`.

### Liste de paramètres

`extension`

  Pour décompresser, l'extension par défaut est `.tar`. Utiliser ce paramètre pour spécifier une autre extension de fichier. Gardez à l'esprit que seules les archives exécutables peuvent contenir `.phar` dans leur nom de fichier.

### Valeurs de retour

Un objet PharData est retourné en cas de succès, ou `null` en cas d'échec.

### Erreurs / Exceptions

Soulève une exception BadMethodCallException si l'extension zlib n'est pas disponible ou si l'extension bzip2 n'est pas activée.

### Historique

Version | Description
--- | ---
8.0.0 | `extension` est désormais nullable.

### Exemples

Exemple #1 Exemple avec PharData::decompress()

    <?php
    $p = new PharData('/path/to/my.tar.gz');
    $p->decompress(); // crée /path/to/my.tar
    ?>

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- PharData::compress() - Compresse l'archive tar/zip complète en utilisant la compression Gzip ou Bzip2
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- PharData::compress() - Compresse l'archive tar/zip complète en utilisant la compression Gzip ou Bzip2
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- PharData::compressFiles() - Compresse tous les fichiers de l'archive tar/zip courante
- PharData::decompressFiles() - Décompresse tous les fichiers de l'archive zip courante

# PharData::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompressFiles — Décompresse tous les fichiers de l'archive zip courante

### Description

public function PharData::decompressFiles(): true

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Pour les archives basées sur tar, cette méthode soulève une exception BadMethodCallException, car la compression individuelle des fichiers au sein d'une archive tar n'est pas supportée par le format de fichier. Utiliser PharData::compress() pour compresser une archive basée sur tar complète.

Pour les archives basées sur Zip, cette méthode décompresse tous les fichiers de l'archive. Les extensions zlib ou bzip2 doivent être activées pour tirer parti de cette fonctionnalité si au moins un des fichiers est compressé avec bzip2/zlib.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Soulève une exception BadMethodCallException si l'extension zlib n'est pas disponible ou si au moins un des fichiers est compressé avec bzip2 et que l'extension bzip2 n'est pas activée.

### Exemples

Exemple #1 Un exemple avec PharData::decompressFiles()

    <?php
    $p = new PharData('/chemin/vers/mon.zip');
    $p['monfichier.txt'] = 'salut';
    $p['monfichier2.txt'] = 'salut';
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->decompressFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

L'exemple ci-dessus va afficher :

    string(14) "monfichier.txt"
    int(4096)
    bool(false)
    bool(true)
    string(15) "monfichier2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(14) "monfichier.txt"
    bool(false)
    bool(false)
    bool(false)
    string(15) "monfichier2.txt"
    bool(false)
    bool(false)
    bool(false)

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- PharData::compressFiles() - Compresse tous les fichiers de l'archive tar/zip courante
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- PharData::compress() - Compresse l'archive tar/zip complète en utilisant la compression Gzip ou Bzip2
- PharData::decompress() - Décompresse l'archive Phar entière

# PharData::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delMetadata — Efface les méta-données globales d'une archive zip

### Description

public function PharData::delMetadata(): true

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Efface les méta-données globales de l'archive zip

### Liste de paramètres

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Soulève une exception PharException si des erreurs sont rencontrées lors de l'écriture des changements sur le disque.

### Exemples

Exemple #1 Un exemple avec PharData::delMetaData()

    <?php
    try {
        $phar = new PharData('monphar.zip');
        var_dump($phar->getMetadata());
        $phar->setMetadata("salut");
        var_dump($phar->getMetadata());
        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // on traite les erreurs
    }
    ?>

L'exemple ci-dessus va afficher :

    NULL
    string(5) "salut"
    NULL

### Voir aussi

- Phar::delMetadata() - Efface les méta-données globales du phar

# PharData::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delete — Efface un fichier au sein de l'archive tar/zip

### Description

public function PharData::delete(string `$localName`): true

Efface un fichier au sein de l'archive. C'est l'équivalent fonctionnel de l'appel à unlink() à l'aide du gestionnaire de flux phar, comme montré dans l'exemple ci-dessous.

### Liste de paramètres

`localName`

  Chemin du fichier à effacer au sein de l'archive.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Soulève une exception PharException si des erreurs sont rencontrées lors de l'écriture des changements sur le disque.

### Exemples

Exemple #1 Un exemple avec PharData::delete()

    <?php
    try {
        $phar = new PharData('monphar.zip');
        $phar->delete('efface/moi.php');
        // c'est l'équivalent de :
        unlink('phar://monphar.phar/efface/moi.php');
    } catch (Exception $e) {
        // on traite les erreurs
    }
    ?>

### Voir aussi

- Phar::delete() - Efface un fichier au sein d'une archive phar

# PharData::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__destruct — Détruit un objet non exécutable tar ou une archive zip

### Description

public function PharData::__destruct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# PharData::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::extractTo — Extrait le contenu d'une archive tar/zip vers un répertoire

### Description

public function PharData::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Extrait tous les fichiers d'une archive tar/zip vers le disque. Les fichiers et les répertoires extraits conservent les permissions telles qu'au sein de l'archive. Les paramètres optionnels permettent un éventuel contrôle sur quels fichiers seront extraits et si les fichiers déjà présents sur le disque peuvent être écrasés. Le second paramètre `files` peut être le nom d'un fichier ou d'un répertoire à extraire, ou tableau de noms de fichiers et de répertoires à extraire. Par défaut, cette méthode n'écrasera aucun fichier déjà existant, à moins que le troisième paramètre soit à `true`. Cette méthode est identique à ZipArchive::extractTo().

### Liste de paramètres

`directory`

  Chemin où les fichiers seront extraits.

`files`

  Le nom d'un fichier ou d'un répertoire à extraire, ou un tableau de fichiers/répertoires à extraire

`overwrite`

  Le passer à `true` pour activer l'écrasement des fichiers déjà existants

### Valeurs de retour

Retourne `true` en cas de succès, mais il est préférable de vérifier les exceptions soulevées et de considérer le succès si aucune ne l'est.

### Erreurs / Exceptions

Soulève une exception PharException si des erreurs sont rencontrées lors de l'écriture des changements sur le disque.

### Exemples

Exemple #1 Exemple avec PharData::extractTo()

    <?php
    try {
        $phar = new PharData('monphar.tar');
        $phar->extractTo('/chemin/complet'); // extrait tous les fichiers
        $phar->extractTo('/un/autre/chemin', 'fichier.txt'); // extrait seulement fichier.txt
        $phar->extractTo('/ce/chemin',
            array('fichier1.txt', 'fichier2.txt')); // extrait seulement 2 fichiers
        $phar->extractTo('/troisieme/chemin', null, true); // extrait tous les fichiers, en écrasant
    } catch (Exception $e) {
        // on traite les erreurs
    }
    ?>

### Notes

> Note: Les systèmes de fichiers NTFS Windows ne supportent pas certain caractères dans le noms de fichier, à savoir `<|>*?":`. Les noms de fichiers avec un point trainant ne sont également pas supporté. Contrairement à certains outils d'extraction, cette méthode ne remplace pas ces caractères avec un tiret bas, mais échoue à extraire de tel fichiers.

### Voir aussi

- Phar::extractTo() - Extrait le contenu d'une archive phar vers un répertoire

# PharData::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::isWritable — Vérifie si l'archive tar/zip peut être modifiée

### Description

public function PharData::isWritable(): bool

Cette méthode retourne `true` si l'archive tar/zip sur le disque n'est pas en lecture seule. Contrairement à Phar::isWritable(), les archives tar/zip de données peuvent être modifiées même si `phar.readonly` est à `1`.

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

Retourne `true` si l'archive tar/zip peut être modifiée

### Voir aussi

- Phar::canWrite() - Détermine si l'extension phar supporte la création et l'écriture des phars
- Phar::isWritable() - Retourne true si l'archive phar peut être modifiée

# PharData::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetSet — Remplit un fichier au sein de l'archive tar/zip avec le contenu d'un fichier externe ou d'une chaîne de caractères

### Description

public function PharData::offsetSet(string `$localName`, resource|string `$value`): void

C'est une implémentation de l'interface ArrayAccess permettant la manipulation directe du contenu d'une archive tar/zip en utilisant les crochets, opérateurs d'accès au tableau. offsetSet est utilisé pour modifier un fichier existant ou pour ajouter un nouveau fichier à l'archive tar/zip.

### Liste de paramètres

`localName`

  Le chemin (relatif) du fichier à modifier au sein de l'archive tar ou zip.

`value`

  Contenu du fichier.

### Valeurs de retour

Aucune valeur de retour.

### Erreurs / Exceptions

Soulève une exception PharException si des problèmes ont été rencontrés lors de l'écriture sur le disque des changements de l'archive tar/zip.

### Exemples

Exemple #1 Un exemple avec PharData::offsetSet()

offsetSet ne doit pas être accédé directement, mais plutôt utilisé via l'opérateur `[]`.

    <?php
    $p = new PharData('/chemin/vers/mon.tar');
    try {
        // appelle offsetSet
        $p['fichier.txt'] = 'Salut';
    } catch (Exception $e) {
        echo 'Ne peut pas modifier fichier.txt:', $e;
    }
    ?>

### Notes

> Note: Phar::addFile(), Phar::addFromString() et Phar::offsetSet() enregistre une nouvelle archive phar à chaque fois qu'elles sont appelées. Si les performances sont une préoccupation, Phar::buildFromDirectory() ou Phar::buildFromIterator() devraient être utilisé à la place.

### Voir aussi

- Phar::offsetSet() - Met le contenu d'un fichier interne à l'archive à l'identique du contenu d'un fichier externe

# PharData::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetUnset — Efface un fichier d'une archive tar/zip

### Description

public function PharData::offsetUnset(string `$localName`): void

C'est une implémentation de l'interface ArrayAccess permettant la manipulation directe du contenu d'une archive tar/zip en utilisant les crochets, opérateurs d'accès au tableau. offsetUnset est utilisé pour effacer un fichier existant et est appelé par la construction de langage unset().

### Liste de paramètres

`localName`

  Le chemin (relatif) du fichier à modifier au sein de l'archive tar ou zip.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Soulève une exception PharException si des problèmes ont été rencontrés lors de l'écriture sur le disque des changements de l'archive tar/zip.

### Exemples

Exemple #1 Un exemple avec PharData::offsetUnset()

    <?php
    $p = new PharData('/chemin/vers/mon.zip');
    try {
        // efface fichier.txt de mon.zip en appelant offsetUnset
        unset($p['fichier.txt']);
    } catch (Exception $e) {
        echo 'Ne peut pas effacer fichier.txt: ', $e;
    }
    ?>

### Voir aussi

- Phar::offsetUnset() - Efface un fichier d'un phar

# PharData::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setAlias — Fonction inutile (Phar::setAlias n'est pas valide pour PharData)

### Description

public function PharData::setAlias(string `$alias`): bool

Les archives tar/zip non exécutables ne peuvent pas avoir d'alias, donc cette méthode ne fait que soulever une exception.

### Liste de paramètres

`alias`

  Une courte chaîne de caractères à laquelle se référer pour faire appel à l'archive via le gestionnaire de flux phar. Ce paramètre est ignoré.

### Valeurs de retour

### Erreurs / Exceptions

Soulève une exception PharException lors de l'appel à la méthode

### Voir aussi

- Phar::setAlias() - Fixe l'alias de l'archive Phar

# PharData::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setDefaultStub — Fonction inutile (Phar::setDefaultStub n'est pas valide pour PharData)

### Description

public function PharData::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool

Les archives tar/zip non-exécutables ne peuvent pas avoir de conteneur de chargement, donc cette méthode ne fait que soulever une exception.

### Liste de paramètres

`index`

  Chemin relatif au sein de l'archive phar à exécuter en cas d'accès à partir de la ligne de commande

`webIndex`

  Chemin relatif au sein de l'archive phar à exécuter en cas d'accès à partir d'un navigateur

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Soulève une exception PharException lors de l'appel à la méthode

### Historique

Version | Description
--- | ---
8.0.0 | `webIndex` est désormais nullable.

### Voir aussi

- Phar::setDefaultStub() - Utilisé pour fixer le chargeur PHP ou le conteneur de chargement d'une archive Phar en tant que chargeur par défaut

# PharData::setMetadata

(No version information available, might only be in Git)

PharData::setMetadata — Fixe les méta-données de l'archive

### Description

public function PharData::setMetadata(mixed `$metadata`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Phar::setMetadata() doit être utilisé pour stocker des méta-données personnalisées qui décrivent quelque chose à propos de l'archive phar en tant qu'entité complète. PharFileInfo::setMetadata() doit être utilisé pour les méta-données spécifiques aux fichiers. Les méta-données peuvent dégrader les performances de chargement d'une archive phar si les données sont trop lourdes.

Les méta-données peuvent être utilisées pour spécifier quel fichier au sein de l'archive doit être utilisé pour charger l'archive ou l'emplacement d'un fichier de manifeste comme le fichier package.xml de » PEAR. De manière générale, n'importe quelle donnée utile décrivant l'archive phar peut être stockée.

### Liste de paramètres

`metadata`

  N'importe quelle variable PHP contenant de l'information à stocker pour décrire l'archive phar

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Un exemple avec Phar::setMetadata()

    <?php
    // on s'assure que le phar n'existe pas
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.php'] = '<?php echo "salut"';
        $p->setMetadata(array('chargement' => 'fichier.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Ne peut pas créer/modifier le phar:', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["chargement"]=>
      string(11) "fichier.php"
    }

### Voir aussi

- Phar::getMetadata() - Retourne les méta-données de l'archive phar
- Phar::delMetadata() - Efface les méta-données globales du phar
- Phar::hasMetadata() - Détermine si le phar a ou non des méta-données

# PharData::setSignatureAlgorithm

(No version information available, might only be in Git)

PharData::setSignatureAlgorithm — Assigne l'algorithme de signature d'un phar et l'applique

### Description

public function PharData::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Note: Cette méthode nécessite que la variable de configuration INI `phar.readonly` soit définie à `0` pour fonctionner avec les objets Phar. Sinon, une exception PharException sera lançée.

Assigne l'algorithme de signature d'un phar et l'applique. L'algorithme de signature doit être `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, ou `Phar::OPENSSL`.

### Liste de paramètres

`algo`

  Un algorithme parmi `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, ou `Phar::OPENSSL`.

`privateKey`

  Le contenu d'une clé privée OpenSSL, comme extrait depuis un certificat ou un fichier de clé OpenSSL :

      <?php
      $private = openssl_get_privatekey(file_get_contents('private.pem'));
      $pkey = '';
      openssl_pkey_export($private, $pkey);
      $p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
      ?>

  Voir l'introduction Phar pour des consignes de nommage et de placement de fichier de clé publique.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Soulève une exception UnexpectedValueException pour beaucoup d'erreurs, une exception BadMethodCallException si l'appel est fait pour une archive phar basée sur tar ou sur zip, une exception PharException si des problèmes sont rencontrés lors de l'écriture des changements sur le disque.

### Historique

Version | Description
--- | ---
8.0.0 | `privateKey` est désormais nullable.

### Voir aussi

- Phar::getSupportedSignatures() - Retourne un tableau des types de signature supportés
- Phar::getSignature() - Retourne la signature MD5/SHA1/SHA256/SHA512 d'une archive Phar

# PharData::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setStub — Fonction inutile (Phar::setStub n'est pas valide pour PharData)

### Description

public function PharData::setStub(resource|string `$stub`, int `$length` = -1): true

Les archives tar/zip non-exécutables ne peuvent pas avoir de conteneur de chargement, donc cette méthode ne fait que soulever une exception.

### Liste de paramètres

`stub`
  Formellement, une chaîne de caractères ou un gestionnaire de flux ouvert à utiliser en tant que conteneur de chargement exécutable pour l'archive phar. Ce paramètre est ignoré.
`length`
  `stub` en octets. Ce paramètre est ignoré.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Soulève une exception PharException lors de tout appel à la méthode

### Historique

Version | Description
--- | ---
8.4.0 | Le type de retour est maintenant `true`, auparavant il était bool.

### Voir aussi

- Phar::setStub() - Utilisé pour spécifier le chargeur PHP ou le conteneur de chargement d'une archive Phar

## Sommaire

- PharData::addEmptyDir — Ajoute un répertoire vide à l'archive tar/zip
- PharData::addFile — Ajoute un fichier du système de fichiers à l'archive tar/zip
- PharData::addFromString — Ajoute un fichier à partir d'une chaîne de caractères à l'archive tar/zip
- PharData::buildFromDirectory — Construit une archive tar/zip à partir des fichiers d'un répertoire
- PharData::buildFromIterator — Construit une archive tar ou zip à partir d'un itérateur
- PharData::compress — Compresse l'archive tar/zip complète en utilisant la compression Gzip ou Bzip2
- PharData::compressFiles — Compresse tous les fichiers de l'archive tar/zip courante
- PharData::__construct — Construit un objet d'archive tar ou zip non-exécutable
- PharData::convertToData — Convertit une archive phar en une archive tar ou zip non-exécutable
- PharData::convertToExecutable — Convertit une archive tar/zip non-exécutable en une archive phar exécutable
- PharData::copy — Copie un fichier interne à l'archive tar/zip vers un autre fichier au sein de la même archive
- PharData::decompress — Décompresse l'archive Phar entière
- PharData::decompressFiles — Décompresse tous les fichiers de l'archive zip courante
- PharData::delMetadata — Efface les méta-données globales d'une archive zip
- PharData::delete — Efface un fichier au sein de l'archive tar/zip
- PharData::__destruct — Détruit un objet non exécutable tar ou une archive zip
- PharData::extractTo — Extrait le contenu d'une archive tar/zip vers un répertoire
- PharData::isWritable — Vérifie si l'archive tar/zip peut être modifiée
- PharData::offsetSet — Remplit un fichier au sein de l'archive tar/zip avec le contenu d'un fichier externe ou d'une chaîne de caractères
- PharData::offsetUnset — Efface un fichier d'une archive tar/zip
- PharData::setAlias — Fonction inutile (Phar::setAlias n'est pas valide pour PharData)
- PharData::setDefaultStub — Fonction inutile (Phar::setDefaultStub n'est pas valide pour PharData)
- PharData::setMetadata — Fixe les méta-données de l'archive
- PharData::setSignatureAlgorithm — Assigne l'algorithme de signature d'un phar et l'applique
- PharData::setStub — Fonction inutile (Phar::setStub n'est pas valide pour PharData)

# La classe PharFileInfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Introduction

La classe PharFileInfo fournit une interface de haut niveau pour accéder au contenu et aux attributs d'un fichier contenu dans une archive phar.

## Synopsis de la classe

class PharFileInfo extends SplFileInfo {
/* Méthodes */
public function __construct(string `$filename`)
public function chmod(int `$perms`): void
public function compress(int `$compression`): true
public function decompress(): true
public function delMetadata(): true
public function getCRC32(): int
public function getCompressedSize(): int
public function getContent(): string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getPharFlags(): int
public function hasMetadata(): bool
public function isCRCChecked(): bool
public function isCompressed(?int `$compression` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function __destruct()
/* Méthodes héritées */
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharFileInfo::chmod

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::chmod — Fixe les bits de permission spécifiques aux fichiers

### Description

public function PharFileInfo::chmod(int `$perms`): void

PharFileInfo::chmod() permet de fixer les bits d'exécution des fichiers, ainsi que ceux de lecture seule. Ceux d'écriture sont ignorés car fixés au démarrage par la variable INI phar.readonly. Comme avec toutes les fonctionnalités qui modifient le contenu d'un phar, la variable INI phar.readonly doit être à off pour réussir si le fichier est au sein d'une archive Phar. Les fichiers au sein d'une archive PharData n'ont pas cette restriction.

### Liste de paramètres

`perms`

  Les permissions (voir chmod())

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Un exemple avec PharFileInfo::chmod()

    <?php
    // on s'assure que le phar n'existe pas
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar('nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.sh'] = '#!/usr/local/lib/php
        <?php echo "salut"; ?>';
        // met le bit d'exécution
        $p['fichier.sh']->chmod(0555);
        var_dump($p['fichier.sh']->isExecutable());
    } catch (Exception $e) {
        echo 'Ne peut pas créer/modifier le phar: ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

# PharFileInfo::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::compress — Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2

### Description

public function PharFileInfo::compress(int `$compression`): true

Cette méthode compresse le fichier au sein de l'archive Phar en utilisant l'une des compressions bzip2 ou zlib. Les extensions bzip2 ou zlib doivent être activées pour tirer parti de cette fonctionnalité. De plus, si le fichier est déjà compressé, l'extension adéquate doit être activée pour le décompresser. Comme avec toutes les fonctionnalités qui modifient le contenu d'un phar, la variable INI phar.readonly doit être à off pour réussir si le fichier est au sein d'une archive Phar. Les fichiers au sein d'archives PharData n'ont pas cette restriction.

### Liste de paramètres

`compression`

  La compression doit être `Phar::GZ` ou `Phar::BZ2`.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Soulève une exception BadMethodCallException si la variable INI phar.readonly est à on, ou si l'extension bzip2/zlib n'est pas disponible.

### Exemples

Exemple #1 Un exemple avec PharFileInfo::compress()

    <?php
    try {
        $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'salut';
        $file = $p['monfichier.txt'];
        var_dump($file->isCompressed(Phar::BZ2));
        $p['monfichier.txt']->compress(Phar::BZ2);
        var_dump($file->isCompressed(Phar::BZ2));
    } catch (Exception $e) {
        echo 'Ne peut pas créer/modifier mon.phar : ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante
- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::decompress() - Décompresse l'archive tar complète
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés

# PharFileInfo::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__construct — Construit un objet d'entrée Phar

### Description

public function PharFileInfo::__construct(string `$filename`)

Cette méthode ne doit pas être appelée directement. À la place, un objet PharFileInfo est initialisé en appelant Phar::offsetGet() via un accès de type tableau.

### Liste de paramètres

`filename`

  L'URL complète pour récupérer un fichier. Pour récupérer les informations du fichier `mon/fichier.php` du phar `boo.phar`, il faudra préciser `phar://boo.phar/mon/fichier.php`.

### Erreurs / Exceptions

Soulève une exception BadMethodCallException si __construct() est appelé deux fois. Soulève une exception UnexpectedValueException si l'URL du phar demandé est mal formée, si le phar ne peut pas être ouvert ou si le fichier ne peut pas être trouvé au sein du phar.

### Exemples

Exemple #1 Exemple avec PharFileInfo::__construct()

    <?php
    try {
        $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
        $p['fichierdetest.txt'] = "salut\nmon\npote";
        $file = $p['fichierdetest.txt'];
        foreach ($file as $line => $text) {
            echo "ligne numéro $line: $text";
        }
        // ceci marche aussi
        $file = new PharFileInfo('phar:///chemin/vers/mon.phar/fichierdetest.txt');
        foreach ($file as $line => $text) {
            echo "ligne numéro $line: $text";
        }
    } catch (Exception $e) {
        echo 'L\'opération Phar a échoué : ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    ligne numéro 1: salut
    ligne numéro 2: mon
    ligne numéro 3: pote
    ligne numéro 1: salut
    ligne numéro 2: mon
    ligne numéro 3: pote

# PharFileInfo::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::decompress — Décompresse l'entrée Phar courante au sein du phar

### Description

public function PharFileInfo::decompress(): true

Cette méthode décompresse le fichier au sein de l'archive Phar. Selon la façon dont le fichier est compressé, les extensions bzip2 ou zlib doivent être activées pour tirer parti de cette fonctionnalité. Comme avec toutes les fonctionnalités qui modifient le contenu d'un phar, la variable INI phar.readonly doit être à off pour réussir si le fichier est dans une archive Phar. Les fichiers au sein d'archives PharData n'ont pas cette restriction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Soulève une exception BadMethodCallException si la variable INI phar.readonly est à on, ou si l'extension bzip2/zlib n'est pas disponible.

### Exemples

Exemple #1 Exemple avec PharFileInfo::decompress()

    <?php
    try {
        $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'salut';
        $file = $p['monfichier.txt'];
        $file->compress(Phar::GZ);
        var_dump($file->isCompressed());
        $p['monfichier.txt']->decompress();
        var_dump($file->isCompressed());
    } catch (Exception $e) {
        echo 'Ne peut pas créer/modifier mon.phar: ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    int(4096)
    bool(false)

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante
- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::decompress() - Décompresse l'archive tar complète
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés

# PharFileInfo::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::delMetadata — Efface les métadonnées de l'entrée

### Description

public function PharFileInfo::delMetadata(): true

Efface les métadonnées de l'entrée, s'il y en a.

### Liste de paramètres

Pas de paramètres.

### Valeurs de retour

Retourne toujours `true`. Comme avec toutes les fonctionnalités qui modifient le contenu d'un phar, la variable INI phar.readonly doit être à off pour réussir si le fichier est au sein d'une archive Phar. Les fichiers au sein d'archives PharData n'ont pas cette restriction.

### Erreurs / Exceptions

Soulève une exception PharException si des erreurs ont été rencontrées lors de l'écriture des changements sur le disque, et une exception BadMethodCallException si l'accès en écriture est désactivé.

### Exemples

Exemple #1 Un exemple avec PharFileInfo::delMetaData()

    <?php
    try {
        $a = new Phar('monphar.phar');
        $a['salut'] = 'salut';
        var_dump($a['salut']->delMetadata());
        $a['salut']->setMetadata('mon pote');
        var_dump($a['salut']->delMetadata());
        var_dump($a['salut']->delMetadata());
    } catch (Exception $e) {
        // on traite les erreurs
    }
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(false)

### Voir aussi

- PharFileInfo::setMetadata() - Fixe les métadonnées spécifiques à un fichier
- PharFileInfo::hasMetadata() - Retourne les méta-données de l'entrée
- PharFileInfo::getMetadata() - Retourne les méta-données spécifiques attachées à un fichier
- Phar::setMetadata() - Fixe les métadonnées de l'archive phar
- Phar::hasMetadata() - Détermine si le phar a ou non des méta-données
- Phar::getMetadata() - Retourne les méta-données de l'archive phar

# PharFileInfo::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__destruct — Détruit un objet PharFileInfo

### Description

public function PharFileInfo::__destruct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# PharFileInfo::getCRC32

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCRC32 — Retourne le code CRC32 ou soulève une exception si le CRC n'a pas été vérifié

### Description

public function PharFileInfo::getCRC32(): int

Retourne la somme de contrôle crc32() du fichier au sein de l'archive Phar.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La somme de contrôle crc32() du fichier au sein de l'archive Phar.

### Erreurs / Exceptions

Soulève une exception BadMethodCallException si le CRC32 du fichier n'a pas encore été vérifié. Ceci n'arrive normalement pas, car le CRC est vérifié à l'ouverture du fichier en lecture ou en écriture.

### Exemples

Exemple #1 Exemple avec PharFileInfo::getCRC32()

    <?php
    try {
        $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'salut';
        $file = $p['monfichier.txt'];
        echo $file->getCRC32();
    } catch (Exception $e) {
        echo 'L\'écriture de mon.phar.phar a échoué : ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    3633523372

# PharFileInfo::getCompressedSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCompressedSize — Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar

### Description

public function PharFileInfo::getCompressedSize(): int

Cette méthode retourne la taille du fichier au sein de l'archive Phar. Les fichiers non compressés retournent la même valeur avec getCompressedSize qu'avec filesize()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La taille en octets du fichier au sein de l'archive Phar sur le disque.

### Exemples

Exemple #1 Un exemple avec PharFileInfo::getCompressedSize()

    <?php
    try {
        $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'salut';
        $file = $p['monfichier.txt'];
        echo $file->getCompressedSize();
    } catch (Exception $e) {
        echo 'L\'écriture de mon.phar a échoué : ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    5

### Voir aussi

- PharFileInfo::isCompressed() - Retourne si l'entrée est compressée
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::decompress() - Décompresse l'archive tar complète
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante

# PharFileInfo::getContent

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PharFileInfo::getContent — Récupère le contenu entier du fichier de l'entrée

### Description

public function PharFileInfo::getContent(): string

Cette fonction se comporte comme file_get_contents() mais pour Phar.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le contenu du fichier.

# PharFileInfo::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getMetadata — Retourne les méta-données spécifiques attachées à un fichier

### Description

public function PharFileInfo::getMetadata(array `$unserializeOptions` = []): mixed

Retourne les méta-données qui ont été sauvegardées dans le manifeste de l'archive Phar pour ce fichier.

### Liste de paramètres

### Valeurs de retour

N'importe quelle variable PHP qui peut être sérialisée et qui est stockée comme méta-données pour le fichier, ou `null` si aucune méta-donnée n'est stockée.

### Historique

Version | Description
--- | ---
8.0.0 | Le paramètre `unserializeOptions` a été ajouté.

### Exemples

Exemple #1 Un exemple avec PharFileInfo::getMetadata()

    <?php
    // on s'assure que le phar n'existe pas déjà
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.txt'] = 'salut';
        $p['fichier.txt']->setMetadata(array('utilisateur' => 'Yannick', 'mime-type' => 'text/plain'));
        var_dump($p['fichier.txt']->getMetadata());
    } catch (Exception $e) {
        echo 'Ne peut pas créer/modifier nouveauphar.phar: ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    array(2) {
      ["utilisateur"]=>
      string(7) "Yannick"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Voir aussi

- PharFileInfo::setMetadata() - Fixe les métadonnées spécifiques à un fichier
- PharFileInfo::hasMetadata() - Retourne les méta-données de l'entrée
- PharFileInfo::delMetadata() - Efface les métadonnées de l'entrée
- Phar::setMetadata() - Fixe les métadonnées de l'archive phar
- Phar::hasMetadata() - Détermine si le phar a ou non des méta-données
- Phar::getMetadata() - Retourne les méta-données de l'archive phar

# PharFileInfo::getPharFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getPharFlags — Retourne les drapeaux du fichier Phar

### Description

public function PharFileInfo::getPharFlags(): int

Cette méthode retourne les drapeaux fixés dans le manifeste pour un Phar. Elle retournera toujours `0` dans son implémentation actuelle.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Les drapeaux Phar (toujours `0` dans son implémentation actuelle)

### Exemples

Exemple #1 Un exemple avec PharFileInfo::getPharFlags()

    <?php
    try {
        $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'salut';
        $file = $p['monfichier.txt'];
        var_dump($file->getPharFlags());
    } catch (Exception $e) {
        echo 'Ne peut pas créer/modifier mon.phar: ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    int(0)

# PharFileInfo::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::hasMetadata — Retourne les méta-données de l'entrée

### Description

public function PharFileInfo::hasMetadata(): bool

Retourne les méta-données d'un fichier au sein d'une archive Phar.

### Liste de paramètres

Aucun paramètre.

### Valeurs de retour

Retourne `false` si aucune méta-donnée n'est présente ou vaut `null`, `true` si les méta-données ne valent pas `null`

### Voir aussi

- PharFileInfo::setMetadata() - Fixe les métadonnées spécifiques à un fichier
- PharFileInfo::getMetadata() - Retourne les méta-données spécifiques attachées à un fichier
- PharFileInfo::delMetadata() - Efface les métadonnées de l'entrée
- Phar::setMetadata() - Fixe les métadonnées de l'archive phar
- Phar::hasMetadata() - Détermine si le phar a ou non des méta-données
- Phar::getMetadata() - Retourne les méta-données de l'archive phar

# PharFileInfo::isCRCChecked

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCRCChecked — Détermine si le fichier a un CRC vérifié

### Description

public function PharFileInfo::isCRCChecked(): bool

Cette méthode détermine si un fichier au sein d'une archive Phar a un CRC vérifié.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si le fichier a un CRC vérifié, `false` sinon.

### Exemples

Exemple #1 Un exemple avec PharFileInfo::isCRCChecked()

    <?php
    try {
        $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'salut';
        $file = $p['monfichier.txt'];
        var_dump($file->isCRCChecked());
    } catch (Exception $e) {
        echo 'La création/modification de mon.phar a échoué : ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

# PharFileInfo::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCompressed — Retourne si l'entrée est compressée

### Description

public function PharFileInfo::isCompressed(?int `$compression` = `null`): bool

Cette méthode détermine si un fichier au sein d'une archive Phar est compressé avec une des compressions Gzip ou Bzip2.

### Liste de paramètres

`compression`

  Une des compressions `Phar::GZ` ou `Phar::BZ2`, aucune compression par défaut.

### Valeurs de retour

`true` si le fichier au sein de l'archive est compressé, `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0 | `compression` est désormais nullable.

### Exemples

Exemple #1 Un exemple avec PharFileInfo::isCompressed()

    <?php
    try {
        $p = new Phar('/chemin/vers/mon.phar', 0, 'mon.phar');
        $p['monfichier.txt'] = 'salut';
        $p['monfichier2.txt'] = 'salut';
        $p['monfichier2.txt']->setCompressedGZ();
        $file = $p['monfichier.txt'];
        $file2 = $p['monfichier2.txt'];
        var_dump($file->isCompressed());
        var_dump($file2->isCompressed());
    } catch (Exception $e) {
        echo 'La création/modification de mon.phar a échoué : ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)

### Voir aussi

- PharFileInfo::getCompressedSize() - Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::decompress() - Décompresse l'entrée Phar courante au sein du phar
- PharFileInfo::compress() - Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- Phar::decompress() - Décompresse l'archive tar complète
- Phar::compress() - Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
- Phar::canCompress() - Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
- Phar::isCompressed() - Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
- Phar::getSupportedCompression() - Retourne un tableau des algorithmes de compression supportés
- Phar::decompressFiles() - Décompresse tous les fichiers de l'archive Phar courante
- Phar::compressFiles() - Compresse tous les fichiers de l'archive Phar courante

# PharFileInfo::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::setMetadata — Fixe les métadonnées spécifiques à un fichier

### Description

public function PharFileInfo::setMetadata(mixed `$metadata`): void

PharFileInfo::setMetadata() ne doit être utilisée que pour stocker des données personnalisées dans un fichier qui ne peuvent pas l'être avec des informations normalement stockées avec le fichier. Les métadonnées peuvent dégrader les performances de chargement d'une archive phar si les données sont trop lourdes ou s'il y a beaucoup de fichiers avec des métadonnées. Il est important de noter que les permissions de fichiers sont supportées nativement dans un phar ; il est possible de les fixer avec la méthode PharFileInfo::chmod(). Comme avec toutes les fonctionnalités qui modifient le contenu du phar, la variable INI phar.readonly doit être à off pour réussir si le fichier est au sein d'une archive Phar. Les fichiers au sein d'archives PharData n'ont pas cette restriction.

Une utilisation possible des métadonnées est le passage d'un utilisateur/groupe qui devrait être utilisé quand un fichier est extrait du phar vers le disque. On peut aussi spécifier un type MIME à retourner. De manière générale, on peut stocker toute donnée utile qui décrit un fichier mais qui ne peut pas y être inscrite directement.

### Liste de paramètres

`metadata`

  Toute variable PHP contenant des informations à stocker à part du fichier

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Un exemple avec PharFileInfo::setMetadata()

    <?php
    // on s'assure que le phar n'existe pas déjà
    @unlink('nouveauphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/nouveauphar.phar', 0, 'nouveauphar.phar');
        $p['fichier.txt'] = 'salut';
        $p['fichier.txt']->setMetadata(array('utilisateur' => 'Yannick', 'mime-type' => 'text/plain'));
        var_dump($p['fichier.txt']->getMetadata());
    } catch (Exception $e) {
        echo 'Ne peut pas créer/modifier le phar : ', $e;
    }
    ?>

L'exemple ci-dessus va afficher :

    array(2) {
      ["utilisateur"]=>
      string(7) "Yannick"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Voir aussi

- PharFileInfo::hasMetadata() - Retourne les méta-données de l'entrée
- PharFileInfo::getMetadata() - Retourne les méta-données spécifiques attachées à un fichier
- PharFileInfo::delMetadata() - Efface les métadonnées de l'entrée
- Phar::setMetadata() - Fixe les métadonnées de l'archive phar
- Phar::hasMetadata() - Détermine si le phar a ou non des méta-données
- Phar::getMetadata() - Retourne les méta-données de l'archive phar

## Sommaire

- PharFileInfo::chmod — Fixe les bits de permission spécifiques aux fichiers
- PharFileInfo::compress — Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
- PharFileInfo::__construct — Construit un objet d'entrée Phar
- PharFileInfo::decompress — Décompresse l'entrée Phar courante au sein du phar
- PharFileInfo::delMetadata — Efface les métadonnées de l'entrée
- PharFileInfo::__destruct — Détruit un objet PharFileInfo
- PharFileInfo::getCRC32 — Retourne le code CRC32 ou soulève une exception si le CRC n'a pas été vérifié
- PharFileInfo::getCompressedSize — Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
- PharFileInfo::getContent — Récupère le contenu entier du fichier de l'entrée
- PharFileInfo::getMetadata — Retourne les méta-données spécifiques attachées à un fichier
- PharFileInfo::getPharFlags — Retourne les drapeaux du fichier Phar
- PharFileInfo::hasMetadata — Retourne les méta-données de l'entrée
- PharFileInfo::isCRCChecked — Détermine si le fichier a un CRC vérifié
- PharFileInfo::isCompressed — Retourne si l'entrée est compressée
- PharFileInfo::setMetadata — Fixe les métadonnées spécifiques à un fichier

# La classe PharException

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Introduction

La classe PharException fournit une classe d'exception spécifique à phar pour les blocs try/catch.

## Synopsis de la classe

class PharException extends Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Utiliser les archives Phar
  - Utiliser les archives Phar : Introduction
  - Utiliser les archives Phar : le flux phar
  - Utiliser les archives Phar : les classes Phar et PharData
- Créer des archives Phar
  - Créer des archives Phar : Introduction
- Qu'est-ce qui fait d'un phar un phar et pas un tar ou un zip ?
  - Les constituants de toutes les archives Phar, indépendamment du format de fichier
  - Le conteneur de fichier Phar
  - Comparaison entre Phar, Tar et Zip
  - Les phars basés sur Tar
  - Les phars basés sur Zip
  - Le format de fichier Phar
  - Drapeaux "bitmappés" globaux du Phar
  - Définition des entrées du manifeste Phar
  - Phar Signature format
- Phar — La classe Phar
  - Phar::addEmptyDir — Ajoute un répertoire vide à l'archive phar
  - Phar::addFile — Ajoute un fichier du système de fichiers à l'archive phar
  - Phar::addFromString — Ajoute un fichier depuis une chaîne de caractères à l'archive phar
  - Phar::apiVersion — Retourne la version de l'API
  - Phar::buildFromDirectory — Construit une archive phar à partir des fichiers d'un répertoire
  - Phar::buildFromIterator — Construit une archive phar à partir d'un itérateur
  - Phar::canCompress — Détermine si l'extension phar supporte la compression en utilisant soit zlib soit bzip2
  - Phar::canWrite — Détermine si l'extension phar supporte la création et l'écriture des phars
  - Phar::compress — Compresse l'archive Phar complète en utilisant la compression Gzip ou Bzip2
  - Phar::compressFiles — Compresse tous les fichiers de l'archive Phar courante
  - Phar::__construct — Construit un objet d'archive Phar
  - Phar::convertToData — Convertit une archive phar en un fichier non-exécutable
  - Phar::convertToExecutable — Convertit une archive phar vers un autre format de fichier d'archive phar exécutable
  - Phar::copy — Copie un fichier appartenant à une archive vers un autre fichier de la même archive
  - Phar::count — Retourne le nombre d'entrées (fichiers) dans l'archive Phar
  - Phar::createDefaultStub — Crée un conteneur de chargement d'une archive Phar
  - Phar::decompress — Décompresse l'archive tar complète
  - Phar::decompressFiles — Décompresse tous les fichiers de l'archive Phar courante
  - Phar::delMetadata — Efface les méta-données globales du phar
  - Phar::delete — Efface un fichier au sein d'une archive phar
  - Phar::__destruct — Détruit un objet archive Phar
  - Phar::extractTo — Extrait le contenu d'une archive phar vers un répertoire
  - Phar::getAlias — Récupère l'alias pour Phar
  - Phar::getMetadata — Retourne les méta-données de l'archive phar
  - Phar::getModified — Indique si le fichier phar a été modifié
  - Phar::getPath — Récupère le chemin absolu de l'archive Phar sur le disque
  - Phar::getSignature — Retourne la signature MD5/SHA1/SHA256/SHA512 d'une archive Phar
  - Phar::getStub — Retourne le chargeur PHP ou le conteneur de chargement d'une archive Phar
  - Phar::getSupportedCompression — Retourne un tableau des algorithmes de compression supportés
  - Phar::getSupportedSignatures — Retourne un tableau des types de signature supportés
  - Phar::getVersion — Retourne les informations de version de l'archive Phar
  - Phar::hasMetadata — Détermine si le phar a ou non des méta-données
  - Phar::interceptFileFuncs — Informe phar qu'il doit intercepter les fonctions de fichiers
  - Phar::isBuffering — Détermine si les opérations d'écriture du Phar sont mises en tampons ou sont directement inscrites sur le disque
  - Phar::isCompressed — Retourne Phar::GZ ou PHAR::BZ2 si l'archive entière est compressée (.tar.gz/tar.bz, etc)
  - Phar::isFileFormat — Retourne true si l'archive phar est basée sur le format de fichier tar/phar/zip selon le paramètre
  - Phar::isValidPharFilename — Détermine si le nom de fichier spécifié est un nom de fichier valide pour une archive phar
  - Phar::isWritable — Retourne true si l'archive phar peut être modifiée
  - Phar::loadPhar — Charge n'importe quelle archive phar avec un alias
  - Phar::mapPhar — Lit le phar exécuté et charge son manifeste
  - Phar::mount — Monte un chemin ou un fichier externe à un emplacement virtuel au sein de l'archive phar
  - Phar::mungServer — Définit une liste de maximum 4 variables $_SERVER qui doivent être modifiées lors de l'exécution
  - Phar::offsetExists — Détermine si un fichier existe dans le phar
  - Phar::offsetGet — Obtient un objet PharFileInfo à partir d'un fichier
  - Phar::offsetSet — Met le contenu d'un fichier interne à l'archive à l'identique du contenu d'un fichier externe
  - Phar::offsetUnset — Efface un fichier d'un phar
  - Phar::running — Retourne le chemin complet sur le disque ou l'URL phar complète de l'archive phar couramment exécutée
  - Phar::setAlias — Fixe l'alias de l'archive Phar
  - Phar::setDefaultStub — Utilisé pour fixer le chargeur PHP ou le conteneur de chargement d'une archive Phar en tant que chargeur par défaut
  - Phar::setMetadata — Fixe les métadonnées de l'archive phar
  - Phar::setSignatureAlgorithm — Fixe et applique l'algorithme de signature d'un phar
  - Phar::setStub — Utilisé pour spécifier le chargeur PHP ou le conteneur de chargement d'une archive Phar
  - Phar::startBuffering — Démarre la mise en tampon d'écritures Phar, ne modifie pas l'objet Phar sur le disque
  - Phar::stopBuffering — Arrête la mise en tampon des écritures Phar et provoque l'écriture sur le disque
  - Phar::unlinkArchive — Efface complètement une archive phar du disque et de la mémoire
  - Phar::webPhar — Redirige une requête depuis un navigateur web à un fichier interne dans l'archive phar
- PharData — La classe PharData
  - PharData::addEmptyDir — Ajoute un répertoire vide à l'archive tar/zip
  - PharData::addFile — Ajoute un fichier du système de fichiers à l'archive tar/zip
  - PharData::addFromString — Ajoute un fichier à partir d'une chaîne de caractères à l'archive tar/zip
  - PharData::buildFromDirectory — Construit une archive tar/zip à partir des fichiers d'un répertoire
  - PharData::buildFromIterator — Construit une archive tar ou zip à partir d'un itérateur
  - PharData::compress — Compresse l'archive tar/zip complète en utilisant la compression Gzip ou Bzip2
  - PharData::compressFiles — Compresse tous les fichiers de l'archive tar/zip courante
  - PharData::__construct — Construit un objet d'archive tar ou zip non-exécutable
  - PharData::convertToData — Convertit une archive phar en une archive tar ou zip non-exécutable
  - PharData::convertToExecutable — Convertit une archive tar/zip non-exécutable en une archive phar exécutable
  - PharData::copy — Copie un fichier interne à l'archive tar/zip vers un autre fichier au sein de la même archive
  - PharData::decompress — Décompresse l'archive Phar entière
  - PharData::decompressFiles — Décompresse tous les fichiers de l'archive zip courante
  - PharData::delMetadata — Efface les méta-données globales d'une archive zip
  - PharData::delete — Efface un fichier au sein de l'archive tar/zip
  - PharData::__destruct — Détruit un objet non exécutable tar ou une archive zip
  - PharData::extractTo — Extrait le contenu d'une archive tar/zip vers un répertoire
  - PharData::isWritable — Vérifie si l'archive tar/zip peut être modifiée
  - PharData::offsetSet — Remplit un fichier au sein de l'archive tar/zip avec le contenu d'un fichier externe ou d'une chaîne de caractères
  - PharData::offsetUnset — Efface un fichier d'une archive tar/zip
  - PharData::setAlias — Fonction inutile (Phar::setAlias n'est pas valide pour PharData)
  - PharData::setDefaultStub — Fonction inutile (Phar::setDefaultStub n'est pas valide pour PharData)
  - PharData::setMetadata — Fixe les méta-données de l'archive
  - PharData::setSignatureAlgorithm — Assigne l'algorithme de signature d'un phar et l'applique
  - PharData::setStub — Fonction inutile (Phar::setStub n'est pas valide pour PharData)
- PharFileInfo — La classe PharFileInfo
  - PharFileInfo::chmod — Fixe les bits de permission spécifiques aux fichiers
  - PharFileInfo::compress — Compresse l'entrée Phar courante avec une des compressions zlib ou bzip2
  - PharFileInfo::__construct — Construit un objet d'entrée Phar
  - PharFileInfo::decompress — Décompresse l'entrée Phar courante au sein du phar
  - PharFileInfo::delMetadata — Efface les métadonnées de l'entrée
  - PharFileInfo::__destruct — Détruit un objet PharFileInfo
  - PharFileInfo::getCRC32 — Retourne le code CRC32 ou soulève une exception si le CRC n'a pas été vérifié
  - PharFileInfo::getCompressedSize — Retourne la taille actuelle (avec compression) du fichier au sein de l'archive Phar
  - PharFileInfo::getContent — Récupère le contenu entier du fichier de l'entrée
  - PharFileInfo::getMetadata — Retourne les méta-données spécifiques attachées à un fichier
  - PharFileInfo::getPharFlags — Retourne les drapeaux du fichier Phar
  - PharFileInfo::hasMetadata — Retourne les méta-données de l'entrée
  - PharFileInfo::isCRCChecked — Détermine si le fichier a un CRC vérifié
  - PharFileInfo::isCompressed — Retourne si l'entrée est compressée
  - PharFileInfo::setMetadata — Fixe les métadonnées spécifiques à un fichier
- PharException — La classe PharException

# Archives RAR

# Introduction

Rar est un archiveur puissant et fiable, créé par Eugene Roshal. Cette extension donne la possibilité de lire des archives Rar, mais ne supporte pas l'écriture, car elle n'est pas supportée par la bibliothèque UnRar et que c'est interdit directement par la licence.

Plus d'informations sur Rar et UnRar peuvent être trouvées sur » http://www.rarlabs.com/.

# Installation/Configuration

## Sommaire

- Installation
- Types de ressources

## Installation

Rar est actuellement disponible via PECL » https://pecl.php.net/package/rar.

Il est possible d'utiliser l'assistant d'installation PECL pour installer l'extension Rar, en utilisant la commande suivante : pecl -v install rar.

Il est possible d'également télécharger le paquet tar.gz et installer Rar manuellement :

Exemple #1 Installation de Rar

    gunzip rar-xxx.tgz
    tar -xvf rar-xxx.tar
    cd rar-xxx
    phpize
    ./configure && make && make install

Les utilisateurs de Windows doivent activer la bibliothèque php_rar.dll dans le fichier php.ini afin d'utiliser ces fonctions.

## Types de ressources

Cette extension enregistre 3 classes internes : La représentation de l'archive retournée par la fonction rar_open() – RarArchive, la représentation des entrées retournée par les fonctions rar_list() et rar_entry_get() – RarEntry et les exceptions de type RarException.

Cette extension enregistre également un flux de ressource appelé "rar" et un gestionnaire d'url appelé "rar wrapper", et enregistré sous le préfixe "rar".

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`RAR_HOST_MSDOS` (int)
  Utiliser la constante `RarEntry::HOST_MSDOS` à la place.
`RAR_HOST_OS2` (int)
  Utiliser la constante `RarEntry::HOST_OS2` à la place.
`RAR_HOST_WIN32` (int)
  Utiliser la constante `RarEntry::HOST_WIN32` à la place.
`RAR_HOST_UNIX` (int)
  Utiliser la constante `RarEntry::HOST_UNIX` à la place.
`RAR_HOST_BEOS` (int)
  Utiliser la constante `RarEntry::HOST_BEOS` à la place.

# Exemples

Voir aussi les exemples de la section sur le gestionnaire `rar://`.

Exemple #1 Décompression à la volée

    <?php

    if (!array_key_exists("i", $_GET) || !is_numeric($_GET["i"]))
        die("Index non spécifié ou non numérique");
    $index = (int) $_GET["i"];

    $arch = RarArchive::open("example.rar");
    if ($arch === FALSE)
        die("Impossible d'ouvrir example.rar");

    $entries = $arch->getEntries();
    if ($entries === FALSE)
        die("Impossible de récupérer les entrées");

    if (!array_key_exists($index, $entries))
        die("L'index $index n'existe pas");

    $orfilename = $entries[$index]->getName(); //Encodage UTF-8

    $filesize = $entries[$index]->getUnpackedSize();

    /* Il est possible de vérifier ici HTTP_IF_MODIFIED_SINCE et le comparer
     * avec $entries[$index]->getFileTime(). Il est également possible de envoyer
     * un en-tête "Last modified" */

    $fp = $entries[$index]->getStream();
    if ($fp === FALSE)
        die("Impossible d'ouvrir le fichier d'index $index depuis l'archive.");

    $arch->close(); //plus nécessaire ; le flux est indépendant

    function detectUserAgent() {
        if (!array_key_exists('HTTP_USER_AGENT', $_SERVER))
            return "Autre";

        $uas = $_SERVER['HTTP_USER_AGENT'];
        if (preg_match("@Opera/@", $uas))
            return "Opera";
        if (preg_match("@Firefox/@", $uas))
            return "Firefox";
        if (preg_match("@Chrome/@", $uas))
            return "Chrome";
        if (preg_match("@MSIE ([0-9.]+);@", $uas, $matches)) {
            if (((float) $matches[1]) >= 7.0)
                return "IE";
        }

        return "Autre";
    }

    /*
     * Nous avons 3 options :
     * - Pour FF et Opera, qui supportent RFC 2231, utiliser ce format.
     * - Pour IE et Chrome, utiliser attwithfnrawpctenclong
     *   (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
     * - Pour les autres, convertissez en ISO-8859-1, si possible
     */
    $formatRFC2231 = 'Content-Disposition: attachment; filename*=UTF-8\'\'%s';
    $formatDef = 'Content-Disposition: attachment; filename="%s"';

    switch (detectUserAgent()) {
        case "Opera":
        case "Firefox":
            $orfilename = rawurlencode($orfilename);
            $format = $formatRFC2231;
            break;

        case "IE":
        case "Chrome":
            $orfilename = rawurlencode($orfilename);
            $format = $formatDef;
            break;
        default:
            if (function_exists('iconv'))
                $orfilename =
                    @iconv("UTF-8", "ISO-8859-1//TRANSLIT", $orfilename);
            $format = $formatDef;
    }

    header(sprintf($format, $orfilename));
    // Impossible d'envoyer les messages d'erreur à partir d'ici (les en-têtes
    // ont déjà été émis)

    // Remplacement par le type de contenu réel, pourquoi pas par déduction de l'extension du fichier
    $contentType = "application/octet-stream";
    header("Content-Type: $contentType");

    header("Content-Transfer-Encoding: binary");

    header("Content-Length: $filesize");

    if ($_SERVER['REQUEST_METHOD'] == "HEAD")
        die();

    while (!feof($fp)) {
        $s = @fread($fp, 8192);
        if ($s === false)
            break; //utile pour envoyer des messages d'erreur

        echo $s;
    }
    ?>

Cet exemple ouvre un fichier RAR et présente le fichier demandé contenu dans l'archive RAR pour téléchargement par le client.

Exemple #2 Exemple d'extractions RAR

    <?php

    $rar_file = rar_open('example.rar') or die("Impossible d'ouvrir l'archive Rar");

    $entries = rar_list($rar_file);

    foreach ($entries as $entry) {
        echo 'Nom du fichier : ' . $entry->getName() . "\n";
        echo 'Taille compressée : ' . $entry->getPackedSize() . "\n";
        echo 'Taille après décompression : ' . $entry->getUnpackedSize() . "\n";

        $entry->extract('/dir/extract/to/');
    }

    rar_close($rar_file);

    ?>

Cet exemple ouvre une archive RAR et extrait chaque entrée dans le dossier spécifié.

# Fonctions Rar

# rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_stats — Statistique pour le cache du gestionnaire URL

### Description

function rar_wrapper_cache_stats(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

## Sommaire

- rar_wrapper_cache_stats — Statistique pour le cache du gestionnaire URL

# La classe RarArchive

(PECL rar >= 2.0.0)

## Introduction

Cette classe représente une archive RAR, qui peut être formée de plusieurs volumes (parties) et qui peut contenir plusieurs entrées RAR (c.-à-d., fichiers, dossiers et autres objets spéciaux comme des liens symboliques).

Les objets de cette classe peuvent être parcourus, permettant ainsi d'accéder aux entrées contenues dans les archives RAR respectives. Ces entrées peuvent également être obtenues via les méthodes RarArchive::getEntry() et RarArchive::getEntries().

## Synopsis de la classe

final class RarArchive implements Traversable {
/* Méthodes */
public function close(): bool
public function getComment(): string
public function getEntries(): array|false
public function getEntry(string `$entryname`): RarEntry|false
public function isBroken(): bool
public function isSolid(): bool
public static function open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false
public function setAllowBroken(bool `$allow_broken`): bool
public function __toString(): string
}

# RarArchive::close

# rar_close

(PECL rar >= 2.0.0)

RarArchive::close -- rar_close — Ferme une archive RAR et libère toutes les ressources

### Description

Style orienté objet (méthode) :

public function RarArchive::close(): bool

Style procédural :

function rar_close(RarArchive `$rarfile`): bool

Ferme une archive RAR et libère toutes les ressources associées.

### Liste de paramètres

`rarfile`
  Un objet RarArchive, ouvert avec la fonction rar_open().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL rar 2.0.0 | Les entrées RAR retournées par RarArchive::getEntry() et RarArchive::getEntries() sont désormais invalidées lors de l'appel à cette méthode. Cela signifie que tous les appels d'instances sur de telles entrées ne sont pas garanties.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

Exemple #2 Style procédural

    <?php
    $rar_arch = rar_open('latest_winrar.rar');
    echo $rar_arch."\n";
    rar_close($rar_arch);
    echo $rar_arch."\n";
    ?>

# RarArchive::getComment

# rar_comment_get

(PECL rar >= 2.0.0)

RarArchive::getComment -- rar_comment_get — Récupère un commentaire depuis une archive RAR

### Description

Style orienté objet (méthode) :

public function RarArchive::getComment(): string

Style procédural :

function rar_comment_get(RarArchive `$rarfile`): string

Récupère le commentaire global stocké dans l'archive RAR. Il peut atteindre 64 Ko de long.

> Note: Cette extension ne supporte pas les commentaires sur de simples entrées.

### Liste de paramètres

`rarfile`
  Un objet RarArchive, ouvert avec la fonction rar_open().

### Valeurs de retour

Retourne le commentaire, ou `null` s'il n'y en a pas.

> Note: RAR ne supporte actuellement pas les commentaires unicodes. L'encodage du résultat de cette fonction n'est pas spécifié, mais il sera probablement de type Windows-1252.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $rar_arch = RarArchive::open('commented.rar');
    echo $rar_arch->getComment();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Ceci est le commentaire du fichier commented.rar.

Exemple #2 Style procédural

    <?php
    $rar_arch = rar_open('commented.rar');
    echo rar_comment_get($rar_arch);
    ?>

# RarArchive::getEntries

# rar_list

(PECL rar >= 2.0.0)

RarArchive::getEntries -- rar_list — Récupère la liste complète depuis l'archive RAR

### Description

Style orienté objet (méthode):

public function RarArchive::getEntries(): array|false

Style procédural :

function rar_list(RarArchive `$rarfile`): array|false

Récupère la liste complète (fichiers et dossiers) depuis l'archive RAR.

> Note: Si l'archive contient des entrées portant le même nom, cette méthode, combinée avec l'itération RarArchive `foreach` et un accès style tableau avec des index numériques, est la seule permettant d'accéder à toutes les entrées (c.-à-d. RarArchive::getEntry() et le gestionnaire `rar://` sont insuffisants).

### Liste de paramètres

`rarfile`
  Un objet RarArchive, ouvert avec la fonction rar_open().

### Valeurs de retour

Retourne un tableau d'objets RarEntry ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL rar 3.0.0 | Support des archives RAR contenant des entrées portant le même nom.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Impossible d'ouvrir l'archive RAR.");

    $rar_entries = $rar_arch->getEntries();
    if ($rar_entries === FALSE)
        die("Impossible de récupérer les entrées.");

    echo "Nombre d'entrées trouvées : " . count($rar_entries) . "\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    $rar_arch->close();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Nombre d'entrées trouvées : 2
    RarEntry for file "tese.txt" (23b93a7a)
    RarEntry for file "unrardll.txt" (2ed64b6e)

Exemple #2 Style procédural

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Impossible d'ouvrir l'archive RAR.");

    $rar_entries = rar_list($rar_arch);
    if ($rar_entries === FALSE)
        die("Impossible de récupérer les entrées.");

    echo "Nombre d'entrées trouvées : " . count($rar_entries) . "\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    rar_close($rar_arch);
    ?>

### Voir aussi

- RarArchive::getEntry() - Récupère une entrée depuis une archive RAR
- Le gestionnaire `rar://`

# RarArchive::getEntry

# rar_entry_get

(PECL rar >= 2.0.0)

RarArchive::getEntry -- rar_entry_get — Récupère une entrée depuis une archive RAR

### Description

Style orienté objet (méthode):

public function RarArchive::getEntry(string `$entryname`): RarEntry|false

Style procédural :

function rar_entry_get(RarArchive `$rarfile`, string `$entryname`): RarEntry|false

Récupère une entrée (fichier ou dossier) depuis une archive RAR.

> Note: Il est possible d'également récupérer les entrées en utilisant la méthode RarArchive::getEntries(). Il est à noter qu'une archive RAR peut avoir plusieurs entrées portant le même nom ; cette méthode ne récupérera que la première.

### Liste de paramètres

`rarfile`
  Un objet RarArchive, ouvert avec la fonction rar_open().
`entryname`
  Chemin vers l'entrée, dans l'archive RAR.

  > Note: Le chemin doit être le même que celui retourné par la méthode RarEntry::getName().

### Valeurs de retour

Retourne l'entrée RarEntry correspondante ou `false` si une erreur survient.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Impossible d'ouvrir l'archive RAR.");
    $rar_entry = $rar_arch->getEntry('tese.txt');
    if ($rar_entry === FALSE)
        die("Impossible de récupérer cette entrée.");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    $rar_arch->close();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    RarEntry
    RarEntry for file "tese.txt" (23b93a7a)

Exemple #2 Style procédural

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Impossible d'ouvrir l'archive RAR.");
    $rar_entry = rar_entry_get($rar_arch, 'tese.txt');
    if ($rar_entry === FALSE)
        die("Impossible de récupérer cette entrée.");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    rar_close($rar_arch);
    ?>

### Voir aussi

- RarArchive::getEntries() - Récupère la liste complète depuis l'archive RAR
- Le gestionnaire `rar://`

# RarArchive::isBroken

# rar_broken_is

(PECL rar >= 3.0.0)

RarArchive::isBroken -- rar_broken_is — Teste si une archive est corrompue (incomplète)

### Description

Style orienté objet (méthode) :

public function RarArchive::isBroken(): bool

Style procédural :

function rar_broken_is(RarArchive `$rarfile`): bool

Cette fonction détermine si une archive est incomplète, c.-à-d., si un volume est manquant ou un volume est tronqué.

### Liste de paramètres

`rarfile`
  Un objet RarArchive, ouvert avec la fonction rar_open().

### Valeurs de retour

Retourne `true` si l'archive est corrompue, `false` sinon. Cette fonction peut également retourner `false` si le fichier passé a déjà été clos. La seule solution pour faire la différence entre ces 2 cas est d'activer les exceptions grâce à la méthode RarException::setUsingExceptions() ; cependant, ce n'est pas nécessaire sachant qu'un programme ne doit pas fonctionner sur des fichiers fermés.

### Exemples

Exemple #1 Style orienté objet

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* Le 3ème argument est utilisé pour éviter une alerte */
    $arch = RarArchive::open($file, null, 'retnull');
    var_dump($arch->isBroken());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    bool(true)

Exemple #2 Style procédural

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* Le 3ème argument est utilisé pour éviter une alerte */
    $arch = rar_open($file, null, 'retnull');
    var_dump(rar_broken_is($arch));
    ?>

### Voir aussi

- RarArchive::setAllowBroken() - Autorise ou non l'ouverture d'archives corrompues

# RarArchive::isSolid

# rar_solid_is

(PECL rar >= 2.0.0)

RarArchive::isSolid -- rar_solid_is — Vérifie si l'archive RAR est solide

### Description

Style orienté objet (méthode) :

public function RarArchive::isSolid(): bool

Style procédural :

function rar_solid_is(RarArchive `$rarfile`): bool

Vérifie si l'archive RAR est solide. L'extraction de fichier individuel est plus lente sur les archives solides.

### Liste de paramètres

`rarfile`
  Un objet RarArchive, ouvert avec la fonction rar_open().

### Valeurs de retour

Retourne `true` si l'archive est solide, `false` sinon.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $arch1 = RarArchive::open("store_method.rar");
    $arch2 = RarArchive::open("solid.rar");
    echo "$arch1: " . ($arch1->isSolid()?'oui':'non') ."\n";
    echo "$arch2: " . ($arch2->isSolid()?'oui':'non') . "\n";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    RAR Archive "C:\php_rar\trunk\tests\store_method.rar": non
    RAR Archive "C:\php_rar\trunk\tests\solid.rar": oui

Exemple #2 Style procédural

    <?php
    $arch1 = rar_open("store_method.rar");
    $arch2 = rar_open("solid.rar");
    echo "$arch1: " . (rar_solid_is($arch1)?'oui':'non') ."\n";
    echo "$arch2: " . (rar_solid_is($arch2)?'oui':'non') . "\n";
    ?>

# RarArchive::open

# rar_open

(PECL rar >= 2.0.0)

RarArchive::open -- rar_open — Ouvre une archive RAR

### Description

Style orienté objet (méthode) :

public static function RarArchive::open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Style procédural :

function rar_open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Ouvre une archive RAR et retourne une instance RarArchive la représentant.

> Note: Si on tente d'ouvrir une archive multivolume, le chemin du premier volume doit être passé comme premier paramètre. Sinon, l'ensemble des fichiers ne sera pas affiché.

### Liste de paramètres

`filename`
  Chemin vers l'archive Rar.
`password`
  Un mot de passe en texte brut, si nécessaire pour déchiffrer l'en-tête. Il sera également utilisé par défaut si des fichiers cryptés sont trouvés. Il est à noter que les fichiers peuvent avoir un mot de passe différent de celui des en-têtes et différents entre eux.
`volume_callback`
  Une fonction qui reçoit un seul paramètre - le chemin du volume non trouvé - et retourne une chaîne de caractères contenant le chemin correct du volume ou `null` si le volume n'existe pas ou le chemin n'est pas connu. Attention à ne pas créer de boucle infinie sachant que la fonction sera appelée indéfiniment si le chemin retourné dans un précédent appel ne correspond pas au volume désiré. Le fait de spécifier ce paramètre évitera une alerte qui devrait être émise lorsqu'un volume n'est pas trouvé ; une implémentation qui ne retourne que `null` peut toutefois être utilisée pour éviter une telle alerte.

Avertissement

Avant la version 2.0.0, cette fonction ne gérait pas correctement les chemins relatifs. Utiliser la fonction realpath() pour corriger ce bogue.

### Valeurs de retour

Retourne l'instance RarArchive requise ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL rar 3.0.0 | Le paramètre `volume_callback` a été ajouté.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Échec lors de l'ouverture du fichier");

    $entries = $rar_arch->getEntries();
    if ($entries === FALSE)
        die("Échec lors de la récupération des entrées");

    echo count($entries) . " fichier(s) trouvé(s).\n";

    if (empty($entries))
        die("Aucune entrée valide n'a été trouvée.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Échec lors de l'ouverture du premier fichier");

    $rar_arch->close();

    echo "Contenu du premier fichier :\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    2 fichier(s) trouvé(s).
    Contenu du premier fichier :
    Encrypted file 1 contents.

Exemple #2 Style procédural

    <?php
    $rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Échec lors de l'ouverture du fichier");

    $entries = rar_list($rar_arch);
    if ($entries === FALSE)
        die("Échec lors de la récupération des entrées");

    echo count($entries) . " fichier(s) trouvé(s).\n";

    if (empty($entries))
        die("Aucune entrée valide n'a été trouvée.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Échec lors de l'ouverture du premier fichier");

    rar_close($rar_arch);

    echo "Contenu du premier fichier :\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

Exemple #3 Fonction de rappel pour le volume

    <?php
    /* Dans cet exemple, il y a un volume nommé multi_broken.part1.rar
     * dont le volume suivant est nommé multi.part2.rar */
    function resolve($vol) {
        if (preg_match('/_broken/', $vol))
            return str_replace('_broken', '', $vol);
        else
            return null;
    }
    $rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
    $entry = $rar_file1->getEntry('file2.txt');
    $entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
    ?>

### Voir aussi

- Le gestionnaire `rar://`

# RarArchive::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBroken — Autorise ou non l'ouverture d'archives corrompues

### Description

Style orienté objet (méthode) :

public function RarArchive::setAllowBroken(bool `$allow_broken`): bool

Style procédural :

function rar_allow_broken_set(RarArchive `$rarfile`, bool `$allow_broken`): bool

Cette méthode définit si les archives corrompues peuvent être lues ou bien si les opérations qui tentent d'extraire les entrées de l'archive doivent échouer. Les archives corrompues sont les archives pour lesquelles aucune erreur n'est détectée lorsque le fichier est ouvert mais qu'une erreur survient lors de la lecture des entrées.

### Liste de paramètres

`rarfile`
  Un objet RarArchive, ouvert avec la fonction rar_open().
`allow_broken`
  Si la lecture des archives corrompues est autorisée (`true`) ou non (`false`).

### Valeurs de retour

Retourne `true` ou `false` si une erreur survient. La méthode échouera uniquement si le fichier a déjà été clos.

### Exemples

Exemple #1 Style orienté objet

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* Le 3ème argument évite le message "volume not found" */
    $a = RarArchive::open($file, null, 'retnull');
    $a->setAllowBroken(true);
    foreach ($a->getEntries() as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    RarEntry for file "file1.txt" (52b28202)
    int(1)

Exemple #2 Style procédural

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* Le 3ème argument évite le message "volume not found" */
    $a = rar_open($file, null, 'retnull');
    rar_allow_broken_set($a, true);
    foreach (rar_list($a) as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

### Voir aussi

- RarArchive::isBroken() - Teste si une archive est corrompue (incomplète)

# RarArchive::__toString

(PECL rar >= 2.0.0)

RarArchive::__toString — Récupère une représentation sous forme de texte

### Description

public function RarArchive::__toString(): string

Fournit une représentation sous forme de chaîne de caractères pour l'objet RarArchive. Actuellement, ce sera le nom du chemin complet vers le volume de l'archive ouverte ainsi qu'une information indiquant si la ressource est valide ou bien si elle a été close via un appel à la méthode RarArchive::close().

Cette méthode ne doit être utilisée qu'à des fins de débogage, sachant qu'elle n'est ni garantie dans les informations composant le résultat, ni garantie dans la façon dont le résultat sera formaté.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une représentation textuelle de l'objet RarArchive. Le contenu de cette représentation n'est pas spécifié.

### Exemples

Exemple #1 Exemple avec RarArchive::__toString()

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

## Sommaire

- RarArchive::close — Ferme une archive RAR et libère toutes les ressources
- RarArchive::getComment — Récupère un commentaire depuis une archive RAR
- RarArchive::getEntries — Récupère la liste complète depuis l'archive RAR
- RarArchive::getEntry — Récupère une entrée depuis une archive RAR
- RarArchive::isBroken — Teste si une archive est corrompue (incomplète)
- RarArchive::isSolid — Vérifie si l'archive RAR est solide
- RarArchive::open — Ouvre une archive RAR
- RarArchive::setAllowBroken — Autorise ou non l'ouverture d'archives corrompues
- RarArchive::__toString — Récupère une représentation sous forme de texte

# La classe RarEntry

(PECL rar >= 0.1)

## Introduction

Une entrée RAR, représentant un dossier ou un fichier compressé dans une archive RAR.

## Synopsis de la classe

final class RarEntry {
/* Constantes */
const int HOST_MSDOS = 0;
const int HOST_OS2 = 1;
const int HOST_WIN32 = 2;
const int HOST_UNIX = 3;
const int HOST_MACOS = 4;
const int HOST_BEOS = 5;
const int ATTRIBUTE_WIN_READONLY = 1;
const int ATTRIBUTE_WIN_HIDDEN = 2;
const int ATTRIBUTE_WIN_SYSTEM = 4;
const int ATTRIBUTE_WIN_DIRECTORY = 16;
const int ATTRIBUTE_WIN_ARCHIVE = 32;
const int ATTRIBUTE_WIN_DEVICE = 64;
const int ATTRIBUTE_WIN_NORMAL = 128;
const int ATTRIBUTE_WIN_TEMPORARY = 256;
const int ATTRIBUTE_WIN_SPARSE_FILE = 512;
const int ATTRIBUTE_WIN_REPARSE_POINT = 1024;
const int ATTRIBUTE_WIN_COMPRESSED = 2048;
const int ATTRIBUTE_WIN_OFFLINE = 4096;
const int ATTRIBUTE_WIN_NOT_CONTENT_INDEXED = 8192;
const int ATTRIBUTE_WIN_ENCRYPTED = 16384;
const int ATTRIBUTE_WIN_VIRTUAL = 65536;
const int ATTRIBUTE_UNIX_WORLD_EXECUTE = 1;
const int ATTRIBUTE_UNIX_WORLD_WRITE = 2;
const int ATTRIBUTE_UNIX_WORLD_READ = 4;
const int ATTRIBUTE_UNIX_GROUP_EXECUTE = 8;
const int ATTRIBUTE_UNIX_GROUP_WRITE = 16;
const int ATTRIBUTE_UNIX_GROUP_READ = 32;
const int ATTRIBUTE_UNIX_OWNER_EXECUTE = 64;
const int ATTRIBUTE_UNIX_OWNER_WRITE = 128;
const int ATTRIBUTE_UNIX_OWNER_READ = 256;
const int ATTRIBUTE_UNIX_STICKY = 512;
const int ATTRIBUTE_UNIX_SETGID = 1024;
const int ATTRIBUTE_UNIX_SETUID = 2048;
const int ATTRIBUTE_UNIX_FINAL_QUARTET = 61440;
const int ATTRIBUTE_UNIX_FIFO = 4096;
const int ATTRIBUTE_UNIX_CHAR_DEV = 8192;
const int ATTRIBUTE_UNIX_DIRECTORY = 16384;
const int ATTRIBUTE_UNIX_BLOCK_DEV = 24576;
const int ATTRIBUTE_UNIX_REGULAR_FILE = 32768;
const int ATTRIBUTE_UNIX_SYM_LINK = 40960;
const int ATTRIBUTE_UNIX_SOCKET = 49152;
/* Méthodes */
public function extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool
public function getAttr(): int
public function getCrc(): string
public function getFileTime(): string
public function getHostOs(): int
public function getMethod(): int
public function getName(): string
public function getPackedSize(): int
public function getStream(string `$password` = ?): resource|false
public function getUnpackedSize(): int
public function getVersion(): int
public function isDirectory(): bool
public function isEncrypted(): bool
public function __toString(): string
}

## Constantes pré-définies

`RarEntry::HOST_MSDOS`
  Si la valeur retournée de RarEntry::getHostOs() est égale à cette constante, MS-DOS est utilisé pour ajouter cette entrée. Destinée à remplacer la constante `RAR_HOST_MSDOS`.
`RarEntry::HOST_OS2`
  Si la valeur retournée de RarEntry::getHostOs() est égale à cette constante, OS/2 est utilisé pour ajouter cette entrée. Destinée à remplacer la constante `RAR_HOST_OS2`.
`RarEntry::HOST_WIN32`
  Si la valeur retournée de RarEntry::getHostOs() est égale à cette constante, Microsoft Windows est utilisé pour ajouter cette entrée. Destinée à remplacer la constante `RAR_HOST_WIN32`.
`RarEntry::HOST_UNIX`
  Si la valeur retournée de RarEntry::getHostOs() est égale à cette constante, UNIX OS est utilisé pour ajouter cette entrée. Destinée à remplacer la constante `RAR_HOST_UNIX`.
`RarEntry::HOST_MACOS`
  Si la valeur retournée de RarEntry::getHostOs() est égale à cette constante, Mac OS est utilisé pour ajouter cette entrée.
`RarEntry::HOST_BEOS`
  Si la valeur retournée de RarEntry::getHostOs() est égale à cette constante, BeOS est utilisé pour ajouter cette entrée. Destinée à remplacer la constante `RAR_HOST_BEOS`.
`RarEntry::ATTRIBUTE_WIN_READONLY`
  Bit représentant une entrée Windows avec un attribut en lecture seule. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_HIDDEN`
  Bit représentant une entrée Windows avec un attribut caché. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_SYSTEM`
  Bit représentant une entrée Windows avec un attribut système. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_DIRECTORY`
  Bit représentant une entrée Windows avec un attribut dossier (l'entrée est un dossier). À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows. Voir aussi la méthode RarEntry::isDirectory(), qui fonctionne également avec les entrées qui ne sont pas ajoutées dans WinRAR.
`RarEntry::ATTRIBUTE_WIN_ARCHIVE`
  Bit représentant une entrée Windows avec un attribut d'archive. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_DEVICE`
  Bit représentant une entrée Windows avec un attribut de périphérique. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_NORMAL`
  Bit représentant une entrée Windows avec un attribut de fichier normal (l'entrée n'est pas un dossier). À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows. Voir aussi la méthode RarEntry::isDirectory(), qui fonctionne également avec les entrées qui ne sont pas ajoutées dans WinRAR.
`RarEntry::ATTRIBUTE_WIN_TEMPORARY`
  Bit représentant une entrée Windows avec un attribut temporaire. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_SPARSE_FILE`
  Bit représentant une entrée Windows avec un attribut de fichier fragmenté (le fichier est un fichier NTFS fragmenté). À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_REPARSE_POINT`
  Bit représentant une entrée Windows avec un attribut de point d'analyse (le fichier est un point d'analyse NTFS ; c.-à-d. une jonction de dossier ou un système de fichier monté). À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_COMPRESSED`
  Bit représentant une entrée Windows avec un attribut compressé (NTFS uniquement). À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_OFFLINE`
  Bit représentant une entrée Windows avec un attribut hors-ligne (le fichier est hors-ligne et non accessible). À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED`
  Bit représentant une entrée Windows avec un attribut dont le contenu n'est pas indexé (l'entrée doit être indexée). À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_ENCRYPTED`
  Bit représentant une entrée Windows avec un attribut crypté (NTFS uniquement). À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_VIRTUAL`
  Bit représentant une entrée Windows avec un attribut virtuel. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est Microsoft Windows.
`RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE`
  Bit représentant une entrée UNIX qui est exécutable par tous. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE`
  Bit représentant une entrée UNIX qui est accessible en écriture par tous. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_READ`
  Bit représentant une entrée UNIX qui est accessible en lecture par tous. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE`
  Bit représentant une entrée UNIX qui est dans le groupe des exécutables. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE`
  Bit représentant une entrée UNIX qui est dans le groupe des accessibles en écriture. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_READ`
  Bit représentant une entrée UNIX qui est dans le groupe des accessibles en lecture. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE`
  Bit représentant une entrée UNIX dont le propriétaire est exécutable. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE`
  Bit représentant une entrée UNIX dont le propriétaire est accessible en écriture. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_READ`
  Bit représentant une entrée UNIX dont le propriétaire est accessible en lecture. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_STICKY`
  Bit représentant une entrée UNIX ayant le bit sticky. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETGID`
  Bit représentant un attribut UNIX setgid. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETUID`
  Bit représentant un attribut UNIX setuid. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX.
`RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`
  Masque permettant d'isoler les 4 derniers bits (nibble) des attributs UNIX (_S_IFMT, le type du masque de fichier). À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX et avec les constantes `RarEntry::ATTRIBUTE_UNIX_FIFO`, `RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`, `RarEntry::ATTRIBUTE_UNIX_DIRECTORY`, `RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`, `RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`, `RarEntry::ATTRIBUTE_UNIX_SYM_LINK` et `RarEntry::ATTRIBUTE_UNIX_SOCKET`.
`RarEntry::ATTRIBUTE_UNIX_FIFO`
  Attributs FIFOs Unix dont les 4 derniers bits ont cette valeur. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX et avec la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`
  Attributs des périphériques Unix dont les 4 derniers bits ont cette valeur. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX et avec la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_DIRECTORY`
  Attributs des dossiers Unix dont les 4 derniers bits ont cette valeur. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX et avec la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. Voir aussi la méthode RarEntry::isDirectory() qui fonctionne également avec les entrées qui ont été ajoutées sous d'autres systèmes d'exploitation.
`RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`
  Attributs des périphériques de bloc Unix dont les 4 derniers bits ont cette valeur. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX et avec la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`
  Attributs des fichiers réguliers (pas de dossiers) Unix dont les 4 derniers bits ont cette valeur. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX et avec la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. Voir aussi la méthode RarEntry::isDirectory() qui fonctionne également avec les entrées qui ont été ajoutées sous d'autres systèmes d'exploitation.
`RarEntry::ATTRIBUTE_UNIX_SYM_LINK`
  Attributs des liens symboliques Unix dont les 4 derniers bits ont cette valeur. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX et avec la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_SOCKET`
  Attributs des sockets Unix dont les 4 derniers bits ont cette valeur. À utiliser avec la méthode RarEntry::getAttr() sur les entrées dont l'OS hôte est UNIX et avec la constante `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.

# RarEntry::extract

(PECL rar >= 0.1)

RarEntry::extract — Extrait une entrée d'une archive

### Description

public function RarEntry::extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool

RarEntry::extract() extrait une entrée de données. Ceci va créer un nouveau fichier dans le dossier spécifié par le paramètre `dir` portant un nom identique au nom de l'entrée, tant que le second argument n'est pas spécifié. Voir ci-dessous pour plus d'informations.

### Liste de paramètres

`dir`
  Chemin vers le dossier où le fichier extrait devra être créé. Ce paramètre sera utilisé uniquement si le paramètre `filepath` n'est pas fourni. Si ces 2 paramètres sont vides, l'extraction se fera dans le dossier courant.
`filepath`
  Chemin (relatif ou absolu) contenant le dossier et le nom du fichier à extraire. Ce paramètre écrase à la fois le paramètre `dir` et le nom original du fichier.
`password`
  Le mot de passe à utiliser pour déchiffrer cette entrée. Si l'entrée n'est pas cryptée, cette valeur ne sera pas utilisée et peut être omise. Si ce paramètre est omis et que l'entrée est cryptée, le mot de passe fourni à la fonction rar_open(), s'il existe, sera utilisé. Si un mauvais mot de passe est fourni, soit explicitement ou implicitement via la fonction rar_open(), la vérification CRC échouera et cette méthode échouera, en retournant `false`. Si aucun mot de passe n'est fourni alors qu'il est nécessaire, cette méthode échouera en retournant `false`. Il est possible de vérifier si une entrée est cryptée avec la méthode RarEntry::isEncrypted().
`extended_data`
  Si vaut `true`, les informations étendues comme NTFS ACLs et les informations sur le propriétaire Unix seront définies dans les fichiers extraits, s'ils sont bien définis dans l'archive.

Avertissement

Avant la version 2.0.0, cette fonction ne gérait pas les chemins relatifs correctement. Utiliser la fonction realpath() comme contournement.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL rar 3.0.0 | Le paramètre `extended_data` a été ajouté.
PECL rar 3.0.0 | Support des archives RAR contenant des entrées portant le même nom.

### Exemples

Exemple #1 Exemple avec RarEntry::extract()

    <?php

    $rar_file = rar_open('example.rar') or die("Échec lors de l'ouverture de l'archive RAR");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("L'entrée demandée n'existe pas !");

    $entry->extract('/dir/to'); // Création de /dir/to/Dir/file.txt
    $entry->extract(false, '/dir/to/new_name.txt'); // Création de /dir/to/new_name.txt

    ?>

Exemple #2 Comment extraire tous les fichiers d'une archive :

    <?php

    /* Exemple fourni par Erik Jenssen aka erix */

    $filename = "foobar.rar";
    $filepath = "/home/foo/bar/";

    $rar_file = rar_open($filepath.$filename);
    $list = rar_list($rar_file);
    foreach($list as $file) {
        $entry = rar_entry_get($rar_file, $file);
        $entry->extract("."); // Extraction dans le dossier courant
    }
    rar_close($rar_file);

    ?>

### Voir aussi

- RarEntry::getStream() - Récupère le gestionnaire de fichier pour une entrée
- Le gestionnaire `rar://`

# RarEntry::getAttr

(PECL rar >= 0.1)

RarEntry::getAttr — Récupère les attributs d'une entrée

### Description

public function RarEntry::getAttr(): int

Retourne les attributs dépendants de l'OS d'une entrée d'une archive.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les attributs ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec RarEntry::getAttr()

    <?php

    $rar_file = rar_open('example.rar') or die("Impossible d'ouvrir l'archive RAR");

    $entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("L'entrée demandée n'existe pas !");

    $host_os = $entry->getHostOs();
    $attr = $entry->getAttr();

    switch($host_os) {
        case RAR_HOST_MSDOS:
        case RAR_HOST_OS2:
        case RAR_HOST_WIN32:
        case RAR_HOST_MACOS:
            printf("%c%c%c%c%c%c\n",
                    ($attr & 0x08) ? 'V' : '.',
                    ($attr & 0x10) ? 'D' : '.',
                    ($attr & 0x01) ? 'R' : '.',
                    ($attr & 0x02) ? 'H' : '.',
                    ($attr & 0x04) ? 'S' : '.',
                    ($attr & 0x20) ? 'A' : '.');
            break;
        case RAR_HOST_UNIX:
        case RAR_HOST_BEOS:
            switch ($attr & 0xF000)
            {
                case 0x4000:
                    printf("d");
                    break;
                case 0xA000:
                    printf("l");
                    break;
                default:
                    printf("-");
                    break;
            }
            printf("%c%c%c%c%c%c%c%c%c\n",
                    ($attr & 0x0100) ? 'r' : '-',
                    ($attr & 0x0080) ? 'w' : '-',
                    ($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
                    ($attr & 0x0020) ? 'r' : '-',
                    ($attr & 0x0010) ? 'w' : '-',
                    ($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
                    ($attr & 0x0004) ? 'r' : '-',
                    ($attr & 0x0002) ? 'w' : '-',
                    ($attr & 0x0001) ? 'x' : '-');
            break;
    }

    rar_close($rar_file);

    ?>

### Voir aussi

- RarEntry::getHostOs() - Récupère le code de l'hôte pour une entrée
- Les constantes de la classe RarEntry

# RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrc — Récupère le CRC d'une entrée

### Description

public function RarEntry::getCrc(): string

Retourne une chaîne de caractères hexadécimale représentant le CRC d'une entrée d'une archive.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le CRC d'une entrée d'une archive, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL rar 2.0.0 | Cette méthode retourne maintenant des valeurs correctes pour les archives sur plusieurs volumes.

# RarEntry::getFileTime

(PECL rar >= 0.1)

RarEntry::getFileTime — Récupère la date de dernière modification d'une entrée

### Description

public function RarEntry::getFileTime(): string

Récupère la date de dernière modification d'une entrée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la date de dernière modification de l'entrée sous la forme d'une chaîne de caractères au format `YYYY-MM-DD HH:II:SS`, ou `false` si une erreur survient.

# RarEntry::getHostOs

(PECL rar >= 0.1)

RarEntry::getHostOs — Récupère le code de l'hôte pour une entrée

### Description

public function RarEntry::getHostOs(): int

Retourne le code de l'OS hôte d'une entrée d'une archive.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code de l'OS hôte d'une entrée, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec RarEntry::getHostOs() (version >= 2.0.0)

    <?php

    $rar_file = rar_open('example.rar') or die("Échec lors de l'ouverture de l'archive RAR");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("L'entrée demandée n'existe pas !");

    switch ($entry->getHostOs()) {
        case RarEntry::HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RarEntry::HOST_OS2:
            echo "OS2\n";
            break;
        case RarEntry::HOST_WIN32:
            echo "Win32\n";
            break;
        case RarEntry::HOST_MACOS:
            echo "MacOS\n";
            break;
        case RarEntry::HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RarEntry::HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

Exemple #2 Exemple avec RarEntry::getHostOs() (version <= 1.0.0)

    <?php

    $rar_file = rar_open('example.rar') or die("Échec lors de l'ouverture de l'archive RAR");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("L'entrée demandée n'existe pas !");

    switch ($entry->getHostOs()) {
        case RAR_HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RAR_HOST_OS2:
            echo "OS2\n";
            break;
        case RAR_HOST_WIN32:
            echo "Win32\n";
            break;
        case RAR_HOST_MACOS:
            echo "MacOS\n";
            break;
        case RAR_HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RAR_HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

### Voir aussi

- RarEntry::extract() - Extrait une entrée d'une archive

# RarEntry::getMethod

(PECL rar >= 0.1)

RarEntry::getMethod — Récupère la méthode utilisée pour l'ajout d'une entrée

### Description

public function RarEntry::getMethod(): int

Récupère la méthode utilisée lors de l'ajout d'une entrée dans l'archive courante.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le numéro de la méthode, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec RarEntry::getMethod()

    <?php

    $rar_file = rar_open('example.rar') or die("Échec lors de l'ouverture de l'archive RAR");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("L'entrée demandée n'existe pas !");

    echo "Numéro de la méthode : " . $entry->getMethod();

    ?>

# RarEntry::getName

(PECL rar >= 0.1)

RarEntry::getName — Récupère le nom de l'entrée

### Description

public function RarEntry::getName(): string

Retourne le nom (avec le chemin) de l'entrée d'une archive.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nom de l'entrée, sous la forme d'une chaîne de caractères ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL rar 2.0.0 | Depuis la version 2.0.0, la chaîne de caractères retournée est encodée en Unicode/UTF-8.

### Exemples

Exemple #1 Exemple avec RarEntry::getName()

    <?php

    // Cet exemple est sûr même pour les pages non encodées en UTF-8.
    // Pour celles encodées en UTF-8, l'appel à la fonction mb_convert_encoding n'est pas nécessaire

    $rar_file = rar_open('example.rar') or die("Erreur lors de l'ouverture de l'archive Rar");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Entrée non trouvée");

    echo "Nom de l'entrée : " . mb_convert_encoding(
        htmlentities(
            $entry->getName(),
            ENT_COMPAT,
            "UTF-8"
        ),
        "HTML-ENTITIES",
        "UTF-8"
    );

    ?>

# RarEntry::getPackedSize

(PECL rar >= 0.1)

RarEntry::getPackedSize — Récupère la taille compressée d'une entrée

### Description

public function RarEntry::getPackedSize(): int

Récupère la taille compressée d'une entrée d'archive.

> Note: Noter que sous les plateformes 32bits (y compris sous Windows 64bits), la taille maximale retournée sera tronquée à 2 Go. Vérifier la constante `PHP_INT_MAX`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la taille compressée, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL rar 2.0.0 | Cette méthode retourne maintenant des valeurs correctes de tailles compressées plus grandes que 2Go sous les plateformes 64bits et ne retourne jamais de valeurs négatives sous les autres plateformes.

### Exemples

Exemple #1 Exemple avec RarEntry::getPackedSize()

    <?php

    $rar_file = rar_open('example.rar') or die("Échec lors de l'ouverture de l'archive Rar");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Impossible de trouver l'entrée demandée");

    echo "Taille compressée de " . $entry->getName() . " = " . $entry->getPackedSize() . " octets";

    ?>

# RarEntry::getStream

(PECL rar >= 2.0.0)

RarEntry::getStream — Récupère le gestionnaire de fichier pour une entrée

### Description

public function RarEntry::getStream(string `$password` = ?): resource|false

Retourne le gestionnaire de fichier qui supporte les opérations de lecture. Ce gestionnaire permet la décompression à la volée de l'entrée.

Le gestionnaire ne sera pas touché par l'appel à la fonction rar_close().

Avertissement

Le flux résultant ne permet pas de vérifier l'intégrité des données. Par exemple, un fichier corrompu ou crypté avec une clé fausse ne sera pas détecté. Ce sera de la responsabilité du développeur d'utiliser le CRC de l'entrée pour vérifier son intégrité, s'il le souhaite.

### Liste de paramètres

`password`
  Le mot de passe à utiliser pour déchiffrer l'entrée. Si l'entrée n'est pas cryptée, la valeur ne sera pas utilisée et peut être omise. Si ce paramètre est omis et que l'entrée est cryptée, le mot de passe fourni lors de l'appel à la fonction rar_open() sera utilisé, s'il a été fourni. Si un mauvais mot de passe est fourni, soit explicitement, soit implicitement via la fonction rar_open(), le flux résultant produira un affichage incorrect. Si aucun mot de passe n'est fourni alors qu'il est nécessaire, la méthode échoue et retournera `false`. Il est possible de vérifier si l'entrée est cryptée en utilisant la méthode RarEntry::isEncrypted().

### Valeurs de retour

Le gestionnaire de fichier, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL rar 3.0.0 | Support des archives RAR dont les entrées portent le même nom.

### Exemples

Exemple #1 Exemple avec RarEntry::getStream()

    <?php

    $rar_file = rar_open('example.rar');
    if ($rar_file === false)
        die("Échec lors de l'ouverture de l'archive Rar");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt');
    if ($entry === false)
        die("Impossible de trouver l'entrée demandée");

    $stream = $entry->getStream();
    if ($stream === false)
        die("Échec lors de la récupération du flux.");

    rar_close($rar_file); //le flux est indépendant du fichier

    while (!feof($stream)) {
        $buff = fread($stream, 8192);
        if ($buff !== false)
            echo $buff;
        else
            break; //erreur fread
    }

    fclose($stream);

    ?>

### Voir aussi

- RarEntry::extract() - Extrait une entrée d'une archive
- Le gestionnaire `rar://`

# RarEntry::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSize — Récupère la taille décompressée d'une entrée

### Description

public function RarEntry::getUnpackedSize(): int

Récupère la taille décompressée d'une entrée d'une archive.

> Note: Il est à noter que sur les plateformes 32bits (y compris les Windows x64), la taille maximale est tronquée à 2 Go. Vérifier la constante `PHP_INT_MAX`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la taille décompressée, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL rar 2.0.0 | Cette méthode retourne désormais les valeurs correctes pour les tailles décompressées plus grandes que 2Go sur les plateformes 64bits et ne retournera jamais de valeurs négatives pour les autres plateformes.

### Valeurs de retour

Exemple #1 Exemple avec RarEntry::getUnpackedSize()

    <?php

    $rar_file = rar_open('example.rar') or die("Échec lors de l'ouverture de l'archive Rar");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Échec lors de la récupération de l'entrée");

    echo "Taille décompressée de " . $entry->getName() . " = " . $entry->getUnpackedSize() . " octets";

    ?>

# RarEntry::getVersion

(PECL rar >= 0.1)

RarEntry::getVersion — Récupère la version minimale du logiciel RAR à utiliser pour décompresser une entrée

### Description

public function RarEntry::getVersion(): int

Retourne la version minimale du logiciel RAR (e.g. WinRAR) requise pour décompresser l'entrée. Elle sera encodée sous la forme 10 * version majeure + version mineure.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la version ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec RarEntry::getVersion()

    <?php

    $rar_file = rar_open('example.rar') or die("Échec lors de l'ouverture de l'archive Rar");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("L'entrée demandée n'existe pas");

    echo "Version Rar requise pour décompresser l'entrée : " . $entry->getVersion();

    ?>

# RarEntry::isDirectory

(PECL rar >= 2.0.0)

RarEntry::isDirectory — Teste si l'entrée courante est un dossier

### Description

public function RarEntry::isDirectory(): bool

Teste si l'entrée courante est un dossier.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'entrée est un dossier, `false` sinon.

### Notes

Cette fonction est uniquement disponible depuis la version 2.0.0, mais ce test peut également être effectué en vérifiant les attributs de l'entrée comme ceci (ne fonctionne que pour des fichiers compressés avec RAR sous Windows ou Unix) :

    <?php
    //...
    // Ouvre le fichier, récupère l'entrée et la stock dans la variable $e...
    //...

    $isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
        (($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
    ?>

# RarEntry::isEncrypted

(PECL rar >= 2.0.0)

RarEntry::isEncrypted — Teste si une entrée est cryptée

### Description

public function RarEntry::isEncrypted(): bool

Teste si le contenu de l'entrée courante est crypté.

> Note: Le mot de passe utilisé peut différer entre plusieurs fichiers de la même archive RAR.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'entrée courante est cryptée, `false` sinon.

# RarEntry::__toString

(PECL rar >= 2.0.0)

RarEntry::__toString — Récupère une représentation sous forme de chaîne de caractères d'une entrée

### Description

public function RarEntry::__toString(): string

Retourne une représentation textuelle d'une entrée. Ceci inclut les entrées sous forme de fichier, de dossier (les liens symboliques ou les objets spéciaux seront traités comme des fichiers), les noms UTF-8 des entrées, mais aussi les CRC. La forme et le contenu de cette représentation peuvent changer dans le futur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une représentation textuelle de l'entrée.

## Sommaire

- RarEntry::extract — Extrait une entrée d'une archive
- RarEntry::getAttr — Récupère les attributs d'une entrée
- RarEntry::getCrc — Récupère le CRC d'une entrée
- RarEntry::getFileTime — Récupère la date de dernière modification d'une entrée
- RarEntry::getHostOs — Récupère le code de l'hôte pour une entrée
- RarEntry::getMethod — Récupère la méthode utilisée pour l'ajout d'une entrée
- RarEntry::getName — Récupère le nom de l'entrée
- RarEntry::getPackedSize — Récupère la taille compressée d'une entrée
- RarEntry::getStream — Récupère le gestionnaire de fichier pour une entrée
- RarEntry::getUnpackedSize — Récupère la taille décompressée d'une entrée
- RarEntry::getVersion — Récupère la version minimale du logiciel RAR à utiliser pour décompresser une entrée
- RarEntry::isDirectory — Teste si l'entrée courante est un dossier
- RarEntry::isEncrypted — Teste si une entrée est cryptée
- RarEntry::__toString — Récupère une représentation sous forme de chaîne de caractères d'une entrée

# La classe RarException

(PECL rar >= 2.0.0)

## Introduction

Cette classe sert à 2 choses : C'est le type d'exceptions lancées par l'extension RAR et permet, via ses méthodes statiques, de savoir et de définir les comportements des erreurs de l'extension, c.-à-d. si l'exception doit être émise ou bien si des alertes PHP doivent être émises.

Les codes erreurs suivants sont utilisés :

- -1 - Erreur externe à la bibliothèque UnRAR
- 11 - Mémoire insuffisante
- 12 - Données incorrectes
- 13 - Archive incorrecte
- 14 - Format inconnu
- 15 - Erreur lors de l'ouverture du fichier
- 16 - Erreur lors de la création d'un fichier
- 17 - Erreur lors de la fermeture d'un fichier
- 18 - Erreur lors de la lecture
- 19 - Erreur lors de l'écriture
- 20 - Buffer trop petit
- 21 - Erreur RAR inconnue
- 22 - Mot de passe nécessaire mais non fourni

## Synopsis de la classe

final class RarException extends Exception {
/* Méthodes */
public static function isUsingExceptions(): bool
public static function setUsingExceptions(bool `$using_exceptions`): void
/* Méthodes héritées */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# RarException::isUsingExceptions

(PECL rar >= 2.0.0)

RarException::isUsingExceptions — Vérifie si le gestionnaire d'erreur utilise les exceptions ou non

### Description

public static function RarException::isUsingExceptions(): bool

Vérifie si les fonctions RAR émettent des alertes et retournent des valeurs d'erreur ou bien si elles émettent des exceptions dans la plupart des cas (cela n'inclut pas certaines erreurs de programmation telles que le fait de passer des types incorrects comme arguments).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si les exceptions sont utilisées, `false` sinon.

### Exemples

Exemple #1 Exemple avec RarException::isUsingExceptions()

    <?php
    // Par défaut, les exceptions ne sont pas utilisées
    var_dump(RarException::isUsingExceptions());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    bool(false)

### Voir aussi

- RarException::setUsingExceptions() - Active ou désactive les exceptions dans le gestionnaire d'erreurs

# RarException::setUsingExceptions

(PECL rar >= 2.0.0)

RarException::setUsingExceptions — Active ou désactive les exceptions dans le gestionnaire d'erreurs

### Description

public static function RarException::setUsingExceptions(bool `$using_exceptions`): void

Si et seulement si l'argument vaut `true`, alors, au lieu d'émettre des alertes et de retourner des valeurs spéciales indiquant une erreur lorsque la bibliothèque UnRAR rencontre une erreur, une exception de type RarException est émise.

Les exceptions seront également lancées pour les erreurs suivantes, qui surviennent en dehors de la bibliothèque (leurs codes erreurs seront -1) :

- tentative d'une opération sur un objet RarArchive clos ou un objet RarEntry relatif au premier ;
- tentative de récupération d'une entrée qui n'existe pas avec la méthode RarArchive::getEntry().

### Liste de paramètres

`using_exceptions`
  Doit valoir `true` pour activer l'émission d'exceptions, `false` pour le désactiver (par défaut).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec RarException::setUsingExceptions()

    <?php
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("does_not_exist.rar");
    var_dump($arch);

    RarException::setUsingExceptions(true);
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("does_not_exist.rar");
    var_dump($arch); //non atteint
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    bool(false)

    Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
    bool(false)
    bool(true)

    Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
    Stack trace:
    #0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
    #1 {main}
      thrown in C:\php_rar\trunk\tests\test.php on line 8

### Voir aussi

- RarException::isUsingExceptions() - Vérifie si le gestionnaire d'erreur utilise les exceptions ou non

## Sommaire

- RarException::isUsingExceptions — Vérifie si le gestionnaire d'erreur utilise les exceptions ou non
- RarException::setUsingExceptions — Active ou désactive les exceptions dans le gestionnaire d'erreurs

- Installation/Configuration
  - Installation
  - Types de ressources
- Constantes pré-définies
- Exemples
- Fonctions Rar
  - rar_wrapper_cache_stats — Statistique pour le cache du gestionnaire URL
- RarArchive — La classe RarArchive
  - RarArchive::close — Ferme une archive RAR et libère toutes les ressources
  - RarArchive::getComment — Récupère un commentaire depuis une archive RAR
  - RarArchive::getEntries — Récupère la liste complète depuis l'archive RAR
  - RarArchive::getEntry — Récupère une entrée depuis une archive RAR
  - RarArchive::isBroken — Teste si une archive est corrompue (incomplète)
  - RarArchive::isSolid — Vérifie si l'archive RAR est solide
  - RarArchive::open — Ouvre une archive RAR
  - RarArchive::setAllowBroken — Autorise ou non l'ouverture d'archives corrompues
  - RarArchive::__toString — Récupère une représentation sous forme de texte
- RarEntry — La classe RarEntry
  - RarEntry::extract — Extrait une entrée d'une archive
  - RarEntry::getAttr — Récupère les attributs d'une entrée
  - RarEntry::getCrc — Récupère le CRC d'une entrée
  - RarEntry::getFileTime — Récupère la date de dernière modification d'une entrée
  - RarEntry::getHostOs — Récupère le code de l'hôte pour une entrée
  - RarEntry::getMethod — Récupère la méthode utilisée pour l'ajout d'une entrée
  - RarEntry::getName — Récupère le nom de l'entrée
  - RarEntry::getPackedSize — Récupère la taille compressée d'une entrée
  - RarEntry::getStream — Récupère le gestionnaire de fichier pour une entrée
  - RarEntry::getUnpackedSize — Récupère la taille décompressée d'une entrée
  - RarEntry::getVersion — Récupère la version minimale du logiciel RAR à utiliser pour décompresser une entrée
  - RarEntry::isDirectory — Teste si l'entrée courante est un dossier
  - RarEntry::isEncrypted — Teste si une entrée est cryptée
  - RarEntry::__toString — Récupère une représentation sous forme de chaîne de caractères d'une entrée
- RarException — La classe RarException
  - RarException::isUsingExceptions — Vérifie si le gestionnaire d'erreur utilise les exceptions ou non
  - RarException::setUsingExceptions — Active ou désactive les exceptions dans le gestionnaire d'erreurs

# Zip

# Introduction

Cette extension offre la possibilité de lire et d'écrire des archives compressées ZIP, et d'accéder aux fichiers et dossiers s'y trouvant.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Types de ressources

## Pré-requis

Cette extension requiert » libzip. Version 1.1.2 était fournie avec PHP jusqu'à la version 7.3.

La version minimale supportée est 0.11, mais une version ultérieure est vivement recommandée.

- Version 1.2 requise pour le support du chiffrement, voir ZipArchive::setEncryptionIndex()
- Version 1.3 requise pour le support de l'avancement, voir ZipArchive::registerProgressCallback()
- Version 1.6 requise pour le support d'annulation, voir ZipArchive::registerCancelCallback()

## Installation

## Systèmes Linux

Pour utiliser ces fonctions, PHP doit être compilé avec le support ZIP en utilisant l'option de configuration --with-zip.

Avant PHP 7.4.0, libzip était inclus avec PHP, et pour compiler l'extension, il fallait utiliser l'option de configuration --enable-zip. À partir de PHP 7.3.0, il était déconseillé de construire avec la version incluse de libzip, mais cela restait possible en utilisant l'option de configuration --without-libzip.

Une option de configuration --with-libzip=DIR a été ajoutée pour utiliser une installation système de libzip. La version 0.11 de libzip est requise, avec la recommandation d'utiliser la version 0.11.2 ou ultérieure.

## Windows

À partir de PHP 8.2.0, la DLL php_zip.dll doit être activée dans php.ini. Précédemment, cette extension était intégrée.

## Installation via PECL

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/zip.

## Types de ressources

Il y a deux types de ressources utilisées par le module Zip. La première est le dossier Zip d'une archive Zip, et la seconde, l'entrée Zip de l'archive.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

ZipArchive utilise des constantes de classe. Il existe différents types de constantes, dont les principaux sont les suivants : Les drapeaux globaux (préfixés par `AFL_`), les options (préfixées par `FL_`), les erreurs (préfixées par `ER_`) ou les modes (sans préfixe).

Modes d'ouverture de l'archive
`ZipArchive::CREATE` (int)
  Crée l'archive si elle n'existe pas.
`ZipArchive::OVERWRITE` (int)
  Si l'archive existe, ignorer son contenu actuel. En d'autres termes, gérer de la même manière qu'une archive vide.
`ZipArchive::EXCL` (int)
  Erreur si l'archive existe déjà.
`ZipArchive::RDONLY` (int)
  Ouvre l'archive en mode lecture seule. Disponible à partir de PHP 7.4.3 et PECL zip 1.17.1, respectivement, si compilé contre libzip ≥ 1.0.0.
`ZipArchive::CHECKCONS` (int)
  Effectue des analyses supplémentaires de cohérence et émet une erreur si elles échouent.

Les drapeaux globaux d'archivage
`ZipArchive::AFL_RDONLY` (int)
  L'archive est en lecture seule, elle ne peut pas être effacée. Disponible à partir de PHP 8.3.0 et PECL zip 1.22.0, respectivement, si construit avec libzip ≥ 1.10.0.
`ZipArchive::AFL_IS_TORRENTZIP` (int)
  L'archive actuelle est torrentzippée. Disponible à partir de PHP 8.3.0 et PECL zip 1.22.0, respectivement, si construit avec libzip ≥ 1.10.0.
`ZipArchive::AFL_WANT_TORRENTZIP` (int)
  Écriture d'une archive au format torrentzip. Disponible à partir de PHP 8.3.0 et PECL zip 1.22.0, respectivement, si construit avec libzip ≥ 1.10.0.
`ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` (int)
  Ne supprime pas le fichier si l'archive est vide. Disponible à partir de PHP 8.3.0 et PECL zip 1.22.0, respectivement, si construit avec libzip ≥ 1.10.0.

Les options d'archivage
`ZipArchive::FL_NOCASE` (int)
  Ignore la casse sur le nom.
`ZipArchive::FL_NODIR` (int)
  Ignore le composant dossier.
`ZipArchive::FL_COMPRESSED` (int)
  Lit les données compressées.
`ZipArchive::FL_UNCHANGED` (int)
  Utilise les données originales, en ignorant les modifications.
`ZipArchive::FL_RECOMPRESS` (int)
  Force la recompression des données. Disponible à partir de PHP 8.0.0 et PECL zip 1.18.0. Obsolète à partir de PHP 8.3.0 et PECL zip 1.22.1, sera supprimé dans une version future de libzip.
`ZipArchive::FL_ENCRYPTED` (int)
  Lit les données chiffrées (implique FL_COMPRESSED). Disponible à partir de PHP 8.0.0 et PECL zip 1.18.0.
`ZipArchive::FL_OVERWRITE` (int)
  Si un fichier avec ce nom existe, le réécrire (remplacer). Disponible à partir de PHP 8.0.0 et PECL zip 1.18.0.
`ZipArchive::FL_LOCAL` (int)
  Dans l'en-tête local. Disponible à partir de PHP 8.0.0 et PECL zip 1.18.0.
`ZipArchive::FL_CENTRAL` (int)
  Dans le dossier central. Disponible à partir de PHP 8.0.0 et PECL zip 1.18.0.
`ZipArchive::FL_ENC_GUESS` (int)
  Devine l'encodage de la chaîne (par défaut). Disponible à partir de PHP 7.0.8.
`ZipArchive::FL_ENC_RAW` (int)
  Récupère la chaîne non modifiée. Disponible à partir de PHP 7.0.8.
`ZipArchive::FL_ENC_STRICT` (int)
  Suit les spécifications strictement. Disponible à partir de PHP 7.0.8.
`ZipArchive::FL_ENC_UTF_8` (int)
  La chaîne est encodée UTF-8. Disponible à partir de PHP 7.0.8.
`ZipArchive::FL_ENC_CP437` (int)
  La chaîne est encodée CP437. Disponible à partir de PHP 7.0.8.
`ZipArchive::FL_OPEN_FILE_NOW` (int)
  Ouvrir le fichier lorsqu'il est ajouté au lieu d'attendre que l'archive soit fermée. Attention à la consommation des descripteurs de fichiers. Disponible à partir de PHP 8.3.0 et PECL zip 1.22.1.

Modes de compression
`ZipArchive::CM_DEFAULT` (int)
  Meilleure compression ou stockage.
`ZipArchive::CM_STORE` (int)
  Stocké (non-compressé).
`ZipArchive::CM_SHRINK` (int)
  Retrait.
`ZipArchive::CM_REDUCE_1` (int)
  Réduit de facteur 1.
`ZipArchive::CM_REDUCE_2` (int)
  Réduit de facteur 2.
`ZipArchive::CM_REDUCE_3` (int)
  Réduit de facteur 3.
`ZipArchive::CM_REDUCE_4` (int)
  Réduit de facteur 4.
`ZipArchive::CM_IMPLODE` (int)
  Réunit.
`ZipArchive::CM_DEFLATE` (int)
  Compression.
`ZipArchive::CM_DEFLATE64` (int)
  Compression 64.
`ZipArchive::CM_PKWARE_IMPLODE` (int)
  Réunit PKWARE.
`ZipArchive::CM_BZIP2` (int)
  Algorithme BZIP2.
`ZipArchive::CM_LZMA` (int)
  Algorithme LZMA.
`ZipArchive::CM_LZMA2` (int)
  Algorithme LZMA2. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.0, respectivement, si compilé avec la bibliothèque libzip ≥ 1.6.0.
`ZipArchive::CM_ZSTD` (int)
  Algorithme Zstandard. Disponible à partir de PHP 8.0.0 et PECL zip 1.19.1, respectivement, si compilé avec la bibliothèque libzip ≥ 1.8.0.
`ZipArchive::CM_XZ` (int)
  Algorithme XZ. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement, si compilé avec la bibliothèque libzip ≥ 1.6.0.
`ZipArchive::CM_TERSE` (int)
`ZipArchive::CM_LZ77` (int)
`ZipArchive::CM_WAVPACK` (int)
`ZipArchive::CM_PPMD` (int)

Erreurs
`ZipArchive::ER_OK` (int)
  Aucune erreur.
`ZipArchive::ER_MULTIDISK` (int)
  Archives ZIP multidisques non supportées.
`ZipArchive::ER_RENAME` (int)
  Échec du changement de nom du fichier temporaire.
`ZipArchive::ER_CLOSE` (int)
  Échec de la fermeture de l'archive ZIP.
`ZipArchive::ER_SEEK` (int)
  Erreur de pointeur.
`ZipArchive::ER_READ` (int)
  Erreur de lecture.
`ZipArchive::ER_WRITE` (int)
  Erreur d'écriture.
`ZipArchive::ER_CRC` (int)
  Erreur CRC.
`ZipArchive::ER_ZIPCLOSED` (int)
  Archive ZIP fermée.
`ZipArchive::ER_NOENT` (int)
  Le fichier n'existe pas.
`ZipArchive::ER_EXISTS` (int)
  Le fichier existe déjà.
`ZipArchive::ER_OPEN` (int)
  Impossible d'ouvrir le fichier.
`ZipArchive::ER_TMPOPEN` (int)
  Échec lors de la création du fichier temporaire.
`ZipArchive::ER_ZLIB` (int)
  Erreur Zlib.
`ZipArchive::ER_MEMORY` (int)
  Échec d'allocation mémoire.
`ZipArchive::ER_CHANGED` (int)
  L'entrée a été modifiée.
`ZipArchive::ER_COMPNOTSUPP` (int)
  Méthode de compression non supportée.
`ZipArchive::ER_EOF` (int)
  EOF prématuré.
`ZipArchive::ER_INVAL` (int)
  Argument invalide.
`ZipArchive::ER_NOZIP` (int)
  Ce n'est pas une archive ZIP.
`ZipArchive::ER_INTERNAL` (int)
  Erreur interne.
`ZipArchive::ER_INCONS` (int)
  Archive ZIP incohérente.
`ZipArchive::ER_REMOVE` (int)
  Impossible d'effacer le fichier.
`ZipArchive::ER_DELETED` (int)
  L'entrée a été supprimée.
`ZipArchive::ER_ENCRNOTSUPP` (int)
  Méthode de chiffrement non supportée. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement.
`ZipArchive::ER_RDONLY` (int)
  Archive en lecture seule. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement.
`ZipArchive::ER_NOPASSWD` (int)
  Aucun mot de passe fourni. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement.
`ZipArchive::ER_WRONGPASSWD` (int)
  Mauvais mot de passe fourni. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement.
`ZipArchive::ER_OPNOTSUPP` (int)
  Opération non supportée. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement si compilé avec la bibliothèque libzip ≥ 1.0.0.
`ZipArchive::ER_INUSE` (int)
  La ressource est toujours en cours d'utilisation. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement si compilé avec la bibliothèque libzip ≥ 1.0.0.
`ZipArchive::ER_TELL` (int)
  Erreur de positionnement (tell). Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement si compilé avec la bibliothèque libzip ≥ 1.0.0.
`ZipArchive::ER_COMPRESSED_DATA` (int)
  Données compressées invalides. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement si compilé avec la bibliothèque libzip ≥ 1.6.0.
`ZipArchive::ER_CANCELLED` (int)
  Annulation de l'opération. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.1, respectivement si compilé avec la bibliothèque libzip ≥ 1.6.0.
`ZipArchive::ER_DATA_LENGTH` (int)
  Longueur inattendue des données. Disponible à partir de PHP 8.3.0 et PECL zip 1.22.0, respectivement, si construit avec libzip ≥ 1.10.0.
`ZipArchive::ER_NOT_ALLOWED` (int)
  Non autorisé dans torrentzip. Disponible à partir de PHP 8.3.0 et PECL zip 1.22.0, respectivement, si construit avec libzip ≥ 1.10.0.
`ZipArchive::ER_TRUNCATED_ZIP` (int)
  Archive zip potentiellement tronquée ou corrompue. Disponible à partir de PHP 8.4.0 et PECL zip 1.22.4, respectivement, si compilé avec libzip ≥ 1.11.1.

Modes de chiffrement
`ZipArchive::EM_NONE` (int)
  Aucun chiffrement. Disponible à partir de PHP 7.2.0 et PECL zip 1.14.0, respectivement.
`ZipArchive::EM_TRAD_PKWARE` (int)
  Chiffrement PKWARE traditionnel. Disponible à partir de PHP 8.0.0 et PECL zip 1.19.0, respectivement.
`ZipArchive::EM_AES_128` (int)
  Chiffrement AES 128. Disponible à partir de PHP 7.2.0 et PECL zip 1.14.0, respectivement, si compilé contre libzip ≥ 1.2.0.
`ZipArchive::EM_AES_192` (int)
  Chiffrement AES 192. Disponible à partir de PHP 7.2.0 et PECL zip 1.14.0, respectivement, si compilé contre libzip ≥ 1.2.0.
`ZipArchive::EM_AES_256` (int)
  Chiffrement AES 256. Disponible à partir de PHP 7.2.0 et PECL zip 1.14.0, respectivement, si compilé contre libzip ≥ 1.2.0.
`ZipArchive::EM_UNKNOWN` (int)
  Algorithme de chiffrement inconnu. Disponible à partir de PHP 8.0.0 et PECL zip 1.19.0, respectivement.

Constantes de paramètres de longueur
`ZipArchive::LENGTH_TO_END` (int)
  Utilise la taille du fichier, si le fichier augmente, les données additionnelles sont ignorées ; si le fichier diminue, une erreur est générée (`ZipArchive::ER_DATA_LENGTH`). Disponible à partir de PHP 8.3.0 et PECL zip 1.22.2.
`ZipArchive::LENGTH_UNCHECKED` (int)
  Utilise toutes les données disponibles. Disponible à partir de PHP 8.3.0 et PECL zip 1.22.2, si compilé avec libzip ≥ 1.10.1.

Autres constantes
`ZipArchive::LIBZIP_VERSION` (string)
  Version de la bibliothèque Zip. Disponible à partir de PHP 7.4.3 et PECL zip 1.16.0.

Système d'exploitation, constantes pour les attributs étendus
`ZipArchive::OPSYS_DOS` (int)
`ZipArchive::OPSYS_AMIGA` (int)
`ZipArchive::OPSYS_OPENVMS` (int)
`ZipArchive::OPSYS_UNIX` (int)
`ZipArchive::OPSYS_VM_CMS` (int)
`ZipArchive::OPSYS_ATARI_ST` (int)
`ZipArchive::OPSYS_OS_2` (int)
`ZipArchive::OPSYS_MACINTOSH` (int)
`ZipArchive::OPSYS_Z_SYSTEM` (int)
`ZipArchive::OPSYS_CPM` (int)
`ZipArchive::OPSYS_WINDOWS_NTFS` (int)
`ZipArchive::OPSYS_MVS` (int)
`ZipArchive::OPSYS_VSE` (int)
`ZipArchive::OPSYS_ACORN_RISC` (int)
`ZipArchive::OPSYS_VFAT` (int)
`ZipArchive::OPSYS_ALTERNATE_MVS` (int)
`ZipArchive::OPSYS_BEOS` (int)
`ZipArchive::OPSYS_TANDEM` (int)
`ZipArchive::OPSYS_OS_400` (int)
`ZipArchive::OPSYS_OS_X` (int)
`ZipArchive::OPSYS_DEFAULT` (int)
  À partir de PECL zip 1.12.4

# Exemples

Exemple #1 Création d'une archive Zip

    <?php

    $zip = new ZipArchive();
    $filename = "./test112.zip";

    if ($zip->open($filename, ZipArchive::CREATE)!==TRUE) {
        exit("Impossible d'ouvrir le fichier <$filename>\n");
    }

    $zip->addFromString("testfilephp.txt" . time(), "#1 Ceci est une chaîne texte, ajoutée comme testfilephp.txt.\n");
    $zip->addFromString("testfilephp2.txt" . time(), "#2 Ceci est une chaîne texte, ajoutée comme testfilephp2.txt.\n");
    $zip->addFile($thisdir . "/too.php","/testfromfile.php");
    echo "Nombre de fichiers : " . $zip->numFiles . "\n";
    echo "Statut :" . $zip->status . "\n";
    $zip->close();
    ?>

Exemple #2 Affiche les détails de l'archive et liste son contenu

    <?php
    $za = new ZipArchive();

    $za->open('test_with_comment.zip');
    print_r($za);
    var_dump($za);
    echo "Nombre de fichiers : " . $za->numFiles . "\n";
    echo "Statut : " . $za->status  . "\n";
    echo "Statut du système : " . $za->statusSys . "\n";
    echo "Nom du fichier : " . $za->filename . "\n";
    echo "Commentaire : " . $za->comment . "\n";

    for ($i=0; $i<$za->numFiles;$i++) {
        echo "index : $i\n";
        print_r($za->statIndex($i));
    }
    echo "Nombre de fichiers :" . $za->numFiles . "\n";
    ?>

Exemple #3 Flux ZIP : lit les meta-données d'un fichier OpenOffice

    <?php
    $reader = new XMLReader();

    $reader->open('zip://' . dirname(__FILE__) . '/test.odt#meta.xml');
    $odt_meta = array();
    while ($reader->read()) {
        if ($reader->nodeType == XMLREADER::ELEMENT) {
            $elm = $reader->name;
        } else {
            if ($reader->nodeType == XMLREADER::END_ELEMENT && $reader->name == 'office:meta') {
                break;
            }
            if (!trim($reader->value)) {
                continue;
            }
            $odt_meta[$elm] = $reader->value;
        }
    }
    print_r($odt_meta);
    ?>

Cet exemple utilise l'ancienne API (PHP 4) ; il ouvre une archive ZIP, lit chaque fichier de l'archive et affiche son contenu. L'archive test2.zip utilisée dans cet exemple est une des archives de test, se trouvant dans les sources de ZZIPlib.

Exemple #4 Exemple d'utilisation de Zip

    <?php

    $zip = zip_open("/tmp/test2.zip");

    if ($zip) {
        while ($zip_entry = zip_read($zip)) {
            echo "Nom :                        " . zip_entry_name($zip_entry) . "\n";
            echo "Taille actuelle du fichier : " . zip_entry_filesize($zip_entry) . "\n";
            echo "Taille compressée :          " . zip_entry_compressedsize($zip_entry) . "\n";
            echo "Méthode de compression :     " . zip_entry_compressionmethod($zip_entry) . "\n";

            if (zip_entry_open($zip, $zip_entry, "r")) {
                echo "Contenu du fichier :\n";
                $buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
                echo "$buf\n";

                zip_entry_close($zip_entry);
            }
            echo "\n";

        }

        zip_close($zip);

    }
    ?>

# La classe ZipArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

## Introduction

Un fichier d'archive, compressé avec Zip.

## Synopsis de la classe

class ZipArchive implements Countable {
/* Constantes */
public const int CREATE;
public const int EXCL;
public const int CHECKCONS;
public const int OVERWRITE;
public const int RDONLY;
public const int FL_NOCASE;
public const int FL_NODIR;
public const int FL_COMPRESSED;
public const int FL_UNCHANGED;
public const int FL_RECOMPRESS;
public const int FL_ENCRYPTED;
public const int FL_OVERWRITE;
public const int FL_LOCAL;
public const int FL_CENTRAL;
public const int FL_ENC_GUESS;
public const int FL_ENC_RAW;
public const int FL_ENC_STRICT;
public const int FL_ENC_UTF_8;
public const int FL_ENC_CP437;
public const int FL_OPEN_FILE_NOW;
public const int CM_DEFAULT;
public const int CM_STORE;
public const int CM_SHRINK;
public const int CM_REDUCE_1;
public const int CM_REDUCE_2;
public const int CM_REDUCE_3;
public const int CM_REDUCE_4;
public const int CM_IMPLODE;
public const int CM_DEFLATE;
public const int CM_DEFLATE64;
public const int CM_PKWARE_IMPLODE;
public const int CM_BZIP2;
public const int CM_LZMA;
public const int CM_LZMA2;
public const int CM_ZSTD;
public const int CM_XZ;
public const int CM_TERSE;
public const int CM_LZ77;
public const int CM_WAVPACK;
public const int CM_PPMD;
public const int ER_OK;
public const int ER_MULTIDISK;
public const int ER_RENAME;
public const int ER_CLOSE;
public const int ER_SEEK;
public const int ER_READ;
public const int ER_WRITE;
public const int ER_CRC;
public const int ER_ZIPCLOSED;
public const int ER_NOENT;
public const int ER_EXISTS;
public const int ER_OPEN;
public const int ER_TMPOPEN;
public const int ER_ZLIB;
public const int ER_MEMORY;
public const int ER_CHANGED;
public const int ER_COMPNOTSUPP;
public const int ER_EOF;
public const int ER_INVAL;
public const int ER_NOZIP;
public const int ER_INTERNAL;
public const int ER_INCONS;
public const int ER_REMOVE;
public const int ER_DELETED;
public const int ER_ENCRNOTSUPP;
public const int ER_RDONLY;
public const int ER_NOPASSWD;
public const int ER_WRONGPASSWD;
public const int ER_OPNOTSUPP;
public const int ER_INUSE;
public const int ER_TELL;
public const int ER_COMPRESSED_DATA;
public const int ER_CANCELLED;
public const int ER_DATA_LENGTH;
public const int ER_NOT_ALLOWED;
public const int ER_TRUNCATED_ZIP;
public const int AFL_RDONLY;
public const int AFL_IS_TORRENTZIP;
public const int AFL_WANT_TORRENTZIP;
public const int AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE;
public const int OPSYS_DOS;
public const int OPSYS_AMIGA;
public const int OPSYS_OPENVMS;
public const int OPSYS_UNIX;
public const int OPSYS_VM_CMS;
public const int OPSYS_ATARI_ST;
public const int OPSYS_OS_2;
public const int OPSYS_MACINTOSH;
public const int OPSYS_Z_SYSTEM;
public const int OPSYS_CPM;
public const int OPSYS_WINDOWS_NTFS;
public const int OPSYS_MVS;
public const int OPSYS_VSE;
public const int OPSYS_ACORN_RISC;
public const int OPSYS_VFAT;
public const int OPSYS_ALTERNATE_MVS;
public const int OPSYS_BEOS;
public const int OPSYS_TANDEM;
public const int OPSYS_OS_400;
public const int OPSYS_OS_X;
public const int OPSYS_DEFAULT;
public const int EM_NONE;
public const int EM_TRAD_PKWARE;
public const int EM_AES_128;
public const int EM_AES_192;
public const int EM_AES_256;
public const int EM_UNKNOWN;
public const string LIBZIP_VERSION;
public const int LENGTH_TO_END;
public const int LENGTH_UNCHECKED;
/* Propriétés */
public readonly int $lastId;
public readonly int $status;
public readonly int $statusSys;
public readonly int $numFiles;
public readonly string $filename;
public readonly string $comment;
/* Méthodes */
public function addEmptyDir(string `$dirname`, int `$flags` = 0): bool
public function addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool
public function addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool
public function addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false
public function addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false
public function clearError(): void
public function close(): bool
public function count(): int
public function deleteIndex(int `$index`): bool
public function deleteName(string `$name`): bool
public function extractTo(string `$pathto`, array|string|null `$files` = `null`): bool
public function getArchiveComment(int `$flags` = 0): string|false
public function getArchiveFlag(int `$flag`, int `$flags` = 0): int
public function getCommentIndex(int `$index`, int `$flags` = 0): string|false
public function getCommentName(string `$name`, int `$flags` = 0): string|false
public function getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false
public function getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false
public function getNameIndex(int `$index`, int `$flags` = 0): string|false
public function getStatusString(): string
public function getStream(string `$name`): resource|false
public function getStreamIndex(int `$index`, int `$flags` = 0): resource|false
public function getStreamName(string `$name`, int `$flags` = 0): resource|false
public static function isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public static function isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public function locateName(string `$name`, int `$flags` = 0): int|false
public function open(string `$filename`, int `$flags` = 0): bool|int
public function registerCancelCallback(callable `$callback`): bool
public function registerProgressCallback(float `$rate`, callable `$callback`): bool
public function renameIndex(int `$index`, string `$new_name`): bool
public function renameName(string `$name`, string `$new_name`): bool
public function replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool
public function setArchiveComment(string `$comment`): bool
public function setArchiveFlag(int `$flag`, int `$value`): bool
public function setCommentIndex(int `$index`, string `$comment`): bool
public function setCommentName(string `$name`, string `$comment`): bool
public function setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool
public function setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool
public function setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool
public function setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool
public function setPassword(#[\SensitiveParameter]string `$password`): bool
public function statIndex(int `$index`, int `$flags` = 0): array|false
public function statName(string `$name`, int `$flags` = 0): array|false
public function unchangeAll(): bool
public function unchangeArchive(): bool
public function unchangeIndex(int `$index`): bool
public function unchangeName(string `$name`): bool
}

## Propriétés

lastId
  Valeur de l'index de la dernière entrée ajoutée (fichier ou dossier). Disponible à partir de PHP 8.0.0 et PECL zip 1.18.0.
status
  Le statut de l'archive Zip. Disponible pour les archives fermées, à partir de PHP 8.0.0 et PECL zip 1.18.0.
statusSys
  Le statut système de l'archive Zip. Disponible pour les archives fermées, à partir de PHP 8.0.0 et PECL zip 1.18.0.
numFiles
  Le nombre de fichiers dans l'archive
filename
  Le nom du fichier dans le système de fichiers
comment
  Commentaire pour l'archive

# ZipArchive::addEmptyDir

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDir — Ajoute un nouveau dossier à une archive Zip

### Description

public function ZipArchive::addEmptyDir(string `$dirname`, int `$flags` = 0): bool

Ajoute un dossier vide dans l'archive Zip.

### Liste de paramètres

`dirname`
  Le dossier à ajouter.
`flags`
  Masque de bit consistant de `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. Le comportement de ces constantes est décrit sur la page des constantes ZIP.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` a été ajouté.

### Exemples

Exemple #1 Crée un nouveau dossier dans l'archive

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        if($zip->addEmptyDir('newDirectory')) {
            echo 'Création d\'un nouveau dossier racine';
        } else {
            echo 'Impossible de créer un nouveau dossier';
        }
        $zip->close();
    } else {
        echo 'Échec';
    }
    ?>

# ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFile — Ajoute un fichier à l'archive ZIP depuis le chemin fourni

### Description

public function ZipArchive::addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool

Ajoute un fichier à une archive ZIP depuis le chemin fourni.

> Note: Pour une portabilité maximale, il est recommandé de toujours utiliser des barres obliques (`/`) comme séparateur de dossier dans les noms de fichiers zip.

### Liste de paramètres

`filepath`
  Le chemin vers le fichier à ajouter
`entryname`
  Si fourni, ce sera le nom local dans l'archive ZIP qui écrasera le contenu du paramètre `filepath`.
`start`
  Pour copie partielle, position de départ.
`length`
  Pour copie partielle, longueur à copier, Si `ZipArchive::LENGTH_TO_END` (0) est spécifié, la taille du fichier est utilisée. Si `ZipArchive::LENGTH_UNCHECKED` est spécifié, la totalité du fichier est utilisée (à partir de `start`).
`flags`
  Masque de bit consistant de `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. Le comportement de ces constantes est décrit sur la page des constantes ZIP.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` a été ajouté.
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` a été ajouté.
8.3.0, PECL zip 1.22.2 | `ZipArchive::LENGTH_TO_END` et `ZipArchive::LENGTH_UNCHECKED` ont été ajoutés.

### Exemples

Cet exemple ouvre l'archive ZIP test.zip et ajoute le fichier /path/to/index.txt, en tant que newname.txt.

Exemple #1 Ouverture et ajout

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->addFile('/chemin/vers/index.txt', 'newname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

### Notes

> Note: Lorsqu'un fichier est marqué comme étant à ajouter à l'archive, PHP va verrouiller ce fichier. Le verrou sera relâché uniquement lorsque l'objet ZipArchive sera fermé, soit via ZipArchive::close() soit via destruction de l'objet ZipArchive. Ceci peut empêcher de supprimer le fichier en cours d'ajout même après que le verrou soit relâché.

### Voir aussi

- ZipArchive::replaceFile() - Remplace un fichier d'une archive ZIP

# ZipArchive::addFromString

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFromString — Ajoute un fichier à une archive ZIP en utilisant son contenu

### Description

public function ZipArchive::addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool

Ajoute un fichier à une archive ZIP en utilisant son contenu.

> Note: Pour une portabilité maximale, il est recommandé de toujours utiliser des barres obliques (`/`) comme séparateur de dossier dans les noms de fichiers zip.

### Liste de paramètres

`name`
  Le nom de l'entrée à créer
`content`
  Le contenu à utiliser pour créer l'entrée. Ceci est utilisé dans un mode binaire sécurisé.
`flags`
  Masque de bit consistant de `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. Le comportement de ces constantes est décrit sur la page des constantes ZIP.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` a été ajouté.

### Exemples

Exemple #1 Ajout d'une entrée dans une nouvelle archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'contenu du fichier ici');
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

Exemple #2 Ajout d'un fichier dans un dossier d'une archive

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->addFromString('dir/test.txt', 'contenu du fichier ici');
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

# ZipArchive::addGlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addGlob — Ajoute des fichiers d'un dossier en utilisant un masque glob

### Description

public function ZipArchive::addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false

Ajoute des fichiers d'un dossier qui correspondent à un masque glob `pattern`.

> Note: Pour une portabilité maximale, il est recommandé de toujours utiliser des barres obliques (`/`) comme séparateur de dossier dans les noms de fichiers zip.

### Liste de paramètres

`pattern`
  Un masque glob().
`flags`
  Un masque de bits de drapeaux `glob()`.
`options`

  Un tableau associatif d'options. Les options disponibles sont :

  - `"add_path"` Préfixe à ajouter lors de la traduction du chemin local du fichier dans l'archive. Il sera appliqué après les opérations de suppression définies par l'option `"remove_path"` ou l'option `"remove_all_path"`.
  - `"remove_path"` Préfixe à supprimer des chemins des fichiers avant de les ajouter à l'archive.
  - `"remove_all_path"` `true` pour utiliser le nom du fichier uniquement, et ajouter les fichiers directement à la racine de l'archive.
  - `"flags"` Masque de bits composé de `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. Le comportement de ces constantes est décrit sur la page des constantes ZIP.
  - `"comp_method"` Méthode de compression, l'une des constantes `ZipArchive::CM_*`.
  - `"comp_flags"` Niveau de compression.
  - `"enc_method"` Méthode de chiffrement, l'une des constantes `ZipArchive::EM_*`.
  - `"enc_password"` Mot de passe utilisé pour le chiffrement.

### Valeurs de retour

Un tableau des fichiers ajoutés en cas de succès ou `false` si une erreur survient

### Historique

Version | Description
--- | ---
8.0.0, PECL zip 1.18.0 | `"flags"` dans `options` a été ajouté.
8.0.0, PECL zip 1.18.1 | `"comp_method"`, `"comp_flags"`, `"enc_method"` et `"enc_password"` dans `options` ont été ajoutés.
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` a été ajouté.

### Exemples

Exemple #1 Exemple avec ZipArchive::addGlob()

Ajoute tous les scripts PHP et les fichiers textes du dossier courant.

    <?php
    $zip = new ZipArchive();
    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
    if ($ret !== TRUE) {
        printf("A échoué avec le code d'erreur %d", $ret);
    } else {
        $options = array('add_path' => 'sources/', 'remove_all_path' => TRUE);
        $zip->addGlob('*.{php,txt}', GLOB_BRACE, $options);
        $zip->close();
    }
    ?>

### Voir aussi

- ZipArchive::addFile() - Ajoute un fichier à l'archive ZIP depuis le chemin fourni
- ZipArchive::addPattern() - Ajoute des fichiers d'un dossier en utilisant une expression régulière PCRE

# ZipArchive::addPattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addPattern — Ajoute des fichiers d'un dossier en utilisant une expression régulière PCRE

### Description

public function ZipArchive::addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false

Ajoute des fichiers depuis un dossier qui correspondent à l'expression régulière `pattern`. L'opération n'est pas récursive. L'expression régulière sera uniquement exécutée sur le nom des fichiers.

### Liste de paramètres

`pattern`
  Une expression régulière PCRE.
`path`
  Le dossier à analyser. Par défaut, le dossier courant.
`options`
  Un tableau associatif d'options acceptées par la méthode ZipArchive::addGlob().

### Valeurs de retour

Un tableau des fichiers ajoutés en cas de succès ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec ZipArchive::addPattern()

Ajoute tous les scripts PHP et les fichiers textes du dossier courant.

    <?php
    $zip = new ZipArchive();
    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
    if ($ret !== TRUE) {
        printf("A échoué avec le code d'erreur %d", $ret);
    } else {
        $directory = realpath('.');
        $options = array('add_path' => 'sources/', 'remove_path' => $directory);
        $zip->addPattern('/\.(?:php|txt)$/', $directory, $options);
        $zip->close();
    }
    ?>

### Voir aussi

- ZipArchive::addFile() - Ajoute un fichier à l'archive ZIP depuis le chemin fourni
- ZipArchive::addGlob() - Ajoute des fichiers d'un dossier en utilisant un masque glob

# ZipArchive::clearError

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::clearError — Efface le message d'erreur, les messages système et/ou zip

### Description

public function ZipArchive::clearError(): void

Efface le message d'erreur, les messages système et/ou zip.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- ZipArchive::getStatusString() - Retourne le message du statut de l'erreur, du système ou de zip

# ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::close — Ferme l'archive active

### Description

public function ZipArchive::close(): bool

Ferme une archive ouverte ou nouvellement créée et sauvegarde les modifications. Cette méthode est appelée automatiquement à la fin du script.

Si l'archive ne contient aucun fichier, elle est complètement supprimée par défaut (pas d'enregistrement d'une archive vide) en fonction de la valeur de la constante `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- ZipArchive::setArchiveFlag() - Définit un drapeau global d'une archive ZIP

# ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::count — Compte le nombre de fichiers dans l'archive

### Description

public function ZipArchive::count(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de fichiers dans l'archive.

# ZipArchive::deleteIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteIndex — Efface une entrée de l'archive en utilisant son index

### Description

public function ZipArchive::deleteIndex(int `$index`): bool

Efface une entrée de l'archive en utilisant son index.

### Liste de paramètres

`index`
  Index de l'entrée à effacer

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Efface le fichier depuis l'archive en utilisant son index

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->deleteIndex(2);
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

# ZipArchive::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteName — Efface une entrée dans l'archive en utilisant son nom

### Description

public function ZipArchive::deleteName(string `$name`): bool

Efface une entrée dans l'archive en utilisant son nom.

### Liste de paramètres

`name`
  Nom de l'entrée à effacer

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Efface un fichier et un dossier de l'archive en utilisant les noms

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        $zip->deleteName('testfromfile.php');
        $zip->deleteName('testDir/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

# ZipArchive::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractTo — Extrait le contenu de l'archive

### Description

public function ZipArchive::extractTo(string `$pathto`, array|string|null `$files` = `null`): bool

Extrait l'archive complète ou les fichiers fournis vers un chemin spécifié.

Avertissement

Les permissions par défaut pour les fichiers et dossiers extraits donnent le plus large accès possible. Ceci peut être restreint en définissant le umask courant, qui peut être changé en utilisant umask().

Pour des raisons de sécurité, les permissions d'origine ne sont pas restaurées. Pour un exemple de comment les restaurer, consulter l'échantillon de code sur la page d'exemple de la méthode ZipArchive::getExternalAttributesIndex().

### Liste de paramètres

`pathto`
  Endroit où l'on doit extraire les fichiers.
`files`
  Les entrées à extraire. Ce peut être soit le nom d'une entrée ou un tableau de noms.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Extrait toutes les entrées

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->extractTo('/mon/dossier/destination/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

Exemple #2 Extrait deux entrées

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_im.zip');
    if ($res === TRUE) {
        $zip->extractTo('/mon/dossier/destination/', array('pear_item.gif', 'testfromfile.php'));
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

### Notes

> Note: Les systèmes de fichiers NTFS Windows ne supportent pas certain caractères dans le noms de fichier, à savoir `<|>*?":`. Les noms de fichiers avec un point trainant ne sont également pas supporté. Contrairement à certains outils d'extraction, cette méthode ne remplace pas ces caractères avec un tiret bas, mais échoue à extraire de tel fichiers.

# ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveComment — Retourne le commentaire de l'archive ZIP

### Description

public function ZipArchive::getArchiveComment(int `$flags` = 0): string|false

Retourne le commentaire de l'archive ZIP.

### Liste de paramètres

`flags`
  Si ce paramètre est défini à `ZipArchive::FL_UNCHANGED`, le commentaire original non modifié sera retourné.

### Valeurs de retour

Retourne le commentaire de l'archive ZIP ou `false` si une erreur survient.

### Exemples

Exemple #1 Extrait le commentaire de l'archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_avec_commentaire.zip');
    if ($res === TRUE) {
        var_dump($zip->getArchiveComment());
        /* Ou en utilisant la propriété de l'archive */
        var_dump($zip->comment);
    } else {
        echo 'échec, code:' . $res;
    }
    ?>

# ZipArchive::getArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::getArchiveFlag — Retourne la valeur d'un drapeau global de l'archive

### Description

public function ZipArchive::getArchiveFlag(int `$flag`, int `$flags` = 0): int

Retourne la valeur d'un drapeau global de l'archive.

### Liste de paramètres

`flag`

  Le drapeau global à récupérer, parmi les constantes `AFL_*`:

  - `ZipArchive::AFL_RDONLY`
  - `ZipArchive::AFL_IS_TORRENTZIP`
  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`flags`
  Si `flags` est défini comme `ZipArchive::FL_UNCHANGED`, le drapeau original est inchangé et retourné.

### Valeurs de retour

Retourne 1 si le drapeau est défini pour l'archive, 0 si non, et -1 si une erreur s'est produite.

### Exemples

Exemple #1 Teste si l'archive est au format torrentzip

    <?php

    $zip = new ZipArchive;
    $res = $zip->open('test.zip');

    if ($res === TRUE) {
        var_dump($zip->getArchiveFlag(ZipArchive::AFL_IS_TORRENTZIP));
    } else {
        echo 'Failed, code: ' . $res;
    }
    ?>

### Voir aussi

- ZipArchive::setArchiveFlag() - Définit un drapeau global d'une archive ZIP

# ZipArchive::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndex — Retourne le commentaire d'une entrée

### Description

public function ZipArchive::getCommentIndex(int `$index`, int `$flags` = 0): string|false

Retourne le commentaire d'une entrée en utilisant l'index de l'entrée.

### Liste de paramètres

`index`
  Index de l'entrée
`flags`
  Si ce flag est défini à `ZipArchive::FL_UNCHANGED`, le commentaire original est retourné.

### Valeurs de retour

Retourne le commentaire en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Affiche le commentaire d'une entrée

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentIndex(1));
    } else {
        echo 'échec, code:' . $res;
    }
    ?>

# ZipArchive::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentName — Retourne le commentaire d'une entrée en utilisant le nom de l'entrée

### Description

public function ZipArchive::getCommentName(string `$name`, int `$flags` = 0): string|false

Retourne le commentaire d'une entrée en utilisant le nom de l'entrée.

### Liste de paramètres

`name`
  Nom de l'entrée
`flags`
  Si ce flag est défini à `ZipArchive::FL_UNCHANGED`, le commentaire original est retourné.

### Valeurs de retour

Retourne le commentaire en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Affiche le commentaire d'une entrée

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentName('test/entry1.txt'));
    } else {
        echo 'échec, code:' . $res;
    }
    ?>

# ZipArchive::getExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesIndex — Récupère les attributs externes d'une entrée définie par son index

### Description

public function ZipArchive::getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Récupère les attributs externes d'une entrée définie par son index.

### Liste de paramètres

`index`
  Index de l'entrée.
`opsys`
  En cas de succès, récupère le code du système d'exploitation défini par une des constantes ZipArchive::OPSYS_.
`attr`
  En cas de succès, récupère les attributs externes, la valeur dépend du système d'exploitation.
`flags`
  Si ce drapeau est positionné à `ZipArchive::FL_UNCHANGED`, les attributs originaux inchangés sont retournés.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Cet exemple extrait toutes les entrées de l'archive ZIP test.zip et définit les droits Unix à partir des attributs externes.

Exemple #1 Extrait toutes les entrées avec leurs droits Unix

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip') === TRUE) {
        for ($idx=0 ; $s = $zip->statIndex($idx) ; $idx++) {
            if ($zip->extractTo('.', $s['name'])) {
                if ($zip->getExternalAttributesIndex($idx, $opsys, $attr)
                    && $opsys==ZipArchive::OPSYS_UNIX) {
                   chmod($s['name'], ($attr >> 16) & 0777);
                }
            }
        }
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

# ZipArchive::getExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesName — Récupère les attributs externes d'une entrée définie par son nom

### Description

public function ZipArchive::getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Récupère les attributs externes d'une entrée définie par son nom.

### Liste de paramètres

`name`
  Nom de l'entrée.
`opsys`
  En cas de succès, récupère le code du système d'exploitation défini par une des constantes ZipArchive::OPSYS_.
`attr`
  En cas de succès, récupère les attributs externes, la valeur dépend du système d'exploitation.
`flags`
  Si ce drapeau est positionné à `ZipArchive::FL_UNCHANGED`, les attributs originaux inchangés sont retournés.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndex — Retourne le contenu d'une entrée en utilisant son index

### Description

public function ZipArchive::getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false

Retourne le contenu d'une entrée en utilisant son index.

### Liste de paramètres

`index`
  Index de l'entrée
`len`
  La longueur à lire depuis l'entrée. Si vaut `0`, alors toute l'entrée sera lue.
`flags`

  Les flags à utiliser pour ouvrir l'archive.

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`

### Valeurs de retour

Retourne le contenu de l'entrée en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Récupère le contenu du fichier

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        echo $zip->getFromIndex(2);
        $zip->close();
    } else {
        echo 'échec';
    }
    ?>

### Voir aussi

- ZipArchive::getFromName() - Retourne le contenu de l'entrée en utilisant son nom

# ZipArchive::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromName — Retourne le contenu de l'entrée en utilisant son nom

### Description

public function ZipArchive::getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false

Retourne le contenu de l'entrée en utilisant son nom.

### Liste de paramètres

`name`
  Nom de l'entrée
`len`
  La longueur à lire depuis l'entrée. Si vaut `0`, alors toute l'entrée sera lue.
`flags`

  Le flag à utiliser pour trouver l'entrée. Les constantes suivantes peuvent être utilisées.

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`
  - `ZipArchive::FL_NOCASE`

### Valeurs de retour

Retourne le contenu de l'entrée en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Récupère le contenu d'un fichier

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        echo $zip->getFromName('testfromfile.php');
        $zip->close();
    } else {
        echo 'échec';
    }
    ?>

Exemple #2 Convertit une image depuis une entrée ZIP

    <?php
    $z = new ZipArchive();
    if ($z->open(dirname(__FILE__) . '/test_im.zip')) {
        $im_string = $z->getFromName("pear_item.gif");
        $im = imagecreatefromstring($im_string);
        imagepng($im, 'b.png');
    }
    ?>

### Voir aussi

- ZipArchive::getFromIndex() - Retourne le contenu d'une entrée en utilisant son index

# ZipArchive::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndex — Retourne le nom d'une entrée en utilisant son index

### Description

public function ZipArchive::getNameIndex(int `$index`, int `$flags` = 0): string|false

Retourne le nom d'une entrée en utilisant son index.

### Liste de paramètres

`index`
  Index de l'entrée
`flags`
  Si ce paramètre est défini à `ZipArchive::FL_UNCHANGED`, le nom original non modifié sera retourné.

### Valeurs de retour

Retourne le nom en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ZipArchive::getNameIndex()

    <?php
    if ($zip->open('test.zip') == TRUE) {
     for ($i = 0; $i < $zip->numFiles; $i++) {
         $filename = $zip->getNameIndex($i);
         // ...
     }
    }
    ?>

# ZipArchive::getStatusString

(PHP 5 >= 5.2.7, PHP 7, PHP 8)

ZipArchive::getStatusString — Retourne le message du statut de l'erreur, du système ou de zip

### Description

public function ZipArchive::getStatusString(): string

Retourne le message du statut de l'erreur, du système ou de zip.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères contenant le message du statut.

### Historique

Version | Description
--- | ---
8.0.0, PECL zip 1.18.0 | Cette méthode ne retourne plus `false` en cas d'échec.
8.0.0, PECL zip 1.18.0 | Cette méthode peut être appelée sur une archive fermée.

# ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStream — Récupère un gestionnaire de fichier pour l'entrée définie par son nom (lecture seule)

### Description

public function ZipArchive::getStream(string `$name`): resource|false

Récupère un gestionnaire de fichier pour l'entrée définie par son nom. Actuellement, cette fonction ne supporte que les opérations de lecture.

### Liste de paramètres

`name`
  Le nom de l'entrée à utiliser

### Valeurs de retour

Retourne un pointeur de fichier (ressource) en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Récupère le contenu de l'entrée ZIP

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStream('test');
        if(!$fp) exit("échec\n");

        while (!feof($fp)) {
            $contents .= fread($fp, 2);
        }

        fclose($fp);
        file_put_contents('t',$contents);
        echo "fait.\n";
    }
    ?>

Exemple #2 Récupère une entrée Zip avec la fonction fopen() et le gestionnaire de flux ZIP

    <?php
    $contents = '';
    $fp = fopen('zip://' . dirname(__FILE__) . '/test.zip#test', 'r');
    if (!$fp) {
        exit("impossible d'ouvrir\n");
    }
    while (!feof($fp)) {
        $contents .= fread($fp, 2);
    }
    echo "$contents\n";
    fclose($fp);
    echo "fait.\n";
    ?>

Exemple #3 Gestionnaire de flux et image, peut être utilisé également avec les fonctions XML

    <?php
    $im = imagecreatefromgif('zip://' . dirname(__FILE__) . '/test_im.zip#pear_item.gif');
    imagepng($im, 'a.png');
    ?>

### Voir aussi

- ZipArchive::getStreamIndex() - Récupère un gestionnaire de fichier pour l'entrée définie par son index (lecture seule)
- ZipArchive::getStreamName() - Récupère un gestionnaire de fichier pour l'entrée définie par son nom (lecture seule)
- Flux de compression

# ZipArchive::getStreamIndex

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamIndex — Récupère un gestionnaire de fichier pour l'entrée définie par son index (lecture seule)

### Description

public function ZipArchive::getStreamIndex(int `$index`, int `$flags` = 0): resource|false

Récupère un gestionnaire de fichier pour l'entrée définie par son index. Actuellement, cette fonction ne supporte que les opérations de lecture.

### Liste de paramètres

`index`
  L'index de l'entrée à utiliser.
`flags`
  Si flags est défini sur `ZipArchive::FL_UNCHANGED`, le flux original est renvoyé.

### Valeurs de retour

Retourne un pointeur de fichier (ressource) en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Obtenir le contenu de l'entrée avec fread() et le stocker

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamIndex(1, ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Voir aussi

- ZipArchive::getStreamName() - Récupère un gestionnaire de fichier pour l'entrée définie par son nom (lecture seule)

# ZipArchive::getStreamName

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamName — Récupère un gestionnaire de fichier pour l'entrée définie par son nom (lecture seule)

### Description

public function ZipArchive::getStreamName(string `$name`, int `$flags` = 0): resource|false

Récupère un gestionnaire de fichier pour l'entrée définie par son nom. Actuellement, cette fonction ne supporte que les opérations de lecture.

### Liste de paramètres

`name`
  Le nom de l'entrée à utiliser.
`flags`
  Si flags est défini sur `ZipArchive::FL_UNCHANGED`, le flux original est renvoyé.

### Valeurs de retour

Retourne un pointeur de fichier (ressource) en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Obtenir le contenu de l'entrée avec fread() et le stocker

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamName('test', ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Voir aussi

- ZipArchive::getStreamIndex() - Récupère un gestionnaire de fichier pour l'entrée définie par son index (lecture seule)

# ZipArchive::isCompressionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isCompressionMethodSupported — Vérifie si une méthode de compression est supportée par libzip

### Description

public static function ZipArchive::isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Vérifie si une méthode de compression est supportée par libzip.

### Liste de paramètres

`method`
  La méthode de compression, une des constantes `ZipArchive::CM_*`.
`enc`
  Si `true`, vérifie la compression, sinon, vérifie la décompression.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Notes

> Note: Cette fonction est uniquement disponible si la compilation a été réalisée avec libzip ≥ 1.7.0.

### Voir aussi

- ZipArchive::setCompressionIndex() - Définit la méthode de compression d'une entrée définie par son index
- ZipArchive::setCompressionName() - Définit la méthode de compression d'une entrée définie par son nom

# ZipArchive::isEncryptionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isEncryptionMethodSupported — Vérifie si une méthode de chiffrement est supportée par libzip

### Description

public static function ZipArchive::isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Vérifie si une méthode de chiffrement est supportée par libzip.

### Liste de paramètres

`method`
  La méthode de chiffrement, une des constantes `ZipArchive::EM_*`.
`enc`
  Si `true`, vérifie le chiffrement, sinon, vérifie le déchiffrement.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Notes

> Note: Cette fonction est uniquement disponible si l'extension a été compilée avec libzip ≥ 1.7.0.

### Voir aussi

- ZipArchive::setEncryptionIndex() - Définit la méthode de chiffrement d'une entrée définie par son index
- ZipArchive::setEncryptionName() - Définit la méthode de chiffrement d'une entrée définie par son nom

# ZipArchive::locateName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::locateName — Retourne l'index d'une entrée de l'archive

### Description

public function ZipArchive::locateName(string `$name`, int `$flags` = 0): int|false

Localise une entrée en utilisant son nom.

### Liste de paramètres

`name`
  Le nom de l'entrée à chercher
`flags`

  La fonction retourne l'index du fichier dans l'archive. Le flag est spécifié par les valeurs suivantes ou par 0 pour aucun d'entre eux.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`

### Valeurs de retour

Retourne l'index de l'entrée en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Crée une archive et l'utilise avec ZipArchive::locateName()

    <?php
    $file = 'testlocate.zip';

    $zip = new ZipArchive;
    if ($zip->open($file, ZipArchive::CREATE) !== TRUE) {
        exit('failed');
    }

    $zip->addFromString('entry1.txt', 'entry #1');
    $zip->addFromString('entry2.txt', 'entry #2');
    $zip->addFromString('dir/entry2d.txt', 'entry #2');

    if ($zip->status !== ZipArchive::ER_OK) {
        echo "failed to write zip\n";
    }
    $zip->close();

    if ($zip->open($file) !== TRUE) {
        exit('failed');
    }

    echo $zip->locateName('entry1.txt') . "\n";
    echo $zip->locateName('eNtry2.txt') . "\n";
    echo $zip->locateName('eNtry2.txt', ZipArchive::FL_NOCASE) . "\n";
    echo $zip->locateName('enTRy2d.txt', ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) . "\n";
    $zip->close();

    ?>

L'exemple ci-dessus va afficher :

    0

    1
    2

# ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::open — Ouvre une archive ZIP

### Description

public function ZipArchive::open(string `$filename`, int `$flags` = 0): bool|int

Ouvre une archive ZIP nouvelle ou pré-existante pour lecture, écriture et modification.

À partir de libzip 1.6.0, un fichier vide n'est plus une archive valide.

### Liste de paramètres

`filename`
  Le nom du fichier ZIP à ouvrir.
`flags`

  Le mode à utiliser pour ouvrir l'archive.

  - `ZipArchive::OVERWRITE`
  - `ZipArchive::CREATE`
  - `ZipArchive::RDONLY`
  - `ZipArchive::EXCL`
  - `ZipArchive::CHECKCONS`

### Valeurs de retour

Retourne `true` en cas de succès, `false` ou un des codes d'erreur suivants :

`ZipArchive::ER_EXISTS`
  Le fichier existe déjà.
`ZipArchive::ER_INCONS`
  L'archive ZIP est incohérente.
`ZipArchive::ER_INVAL`
  Argument invalide.
`ZipArchive::ER_MEMORY`
  Échec de malloc.
`ZipArchive::ER_NOENT`
  Le fichier n'existe pas.
`ZipArchive::ER_NOZIP`
  N'est pas une archive ZIP.
`ZipArchive::ER_OPEN`
  Impossible d'ouvrir le fichier.
`ZipArchive::ER_READ`
  Erreur lors de la lecture.
`ZipArchive::ER_SEEK`
  Erreur de position.

### Exemples

Exemple #1 Ouverture et extraction

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        echo 'ok';
        $zip->extractTo('test');
        $zip->close();
    } else {
        echo 'échec, code:' . $res;
    }
    ?>

Exemple #2 Création d'une archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->addFile('data.txt', 'nom_de_l_entree.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

Exemple #3 Créer une archive temporaire

    <?php
    $name = tempnam(sys_get_temp_dir(), "FOO");
    $zip = new ZipArchive;
    $res = $zip->open($name, ZipArchive::OVERWRITE); /* truncate as empty file is not valid */
    if ($res === TRUE) {
        $zip->addFile('data.txt', 'entryname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallback — Enregistre une fonction de rappel permettant d'annuler pendant la clôture d'une archive

### Description

public function ZipArchive::registerCancelCallback(callable `$callback`): bool

Enregistre une fonction de rappel `callback` permettant l'annulation pendant la clôture d'une archive.

### Liste de paramètres

`callback`
  Si la fonction retourne 0, l'opération continue, sinon, elle sera annulée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Cet exemple crée un fichier ZIP php.zip et annule l'opération sous certaines conditions.

Exemple #1 Archivage d'un fichier

    <?php
    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerCancelCallback(function () {
            return ($someruncondition ? -1 : 0);
        });
        $zip->close();
    }

### Notes

> Note: Cette fonction est uniquement disponible si l'extension a été compilée avec libzip ≥ 1.6.0.

### Voir aussi

- ZipArchive::registerProgressCallback() - Enregistre une fonction de rappel pour permettre des mises à jour pendant la fermeture de l'archive

# ZipArchive::registerProgressCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerProgressCallback — Enregistre une fonction de rappel pour permettre des mises à jour pendant la fermeture de l'archive

### Description

public function ZipArchive::registerProgressCallback(float `$rate`, callable `$callback`): bool

Enregistre une fonction de rappel `callback` pour permettre des mises à jour pendant la fermeture de l'archive.

### Liste de paramètres

`rate`
  Modification entre chaque appel de la fonction de rappel (de 0.0 à 1.0).
`callback`
  Cette fonction va recevoir le statut `state` courant sous la forme d'un float (de 0.0 à 1.0).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Cet exemple crée un fichier archive ZIP php.zip et affiche la progression.

Exemple #1 Archive un fichier

    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerProgressCallback(0.05, function ($r) {
            printf("%d%%\n", $r * 100);
        });
        $zip->close();
    }

### Notes

> Note: Cette fonction n'est disponible que si compilé avec libzip ≥ 1.3.0.

### Voir aussi

- ZipArchive::registerCancelCallback() - Enregistre une fonction de rappel permettant d'annuler pendant la clôture d'une archive

# ZipArchive::renameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameIndex — Renomme une entrée définie par son index

### Description

public function ZipArchive::renameIndex(int `$index`, string `$new_name`): bool

Renomme une entrée définie par son index.

### Liste de paramètres

`index`
  Index de l'entrée à renommer
`new_name`
  Nouveau nom

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Renommer une entrée

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameIndex(2,'newname.txt');
        $zip->close();
    } else {
        echo 'échec, code:' . $res;
    }
    ?>

# ZipArchive::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameName — Renomme une entrée définie par son nom

### Description

public function ZipArchive::renameName(string `$name`, string `$new_name`): bool

Renomme une entrée définie par son nom.

### Liste de paramètres

`name`
  Nom de l'entrée à renommer
`new_name`
  Nouveau nom

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Renommer une entrée

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameName('currentname.txt','newname.txt');
        $zip->close();
    } else {
        echo 'échec, code:' . $res;
    }
    ?>

# ZipArchive::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFile — Remplace un fichier d'une archive ZIP

### Description

public function ZipArchive::replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool

Remplace un fichier d'une archive ZIP avec un fichier donné.

> Note: Pour une portabilité maximale, il est recommandé de toujours utiliser des barres obliques (`/`) comme séparateur de dossier dans les noms de fichiers zip.

### Liste de paramètres

`filepath`
  Le chemin vers le fichier à ajouter.
`index`
  L'index du fichier à remplacer ; son nom restera inchangé.
`start`
  Pour une copie partielle, la position de départ.
`length`
  Pour copie partielle, longueur à copier, Si `ZipArchive::LENGTH_TO_END` (0) est spécifié, la taille du fichier est utilisée. Si `ZipArchive::LENGTH_UNCHECKED` est spécifié, la totalité du fichier est utilisée (à partir de `start`).
`flags`
  Un masque composé d'une des constantes suivantes : `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. Le comportement de ces constantes est décrit sur la page des constantes ZIP.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` a été ajouté.
8.3.0, PECL zip 1.22.2 | `ZipArchive::LENGTH_TO_END` et `ZipArchive::LENGTH_UNCHECKED` ont été ajoutés.

### Exemples

Cet exemple ouvre un fichier archive ZIP test.zip et remplace l'index 1 par /path/to/index.txt.

Exemple #1 Ouvre et remplace

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->replaceFile('/path/to/index.txt', 1);
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

### Voir aussi

- ZipArchive::addFile() - Ajoute un fichier à l'archive ZIP depuis le chemin fourni

# ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveComment — Définit le commentaire d'une archive ZIP

### Description

public function ZipArchive::setArchiveComment(string `$comment`): bool

Définit le commentaire d'une archive ZIP.

### Liste de paramètres

`comment`
  Le contenu du commentaire

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Création d'une archive et définition d'un commentaire

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'contenu du fichier ici');
        $zip->setArchiveComment('commentaire de l\'archive');
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

# ZipArchive::setArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::setArchiveFlag — Définit un drapeau global d'une archive ZIP

### Description

public function ZipArchive::setArchiveFlag(int `$flag`, int `$value`): bool

Définit un drapeau global d'une archive ZIP.

### Liste de paramètres

`flag`

  Le drapeau global à changer, parmi les constantes `AFL_*`.

  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`value`
  La nouvelle valeur du drapeau.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Créer une archive torrentzip

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->setArchiveFlag(ZipArchive::AFL_WANT_TORRENTZIP, 1);
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

### Voir aussi

- ZipArchive::getArchiveFlag() - Retourne la valeur d'un drapeau global de l'archive

# ZipArchive::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndex — Définit le commentaire d'une entrée définie par son index

### Description

public function ZipArchive::setCommentIndex(int `$index`, string `$comment`): bool

Définit le commentaire d'une entrée définie par son index.

### Liste de paramètres

`index`
  Index de l'entrée
`comment`
  Le contenu du commentaire

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Ouvre une archive et définit un commentaire pour une entrée

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentIndex(2, 'commentaire de l\'entrée');
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

# ZipArchive::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentName — Définit le commentaire d'une entrée spécifiée par son nom

### Description

public function ZipArchive::setCommentName(string `$name`, string `$comment`): bool

Définit le commentaire pour une entrée définie par son nom.

### Liste de paramètres

`name`
  Nom de l'entrée.
`comment`
  Le contenu du commentaire.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Ouvre une archive et définit le commentaire pour une entrée

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentName('entry1.txt', 'commentaire de l\'entrée');
        $zip->close();
        echo 'ok';
    } else {
        echo 'échec';
    }
    ?>

# ZipArchive::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndex — Définit la méthode de compression d'une entrée définie par son index

### Description

public function ZipArchive::setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool

Définit la méthode de compression d'une entrée définie par son index.

### Liste de paramètres

`index`
  Index de l'entrée.
`method`
  La méthode de compression, une des constantes `ZipArchive::CM_*`.
`compflags`
  Niveau de compression.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Ajoute des fichiers avec différentes méthodes de compression dans une archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('foo', 'Some text');
        $zip->addFromString('bar', 'Some other text');
        $zip->setCompressionIndex(0, ZipArchive::CM_STORE);
        $zip->setCompressionIndex(1, ZipArchive::CM_DEFLATE);
        $zip->close();
        echo 'ok';
    } else {
        echo 'échoué';
    }
    ?>

# ZipArchive::setCompressionName

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionName — Définit la méthode de compression d'une entrée définie par son nom

### Description

public function ZipArchive::setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool

Définit la méthode de compression d'une entrée définie par son nom.

### Liste de paramètres

`name`
  Nom de l'entrée.
`method`
  La méthode de compression, une des constantes `ZipArchive::CM_*`.
`compflags`
  Niveau de compression.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Ajoute des fichiers avec différentes méthodes de compression dans une archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('foo', 'Some text');
        $zip->addFromString('bar', 'Some other text');
        $zip->setCompressionName('foo', ZipArchive::CM_STORE);
        $zip->setCompressionName('bar', ZipArchive::CM_DEFLATE);
        $zip->close();
        echo 'ok';
    } else {
        echo 'échoué';
    }
    ?>

Exemple #2 Ajouter un fichier et définir la méthode de compression

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFile('foo.jpg', 'bar.jpg');
        $zip->setCompressionName('bar.jpg', ZipArchive::CM_XZ);
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::setEncryptionIndex

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionIndex — Définit la méthode de chiffrement d'une entrée définie par son index

### Description

public function ZipArchive::setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Définit la méthode de chiffrement d'une entrée définie par son index.

### Liste de paramètres

`index`
  Index de l'entrée.
`method`
  La méthode de chiffrement définie par l'une des constantes ZipArchive::EM_.
`password`
  Mot de passe optionnel, valeur par défaut utilisée si absent.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `password` est désormais nullable.

### Notes

> Note: Cette fonction est seulement disponible quand compilé contre libzip ≥ 1.2.0.

### Voir aussi

- ZipArchive::setPassword() - Définit le mot de passe de l'archive active
- ZipArchive::setEncryptionName() - Définit la méthode de chiffrement d'une entrée définie par son nom

# ZipArchive::setEncryptionName

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionName — Définit la méthode de chiffrement d'une entrée définie par son nom

### Description

public function ZipArchive::setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Définit la méthode de chiffrement d'une entrée définie par son nom.

### Liste de paramètres

`name`
  Nom de l'entrée.
`method`
  La méthode de chiffrement définie par l'une des constantes ZipArchive::EM_.
`password`
  Mot de passe optionnel, valeur par défaut utilisée si absent.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `password` est désormais nullable.

### Exemples

Cet exemple crée un fichier d'archive ZIP test.zip et ajoute le fichier test.txt chiffré grâce à la méthode AES 256.

Exemple #1 Archiver et chiffrer un fichier

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->setPassword('secret');
        $zip->addFile('text.txt');
        $zip->setEncryptionName('text.txt', ZipArchive::EM_AES_256);
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Notes

> Note: Cette fonction est seulement disponible quand compilé contre libzip ≥ 1.2.0.

### Voir aussi

- ZipArchive::setPassword() - Définit le mot de passe de l'archive active
- ZipArchive::setEncryptionIndex() - Définit la méthode de chiffrement d'une entrée définie par son index

# ZipArchive::setExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesIndex — Définit les attributs externes d'une entrée définie par son index

### Description

public function ZipArchive::setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Définit les attributs externes d'une entrée définie par son index.

### Liste de paramètres

`index`
  Index de l'entrée.
`opsys`
  Code du système d'exploitation, défini par une des constantes ZipArchive::OPSYS_.
`attr`
  Attributs externes, la valeur dépend du système d'exploitation.
`flags`
  Drapeaux optionnels. Actuellement inutilisé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ZipArchive::setExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesName — Définit les attributs externes d'une entrée définie par son nom

### Description

public function ZipArchive::setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Définit les attributs externes d'une entrée définie par son nom.

### Liste de paramètres

`name`
  Nom de l'entrée.
`opsys`
  Code du système d'exploitation, défini par une des constantes ZipArchive::OPSYS_.
`attr`
  Attributs externes, la valeur dépend du système d'exploitation.
`flags`
  Drapeaux optionnels. Actuellement inutilisé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Cet exemple crée une archive ZIP test.zip et ajoute le fichier test.txt ainsi que ses permissions Unix dans les attributs externes.

Exemple #1 Archiver un fichier avec ses droits Unix

    <?php
    $zip = new ZipArchive();
    $stat = stat($filename='test.txt');
    if (is_array($stat) && $zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile($filename);
        $zip->setExternalAttributesName($filename, ZipArchive::OPSYS_UNIX, $stat['mode'] << 16);
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

# ZipArchive::setMtimeIndex

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeIndex — Définit la date de modification d'une entrée

### Description

public function ZipArchive::setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool

Définit la date de modification d'une entrée définie par son index.

### Liste de paramètres

`index`
  Index de l'entrée.
`timestamp`
  La date de modification (unix timestamp) du fichier.
`flags`
  Drapeaux optionnels, non utilisés pour le moment.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Cet exemple crée un fichier archive ZIP test.zip et ajoute le fichier test.txt avec les modifications quant à la date de modification.

Exemple #1 Archive un fichier

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeIndex(0, mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Notes

> Note: Cette fonction n'est disponible que si l'extension a été compilée avec libzip ≥ 1.0.0.

### Voir aussi

- ZipArchive::setMtimeName() - Définit la date de modification d'une entrée par son nom

# ZipArchive::setMtimeName

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeName — Définit la date de modification d'une entrée par son nom

### Description

public function ZipArchive::setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool

Définit la date de modification d'une entrée par son nom.

### Liste de paramètres

`name`
  Nom de l'entrée.
`timestamp`
  La date de modification (unix timestamp) du fichier.
`flags`
  Drapeaux optionnels, non utilisés pour le moment.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Cet exemple crée un fichier archive ZIP test.zip et ajoute le fichier test.txt avec les modifications faites sur la date de modification.

Exemple #1 Archive un fichier

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeName('text.txt', mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Notes

> Note: Cette fonction n'est disponible que si l'extension a été compilée avec libzip ≥ 1.0.0.

### Voir aussi

- ZipArchive::setMtimeIndex() - Définit la date de modification d'une entrée

# ZipArchive::setPassword

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setPassword — Définit le mot de passe de l'archive active

### Description

public function ZipArchive::setPassword(#[\SensitiveParameter]string `$password`): bool

Définit le mot de passe de l'archive active.

### Liste de paramètres

`password`
  Le mot de passe à utiliser sur l'archive.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Notes

> Note: À partir de PHP 7.2.0 et libzip 1.2.0, le mot de passe est utilisé pour décompresser l'archive, et est également le mot de passe par défaut pour ZipArchive::setEncryptionName() et ZipArchive::setEncryptionIndex(). Antérieurement, cette fonction ne définissait que le mot de passe à utiliser pour décompresser l'archive ; elle ne permettait pas de transformer une ZipArchive non protégée par mot de passe en une ZipArchive protégée par un mot de passe.

### Voir aussi

- ZipArchive::setEncryptionIndex() - Définit la méthode de chiffrement d'une entrée définie par son index
- ZipArchive::setEncryptionName() - Définit la méthode de chiffrement d'une entrée définie par son nom

# ZipArchive::statIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::statIndex — Récupère les détails d'une entrée définie par son index

### Description

public function ZipArchive::statIndex(int `$index`, int `$flags` = 0): array|false

Cette fonction obtient des informations d'une entrée définie par son index.

### Liste de paramètres

`index`
  Index de l'entrée
`flags`
  `ZipArchive::FL_UNCHANGED` permet d'obtenir les informations du fichier original de l'archive, ignorant toutes les modifications effectuées

### Valeurs de retour

Retourne un tableau contenant les détails de l'entrée ou `false` si une erreur survient.

### Exemples

Exemple #1 Récupère les informations d'une entrée

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statIndex(3));
        $zip->close();
    } else {
        echo 'échec, code:' . $res;
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::statName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::statName — Récupère les détails de l'entrée définie par son nom

### Description

public function ZipArchive::statName(string `$name`, int `$flags` = 0): array|false

Cette fonction obtient des informations sur l'entrée définie par son nom.

### Liste de paramètres

`name`
  Nom de l'entrée
`flags`

  Le flag spécifie comment la recherche sur le nom doit s'effectuer. `ZipArchive::FL_UNCHANGED` doit être utilisé pour récupérer les informations sur le fichier original de l'archive, ignorant toutes les modifications effectuées.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`
  - `ZipArchive::FL_UNCHANGED`

### Valeurs de retour

Retourne un tableau contenant les détails de l'entrée, ou `false` si une erreur survient.

### Exemples

Exemple #1 Récupère les informations d'une entrée

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statName('foobar/baz'));
        $zip->close();
    } else {
        echo 'échec, code:' . $res;
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::unchangeAll

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeAll — Annule toutes les modifications faites sur l'archive

### Description

public function ZipArchive::unchangeAll(): bool

Annule toutes les modifications faites sur l'archive.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchive — Annule toutes les modifications globales faites sur l'archive

### Description

public function ZipArchive::unchangeArchive(): bool

Annule toutes les modifications faites sur l'archive. Actuellement, ceci annule uniquement les modifications effectuées sur les commentaires.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndex — Annule toutes les modifications faites sur une entrée, définie par nom index

### Description

public function ZipArchive::unchangeIndex(int `$index`): bool

Annule toutes les modifications faites sur une entrée, définie par son index.

### Liste de paramètres

`index`
  Index de l'entrée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeName — Annule toutes les modifications faites sur une entrée, définie par son nom

### Description

public function ZipArchive::unchangeName(string `$name`): bool

Annule toutes les modifications faites sur une entrée, définie par son nom.

### Liste de paramètres

`name`
  Nom de l'entrée

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

## Sommaire

- ZipArchive::addEmptyDir — Ajoute un nouveau dossier à une archive Zip
- ZipArchive::addFile — Ajoute un fichier à l'archive ZIP depuis le chemin fourni
- ZipArchive::addFromString — Ajoute un fichier à une archive ZIP en utilisant son contenu
- ZipArchive::addGlob — Ajoute des fichiers d'un dossier en utilisant un masque glob
- ZipArchive::addPattern — Ajoute des fichiers d'un dossier en utilisant une expression régulière PCRE
- ZipArchive::clearError — Efface le message d'erreur, les messages système et/ou zip
- ZipArchive::close — Ferme l'archive active
- ZipArchive::count — Compte le nombre de fichiers dans l'archive
- ZipArchive::deleteIndex — Efface une entrée de l'archive en utilisant son index
- ZipArchive::deleteName — Efface une entrée dans l'archive en utilisant son nom
- ZipArchive::extractTo — Extrait le contenu de l'archive
- ZipArchive::getArchiveComment — Retourne le commentaire de l'archive ZIP
- ZipArchive::getArchiveFlag — Retourne la valeur d'un drapeau global de l'archive
- ZipArchive::getCommentIndex — Retourne le commentaire d'une entrée
- ZipArchive::getCommentName — Retourne le commentaire d'une entrée en utilisant le nom de l'entrée
- ZipArchive::getExternalAttributesIndex — Récupère les attributs externes d'une entrée définie par son index
- ZipArchive::getExternalAttributesName — Récupère les attributs externes d'une entrée définie par son nom
- ZipArchive::getFromIndex — Retourne le contenu d'une entrée en utilisant son index
- ZipArchive::getFromName — Retourne le contenu de l'entrée en utilisant son nom
- ZipArchive::getNameIndex — Retourne le nom d'une entrée en utilisant son index
- ZipArchive::getStatusString — Retourne le message du statut de l'erreur, du système ou de zip
- ZipArchive::getStream — Récupère un gestionnaire de fichier pour l'entrée définie par son nom (lecture seule)
- ZipArchive::getStreamIndex — Récupère un gestionnaire de fichier pour l'entrée définie par son index (lecture seule)
- ZipArchive::getStreamName — Récupère un gestionnaire de fichier pour l'entrée définie par son nom (lecture seule)
- ZipArchive::isCompressionMethodSupported — Vérifie si une méthode de compression est supportée par libzip
- ZipArchive::isEncryptionMethodSupported — Vérifie si une méthode de chiffrement est supportée par libzip
- ZipArchive::locateName — Retourne l'index d'une entrée de l'archive
- ZipArchive::open — Ouvre une archive ZIP
- ZipArchive::registerCancelCallback — Enregistre une fonction de rappel permettant d'annuler pendant la clôture d'une archive
- ZipArchive::registerProgressCallback — Enregistre une fonction de rappel pour permettre des mises à jour pendant la fermeture de l'archive
- ZipArchive::renameIndex — Renomme une entrée définie par son index
- ZipArchive::renameName — Renomme une entrée définie par son nom
- ZipArchive::replaceFile — Remplace un fichier d'une archive ZIP
- ZipArchive::setArchiveComment — Définit le commentaire d'une archive ZIP
- ZipArchive::setArchiveFlag — Définit un drapeau global d'une archive ZIP
- ZipArchive::setCommentIndex — Définit le commentaire d'une entrée définie par son index
- ZipArchive::setCommentName — Définit le commentaire d'une entrée spécifiée par son nom
- ZipArchive::setCompressionIndex — Définit la méthode de compression d'une entrée définie par son index
- ZipArchive::setCompressionName — Définit la méthode de compression d'une entrée définie par son nom
- ZipArchive::setEncryptionIndex — Définit la méthode de chiffrement d'une entrée définie par son index
- ZipArchive::setEncryptionName — Définit la méthode de chiffrement d'une entrée définie par son nom
- ZipArchive::setExternalAttributesIndex — Définit les attributs externes d'une entrée définie par son index
- ZipArchive::setExternalAttributesName — Définit les attributs externes d'une entrée définie par son nom
- ZipArchive::setMtimeIndex — Définit la date de modification d'une entrée
- ZipArchive::setMtimeName — Définit la date de modification d'une entrée par son nom
- ZipArchive::setPassword — Définit le mot de passe de l'archive active
- ZipArchive::statIndex — Récupère les détails d'une entrée définie par son index
- ZipArchive::statName — Récupère les détails de l'entrée définie par son nom
- ZipArchive::unchangeAll — Annule toutes les modifications faites sur l'archive
- ZipArchive::unchangeArchive — Annule toutes les modifications globales faites sur l'archive
- ZipArchive::unchangeIndex — Annule toutes les modifications faites sur une entrée, définie par nom index
- ZipArchive::unchangeName — Annule toutes les modifications faites sur une entrée, définie par son nom

# Fonctions Zip

Avertissement

L'API procédurale est obsolète à partir de PHP 8.0.0. ZipArchive devrait être utilisé à la place.

# zip_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_close — Ferme une archive Zip

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_close(resource `$zip`): void

zip_close() ferme l'archive ZIP donnée.

### Liste de paramètres

`zip`
  Un fichier ZIP précédemment ouvert avec la fonction zip_open().

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet, voir ZipArchive::close().

### Voir aussi

- zip_open() - Ouvre une archive ZIP
- zip_read() - Lit la prochaine entrée dans une archive ZIP

# zip_entry_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_close — Ferme un dossier d'archive

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_entry_close(resource `$zip_entry`): bool

zip_entry_close() ferme un dossier d'archive donné.

### Liste de paramètres

`zip_entry`
  Un dossier d'archive précédemment ouvert avec la fonction zip_entry_open().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet.

### Voir aussi

- zip_entry_open() - Ouvre un dossier d'archives en lecture
- zip_entry_read() - Lit le contenu d'un fichier dans un dossier

# zip_entry_compressedsize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressedsize — Lit la taille compressée d'un dossier d'archives

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_entry_compressedsize(resource `$zip_entry`): int|false

zip_entry_compressedsize() retourne la taille compressée d'un dossier d'archives donné.

### Liste de paramètres

`zip_entry`
  Un dossier d'archives retourné par la fonction zip_read().

### Valeurs de retour

La taille compressée, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet, voir ZipArchive::statIndex().

### Voir aussi

- zip_open() - Ouvre une archive ZIP
- zip_read() - Lit la prochaine entrée dans une archive ZIP

# zip_entry_compressionmethod

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressionmethod — Lit la méthode de compression utilisée sur un dossier d'archives

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_entry_compressionmethod(resource `$zip_entry`): string|false

zip_entry_compressionmethod() retourne la méthode de compression utilisée sur le dossier d'archives spécifié par `zip_entry`.

### Liste de paramètres

`zip_entry`
  Un dossier d'archives retourné par la fonction zip_read().

### Valeurs de retour

La méthode de compression, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet, voir ZipArchive::statIndex().

### Voir aussi

- zip_open() - Ouvre une archive ZIP
- zip_read() - Lit la prochaine entrée dans une archive ZIP

# zip_entry_filesize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_filesize — Lit la taille décompressée d'un dossier d'archives

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_entry_filesize(resource `$zip_entry`): int|false

zip_entry_filesize() retourne la taille décompressée d'un dossier d'archives donné.

### Liste de paramètres

`zip_entry`
  Un dossier d'archives retourné par la fonction zip_read().

### Valeurs de retour

La taille décompressée du dossier d'archives, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet, voir ZipArchive::statIndex().

### Voir aussi

- zip_open() - Ouvre une archive ZIP
- zip_read() - Lit la prochaine entrée dans une archive ZIP

# zip_entry_name

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_name — Lit le nom d'un dossier d'archives

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_entry_name(resource `$zip_entry`): string|false

zip_entry_name() retourne le nom d'un dossier d'archives donné.

### Liste de paramètres

`zip_entry`
  Un dossier d'archives retourné par la fonction zip_read().

### Valeurs de retour

Le nom du dossier d'archives, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet, voir ZipArchive::statIndex().

### Voir aussi

- zip_open() - Ouvre une archive ZIP
- zip_read() - Lit la prochaine entrée dans une archive ZIP

# zip_entry_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_open — Ouvre un dossier d'archives en lecture

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_entry_open(resource `$zip_dp`, resource `$zip_entry`, string `$mode` = "rb"): bool

zip_entry_open() ouvre un dossier dans un fichier ZIP pour lecture.

### Liste de paramètres

`zip_dp`
  Une ressource valide retournée par la fonction zip_open().
`zip_entry`
  Un dossier d'archives retourné par la fonction zip_read().
`mode`
  L'un des modes spécifiés dans la documentation de la fonction fopen().

  > Note: Actuellement, `mode` est ignoré et vaut toujours `"rb"`. Cela est dû au fait que le support ZIP de PHP est uniquement en lecture seule.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

> Note: Contrairement à fopen() et les autres fonctions de fichiers, la valeur retournée par zip_entry_open() indique uniquement le résultat de l'opération, et n'est pas nécessaire pour la lecture ou la fermeture du fichier de dossier d'archives.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet.

### Voir aussi

- zip_entry_close() - Ferme un dossier d'archive
- zip_entry_read() - Lit le contenu d'un fichier dans un dossier

# zip_entry_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_read — Lit le contenu d'un fichier dans un dossier

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_entry_read(resource `$zip_entry`, int `$len` = 1024): string|false

zip_entry_read() lit dans un dossier d'archives ouvert.

### Liste de paramètres

`zip_entry`
  Un dossier d'archives retourné par la fonction zip_read().
`len`
  Le nombre d'octets à retourner.

  > Note: Ceci devrait être la taille non-compressée qu'on souhaite lire.

### Valeurs de retour

Retourne les données lues, une chaîne vide si l'on est à la fin du fichier, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet, voir ZipArchive::getFromIndex().

### Voir aussi

- zip_entry_open() - Ouvre un dossier d'archives en lecture
- zip_entry_close() - Ferme un dossier d'archive
- zip_entry_filesize() - Lit la taille décompressée d'un dossier d'archives

# zip_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_open — Ouvre une archive ZIP

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_open(string `$filename`): resource|int|false

zip_open() ouvre une nouvelle archive ZIP pour lecture.

### Liste de paramètres

`filename`
  Le nom du fichier de l'archive ZIP à ouvrir.

### Valeurs de retour

Retourne une ressource à utiliser plus tard avec les fonctions zip_read() et zip_close(), ou bien retourne soit `false`, soit le numéro de l'erreur si le paramètre `filename` n'existe pas ou dans le cas d'une autre erreur.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet, voir ZipArchive::open().

### Voir aussi

- zip_read() - Lit la prochaine entrée dans une archive ZIP
- zip_close() - Ferme une archive Zip

# zip_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_read — Lit la prochaine entrée dans une archive ZIP

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function zip_read(resource `$zip`): resource|false

zip_read() lit la prochaine entrée dans une archive ZIP.

### Liste de paramètres

`zip`
  Un fichier ZIP précédemment ouvert avec la fonction zip_open().

### Valeurs de retour

Retourne une ressource de dossier d'archive, à utiliser plus tard avec les autres fonctions de la bibliothèque, `false` s'il n'y a plus d'entrées à lire dans l'archive ZIP ou le numéro de l'erreur si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est obsolète en faveur de l'API orientée objet, voir ZipArchive::statIndex().

### Voir aussi

- zip_open() - Ouvre une archive ZIP
- zip_close() - Ferme une archive Zip
- zip_entry_open() - Ouvre un dossier d'archives en lecture
- zip_entry_read() - Lit le contenu d'un fichier dans un dossier

## Sommaire

- zip_close — Ferme une archive Zip
- zip_entry_close — Ferme un dossier d'archive
- zip_entry_compressedsize — Lit la taille compressée d'un dossier d'archives
- zip_entry_compressionmethod — Lit la méthode de compression utilisée sur un dossier d'archives
- zip_entry_filesize — Lit la taille décompressée d'un dossier d'archives
- zip_entry_name — Lit le nom d'un dossier d'archives
- zip_entry_open — Ouvre un dossier d'archives en lecture
- zip_entry_read — Lit le contenu d'un fichier dans un dossier
- zip_open — Ouvre une archive ZIP
- zip_read — Lit la prochaine entrée dans une archive ZIP

- Installation/Configuration
  - Pré-requis
  - Installation
  - Types de ressources
- Constantes pré-définies
- Exemples
- ZipArchive — La classe ZipArchive
  - ZipArchive::addEmptyDir — Ajoute un nouveau dossier à une archive Zip
  - ZipArchive::addFile — Ajoute un fichier à l'archive ZIP depuis le chemin fourni
  - ZipArchive::addFromString — Ajoute un fichier à une archive ZIP en utilisant son contenu
  - ZipArchive::addGlob — Ajoute des fichiers d'un dossier en utilisant un masque glob
  - ZipArchive::addPattern — Ajoute des fichiers d'un dossier en utilisant une expression régulière PCRE
  - ZipArchive::clearError — Efface le message d'erreur, les messages système et/ou zip
  - ZipArchive::close — Ferme l'archive active
  - ZipArchive::count — Compte le nombre de fichiers dans l'archive
  - ZipArchive::deleteIndex — Efface une entrée de l'archive en utilisant son index
  - ZipArchive::deleteName — Efface une entrée dans l'archive en utilisant son nom
  - ZipArchive::extractTo — Extrait le contenu de l'archive
  - ZipArchive::getArchiveComment — Retourne le commentaire de l'archive ZIP
  - ZipArchive::getArchiveFlag — Retourne la valeur d'un drapeau global de l'archive
  - ZipArchive::getCommentIndex — Retourne le commentaire d'une entrée
  - ZipArchive::getCommentName — Retourne le commentaire d'une entrée en utilisant le nom de l'entrée
  - ZipArchive::getExternalAttributesIndex — Récupère les attributs externes d'une entrée définie par son index
  - ZipArchive::getExternalAttributesName — Récupère les attributs externes d'une entrée définie par son nom
  - ZipArchive::getFromIndex — Retourne le contenu d'une entrée en utilisant son index
  - ZipArchive::getFromName — Retourne le contenu de l'entrée en utilisant son nom
  - ZipArchive::getNameIndex — Retourne le nom d'une entrée en utilisant son index
  - ZipArchive::getStatusString — Retourne le message du statut de l'erreur, du système ou de zip
  - ZipArchive::getStream — Récupère un gestionnaire de fichier pour l'entrée définie par son nom (lecture seule)
  - ZipArchive::getStreamIndex — Récupère un gestionnaire de fichier pour l'entrée définie par son index (lecture seule)
  - ZipArchive::getStreamName — Récupère un gestionnaire de fichier pour l'entrée définie par son nom (lecture seule)
  - ZipArchive::isCompressionMethodSupported — Vérifie si une méthode de compression est supportée par libzip
  - ZipArchive::isEncryptionMethodSupported — Vérifie si une méthode de chiffrement est supportée par libzip
  - ZipArchive::locateName — Retourne l'index d'une entrée de l'archive
  - ZipArchive::open — Ouvre une archive ZIP
  - ZipArchive::registerCancelCallback — Enregistre une fonction de rappel permettant d'annuler pendant la clôture d'une archive
  - ZipArchive::registerProgressCallback — Enregistre une fonction de rappel pour permettre des mises à jour pendant la fermeture de l'archive
  - ZipArchive::renameIndex — Renomme une entrée définie par son index
  - ZipArchive::renameName — Renomme une entrée définie par son nom
  - ZipArchive::replaceFile — Remplace un fichier d'une archive ZIP
  - ZipArchive::setArchiveComment — Définit le commentaire d'une archive ZIP
  - ZipArchive::setArchiveFlag — Définit un drapeau global d'une archive ZIP
  - ZipArchive::setCommentIndex — Définit le commentaire d'une entrée définie par son index
  - ZipArchive::setCommentName — Définit le commentaire d'une entrée spécifiée par son nom
  - ZipArchive::setCompressionIndex — Définit la méthode de compression d'une entrée définie par son index
  - ZipArchive::setCompressionName — Définit la méthode de compression d'une entrée définie par son nom
  - ZipArchive::setEncryptionIndex — Définit la méthode de chiffrement d'une entrée définie par son index
  - ZipArchive::setEncryptionName — Définit la méthode de chiffrement d'une entrée définie par son nom
  - ZipArchive::setExternalAttributesIndex — Définit les attributs externes d'une entrée définie par son index
  - ZipArchive::setExternalAttributesName — Définit les attributs externes d'une entrée définie par son nom
  - ZipArchive::setMtimeIndex — Définit la date de modification d'une entrée
  - ZipArchive::setMtimeName — Définit la date de modification d'une entrée par son nom
  - ZipArchive::setPassword — Définit le mot de passe de l'archive active
  - ZipArchive::statIndex — Récupère les détails d'une entrée définie par son index
  - ZipArchive::statName — Récupère les détails de l'entrée définie par son nom
  - ZipArchive::unchangeAll — Annule toutes les modifications faites sur l'archive
  - ZipArchive::unchangeArchive — Annule toutes les modifications globales faites sur l'archive
  - ZipArchive::unchangeIndex — Annule toutes les modifications faites sur une entrée, définie par nom index
  - ZipArchive::unchangeName — Annule toutes les modifications faites sur une entrée, définie par son nom
- Fonctions Zip
  - zip_close — Ferme une archive Zip
  - zip_entry_close — Ferme un dossier d'archive
  - zip_entry_compressedsize — Lit la taille compressée d'un dossier d'archives
  - zip_entry_compressionmethod — Lit la méthode de compression utilisée sur un dossier d'archives
  - zip_entry_filesize — Lit la taille décompressée d'un dossier d'archives
  - zip_entry_name — Lit le nom d'un dossier d'archives
  - zip_entry_open — Ouvre un dossier d'archives en lecture
  - zip_entry_read — Lit le contenu d'un fichier dans un dossier
  - zip_open — Ouvre une archive ZIP
  - zip_read — Lit la prochaine entrée dans une archive ZIP

# Compression Zlib

# Introduction

Ce module permet de lire et d'écrire des fichiers compressés gzip (.gz), via la plupart des fonctions du système de fichiers qui fonctionnent avec les fichiers compressés gzip (ainsi qu'avec les fichiers non-compressés, mais sans sockets).

> Note:

> PHP inclut un gestionnaire de format pour les fichiers .gz. Plus d'informations sont disponibles dans la section zlib://.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Ce module utilise les fonctions » zlib créées par Jean-loup Gailly et Mark Adler. À partir de PHP 8.4.0, la version minimale de zlib requise est 1.2.11. Antérieur à PHP 8.4.0, la version minimale de zlib requise était 1.2.0.4.

## Installation

Le support de Zlib dans PHP n'est pas activé par défaut. Il faut compiler PHP avec l'option --with-zlib[=DIR].

La version Windows de PHP dispose du support automatique de cette extension. Vous n'avez pas à ajouter de bibliothèque supplémentaire pour disposer de ces fonctions.

## Configuration à l'exécution

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

L'extension zlib offre l'option de compresser de manière transparente les pages PHP à la volée, si le navigateur du visiteur le supporte. Voici donc les trois options à utiliser dans le fichier de configuration php.ini.

Options de configuration Zlib
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
zlib.output_compression | "0" | `INI_ALL` |
zlib.output_compression_level | "-1" | `INI_ALL` |
zlib.output_handler | "" | `INI_ALL` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`zlib.output_compression` bool/int

  Active ou pas la compression transparente des pages. Si cette option est mise à "On" dans php.ini ou dans la configuration Apache, les pages sont compressées si le navigateur envoie un en-tête "Accept-Encoding: gzip" ou "deflate". Les en-têtes "Content-Encoding: gzip" (respectivement "deflate") et "Vary: Accept-Encoding" sont ajoutés dans la page envoyée au navigateur. En fonctionnement, il peut être défini uniquement avant tout affichage.

  Cette option accepte aussi des valeurs entières au lieu des booléens, "On"/"Off", ce qui permet de configurer la taille du tampon de sortie (par défaut, il vaut 4 Ko).

  > Note:

  > output_handler doit être laissée à vide si cette option est activée. Sinon, il faut utiliser `zlib.output_handler`.

`zlib.output_compression_level` int

  Niveau de compression utilisé pour la compression de sortie. La valeur doit être comprise entre 0 (aucune compression) et 9 (compression élevée). La valeur par défaut est -1, ce qui laissera le serveur décider du niveau de compression à utiliser.

`zlib.output_handler` string

  Il n'est pas possible de spécifier de gestionnaire de sortie supplémentaire si zlib.output_compression est activée. Cette configuration est la même que output_handler mais dans un ordre différent.

## Types de ressources

Cette extension définit une ressource de fichier, retournée par la fonction gzopen(). Antérieur à PHP 8.0.0, les ressources `zlib.deflate` et `zlib.inflate` étaient aussi définies.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`FORCE_GZIP` (int)
`FORCE_DEFLATE` (int)
`ZLIB_ENCODING_RAW` (int)
  Algorithme DEFLATE tel que décrit dans la RFC 1951.
`ZLIB_ENCODING_DEFLATE` (int)
  Algorithme de compression ZLIB tel que décrit dans la RFC 1950.
`ZLIB_ENCODING_GZIP` (int)
  Algorithme GZIP tel que décrit par la RFC 1952.
`ZLIB_FILTERED` (int)
`ZLIB_HUFFMAN_ONLY` (int)
`ZLIB_FIXED` (int)
`ZLIB_RLE` (int)
`ZLIB_DEFAULT_STRATEGY` (int)
`ZLIB_BLOCK` (int)
`ZLIB_NO_FLUSH` (int)
`ZLIB_PARTIAL_FLUSH` (int)
`ZLIB_SYNC_FLUSH` (int)
`ZLIB_FULL_FLUSH` (int)
`ZLIB_FINISH` (int)
`ZLIB_VERSION` (string)
  Numéro de version de `zlib` en tant que string.
`ZLIB_VERNUM` (int)
  Numéro de version de `zlib` en tant que int.
`ZLIB_OK` (int)
  Pas d'erreurs ou d'informations supplémentaires.
`ZLIB_STREAM_END` (int)
  Le flux s'est terminé avec succès.
`ZLIB_NEED_DICT` (int)
  Un dictionnaire prédéfini est nécessaire.
`ZLIB_ERRNO` (int)
  Erreur d'opération de fichier.
`ZLIB_STREAM_ERROR` (int)
  L'état du flux est incohérent ou un paramètre est invalide.
`ZLIB_DATA_ERROR` (int)
  Les données d'entrée sont corrompues.
`ZLIB_MEM_ERROR` (int)
  Mémoire insuffisante.
`ZLIB_BUF_ERROR` (int)
  Aucun progrès n'est possible en raison d'un espace tampon insuffisant ou d'une fin inattendue d'un flux d'entrée.
`ZLIB_VERSION_ERROR` (int)
  La version de la bibliothèque `zlib` est incompatible avec la version supposée par l'appelant.

# Exemples

Cet exemple ouvre un fichier temporaire et y écrit une chaîne de test, puis, affiche le contenu de ce fichier, deux fois.

Exemple #1 Exemple avec Zlib

    <?php

    $filename = tempnam('/tmp', 'zlibtest') . '.gz';
    echo "<html>\n<head></head>\n<body>\n<pre>\n";
    $s = "Seulement un test, test, test, test, test, test, test, test!\n";

    // Ouvre un fichier en écriture, avec une compression maximale
    $zp = gzopen($filename, "w9");

    // Écrit une chaîne dans le fichier
    gzwrite($zp, $s);

    // Ferme le fichier
    gzclose($zp);

    // Ouvre un fichier en lecture
    $zp = gzopen($filename, "r");

    // Lit 3 caractères
    echo gzread($zp, 3);

    // Lit tout le contenu et ferme le fichier
    gzpassthru($zp);
    gzclose($zp);

    echo "\n";

    // Ouvre un fichier et affiche le contenu (pour la deuxième fois).
    if (readgzfile($filename) != strlen($s)) {
            echo "Erreur avec les fonctions zlib !";
    }
    unlink($filename);
    echo "</pre>\n</body>\n</html>\n";

    ?>

Exemple #2 Fonctionnement avec l'API de compression et de décompression incrémentale

    <?php
    // Compression GZIP :
    $deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
    $compressed = deflate_add($deflateContext, "Data to compress", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", more data", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", and even more data!", ZLIB_FINISH);

    // Décompression GZIP :
    $inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
    $uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
    $uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
    echo $uncompressed;
    ?>

L'exemple ci-dessus va afficher :

    Data to compress, more data, and even more data!

# Fonctions Zlib

# deflate_add

(PHP 7, PHP 8)

deflate_add — Compresse des données de manière incrémentielle

### Description

function deflate_add(DeflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Compresse de manière incrémentielle des données dans le contexte spécifié.

### Liste de paramètres

`context`

  Un contexte créé avec deflate_init().

`data`

  Un morceau de données à compresser.

`flush_mode`

  Une des `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (par défaut), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Normalement, on voudra définir `ZLIB_NO_FLUSH` pour maximiser la compression, et `ZLIB_FINISH` pour terminer avec le dernier morceau de données. Consulter le » manuel de zlib pour une description détaillée de ces constantes.

### Valeurs de retour

Renvoie un morceau de données compressées, ou `false` si une erreur survient.

### Erreurs / Exceptions

Si un argument invalide est donné, une erreur de niveau `E_WARNING` est générée.

### Historique

Version | Description
--- | ---
8.0.0 | `context` attend désormais une instance de DeflateContext ; avant, une resource était attendue.

### Voir aussi

- deflate_init() - Initialise un contexte de compressage incrémentiel

# deflate_init

(PHP 7, PHP 8)

deflate_init — Initialise un contexte de compressage incrémentiel

### Description

function deflate_init(int `$encoding`, array|object `$options` = []): DeflateContext|false

Initialise un contexte de compressage incrémentiel en utilisant le `encoding` spécifié.

Il est à noter que l'option `window` ne définit ici que la taille de la fenêtre de l'algorithme, différemment des filtres zlib où le même paramètre définit également l'encodage à utiliser ; l'encodage doit être défini avec le paramètre `encoding`.

Limitation : il n'y a actuellement aucun moyen de définir les informations d'en-tête sur un flux compressé GZIP, qui sont définies comme suit : signature GZIP (`\x1f\x8B`) ; méthode de compression (`\x08` == DEFLATE) ; 6 octets nuls ; le système d'exploitation défini sur le système actuel (`\x00` = Windows, `\x03` = Unix, etc.).

### Liste de paramètres

`encoding`

  Une des constantes `ZLIB_ENCODING_*`.

`options`

  Un tableau associatif qui peut contenir les éléments suivants :

  level

    Le niveau de compression dans la plage -1..9 ; par défaut -1.

  memory

    Le niveau de mémoire de compression dans la plage 1..9 ; par défaut 8.

  window

    La taille de la fenêtre zlib (logarithmique) dans la plage `8`..`15`; par défaut `15`. zlib change une taille de fenêtre de `8` à `9`, et à partir de zlib 1.2.8 échoue avec un avertissement, si une taille de fenêtre de `8` est demandée pour `ZLIB_ENCODING_RAW` ou `ZLIB_ENCODING_GZIP`.

  strategy

    Une des `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` ou `ZLIB_DEFAULT_STRATEGY` (par défaut).

  dictionary

    Un string ou un array de strings du dictionnaire prédéfini (par défaut : aucun dictionnaire prédéfini).

### Valeurs de retour

Renvoie un contexte de compressage (`zlib.deflate`) en cas de succès, ou `false` si une erreur survient.

### Erreurs / Exceptions

Si une option invalide est passée à `options` ou que le contexte n'a pas pu être créé, une erreur de niveau `E_WARNING` est générée.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction renvoie désormais une instance de DeflateContext ; précédemment, une resource était renvoyée.

### Voir aussi

- deflate_add() - Compresse des données de manière incrémentielle
- inflate_init() - Initialise un contexte de décompressage incrémentiel

# gzclose

(PHP 4, PHP 5, PHP 7, PHP 8)

gzclose — Ferme un pointeur sur un fichier gz ouvert

### Description

function gzclose(resource `$stream`): bool

gzclose() referme le fichier compressé `stream`.

### Liste de paramètres

`stream`

  Le pointeur de fichier compressé. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec gzclose()

    <?php
    $gz = gzopen('somefile.gz','w9');
    gzputs ($gz, 'Je suis ajouté à somefile.gz');
    gzclose($gz);
    ?>

### Voir aussi

- gzopen() - Ouvre un fichier compressé avec gzip

# gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompress — Compresse une chaîne

### Description

function gzcompress(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_DEFLATE`): string|false

gzcompress() compresse la chaîne donnée en utilisant le format de données `ZLIB`.

Pour plus de détails sur l'algorithme, consulter le document "» ZLIB Compressed Data Format Specification version 3.3" (RFC 1950).

> Note:

> Ce n'est pas la même chose que la compression gzip, qui inclut quelques en-têtes de données. Voir gzencode() pour la compression gzip.

### Liste de paramètres

`data`

  La donnée à compresser.

`level`

  Le degré de compression. 0 signifie aucune compression, jusqu'à 9 pour une compression maximale.

  Si ce paramètre vaut -1, la compression par défaut de la bibliothèque zlib sera utilisée, soit 6.

`encoding`

  Une constante `ZLIB_ENCODING_*`.

### Valeurs de retour

La chaîne compressée ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec gzcompress()

    <?php
    $compressed = gzcompress('Compresse moi', 9);
    echo $compressed;
    ?>

### Voir aussi

- gzdeflate() - Compresse une chaîne
- gzinflate() - Décompresse une chaîne
- gzuncompress() - Décompresse une chaîne compressée
- gzencode() - Crée une chaîne compressée gzip

# gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecode — Décode une chaîne de caractères compressée gzip

### Description

function gzdecode(string `$data`, int `$max_length` = 0): string|false

Cette fonction retourne une version décodée des données `data`.

### Liste de paramètres

`data`

  Les données à décoder, encodées par la fonction gzencode().

`max_length`

  La longueur maximale de données à décoder.

### Valeurs de retour

La chaîne de caractères décodée, ou `false` si une erreur survient.

### Erreurs / Exceptions

En cas d'échec, une erreur de niveau `E_WARNING` est émise.

### Voir aussi

- gzencode() - Crée une chaîne compressée gzip

# gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflate — Compresse une chaîne

### Description

function gzdeflate(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_RAW`): string|false

gzdeflate() compresse la chaîne donnée en utilisant le format de données `DEFLATE`.

Pour plus de détails sur l'algorithme de compression DEFLATE, consulter le document "» DEFLATE Compressed Data Format Specification version 1.3" (RFC 1951).

### Liste de paramètres

`data`

  Les données à compresser.

`level`

  Le degré de compression. 0 signifie aucune compression jusqu'à 9 pour une compression maximale. Si omis, le degré de compression par défaut sera celui de la bibliothèque zlib.

`encoding`

  Une constante `ZLIB_ENCODING_*`.

### Valeurs de retour

La chaîne compressée ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec gzdeflate()

    <?php
    $compressed = gzdeflate('Compresse moi', 9);
    echo $compressed;
    ?>

### Voir aussi

- gzinflate() - Décompresse une chaîne
- gzcompress() - Compresse une chaîne
- gzuncompress() - Décompresse une chaîne compressée
- gzencode() - Crée une chaîne compressée gzip

# gzencode

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzencode — Crée une chaîne compressée gzip

### Description

function gzencode(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_GZIP`): string|false

gzencode() retourne la version compressée de la chaîne `data` compatible avec la sortie du programme gzip.

Pour plus de détails sur l'algorithme, consulter le document "» GZIP file format specification version 4.3" (RFC 1952).

### Liste de paramètres

`data`

  Les données à encoder.

`level`

  Le degré de compression. 0 signifie aucune compression, jusqu'à 9 pour une compression maximale. Si omis, le degré de compression par défaut sera celui de la bibliothèque zlib.

`encoding`

  Le mode d'encodage. Peut être `FORCE_GZIP` (par défaut) ou `FORCE_DEFLATE`.

  `FORCE_DEFLATE` génère un affichage conforme à la RFC 1950, contenant un en-tête zlib, les données standard, et une somme de vérification Adler.

### Valeurs de retour

La chaîne encodée ou `false` si une erreur survient.

### Exemples

Les données résultantes contiennent les en-têtes appropriés ainsi que la structure de données pour faire un fichier .gz standard, e.g. :

Exemple #1 Création d'un fichier gzip

    <?php
    $data = file_get_contents("bigfile.txt");
    $gzdata = gzencode($data, 9);
    file_put_contents("bigfile.txt.gz", $gzdata);
    ?>

### Voir aussi

- gzdecode() - Décode une chaîne de caractères compressée gzip
- gzdeflate() - Compresse une chaîne
- gzinflate() - Décompresse une chaîne
- gzuncompress() - Décompresse une chaîne compressée
- gzcompress() - Compresse une chaîne
- » Spécification du format de données compressées ZLIB (RFC 1950)

# gzeof

(PHP 4, PHP 5, PHP 7, PHP 8)

gzeof — Indique si la fin d'un fichier (EOF) compressé est atteinte

### Description

function gzeof(resource `$stream`): bool

Indique si la fin d'un fichier compressé est atteinte, c'est-à-dire si le pointeur est à la position EOF.

### Liste de paramètres

`stream`

  Le pointeur de fichier gz. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

### Valeurs de retour

Retourne `true` si le pointeur de fichier gz est à la fin du fichier (EOF) ou si une erreur survient ; sinon, retourne `false`.

### Exemples

Exemple #1 Exemple avec gzeof()

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

# gzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

gzfile — Lit la totalité d'un fichier compressé

### Description

function gzfile(string `$filename`, bool `$use_include_path` = `false`): array|false

gzfile() est identique à la fonction readgzfile(), excepté qu'elle retourne le fichier dans un tableau.

### Liste de paramètres

`filename`

  Le nom du fichier.

`use_include_path`
  Si défini à `true`, les fichiers dans l'include_path seront également recherchés.

### Valeurs de retour

Un tableau contenant le fichier, une ligne par cellule ; les lignes vides sont incluses, et les nouvelles lignes sont toujours attachées, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | `use_include_path` est désormais de type bool. Précédemment, c'était un int.

### Exemples

Exemple #1 Exemple avec gzfile()

    <?php
    $lines = gzfile('somefile.gz');
    foreach ($lines as $line) {
        echo $line;
    }
    ?>

### Voir aussi

- readgzfile() - Lit tout le fichier compressé
- gzopen() - Ouvre un fichier compressé avec gzip

# gzgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetc — Lit un caractère dans un fichier compressé

### Description

function gzgetc(resource `$stream`): string|false

gzgetc() retourne une chaîne contenant un seul caractère (décompressé) lu depuis le pointeur de fichier gz.

### Liste de paramètres

`stream`

  Le pointeur de fichier gz. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

### Valeurs de retour

Le caractère décompressé ou `false` si le pointeur est à la fin du fichier, position EOF (contrairement à la fonction gzeof()).

### Exemples

Exemple #1 Exemple avec gzgetc()

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

### Voir aussi

- gzopen() - Ouvre un fichier compressé avec gzip
- gzgets() - Lit une ligne dans un fichier compressé

# gzgets

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgets — Lit une ligne dans un fichier compressé

### Description

function gzgets(resource `$stream`, ?int `$length` = `null`): string|false

gzgets() retourne une chaîne non compressée, de taille maximale `length` - 1 octets, lue dans le fichier représenté par `zp`. La lecture s'arrête lorsque `length` - 1 octets ont été lus, ou que la fonction a rencontré une nouvelle ligne ou la fin du fichier (le premier des trois qui survient).

### Liste de paramètres

`stream`

  Le pointeur de fichier gz. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

`length`

  La longueur de données à lire.

### Valeurs de retour

La chaîne décompressée ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `length` est désormais nullable ; auparavant, la valeur par défaut était `1024`.

### Exemples

Exemple #1 Exemple avec gzgets()

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgets($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Voir aussi

- gzopen() - Ouvre un fichier compressé avec gzip
- gzgetc() - Lit un caractère dans un fichier compressé
- gzwrite() - Écrit dans un fichier compressé gzip

# gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetss — Lit une ligne dans un fichier compressé, et supprime les balises HTML

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.3.0, et a été SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function gzgetss(resource `$zp`, int `$length`, string `$allowable_tags` = ?): string

gzgetss() est identique à la fonction gzgets(), excepté que gzgetss() tente de supprimer toutes les balises HTML et PHP du texte lu.

### Liste de paramètres

`zp`

  Le pointeur de fichier gz. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

`length`

  La longueur des données à récupérer.

`allowable_tags`

  Il est possible d'utiliser ce paramètre optionnel pour spécifier les balises à ne pas supprimer.

### Valeurs de retour

La chaîne décompressée et nettoyée ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec gzgetss()

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgetss($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Voir aussi

- gzopen() - Ouvre un fichier compressé avec gzip
- gzgets() - Lit une ligne dans un fichier compressé
- strip_tags() - Supprime les balises HTML et PHP d'une chaîne

# gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflate — Décompresse une chaîne

### Description

function gzinflate(string `$data`, int `$max_length` = 0): string|false

gzinflate() décompresse une chaîne.

### Liste de paramètres

`data`

  Les données compressées avec la fonction gzdeflate().

`max_length`

  La longueur maximale des données décodées.

### Valeurs de retour

Les données originales décompressées ou `false` si une erreur survient.

gzinflate() retourne une erreur si la chaîne décompressée est plus de 32768 fois plus longue que la chaîne compressée `data` ou, sauf si `max_length` est `0`, plus grande que la taille de `max_length` octets, passé comme paramètre optionnel.

### Exemples

Exemple #1 Exemple avec gzinflate()

    <?php
    $compressed   = gzdeflate('Compresse moi', 9);
    $uncompressed = gzinflate($compressed);
    echo $uncompressed;
    ?>

### Voir aussi

- gzdeflate() - Compresse une chaîne
- gzcompress() - Compresse une chaîne
- gzuncompress() - Décompresse une chaîne compressée
- gzencode() - Crée une chaîne compressée gzip

# gzopen

(PHP 4, PHP 5, PHP 7, PHP 8)

gzopen — Ouvre un fichier compressé avec gzip

### Description

function gzopen(string `$filename`, string `$mode`, bool `$use_include_path` = `false`): resource|false

gzopen() ouvre un fichier compressé avec gzip pour y écrire ou y lire des données.

gzopen() peut être utilisée pour lire un fichier qui n'est pas dans un format gzip ; dans ce cas, gzread() lira directement le fichier sans décompression.

### Liste de paramètres

`filename`

  Le nom du fichier.

`mode`

  Comme dans la fonction fopen() (`rb` ou `wb`) mais peut également inclure un degré de compression (`wb9`) ou une stratégie : `f` pour les données filtrées comme `wb6f`, `h` pour `Huffman only compression` comme `wb1h`. (Consulter la description de `deflateInit2` dans le fichier zlib.h pour plus d'informations sur la stratégie des paramètres.)

`use_include_path`
  Si défini à `true`, les fichiers dans l'include_path seront également recherchés.

### Valeurs de retour

Retourne un pointeur de fichier vers le fichier ouvert, ainsi, la lecture depuis ce pointeur de fichier sera des données décompressées et ce que l'on y écrira, sera compressé.

Si l'ouverture échoue, cette fonction retourne `false`.

### Historique

Version | Description
--- | ---
8.5.0 | `use_include_path` est désormais de type bool. Précédemment, c'était un int.

### Exemples

Exemple #1 Exemple avec gzopen()

    <?php
    $fp = gzopen("/tmp/file.gz", "r");
    ?>

### Voir aussi

- gzclose() - Ferme un pointeur sur un fichier gz ouvert

# gzpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

gzpassthru — Affiche toutes les données qui restent dans un pointeur gz

### Description

function gzpassthru(resource `$stream`): int

gzpassthru() lit les données restantes du fichier `stream` jusqu'à la fin (position EOF), puis affiche le résultat (décompressé).

> Note:

> Il serait possible d'avoir besoin d'appeler la fonction gzrewind() pour réinitialiser le pointeur de fichier au début du fichier si l'on a déjà écrit des données dedans.

Astuce

Pour uniquement afficher le contenu d'un fichier, sans le modifier auparavant ou sans déplacer le pointeur à une position particulière, il est recommandé d'utiliser la fonction readgzfile(), ce qui évitera d'appeler la fonction gzopen().

### Liste de paramètres

`stream`

  Le pointeur de fichier gz. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

### Valeurs de retour

Le nombre de caractères décompressés lus depuis `gz` et affichés.

### Exemples

Exemple #1 Exemple avec gzpassthru()

    <?php
    $fp = gzopen('file.gz', 'r');
    gzpassthru($fp);
    gzclose($fp);
    ?>

# gzputs

(PHP 4, PHP 5, PHP 7, PHP 8)

gzputs — Alias de gzwrite()

### Description

Cette fonction est un alias de : gzwrite().

# gzread

(PHP 4, PHP 5, PHP 7, PHP 8)

gzread — Lecture de fichier compressé binaire

### Description

function gzread(resource `$stream`, int `$length`): string|false

gzread() lit jusqu'à `length` octets dans le fichier compressé gzip, représenté par `stream`. La lecture s'arrête lorsque `length` octets (décompressés) ont été lus, ou que la fin du fichier a été atteinte (position EOF).

### Liste de paramètres

`stream`

  Le pointeur de fichier gz. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

`length`

  Le nombre d'octets à lire.

### Valeurs de retour

Les données qui ont été lues, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.4.0 | Cette fonction retourne désormais `false` en cas d'échec ; auparavant `0` était retourné.

### Exemples

Exemple #1 Exemple avec gzread()

    <?php
    // récupère le contenu d'un fichier gz dans une chaîne
    $filename = "/usr/local/something.txt.gz";
    $zd = gzopen($filename, "r");
    $contents = gzread($zd, 10000);
    gzclose($zd);
    ?>

### Voir aussi

- gzwrite() - Écrit dans un fichier compressé gzip
- gzopen() - Ouvre un fichier compressé avec gzip
- gzgets() - Lit une ligne dans un fichier compressé
- gzgetss() - Lit une ligne dans un fichier compressé, et supprime les balises HTML
- gzfile() - Lit la totalité d'un fichier compressé
- gzpassthru() - Affiche toutes les données qui restent dans un pointeur gz

# gzrewind

(PHP 4, PHP 5, PHP 7, PHP 8)

gzrewind — Replace le pointeur au début du fichier

### Description

function gzrewind(resource `$stream`): bool

gzrewind() replace le pointeur de position du fichier `stream` au début de celui-ci.

### Liste de paramètres

`stream`

  Le pointeur de fichier gz. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- gzseek() - Déplace le pointeur de lecture
- gztell() - Lit la position courante du pointeur de lecture

# gzseek

(PHP 4, PHP 5, PHP 7, PHP 8)

gzseek — Déplace le pointeur de lecture

### Description

function gzseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

gzseek() place le pointeur de lecture du fichier `zp` à la position `offset`, comptée en octets depuis le début du fichier. C'est l'équivalent de la fonction `gzseek(zp, offset, SEEK_SET)`, du langage C.

Si le fichier est ouvert en lecture, cette fonction est alors émulée, et se révèle extrêmement lente. Si le fichier est ouvert en écriture, seuls les déplacements vers l'avant sont supportés : gzseek() compresse alors une série de zéros jusqu'à la nouvelle position.

### Liste de paramètres

`stream`

  Le pointeur de fichier gz. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

`offset`

  La position désirée.

`whence`

  Les valeurs de `whence` sont :

  - `SEEK_SET` : ramène la position à l'`offset`.
  - `SEEK_CUR` : ramène la position à la position actuelle plus `offset`.

  Si `whence` n'est pas spécifié, il vaut par défaut `SEEK_SET`.

### Valeurs de retour

0 en cas de réussite, -1 sinon. Il est à noter que placer le pointeur au-delà de la fin du fichier n'est pas considéré comme une erreur.

### Exemples

Exemple #1 Exemple avec gzseek()

    <?php
    $gz = gzopen('somefile.gz', 'r');
    gzseek($gz,2);
    echo gzgetc($gz);
    gzclose($gz);
    ?>

### Voir aussi

- gztell() - Lit la position courante du pointeur de lecture
- gzrewind() - Replace le pointeur au début du fichier

# gztell

(PHP 4, PHP 5, PHP 7, PHP 8)

gztell — Lit la position courante du pointeur de lecture

### Description

function gztell(resource `$stream`): int|false

gztell() retourne la position du pointeur de fichier donné ; c'est-à-dire son décalage dans le flux de fichier non compressé.

### Liste de paramètres

`stream`

  Le pointeur de fichier. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

### Valeurs de retour

La position du pointeur de fichier ou `false` si une erreur survient.

### Voir aussi

- gzopen() - Ouvre un fichier compressé avec gzip
- gzseek() - Déplace le pointeur de lecture
- gzrewind() - Replace le pointeur au début du fichier

# gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompress — Décompresse une chaîne compressée

### Description

function gzuncompress(string `$data`, int `$max_length` = 0): string|false

gzuncompress() décompresse une chaîne compressée.

### Liste de paramètres

`data`

  Les données compressées par gzcompress().

`max_length`

  La longueur maximale de données à décoder.

### Valeurs de retour

Les données originales décompressées ou `false` si une erreur survient.

gzuncompress() retourne une erreur si la chaîne décompressée est plus de 32768 fois plus longue que la chaîne compressée `data` ou plus grande que la taille de `max_length` octets, passé comme paramètre optionnel.

### Exemples

Exemple #1 Exemple avec gzuncompress()

    <?php
    $compressed   = gzcompress('Compresse moi', 9);
    $uncompressed = gzuncompress($compressed);
    echo $uncompressed;
    ?>

### Voir aussi

- gzcompress() - Compresse une chaîne
- gzinflate() - Décompresse une chaîne
- gzdeflate() - Compresse une chaîne
- gzencode() - Crée une chaîne compressée gzip

# gzwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

gzwrite — Écrit dans un fichier compressé gzip

### Description

function gzwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

gzwrite() écrit le contenu de `data` dans le fichier gz donné.

### Liste de paramètres

`stream`

  Le pointeur de fichier. Il doit être valide et doit pointer vers un fichier ouvert avec succès grâce à la fonction gzopen().

`data`

  La chaîne à écrire.

`length`

  Le nombre d'octets décompressés à écrire. Si fournie, l'écriture s'arrêtera après `length` (décompressé) octets écrits ou si la fin de la chaîne `data` est atteinte ; celui qui survient le premier.

### Valeurs de retour

Retourne le nombre d'octets (décompressés) écrits dans le flux gz donné, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `length` est désormais nullable; auparavant la valeur par défaut était `0`.
7.4.0 | Cette fonction retourne désormais `false` en cas d'échec; auparavant `0` était retourné.

### Exemples

Exemple #1 Exemple avec gzwrite()

    <?php
    $string = 'Quelques informations à compresser';
    $gz = gzopen('somefile.gz','w9');
    gzwrite($gz, $string);
    gzclose($gz);
    ?>

### Voir aussi

- gzread() - Lecture de fichier compressé binaire
- gzopen() - Ouvre un fichier compressé avec gzip

# inflate_add

(PHP 7, PHP 8)

inflate_add — Décompresse des données de manière incrémentielle

### Description

function inflate_add(InflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Décompresse de manière incrémentielle des données dans le `context` spécifié.

Limitation : les informations d'en-tête d'un flux compressé GZIP ne sont pas disponibles.

### Liste de paramètres

`context`

  Un contexte créé avec inflate_init().

`data`

  Un morceau de données compressées.

`flush_mode`

  Une des `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (par défaut), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Normalement on voudra définir `ZLIB_NO_FLUSH` pour maximiser la compression, et `ZLIB_FINISH` pour terminer avec le dernier morceau de données. Consulter le » manuel de zlib pour une description détaillée de ces constantes.

### Valeurs de retour

Renvoie un morceau de données décompressées, ou `false` si une erreur survient.

### Erreurs / Exceptions

Si des paramètres invalides sont donnés, décompresser les données nécessite un dictionnaire prédéfini, mais aucun n'est spécifié, le flux compressé est corrompu ou a un checksum invalide, une erreur de niveau `E_WARNING` est générée.

### Historique

Version | Description
--- | ---
8.0.0 | `context` attend désormais une instance InflateContext ; auparavant, une resource était attendue.

### Voir aussi

- inflate_init() - Initialise un contexte de décompressage incrémentiel

# inflate_get_read_len

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_read_len — Renvoie le nombre d'octets lus jusqu'à présent

### Description

function inflate_get_read_len(InflateContext `$context`): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`context`

### Valeurs de retour

Renvoie le nombre d'octets lus jusqu'à présent ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `context` attend désormais une instance de InflateContext ; auparavant, une resource était attendue.

# inflate_get_status

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_status — Renvoie le statut de décompression

### Description

function inflate_get_status(InflateContext `$context`): int

Renvoie généralement `ZLIB_OK` ou `ZLIB_STREAM_END`.

### Liste de paramètres

`context`

### Valeurs de retour

Renvoie le statut de décompression.

### Historique

Version | Description
--- | ---
8.0.0 | `context` attend désormais une instance de InflateContext ; auparavant, une resource était attendue.

# inflate_init

(PHP 7, PHP 8)

inflate_init — Initialise un contexte de décompressage incrémentiel

### Description

function inflate_init(int `$encoding`, array|object `$options` = []): InflateContext|false

Initialise un contexte de décompressage incrémentiel avec l'`encoding` spécifié.

### Liste de paramètres

`encoding`

  Une des constantes `ZLIB_ENCODING_*`.

`options`

  Un tableau associatif qui peut contenir les éléments suivants :

  level

    Le niveau de compression dans la plage -1..9 ; par défaut -1.

  memory

    Le niveau de mémoire de compression dans la plage 1..9 ; par défaut 8.

  window

    La taille de la fenêtre de compression (logarithmique) dans la plage 8..15 ; par défaut 15.

  strategy

    Une des `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` ou `ZLIB_DEFAULT_STRATEGY` (par défaut).

  dictionary

    Un string ou un array de strings du dictionnaire prédéfini (par défaut : aucun dictionnaire prédéfini).

### Valeurs de retour

Renvoie un contexte de décompressage (`zlib.inflate`) en cas de succès, ou `false` si une erreur survient.

### Erreurs / Exceptions

Si un encodage ou une option invalide est passé à `options`, ou que le contexte n'a pas pu être créé, une erreur de niveau `E_WARNING` est générée.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction renvoie désormais une instance de InflateContext ; précédemment, un resource était renvoyé.

### Notes

Attention

Contrairement à gzinflate(), les contextes de gonflage incrémentiel ne limitent pas la longueur des données décodées, donc ne fournissent aucune protection automatique contre les bombes Zip.

### Voir aussi

- inflate_add() - Décompresse des données de manière incrémentielle
- deflate_init() - Initialise un contexte de compressage incrémentiel

# ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ob_gzhandler — Fonction de rappel pour la compression automatique des tampons

### Description

function ob_gzhandler(string `$data`, int `$flags`): string|false

ob_gzhandler() est destinée à être utilisée comme fonction de rappel par ob_start() pour faciliter l'envoi de données compressées aux navigateurs qui supportent les pages compressées. Avant que ob_gzhandler() envoie les données compressées, il détermine les types d'encodage qui sont supportés par le navigateur (`"gzip"`, `"deflate"` ou aucun) et retourne le contenu des tampons de manière appropriée. Tous les navigateurs sont traités, car c'est aux navigateurs d'envoyer un en-tête indiquant les types de pages supportés. Si le navigateur ne supporte pas les pages compressées, cette fonction retournera `false`.

### Liste de paramètres

`data`

`flags`

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec ob_gzhandler()

    <?php

    ob_start("ob_gzhandler");

    ?>
    <html>
    <body>
    <p>Ceci devrait être une page compressée.</p>
    </body>
    </html>

### Notes

> Note:

> ob_gzhandler() nécessite l'extension zlib.

> Note:

> Il n'est pas possible d'utiliser simultanément ob_gzhandler() et zlib.output_compression. De plus, il est à noter que zlib.output_compression est préférable à ob_gzhandler().

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie
- ob_end_flush() - Vide (envoie) la valeur de retour du gestionnaire de sortie actif et désactive le tampon de sortie actif

# readgzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readgzfile — Lit tout le fichier compressé

### Description

function readgzfile(string `$filename`, bool `$use_include_path` = `false`): int|false

readgzfile() lit le fichier `filename`, le décompresse et affiche le résultat.

readgzfile() peut aussi servir à lire un fichier qui n'est pas compressé : dans ce cas, readgzfile() va lire le fichier sans le décompresser.

### Liste de paramètres

`filename`

  Le nom du fichier. Ce fichier devra être ouvert depuis le système de fichiers et son contenu sera affiché.

`use_include_path`
  Lorsque défini à `true` le chemin include_path sera utilisé pour déterminer le fichier à ouvrir.

### Valeurs de retour

Retourne le nombre d'octets (décompressés) lus depuis le fichier en cas de succès, ou `false` si une erreur survient

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Historique

Version | Description
--- | ---
8.5.0 | `use_include_path` est désormais de type bool. Précédemment, c'était un int.

### Voir aussi

- gzpassthru() - Affiche toutes les données qui restent dans un pointeur gz
- gzfile() - Lit la totalité d'un fichier compressé
- gzopen() - Ouvre un fichier compressé avec gzip

# zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decode — Décompresse des données encodées raw/gzip/zlib

### Description

function zlib_decode(string `$data`, int `$max_length` = 0): string|false

Décompresse des données encodées raw/gzip/zlib.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`data`

`max_length`

### Valeurs de retour

Retourne les données décompressées, ou `false` si une erreur survient.

### Voir aussi

- zlib_encode() - Compresse des données avec l'encodage spécifié

# zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encode — Compresse des données avec l'encodage spécifié

### Description

function zlib_encode(string `$data`, int `$encoding`, int `$level` = -1): string|false

Compresse des données avec l'encodage spécifié.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`data`

  Les données à compresser.

`encoding`

  L'algorithme de compression. Soit `ZLIB_ENCODING_RAW`, `ZLIB_ENCODING_DEFLATE` ou `ZLIB_ENCODING_GZIP`.

`level`

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec zlib_encode()

    <?php
    $str = 'hello world';
    $enc = zlib_encode($str, ZLIB_ENCODING_DEFLATE);
    echo bin2hex($enc);
    ?>

L'exemple ci-dessus va afficher :

    789ccb48cdc9c95728cf2fca4901001a0b045d

### Voir aussi

- zlib_decode() - Décompresse des données encodées raw/gzip/zlib

# zlib_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_type — Retourne la méthode de compression utilisée pour la compression de sortie

### Description

function zlib_get_coding_type(): string|false

zlib_get_coding_type() retourne la méthode de compression utilisée avec Gzip.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Les valeurs possibles de retour sont `gzip`, `deflate` ou `false`.

### Voir aussi

- La directive zlib.output_compression

## Sommaire

- deflate_add — Compresse des données de manière incrémentielle
- deflate_init — Initialise un contexte de compressage incrémentiel
- gzclose — Ferme un pointeur sur un fichier gz ouvert
- gzcompress — Compresse une chaîne
- gzdecode — Décode une chaîne de caractères compressée gzip
- gzdeflate — Compresse une chaîne
- gzencode — Crée une chaîne compressée gzip
- gzeof — Indique si la fin d'un fichier (EOF) compressé est atteinte
- gzfile — Lit la totalité d'un fichier compressé
- gzgetc — Lit un caractère dans un fichier compressé
- gzgets — Lit une ligne dans un fichier compressé
- gzgetss — Lit une ligne dans un fichier compressé, et supprime les balises HTML
- gzinflate — Décompresse une chaîne
- gzopen — Ouvre un fichier compressé avec gzip
- gzpassthru — Affiche toutes les données qui restent dans un pointeur gz
- gzputs — Alias de gzwrite
- gzread — Lecture de fichier compressé binaire
- gzrewind — Replace le pointeur au début du fichier
- gzseek — Déplace le pointeur de lecture
- gztell — Lit la position courante du pointeur de lecture
- gzuncompress — Décompresse une chaîne compressée
- gzwrite — Écrit dans un fichier compressé gzip
- inflate_add — Décompresse des données de manière incrémentielle
- inflate_get_read_len — Renvoie le nombre d'octets lus jusqu'à présent
- inflate_get_status — Renvoie le statut de décompression
- inflate_init — Initialise un contexte de décompressage incrémentiel
- ob_gzhandler — Fonction de rappel pour la compression automatique des tampons
- readgzfile — Lit tout le fichier compressé
- zlib_decode — Décompresse des données encodées raw/gzip/zlib
- zlib_encode — Compresse des données avec l'encodage spécifié
- zlib_get_coding_type — Retourne la méthode de compression utilisée pour la compression de sortie

# La classe DeflateContext

(PHP 8)

## Introduction

Une classe entièrement opaque qui remplace les ressources `zlib.deflate` à partir de PHP 8.0.0.

## Synopsis de la classe

final class DeflateContext {
}

# La classe InflateContext

(PHP 8)

## Introduction

Une classe entièrement opaque qui remplace les ressources `zlib.inflate` à partir de PHP 8.0.0.

## Synopsis de la classe

final class InflateContext {
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Exemples
- Fonctions Zlib
  - deflate_add — Compresse des données de manière incrémentielle
  - deflate_init — Initialise un contexte de compressage incrémentiel
  - gzclose — Ferme un pointeur sur un fichier gz ouvert
  - gzcompress — Compresse une chaîne
  - gzdecode — Décode une chaîne de caractères compressée gzip
  - gzdeflate — Compresse une chaîne
  - gzencode — Crée une chaîne compressée gzip
  - gzeof — Indique si la fin d'un fichier (EOF) compressé est atteinte
  - gzfile — Lit la totalité d'un fichier compressé
  - gzgetc — Lit un caractère dans un fichier compressé
  - gzgets — Lit une ligne dans un fichier compressé
  - gzgetss — Lit une ligne dans un fichier compressé, et supprime les balises HTML
  - gzinflate — Décompresse une chaîne
  - gzopen — Ouvre un fichier compressé avec gzip
  - gzpassthru — Affiche toutes les données qui restent dans un pointeur gz
  - gzputs — Alias de gzwrite
  - gzread — Lecture de fichier compressé binaire
  - gzrewind — Replace le pointeur au début du fichier
  - gzseek — Déplace le pointeur de lecture
  - gztell — Lit la position courante du pointeur de lecture
  - gzuncompress — Décompresse une chaîne compressée
  - gzwrite — Écrit dans un fichier compressé gzip
  - inflate_add — Décompresse des données de manière incrémentielle
  - inflate_get_read_len — Renvoie le nombre d'octets lus jusqu'à présent
  - inflate_get_status — Renvoie le statut de décompression
  - inflate_init — Initialise un contexte de décompressage incrémentiel
  - ob_gzhandler — Fonction de rappel pour la compression automatique des tampons
  - readgzfile — Lit tout le fichier compressé
  - zlib_decode — Décompresse des données encodées raw/gzip/zlib
  - zlib_encode — Compresse des données avec l'encodage spécifié
  - zlib_get_coding_type — Retourne la méthode de compression utilisée pour la compression de sortie
- DeflateContext — La classe DeflateContext
- InflateContext — La classe InflateContext

- Bzip2
  - Installation/Configuration
  - Exemples
  - Bzip2 Fonctions
- LZF
  - Installation/Configuration
  - Fonctions LZF
- Phar
  - Installation/Configuration
  - Constantes pré-définies
  - Utiliser les archives Phar
  - Créer des archives Phar
  - Qu'est-ce qui fait d'un phar un phar et pas un tar ou un zip ?
  - Phar — La classe Phar
  - PharData — La classe PharData
  - PharFileInfo — La classe PharFileInfo
  - PharException — La classe PharException
- Rar — Archives RAR
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions Rar
  - RarArchive — La classe RarArchive
  - RarEntry — La classe RarEntry
  - RarException — La classe RarException
- Zip
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - ZipArchive — La classe ZipArchive
  - Fonctions Zip
- Zlib — Compression Zlib
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions Zlib
  - DeflateContext — La classe DeflateContext
  - InflateContext — La classe InflateContext

# Extensions sur la cryptographie

# HASH Message Digest Framework

# Introduction

Cette extension fournit des fonctions qui peuvent être utilisées pour le traitement direct ou incrémental de messages de longueur arbitraire en utilisant une variété d'algorithmes de hachage, y compris la génération de valeurs HMAC et des dérivations de clés incluant HKDF et PBKDF2.

Il existe grosso modo trois catégories d'algorithmes de hachage, et une liste complète des algorithmes peut être trouvée dans la documentation pour hash_algos().

- Algorithmes de somme de contrôle (tels que `"crc32b"` ou `"adler32"`) : Ceux-ci sont utilisés pour calculer des sommes de contrôle, utiles dans des situations telles que la détection des erreurs de transmission. Ils sont souvent très rapides. Ces algorithmes génèrent souvent des valeurs facilement "devinables" ou peuvent être manipulés pour créer des collisions, ils sont donc totalement inadaptés à une utilisation cryptographique.
- Algorithmes non cryptographiques (comme la famille xxHash) : Ceux-ci sont souvent utilisés pour calculer des valeurs de hachage pour des tables de hachage, car ils sont conçus pour produire une bonne distribution sur des entrées de chaîne arbitraires. Ils sont également généralement rapides, mais aussi inadaptés à une utilisation cryptographique.
- Algorithmes cryptographiques (comme la famille SHA-2) : Ceux-ci sont conçus pour produire des valeurs de hachage représentatives de leurs entrées mais ne pouvant pas être devinées ni sujettes aux collisions. La performance est souvent une préoccupation secondaire, mais le matériel moderne supporte souvent une gestion spéciale pour ces algorithmes que PHP essaie d'utiliser lorsque disponible. Le Centre de ressources pour la sécurité informatique du NIST a » une explication des algorithmes actuellement approuvés par les Standards fédéraux de traitement de l'information des États-Unis.
  Attention

  Certains des premiers algorithmes cryptographiques, tels que `"md4"`, `"md5"`, et `"sha1"`, se sont avérés être sujets à des attaques par collision et il est généralement recommandé de ne plus les utiliser pour des applications cryptographiques.

Voir également la FAQ sur le hachage sécurisé des mots de passe pour des informations sur les meilleures pratiques d'utilisation des fonctions de hachage dans la gestion des mots de passe.

# Installation/Configuration

## Sommaire

- Installation
- Types de ressources

## Installation

L'extension Hash est une extension du cœur de PHP, donc elle est toujours activée.

Avant PHP 7.4.0, l'extension Hash était incluse et compilée dans PHP par défaut, mais pouvait être explicitement désactivée en utilisant --disable-hash.

Avant PHP 5.1.2, l'extension Hash était installée en tant que » module PECL.

## Types de ressources

Cette extension définit une ressource Hash de contexte, retournée par la fonction hash_init().

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`HASH_HMAC` (int)
  Drapeau optionnel pour hash_init(). Indique que l'algorithme de clé HMAC doit être appliqué au contexte courant de hachage.

# La classe HashContext

(PHP 7 >= 7.2.0, PHP 8)

## Introduction

## Synopsis de la classe

final class HashContext {
/* Méthodes */
private function __construct()
public function __debugInfo(): array
public function __serialize(): array
public function __unserialize(array `$data`): void
}

# HashContext::__construct

(PHP 7 >= 7.2.0, PHP 8)

HashContext::__construct — Constructeur privé pour interdire l'instanciation directe

### Description

private function HashContext::__construct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# HashContext::__debugInfo

(PHP 8 >= 8.4.0)

HashContext::__debugInfo — Retourne des informations de débogage sur le contexte de hachage

### Description

public function HashContext::__debugInfo(): array

Cette méthode n'est pas destinée à être appelée directement ; elle est invoquée par var_dump() et les fonctions associées lors de l'inspection d'une instance de HashContext.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif d'informations de débogage. Il contient une clé `algo` contenant le nom de l'algorithme de hachage utilisé par le contexte.

### Exemples

Exemple #1 Exemple avec HashContext::__debugInfo()

    <?php
    $ctx = hash_init('sha256');
    var_dump($ctx);
    ?>

L'exemple ci-dessus va afficher :

    object(HashContext)#1 (1) {
      ["algo"]=>
      string(6) "sha256"
    }

### Voir aussi

- hash_init() - Initialise un contexte de hachage incrémental
- var_dump() - Affiche les informations d'une variable

# HashContext::__serialize

(PHP 8)

HashContext::__serialize — Sérialise l'objet HashContext

### Description

public function HashContext::__serialize(): array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

# HashContext::__unserialize

(PHP 8)

HashContext::__unserialize — Désérialise le paramètre `data` en un objet HashContext

### Description

public function HashContext::__unserialize(array `$data`): void

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`data`

  La valeur en cours de désérialisation.

### Valeurs de retour

Aucune valeur n'est retournée.

## Sommaire

- HashContext::__construct — Constructeur privé pour interdire l'instanciation directe
- HashContext::__debugInfo — Retourne des informations de débogage sur le contexte de hachage
- HashContext::__serialize — Sérialise l'objet HashContext
- HashContext::__unserialize — Désérialise le paramètre data en un objet HashContext

# Fonctions Hash

# hash

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash — Génère une valeur de hachage (empreinte numérique)

### Description

function hash(
string `$algo`,
string `$data`,
bool `$binary` = `false`,
array `$options` = []
): string

### Liste de paramètres

`algo`

  Nom de l'algorithme de hachage sélectionné (par exemple : `"sha256"`). Pour une liste des algorithmes supportés voir hash_algos().

`data`

  Message à hacher.

`binary`

  Lorsqu'il vaut `true`, la sortie sera des données brutes binaires. Lorsqu'il vaut `false`, la sortie sera des chiffres hexadécimaux en minuscule.

`options`

  Un tableau d'options pour les divers algorithmes de hachage. Actuellement, seul le paramètre `"seed"` est supporté pour les variantes MurmurHash.

### Valeurs de retour

Retourne une chaîne de caractères contenant l'empreinte numérique calculée en chiffre hexadécimal minuscule à moins que `binary` soit fixé à `true`. Dans ce cas, la représentation brute binaire de l'empreinte numérique est retournée.

### Erreurs / Exceptions

Lève une exception ValueError si le paramètre `algo` est inconnu.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `options` a été ajouté.
8.0.0 | Lève désormais une exception ValueError si l'`algo` est inconnu ; auparavant, `false` était retourné et un message `E_WARNING` était émis.

### Exemples

Exemple #1 Exemple avec hash()

    <?php
    echo hash('sha256', 'The quick brown fox jumped over the lazy dog.');
    ?>

L'exemple ci-dessus va afficher :

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Voir aussi

- hash_init() - Initialise un contexte de hachage incrémental
- hash_file() - Génère une valeur de hachage en utilisant le contenu d'un fichier donné
- hash_hmac() - Génère une valeur de clé de hachage en utilisant la méthode HMAC

# hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algos — Retourne une liste des algorithmes de hachage enregistrés

### Description

function hash_algos(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau indexé numériquement contenant la liste des algorithmes de hachage disponibles.

### Historique

Version | Description
--- | ---
8.1.0 | Support pour MurmurHash3 et xxHash a été ajouté.
7.4.0 | Support pour crc32c a été ajouté.
7.1.0 | Support pour sha512/224, sha512/256, sha3-224, sha3-256, sha3-384 et sha3-512 a été ajouté.

### Exemples

Exemple #1 Exemple avec hash_algos()

À partir de PHP 8.1.0, hash_algos() retourne la liste d'algorithmes suivante :

    <?php
    print_r(hash_algos());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => adler32
        [30] => crc32
        [31] => crc32b
        [32] => crc32c
        [33] => fnv132
        [34] => fnv1a32
        [35] => fnv164
        [36] => fnv1a64
        [37] => joaat
        [38] => murmur3a
        [39] => murmur3c
        [40] => murmur3f
        [41] => xxh32
        [42] => xxh64
        [43] => xxh3
        [44] => xxh128
        [45] => haval128,3
        [46] => haval160,3
        [47] => haval192,3
        [48] => haval224,3
        [49] => haval256,3
        [50] => haval128,4
        [51] => haval160,4
        [52] => haval192,4
        [53] => haval224,4
        [54] => haval256,4
        [55] => haval128,5
        [56] => haval160,5
        [57] => haval192,5
        [58] => haval224,5
        [59] => haval256,5
    )

### Voir aussi

- hash() - Génère une valeur de hachage (empreinte numérique)
- hash_hmac_algos() - Retourne la liste des algorithmes de hachage adaptés pour hash_hmac

# hash_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copy — Copie un contexte de hachage

### Description

function hash_copy(HashContext `$context`): HashContext

### Liste de paramètres

`context`

  Contexte de hachage, retourné par la fonction hash_init().

### Valeurs de retour

Retourne une copie du contexte de hachage.

### Historique

Version | Description
--- | ---
7.2.0 | Accepte et retourne une classe HashContext au lieu d'une ressource.

### Exemples

Exemple #1 Exemple avec hash_copy()

    <?php
    $context = hash_init("sha256");
    hash_update($context, "The quick brown fox ");

    /* copie le contexte afin de pouvoir continuer à l'utiliser */
    $copy_context = hash_copy($context);

    echo hash_final($context), "\n";

    hash_update($copy_context, "jumped over the lazy dog.");
    echo hash_final($copy_context), "\n";
    ?>

L'exemple ci-dessus va afficher :

    b29d66e56ed90cce9b0165c43fedec612b60a071974d8be4513e18580d55b5bd
    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

# hash_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equals — Comparaison de chaînes résistante aux attaques temporelles

### Description

function hash_equals(#[\SensitiveParameter]string `$known_string`, #[\SensitiveParameter]string `$user_string`): bool

Vérifie si deux chaînes de caractères sont égales sans divulguer d'informations sur le contenu de `known_string` via le temps d'exécution.

Cette fonction peut être utilisée pour atténuer les attaques temporelles. L'exécution d'une comparaison régulière avec `===` prend plus ou moins de temps selon que les deux valeurs sont différentes ou non et selon la position à laquelle la première différence peut être trouvée, laissant ainsi filtrer des informations sur le contenu de la `known_string` secrète.

Attention

Il est important de passer la chaîne fournie par l'utilisateur en tant que second paramètre plutôt qu'en premier.

### Liste de paramètres

`known_string`

  La chaîne de caractères connue qui doit être gardée secrète.

`user_string`

  La chaîne fournie par l'utilisateur à comparer.

### Valeurs de retour

Retourne `true` si les deux chaînes sont égales, `false` sinon.

### Exemples

Exemple #1 Exemple avec hash_equals()

    <?php
    $secretKey = '8uRhAeH89naXfFXKGOEj';

    // La valeur et la signature sont fournies par l'utilisateur, par ex. dans l'URL
    // et récupérées en utilisant $_GET.
    $value = 'username=rasmuslerdorf';
    $signature = '8c35009d3b50caf7f5d2c1e031842e6b7823a1bb781d33c5237cd27b57b5f327';

    if (hash_equals(hash_hmac('sha256', $value, $secretKey), $signature)) {
        echo "La valeur est correctement signée.", PHP_EOL;
    } else {
        echo "La valeur a été altérée.", PHP_EOL;
    }
    ?>

L'exemple ci-dessus va afficher :

    La valeur est correctement signée.

### Notes

> Note:

> Les deux arguments doivent être de même longueur pour être comparés avec succès. Quand des arguments de longueur différente sont passés, `false` est retourné immédiatement et la longueur de la chaîne connue peut être dévoilée en cas d'attaque temporelle.

### Voir aussi

- hash_hmac() - Génère une valeur de clé de hachage en utilisant la méthode HMAC

# hash_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_file — Génère une valeur de hachage en utilisant le contenu d'un fichier donné

### Description

function hash_file(
string `$algo`,
string `$filename`,
bool `$binary` = `false`,
array `$options` = []
): string|false

### Liste de paramètres

`algo`

  Nom de l'algorithme de hachage sélectionné (par exemple : `"sha256"`). Pour une liste des algorithmes disponibles voir hash_algos().

`filename`

  URL indiquant l'emplacement du fichier qui sera haché ; Supporte les enveloppes fopen().

`binary`

  Lorsqu'il vaut `true`, la sortie sera des données brutes binaires. Lorsqu'il vaut `false`, la sortie sera des chiffres hexadécimaux en minuscule.

`options`

  Un tableau d'options pour les différents algorithmes de hachage. Actuellement, seul le paramètre `"seed"` est supporté pour les variantes MurmurHash.

### Valeurs de retour

Retourne une chaîne de caractères contenant l'empreinte numérique calculée en chiffre hexadécimal minuscule à moins que `binary` soit fixé à `true`. Dans ce cas, la représentation brute binaire de l'empreinte numérique est retournée, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `options` a été ajouté.

### Exemples

Exemple #1 Exemple avec hash_file()

    <?php
    /* Crée un fichier pour calculer son empreinte numérique */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_file('sha256', 'example.txt');
    ?>

L'exemple ci-dessus va afficher :

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Voir aussi

- hash_init() - Initialise un contexte de hachage incrémental
- hash_hmac_file() - Génère une valeur de clé de hachage en utilisant la méthode HMAC et le contenu d'un fichier donné

# hash_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_final — Finalise un hachage incrémental et retourne le résultat de l'empreinte numérique

### Description

function hash_final(HashContext `$context`, bool `$binary` = `false`): string

### Liste de paramètres

`context`

  Contexte de hachage retourné par hash_init().

`binary`

  Lorsqu'il vaut `true`, la sortie sera des données brutes binaires. Lorsqu'il vaut `false`, la sortie sera des chiffres hexadécimaux en minuscule.

### Valeurs de retour

Retourne une chaîne de caractères contenant l'empreinte numérique calculée en chiffre hexadécimal minuscule à moins que `binary` soit fixé à `true`. Dans ce cas, la représentation brute binaire de l'empreinte numérique est retournée.

### Historique

Version | Description
--- | ---
7.2.0 | Accepte une HashContext au lieu d'une ressource.

### Voir aussi

- hash_init() - Initialise un contexte de hachage incrémental
- hash_update() - Ajoute des données dans le contexte de hachage actif
- hash_update_stream() - Ajoute des données dans un contexte de hachage actif d'un flux ouvert
- hash_update_file() - Ajoute des données dans un contexte de hachage actif provenant d'un fichier

# hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdf — Génère une dérivation de clé HKDF depuis une clé fournie

### Description

function hash_hkdf(
string `$algo`,
#[\SensitiveParameter]string `$key`,
int `$length` = 0,
string `$info` = "",
string `$salt` = ""
): string

### Liste de paramètres

`algo`

  Nom de l'algorithme de hachage sélectionné (par exemple : `"sha256"`). Pour une liste des algorithmes supportés voir hash_hmac_algos().

  > Note:

  > Les fonctions de hachage non cryptographiques ne sont pas autorisées.

`key`

  Données (Input keying material) en binaire qui serviront au clavetage. Ne peut pas être vide.

`length`

  Longueur désirée des données de sortie en octets. Ne peut être plus grand que 255 fois la taille de la fonction de hachage.

  Si `length` vaut `0`, la longueur des données de sortie sera par défaut la taille de la fonction de hachage choisie.

`info`

  Information sous forme de chaîne de caractères spécifique à l'application/contexte.

`salt`

  Sel à utiliser lors de la dérivation.

  Bien qu'optionnel, ajouter un sel aléatoire augmente de façon significative la robustesse de HKDF.

### Valeurs de retour

Retourne un chaîne de caractères contenant une représentation binaire brute de la clé dérivée (aussi connue sous le nom de output keying material - OKM).

### Erreurs / Exceptions

Lève une exception ValueError si `key` est vide, `algo` est inconnu/non cryptographique, `length` est inférieur à `0` ou trop grand (plus grand que 255 fois la taille de la fonction de hachage).

### Historique

Version | Description
--- | ---
8.0.0 | Lève une exception ValueError en cas d'erreur dorénavant. Précédemment, `false` était retournée et un message `E_WARNING` était émis.

### Exemples

L’exemple ci-dessous génère une paire de clés distinctes, adaptée à la création d’une construction de type chiffrer-puis-HMAC, en utilisant AES-256 et SHA-256 respectivement pour le chiffrement et l’authentification.

Exemple #1 Exemple avec hash_hkdf()

    <?php
    // Génère une clé aléatoire, et un sel pour la renforcer lors de la dérivation.
    $inputKey = random_bytes(32);
    $salt = random_bytes(16);

    // Dérive une paire de clés séparées, utilisant les mêmes données créées juste avant.
    $encryptionKey = hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption', $salt);
    $authenticationKey = hash_hkdf('sha256', $inputKey, 32, 'sha-256-authentication', $salt);

    var_dump($encryptionKey !== $authenticationKey); // bool(true)
    ?>

### Voir aussi

- hash_pbkdf2() - Génère une clé PBKDF2 dérivée du mot de passe fourni
- » RFC 5869
- » userland implementation

# hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac — Génère une valeur de clé de hachage en utilisant la méthode HMAC

### Description

function hash_hmac(
string `$algo`,
string `$data`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string

### Liste de paramètres

`algo`

  Nom de l'algorithme de hachage sélectionné (par exemple : `"sha256"`). Pour une liste des algorithmes supportés voir hash_hmac_algos().

  > Note:

  > Les fonctions de hachage non cryptographiques ne sont pas autorisées.

`data`

  Le message qui sera haché.

`key`

  Clé secrète partagée utilisée pour générer la variante HMAC de l'empreinte numérique.

`binary`

  Lorsqu'il vaut `true`, la sortie sera des données brutes binaires. Lorsqu'il vaut `false`, la sortie sera des chiffres hexadécimaux en minuscule.

### Valeurs de retour

Retourne une chaîne de caractères contenant l'empreinte numérique calculée en chiffre hexadécimal minuscule à moins que `binary` soit fixé à `true`. Dans ce cas, la représentation brute binaire de l'empreinte numérique est retournée.

### Erreurs / Exceptions

Lève une exception ValueError si le paramètre `algo` est inconnu ou n'est pas une fonction de hachage cryptographique.

### Historique

Version | Description
--- | ---
8.0.0 | hash_hmac() lance désormais une exception ValueError si l'`algo` est inconnu ou n'est pas une fonction de hachage cryptographique ; auparavant, `false` était retourné et un message `E_WARNING` était émis.
7.2.0 | L'utilisation de fonctions de hachage non cryptographiques (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) a été désactivée.

### Exemples

Exemple #1 Exemple avec hash_hmac()

    <?php
    echo hash_hmac('sha256', 'The quick brown fox jumped over the lazy dog.', 'secret');
    ?>

L'exemple ci-dessus va afficher :

    9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

### Voir aussi

- hash_hmac_algos() - Retourne la liste des algorithmes de hachage adaptés pour hash_hmac
- hash_hmac_file() - Génère une valeur de clé de hachage en utilisant la méthode HMAC et le contenu d'un fichier donné
- hash_equals() - Comparaison de chaînes résistante aux attaques temporelles

# hash_hmac_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algos — Retourne la liste des algorithmes de hachage adaptés pour hash_hmac

### Description

function hash_hmac_algos(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau indexé numériquement contenant la liste de tous les algorithmes de hachage disponibles qui sont adaptés pour hash_hmac().

### Exemples

Exemple #1 Exemple avec hash_hmac_algos()

    <?php
    print_r(hash_hmac_algos());

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => haval128,3
        [30] => haval160,3
        [31] => haval192,3
        [32] => haval224,3
        [33] => haval256,3
        [34] => haval128,4
        [35] => haval160,4
        [36] => haval192,4
        [37] => haval224,4
        [38] => haval256,4
        [39] => haval128,5
        [40] => haval160,5
        [41] => haval192,5
        [42] => haval224,5
        [43] => haval256,5
    )

### Notes

> Note:

> Antérieur à PHP 7.2.0 la seule façon pour récupérer une liste des algorithmes disponibles était d'appeler hash_algos() qui retournait aussi des algorithmes qui ne sont pas adaptés pour hash_hmac().

### Voir aussi

- hash_hmac() - Génère une valeur de clé de hachage en utilisant la méthode HMAC
- hash_algos() - Retourne une liste des algorithmes de hachage enregistrés

# hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_file — Génère une valeur de clé de hachage en utilisant la méthode HMAC et le contenu d'un fichier donné

### Description

function hash_hmac_file(
string `$algo`,
string `$filename`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string|false

### Liste de paramètres

`algo`

  Nom de l'algorithme de hachage sélectionné (par exemple : `"sha256"`). Pour une liste des algorithmes supportés voir hash_hmac_algos().

  > Note:

  > Les fonctions de hachage non cryptographiques ne sont pas autorisées.

`filename`

  URL indiquant l'emplacement du fichier qui sera haché ; Supporte les enveloppes fopen().

`key`

  Clé secrète partagée utilisée pour générer la variante HMAC de l'empreinte numérique.

`binary`

  Lorsqu'il vaut `true`, la sortie sera des données brutes binaires. Lorsqu'il vaut `false`, la sortie sera des chiffres hexadécimaux en minuscule.

### Valeurs de retour

Retourne une chaîne de caractères contenant l'empreinte numérique calculée en chiffre hexadécimal minuscule à moins que `binary` soit fixé à `true`. Dans ce cas, la représentation brute binaire de l'empreinte numérique est retournée. Retourne `false` si le fichier `filename` ne peut pas être lu.

### Erreurs / Exceptions

Lève une exception ValueError si le paramètre `algo` est inconnu ou n'est pas une fonction de hachage cryptographique.

### Historique

Version | Description
--- | ---
8.0.0 | Lève une exception ValueError dorénavant si le paramètre `algo` est inconnu ou n'est pas une fonction de hachage cryptographique ; précédemment, `false` était retourné et un message `E_WARNING` était émis.
7.2.0 | L'utilisation de fonctions de hachage non cryptographiques (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) a été désactivée.

### Exemples

Exemple #1 Exemple avec hash_hmac_file()

    <?php
    /* Crée un fichier pour calculer son empreinte numérique */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_hmac_file('sha256', 'example.txt', 'secret');
    ?>

L'exemple ci-dessus va afficher :

    9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

### Voir aussi

- hash_hmac() - Génère une valeur de clé de hachage en utilisant la méthode HMAC
- hash_hmac_algos() - Retourne la liste des algorithmes de hachage adaptés pour hash_hmac
- hash_init() - Initialise un contexte de hachage incrémental
- hash_equals() - Comparaison de chaînes résistante aux attaques temporelles

# hash_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_init — Initialise un contexte de hachage incrémental

### Description

function hash_init(
string `$algo`,
int `$flags` = 0,
#[\SensitiveParameter]string `$key` = "",
array `$options` = []
): HashContext

### Liste de paramètres

`algo`

  Nom de l'algorithme de hachage sélectionné (par exemple : `"sha256"`). Pour une liste des algorithmes supportés voir hash_algos().

  > Note:

  > Les fonctions de hachage non cryptographiques ne sont pas autorisées si le drapeau `HASH_HMAC` est spécifié.

`flags`

  Configurations optionnelles pour la génération du hachage, supporte actuellement seulement une option : `HASH_HMAC`. Lorsque cette option est spécifiée, le paramètre `key` doit être spécifié.

`key`

  Lorsque `HASH_HMAC` est spécifié pour `flags`, une clé secrète partagée qui sera utilisée avec la méthode de hachage HMAC doit être fournie dans ce paramètre.

`options`

  Un tableau d'options pour les divers algorithmes de hachage. Actuellement, seul le paramètre `"seed"` est supporté pour les variantes MurmurHash.

### Valeurs de retour

Retourne le contexte de hachage HashContext pour utilisation avec hash_update(), hash_update_stream(), hash_update_file() et hash_final().

### Erreurs / Exceptions

- Lève une exception ValueError si le `algo` est inconnu, s'il s'agit d'une fonction de hachage non cryptographique, ou si `key` est vide.
- Passer des options de configuration de type incorrect dans `options` émettra désormais une erreur `E_DEPRECATED`, car elles peuvent être mal interprétées. Cela entraînera une exception ValueError à l'avenir.

### Historique

Version | Description
--- | ---
8.4.0 | Passer des options d'un type incorrect est désormais déconseillé.
8.1.0 | Le paramètre `options` a été ajouté.
8.0.0 | Lève une exception ValueError dorénavant si le paramètre `algo` est inconnu ou n'est pas une fonction de hachage cryptographique, ou si le paramètre `key` est vide. Précédemment, `false` était retourné et un message `E_WARNING` était émis.
7.2.0 | L'usage de fonction de hachage non-cryptographique (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) avec `HASH_HMAC` a été désactivé.
7.2.0 | Retourne une HashContext au lieu d'une ressource.

### Exemples

Exemple #1 Exemple de hachage incrémental

    <?php
    $hash = hash('sha256', 'The quick brown fox jumped over the lazy dog.');

    $ctx = hash_init('sha256');
    hash_update($ctx, 'The quick brown fox ');
    hash_update($ctx, 'jumped over the lazy dog.');
    $incremental_hash = hash_final($ctx);

    echo $incremental_hash, PHP_EOL;
    var_dump($hash === $incremental_hash);
    ?>

L'exemple ci-dessus va afficher :

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483
    bool(true)

### Voir aussi

- hash_algos() - Retourne une liste des algorithmes de hachage enregistrés
- hash_update() - Ajoute des données dans le contexte de hachage actif
- hash_update_file() - Ajoute des données dans un contexte de hachage actif provenant d'un fichier
- hash_update_stream() - Ajoute des données dans un contexte de hachage actif d'un flux ouvert
- hash_final() - Finalise un hachage incrémental et retourne le résultat de l'empreinte numérique

# hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — Génère une clé PBKDF2 dérivée du mot de passe fourni

### Description

function hash_pbkdf2(
string `$algo`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$iterations`,
int `$length` = 0,
bool `$binary` = `false`,
array `$options` = []
): string

### Liste de paramètres

`algo`

  Nom de l'algorithme de hachage sélectionné (par exemple : `"sha256"`). Pour une liste des algorithmes supportés voir hash_hmac_algos().

  > Note:

  > Les fonctions de hachage non cryptographiques ne sont pas autorisées.

`password`

  Le mot de passe à utiliser pour la dérivation.

`salt`

  Le sel à utiliser pour la dérivation. Cette valeur doit être générée aléatoirement.

`iterations`

  Le nombre d'itérations internes pour effectuer la dérivation.

`length`

  La longueur de la chaîne de sortie. Si le paramètre `binary` vaut `true`, ce paramètre correspondra à la longueur, en octets, de la clé dérivée ; si le paramètre `binary` vaut `false`, il correspondra à deux fois la longueur, en octets, de la clé dérivée (vu que chaque octet de la clé est retourné sur deux hexits).

  Si `0` est passé, la sortie complète de l'algorithme choisi sera utilisée.

`binary`

  Lorsque `true`, retourne les données binaires brutes. Lorsque `false`, retourne des chiffres hexadécimaux en minuscule.

`options`

  Un tableau d'options pour les différents algorithmes d'hachage. Actuellement, seule la clé `"seed"` est supportée par les variantes MurmurHash.

### Valeurs de retour

Retourne une chaîne contenant la clé dérivée en minuscule, à moins que le paramètre `binary` ne soit positionné à `true` auquel cas, la représentation binaire brute de la clé dérivée est retournée.

### Erreurs / Exceptions

Lève une exception ValueError si l'algorithme n'est pas connu, si le paramètre `iterations` est inférieur ou égal à `0`, si la longueur `length` est inférieure à `0` ou si le `salt` est trop long (plus grand que `INT_MAX``- 4`).

### Historique

Version | Description
--- | ---
8.0.0 | Lève une exception ValueError dorénavant en cas d'erreur. Précédemment, `false` était retourné et un message `E_WARNING` était émis.
7.2.0 | L'utilisation de fonctions de hachage non cryptographiques (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) a été désactivée.

### Exemples

Exemple #1 Exemple avec hash_pbkdf2()

    <?php
    $password = "password";
    $iterations = 600000;

    // Génère un sel cryptographiquement sécurisé aléatoire en utilisant la fonction random_bytes()
    $salt = random_bytes(16);

    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
    var_dump($hash);

    // Pour du binaire brut, $length doit être divisé par deux pour des résultats équivalents
    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
    var_dump(bin2hex($hash));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(20) "120fb6cffcf8b32c43e7"
    string(20) "120fb6cffcf8b32c43e7"

### Notes

Attention

La méthode PBKDF2 peut être utilisée pour hacher des mots de passe pour le stockage. Cependant, il faut garder à l'esprit que la fonction password_hash() ou la fonction crypt() avec la constante `CRYPT_BLOWFISH` sont mieux adaptées pour cet usage.

### Voir aussi

- password_hash() - Crée une clé de hachage pour un mot de passe
- hash_hkdf() - Génère une dérivation de clé HKDF depuis une clé fournie
- sodium_crypto_pwhash() - Dérive une clé à partir d'un mot de passe, en utilisant Argon2

# hash_update

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update — Ajoute des données dans le contexte de hachage actif

### Description

function hash_update(HashContext `$context`, string `$data`): true

### Liste de paramètres

`context`

  Contexte de hachage retourné par hash_init().

`data`

  Message qui sera inclus dans l'empreinte de hachage.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.4.0 | Possède désormais un type de retour true au lieu de bool.
7.2.0 | Accepte une HashContext au lieu d'une ressource.

### Voir aussi

- hash_init() - Initialise un contexte de hachage incrémental
- hash_update_file() - Ajoute des données dans un contexte de hachage actif provenant d'un fichier
- hash_update_stream() - Ajoute des données dans un contexte de hachage actif d'un flux ouvert
- hash_final() - Finalise un hachage incrémental et retourne le résultat de l'empreinte numérique

# hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_file — Ajoute des données dans un contexte de hachage actif provenant d'un fichier

### Description

function hash_update_file(HashContext `$context`, string `$filename`, ?resource `$stream_context` = `null`): bool

### Liste de paramètres

`context`

  Contexte de hachage retourné par hash_init().

`filename`

  URL indiquant l'emplacement du fichier qui sera haché; Supporte les enveloppes fopen().

`stream_context`

  Contexte de flux retourné par stream_context_create().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `stream_context` est désormais nullable.
7.2.0 | Accepte une HashContext au lieu d'une ressource.

### Voir aussi

- hash_init() - Initialise un contexte de hachage incrémental
- hash_update() - Ajoute des données dans le contexte de hachage actif
- hash_update_stream() - Ajoute des données dans un contexte de hachage actif d'un flux ouvert
- hash_final() - Finalise un hachage incrémental et retourne le résultat de l'empreinte numérique
- hash_file() - Génère une valeur de hachage en utilisant le contenu d'un fichier donné

# hash_update_stream

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_stream — Ajoute des données dans un contexte de hachage actif d'un flux ouvert

### Description

function hash_update_stream(HashContext `$context`, resource `$stream`, int `$length` = -1): int

### Liste de paramètres

`context`

  Contexte de hachage retourné par hash_init().

`stream`

  Gestionnaire de fichier ouvert comme retourné par n'importe quelle fonction de création de flux.

`length`

  Nombre maximum de caractères à copier de `stream` dans le contexte de hachage.

### Valeurs de retour

Nombre effectif d'octets ajoutés au contexte de hachage de `stream`.

### Historique

Version | Description
--- | ---
7.2.0 | Accepte une HashContext au lieu d'une ressource.

### Exemples

Exemple #1 Exemple avec hash_update_stream()

    <?php
    $fp = tmpfile();
    fwrite($fp, 'jumped over the lazy dog.');
    rewind($fp);

    $ctx = hash_init('sha256');
    hash_update($ctx, 'The quick brown fox ');
    hash_update_stream($ctx, $fp);
    echo hash_final($ctx);
    ?>

L'exemple ci-dessus va afficher :

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Voir aussi

- hash_init() - Initialise un contexte de hachage incrémental
- hash_update() - Ajoute des données dans le contexte de hachage actif
- hash_final() - Finalise un hachage incrémental et retourne le résultat de l'empreinte numérique

## Sommaire

- hash — Génère une valeur de hachage (empreinte numérique)
- hash_algos — Retourne une liste des algorithmes de hachage enregistrés
- hash_copy — Copie un contexte de hachage
- hash_equals — Comparaison de chaînes résistante aux attaques temporelles
- hash_file — Génère une valeur de hachage en utilisant le contenu d'un fichier donné
- hash_final — Finalise un hachage incrémental et retourne le résultat de l'empreinte numérique
- hash_hkdf — Génère une dérivation de clé HKDF depuis une clé fournie
- hash_hmac — Génère une valeur de clé de hachage en utilisant la méthode HMAC
- hash_hmac_algos — Retourne la liste des algorithmes de hachage adaptés pour hash_hmac
- hash_hmac_file — Génère une valeur de clé de hachage en utilisant la méthode HMAC et le contenu d'un fichier donné
- hash_init — Initialise un contexte de hachage incrémental
- hash_pbkdf2 — Génère une clé PBKDF2 dérivée du mot de passe fourni
- hash_update — Ajoute des données dans le contexte de hachage actif
- hash_update_file — Ajoute des données dans un contexte de hachage actif provenant d'un fichier
- hash_update_stream — Ajoute des données dans un contexte de hachage actif d'un flux ouvert

- Installation/Configuration
  - Installation
  - Types de ressources
- Constantes pré-définies
- HashContext — La classe HashContext
  - HashContext::__construct — Constructeur privé pour interdire l'instanciation directe
  - HashContext::__debugInfo — Retourne des informations de débogage sur le contexte de hachage
  - HashContext::__serialize — Sérialise l'objet HashContext
  - HashContext::__unserialize — Désérialise le paramètre data en un objet HashContext
- Fonctions Hash
  - hash — Génère une valeur de hachage (empreinte numérique)
  - hash_algos — Retourne une liste des algorithmes de hachage enregistrés
  - hash_copy — Copie un contexte de hachage
  - hash_equals — Comparaison de chaînes résistante aux attaques temporelles
  - hash_file — Génère une valeur de hachage en utilisant le contenu d'un fichier donné
  - hash_final — Finalise un hachage incrémental et retourne le résultat de l'empreinte numérique
  - hash_hkdf — Génère une dérivation de clé HKDF depuis une clé fournie
  - hash_hmac — Génère une valeur de clé de hachage en utilisant la méthode HMAC
  - hash_hmac_algos — Retourne la liste des algorithmes de hachage adaptés pour hash_hmac
  - hash_hmac_file — Génère une valeur de clé de hachage en utilisant la méthode HMAC et le contenu d'un fichier donné
  - hash_init — Initialise un contexte de hachage incrémental
  - hash_pbkdf2 — Génère une clé PBKDF2 dérivée du mot de passe fourni
  - hash_update — Ajoute des données dans le contexte de hachage actif
  - hash_update_file — Ajoute des données dans un contexte de hachage actif provenant d'un fichier
  - hash_update_stream — Ajoute des données dans un contexte de hachage actif d'un flux ouvert

# Mcrypt

# Introduction

Avertissement

Cette fonctionnalité est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0.

Les alternatives à cette fonctionnalité incluent :

- Sodium (disponible à partir de PHP 7.2.0)
- OpenSSL

> Note: Cette extension a été déplacée dans le module » PECL et ne sera plus intégrée dans PHP à partir de PHP 7.2.0.

Ces fonctions permettent d'accéder à la bibliothèque mcrypt, qui dispose d'une grande variété d'algorithmes de chiffrement, tels DES, TripleDES, Blowfish (par défaut), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 et GOST en modes CBC, OFB, CFB et ECB. De plus, elles acceptent aussi RC6 et IDEA qui sont considérés comme "non-libres". CFB/OFB est sur 8bit par défaut.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Ces fonctions utilisent » mcrypt. Pour utiliser cette bibliothèque, téléchargez le fichier libmcrypt-x.x.tar.gz sur » http://mcrypt.sourceforge.net/ et suivez les instructions d'installation fournies.

La version 2.5.6 ou suivante de la bibliothèque libmcrypt est requise.

Les utilisateurs de Windows trouveront la bibliothèque dans la version Windows de PHP 5.2. La version binaire Windows de PHP 5.3 utilise la version statique de la bibliothèque MCrypt, aucune DLL n'est nécessaire.

Si on compile PHP avec la bibliothèque `libmcrypt 2.4.x`, les algorithmes suivants sont supportés : `"CAST"`, `"LOKI97"`, `"RIJNDAEL"`, `"SAFERPLUS"`, `"SERPENT"` ainsi que les chiffrements suivants : `"ENIGMA"` (chiffrement), `"PANAMA"`, `"RC4"` et `"WAKE"`. Avec `libmcrypt 2.4.x` un autre mode de chiffrement est disponible : `"nOFB"`.

## Installation

Cette extension a été déplacée dans le module » PECL et ne sera plus intégrée dans PHP à partir de PHP 7.2.0

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/mcrypt.

## Configuration à l'exécution

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

Options de configuration mcrypt
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
mcrypt.algorithms_dir | `null` | `INI_ALL` |
mcrypt.modes_dir | `null` | `INI_ALL` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`mcrypt.algorithms_dir` string
  Le dossier contenant les algorithmes. Par défaut il s'agit du dossier indiqué à la compilation de libmcrypt, typiquement il s'agit de /usr/local/lib/libmcrypt. Voir mcrypt_list_algorithms() pour plus de détails.
`mcrypt.modes_dir` string
  Le dossier contenant les modes. Par défaut il s'agit du dossier indiqué à la compilation de libmcrypt, typiquement il s'agit de /usr/local/lib/libmcrypt. Voir mcrypt_list_modes() pour plus de détails.

## Types de ressources

mcrypt_module_open() retourne un pointeur de chiffrement.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Mcrypt peut opérer en 4 modes de chiffrement (`CBC`, `OFB`, `CFB`, et `ECB`). Si lié contre libmcrypt-2.4.x ou ultérieur, les fonctions peuvent aussi opérer en mode `nOFB` et en mode `STREAM`. Ci-dessous se trouve une liste avec tous les modes de chiffrement supportés avec les constantes qui sont définies pour le mode de chiffrement. Pour une référence plus complète et des discussions voir Applied Cryptography by Schneier (ISBN 0-471-11709-9).

- `MCRYPT_MODE_ECB` (`electronic codebook`) est un mode de chiffrement par bloc qui est généralement inapproprié à la plupart des utilisations. L'utilisation de ce mode est déconseillée.
- `MCRYPT_MODE_CBC` (`cipher block chaining`) est un mode de chiffrement par bloc qui est considérablement plus sécurisé que le mode `ECB`.
- `MCRYPT_MODE_CFB` (`cipher feedback, in 8-bit mode`) est un mode de chiffrement par flot. Il est conseillé d'utiliser le mode `NCFB` plutôt que le mode `CFB`.
- `MCRYPT_MODE_OFB` (`output feedback, in 8bit`) est un mode de chiffrement par flot comparable à `CFB`, mais peut être utilisé dans des applications où la propagation d'erreur ne peut être tolérée. Il est conseillé d'utiliser le mode `NOFB` plutôt que le mode `OFB`.
- `MCRYPT_MODE_NOFB` (`output feedback, in n-bit mode`) est comparable au mode `OFB`, mais opère sur la taille de bloc complète de l'algorithme.
- `MCRYPT_MODE_STREAM` est un mode supplémentaire, pour inclure des algorithmes de flot tels que `"WAKE"` ou `"RC4"`.

Mcrypt supporte d'autres modes d'opération pour lesquels il n'y a pas de constantes prédéfinies. Ils peuvent être utilisés en passant une chaîne de caractères à la place des constantes manquantes.

- `"ctr"` (`counter mode`) est un mode de chiffrement par flot.
- `"ncfb"` (`cipher feedback, in n-bit mode`) est comparable au mode `CFB`, mais opère sur la taille de bloc complète de l'algorithme.

Voici quelques autres constantes de modes et de périphériques aléatoires :

`MCRYPT_ENCRYPT` (int)
`MCRYPT_DECRYPT` (int)
`MCRYPT_DEV_RANDOM` (int)
`MCRYPT_DEV_URANDOM` (int)
`MCRYPT_RAND` (int)

# Chiffrements Mcrypt

Voici une liste non exhaustive des chiffrements de l'extension mcrypt. Pour disposer d'une liste complète des chiffrements supportés, voir les définitions dans le fichier mcrypt.h. La règle générale avec l'API mcrypt-2.2.x est qu'il est possible d'accéder au mode de chiffrement via PHP avec la constante MCRYPT_ciphername. Avec la bibliothèque libmcrypt-2.4.x et libmcrypt-2.5.x, ces constantes fonctionnent toujours, mais il est possible de spécifier le nom du chiffrement dans une chaîne, lors de l'appel à mcrypt_module_open().

- MCRYPT_3DES
- MCRYPT_ARCFOUR_IV (libmcrypt > 2.4.x uniquement)
- MCRYPT_ARCFOUR (libmcrypt > 2.4.x uniquement)
- MCRYPT_BLOWFISH
- MCRYPT_CAST_128
- MCRYPT_CAST_256
- MCRYPT_CRYPT
- MCRYPT_DES
- MCRYPT_DES_COMPAT (libmcrypt 2.2.x uniquement)
- MCRYPT_ENIGMA (libmcrypt > 2.4.x uniquement, alias de MCRYPT_CRYPT)
- MCRYPT_GOST
- MCRYPT_IDEA (non libre)
- MCRYPT_LOKI97 (libmcrypt > 2.4.x uniquement)
- MCRYPT_MARS (libmcrypt > 2.4.x uniquement, non libre)
- MCRYPT_PANAMA (libmcrypt > 2.4.x uniquement)
- MCRYPT_RIJNDAEL_128 (libmcrypt > 2.4.x uniquement)
- MCRYPT_RIJNDAEL_192 (libmcrypt > 2.4.x uniquement)
- MCRYPT_RIJNDAEL_256 (libmcrypt > 2.4.x uniquement)
- MCRYPT_RC2
- MCRYPT_RC4 (libmcrypt 2.2.x uniquement)
- MCRYPT_RC6 (libmcrypt > 2.4.x uniquement)
- MCRYPT_RC6_128 (libmcrypt 2.2.x uniquement)
- MCRYPT_RC6_192 (libmcrypt 2.2.x uniquement)
- MCRYPT_RC6_256 (libmcrypt 2.2.x uniquement)
- MCRYPT_SAFER64
- MCRYPT_SAFER128
- MCRYPT_SAFERPLUS (libmcrypt > 2.4.x uniquement)
- MCRYPT_SERPENT(libmcrypt > 2.4.x uniquement)
- MCRYPT_SERPENT_128 (libmcrypt 2.2.x uniquement)
- MCRYPT_SERPENT_192 (libmcrypt 2.2.x uniquement)
- MCRYPT_SERPENT_256 (libmcrypt 2.2.x uniquement)
- MCRYPT_SKIPJACK (libmcrypt > 2.4.x uniquement)
- MCRYPT_TEAN (libmcrypt 2.2.x uniquement)
- MCRYPT_THREEWAY
- MCRYPT_TRIPLEDES (libmcrypt > 2.4.x uniquement)
- MCRYPT_TWOFISH (pour les anciennes versions de mcrypt 2.x ou mcrypt > 2.4.x )
- MCRYPT_TWOFISH128 (TWOFISHxxx est disponible dans les nouvelles versions 2.x, mais pas dans les versions 2.4.x)
- MCRYPT_TWOFISH192
- MCRYPT_TWOFISH256
- MCRYPT_WAKE (libmcrypt > 2.4.x uniquement)
- MCRYPT_XTEA (libmcrypt > 2.4.x uniquement)

Il faut (mode `CFB` et `OFB`) ou il est possible de (mode `CBC`) fournir un vecteur d'initialisation (IV) pour ces modes de chiffrement. IV doit être unique, et avoir la même valeur au chiffrement et au déchiffrement. Pour des données qui seront enregistrées après chiffrement, il est possible de prendre le résultat d'une fonction telle que MD5, appliquée sur le nom du fichier. Sinon, l'on peut envoyer le IV avec les données chiffrées, (se reporter au chapitre 9.3 de Applied Cryptography by Schneier (ISBN 0-471-11709-9) de Schneier (ISBN 0-471-11709-9) pour plus de détails sur le sujet).

# Fonctions Mcrypt

# mcrypt_create_iv

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_create_iv — Crée un vecteur d'initialisation (IV) à partir d'une source aléatoire

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0.

Les alternatives à cette fonction incluent :

- random_bytes()

### Description

function mcrypt_create_iv(int `$size`, int `$source` = MCRYPT_DEV_URANDOM): string

mcrypt_create_iv() crée un IV (vecteur d'initialisation) à partir d'une source aléatoire.

Le vecteur d'initialisation est le seul moyen de fournir une initialisation de remplacement aux méthodes d'initialisation. Ce vecteur n'a pas besoin d'être particulièrement secret, même si c'est mieux. Il est possible de l'envoyer avec les documents chiffrés sans perdre en sécurité.

### Liste de paramètres

`size`
  La taille du vecteur.
`source`
  La source d'un IV. La source peut être `MCRYPT_RAND` (le générateur de nombre aléatoire du système), `MCRYPT_DEV_RANDOM` (lit les données depuis /dev/random) et `MCRYPT_DEV_URANDOM` (lit les données depuis /dev/urandom). Avant la version 5.3.0, `MCRYPT_RAND` était la seule constante supportée par Windows. À noter que la valeur par défaut de ce paramètre était `MCRYPT_DEV_RANDOM` avant PHP 5.6.0.

  > Note: À noter que la constante `MCRYPT_DEV_RANDOM` peut se bloquer en attendant que plus d'entropie ne soit disponible.

### Valeurs de retour

Retourne le vecteur d'initialisation, ou bien `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec mcrypt_create_iv()

    <?php
         $size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
         $iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);
         ?>

### Voir aussi

- » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
- » http://www.quadibloc.com/crypto/co0409.htm
- Chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9)
- random_bytes() - Récupère des octets aléatoires cryptographiquement sécurisés

# mcrypt_decrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_decrypt — Déchiffre un texte avec les paramètres donnés

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_decrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

Déchiffre les données `data` et retourne les données déchiffrées.

### Liste de paramètres

`cipher`
  Une constante parmi les constantes `MCRYPT_ciphername`, ou le nom de l'algorithme, sous la forme d'une chaîne de caractères.
`key`
  La clé utilisée lors du chiffrement des données. Si la taille de la clé fournie n'est pas supportée par le cipher, la fonction émettra un warning et retournera `false`
`data`
  Les données qui seront déchiffrées en utilisant les paramètres `cipher` et `mode`. Si la taille des données ne correspond pas à n * la taille du bloc, les données seront complétées par des '`\0`'.
`mode`
  Une constantes parmi les constantes `MCRYPT_MODE_modename`, ou une des chaînes suivantes : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
`iv`
  Utilisé pour l'initialisation des modes CBC, CFB, OFB, ainsi que dans quelques algorithmes du mode STREAM. Si la taille de l'IV fourni n'est pas supporté par le mode d'opération ou si vous ne fournissez pas d'IV, mais que le mode d'opération en requiert un, la fonction émettra un avertissement et retournera `false`.

### Valeurs de retour

Retourne les données déchiffrées sous la forme d'une chaîne de caractères ou `false` si une erreur survient.

### Voir aussi

- mcrypt_encrypt() - Chiffre un texte

# mcrypt_enc_get_algorithms_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_algorithms_name — Retourne le nom de l'algorithme de chiffrement

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_get_algorithms_name(resource `$td`): string

mcrypt_enc_get_algorithms_name() retourne le nom de l'algorithme utilisé par `td`.

### Liste de paramètres

`td`
  La ressource de chiffrement.

### Valeurs de retour

Retourne le nom de l'algorithme courant, sous forme de chaîne de caractères

### Exemples

Exemple #1 Exemple avec mcrypt_enc_get_algorithms_name()

    <?php
         $td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
         echo mcrypt_enc_get_algorithms_name($td). "\n";

         $td = mcrypt_module_open ('cast-256', '', MCRYPT_MODE_CFB, '');
         echo mcrypt_enc_get_algorithms_name($td). "\n";
         ?>

L'exemple ci-dessus va afficher :

    CAST-256
    CAST-256

# mcrypt_enc_get_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_block_size — Retourne la taille du bloc d'un algorithme

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_get_block_size(resource `$td`): int

Récupère la taille du bloc d'un algorithme.

### Liste de paramètres

`td`
  Le pointeur de fichiers.

### Valeurs de retour

Retourne la taille du bloc de l'algorithme, en octets.

# mcrypt_enc_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_iv_size — Retourne la taille du VI d'un algorithme

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_get_iv_size(resource `$td`): int

Cette fonction retourne la taille du VI de l'algorithme désigné par `td`, en octets. Si la valeur retournée est 0, c'est que l'algorithme ne demande pas de VI. Un VI est demandé en mode `"cbc"`, `"cfb"` et `"ofb"`, et parfois en mode `"stream"`.

### Liste de paramètres

`td`
  Le pointeur de fichiers.

### Valeurs de retour

Retourne la taille du IV, ou `0` si l'IV est ignoré par l'algorithme.

# mcrypt_enc_get_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_key_size — Retourne la taille maximale de la clé pour un mode

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_get_key_size(resource `$td`): int

Retourne la taille maximale de la clé pour un mode donné.

### Liste de paramètres

`td`
  Le pointeur de fichier.

### Valeurs de retour

Retourne la taille maximale de la clé pour le mode donné.

# mcrypt_enc_get_modes_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_modes_name — Retourne le nom du mode

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_get_modes_name(resource `$td`): string

Retourne le nom du mode.

### Liste de paramètres

`td`
  La ressource de chiffrement.

### Valeurs de retour

Retourne le nom, sous la forme d'une chaîne de caractères.

### Exemples

Exemple #1 Exemple avec mcrypt_enc_get_modes_name()

    <?php
    $td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_modes_name($td). "\n";

    $td = mcrypt_module_open ('cast-256', '', 'ecb', '');
    echo mcrypt_enc_get_modes_name($td). "\n";
    ?>

L'exemple ci-dessus va afficher :

    CFB
    ECB

# mcrypt_enc_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_supported_key_sizes — Retourne un tableau contenant les tailles de clés acceptées par un algorithme

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_get_supported_key_sizes(resource `$td`): array

mcrypt_enc_get_supported_key_sizes() lit les tailles de clés supportées par l'algorithme courant de la ressource de chiffrement `td`.

### Liste de paramètres

`td`
  La ressource de chiffrement.

### Valeurs de retour

Retourne un tableau contenant les tailles des clés supportées par l'algorithme désigné par `td`. S'il retourne un tableau vide, c'est que toutes les clés entre 1 et mcrypt_enc_get_key_size() sont acceptées par l'algorithme.

### Exemples

Exemple #1 Exemple avec mcrypt_enc_get_supported_key_sizes()

    <?php
        $td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
        var_dump(mcrypt_enc_get_supported_key_sizes($td));
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
      [0]=>
      int(16)
      [1]=>
      int(24)
      [2]=>
      int(32)
    }

# mcrypt_enc_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm — Teste le chiffrement par blocs d'un algorithme

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_is_block_algorithm(resource `$td`): bool

Teste le chiffrement par blocs d'un algorithme.

### Liste de paramètres

`td`
  La ressource de chiffrement.

### Valeurs de retour

Retourne `true` si l'algorithme utilisé est un algorithme par blocs, et `false` si c'est un algorithme par flux.

# mcrypt_enc_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm_mode — Teste le chiffrement par blocs d'un mode

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_is_block_algorithm_mode(resource `$td`): bool

Teste le chiffrement par blocs d'un mode (p. ex. `false` pour un flux, et `true` pour `"cbc"`, `"cfb"`, `"ofb"`).

### Liste de paramètres

`td`
  La ressource de chiffrement.

### Valeurs de retour

Retourne `true` si ce mode utilise des algorithmes par blocs, et `false` sinon.

# mcrypt_enc_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_mode — Teste si le mode retourne les données par blocs

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_is_block_mode(resource `$td`): bool

Teste si le mode retourne les données par blocs (p. ex. `true` pour `"cbc"` et `"ecb"`, et `false` pour `"cfb"` et un flux).

### Liste de paramètres

`td`
  La ressource de chiffrement.

### Valeurs de retour

Retourne `true` si le mode retourne des blocs d'octets, ou bien `false` s'il ne retourne que des octets.

# mcrypt_enc_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_self_test — Teste un module ouvert

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_enc_self_test(resource `$td`): int

Effectue un test du module ouvert et désigné par `td`.

### Liste de paramètres

`td`
  La ressource de chiffrement.

### Valeurs de retour

Retourne `0` en cas de succès ou un entier négatif en cas d'échec.

# mcrypt_encrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_encrypt — Chiffre un texte

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_encrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

mcrypt_encrypt() chiffre les données, et retourne les données chiffrées.

### Liste de paramètres

`cipher`
  Une constante parmi les constantes `MCRYPT_ciphername`, ou le nom de l'algorithme, sous la forme d'une chaîne de caractères.
`key`
  La clé avec laquelle les données seront chiffrées. Si la taille de la clé fournie n'est pas supportée par le cipher, la fonction émettra un warning et retournera `false`
`data`
  Les données qui seront chiffrées, avec le `cipher` et le `mode` indiqué. Si la taille des données n'est pas un multiple de la taille de bloc, les données seront complétées par des caractères '`\0`', autant que nécessaire. Le texte chiffré retourné peut être plus long que la taille des données passées en argument via `data`.
`mode`
  Une constantes parmi les constantes `MCRYPT_MODE_modename`, ou une des chaînes suivantes : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
`iv`
  Utilisé pour l'initialisation des modes CBC, CFB, OFB, ainsi que dans quelques algorithmes du mode STREAM. Si la taille de l'IV fourni n'est pas supporté par le mode d'opération ou si vous ne fournissez pas d'IV, mais que le mode d'opération en requiert un, la fonction émettra un avertissement et retournera `false`.

### Valeurs de retour

Retourne les données chiffrées, sous forme de chaîne de caractères ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mcrypt_encrypt()

    <?php
        # --- CHIFFREMENT ---

        # la clé devrait être un binaire aléatoire, utiliser la fonction scrypt, bcrypt
        # ou PBKDF2 pour convertir une chaîne de caractères en une clé.
        # La clé est spécifiée en utilisant une notation hexadécimale.
        $key = pack('H*', "bcb04b7e103a0cd8b54763051cef08bc55abe029fdebae5e1d417e2ffb2a00a3");

        # Montre la taille de la clé utilisée ; soit des clés sur 16, 24 ou 32 octets pour
        # AES-128, 192 et 256 respectivement.
        $key_size =  strlen($key);
        echo "Taille de la clé : " . $key_size . "\n";

        $plaintext = "Cette chaîne de caractère a été chiffrée en AES-256 / CBC / ZeroBytePadding.";

        # Crée un IV aléatoire à utiliser avec l'encodage CBC
        $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
        $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

        # Crée un texte cipher compatible avec AES (Rijndael block size = 128)
        # pour conserver le texte confidentiel.
        # Uniquement applicable pour les entrées encodées qui ne se terminent jamais
        # pas la valeur 00h (en raison de la suppression par défaut des zéros finaux)
        $ciphertext = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key,
                                     $plaintext, MCRYPT_MODE_CBC, $iv);

        # On ajoute le IV au début du texte chiffré pour le rendre disponible pour le déchiffrement
        $ciphertext = $iv . $ciphertext;

        # Encode le texte chiffré résultant pour qu'il puisse être représenté par une chaîne de caractères
        $ciphertext_base64 = base64_encode($ciphertext);

        echo  $ciphertext_base64 . "\n";

        # === ATTENTION ===

        # Le texte chiffré résultant ne contient aucune intégrité ni d'authentification
        # et il n'est pas protégé contre des attaques de type "oracle padding".

        # --- DECHIFFREMENT ---

        $ciphertext_dec = base64_decode($ciphertext_base64);

        # Récupère le IV, iv_size doit avoir été créé en utilisant la fonction
        # mcrypt_get_iv_size()
        $iv_dec = substr($ciphertext_dec, 0, $iv_size);

        # Récupère le texte du cipher (tout, sauf $iv_size du début)
        $ciphertext_dec = substr($ciphertext_dec, $iv_size);

        # On doit supprimer les caractères de valeur 00h de la fin du texte plein
        $plaintext_dec = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key,
                                        $ciphertext_dec, MCRYPT_MODE_CBC, $iv_dec);

        echo  $plaintext_dec . "\n";
    ?>

L'exemple ci-dessus va afficher :

    Taille de la clé : 32
    ENJW8mS2KaJoNB5E5CoSAAu0xARgsR1bdzFWpEn+poYw45q+73az5kYi4j+0haevext1dGrcW8Qi59txfCBV8BBj3bzRP3dFCp3CPQSJ8eU=
    Cette chaîne de caractère a été chiffrée en AES-256 / CBC / ZeroBytePadding.

### Voir aussi

- mcrypt_decrypt() - Déchiffre un texte avec les paramètres donnés
- mcrypt_module_open() - Ouvre le module de l'algorithme et du mode à utiliser

# mcrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic — Chiffre les données

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_generic(resource `$td`, string `$data`): string

mcrypt_generic() chiffre les données `data`. Les données sont complétées par des "`\0`" pour obtenir une taille multiple de la taille d'un bloc. Elle retourne les données chiffrées. À noter que la longueur de la chaîne retournée peut être plus longue que celle passée en argument, à cause du complément.

Pour enregistrer les données chiffrées dans une base de données il faut s'assurer d'enregistrer la chaîne entière retournée par cette fonction, sinon la chaîne ne sera pas déchiffrée correctement. Si la chaîne d'origine comporte 10 caractères et que la taille d'un bloc est de 8 (utiliser mcrypt_enc_get_block_size() pour déterminer cette taille), on aura besoin d'au moins 16 caractères dans le champ de la base de données. À noter que la chaîne retournée par mdecrypt_generic() aura 16 caractères de long... utiliser `rtrim($str, "\0")` pour supprimer le complément.

Par exemple, si on enregistre les données dans une base de données MySQL, il faut se souvenir que les champs de type VARCHAR suppriment automatiquement les espaces en trop durant l'insertion. Comme les données chiffrées peuvent se terminer avec un espace (ASCII 32), les données seront endommagées par cette suppression. Stockez les données dans un champ de type TINYBLOB/TINYTEXT (ou plus grand) pour que tout fonctionne normalement.

### Liste de paramètres

`td`
  La ressource de chiffrement. Le gestionnaire de chiffrement `td` doit être initialisé avec la fonction mcrypt_generic_init(), avec une clé et un VI, avant d'appeler cette fonction. Lorsque le chiffrement est réalisé, il faut libérer les buffers en appelant la fonction mcrypt_generic_deinit(). Voir mcrypt_module_open() pour un exemple.
`data`
  Les données à chiffrer.

### Valeurs de retour

Retourne les données chiffrées.

### Voir aussi

- mdecrypt_generic() - Déchiffre les données
- mcrypt_generic_init() - Initialise tous les tampons nécessaires
- mcrypt_generic_deinit() - Prépare le module pour le déchargement

# mcrypt_generic_deinit

(PHP 4 >= 4.0.7, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_deinit — Prépare le module pour le déchargement

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_generic_deinit(resource `$td`): bool

Prépare le module de chiffrement `td` pour le déchargement. Tous les tampons sont vidés, mais le module n'est pas déchargé. Il faut appeler mcrypt_module_close() soi-même (mais PHP le fera automatiquement à la fin du script).

### Liste de paramètres

`td`
  La ressource de chiffrement.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- mcrypt_module_open() - Ouvre le module de l'algorithme et du mode à utiliser
- mcrypt_generic_init() - Initialise tous les tampons nécessaires

# mcrypt_generic_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_init — Initialise tous les tampons nécessaires

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_generic_init(resource `$td`, string `$key`, string `$iv`): int

Il faut appeler mcrypt_generic_init() avant chaque appel à mcrypt_generic() ou mdecrypt_generic().

### Liste de paramètres

`td`
  La ressource de chiffrement.
`key`
  La taille maximale de la clé doit être celle retournée par mcrypt_enc_get_key_size() et toutes les valeurs inférieures seront aussi valides.
`iv`
  Le vecteur d'initialisation (VI) doit avoir la taille d'un bloc, mais il faut lire sa taille en appelant mcrypt_enc_get_iv_size(). IV est ignoré en mode ECB. IV DOIT exister en modes `"CFB"`, `"CBC"`, `"STREAM"`, `"nOFB"` et `"OFB"`. Il doit être aléatoire et unique (mais pas secret). Le même VI doit être utilisé pour le chiffrement et le déchiffrement. Si l'on ne veut pas l'utiliser, il suffit de le remplir de zéros, mais ce n'est pas recommandé.

### Valeurs de retour

Retourne une valeur négative en cas d'erreur : -3 si la taille de la clé est incorrecte, -4 quand il y a eu un problème d'allocation de mémoire et toute autre valeur en cas d'erreur inconnue. Si une erreur survient, une alerte est affichée. `false` est retourné si des paramètres incorrects sont passés à la fonction.

### Voir aussi

- mcrypt_module_open() - Ouvre le module de l'algorithme et du mode à utiliser

# mcrypt_get_block_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_block_size — Retourne la taille de blocs d'un chiffrement

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_get_block_size(int `$cipher`): int|false
function mcrypt_get_block_size(string `$cipher`, string `$mode`): int|false

Le premier prototype sert lorsque PHP est compilé avec la bibliothèque libmcrypt 2.2.x, le second lorsqu'il est compilé avec libmcrypt 2.4.x ou 2.5.x.

mcrypt_get_block_size() sert à lire la taille de blocs du chiffrement `cipher` (en combinaison avec un mode de chiffrement).

Il est recommandé de se servir de la fonction mcrypt_enc_get_block_size(), car elle utilise la ressource retournée par mcrypt_module_open().

### Liste de paramètres

`cipher`
  Une constante parmi les constantes `MCRYPT_ciphername`, ou le nom de l'algorithme, sous la forme d'une chaîne de caractères.
`mode`
  Une constantes parmi les constantes `MCRYPT_MODE_modename`, ou une des chaînes suivantes : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".

### Valeurs de retour

Lit la taille de bloc, sous forme d'un entier.

### Exemples

Exemple #1 Exemple avec mcrypt_get_block_size()

Cet exemple montre comment utiliser cette fonction lorsque PHP est compilé avec libmcrypt 2.4.x et 2.5.x.

    <?php
    echo mcrypt_get_block_size('tripledes', 'ecb'); // 8
    ?>

### Voir aussi

- mcrypt_get_key_size() - Retourne la taille de la clé de chiffrement
- mcrypt_enc_get_block_size() - Retourne la taille du bloc d'un algorithme
- mcrypt_encrypt() - Chiffre un texte

# mcrypt_get_cipher_name

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_cipher_name — Lit le nom du chiffrement utilisé

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_get_cipher_name(int `$cipher`): string
function mcrypt_get_cipher_name(string `$cipher`): string

mcrypt_get_cipher_name() retourne le nom du chiffrement utilisé.

mcrypt_get_cipher_name() prend le numéro de chiffrement (avec libmcrypt 2.2.x) ou prend le nom du chiffrement (avec libmcrypt 2.4.x) comme paramètre, et retourne le nom du chiffrement, ou `false`, s'il n'existe pas.

### Liste de paramètres

`cipher`
  Une constante parmi les constantes `MCRYPT_ciphername`, ou le nom de l'algorithme, sous la forme d'une chaîne de caractères.

### Valeurs de retour

Cette fonction retourne le nom du cipher ou `false` si le cipher n'existe pas.

### Exemples

Exemple #1 Exemple avec mcrypt_get_cipher_name()

    <?php
    $cipher = MCRYPT_TripleDES;

    echo mcrypt_get_cipher_name($cipher);
    ?>

L'exemple ci-dessus va afficher :

    3DES

# mcrypt_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_iv_size — Retourne la taille du VI utilisé par un couple chiffrement/mode

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_get_iv_size(string `$cipher`, string `$mode`): int

mcrypt_get_iv_size() retourne la taille du vecteur d'initialisation (VI). Si l'algorithme n'utilise pas de vecteur d'initialisation, zéro est retourné.

Il est plus utile d'utiliser la fonction mcrypt_enc_get_iv_size(), car elle utilise la ressource retournée par mcrypt_module_open().

### Liste de paramètres

`cipher`
  Une constante parmi les constantes `MCRYPT_ciphername`, ou le nom de l'algorithme, sous la forme d'une chaîne de caractères.
`mode`
  Une constantes parmi les constantes `MCRYPT_MODE_modename`, ou une des chaînes suivantes : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream". IV est ignoré en mode ECB sachant que ce mode ne le demande pas. Il faut avoir le même IV (point de départ) lors du chiffrement et du déchiffrement, sinon, le chiffrement échouera.

### Valeurs de retour

Retourne la taille du vecteur d'initialisation (IV), en octets. En cas d'erreur, la fonction retourne `false`. Si le vecteur d'initialisation est inutile, 0 est retourné.

### Exemples

Exemple #1 Exemple avec mcrypt_get_iv_size()

    <?php
    echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";

    echo mcrypt_get_iv_size('des', 'ecb') . "\n";
    ?>

### Voir aussi

- mcrypt_get_block_size() - Retourne la taille de blocs d'un chiffrement
- mcrypt_enc_get_iv_size() - Retourne la taille du VI d'un algorithme
- mcrypt_create_iv() - Crée un vecteur d'initialisation (IV) à partir d'une source aléatoire

# mcrypt_get_key_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_key_size — Retourne la taille de la clé de chiffrement

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_get_key_size(int `$cipher`): int|false
function mcrypt_get_key_size(string `$cipher`, string `$mode`): int|false

La première syntaxe utilise libmcrypt 2.2.x, et la seconde libmcrypt 2.4.x ou plus récent.

mcrypt_get_key_size() sert à lire la taille de clé du chiffrement `cipher`.

Il est plus intéressant d'utiliser la fonction mcrypt_enc_get_key_size() sachant qu'elle utilise la ressource retournée par la fonction mcrypt_module_open().

### Liste de paramètres

`cipher`
  Une constante parmi les constantes `MCRYPT_ciphername`, ou le nom de l'algorithme, sous la forme d'une chaîne de caractères.
`mode`
  Une constantes parmi les constantes `MCRYPT_MODE_modename`, ou une des chaînes suivantes : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".

### Valeurs de retour

Retourne la taille maximale supportée pour une clé de l'algorithme, en octets ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mcrypt_get_key_size()

    <?php
    echo mcrypt_get_key_size('tripledes', 'ecb');
    ?>

L'exemple ci-dessus montre l'utilisation de la fonction lorsqu'elle a été compilée avec la bibliothèque 2.4.x ou 2.5.x.

L'exemple ci-dessus va afficher :

    24

### Voir aussi

- mcrypt_get_block_size() - Retourne la taille de blocs d'un chiffrement
- mcrypt_enc_get_key_size() - Retourne la taille maximale de la clé pour un mode
- mcrypt_encrypt() - Chiffre un texte

# mcrypt_list_algorithms

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_algorithms — Liste tous les algorithmes de chiffrement supportés

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_list_algorithms(string `$lib_dir` = ini_get("mcrypt.algorithms_dir")): array

Liste tous les algorithmes de chiffrement de `lib_dir`.

### Liste de paramètres

`lib_dir`
  Spécifie le dossier où les algorithmes sont situés. Si omis, la valeur de la directive `mcrypt.algorithms_dir` du fichier php.ini est utilisée.

### Valeurs de retour

Retourne un tableau avec les algorithmes supportés.

### Exemples

Exemple #1 Exemple avec mcrypt_list_algorithms()

    <?php
    $algorithms = mcrypt_list_algorithms();
    print_r($algorithms);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => cast-128
        [1] => gost
        [2] => rijndael-128
        [3] => twofish
        [4] => arcfour
        [5] => cast-256
        [6] => loki97
        [7] => rijndael-192
        [8] => saferplus
        [9] => wake
        [10] => blowfish-compat
        [11] => des
        [12] => rijndael-256
        [13] => serpent
        [14] => xtea
        [15] => blowfish
        [16] => enigma
        [17] => rc2
        [18] => tripledes
    )

# mcrypt_list_modes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_modes — Liste tous les modes de chiffrement supportés

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_list_modes(string `$lib_dir` = ini_get("mcrypt.modes_dir")): array

Liste tous les modes de chiffrement de `lib_dir`.

### Liste de paramètres

`lib_dir`
  Spécifie le dossier où tous les modes sont situés. Si omis, la valeur de la directive `mcrypt.modes_dir` dans le php.ini est utilisée.

### Valeurs de retour

Retourne un tableau avec tous les modes supportés.

### Exemples

Exemple #1 Exemple avec mcrypt_list_modes()

    <?php
    $modes = mcrypt_list_modes();

    foreach ($modes as $mode) {
        echo "$mode <br />\n";
    }
    ?>

L'exemple ci-dessus va afficher tous les modes supportés dans le dossier par défaut. Si le mode n'est pas défini par la directive `mcrypt.modes_dir` du php.ini, le dossier par défaut de mcrypt sera utilisé (soit le dossier /usr/local/lib/libmcrypt).

# mcrypt_module_close

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_close — Décharge le module de chiffrement

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_module_close(resource `$td`): bool

Décharge le module `td`.

### Liste de paramètres

`td`
  La ressource de chiffrement.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- mcrypt_module_open() - Ouvre le module de l'algorithme et du mode à utiliser

# mcrypt_module_get_algo_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_block_size — Retourne la taille de blocs d'un algorithme

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_module_get_algo_block_size(string `$algorithm`, string `$lib_dir` = ?): int

Retourne la taille de blocs d'un algorithme.

### Liste de paramètres

`algorithm`
  Le nom de l'algorithme.
`lib_dir`
  Le paramètre optionnel `lib_dir` contient le chemin jusqu'au module de l'algorithme sur le système.

### Valeurs de retour

Retourne la taille de blocs d'un algorithme, en octets.

# mcrypt_module_get_algo_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_key_size — Retourne la taille maximale de clé

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_module_get_algo_key_size(string `$algorithm`, string `$lib_dir` = ?): int

Retourne la taille maximale de clé.

### Liste de paramètres

`algorithm`
  Le nom de l'algorithme.
`lib_dir`
  Le paramètre optionnel `lib_dir` contient le chemin jusqu'au module de l'algorithme sur le système.

### Valeurs de retour

Retourne la taille maximale de la clé supportée par l'algorithme `algorithm`.

# mcrypt_module_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_supported_key_sizes — Retourne un tableau contenant les tailles de clés supportées par l'algorithme ouvert

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_module_get_supported_key_sizes(string `$algorithm`, string `$lib_dir` = ?): array

Retourne un tableau contenant les tailles de clés supportées par l'algorithme de chiffrement `algorithm`. S'il retourne un tableau vide, alors toutes les clés entre 1 et mcrypt_module_get_algo_key_size() sont supportées par l'algorithme.

### Liste de paramètres

`algorithm`
  L'algorithme à utiliser.
`lib_dir`
  Le paramètre optionnel `lib_dir` peut contenir le chemin du dossier d'installation du module, sur le système.

### Valeurs de retour

Retourne un tableau contenant les tailles de clés supportées par l'algorithme de chiffrement `algorithm`. S'il retourne un tableau vide, alors toutes les clés entre 1 et mcrypt_module_get_algo_key_size() sont supportées par l'algorithme.

### Voir aussi

- mcrypt_enc_get_supported_key_sizes() - Retourne un tableau contenant les tailles de clés acceptées par un algorithme

# mcrypt_module_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm — Indique si un algorithme fonctionne par blocs

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_module_is_block_algorithm(string `$algorithm`, string `$lib_dir` = ?): bool

mcrypt_module_is_block_algorithm() retourne `true` si `algorithm` est un algorithme par blocs, ou `false` si c'est un algorithme par flux.

### Liste de paramètres

`algorithm`
  L'algorithme à vérifier.
`lib_dir`
  Le paramètre optionnel `lib_dir` peut contenir le chemin où se trouvent les modules des algorithmes sur le disque système.

### Valeurs de retour

Retourne `true` si l'algorithme spécifié est un algorithme par blocs ou `false` si c'est un algorithme par flux.

# mcrypt_module_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm_mode — Indique si un mode fonctionne par blocs

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_module_is_block_algorithm_mode(string `$mode`, string `$lib_dir` = ?): bool

Cette fonction retourne `true` si le mode doit être utilisé avec un algorithme par bloc, sinon, elle retourne `false` (c.-à-d. `false` pour un flux, et `true` pour cbc, cfb, ofb).

### Liste de paramètres

`mode`
  Le mode à vérifier.
`lib_dir`
  Le paramètre optionnel `lib_dir` peut contenir le dossier où les modules d'algorithme se trouvent sur le système.

### Valeurs de retour

Cette fonction retourne `true` si le mode doit être utilisé avec un algorithme par bloc, sinon, elle retourne `false` (c.-à-d. `false` pour un flux, et `true` pour cbc, cfb, ofb).

# mcrypt_module_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_mode — Indique si un mode travaille par blocs

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_module_is_block_mode(string `$mode`, string `$lib_dir` = ?): bool

Cette fonction retourne `true` si ce mode fournit des blocs d'octets ou `false` s'il ne sort que des octets. (c.-à-d. `true` pour `"cbc"` et `"ecb"`, et `false` pour `"cfb"` et `"stream"`).

### Liste de paramètres

`mode`
  Une constantes parmi les constantes `MCRYPT_MODE_modename`, ou une des chaînes suivantes : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
`lib_dir`
  Le paramètre optionnel `lib_dir` contient le chemin jusqu'au module de l'algorithme sur le système.

### Valeurs de retour

Cette fonction retourne `true` si ce mode fournit des blocs d'octets ou `false` s'il ne sort que des octets. (c.-à-d. `true` pour `"cbc"` et `"ecb"`, et `false` pour `"cfb"` et `"stream"`).

# mcrypt_module_open

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_open — Ouvre le module de l'algorithme et du mode à utiliser

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_module_open(
string `$algorithm`,
string `$algorithm_directory`,
string `$mode`,
string `$mode_directory`
): resource

mcrypt_module_open() ouvre le module de l'algorithme et du mode à utiliser. Le nom de l'algorithme est spécifié par le paramètre `algorithm` (par exemple : `"twofish"`), ou bien une des constantes `MCRYPT_ciphername`. La bibliothèque est refermée en appelant mcrypt_module_close().

### Liste de paramètres

`algorithm`
  Une constante parmi les constantes `MCRYPT_ciphername`, ou le nom de l'algorithme, sous la forme d'une chaîne de caractères.
`algorithm_directory`
  Le paramètre `algorithm_directory` est utilisé pour localiser le module de chiffrement. Lorsqu'on spécifie un nom de dossier, il sera utilisé. Si on spécifie une chaîne vide (`""`), la valeur définie dans la directive `mcrypt.algorithms_dir` du fichier php.ini sera utilisée. Lorsqu'elle n'est pas définie, le dossier par défaut utilisé sera celui dans lequel se trouve la bibliothèque libmcrypt (habituellement, /usr/local/lib/libmcrypt).
`mode`
  Une constantes parmi les constantes `MCRYPT_MODE_modename`, ou une des chaînes suivantes : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
`mode_directory`
  Le paramètre `mode_directory` est utilisé pour localiser le module de chiffrement. Si un nom de dossier est spécifié, il sera utilisé. Lorsqu'on spécifie une chaîne vide (`""`), la valeur de la directive `mcrypt.modes_dir` du fichier php.ini sera utilisée. Si elle n'est pas définie, le dossier par défaut utilisé sera celui dans lequel se trouve la bibliothèque libmcrypt (habituellement /usr/local/lib/libmcrypt).

### Valeurs de retour

Normalement, cette fonction retourne un descripteur de chiffrement, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mcrypt_module_open()

    <?php
    $td = mcrypt_module_open(MCRYPT_DES, '',
        MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');

    $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
    ?>

La première ligne de l'exemple ci-dessus va essayer d'ouvrir le chiffrement `DES`, dans le dossier par défaut, et le mode `ECB` dans le dossier /usr/lib/mcrypt-modes. Le second exemple utilise les chaînes comme nom pour le chiffrement et le mode. Cela ne fonctionne que si l'extension est compilée avec libmcrypt 2.4.x ou 2.5.x.

Exemple #2 Utilisation de mcrypt_module_open() pour chiffrer

    <?php
    /* Charge un chiffrement */
    $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');

    /* Crée le VI et détermine la taille de la clé */
    $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
    $ks = mcrypt_enc_get_key_size($td);

    /* Crée la clé (exemple uniquement : MD5 n'est pas un bon algorithme de hachage pour cela) */
    $key = substr(hash('md5', 'very secret key'), 0, $ks);

    /* Initialise le chiffrement */
    mcrypt_generic_init($td, $key, $iv);

    /* Chiffre les données */
    $encrypted = mcrypt_generic($td, 'This is very important data');

    /* Libère le gestionnaire de chiffrement */
    mcrypt_generic_deinit($td);

    /* Initialise le module de chiffrement pour le déchiffrement */
    mcrypt_generic_init($td, $key, $iv);

    /* Déchiffre les données */
    $decrypted = mdecrypt_generic($td, $encrypted);

    /* Libère le gestionnaire de déchiffrement, et ferme le module */
    mcrypt_generic_deinit($td);
    mcrypt_module_close($td);

    /* Affiche la chaîne */
    echo trim($decrypted)."\n";
    ?>

### Voir aussi

- mcrypt_module_close() - Décharge le module de chiffrement
- mcrypt_generic() - Chiffre les données
- mdecrypt_generic() - Déchiffre les données
- mcrypt_generic_init() - Initialise tous les tampons nécessaires
- mcrypt_generic_deinit() - Prépare le module pour le déchargement

# mcrypt_module_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_self_test — Teste un mode

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mcrypt_module_self_test(string `$algorithm`, string `$lib_dir` = ?): bool

Effectue un test sur l'algorithme spécifié.

### Liste de paramètres

`algorithm`
  Une constante parmi les constantes `MCRYPT_ciphername`, ou le nom de l'algorithme, sous la forme d'une chaîne de caractères.
`lib_dir`
  Le paramètre optionnel `lib_dir` contient le chemin jusqu'au module de l'algorithme sur le système.

### Valeurs de retour

Retourne `true` si le test fonctionne, et `false` sinon.

### Exemples

Exemple #1 Exemple avec mcrypt_module_self_test()

    <?php
    var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
    var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)

# mdecrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mdecrypt_generic — Déchiffre les données

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.1.0 et a été SUPPRIMÉE à partir de PHP 7.2.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function mdecrypt_generic(resource `$td`, string `$data`): string

Déchiffre les données `data`. À noter que la longueur de la chaîne déchiffrée peut être plus longue que la chaîne originale, car elle peut avoir été complétée par des caractères.

### Liste de paramètres

`td`
  Un descripteur de chiffrement, retourné par la fonction mcrypt_module_open()
`data`
  Les données chiffrées.

### Valeurs de retour

Retourne la chaîne déchiffrée.

### Exemples

Exemple #1 Exemple avec mdecrypt_generic()

    <?php
    /* Données */
    $key = 'Ceci est une très longue clé de chiffrement, et même trop longue';
    $plain_text = 'Ceci sont des données importantes';

    /* Ouvre le module et crée un VI */
    $td = mcrypt_module_open('des', '', 'ecb', '');
    $key = substr($key, 0, mcrypt_enc_get_key_size($td));
    $iv_size = mcrypt_enc_get_iv_size($td);
    $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

    /* Initialise le module de chiffrement */
    if (mcrypt_generic_init($td, $key, $iv) != -1) {

        /* Chiffre les données */
        $c_t = mcrypt_generic($td, $plain_text);
        mcrypt_generic_deinit($td);

        /* Réinitialise les tampons pour le déchiffrement */
        mcrypt_generic_init($td, $key, $iv);
        $p_t = mdecrypt_generic($td, $c_t);

        /* Nettoie */
        mcrypt_generic_deinit($td);
        mcrypt_module_close($td);
    }

    if (strncmp($p_t, $plain_text, strlen($plain_text)) == 0) {
        echo "ok\n";
    } else {
        echo "erreur\n";
    }
    ?>

L'exemple ci-dessus montre comment vérifier que les données avant chiffrement sont bien les mêmes que celles après chiffrement/déchiffrement. Il est très important de réinitialiser le buffer de chiffrement avec mcrypt_generic_init() avant de déchiffrer les données.

Le gestionnaire de déchiffrement doit toujours être initialisé par la fonction mcrypt_generic_init() avec une clé et un VI avant d'appeler cette fonction. Lorsque le chiffrement est fait, il faut qu'on libère les données chiffrées en appelant mcrypt_generic_deinit(). Voir mcrypt_module_open() pour un exemple.

### Voir aussi

- mcrypt_generic() - Chiffre les données
- mcrypt_generic_init() - Initialise tous les tampons nécessaires
- mcrypt_generic_deinit() - Prépare le module pour le déchargement

## Sommaire

- mcrypt_create_iv — Crée un vecteur d'initialisation (IV) à partir d'une source aléatoire
- mcrypt_decrypt — Déchiffre un texte avec les paramètres donnés
- mcrypt_enc_get_algorithms_name — Retourne le nom de l'algorithme de chiffrement
- mcrypt_enc_get_block_size — Retourne la taille du bloc d'un algorithme
- mcrypt_enc_get_iv_size — Retourne la taille du VI d'un algorithme
- mcrypt_enc_get_key_size — Retourne la taille maximale de la clé pour un mode
- mcrypt_enc_get_modes_name — Retourne le nom du mode
- mcrypt_enc_get_supported_key_sizes — Retourne un tableau contenant les tailles de clés acceptées par un algorithme
- mcrypt_enc_is_block_algorithm — Teste le chiffrement par blocs d'un algorithme
- mcrypt_enc_is_block_algorithm_mode — Teste le chiffrement par blocs d'un mode
- mcrypt_enc_is_block_mode — Teste si le mode retourne les données par blocs
- mcrypt_enc_self_test — Teste un module ouvert
- mcrypt_encrypt — Chiffre un texte
- mcrypt_generic — Chiffre les données
- mcrypt_generic_deinit — Prépare le module pour le déchargement
- mcrypt_generic_init — Initialise tous les tampons nécessaires
- mcrypt_get_block_size — Retourne la taille de blocs d'un chiffrement
- mcrypt_get_cipher_name — Lit le nom du chiffrement utilisé
- mcrypt_get_iv_size — Retourne la taille du VI utilisé par un couple chiffrement/mode
- mcrypt_get_key_size — Retourne la taille de la clé de chiffrement
- mcrypt_list_algorithms — Liste tous les algorithmes de chiffrement supportés
- mcrypt_list_modes — Liste tous les modes de chiffrement supportés
- mcrypt_module_close — Décharge le module de chiffrement
- mcrypt_module_get_algo_block_size — Retourne la taille de blocs d'un algorithme
- mcrypt_module_get_algo_key_size — Retourne la taille maximale de clé
- mcrypt_module_get_supported_key_sizes — Retourne un tableau contenant les tailles de clés supportées par l'algorithme ouvert
- mcrypt_module_is_block_algorithm — Indique si un algorithme fonctionne par blocs
- mcrypt_module_is_block_algorithm_mode — Indique si un mode fonctionne par blocs
- mcrypt_module_is_block_mode — Indique si un mode travaille par blocs
- mcrypt_module_open — Ouvre le module de l'algorithme et du mode à utiliser
- mcrypt_module_self_test — Teste un mode
- mdecrypt_generic — Déchiffre les données

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Chiffrements Mcrypt
- Fonctions Mcrypt
  - mcrypt_create_iv — Crée un vecteur d'initialisation (IV) à partir d'une source aléatoire
  - mcrypt_decrypt — Déchiffre un texte avec les paramètres donnés
  - mcrypt_enc_get_algorithms_name — Retourne le nom de l'algorithme de chiffrement
  - mcrypt_enc_get_block_size — Retourne la taille du bloc d'un algorithme
  - mcrypt_enc_get_iv_size — Retourne la taille du VI d'un algorithme
  - mcrypt_enc_get_key_size — Retourne la taille maximale de la clé pour un mode
  - mcrypt_enc_get_modes_name — Retourne le nom du mode
  - mcrypt_enc_get_supported_key_sizes — Retourne un tableau contenant les tailles de clés acceptées par un algorithme
  - mcrypt_enc_is_block_algorithm — Teste le chiffrement par blocs d'un algorithme
  - mcrypt_enc_is_block_algorithm_mode — Teste le chiffrement par blocs d'un mode
  - mcrypt_enc_is_block_mode — Teste si le mode retourne les données par blocs
  - mcrypt_enc_self_test — Teste un module ouvert
  - mcrypt_encrypt — Chiffre un texte
  - mcrypt_generic — Chiffre les données
  - mcrypt_generic_deinit — Prépare le module pour le déchargement
  - mcrypt_generic_init — Initialise tous les tampons nécessaires
  - mcrypt_get_block_size — Retourne la taille de blocs d'un chiffrement
  - mcrypt_get_cipher_name — Lit le nom du chiffrement utilisé
  - mcrypt_get_iv_size — Retourne la taille du VI utilisé par un couple chiffrement/mode
  - mcrypt_get_key_size — Retourne la taille de la clé de chiffrement
  - mcrypt_list_algorithms — Liste tous les algorithmes de chiffrement supportés
  - mcrypt_list_modes — Liste tous les modes de chiffrement supportés
  - mcrypt_module_close — Décharge le module de chiffrement
  - mcrypt_module_get_algo_block_size — Retourne la taille de blocs d'un algorithme
  - mcrypt_module_get_algo_key_size — Retourne la taille maximale de clé
  - mcrypt_module_get_supported_key_sizes — Retourne un tableau contenant les tailles de clés supportées par l'algorithme ouvert
  - mcrypt_module_is_block_algorithm — Indique si un algorithme fonctionne par blocs
  - mcrypt_module_is_block_algorithm_mode — Indique si un mode fonctionne par blocs
  - mcrypt_module_is_block_mode — Indique si un mode travaille par blocs
  - mcrypt_module_open — Ouvre le module de l'algorithme et du mode à utiliser
  - mcrypt_module_self_test — Teste un mode
  - mdecrypt_generic — Déchiffre les données

# Mhash

# Introduction

Ces fonctions ont été prévues pour fonctionner avec » mhash. Mhash peut être utilisé pour créer des sommes de contrôle, des condensés de messages, des codes d'authentification de messages et bien plus.

Cet ensemble de fonctions représente une interface avec la bibliothèque mhash. Mhash accepte un grand nombre d'algorithmes différents, tels MD5, SHA1, GOST et bien d'autres. Pour une liste complète des hashes supportés, se reporter à la page sur les constantes. La règle générale est que l'on peut accéder à un algorithme à partir de PHP avec la constante `MHASH_hashname`. Par exemple, pour accéder à l'algorithme TIGER, il est possible d'utiliser la constante PHP `MHASH_TIGER`.

> Note:

> Cette extension est obsolète. Il convient d'utiliser l'extension Hash à la place.

> Note:

> À partir de PHP 7.0.0 l'extension Mhash a été complètement intégrée dans l'extension Hash. Par conséquent il n'est plus possible de détecter le support de Mhash grâce à extension_loaded() ; utiliser function_exists() à la place. De plus, Mhash n'est plus signalé par get_loaded_extensions() et les fonctionnalités liées.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Pour l'utiliser, télécharger les distributions de mhash depuis ce » site internet et suivre les instructions d'installation incluses.

## Installation

On aura besoin de compiler PHP avec l'option --with-mhash[=DIR] pour activer cette extension. DIR est le chemin du dossier d'installation de la bibliothèque MHASH.

À partir de PHP 5.3.0, l'extension mhash est émulée via l'extension Hash. Aussi, l'option permettant de spécifier le dossier d'installation de mhash n'a plus d'effet, et cette extension nécessite l'installation de l'extension hash pour fonctionner.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Voici une liste des modes qui sont supportés par mhash. Si un mode n'est pas listé ici, mais listé dans la documentation mhash comme étant supporté, il est possible de considérer que cette liste n'est plus à jour.

`MHASH_ADLER32` (int)
`MHASH_CRC32` (int)
`MHASH_CRC32B` (int)
`MHASH_CRC32C` (int)
  Disponible à partir de PHP 7.4.0.
`MHASH_FNV132` (int)
`MHASH_FNV1A32` (int)
`MHASH_FNV164` (int)
`MHASH_FNV1A64` (int)
`MHASH_GOST` (int)
`MHASH_HAVAL128` (int)
`MHASH_HAVAL160` (int)
`MHASH_HAVAL192` (int)
`MHASH_HAVAL224` (int)
`MHASH_HAVAL256` (int)
`MHASH_JOAAT` (int)
`MHASH_MD2` (int)
`MHASH_MD4` (int)
`MHASH_MD5` (int)
`MHASH_MURMUR3A` (int)
  Disponible à partir de PHP 8.1.0.
`MHASH_MURMUR3C` (int)
  Disponible à partir de PHP 8.1.0.
`MHASH_MURMUR3F` (int)
  Disponible à partir de PHP 8.1.0.
`MHASH_RIPEMD128` (int)
`MHASH_RIPEMD160` (int)
`MHASH_RIPEMD256` (int)
`MHASH_RIPEMD320` (int)
`MHASH_SHA1` (int)
`MHASH_SHA224` (int)
`MHASH_SHA256` (int)
`MHASH_SHA384` (int)
`MHASH_SHA512` (int)
`MHASH_SNEFRU256` (int)
`MHASH_TIGER` (int)
`MHASH_TIGER128` (int)
`MHASH_TIGER160` (int)
`MHASH_WHIRLPOOL` (int)
`MHASH_XXH32` (int)
`MHASH_XXH64` (int)
`MHASH_XXH3` (int)
`MHASH_XXH128` (int)

# Exemples

Exemple #1 Calcule le MD5 et le hmac, puis l'affiche comme un hexadécimal

    <?php
    $input = "what do ya want for nothing?";
    $hash = mhash(MHASH_MD5, $input);
    echo "Le hash vaut " . bin2hex($hash) . "<br />\n";
    $hash = mhash(MHASH_MD5, $input, "Jefe");
    echo "Le hmac vaut " . bin2hex($hash) . "<br />\n";
    ?>

L'exemple ci-dessus va afficher :

    Le hash vaut d03cb659cbf9192dcd066272249f8412
    Le hmac vaut 750c783e6ab0b503eaa86e310a5db738

# Fonctions Mhash

# mhash

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash — Calcule un hash

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function mhash(int `$algo`, string `$data`, ?string `$key` = null): string|false

mhash() applique la fonction de hash `algo` aux données `data`.

### Liste de paramètres

`algo`

  L'identifiant du hash. Une parmi les constantes `MHASH_hashname`.

`data`

  L'entrée utilisateur, sous la forme d'une chaîne de caractères.

`key`

  Si spécifié, la fonction retournera le HMAC résultant à la place. HMAC est un hachage à clé utilisé pour l'authentification de messages, ou simplement un condensé de message qui dépend de la clé spécifiée. Certains algorithmes supportés dans mhash ne sont pas compatibles avec le mode HMAC.

### Valeurs de retour

Retourne le hash résultant (appelé aussi "digest") ou HMAC, sous la forme d'une chaîne de caractères ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Cette fonction a été rendue obsolète. Utiliser les fonctions `hash_*()` à la place.
8.0.0 | `key` est désormais nullable.

# mhash_count

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_count — Récupère l'identifiant maximal de hash

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function mhash_count(): int

Récupère l'identifiant maximal de hash.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'identifiant de hash maximal. Les hashs sont numérotés de 0 jusqu'à cet identifiant.

### Historique

Version | Description
--- | ---
8.1.0 | Cette fonction a été rendue obsolète. Utiliser les fonctions `hash_*()` à la place.

### Exemples

Exemple #1 Parcourir la liste des hash

    <?php

    $nr = mhash_count();

    for ($i = 0; $i <= $nr; $i++) {
        echo sprintf("La taille de bloc de %s est %d\n",
            mhash_get_hash_name($i),
            mhash_get_block_size($i));
    }
    ?>

# mhash_get_block_size

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_block_size — Retourne la taille de bloc du hash

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function mhash_get_block_size(int `$algo`): int|false

Retourne la taille de bloc de l'`algo` spécifié.

### Liste de paramètres

`algo`

  L'identifiant du hash. Une des constantes `MHASH_hashname`.

### Valeurs de retour

Retourne la taille, en octets, ou `false` si l'`algo` n'existe pas.

### Historique

Version | Description
--- | ---
8.1.0 | Cette fonction a été rendue obsolète. Utiliser les fonctions `hash_*()` à la place.

### Exemples

Exemple #1 Exemple avec mhash_get_block_size()

    <?php

    echo mhash_get_block_size(MHASH_MD5); // 16

    ?>

# mhash_get_hash_name

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_hash_name — Retourne le nom du hash

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function mhash_get_hash_name(int `$algo`): string|false

Retourne le nom de l'`algo` spécifié.

### Liste de paramètres

`algo`

  L'identifiant du hash. Une des constantes `MHASH_hashname`.

### Valeurs de retour

Retourne le nom du hash ou `false` si le hash n'existe pas.

### Historique

Version | Description
--- | ---
8.1.0 | Cette fonction a été rendue obsolète. Utiliser les fonctions `hash_*()` à la place.

### Exemples

Exemple #1 Exemple avec mhash_get_hash_name()

    <?php

    echo mhash_get_hash_name(MHASH_MD5); // MD5

    ?>

# mhash_keygen_s2k

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

mhash_keygen_s2k — Génère une clé

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function mhash_keygen_s2k(
int `$algo`,
string `$password`,
string `$salt`,
int `$length`
): string|false

Génère une clé suivant l'`algo` fourni, en utilisant le mot de passe `password` fourni.

Cette fonction utilise l'algorithme `Salted S2K`, spécifié dans OpenPGP (» RFC 2440).

Il est à noter que les mots de passe fournis par les utilisateurs ne sont pas conseillés pour faire des clés cryptographiques, étant donné que les utilisateurs choisissent normalement des clés qu'ils peuvent saisir au clavier. Ces clés utilisent uniquement 6 à 7 des 8 bits d'un caractère (voire moins). Il est vivement recommandé d'appliquer une fonction de transformation (comme celle-ci) à la clé fournie par l'utilisateur.

### Liste de paramètres

`algo`

  L'identifiant du hash utilisé pour créer la clé. Une parmi les constantes `MHASH_hashname`.

`password`

  Mot de passe fourni par l'utilisateur.

`salt`

  Doit être différent et suffisamment aléatoire pour chaque clé qu'on génère, afin de créer des clés différentes. Du fait que le paramètre `salt` doit être connu lorsqu'on vérifie les clés, c'est une bonne idée d'y ajouter la clé. Le paramètre salt doit avoir une longueur de 8 octets, et sera complété de zéros si l'on en fournit un d'une taille inférieure.

`length`

  La longueur de la clé, en octets.

### Valeurs de retour

Retourne la clé générée, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Cette fonction a été rendue obsolète. Utiliser les fonctions `hash_*()` à la place.

## Sommaire

- mhash — Calcule un hash
- mhash_count — Récupère l'identifiant maximal de hash
- mhash_get_block_size — Retourne la taille de bloc du hash
- mhash_get_hash_name — Retourne le nom du hash
- mhash_keygen_s2k — Génère une clé

- Installation/Configuration
  - Pré-requis
  - Installation
- Constantes pré-définies
- Exemples
- Fonctions Mhash
  - mhash — Calcule un hash
  - mhash_count — Récupère l'identifiant maximal de hash
  - mhash_get_block_size — Retourne la taille de bloc du hash
  - mhash_get_hash_name — Retourne le nom du hash
  - mhash_keygen_s2k — Génère une clé

# OpenSSL

# Introduction

Cette extension lie des fonctions de la bibliothèque » OpenSSL pour le chiffrement et déchiffrement symétrique et asymétrique, PBKDF2, PKCS7, PKCS12, X509 et autres opérations cryptographiques. De plus elle fournit une implémentation de flux TLS.

OpenSSL offre beaucoup de fonctionnalités que ce module n'offre pas actuellement. Quelques-unes pourront être ajoutées dans le futur.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Afin de pouvoir utiliser les fonctions OpenSSL, il faut installer la bibliothèque » OpenSSL. PHP 7.0 nécessite OpenSSL >= 0.9.8, < 1.2. PHP 7.1-8.0 nécessitent OpenSSL >= 1.0.1, < 3.0. PHP >= 8.1 nécessite OpenSSL >= 1.0.2, < 4.0. PHP >= 8.4 nécessite OpenSSL >= 1.1.1, < 4.0.

Avertissement

On est vivement encouragé à utiliser la version maintenue d'OpenSSL afin d'éviter certaines vulnérabilités sur le serveur web.

## Installation

Pour utiliser le support OpenSSL de PHP, il faut aussi compiler PHP avec l'option de configuration --with-openssl.

La bibliothèque OpenSSL possède aussi des dépendances à l'exécution. Par exemple, OpenSSL a besoin d'accéder à un générateur de nombres pseudo-aléatoires; sur la plupart des plateformes Unix (incluant donc Linux), elle doit avoir accès au périphérique `/dev/urandom` ou `/dev/random`.

L'option de configuration --with-system-ciphers est disponible qui fait que PHP utilise la liste de chiffrement système au lieu des valeurs par défaut codées en dur.

> Note: Note aux utilisateurs Win32

> Afin de faire fonctionner cette extension, quelques bibliothèques DLL doivent être disponibles via le PATH du système Windows. Lisez la F.A.Q intitulée "Comment ajouter mon dossier PHP à mon PATH Windows" pour plus d'informations. Le fait de copier les bibliothèques DLL depuis le dossier PHP dans le dossier système Windows fonctionne également (car le dossier système est par défaut dans le PATH système), mais cette méthode n'est pas recommandée. Cette extension nécessite que les fichiers suivants se trouvent dans le PATH : libeay32.dll, ou, à partir d'OpenSSL 1.1, libcrypto-*.dll

> De plus, si on a prévu d'utiliser les fonctions relatives à la génération de clés et aux certificats, il faut installer un fichier openssl.cnf valide sur le système. Un fichier de configuration de base est inclus dans les distributions de PHP pour win32 dans le dossier extras/ssl.

> PHP va rechercher le fichier openssl.cnf suivant la tactique suivante :

> - La variable d'environnement OPENSSL_CONF, si elle est définie, sera utilisée comme chemin (comprenant le fichier) vers le fichier de configuration.
> - La variable d'environnement SSLEAY_CONF, si elle est définie, sera utilisée comme chemin (comprenant le fichier) vers le fichier de configuration.
> - Le fichier openssl.cnf sera supposé se trouver dans le dossier des certificats, tel que configuré lors de la compilation de la bibliothèque openssl. Cela signifie généralement C:\Program Files\Common Files\SSL\openssl.cnf (x64) ou C:\Program Files (x86)\Common Files\SSL\openssl.cnf (x86), ou, avant PHP 7.4.0, c:\usr\local\ssl\openssl.cnf.
> Dans l'installation, il faudra décider si on va installer le fichier de configuration dans le chemin par défaut ou si on va le faire ailleurs et configurer une variable d'environnement (possiblement par site virtuel). À noter qu'il est possible de remplacer le chemin par défaut en utilisant le paramètre `options` des fonctions qui requièrent un fichier de configuration.
> Attention

> Veiller à ce que les utilisateurs non privilégiés ne soient pas autorisés à modifier openssl.cnf.

> À partir d'OpenSSL 3.0.0, qui est utilisé par défaut sur Windows à partir de PHP 8.2.0, plusieurs algorithmes ont été jugés obsolètes. Ces algorithmes sont souvent tombés en désuétude, ont été considérés comme non sécurisés par la communauté cryptographique, ou quelque chose de similaire. Ces algorithmes sont encore disponibles via le fournisseur d'algorithmes legacy (extras/ssl/legacy.dll) ; son utilisation est décrite dans la section » configuration du fournisseur du manuel OpenSSL.

### Historique

Version | Description
--- | ---
7.4.0 | L'option --with-openssl[=DIR] n'accepte plus d'argument de répertoire en faveur du réglage de la variable pkg-config PKG_CONFIG_PATH vers l'emplacement d'OpenSSL, ou en spécifiant les variables OPENSSL_LIBS et OPENSSL_CFLAGS.
7.4.0 | Le chemin de configuration par défaut d'OpenSSL a été modifié de C:\usr\local\ssl à C:\Program Files\Common Files\SSL et C:\Program Files (x86)\Common Files\SSL, respectivement.

## Configuration à l'exécution

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

openssl Options de configuration
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
openssl.cafile | "" | `INI_PERDIR` |
openssl.capath | "" | `INI_PERDIR` |
openssl.libctx | "custom" | `INI_PERDIR` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`openssl.cafile` string

  Emplacement du fichier Certificate Authority sur le système de fichier local qui devrait être utilisé avec l'option de contexte verify_peer pour authentifier l'identité du pair distant.

`openssl.capath` string

  Si cafile n'est pas spécifié ou si le certificat n'y est pas trouvé, le dossier pointé par capath est fouillé pour un certificat convenable. capath doit être un répertoire de certificat correctement haché.

`openssl.libctx` string
  Spécifie le type de contexte de bibliothèque OpenSSL à utiliser. La valeur par défaut, `custom`, crée un contexte de bibliothèque séparé pour chaque worker ou thread. Cela améliore l'isolation des autres bibliothèques utilisant OpenSSL et, dans les versions ZTS, augmente la séparation entre les threads. Il est également possible d'utiliser la valeur `default`, qui fait que PHP utilise le contexte de bibliothèque global par défaut d'OpenSSL.

Voir aussi les options du contexte de flux SSL.

## Types de ressources

Antérieur à PHP 8.0.0, il y avait 3 types de ressources définis dans le module OpenSSL :

- `OpenSSL key`
- `OpenSSL X.509`
- `OpenSSL X.509 CSR`

# Constantes pré-définies

## Sommaire

- Options de validations générales
- Options de remplissage (Padding) pour le chiffrement asymétrique
- Types de clés
- Constantes/options PKCS7
- Drapeaux/Constantes CMS
- Algorithmes de signature
- Chiffrements
- Constantes de version
- Constantes d'identification du nom de serveur
- Autres constantes

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

## Options de validations générales

`X509_PURPOSE_SSL_CLIENT` (int)
`X509_PURPOSE_SSL_SERVER` (int)
`X509_PURPOSE_NS_SSL_SERVER` (int)
`X509_PURPOSE_SMIME_SIGN` (int)
`X509_PURPOSE_SMIME_ENCRYPT` (int)
`X509_PURPOSE_CRL_SIGN` (int)
`X509_PURPOSE_ANY` (int)
`X509_PURPOSE_OCSP_HELPER` (int)
  Vérifie le certificat pour une utilisation comme assistant de répondeur OCSP. Disponible à partir de PHP 8.4.0.
`X509_PURPOSE_TIMESTAMP_SIGN` (int)
  Vérifie le certificat pour une utilisation comme signataire d'horodatage de confiance. Disponible à partir de PHP 8.4.0.

## Options de remplissage (`Padding`) pour le chiffrement asymétrique

`OPENSSL_PKCS1_PADDING` (int)
`OPENSSL_SSLV23_PADDING` (int)
`OPENSSL_NO_PADDING` (int)
`OPENSSL_PKCS1_OAEP_PADDING` (int)
`OPENSSL_PKCS1_PSS_PADDING` (int)
  Remplissage RSA-PSS. Disponible à partir de PHP 8.5.0.

## Types de clés

`OPENSSL_KEYTYPE_RSA` (int)
  Type de clé RSA.
`OPENSSL_KEYTYPE_DSA` (int)
  Type de clé DSA.
`OPENSSL_KEYTYPE_DH` (int)
  Type de clé DH (Diffie-Hellman).
`OPENSSL_KEYTYPE_EC` (int)
  Type de clé à courbe elliptique.
`OPENSSL_KEYTYPE_X25519` (int)
  Type de clé à courbe X25519. Cette constante n'est disponible que lorsque PHP est compilé avec OpenSSL 3.0+.
`OPENSSL_KEYTYPE_ED25519` (int)
  Type de clé à courbe Ed25519. Cette constante n'est disponible que lorsque PHP est compilé avec OpenSSL 3.0+.
`OPENSSL_KEYTYPE_X448` (int)
  Type de clé à courbe X448. Cette constante n'est disponible que lorsque PHP est compilé avec OpenSSL 3.0+.
`OPENSSL_KEYTYPE_ED448` (int)
  Type de clé à courbe Ed448. Cette constante n'est disponible que lorsque PHP est compilé avec OpenSSL 3.0+.

## Constantes/options PKCS7

Les fonctions S/MIME utilisent des options qui sont spécifiées par un champ de bits. Les valeurs valides sont :

Constantes PKCS7
Constante | Description
--- | ---
`PKCS7_TEXT` (int) | Ajoute le texte plein en clair dans les en-têtes du message signé/chiffré. Lors du déchiffrement ou de la vérification, il supprime purement et simplement ces données. Si le message chiffré ou signé n'est pas du type MIME, une erreur surviendra.
`PKCS7_BINARY` (int) | Normalement, le message est converti au format canonique qui utilise effectivement des `CR` et `LF` comme fin de ligne, comme demandé dans les spécifications de S/MIME. Lorsque cette option est activée, le message ne sera pas converti. Cela sert lorsqu'on manipule des données binaires qui ne sont pas au format MIME.
`PKCS7_NOINTERN` (int) | Lors de la vérification d'un message, les certificats (s'il y en a) inclus dans le message sont normalement utilisés pour rechercher le certificat de signature. Avec cette option, seul le certificat spécifié par le paramètre `untrusted_certificates_filename` de la fonction openssl_pkcs7_verify() est utilisé. Les certificats fournis peuvent toujours être utilisés, avec un niveau de confiance réduit.
`PKCS7_NOVERIFY` (int) | Ne vérifie pas les certificats des signataires d'un message signé.
`PKCS7_NOCHAIN` (int) | N'enchaîne pas les vérifications des signataires de certificats. C'est-à-dire, n'utilise pas les certificats contenus dans le message.
`PKCS7_NOCERTS` (int) | Lors de la signature d'un message, le certificat du signataire est normalement inclus. Avec cette option, c'est désactivé. Cela va réduire la taille du message, mais le vérificateur devra avoir une copie locale du certificat du signataire (passée au paramètre `untrusted_certificates_filename`, avec la fonction openssl_pkcs7_verify()).
`PKCS7_NOATTR` (int) | Normalement, lorsqu'un message est signé, un jeu d'attributs contenant l'heure de signature et l'algorithme symétrique supportés, est inclus dans le message. Avec cette option, il n'est pas inclus.
`PKCS7_DETACHED` (int) | Lors de la signature d'un message, utilise la signature en texte clair, avec le type MIME `"multipart/signed"`. C'est la valeur par défaut du paramètre `flags` pour la fonction openssl_pkcs7_sign(). Si on annule cette option, le message sera signé de manière opaque, ce qui résiste mieux à la traduction des relais mail (certains anciens serveurs mail corrompent les messages), mais empêche la lecture par les clients emails qui ne connaissent pas S/MIME.
`PKCS7_NOSIGS` (int) | Ne vérifie pas les signatures d'un message
`PKCS7_NOOLDMIMETYPE` (int) | Disponible à partir de PHP 8.3.0. Définit l'en-tête HTTP Content-Type sur `application/pkcs7-mime` au lieu de `application/x-pkcs7-mime` pour chiffrer un message.
`PKCS7_NOSMIMECAP` (int) | Disponible à partir de PHP 8.5.0. N'inclut pas les capacités S/MIME (SMIMECapabilities) dans la signature.
`PKCS7_CRLFEOL` (int) | Disponible à partir de PHP 8.5.0. Utilise `CRLF` comme fin de ligne dans la sortie.
`PKCS7_NOCRL` (int) | Disponible à partir de PHP 8.5.0. N'inclut pas les CRL dans la structure PKCS7.
`PKCS7_NO_DUAL_CONTENT` (int) | Disponible à partir de PHP 8.5.0. N'inclut pas le contenu en double, évitant la duplication du contenu signé.

## Drapeaux/Constantes CMS

Les fonctions CMS utilisent des drapeaux qui sont spécifiés en utilisant un masque de bit qui inclut une ou plusieurs des valeurs suivantes :

Constantes CMS
Constantes | Description
--- | ---
`OPENSSL_CMS_TEXT` (int) | Ajoute l'en-tête content type `text/plain` au message chiffré/signé. Lors du déchiffrement/vérification, ces en-têtes sont enlevés de la sortie, si le message déchiffré ou vérifié n'est pas du type MIME `text/plain` alors une erreur surviendra.
`OPENSSL_CMS_BINARY` (int) | Normalement le message d'entrée est converti en sa forme "canonique" qui en réalité utilise `CR` et `LF` comme fin de ligne: tel que requis par la spécification CMS. Quand cette option est présente, aucune translation n'est effectuée. Ceci est utile lors de la gestion de données binaires qui peuvent ne pas être en format CMS.
`OPENSSL_CMS_NOINTERN` (int) | Lors de la vérification d'un message, les certificats (le cas échéant) inclus dans le message sont normalement recherchés pour le certificat de signature. Avec cette option, seuls les certificats spécifiés dans le paramètre `untrusted_certificates_filename` de openssl_cms_verify() sont utilisés. Les certificats fournis peuvent cependant toujours être utilisés comme des autorités de certification non fiables.
`OPENSSL_CMS_NOVERIFY` (int) | Ne vérifie pas le certificat du signataire d'un message signé.
`OPENSSL_CMS_NOCERTS` (int) | Lors de la signature d'un message le certificat du signataire est normalement inclus, avec cette option il est exclus. Ceci réduira la taille du message signé mais le vérificateur doit avoir une copie du certificat du signataire disponible localement (passé en utilisant `untrusted_certificates_filename` de openssl_cms_verify() par exemple).
`OPENSSL_CMS_NOATTR` (int) | Normalement, quand un message est signé, un jeu d'attributs est inclus qui comprend l'heure de signature et les algorithmes symétriques supportés. Avec cette option ils ne sont pas inclus.
`OPENSSL_CMS_DETACHED` (int) | Lors de la signature d'un message, la signature en clair est utilisée avec le MIME type `"multipart/signed"`. Ceci est le comportement par défaut, si l'on ne spécifie aucun `flags` à openssl_cms_sign(). Si l'on désactive cette option, le message sera signé en utilisant une signature opaque, qui est plus résistante à la translation par les relais mail mais ne peut pas être lu par les agents mail qui ne prennent pas en charge S/MIME.
`OPENSSL_CMS_NOSIGS` (int) | Ne tente pas de vérifier les signatures d'un message
`OPENSSL_CMS_OLDMIMETYPE` (int) | Disponible à partir de PHP 8.3.0. Définit l'en-tête HTTP Content-Type sur `application/x-pkcs7-mime` au lieu de `application/pkcs7-mime` pour chiffrer un message.

## Algorithmes de signature

`OPENSSL_ALGO_DSS1` (int)
`OPENSSL_ALGO_SHA1` (int)
  Utilisé comme algorithme par défaut pour les fonctions openssl_sign() et openssl_verify().
`OPENSSL_ALGO_SHA224` (int)
`OPENSSL_ALGO_SHA256` (int)
`OPENSSL_ALGO_SHA384` (int)
`OPENSSL_ALGO_SHA512` (int)
`OPENSSL_ALGO_RMD160` (int)
`OPENSSL_ALGO_MD5` (int)
`OPENSSL_ALGO_MD4` (int)
`OPENSSL_ALGO_MD2` (int)
  Cette constante n'est disponible que lorsque PHP est compilé avec le support MD2. Il est nécessaire de passer le CFLAG `-DHAVE_OPENSSL_MD2_H` lors de la compilation de PHP et de passer `enable-md2` lors de la compilation d'OpenSSL 1.0.0+.

## Chiffrements

`OPENSSL_DEFAULT_STREAM_CIPHERS` (string)
  Liste des chiffrements par défaut.
`OPENSSL_CIPHER_RC2_40` (int)
`OPENSSL_CIPHER_RC2_128` (int)
`OPENSSL_CIPHER_RC2_64` (int)
`OPENSSL_CIPHER_DES` (int)
`OPENSSL_CIPHER_3DES` (int)

`OPENSSL_CIPHER_AES_128_CBC` (int)
`OPENSSL_CIPHER_AES_192_CBC` (int)
`OPENSSL_CIPHER_AES_256_CBC` (int)

## Constantes de version

`OPENSSL_VERSION_TEXT` (string)
`OPENSSL_VERSION_NUMBER` (int)

## Constantes d'identification du nom de serveur

`OPENSSL_TLSEXT_SERVER_NAME` (int)
  Si le support SNI est disponible ou non.

> Note:

> Cette constante n'est disponible que lorsque PHP est compilé avec OpenSSL 0.9.8j ou ultérieur

## Autres constantes

`OPENSSL_RAW_DATA` (int)
  Si `OPENSSL_RAW_DATA` est définie dans openssl_encrypt() ou openssl_decrypt(), les données retournées sont retournées telles quelles. Quand ceci n'est pas spécifié, les données retournées à l'appeleur sont encodées en Base64.
`OPENSSL_DONT_ZERO_PAD_KEY` (int)
  Empêche openssl_encrypt() de remplir les clés qui sont plus courtes que la longueur de clé par défaut.
`OPENSSL_ZERO_PADDING` (int)
  Par défaut, les opérations de chiffrement sont complétées en utilisant des blocs standards et la complétion est vérifiée et supprimée lors du déchiffrement. Si la constante `OPENSSL_ZERO_PADDING` est définie dans le paramètre `options` de la fonction openssl_encrypt() ou openssl_decrypt() alors aucune complétion ne sera réalisée, la quantité totale de données chiffrées devra alors être un multiple de la taille du bloc ou bien une erreur surviendra.
`OPENSSL_ENCODING_SMIME` (int)
  Indique que l'encodage est S/MIME.
`OPENSSL_ENCODING_DER` (int)
  Indique que l'encodage est DER (Distinguished Encoding Rules).
`OPENSSL_ENCODING_PEM` (int)
  Indique que l'encodage est PEM (Privacy-Enhanced Mail).

# Paramètres clés/certificats

Un bon nombre de fonctions OpenSSL exigent une clé ou un certificat comme paramètres. Les méthodes suivantes peuvent être utilisées pour les récupérer:

- Certificats

  1. Une instance de OpenSSLCertificate (ou antérieur à PHP 8.0.0, une resource de type `OpenSSL X.509`) retournée par openssl_x509_read()
  2. Une chaîne au format file://path/to/cert.pem; Le fichier ainsi repéré doit contenir un certificat, encodé au format PEM.
  3. Une chaîne contenant le contenu d'un certificat, encodé au format PEM, peut commencer par `-----BEGIN CERTIFICATE-----`.

- Demandes de signature de certificat (Certificate Signing Requests abrévié CSRs)

  1. Une instance de OpenSSLCertificateSigningRequest (ou antérieur à PHP 8.0.0, une resource de type `OpenSSL X.509 CSR`) retournée par openssl_csr_new()
  2. Une chaîne de caractères ayant le format file://path/to/csr.pem ; le fichier nommé doit contenir un CSR encodé au format PEM.
  3. Une chaîne de caractères contenant le contenu d'un CSR, encodé au format PEM, peut commencer par `-----BEGIN CERTIFICATE REQUEST-----`.

- Clés publiques/privées

  1. Une instance de OpenSSLAsymmetricKey (ou antérieur à PHP 8.0.0, une resource de type `OpenSSL key`) retournée par openssl_get_publickey() ou openssl_get_privatekey()
  2. Pour les clés publiques uniquement : une instance de OpenSSLCertificate (ou antérieur à PHP 8.0.0, une resource de type `OpenSSL X.509`)
  3. Une chaîne avec le format : file://path/to/file.pem. Le fichier doit contenir une clé privée, ou un certificat, encodé au format PEM (il peut contenir les deux).
  4. Une chaîne de caractères contenant le contenu d'un certificat/clé, encodé au format PEM, peut commencer par `-----BEGIN PUBLIC KEY-----`.
  5. Pour les clés privées, il est également possible d'utiliser la syntaxe `array($key, $passphrase)`, où $key représente une clé spécifiée par un fichier ou une représentation textuelle comme cité ci-dessus, et $passphrase représente une chaîne contenant la phrase de passe de cette clé privée.

# Vérification de certificats

Lorsqu'on appelle une fonction qui va vérifier une signature ou un certificat, le paramètre `ca_info` doit être un tableau contenant les noms d'un dossier et d'un fichier indiquant les tiers de confiance. Si un dossier est spécifié, il doit être correct, car openssl va l'utiliser.

# Fonctions OpenSSL

# openssl_cipher_iv_length

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

openssl_cipher_iv_length — Récupère la longueur cipher iv

### Description

function openssl_cipher_iv_length(string `$cipher_algo`): int|false

Récupère la longueur cipher du vecteur d'initialisation.

### Liste de paramètres

`cipher_algo`

  La méthode cipher, voir la fonction openssl_get_cipher_methods() pour une liste de valeurs potentielles.

### Valeurs de retour

Retourne la longueur cipher en cas de succès, ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` lorsque l'algorithme cipher est inconnu.

### Exemples

Exemple #1 Exemple avec openssl_cipher_iv_length()

    <?php
    $method = 'AES-128-CBC';
    $ivlen = openssl_cipher_iv_length($method);

    echo $ivlen;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    16

# openssl_cipher_key_length

(PHP 8 >= 8.2.0)

openssl_cipher_key_length — Renvoie la longueur de la clé de chiffrement

### Description

function openssl_cipher_key_length(string `$cipher_algo`): int|false

Renvoie la longueur de la clé de chiffrement.

### Liste de paramètres

`cipher_algo`

  La méthode de chiffrement, voir openssl_get_cipher_methods() pour une liste de valeurs potentielles.

### Valeurs de retour

Renvoie la longueur de la clé de chiffrement en cas de succès, ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` lorsque l'algorithme de chiffrement est inconnu.

### Exemples

Exemple #1 Exemple de openssl_cipher_key_length()

    <?php
    $method = 'AES-128-CBC';

    var_dump(openssl_cipher_key_length($method));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(16)

# openssl_cms_decrypt

(PHP 8)

openssl_cms_decrypt — Déchiffre un message CMS

### Description

function openssl_cms_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

Déchiffre un message CMS.

### Liste de paramètres

`input_filename`

  Le nom d'un fichier contenant un contenu chiffré.

`output_filename`

  Le nom du fichier pour déposer le contenu déchiffré.

`certificate`

  Le nom du fichier contenant un certificat du destinataire.

`private_key`

  Le nom du fichier contenant une clé PKCS#8.

`encoding`

  L'encodage du fichier d'entrée. Une des constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` ou `OPENSSL_ENCODING_PEM`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# openssl_cms_encrypt

(PHP 8)

openssl_cms_encrypt — Chiffre un message CMS

### Description

function openssl_cms_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
string|int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

Cette fonction chiffre le contenu pour un ou plusieurs destinataires, basé sur les certificats qui lui sont passés.

### Liste de paramètres

`input_filename`

  Le fichier à chiffrer.

`output_filename`

  Le fichier de sortie.

`certificate`

  Les destinataires pour lesquels chiffrer.

`headers`

  Les en-têtes à inclure lors de l'utilisation de S/MIME.

`flags`

  Les drapeaux à passer à CMS_sign.

`encoding`

  Un encodage de sortie. Une des constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` ou `OPENSSL_ENCODING_PEM`.

`cipher_algo`

  Le chiffrement à utiliser.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | `cipher_algo` est maintenant de type int ou string. Précédemment, il était de type int.
8.1.0 | L'algorithme de chiffrement par défaut (`cipher_algo`) est maintenant AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`). Précédemment, PKCS7/CMS était utilisé (`OPENSSL_CIPHER_RC2_40`).

# openssl_cms_read

(PHP 8)

openssl_cms_read — Exporte le fichier CMS vers un tableau de certificats PEM

### Description

function openssl_cms_read(string `$input_filename`, array `&$certificates`): bool

Effectue l'opération équivalente de openssl_pkcs7_read().

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`input_filename`

`certificates`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# openssl_cms_sign

(PHP 8)

openssl_cms_sign — Signe un fichier

### Description

function openssl_cms_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
?string `$untrusted_certificates_filename` = `null`
): bool

Cette fonction signe un fichier avec un certificat X.509 et une clé.

### Liste de paramètres

`input_filename`

  Le nom du fichier à signer.

`output_filename`

  Le nom du fichier pour déposer les résultats.

`certificate`

  Le certificat de signature. Voir Paramètres de clé/certificat pour une liste de valeurs valides.

`private_key`

  La clé associée au `certificate`. Voir Paramètres de clé/certificat pour une liste de valeurs valides.

`headers`

  Un tableau d'en-têtes à inclure dans la sortie S/MIME.

`flags`

  Les drapeaux à passer à cms_sign().

`encoding`

  L'encodage du fichier de sortie. Une des constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` ou `OPENSSL_ENCODING_PEM`.

`untrusted_certificates_filename`

  Les certificats intermédiaires à inclure dans la signature.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de openssl_cms_sign()

    <?php

    openssl_cms_sign('input.txt', 'output.txt', 'file://cert.pem', 'file://privkey.pem', null, OPENSSL_CMS_BINARY, OPENSSL_ENCODING_DER, 'chain.pem');
    ?>

# openssl_cms_verify

(PHP 8)

openssl_cms_verify — Vérifie une signature CMS

### Description

function openssl_cms_verify(
string `$input_filename`,
int `$flags` = 0,
?string `$certificates` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$pk7` = `null`,
?string `$sigfile` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

Cette fonction vérifie une signature CMS, qu'elle soit attachée ou détachée, avec l'encodage spécifié.

### Liste de paramètres

`input_filename`

  Le fichier d'entrée.

`flags`

  Les drapeaux à passer à cms_verify().

`certificates`

  Un fichier avec le certificat du signataire et éventuellement des certificats intermédiaires.

`ca_info`

  Un tableau contenant des certificats d'autorité auto-signés.

`untrusted_certificates_filename`

  Un fichier contenant des certificats intermédiaires supplémentaires.

`content`

  Un fichier pointant vers le contenu lorsque les signatures sont détachées.

`pk7`

`sigfile`

  Un fichier pour sauvegarder la signature.

`encoding`

  L'encodage du fichier d'entrée. Une des constantes `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` ou `OPENSSL_ENCODING_PEM`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# openssl_csr_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export — Exporte un CSR vers un fichier ou une variable

### Description

function openssl_csr_export(OpenSSLCertificateSigningRequest|string `$csr`, string `&$output`, bool `$no_text` = `true`): bool

openssl_csr_export() prend la demande de signature de certificat représentée par `CSR` et la stocke au format PEM dans `output`, qui est passé par référence.

### Liste de paramètres

`csr`
  Voir les paramètres CSR pour obtenir une liste des valeurs valides.
`output`

  en cas de succès, cette chaîne contiendra le CSR encodé en PEM

`no_text`
  Le paramètre optionnel `notext` affecte le niveau verbeux de l'affichage ; s'il vaut `false`, des informations humainement lisibles seront ajoutées dans l'affichage. Par défaut, le paramètre `notext` vaut `true`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `csr` accepte désormais une instance de OpenSSLCertificateSigningRequest ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.

### Exemples

Exemple #1 openssl_csr_export() example

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha256WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $private_key, $configargs);
    openssl_csr_export($csr, $csr_string);
    echo $csr_string;
    ?>

### Voir aussi

- openssl_csr_export_to_file() - Exporte une CSR vers un fichier
- openssl_csr_new() - Génère une CSR
- openssl_csr_sign() - Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat

# openssl_csr_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export_to_file — Exporte une CSR vers un fichier

### Description

function openssl_csr_export_to_file(OpenSSLCertificateSigningRequest|string `$csr`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_csr_export_to_file() prend la CSR représentée par le paramètre `csr` et la sauve au format PEM dans le fichier nommé `output_filename`.

### Liste de paramètres

`csr`
  Voir les paramètres CSR pour obtenir une liste des valeurs valides.
`output_filename`

  Chemin vers le fichier de sortie.

`no_text`
  Le paramètre optionnel `notext` affecte le niveau verbeux de l'affichage ; s'il vaut `false`, des informations humainement lisibles seront ajoutées dans l'affichage. Par défaut, le paramètre `notext` vaut `true`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `csr` accepte désormais une instance de OpenSSLCertificateSigningRequest ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.

### Exemples

Exemple #1 openssl_csr_export_to_file() example

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384') );
    openssl_pkey_export_to_file($private_key, 'example-priv.key');
    // En même temps que le sujet, la CSR contient la clé publique correspondant à la clé privée
    openssl_csr_export_to_file($csr, 'example-csr.pem');
    ?>

### Voir aussi

- openssl_csr_export() - Exporte un CSR vers un fichier ou une variable
- openssl_csr_new() - Génère une CSR
- openssl_csr_sign() - Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat

# openssl_csr_get_public_key

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_public_key — Retourne la clé publique d'un CSR

### Description

function openssl_csr_get_public_key(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): OpenSSLAsymmetricKey|false

openssl_csr_get_public_key() extrait la clé publique de la `csr` et la prépare pour une utilisation par d'autres fonctions.

### Liste de paramètres

`csr`
  Voir les paramètres CSR pour obtenir une liste des valeurs valides.
`short_names`
  Avertissement

  Ce paramètre est ignoré

### Valeurs de retour

Retourne une OpenSSLAsymmetricKey en cas de succès, ou `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de OpenSSLAsymmetricKey ; auparavant une resource de type `OpenSSL key` était retournée.
8.0.0 | `csr` accepte désormais une instance de OpenSSLCertificateSigningRequest ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.

### Exemples

Exemple #1 openssl_csr_get_public_key() example

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha256') );
    $public_key = openssl_csr_get_public_key($csr);
    $info = openssl_pkey_get_details($public_key);
    echo $info['key'];
    ?>

### Voir aussi

- openssl_csr_get_subject() - Retourne le sujet d'une CSR
- openssl_csr_new() - Génère une CSR
- openssl_pkey_get_details() - Retourne un tableau contenant les détails de la clé
- openssl_pkey_export_to_file() - Sauve une clé au format ASCII dans un fichier
- openssl_pkey_export() - Stocke une représentation exportable de la clé dans une chaîne de caractères

# openssl_csr_get_subject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_subject — Retourne le sujet d'une CSR

### Description

function openssl_csr_get_subject(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): array|false

openssl_csr_get_subject() retourne les informations sur le nom distinctif du sujet codées dans le `csr`, y compris les champs commonName (CN), organizationName (O), countryName (C) etc.

### Liste de paramètres

`csr`
  Voir les paramètres CSR pour obtenir une liste des valeurs valides.
`short_names`

  `short_names` contrôle comment les données sont indexées dans le tableau - si `short_names` est `true` (par défaut) alors les champs seront indexés avec la forme courte du nom, sinon le nom complet sera utilisé - par exemple : CN est le nom court de commonName.

### Valeurs de retour

Retourne un tableau associatif avec la description du sujet, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `csr` accepte désormais une instance de OpenSSLCertificateSigningRequest ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.

### Exemples

Exemple #1 Exemple avec openssl_csr_get_subject()

    <?php
    $subject = array(
        "countryName" => "CA",
        "stateOrProvinceName" => "Alberta",
        "localityName" => "Calgary",
        "organizationName" => "XYZ Widgets Inc",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha512WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $privkey, $configargs);
    print_r(openssl_csr_get_subject($csr));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [C] => CA
        [ST] => Alberta
        [L] => Calgary
        [O] => XYZ Widgets Inc
        [OU] => PHP Documentation Team
        [CN] => Wez Furlong
        [emailAddress] => wez@example.com
    )

### Voir aussi

- openssl_csr_new() - Génère une CSR
- openssl_csr_get_public_key() - Retourne la clé publique d'un CSR
- openssl_x509_parse() - Analyse un certificat X509

# openssl_csr_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_new — Génère une CSR

### Description

function openssl_csr_new(
array `$distinguished_names`,
#[\SensitiveParameter]?OpenSSLAsymmetricKey `&$private_key`,
?array `$options` = `null`,
?array `$extra_attributes` = `null`
): OpenSSLCertificateSigningRequest|bool

openssl_csr_new() génère une nouvelle CSR (requête de signature de certificat), basée sur les informations apportées par `distinguished_names`.

> Note: Vous devez avoir un fichier openssl.cnf valide et installé pour que cette fonction opère correctement. Voir les notes se trouvant dans la section concernant l'installation pour plus d'informations.

### Liste de paramètres

`distinguished_names`

  Le nom distinctif (Distinguished Name) ou les champs du sujet à inclure dans le certificat. Le `distinguished_names` est un tableau associatif dont les clés représentent les noms d'attributs des Distinguished Names, et les valeurs peuvent être soit des chaînes (pour une valeur unique) soit des tableaux (si plusieurs valeurs doivent être définies).

`private_key`

  `private_key` doit être une clé privée qui a été générée par openssl_pkey_new() (ou obtenue autrement par l'une des fonctions de la famille openssl_pkey) , ou la variable `null`. Si sa valeur est une variable `null`, une nouvelle clé privée est générée en fonction des `options` fournies et assignée à la variable fournie. La partie publique correspondante de la clé sera utilisée pour signer le CSR.

`options`

  Par défaut, le fichier `openssl.conf` du système est utilisé pour initialiser la requête; il est possible de spécifier une section du fichier de configuration en paramétrant la clé `config_section_section` dans `options`. Il est également possible de spécifier un fichier de configuration OpenSSL alternatif en paramétrant la valeur de `config` avec le chemin du fichier à utiliser. Si les clés suivantes sont présentes dans `options`, elles se comportent comme leurs équivalents dans `openssl.conf`, selon la liste suivante.

  Écrasement de configuration
  `options` | type | Équivalent de `openssl.conf` | description
  --- | --- | --- | ---
  digest_alg | string | default_md | Méthode de digest ou signature de hachage, généralement un de openssl_get_md_methods()
  x509_extensions | string | x509_extensions | Sélectionne quelle extension utiliser lors de la création d'un certificat x509
  req_extensions | string | req_extensions | Sélectionne quelle extension utiliser lors de la création d'une CSR
  private_key_bits | int | default_bits | Spécifie la longueur en bits de la clé privée
  private_key_type | int | none | Spécifie le type de clé privée à créer. Cela peut être l'un de `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_RSA` ou `OPENSSL_KEYTYPE_EC`. La valeur par défaut est `OPENSSL_KEYTYPE_RSA`.
  encrypt_key | bool | encrypt_key | La clé (avec mot de passe) exportée doit-elle être chiffrée?
  encrypt_key_cipher | int | none | Une des constantes cipher.
  curve_name | string | none | Un de openssl_get_curve_names().
  config | string | N/A | Chemin vers le fichier openssl.conf alternatif.

`extra_attributes`

  `extra_attributes` est utilisé pour spécifier des attributs supplémentaires pour le CSR. Il s'agit d'un tableau associatif dont les clés sont converties en OID et appliquées comme attributs de CSR.

### Valeurs de retour

Retourne le CSR en cas de succès, `true` si la création du CSR réussit mais que la signature échoue ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le tableau associatif `distinguished_names` prend désormais en charge les tableaux en tant que valeurs, permettant de spécifier plusieurs valeurs pour un même attribut.
8.4.0 | Le paramètre `extra_attributes` définit désormais correctement les attributs du CSR, au lieu de modifier le nom distinctif du sujet comme il le faisait auparavant de manière incorrecte.
8.0.0 | `csr` accepte désormais une instance de OpenSSLCertificateSigningRequest ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de OpenSSLAsymmetricKey ; auparavant une resource de type `OpenSSL key` était retournée.
7.1.0 | `options` supporte désormais `curve_name`.

### Exemples

Exemple #1 Création d'un certificat autosigné

    <?php
    // pour les certificats SSL serveur, le commonName est le nom de domaine à sécuriser
    // pour les certificats e-mail S/MIME le commonName est le propriétaire de l'adresse e-mail
    // les champs d'emplacement et d'identification font référence au propriétaire du domaine ou à l'objet de l'e-mail à sécuriser
    $dn = array(
        "countryName" => "GB",
        "stateOrProvinceName" => "Somerset",
        "localityName" => "Glastonbury",
        "organizationName" => "The Brain Room Limited",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com"
    );

    // Génère une nouvelle paire de clés privée (et publique)
    $privkey = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));

    // Génère une requête de signature de certificat
    $csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

    // Génère un certificat autosigné, valide pour 365 jours
    $x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

    // Conservez votre clé privée, CSR et certificat autosigné pour une utilisation ultérieure
    openssl_csr_export($csr, $csrout) and var_dump($csrout);
    openssl_x509_export($x509, $certout) and var_dump($certout);
    openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);

    // Affiche les erreurs qui sont survenues
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

Exemple #2 Création d'un certificat ECC autosigné (à partir de PHP 7.1.0)

    <?php
    $subject = array(
        "commonName" => "docs.php.net",
    );

    // Génère une nouvelle paire de clés privée (et publique)
    $private_key = openssl_pkey_new(array(
        "private_key_type" => OPENSSL_KEYTYPE_EC,
        "curve_name" => 'prime256v1',
    ));

    // Génère une requête de signature de certificat
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

    // Génère un certificat EC autosigné
    $x509 = openssl_csr_sign($csr, null, $private_key, $days=365, array('digest_alg' => 'sha384'));
    openssl_x509_export_to_file($x509, 'ecc-cert.pem');
    openssl_pkey_export_to_file($private_key, 'ecc-private.key');
    ?>

### Voir aussi

- openssl_csr_sign() - Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat

# openssl_csr_sign

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_sign — Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat

### Description

function openssl_csr_sign(
OpenSSLCertificateSigningRequest|string `$csr`,
OpenSSLCertificate|string|null `$ca_certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$days`,
?array `$options` = `null`,
int `$serial` = 0,
?string `$serial_hex` = `null`
): OpenSSLCertificate|false

openssl_csr_sign() génère un certificat x509 depuis le CSR donnée.

> Note: Vous devez avoir un fichier openssl.cnf valide et installé pour que cette fonction opère correctement. Voir les notes se trouvant dans la section concernant l'installation pour plus d'informations.

### Liste de paramètres

`csr`

  Une CSR générée précédemment par openssl_csr_new(). Mais ceci peut aussi être le chemin vers une CSR encodée au format PEM si spécifiée avec file://path/to/csr ou une chaîne exportée générée par openssl_csr_export().

`ca_certificate`

  Le certificat généré sera signé par le certificat `ca_certificate`. Si `ca_certificate` vaut `null`, le certificat généré sera autosigné.

`private_key`

  `private_key` est la clé privée qui correspond au certificat `ca_certificate`.

`days`

  `days` spécifie la durée pour laquelle le certificat est valide, en nombre de jours.

`options`

  Il est possible d'affiner la signature CSR avec `options`. Voir la fonction openssl_csr_new() pour plus d'informations sur `options`.

`serial`

  Un numéro de série optionnel pour le certificat émis. S'il n'est pas spécifié, il vaudra 0.

`serial_hex`

  Une chaîne hexadécimale facultative représentant le numéro de série du certificat émis. Si elle est définie, elle a la priorité sur la valeur du paramètre `serial`. Si elle n’est pas spécifiée ou qu’elle est définie à `null`, la valeur du paramètre `serial` est alors utilisée à la place.

### Valeurs de retour

Retourne une OpenSSLCertificate en cas de succès, `false` sinon.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `serial_hex` a été ajouté.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de OpenSSLCertificate ; auparavant une resource de type `OpenSSL X.509` était retournée.
8.0.0 | `csr` accepte désormais une instance de OpenSSLCertificateSigningRequest ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.
8.0.0 | `ca_certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.
8.0.0 | `ca_certificate` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

### Exemples

Exemple #1 Exemple avec openssl_csr_sign() - signer une CSR (comment être le propre Autorité de Certification)

    <?php
    // Supposons que ce script est configuré pour recevoir des CSR qui ont
    // été collés dans un champ textarea depuis une autre page
    $csrdata = $_POST["CSR"];

    // Nous allons signer la requête avec notre propre certificat, en tant
    // qu'"autorité de certification". Vous pouvez utiliser n'importe quel
    // certificat pour en signer un autre, mais le processus est inutile à moins
    // que le certificat de signature n'ait la confiance des utilisateurs
    // qui utiliseront le nouveau certificat signé.

    // Nous avons besoin de notre certificat et de la clé privée
    $cacert = "file://path/to/ca.crt";
    $privkey = array("file://path/to/ca.key", "la_cle_secrete_de_votre_certificat");

    $usercert = openssl_csr_sign($csrdata, $cacert, $privkey, 365, array('digest_alg'=>'sha256') );

    // Affichons maintenant le certificat généré, de façon à ce que l'utilisateur
    // puisse le copier/coller dans sa configuration locale (comme un
    // fichier qui contient les certificats de son serveur SSL)
    openssl_x509_export($usercert, $certout);
    echo $certout;

    // Affiche toutes les erreurs survenues
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

# openssl_decrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_decrypt — Déchiffre les données

### Description

function openssl_decrypt(
string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
?string `$tag` = `null`,
string `$aad` = ""
): string|false

Prend une chaîne brute ou base64 encodée et la déchiffre en utilisant la méthode et la phrase de passe passées.

### Liste de paramètres

`data`

  Le message chiffré à déchiffrer.

`cipher_algo`

  L'algorithme de chiffrement. Pour la liste des algorithmes de chiffrement disponible, utiliser openssl_get_cipher_methods().

`passphrase`

  La phrase de passe. Si la phrase de passe est plus courte que prévu, elle est silencieusement complétée avec des caractères `NUL` ; si la phrase de passe est plus longue que prévu, elle est silencieusement tronquée.

  Attention

  Il n'y a pas de fonction de dérivation de clé utilisée pour le paramètre `passphrase` comme son nom pourrait le suggérer. La seule opération utilisée est le remplissage avec des caractères `NUL` ou la troncature si la longueur est différente de celle attendue.

`options`

  Le paramètre `options` peut prendre comme valeur `OPENSSL_RAW_DATA` ou `OPENSSL_ZERO_PADDING` ou `OPENSSL_DONT_ZERO_PAD_KEY`.

`iv`

  Un vecteur d'initialisation non-`null`. Si le VI est plus court que prévu, il est complété avec des caractères `NUL` et un avertissement est émis ; si le VI est plus long que prévu, il est tronqué et un avertissement est émis.

`tag`

  La balise d'authentification en mode de chiffrement AEAD. Si elle est incorrecte, l'authentification échoue et la fonction retourne `false`.

  Attention

  La longueur de `tag` n'est pas vérifiée par la fonction. C'est la responsabilité de l'appelant de s'assurer que la longueur du tag correspond à la longueur du tag reçu quand openssl_encrypt() a été appelée. Sinon, le déchiffrement peut réussir si le début du tag donné correspond au début du vrai tag.

`aad`

  Données supplémentaires authentifiées.

### Valeurs de retour

La chaîne déchiffrée en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si un algorithme cipher inconnu est passé via `cipher_algo`.

Émet une erreur de niveau `E_WARNING` si une valeur vide est passée comme paramètre `iv`.

### Historique

Version | Description
--- | ---
8.1.0 | `tag` est désormais nullable.
7.1.0 | Les paramètres `tag` et `aad` ont été ajoutés.

### Voir aussi

- openssl_encrypt() - Chiffre les données

# openssl_dh_compute_key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_dh_compute_key — Calcule un secret partagé pour une valeur publique de la clé DH publique distante et la clé DH locale

### Description

function openssl_dh_compute_key(string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey `$private_key`): string|false

Le secret partagé retourné par openssl_dh_compute_key() est souvent utilisé comme une clé de chiffrement pour communiquer secrètement avec une partie distante. Ceci est connue sous l'échange de clé Diffie-Hellman.

Attention

Il est important d'utiliser les mêmes paramètres DH pour les paires de clés locales et distantes ; sinon, le secret généré entre les deux parties ne correspondra pas.

> Note: ECDH n'est supporté qu'à partir de PHP 8.1.0 et OpenSSL 3.0.0.

### Liste de paramètres

`public_key`

  Clé DH publique de la partie distante.

`private_key`

  Une clé DH privée locale, correspondant à la clé publique à partager avec la partie distante.

### Valeurs de retour

Retourne le secret partagé en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ; auparavant, une resource de type `OpenSSL key` était acceptée.

### Exemples

Exemple #1 Calcule un secret partagé

Tout d'abord générez localement une paire de clés DH publique / privée et demandez à la partie distante de faire de même. Nous devons utiliser l'utilitaire de ligne de commande `openssl`

    # générer une paire de clé privée/publique
    openssl dhparam -out dhparam.pem 2048
    openssl genpkey -paramfile dhparam.pem -out privatekey.pem

    # extraire uniquement la clé publique
    openssl pkey -in privatekey.pem -pubout -out publickey.pem

Maintenant, envoyer la clé publique à la partie distante. La commande `openssl pkey` permet d'afficher la clé publique qui sera envoyée par la partie distante.

    openssl pkey -pubin -in remotepublickey.pem -text -noout

Résultat de l'exemple ci-dessus est similaire à :

    PKCS#3 DH Public-Key: (2048 bit)
        public-key:
            67:e5:e5:fa:e0:7b:0f:96:2c:dc:96:44:5f:50:02:
            9e:8d:c2:6c:04:68:b0:d1:1d:75:66:fc:63:f5:e3:
            42:30:b8:96:c1:45:cc:08:60:b4:21:3b:dd:ee:66:
            88:db:77:d9:1e:11:89:d4:5c:f2:7a:f2:f1:fe:1c:
            77:9d:6f:13:b8:b2:56:00:ef:cb:3b:60:79:74:02:
            98:f5:f9:8e:3e:b5:62:08:de:ca:8c:c3:40:4a:80:
            79:d5:43:06:17:a8:19:56:af:cc:95:5e:e2:32:2d:
            d2:14:7b:76:5a:9a:f1:3c:76:76:35:cc:7b:c1:a5:
            f4:39:e5:b6:ca:71:3f:7c:3f:97:e5:ab:86:c1:cd:
            0e:e6:ee:04:c9:e6:2d:80:7e:59:c0:49:eb:b6:64:
            4f:a8:f9:bb:a3:87:b3:3d:76:01:9e:2b:16:94:a4:
            37:30:fb:35:e2:63:be:23:90:b9:ef:3f:46:46:04:
            94:8f:60:79:7a:51:55:d6:1a:1d:f5:d9:7f:4a:3e:
            aa:ac:b0:d0:82:cc:c2:e0:94:e0:54:c1:17:83:0b:
            74:08:4d:5a:79:ae:ff:7f:1c:04:ab:23:39:4a:ae:
            87:83:55:43:ab:7a:7c:04:9d:20:80:bb:af:5f:16:
            a3:e3:20:b9:21:47:8c:f8:7f:a8:60:80:9e:61:77:
            36
     [...abbreviated...]

Utiliser cette clé publique en tant que paramètre pour openssl_dh_compute_key() afin de calculer le secret partagé.

    <?php
    $remote_public_key = '67e5e5fae07b0f962cdc96445f50029e8dc26c0468b0d11d7566fc63f5e34230b896c145cc0860b4213bddee6688db77d91e1189d45cf27af2f1fe1c779d6f13b8b25600efcb3b6079740298f5f98e3eb56208deca8cc3404a8079d5430617a81956afcc955ee2322dd2147b765a9af13c767635cc7bc1a5f439e5b6ca713f7c3f97e5ab86c1cd0ee6ee04c9e62d807e59c049ebb6644fa8f9bba387b33d76019e2b1694a43730fb35e263be2390b9ef3f464604948f60797a5155d61a1df5d97f4a3eaaacb0d082ccc2e094e054c117830b74084d5a79aeff7f1c04ab23394aae87835543ab7a7c049d2080bbaf5f16a3e320b921478cf87fa860809e617736';

    $local_priv_key = openssl_pkey_get_private('file://privatekey.pem');

    $shared_secret = openssl_dh_compute_key(hex2bin($remote_public_key), $local_priv_key);
    echo bin2hex($shared_secret)."\n";
    ?>

Exemple #2 Générer une paire de clé DH publique/privée en PHP

Tout d'abord, générer le nombre premier DH

    openssl dhparam -out dhparam.pem 2048
    openssl dh -in dhparam.pem -noout  -text

Résultat de l'exemple ci-dessus est similaire à :

    PKCS#3 DH Parameters: (2048 bit)
            prime:
                00:a3:25:1e:73:3f:44:b9:2b:ee:f4:9d:9f:37:6a:
                4b:fd:1d:bd:f4:af:da:c8:10:77:59:41:c6:5f:73:
                d2:88:29:39:cd:1c:5f:c3:9f:0f:22:d2:9c:20:c1:
                e4:c0:18:03:b8:b6:d8:da:ad:3b:39:a6:da:8e:fe:
                12:30:e9:03:5d:22:ba:ef:18:d2:7b:69:f9:5b:cb:
                78:c6:0c:8c:6b:f2:49:92:c2:49:e0:45:77:72:b3:
                55:36:30:f2:40:17:89:18:50:03:fa:2d:54:7a:7f:
                34:4c:73:32:b6:88:14:51:14:be:80:57:95:e6:a3:
                f6:51:ff:17:47:4f:15:d6:0e:6c:47:53:72:2c:2a:
                4c:21:cb:7d:f3:49:97:c9:47:5e:40:33:7b:99:52:
                7e:7a:f3:52:27:80:de:1b:26:6b:40:bb:14:11:0b:
                fb:e6:d8:2f:cf:a0:06:2f:96:b9:1c:0b:b4:cb:d3:
                a6:62:9c:48:67:f6:81:f2:c6:ff:45:03:0a:9d:67:
                9d:ce:27:d9:6b:48:5d:ca:fb:c2:5d:84:9b:8b:cb:
                40:c7:a4:0c:8a:6e:f4:ab:ba:b6:10:c3:b8:25:4d:
                cf:60:96:f4:db:e8:00:1c:58:47:7a:fb:51:86:d1:
                22:d7:4e:94:31:7a:d5:da:3d:53:de:da:bb:64:8d:
                62:6b
            generator: 2 (0x2)

Le nombre premier et les valeurs du générateurs sont passées en tant que p et q dans openssl_pkey_new()

    <?php
    $configargs = array();
    $configargs['p'] = hex2bin('00a3251e733f44b92beef49d9f376a4bfd1dbdf4afdac810775941c65f73d2882939cd1c5fc39f0f22d29c20c1e4c01803b8b6d8daad3b39a6da8efe1230e9035d22baef18d27b69f95bcb78c60c8c6bf24992c249e0457772b3553630f2401789185003fa2d547a7f344c7332b688145114be805795e6a3f651ff17474f15d60e6c4753722c2a4c21cb7df34997c9475e40337b99527e7af3522780de1b266b40bb14110bfbe6d82fcfa0062f96b91c0bb4cbd3a6629c4867f681f2c6ff45030a9d679dce27d96b485dcafbc25d849b8bcb40c7a40c8a6ef4abbab610c3b8254dcf6096f4dbe8001c58477afb5186d122d74e94317ad5da3d53dedabb648d626b');
    $configargs['g'] = hex2bin('02');
    $private_key = openssl_pkey_new(array('dh' => $configargs));
    openssl_pkey_export_to_file($private_key,'privatekey.pem',$passphrase='y0urp@s5phr@se');

    $details = openssl_pkey_get_details($private_key);
    $local_pub_key = $details['dh']['pub_key'];
    echo bin2hex($local_pub_key)."\n";
    // vous pouvez envoyer votre clé publique à la partie distante

    $details = openssl_pkey_get_details(openssl_pkey_get_public("file://remotepublickey.pem"));
    $remote_public_key = $details['dh']['pub_key'];
    $shared_secret = openssl_dh_compute_key($remote_public_key, $private_key);
    echo bin2hex($shared_secret)."\n";
    ?>

### Voir aussi

- openssl_pkey_new() - Génère une nouvelle clé privée
- openssl_pkey_get_details() - Retourne un tableau contenant les détails de la clé
- openssl_pkey_get_private() - Lit une clé privée
- openssl_pkey_get_public() - Extrait une clé publique d'un certificat, et la prépare

# openssl_digest

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_digest — Calcule un digest

### Description

function openssl_digest(string `$data`, string `$digest_algo`, bool `$binary` = `false`): string|false

Calcule une hash digest pour les données d'entrée en utilisant la méthode fournie. Retourne une chaîne brute ou hexadécimale.

### Liste de paramètres

`data`

  Les données.

`digest_algo`

  La méthode digest à utiliser par exemple "SHA256", voir openssl_get_md_methods() pour obtenir la liste des méthodes de digest disponibles.

`binary`

  Passez à `true` et une donnée brute sera retournée, sinon la valeur retournée sera hexadécimale.

### Valeurs de retour

Retourne la valeur en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si un algorithme inconnu est passé au paramètre `digest_algo`.

### Voir aussi

- openssl_get_md_methods() - Récupère la liste des méthodes digest disponibles

# openssl_encrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_encrypt — Chiffre les données

### Description

function openssl_encrypt(
#[\SensitiveParameter]string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
string `&$tag` = `null`,
string `$aad` = "",
int `$tag_length` = 16
): string|false

Chiffre les données passées avec la méthode et la phrase de passe précisées. Retourne une chaîne de caractères brute ou encodée en base64.

### Liste de paramètres

`data`

  Les données du message en texte brut à chiffrer.

`cipher_algo`

  La méthode de cipher. Pour une liste des méthodes de cipher disponibles, utiliser openssl_get_cipher_methods().

`passphrase`

  La passphrase. Si la passphrase est plus courte qu'attendu, elle est silencieusement complétée avec des caractères `NUL` ; si la passphrase est plus longue qu'attendu, elle est silencieusement tronquée.

  Attention

  Il n'y a pas de fonction de dérivation de clé utilisée pour le paramètre `passphrase` comme son nom pourrait le suggérer. La seule opération utilisée est le remplissage avec des caractères `NUL` ou la troncature si la longueur est différente de celle attendue.

`options`

  `options` est une disjonction au niveau des bits des drapeaux `OPENSSL_RAW_DATA` et `OPENSSL_ZERO_PADDING` ou `OPENSSL_DONT_ZERO_PAD_KEY`.

`iv`

  Un vecteur d'initialisation non-`null`. Si le VI est plus court que prévu, il est complété par des caractères `NUL` et un avertissement est émis ; si le VI est plus long que prévu, il est tronqué et un avertissement est émis.

`tag`

  Le tag d'authentification passé par référence lors de l'utilisation du mode cipher AEAD (GCM ou CCM).

`aad`

  Données supplémentaires authentifiées.

`tag_length`

  La longueur du `tag` d'authentification. Sa valeur peut être entre 4 et 16 pour le mode GCM.

### Valeurs de retour

Retourne la chaîne chiffrée en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si un algorithme cipher inconnu est passé comme paramètre `cipher_algo`.

Émet une erreur de niveau `E_WARNING` si une valeur vide est passée comme paramètre `iv`.

### Historique

Version | Description
--- | ---
7.1.0 | Les paramètres `tag`, `aad` et `tag_length` ont été ajoutés.

### Exemples

Exemple #1 Exemple de chiffrement authentifié AES en mode GCM pour PHP 7.1+

    <?php
    //$key devrait être généré précédemment d'une manière cryptographique, tel que openssl_random_pseudo_bytes
    $plaintext = "message à chiffrer";
    $cipher = "aes-128-gcm";
    if (in_array($cipher, openssl_get_cipher_methods()))
    {
        $ivlen = openssl_cipher_iv_length($cipher);
        $iv = openssl_random_pseudo_bytes($ivlen);
        $ciphertext = openssl_encrypt($plaintext, $cipher, $key, $options=0, $iv, $tag);
        //stocke $cipher, $iv, et $tag pour le déchiffrement ultérieur
        $original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);
        echo $original_plaintext."\n";
    }
    ?>

Exemple #2 Exemple de chiffrement authentifié AES en mode GCM antérieur à PHP 7.1

    <?php
    //$key devrait être généré précédemment d'une manière cryptographique, tel que openssl_random_pseudo_bytes
    $plaintext = "message à chiffrer";
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = openssl_random_pseudo_bytes($ivlen);
    $ciphertext_raw = openssl_encrypt($plaintext, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $hmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
    $ciphertext = base64_encode( $iv.$hmac.$ciphertext_raw );

    // déchiffrer plus tard ...
    $c = base64_decode($ciphertext);
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = substr($c, 0, $ivlen);
    $hmac = substr($c, $ivlen, $sha2len=32);
    $ciphertext_raw = substr($c, $ivlen+$sha2len);
    $original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
    if (hash_equals($hmac, $calcmac))// timing attack safe comparison
    {
        echo $original_plaintext."\n";
    }
    ?>

### Voir aussi

- openssl_decrypt() - Déchiffre les données

# openssl_error_string

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_error_string — Retourne le message d'erreur OpenSSL

### Description

function openssl_error_string(): string|false

openssl_error_string() retourne la dernière erreur de la bibliothèque OpenSSL. Les messages d'erreurs sont placés en file d'attente, et la fonction openssl_error_string() doit être appelée plusieurs fois pour afficher toutes les erreurs. La dernière erreur sera la plus récente dans cette file.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un message d'erreur, sous la forme d'une chaîne de caractères, ou `false` s'il n'y a plus de message à afficher.

### Exemples

Exemple #1 Exemple avec openssl_error_string()

    <?php
    // Imaginons que vous avez appelé une fonction qui a émis une erreur
    while ($msg = openssl_error_string())
        echo $msg . "<br />\n";
    ?>

# openssl_free_key

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_free_key — Libère les ressources

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function openssl_free_key(OpenSSLAsymmetricKey `$key`): void

openssl_free_key() libère les clés associées à `key` de la mémoire.

### Liste de paramètres

`key`

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est désormais obsolète car elle n'a plus d'effet.
8.0.0 | `key` accepte désormais une instance de OpenSSLAsymmetricKey ; auparavant, une resource de type `OpenSSL key` était acceptée.

# openssl_get_cert_locations

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_get_cert_locations — Récupère les chemins vers les certificats disponibles

### Description

function openssl_get_cert_locations(): array

La fonction openssl_get_cert_locations() retourne un tableau contenant les informations sur les chemins où l'on cherchera les certificats SSL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau contenant les chemins vers les certificats disponibles.

### Exemples

Exemple #1 Exemple avec openssl_get_cert_locations()

    <?php
    var_dump(openssl_get_cert_locations());
    ?>

L'exemple ci-dessus va afficher :

    array(8) {
      ["default_cert_file"]=>
      string(21) "/usr/lib/ssl/cert.pem"
      ["default_cert_file_env"]=>
      string(13) "SSL_CERT_FILE"
      ["default_cert_dir"]=>
      string(18) "/usr/lib/ssl/certs"
      ["default_cert_dir_env"]=>
      string(12) "SSL_CERT_DIR"
      ["default_private_dir"]=>
      string(20) "/usr/lib/ssl/private"
      ["default_default_cert_area"]=>
      string(12) "/usr/lib/ssl"
      ["ini_cafile"]=>
      string(0) ""
      ["ini_capath"]=>
      string(0) ""
    }

# openssl_get_cipher_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_cipher_methods — Récupère la liste des méthodes de chiffrements disponibles

### Description

function openssl_get_cipher_methods(bool `$aliases` = `false`): array

Récupère la liste des méthodes de chiffrements disponibles.

### Liste de paramètres

`aliases`

  Passez `true` pour que les alias des méthodes de chiffrement soient inclus dans le tableau retourné.

### Valeurs de retour

Un array des méthodes de chiffrements disponibles. Il est à noter qu'avant OpenSSL 1.1.1, les méthodes de chiffrements étaient retournées en majuscule et en minuscule ; à partir d'OpenSSL 1.1.1 seule la variante en minuscule est retournée.

### Exemples

Exemple #1 Exemple openssl_get_cipher_methods()

Montre à quoi ressemblent les ciphers disponibles, ainsi que les alias disponibles.

    <?php
    $ciphers             = openssl_get_cipher_methods();
    $ciphers_and_aliases = openssl_get_cipher_methods(true);
    $cipher_aliases      = array_diff($ciphers_and_aliases, $ciphers);

    //Le mode ECB devrait être évité
    $ciphers = array_filter( $ciphers, function($n) { return stripos($n,"ecb")===FALSE; } );

    //Au moins dès août 2016, OpenSSL a déclaré faibles : RC2, RC4, DES, 3DES, et ceux basés sur MD5
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"des")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc2")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc4")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"md5")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"des")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"rc2")===FALSE; } );

    print_r($ciphers);
    print_r($cipher_aliases);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => aes-128-cbc
        [1] => aes-128-cbc-hmac-sha1
        [2] => aes-128-cbc-hmac-sha256
        [3] => aes-128-ccm
        [4] => aes-128-cfb
        [5] => aes-128-cfb1
        [6] => aes-128-cfb8
        [7] => aes-128-ctr
        [9] => aes-128-gcm
        [10] => aes-128-ocb
        [11] => aes-128-ofb
        [12] => aes-128-xts
        [13] => aes-192-cbc
        [14] => aes-192-ccm
        [15] => aes-192-cfb
        [16] => aes-192-cfb1
        [17] => aes-192-cfb8
        [18] => aes-192-ctr
        [20] => aes-192-gcm
        [21] => aes-192-ocb
        [22] => aes-192-ofb
        [23] => aes-256-cbc
        [24] => aes-256-cbc-hmac-sha1
        [25] => aes-256-cbc-hmac-sha256
        [26] => aes-256-ccm
        [27] => aes-256-cfb
        [28] => aes-256-cfb1
        [29] => aes-256-cfb8
        [30] => aes-256-ctr
        [32] => aes-256-gcm
        [33] => aes-256-ocb
        [34] => aes-256-ofb
        [35] => aes-256-xts
        [36] => aria-128-cbc
        [37] => aria-128-ccm
        [38] => aria-128-cfb
        [39] => aria-128-cfb1
        [40] => aria-128-cfb8
        [41] => aria-128-ctr
        [43] => aria-128-gcm
        [44] => aria-128-ofb
        [45] => aria-192-cbc
        [46] => aria-192-ccm
        [47] => aria-192-cfb
        [48] => aria-192-cfb1
        [49] => aria-192-cfb8
        [50] => aria-192-ctr
        [52] => aria-192-gcm
        [53] => aria-192-ofb
        [54] => aria-256-cbc
        [55] => aria-256-ccm
        [56] => aria-256-cfb
        [57] => aria-256-cfb1
        [58] => aria-256-cfb8
        [59] => aria-256-ctr
        [61] => aria-256-gcm
        [62] => aria-256-ofb
        [63] => bf-cbc
        [64] => bf-cfb
        [66] => bf-ofb
        [67] => camellia-128-cbc
        [68] => camellia-128-cfb
        [69] => camellia-128-cfb1
        [70] => camellia-128-cfb8
        [71] => camellia-128-ctr
        [73] => camellia-128-ofb
        [74] => camellia-192-cbc
        [75] => camellia-192-cfb
        [76] => camellia-192-cfb1
        [77] => camellia-192-cfb8
        [78] => camellia-192-ctr
        [80] => camellia-192-ofb
        [81] => camellia-256-cbc
        [82] => camellia-256-cfb
        [83] => camellia-256-cfb1
        [84] => camellia-256-cfb8
        [85] => camellia-256-ctr
        [87] => camellia-256-ofb
        [88] => cast5-cbc
        [89] => cast5-cfb
        [91] => cast5-ofb
        [92] => chacha20
        [93] => chacha20-poly1305
        [111] => id-aes128-CCM
        [112] => id-aes128-GCM
        [113] => id-aes128-wrap
        [114] => id-aes128-wrap-pad
        [115] => id-aes192-CCM
        [116] => id-aes192-GCM
        [117] => id-aes192-wrap
        [118] => id-aes192-wrap-pad
        [119] => id-aes256-CCM
        [120] => id-aes256-GCM
        [121] => id-aes256-wrap
        [122] => id-aes256-wrap-pad
        [124] => idea-cbc
        [125] => idea-cfb
        [127] => idea-ofb
        [137] => seed-cbc
        [138] => seed-cfb
        [140] => seed-ofb
        [141] => sm4-cbc
        [142] => sm4-cfb
        [143] => sm4-ctr
        [145] => sm4-ofb
    )
    Array
    (
        [36] => aes128
        [37] => aes128-wrap
        [38] => aes192
        [39] => aes192-wrap
        [40] => aes256
        [41] => aes256-wrap
        [69] => aria128
        [70] => aria192
        [71] => aria256
        [72] => bf
        [77] => blowfish
        [99] => camellia128
        [100] => camellia192
        [101] => camellia256
        [102] => cast
        [103] => cast-cbc
        [146] => idea
        [164] => seed
        [169] => sm4
    )

### Voir aussi

- openssl_get_md_methods() - Récupère la liste des méthodes digest disponibles

# openssl_get_curve_names

(PHP 7 >= 7.1.0, PHP 8)

openssl_get_curve_names — Récupère la liste des noms de courbes disponibles pour ECC

### Description

function openssl_get_curve_names(): array|false

Récupère la liste des noms de courbes disponibles à utilisation dans la cryptographie à courbe elliptique (ECC) pour les opérations clé publique / privée. Les deux courbes les plus largement standardisées / supportées sont prime256v1 (NIST P-256) et secp384r1 (NIST P-384).

Équivalences approximatives des tailles de clés d'AES, RSA, DSA et ECC
Taille de clé symétrique AES (Bits) | Taille de clé RSA et DSA (Bits) | Taille de clé ECC (Bits)
--- | --- | ---
80 | 1024 | 160
112 | 2048 | 224
128 | 3072 | 256
192 | 7680 | 384
256 | 15360 | 512

» NIST recommande d'utiliser des courbes ECC qui ont au moins 256 bits.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau des noms de courbes disponibles, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec openssl_get_curve_names()

    <?php
    $curve_names = openssl_get_curve_names();
    print_r($curve_names);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => secp112r1
        [1] => secp112r2
        [2] => secp128r1
        [3] => secp128r2
        [4] => secp160k1
        [5] => secp160r1
        [6] => secp160r2
        [7] => secp192k1
        [8] => secp224k1
        [9] => secp224r1
        [10] => secp256k1
        [11] => secp384r1
        [12] => secp521r1
        [13] => prime192v1
        [14] => prime192v2
        [15] => prime192v3
        [16] => prime239v1
        [17] => prime239v2
        [18] => prime239v3
        [19] => prime256v1
        [20] => sect113r1
        [21] => sect113r2
        [22] => sect131r1
        [23] => sect131r2
        [24] => sect163k1
        [25] => sect163r1
        [26] => sect163r2
        [27] => sect193r1
        [28] => sect193r2
        [29] => sect233k1
        [30] => sect233r1
        [31] => sect239k1
        [32] => sect283k1
        [33] => sect283r1
        [34] => sect409k1
        [35] => sect409r1
        [36] => sect571k1
        [37] => sect571r1
        [38] => c2pnb163v1
        [39] => c2pnb163v2
        [40] => c2pnb163v3
        [41] => c2pnb176v1
        [42] => c2tnb191v1
        [43] => c2tnb191v2
        [44] => c2tnb191v3
        [45] => c2pnb208w1
        [46] => c2tnb239v1
        [47] => c2tnb239v2
        [48] => c2tnb239v3
        [49] => c2pnb272w1
        [50] => c2pnb304w1
        [51] => c2tnb359v1
        [52] => c2pnb368w1
        [53] => c2tnb431r1
        [54] => wap-wsg-idm-ecid-wtls1
        [55] => wap-wsg-idm-ecid-wtls3
        [56] => wap-wsg-idm-ecid-wtls4
        [57] => wap-wsg-idm-ecid-wtls5
        [58] => wap-wsg-idm-ecid-wtls6
        [59] => wap-wsg-idm-ecid-wtls7
        [60] => wap-wsg-idm-ecid-wtls8
        [61] => wap-wsg-idm-ecid-wtls9
        [62] => wap-wsg-idm-ecid-wtls10
        [63] => wap-wsg-idm-ecid-wtls11
        [64] => wap-wsg-idm-ecid-wtls12
        [65] => Oakley-EC2N-3
        [66] => Oakley-EC2N-4
        [67] => brainpoolP160r1
        [68] => brainpoolP160t1
        [69] => brainpoolP192r1
        [70] => brainpoolP192t1
        [71] => brainpoolP224r1
        [72] => brainpoolP224t1
        [73] => brainpoolP256r1
        [74] => brainpoolP256t1
        [75] => brainpoolP320r1
        [76] => brainpoolP320t1
        [77] => brainpoolP384r1
        [78] => brainpoolP384t1
        [79] => brainpoolP512r1
        [80] => brainpoolP512t1
    )

# openssl_get_md_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_md_methods — Récupère la liste des méthodes digest disponibles

### Description

function openssl_get_md_methods(bool `$aliases` = `false`): array

Récupère la liste des méthodes digest disponibles.

### Liste de paramètres

`aliases`

  Passez `true` pour que les alias de digest soient inclus dans le tableau retourné.

### Valeurs de retour

Un array des méthodes digest disponibles.

### Exemples

Exemple #1 Exemple openssl_get_md_methods()

Montre à quoi ressemblent les digests disponibles, ainsi que les alias disponibles.

    <?php
    $digests             = openssl_get_md_methods();
    $digests_and_aliases = openssl_get_md_methods(true);
    $digest_aliases      = array_diff($digests_and_aliases, $digests);

    print_r($digests);

    print_r($digest_aliases);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => DSA
        [1] => DSA-SHA
        [2] => MD2
        [3] => MD4
        [4] => MD5
        [5] => RIPEMD160
        [6] => SHA
        [7] => SHA1
        [8] => SHA224
        [9] => SHA256
        [10] => SHA384
        [11] => SHA512
        [12] => dsaEncryption
        [13] => dsaWithSHA
        [14] => ecdsa-with-SHA1
        [15] => md2
        [16] => md4
        [17] => md5
        [18] => ripemd160
        [19] => sha
        [20] => sha1
        [21] => sha224
        [22] => sha256
        [23] => sha384
        [24] => sha512
    )
    Array
    (
        [2] => DSA-SHA1
        [3] => DSA-SHA1-old
        [4] => DSS1
        [9] => RSA-MD2
        [10] => RSA-MD4
        [11] => RSA-MD5
        [12] => RSA-RIPEMD160
        [13] => RSA-SHA
        [14] => RSA-SHA1
        [15] => RSA-SHA1-2
        [16] => RSA-SHA224
        [17] => RSA-SHA256
        [18] => RSA-SHA384
        [19] => RSA-SHA512
        [28] => dsaWithSHA1
        [29] => dss1
        [32] => md2WithRSAEncryption
        [34] => md4WithRSAEncryption
        [36] => md5WithRSAEncryption
        [37] => ripemd
        [39] => ripemd160WithRSA
        [40] => rmd160
        [43] => sha1WithRSAEncryption
        [45] => sha224WithRSAEncryption
        [47] => sha256WithRSAEncryption
        [49] => sha384WithRSAEncryption
        [51] => sha512WithRSAEncryption
        [52] => shaWithRSAEncryption
        [53] => ssl2-md5
        [54] => ssl3-md5
        [55] => ssl3-sha1
    )

### Voir aussi

- openssl_digest() - Calcule un digest
- openssl_get_cipher_methods() - Récupère la liste des méthodes de chiffrements disponibles

# openssl_get_privatekey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_privatekey — Alias de openssl_pkey_get_private()

### Description

Cette fonction est un alias de : openssl_pkey_get_private().

# openssl_get_publickey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_publickey — Alias de openssl_pkey_get_public()

### Description

Cette fonction est un alias de : openssl_pkey_get_public().

# openssl_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_open — Ouvre des données scellées

### Description

function openssl_open(
string `$data`,
#[\SensitiveParameter]string `&$output`,
string `$encrypted_key`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string `$cipher_algo`,
?string `$iv` = `null`
): bool

La openssl_open() ouvre (déchiffre) `data` en utilisant une clé d'enveloppe qui est déchiffrée à partir de `encrypted_key` en utilisant `private_key`. Le déchiffrement est effectué à l'aide de `cipher_algo` et `iv`. Le VI est requis uniquement si la méthode de chiffrement l'exige. La fonction remplit `output` avec les données déchiffrées. La clé d'enveloppe est généralement générée lorsque les données sont scellées à l'aide d'une clé publique associée à la clé privée. Consulter openssl_seal() pour plus d'informations.

### Liste de paramètres

`data`

  Les données scellées.

`output`

  Si l'appel a réussi, les données ouvertes sont retournées dans ce paramètre.

`encrypted_key`

  La clé symétrique chiffrée qui peut être déchiffrée à l'aide de `private_key`

`private_key`

  La clé privée utilisée pour déchiffrer `encrypted_key`.

`cipher_algo`

  La méthode de chiffrement utilisée pour le déchiffrement de `data`.

  Attention

  La valeur par défaut pour les versions de PHP antérieures à 8.0 est (`'RC4'`), qui est considérée comme non sécurisée. Il est fortement recommandé de spécifier explicitement une méthode de chiffrement sécurisée.

`iv`

  Le vecteur d'initialisation utilisé pour le déchiffrement de `data`. Il est requis si la méthode de chiffrement nécessite un VI. Cela peut être déterminé en appelant openssl_cipher_iv_length() avec `cipher_algo`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509 CSR` était acceptée.
8.0.0 | `cipher_algo` n'est désormais plus un paramètre optionnel.

### Exemples

Exemple #1 Exemple avec openssl_open()

    <?php

    // On suppose que $sealed, $env_key et $iv contiennent les données scellées,
    // la clé d'enveloppe et IV. Toutes fournies par l'expéditeur.

    // Récupérer la clé privée depuis le fichier situé dans private_key.pem
    $pkey = openssl_get_privatekey("file://private_key.pem");

    // Déchiffrement des données : elles sont placées dans $open
    if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
        echo "Voici les données déchiffrées : ", $open;
    } else {
        echo "Impossible de déchiffrer les données";
    }

    ?>

### Voir aussi

- openssl_seal() - Scelle des données

# openssl_password_hash

(PHP 8 >= 8.4.0)

openssl_password_hash — Crée un hachage de mot de passe en utilisant l'implémentation Argon2 d'OpenSSL

### Description

function openssl_password_hash(string `$algo`, string `$password`, array `$options` = []): string

Crée un hachage de mot de passe en utilisant l'implémentation Argon2 d'OpenSSL. Il s'agit d'une alternative à password_hash() qui utilise OpenSSL comme moteur, ce qui peut offrir une accélération matérielle sur certaines plateformes.

Cette fonction n'est disponible que lorsque PHP est compilé avec le support OpenSSL incluant Argon2 (`HAVE_OPENSSL_ARGON2`).

### Liste de paramètres

`algo`

  L'algorithme de hachage du mot de passe. Valeurs supportées : `"argon2id"` et `"argon2i"`.

`password`

  Le mot de passe de l'utilisateur.

`options`

  Un tableau associatif d'options. Clés supportées :

  - `memory_cost` : mémoire maximale (en Kio) pouvant être utilisée pour calculer le hachage
  - `time_cost` : temps maximal pouvant être pris pour calculer le hachage
  - `threads` : nombre de threads à utiliser pour calculer le hachage

### Valeurs de retour

Retourne le hachage du mot de passe sous forme de chaîne de caractères.

### Erreurs / Exceptions

Lance une ValueError si `algo` n'est pas l'une des valeurs supportées (`"argon2i"` ou `"argon2id"`).

Lance une Error si l'opération de hachage échoue pour une raison inconnue.

### Historique

Version | Description
--- | ---
8.4.0 | Ajout de la fonction.

### Exemples

Exemple #1 Exemple avec openssl_password_hash()

    <?php
    $hash = openssl_password_hash('argon2id', 'mon-mot-de-passe-secret');
    echo $hash;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    $argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$hashvalue...

Exemple #2 openssl_password_hash() avec des options personnalisées

    <?php
    $hash = openssl_password_hash('argon2id', 'mon-mot-de-passe-secret', [
        'memory_cost' => 65536,
        'time_cost'   => 4,
        'threads'     => 1,
    ]);
    ?>

### Voir aussi

- openssl_password_verify() - Vérifie un mot de passe par rapport à un hachage en utilisant l'implémentation Argon2 d'OpenSSL
- password_hash() - Crée une clé de hachage pour un mot de passe

# openssl_password_verify

(PHP 8 >= 8.4.0)

openssl_password_verify — Vérifie un mot de passe par rapport à un hachage en utilisant l'implémentation Argon2 d'OpenSSL

### Description

function openssl_password_verify(string `$algo`, string `$password`, string `$hash`): bool

Vérifie qu'un mot de passe correspond à un hachage créé par openssl_password_hash().

Cette fonction n'est disponible que lorsque PHP est compilé avec le support OpenSSL incluant Argon2 (`HAVE_OPENSSL_ARGON2`).

### Liste de paramètres

`algo`

  L'algorithme de hachage du mot de passe. Valeurs supportées : `"argon2id"` et `"argon2i"`.

`password`

  Le mot de passe de l'utilisateur.

`hash`

  Un hachage créé par openssl_password_hash().

### Valeurs de retour

Retourne `true` si le mot de passe et le hachage correspondent, ou `false` sinon.

### Erreurs / Exceptions

Lance une ValueError si `algo` n'est pas l'une des valeurs supportées (`"argon2i"` ou `"argon2id"`).

### Historique

Version | Description
--- | ---
8.4.0 | Ajout de la fonction.

### Exemples

Exemple #1 Exemple avec openssl_password_verify()

    <?php
    $hash = openssl_password_hash('argon2id', 'mon-mot-de-passe-secret');

    if (openssl_password_verify('argon2id', 'mon-mot-de-passe-secret', $hash)) {
        echo 'Le mot de passe correspond.';
    } else {
        echo 'Le mot de passe ne correspond pas.';
    }
    ?>

### Voir aussi

- openssl_password_hash() - Crée un hachage de mot de passe en utilisant l'implémentation Argon2 d'OpenSSL
- password_verify() - Vérifie qu'un mot de passe correspond à un hachage

# openssl_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

openssl_pbkdf2 — Génère une chaîne PKCS5 v2 PBKDF2

### Description

function openssl_pbkdf2(
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$key_length`,
int `$iterations`,
string `$digest_algo` = "sha1"
): string|false

openssl_pbkdf2() calcule PBKDF2 (Password-Based Key Derivation Function 2), une fonction de dérivation de clé définie dans PKCS5 v2.

### Liste de paramètres

`password`

  Mot de passe depuis lequel la clé dérivée est générée.

`salt`
  PBKDF2 recommande un sel cryptographique d'au moins 128 bits (16 octets).
`key_length`

  Longueur désirée de la clé de sortie.

`iterations`

  Le nombre d'itérations désiré. » Le NIST recommande au moins 1 000. À partir de 2023, l'OWASP recommande 600 000 itérations pour PBKDF2-HMAC-SHA256 et 210 000 pour PBKDF2-HMAC-SHA512.

`digest_algo`

  Algorithme de hachage ou de digest optionnel à partir de openssl_get_md_methods(). Par défaut SHA-1. Il est recommandé de le définir sur SHA-256 ou SHA-512.

### Valeurs de retour

Retourne une chaîne binaire brute ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec openssl_pbkdf2()

    <?php
    $password = 'password';
    $salt = openssl_random_pseudo_bytes(16);
    $keyLength = 20;
    $iterations = 600000;
    $generated_key = openssl_pbkdf2($password, $salt, $keyLength, $iterations, 'sha256');
    echo bin2hex($generated_key)."\n";
    echo base64_encode($generated_key)."\n";
    ?>

### Voir aussi

- hash_pbkdf2() - Génère une clé PBKDF2 dérivée du mot de passe fourni
- openssl_get_md_methods() - Récupère la liste des méthodes digest disponibles

# openssl_pkcs12_export

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export — Exporte un certificat compatible PKCS#12 dans une variable

### Description

function openssl_pkcs12_export(
OpenSSLCertificate|string `$certificate`,
string `&$output`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

openssl_pkcs12_export() stocke un certificat `certificate` dans une chaîne nommée `output` dans un format PKCS#12.

### Liste de paramètres

`certificate`
  Voir les paramètres clés/Certificats pour une liste de valeurs valides.
`output`

  En cas de succès, cette variable contiendra le PKCS#12.

`private_key`

  Clé privée du fichier PKCS#12. Consulter Public/Private Key Parameters pour obtenir la liste des valeurs valides.

`passphrase`

  Mot de passe de chiffrement pour déverrouiller le fichier PKCS#12.

`options`

  Tableau optionnel, les autres clés seront ignorées.

  Clé | Description
  --- | ---
  `"extracerts"` | Tableau de certificats supplémentaires ou d'un certificat unique à inclure dans le fichier PKCS#12.
  `"friendly_name"` | chaîne à utiliser pour le certificat et la clé fournis

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

# openssl_pkcs12_export_to_file

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export_to_file — Exporte un certificat compatible PKCS#12

### Description

function openssl_pkcs12_export_to_file(
OpenSSLCertificate|string `$certificate`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

openssl_pkcs12_export_to_file() stocke un certificat `certificate` dans un fichier nommé `output_filename` dans un format de fichier PKCS#12.

### Liste de paramètres

`certificate`
  Voir les paramètres clés/Certificats pour une liste de valeurs valides.
`output_filename`

  Chemin vers le fichier de sortie.

`private_key`

  Clé privée du fichier PKCS#12. Voir paramètres Clé/Certificat pour une liste de valeurs valides.

`passphrase`

  Mot de passe de chiffrement pour déverrouiller le fichier PKCS#12.

`options`

  Tableau optionnel, les autres clés seront ignorées.

  Key | Description
  --- | ---
  `"extracerts"` | tableau de certificats supplémentaires ou un certificat unique à inclure dans le fichier PKCS#12.
  `"friendly_name"` | chaîne de caractères à utiliser pour le certificat et la clé fournis

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

# openssl_pkcs12_read

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_read — Lit un certificat PKCS#12 dans un tableau

### Description

function openssl_pkcs12_read(string `$pkcs12`, array `&$certificates`, #[\SensitiveParameter]string `$passphrase`): bool

openssl_pkcs12_read() lit le certificat PKCS#12 fourni par le paramètre `pkcs12` dans un tableau nommé `certificates`.

### Liste de paramètres

`pkcs12`

  Le contenu du magasin de certificats, pas son nom de fichier.

`certificates`

  En cas de succès, ce tableau contiendra les données du certificat.

`passphrase`

  Mot de passe de chiffrement pour déverrouiller le fichier PKCS#12.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 openssl_pkcs12_read() example

    <?php
    if (!$cert_store = file_get_contents("/certs/file.p12")) {
        echo "Erreur : impossible de lire le fichier de certificat\n";
        exit;
    }

    if (openssl_pkcs12_read($cert_store, $cert_info, "my_secret_pass")) {
        echo "Informations sur le certificat\n";
        print_r($cert_info);
    } else {
        echo "Erreur : impossible de lire le magasin de certificats.\n";
        exit;
    }
    ?>

# openssl_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_decrypt — Déchiffre un message S/MIME

### Description

function openssl_pkcs7_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`
): bool

Déchiffre le message S/MIME contenu dans le fichier `input_filename`, en utilisant le certificat et la clé privée associés par `certificate` et `private_key`.

### Liste de paramètres

`input_filename`

`output_filename`

  Le message déchiffré est écrit dans le fichier spécifié par ce paramètre.

`certificate`

`private_key`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509 CSR` était acceptée.

### Exemples

Exemple #1 Exemple avec openssl_pkcs7_decrypt()

    <?php
    // $cert et $key contiennent vos certificats et clés privés
    // On suppose aussi que le message vous est destiné
    $infilename = "encrypted.msg";  // ce fichier contient votre message chiffré
    $outfilename = "decrypted.msg"; // assurez-vous de pouvoir écrire dans ce fichier

    if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key)) {
        echo "déchiffré !";
    } else {
        echo "Échec lors du déchiffrement !";
    }
    ?>

# openssl_pkcs7_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_encrypt — Chiffre un message S/MIME

### Description

function openssl_pkcs7_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

openssl_pkcs7_encrypt() prend le contenu du fichier `input_filename` et le chiffre en utilisant un chiffrement RC2 à 40-bit, de manière que le message ne puisse être lu que par le possesseur de `certificate`.

### Liste de paramètres

`input_filename`

`output_filename`

`certificate`

  Soit un certificat X.509, soit un tableau de certificats X.509.

`headers`

  `headers` est un tableau d'en-têtes qui seront ajoutés en tête de message, une fois que les données auront été chiffrées.

  `headers` peut être un tableau associatif, dont les clés sont les noms d'en-tête, ou bien un tableau indexé dont chaque ligne contient un en-tête complet.

`flags`

  `flags` peut être utilisé pour spécifier des options qui affecteront le chiffrement (voir les constantes PKCS7).

`cipher_algo`

  Une des constantes cipher.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | L'algorithme de chiffrement par défaut (`cipher_algo`) est désormais AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`). Auparavant, PKCS7/CMS était utilisé (`OPENSSL_CIPHER_RC2_40`).
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.

### Exemples

Exemple #1 Exemple avec openssl_pkcs7_encrypt()

    <?php
    // le message que vous souhaitez chiffrer et envoyer à votre agent secret
    // en mission commandée, appelé "nighthawk". Vous avez son certificat
    // dans le fichier "nighthawk.pem"
    $data = <<<EOD
    Nighthawk,

    Top secret, uniquement votre lecture !

    L'ennemi approche! Rendez-vous au café à 8 h 30,
    pour votre faux passeport.

    HQ
    EOD;

    // Chargement de la clé
    $key = file_get_contents("nighthawk.pem");

    // Sauvegarde du message dans un fichier
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);

    // Chiffrons-le
    if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
        array("To" => "nighthawk@example.com", // syntaxe sous forme de clé
              "From: HQ <hq@example.com>", // syntaxe sous forme d'indexe
              "Subject" => "Que pour vos yeux !"))) {
        // message chiffré - envoyez-le !
        exec(ini_get("sendmail_path") . " < enc.txt");
    }
    ?>

# openssl_pkcs7_read

(PHP 7 >= 7.2.0, PHP 8)

openssl_pkcs7_read — Exporte le fichier PKCS7 vers un tableau de certificats PEM

### Description

function openssl_pkcs7_read(string `$data`, array `&$certificates`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`data`

  La chaîne de données qui doit être analysée (au format p7b).

`certificates`

  Un tableau de certificats PEM depuis les données d'entrées p7b.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Récupérer un tableau PEM depuis un fichier P7B

    <?php

    $file = 'certs.p7b';

    $f = file_get_contents($file);
    $p7 = array();
    $r = openssl_pkcs7_read($f, $p7);

    if ($r === false) {
        printf("ERREUR : %s n'est pas un fichier p7b valide".PHP_EOL, $file);
            for($e = openssl_error_string(), $i = 0; $e; $e = openssl_error_string(), $i++)
                printf("SSL l%d: %s".PHP_EOL, $i, $e);
        exit(1);
    }

    print_r($p7);
    ?>

### Voir aussi

- openssl_csr_sign() - Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat

# openssl_pkcs7_sign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_sign — Signe un message S/MIME

### Description

function openssl_pkcs7_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = `PKCS7_DETACHED`,
?string `$untrusted_certificates_filename` = `null`
): bool

openssl_pkcs7_sign() prend le contenu du fichier `input_filename` et le signe en utilisant le certificat et la clé privée contenus dans les arguments `certificate` et `private_key`.

### Liste de paramètres

`input_filename`

  Le fichier d'entrée qu'on a l'intention de signer numériquement.

`output_filename`

  Le fichier où la signature numérique sera écrite.

`certificate`

  Le certificat X.509 utilisé pour signer numériquement `input_filename`. Voir paramètres Clé/Certificat pour une liste de valeurs valides.

`private_key`

  `private_key` est la clé privée correspondant à `certificate`. Voir paramètres Clé Publique/Privée pour une liste de valeurs valides.

`headers`

  `headers` est un tableau d'en-têtes qui seront ajoutés aux données signées (voir la fonction openssl_pkcs7_encrypt() pour plus de détails sur le format du paramètre).

`flags`

  `flags` peut être utilisé pour modifier la sortie. Voir les constantes PKCS7.

`untrusted_certificates_filename`

  `untrusted_certificates_filename` spécifie le nom du fichier contenant un ensemble de certificats supplémentaires à inclure dans la signature, qui pourront aider le destinataire à vérifier le certificat utilisé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509 CSR` était acceptée.
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

### Exemples

Exemple #1 Exemple avec openssl_pkcs7_sign()

    <?php
    // le message que vous voulez signer, afin que le destinataire soit sûr qu'il
    // vient bien de vous
    $data = <<<EOD

    Vous êtes autorisé à dépenser 10 000€ en note de frais.

    Le PDG
    EOD;
    // sauvez le message dans un fichier
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);
    // encrypt it
    if (openssl_pkcs7_sign("msg.txt", "signed.txt", "file://mycert.pem",
        array("file://mycert.pem", "mypassphrase"),
        array("To" => "joes@example.com", // syntaxe à clé
              "From: HQ <ceo@example.com>", // syntaxe indexée
              "Subject" => "Eyes only")
        )) {
        // message signé - envoyez-le !
        exec(ini_get("sendmail_path") . " < signed.txt");
    }
    ?>

# openssl_pkcs7_verify

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_verify — Vérifie la signature d'un message S/MIME

### Description

function openssl_pkcs7_verify(
string `$input_filename`,
int `$flags`,
?string `$signers_certificates_filename` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$output_filename` = `null`
): bool|int

openssl_pkcs7_verify() lit le message S/MIME contenu dans le fichier `input_filename` et examine la signature numérique.

### Liste de paramètres

`input_filename`

  Chemin vers le message.

`flags`

  `flags` sert à modifier la façon dont la signature est vérifiée. Voir les constantes PKCS7. Par défaut, la valeur est : PKCS7_DETACHED.

`signers_certificates_filename`

  Si le paramètre `signers_certificates_filename` est spécifié, il doit être une chaîne contenant le nom d'un fichier qui contient le certificat du signataire, au format PEM.

`ca_info`

  Si le paramètre `ca_info` est spécifié, il doit contenir les informations sur les tiers de certificats de confiance utilisés lors de la vérification. Voir vérification des certificats pour plus de détails.

`untrusted_certificates_filename`

  Si le paramètre `untrusted_certificates_filename` est spécifié, il doit représenter le nom d'un fichier contenant un ensemble de certificats utilisés comme certificats de peu de confiance.

`content`

  Il est possible de spécifier un nom de fichier avec le paramètre `content` qui peut être rempli avec les données vérifiées, sans les informations de signature.

`output_filename`

### Valeurs de retour

Retourne `true` si la signature est vérifiée, et `false` sinon (le message a été modifié, ou bien le certificat de signature est invalide) ou -1 si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `signers_certificates_filename`, `untrusted_certificates_filename`, `content` et `output_filename` sont désormais nullable.
7.2.0 | Le paramètre `output_filename` a été ajouté.

### Notes

> Note: Tel que spécifié dans la RFC 2045, les lignes ne doivent pas être plus longues que 76 caractères dans le paramètre `input_filename`.

# openssl_pkey_derive

(PHP 7 >= 7.3.0, PHP 8)

openssl_pkey_derive — Calcule le secret partagé pour la valeur publique de la clé DH ou ECDH distante et locale

### Description

function openssl_pkey_derive(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, int `$key_length` = 0): string|false

openssl_pkey_derive() prend un ensemble de `public_key` et `private_key` et dérive un secret partagé, pour les clés DH ou EC.

### Liste de paramètres

`public_key`

  `public_key` est la clé publique pour la dérivation. Voir Paramètres de clé/certificat pour une liste de valeurs valides.

`private_key`

  `private_key` est la clé privée pour la dérivation. Voir Public/Private Key parameters pour une liste de valeurs valides.

`key_length`

  S'il n'est pas nul, tentera de définir la longueur souhaitée du secret dérivé.

  Attention

  Ce paramètre est obsolète et ne doit pas être utilisé, car il ne fonctionne pas comme prévu. Il ne retourne jamais un secret plus long que la taille du nombre premier. Si la longueur souhaitée est inférieure à la taille du nombre premier, elle est tronquée uniquement pour les clés ECDH, mais cela échoue pour les clés DH.

### Valeurs de retour

Le secret dérivé en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre `key_length` est désormais obsolète.

### Exemples

Exemple #1 Exemple de openssl_pkey_derive()

    <?php
    // Charge la clé privée
    $priv = openssl_pkey_get_private("-----BEGIN PRIVATE KEY-----
    MIICJgIBADCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDy
    upojBIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2f
    VtCEMPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC
    0DCNt4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2
    197JGZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/
    HnyfVCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsC
    AQIEggEEAoIBAGwAYC2E81Y1U2Aox0U7u1+vBcbht/OO87tutMvc4NTLf6NLPHsW
    cPqBixs+3rSn4fADzAIvdLBmogjtiIZoB6qyHrllF/2xwTVGEeYaZIupQH3bMK2b
    6eUvnpuu4Ytksiz6VpXBBRMrIsj3frM+zUtnq8vKUr+TbjV2qyKR8l3eNDwzqz30
    dlbKh9kIhZafclHfRVfyp+fVSKPfgrRAcLUgAbsVjOjPeJ90xQ4DTMZ6vjiv6tHM
    hkSjJIcGhRtSBzVF/cT38GyCeTmiIA/dRz2d70lWrqDQCdp9ArijgnpjNKAAulSY
    CirnMsGZTDGmLOHg4xOZ5FEAzZI2sFNLlcw=
    -----END PRIVATE KEY-----
    ");

    // Charge la clé publique
    $pub = openssl_pkey_get_public("-----BEGIN PUBLIC KEY-----
    MIICJDCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDyupoj
    BIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2fVtCE
    MPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC0DCN
    t4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2197J
    GZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/Hnyf
    VCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsCAQID
    ggEFAAKCAQAiCSBpxvGgsTorxAWtcAlSmzAJnJxFgSPef0g7OjhESytnc8G2QYmx
    ovMt5KVergcitztWh08hZQUdAYm4rI+zMlAFDdN8LWwBT/mGKSzRkWeprd8E7mvy
    ucqC1YXCMqmIwPySvLQUB/Dl8kgau7BLAnIJm8VP+MVrn8g9gghD0qRCgPgtEaDV
    vocfgnOU43rhKnIgO0cHOKtw2qybSFB8QuZrYugq4j8Bwkrzh6rdMMeyMl/ej5Aj
    c0wamOzuBDtXt0T9+Fx3khHaowjCc7xJZRgZCxg43SbqMWJ9lUg94I7+LTX61Gyv
    dtlkbGbtoDOnxeNnN93gwQZngGYZYciu
    -----END PUBLIC KEY-----
    ");

    // Sortie de la version hexadécimale de la clé dérivée
    echo bin2hex(openssl_pkey_derive($pub,$priv));

# openssl_pkey_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export — Stocke une représentation exportable de la clé dans une chaîne de caractères

### Description

function openssl_pkey_export(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `&$output`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

openssl_pkey_export() exporte la clé `key` sous forme de chaîne au format PEM, et la stocke dans la variable `output` (qui est passée par référence).

> Note: Vous devez avoir un fichier openssl.cnf valide et installé pour que cette fonction opère correctement. Voir les notes se trouvant dans la section concernant l'installation pour plus d'informations.

### Liste de paramètres

`key`

`output`

`passphrase`

  La clé est éventuellement protégée par le mot de passe `passphrase`.

`options`

  `options` peut être utilisé pour calibrer le processus d'exportation en spécifiant ou remplaçant les options du fichier de configuration d'OpenSSL. Voir openssl_csr_new() pour plus d'informations sur `options`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

# openssl_pkey_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export_to_file — Sauve une clé au format ASCII dans un fichier

### Description

function openssl_pkey_export_to_file(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `$output_filename`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

openssl_pkey_export_to_file() sauve la clé au format ASCII (PEM) `key` dans le fichier `output_filename`.

> Note: Vous devez avoir un fichier openssl.cnf valide et installé pour que cette fonction opère correctement. Voir les notes se trouvant dans la section concernant l'installation pour plus d'informations.

### Liste de paramètres

`key`

`output_filename`

  Chemin du fichier de sortie.

`passphrase`

  La clé peut éventuellement être protégée par un `passphrase`.

`options`

  `options` peut être utilisé pour calibrer le processus d'exportation en spécifiant ou remplaçant les options du fichier de configuration d'OpenSSL. Voir openssl_csr_new() pour plus d'informations sur `options`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

# openssl_pkey_free

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_free — Libère une clé privée

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function openssl_pkey_free(OpenSSLAsymmetricKey `$key`): void

> Note: Cette fonction n'a aucun effet. Antérieur à PHP 8.0.0, cette fonction était utilisé pour fermer une ressource.

Libère une clé privée créée par la fonction openssl_pkey_new().

### Liste de paramètres

`key`

  Ressource représentant la clé.

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est désormais obsolète car elle n'a plus d'effet.
8.0.0 | `key` accepte désormais une instance de OpenSSLAsymmetricKey ; auparavant, une resource de type `OpenSSL key` était acceptée.

# openssl_pkey_get_details

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_pkey_get_details — Retourne un tableau contenant les détails de la clé

### Description

function openssl_pkey_get_details(OpenSSLAsymmetricKey `$key`): array|false

Cette fonction retourne les détails de la clé (bits, key, type).

### Liste de paramètres

`key`

  Ressource contenant la clé.

### Valeurs de retour

Retourne un tableau avec les détails de la clé en cas de succès, ou `false` en cas d'échec. Le tableau retourné contient les index `bits` (nombre de bits), `key` (représentation sous forme de chaîne de caractères de la clé publique) et `type` (type de clé qui est l'un de `OPENSSL_KEYTYPE_RSA`, `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_EC`, `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, `OPENSSL_KEYTYPE_ED448`, ou `-1` signifiant inconnu).

En fonction du type de clés utilisées, des détails supplémentaires peuvent être retournés. Il est à noter que quelques éléments peuvent ne pas être toujours disponibles.

- `OPENSSL_KEYTYPE_RSA`, une clé de tableau additionnelle appelée `"rsa"`, contenant la donnée de clé est retournée

  Key | Description
  --- | ---
  `"n"` | module
  `"e"` | exposant public
  `"d"` | exposant privé
  `"p"` | nombre premier 1
  `"q"` | nombre premier 2
  `"dmp1"` | exponent1, d mod (p-1)
  `"dmq1"` | exponent2, d mod (q-1)
  `"iqmp"` | coefficient, (inverse de q) mod p

- `OPENSSL_KEYTYPE_DSA`, une clé de tableau additionnelle appelée `"dsa"`, contenant la donnée de clé est retournée

  Key | Description
  --- | ---
  `"p"` | nombre premier (public)
  `"q"` | 160-bit nombre sous-prime, q | p-1 (public)
  `"g"` | générateur du sous-groupe (publique)
  `"priv_key"` | clé privée x
  `"pub_key"` | clé publique y = g^x

- `OPENSSL_KEYTYPE_DH`, une clé de tableau additionnelle appelée `"dh"`, contenant la donnée de clé est retournée.

  Key | Description
  --- | ---
  `"p"` | nombre premier (partagé)
  `"g"` | générateur de Z_p (partagé)
  `"priv_key"` | valeur privée DH x
  `"pub_key"` | valeur publique DH g^x

- `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, ou `OPENSSL_KEYTYPE_ED448` une clé supplémentaire dans le tableau nommée `"x25519"`, `"ed25519"`, `"x448"`, ou `"ed448"` respectivement, est retournée, contenant les données de la clé.

  Key | Description
  --- | ---
  `"priv_key"` | clé privée
  `"pub_key"` | clé publique

### Historique

Version | Description
--- | ---
8.4.0 | Ajout de la prise en charge des clés basées sur Curve25519 et Curve448. Plus précisément, les champs `x25519`, `ed25519`, `x448` et `ed448` ont été introduits.
8.0.0 | `key` accepte désormais une instance de OpenSSLAsymmetricKey ; auparavant, une resource de type `OpenSSL key` était acceptée.

# openssl_pkey_get_private

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_private — Lit une clé privée

### Description

function openssl_pkey_get_private(#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, #[\SensitiveParameter]?string `$passphrase` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_get_private() analyse la clé `private_key` et la prépare pour être utilisée par d'autres fonctions.

### Liste de paramètres

`private_key`

  `private_key` peut être l'une des valeurs suivantes :

  1. une chaîne au format file://path/to/file.pem. Le fichier ainsi désigné doit contenir une clé privée ou un certificat au format PEM (éventuellement les deux).
  2. Une clé privée au format PEM.
`passphrase`

  Le paramètre optionnel `passphrase` doit être utilisé si la clé spécifiée est chiffrée (protégée par un mot de passe).

### Valeurs de retour

Retourne une instance de OpenSSLAsymmetricKey en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de OpenSSLAsymmetricKey ; auparavant, une resource de type `OpenSSL key` était retournée.
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.
8.0.0 | `passphrase` est désormais nullable.

# openssl_pkey_get_public

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_public — Extrait une clé publique d'un certificat, et la prépare

### Description

function openssl_pkey_get_public(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): OpenSSLAsymmetricKey|false

openssl_pkey_get_public() extrait la clé publique du certificat `public_key` et la prépare pour être utilisée par les autres fonctions.

### Liste de paramètres

`public_key`

  `public_key` peut avoir l'une des valeurs suivantes :

  1. Une instance de OpenSSLAsymmetricKey.
  2. Une chaîne au format file://path/to/file.pem. Le fichier ainsi désigné doit contenir une clé publique ou un certificat au format PEM (éventuellement les deux).
  3. Une clé publique au format PEM.

### Valeurs de retour

Retourne une instance de OpenSSLAsymmetricKey en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de OpenSSLAsymmetricKey ; auparavant, une resource de type `OpenSSL key` était retournée.
8.0.0 | `public_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

# openssl_pkey_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_new — Génère une nouvelle clé privée

### Description

function openssl_pkey_new(?array `$options` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_new() génère une nouvelle clé privée. Comment obtenir le composant public de la clé est démontré dans un exemple ci-dessous.

> Note: Vous devez avoir un fichier openssl.cnf valide et installé pour que cette fonction opère correctement. Voir les notes se trouvant dans la section concernant l'installation pour plus d'informations.

### Liste de paramètres

`options`

  Il est possible d'affiner la génération de clés (par exemple, en spécifiant le nombre de bits ou les paramètres) à l'aide du paramètre `options`. Ces options peuvent soit être des paramètres spécifiques à l'algorithme utilisés pour la génération de clés, soit des options génériques également utilisées pour la génération de CSR si non spécifiées. Consulter openssl_csr_new() pour plus d'informations sur l'utilisation de `options` pour un CSR. Parmi ces options, seules `private_key_bits`, `private_key_type`, `curve_name`, et `config` sont utilisées pour la génération de clés. Les options spécifiques à un algorithme sont utilisées si le tableau associatif inclut l'une des clés spécifiques.

  - Clé `"rsa"` pour définir les paramètres RSA.

    options | type | format | requis | description
    --- | --- | --- | --- | ---
    `"n"` | string | nombre binaire | oui | module
    `"e"` | string | nombre binaire | non | exposant public
    `"d"` | string | nombre binaire | oui | exposant privé
    `"p"` | string | nombre binaire | non | premier 1
    `"q"` | string | nombre binaire | non | premier 2
    `"dmp1"` | string | nombre binaire | non | exponent1, d mod (p-1)
    `"dmq1"` | string | nombre binaire | non | exponent2, d mod (q-1)
    `"iqmp"` | string | nombre binaire | non | coefficient, (inverse de q) mod p

  - Clé `"dsa"` pour définir les paramètres DSA.

    options | type | format | requis | description
    --- | --- | --- | --- | ---
    `"p"` | string | nombre binaire | non | nombre premier (public)
    `"q"` | string | nombre binaire | non | 160 bits sous-prime, q | p-1 (public)
    `"g"` | string | nombre binaire | non | générateur du sous-groupe (public)
    `"priv_key"` | string | clé PEM | non | clé privée x
    `"pub_key"` | string | clé PEM | non | clé publique y = g^x

  - Clé `"dh"` pour les paramètres DH (échange de clés Diffie–Hellman).

    Options | Type | Format | Requis | Description
    --- | --- | --- | --- | ---
    `"p"` | string | nombre binaire | non | nombre premier (partagé)
    `"g"` | string | nombre binaire | non | générateur de Z_p (partagé)
    `"priv_key"` | string | clé PEM | non | valeur DH privée x
    `"pub_key"` | string | clé PEM | non | valeur DH publique g^x

  - Clé `"ec"` pour les paramètres de courbe elliptique

    Options | Type | Format | Requis | Description
    --- | --- | --- | --- | ---
    `"curve_name"` | string | nom | non | nom de la courbe, voir openssl_get_curve_names()
    `"p"` | string | nombre binaire | non | nombre premier du champ pour la courbe sur Fp
    `"a"` | string | nombre binaire | non | coefficient a de la courbe pour Fp : y^2 mod p = x^3 + ax + b mod p
    `"b"` | string | nombre binaire | non | coefficient b de la courbe pour Fp : y^2 mod p = x^3 + ax + b mod p
    `"seed"` | string | nombre binaire | non | nombre aléatoire facultatif utilisé pour générer le coefficient b
    `"generator"` | string | point encodé en binaire | non | point générateur de la courbe
    `"g_x"` | string | nombre binaire | non | coordonnée x du point générateur de la courbe
    `"g_y"` | string | nombre binaire | non | coordonnée y du point générateur de la courbe
    `"cofactor"` | string | nombre binaire | non | cofacteur de la courbe
    `"order"` | string | nombre binaire | non | ordre de la courbe
    `"x"` | string | nombre binaire | non | coordonnée x (publique)
    `"y"` | string | nombre binaire | non | coordonnée y (publique)
    `"d"` | string | nombre binaire | non | clé privée

  - Clés `"x25519"`, `"x448"`, `"ed25519"`, `"ed448"` pour les paramètres Curve25519 et Curve448.

    Options | Type | Format | Requis | Description
    --- | --- | --- | --- | ---
    `"priv_key"` | string | clé PEM | non | clé privée
    `"pub_key"` | string | clé PEM | non | clé publique

### Valeurs de retour

Retourne une instance de OpenSSLAsymmetricKey en cas de succès, `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.4.0 | Ajout de la prise en charge des clés basées sur Curve25519 et Curve448 avec l'introduction des champs `x25519`, `ed25519`, `x448`, et `ed448`.
8.3.0 | Ajout de la prise en charge de la génération de clés EC avec des paramètres EC personnalisés. Plus précisément, avec l'introduction des options EC : `p`, `a`, `b`, `seed`, `generator`, `g_x`, `g_y`, `cofactor`, et `order`.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de OpenSSLAsymmetricKey ; auparavant, une resource de type `OpenSSL key` était retournée.
7.1.0 | L'option `curve_name` a été ajoutée pour permettre la création de clés EC.

### Exemples

Exemple #1 Obtention de la clé publique à partir d'une clé privée

    <?php

    $private_key = openssl_pkey_new();
    $public_key_pem = openssl_pkey_get_details($private_key)['key'];
    echo $public_key_pem, PHP_EOL;

    $public_key = openssl_pkey_get_public($public_key_pem);
    var_dump($public_key);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    // Résultat avant PHP 8.0.0 ; notez que la fonction retourne une ressource
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----
    resource(6) of type (OpenSSL key)

    // Résultat à partir de PHP 8.0.0 ; notez que la fonction retourne un objet
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    object(OpenSSLAsymmetricKey)#2 (0) {
    }

Exemple #2 Génération d'une clé RSA à partir de paramètres

    <?php

    $nhex = "BBF82F090682CE9C2338AC2B9DA871F7368D07EED41043A440D6B6F07454F51F" .
            "B8DFBAAF035C02AB61EA48CEEB6FCD4876ED520D60E1EC4619719D8A5B8B807F" .
            "AFB8E0A3DFC737723EE6B4B7D93A2584EE6A649D060953748834B2454598394E" .
            "E0AAB12D7B61A51F527A9A41F6C1687FE2537298CA2A8F5946F8E5FD091DBDCB";

    $ehex = "11";
    $dhex = "A5DAFC5341FAF289C4B988DB30C1CDF83F31251E0668B42784813801579641B2" .
            "9410B3C7998D6BC465745E5C392669D6870DA2C082A939E37FDCB82EC93EDAC9" .
            "7FF3AD5950ACCFBC111C76F1A9529444E56AAF68C56C092CD38DC3BEF5D20A93" .
            "9926ED4F74A13EDDFBE1A1CECC4894AF9428C2B7B8883FE4463A4BC85B1CB3C1";

    $phex = "EECFAE81B1B9B3C908810B10A1B5600199EB9F44AEF4FDA493B81A9E3D84F632" .
            "124EF0236E5D1E3B7E28FAE7AA040A2D5B252176459D1F397541BA2A58FB6599";

    $qhex = "C97FB1F027F453F6341233EAAAD1D9353F6C42D08866B1D05A0F2035028B9D86" .
            "9840B41666B42E92EA0DA3B43204B5CFCE3352524D0416A5A441E700AF461503";

    $dphex = "11";
    $dqhex = "11";
    $qinvhex = "b06c4fdabb6301198d265bdbae9423b380f271f73453885093077fcd39e2119f" .
               "c98632154f5883b167a967bf402b4e9e2e0f9656e698ea3666edfb25798039f7";

    $rsa= openssl_pkey_new([
        'rsa' => [
            'n' => hex2bin($nhex),
            'e' => hex2bin($ehex),
            'd' => hex2bin($dhex),
            'p' => hex2bin($phex),
            'q' => hex2bin($qhex),
            'dmp1' => hex2bin($dphex),
            'dmq1' => hex2bin($dqhex),
            'iqmp' => hex2bin($qinvhex),
        ],
    ]);
    $details = openssl_pkey_get_details($rsa);
    var_dump($details);

    ?>

# openssl_private_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_decrypt — Déchiffre des données avec une clé privée

### Description

function openssl_private_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

openssl_private_decrypt() déchiffre `data` qui a été chiffrée précédemment avec openssl_public_encrypt(), puis stocke le résultat dans la variable `decrypted_data`.

Il est possible d'utiliser cette fonction, par exemple pour déchiffrer des données qui ne sont censées être disponibles que pour soi.

### Liste de paramètres

`data`

`decrypted_data`

`private_key`

  `private_key` doit être la clé privée correspondant à la clé publique qui a été utilisée pour chiffrer les données.

`padding`

  `padding` peut être `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING` ou `OPENSSL_NO_PADDING`.

`digest_algo`
  L'algorithme de hachage pour le remplissage OAEP, ou `null` pour utiliser l'algorithme par défaut.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `digest_algo` a été ajouté.
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

### Voir aussi

- openssl_public_encrypt() - Chiffre des données avec une clé publique
- openssl_public_decrypt() - Déchiffre des données avec une clé publique

# openssl_private_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_encrypt — Chiffre des données avec une clé privée

### Description

function openssl_private_encrypt(
#[\SensitiveParameter]string `$data`,
string `&$encrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

openssl_private_encrypt() chiffre les données `data` avec la clé privée `private_key` et stocke le résultat dans `encrypted_data`. Les données chiffrées peuvent être déchiffrées avec la fonction openssl_public_decrypt().

Cette fonction peut être utilisée pour signer les données (ou leur hash) pour prouver qu'elles n'ont pas été écrites par une autre personne.

### Liste de paramètres

`data`

`encrypted_data`

`private_key`

  `private_key` doit être la clé privée correspondant à la clé publique qui sera utilisée pour déchiffrer les données.

`padding`

  Le paramètre `padding` peut être `OPENSSL_PKCS1_PADDING` ou `OPENSSL_NO_PADDING`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

### Voir aussi

- openssl_public_encrypt() - Chiffre des données avec une clé publique
- openssl_public_decrypt() - Déchiffre des données avec une clé publique

# openssl_public_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_decrypt — Déchiffre des données avec une clé publique

### Description

function openssl_public_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

openssl_public_decrypt() déchiffre les données `data` qui ont été chiffrées avec la fonction openssl_private_encrypt() et stocke le résultat dans `decrypted_data`.

Il est possible d'utiliser cette fonction pour vérifier si le message a été écrit par le propriétaire de la clé privée.

### Liste de paramètres

`data`

`decrypted_data`

`public_key`

  `public_key` doit être la clé publique correspondant à la clé privée qui a été utilisée pour chiffrer les données.

`padding`

  `padding` peut être `OPENSSL_PKCS1_PADDING` ou `OPENSSL_NO_PADDING`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `public_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

### Voir aussi

- openssl_private_encrypt() - Chiffre des données avec une clé privée
- openssl_private_decrypt() - Déchiffre des données avec une clé privée

# openssl_public_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_encrypt — Chiffre des données avec une clé publique

### Description

function openssl_public_encrypt(
#[\SensitiveParameter]string `$data`,
string `&$encrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

openssl_public_encrypt() chiffre les données `data` avec la clé publique `public_key` et stocke le résultat dans `encrypted_data`. Les données chiffrées peuvent être déchiffrées avec la fonction openssl_private_decrypt().

Cette fonction peut être utilisée pour chiffrer un message qui pourra être lu uniquement par le propriétaire de la clé privée. Elle peut être également utilisée pour stocker des données sécurisées dans une base de données.

### Liste de paramètres

`data`

`encrypted_data`

  Contiendra le résultat du chiffrement.

`public_key`

  `public_key` doit être la clé publique correspondant à la clé privée qui sera utilisée pour déchiffrer les données.

`padding`

  `padding` peut être `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING` ou `OPENSSL_NO_PADDING`.

`digest_algo`
  L'algorithme de hachage pour le remplissage OAEP, ou `null` pour utiliser l'algorithme par défaut.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `digest_algo` a été ajouté.
8.0.0 | `public_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

### Voir aussi

- openssl_private_encrypt() - Chiffre des données avec une clé privée
- openssl_private_decrypt() - Déchiffre des données avec une clé privée

# openssl_random_pseudo_bytes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_random_pseudo_bytes — Génère une chaîne pseudo-aléatoire d'octets

### Description

function openssl_random_pseudo_bytes(int `$length`, bool `&$strong_result` = `null`): string

Génère une chaîne de caractères pseudo-aléatoire d'octets, dont la longueur est spécifiée par le paramètre `length`.

Indique également si l'algorithme fort de cryptologie a été utilisé pour produire ces octets pseudo-aléatoires, en utilisant le paramètre `strong_result`.

### Liste de paramètres

`length`

  La taille désirée pour la chaîne d'octets. Doit être un nombre entier positif inférieur ou égal à `2147483647`. PHP va tenter de transtyper ce paramètre en un entier non nul pour l'utiliser.

`strong_result`

  Si fourni, détermine si l'algorithme de cryptologie utilisé était cryptographiquement fort, c.-à-d. sécurisé pour être utilisé avec GPG, les mots de passe, etc. `true` s'il l'est, `false` sinon.

### Valeurs de retour

Retourne la chaîne d'octets générée.

### Erreurs / Exceptions

openssl_random_pseudo_bytes() lance une Exception en cas d'échec.

### Historique

Version | Description
--- | ---
8.0.0 | `strong_result` est désormais nullable.
7.4.0 | La fonction ne retourne plus `false` en cas d'échec, mais lance une Exception à la place.

### Exemples

Exemple #1 Exemple openssl_random_pseudo_bytes()

    <?php
    for ($i = 1; $i <= 4; $i++) {
        $bytes = openssl_random_pseudo_bytes($i, $cstrong);
        $hex   = bin2hex($bytes);

        echo "Longueur : Octets : $i et Hex: " . strlen($hex) . PHP_EOL;
        var_dump($hex);
        var_dump($cstrong);
        echo PHP_EOL;
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Longueur : Octets : 1 et Hex: 2
    string(2) "42"
    bool(true)

    Longueur : Octets : 2 et Hex: 4
    string(4) "dc6e"
    bool(true)

    Longueur : Octets : 3 et Hex: 6
    string(6) "288591"
    bool(true)

    Longueur : Octets : 4 et Hex: 8
    string(8) "ab86d144"
    bool(true)

### Voir aussi

- random_bytes() - Récupère des octets aléatoires cryptographiquement sécurisés
- bin2hex() - Convertit des données binaires en représentation hexadécimale
- crypt() - Hachage à sens unique (indéchiffrable)
- random_int() - Récupère un entier sélectionné de manière uniforme et cryptographiquement sécurisée

# openssl_seal

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_seal — Scelle des données

### Description

function openssl_seal(
#[\SensitiveParameter]string `$data`,
string `&$sealed_data`,
array `&$encrypted_keys`,
array `$public_key`,
string `$cipher_algo`,
string `&$iv` = `null`
): int|false

La openssl_seal() scelle (chiffre) `data` en utilisant le `cipher_algo` spécifié avec une clé secrète générée aléatoirement. La clé est ensuite chiffrée avec chacune des clés publiques dans le tableau `public_key`, et chaque clé d'enveloppe chiffrée est retournée dans `encrypted_keys`. Cela permet d'envoyer des données scellées à plusieurs destinataires (à condition que leurs clés publiques soient disponibles). Chaque destinataire doit recevoir à la fois les données scellées et la clé d'enveloppe qui a été chiffrée avec la clé publique du destinataire. Le VI (vecteur d'initialisation) est généré, et sa valeur est retournée dans `iv`.

### Liste de paramètres

`data`

  Les données à sceller

`sealed_data`

  Les données scellées.

`encrypted_keys`

  Tableau des clés chiffrées.

`public_key`

  Tableau d'instances OpenSSLAsymmetricKey contenant les clés publiques.

`cipher_algo`

  La méthode de chiffrement.

  Attention

  La valeur par défaut pour les versions de PHP antérieures à 8.0 est (`'RC4'`), qui est considérée comme non sécurisée. Il est fortement recommandé de spécifier explicitement une méthode de chiffrement sécurisée.

`iv`

  Le vecteur d'initialisation pour le déchiffrement de `data`. Il est requis si la méthode de chiffrement nécessite un VI. Cela peut être déterminé en appelant openssl_cipher_iv_length() avec `cipher_algo`.

  Attention

  Le VI ne peut pas être défini explicitement. Toute valeur qui y est définie est écrasée par une valeur générée aléatoirement.

### Valeurs de retour

Retourne la longueur des données scellées en cas de succès, et `false` sinon. En cas de succès, les données scellées sont placées dans le paramètre `sealed_data`, et les clés d'enveloppe dans `encrypted_keys`.

### Historique

Version | Description
--- | ---
8.0.0 | `public_key` accepte désormais un tableau d'instances de OpenSSLAsymmetricKey ; auparavant, un tableau de resources de type `OpenSSL key` était acceptée.
8.0.0 | `cipher_algo` n'est désormais plus un paramètre optionnel.
8.0.0 | `iv` est désormais nullable.

### Exemples

Exemple #1 Exemple avec openssl_seal()

    <?php

    $data = "test";

    // récupérer les clés publiques
    $pk1 = openssl_get_publickey("file://cert1.pem");
    $pk2 = openssl_get_publickey("file://cert2.pem");

    // scelle le message : seuls, les possesseurs de $pk1 et $pk2 peuvent déchiffrer
    // le message $sealed avec les clés $ekeys[0] et $ekeys[1] (respectivement).
    openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2));

    if (openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2), 'AES256', $iv) > 0) {
        // éventuellement stocker les valeurs $sealed et $iv et les utiliser plus tard dans openssl_open
        echo "succès\n";
    }
    ?>

### Voir aussi

- openssl_open() - Ouvre des données scellées

# openssl_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_sign — Signe les données

### Description

function openssl_sign(
string `$data`,
string `&$signature`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): bool

openssl_sign() calcule la signature des données `data` en générant une signature numérique cryptographique en utilisant la clé privée associée avec le paramètre `private_key`. À noter que les données elles-mêmes ne sont pas chiffrées.

### Liste de paramètres

`data`

  La chaîne de données qu'on souhaite signer.

`signature`

  Si l'appel à la fonction est un succès, la signature sera retournée dans le paramètre `signature`.

`private_key`

  OpenSSLAsymmetricKey - une clé, retournée par la fonction openssl_get_privatekey()

  string - une clé au format PEM.

`algorithm`

  int - une des signatures d'algorithmes.

  string - une chaîne valide retournée par la fonction openssl_get_md_methods(), par exemple : "sha256WithRSAEncryption" ou "sha384".

`padding`
  Le remplissage RSA PSS à utiliser.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `padding` a été ajouté.
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

### Exemples

Exemple #1 Exemple avec openssl_sign()

    <?php
    // On suppose que $data contient les données à signer

    // lecture de la clé privée pour chaque destinataire
    $pkeyid = openssl_pkey_get_private("file://src/openssl-0.9.6/demos/sign/key.pem");

    // calcul de la signature
    openssl_sign($data, $signature, $pkeyid);

    // libère les clés de la mémoire
    openssl_free_key($pkeyid);
    ?>

Exemple #2 Exemple avec openssl_sign()

    <?php
    //données que vous souhaitez signer
    $data = 'my data';

    //Crée une nouvelle clé privée et publique
    $new_key_pair = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    openssl_pkey_export($new_key_pair, $private_key_pem);

    $details = openssl_pkey_get_details($new_key_pair);
    $public_key_pem = $details['key'];

    //Création de la signature
    openssl_sign($data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);

    //Sauvegarde pour utilisation ultérieure
    file_put_contents('private_key.pem', $private_key_pem);
    file_put_contents('public_key.pem', $public_key_pem);
    file_put_contents('signature.dat', $signature);

    //Vérification de la signature
    $r = openssl_verify($data, $signature, $public_key_pem, "sha256WithRSAEncryption");
    var_dump($r);
    ?>

### Voir aussi

- openssl_verify() - Vérifie une signature

# openssl_spki_export

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export — Exporte un PEM valide formaté comme une clé publique signée

### Description

function openssl_spki_export(string `$spki`): string|false

Exporte un PEM valide formaté comme une clé publique signée.

### Liste de paramètres

`spki`

  Une clé publique signée valide

### Valeurs de retour

Retourne le PEM associé formaté en clé publique, ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une alerte de niveau `E_WARNING` si un argument non valide est passé via le paramètre `spki`.

### Exemples

Exemple #1 Exemple avec openssl_spki_export()

Extrait le PEM associé formaté comme clé publique, ou `null` en cas d'échec.

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');
    $pubKey = openssl_spki_export(preg_replace('/SPKAC=/', '', $spkac));

    if ($pubKey) {
        echo $pubKey;
    }
    ?>

Exemple #2 Exemple avec openssl_spki_export() depuis <keygen>

Extrait le PEM associé formaté en clé publique, issue d'un élément <keygen>

    <?php
    $spkac = openssl_spki_export(preg_replace('/SPKAC=/', '', $_POST['spkac']));
    if ($spkac != NULL) {
        echo $spkac;
    } else {
        echo "Échec de l'extraction de la clé publique";
    }
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Voir aussi

- openssl_spki_new() - Génère une clé publique signée et effectue un challenge
- openssl_spki_verify() - Vérifie une clé publique signée, et effectue un challenge
- openssl_spki_export_challenge() - Exporte le challenge associé avec la clé publique signée
- openssl_get_md_methods() - Récupère la liste des méthodes digest disponibles
- openssl_csr_new() - Génère une CSR
- openssl_csr_sign() - Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat

# openssl_spki_export_challenge

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export_challenge — Exporte le challenge associé avec la clé publique signée

### Description

function openssl_spki_export_challenge(string `$spki`): string|false

Exporte le challenge associé avec la clé publique signée.

### Liste de paramètres

`spki`

  Une clé publique signée valide

### Valeurs de retour

Retourne le challenge associé sous la forme d'une chaîne de caractères ou `false` en cas d'échec.

### Erreurs / Exceptions

Émet une alerte de niveau `E_WARNING` si un argument invalide est passé via le paramètre `spki`.

### Exemples

Exemple #1 Exemple avec openssl_spki_export_challenge()

Extrait le challenge associé sous la forme d'une chaîne de caractères ou `null` en cas d'échec.

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $spkac));
    ?>

Exemple #2 Exemple avec openssl_spki_export_challenge() depuis <keygen>

Extrait le challenge associé issu d'un élément <keygen>

    <?php
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $_POST['spkac']));
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Voir aussi

- openssl_spki_new() - Génère une clé publique signée et effectue un challenge
- openssl_spki_verify() - Vérifie une clé publique signée, et effectue un challenge
- openssl_spki_export() - Exporte un PEM valide formaté comme une clé publique signée
- openssl_get_md_methods() - Récupère la liste des méthodes digest disponibles
- openssl_csr_new() - Génère une CSR
- openssl_csr_sign() - Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat

# openssl_spki_new

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_new — Génère une clé publique signée et effectue un challenge

### Description

function openssl_spki_new(#[\SensitiveParameter]OpenSSLAsymmetricKey `$private_key`, string `$challenge`, int `$digest_algo` = `OPENSSL_ALGO_MD5`): string|false

Génère une clé publique signée en utilisant un algorithme de hachage spécifié.

### Liste de paramètres

`private_key`

  `private_key` doit être une clé privée qui a été précédemment générée par la fonction openssl_pkey_new() (ou sinon, obtenue depuis une fonction de la famille openssl_pkey). La portion publique de la clé sera utilisée pour signer le CSR.

`challenge`

  Le challenge associé à associer avec le SPKAC

`digest_algo`

  L'algorithme digest. Voir openssl_get_md_method().

### Valeurs de retour

Retourne une clé publique signée sous la forme d'une chaîne de caractères ou `false` en cas d'échec.

### Erreurs / Exceptions

Émet une alerte de niveau `E_WARNING` si un algorithme avec une signature non connue est passé via le paramètre `digest_algo`.

### Historique

Version | Description
--- | ---
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ; auparavant, une resource de type `OpenSSL key` était acceptée.

### Exemples

Exemple #1 Exemple avec openssl_spki_new()

Génère un nouveau SPKAC avec le digest par défaut (MD5)

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'testing');

    if ($spkac !== NULL) {
        echo $spkac;
    } else {
        echo "Échec de la génération du SPKAC";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    MIICRzCCAS8wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDM3V3sS4o4
    mB9dczziRnjGAmSp+JwPrHoYMAFGvDNmZGyiWfU586X4BKs++BAj7e/FsAfno0Hd
    hN9FwpCNFSox30L03nQvLYJE7f/WqigwBeMRT7Op/xvFks4sT70xP2HRYv4KqP9a
    WRcKU6cFH8VxhFhqM2txEIxZKdFLaL28yT7bEDmcglf4JLDdgNMb9rET1dkgtKE6
    dOaJHPGjf1uvnOH4YwkQr7n4sLUR3Kdbh0ZJAFuQVDZulo+LLzxBBkqJJcB6FhF+
    oXCdHTKZnqAhpWDz+NXYytAmevab6IYm5TWPWsJUv1YKJA5lg2mXbbloIZlN9Mgc
    i9fi03bdw+crAgMBAAEWB3Rlc3RpbmcwDQYJKoZIhvcNAQEEBQADggEBALyUvP/o
    pPSoWBlorFyZ2RnGwKf9qMpE0q2IJP7G3oDR4LyK/m933DUiZ+YnqThrH/CWb4Ek
    y5I3OCyl3S4wCuU1ibZZwDVwYShr5ELp0J9PEf7qMQZOhNsizoC7k+Czb2xB6hYW
    sKfsfTKm3cXBtH3fdgc/Z1Z7VSWnAzYo38snqm72NTf5yFRnrQdphNNXi+kn1zHA
    lxXRyFDXHOcYsOnwAWfyXFA4QDHQ0ezz0UoCY8gJXovcZb4GRYqOLUAsF2HcNboy
    29WN8VqE29sL9QxVZFlwMcqyoLcNnyw38GvNvAGqSvzzbnEFP2MAQXJVe0H0hdp/
    MML5G2iNVgNozAo=

### Voir aussi

- openssl_spki_verify() - Vérifie une clé publique signée, et effectue un challenge
- openssl_spki_export_challenge() - Exporte le challenge associé avec la clé publique signée
- openssl_spki_export() - Exporte un PEM valide formaté comme une clé publique signée
- openssl_get_md_methods() - Récupère la liste des méthodes digest disponibles
- openssl_csr_new() - Génère une CSR
- openssl_csr_sign() - Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat

# openssl_spki_verify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_verify — Vérifie une clé publique signée, et effectue un challenge

### Description

function openssl_spki_verify(string `$spki`): bool

Vérifie une clé publique signée, et effectue un challenge.

### Liste de paramètres

`spki`

  Une clé publique signée valide

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une alerte de niveau `E_WARNING` si un argument invalide est passé au paramètre `spki`.

### Exemples

Exemple #1 Exemple avec openssl_spki_verify()

Valide une clé publique signée existante et effectue un challenge

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');

    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $spkac))) {
        echo $spkac;
    } else {
        echo "Échec de la validation du SPKAC";
    }
    ?>

Exemple #2 Exemple avec openssl_spki_verify() depuis <keygen>

Valide une clé publique signée existante issue d'un élément <keygen>

    <?php
    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $_POST['spkac']))) {
        echo $spkac;
    } else {
        echo "Échec de la validation du SPKAC";
    }
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Voir aussi

- openssl_spki_new() - Génère une clé publique signée et effectue un challenge
- openssl_spki_export_challenge() - Exporte le challenge associé avec la clé publique signée
- openssl_spki_export() - Exporte un PEM valide formaté comme une clé publique signée
- openssl_get_md_methods() - Récupère la liste des méthodes digest disponibles
- openssl_csr_new() - Génère une CSR
- openssl_csr_sign() - Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat

# openssl_verify

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_verify — Vérifie une signature

### Description

function openssl_verify(
string `$data`,
string `$signature`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): int|false

openssl_verify() vérifie que la signature `signature` est correcte pour les données `data`, et avec la clé publique `public_key`. Cette clé doit être la clé publique correspondant à la clé privée utilisée lors de la signature.

### Liste de paramètres

`data`

  La chaîne de données utilisée pour générer la signature

`signature`

  Une chaîne brute binaire, générée par la fonction openssl_sign() ou un moyen similaire

`public_key`

  OpenSSLAsymmetricKey - une clé, retournée par la fonction openssl_get_publickey()

  string - une clé au format PEM, par exemple : `-----BEGIN PUBLIC KEY----- MIIBCgK...`.

`algorithm`

  int - une des signatures d'algorithmes.

  string - une chaîne valide retournée par la fonction openssl_get_md_methods(), par exemple : "sha1WithRSAEncryption" ou "sha512". Algorithme par défaut: "OPENSSL_ALGO_SHA1".

`padding`
  Le remplissage RSA PSS à utiliser.

### Valeurs de retour

Retourne 1 si la signature est correcte, 0 si elle est incorrecte et -1 ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `padding` a été ajouté.
8.0.0 | `public_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

### Exemples

Exemple #1 Exemple avec openssl_verify()

    <?php
    // On suppose que $data et $signature contiennent les données à signer et
    // la signature.

    // Lecture de la clé publique depuis le certificat
    $pubkeyid = openssl_pkey_get_public("file://src/openssl-0.9.6/demos/sign/cert.pem");

    // indique si la signature est correcte
    $ok = openssl_verify($data, $signature, $pubkeyid);
    if ($ok == 1) {
        echo "Signature valide";
    } elseif ($ok == 0) {
        echo "Signature erronée";
    } else {
        echo "Erreur de vérification de la signature";
    }
    // libère les clés de la mémoire
    openssl_free_key($pubkeyid);
    ?>

Exemple #2 Exemple avec openssl_verify()

    <?php
    //Données que vous souhaitez signer
    $data = 'my data';

    //Crée une nouvelle clé privée et publique
    $private_key_res = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $details = openssl_pkey_get_details($private_key_res);
    $public_key_res = openssl_pkey_get_public($details['key']);

    //Crée une signature
    openssl_sign($data, $signature, $private_key_res, "sha256WithRSAEncryption");

    //Vérifie la signature
    $ok = openssl_verify($data, $signature, $public_key_res, OPENSSL_ALGO_SHA256);
    if ($ok == 1) {
        echo "valide";
    } elseif ($ok == 0) {
        echo "invalide";
    } else {
        echo "erreur : ".openssl_error_string();
    }
    ?>

### Voir aussi

- openssl_sign() - Signe les données

# openssl_x509_check_private_key

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_check_private_key — Vérifie si une clé privée correspond à un certificat

### Description

function openssl_x509_check_private_key(OpenSSLCertificate|string `$certificate`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`): bool

Vérifie si le paramètre `private_key` fourni est la clé privée qui correspond à `certificate`.

Avertissement

Cette fonction ne vérifie pas si `private_key` est effectivement une clé privée ou pas. Elle compare simplement le matériel public (par exemple l'exposant et le module d'une clé RSA) et/ou les paramètres de clé (par exemple les paramètres EC d'une clé EC) d'une paire de clés.

Ceci signifie, par exemple, qu'une clé publique pourrait être fournie pour `private_key` et la fonction peut retourner `true`.

### Liste de paramètres

`certificate`

  Le certificat.

`private_key`

  La clé privée.

### Valeurs de retour

Retourne `true` si `private_key` est la clé privée qui correspond à `certificate`, ou `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.
8.0.0 | `private_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

# openssl_x509_checkpurpose

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_checkpurpose — Vérifie l'usage d'un certificat

### Description

function openssl_x509_checkpurpose(
OpenSSLCertificate|string `$certificate`,
int `$purpose`,
array `$ca_info` = [],
?string `$untrusted_certificates_file` = `null`
): bool|int

openssl_x509_checkpurpose() examine le certificat spécifié par `certificate`, pour voir s'il peut être utilisé pour une opération particulière `purpose`.

### Liste de paramètres

`certificate`

  Le certificat examiné.

`purpose`

  Utilisation de openssl_x509_checkpurpose()
  Constante | Description
  --- | ---
  X509_PURPOSE_SSL_CLIENT | Est-ce que le certificat peut être utilisé avec le client d'une connexion SSL ?
  X509_PURPOSE_SSL_SERVER | Est-ce que le certificat peut être utilisé avec le serveur d'une connexion SSL ?
  X509_PURPOSE_NS_SSL_SERVER | Est-ce que le certificat peut être utilisé avec un serveur Netscape d'une connexion SSL ?
  X509_PURPOSE_SMIME_SIGN | Est-ce que le certificat peut être utilisé pour signer des courriers à la norme S/MIME ?
  X509_PURPOSE_SMIME_ENCRYPT | Est-ce que le certificat peut être utilisé pour chiffrer un courrier au format S/MIME ?
  X509_PURPOSE_CRL_SIGN | Est-ce que le certificat peut être utilisé pour signer une liste de révocation de certificats ? (CRL)?
  X509_PURPOSE_ANY | Est-ce que le certificat peut être utilisé pour n'importe lequel de ces cas ?

  Ces options ne sont pas des champs de bits : on ne peut en passer qu'une seule à la fois.
`ca_info`

  `ca_info` doit être un tableau de dossiers/fichiers de CA de confiance comme décrit dans la Vérification des certificats.

`untrusted_certificates_file`

  Si spécifié, est le nom d'un fichier au format PEM contenant les certificats qui pourront aider lors de la vérification du certificat, même si aucune confiance n'est accordée aux certificats provenant de ce fichier.

### Valeurs de retour

Retourne `true` si le certificat peut être utilisé pour un but particulier, `false` s'il ne le peut pas, ou -1 si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.
8.0.0 | `untrusted_certificates_file` est désormais nullable.

# openssl_x509_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export — Exporte un certificat vers une chaîne de caractères

### Description

function openssl_x509_export(OpenSSLCertificate|string `$certificate`, string `&$output`, bool `$no_text` = `true`): bool

openssl_x509_export() stocke un certificat `certificate` dans la chaîne `output` au format PEM.

### Liste de paramètres

`certificate`
  Voir les paramètres clés/Certificats pour une liste de valeurs valides.
`output`

  En cas de succès, contiendra le PEM.

`no_text`
  Le paramètre optionnel `notext` affecte le niveau verbeux de l'affichage ; s'il vaut `false`, des informations humainement lisibles seront ajoutées dans l'affichage. Par défaut, le paramètre `notext` vaut `true`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.

# openssl_x509_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export_to_file — Exporte un certificat vers un fichier

### Description

function openssl_x509_export_to_file(OpenSSLCertificate|string `$certificate`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_x509_export_to_file() stocke un certificat `certificate` dans le fichier `output_filename` au format PEM.

### Liste de paramètres

`certificate`
  Voir les paramètres clés/Certificats pour une liste de valeurs valides.
`output_filename`

  Chemin du fichier de sortie.

`no_text`
  Le paramètre optionnel `notext` affecte le niveau verbeux de l'affichage ; s'il vaut `false`, des informations humainement lisibles seront ajoutées dans l'affichage. Par défaut, le paramètre `notext` vaut `true`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.

# openssl_x509_fingerprint

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_x509_fingerprint — Calcule l'empreinte, ou le digest d'un certificat X.509 donné

### Description

function openssl_x509_fingerprint(OpenSSLCertificate|string `$certificate`, string `$digest_algo` = "sha1", bool `$binary` = `false`): string|false

La fonction openssl_x509_fingerprint() retourne le digest d'un certificat `certificate` sous la forme d'une chaîne de caractères.

### Liste de paramètres

`certificate`
  Voir les paramètres clés/Certificats pour une liste de valeurs valides.
`digest_algo`

  La méthode de digest ou l'algorithme de hachage à utiliser, par exemple "sha256", l'un de openssl_get_md_methods().

`binary`

  Lorsque défini à `true`, affiche les données brutes binaires. `false` affiche en hexits minuscules.

### Valeurs de retour

Retourne une chaîne de caractères contenant l'empreinte calculée du certificat sous la forme d'hexits minuscules sauf si `binary` est défini à `true` dans ce cas la représentation brute binaire du message digest est retournée.

Retourne `false` en cas d'échec.

### Historique

Version | Description
--- | ---
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.

# openssl_x509_free

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_free — Libère les ressources prises par un certificat

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function openssl_x509_free(OpenSSLCertificate `$certificate`): void

> Note: Cette fonction n'a aucun effet. Antérieur à PHP 8.0.0, cette fonction était utilisé pour fermer une ressource.

openssl_x509_free() libère les ressources mémoire prises par le certificat `certificate`.

### Liste de paramètres

`certificate`

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est désormais obsolète car elle n'a plus d'effet.
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.

# openssl_x509_parse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_parse — Analyse un certificat X509

### Description

function openssl_x509_parse(OpenSSLCertificate|string `$certificate`, bool `$short_names` = `true`): array|false

openssl_x509_parse() analyse le certificat X509 `certificate`, et retourne les informations contenues dedans, y compris le sujet (`subject`), nom (`name`), émetteur (`issuer name`), dates de début et de fin (`valid from date` et `valid to date`), etc.

### Liste de paramètres

`certificate`

  Certificat X509. Voir paramètre de Clé/Certificat pour une liste de valeurs valides.

`short_names`

  `short_names` contrôle l'indexation des données dans le tableau : si `short_names` vaut `true` (valeur par défaut), alors les champs seront indexés avec la forme courte des noms, sinon, les noms longs seront utilisés. (par exemple, `CN` est le nom court de `commonName`).

### Valeurs de retour

La structure des données retournées est (délibérément) non documentée, car elle est sujette à des changements sans préavis.

### Historique

Version | Description
--- | ---
8.4.0 | L'analyse d'un certificat sans secondes dans UTCTime n'est plus autorisée pour aucune version d'OpenSSL. Cela était déjà interdit pour OpenSSL version 3.3+.
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.

# openssl_x509_read

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_read — Analyse un certificat X.509 et retourne un objet

### Description

function openssl_x509_read(OpenSSLCertificate|string `$certificate`): OpenSSLCertificate|false

openssl_x509_read() analyse le certificat `certificate` et retourne un objet OpenSSLCertificate pour celui-ci.

### Liste de paramètres

`certificate`

  Certificat X509. Voir paramètres clés/certificats pour la liste des valeurs valides.

### Valeurs de retour

Retourne un OpenSSLCertificate en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Un `E_WARNING` est émis si le certificat X.509 ne peut pas être récupéré.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était retournée.
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.

# openssl_x509_verify

(PHP 7 >= 7.4.0, PHP 8)

openssl_x509_verify — Vérifie la signature numérique d'un certificat x509 par rapport à une clé publique

### Description

function openssl_x509_verify(OpenSSLCertificate|string `$certificate`, OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): int

La fonction openssl_x509_verify() vérifie que le certificat `certificate` a été signé par la clé privée correspondant à la clé publique `public_key`.

### Liste de paramètres

`certificate`
  Voir les paramètres clés/Certificats pour une liste de valeurs valides.
`public_key`

  OpenSSLAsymmetricKey - une clé, retournée par la fonction openssl_get_publickey()

  string - une clé formatée PEM, par exemple, `-----BEGIN PUBLIC KEY----- MIIBCgK...`.

### Valeurs de retour

Retourne 1 si la signature est correcte, 0 si elle est incorrecte, et -1 si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `certificate` accepte désormais une instance de OpenSSLCertificate ; auparavant, une resource de type `OpenSSL X.509` était acceptée.
8.0.0 | `public_key` accepte désormais une instance de OpenSSLAsymmetricKey ou OpenSSLCertificate ; auparavant, une resource de type `OpenSSL key` ou `OpenSSL X.509` était acceptée.

### Exemples

Exemple #1 Exemple avec openssl_x509_verify()

    <?php
    $hostname = "news.php.net";
    $ssloptions = array(
        "capture_peer_cert" => true,
        "capture_peer_cert_chain" => true,
        "allow_self_signed"=> false,
        "CN_match" => $hostname,
        "verify_peer" => true,
        "SNI_enabled" => true,
        "SNI_server_name" => $hostname,
    );

    $ctx = stream_context_create( array("ssl" => $ssloptions) );
    $result = stream_socket_client("ssl://$hostname:443", $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $ctx);
    $cont = stream_context_get_params($result);
    $x509 = $cont["options"]["ssl"]["peer_certificate"];
    $certparsed = openssl_x509_parse($x509);

    foreach($cont["options"]["ssl"]["peer_certificate_chain"] as $chaincert)
    {
        $chainparsed = openssl_x509_parse($chaincert);
        $chain_public_key = openssl_get_publickey($chaincert);
        $r = openssl_x509_verify($x509, $chain_public_key);
        if ($r==1)
        {
            echo $certparsed['subject']['CN'];
            echo " a été signé numériquement par ";
            echo $chainparsed['subject']['CN']."\n";
        }
    }
    ?>

### Voir aussi

- openssl_verify() - Vérifie une signature
- openssl_get_publickey() - Alias de openssl_pkey_get_public

## Sommaire

- openssl_cipher_iv_length — Récupère la longueur cipher iv
- openssl_cipher_key_length — Renvoie la longueur de la clé de chiffrement
- openssl_cms_decrypt — Déchiffre un message CMS
- openssl_cms_encrypt — Chiffre un message CMS
- openssl_cms_read — Exporte le fichier CMS vers un tableau de certificats PEM
- openssl_cms_sign — Signe un fichier
- openssl_cms_verify — Vérifie une signature CMS
- openssl_csr_export — Exporte un CSR vers un fichier ou une variable
- openssl_csr_export_to_file — Exporte une CSR vers un fichier
- openssl_csr_get_public_key — Retourne la clé publique d'un CSR
- openssl_csr_get_subject — Retourne le sujet d'une CSR
- openssl_csr_new — Génère une CSR
- openssl_csr_sign — Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat
- openssl_decrypt — Déchiffre les données
- openssl_dh_compute_key — Calcule un secret partagé pour une valeur publique de la clé DH publique distante et la clé DH locale
- openssl_digest — Calcule un digest
- openssl_encrypt — Chiffre les données
- openssl_error_string — Retourne le message d'erreur OpenSSL
- openssl_free_key — Libère les ressources
- openssl_get_cert_locations — Récupère les chemins vers les certificats disponibles
- openssl_get_cipher_methods — Récupère la liste des méthodes de chiffrements disponibles
- openssl_get_curve_names — Récupère la liste des noms de courbes disponibles pour ECC
- openssl_get_md_methods — Récupère la liste des méthodes digest disponibles
- openssl_get_privatekey — Alias de openssl_pkey_get_private
- openssl_get_publickey — Alias de openssl_pkey_get_public
- openssl_open — Ouvre des données scellées
- openssl_password_hash — Crée un hachage de mot de passe en utilisant l'implémentation Argon2 d'OpenSSL
- openssl_password_verify — Vérifie un mot de passe par rapport à un hachage en utilisant l'implémentation Argon2 d'OpenSSL
- openssl_pbkdf2 — Génère une chaîne PKCS5 v2 PBKDF2
- openssl_pkcs12_export — Exporte un certificat compatible PKCS#12 dans une variable
- openssl_pkcs12_export_to_file — Exporte un certificat compatible PKCS#12
- openssl_pkcs12_read — Lit un certificat PKCS#12 dans un tableau
- openssl_pkcs7_decrypt — Déchiffre un message S/MIME
- openssl_pkcs7_encrypt — Chiffre un message S/MIME
- openssl_pkcs7_read — Exporte le fichier PKCS7 vers un tableau de certificats PEM
- openssl_pkcs7_sign — Signe un message S/MIME
- openssl_pkcs7_verify — Vérifie la signature d'un message S/MIME
- openssl_pkey_derive — Calcule le secret partagé pour la valeur publique de la clé DH ou ECDH distante et locale
- openssl_pkey_export — Stocke une représentation exportable de la clé dans une chaîne de caractères
- openssl_pkey_export_to_file — Sauve une clé au format ASCII dans un fichier
- openssl_pkey_free — Libère une clé privée
- openssl_pkey_get_details — Retourne un tableau contenant les détails de la clé
- openssl_pkey_get_private — Lit une clé privée
- openssl_pkey_get_public — Extrait une clé publique d'un certificat, et la prépare
- openssl_pkey_new — Génère une nouvelle clé privée
- openssl_private_decrypt — Déchiffre des données avec une clé privée
- openssl_private_encrypt — Chiffre des données avec une clé privée
- openssl_public_decrypt — Déchiffre des données avec une clé publique
- openssl_public_encrypt — Chiffre des données avec une clé publique
- openssl_random_pseudo_bytes — Génère une chaîne pseudo-aléatoire d'octets
- openssl_seal — Scelle des données
- openssl_sign — Signe les données
- openssl_spki_export — Exporte un PEM valide formaté comme une clé publique signée
- openssl_spki_export_challenge — Exporte le challenge associé avec la clé publique signée
- openssl_spki_new — Génère une clé publique signée et effectue un challenge
- openssl_spki_verify — Vérifie une clé publique signée, et effectue un challenge
- openssl_verify — Vérifie une signature
- openssl_x509_check_private_key — Vérifie si une clé privée correspond à un certificat
- openssl_x509_checkpurpose — Vérifie l'usage d'un certificat
- openssl_x509_export — Exporte un certificat vers une chaîne de caractères
- openssl_x509_export_to_file — Exporte un certificat vers un fichier
- openssl_x509_fingerprint — Calcule l'empreinte, ou le digest d'un certificat X.509 donné
- openssl_x509_free — Libère les ressources prises par un certificat
- openssl_x509_parse — Analyse un certificat X509
- openssl_x509_read — Analyse un certificat X.509 et retourne un objet
- openssl_x509_verify — Vérifie la signature numérique d'un certificat x509 par rapport à une clé publique

# La classe OpenSSLCertificate

(PHP 8)

## Introduction

Une classe entièrement opaque qui remplace les ressources `OpenSSL X.509` à partir de PHP 8.0.0.

## Synopsis de la classe

final class OpenSSLCertificate {
}

# La classe OpenSSLCertificateSigningRequest

(PHP 8)

## Introduction

Une classe entièrement opaque qui remplace les ressources `OpenSSL X.509 CSR` à partir de PHP 8.0.0.

## Synopsis de la classe

final class OpenSSLCertificateSigningRequest {
}

# La classe OpenSSLAsymmetricKey

(PHP 8)

## Introduction

Une classe entièrement opaque qui remplace les ressources `OpenSSL key` à partir de PHP 8.0.0.

## Synopsis de la classe

final class OpenSSLAsymmetricKey {
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
  - Options de validations générales
  - Options de remplissage (Padding) pour le chiffrement asymétrique
  - Types de clés
  - Constantes/options PKCS7
  - Drapeaux/Constantes CMS
  - Algorithmes de signature
  - Chiffrements
  - Constantes de version
  - Constantes d'identification du nom de serveur
  - Autres constantes
- Paramètres clés/certificats
- Vérification de certificats
- Fonctions OpenSSL
  - openssl_cipher_iv_length — Récupère la longueur cipher iv
  - openssl_cipher_key_length — Renvoie la longueur de la clé de chiffrement
  - openssl_cms_decrypt — Déchiffre un message CMS
  - openssl_cms_encrypt — Chiffre un message CMS
  - openssl_cms_read — Exporte le fichier CMS vers un tableau de certificats PEM
  - openssl_cms_sign — Signe un fichier
  - openssl_cms_verify — Vérifie une signature CMS
  - openssl_csr_export — Exporte un CSR vers un fichier ou une variable
  - openssl_csr_export_to_file — Exporte une CSR vers un fichier
  - openssl_csr_get_public_key — Retourne la clé publique d'un CSR
  - openssl_csr_get_subject — Retourne le sujet d'une CSR
  - openssl_csr_new — Génère une CSR
  - openssl_csr_sign — Signe un CSR avec un autre certificat (ou lui-même) et génère un certificat
  - openssl_decrypt — Déchiffre les données
  - openssl_dh_compute_key — Calcule un secret partagé pour une valeur publique de la clé DH publique distante et la clé DH locale
  - openssl_digest — Calcule un digest
  - openssl_encrypt — Chiffre les données
  - openssl_error_string — Retourne le message d'erreur OpenSSL
  - openssl_free_key — Libère les ressources
  - openssl_get_cert_locations — Récupère les chemins vers les certificats disponibles
  - openssl_get_cipher_methods — Récupère la liste des méthodes de chiffrements disponibles
  - openssl_get_curve_names — Récupère la liste des noms de courbes disponibles pour ECC
  - openssl_get_md_methods — Récupère la liste des méthodes digest disponibles
  - openssl_get_privatekey — Alias de openssl_pkey_get_private
  - openssl_get_publickey — Alias de openssl_pkey_get_public
  - openssl_open — Ouvre des données scellées
  - openssl_password_hash — Crée un hachage de mot de passe en utilisant l'implémentation Argon2 d'OpenSSL
  - openssl_password_verify — Vérifie un mot de passe par rapport à un hachage en utilisant l'implémentation Argon2 d'OpenSSL
  - openssl_pbkdf2 — Génère une chaîne PKCS5 v2 PBKDF2
  - openssl_pkcs12_export — Exporte un certificat compatible PKCS#12 dans une variable
  - openssl_pkcs12_export_to_file — Exporte un certificat compatible PKCS#12
  - openssl_pkcs12_read — Lit un certificat PKCS#12 dans un tableau
  - openssl_pkcs7_decrypt — Déchiffre un message S/MIME
  - openssl_pkcs7_encrypt — Chiffre un message S/MIME
  - openssl_pkcs7_read — Exporte le fichier PKCS7 vers un tableau de certificats PEM
  - openssl_pkcs7_sign — Signe un message S/MIME
  - openssl_pkcs7_verify — Vérifie la signature d'un message S/MIME
  - openssl_pkey_derive — Calcule le secret partagé pour la valeur publique de la clé DH ou ECDH distante et locale
  - openssl_pkey_export — Stocke une représentation exportable de la clé dans une chaîne de caractères
  - openssl_pkey_export_to_file — Sauve une clé au format ASCII dans un fichier
  - openssl_pkey_free — Libère une clé privée
  - openssl_pkey_get_details — Retourne un tableau contenant les détails de la clé
  - openssl_pkey_get_private — Lit une clé privée
  - openssl_pkey_get_public — Extrait une clé publique d'un certificat, et la prépare
  - openssl_pkey_new — Génère une nouvelle clé privée
  - openssl_private_decrypt — Déchiffre des données avec une clé privée
  - openssl_private_encrypt — Chiffre des données avec une clé privée
  - openssl_public_decrypt — Déchiffre des données avec une clé publique
  - openssl_public_encrypt — Chiffre des données avec une clé publique
  - openssl_random_pseudo_bytes — Génère une chaîne pseudo-aléatoire d'octets
  - openssl_seal — Scelle des données
  - openssl_sign — Signe les données
  - openssl_spki_export — Exporte un PEM valide formaté comme une clé publique signée
  - openssl_spki_export_challenge — Exporte le challenge associé avec la clé publique signée
  - openssl_spki_new — Génère une clé publique signée et effectue un challenge
  - openssl_spki_verify — Vérifie une clé publique signée, et effectue un challenge
  - openssl_verify — Vérifie une signature
  - openssl_x509_check_private_key — Vérifie si une clé privée correspond à un certificat
  - openssl_x509_checkpurpose — Vérifie l'usage d'un certificat
  - openssl_x509_export — Exporte un certificat vers une chaîne de caractères
  - openssl_x509_export_to_file — Exporte un certificat vers un fichier
  - openssl_x509_fingerprint — Calcule l'empreinte, ou le digest d'un certificat X.509 donné
  - openssl_x509_free — Libère les ressources prises par un certificat
  - openssl_x509_parse — Analyse un certificat X509
  - openssl_x509_read — Analyse un certificat X.509 et retourne un objet
  - openssl_x509_verify — Vérifie la signature numérique d'un certificat x509 par rapport à une clé publique
- OpenSSLCertificate — La classe OpenSSLCertificate
- OpenSSLCertificateSigningRequest — La classe OpenSSLCertificateSigningRequest
- OpenSSLAsymmetricKey — La classe OpenSSLAsymmetricKey

# Hachage de mot de passe

# Introduction

L'API de hachage de mot de passe fournit une enveloppe simple à utiliser reposant sur la fonction crypt() et autres algorithmes de hachage de mots de passe, rendant simple la création et la gestion des mots de passe, de manière sécurisée.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Aucune bibliothèque externe n'est nécessaire pour compiler cette extension.

Pour le hachage de mots de passe Argon2, soit » libargon2 est requis ou, à partir de PHP 8.4.0, la version OpenSSL 3.2 ou ultérieure. À partir de PHP 7.3.0, la version 20161029 ou ultérieure de libargon2 est requise si libargon2 est utilisée.

## Installation

Il n'y pas d'installation nécessaire pour utiliser ces fonctions, elles font parties du cœur de PHP.

Cependant, pour activer le hachage de mots de passe Argon2, PHP doit être compilé soit avec le support libargon2 en utilisant l'option de configuration --with-password-argon2 ou, à partir de PHP 8.4.0, avec OpenSSL en utilisant --with-openssl et --with-openssl-argon2.

Antérieur à PHP 8.1.0, il était possible de spécifier le répertoire argon2 avec --with-password-argon2[=DIR].

# Constantes pré-définies

Les constantes listées ici sont toujours disponibles dans PHP.

`PASSWORD_BCRYPT` (string)

  La constante `PASSWORD_BCRYPT` est utilisée pour créer de nouveaux hachages de mot de passe en utilisant l'algorithme `CRYPT_BLOWFISH`.

  Elle a toujours retourné le résultat de hachage en utilisant le format crypt "$2y$", qui sera toujours une chaîne de caractères de 60 caractères de long.

  Options supportées :

  - `salt` (string) - permet de fournir manuellement un salt à utiliser pour le hachage du mot de passe. À noter que ceci va écraser tout salt généré automatiquement.

    Si omis, un salt aléatoire sera généré par la fonction password_hash() pour chaque mot de passe haché. C'est bien le but de l'opération et à partir de PHP 7.0.0 l'option salt a été désapprouvée.

  - `cost` (int) - le coût algorithmique à utiliser. Des exemples de ces valeurs peuvent être trouvés sur la page de la documentation de la fonction crypt().

    Si omis, une valeur par défaut de `12` sera utilisée. C'est une bonne base mais il serait possible de vouloir l'augmenter suivant l'architecture matérielle.

`PASSWORD_BCRYPT_DEFAULT_COST` (int)

`PASSWORD_ARGON2I` (string)

  `PASSWORD_ARGON2I` est utilisé pour créer de nouveaux hashs de mot de passe à l'aide de l'algorithme Argon2i.

  Options prises en charge :

  - `memory_cost` (int) - Mémoire maximale (en kibioctets) pouvant être utilisée pour calculer le hachage Argon2. Par défaut à `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

  - `time_cost` (int) - Durée maximale de temps qu'il peut prendre pour calculer le hachage Argon2. Par défaut à `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

  - `threads` (int) - Nombre de threads à utiliser pour calculer le hachage Argon2. Par défaut à `PASSWORD_ARGON2_DEFAULT_THREADS`. Uniquement disponible avec libargon2, et non avec l'implémentation libsodium.

  Disponible à partir de PHP 7.2.0.

`PASSWORD_ARGON2ID` (string)

  `PASSWORD_ARGON2ID` est utilisé pour créer de nouveaux hashs de mot de passe à l'aide de l'algorithme Argon2id. Supporte les mêmes options que `PASSWORD_ARGON2I`.

  Disponible à partir de PHP 7.3.0.

`PASSWORD_ARGON2_DEFAULT_MEMORY_COST` (int)

  Quantité de mémoire par défaut (en octets) qui sera utilisée en essayant de calculer un hachage.

  Disponible à partir de PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_TIME_COST` (int)

  Durée de temps par défaut qui sera consacrée pour essayer de calculer un hachage.

  Disponible à partir de PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_THREADS` (int)

  Nombre par défaut de threads que Argon2lib va utiliser. Pas disponible avec l'implémentation libsodium.

  Disponible à partir de PHP 7.2.0.

`PASSWORD_ARGON2_PROVIDER` (string)

  Disponible à partir de PHP 7.4.0.

`PASSWORD_DEFAULT` (string)

  L'algorithme par défaut à utiliser pour le hachage si aucun algorithme n'est fourni. Cette valeur peut changer dans les futures versions de PHP où il est probable que de meilleurs algorithmes de hachage soient supportés.

  Il est important de noter qu'au fil du temps, cette constante peut changer. Il est donc crucial d'être conscient que la longueur du hachage résultant peut varier. Par conséquent, lors de l'utilisation de `PASSWORD_DEFAULT`, le hachage résultant doit être stocké d'une manière capable d'accueillir des hachages arbitraires, la largeur recommandée est de `255` octets.

  Actuellement, c'est un alias de `PASSWORD_BCRYPT`.

##### Historique

Version | Description
--- | ---
7.4.0 | Les valeurs pour les constantes `PASSWORD_BCRYPT`, `PASSWORD_ARGON2I`, `PASSWORD_ARGON2ID` et `PASSWORD_DEFAULT` sont désormais des chaîne de caractèress. Auparavant, elles étaient des entiers.

# Fonctions de hachage de mot de passe

# password_algos

(PHP 7 >= 7.4.0, PHP 8)

password_algos — Récupère tous les identifiants des algorithmes de hachage de mots de passe disponibles

### Description

function password_algos(): array

Retourne une liste complète de tous les identifiants des algorithmes de hachage de mots de passe enregistrés, sous la forme d'un tableau de chaîne de caractères.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne tous les identifiants des algorithmes de hachage de mots de passe disponibles.

### Exemples

Exemple #1 Utilisation basique de la fonction password_algos()

    <?php
    print_r(password_algos());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 2y
        [1] => argon2i
        [2] => argon2id
    )

# password_get_info

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_get_info — Retourne des informations à propos du hachage fourni

### Description

function password_get_info(string `$hash`): array

Lorsqu'il est passé un hachage valide, créé par un algorithme supporté par la fonction password_hash(), cette fonction retournera un tableau d'information à propos de ce dernier.

### Liste de paramètres

`hash`

  Un hachage créé par la fonction password_hash().

### Valeurs de retour

Retourne un tableau associatif contenant trois éléments :

- `algo`, qui doit correspondre à une constante de l'algorithme de mot de passe
- `algoName`, qui correspond au nom humainement lisible de l'algorithme
- `options`, qui contient les options fournies lors de l'appel de la fonction password_hash()

# password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — Crée une clé de hachage pour un mot de passe

### Description

function password_hash(#[\SensitiveParameter]string `$password`, string|int|null `$algo`, array `$options` = []): string

La fonction password_hash() crée un nouveau hachage en utilisant un algorithme de hachage fort et irréversible.

Les algorithmes suivants sont actuellement supportés :

- `PASSWORD_DEFAULT` - Utilisation de l'algorithme bcrypt (par défaut à partir de PHP 5.5.0). Il est à noter que cette constante est conçue pour changer dans le temps, au fur et à mesure que des algorithmes plus récents et plus forts sont ajoutés à PHP. Pour cette raison, la longueur du résultat issu de cet algorithme peut changer dans le temps, il est donc recommandé de stocker le résultat dans une colonne de la base de données qui peut s'étendre au-delà de 60 octets (255 octets peut être un très bon choix).
- `PASSWORD_BCRYPT` - Utilisation de l'algorithme bcrypt pour créer la clé de hachage. Ceci va créer une clé de hachage standard crypt() utilisant l'identifiant `$2y$`.
- `PASSWORD_ARGON2I` - Utilise l'algorithme de hachage Argon2i pour créer le hachage. Cet algorithme est seulement disponible si PHP a été compilé avec le support d'Argon2
- `PASSWORD_ARGON2ID` - Utilise l'algorithme de hachage Argon2id pour créer le hachage. Cet algorithme est seulement disponible si PHP a été compilé avec le support d'Argon2

Options supportées pour `PASSWORD_BCRYPT`:

- `salt` - pour fournir manuellement un salt à utiliser lors du hachage du mot de passe. Il est à noter que cette option empêchera la génération automatique.

  Si omis, un salt aléatoire sera généré par la fonction password_hash() pour chaque mot de passe haché. C'est le mode de fonctionnement prévu.

  Avertissement

  L'option Salt est obsolète. Il est préférable d'utiliser simplement le sel qui est généré par défaut. À partir de PHP 8.0.0, un sel explicitement fourni est ignoré.

- `cost` - détermine le coût algorithmique qui doit être utilisé. Des exemples de ces valeurs peuvent être trouvés sur la page de la documentation de la fonction crypt().

  Si omis, la valeur par défaut `12` sera utilisée. C'est un bon compromis, mais cela doit être ajusté en fonction du matériel utilisé.

Options supportées pour `PASSWORD_ARGON2I` et `PASSWORD_ARGON2ID` :

- `memory_cost` (int) - Mémoire maximale (en kibioctets) pouvant être utilisée pour calculer le hachage Argon2. Par défaut à `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

- `time_cost` (int) - Durée maximale de temps qu'il peut prendre pour calculer le hachage Argon2. Par défaut à `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

- `threads` (int) - Nombre de threads à utiliser pour calculer le hachage Argon2. Par défaut à `PASSWORD_ARGON2_DEFAULT_THREADS`.

  Avertissement

  Uniquement disponible quand PHP utilise libargon2, et non l'implémentation libsodium.

### Liste de paramètres

`password`

  Le mot de passe utilisateur.

  Attention

  L'utilisation de la constante `PASSWORD_BCRYPT` pour l'algorithme fera que le paramètre `password` sera tronqué à une longueur maximale de 72 octets.

`algo`

  Une constantes de l'algorithme de mot de passe représentant l'algorithme à utiliser lors du hachage du mot de passe.

`options`

  Un tableau associatif contenant les options. Voir aussi les constantes de l'algorithme de mot de passe pour une documentation sur les options supportées pour chaque algorithme.

### Valeurs de retour

Retourne le mot de passe haché.

L'algorithme utilisé, le coût et le salt sont contenus dans le hachage retourné. Aussi, toutes les informations utiles pour vérifier ce dernier y sont incluses. Ceci permet à la fonction password_verify() de vérifier le hachage sans avoir besoin de stocker séparément ces informations.

### Historique

Version | Description
--- | ---
8.4.0 | La valeur par défaut de l'option `cost` de l'algorithme `PASSWORD_BCRYPT` a été augmentée de `10` à `12`.
8.3.0 | password_hash() associe désormais l'exception Random\RandomException sous-jacente à Exception::$previous lorsqu'une ValueError est levée en raison d'un échec de la génération du sel.
8.0.0 | password_hash() ne retourne plus `false` en cas d'échec, une ValueError sera levée si l'algorithme de hachage de mot de passe n'est pas valide, ou une Error si le hachage de mot de passe a échoué pour une raison inconnue.
8.0.0 | `algo` est désormais nullable.
7.4.0 | Le paramètre `algo` attend désormais une chaîne de caractères, mais continue d'accepter un entier afin de conserver une compatibilité antérieure.
7.4.0 | L'extension sodium fournit une implémentation alternative pour les mots de passe Argon2.
7.3.0 | Ajout de la prise en charge des mots de passe Argon2id à l'aide de `PASSWORD_ARGON2ID`.
7.2.0 | Ajout de la prise en charge des mots de passe Argon2i à l'aide de `PASSWORD_ARGON2I`.

### Exemples

Exemple #1 Exemple avec password_hash()

    <?php
    echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    $2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

Exemple #2 Exemple avec password_hash() en définissant manuellement l'option cost

    <?php
    $options = [
         // Augmente le coût de bcrypt de 12 à 13.
        'cost' => 13,
    ];
    echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    $2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

Exemple #3 Exemple avec password_hash() pour trouver un bon coût

Ce code effectuera un benchmark de la machine afin de déterminer le coût maximal pouvant être utilisé sans dégrader l'expérience utilisateur. Il est recommandé de choisir le coût le plus élevé possible sans ralentir les autres opérations que la machine doit exécuter. 11 constitue une bonne base, et une valeur plus élevée est préférable si la machine est suffisamment rapide. Le code ci-dessous vise un temps d'étirement ≤ 350 millisecondes, ce qui représente un délai adapté aux systèmes gérant des connexions interactives.

    <?php
    $timeTarget = 0.350; // 350 millisecondes

    $cost = 11;
    do {
        $cost++;
        $start = microtime(true);
        password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
        $end = microtime(true);
    } while (($end - $start) < $timeTarget);

    echo "Valeur de 'cost' la plus appropriée : " . $cost - 1;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Valeur de 'cost' la plus appropriée : 13

Exemple #4 Exemple avec password_hash() et Argon2i

    <?php
    echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

### Notes

Attention

Il est fortement recommandé de ne pas fournir de sel explicite pour cette fonction. Un sel sécurisé sera automatiquement généré si aucun sel n'est spécifié.

Comme mentionné ci-dessus, l'utilisation de l'option `salt` à partir de PHP 7.0.0 générera un avertissement de dépréciation. La prise en charge d'un sel explicite a été supprimée à partir de PHP 8.0.0.

> Note:

> Il est recommandé de tester cette fonction sur la machine utilisée et d'ajuster le(s) paramètre(s) de coût afin que l'exécution de la fonction prenne moins de 350 millisecondes pour les connexions interactives. Le script de l'exemple ci-dessus aidera à choisir un coût bcrypt adapté à la machine donnée.

> Note: La mise à jour des algorithmes supportés par cette fonction (ou le changement à celui par défaut) doit suivre les règles suivantes :

> - Chaque nouvel algorithme doit faire partie du cœur de PHP pendant au moins 1 version complète avant de prétendre à devenir l'algorithme par défaut. Aussi, si, par exemple, un nouvel algorithme est ajouté en version 7.5.5, il ne sera éligible comme algorithme par défaut qu'à partir de PHP 7.7 (sachant que 7.6 sera la première version complète). Mais si un algorithme différent a été ajouté en 7.6.0, il sera aussi éligible comme algorithme par défaut à partir de la version 7.7.0.
> - L'algorithme par défaut ne peut être changé que lors d'une version complète (7.3.0, 8.0.0, etc.) et non pendant une version de révision. La seule exception à ce principe de base serait une urgence, par exemple, lors de la découverte d'un bogue critique au niveau de la sécurité dans l'algorithme par défaut.

### Voir aussi

- password_verify() - Vérifie qu'un mot de passe correspond à un hachage
- password_needs_rehash() - Vérifie que le hachage fourni est conforme à l'algorithme et aux options spécifiées
- crypt() - Hachage à sens unique (indéchiffrable)
- sodium_crypto_pwhash_str() - Renvoie un hachage encodé en ASCII

# password_needs_rehash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_needs_rehash — Vérifie que le hachage fourni est conforme à l'algorithme et aux options spécifiées

### Description

function password_needs_rehash(string `$hash`, string|int|null `$algo`, array `$options` = []): bool

Cette fonction vérifie que le hachage fourni correspond à l'algorithme et aux options spécifiées. Si ce n'est pas le cas, le hachage devrait être re-généré.

### Liste de paramètres

`hash`

  Un hachage créé par la fonction password_hash().

`algo`

  Une constantes de l'algorithme de mot de passe représentant l'algorithme à utiliser lors du hachage du mot de passe.

`options`

  Un tableau associatif contenant les options. Voir aussi les constantes de l'algorithme de mot de passe pour une documentation sur les options supportées pour chaque algorithme.

### Valeurs de retour

Retourne `true` si le hachage doit être re-généré pour correspondre aux paramètres `algo` et `options` fournis, ou `false` sinon.

### Historique

Version | Description
--- | ---
7.4.0 | Le paramètre `algo` attend désormais une chaîne de caractères, mais continue d'accepter un entier afin de conserver une compatibilité antérieure.

### Exemples

Exemple #1 Usage de password_needs_rehash()

    <?php

    $password = 'rasmuslerdorf';
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    $algorithm = PASSWORD_BCRYPT;
    // Le paramètre cost de bcrypt peut évoluer avec le temps en fonction des améliorations matérielles.
    $options = ['cost' => 13];

    // Vérifions d'abord que le mot de passe correspond au hachage stocké
    if (password_verify($password, $hash)) {
        // Vérifie si soit l'algorithme ou les options ont changé
        if (password_needs_rehash($hash, $algorithm, $options)) {
            // On crée un nouveau hachage afin de mettre à jour l'ancien
            $newHash = password_hash($password, $algorithm, $options);

            // Mettre à jour l'entrée de l'utilisateur avec  $newHash
        }

        // Exécute la connexion de l'utilisateur
    }
    ?>

# password_verify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_verify — Vérifie qu'un mot de passe correspond à un hachage

### Description

function password_verify(#[\SensitiveParameter]string `$password`, string `$hash`): bool

Vérifie que le hachage fourni correspond bien au mot de passe fourni. La fonction password_verify() est compatible avec la fonction crypt(). Ainsi, un mot de passe haché par la fonction crypt() peut être utilisé avec la fonction password_verify().

Il est à noter que la fonction password_hash() retourne l'algorithme, le "cost", et le salt comme parties du hachage retourné. Par conséquent, toutes les informations nécessaires pour vérifier le hachage y sont incluses. Ceci permet à la fonction de vérifier le hachage sans avoir besoin d'un stockage séparé pour les informations concernant l'algorithme et le salt.

Cette fonction est sans danger contre les attaques sur le temps.

### Liste de paramètres

`password`

  Le mot de passe utilisateur.

`hash`

  Un hachage créé par la fonction password_hash().

### Valeurs de retour

Retourne `true` si le mot de passe et le hachage correspondent, ou `false` sinon.

### Exemples

Exemple #1 Exemple avec password_verify()

Ceci est un exemple simplifié ; il est recommandé de ré-hacher un mot de passe correct si nécessaire ; voir la fonction password_needs_rehash() pour un exemple.

    <?php
    // Voir l'exemple fourni sur la page de la fonction password_hash()
    // pour savoir d'où cela provient.
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    if (password_verify('rasmuslerdorf', $hash)) {
        echo 'Le mot de passe est valide !';
    } else {
        echo 'Le mot de passe est invalide.';
    }
    ?>

L'exemple ci-dessus va afficher :

    Le mot de passe est valide !

### Voir aussi

- password_needs_rehash() - Vérifie que le hachage fourni est conforme à l'algorithme et aux options spécifiées
- password_hash() - Crée une clé de hachage pour un mot de passe
- sodium_crypto_pwhash_str_verify() - Vérifie qu'un mot de passe correspond à un hachage

## Sommaire

- password_algos — Récupère tous les identifiants des algorithmes de hachage de mots de passe disponibles
- password_get_info — Retourne des informations à propos du hachage fourni
- password_hash — Crée une clé de hachage pour un mot de passe
- password_needs_rehash — Vérifie que le hachage fourni est conforme à l'algorithme et aux options spécifiées
- password_verify — Vérifie qu'un mot de passe correspond à un hachage

- Installation/Configuration
  - Pré-requis
  - Installation
- Constantes pré-définies
- Fonctions de hachage de mot de passe
  - password_algos — Récupère tous les identifiants des algorithmes de hachage de mots de passe disponibles
  - password_get_info — Retourne des informations à propos du hachage fourni
  - password_hash — Crée une clé de hachage pour un mot de passe
  - password_needs_rehash — Vérifie que le hachage fourni est conforme à l'algorithme et aux options spécifiées
  - password_verify — Vérifie qu'un mot de passe correspond à un hachage

# Rnp

# Introduction

Avertissement

Cette extension est EXPERIMENTALE. Le comportement de cette extension, les noms de ses fonctions, et toute la documentation autour de cette extension peut changer sans préavis dans une prochaine version de PHP. Cette extension doit être utilisée à vos risques et périls.

Ce module permet d'utiliser la bibliothèque » RNP. RNP est une bibliothèque OpenPGP C++ haute performance utilisée par Mozilla Thunderbird.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Pour utiliser les fonctions de la bibliothèque RNP, il faut installer la » bibliothèque RNP. La version de la bibliothèque RNP doit être >= 0.16.2.

## Installation

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/rnp

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`RNP_KEYSTORE_GPG` (string)
  Format du trousseau "GPG".
`RNP_KEYSTORE_KBX` (string)
  Format du trousseau "KBX". Pour les clés publiques uniquement. Une boîte à clés (keybox) est un format de fichier utilisé pour stocker des clés publiques avec des métadonnées et des indices.
`RNP_KEYSTORE_G10` (string)
  Format du trousseau "G10". Pour les clés privées.
`RNP_LOAD_SAVE_PUBLIC_KEYS` (integer)
  Charge ou sauvegarde uniquement les clés publiques. Peut être combiné avec `RNP_LOAD_SAVE_SECRET_KEYS` pour charger à la fois les clés publiques et privées dans le contexte FFI ou les sauvegarder du contexte.
`RNP_LOAD_SAVE_SECRET_KEYS` (integer)
  Charge ou sauvegarde uniquement les clés secrètes. Peut être combiné avec `RNP_LOAD_SAVE_PUBLIC_KEYS` pour charger à la fois les clés publiques et privées dans le contexte FFI ou les sauvegarder du contexte.
`RNP_LOAD_SAVE_PERMISSIVE` (integer)
  Permet d'ignorer les paquets de signature/clé/sous-clé incorrects lors de l'importation de clés.
`RNP_LOAD_SAVE_SINGLE` (integer)
  Si défini, seule la première clé sera chargée.
`RNP_LOAD_SAVE_BASE64` (integer)
  Permet l'importation de clés codées en base64 (clés autocrypt).
`RNP_FEATURE_SYMM_ALG` (string)
  Liste les algorithmes de chiffrement symétrique disponibles.
`RNP_FEATURE_AEAD_ALG` (string)
  Liste les algorithmes AEAD disponibles.
`RNP_FEATURE_PROT_MODE` (string)
  Liste les modes de protection disponibles.
`RNP_FEATURE_PK_ALG` (string)
  Liste les algorithmes de clé publique disponibles.
`RNP_FEATURE_HASH_ALG` (string)
  Liste les algorithmes de hachage disponibles.
`RNP_FEATURE_COMP_ALG` (string)
  Liste les algorithmes de compression disponibles.
`RNP_FEATURE_CURVE` (string)
  Liste les courbes elliptiques disponibles.
`RNP_DUMP_MPI` (integer)
  Affiche les valeurs MPI (entiers multi-précision).
`RNP_DUMP_RAW` (integer)
  Affiche également le contenu brut du paquet.
`RNP_DUMP_GRIP` (integer)
  Affiche les empreintes et les identifiants de clé.
`RNP_JSON_DUMP_MPI` (integer)
  Affiche les valeurs MPI (entiers multi-précision).
`RNP_JSON_DUMP_RAW` (integer)
  Affiche également le contenu brut du paquet.
`RNP_JSON_DUMP_GRIP` (integer)
  Affiche les empreintes et les identifiants de clé.
`RNP_ENCRYPT_NOWRAP` (integer)
  Permet le chiffrement du message signé. Le message n'est pas enveloppé dans un paquet de données littérales.
`RNP_KEY_EXPORT_ARMORED` (integer)
  Active l'armure ASCII des données exportées.
`RNP_KEY_EXPORT_PUBLIC` (integer)
  Exporte la clé publique.
`RNP_KEY_EXPORT_SECRET` (integer)
  Exporte la clé secrète.
`RNP_KEY_EXPORT_SUBKEYS` (integer)
  Si la clé principale est exportée, toutes les sous-clés le seront également.
`RNP_KEY_EXPORT_BASE64` (integer)
  Exporte la clé autocrypt codée en base64 au lieu de binaire.
`RNP_KEY_REMOVE_PUBLIC` (integer)
  Supprime la clé publique.
`RNP_KEY_REMOVE_SECRET` (integer)
  Supprime la clé secrète.
`RNP_KEY_REMOVE_SUBKEYS` (integer)
  Si la clé principale est supprimée, toutes les sous-clés le seront également.

# Exemples

## Sommaire

- Texte signé en clair

## Texte signé en clair

Cet exemple va signer en clair un texte donné.

Exemple #1 Exemple RNP signature en clair

    <?php
    // initialise l'objet FFI
    $ffi = rnp_ffi_create('GPG', 'GPG');

    // génère une clé RSA
    $key = rnp_op_generate_key($ffi, 'test@example.com', 'RSA');

    // signe
    $data = "Example text to sign";
    $signature = rnp_op_sign_cleartext($ffi, $data, array($key));

    echo $signature;

    // détruit l'objet FFI
    rnp_ffi_destroy($ffi);
    ?>

# Fonctions de Rnp

# rnp_backend_string

(PECL rnp >= 0.1.1)

rnp_backend_string — Renvoie le nom de la bibliothèque back-end de cryptographie

### Description

function rnp_backend_string(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nom de la bibliothèque back-end de cryptographie. Les bibliothèques de cryptographie supportées sont "Botan" et "OpenSSL".

# rnp_backend_version

(PECL rnp >= 0.1.1)

rnp_backend_version — Renvoie la version de la bibliothèque back-end de cryptographie

### Description

function rnp_backend_version(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La version sous forme de chaîne.

# rnp_decrypt

(PECL rnp >= 0.1.1)

rnp_decrypt — Déchiffre un message PGP

### Description

function rnp_decrypt(RnpFFI `$ffi`, string `$input`): string|false

Les clés privées utilisées pour le déchiffrement doivent être chargées dans l'objet FFI avant d'appeler cette fonction. Si le chiffrement par mot de passe a été utilisé, le fournisseur de mot de passe doit être défini en appelant rnp_ffi_set_pass_provider().

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`input`
  Le message chiffré.

### Valeurs de retour

Le message déchiffré en cas de succès ou `false` si une erreur survient.

# rnp_dump_packets

(PECL rnp >= 0.1.1)

rnp_dump_packets — Affiche les informations du flux de paquets OpenPGP dans un format lisible par l'homme

### Description

function rnp_dump_packets(string `$input`, int `$flags`): string|false

### Liste de paramètres

`input`
  La chaîne d'entrée contenant les données OpenPGP, soit au format binaire, soit au format ASCII-armored.
`flags`
  Voir les constantes prédéfinies `RNP_DUMP_*`.

### Valeurs de retour

Un texte décrivant la séquence de paquets ou `false` si une erreur survient.

# rnp_dump_packets_to_json

(PECL rnp >= 0.1.1)

rnp_dump_packets_to_json — Affiche les informations du flux de paquets OpenPGP dans une chaîne JSON

### Description

function rnp_dump_packets_to_json(string `$input`, int `$flags`): string|false

### Liste de paramètres

`input`
  La chaîne d'entrée contenant les données OpenPGP, soit au format binaire, soit au format ASCII-armored.
`flags`
  Voir les constantes prédéfinies `RNP_JSON_DUMP_*`.

### Valeurs de retour

Une chaîne JSON avec les informations ou `false` si une erreur survient.

# rnp_ffi_create

(PECL rnp >= 0.1.1)

rnp_ffi_create — Créer un objet de niveau supérieur utilisé pour interagir avec la bibliothèque

### Description

function rnp_ffi_create(string `$pub_format`, string `$sec_format`): RnpFFI|false

### Liste de paramètres

`pub_format`
  Le format du trousseau de clés public, RNP_KEYSTORE_GPG ou autre constante RNP_KEYSTORE_*.
`sec_format`
  Le format du trousseau de clés secrètes, RNP_KEYSTORE_GPG ou autre constante RNP_KEYSTORE_*.

### Valeurs de retour

Renvoie un objet RnpFFI en cas de succès ou `false` si une erreur survient.

# rnp_ffi_destroy

(PECL rnp >= 0.1.1)

rnp_ffi_destroy — Détruit l'objet de niveau supérieur utilisé pour interagir avec la bibliothèque

### Description

function rnp_ffi_destroy(RnpFFI `$ffi`): void

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().

### Valeurs de retour

# rnp_ffi_set_pass_provider

(PECL rnp >= 0.1.1)

rnp_ffi_set_pass_provider — Définit la fonction de rappel du fournisseur de mot de passe

### Description

function rnp_ffi_set_pass_provider(RnpFFI `$ffi`, callable `$password_callback`): bool

Définit la fonction de rappel du fournisseur de mot de passe. Cette fonction peut demander le mot de passe sur une entrée standard (si le script PHP est exécuté dans un environnement de ligne de commande), afficher une boîte de dialogue GUI ou fournir le mot de passe de toutes les manières possibles. Les mots de passe demandés sont utilisés pour chiffrer ou déchiffrer les clés secrètes ou effectuer des opérations de chiffrement/déchiffrement symétriques.

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`password_callback`

  La fonction qui doit être appelée pour chaque demande de mot de passe. Elle a la signature suivante:

  function password_callback(string `$key_fp`, string `$pgp_context`, string `&$password`): bool
  - `$key_fp` - L'empreinte de la clé, le cas échéant. Peut être vide.
  - `$pgp_context` - Chaîne décrivant pourquoi la clé est demandée.
  - `$password` - Référence de chaîne où le mot de passe fourni doit être stocké.
  La fonction de rappel doit retourner `true` si le mot de passe a été défini avec succès ou `false` si une erreur survient.

### Valeurs de retour

Renvoie `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple d'une fonction de rappel simple

    <?php
    function password_callback(string $key_fp, string $pgp_context, string &$password)
    {
        $password = "password";

        return true;
    }

    $ffi = rnp_ffi_create('GPG', 'GPG');

    rnp_ffi_set_pass_provider($ffi, 'password_callback');

# rnp_import_keys

(PECL rnp >= 0.1.1)

rnp_import_keys — Importe des clés depuis une chaîne PHP vers le trousseau de clés et renvoie un JSON décrivant les clés nouvelles ou mises à jour

### Description

function rnp_import_keys(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`input`
  Les paquets OpenPGP contenant la ou les clés à charger. Peut être binaire ou ASCII armored.
`flags`
  Voir les constantes prédéfinies `RNP_LOAD_SAVE_*`.

### Valeurs de retour

Une chaîne JSON avec les informations sur les clés nouvelles et mises à jour en cas de succès ou `false` si une erreur survient.

# rnp_import_signatures

(PECL rnp >= 0.1.1)

rnp_import_signatures — Importe des signatures autonomes dans le trousseau de clés et renvoie un JSON décrivant les clés mises à jour

### Description

function rnp_import_signatures(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`input`
  Les paquets OpenPGP contenant les signatures à importer. Peut être binaire ou ASCII armé.
`flags`
  Actuellement doit être 0.

### Valeurs de retour

La chaîne JSON avec des informations sur les clés mises à jour en cas de succès ou `false` si une erreur survient.

# rnp_key_export

(PECL rnp >= 0.1.1)

rnp_key_export — Exporte une clé

### Description

function rnp_key_export(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): string|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`key_fp`
  L'empreinte de la clé.
`flags`
  Voir `RNP_KEY_EXPORT_*` constantes prédéfinies (sauf `RNP_KEY_EXPORT_BASE64`).

### Valeurs de retour

Le paquet OpenPGP exporté de la clé (binaire ou ASCII-armored) en cas de succès ou `false` si une erreur survient.

# rnp_key_export_autocrypt

(PECL rnp >= 0.1.1)

rnp_key_export_autocrypt — Exporte la clé minimale pour la fonctionnalité autocrypt (juste 5 paquets: clé, uid, signature, sous-clé de chiffrement, signature)

### Description

function rnp_key_export_autocrypt(
RnpFFI `$ffi`,
string `$key_fp`,
string `$subkey_fp`,
string `$uid`,
int `$flags`
): string|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`key_fp`
  L'empreinte de la clé primaire.
`subkey_fp`
  La sous-clé à exporter. Peut être une chaîne vide pour choisir la première sous-clé appropriée.
`uid`
  L'identifiant de l'utilisateur à exporter. Peut être une chaîne vide si la clé exportée n'a qu'un seul identifiant.
`flags`
  Seulement `RNP_KEY_EXPORT_BASE64` est actuellement supporté. L'activer exportera les données de clé encodées en base64 au lieu de binaire.

### Valeurs de retour

Les paquets OpenPGP de la clé exportée en cas de succès ou `false` si une erreur survient.

# rnp_key_export_revocation

(PECL rnp >= 0.1.1)

rnp_key_export_revocation — Génère et exporte une signature de révocation de clé primaire

### Description

function rnp_key_export_revocation(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): string|false

Notes: pour révoquer une clé, il faudra importer cette signature dans le trousseau de clés ou utiliser la fonction rnp_key_revoke().

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`key_fp`
  L'empreinte de la clé primaire à révoquer.
`flags`
  `RNP_KEY_EXPORT_ARMORED` ou 0.
`options`
  Un tableau associatif avec des options.

  Key | Type de donnée | Description
  --- | --- | ---
  `"hash"` | string | Définit l'algorithme de hachage utilisé lors du calcul de la signature.
  `"code"` | string | Code de raison de la révocation. Valeurs possibles : 'no', 'superseded', 'compromised', 'retired'. Si non défini, la valeur 'no' sera utilisée par défaut.
  `"reason"` | string | Représentation textuelle de la raison de la révocation.

### Valeurs de retour

Révocation exportée en cas de succès ou `false` si une erreur survient.

# rnp_key_get_info

(PECL rnp >= 0.1.1)

rnp_key_get_info — Renvoie des informations sur la clé

### Description

function rnp_key_get_info(RnpFFI `$ffi`, string `$key_fp`): array|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`key_fp`
  L'empreinte de la clé.

### Valeurs de retour

Un tableau associatif avec des informations sur la clé ou `false` si une erreur survient.

Key | Type de données | Description
--- | --- | ---
`"is_primary"` | boolean | `true` si cette clé est la clé primaire.
`"is_sub"` | boolean | `true` si cette clé est une sous-clé.
`"is_valid"` | boolean | `true` si la clé publique est valide. Cela inclut les vérifications des auto-signatures, les dates d'expiration, les révocations, etc.
`"is_revoked"` | boolean | `true` si cette clé est révoquée.
`"is_superseded"` | boolean | `true` si cette clé est obsolète. Présent uniquement si la clé est révoquée.
`"is_compromised"` | boolean | `true` si cette clé est compromise. Présent uniquement si la clé est révoquée.
`"is_retired"` | boolean | `true` si cette clé est retirée. Présent uniquement si la clé est révoquée.
`"is_expired"` | boolean | `true` si cette clé est expirée.
`"have_secret"` | boolean | `true` si cette clé a une partie secrète.
`"is_locked"` | boolean | `true` si cette clé est actuellement verrouillée. Présent uniquement pour les clés secrètes.
`"is_protected"` | boolean | `true` si cette clé est protégée. Présent uniquement pour les clés secrètes. Une clé protégée est une clé qui est chiffrée et peut être stockée en toute sécurité en mémoire et verrouillée/déverrouillée au besoin.
`"have_public"` | boolean | `true` si cette clé a une partie publique. En général, toutes les clés ont une partie publique.
`"valid_till"` | integer | Le timestamp jusqu'auquel la clé peut être considérée comme valide. Note : cela prendra en compte non seulement l'expiration de la clé, mais aussi les révocations. Pour la sous-clé primaire, le temps de validité de la clé publique sera également vérifié.
`"bits"` | integer | Le nombre de bits dans la clé. Pour les clés basées sur EC, cela contiendra la taille de la courbe.
`"alg"` | string | L'algorithme de nom de clé.
`"subkeys"` | array | Un tableau indexé contenant des informations sur les sous-clés. Peut être vide si la clé primaire n'a pas de sous-clés.
`"uids"` | array | Un tableau indexé contenant des informations sur les identifiants d'utilisateur. Peut être vide si la clé primaire n'a pas d'identifiants d'utilisateur.

# rnp_key_remove

(PECL rnp >= 0.1.1)

rnp_key_remove — Supprime une clé des trousseaux de clés

### Description

function rnp_key_remove(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): bool

Note: il faut appeler rnp_save_keys() pour écrire les trousseaux de clés mis à jour.

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`key_fp`
  L'empreinte de la clé.
`flags`
  Voir `RNP_KEY_REMOVE_*` constantes prédéfinies. Le drapeau `RNP_KEY_REMOVE_SUBKEYS` ne fonctionnera que pour la clé principale et supprimera également toutes ses sous-clés.

### Valeurs de retour

Renvoie `true` en cas de succès ou `false` si une erreur survient.

# rnp_key_revoke

(PECL rnp >= 0.1.1)

rnp_key_revoke — Supprime une clé ou une sous-clé en générant et ajoutant une signature de révocation

### Description

function rnp_key_revoke(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): bool

Note: il faut appeler rnp_save_keys() pour écrire les trousseaux de clés mis à jour.

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`key_fp`
  L'empreinte de la clé.
`flags`
  Actuellement doit être 0.
`options`
  Un tableau associatif avec des options.

  Key | Type de donnée | Description
  --- | --- | ---
  `"hash"` | string | Définit l'algorithme de hachage utilisé lors du calcul de la signature.
  `"code"` | string | Le code de révocation de la clé. Les valeurs possibles sont 'no', 'superseded', 'compromised', 'retired'. Si non défini, la valeur 'no' sera utilisée par défaut.
  `"reason"` | string | Représentation textuelle de la raison de la révocation.

### Valeurs de retour

Renvoie `true` en cas de succès ou `false` si une erreur survient.

# rnp_list_keys

(PECL rnp >= 0.1.1)

rnp_list_keys — Enumère toutes les clés présentes dans un trousseau de clés par type d'identifiant spécifié

### Description

function rnp_list_keys(RnpFFI `$ffi`, string `$identifier_type`): array|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`identifier_type`
  La clé de type d'identifiant ("userid", "keyid", "grip", "fingerprint").

### Valeurs de retour

Un tableau associatif où la clé est une chaîne d'identifiant et la valeur est une empreinte de clé PGP ou `false` si une erreur survient.

# rnp_load_keys

(PECL rnp >= 0.1.1)

rnp_load_keys — Charge les clés à partir d'une chaîne PHP

### Description

function rnp_load_keys(
RnpFFI `$ffi`,
string `$format`,
string `$input`,
int `$flags`
): bool

Il est à noter que pour G10, l'entrée doit être un répertoire (qui doit déjà exister).

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`format`
  Le format de clé pour la donnée (GPG, KBX, G10).
`input`
  Les paquets OpenPGP contenant la ou les clés à charger. Peut être binaire ou ASCII armored.
`flags`
  Voir la description des drapeaux `RNP_LOAD_SAVE_*`.

### Valeurs de retour

Renvoie `true` en cas de succès ou `false` si une erreur survient.

# rnp_load_keys_from_path

(PECL rnp >= 0.1.1)

rnp_load_keys_from_path — Charge des clés à partir du chemin spécifié

### Description

function rnp_load_keys_from_path(
RnpFFI `$ffi`,
string `$format`,
string `$input_path`,
int `$flags`
): bool

Il est à noter que pour G10, l'entrée doit être un répertoire (qui doit déjà exister).

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`format`
  Le format de clé pour la donnée (GPG, KBX, G10).
`input_path`
  le fichier ou le répertoire contenant les clés.
`flags`
  Voir la description des drapeaux `RNP_LOAD_SAVE_*`.

### Valeurs de retour

Renvoie `true` en cas de succès ou `false` si une erreur survient.

# rnp_locate_key

(PECL rnp >= 0.1.1)

rnp_locate_key — Recherche de la clé

### Description

function rnp_locate_key(RnpFFI `$ffi`, string `$identifier_type`, string `$identifier`): string|false

Note: les identifiants valides sont vérifiés lors de la recherche par identifiant.

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`identifier_type`
  Chaîne de type d'identifiant: "userid", "keyid", "fingerprint", "grip".
`identifier`
  L'identifiant de l'utilisateur OpenPGP (nom et email) pour le type "userid", chaîne hexadécimale qui représente l'identifiant de clé, l'empreinte ou le grip de clé correspondant.

### Valeurs de retour

Renvoie l'empreinte hexadécimale de la clé trouvée en cas de succès ou `false` si une erreur survient.

# rnp_op_encrypt

(PECL rnp >= 0.1.1)

rnp_op_encrypt — Chiffre un message

### Description

function rnp_op_encrypt(
RnpFFI `$ffi`,
string `$message`,
array `$recipient_keys_fp`,
array `$options` = ?
): string|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`message`
  Le message à chiffrer.
`recipient_keys_fp`
  Un tableau avec les empreintes des clés du destinataire. Au moins une clé doit être présente.
`options`
  Un tableau associatif avec des options.

  Key | Type de donnée | Description
  --- | --- | ---
  `"compression_alg"` | string | Algorithme de compression. Les options `"compression_alg"` et `"compression_level"` doivent toutes les deux être définies pour activer la compression des données.
  `"compression_level"` | integer | Le niveau de compression, de 0 à 9. 0 désactive la compression.
  `"armor"` | boolean | Active la sortie ASCII armée. Désactivé par défaut.
  `"add_signature"` | boolean | Le message chiffré sera également signé.
  `"hash"` | string | Définit l'algorithme de hachage utilisé lors du calcul de la signature. L'option "add_signature" doit être définie à `true`.
  `"creation_time"` | integer | Définit l'heure de création de la signature en secondes depuis le 1er janvier 1970 UTC. Par défaut, l'heure actuelle est utilisée.
  `"expiration_time"` | integer | Définit le temps d'expiration de la signature en secondes depuis l'heure de création. La valeur 0 est utilisée pour marquer la signature comme non expirante (valeur par défaut).
  `"password"` | string | Ajoute un mot de passe utilisé pour chiffrer les données.
  `"cipher"` | string | Définit l'algorithme de chiffrement symétrique. Les valeurs possibles sont "IDEA", "TRIPLEDES", "CAST5", "BLOWFISH", "AES128", "AES192", "AES256", "TWOFISH", "CAMELLIA128", "CAMELLIA192", "CAMELLIA256", "SM4".
  `"aead"` | string | Définit l'algorithme de mode AEAD. Les valeurs possibles sont "None" pour désactiver AEAD, "EAX", "OCB".
  `"aead_bits"` | integer | Définit la longueur du chunk pour le mode AEAD en nombre de bits de taille de chunk. Doit être compris entre 0 et 56.
  `"flags"` | integer | Définit des indicateurs de chiffrement supplémentaires. Les indicateurs pris en charge sont : RNP_ENCRYPT_NOWRAP - ne pas envelopper les données dans un paquet de données littérales. Cela permettrait de chiffrer des données déjà signées.
  `"file_name"` | string | Définit le nom de fichier stocké en interne pour les données chiffrées. La valeur spéciale _CONSOLE peut être utilisée pour marquer le message comme "pour les yeux seulement", c'est-à-dire qu'il ne doit être stocké nulle part mais seulement affiché au destinataire. Par défaut, c'est une chaîne vide.
  `"file_mtime"` | integer | Définit la date de modification du fichier d'entrée en secondes depuis le 1er janvier 1970 UTC.

### Valeurs de retour

Les données chiffrées en cas de succès ou `false` si une erreur survient.

# rnp_op_generate_key

(PECL rnp >= 0.1.1)

rnp_op_generate_key — Génère une clé

### Description

function rnp_op_generate_key(
RnpFFI `$ffi`,
string `$userid`,
string `$key_alg`,
string `$sub_alg` = ?,
array `$options` = ?
): string|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`userid`
  L'identifiant de l'utilisateur PGP - texte qui est censé représenter le nom et l'adresse email du détenteur de la clé.
`key_alg`
  La clé d'algorithme (c'est-à-dire 'RSA', 'DSA', etc).
`sub_alg`
  L'algorithme de sous-clé. Si non défini, la sous-clé ne sera pas générée.
`options`
  Un tableau associatif avec des options.

  Key | Type de donnée | Description
  --- | --- | ---
  `"bits"` | integer | La taille de la clé primaire en bits. Applicable uniquement aux clés RSA, DSA et El-Gamal.
  `"hash"` | string | Algorithme de hachage utilisé dans la signature de la clé ou la signature de liaison de sous-clé.
  `"dsa_qbits"` | integer | Définit la taille d'un paramètre `q` pour la clé DSA. Remarque : une valeur par défaut appropriée sera définie, en fonction du nombre de bits de la clé. Cependant, il est possible de la remplacer si nécessaire.
  `"curve"` | string | Définit la courbe utilisée pour la clé ECC. Remarque : cela s'applique uniquement aux clés ECDSA, ECDH et SM2.
  `"request_password"` | boolean | Active la demande de mot de passe via le fournisseur de mot de passe. Ce mot de passe sera utilisé pour le chiffrement de la clé. La fonction de rappel du fournisseur de mot de passe doit être définie à l'avance en appelant rnp_ffi_set_pass_provider(). Remarque : ce paramètre sera ignoré si le mot de passe a été défini via `"password"`
  `"password"` | string | Définit le mot de passe utilisé pour chiffrer les données de la clé secrète.
  `"expiration"` | integer | Définit le temps d'expiration de la clé primaire et de la sous-clé en secondes.
  `"sub_bits"` | integer | La taille de la sous-clé en bits. Applicable uniquement aux clés RSA, DSA et El-Gamal.
  `"sub_hash"` | string | Algorithme de hachage utilisé dans la signature de la sous-clé ou la signature de liaison de sous-clé.
  `"sub_curve"` | string | Définit la courbe utilisée pour la sous-clé ECC. Remarque : cela s'applique uniquement aux clés ECDSA, ECDH et SM2.

### Valeurs de retour

L'empreinte de la clé primaire générée ou `false` si une erreur survient. Cette empreinte peut être utilisée plus tard pour référencer la clé dans les opérations de signature et de chiffrement. Les données de la clé sont stockées dans le contexte de mémoire FFI et peuvent être sauvegardées en utilisant rnp_save_keys() ou rnp_save_keys_to_path().

# rnp_op_sign

(PECL rnp >= 0.1.1)

rnp_op_sign — Effectue une opération de signature sur des données binaires, renvoie la ou les signatures intégrées

### Description

function rnp_op_sign(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`data`
  Les données à signer.
`keys_fp`
  Un tableau avec les empreintes des clés. Au moins une clé doit être fournie. Les clés doivent être présentes dans `ffi`.
`options`
  Un tableau associatif avec des options.

  Key | Type de donnée | Description
  --- | --- | ---
  `"compression_alg"` | string | Algorithme de compression. Les options `"compression_alg"` et `"compression_level"` doivent toutes les deux être définies pour activer la compression des données.
  `"compression_level"` | integer | Niveau de compression, 0-9. 0 désactive la compression.
  `"armor"` | boolean | Active la sortie ASCII armée. Désactivé par défaut.
  `"hash"` | string | Définit l'algorithme de hachage utilisé lors du calcul de la signature.
  `"creation_time"` | integer | Définit l'heure de création de la signature en secondes depuis le 1er janvier 1970 UTC. Par défaut, l'heure actuelle est utilisée.
  `"expiration_time"` | integer | Définit le temps d'expiration de la signature en secondes depuis l'heure de création. La valeur 0 est utilisée pour marquer la signature comme non expirante (valeur par défaut).
  `"file_name"` | string | Définit le nom du fichier d'entrée. La valeur spéciale _CONSOLE peut être utilisée pour marquer le message comme 'pour les yeux seulement', c'est-à-dire qu'il ne doit pas être stocké n'importe où mais seulement affiché au destinataire. Par défaut, c'est une chaîne vide.
  `"file_mtime"` | integer | Définit la date de modification du fichier d'entrée en secondes depuis le 1er janvier 1970 UTC.

### Valeurs de retour

Les données signées avec la ou les signatures intégrées en cas de succès ou `false` si une erreur survient.

# rnp_op_sign_cleartext

(PECL rnp >= 0.1.1)

rnp_op_sign_cleartext — Effectue une opération de signature sur des données textuelles, renvoie le message signé en clair

### Description

function rnp_op_sign_cleartext(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`data`
  La donnée à signer.
`keys_fp`
  Le tableau avec les empreintes des clés. Au moins une clé doit être fournie. Les clés doivent être présentes dans `ffi`.
`options`
  Un tableau associatif avec des options.

  Key | Type de donnée | Description
  --- | --- | ---
  `"armor"` | boolean | Active la sortie ASCII armée. Désactivé par défaut.
  `"hash"` | string | Définit l'algorithme de hachage utilisé lors du calcul de la signature.
  `"creation_time"` | integer | Définit l'heure de création de la signature en secondes depuis le 1er janvier 1970 UTC. Par défaut, l'heure actuelle est utilisée.
  `"expiration_time"` | integer | Définit le temps d'expiration de la signature en secondes depuis l'heure de création. La valeur 0 est utilisée pour marquer la signature comme non expirée (valeur par défaut).

### Valeurs de retour

Le message signé en clair contenant les données source avec des en-têtes supplémentaires et la signature ASCII-armored en cas de succès ou `false` si une erreur survient.

# rnp_op_sign_detached

(PECL rnp >= 0.1.1)

rnp_op_sign_detached — Effectue une opération de signature, renvoie la signature détachée

### Description

function rnp_op_sign_detached(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`data`
  La donnée à signer.
`keys_fp`
  Un tableau avec les empreintes des clés. Au moins une clé doit être fournie. Les clés doivent être présentes dans `ffi`.
`options`
  Un tableau associatif avec des options.

  Key | Type de donnée | Description
  --- | --- | ---
  `"armor"` | boolean | Active la sortie ASCII-armored. Désactivé par défaut.
  `"hash"` | string | Définit l'algorithme de hachage utilisé lors du calcul de la signature.
  `"creation_time"` | integer | Définit l'heure de création de la signature en secondes depuis le 1er janvier 1970 UTC. Par défaut, l'heure actuelle est utilisée.
  `"expiration_time"` | integer | Définit le temps d'expiration de la signature en secondes depuis l'heure de création. La valeur 0 est utilisée pour marquer la signature comme non expirée (valeur par défaut).

### Valeurs de retour

Les données de signature détachées en cas de succès ou `false` si une erreur survient.

# rnp_op_verify

(PECL rnp >= 0.1.1)

rnp_op_verify — Vérifie les signatures intégrées ou en clair

### Description

function rnp_op_verify(RnpFFI `$ffi`, string `$data`): array|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`data`
  Les données signées.

### Valeurs de retour

Un tableau associatif avec des informations sur les résultats de la vérification ou `false` si une erreur survient.

Key | Type de donnée | Description
--- | --- | ---
`"verification_status"` | string | Résultats de la vérification globale, soit la chaîne "Success" soit un message d'erreur approprié. Le résultat "Success" est défini lorsqu'au moins une signature est valide et vérifiée avec succès. Le résultat de la vérification individuelle pour chaque signature peut être vérifié dans le tableau "signatures".
`"file_name"` | string | Le nom du fichier.
`"file_mtime"` | integer | Heure de modification du fichier.
`"mode"` | string | Mode de protection des données (chiffrement) utilisé dans le message traité. Les valeurs actuellement définies sont "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
`"cipher"` | string | Chiffrement symétrique utilisé pour le chiffrement des données.
`"valid_integrity"` | boolean | `true` si la protection de l'intégrité du message a été utilisée (c'est-à-dire MDC ou AEAD) et qu'elle a été validée avec succès.
`"signatures"` | array | Un tableau associatif décrivant chaque signature trouvée. Voir la description ci-dessous.

Le sous-tableau "signatures".

Key | Type de donnée | Description
--- | --- | ---
"verification_status" | string | Statut de vérification de la signature, soit la chaîne "Success" soit un message d'erreur approprié.
"creation_time" | integer | Heure de création de la signature en secondes depuis le 1er janvier 1970 UTC.
"expiration_time" | integer | Le temps d'expiration de la signature en secondes depuis le temps de création ou 0 si la signature n'expire jamais.
"hash" | string | Algorithme de hachage utilisé pour calculer la signature.
"signing_key" | string | L'empreinte de la clé utilisée pour signer. Peut être "Not found" si la clé publique correspondante n'est pas chargée dans l'objet FFI.
"signature_type" | string | Le type de signature. Les valeurs actuellement définies sont "binary", "text", "standalone", "certification (generic)", "certification (persona)", "certification (casual)", "certification (positive)", "subkey binding", "primary key binding", "direct", "key revocation", "subkey revocation", "certification revocation", "timestamp", "uknown: 0..255".

# rnp_op_verify_detached

(PECL rnp >= 0.1.1)

rnp_op_verify_detached — Vérifie les signatures détachées

### Description

function rnp_op_verify_detached(RnpFFI `$ffi`, string `$data`, string `$signature`): array|false

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`data`
  Les données source.
`signature`
  Les données de signature détachée.

### Valeurs de retour

Un tableau associatif avec des informations sur les résultats de la vérification ou `false` si une erreur survient.

Key | Type de donnée | Description
--- | --- | ---
`"verification_status"` | string | Les résultats de la vérification globale, soit la chaîne "Success" soit un message d'erreur approprié. Le résultat "Success" est défini lorsqu'au moins une signature est valide et vérifiée avec succès. Les résultats de vérification individuels pour chaque signature peuvent être vérifiés dans le tableau "signatures".
`"file_name"` | string | Nom du fichier.
`"file_mtime"` | integer | Heure de modification du fichier.
`"mode"` | string | Mode de protection des données (chiffrement) utilisé dans le message traité. Les valeurs actuellement définies sont "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
`"cipher"` | string | Algorithme de chiffrement symétrique utilisé pour le chiffrement des données.
`"valid_integrity"` | boolean | `true` si la protection de l'intégrité du message a été utilisée (c'est-à-dire MDC ou AEAD) et qu'elle a été validée avec succès.
`"signatures"` | array | Un tableau associatif décrivant chaque signature trouvée. Voir la description ci-dessous.

Un sous-tableau "signatures".

Key | Type de donnée | Description
--- | --- | ---
"verification_status" | string | Statut de vérification de la signature, soit la chaîne "Success" soit un message d'erreur approprié.
"creation_time" | integer | Heure de création de la signature en secondes depuis le 1er janvier 1970 UTC.
"expiration_time" | integer | Temps d'expiration de la signature en secondes depuis l'heure de création ou 0 si la signature n'expire jamais.
"hash" | string | Algorithme de hachage utilisé pour calculer la signature.
"signing_key" | string | L'empreinte de la clé utilisée pour signer. Peut être "Not found" si la clé publique correspondante n'est pas chargée dans l'objet FFI.
"signature_type" | string | Le type de signature. Les valeurs actuellement définies sont "binary", "text", "standalone", "certification (generic)", "certification (persona)", "certification (casual)", "certification (positive)", "subkey binding", "primary key binding", "direct", "key revocation", "subkey revocation", "certification revocation", "timestamp", "uknown: 0..255".

# rnp_save_keys

(PECL rnp >= 0.1.1)

rnp_save_keys — Sauvegarde les clés dans une chaîne PHP

### Description

function rnp_save_keys(
RnpFFI `$ffi`,
string `$format`,
string `&$output`,
int `$flags`
): bool

Il est à noter que pour G10, la sortie doit être un répertoire (qui doit déjà exister).

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`format`
  Le format de clé pour la donnée (GPG, KBX, G10).
`output`
  Les paquets de clés seront sauvegardés dans la chaîne référencée par `output`.
`flags`
  Voir la description des drapeaux `RNP_LOAD_SAVE_*`.

### Valeurs de retour

Renvoie `true` en cas de succès ou `false` si une erreur survient.

# rnp_save_keys_to_path

(PECL rnp >= 0.1.1)

rnp_save_keys_to_path — Sauvegarde les clés dans le chemin spécifié

### Description

function rnp_save_keys_to_path(
RnpFFI `$ffi`,
string `$format`,
string `$output_path`,
int `$flags`
): bool

Sauvegarde les clés présentes dans l'objet FFI (chargées ou générées) dans le fichier ou le répertoire spécifié.

### Liste de paramètres

`ffi`
  L'objet FFI retourné par rnp_ffi_create().
`format`
  Le format de clé pour la donnée (GPG, KBX, G10).
`output_path`
  Le chemin du fichier ou du répertoire où les clés doivent être sauvegardées.
`flags`
  Voir la description des drapeaux `RNP_LOAD_SAVE_*`.

### Valeurs de retour

Renvoie `true` en cas de succès ou `false` si une erreur survient.

# rnp_supported_features

(PECL rnp >= 0.1.1)

rnp_supported_features — Renvoie les fonctionnalités supportées au format JSON

### Description

function rnp_supported_features(string `$type`): string|false

Renvoie le format JSON contenant un tableau des valeurs de fonctionnalités rnp supportées (algorithmes, courbes, etc) par type.

### Liste de paramètres

`type`
  Voir les constantes RNP_FEATURE_* pour les valeurs supportées.

### Valeurs de retour

Une chaîne de caractères contenant un tableau formaté en JSON des algorithmes, courbes, etc supportés ou `false` si une erreur survient.

# rnp_version_string

(PECL rnp >= 0.1.1)

rnp_version_string — La version de la bibliothèque RNP

### Description

function rnp_version_string(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la chaîne de version de la bibliothèque RNP.

# rnp_version_string_full

(PECL rnp >= 0.1.1)

rnp_version_string_full — La chaîne de version complète de la bibliothèque RNP

### Description

function rnp_version_string_full(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la chaîne de version complète de la bibliothèque RNP.

## Sommaire

- rnp_backend_string — Renvoie le nom de la bibliothèque back-end de cryptographie
- rnp_backend_version — Renvoie la version de la bibliothèque back-end de cryptographie
- rnp_decrypt — Déchiffre un message PGP
- rnp_dump_packets — Affiche les informations du flux de paquets OpenPGP dans un format lisible par l'homme
- rnp_dump_packets_to_json — Affiche les informations du flux de paquets OpenPGP dans une chaîne JSON
- rnp_ffi_create — Créer un objet de niveau supérieur utilisé pour interagir avec la bibliothèque
- rnp_ffi_destroy — Détruit l'objet de niveau supérieur utilisé pour interagir avec la bibliothèque
- rnp_ffi_set_pass_provider — Définit la fonction de rappel du fournisseur de mot de passe
- rnp_import_keys — Importe des clés depuis une chaîne PHP vers le trousseau de clés et renvoie un JSON décrivant les clés nouvelles ou mises à jour
- rnp_import_signatures — Importe des signatures autonomes dans le trousseau de clés et renvoie un JSON décrivant les clés mises à jour
- rnp_key_export — Exporte une clé
- rnp_key_export_autocrypt — Exporte la clé minimale pour la fonctionnalité autocrypt (juste 5 paquets: clé, uid, signature, sous-clé de chiffrement, signature)
- rnp_key_export_revocation — Génère et exporte une signature de révocation de clé primaire
- rnp_key_get_info — Renvoie des informations sur la clé
- rnp_key_remove — Supprime une clé des trousseaux de clés
- rnp_key_revoke — Supprime une clé ou une sous-clé en générant et ajoutant une signature de révocation
- rnp_list_keys — Enumère toutes les clés présentes dans un trousseau de clés par type d'identifiant spécifié
- rnp_load_keys — Charge les clés à partir d'une chaîne PHP
- rnp_load_keys_from_path — Charge des clés à partir du chemin spécifié
- rnp_locate_key — Recherche de la clé
- rnp_op_encrypt — Chiffre un message
- rnp_op_generate_key — Génère une clé
- rnp_op_sign — Effectue une opération de signature sur des données binaires, renvoie la ou les signatures intégrées
- rnp_op_sign_cleartext — Effectue une opération de signature sur des données textuelles, renvoie le message signé en clair
- rnp_op_sign_detached — Effectue une opération de signature, renvoie la signature détachée
- rnp_op_verify — Vérifie les signatures intégrées ou en clair
- rnp_op_verify_detached — Vérifie les signatures détachées
- rnp_save_keys — Sauvegarde les clés dans une chaîne PHP
- rnp_save_keys_to_path — Sauvegarde les clés dans le chemin spécifié
- rnp_supported_features — Renvoie les fonctionnalités supportées au format JSON
- rnp_version_string — La version de la bibliothèque RNP
- rnp_version_string_full — La chaîne de version complète de la bibliothèque RNP

# La classe RnpFFI

(PECL rnp >= 0.1.1)

## Introduction

## Synopsis de la classe

class RnpFFI {
}

- Installation/Configuration
  - Pré-requis
  - Installation
- Constantes pré-définies
- Exemples
  - Texte signé en clair
- Fonctions de Rnp
  - rnp_backend_string — Renvoie le nom de la bibliothèque back-end de cryptographie
  - rnp_backend_version — Renvoie la version de la bibliothèque back-end de cryptographie
  - rnp_decrypt — Déchiffre un message PGP
  - rnp_dump_packets — Affiche les informations du flux de paquets OpenPGP dans un format lisible par l'homme
  - rnp_dump_packets_to_json — Affiche les informations du flux de paquets OpenPGP dans une chaîne JSON
  - rnp_ffi_create — Créer un objet de niveau supérieur utilisé pour interagir avec la bibliothèque
  - rnp_ffi_destroy — Détruit l'objet de niveau supérieur utilisé pour interagir avec la bibliothèque
  - rnp_ffi_set_pass_provider — Définit la fonction de rappel du fournisseur de mot de passe
  - rnp_import_keys — Importe des clés depuis une chaîne PHP vers le trousseau de clés et renvoie un JSON décrivant les clés nouvelles ou mises à jour
  - rnp_import_signatures — Importe des signatures autonomes dans le trousseau de clés et renvoie un JSON décrivant les clés mises à jour
  - rnp_key_export — Exporte une clé
  - rnp_key_export_autocrypt — Exporte la clé minimale pour la fonctionnalité autocrypt (juste 5 paquets: clé, uid, signature, sous-clé de chiffrement, signature)
  - rnp_key_export_revocation — Génère et exporte une signature de révocation de clé primaire
  - rnp_key_get_info — Renvoie des informations sur la clé
  - rnp_key_remove — Supprime une clé des trousseaux de clés
  - rnp_key_revoke — Supprime une clé ou une sous-clé en générant et ajoutant une signature de révocation
  - rnp_list_keys — Enumère toutes les clés présentes dans un trousseau de clés par type d'identifiant spécifié
  - rnp_load_keys — Charge les clés à partir d'une chaîne PHP
  - rnp_load_keys_from_path — Charge des clés à partir du chemin spécifié
  - rnp_locate_key — Recherche de la clé
  - rnp_op_encrypt — Chiffre un message
  - rnp_op_generate_key — Génère une clé
  - rnp_op_sign — Effectue une opération de signature sur des données binaires, renvoie la ou les signatures intégrées
  - rnp_op_sign_cleartext — Effectue une opération de signature sur des données textuelles, renvoie le message signé en clair
  - rnp_op_sign_detached — Effectue une opération de signature, renvoie la signature détachée
  - rnp_op_verify — Vérifie les signatures intégrées ou en clair
  - rnp_op_verify_detached — Vérifie les signatures détachées
  - rnp_save_keys — Sauvegarde les clés dans une chaîne PHP
  - rnp_save_keys_to_path — Sauvegarde les clés dans le chemin spécifié
  - rnp_supported_features — Renvoie les fonctionnalités supportées au format JSON
  - rnp_version_string — La version de la bibliothèque RNP
  - rnp_version_string_full — La chaîne de version complète de la bibliothèque RNP
- RnpFFI — La classe RnpFFI

# Sodium

# Introduction

Sodium est une bibliothèque moderne et facile à utiliser pour le chiffrement, déchiffrement, les signatures, et le hashage de mot de passe entre autres. Son objectif est de fournir toutes les opérations de base nécessaires à la construction d'outils cryptographiques de plus haut niveau.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Cette extension nécessite » libsodium ≥ 1.0.8.

## Installation

À partir de PHP 7.2.0 cette extension est fournie avec PHP. Pour les versions de PHP plus anciennes cette extension est disponible via PECL.

## Systèmes Linux

Pour pouvoir utiliser cette extension il faut compiler PHP avec le support de sodium en utilisant l'option de configuration --with-sodium[=DIR].

## Windows

Pour pouvoir utiliser cette extension il faut ajouter `extension=php_sodium.dll` au php.ini.

## Installation via PECL

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/libsodium

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`SODIUM_LIBRARY_VERSION` (string)
`SODIUM_LIBRARY_MAJOR_VERSION` (int)
`SODIUM_LIBRARY_MINOR_VERSION` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` (int)
`SODIUM_BASE64_VARIANT_URLSAFE` (int)
`SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` (int)
`SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES` (int)
  Disponible à partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NSECBYTES` (int)
  Disponible à partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES` (int)
  Disponible à partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_ABYTES` (int)
  Disponible à partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES` (int)
  Disponible à partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NSECBYTES` (int)
  Disponible à partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES` (int)
  Disponible à partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_ABYTES` (int)
  Disponible à partir de PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AUTH_BYTES` (int)
`SODIUM_CRYPTO_AUTH_KEYBYTES` (int)
`SODIUM_CRYPTO_BOX_SEALBYTES` (int)
`SODIUM_CRYPTO_BOX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_BOX_MACBYTES` (int)
`SODIUM_CRYPTO_BOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_BOX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KDF_BYTES_MIN` (int)
`SODIUM_CRYPTO_KDF_BYTES_MAX` (int)
`SODIUM_CRYPTO_KDF_CONTEXTBYTES` (int)
`SODIUM_CRYPTO_KDF_KEYBYTES` (int)
`SODIUM_CRYPTO_KX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KX_SESSIONKEYBYTES` (int)
`SODIUM_CRYPTO_KX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_KX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_KX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MAX` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (int)
`SODIUM_CRYPTO_PWHASH_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_STRPREFIX` (string)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_STRPREFIX` (string)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_CORE_RISTRETTO255_BYTES` (int)
  Disponible à partir de PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_HASHBYTES` (int)
  Disponible à partir de PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_NONREDUCEDSCALARBYTES` (int)
  Disponible à partir de PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_SCALARBYTES` (int)
  Disponible à partir de PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_BYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_SCALARBYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_BYTES` (int)
  Disponible à partir de PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_SCALARBYTES` (int)
  Disponible à partir de PHP 8.1.0.
`SODIUM_CRYPTO_SHORTHASH_BYTES` (int)
`SODIUM_CRYPTO_SHORTHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_MACBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_HEADERBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_MESSAGEBYTES_MAX` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY` (int)
`SODIUM_CRYPTO_SIGN_BYTES` (int)
`SODIUM_CRYPTO_SIGN_SEEDBYTES` (int)
`SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_STREAM_NONCEBYTES` (int)
`SODIUM_CRYPTO_STREAM_KEYBYTES` (int)
`SODIUM_CRYPTO_STREAM_XCHACHA20_KEYBYTES` (int)
  Disponible à partir de PHP 8.1.0.
`SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES` (int)
  Disponible à partir de PHP 8.1.0.

# Fonctions Sodium

# sodium_add

(PHP 7 >= 7.2.0, PHP 8)

sodium_add — Ajoute de grands nombres

### Description

function sodium_add(string `&$string1`, string `$string2`): void

Ceci ajoute le paramètre `string2` à `string1`, en écrasant la valeur stockée dans `string1`. Cette fonction suppose que les deux paramètres sont des chaînes binaires qui représentent des entiers non signés en petit-boutiste.

### Liste de paramètres

`string1`
  La chaîne représentant un entier non signé de longueur arbitraire en petit-boutiste. Ce paramètre est passé par référence et contiendra la somme des deux paramètres.
`string2`
  La chaîne représentant un entier non signé de longueur arbitraire en petit-boutiste.

### Valeurs de retour

Aucune valeur n'est retournée.

# sodium_base642bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_base642bin — Décode une chaîne encodée en base64 en binaire brut.

### Description

function sodium_base642bin(#[\SensitiveParameter]string `$string`, int `$id`, string `$ignore` = ""): string

Convertit une chaîne encodée en base64 en binaire brut. Contrairement à base64_decode(), sodium_base642bin() est en temps constant (une propriété importante pour tout code qui manipule des entrées cryptographiques, telles que des textes en clair ou des clés) et prend en charge plusieurs jeux de caractères.

### Liste de paramètres

`string`
  string; Chaîne encodée.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` pour le standard (`A-Za-z0-9/\+`) encodé en base64.
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` pour le standard (`A-Za-z0-9/\+`) encodé en base64, sans caractères de remplissage `=`.
  - `SODIUM_BASE64_VARIANT_URLSAFE` pour l'encodage Base64 sûr pour les URL (`A-Za-z0-9\-_`).
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` pour l'encodage Base64 sûr pour les URL (`A-Za-z0-9\-_`), sans caractères de remplissage `=`.
`ignore`
  Les caractères à ignorer lors du décodage (par exemple, les caractères d'espacement).

### Valeurs de retour

La chaîne décodée.

# sodium_bin2base64

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2base64 — Encode une chaîne binaire brute en base64.

### Description

function sodium_bin2base64(#[\SensitiveParameter]string `$string`, int `$id`): string

Convertit une chaîne binaire brute en une chaîne encodée en base64. Contrairement à base64_encode(), sodium_bin2base64() est en temps constant (une propriété importante pour tout code qui manipule des entrées cryptographiques, telles que des textes en clair ou des clés) et prend en charge plusieurs jeux de caractères.

### Liste de paramètres

`string`
  La chaîne binaire brute.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` pour le standard (`A-Za-z0-9/\+`) encodé en base64.
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` pour le standard (`A-Za-z0-9/\+`) encodé en base64, sans caractères de remplissage `=`.
  - `SODIUM_BASE64_VARIANT_URLSAFE` pour l'encodage Base64 sûr pour les URL (`A-Za-z0-9\-_`).
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` pour l'encodage Base64 sûr pour les URL (`A-Za-z0-9\-_`), sans caractères de remplissage `=`.

### Valeurs de retour

La chaîne encodée en base64.

# sodium_bin2hex

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2hex — Encode en hexadécimal

### Description

function sodium_bin2hex(#[\SensitiveParameter]string `$string`): string

Convertit une chaîne binaire brute en une chaîne encodée en hexadécimal. Contrairement à la fonction d'encodage hexadécimal standard, sodium_bin2hex() est en temps constant (une propriété importante pour tout code qui manipule des entrées cryptographiques, telles que des textes en clair ou des clés).

### Liste de paramètres

`string`
  Une chaîne binaire brute.

### Valeurs de retour

Une chaîne encodée en hexadécimal.

# sodium_compare

(PHP 7 >= 7.2.0, PHP 8)

sodium_compare — Compare des grands nombres

### Description

function sodium_compare(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

Compare deux chaînes comme si elles étaient des entiers non signés de longueur arbitraire, en petit-boutiste, sans fuite de canal secondaire.

### Liste de paramètres

`string1`
  Opérande de gauche
`string2`
  Opérande de droite

### Valeurs de retour

Renvoie `-1` si `string1` est plus petit que `string2`.

Renvoie `1` si `string1` est plus grand que `string2`.

Renvoie `0` si les deux chaînes sont égales.

# sodium_crypto_aead_aegis128l_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_decrypt — Vérifie puis déchiffre un message avec AEGIS-128L

### Description

function sodium_crypto_aead_aegis128l_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Vérifie puis déchiffre un message avec AEGIS-128L.

### Liste de paramètres

`ciphertext`
  Doit être au format fourni par sodium_crypto_aead_aegis128l_encrypt().
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message.
`key`
  La clé de chiffrement (128 bits).

### Valeurs de retour

Renvoie le texte en clair en cas de succès, ou `false` si une erreur survient.

### Voir aussi

- sodium_crypto_aead_aegis128l_encrypt() - Chiffre puis authentifie un message avec AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Génère une clé AEGIS-128L aléatoire

# sodium_crypto_aead_aegis128l_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_encrypt — Chiffre puis authentifie un message avec AEGIS-128L

### Description

function sodium_crypto_aead_aegis128l_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Chiffre puis authentifie un message avec AEGIS-128L.

### Liste de paramètres

`message`
  Le message en clair à chiffrer.
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message.
`key`
  La clé de chiffrement (128 bits).

### Valeurs de retour

Renvoie le texte chiffré et l'étiquette d'authentification sous forme de chaîne de bytes bruts.

### Voir aussi

- sodium_crypto_aead_aegis128l_decrypt() - Vérifie puis déchiffre un message avec AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Génère une clé AEGIS-128L aléatoire

# sodium_crypto_aead_aegis128l_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_keygen — Génère une clé AEGIS-128L aléatoire

### Description

function sodium_crypto_aead_aegis128l_keygen(): string

Génère une clé aléatoire de 128 bits pour être utilisée avec sodium_crypto_aead_aegis128l_encrypt() et sodium_crypto_aead_aegis128l_decrypt().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une clé aléatoire de 128 bits.

### Voir aussi

- sodium_crypto_aead_aegis128l_decrypt() - Vérifie puis déchiffre un message avec AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt() - Chiffre puis authentifie un message avec AEGIS-128L

# sodium_crypto_aead_aegis256_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_decrypt — Vérifie puis déchiffre un message avec AEGIS-256

### Description

function sodium_crypto_aead_aegis256_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Vérifie puis déchiffre un message avec AEGIS-256.

### Liste de paramètres

`ciphertext`
  Doit être au format fourni par sodium_crypto_aead_aegis256_encrypt().
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message.
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Renvoie le texte en clair en cas de succès, ou `false` si une erreur survient.

### Voir aussi

- sodium_crypto_aead_aegis256_encrypt() - Chiffre puis authentifie un message avec AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Génère une clé AEGIS-256 aléatoire

# sodium_crypto_aead_aegis256_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_encrypt — Chiffre puis authentifie un message avec AEGIS-256

### Description

function sodium_crypto_aead_aegis256_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Chiffre puis authentifie un message avec AEGIS-256.

### Liste de paramètres

`message`
  Le message en clair à chiffrer.
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message.
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Renvoie le texte chiffré et l'étiquette d'authentification sous forme de chaîne d'octets bruts.

### Voir aussi

- sodium_crypto_aead_aegis256_decrypt() - Vérifie puis déchiffre un message avec AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Génère une clé AEGIS-256 aléatoire

# sodium_crypto_aead_aegis256_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_keygen — Génère une clé AEGIS-256 aléatoire

### Description

function sodium_crypto_aead_aegis256_keygen(): string

Génère une clé aléatoire de 256 bits pour être utilisée avec sodium_crypto_aead_aegis256_encrypt() et sodium_crypto_aead_aegis256_decrypt().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une clé aléatoire de 256 bits.

### Voir aussi

- sodium_crypto_aead_aegis256_decrypt() - Vérifie puis déchiffre un message avec AEGIS-256
- sodium_crypto_aead_aegis256_encrypt() - Chiffre puis authentifie un message avec AEGIS-256

# sodium_crypto_aead_aes256gcm_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_decrypt — Vérifie puis déchiffre un message avec AES-256-GCM

### Description

function sodium_crypto_aead_aes256gcm_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Vérifie puis déchiffre avec AES-256-GCM. Disponible uniquement si sodium_crypto_aead_aes256gcm_is_available() retourne `true`.

### Liste de paramètres

`ciphertext`
  Doit être au format fourni par sodium_crypto_aead_aes256gcm_encrypt() (texte chiffré et étiquette, concaténés).
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 12 octets de long.
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Renvoie le texte en clair en cas de succès, ou `false` si une erreur survient.

# sodium_crypto_aead_aes256gcm_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_encrypt — Chiffre puis authentifie avec AES-256-GCM

### Description

function sodium_crypto_aead_aes256gcm_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Chiffre puis authentifie avec AES-256-GCM. Disponible uniquement si sodium_crypto_aead_aes256gcm_is_available() retourne `true`.

### Liste de paramètres

`message`
  Le message en texte clair à chiffrer.
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 12 octets de long.
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Renvoie le texte chiffré et l'étiquette d'authentification sous forme de chaîne de bytes binaires bruts. (Format : texte chiffré, puis étiquette.)

# sodium_crypto_aead_aes256gcm_is_available

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_is_available — Vérifie si le matériel prend en charge AES256-GCM

### Description

function sodium_crypto_aead_aes256gcm_is_available(): bool

La valeur de retour de cette fonction dépend du fait que le matériel prend en charge ou non l'AES accéléré par matériel.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` s'il est sûr de chiffrer avec AES-256-GCM, et `false` sinon.

# sodium_crypto_aead_aes256gcm_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_keygen — Génère une clé AES-256-GCM aléatoire

### Description

function sodium_crypto_aead_aes256gcm_keygen(): string

Génère une clé aléatoire pour une utilisation avec sodium_crypto_aead_aes256gcm_encrypt() et sodium_crypto_aead_aes256gcm_decrypt().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une clé aléatoire de 256 bits.

# sodium_crypto_aead_chacha20poly1305_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_decrypt — Vérifie puis déchiffre avec ChaCha20-Poly1305

### Description

function sodium_crypto_aead_chacha20poly1305_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Vérifie puis déchiffre avec ChaCha20-Poly1305.

### Liste de paramètres

`ciphertext`
  Doit être au format fourni par sodium_crypto_aead_chacha20poly1305_encrypt() (texte chiffré et étiquette, concaténés).
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 8 octets de long.
`key`
  La clé de chiffrement. 256 bits.

### Valeurs de retour

Renvoie le texte en clair en cas de succès, ou `false` si une erreur survient.

# sodium_crypto_aead_chacha20poly1305_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_encrypt — Chiffre puis authentifie avec ChaCha20-Poly1305

### Description

function sodium_crypto_aead_chacha20poly1305_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Chiffre puis authentifie avec ChaCha20-Poly1305.

### Liste de paramètres

`message`
  Le message en texte clair à chiffrer.
`additional_data`
  Données additionnelles authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 8 octets de long.
`key`
  La clé de chiffrement. 256 bits.

### Valeurs de retour

Renvoie le texte chiffré et l'étiquette en cas de succès, ou `false` si une erreur survient.

# sodium_crypto_aead_chacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Vérifie que le texte chiffré inclut une étiquette valide

### Description

function sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Vérifie puis déchiffre avec ChaCha20-Poly1305 (variante IETF).

La variante IETF utilise des nonces de 96 bits et des compteurs internes de 32 bits, au lieu de 64 bits pour les deux.

### Liste de paramètres

`ciphertext`
  Doit être au format fourni par sodium_crypto_aead_chacha20poly1305_ietf_encrypt() (texte chiffré et étiquette, concaténés).
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 12 octets de long.
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Renvoie le texte en clair en cas de succès, ou `false` si une erreur survient.

# sodium_crypto_aead_chacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Chiffre un message

### Description

function sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Chiffre puis authentifie avec ChaCha20-Poly1305 (variante IETF).

La variante IETF utilise des nonces de 96 bits et des compteurs internes de 32 bits, au lieu de 64 bits pour les deux.

### Liste de paramètres

`message`
  Le message en texte clair à chiffrer.
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 12 octets de long.
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Renvoie le texte chiffré et l'étiquette en cas de succès, ou `false` si une erreur survient.

# sodium_crypto_aead_chacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_keygen — Génère une clé ChaCha20-Poly1305 (IETF) aléatoire

### Description

function sodium_crypto_aead_chacha20poly1305_ietf_keygen(): string

Génère une clé aléatoire pour une utilisation avec sodium_crypto_aead_chacha20poly1305_ietf_encrypt() et sodium_crypto_aead_chacha20poly1305_ietf_decrypt().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une clé aléatoire de 256 bits.

# sodium_crypto_aead_chacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_keygen — Génère une clé ChaCha20-Poly1305 aléatoire

### Description

function sodium_crypto_aead_chacha20poly1305_keygen(): string

Génère une clé aléatoire pour une utilisation avec sodium_crypto_aead_chacha20poly1305_encrypt() et sodium_crypto_aead_chacha20poly1305_decrypt().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une clé aléatoire de 256 bits.

# sodium_crypto_aead_xchacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Préféré) Vérifie puis déchiffre avec XChaCha20-Poly1305

### Description

function sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Vérifie puis déchiffre avec XChaCha20-Poly1305 (variante eXtended-nonce).

Généralement, XChaCha20-Poly1305 est le meilleur des modes AEAD fournis à utiliser.

### Liste de paramètres

`ciphertext`
  Doit être au format fourni par sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() (texte chiffré et étiquette, concaténés).
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 24 octets de long. Ceci est une limite suffisamment grande pour être générée aléatoirement (c.-à-d. random_bytes()).
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Renvoie le texte en clair en cas de succès, ou `false` si une erreur survient.

# sodium_crypto_aead_xchacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Préféré) Chiffre puis authentifie avec XChaCha20-Poly1305

### Description

function sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Chiffre puis authentifie avec XChaCha20-Poly1305 (variante eXtended-nonce).

Généralement, XChaCha20-Poly1305 est le meilleur des modes AEAD fournis à utiliser.

### Liste de paramètres

`message`
  Le message en texte clair à chiffrer.
`additional_data`
  Données supplémentaires authentifiées. Cela est utilisé dans la vérification de l'étiquette d'authentification ajoutée au texte chiffré, mais il n'est pas chiffré ou stocké dans le texte chiffré.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 24 octets de long. Ceci est une limite suffisamment grande pour être générée aléatoirement (c.-à-d. random_bytes()).
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Renvoie le texte chiffré et l'étiquette en cas de succès, ou `false` si une erreur survient.

# sodium_crypto_aead_xchacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Génère une clé XChaCha20-Poly1305 aléatoire.

### Description

function sodium_crypto_aead_xchacha20poly1305_ietf_keygen(): string

Génère une clé aléatoire pour une utilisation avec sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() et sodium_crypto_aead_xchacha20poly1305_ietf_decrypt().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une clé aléatoire de 256 bits.

# sodium_crypto_auth

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth — Calcule une étiquette pour le message

### Description

function sodium_crypto_auth(string `$message`, #[\SensitiveParameter]string `$key`): string

L'authentification symétrique de message via sodium_crypto_auth() fournit l'intégrité, mais pas la confidentialité.

Contrairement aux signatures numériques (par exemple sodium_crypto_sign_detached()), toute partie capable de vérifier un message est également capable d'authentifier ses propres messages. (D'où, l'authentification symétrique.)

### Liste de paramètres

`message`
  Le message que l'on souhaite authentifier
`key`
  La clé d'authentification

### Valeurs de retour

L'étiquette d'authentification

# sodium_crypto_auth_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_keygen — Génère une clé aléatoire pour sodium_crypto_auth

### Description

function sodium_crypto_auth_keygen(): string

Génère une clé aléatoire pour une utilisation avec sodium_crypto_auth() et sodium_crypto_auth_verify().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une clé aléatoire de 256 bits.

# sodium_crypto_auth_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_verify — Vérifie que l'étiquette est valide pour le message

### Description

function sodium_crypto_auth_verify(string `$mac`, string `$message`, #[\SensitiveParameter]string `$key`): bool

Vérifie que l'étiquette est valide pour un message et une clé donnés.

Contrairement aux signatures numériques (par exemple sodium_crypto_sign_verify_detached()), toute partie capable de vérifier un message est également capable d'authentifier ses propres messages. (D'où, l'authentification symétrique.)

### Liste de paramètres

`mac`
  Etiquette d'authentification produite par sodium_crypto_auth()
`message`
  Message
`key`
  La clé d'authentification

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# sodium_crypto_box

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box — Chiffrement asymétrique authentifié

### Description

function sodium_crypto_box(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string

Chiffre un message en utilisant la cryptographie asymétrique (clé publique).

L'algorithme utilisé par les fonctions préfixées par sodium_crypto_box() est Diffie-Hellman sur la courbe de Montgomery, Curve25519; généralement abrégée en X25519.

### Liste de paramètres

`message`
  Le message à chiffrer.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 24 octets de long. Ceci est une limite suffisamment grande pour être générée aléatoirement (c.-à-d. random_bytes()).
`key_pair`
  Voir sodium_crypto_box_keypair_from_secretkey_and_publickey(). Ceci devrait inclure la clé secrète X25519 de l'expéditeur et la clé publique X25519 du destinataire.

### Valeurs de retour

Renvoie le message chiffré (ciphertext plus étiquette d'authentification). Le texte chiffré sera 16 octets plus long que le texte en clair, et une chaîne binaire brute. Voir sodium_bin2base64() pour un encodage sûr pour le stockage.

# sodium_crypto_box_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair — Génère aléatoirement une clé secrète et une clé publique correspondante

### Description

function sodium_crypto_box_keypair(): string

Génère une clé secrète et une clé publique en une seule chaîne.

Pour extraire la clé secrète de cette chaîne de clé unifiée, voir sodium_crypto_box_secretkey(). Pour extraire la clé publique de cette chaîne de clé unifiée, voir sodium_crypto_box_publickey().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une chaîne contenant à la fois la clé secrète X25519 et la clé publique X25519 correspondante.

# sodium_crypto_box_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair_from_secretkey_and_publickey — Créer une paire de clés unifiée à partir d'une clé secrète et d'une clé publique

### Description

function sodium_crypto_box_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

Cette fonction existe pour satisfaire les exigences de l'API de crypto_box(). Passer la clé secrète d'une partie et la clé publique de l'autre, et on obtiendra une "paire de clés" pour la conversation.

### Liste de paramètres

`secret_key`
  La clé secrète.
`public_key`
  La clé publique.

### Valeurs de retour

Une paire de clés X25519.

# sodium_crypto_box_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_open — Déchiffrement authentifié avec clé publique

### Description

function sodium_crypto_box_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string|false

Déchiffre un message en utilisant la cryptographie asymétrique (clé publique).

### Liste de paramètres

`ciphertext`
  Le message chiffré à déchiffrer.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 24 octets de long. C'est une limite suffisamment grande pour être générée aléatoirement (c.-à-d. random_bytes()).
`key_pair`
  Voir sodium_crypto_box_keypair_from_secretkey_and_publickey(). Cela devrait inclure la clé publique de l'expéditeur et la clé secrète du destinataire.

### Valeurs de retour

Renvoie le message en clair en cas de succès, ou `false` si une erreur survient.

# sodium_crypto_box_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey — Extrait la clé publique d'une paire de clés crypto_box

### Description

function sodium_crypto_box_publickey(#[\SensitiveParameter]string `$key_pair`): string

Étant donné une paire de clés, extrait uniquement la clé publique.

### Liste de paramètres

`key_pair`
  Une paire de clés, telle que celle générée par sodium_crypto_box_keypair() ou sodium_crypto_box_seed_keypair()

### Valeurs de retour

La clé publique X25519.

# sodium_crypto_box_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey_from_secretkey — Calcule la clé publique à partir d'une clé secrète

### Description

function sodium_crypto_box_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Étant donné une clé secrète, calcule la clé publique correspondante.

Cela ne fonctionne qu'avec le type de clés destinées à être utilisées avec crypto_box() (qui utilise l'échange de clés de Diffie-Hellman sur la courbe de Montgomery, Curve25519; abrégé X25519), pas crypto_sign() (qui utilise l'algorithme de signature numérique d'Edwards sur la courbe d'Edwards avec les paramètres correspondants; abrégé Ed25519).

### Liste de paramètres

`secret_key`
  La clé secrète X25519

### Valeurs de retour

La clé publique X25519.

# sodium_crypto_box_seal

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal — Chiffrement anonyme avec clé publique

### Description

function sodium_crypto_box_seal(#[\SensitiveParameter]string `$message`, string `$public_key`): string

Chiffre un message de telle sorte que seul le destinataire puisse le déchiffrer.

Contrairement à sodium_crypto_box(), on n'a besoin que de la clé publique du destinataire pour utiliser sodium_crypto_box_seal(). Une conséquence de cette commodité, cependant, est que le texte chiffré n'est pas lié à une clé publique statique, et n'est donc pas authentifié. D'où le chiffrement anonyme avec clé publique.

sodium_crypto_box_seal() fournit toujours l'intégrité du texte chiffré. Juste pas l'authentification de l'identité de l'expéditeur.

Si l'on a également besoin d'authentification de l'expéditeur, les fonctions sodium_crypto_sign() sont probablement le meilleur point de départ.

### Liste de paramètres

`message`
  Le message à chiffrer.
`public_key`
  La clé publique qui correspond à la seule clé qui peut déchiffrer le message.

### Valeurs de retour

Un texte chiffré sous la forme de (clé publique à usage unique, message chiffré, étiquette d'authentification).

### Exemples

Exemple #1 Exemple de sodium_crypto_box_seal()

    <?php
    $keypair = sodium_crypto_box_keypair();
    $public_key = sodium_crypto_box_publickey($keypair);

    // Le texte en clair obfusqué pour rendre l'exemple plus amusant
    $plaintext_b64 = "V3JpdGluZyBzb2Z0d2FyZSBpbiBQSFAgY2FuIGJlIGEgZGVsaWdodCE=";
    $decoded_plaintext = sodium_base642bin($plaintext_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $sealed = sodium_crypto_box_seal($decoded_plaintext, $public_key);
    var_dump(base64_encode($sealed));

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(120) "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw="
    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_seal_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal_open — Déchiffrement anonyme avec clé publique

### Description

function sodium_crypto_box_seal_open(string `$ciphertext`, #[\SensitiveParameter]string `$key_pair`): string|false

Déchiffre un message qui a été chiffré avec sodium_crypto_box_seal()

### Liste de paramètres

`ciphertext`
  Le message chiffré
`key_pair`
  La paire de clés du destinataire. Doit inclure la clé secrète.

### Valeurs de retour

Le texte en clair en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 sodium_crypto_box_seal_open() example

    <?php
    // Le texte chiffré n'est pas sensible; base64_decode est suffisant
    $sealed_b64 = "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw=";
    $sealed = base64_decode($sealed_b64);

    // La paire de clés contient un secret cryptographique; utiliser un décodeur sûr en temps
    $keypair_b64 = "KZkF8wnB7bnC2aXB3lFOqCTc0Z6MllvaQb9ASVG8o2/MsewkuE4u1uaEgTzSakeiYyIW8DGj+02/L3cWIbs9bQ==";
    $keypair = sodium_base642bin($keypair_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_secretkey — Extrait la clé secrète d'une paire de clés crypto_box

### Description

function sodium_crypto_box_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Étant donné une paire de clés, extrait uniquement la clé secrète.

### Liste de paramètres

`key_pair`
  Une paire de clés, telle que celle générée par sodium_crypto_box_keypair() ou sodium_crypto_box_seed_keypair()

### Valeurs de retour

La clé secrète X25519

# sodium_crypto_box_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seed_keypair — Dérive de manière déterministe la paire de clés à partir d'une seule clé

### Description

function sodium_crypto_box_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Conditionne la graine pour former une clé secrète, dérive la clé publique, et renvoie les deux en tant que paire de clés.

Les fonctions `*_seed_keypair` sont idéales pour générer une paire de clés à partir d'un mot de passe et d'un sel. Utiliser le résultat comme `seed` pour générer les clés souhaitées.

### Liste de paramètres

`seed`
  Une entrée cryptographique. Doit être de 32 octets.

### Valeurs de retour

Une paire de clés X25519 (clé secrète et clé publique).

# sodium_crypto_core_ristretto255_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_add — Ajoute un élément

### Description

function sodium_crypto_core_ristretto255_add(string `$p`, string `$q`): string

Ajoute un élément `q` à `p`. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`p`
  Un élément.
`q`
  Un élément.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_add()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_crypto_core_ristretto255_random() - Génère une clé aléatoire
- sodium_crypto_core_ristretto255_sub() - Soustrait un élément

# sodium_crypto_core_ristretto255_from_hash

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_from_hash — Mappe un vecteur

### Description

function sodium_crypto_core_ristretto255_from_hash(string `$s`): string

Mappe un vecteur `s` de 64 octets à un élément de groupe. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`s`
  Un vecteur de 64 octets.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_from_hash()

    <?php

    $hashes = sodium_hex2bin(
        '5d1be09e3d0c82fc538112490e35701979d99e06ca3e2b5b54bffe8b4dc772c1' .
        '4d98b696a1bbfb5ca32c436cc61c16563790306c79eaca7705668b47dffe5bb6'
    );
    var_dump(sodium_bin2hex(sodium_crypto_core_ristretto255_from_hash($hashes)));
    ?>

L'exemple ci-dessus va afficher :

    string(64) "3066f82a1a747d45120d1740f14358531a8f04bbffe6a819f86dfe50f44a0a46"

### Voir aussi

- sodium_hex2bin() - Décode une chaîne binaire encodée en hexadécimal
- sodium_bin2hex() - Encode en hexadécimal
- sodium_crypto_core_ristretto255_from_hash()

# sodium_crypto_core_ristretto255_is_valid_point

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_is_valid_point — Détermine si un point est sur la courbe ristretto255

### Description

function sodium_crypto_core_ristretto255_is_valid_point(string `$s`): bool

Détermine si un point sur la courbe ristretto255, en forme canonique, sur le sous-groupe principal, et que le point n'a pas un petit ordre. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`s`
  Un point sur la courbe elliptique.

### Valeurs de retour

Renvoie `true` si `s` est sur la courbe ristretto255, `false` sinon.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_is_valid_point()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_scalarmult_ristretto255_base($foo);

    var_dump(sodium_crypto_core_ristretto255_is_valid_point($bar));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_crypto_core_ristretto255_scalar_random() - Génère une clé aléatoire
- sodium_crypto_scalarmult_ristretto255_base() - Calcule la clé publique à partir d'une clé secrète

# sodium_crypto_core_ristretto255_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_random — Génère une clé aléatoire

### Description

function sodium_crypto_core_ristretto255_random(): string

Génère une clé aléatoire. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_random()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_crypto_core_ristretto255_add() - Ajoute un élément
- sodium_crypto_core_ristretto255_sub() - Soustrait un élément

# sodium_crypto_core_ristretto255_scalar_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_add — Ajoute une valeur scalaire

### Description

function sodium_crypto_core_ristretto255_scalar_add(string `$x`, string `$y`): string

Ajoute un élément `y` à `x`. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`x`
  Scalaire représentant la coordonnée X.
`y`
  Scalaire, représentant la coordonnée Y.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_scalar_add()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_crypto_core_ristretto255_scalar_random() - Génère une clé aléatoire
- sodium_crypto_core_ristretto255_scalar_sub() - Soustrait une valeur scalaire

# sodium_crypto_core_ristretto255_scalar_complement

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_complement — Le but de sodium_crypto_core_ristretto255_scalar_complement

### Description

function sodium_crypto_core_ristretto255_scalar_complement(string `$s`): string

Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`s`
  Valeur scalaire.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Voir aussi

- sodium_crypto_core_ristretto255_scalar_random() - Génère une clé aléatoire

# sodium_crypto_core_ristretto255_scalar_invert

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_invert — Inverse une valeur scalaire

### Description

function sodium_crypto_core_ristretto255_scalar_invert(string `$s`): string

Inverse une valeur scalaire. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`s`
  Valeur scalaire.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_scalar_invert()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $inverted = sodium_crypto_core_ristretto255_scalar_invert($foo);
    $reInverted = sodium_crypto_core_ristretto255_scalar_invert($inverted);

    var_dump(hash_equals($foo, $reInverted));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_crypto_core_ristretto255_scalar_random() - Génère une clé aléatoire

# sodium_crypto_core_ristretto255_scalar_mul

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_mul — Multiplie une valeur scalaire

### Description

function sodium_crypto_core_ristretto255_scalar_mul(string `$x`, string `$y`): string

Multiplie une valeur scalaire. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`x`
  Scalaire représentant la coordonnée X.
`y`
  Scalaire, représentant la coordonnée Y.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Voir aussi

- sodium_crypto_core_ristretto255_scalar_random() - Génère une clé aléatoire

# sodium_crypto_core_ristretto255_scalar_negate

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_negate — Inverse le signe d'une valeur scalaire

### Description

function sodium_crypto_core_ristretto255_scalar_negate(string `$s`): string

Inverse le signe d'une valeur scalaire. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`s`
  Valeur scalaire.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_scalar_negate()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $negate = sodium_crypto_core_ristretto255_scalar_negate($foo);
    $reNegate = sodium_crypto_core_ristretto255_scalar_negate($negate);

    var_dump(hash_equals($foo, $reNegate));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_crypto_core_ristretto255_scalar_random() - Génère une clé aléatoire

# sodium_crypto_core_ristretto255_scalar_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_random — Génère une clé aléatoire

### Description

function sodium_crypto_core_ristretto255_scalar_random(): string

Génère une clé aléatoire. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_scalar_random()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_crypto_core_ristretto255_scalar_add() - Ajoute une valeur scalaire
- sodium_crypto_core_ristretto255_scalar_sub() - Soustrait une valeur scalaire

# sodium_crypto_core_ristretto255_scalar_reduce

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_reduce — Réduit une valeur scalaire

### Description

function sodium_crypto_core_ristretto255_scalar_reduce(string `$s`): string

Réduit une valeur scalaire. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`s`
  Une valeur scalaire.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Voir aussi

- sodium_crypto_core_ristretto255_scalar_random() - Génère une clé aléatoire

# sodium_crypto_core_ristretto255_scalar_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_sub — Soustrait une valeur scalaire

### Description

function sodium_crypto_core_ristretto255_scalar_sub(string `$x`, string `$y`): string

Soustrait un scalaire `y` de `x`. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`x`
  Scalaire, représentant la coordonnée X.
`y`
  Scalaire, représentant la coordonnée Y.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_scalar_sub()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_crypto_core_ristretto255_scalar_random() - Génère une clé aléatoire
- sodium_crypto_core_ristretto255_scalar_add() - Ajoute une valeur scalaire

# sodium_crypto_core_ristretto255_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_sub — Soustrait un élément

### Description

function sodium_crypto_core_ristretto255_sub(string `$p`, string `$q`): string

Soustrait un élément `q` de `p`. Disponible à partir de libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`p`
  Un élément.
`q`
  Un élément.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Exemples

Exemple #1 Exemple de sodium_crypto_core_ristretto255_sub()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_crypto_core_ristretto255_random() - Génère une clé aléatoire
- sodium_crypto_core_ristretto255_add() - Ajoute un élément

# sodium_crypto_generichash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash — Renvoie un hachage du message

### Description

function sodium_crypto_generichash(string `$message`, #[\SensitiveParameter]string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

Hache un message avec BLAKE2b.

### Liste de paramètres

`message`
  Le message à hacher.
`key`
  (Optionnel) clé cryptographique. Cela sert à la même fonction qu'une clé HMAC, mais elle est utilisée comme une section réservée de l'état interne de BLAKE2.
`length`
  La taille de la sortie.

### Valeurs de retour

Le hachage cryptographique en tant que chaîne binaire brute. Si une sortie hexadécimale est désirée, le résultat peut être passé à sodium_bin2hex().

# sodium_crypto_generichash_final

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_final — Complète le hachage

### Description

function sodium_crypto_generichash_final(string `&$state`, int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

La méthode de finalisation pour l'API de hachage générique en streaming.

### Liste de paramètres

`state`
  L'état de hachage retourné par sodium_crypto_generichash_init()
`length`
  La longueur de la sortie.

### Valeurs de retour

Le hachage cryptographique.

### Exemples

Exemple #1 Exemple de sodium_crypto_generichash_final()

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }

    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_init

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_init — Initialise un hachage pour le streaming

### Description

function sodium_crypto_generichash_init(#[\SensitiveParameter]string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

La méthode d'initialisation pour l'API de hachage générique en streaming.

### Liste de paramètres

`key`
  La clé de hachage générique.
`length`
  La taille de la sortie attendue de la fonction de hachage.

### Valeurs de retour

Renvoie un état de hachage, sérialisé sous forme d'une chaîne binaire brute.

### Exemples

Exemple #1 Exemple de sodium_crypto_generichash_init()

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }
    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));
    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_keygen — Génère une clé de hachage générique aléatoire

### Description

function sodium_crypto_generichash_keygen(): string

Génère une clé aléatoire pour une utilisation avec l'API de hachage générique.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une clé aléatoire de 256 bits.

# sodium_crypto_generichash_update

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_update — Ajoute un message à un hachage

### Description

function sodium_crypto_generichash_update(string `&$state`, string `$message`): true

Ajoute un message à l'état de hachage interne.

### Liste de paramètres

`state`
  La valeur de retour de sodium_crypto_generichash_init().
`message`
  Les données à ajouter à l'état de hachage.

### Valeurs de retour

Retourne toujours `true`.

### Exemples

Exemple #1 Exemple de sodium_crypto_generichash_update()

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init();
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }
    $final = sodium_crypto_generichash_final($state);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"
    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"

# sodium_crypto_kdf_derive_from_key

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_derive_from_key — Dérive une sous-clé

### Description

function sodium_crypto_kdf_derive_from_key(
int `$subkey_length`,
int `$subkey_id`,
string `$context`,
#[\SensitiveParameter]string `$key`
): string

Dérive une sous-clé à partir d'une clé racine et d'un contexte supplémentaire.

Similaire à hash_hkdf().

### Liste de paramètres

`subkey_length`
  La longueur de la clé à retourner (en octets)
`subkey_id`
  Renvoie la N-ième sous-clé d'une clé racine donnée. Utile pour la recherche.
`context`
  Le contexte spécifique à l'application.
`key`
  La clé racine à partir de laquelle la sous-clé est dérivée.

### Valeurs de retour

Une chaîne de bytes pseudorandom (binaire brut).

# sodium_crypto_kdf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_keygen — Génère une clé racine aléatoire pour l'interface KDF

### Description

function sodium_crypto_kdf_keygen(): string

Génère une clé aléatoire adaptée pour servir de clé racine pour sodium_crypto_kdf_derive_from_key().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une clé aléatoire de 256 bits.

# sodium_crypto_kx_client_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_client_session_keys — Calcule les clés de session côté client.

### Description

function sodium_crypto_kx_client_session_keys(#[\SensitiveParameter]string `$client_key_pair`, string `$server_key`): array

Calcule les clés de session côté client, en utilisant la méthode d'échange de clés X25519 + BLAKE2b.

### Liste de paramètres

`client_key_pair`
  Une paire de clés crypto_kx, telle que celle générée par sodium_crypto_kx_keypair().
`server_key`
  Une clé publique crypto_kx.

### Valeurs de retour

Un tableau composé de deux chaînes. La première doit être utilisée pour recevoir des données du serveur. La seconde doit être utilisée pour envoyer des données au serveur.

# sodium_crypto_kx_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_keypair — Créer une nouvelle paire de clés sodium

### Description

function sodium_crypto_kx_keypair(): string

Crée une nouvelle paire de clés sodium composée de la clé secrète (32 octets) suivie de la clé publique (32 octets). Les clés peuvent être récupérées en appelant sodium_crypto_kx_secretkey() et sodium_crypto_kx_publickey(), respectivement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la nouvelle paire de clés en cas de succès ; lève une exception sinon.

### Exemples

Exemple #1 sodium_crypto_kx_keypair() usage

Crée une nouvelle paire de clés et récupère la clé secrète et la clé publique associée.

    <?php
    $keypair = sodium_crypto_kx_keypair();
    $secret = sodium_crypto_kx_secretkey($keypair);
    $public = sodium_crypto_kx_publickey($keypair);
    printf("secret: %s\npublic: %s", sodium_bin2hex($secret), sodium_bin2hex($public));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    secret: e7c5c918fdc40762e6000542c0118f4368ce8fd242b0e48c1e17202797a25daf
    public: d1f59fda8652caf40ed1a01d2b6f3802b60846986372cd8fa337b7c12c428b18

# sodium_crypto_kx_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_publickey — Extrait la clé publique d'une paire de clés crypto_kx

### Description

function sodium_crypto_kx_publickey(#[\SensitiveParameter]string `$key_pair`): string

Extrait la clé publique d'une paire de clés crypto_kx.

### Liste de paramètres

`key_pair`
  Une paire de clés X25519, telle que celle générée par sodium_crypto_kx_keypair().

### Valeurs de retour

Une clé publique X25519.

# sodium_crypto_kx_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_secretkey — Extrait la clé secrète d'une paire de clés crypto_kx

### Description

function sodium_crypto_kx_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Extrait la clé secrète d'une paire de clés crypto_kx.

### Liste de paramètres

`key_pair`
  Une paire de clés X25519, telle que celle générée par sodium_crypto_kx_keypair().

### Valeurs de retour

La clé secrète X25519.

# sodium_crypto_kx_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_seed_keypair — Description

### Description

function sodium_crypto_kx_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`seed`

### Valeurs de retour

# sodium_crypto_kx_server_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_server_session_keys — Calcule les clés de session côté serveur.

### Description

function sodium_crypto_kx_server_session_keys(#[\SensitiveParameter]string `$server_key_pair`, string `$client_key`): array

Calcule les clés de session côté serveur, en utilisant la méthode d'échange de clés X25519 + BLAKE2b.

### Liste de paramètres

`server_key_pair`
  Une paire de clés crypto_kx, telle que celle générée par sodium_crypto_kx_keypair().
`client_key`
  Une clé publique crypto_kx.

### Valeurs de retour

Un tableau composé de deux chaînes. La première doit être utilisée pour recevoir des données du client. La seconde doit être utilisée pour envoyer des données au client.

# sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Dérive une clé à partir d'un mot de passe, en utilisant Argon2

### Description

function sodium_crypto_pwhash(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`,
int `$algo` = `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT`
): string

Cette fonction fournit un accès de bas niveau à la fonction de dérivation de clé crypto_pwhash de libsodium. À moins d'avoir une raison spécifique d'utiliser cette fonction, il est recommandé d'utiliser les fonctions sodium_crypto_pwhash_str() ou password_hash() à la place.

Une raison courante d'utiliser cette fonction est de dériver les graines pour les clés cryptographiques à partir d'un mot de passe et d'un sel, puis d'utiliser ces graines pour générer les clés réelles nécessaires à un certain usage (par exemple sodium_crypto_sign_detached()).

### Liste de paramètres

`length`
  int; La longueur du hachage de mot de passe à générer, en octets.
`password`
  string; Le mot de passe pour lequel générer un hachage.
`salt`
  Un sel à ajouter au mot de passe avant le hachage. Le sel doit être imprévisible, idéalement généré à partir d'une bonne source de nombres aléatoires telle que random_bytes(), et avoir une longueur d'exactement `SODIUM_CRYPTO_PWHASH_SALTBYTES` octets.
`opslimit`
  Représente une quantité maximale de calculs à effectuer. Augmenter ce nombre fera que la fonction nécessitera plus de cycles CPU pour calculer une clé. Il existe des constantes disponibles pour définir la limite d'opérations à des valeurs appropriées en fonction de l'utilisation prévue, dans l'ordre de la force : `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` et `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  La quantité maximale de RAM que la fonction utilisera, en octets. Il existe des constantes pour aider à choisir une valeur appropriée, dans l'ordre de la taille : `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` et `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Typiquement, ces valeurs devraient être associées aux valeurs opslimit correspondantes.
`algo`
  int Un nombre indiquant l'algorithme de hachage à utiliser. Par défaut `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (l'algorithme actuellement recommandé, qui peut changer d'une version de libsodium à une autre), ou explicitement en utilisant `SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13`, représentant l'algorithme Argon2id version 1.3.

### Valeurs de retour

Renvoie la clé dérivée. La valeur de retour est une chaîne binaire du hachage, pas une représentation encodée en ASCII, et ne contient pas d'informations supplémentaires sur les paramètres utilisés pour créer le hachage, donc il faudra conserver ces informations si l'on doit jamais vérifier le mot de passe à l'avenir. Utiliser sodium_crypto_pwhash_str() pour éviter d'avoir besoin de faire tout cela.

### Exemples

Exemple #1 Exemple de sodium_crypto_pwhash()

    <?php
    //Requis pour conserver le sel si nous devons jamais vérifier ce mot de passe
    $salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
    //Utiliser bin2hex pour garder la sortie lisible
    echo bin2hex(
        sodium_crypto_pwhash(
            16, // == 128 bits
            'password',
            $salt,
            SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
        )
    );
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    a18f346ba57992eb7e4ae6abf3fd30ee

# sodium_crypto_pwhash_scryptsalsa208sha256

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256 — Dérive une clé à partir d'un mot de passe, en utilisant scrypt

### Description

function sodium_crypto_pwhash_scryptsalsa208sha256(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`
): string

Ceci est le pendant scrypt de sodium_crypto_pwhash().

Une raison courante d'utiliser cette fonction est de dériver les graines pour les clés cryptographiques à partir d'un mot de passe et d'un sel, puis d'utiliser ces graines pour générer les clés réelles nécessaires à un certain usage (par exemple sodium_crypto_sign_detached()).

### Liste de paramètres

`length`
  La longueur du hachage de mot de passe à générer, en octets.
`password`
  Le mot de passe pour lequel générer un hachage.
`salt`
  Un sel à ajouter au mot de passe avant le hachage. Le sel doit être imprévisible, idéalement généré à partir d'une bonne source de nombres aléatoires telle que random_bytes(), et avoir une longueur d'au moins `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` octets.
`opslimit`
  Représente une quantité maximale de calculs à effectuer. Augmenter ce nombre fera que la fonction nécessitera plus de cycles CPU pour calculer une clé. Il existe des constantes disponibles pour définir la limite d'opérations à des valeurs appropriées en fonction de l'utilisation prévue, dans l'ordre de la force : `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` et `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE`.
`memlimit`
  La quantité maximale de RAM que la fonction utilisera, en octets. Il existe des constantes pour aider à choisir une valeur appropriée, dans l'ordre de la taille : `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` et `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE`. Typiquement, celles-ci devraient être associées aux valeurs `opslimit` correspondantes.

### Valeurs de retour

Une chaîne d'octets de la longueur désirée.

# sodium_crypto_pwhash_scryptsalsa208sha256_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str — Renvoie un hachage encodé en ASCII

### Description

function sodium_crypto_pwhash_scryptsalsa208sha256_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`password`
`opslimit`
`memlimit`

### Valeurs de retour

# sodium_crypto_pwhash_scryptsalsa208sha256_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Vérifie si le mot de passe correspond à une chaîne de hachage de mot de passe

### Description

function sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`hash`
`password`

### Valeurs de retour

# sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — Renvoie un hachage encodé en ASCII

### Description

function sodium_crypto_pwhash_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Utilise un algorithme de hachage dur en CPU et en mémoire avec un sel généré aléatoirement, et des limites de mémoire et de CPU pour générer un hachage encodé en ASCII adapté au stockage de mots de passe.

### Liste de paramètres

`password`
  string ; Le mot de passe pour lequel générer un hachage.
`opslimit`
  Représente une quantité maximale de calculs à effectuer. Augmenter ce nombre fera que la fonction nécessitera plus de cycles CPU pour calculer une clé. Il existe des constantes disponibles pour définir la limite d'opérations à des valeurs appropriées en fonction de l'utilisation prévue, dans l'ordre de la force : `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` et `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  La quantité maximale de RAM que la fonction utilisera, en octets. Il existe des constantes pour aider à choisir une valeur appropriée, dans l'ordre de la taille : `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` et `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Typiquement, ces valeurs devraient être associées aux valeurs opslimit correspondantes.

### Valeurs de retour

Renvoie le hachage de mot de passe.

Pour produire le même hachage de mot de passe à partir du même mot de passe, les mêmes valeurs pour `opslimit` et `memlimit` doivent être utilisées. Ces valeurs sont intégrées dans le hachage généré, donc tout ce qui est nécessaire pour vérifier le hachage est inclus. Cela permet à la fonction sodium_crypto_pwhash_str_verify() de vérifier le hachage sans avoir besoin de stockage séparé pour les autres paramètres.

### Exemples

Exemple #1 Exemple de sodium_crypto_pwhash_str()

    <?php
    $password = 'password';
    echo sodium_crypto_pwhash_str(
        $password,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
    );

Résultat de l'exemple ci-dessus est similaire à :

    $argon2id$v=19$m=65536,t=2,p=1$oWIfdaXwWwhVmovOBc2NAQ$EbsZ+JnZyyavkafS0hoc4HdaOB0ILWZESAZ7kVGa+Iw

### Notes

> Note: Les hachages sont calculés en utilisant l'algorithme Argon2ID, fournissant une résistance à la fois aux attaques GPU et aux attaques par canaux latéraux. Contrairement à la fonction password_hash(), il n'y a pas de paramètre de sel (un sel est généré automatiquement), et les paramètres `opslimit` et `memlimit` ne sont pas optionnels.

### Voir aussi

- sodium_crypto_pwhash_str_verify() - Vérifie qu'un mot de passe correspond à un hachage
- sodium_crypto_pwhash() - Dérive une clé à partir d'un mot de passe, en utilisant Argon2
- password_hash() - Crée une clé de hachage pour un mot de passe
- password_verify() - Vérifie qu'un mot de passe correspond à un hachage
- » Libsodium Argon2 docs

# sodium_crypto_pwhash_str_needs_rehash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_needs_rehash — Détermine si un mot de passe doit être rehaché

### Description

function sodium_crypto_pwhash_str_needs_rehash(string `$password`, int `$opslimit`, int `$memlimit`): bool

Détermine si un mot de passe doit être rehaché, basé sur le hachage actuel `opslimit` et `memlimit`.

### Liste de paramètres

`password`
  Le hachage de mot de passe
`opslimit`
  La opslimit; voir sodium_crypto_pwhash_str()
`memlimit`
  La memlimit; voir sodium_crypto_pwhash_str()

### Valeurs de retour

Renvoie `true` si le memlimit/opslimit fourni ne correspond pas à ce qui est stocké dans le hachage. Renvoie `false` s'ils correspondent.

# sodium_crypto_pwhash_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_verify — Vérifie qu'un mot de passe correspond à un hachage

### Description

function sodium_crypto_pwhash_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Vérifie qu'un hachage de mot de passe créé en utilisant sodium_crypto_pwhash_str() correspond à un mot de passe en clair donné. Il est à noter que les paramètres sont dans l'ordre inverse des mêmes paramètres dans la fonction similaire password_verify().

### Liste de paramètres

`hash`
  Un hachage créé par la fonction password_hash().
`password`
  Le mot de passe utilisateur.

### Valeurs de retour

Renvoie `true` si le mot de passe et le hachage correspondent, ou `false` sinon.

### Notes

> Note: Les hachages sont calculés en utilisant l'algorithme Argon2ID, fournissant une résistance à la fois aux attaques GPU et aux attaques par canaux latéraux.

### Voir aussi

- sodium_crypto_pwhash_str() - Renvoie un hachage encodé en ASCII
- password_hash() - Crée une clé de hachage pour un mot de passe
- password_verify() - Vérifie qu'un mot de passe correspond à un hachage

# sodium_crypto_scalarmult

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult — Calcule un secret partagé à partir d'une clé secrète et d'une clé publique

### Description

function sodium_crypto_scalarmult(string `$n`, string `$p`): string

Courbe elliptique Diffie-Hellman. Calcule le scalaire n fois le point p, sur une courbe elliptique.

### Liste de paramètres

`n`
  Scalaire, qui est typiquement une clé secrète
`p`
  Un point (coordonnée x), qui est typiquement une clé publique

### Valeurs de retour

Une chaîne aléatoire de 32 octets.

# sodium_crypto_scalarmult_base

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult_base — Alias de sodium_crypto_box_publickey_from_secretkey()

### Description

Cette fonction est un alias de : sodium_crypto_box_publickey_from_secretkey().

# sodium_crypto_scalarmult_ristretto255

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255 — Calcule un secret partagé

### Description

function sodium_crypto_scalarmult_ristretto255(string `$n`, string `$p`): string

Calcule le scalaire `n` fois le point `p`. Disponible depuis libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`n`
  Un scalaire, qui est typiquement une clé secrète.
`p`
  Un point (coordonnée x), qui est typiquement une clé publique.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Voir aussi

- sodium_crypto_scalarmult_ristretto255_base() - Calcule la clé publique à partir d'une clé secrète

# sodium_crypto_scalarmult_ristretto255_base

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255_base — Calcule la clé publique à partir d'une clé secrète

### Description

function sodium_crypto_scalarmult_ristretto255_base(string `$n`): string

Étant donné une clé secrète, calcule la clé publique correspondante. Disponible depuis libsodium 1.0.18.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`n`
  Une clé secrète.

### Valeurs de retour

Renvoie une chaîne de caractères aléatoire de 32 octets.

### Voir aussi

- sodium_crypto_scalarmult_ristretto255() - Calcule un secret partagé

# sodium_crypto_secretbox

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox — Chiffrement authentifié avec une clé partagée

### Description

function sodium_crypto_secretbox(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Chiffre un message avec une clé symétrique (partagée).

### Liste de paramètres

`message`
  Le message en clair à chiffrer.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 24 octets de long. Ceci est une limite suffisamment grande pour être générée aléatoirement (c.-à-d. random_bytes()).
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Renvoie la chaîne chiffrée.

### Erreurs / Exceptions

- Si `nonce` a une longueur de bytes différente de `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 bytes), une SodiumException sera lancée.
- Si `key` a une longueur de bytes différente de `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 bytes), une SodiumException sera lancée.
- Lance une SodiumException en cas d'échec.

### Exemples

Exemple #1 Exemple de sodium_crypto_secretbox()

    <?php
    // La $key doit être gardée confidentielle
    $key = sodium_crypto_secretbox_keygen();
    // Ne pas réutiliser $nonce avec la même clé
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $plaintext = "message to be encrypted";
    $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);

    var_dump(bin2hex($ciphertext));
    // Le même nonce et la même clé sont nécessaires pour déchiffrer le $ciphertext
    var_dump(sodium_crypto_secretbox_open($ciphertext, $nonce, $key));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(78) "3a1fa3e9f7b72ef8be51d40abf8e296c6899c185d07b18b4c93e7f26aa776d24c50852cd6b1076"
    string(23) "message to be encrypted"

### Voir aussi

- sodium_crypto_secretbox_open() - Déchiffrement authentifié avec une clé partagée
- sodium_crypto_secretbox_keygen() - Génère une clé aléatoire pour sodium_crypto_secretbox
- random_bytes() - Récupère des octets aléatoires cryptographiquement sécurisés

# sodium_crypto_secretbox_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_keygen — Génère une clé aléatoire pour sodium_crypto_secretbox

### Description

function sodium_crypto_secretbox_keygen(): string

Génère une clé pour être utilisée avec sodium_crypto_secretbox() et sodium_crypto_secretbox_open().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la chaîne générée de bytes aléatoires cryptographiquement sécurisés.

### Exemples

Exemple #1 Exemple de sodium_crypto_secretbox_keygen()

    <?php
    $key = sodium_crypto_secretbox_keygen();
    var_dump( sodium_bin2hex( $key ) );
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(64) "88bd1dc51ec81984f3ddc5a8f59a3d95b647e2da3e879f1b9ceb0abd89e7286c"

Exemple #2 Comparer sodium_crypto_secretbox_keygen() avec random_bytes()

    <?php
    $key = sodium_crypto_secretbox_keygen();
    $bytes = random_bytes( SODIUM_CRYPTO_SECRETBOX_KEYBYTES );
    var_dump( mb_strlen( $key, '8bit' ) === mb_strlen( $bytes, '8bit' ) );
    ?>

L'exemple ci-dessus va afficher :

    bool(true)

### Voir aussi

- sodium_bin2hex() - Encode en hexadécimal
- random_bytes() - Récupère des octets aléatoires cryptographiquement sécurisés

# sodium_crypto_secretbox_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_open — Déchiffrement authentifié avec une clé partagée

### Description

function sodium_crypto_secretbox_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key`): string|false

Déchiffrement d'un message chiffré avec une clé symétrique (partagée).

### Liste de paramètres

`ciphertext`
  Doit être au format fourni par sodium_crypto_secretbox() (concaténation du texte chiffré et du tag).
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 24 octets de long. Ceci est une limite suffisamment grande pour être générée aléatoirement (c.-à-d. random_bytes()).
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

La chaîne déchiffrée en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

- Si `nonce` a une longueur d'octets différente de `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 octets), une SodiumException sera lancée.
- Si `key` a une longueur d'octets différente de `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 octets), une SodiumException sera lancée.

### Exemples

Exemple #1 Exemple de sodium_crypto_secretbox_open()

    <?php
    // La $key doit être gardée confidentielle
    $key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
    // Ne pas réutiliser $nonce avec la même clé
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = sodium_crypto_secretbox('message to be encrypted', $nonce, $key);

    // Le même nonce et la même clé sont nécessaires pour déchiffrer le $ciphertext
    $plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
    if ($plaintext !== false) {
        echo $plaintext . PHP_EOL;
    }
    ?>

L'exemple ci-dessus va afficher :

    message to be encrypted

### Voir aussi

- sodium_crypto_secretbox() - Chiffrement authentifié avec une clé partagée
- sodium_crypto_secretbox_keygen() - Génère une clé aléatoire pour sodium_crypto_secretbox
- random_bytes() - Récupère des octets aléatoires cryptographiquement sécurisés

# sodium_crypto_secretstream_xchacha20poly1305_init_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_pull — Initialise un contexte secretstream pour le déchiffrement

### Description

function sodium_crypto_secretstream_xchacha20poly1305_init_pull(string `$header`, #[\SensitiveParameter]string `$key`): string

Initialise un contexte secretstream pour le déchiffrement.

### Liste de paramètres

`header`
  L'en-tête du secretstream. Cela devrait être une des valeurs produites par sodium_crypto_secretstream_xchacha20poly1305_init_push().
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

L'état du secretstream.

### Exemples

Exemple #1 Exemple de sodium_crypto_secretstream_xchacha20poly1305_init_pull()

    <?php
    function decrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        $header = fread($inputFile, 24);

        $state = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
        $inputFileSize = fstat($inputFile)['size'];

        // Déchiffre le fichier et écrit son contenu dans le fichier de sortie :
        for ($i = 24; $i < $inputFileSize; $i += 8192) {
            $ctxt_chunk = fread($inputFile, 8192);

            // Nous n'utilisons pas $tag, mais dans de vrais protocoles, vous pouvez l'utiliser pour chiffrer par exemple
            // déclencher une nouvelle clé ou indiquer la fin du fichier. Ensuite, lors du déchiffrement, vous pouvez
            // vérifier ce comportement.
            [$ptxt_chunk, $tag] = sodium_crypto_secretstream_xchacha20poly1305_pull($state, $ctxt_chunk);
            fwrite($outputFile, $ptxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    $example = sodium_hex2bin('971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c');
    file_put_contents('hello.enc', $example);
    decrypt_file('hello.enc', 'hello.txt.decrypted', $key);
    var_dump(file_get_contents('hello.txt.decrypted'));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(12) "Hello world!"

# sodium_crypto_secretstream_xchacha20poly1305_init_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_push — Initialise un contexte secretstream pour le chiffrement

### Description

function sodium_crypto_secretstream_xchacha20poly1305_init_push(#[\SensitiveParameter]string `$key`): array

Initialise un contexte secretstream pour le chiffrement.

### Liste de paramètres

`key`
  La clé de chiffrement. Voir sodium_crypto_secretstream_xchacha20poly1305_keygen().

### Valeurs de retour

Un tableau avec deux valeurs de chaîne:

- L'état du secretstream, nécessaire pour les prochains appels
- L'en-tête du secretstream, qui doit être fourni au destinataire pour qu'il puisse extraire les données

### Exemples

Exemple #1 Exemple de sodium_crypto_secretstream_xchacha20poly1305_init_push()

    <?php
    function encrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        [$state, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);

        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        // Ecrit l'en-tête:
        fwrite($outputFile, $header);
        $inputFileSize = fstat($inputFile)['size'];

        // Encrypte le fichier et écrit son contenu dans le fichier de sortie:
        for ($i = 0; $i < $inputFileSize; $i += 8175) {
            $ptxt_chunk = fread($inputFile, 8175);
            $ctxt_chunk = sodium_crypto_secretstream_xchacha20poly1305_push($state, $ptxt_chunk);
            fwrite($outputFile, $ctxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    file_put_contents('hello.txt', 'Hello world!');
    encrypt_file('hello.txt', 'hello.txt.encrypted', $key);
    var_dump(sodium_bin2hex(file_get_contents('hello.txt.encrypted')));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(106) "971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c"

# sodium_crypto_secretstream_xchacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_keygen — Génère une clé secretstream aléatoire.

### Description

function sodium_crypto_secretstream_xchacha20poly1305_keygen(): string

Génère une clé secretstream aléatoire.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une chaîne de bytes aléatoires.

# sodium_crypto_secretstream_xchacha20poly1305_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_pull — Déchiffre un morceau de données d'un flux chiffré

### Description

function sodium_crypto_secretstream_xchacha20poly1305_pull(string `&$state`, string `$ciphertext`, string `$additional_data` = ""): array|false

Déchiffre un morceau de données d'un flux chiffré.

### Liste de paramètres

`state`
  Voir sodium_crypto_secretstream_xchacha20poly1305_init_pull() et sodium_crypto_secretstream_xchacha20poly1305_init_push()
`ciphertext`
  Le morceau de texte chiffré à déchiffrer.
`additional_data`
  Optionnel des données supplémentaires à inclure dans le tag d'authentification.

### Valeurs de retour

Un tableau avec deux valeurs:

- string; le morceau de texte déchiffré.

- int; Une étiquette optionnelle (si fournie lors de l'envoi). Valeurs possibles:

  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: l'étiquette la plus courante, qui n'ajoute aucune information sur la nature du message.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: indique que le message marque la fin du flux, et efface la clé secrète utilisée pour chiffrer la séquence précédente.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: indique que le message marque la fin d'un ensemble de messages, mais pas la fin du flux. Par exemple, une énorme chaîne JSON envoyée en plusieurs morceaux peut utiliser cette étiquette pour indiquer à l'application que la chaîne est complète et qu'elle peut être décodée. Mais le flux lui-même n'est pas fermé, et d'autres données peuvent suivre.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: "forget" la clé utilisée pour chiffrer ce message et les précédents, et dérive une nouvelle clé secrète.

# sodium_crypto_secretstream_xchacha20poly1305_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_push — Chiffre un morceau de données pour qu'il puisse être déchiffré dans une API de streaming

### Description

function sodium_crypto_secretstream_xchacha20poly1305_push(
string `&$state`,
#[\SensitiveParameter]string `$message`,
string `$additional_data` = "",
int `$tag` = `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`
): string

Chiffre un morceau de données pour qu'il puisse être déchiffré dans une API de streaming.

### Liste de paramètres

`state`
  Voir sodium_crypto_secretstream_xchacha20poly1305_init_pull() et sodium_crypto_secretstream_xchacha20poly1305_init_push()
`message`
`additional_data`
`tag`
  Optionnel. Peut être utilisé pour affirmer le comportement de déchiffrement (c'est-à-dire le renouvellement de la clé ou l'indication du dernier morceau dans un flux).
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: l'étiquette la plus courante, qui n'ajoute aucune information sur la nature du message.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: indique que le message marque la fin du flux, et efface la clé secrète utilisée pour chiffrer la séquence précédente.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: indique que le message marque la fin d'un ensemble de messages, mais pas la fin du flux. Par exemple, une énorme chaîne JSON envoyée en plusieurs morceaux peut utiliser cette étiquette pour indiquer à l'application que la chaîne est complète et qu'elle peut être décodée. Mais le flux lui-même n'est pas fermé, et d'autres données peuvent suivre.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: "forget" la clé utilisée pour chiffrer ce message et les précédents, et dériver une nouvelle clé secrète.

### Valeurs de retour

Renvoie le morceau de texte chiffré.

# sodium_crypto_secretstream_xchacha20poly1305_rekey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_rekey — Renouvelle explicitement la clé dans l'état secretstream

### Description

function sodium_crypto_secretstream_xchacha20poly1305_rekey(string `&$state`): void

Renouvelle explicitement la clé dans l'état secretstream. Remplace la valeur passée en paramètre.

### Liste de paramètres

`state`
  L'état du secretstream.

### Valeurs de retour

Aucune valeur n'est retournée.

# sodium_crypto_shorthash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash — Calcule un hachage court d'un message et d'une clé

### Description

function sodium_crypto_shorthash(string `$message`, #[\SensitiveParameter]string `$key`): string

sodium_crypto_shorthash() enveloppe une fonction de hachage appelée SipHash-2-4, qui est idéale pour implémenter des tables de hachage qui ne sont pas susceptibles aux attaques de déni de service par collision de hachage (Hash-DoS).

SipHash-2-4 n'est pas une fonction de hachage cryptographique générale.

### Liste de paramètres

`message`
  Le message à hacher.
`key`
  La clé de hachage.

### Valeurs de retour

# sodium_crypto_shorthash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash_keygen — Renvoie des octets aléatoires pour la clé

### Description

function sodium_crypto_shorthash_keygen(): string

Renvoie une clé pour une utilisation avec sodium_crypto_shorthash().

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# sodium_crypto_sign

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign — Signe un message

### Description

function sodium_crypto_sign(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Signe un message avec une clé secrète, qui peut être vérifiée par la clé publique correspondante. Cette fonction attache la signature au message. Voir sodium_crypto_sign_detached() pour les signatures détachées.

### Liste de paramètres

`message`
  Le message à signer.
`secret_key`
  La clé secrète. Voir sodium_crypto_sign_secretkey()

### Valeurs de retour

Le message signé (non chiffré).

# sodium_crypto_sign_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_detached — Signe le message

### Description

function sodium_crypto_sign_detached(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Signe un message avec une clé secrète, qui peut être vérifiée par la clé publique correspondante. Cette fonction renvoie une signature détachée.

### Liste de paramètres

`message`
  Le message à signer.
`secret_key`
  La clé secrète. Voir sodium_crypto_sign_secretkey()

### Valeurs de retour

La signature cryptographique.

# sodium_crypto_sign_ed25519_pk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_pk_to_curve25519 — Convertit une clé publique Ed25519 en une clé publique Curve25519

### Description

function sodium_crypto_sign_ed25519_pk_to_curve25519(string `$public_key`): string

Étant donné une clé publique Ed25519, calcule la clé publique X25519 birationnellement équivalente.

### Liste de paramètres

`public_key`
  La clé publique appropriée pour les fonctions crypto_sign.

### Valeurs de retour

La clé publique appropriée pour les fonctions crypto_box.

# sodium_crypto_sign_ed25519_sk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_sk_to_curve25519 — Convertit une clé secrète Ed25519 en une clé secrète Curve25519

### Description

function sodium_crypto_sign_ed25519_sk_to_curve25519(#[\SensitiveParameter]string `$secret_key`): string

Étant donné une clé secrète Ed25519, calcule la clé secrète X25519 birationnellement équivalente.

### Liste de paramètres

`secret_key`
  La clé secrète appropriée pour les fonctions crypto_sign.

### Valeurs de retour

La clé secrète appropriée pour les fonctions crypto_box.

# sodium_crypto_sign_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair — Génère aléatoirement une clé secrète et une clé publique correspondante

### Description

function sodium_crypto_sign_keypair(): string

Génère une paire de clés Ed25519 aléatoires.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La paire de clés Ed25519.

# sodium_crypto_sign_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair_from_secretkey_and_publickey — Rassemble une clé secrète et une clé publique ensemble

### Description

function sodium_crypto_sign_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

Rassemble une clé secrète et une clé publique ensemble.

### Liste de paramètres

`secret_key`
  La clé secrète Ed25519
`public_key`
  La clé publique

### Valeurs de retour

Une paire de clés

# sodium_crypto_sign_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_open — Vérifie que le message signé possède une signature valide

### Description

function sodium_crypto_sign_open(string `$signed_message`, string `$public_key`): string|false

Vérifie la signature attachée à un message et renvoie le message

### Liste de paramètres

`signed_message`
  Un message signé avec sodium_crypto_sign()
`public_key`
  Une clé publique Ed25519

### Valeurs de retour

Renvoie le message signé original en cas de succès, ou `false` si une erreur survient.

# sodium_crypto_sign_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey — Extrait la clé publique Ed25519 d'une paire de clés

### Description

function sodium_crypto_sign_publickey(#[\SensitiveParameter]string `$key_pair`): string

Extrait la clé publique Ed25519 d'une paire de clés

### Liste de paramètres

`key_pair`
  Une paire de clés Ed25519 (voir : sodium_crypto_sign_keypair())

### Valeurs de retour

La clé publique Ed25519

# sodium_crypto_sign_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey_from_secretkey — Extrait la clé publique Ed25519 de la clé secrète

### Description

function sodium_crypto_sign_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Extrait la clé publique Ed25519 de la clé secrète

### Liste de paramètres

`secret_key`
  La clé secrète Ed25519

### Valeurs de retour

La clé publique Ed25519

# sodium_crypto_sign_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_secretkey — Extrait la clé secrète Ed25519 d'une paire de clés

### Description

function sodium_crypto_sign_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Extrait la clé secrète Ed25519 d'une paire de clés

### Liste de paramètres

`key_pair`
  La paire de clés Ed25519 (voir : sodium_crypto_sign_keypair())

### Valeurs de retour

La clé secrète Ed25519

# sodium_crypto_sign_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_seed_keypair — Dérive de manière déterministe la paire de clés à partir d'une seule clé

### Description

function sodium_crypto_sign_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Conditionne la graine pour former une clé secrète, dérive la clé publique et renvoie les deux en tant que paire de clés.

Les fonctions `*_seed_keypair` sont idéales pour générer une paire de clés à partir d'un mot de passe et d'un sel. Utiliser le résultat comme `seed` pour générer les clés souhaitées.

### Liste de paramètres

`seed`
  Quelques données cryptographiques. Doit être de 32 octets.

### Valeurs de retour

Une paire de clés (clé secrète et clé publique)

# sodium_crypto_sign_verify_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_verify_detached — Vérifie la signature d'un message

### Description

function sodium_crypto_sign_verify_detached(string `$signature`, string `$message`, string `$public_key`): bool

Vérifie la signature d'un message

### Liste de paramètres

`signature`
  La signature cryptographique obtenue à partir de sodium_crypto_sign_detached()
`message`
  Le message à vérifier
`public_key`
  La clé publique Ed25519

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# sodium_crypto_stream

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream — Génère une séquence d'octets déterministe à partir d'une graine

### Description

function sodium_crypto_stream(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Génère une séquence d'octets déterministe à partir d'une graine, en utilisant le chiffrement de flux XSalsa20.

### Liste de paramètres

`length`
  Le nombre d'octets à retourner.
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 24 octets de long. C'est une limite suffisamment grande pour être générée aléatoirement (c.-à-d. random_bytes()).
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Une chaîne d'octets pseudo-aléatoires.

# sodium_crypto_stream_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_keygen — Génère une clé de chiffrement aléatoire pour sodium_crypto_stream

### Description

function sodium_crypto_stream_keygen(): string

Génère une clé pour être utilisée avec sodium_crypto_stream() et sodium_crypto_stream_xor().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La clé de chiffrement (256 bits).

# sodium_crypto_stream_xchacha20

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20 — Développe la clé et le nonce en un flux de clés de bytes pseudo-aléatoires

### Description

function sodium_crypto_stream_xchacha20(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Développe la `key` et le `nonce` en un flux de clés d'octets pseudo-aléatoires.

### Liste de paramètres

`length`
  Le nombre d'octets désiré.
`nonce`
  Un nonce de 24 octets.
`key`
  Clé, possiblement générée par la fonction sodium_crypto_stream_xchacha20_keygen().

### Valeurs de retour

Renvoie un flux pseudo-aléatoire qui peut être utilisé avec sodium_crypto_stream_xchacha20_xor().

# sodium_crypto_stream_xchacha20_keygen

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_keygen — Renvoie une clé aléatoire sécurisée

### Description

function sodium_crypto_stream_xchacha20_keygen(): string

Renvoie une clé aléatoire sécurisée pour être utilisée avec sodium_crypto_stream_xchacha20().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une clé sécurisée de 32 octets pour être utilisée avec sodium_crypto_stream_xchacha20().

# sodium_crypto_stream_xchacha20_xor

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_xor — Chiffre une donnée en utilisant un nonce et une clé secrète (sans authentification)

### Description

function sodium_crypto_stream_xchacha20_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Chiffre un `message` en utilisant un `nonce` et une clé secrète `key` (sans authentification).

Attention

Ce chiffrement est non authentifié, et ne prévient pas les attaques par texte chiffré choisi. Il faut s'assurer de combiner le texte chiffré avec un code d'authentification de message, par exemple avec la fonction sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(), ou sodium_crypto_auth().

### Liste de paramètres

`message`
  Le message à chiffrer.
`nonce`
  Un nonce de 24 octets.
`key`
  Clé, possiblement générée par la fonction sodium_crypto_stream_xchacha20_keygen().

### Valeurs de retour

Le texte chiffré.

### Voir aussi

- sodium_crypto_stream_xchacha20_xor_ic() - Chiffre un message en utilisant un nonce et une clé secrète (sans authentification)

# sodium_crypto_stream_xchacha20_xor_ic

(PHP 8 >= 8.2.0)

sodium_crypto_stream_xchacha20_xor_ic — Chiffre un message en utilisant un nonce et une clé secrète (sans authentification)

### Description

function sodium_crypto_stream_xchacha20_xor_ic(
#[\SensitiveParameter]string `$message`,
string `$nonce`,
int `$counter`,
#[\SensitiveParameter]string `$key`
): string

Cette fonction est similaire à sodium_crypto_stream_xchacha20_xor() mais ajoute la possibilité de définir la valeur initiale du compteur de blocs à une valeur non nulle. Cela permet d'accéder directement à n'importe quel bloc sans avoir à calculer les précédents.

Attention

Ce chiffrement est non authentifié, et ne prévient pas les attaques par texte chiffré choisi. Il faut s'assurer de combiner le texte chiffré avec un code d'authentification de message, par exemple avec la fonction sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(), ou sodium_crypto_auth().

### Liste de paramètres

`message`
  Le message à chiffrer.
`nonce`
  Un nonce de 24 octets.
`counter`
  La valeur initiale du compteur de blocs.
`key`
  Clé, possiblement générée par la fonction sodium_crypto_stream_xchacha20_keygen().

### Valeurs de retour

Le texte chiffré, ou ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de sodium_crypto_stream_xchacha20_xor_ic()

    <?php
    $n2 = random_bytes(SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES);
    $left  = str_repeat("\x01", 64);
    $right = str_repeat("\xfe", 64);

    // Tout en une fois :
    $stream7_unified = sodium_crypto_stream_xchacha20_xor($left . $right, $n2, $key);

    // Par morceaux, avec un compteur initial :
    $stream7_left  = sodium_crypto_stream_xchacha20_xor_ic($left, $n2, 0, $key);
    $stream7_right = sodium_crypto_stream_xchacha20_xor_ic($right, $n2, 1, $key);
    $stream7_concat = $stream7_left . $stream7_right;

    var_dump(strlen($stream7_concat));
    var_dump($stream7_unified === $stream7_concat);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(128)
    bool(true)

### Voir aussi

- sodium_crypto_stream_xchacha20_xor() - Chiffre une donnée en utilisant un nonce et une clé secrète (sans authentification)

# sodium_crypto_stream_xor

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_xor — Chiffre un message sans authentification

### Description

function sodium_crypto_stream_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Cette fonction chiffre un message avec XSalsa20, mais ne fournit aucune garantie d'intégrité du texte chiffré sur le texte en clair.

### Liste de paramètres

`message`
  Le message à chiffrer
`nonce`
  Un nombre qui doit être utilisé une seule fois, par message. 24 octets de long. C'est une limite suffisamment grande pour être générée aléatoirement (c.-à-d. random_bytes()).
`key`
  La clé de chiffrement (256 bits).

### Valeurs de retour

Le message chiffré.

# sodium_hex2bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_hex2bin — Décode une chaîne binaire encodée en hexadécimal

### Description

function sodium_hex2bin(#[\SensitiveParameter]string `$string`, string `$ignore` = ""): string

Décode une chaîne binaire encodée en hexadécimal.

Comme sodium_bin2hex(), sodium_hex2bin() est résistant aux attaques par canaux secondaires tandis que hex2bin() ne l'est pas.

### Liste de paramètres

`string`
  La représentation hexadécimale des données.
`ignore`
  Une chaîne de caractères optionnelle pour les caractères à ignorer.

### Valeurs de retour

Renvoie la représentation binaire des données de la chaîne `string`.

# sodium_increment

(PHP 7 >= 7.2.0, PHP 8)

sodium_increment — Incrémente un grand nombre

### Description

function sodium_increment(string `&$string`): void

Traite la chaîne comme un entier non signé en little-endian, puis l'incrémente de 1. Temps constant.

### Liste de paramètres

`string`
  La chaîne à incrémenter.

### Valeurs de retour

Aucune valeur n'est retournée.

# sodium_memcmp

(PHP 7 >= 7.2.0, PHP 8)

sodium_memcmp — Teste l'égalité en temps constant

### Description

function sodium_memcmp(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

Compare deux chaînes en temps constant.

En pratique, l'on veut presque toujours utiliser hash_equals() à la place, car il fournit la même logique mais renvoie un bool au lieu d'un int. Cependant, lors de l'utilisation de la valeur de retour d'une comparaison dans un calcul qui est sensible au temps, et que l'on craigne des fuites de temps avec des conversions bool-to-int, sodium_memcmp() est un remplacement idéal.

### Liste de paramètres

`string1`
  La chaîne à comparer
`string2`
  L'autre chaîne à comparer

### Valeurs de retour

Renvoie `0` si les deux chaînes sont égales; `-1` sinon.

# sodium_memzero

(PHP 7 >= 7.2.0, PHP 8)

sodium_memzero — Écrase une chaîne avec des caractères NUL

### Description

function sodium_memzero(#[\SensitiveParameter]string `&$string`): void

sodium_memzero() remplace par des zéros la chaîne passée par référence.

### Liste de paramètres

`string`
  Chaîne.

### Valeurs de retour

Aucune valeur n'est retournée.

# sodium_pad

(PHP 7 >= 7.2.0, PHP 8)

sodium_pad — Ajoute des données de remplissage

### Description

function sodium_pad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Remplit à droite une chaîne jusqu'à la longueur désirée. Sécurisé en termes de temps.

### Liste de paramètres

`string`
  La chaîne non remplie.
`block_size`
  La chaîne sera remplie jusqu'à ce qu'elle soit un multiple entier de la taille du bloc.

### Valeurs de retour

La chaîne rembourrée.

# sodium_unpad

(PHP 7 >= 7.2.0, PHP 8)

sodium_unpad — Supprime les données de remplissage

### Description

function sodium_unpad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Supprime les données de remplissage d'une chaîne. Sécurisé en termes de temps.

### Liste de paramètres

`string`
  La chaîne remplie.
`block_size`
  La taille du bloc pour le remplissage.

### Valeurs de retour

La chaîne non remplie.

## Sommaire

- sodium_add — Ajoute de grands nombres
- sodium_base642bin — Décode une chaîne encodée en base64 en binaire brut.
- sodium_bin2base64 — Encode une chaîne binaire brute en base64.
- sodium_bin2hex — Encode en hexadécimal
- sodium_compare — Compare des grands nombres
- sodium_crypto_aead_aegis128l_decrypt — Vérifie puis déchiffre un message avec AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt — Chiffre puis authentifie un message avec AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen — Génère une clé AEGIS-128L aléatoire
- sodium_crypto_aead_aegis256_decrypt — Vérifie puis déchiffre un message avec AEGIS-256
- sodium_crypto_aead_aegis256_encrypt — Chiffre puis authentifie un message avec AEGIS-256
- sodium_crypto_aead_aegis256_keygen — Génère une clé AEGIS-256 aléatoire
- sodium_crypto_aead_aes256gcm_decrypt — Vérifie puis déchiffre un message avec AES-256-GCM
- sodium_crypto_aead_aes256gcm_encrypt — Chiffre puis authentifie avec AES-256-GCM
- sodium_crypto_aead_aes256gcm_is_available — Vérifie si le matériel prend en charge AES256-GCM
- sodium_crypto_aead_aes256gcm_keygen — Génère une clé AES-256-GCM aléatoire
- sodium_crypto_aead_chacha20poly1305_decrypt — Vérifie puis déchiffre avec ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_encrypt — Chiffre puis authentifie avec ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Vérifie que le texte chiffré inclut une étiquette valide
- sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Chiffre un message
- sodium_crypto_aead_chacha20poly1305_ietf_keygen — Génère une clé ChaCha20-Poly1305 (IETF) aléatoire
- sodium_crypto_aead_chacha20poly1305_keygen — Génère une clé ChaCha20-Poly1305 aléatoire
- sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Préféré) Vérifie puis déchiffre avec XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Préféré) Chiffre puis authentifie avec XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Génère une clé XChaCha20-Poly1305 aléatoire.
- sodium_crypto_auth — Calcule une étiquette pour le message
- sodium_crypto_auth_keygen — Génère une clé aléatoire pour sodium_crypto_auth
- sodium_crypto_auth_verify — Vérifie que l'étiquette est valide pour le message
- sodium_crypto_box — Chiffrement asymétrique authentifié
- sodium_crypto_box_keypair — Génère aléatoirement une clé secrète et une clé publique correspondante
- sodium_crypto_box_keypair_from_secretkey_and_publickey — Créer une paire de clés unifiée à partir d'une clé secrète et d'une clé publique
- sodium_crypto_box_open — Déchiffrement authentifié avec clé publique
- sodium_crypto_box_publickey — Extrait la clé publique d'une paire de clés crypto_box
- sodium_crypto_box_publickey_from_secretkey — Calcule la clé publique à partir d'une clé secrète
- sodium_crypto_box_seal — Chiffrement anonyme avec clé publique
- sodium_crypto_box_seal_open — Déchiffrement anonyme avec clé publique
- sodium_crypto_box_secretkey — Extrait la clé secrète d'une paire de clés crypto_box
- sodium_crypto_box_seed_keypair — Dérive de manière déterministe la paire de clés à partir d'une seule clé
- sodium_crypto_core_ristretto255_add — Ajoute un élément
- sodium_crypto_core_ristretto255_from_hash — Mappe un vecteur
- sodium_crypto_core_ristretto255_is_valid_point — Détermine si un point est sur la courbe ristretto255
- sodium_crypto_core_ristretto255_random — Génère une clé aléatoire
- sodium_crypto_core_ristretto255_scalar_add — Ajoute une valeur scalaire
- sodium_crypto_core_ristretto255_scalar_complement — Le but de sodium_crypto_core_ristretto255_scalar_complement
- sodium_crypto_core_ristretto255_scalar_invert — Inverse une valeur scalaire
- sodium_crypto_core_ristretto255_scalar_mul — Multiplie une valeur scalaire
- sodium_crypto_core_ristretto255_scalar_negate — Inverse le signe d'une valeur scalaire
- sodium_crypto_core_ristretto255_scalar_random — Génère une clé aléatoire
- sodium_crypto_core_ristretto255_scalar_reduce — Réduit une valeur scalaire
- sodium_crypto_core_ristretto255_scalar_sub — Soustrait une valeur scalaire
- sodium_crypto_core_ristretto255_sub — Soustrait un élément
- sodium_crypto_generichash — Renvoie un hachage du message
- sodium_crypto_generichash_final — Complète le hachage
- sodium_crypto_generichash_init — Initialise un hachage pour le streaming
- sodium_crypto_generichash_keygen — Génère une clé de hachage générique aléatoire
- sodium_crypto_generichash_update — Ajoute un message à un hachage
- sodium_crypto_kdf_derive_from_key — Dérive une sous-clé
- sodium_crypto_kdf_keygen — Génère une clé racine aléatoire pour l'interface KDF
- sodium_crypto_kx_client_session_keys — Calcule les clés de session côté client.
- sodium_crypto_kx_keypair — Créer une nouvelle paire de clés sodium
- sodium_crypto_kx_publickey — Extrait la clé publique d'une paire de clés crypto_kx
- sodium_crypto_kx_secretkey — Extrait la clé secrète d'une paire de clés crypto_kx
- sodium_crypto_kx_seed_keypair — Description
- sodium_crypto_kx_server_session_keys — Calcule les clés de session côté serveur.
- sodium_crypto_pwhash — Dérive une clé à partir d'un mot de passe, en utilisant Argon2
- sodium_crypto_pwhash_scryptsalsa208sha256 — Dérive une clé à partir d'un mot de passe, en utilisant scrypt
- sodium_crypto_pwhash_scryptsalsa208sha256_str — Renvoie un hachage encodé en ASCII
- sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Vérifie si le mot de passe correspond à une chaîne de hachage de mot de passe
- sodium_crypto_pwhash_str — Renvoie un hachage encodé en ASCII
- sodium_crypto_pwhash_str_needs_rehash — Détermine si un mot de passe doit être rehaché
- sodium_crypto_pwhash_str_verify — Vérifie qu'un mot de passe correspond à un hachage
- sodium_crypto_scalarmult — Calcule un secret partagé à partir d'une clé secrète et d'une clé publique
- sodium_crypto_scalarmult_base — Alias de sodium_crypto_box_publickey_from_secretkey
- sodium_crypto_scalarmult_ristretto255 — Calcule un secret partagé
- sodium_crypto_scalarmult_ristretto255_base — Calcule la clé publique à partir d'une clé secrète
- sodium_crypto_secretbox — Chiffrement authentifié avec une clé partagée
- sodium_crypto_secretbox_keygen — Génère une clé aléatoire pour sodium_crypto_secretbox
- sodium_crypto_secretbox_open — Déchiffrement authentifié avec une clé partagée
- sodium_crypto_secretstream_xchacha20poly1305_init_pull — Initialise un contexte secretstream pour le déchiffrement
- sodium_crypto_secretstream_xchacha20poly1305_init_push — Initialise un contexte secretstream pour le chiffrement
- sodium_crypto_secretstream_xchacha20poly1305_keygen — Génère une clé secretstream aléatoire.
- sodium_crypto_secretstream_xchacha20poly1305_pull — Déchiffre un morceau de données d'un flux chiffré
- sodium_crypto_secretstream_xchacha20poly1305_push — Chiffre un morceau de données pour qu'il puisse être déchiffré dans une API de streaming
- sodium_crypto_secretstream_xchacha20poly1305_rekey — Renouvelle explicitement la clé dans l'état secretstream
- sodium_crypto_shorthash — Calcule un hachage court d'un message et d'une clé
- sodium_crypto_shorthash_keygen — Renvoie des octets aléatoires pour la clé
- sodium_crypto_sign — Signe un message
- sodium_crypto_sign_detached — Signe le message
- sodium_crypto_sign_ed25519_pk_to_curve25519 — Convertit une clé publique Ed25519 en une clé publique Curve25519
- sodium_crypto_sign_ed25519_sk_to_curve25519 — Convertit une clé secrète Ed25519 en une clé secrète Curve25519
- sodium_crypto_sign_keypair — Génère aléatoirement une clé secrète et une clé publique correspondante
- sodium_crypto_sign_keypair_from_secretkey_and_publickey — Rassemble une clé secrète et une clé publique ensemble
- sodium_crypto_sign_open — Vérifie que le message signé possède une signature valide
- sodium_crypto_sign_publickey — Extrait la clé publique Ed25519 d'une paire de clés
- sodium_crypto_sign_publickey_from_secretkey — Extrait la clé publique Ed25519 de la clé secrète
- sodium_crypto_sign_secretkey — Extrait la clé secrète Ed25519 d'une paire de clés
- sodium_crypto_sign_seed_keypair — Dérive de manière déterministe la paire de clés à partir d'une seule clé
- sodium_crypto_sign_verify_detached — Vérifie la signature d'un message
- sodium_crypto_stream — Génère une séquence d'octets déterministe à partir d'une graine
- sodium_crypto_stream_keygen — Génère une clé de chiffrement aléatoire pour sodium_crypto_stream
- sodium_crypto_stream_xchacha20 — Développe la clé et le nonce en un flux de clés de bytes pseudo-aléatoires
- sodium_crypto_stream_xchacha20_keygen — Renvoie une clé aléatoire sécurisée
- sodium_crypto_stream_xchacha20_xor — Chiffre une donnée en utilisant un nonce et une clé secrète (sans authentification)
- sodium_crypto_stream_xchacha20_xor_ic — Chiffre un message en utilisant un nonce et une clé secrète (sans authentification)
- sodium_crypto_stream_xor — Chiffre un message sans authentification
- sodium_hex2bin — Décode une chaîne binaire encodée en hexadécimal
- sodium_increment — Incrémente un grand nombre
- sodium_memcmp — Teste l'égalité en temps constant
- sodium_memzero — Écrase une chaîne avec des caractères NUL
- sodium_pad — Ajoute des données de remplissage
- sodium_unpad — Supprime les données de remplissage

# La classe SodiumException

(PHP 7 >= 7.2.0, PHP 8)

## Introduction

Exception lancée par les fonctions sodium.

## Synopsis de la classe

class SodiumException extends Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Installation/Configuration
  - Pré-requis
  - Installation
- Constantes pré-définies
- Fonctions Sodium
  - sodium_add — Ajoute de grands nombres
  - sodium_base642bin — Décode une chaîne encodée en base64 en binaire brut.
  - sodium_bin2base64 — Encode une chaîne binaire brute en base64.
  - sodium_bin2hex — Encode en hexadécimal
  - sodium_compare — Compare des grands nombres
  - sodium_crypto_aead_aegis128l_decrypt — Vérifie puis déchiffre un message avec AEGIS-128L
  - sodium_crypto_aead_aegis128l_encrypt — Chiffre puis authentifie un message avec AEGIS-128L
  - sodium_crypto_aead_aegis128l_keygen — Génère une clé AEGIS-128L aléatoire
  - sodium_crypto_aead_aegis256_decrypt — Vérifie puis déchiffre un message avec AEGIS-256
  - sodium_crypto_aead_aegis256_encrypt — Chiffre puis authentifie un message avec AEGIS-256
  - sodium_crypto_aead_aegis256_keygen — Génère une clé AEGIS-256 aléatoire
  - sodium_crypto_aead_aes256gcm_decrypt — Vérifie puis déchiffre un message avec AES-256-GCM
  - sodium_crypto_aead_aes256gcm_encrypt — Chiffre puis authentifie avec AES-256-GCM
  - sodium_crypto_aead_aes256gcm_is_available — Vérifie si le matériel prend en charge AES256-GCM
  - sodium_crypto_aead_aes256gcm_keygen — Génère une clé AES-256-GCM aléatoire
  - sodium_crypto_aead_chacha20poly1305_decrypt — Vérifie puis déchiffre avec ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_encrypt — Chiffre puis authentifie avec ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Vérifie que le texte chiffré inclut une étiquette valide
  - sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Chiffre un message
  - sodium_crypto_aead_chacha20poly1305_ietf_keygen — Génère une clé ChaCha20-Poly1305 (IETF) aléatoire
  - sodium_crypto_aead_chacha20poly1305_keygen — Génère une clé ChaCha20-Poly1305 aléatoire
  - sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Préféré) Vérifie puis déchiffre avec XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Préféré) Chiffre puis authentifie avec XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Génère une clé XChaCha20-Poly1305 aléatoire.
  - sodium_crypto_auth — Calcule une étiquette pour le message
  - sodium_crypto_auth_keygen — Génère une clé aléatoire pour sodium_crypto_auth
  - sodium_crypto_auth_verify — Vérifie que l'étiquette est valide pour le message
  - sodium_crypto_box — Chiffrement asymétrique authentifié
  - sodium_crypto_box_keypair — Génère aléatoirement une clé secrète et une clé publique correspondante
  - sodium_crypto_box_keypair_from_secretkey_and_publickey — Créer une paire de clés unifiée à partir d'une clé secrète et d'une clé publique
  - sodium_crypto_box_open — Déchiffrement authentifié avec clé publique
  - sodium_crypto_box_publickey — Extrait la clé publique d'une paire de clés crypto_box
  - sodium_crypto_box_publickey_from_secretkey — Calcule la clé publique à partir d'une clé secrète
  - sodium_crypto_box_seal — Chiffrement anonyme avec clé publique
  - sodium_crypto_box_seal_open — Déchiffrement anonyme avec clé publique
  - sodium_crypto_box_secretkey — Extrait la clé secrète d'une paire de clés crypto_box
  - sodium_crypto_box_seed_keypair — Dérive de manière déterministe la paire de clés à partir d'une seule clé
  - sodium_crypto_core_ristretto255_add — Ajoute un élément
  - sodium_crypto_core_ristretto255_from_hash — Mappe un vecteur
  - sodium_crypto_core_ristretto255_is_valid_point — Détermine si un point est sur la courbe ristretto255
  - sodium_crypto_core_ristretto255_random — Génère une clé aléatoire
  - sodium_crypto_core_ristretto255_scalar_add — Ajoute une valeur scalaire
  - sodium_crypto_core_ristretto255_scalar_complement — Le but de sodium_crypto_core_ristretto255_scalar_complement
  - sodium_crypto_core_ristretto255_scalar_invert — Inverse une valeur scalaire
  - sodium_crypto_core_ristretto255_scalar_mul — Multiplie une valeur scalaire
  - sodium_crypto_core_ristretto255_scalar_negate — Inverse le signe d'une valeur scalaire
  - sodium_crypto_core_ristretto255_scalar_random — Génère une clé aléatoire
  - sodium_crypto_core_ristretto255_scalar_reduce — Réduit une valeur scalaire
  - sodium_crypto_core_ristretto255_scalar_sub — Soustrait une valeur scalaire
  - sodium_crypto_core_ristretto255_sub — Soustrait un élément
  - sodium_crypto_generichash — Renvoie un hachage du message
  - sodium_crypto_generichash_final — Complète le hachage
  - sodium_crypto_generichash_init — Initialise un hachage pour le streaming
  - sodium_crypto_generichash_keygen — Génère une clé de hachage générique aléatoire
  - sodium_crypto_generichash_update — Ajoute un message à un hachage
  - sodium_crypto_kdf_derive_from_key — Dérive une sous-clé
  - sodium_crypto_kdf_keygen — Génère une clé racine aléatoire pour l'interface KDF
  - sodium_crypto_kx_client_session_keys — Calcule les clés de session côté client.
  - sodium_crypto_kx_keypair — Créer une nouvelle paire de clés sodium
  - sodium_crypto_kx_publickey — Extrait la clé publique d'une paire de clés crypto_kx
  - sodium_crypto_kx_secretkey — Extrait la clé secrète d'une paire de clés crypto_kx
  - sodium_crypto_kx_seed_keypair — Description
  - sodium_crypto_kx_server_session_keys — Calcule les clés de session côté serveur.
  - sodium_crypto_pwhash — Dérive une clé à partir d'un mot de passe, en utilisant Argon2
  - sodium_crypto_pwhash_scryptsalsa208sha256 — Dérive une clé à partir d'un mot de passe, en utilisant scrypt
  - sodium_crypto_pwhash_scryptsalsa208sha256_str — Renvoie un hachage encodé en ASCII
  - sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Vérifie si le mot de passe correspond à une chaîne de hachage de mot de passe
  - sodium_crypto_pwhash_str — Renvoie un hachage encodé en ASCII
  - sodium_crypto_pwhash_str_needs_rehash — Détermine si un mot de passe doit être rehaché
  - sodium_crypto_pwhash_str_verify — Vérifie qu'un mot de passe correspond à un hachage
  - sodium_crypto_scalarmult — Calcule un secret partagé à partir d'une clé secrète et d'une clé publique
  - sodium_crypto_scalarmult_base — Alias de sodium_crypto_box_publickey_from_secretkey
  - sodium_crypto_scalarmult_ristretto255 — Calcule un secret partagé
  - sodium_crypto_scalarmult_ristretto255_base — Calcule la clé publique à partir d'une clé secrète
  - sodium_crypto_secretbox — Chiffrement authentifié avec une clé partagée
  - sodium_crypto_secretbox_keygen — Génère une clé aléatoire pour sodium_crypto_secretbox
  - sodium_crypto_secretbox_open — Déchiffrement authentifié avec une clé partagée
  - sodium_crypto_secretstream_xchacha20poly1305_init_pull — Initialise un contexte secretstream pour le déchiffrement
  - sodium_crypto_secretstream_xchacha20poly1305_init_push — Initialise un contexte secretstream pour le chiffrement
  - sodium_crypto_secretstream_xchacha20poly1305_keygen — Génère une clé secretstream aléatoire.
  - sodium_crypto_secretstream_xchacha20poly1305_pull — Déchiffre un morceau de données d'un flux chiffré
  - sodium_crypto_secretstream_xchacha20poly1305_push — Chiffre un morceau de données pour qu'il puisse être déchiffré dans une API de streaming
  - sodium_crypto_secretstream_xchacha20poly1305_rekey — Renouvelle explicitement la clé dans l'état secretstream
  - sodium_crypto_shorthash — Calcule un hachage court d'un message et d'une clé
  - sodium_crypto_shorthash_keygen — Renvoie des octets aléatoires pour la clé
  - sodium_crypto_sign — Signe un message
  - sodium_crypto_sign_detached — Signe le message
  - sodium_crypto_sign_ed25519_pk_to_curve25519 — Convertit une clé publique Ed25519 en une clé publique Curve25519
  - sodium_crypto_sign_ed25519_sk_to_curve25519 — Convertit une clé secrète Ed25519 en une clé secrète Curve25519
  - sodium_crypto_sign_keypair — Génère aléatoirement une clé secrète et une clé publique correspondante
  - sodium_crypto_sign_keypair_from_secretkey_and_publickey — Rassemble une clé secrète et une clé publique ensemble
  - sodium_crypto_sign_open — Vérifie que le message signé possède une signature valide
  - sodium_crypto_sign_publickey — Extrait la clé publique Ed25519 d'une paire de clés
  - sodium_crypto_sign_publickey_from_secretkey — Extrait la clé publique Ed25519 de la clé secrète
  - sodium_crypto_sign_secretkey — Extrait la clé secrète Ed25519 d'une paire de clés
  - sodium_crypto_sign_seed_keypair — Dérive de manière déterministe la paire de clés à partir d'une seule clé
  - sodium_crypto_sign_verify_detached — Vérifie la signature d'un message
  - sodium_crypto_stream — Génère une séquence d'octets déterministe à partir d'une graine
  - sodium_crypto_stream_keygen — Génère une clé de chiffrement aléatoire pour sodium_crypto_stream
  - sodium_crypto_stream_xchacha20 — Développe la clé et le nonce en un flux de clés de bytes pseudo-aléatoires
  - sodium_crypto_stream_xchacha20_keygen — Renvoie une clé aléatoire sécurisée
  - sodium_crypto_stream_xchacha20_xor — Chiffre une donnée en utilisant un nonce et une clé secrète (sans authentification)
  - sodium_crypto_stream_xchacha20_xor_ic — Chiffre un message en utilisant un nonce et une clé secrète (sans authentification)
  - sodium_crypto_stream_xor — Chiffre un message sans authentification
  - sodium_hex2bin — Décode une chaîne binaire encodée en hexadécimal
  - sodium_increment — Incrémente un grand nombre
  - sodium_memcmp — Teste l'égalité en temps constant
  - sodium_memzero — Écrase une chaîne avec des caractères NUL
  - sodium_pad — Ajoute des données de remplissage
  - sodium_unpad — Supprime les données de remplissage
- SodiumException — La classe SodiumException

# Xpass

# Introduction

Cette extension apporte des algorithmes de hachage de mots de passe utilisés par les distributions Linux, en utilisant la bibliothèque crypt étendue.

Elle fournit également des fonctions supplémentaires de libxcrypt manquantes dans PHP.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation via PECL

## Pré-requis

Cette extension nécessite » libxcrypt version 4.4 ou supérieure.

## Installation via PECL

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/xpass.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

L'extension Xpass fournit divers ensembles de constantes. Méthodes de hachage (`CRYPT_PREFIX_*`) pour le paramètre prefix de crypt_gensalt(). Codes d'erreur (`CRYPT_SALT_*`) retournés par crypt_checksalt(). Algorithmes de mot de passe (`PASSWORD_*`) pour le paramètre algo de password_hash().

Méthodes de hachage
`CRYPT_PREFIX_STD_DES` (string)
  La méthode de hachage originale de Unix V7, basée sur le chiffrement par bloc DES. Étant donné que DES est peu coûteux sur le matériel moderne, qu'il n'y a que `4096` sels possibles et 2**56 passphrases distinctes, qui sont tronquées à 8 caractères, il est possible de trouver n'importe quel mot de passe haché avec cette méthode. Elle ne devrait être utilisée que pour supporter les anciens systèmes d'exploitation qui ne supportent aucun autre algorithme de génération de hachage, en raison de la faiblesse des hachages DES.
`CRYPT_PREFIX_EXT_DES` (string)
  Une extension du DES traditionnel, qui élimine la limite de longueur, augmente la taille du sel et rend le coût temporel réglable. Elle provient de BSDI BSD/OS et est également disponible sur au moins NetBSD, OpenBSD et FreeBSD en raison de l'utilisation de la bibliothèque FreeSec de David Burren. Elle est bien meilleure que les hachages DES traditionnels et bigcrypt, mais ne devrait toujours pas être utilisée pour de nouveaux hachages.
`CRYPT_PREFIX_MD5` (string)
  Un hachage basé sur l'algorithme MD5, développé à l'origine par Poul-Henning Kamp pour FreeBSD. Supporté sur la plupart des Unix libres et les versions plus récentes de Solaris. Pas aussi faible que les hachages basés sur DES ci-dessous, mais MD5 est si peu coûteux sur le matériel moderne qu'il ne devrait pas être utilisé pour de nouveaux hachages. Le coût de traitement n'est pas ajustable.
`CRYPT_PREFIX_BLOWFISH` (string)
  Un hachage basé sur le chiffrement par bloc Blowfish, modifié pour avoir un calendrier de clés extra-coûteux. Développé à l'origine par Niels Provos et David Mazieres pour OpenBSD et également supporté sur les versions récentes de FreeBSD et NetBSD, sur Solaris 10 et plus récent, et sur plusieurs distributions GNU/*/Linux.
`CRYPT_PREFIX_SHA256` (string)
  Un hachage basé sur SHA-2 avec une sortie de 256 bits, développé à l'origine par Ulrich Drepper pour GNU libc. Supporté sur Linux mais pas courant ailleurs. Acceptable pour de nouveaux hachages. Le paramètre de coût de traitement par défaut est `5000`, ce qui est trop faible pour le matériel moderne.
`CRYPT_PREFIX_SHA512` (string)
  Un hachage basé sur SHA-2 avec une sortie de 512 bits, développé à l'origine par Ulrich Drepper pour GNU libc. Supporté sur Linux mais pas courant ailleurs. Acceptable pour de nouveaux hachages. Le paramètre de coût de traitement par défaut est `5000`, ce qui est trop faible pour le matériel moderne.
`CRYPT_PREFIX_SCRYPT` (string)
  Scrypt est une fonction de dérivation de clé basée sur un mot de passe créée par Colin Percival, à l'origine pour le service de sauvegarde en ligne Tarsnap. L'algorithme a été spécifiquement conçu pour rendre coûteux les attaques matérielles personnalisées à grande échelle en nécessitant de grandes quantités de mémoire. En 2016, l'algorithme scrypt a été publié par l'IETF en tant que RFC 7914.
`CRYPT_PREFIX_GOST_YESCRYPT` (string)
  Gost-yescrypt utilise la sortie de yescrypt comme message d'entrée pour HMAC avec la fonction de hachage GOST R 34.11-2012 (Streebog) avec un digest de 256 bits. Ainsi, les propriétés cryptographiques de yescrypt sont supplantées par celles de la fonction de hachage GOST. Cette méthode de hachage est utile dans les applications qui nécessitent un hachage de mot de passe moderne, mais doivent s'appuyer sur des algorithmes GOST. La fonction de hachage GOST R 34.11-2012 (Streebog) a été publiée par l'IETF en tant que RFC 6986. Acceptable pour de nouveaux hachages si nécessaire.
`CRYPT_PREFIX_YESCRYPT` (string)
  Yescrypt est un schéma de hachage de mot de passe évolutif conçu par Solar Designer, qui est basé sur le scrypt de Colin Percival. Bien que la force de yescrypt contre les attaques de devinettes de mot de passe provienne de sa conception d'algorithme, sa sécurité cryptographique est garantie par son utilisation de SHA-256 sur la couche externe. La fonction de hachage SHA-256 a été publiée par le NIST dans le FIPS PUB 180-2 (et ses révisions ultérieures telles que le FIPS PUB 180-4) et par l'IETF en tant que RFC 4634 (et par la suite RFC 6234). Recommandé pour de nouveaux hachages.
`CRYPT_PREFIX_SM3CRYPT` (string)
  Un hachage basé sur la fonction de hachage ShangMi 3 avec une sortie de 256 bits, qui utilise le même design que sha256crypt et/ou sha512crypt. Supporté sur EulerOS, Kylin, openEuler et openKylin, mais pas courant ailleurs. Acceptable pour de nouveaux hachages si nécessaire. Le paramètre de coût de traitement par défaut est 5000, ce qui est trop faible pour le matériel moderne. Disponible à partir de 1.2.0 avec libcxcrypt >= 4.5.0.
`CRYPT_PREFIX_SM3_YESCRYPT` (string)
  Sm3-yescrypt utilise la sortie de yescrypt comme message d'entrée pour HMAC avec la fonction de hachage ShangMi 3 avec un digest de 256 bits. Ainsi, les propriétés cryptographiques de yescrypt sont supplantées par celles de la fonction de hachage ShangMi 3. Cette méthode de hachage est utile dans les applications qui nécessitent un hachage de mot de passe moderne, mais doivent s'appuyer sur des algorithmes approuvés par le Bureau chinois de l'administration de la cryptographie commerciale d'État (OSCCA). La fonction de hachage ShangMi 3 a été publiée dans la partie 3 : "Fonctions de hachage dédiées" de la norme ISO/IEC 10118-3:2018. Acceptable pour de nouveaux hachages si nécessaire. Disponible à partir de 1.2.0 avec libcxcrypt >= 4.5.0.

Code d'erreur
`CRYPT_SALT_OK` (int)
  Pas d'erreur.
`CRYPT_SALT_INVALID` (int)
  Méthode de hachage inconnue ou paramètres invalides.
`CRYPT_SALT_METHOD_DISABLED` (int)
  Méthode de hachage n'est plus autorisée à être utilisée.
`CRYPT_SALT_METHOD_LEGACY` (int)
  Méthode de hachage n'est plus considérée comme suffisamment forte.
`CRYPT_SALT_TOO_CHEAP` (int)
  Coût des paramètres considéré comme trop faible.

Algorithme de mot de passe
`PASSWORD_SHA512` (string)
  `PASSWORD_SHA512` est utilisé pour créer de nouveaux hachages de mot de passe en utilisant l'algorithme `CRYPT_PREFIX_SHA512`.
`PASSWORD_YESCRYPT` (string)
  `PASSWORD_YESCRYPT` est utilisé pour créer de nouveaux hachages de mot de passe en utilisant l'algorithme `CRYPT_PREFIX_YESCRYPT`.
`PASSWORD_SM3CRYPT` (string)
  `PASSWORD_SM3CRYPT` est utilisé pour créer de nouveaux hachages de mot de passe en utilisant l'algorithme `CRYPT_PREFIX_SM3CRYPT`. Disponible à partir de 1.2.0 avec libcxcrypt >= 4.5.0.
`PASSWORD_SM3_YESCRYPT` (string)
  `PASSWORD_SM3_YESCRYPT` est utilisé pour créer de nouveaux hachages de mot de passe en utilisant l'algorithme `CRYPT_PREFIX_SM3_YESCRYPT`. Disponible à partir de 1.2.0 avec libcxcrypt >= 4.5.0.

# Fonctions Xpass

# crypt_checksalt

(PECL xpass >= 1.1.0)

crypt_checksalt — Valide un paramètre de hachage de mot de passe

### Description

function crypt_checksalt(string `$salt`): ?string

Vérifie si la chaîne de sel est conforme à la configuration système et signale si la méthode de hachage et les paramètres qu'elle spécifie sont acceptables. Il est destiné à être utilisé pour déterminer si le mot de passe de l'utilisateur doit être re-haché en utilisant la méthode de hachage actuellement préférée.

### Liste de paramètres

`salt`
  La chaîne de sel à vérifier.

### Valeurs de retour

Renvoie une des constantes `CRYPT_SALT_*` en tant qu'int.

### Exemples

Exemple #1 Un exemple de crypt_checksalt()

    <?php
    // Génère un sel pour une méthode obsolète
    $salt = crypt_gensalt(CRYPT_PREFIX_STD_DES);
    // Vérifie le sel
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_METHOD_LEGACY);

    // Génère un sel pour une méthode par défaut
    $salt = crypt_gensalt();
    // Vérifie le sel
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_OK);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)

### Voir aussi

- crypt_gensalt() - Compile une chaîne pour utilisation comme argument de sel pour crypt

# crypt_gensalt

(PECL xpass >= 1.1.0)

crypt_gensalt — Compile une chaîne pour utilisation comme argument de sel pour crypt

### Description

function crypt_gensalt(string `$prefix` = `null`, int `$count` = 0): ?string

Compile une chaîne pour utilisation comme argument de sel pour crypt().

### Liste de paramètres

`prefix`
  La méthode de hachage à utiliser. Une des constantes `CRYPT_PREFIX_*`. Si `null`, la meilleure méthode de hachage disponible sera sélectionnée.
`count`
  Contrôle le coût de traitement du hachage ; la plage valide et la signification exacte de count dépendent de la méthode de hachage, mais des nombres plus grands correspondent à des hachages plus coûteux en termes de temps CPU et éventuellement d'utilisation de mémoire. Si count est `0`, un coût par défaut faible sera sélectionné.

### Valeurs de retour

Renvoie une chaîne avec le paramètre, ou `null` en cas d'erreur.

### Exemples

Exemple #1 Un exemple de crypt_gensalt()

    <?php
    // Génère le sel
    $salt = crypt_gensalt(CRYPT_PREFIX_BLOWFISH);
    // Hash le mot de passe
    $hash = crypt("secret", $salt);
    // Vérifie le hachage
    $test = hash_equals(crypt("secret", $hash), $hash);
    var_dump($salt, $hash, $test);
    ?>

L'exemple ci-dessus va afficher :

    string(29) "$2y$05$GcPykP.Am8C1.dGamdpwW."
    string(60) "$2y$05$GcPykP.Am8C1.dGamdpwW.1RR.7uicWvJPZfJfCEizZHqVWwuaJLm"
    bool(true)

### Voir aussi

- crypt_preferred_method() - Renvoie le préfixe de la méthode de hachage préférée
- crypt() - Hachage à sens unique (indéchiffrable)
- hash_equals() - Comparaison de chaînes résistante aux attaques temporelles

# crypt_preferred_method

(PECL xpass >= 1.1.0)

crypt_preferred_method — Renvoie le préfixe de la méthode de hachage préférée

### Description

function crypt_preferred_method(): ?string

Renvoie le préfixe de la méthode de hachage préférée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une chaîne avec le préfixe, ou `null` en cas d'erreur.

### Exemples

Exemple #1 Un exemple de crypt_preferred_method()

    <?php
    var_dump(crypt_preferred_method());
    ?>

L'exemple ci-dessus va afficher :

    string(3) "$y$"

### Voir aussi

- crypt_gensalt() - Compile une chaîne pour utilisation comme argument de sel pour crypt

## Sommaire

- crypt_checksalt — Valide un paramètre de hachage de mot de passe
- crypt_gensalt — Compile une chaîne pour utilisation comme argument de sel pour crypt
- crypt_preferred_method — Renvoie le préfixe de la méthode de hachage préférée

- Installation/Configuration
  - Pré-requis
  - Installation via PECL
- Constantes pré-définies
- Fonctions Xpass
  - crypt_checksalt — Valide un paramètre de hachage de mot de passe
  - crypt_gensalt — Compile une chaîne pour utilisation comme argument de sel pour crypt
  - crypt_preferred_method — Renvoie le préfixe de la méthode de hachage préférée

- Hash — HASH Message Digest Framework
  - Installation/Configuration
  - Constantes pré-définies
  - HashContext — La classe HashContext
  - Fonctions Hash
- Mcrypt
  - Installation/Configuration
  - Constantes pré-définies
  - Chiffrements Mcrypt
  - Fonctions Mcrypt
- Mhash
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions Mhash
- OpenSSL
  - Installation/Configuration
  - Constantes pré-définies
  - Paramètres clés/certificats
  - Vérification de certificats
  - Fonctions OpenSSL
  - OpenSSLCertificate — La classe OpenSSLCertificate
  - OpenSSLCertificateSigningRequest — La classe OpenSSLCertificateSigningRequest
  - OpenSSLAsymmetricKey — La classe OpenSSLAsymmetricKey
- Hachage de mot de passe
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions de hachage de mot de passe
- Rnp
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions de Rnp
  - RnpFFI — La classe RnpFFI
- Sodium
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Sodium
  - SodiumException — La classe SodiumException
- Xpass
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Xpass

# Extensions sur les bases de données

# Interface d'abstraction

# Couche d'abstraction de base de données (style dbm)

# Introduction

Ces fonctions permettent l'accès aux bases de données du style Berkeley DB.

C'est une couche d'abstraction générale pour plusieurs bases de données, basées sur des fichiers. Raison pour laquelle les fonctionnalités sont limitées à des actions communes prises en charge par les bases de données modernes, comme » Oracle Berkeley DB.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Le comportement de certains aspects dépend de l'implémentation de la base de données sous-jacente. Les fonctions comme dba_optimize() et dba_sync() fonctionnent comme prévu pour une base de données, alors qu'elles peuvent ne rien faire sur d'autres. Il faut télécharger et installer les gestionnaires DBA supportés.

Liste des gestionnaires DBA
Gestionnaire | Notes
--- | ---
`dbm` | DBM est la plus ancienne (l'originale) des bases de données de style Berkeley DB. Il est recommandé d'éviter de l'utiliser si on en a le choix. Nous ne fournissons pas de support de la compatibilité des fonctions internes à DB2 et gdbm, car elles ne sont compatibles qu'au niveau source du code, mais ne peuvent pas gérer le format original DBM.
`ndbm` | Ndbm est un nouveau type et plus flexible que dbm. Il comporte néanmoins des limitations arbitraires de dbm (et par conséquent, il est obsolète).
`gdbm` | Gdbm est un » gestionnaire de bases de données GNU.
`db2` | » Oracle Berkeley DB 2. Il est décrit comme étant "un toolkit fournissant un support haute performance pour les bases de données, aussi bien du côté client que du côté serveur."
`db3` | » Oracle Berkeley DB 3.
`db4` | » Oracle Berkeley DB 4 ou 5. Cette option peut être utilisée avec BDB 5 à partir de PHP 5.3.3.
`cdb` | Cdb est un paquet rapide, léger et fiable pour créer et lire des bases de données constantes. Il a été créé par l'auteur de qmail et peut être trouvé sur » http://cr.yp.to/cdb.html. Vu qu'il est "constant", nous ne supporterons donc que les opérations de lecture. Nous supportons également l'écriture (et non la mise à jour) via la bibliothèque interne cdb.
`cdb_make` | Nous supportons l'écriture (et non la mise à jour) des fichiers cdb lorsque la bibliothèque cdb est utilisée.
`flatfile` | Ceci est disponible pour des raisons de compatibilité avec l'extension obsolète `dbm`. Cependant, il est possible de l'utiliser lorsque les fichiers ont été créés dans ce format. Survient lorsque la configuration n'a pas réussi à trouver de bibliothèque externe.
`inifile` | Ceci est disponible afin de permettre de modifier les fichiers php.ini depuis des scripts PHP. Lorsque l'on utilise des fichiers ini, il est possible de passer des tableaux de la forme (0=>groupe,1=>nom_valeur) ou des chaînes de la forme "[groupe]nom_valeur" où le groupe est optionnel. Sachant que les fonctions dba_firstkey() et dba_nextkey() retournent une chaîne de caractères représentant la clé, il y a une nouvelle fonction, dba_key_split(), qui permet de convertir les clés en tableaux sans perdre `false`.
`qdbm` | La bibliothèque qdbm peut être téléchargée depuis » http://fallabs.com/qdbm/index.html.
`tcadb` | La bibliothèque Tokyo Cabinet peut être téléchargée depuis » http://fallabs.com/tokyocabinet/.
`lmdb` | Disponible à partir de PHP 7.2.0. La bibliothèque Lightning Memory-Mapped Database peut être téléchargée depuis » https://symas.com/lmdb/.

Lorsque l'on appelle la fonction dba_open() ou la fonction dba_popen(), un des noms de gestionnaire doit être fourni comme argument. La liste des gestionnaires disponibles peut être affichée en utilisant la fonction phpinfo() ou la fonction dba_handlers().

## Installation

En utilisant l'option de compilation --enable-dba=shared, il est possible de compiler un module dynamique qui activera le support des bases de données de style DBM pour PHP. Il faut aussi ajouter le support d'au moins l'un des gestionnaires suivants, en spécifiant l'option de configuration --with-XXXX ou --enable-XXXX lors de la configuration de PHP.

Avertissement

Après avoir configuré et compilé PHP, il faut exécuter les tests suivants à partir de la ligne de commande : `php run-tests.php ext/dba`. Cela montre si la combinaison de pilotes fonctionne. Les plus problématiques sont `dbm` et `ndbm` qui entrent en conflit avec nombre d'installations. Ceci est dû au fait que sur de nombreux systèmes, ces bibliothèques font partie de plus d'une bibliothèque. Le test de configuration empêche juste de configurer des descripteurs dont la combinaison est défectueuse alors qu'ils fonctionnent correctement séparément.

Gestionnaires DBA supportés
Gestionnaire | Option de configuration
--- | ---
`dbm` | Pour activer le support de dbm, ajoutez l'option de compilation --with-dbm[=DIR]. Note: dbm est une surcouche qui aboutit souvent à des échecs. Ainsi, l'on ne doit utiliser dbm que si l'on est sûr qu'il fonctionne et que ce format est nécessaire.
`ndbm` | Pour activer le support de ndbm, ajoutez l'option de compilation --with-ndbm[=DIR]. Note: ndbm est une surcouche qui aboutit souvent à des échecs. Ainsi, l'on ne doit utiliser ndbm que si l'on est sûr qu'il fonctionne et que ce format est nécessaire.
`gdbm` | Pour activer le support de gdbm, ajoutez l'option de compilation --with-gdbm[=DIR].
`db2` | Pour activer le support d'Oracle Berkeley DB 2, ajoutez l'option de compilation --with-db2[=DIR]. Note: db2 entre en conflit avec db3 et db4.
`db3` | Pour activer le support d'Oracle Berkeley DB 3, ajoutez l'option de compilation --with-db3[=DIR]. Note: db3 entre en conflit avec db2 et db4.
`db4` | Pour activer le support d'Oracle Berkeley DB 4 ou 5, ajoutez l'option de compilation --with-db4[=DIR]. Note: db4 entre en conflit avec db2 et db3. Note: Les bibliothèques db avec des versions allant de 4.1 à 4.1.24 ne peuvent être utilisées avec aucune version de PHP. Le support de BDB 5 a été ajouté en PHP 5.3.3.
`cdb` | Pour activer le support de cdb, ajoutez l'option de compilation --with-cdb[=DIR]. Note: Il est possible d'omettre d'utiliser DIR, afin d'exploiter la bibliothèque cdb fournie avec PHP, qui ajoute un gestionnaire cdb_make, permet la création de fichiers cdb et permet l'accès aux fichiers cdb via le réseau avec les flux de PHP.
`flatfile` | Pour activer le support des fichiers, ajoutez l'option de compilation --enable-flatfile. Antérieurement à PHP 5.2.1, l'option --with-flatfile devait être utilisée à la place. Note: Ceci a été ajouté pour assurer la compatibilité avec l'extension `dbm` qui est obsolète. Utiliser ce gestionnaire seulement quand l'on ne peut installer aucun autre gestionnaire et qu'il n'est pas possible d'utiliser le gestionnaire cdb intégré.
`inifile` | Pour activer le support de `inifile`, ajoutez l'option de compilation --enable-inifile. Antérieurement à PHP 5.2.1, l'option --with-inifile devait être utilisée à la place. Note: Cette option a été ajoutée pour permettre de lire et écrire dans des fichiers d'initialisation de type Microsoft (.ini), comme le php.ini par exemple.
`qdbm` | Pour activer le support de qdbm, ajoutez l'option de compilation --with-qdbm[=DIR]. Note: qdbm entre en conflit avec dbm et gdbm. Note: La bibliothèque qdbm peut être téléchargée depuis » http://fallabs.com/qdbm/index.html.
`tcadb` | Pour activer le support de Tokyo Cabinet, ajoutez l'option de compilation --with-tcadb[=DIR]. Note: La bibliothèque Tokyo Cabinet peut être téléchargée depuis » http://fallabs.com/tokyocabinet/.
`lmdb` | Pour activer le support de Lightning Memory-Mapped Database, ajouter l'option de configuration --with-lmdb[=DIR]. Note: Ceci a été ajouté en PHP 7.2.0. La bibliothèque Lightning Memory-Mapped Database peut être téléchargée depuis » https://symas.com/lmdb/.

## Configuration à l'exécution

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

Options de configuration DBA
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
dba.default_handler | DBA_DEFAULT | `INI_ALL` |

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

`dba.default_handler` string
  Le nom du gestionnaire par défaut

## Types de ressources

Antérieurement à PHP 8.4.0, la plupart des fonctions DBA opèrent sur ou renvoient des ressources (par exemple, dba_open() renvoie un identifiant de lien DBA positif requis par la plupart des fonctions DBA).

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`DBA_LMDB_USE_SUB_DIR` (int)
  Drapeau du pilote LMDB pour permettre la création d'un sous-répertoire pour les fichiers de base de données. Disponible à partir de PHP 8.2.0.
`DBA_LMDB_NO_SUB_DIR` (int)
  Drapeau du pilote LMDB pour interdire la création d'un sous-répertoire pour les fichiers de base de données. Disponible à partir de PHP 8.2.0.

# Exemples

## Sommaire

- Utilisation

## Utilisation

Exemple #1 Exemple avec DBA

    <?php

    $id = dba_open("/tmp/test.db", "n", "db2");

    if (!$id) {
        echo "dba_open a échoué\n";
        exit;
    }

    dba_replace("key", "Ceci est un exemple !", $id);

    if (dba_exists("key", $id)) {
        echo dba_fetch("key", $id);
        dba_delete("key", $id);
    }

    dba_close($id);
    ?>

DBA gère les données binaires et n'a aucune limite arbitraire. Cependant, il hérite de toutes les limites définies par l'implémentation de la base de données accédée.

Toutes les bases de données se basant sur des fichiers doivent fournir une façon de définir le mode de fichier des nouvelles bases créées. Ce mode est passé généralement comme 4ème argument des fonctions dba_open() ou dba_popen().

Il est possible d'accéder à toutes les entrées de la base de données de façon linéaire, en utilisant les fonctions dba_firstkey() et dba_nextkey(). Il n'est pas possible de modifier la base de données lorsque l'on est en train de la lire.

Exemple #2 Lecture d'une base de données

    <?php

    // ...ouverture de la base de données...

    $key = dba_firstkey($id);

    while ($key !== false) {
        if (true) {          // on retient la clé pour effectuer d'autres actions plus tard
            $handle_later[] = $key;
        }
        $key = dba_nextkey($id);
    }

    foreach ($handle_later as $val) {
        dba_delete($val, $id);
    }

    ?>

# La classe Dba\Connection

(PHP 8 >= 8.4.0)

## Introduction

Une classe totalement opaque qui remplace une ressource `dba` à partir de PHP 8.4.0.

## Synopsis de la classe

namespace Dba;
final class Connection {
}

# Fonctions DBA

# dba_close

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_close — Ferme une base DBA

### Description

function dba_close(Dba\Connection `$dba`): void

dba_close() ferme la connexion établie avec la base de données et libère toutes les ressources associées.

### Liste de paramètres

`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.

### Voir aussi

- dba_open() - Ouvre une base de données DBA
- dba_popen() - Ouvre une connexion persistante à une base de données DBA

# dba_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_delete — Efface une ligne dans une base DBA

### Description

function dba_delete(string|array `$key`, Dba\Connection `$dba`): bool

dba_delete() efface l'entrée spécifiée par la clé `key`, dans la base identifiée par `dba`.

### Liste de paramètres

`key`
  La clé de l'entrée à effacer.
`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.

### Voir aussi

- dba_exists() - Vérifie qu'une clé DBA existe
- dba_fetch() - Lit les données liées à une clé DBA
- dba_insert() - Insère une entrée DBA
- dba_replace() - Remplace ou insère une ligne DBA

# dba_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_exists — Vérifie qu'une clé DBA existe

### Description

function dba_exists(string|array `$key`, Dba\Connection `$dba`): bool

dba_exists() vérifie si la clé `key` existe dans la base identifiée par `dba`.

### Liste de paramètres

`key`
  La clé à vérifier.
`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().

### Valeurs de retour

Retourne `true` si la clé existe, `false` sinon.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.

### Voir aussi

- dba_delete() - Efface une ligne dans une base DBA
- dba_fetch() - Lit les données liées à une clé DBA
- dba_insert() - Insère une entrée DBA
- dba_replace() - Remplace ou insère une ligne DBA

# dba_fetch

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_fetch — Lit les données liées à une clé DBA

### Description

function dba_fetch(string|array `$key`, Dba\Connection `$dba`, int `$skip` = 0): string|false

Signature surchargée obsolète à partir de 8.3.0 :

function dba_fetch(string|array `$key`, int `$skip`, resource `$dba`): string

dba_fetch() lit les données spécifiées par la clé `key` dans la base identifiée par `dba`.

### Liste de paramètres

`key`
  La clé correspondant aux données.

  > Note: Lorsque l'on travaille avec des fichiers .ini, cette fonction accepte des tableaux comme clés où l'index 0 est le groupe et l'index 1 est le nom de la valeur. Voir la fonction dba_key_split().

`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().
`skip`
  Le nombre de paires clé-valeur à ignorer lors de l'utilisation de bases de données cdb. Cette valeur est ignorée pour toutes les autres bases de données qui ne prennent pas en charge les clés multiples avec le même nom.

### Valeurs de retour

Retourne la chaîne associée si la paire clé/valeur est trouvée, `false` sinon.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.
8.3.0 | L'appel de dba_fetch() avec `dba` comme troisième argument est désormais obsolète.
8.2.0 | L'argument facultatif "skip" de la fonction dba_fetch() est maintenant placé à la fin, conformément à la sémantique PHP côté utilisateur. La signature précédemment surchargée est toujours acceptée mais déconseillée.

### Voir aussi

- dba_exists() - Vérifie qu'une clé DBA existe
- dba_delete() - Efface une ligne dans une base DBA
- dba_insert() - Insère une entrée DBA
- dba_replace() - Remplace ou insère une ligne DBA
- dba_key_split() - Transforme une représentation de clé DBA par chaîne en une représentation par tableau

# dba_firstkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_firstkey — Lit la première clé DBA

### Description

function dba_firstkey(Dba\Connection `$dba`): string|false

dba_firstkey() retourne la première clé de la base de données et réinitialise le pointeur interne de clé. Cela permet un parcours linéaire de toute la base.

### Liste de paramètres

`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().

### Valeurs de retour

Retourne la clé en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.

### Voir aussi

- dba_nextkey() - Lit la clé DBA suivante
- dba_key_split() - Transforme une représentation de clé DBA par chaîne en une représentation par tableau
- Exemple 2 dans les exemples DBA

# dba_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_handlers — Liste les gestionnaires DBA disponibles

### Description

function dba_handlers(bool `$full_info` = `false`): array

dba_handlers() retourne un tableau avec tous les gestionnaires supportés par cette extension.

### Liste de paramètres

`full_info`
  Active l'affichage de toutes les informations dans le résultat.

### Valeurs de retour

Retourne un tableau des gestionnaires de base de données. Si `full_info` est défini à `true`, le tableau sera associatif avec les noms des gestionnaires en tant que clés, et les informations de version en tant que valeurs. Sinon, le résultat sera un tableau indexé par les noms des gestionnaires.

> Note: Lorsque la bibliothèque interne cdb est utilisée, les gestionnaires `cdb` et `cdb_make` apparaîtront.

### Exemples

Exemple #1 Exemple avec dba_handlers()

    <?php

    echo "Gestionnaires DBA disponibles :\n";
    foreach (dba_handlers(true) as $handler_name => $handler_version) {
      // nettoyer les versions
      $handler_version = str_replace('$', '', $handler_version);
      echo " - $handler_name: $handler_version\n";
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Gestionnaires DBA disponibles :
     - cdb: 0.75, Revision: 1.3.2.3
     - cdb_make: 0.75, Revision: 1.2.2.4
     - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99)
     - inifile: 1.0, Revision: 1.6.2.3
     - flatfile: 1.0, Revision: 1.5.2.4

# dba_insert

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_insert — Insère une entrée DBA

### Description

function dba_insert(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_insert() insère l'entrée décrite par la clé `key` et la valeur `value` dans la base spécifiée par `dba`.

### Liste de paramètres

`key`
  La clé de l'entrée à insérer. Si cette clé existe déjà dans la base de données, cette fonction échouera. La fonction dba_replace() permet de remplacer une clé existante.
`value`
  La valeur à insérer.
`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.

### Voir aussi

- dba_exists() - Vérifie qu'une clé DBA existe
- dba_delete() - Efface une ligne dans une base DBA
- dba_fetch() - Lit les données liées à une clé DBA
- dba_replace() - Remplace ou insère une ligne DBA

# dba_key_split

(PHP 5, PHP 7, PHP 8)

dba_key_split — Transforme une représentation de clé DBA par chaîne en une représentation par tableau

### Description

function dba_key_split(string|false|null `$key`): array|false

dba_key_split() transforme une représentation de clé DBA par chaîne en une représentation par tableau.

### Liste de paramètres

`key`
  La clé sous forme de chaîne de caractères.

### Valeurs de retour

Retourne un tableau sous la forme `array(0 => group, 1 => nom_valeur)`. Cette fonction retourne `false` si `key` vaut `null` ou `false`.

### Historique

Version | Description
--- | ---
8.4.0 | Passer `null` ou `false` à `key` est désormais déprécié.

### Voir aussi

- dba_firstkey() - Lit la première clé DBA
- dba_nextkey() - Lit la clé DBA suivante
- dba_fetch() - Lit les données liées à une clé DBA

# dba_list

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_list — Liste tous les fichiers de bases de données DBA ouverts

### Description

function dba_list(): array

dba_list() liste tous les fichiers de bases de données DBA ouverts.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau associatif, sous la forme `idressource => nomfichier`.

# dba_nextkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_nextkey — Lit la clé DBA suivante

### Description

function dba_nextkey(Dba\Connection `$dba`): string|false

dba_nextkey() retourne la clé suivante de la base de données et avance le pointeur interne de clé.

### Liste de paramètres

`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().

### Valeurs de retour

Retourne la clé en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.

### Voir aussi

- dba_firstkey() - Lit la première clé DBA
- dba_key_split() - Transforme une représentation de clé DBA par chaîne en une représentation par tableau
- Exemple 2 dans les exemples DBA

# dba_open

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_open — Ouvre une base de données DBA

### Description

function dba_open(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_open() établit une connexion à la base identifiée par `path` avec le mode `mode` et l'identifiant `handler`.

### Liste de paramètres

`path`
  Chemin sur le système de fichiers.
`mode`
  Il vaut `r` pour lecture seule, `w` pour lecture/écriture, `c` pour lecture/écriture, et création si la base n'existe pas, et `n` pour création, écrasement et accès en lecture/écriture. La base de données est créée en mode BTree ; les autres modes (comme Hash ou Queue) ne sont pas supportés. De plus, il est possible de choisir la méthode de verrouillage de la base avec le caractère suivant. Il est possible d'utiliser `l` pour verrouiller la base avec un fichier .lck, ou `d` pour verrouiller la base elle-même. Il est important que les applications utilisent ces options de manière cohérente. Si l'on veut tester la possibilité d'accès, et ne pas attendre la disponibilité du verrou, il est possible d'ajouter la lettre `t` comme troisième caractère. Lorsque l'on est absolument certain que la base ne requiert pas de verrou, il est possible d'utiliser le tiret `-` à la place de `l` ou `d`. Lorsque l'on n'utilise ni `d`, ni `l` ni `-`, dba va verrouiller en mode `d`.

  > Note:

  > Il ne peut y avoir qu'un seul type d'écriture dans la base. Lorsque l'on utilise dba sur un serveur web, et que plusieurs requêtes HTTP effectuent des écritures, elles ne peuvent être faites que l'une après l'autre. De même, la lecture durant l'écriture n'est pas possible. L'extension dba utilise un verrou pour éviter ces problèmes. Voici la table de verrouillage :

  > Verrouillage DBA
  > déjà ouverte | `mode` = "rl" | `mode` = "rlt" | `mode` = "wl" | `mode` = "wlt" | `mode` = "rd" | `mode` = "rdt" | `mode` = "wd" | `mode` = "wdt"
  > --- | --- | --- | --- | --- | --- | --- | --- | ---
  > non-ouverte | ok | ok | ok | ok | ok | ok | ok | ok
  > `mode` = "rl" | ok | ok | attente | `false` | illégal | illégal | illégal | illégal
  > `mode` = "wl" | attente | `false` | attente | `false` | illégal | illégal | illégal | illégal
  > `mode` = "rd" | illégal | illégal | illégal | illégal | ok | ok | attente | `false`
  > `mode` = "wd" | illégal | illégal | illégal | illégal | attente | `false` | attente | `false`

  > - ok: Le second appel réussit.
  > - wait: Le second appel attend que dba_close() soit appelé par le premier script.
  > - false: Le second appel retourne `false`.
  > - illégal: il ne faut pas mélanger les options `"l"` et `"d"` pour le paramètre `mode`.

`handler`
  Le nom du gestionnaire qui doit être utilisé pour accéder à `path`. Tous les paramètres facultatifs donnés à dba_open() lui sont passés et il peut agir en leur nom. Si le paramètre `handler` est `null`, alors le gestionnaire par défaut est invoqué.
`permission`
  Paramètre facultatif de type entier qui est passé au pilote. Il a la même signification que le paramètre `permissions` de la fonction chmod(), et a une valeur par défaut de `0644`. Les pilotes `db1`, `db2`, `db3`, `db4`, `dbm`, `gdbm`, `ndbm` et `lmdb` prennent en charge le paramètre `permission`.
`map_size`
  Paramètre facultatif de type entier qui est passé au pilote. Sa valeur doit être un multiple de la taille de page du système d'exploitation, ou zéro pour utiliser la taille de mappage par défaut. Seul le pilote `lmdb` accepte le paramètre `map_size`.
`flags`
  Drapeaux à passer aux pilotes de base de données. Si `null`, les drapeaux par défaut seront fournis. Actuellement, seul le pilote LMDB prend en charge les drapeaux suivants : `DBA_LMDB_USE_SUB_DIR` et `DBA_LMDB_NO_SUB_DIR`.

### Valeurs de retour

Retourne une instance Dba\Connection en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

`false` est retourné et une erreur de niveau `E_WARNING` est émise lorsque le paramètre `handler` est `null`, mais qu'aucun gestionnaire par défaut n'est disponible.

### Historique

Version | Description
--- | ---
8.4.0 | Retourne désormais une instance de Dba\Connection; auparavant, une resource était retournée.
8.2.0 | Le paramètre `flags` est ajouté.
8.2.0 | Le paramètre `handler` est désormais nullable.
7.3.14, 7.4.2 | Le pilote `lmdb` supporte désormais un paramètre additionnel `map_size`.

### Voir aussi

- dba_popen() - Ouvre une connexion persistante à une base de données DBA
- dba_close() - Ferme une base DBA

# dba_optimize

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_optimize — Optimise une base DBA

### Description

function dba_optimize(Dba\Connection `$dba`): bool

dba_optimize() optimise la base de données identifiée par `dba`.

### Liste de paramètres

`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.

### Voir aussi

- dba_sync() - Synchronise une base de données DBA

# dba_popen

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_popen — Ouvre une connexion persistante à une base de données DBA

### Description

function dba_popen(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_popen() établit une connexion persistante à la base repérée par `path` avec le mode `mode`, en utilisant le gestionnaire `handler`.

### Liste de paramètres

`path`
  Chemin sur le système de fichiers.
`mode`
  Il vaut `r` pour lecture seule, `w` pour lecture/écriture, `c` pour lecture/écriture, et création si la base n'existe pas, et `n` pour création, écrasement, et accès en lecture/écriture.
`handler`
  Le nom du gestionnaire qui doit être utilisé pour accéder à `path`. Le gestionnaire reçoit tous les paramètres supplémentaires passés à la fonction dba_popen(). Si le paramètre `handler` est `null`, alors le gestionnaire par défaut est invoqué.
`permission`
  Paramètre optionnel de type entier (entier) qui est passé au pilote. Il a la même signification que le paramètre `permissions` de la fonction chmod(), et sa valeur par défaut est `0644`. Les pilotes `db1`, `db2`, `db3`, `db4`, `dbm`, `gdbm`, `ndbm` et `lmdb` prennent en charge le paramètre `permission`.
`map_size`
  Paramètre optionnel de type entier qui est passé au pilote. Sa valeur doit être un multiple de la taille de page du système d'exploitation, ou zéro pour utiliser la taille de mappage par défaut. Le pilote `lmdb` accepte le paramètre `map_size`.
`flags`
  Permet de passer des drapeaux aux pilotes de base de données. Actuellement, seul le pilote LMDB avec les drapeaux `DBA_LMDB_USE_SUB_DIR` et `DBA_LMDB_NO_SUB_DIR` est pris en charge.

### Valeurs de retour

Retourne une instance Dba\Connection en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

La valeur `false` est renvoyée et une erreur de niveau `E_WARNING` est émise lorsque le paramètre `handler` est `null`, mais qu'aucun gestionnaire par défaut n'est disponible.

### Historique

Version | Description
--- | ---
8.4.0 | Retourne désormais une instance de Dba\Connection; auparavant, une resource était retournée.
8.2.0 | Le paramètre `flags` a été ajouté.
8.1.0 | Le paramètre `handler` est désormais nullable.
7.3.14, 7.4.2 | Le pilote `lmdb` prend désormais en charge un paramètre additionnel `map_size`.

### Voir aussi

- dba_open() - Ouvre une base de données DBA
- dba_close() - Ferme une base DBA

# dba_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_replace — Remplace ou insère une ligne DBA

### Description

function dba_replace(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_replace() remplace ou insère une entrée, pour la clé `key` et avec la valeur `value` dans la base identifiée par `dba`.

### Liste de paramètres

`key`
  La clé de l'entrée à remplacer.
`value`
  La valeur utilisée pour le remplacement.
`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.

### Voir aussi

- dba_exists() - Vérifie qu'une clé DBA existe
- dba_delete() - Efface une ligne dans une base DBA
- dba_fetch() - Lit les données liées à une clé DBA
- dba_insert() - Insère une entrée DBA

# dba_sync

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_sync — Synchronise une base de données DBA

### Description

function dba_sync(Dba\Connection `$dba`): bool

dba_sync() synchronise la base de données. Si cela est pris en charge, cela déclenchera probablement une opération d'écriture physique sur le disque.

### Liste de paramètres

`dba`
  Une instance de Dba\Connection, renvoyée par dba_open() ou dba_popen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le paramètre `dba` attend désormais une instance de Dba\Connection; auparavant, une resource `dba` valide était attendue.

### Voir aussi

- dba_optimize() - Optimise une base DBA

## Sommaire

- dba_close — Ferme une base DBA
- dba_delete — Efface une ligne dans une base DBA
- dba_exists — Vérifie qu'une clé DBA existe
- dba_fetch — Lit les données liées à une clé DBA
- dba_firstkey — Lit la première clé DBA
- dba_handlers — Liste les gestionnaires DBA disponibles
- dba_insert — Insère une entrée DBA
- dba_key_split — Transforme une représentation de clé DBA par chaîne en une représentation par tableau
- dba_list — Liste tous les fichiers de bases de données DBA ouverts
- dba_nextkey — Lit la clé DBA suivante
- dba_open — Ouvre une base de données DBA
- dba_optimize — Optimise une base DBA
- dba_popen — Ouvre une connexion persistante à une base de données DBA
- dba_replace — Remplace ou insère une ligne DBA
- dba_sync — Synchronise une base de données DBA

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Exemples
  - Utilisation
- Dba\Connection — La classe Dba\Connection
- Fonctions DBA
  - dba_close — Ferme une base DBA
  - dba_delete — Efface une ligne dans une base DBA
  - dba_exists — Vérifie qu'une clé DBA existe
  - dba_fetch — Lit les données liées à une clé DBA
  - dba_firstkey — Lit la première clé DBA
  - dba_handlers — Liste les gestionnaires DBA disponibles
  - dba_insert — Insère une entrée DBA
  - dba_key_split — Transforme une représentation de clé DBA par chaîne en une représentation par tableau
  - dba_list — Liste tous les fichiers de bases de données DBA ouverts
  - dba_nextkey — Lit la clé DBA suivante
  - dba_open — Ouvre une base de données DBA
  - dba_optimize — Optimise une base DBA
  - dba_popen — Ouvre une connexion persistante à une base de données DBA
  - dba_replace — Remplace ou insère une ligne DBA
  - dba_sync — Synchronise une base de données DBA

# ODBC (Unifié)

# Introduction

En plus du support de l'ODBC normal, l'ODBC unifié de PHP donne accès à diverses bases de données qui ont emprunté la sémantique des API ODBC pour implémenter leur propre API. Au lieu de maintenir de multiples pilotes qui sont similaires, ces pilotes ont été rassemblés dans un jeu de fonctions ODBC uniques.

Les bases de données suivantes sont supportées par l'ODBC unifié : » Adabas D, » IBM DB2, » iODBC, » Solid, et » Sybase SQL Anywhere.

> Note: Mis à part pour IODBC, il n'y a pas d'ODBC utilisé lors des connexions aux bases de données ci-dessus. Les fonctions utilisées partagent les mêmes noms et syntaxes que les fonctions ODBC. L'exception à ceci est iODBC. En compilant PHP avec le support iODBC, il est possible d'utiliser n'importe quel pilote compatible ODBC avec les applications PHP. Plus d'informations sur iODBC, ainsi qu'un HOWTO (en anglais), sont disponibles sur » www.iodbc.org, ainsi que l'alternative unixODBC, disponible sur » www.unixodbc.org.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Pour accéder à l'une des bases de données supportées, il faut que les bibliothèques équivalentes soient installées.

## Installation

--with-adabas[=DIR]

  Inclut le support Adabas D. DIR est le dossier d'installation d'Adabas D. Par défaut, c'est /usr/local.

--with-sapdb[=DIR]

  Inclut le support SAP DB. DIR est le dossier d'installation de SAP DB. Par défaut, c'est /usr/local.

--with-solid[=DIR]

  Inclut le support Solid. DIR est le dossier d'installation de Solid. Par défaut, c'est /usr/local/solid.

--with-ibm-db2[=DIR]

  Inclut le support IBM DB2. DIR est le dossier d'installation de DB2. Par défaut, c'est /home/db2inst1/sqllib.

--with-empress[=DIR]

  Inclut le support Empress. DIR est le dossier d'installation de Empress. Par défaut, c'est $EMPRESSPATH. Cette option ne supporte que Empress Version 8.60 et plus récentes.

--with-empress-bcs[=DIR]

  Inclut le support `"Empress Local Access"`. DIR est le dossier d'installation de Empress. Par défaut, c'est $EMPRESSPATH. Cette option ne supporte que Empress version 8.60 et plus récentes.

--with-birdstep[=DIR]

  Inclut le support Birdstep. DIR est le dossier d'installation de Birdstep. Par défaut, c'est /usr/local/birdstep.

--with-custom-odbc[=DIR]

  Inclut le support d'un ODBC défini par l'utilisateur. DIR est le dossier d'installation d'ODBC. Par défaut, c'est /usr/local. Il faut s'assurer que la variable CUSTOM_ODBC_LIBS est définie, et que le fichier odbc.h est dans le chemin d'inclusion, c'est-à-dire qu'il est recommandé de définir les lignes suivantes pour `Sybase SQL Anywhere 5.5.00` sous QNX, avant d'utiliser le script de configuration :

         CPPFLAGS="-DODBC_QNX -DSQLANY_BUG"
         LDFLAGS=-lunix
         CUSTOM_ODBC_LIBS="-ldblib -lodbc".

--with-iodbc[=DIR]

  Inclut le support iODBC. DIR est le dossier d'installation d'iODBC. Par défaut, c'est /usr/local.

--with-esoob[=DIR]

  Inclut le support Easysoft OOB. DIR est le dossier d'installation de OOB. Par défaut, c'est /usr/local/easysoft/oob/client.

--with-unixodbc[=DIR]

  Inclut le support UnixODBC. DIR est le dossier d'installation d'UnixODBC. Par défaut, c'est /usr/local.

--with-openlink[=DIR]

  Inclut le support OpenLink ODBC. DIR est le dossier d'installation OpenLink. Par défaut, c'est /usr/local. C'est le même que pour iODBC.

--with-dbmaker[=DIR]

  Inclut le support DBMaker. DIR est le dossier d'installation DBMaker. Par défaut, c'est le chemin de la dernière installation de DBMaker (par exemple /home/dbmaker/3.6).

Les utilisateurs Windows doivent activer php_odbc.dll afin d'utiliser cette extension.

## Configuration à l'exécution

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

Options de configuration UODBC
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
odbc.allow_persistent | "1" | `INI_SYSTEM` |
odbc.check_persistent | "1" | `INI_SYSTEM` |
odbc.max_persistent | "-1" | `INI_SYSTEM` |
odbc.max_links | "-1" | `INI_SYSTEM` |
odbc.defaultlrl | "4096" | `INI_ALL` |
odbc.defaultbinmode | "1" | `INI_ALL` |
odbc.default_cursortype | "3" | `INI_ALL` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`odbc.default_db` string

  La source de données ODBC si aucune n'est spécifiée dans les fonctions odbc_connect() ou odbc_pconnect().

`odbc.default_user` string

  Nom d'utilisateur à utiliser si aucun n'est spécifié dans les fonctions odbc_connect() ou odbc_pconnect().

`odbc.default_pw` string

  Mot de passe à utiliser si aucun n'est spécifié dans les fonctions odbc_connect() ou odbc_pconnect().

`odbc.allow_persistent` bool

  Est-ce que les connexions ODBC persistantes sont autorisées ou pas ?

`odbc.check_persistent` bool

  Vérifie que la connexion est valide avant de l'utiliser.

`odbc.max_persistent` int

  Nombre maximum de connexions persistantes par processus.

`odbc.max_links` int

  Le nombre maximum de connexions ODBC par processus, y compris les connexions persistantes.

`odbc.defaultlrl` int

  Gestion des champs de type LONG. Spécifie le nombre d'octets retournés dans les variables. Voir odbc_longreadlen() pour plus d'information.

  Lorsqu'un entier est utilisé, sa valeur est mesurée en octets. Vous pouvez également utiliser la notation sténographique comme décrit dans cette entrée de la FAQ..
`odbc.defaultbinmode` int

  Gestion des données binaires. Voir odbc_binmode() pour plus d'information.

`odbc.default_cursortype` int

  Contrôle le modèle de curseur ODBC. Valeurs possibles : `SQL_CURSOR_FORWARD_ONLY`, `SQL_CURSOR_KEYSET_DRIVEN`, `SQL_CURSOR_DYNAMIC` et `SQL_CURSOR_STATIC` (par défaut).

## Types de ressources

Avant PHP 8.4.0, cette extension définissait deux types de ressources : un identifiant de connexion ODBC et un identifiant de résultat ODBC.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`ODBC_TYPE` (string)
`ODBC_BINMODE_PASSTHRU` (int)
`ODBC_BINMODE_RETURN` (int)
`ODBC_BINMODE_CONVERT` (int)
`SQL_ODBC_CURSORS` (int)
`SQL_CUR_USE_DRIVER` (int)
`SQL_CUR_USE_IF_NEEDED` (int)
`SQL_CUR_USE_ODBC` (int)
`SQL_CONCURRENCY` (int)
`SQL_CONCUR_READ_ONLY` (int)
`SQL_CONCUR_LOCK` (int)
`SQL_CONCUR_ROWVER` (int)
`SQL_CONCUR_VALUES` (int)
`SQL_CURSOR_TYPE` (int)
`SQL_CURSOR_FORWARD_ONLY` (int)
`SQL_CURSOR_KEYSET_DRIVEN` (int)
`SQL_CURSOR_DYNAMIC` (int)
`SQL_CURSOR_STATIC` (int)
`SQL_KEYSET_SIZE` (int)
`SQL_CHAR` (int)
`SQL_VARCHAR` (int)
`SQL_LONGVARCHAR` (int)
`SQL_WCHAR` (int)
  Chaîne de caractères Unicode de longueur fixe.
`SQL_WVARCHAR` (int)
  Chaîne de caractères Unicode de longueur variable.
`SQL_WLONGVARCHAR` (int)
  Données de caractères Unicode de longueur variable. La longueur maximale dépend de la source de données.
`SQL_DECIMAL` (int)
`SQL_NUMERIC` (int)
`SQL_BIT` (int)
`SQL_TINYINT` (int)
`SQL_SMALLINT` (int)
`SQL_INTEGER` (int)
`SQL_BIGINT` (int)
`SQL_REAL` (int)
`SQL_FLOAT` (int)
`SQL_DOUBLE` (int)
`SQL_BINARY` (int)
`SQL_VARBINARY` (int)
`SQL_LONGVARBINARY` (int)
`SQL_DATE` (int)
`SQL_TIME` (int)
`SQL_TIMESTAMP` (int)
`SQL_TYPE_DATE` (int)
`SQL_TYPE_TIME` (int)
`SQL_TYPE_TIMESTAMP` (int)
`SQL_BEST_ROWID` (int)
`SQL_ROWVER` (int)
`SQL_SCOPE_CURROW` (int)
`SQL_SCOPE_TRANSACTION` (int)
`SQL_SCOPE_SESSION` (int)
`SQL_NO_NULLS` (int)
`SQL_NULLABLE` (int)
`SQL_INDEX_UNIQUE` (int)
`SQL_INDEX_ALL` (int)
`SQL_ENSURE` (int)
`SQL_QUICK` (int)
`SQL_FETCH_FIRST` (int)
  Renvoie le premier jeu de lignes.
`SQL_FETCH_NEXT` (int)
  Renvoie le jeu de lignes suivant.

# Fonctions ODBC

# odbc_autocommit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_autocommit — Active le mode d'autovalidation

### Description

function odbc_autocommit(Odbc\Connection `$odbc`, ?bool `$enable` = `null`): int|bool

Sans le paramètre `enable`, odbc_autocommit() retourne le statut d'autovalidation

Par défaut, l'autovalidation est activée. Désactiver l'autovalidation est équivalent à démarrer une transaction.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`enable`

  Si `enable` vaut `true`, l'autovalidation est activée. S'il est `false`, l'autovalidation est désactivée. Si `null` est passé, cette fonction renvoie le statut d'autovalidation pour `odbc`.

### Valeurs de retour

Avec un paramètre `enable` égal à `null`, odbc_autocommit() retourne le statut d'autovalidation de la connexion `odbc`. Une valeur différente de 0 si le mode est activé, 0 s'il ne l'est pas, ou `false` si une erreur survient.

Si `enable` est non null, cette fonction retourne `true` en cas de succès, et `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.3.0 | `enable` est désormais nullable.

### Voir aussi

- odbc_commit() - Valide une transaction ODBC
- odbc_rollback() - Annule une transaction

# odbc_binmode

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_binmode — Modifie la gestion des colonnes de données binaires

### Description

function odbc_binmode(Odbc\Result `$statement`, int `$mode`): true

odbc_binmode() contrôle la gestion des colonnes de données binaires. Les types ODBC SQL affectés sont `BINARY`, `VARBINARY` et `LONGVARBINARY`. Le mode par défaut peut être défini en utilisant la directive php.ini uodbc.defaultbinmode

Lorsqu'une donnée SQL est convertie en caractère C, (`ODBC_BINMODE_CONVERT`) les 8 bits du caractère source sont représentés par deux caractères ASCII. Ces caractères sont des représentations ASCII des nombres au format hexadécimal. Par exemple, le binaire `00000001` est converti en `"01"` et le binaire `11111111` est converti en `"FF"`.

Alors que la gestion des colonnes `BINARY` et `VARBINARY` dépendent uniquement du binmode, la gestion des colonnes `LONGVARBINARY` dépend aussi de longreadlen, comme ceci :

Conversion des LONGVARBINARY
Mode | Longueur | Résultat
--- | --- | ---
`ODBC_BINMODE_PASSTHRU` | 0 | passthru
`ODBC_BINMODE_RETURN` | 0 | passthru
`ODBC_BINMODE_CONVERT` | 0 | passthru
`ODBC_BINMODE_PASSTHRU` | >0 | passthru
`ODBC_BINMODE_RETURN` | >0 | Tel quel
`ODBC_BINMODE_CONVERT` | >0 | Caractère

Si odbc_fetch_into() est utilisé, passthru signifie qu'une chaîne vide sera retournée pour ces colonnes. Si la fonction odbc_result() est utilisée, passthru signifie que les données sont envoyées directement au client (i.e. imprimées).

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`mode`

  Valeurs possibles pour le paramètre `mode` :

  - `ODBC_BINMODE_PASSTHRU` : retourner les données en binaire
  - `ODBC_BINMODE_RETURN` : retourner sans conversion
  - `ODBC_BINMODE_CONVERT` : convertir en caractère

  > Note: La gestion des colonnes de type binary long est aussi affectée par la fonction odbc_longreadlen().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

# odbc_close

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close — Ferme une connexion ODBC

### Description

function odbc_close(Odbc\Connection `$odbc`): void

Ferme la connexion avec la source de données représentée par l'identifiant de connexion `connection_id`.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.

### Notes

> Note:

> odbc_close() échouera s'il y a des transactions en cours sur cette connexion. Dans ce cas, la connexion restera ouverte.

# odbc_close_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close_all — Ferme toutes les connexions ODBC

### Description

function odbc_close_all(): void

odbc_close_all() ferme toutes les connexions ODBC à des sources de données.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Notes

> Note:

> odbc_close_all() échouera s'il y a des transactions en cours sur cette connexion. Dans ce cas, la connexion restera ouverte.

# odbc_columnprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columnprivileges — Liste les colonnes et leurs droits associés

### Description

function odbc_columnprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
string `$column`
): Odbc\Result|false

Liste les colonnes et leurs droits associés.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`catalog`

  Le catalogue ('calificatif' dans le jargon ODBC 2).

`schema`

  Le schéma ('propriétaire' dans le jargon ODBC 2). Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`table`

  Le nom de la table. Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`column`

  Le nom de la colonne. Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

### Valeurs de retour

Renvoie un objet de résultat ODBC ou `false` si une erreur survient. Cet objet résultat peut être utilisé pour récupérer une liste de colonnes et les droits associés.

Le jeu de résultat contient les colonnes suivantes :

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Les pilotes peuvent signaler des colonnes supplémentaires.

Le jeu de résultat est ordonné par `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `COLUMN_NAME` et `PRIVILEGE`.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.

### Exemples

Exemple #1 Lister les Privilèges pour une Colonne

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $privileges = odbc_columnprivileges($conn, 'TutorialDB', 'dbo', 'test', 'id');
    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => test
        [COLUMN_NAME] => id
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => INSERT
        [IS_GRANTABLE] => YES
    )

# odbc_columns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columns — Liste les colonnes d'une table

### Description

function odbc_columns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Liste les colonnes d'une table.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`catalog`

  Le catalogue ('calificatif' dans le jargon ODBC 2).

`schema`

  Le schéma ('propriétaire' dans le jargon ODBC 2). Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`table`

  Le nom de la table. Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`column`

  Le nom de la colonne. Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

### Valeurs de retour

Renvoie un objet de résultat ODBC ou `false` si une erreur survient.

Le jeu de résultat contient les colonnes suivantes :

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Les pilotes peuvent signaler des colonnes supplémentaires.

Le jeu de résultat est ordonné par `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` et `ORDINAL_POSITION`.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.0.0 | `schema`, `table` et `column` sont désormais nullables.

### Exemples

Exemple #1 Lister les Colonnes d'une Table

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $columns = odbc_columns($conn, 'TutorialDB', 'dbo', 'test', '%');
    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [DATA_TYPE] => 4
        [TYPE_NAME] => int
        [COLUMN_SIZE] => 10
        [BUFFER_LENGTH] => 4
        [DECIMAL_DIGITS] => 0
        [NUM_PREC_RADIX] => 10
        [NULLABLE] => 0
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => 4
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] =>
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => NO
    )

### Voir aussi

- odbc_columnprivileges() - Liste les colonnes et leurs droits associés
- odbc_procedurecolumns() - Liste les paramètres des procédures

# odbc_commit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_commit — Valide une transaction ODBC

### Description

function odbc_commit(Odbc\Connection `$odbc`): bool

Valide toutes les transactions en cours sur la connexion `connection_id`.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.

# odbc_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_connect — Connexion à une source

### Description

function odbc_connect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

L'identifiant de connexion retourné par cette fonction est nécessaire pour toutes les autres fonctions ODBC. Il est possible d'avoir de multiples connexions en même temps.

Avec certains pilotes ODBC, l'exécution de procédures enregistrées complexes peut produire l'erreur suivante : `"Cannot open a cursor on a stored procedure that has anything other than a single select statement in it"`, ce qui signifie : "Impossible de créer un pointeur de résultat dans une procédure enregistrée qui est réduite à une simple sélection (SELECT)". Utiliser l'option SQL_CUR_USE_ODBC peut permettre d'éviter cette erreur. De plus, certains pilotes ne supportent pas le paramètre optionnel de numéro de ligne dans odbc_fetch_row(). SQL_CUR_USE_ODBC peut aussi permettre de résoudre ces problèmes.

### Liste de paramètres

`dsn`

  Le nom source de la base de données (DSN), pour la connexion.

`user`

  Le nom d'utilisateur. Ce paramètre est ignoré si `dsn` contient `uid`. Pour une connexion sans spécifier un `user`, utiliser `null`.

`password`

  Le mot de passe. Ce paramètre est ignoré si `dsn` contient `pwd`. Pour une connexion sans spécifier un `password`, utiliser `null`.

`cursor_option`

  Fixe le type de pointeur de résultat utilisé pour cette connexion. Ce paramètre n'est généralement pas nécessaire, mais il peut être utile pour contourner certains problèmes ODBC.

  Les constantes suivantes sont définies comme types de pointeur :

  - SQL_CUR_USE_IF_NEEDED
  - SQL_CUR_USE_ODBC
  - SQL_CUR_USE_DRIVER

### Valeurs de retour

Retourne une connexion ODBC, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Connection; auparavant, un resource était retourné.
8.4.0 | `user` et `password` peuvent désormais être nuls, ils sont également optionnels et valent par défaut `null`.
8.4.0 | Auparavant, l'utilisation d'une chaîne vide pour `password` n'incluait pas `pwd` dans la chaîne de connexion générée pour `dsn`. Désormais, `pwd` est inclus dans la chaîne de connexion, avec pour valeur une chaîne vide. Pour rétablir le comportement précédent, `password` peut être défini sur `null`.
8.4.0 | Auparavant, si `dsn` contenait `uid` ou `pwd`, alors les paramètres `user` et `password` étaient ignorés. Désormais, `user` est uniquement ignoré si `dsn` contient `uid`, et `password` est uniquement ignoré si `dsn` contient `pwd`.

### Exemples

Exemple #1 Connexion sans DSN

    <?php
    // Microsoft SQL Server utilise le pilote SQL Native Client 10.0 ODBC Driver :
    // il permet les connexions à SQL 7, 2000, 2005 et 2008
    $connection = odbc_connect("Driver={SQL Server Native Client 10.0};Server=$server;Database=$database;", $user, $password);

    // Microsoft Access
    $connection = odbc_connect("Driver={Microsoft Access Driver (*.mdb)};Dbq=$mdbFilename", $user, $password);

    // Microsoft Excel
    $excelFile = realpath('C:/ExcelData.xls');
    $excelDir = dirname($excelFile);
    $connection = odbc_connect("Driver={Microsoft Excel Driver (*.xls)};DriverId=790;Dbq=$excelFile;DefaultDir=$excelDir" , '', '');
    ?>

### Voir aussi

- Pour les connexions persistantes : odbc_pconnect() - Ouvre une connexion persistante à une source de données

# odbc_connection_string_is_quoted

(PHP 8 >= 8.2.0)

odbc_connection_string_is_quoted — Détermine si une valeur de chaîne de caractères de connexion ODBC est entre guillemets

### Description

function odbc_connection_string_is_quoted(string `$str`): bool

Détermine si une chaîne de caractères est correctement entre guillemets pour une chaîne de caractères de connexion ODBC. La mise entre guillemets de chaîne de caractères de connexion ODBC est effectuée en utilisant des accolades, et les accolades de fin dans une chaîne doivent être échappées en les répétant deux fois, similaire à la mise entre guillemets SQL.

### Liste de paramètres

`str`

  La chaîne de caractères à vérifier pour la mise entre guillemets.

### Valeurs de retour

`true` si la chaîne est correctement entre guillemets, `false` sinon.

### Voir aussi

- odbc_connection_string_quote() - Met en guillemets une valeur de chaîne de caractères de connexion ODBC
- odbc_connection_string_should_quote() - Détermine si une valeur de chaîne de caractères de connexion ODBC doit être mise entre guillemets

# odbc_connection_string_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_quote — Met en guillemets une valeur de chaîne de caractères de connexion ODBC

### Description

function odbc_connection_string_quote(string `$str`): string

Met en guillemets une valeur de chaîne de caractères de connexion, selon les règles ODBC. C'est-à-dire, elle sera entourée de guillemets, et toute accolade de fin sera échappée. Cela devrait être fait pour toutes les valeurs de chaîne de caractères de connexion qui proviennent de l'entrée de l'utilisateur. Ne pas le faire peut entraîner des problèmes lors de l'analyse de la chaîne de connexion, ou des valeurs injectées dans la chaîne de connexion.

Il est à noter que cette fonction ne vérifie pas si la chaîne est déjà mise entre guillemets, ni si la chaîne a besoin d'être mise entre guillemets. Pour cela, appeler odbc_connection_string_is_quoted() et odbc_connection_string_should_quote().

### Liste de paramètres

`str`

  La chaîne de caractères sans guillemets.

### Valeurs de retour

Une chaîne de caractères, entourée de guillemets, et correctement échappée.

### Exemples

Exemple #1 odbc_connection_string_quote() example

Cet exemple met en guillemets une chaîne de caractères, puis la place dans une chaîne de connexion. Il est à noter que la chaîne est mise entre guillemets, et le caractère de guillemet de fin au milieu de la chaîne a été échappé.

    <?php
    $value = odbc_connection_string_quote("foo}bar");
    $connection_string = "DSN=PHP;UserValue=$value";
    echo $connection_string;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    DSN=PHP;UserValue={foo}}bar}

### Voir aussi

- odbc_connection_string_is_quoted() - Détermine si une valeur de chaîne de caractères de connexion ODBC est entre guillemets
- odbc_connection_string_should_quote() - Détermine si une valeur de chaîne de caractères de connexion ODBC doit être mise entre guillemets

# odbc_connection_string_should_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_should_quote — Détermine si une valeur de chaîne de caractères de connexion ODBC doit être mise entre guillemets

### Description

function odbc_connection_string_should_quote(string `$str`): bool

Détermine si une chaîne doit être mise entre guillemets pour une connexion ODBC. C'est-à-dire, si elle contient des caractères spéciaux.

Il est à noter que cette fonction ne vérifie pas si la chaîne est déjà mise entre guillemets; une chaîne déjà mise entre guillemets contiendra des caractères qui feront que cette fonction retourne vrai. Il est recommandé d'appeler odbc_connection_string_is_quoted() pour vérifier.

### Liste de paramètres

`str`

  La chaîne à vérifier.

### Valeurs de retour

`true` si la chaîne doit être entre guillemets sinon `false`.

### Voir aussi

- odbc_connection_string_quote() - Met en guillemets une valeur de chaîne de caractères de connexion ODBC
- odbc_connection_string_is_quoted() - Détermine si une valeur de chaîne de caractères de connexion ODBC est entre guillemets

# odbc_cursor

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_cursor — Lit le nom du pointeur de résultat courant

### Description

function odbc_cursor(Odbc\Result `$statement`): string|false

odbc_cursor() lit le nom du pointeur de résultat courant pour le résultat `result_id`.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

### Valeurs de retour

Retourne le nom du curseur, sous forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

# odbc_data_source

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

odbc_data_source — Retourne des informations sur les DSNs disponibles

### Description

function odbc_data_source(Odbc\Connection `$odbc`, int `$fetch_type`): array|null|false

Retourne une liste de DSN disponibles (après l'avoir appelée plusieurs fois).

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`fetch_type`

  Le paramètre `connection_id` est une connexion ODBC valide. Le paramètre `fetch_type` peut être l'une des deux constantes suivantes : `SQL_FETCH_FIRST` ou `SQL_FETCH_NEXT`. Utiliser `SQL_FETCH_FIRST` la première fois que la fonction est appelée, puis `SQL_FETCH_NEXT`.

### Valeurs de retour

Retourne `false` si une erreur survient, un tableau en cas de succès, et `null` après avoir récupéré le dernier DSN disponible.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.

### Exemples

Exemple #1 Lister les DSNs disponibles

    <?php
    $conn = odbc_connect('dsn', 'user', 'pass');
    $dsn_info = odbc_data_source($conn, SQL_FETCH_FIRST);
    while ($dsn_info) {
        print_r($dsn_info);
        $dsn_info = odbc_data_source($conn, SQL_FETCH_NEXT);
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [server] => dsn
        [description] => ODBC Driver 17 for SQL Server
    )
    Array
    (
        [server] => other_dsn
        [description] => Microsoft Access Driver (*.mdb, *.accdb)
    )

# odbc_do

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_do — Alias de odbc_exec()

### Description

Cette fonction est un alias de : odbc_exec().

# odbc_error

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_error — Lit le dernier code d'erreur

### Description

function odbc_error(?Odbc\Connection `$odbc` = `null`): string

Retourne un état ODBC sur 6 chiffres, ou une chaîne vide s'il n'y avait plus d'erreurs.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.

### Valeurs de retour

Si `odbc` est spécifié, le dernier état ODBC de cette connexion est retourné. Si `connection_id` est omis, c'est le dernier état de n'importe quelle connexion qui est retourné.

Cette fonction retourne une valeur significative uniquement si la dernière requête ODBC a échoué (i.e. la fonction odbc_exec() a retourné `false`).

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.0.0 | `odbc` est désormais nullable.

### Voir aussi

- odbc_errormsg() - Lit le dernier message d'erreur
- odbc_exec() - Exécute directement une requête SQL

# odbc_errormsg

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_errormsg — Lit le dernier message d'erreur

### Description

function odbc_errormsg(?Odbc\Connection `$odbc` = `null`): string

Retourne une chaîne contenant le dernier message d'erreur ODBC, ou une chaîne vide s'il n'y avait pas d'erreur.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.

### Valeurs de retour

Si `odbc` est spécifié, le dernier état ODBC de cette connexion est retourné.

Cette fonction retourne une valeur significative uniquement si la dernière requête ODBC a échoué (i.e. la fonction odbc_exec() a retourné `false`).

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.0.0 | `odbc` est désormais nullable.

### Voir aussi

- odbc_error() - Lit le dernier code d'erreur
- odbc_exec() - Exécute directement une requête SQL

# odbc_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_exec — Exécute directement une requête SQL

### Description

function odbc_exec(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

odbc_exec() envoie une commande SQL à la source de données ODBC, représentée par `odbc`.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`query`

  La requête SQL.

### Valeurs de retour

Renvoie un objet de résultat ODBC si la commande SQL a été exécutée avec succès `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.
8.0.0 | `flags` a été supprimé.

### Voir aussi

- odbc_prepare() - Prépare une commande pour l'exécution
- odbc_execute() - Exécute une requête SQL préparée

# odbc_execute

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_execute — Exécute une requête SQL préparée

### Description

function odbc_execute(Odbc\Result `$statement`, array `$params` = []): bool

Exécute une requête SQL préparée par odbc_prepare().

### Liste de paramètres

`statement`

  L’objet de résultat ODBC depuis odbc_prepare().

`params`

  Les valeurs du paramètre `params` seront substituées dans les variables de requêtes de la requête préparée. Les éléments de ce tableau seront convertis en chaînes de caractères en appelant cette fonction.

  Tout paramètre de `params` qui commence et termine par des guillemets simples sera considéré comme un nom de fichier à lire et envoyé à la base de données, avec la variable de requête appropriée.

  Pour stocker une chaîne de caractères qui commence et se finit réellement par des guillemets, il faut ajouter un espace au début ou à la fin de la chaîne, pour éviter que ce paramètre soit confondu avec un nom de fichier. Si ce n'est pas possible dans le cadre de l'application, il faudra passer par la fonction odbc_exec().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.
8.0.0 | Le paramètre `flags`, inutilisé, a été supprimé.

### Exemples

Exemple #1 Exemple avec odbc_execute() et odbc_prepare()

Dans le script suivant, $success ne sera possible que si les trois paramètres de `maproc` sont des paramètres de type IN :

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt    = odbc_prepare($conn, 'CALL maproc(?,?,?)');
    $success = odbc_execute($stmt, array($a, $b, $c));
    ?>

S'il faut appeler une procédure stockée en utilisant des paramètres INOUT ou OUT, la solution est d'utiliser une extension native de la base de données (par exemple pour oci8 pour Oracle).

### Voir aussi

- odbc_prepare() - Prépare une commande pour l'exécution

# odbc_fetch_array

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_array — Lit une ligne de résultat dans un tableau associatif

### Description

function odbc_fetch_array(Odbc\Result `$statement`, ?int `$row` = `null`): array|false

odbc_fetch_array() lit une ligne de résultat dans un tableau associatif depuis une requête ODBC.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC depuis odbc_exec().

`row`

  Le numéro de la ligne devant être lue, optionnel.

### Valeurs de retour

Retourne un tableau correspondant à la ligne récupérée, ou `false` s'il n'y a plus de ligne de disponible.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.
8.4.0 | `row` est désormais nullable.

### Notes

> Note: Cette fonction est disponible lorsque PHP est compilé avec le support IBM DB2 ou UnixODBC.

### Voir aussi

- odbc_fetch_row() - Lit une ligne de résultat
- odbc_fetch_object() - Lit une ligne de résultat dans un objet
- odbc_num_rows() - Nombre de lignes dans un résultat

# odbc_fetch_into

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_into — Lit une ligne de résultat, et la place dans un tableau

### Description

function odbc_fetch_into(Odbc\Result `$statement`, array `&$array`, ?int `$row` = `null`): int|false

Lit une ligne de résultat, et la place dans un tableau.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`array`

  Peut être de n'importe quel type, étant donné qu'il sera converti en tableau. Le tableau contiendra les valeurs des colonnes, ces dernières étant numérotées à partir de 0.

`row`

  Le numéro de la ligne.

### Valeurs de retour

Retourne le nombre de colonnes du résultat, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.
8.4.0 | `row` est désormais nullable.

### Exemples

Exemple #1 Exemple avec odbc_fetch_into()

    <?php
    $rc = odbc_fetch_into($res_id, $my_array);
    ?>

ou

    <?php
    $rc = odbc_fetch_into($res_id, $my_array, 2);
    ?>

# odbc_fetch_object

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_object — Lit une ligne de résultat dans un objet

### Description

function odbc_fetch_object(Odbc\Result `$statement`, ?int `$row` = `null`): stdClass|false

odbc_fetch_object() lit une ligne de résultat dans un objet depuis une requête ODBC.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC depuis odbc_exec().

`row`

  Le numéro de ligne à récupérer, en option.

### Valeurs de retour

Retourne un objet qui correspond à la ligne récupérée, ou `false` s'il n'y a plus de ligne de disponible.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.
8.4.0 | `row` est désormais nullable.

### Notes

> Note: Cette fonction est disponible lorsque PHP est compilé avec le support IBM DB2 ou UnixODBC.

### Voir aussi

- odbc_fetch_row() - Lit une ligne de résultat
- odbc_fetch_array() - Lit une ligne de résultat dans un tableau associatif
- odbc_num_rows() - Nombre de lignes dans un résultat

# odbc_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_row — Lit une ligne de résultat

### Description

function odbc_fetch_row(Odbc\Result `$statement`, ?int `$row` = `null`): bool

Lit une ligne dans le résultat identifié par `result_id` et retourné par odbc_do() ou odbc_exec(). Après odbc_fetch_row(), les champs seront accessibles avec la fonction odbc_result().

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`row`

  Si `row` est omis, `row` va tenter de lire la prochaine ligne dans le résultat. Des appels répétés à odbc_fetch_row() avec et sans paramètre `row` peuvent être combinés librement.

  Pour passer en revue toutes les lignes d'un résultat plusieurs fois, il est possible d'appeler odbc_fetch_row() avec row_number = 1, puis continuer à appeler odbc_fetch_row() sans le paramètre `row` pour passer en revue tout le résultat. Si un pilote ne supporte pas la lecture des lignes par numéro, le paramètre sera ignoré.

### Valeurs de retour

Retourne `true` si la ligne existe, `false` sinon.

### Erreurs / Exceptions

Un `E_WARNING` est émis lorsque `row` est égal ou inférieur à zéro.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.
8.4.0 | Un `E_WARNING` est maintenant émis lorsque `row` est égal ou inférieur à zéro.
8.0.0 | `row` est désormais nullable.

# odbc_field_len

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_len — Lit la longueur d'un champ

### Description

function odbc_field_len(Odbc\Result `$statement`, int `$field`): int|false

Lit la longueur du champ identifié par son numéro.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`field`

  Le numéro du champ. La numérotation commence à 1.

### Valeurs de retour

Retourne la longueur du champ ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

### Voir aussi

- odbc_field_scale() - Lit l'échelle d'un champ pour connaître l'échelle d'un nombre à virgule flottante

# odbc_field_name

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_name — Lit le nom de la colonne

### Description

function odbc_field_name(Odbc\Result `$statement`, int `$field`): string|false

Obtient le nom du champ occupant le numéro de colonne donné dans l'objet résultat spécifié.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`field`

  Le numéro de la colonne. La numérotation commence à 1.

### Valeurs de retour

Retourne le nom de la colonne, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

# odbc_field_num

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_num — Numéro de colonne

### Description

function odbc_field_num(Odbc\Result `$statement`, string `$field`): int|false

Obtient le numéro de la colonne correspondant au champ nommé dans l'objet résultat spécifié.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`field`

  Le nom du champ.

### Valeurs de retour

Retourne le numéro du champ, sous la forme d'un entier, ou `false` si une erreur survient. La numérotation commence à 1.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

# odbc_field_precision

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_precision — Alias de odbc_field_len()

### Description

Cette fonction est un alias de : odbc_field_len().

### Voir aussi

- odbc_field_scale() - Lit l'échelle d'un champ pour connaître l'échelle d'un nombre à virgule flottante.

# odbc_field_scale

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_scale — Lit l'échelle d'un champ

### Description

function odbc_field_scale(Odbc\Result `$statement`, int `$field`): int|false

Lit l'échelle du champ référencé par son numéro de champ `field_number` dans le résultat ODBC `result_id`.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`field`

  Le numéro du champ. La numérotation commence à 1.

### Valeurs de retour

Retourne l'échelle du champ, sous la forme d'un entier, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

# odbc_field_type

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_type — Type de données d'un champ

### Description

function odbc_field_type(Odbc\Result `$statement`, int `$field`): string|false

Lit le type de données SQL d'un champ, identifié par son numéro.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`field`

  Le numéro du champ. La numérotation commence à 1.

### Valeurs de retour

Retourne le type du champ, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

# odbc_foreignkeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_foreignkeys — Liste les clés étrangères

### Description

function odbc_foreignkeys(
Odbc\Connection `$odbc`,
?string `$pk_catalog`,
string `$pk_schema`,
string `$pk_table`,
string `$fk_catalog`,
string `$fk_schema`,
string `$fk_table`
): Odbc\Result|false

Liste les clés étrangères utilisées dans la table `pk_table`.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`pk_catalog`

  Le catalogue ('qualifier' en terminologie ODBC 2) de la clé primaire de table.

`pk_schema`

  Le schéma ('qualifier' en terminologie ODBC 2) de la clé primaire de table.

`pk_table`

  La table de clé primaire.

`fk_catalog`

  Le catalogue ('qualifier' en terminologie ODBC 2) de la clé étrangère de table.

`fk_schema`

  Le schéma ('qualifier' en terminologie ODBC 2) de la clé étrangère de table.

`fk_table`

  La table de clé étrangère.

### Valeurs de retour

Renvoie un objet de résultat ODBC ou `false` si une erreur survient.

Le jeu de résultat contient les colonnes suivantes :

- `PKTABLE_CAT`
- `PKTABLE_SCHEM`
- `PKTABLE_NAME`
- `PKCOLUMN_NAME`
- `FKTABLE_CAT`
- `FKTABLE_SCHEM`
- `FKTABLE_NAME`
- `FKCOLUMN_NAME`
- `KEY_SEQ`
- `UPDATE_RULE`
- `DELETE_RULE`
- `FK_NAME`
- `PK_NAME`
- `DEFERRABILITY`

Les pilotes peuvent signaler des colonnes supplémentaires.

Si les clés étrangères associées avec une clé primaire sont demandées, le jeu de résultat est ordonné par `FKTABLE_CAT`, `FKTABLE_SCHEM`, `FKTABLE_NAME` et `KEY_SEQ`. Si les clés primaires associées avec une clé étrangère sont demandées, le jeu de résultat est ordonné par `PKTABLE_CAT`, `PKTABLE_SCHEM`, `PKTABLE_NAME` et `KEY_SEQ`.

Si `pk_table` contient un nom de table, odbc_foreignkeys() retourne la clé primaire de la table `pk_table`, et toutes les clés étrangères qui y font référence.

Si `fk_table` contient un nom de table, odbc_foreignkeys() retourne la liste des clés étrangères de la table `fk_table`, et les clés primaires (d'autres tables) qui y font référence.

Si `pk_table` et `fk_table` contiennent des noms de tables, odbc_foreignkeys() retourne la liste des clés étrangères de la table `fk_table` qui utilisent la clé primaire de la table `pk_table`. Cette liste devrait ne contenir qu'une clé au mieux.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.

### Voir aussi

- odbc_tables() - Liste les tables d'une source
- odbc_primarykeys() - Liste les colonnes utilisées dans une clé primaire

# odbc_free_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_free_result — Libére les objets associés à un résultat

### Description

function odbc_free_result(Odbc\Result `$statement`): true

Libère les objets associés à un résultat.

odbc_free_result() n'est nécessaire que lorsqu'il y a un risque d'utiliser trop de mémoire lors de l'exécution du script. Tous les résultats en mémoire seront libérés dès la fin du script.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

### Notes

> Note:

> Si l'autovalidation est désactivée (voir odbc_autocommit()) et que l'on appelle odbc_free_result() avant de valider les requêtes, toutes les transactions préparées seront annulées.

# odbc_gettypeinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_gettypeinfo — Liste les types de données supportés par une source

### Description

function odbc_gettypeinfo(Odbc\Connection `$odbc`, int `$data_type` = 0): Odbc\Result|false

Liste les types de données supportés par une source.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`data_type`

  Peut être utilisé pour restreindre les informations à un seul type de données.

### Valeurs de retour

Renvoie un objet de résultat ODBC ou `false` si une erreur survient.

Le résultat possède les colonnes suivantes :

- TYPE_NAME
- DATA_TYPE
- PRECISION
- LITERAL_PREFIX
- LITERAL_SUFFIX
- CREATE_PARAMS
- NULLABLE
- CASE_SENSITIVE
- SEARCHABLE
- UNSIGNED_ATTRIBUTE
- MONEY
- AUTO_INCREMENT
- LOCAL_TYPE_NAME
- MINIMUM_SCALE
- MAXIMUM_SCALE

Le résultat est ordonné par DATA_TYPE et TYPE_NAME.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.

# odbc_longreadlen

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_longreadlen — Gestion des colonnes de type LONG

### Description

function odbc_longreadlen(Odbc\Result `$statement`, int `$length`): true

Active la gestion des colonnes de type `LONG` et `LONGVARCHAR` et `LONGVARBINARY`. La longueur par défaut peut être définie en utilisant la directive php.ini uodbc.defaultlrl

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`length`

  Le nombre d'octets retourné à PHP. S'il est défini à `0`, les données des colonnes de type LONG sont passées au client (i.e. imprimées) lorsqu'elles sont récupérées avec la fonction odbc_result().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

### Notes

> Note:

> La gestion des types `LONGVARBINARY` est aussi affectée par odbc_binmode().

# odbc_next_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_next_result — Vérifie si plusieurs résultats sont disponibles

### Description

function odbc_next_result(Odbc\Result `$statement`): bool

Vérifie s'il y a plus de jeux de résultats de disponibles accessibles via les fonctions odbc_fetch_array(), odbc_fetch_row(), odbc_result(), etc.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

### Valeurs de retour

Retourne `true` s'il y a plus de jeux de résultats, `false` sinon.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

### Exemples

Exemple #1 Exemple avec odbc_next_result()

    <?php
    $r_Connection = odbc_connect($dsn, $username, $password);

    $s_SQL = <<<END_SQL
    SELECT 'A'
    SELECT 'B'
    SELECT 'C'
    END_SQL;

    $r_Results = odbc_exec($r_Connection, $s_SQL);

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Affiche le premier jeu de résultats : ";
    var_dump($a_Row1, $a_Row2);

    echo "Récupération du second jeu de résultats : ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Affiche le second jeu de résultats : ";
    var_dump($a_Row1, $a_Row2);

    echo "Récupération du troisième jeu de résultats : ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Affiche le troisième jeu de résultats : ";
    var_dump($a_Row1, $a_Row2);

    echo "Tente de récupérer un quatrième jeu de résultats : ";
    var_dump(odbc_next_result($r_Results));
    ?>

L'exemple ci-dessus va afficher :

    Affiche le premier jeu de résultats : array(1) {
      ["A"]=>
      string(1) "A"
    }
    bool(false)
    Récupération du second jeu de résultats :bool(true)
    Affiche le second jeu de résultats : array(1) {
      ["B"]=>
      string(1) "B"
    }
    bool(false)
    Récupération du troisième jeu de résultats : bool(true)
    Affiche le troisième jeu de résultats : array(1) {
      ["C"]=>
      string(1) "C"
    }
    bool(false)
    Tente de récupérer un quatrième jeu de résultats : bool(false)

# odbc_num_fields

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_fields — Nombre de colonnes dans un résultat

### Description

function odbc_num_fields(Odbc\Result `$statement`): int

Récupère le nombre de colonnes dans un résultat ODBC.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC retourné par la fonction odbc_exec().

### Valeurs de retour

Retourne le nombre de colonnes, ou -1 si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

# odbc_num_rows

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_rows — Nombre de lignes dans un résultat

### Description

function odbc_num_rows(Odbc\Result `$statement`): int

Lit le nombre de lignes dans un résultat. Pour les commandes INSERT, UPDATE et DELETE, odbc_num_rows() retourne le nombre de lignes affectées. Pour les commandes SELECT, cela PEUT être le nombre de lignes disponibles, mais ce n'est pas certain.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC retourné par la fonction odbc_exec().

### Valeurs de retour

Retourne le nombre de lignes dans le résultat ODBC. Cette fonction retournera -1 si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

### Notes

> Note:

> L'utilisation de la fonction odbc_num_rows() pour déterminer le nombre de lignes disponible après un SELECT retournera -1 avec la plupart des pilotes.

# odbc_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_pconnect — Ouvre une connexion persistante à une source de données

### Description

function odbc_pconnect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

Ouvre une connexion persistante à une source de données.

odbc_pconnect() se comporte de manière similaire à odbc_connect(), mais la connexion ouverte n'est pas vraiment terminée lorsque le script est achevé. Les prochaines requêtes qui se feront sur une connexion dont les `dsn`, `user`, `password` sont les mêmes que celle-ci (avec odbc_connect() et odbc_pconnect()) réutiliseront la connexion ouverte.

### Liste de paramètres

Voir la fonction odbc_connect() pour plus de détails.

### Valeurs de retour

Retourne une connexion ODBC, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Connection; auparavant, un resource était retourné.
8.4.0 | `user` et `password` peuvent désormais être nuls, ils sont également optionnels et valent par défaut `null`.
8.4.0 | Auparavant, l'utilisation d'une chaîne vide pour `password` n'incluait pas `pwd` dans la chaîne de connexion générée pour `dsn`. Désormais, `pwd` est inclus dans la chaîne de connexion, avec pour valeur une chaîne vide. Pour rétablir le comportement précédent, `password` peut être défini sur `null`.
8.4.0 | Auparavant, si `dsn` contenait `uid` ou `pwd`, alors les paramètres `user` et `password` étaient ignorés. Désormais, `user` est uniquement ignoré si `dsn` contient `uid`, et `password` est uniquement ignoré si `dsn` contient `pwd`.

### Notes

> Note: Les connexions persistantes n'ont aucun effet si PHP est utilisé comme CGI.

### Voir aussi

- odbc_connect() - Connexion à une source
- Les connexions persistantes aux bases de données

# odbc_prepare

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_prepare — Prépare une commande pour l'exécution

### Description

function odbc_prepare(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Prépare une commande pour l'exécution. L’objet de résultat ODBC peut être utilisé plus tard pour exécuter la commande avec odbc_execute().

Quelques bases de données (comme IBM DB2, MS SQL Server et Oracle) supportent les procédures stockées qui acceptent les types de paramètres IN, INOUT et OUT comme définis dans les spécifications ODBC. Cependant, le driver unifié ODBC supporte actuellement uniquement le type de paramètres IN pour les procédures stockées.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`query`

  La requête à préparer.

### Valeurs de retour

Renvoie un objet de résultat ODBC si la commande SQL a été préparée avec succès. Retourne `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.

### Exemples

Exemple #1 Exemple avec odbc_prepare() et odbc_execute()

Dans le code suivant, $res ne sera valide uniquement si les trois paramètres pour `myproc` sont des paramètres IN :

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $res  = odbc_execute($stmt, array($a, $b, $c));
    ?>

S'il faut appeler une procédure stockée utilisant des paramètres INOUT ou OUT, il est recommandé d'utiliser l'extension native de la base de données (par exemple oci8 pour Oracle).

### Voir aussi

- odbc_execute() - Exécute une requête SQL préparée

# odbc_primarykeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_primarykeys — Liste les colonnes utilisées dans une clé primaire

### Description

function odbc_primarykeys(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Retourne un objet résultat pouvant être utilisé pour récupérer les noms des colonnes qui composent la clé primaire d'une table.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`catalog`

  Le catalogue ('calificatif' dans le jargon ODBC 2).

`schema`

  Le schéma ('propriétaire' dans le jargon ODBC 2).

`table`

### Valeurs de retour

Renvoie un objet de résultat ODBC ou `false` si une erreur survient.

Le jeu de résultat contient les colonnes suivantes :

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `KEY_SEQ`
- `PK_NAME`

Les pilotes peuvent signaler des colonnes supplémentaires.

Le jeu de résultat est ordonné par `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` et `KEY_SEQ`.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.

### Exemples

Exemple #1 Lister les Clés primaires d'une Colonne

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $primarykeys = odbc_primarykeys($conn, 'TutorialDB', 'dbo', 'TEST');
    while (($row = odbc_fetch_array($primarykeys))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [KEY_SEQ] => 1
        [PK_NAME] => PK__TEST__3213E83FE141F843
    )

### Voir aussi

- odbc_tables() - Liste les tables d'une source
- odbc_foreignkeys() - Liste les clés étrangères

# odbc_procedurecolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedurecolumns — Liste les paramètres des procédures

### Description

function odbc_procedurecolumns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Liste les paramètres des procédures.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`catalog`

  Le catalogue ('calificatif' dans le jargon ODBC 2).

`schema`

  Le schéma ('propriétaire' dans le jargon ODBC 2). Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`procedure`

  La procédure. Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`column`

  La colonne. Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

### Valeurs de retour

Retourne les paramètres d'entrée et de sortie, ainsi que les colonnes utilisées dans les procédures désignées par les paramètres. Renvoie un objet de résultat ODBC ou `false` si une erreur survient.

Le jeu de résultat contient les colonnes suivantes :

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `COLUMN_NAME`
- `COLUMN_TYPE`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Les pilotes peuvent signaler des colonnes supplémentaires.

Le jeu de résultat est ordonné par `PROCEDURE_CAT`, `PROCEDURE_SCHEM`, `PROCEDURE_NAME` et `COLUMN_TYPE`.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.
8.0.0 | Avant cette version, la fonction ne pouvait être appelée qu'avec un ou cinq arguments.

### Exemples

Exemple #1 Liste les Colonnes d'une Procédure Stockée

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $columns = odbc_procedurecolumns($conn, 'TutorialDB', 'dbo', 'GetEmployeeSalesYTD;1', '%');
    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [COLUMN_NAME] => @SalesPerson
        [COLUMN_TYPE] => 1
        [DATA_TYPE] => -9
        [TYPE_NAME] => nvarchar
        [COLUMN_SIZE] => 50
        [BUFFER_LENGTH] => 100
        [DECIMAL_DIGITS] =>
        [NUM_PREC_RADIX] =>
        [NULLABLE] => 1
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => -9
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] => 100
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => YES
    )

### Voir aussi

- odbc_columns() - Liste les colonnes d'une table

# odbc_procedures

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedures — Liste les procédures stockées

### Description

function odbc_procedures(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`
): Odbc\Result|false

Liste les procédures stockées.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`catalog`

  Le catalogue ('calificatif' dans le jargon ODBC 2).

`schema`

  Le schéma ('propriétaire' dans le jargon ODBC 2). Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`procedure`

  Le nom. Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

### Valeurs de retour

Renvoie un objet de résultat ODBC contenant les informations ou `false` si une erreur survient.

Le jeu de résultat contient les colonnes suivantes :

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `NUM_INPUT_PARAMS`
- `NUM_OUTPUT_PARAMS`
- `NUM_RESULT_SETS`
- `REMARKS`
- `PROCEDURE_TYPE`

Les pilotes peuvent signaler des colonnes supplémentaires.

Le jeu de résultat est ordonné par `PROCEDURE_CAT`, `PROCEDURE_SCHEMA` et `PROCEDURE_NAME`.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.
8.0.0 | Avant cette version, la fonction ne pouvait être appelée qu'avec un ou quatre arguments.

### Exemples

Exemple #1 Liste les Procédures stockées d'une Base de Données

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $procedures = odbc_procedures($conn, $catalog, $schema, '%');
    while (($row = odbc_fetch_array($procedures))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [NUM_INPUT_PARAMS] => -1
        [NUM_OUTPUT_PARAMS] => -1
        [NUM_RESULT_SETS] => -1
        [REMARKS] =>
        [PROCEDURE_TYPE] => 2
    )

### Voir aussi

- odbc_procedurecolumns() - Liste les paramètres des procédures
- odbc_tables() - Liste les tables d'une source

# odbc_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result — Lit un champ de résultat UODBC

### Description

function odbc_result(Odbc\Result `$statement`, string|int `$field`): string|bool|null

Lit un champ de résultat UODBC.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`field`

  Le nom du champ à récupérer. Peut être aussi bien un entier, contenant le numéro de colonne du champ, dans le résultat, ou bien une chaîne de caractères, qui représente le nom du champ.

### Valeurs de retour

Retourne le contenu du champ, `false` si une erreur survient, `null` pour les données NULL, ou `true` pour des données binaires.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.

### Exemples

Le premier appel à odbc_result() retourne la valeur du troisième champ de la ligne courante du résultat `result_id`. Le deuxième appel à odbc_result() retourne la valeur du champ dont le nom est "val" de la ligne courante du résultat `result_id`. Une erreur survient si le paramètre de colonne est inférieur à 1, ou dépasse le nombre de colonnes du résultat. De la même manière, une erreur survient si le nom du champ passé ne correspond à aucun champ dans le résultat.

Exemple #1 Exemple avec odbc_result()

    <?php
    $item_3   = odbc_result($Query_ID, 3);
    $item_val = odbc_result($Query_ID, "val");
    ?>

### Notes

Les index de champs commencent à 1. Pour plus d'informations sur la façon de lire des colonnes de type binaire ou long, se reporter à odbc_binmode() et odbc_longreadlen().

# odbc_result_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result_all — Affiche le résultat sous la forme d'une table HTML

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function odbc_result_all(Odbc\Result `$statement`, string `$format` = ""): int|false

Affiche toutes les lignes d'un résultat. L'affichage se fait au format HTML. Les données ne sont pas échappées.

Cette fonction n'est pas supposée être utilisée en environnement de production ; elle est prévue pour le développement pour afficher rapidement un jeu de résultats.

### Liste de paramètres

`statement`

  L’objet de résultat ODBC.

`format`

  Permet de modifier l'aspect global de la table.

### Valeurs de retour

Retourne le nombre de lignes du résultat, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `statement` attend désormais une instance de Odbc\Result; auparavant, un resource était attendu.
8.1.0 | Cette fonction a été rendue obsolète.

# odbc_rollback

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_rollback — Annule une transaction

### Description

function odbc_rollback(Odbc\Connection `$odbc`): bool

Annule toutes les transactions sur la connexion `connection_id`.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.

# odbc_setoption

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_setoption — Modifie les paramètres ODBC

### Description

function odbc_setoption(
Odbc\Connection|Odbc\Result `$odbc`,
int `$which`,
int `$option`,
int `$value`
): bool

odbc_setoption() donne accès aux options ODBC pour une connexion particulière ou un résultat de requête. Elle a été écrite pour aider à la résolution de problèmes liés aux pilotes ODBC récalcitrants. Il sera sûrement à utiliser odbc_setoption() en tant que programmeur ODBC comprenant les divers effets des options disponibles. Il sera aussi besoin d'un bon manuel de référence pour comprendre les options et leur usage. Différentes versions de pilotes supportent différentes versions d'options.

Étant donné que les effets peuvent varier d'un pilote à l'autre, l'utilisation de odbc_setoption() dans des scripts voués à être livrés au public est très fortement déconseillée. De plus, certaines options ODBC ne sont pas disponibles car elles doivent être fixées avant l'établissement de la connexion. Cependant, si dans un cas bien spécifique, odbc_setoption() permet d'utiliser PHP sans qu'il soit nécessaire de recourir à utiliser un produit commercial, alors cela n'a pas d'importance.

### Liste de paramètres

`odbc`

  Un identifiant de connexion, ou un identifiant de résultat, pour lequel il faut modifier des options. Pour `SQLSetConnectOption()`, c'est un identifiant de connexion. Pour `SQLSetStmtOption()`, c'est un identifiant de résultat.

`which`

  Fonction ODBC à utiliser. La valeur doit être de 1 pour utiliser `SQLSetConnectOption()` et 2 pour `SQLSetStmtOption()`.

`option`

  L'option à définir.

`value`

  La valeur pour l'option donnée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection ou de Odbc\Result; auparavant, une resource était attendue.

### Exemples

Exemple #1 Exemple avec odbc_setoption()

    <?php
    // 1. L'option 102 de SQLSetConnectOption() est SQL_AUTOCOMMIT.
    // 1 de SQL_AUTOCOMMIT est SQL_AUTOCOMMIT_ON.
    //    Cet exemple a le même effet que
    //    odbc_autocommit($conn, true);

    odbc_setoption($conn, 1, 102, 1);

    // 2. Option 0 de SQLSetStmtOption() est SQL_QUERY_TIMEOUT.
    //    Cet exemple fixe le délai d'expiration à 30 secondes.

    $result = odbc_prepare($conn, $sql);
    odbc_setoption($result, 2, 0, 30);
    odbc_execute($result);
    ?>

# odbc_specialcolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_specialcolumns — Retourne l'ensemble optimal de colonnes

### Description

function odbc_specialcolumns(
Odbc\Connection `$odbc`,
int `$type`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$scope`,
int `$nullable`
): Odbc\Result|false

Retourne soit l'ensemble optimal de colonnes qui identifie de façon unique une ligne d'une table, ou les colonnes qui sont automatiquement mises à jour lorsqu'une des valeurs de la ligne est mise à jour par une transaction.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`type`
  Lorsque le type est `SQL_BEST_ROWID`, odbc_specialcolumns() retourne la ou les colonnes qui permettent de repérer uniquement chaque ligne d'une table. Lorsque le type est `SQL_ROWVER`, odbc_specialcolumns() retourne la colonne ou les colonnes de la table spécifiée, s'il y en a, elles sont automatiquement mises à jour par les données sources lorsque chaque valeur de la ligne est mise à jour par n'importe quelle transaction.
`catalog`

  Le catalogue ('calificatif' dans le jargon ODBC 2).

`schema`

  Le schéma ('propriétaire' dans le jargon ODBC 2).

`table`

  La table.

`scope`

  Le `scope`, qui ordonne le jeu de résultats. Un de `SQL_SCOPE_CURROW`, `SQL_SCOPE_TRANSACTION` ou `SQL_SCOPE_SESSION`.

`nullable`

  Détermine si les colonnes spéciales qui peuvent avoir une valeur NULL doivent être retournées ou non. Un de `SQL_NO_NULLS` ou `SQL_NULLABLE`.

### Valeurs de retour

Renvoie un objet de résultat ODBC ou `false` si une erreur survient.

Le jeu de résultat contient les colonnes suivantes :

- `SCOPE`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `PSEUDO_COLUMN`

Les pilotes peuvent signaler des colonnes supplémentaires.

Le jeu de résultat est ordonné par `SCOPE`.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.

### Voir aussi

- odbc_tables() - Liste les tables d'une source

# odbc_statistics

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_statistics — Calcul des statistiques sur une table

### Description

function odbc_statistics(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$unique`,
int `$accuracy`
): Odbc\Result|false

Calcul des statistiques sur une table.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`catalog`

  Le catalogue ('calificatif' dans le jargon ODBC 2).

`schema`

  Le schéma ('propriétaire' dans le jargon ODBC 2).

`table`

  Le nom de la table.

`unique`

  Le type de l'index. Un de `SQL_INDEX_UNIQUE` ou `SQL_INDEX_ALL`.

`accuracy`

  Un de `SQL_ENSURE` ou `SQL_QUICK`. Ce dernier demande au pilote de récupérer la `CARDINALITY` et `PAGES` seulement s'ils sont immédiatement disponible depuis le serveur.

### Valeurs de retour

Renvoie un objet de résultat ODBC ou `false` si une erreur survient.

Le jeu de résultat contient les colonnes suivantes :

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `NON_UNIQUE`
- `INDEX_QUALIFIER`
- `INDEX_NAME`
- `TYPE`
- `ORDINAL_POSITION`
- `COLUMN_NAME`
- `ASC_OR_DESC`
- `CARDINALITY`
- `PAGES`
- `FILTER_CONDITION`

Les pilotes peuvent signaler des colonnes supplémentaires.

Le jeu de résultat est ordonné par `NON_UNIQUE`, `TYPE`, `INDEX_QUALIFIER`, `INDEX_NAME` et `ORDINAL_POSITION`.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.

### Exemples

Exemple #1 Liste les Statistiques d'une Table

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $statistics = odbc_statistics($conn, 'TutorialDB', 'dbo', 'TEST', SQL_INDEX_UNIQUE, SQL_QUICK);
    while (($row = odbc_fetch_array($statistics))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [NON_UNIQUE] =>
        [INDEX_QUALIFIER] =>
        [INDEX_NAME] =>
        [TYPE] => 0
        [ORDINAL_POSITION] =>
        [COLUMN_NAME] =>
        [ASC_OR_DESC] =>
        [CARDINALITY] => 15
        [PAGES] => 3
        [FILTER_CONDITION] =>
    )

### Voir aussi

- odbc_tables() - Liste les tables d'une source

# odbc_tableprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tableprivileges — Liste les tables et leurs privilèges

### Description

function odbc_tableprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Liste les tables et leurs privilèges.

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`catalog`

  Le catalogue ('calificatif' dans le jargon ODBC 2).

`schema`

  Le schéma ('propriétaire' dans le jargon ODBC 2). Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`table`

  Le nom. Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

### Valeurs de retour

Renvoie un objet de résultat ODBC ou `false` si une erreur survient.

Le jeu de résultat contient les colonnes suivantes :

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Les pilotes peuvent signaler des colonnes supplémentaires.

Le jeu de résultat est ordonné par `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `PRIVILEGE` et `GRANTEE`.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.

### Exemples

Exemple #1 Liste les Privilèges d'une Table

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $privileges = odbc_tableprivileges($conn, 'SalesOrders', 'dbo', 'Orders');
    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => DELETE
        [IS_GRANTABLE] => YES
    )

### Voir aussi

- odbc_tables() - Liste les tables d'une source

# odbc_tables

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tables — Liste les tables d'une source

### Description

function odbc_tables(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$types` = `null`
): Odbc\Result|false

Liste les tables d'une source.

Pour supporter les énumérations de qualificateurs propriétaires et types de table, la sémantique suivante pour les paramètres `catalog`, `schema`, `table` et `table_type` est disponible :

- Si `catalog` est un signe de pourcentage (%), et `schema` et `table` sont des chaînes vides, alors le résultat contient la liste des qualificateurs valides pour la source (toutes les colonnes hormis TABLE_QUALIFIER contiennent NULL).
- Si `schema` est un signe de pourcentage (%), et `catalog` et `table` sont des chaînes vides, alors le résultat contient la liste des propriétaires de la source (toutes les colonnes hormis TABLE_OWNER contiennent NULL).
- Si `table_type` est un signe de pourcentage (%), et `catalog`, `schema` et `table` sont des chaînes vides, alors le résultat contient la liste des types de tables de la source (toutes les colonnes hormis TABLE_TYPE contiennent NULL).

### Liste de paramètres

`odbc`
  L'objet de connexion ODBC, voir la documentation de la fonction odbc_connect() pour plus de détails.
`catalog`

  Le catalogue ('calificatif' dans le jargon ODBC 2).

`schema`

  Le schéma ('propriétaire' dans le jargon ODBC 2). Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`table`

  Le nom. Ce paramètre accepte les masques de recherche suivants : `%` pour chercher zéro ou plusieurs caractères, et `_` pour chercher un seul caractère.

`types`

  Si `table_type` n'est pas une chaîne vide, il doit contenir une liste de valeurs, séparées par des virgules, qui représentent les types recherchés. Chaque valeur peut être insérée entre guillemets simples (`'`), ou sans guillemets. Par exemple, `'TABLE','VIEW'` ou `TABLE, VIEW`. Si la source de données ne supporte pas un type de table donné, odbc_tables() ne retournera aucun résultat pour ce type.

### Valeurs de retour

Renvoie un objet de résultat ODBC contenant les informations ou `false` si une erreur survient.

Le jeu de résultat contient les colonnes suivantes :

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `TABLE_TYPE`
- `REMARKS`

Les pilotes peuvent signaler des colonnes supplémentaires.

Le jeu de résultat est ordonné par `TABLE_TYPE`, `TABLE_CAT`, `TABLE_SCHEM` et `TABLE_NAME`.

### Historique

Version | Description
--- | ---
8.4.0 | `odbc` attend désormais une instance de Odbc\Connection; auparavant, un resource était attendu.
8.4.0 | Cette fonction retourne désormais une instance de Odbc\Result; auparavant, un resource était retourné.
8.0.0 | `schema`, `table` et `types` sont désormais nullables.

### Exemples

Exemple #1 Liste les Tables dans un Catalogue

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $tables = odbc_tables($conn, 'SalesOrders', 'dbo', '%', 'TABLE');
    while (($row = odbc_fetch_array($tables))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [TABLE_TYPE] => TABLE
        [REMARKS] =>
    )

### Voir aussi

- odbc_tableprivileges() - Liste les tables et leurs privilèges
- odbc_columns() - Liste les colonnes d'une table
- odbc_specialcolumns() - Retourne l'ensemble optimal de colonnes
- odbc_statistics() - Calcul des statistiques sur une table
- odbc_procedures() - Liste les procédures stockées

## Sommaire

- odbc_autocommit — Active le mode d'autovalidation
- odbc_binmode — Modifie la gestion des colonnes de données binaires
- odbc_close — Ferme une connexion ODBC
- odbc_close_all — Ferme toutes les connexions ODBC
- odbc_columnprivileges — Liste les colonnes et leurs droits associés
- odbc_columns — Liste les colonnes d'une table
- odbc_commit — Valide une transaction ODBC
- odbc_connect — Connexion à une source
- odbc_connection_string_is_quoted — Détermine si une valeur de chaîne de caractères de connexion ODBC est entre guillemets
- odbc_connection_string_quote — Met en guillemets une valeur de chaîne de caractères de connexion ODBC
- odbc_connection_string_should_quote — Détermine si une valeur de chaîne de caractères de connexion ODBC doit être mise entre guillemets
- odbc_cursor — Lit le nom du pointeur de résultat courant
- odbc_data_source — Retourne des informations sur les DSNs disponibles
- odbc_do — Alias de odbc_exec
- odbc_error — Lit le dernier code d'erreur
- odbc_errormsg — Lit le dernier message d'erreur
- odbc_exec — Exécute directement une requête SQL
- odbc_execute — Exécute une requête SQL préparée
- odbc_fetch_array — Lit une ligne de résultat dans un tableau associatif
- odbc_fetch_into — Lit une ligne de résultat, et la place dans un tableau
- odbc_fetch_object — Lit une ligne de résultat dans un objet
- odbc_fetch_row — Lit une ligne de résultat
- odbc_field_len — Lit la longueur d'un champ
- odbc_field_name — Lit le nom de la colonne
- odbc_field_num — Numéro de colonne
- odbc_field_precision — Alias de odbc_field_len
- odbc_field_scale — Lit l'échelle d'un champ
- odbc_field_type — Type de données d'un champ
- odbc_foreignkeys — Liste les clés étrangères
- odbc_free_result — Libére les objets associés à un résultat
- odbc_gettypeinfo — Liste les types de données supportés par une source
- odbc_longreadlen — Gestion des colonnes de type LONG
- odbc_next_result — Vérifie si plusieurs résultats sont disponibles
- odbc_num_fields — Nombre de colonnes dans un résultat
- odbc_num_rows — Nombre de lignes dans un résultat
- odbc_pconnect — Ouvre une connexion persistante à une source de données
- odbc_prepare — Prépare une commande pour l'exécution
- odbc_primarykeys — Liste les colonnes utilisées dans une clé primaire
- odbc_procedurecolumns — Liste les paramètres des procédures
- odbc_procedures — Liste les procédures stockées
- odbc_result — Lit un champ de résultat UODBC
- odbc_result_all — Affiche le résultat sous la forme d'une table HTML
- odbc_rollback — Annule une transaction
- odbc_setoption — Modifie les paramètres ODBC
- odbc_specialcolumns — Retourne l'ensemble optimal de colonnes
- odbc_statistics — Calcul des statistiques sur une table
- odbc_tableprivileges — Liste les tables et leurs privilèges
- odbc_tables — Liste les tables d'une source

# La classe Odbc\Connection

(PHP 8 >= 8.4.0)

## Introduction

Une classe entièrement opaque qui remplace une resource `odbc_connection` à partir de PHP 8.4.0.

## Synopsis de la classe

namespace Odbc;
class Connection {
}

# La classe Odbc\Result

(PHP 8 >= 8.4.0)

## Introduction

Une classe entièrement opaque qui remplace une resource `odbc_result` à partir de PHP 8.4.0.

## Synopsis de la classe

namespace Odbc;
class Result {
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Fonctions ODBC
  - odbc_autocommit — Active le mode d'autovalidation
  - odbc_binmode — Modifie la gestion des colonnes de données binaires
  - odbc_close — Ferme une connexion ODBC
  - odbc_close_all — Ferme toutes les connexions ODBC
  - odbc_columnprivileges — Liste les colonnes et leurs droits associés
  - odbc_columns — Liste les colonnes d'une table
  - odbc_commit — Valide une transaction ODBC
  - odbc_connect — Connexion à une source
  - odbc_connection_string_is_quoted — Détermine si une valeur de chaîne de caractères de connexion ODBC est entre guillemets
  - odbc_connection_string_quote — Met en guillemets une valeur de chaîne de caractères de connexion ODBC
  - odbc_connection_string_should_quote — Détermine si une valeur de chaîne de caractères de connexion ODBC doit être mise entre guillemets
  - odbc_cursor — Lit le nom du pointeur de résultat courant
  - odbc_data_source — Retourne des informations sur les DSNs disponibles
  - odbc_do — Alias de odbc_exec
  - odbc_error — Lit le dernier code d'erreur
  - odbc_errormsg — Lit le dernier message d'erreur
  - odbc_exec — Exécute directement une requête SQL
  - odbc_execute — Exécute une requête SQL préparée
  - odbc_fetch_array — Lit une ligne de résultat dans un tableau associatif
  - odbc_fetch_into — Lit une ligne de résultat, et la place dans un tableau
  - odbc_fetch_object — Lit une ligne de résultat dans un objet
  - odbc_fetch_row — Lit une ligne de résultat
  - odbc_field_len — Lit la longueur d'un champ
  - odbc_field_name — Lit le nom de la colonne
  - odbc_field_num — Numéro de colonne
  - odbc_field_precision — Alias de odbc_field_len
  - odbc_field_scale — Lit l'échelle d'un champ
  - odbc_field_type — Type de données d'un champ
  - odbc_foreignkeys — Liste les clés étrangères
  - odbc_free_result — Libére les objets associés à un résultat
  - odbc_gettypeinfo — Liste les types de données supportés par une source
  - odbc_longreadlen — Gestion des colonnes de type LONG
  - odbc_next_result — Vérifie si plusieurs résultats sont disponibles
  - odbc_num_fields — Nombre de colonnes dans un résultat
  - odbc_num_rows — Nombre de lignes dans un résultat
  - odbc_pconnect — Ouvre une connexion persistante à une source de données
  - odbc_prepare — Prépare une commande pour l'exécution
  - odbc_primarykeys — Liste les colonnes utilisées dans une clé primaire
  - odbc_procedurecolumns — Liste les paramètres des procédures
  - odbc_procedures — Liste les procédures stockées
  - odbc_result — Lit un champ de résultat UODBC
  - odbc_result_all — Affiche le résultat sous la forme d'une table HTML
  - odbc_rollback — Annule une transaction
  - odbc_setoption — Modifie les paramètres ODBC
  - odbc_specialcolumns — Retourne l'ensemble optimal de colonnes
  - odbc_statistics — Calcul des statistiques sur une table
  - odbc_tableprivileges — Liste les tables et leurs privilèges
  - odbc_tables — Liste les tables d'une source
- Odbc\Connection — La classe Odbc\Connection
- Odbc\Result — La classe Odbc\Result

# PHP Data Objects

# Introduction

L'extension `PHP Data Objects` (PDO) définit une interface légère et cohérente pour accéder à une base de données depuis PHP. Chaque pilote de base de données implémenté dans l'interface PDO peut utiliser des fonctionnalités spécifiques de chacune des bases de données en utilisant des extensions de fonctions. À noter qu'il n'est pas possible d'exécuter aucune fonction de base de données en utilisant l'extension PDO par elle-même ; il faut utiliser un pilote PDO spécifique à la base de données pour accéder au serveur de base de données.

PDO fournit une interface d'abstraction à l'accès de données, ce qui signifie que l'on utilise les mêmes fonctions pour exécuter des requêtes ou récupérer les données quelle que soit la base de données utilisée. PDO ne fournit pas une abstraction de base de données : il ne réécrit pas le SQL, n'émule pas des fonctionnalités manquantes. Il est recommandé d'utiliser une interface d'abstraction complète en cas de besoin de cela.

PDO est fourni avec PHP.

# Installation/Configuration

## Sommaire

- Installation
- Configuration à l'exécution

## Installation

Cette extension est activée par défaut. Elle peut être désactivée en utilisant l'option de configuration : --disable-pdo

Installer PDO sur les systèmes Unix

1. PDO et le pilote PDO_SQLITE sont activés par défaut. Il faut activer le pilote PDO de la base de données de son choix ; consulter la documentation pour les pilotes spécifiques aux bases de données pour plus d'informations.

   > Note:

   > À noter que lors de la compilation de PDO comme extension partagée (non recommandé), alors tous les pilotes PDO doivent être chargés après le chargement de PDO.

2. Lors de l'installation de PDO comme module partagé, le fichier php.ini doit être mis à jour afin de charger l'extension PDO automatiquement lorsque PHP entre en fonctionnement. Il faut également y activer les pilotes spécifiques à la base de données ; il faut s'assurer que ces pilotes seront listés après la ligne extension=pdo, vu que PDO doit être initialisé avant le chargement des extensions spécifiques aux bases de données. Si l'on compile PDO et les extensions relatives aux bases de données de façon statique, il est possible d'ignorer cette étape.

       extension=pdo

Utilisateurs de Windows

1. PDO est activé par défaut. Il convient de choisir les autres fichiers DLL spécifiques à la base de données et d'utiliser soit la fonction dl() pour les charger au moment de l'exécution, soit de les activer dans le fichier php.ini. Par exemple, ceci charge le pilote PDO_SQLITE mais laisse le pilote PDO_ODBC commenté:

       ;extension=pdo_odbc
       extension=pdo_sqlite

   Ces bibliothèques DLL doivent exister dans le dossier système extension_dir.

> Note:

> Il faut garder à l'esprit qu'après modification du php.ini, il faut redémarrer PHP pour que les nouvelles directives de configuration prennent effet.

## Configuration à l'exécution

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

Options de configuration PDO
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
pdo.dsn.* |  | php.ini seulement |

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

`pdo.dsn.*` string

  Définit un alias DSN. Voir PDO::__construct() pour une explication complète.

# Constantes pré-définies

## Sommaire

- Modes de récupération

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

## Modes de récupération

Voir les constantes de curseur pour les constantes de curseur `PDO::FETCH_ORI_*`.

## Méthodes de récupération de base

Mode de récupération | Résumé
--- | ---
`PDO::FETCH_DEFAULT` | Valeur spéciale pour utiliser le mode de récupération par défaut actuel.
`PDO::FETCH_ASSOC` | Tableau indexé par le nom de colonne uniquement.
`PDO::FETCH_BOTH` (Défaut) | Tableau indexé à la fois par le numéro de colonne et par le nom.
`PDO::FETCH_NAMED` | Variante de `PDO::FETCH_ASSOC` qui conserve les colonnes dupliquées.
`PDO::FETCH_NUM` | Tableau indexé par le numéro de colonne uniquement.
`PDO::FETCH_COLUMN` | Une seule colonne.
`PDO::FETCH_KEY_PAIR` | Paires de clés-valeurs, indexées par la première colonne.
`PDO::FETCH_FUNC` | Utilise une fonction pour créer la valeur de retour. (seulement PDOStatement::fetchAll())
`PDO::FETCH_OBJ` | Objet anonyme (stdClass).
`PDO::FETCH_CLASS` | Crée un objet d'une classe spécifiée.

## PDO::FETCH_CLASS options

Ces modes sont utilisés pour implémenter des options lors de l'utilisation de `PDO::FETCH_CLASS`.

Mode de récupération | Résumé
--- | ---
`PDO::FETCH_CLASSTYPE` | Utilise la première colonne comme nom de classe.
`PDO::FETCH_PROPS_LATE` | Appelle le constructeur avant de définir les propriétés.
`PDO::FETCH_SERIALIZE` | Utilise les données PHP sérialisées. Obsolète à partir de PHP 8.1.0.

## Modes de résultat unique

Les modes suivants ne peuvent pas être utilisés avec PDOStatement::fetchAll().

Mode de récupération | Résumé
--- | ---
`PDO::FETCH_BOUND` | Lie les valeurs aux variables spécifiées.
`PDO::FETCH_INTO` | Met à jour un objet existant.
`PDO::FETCH_LAZY` | Récupération paresseuse via PDORow pour un accès de type tableau et objet.

## Drapeaux spéciaux pour PDOStatement::fetchAll()

Les modes spéciaux suivants pour plusieurs résultats ne fonctionnent qu'avec PDOStatement::fetchAll() et ne fonctionnent pas avec certains autres modes de récupération. Consulter la documentation complète pour plus de détails.

Mode de récupération | Résumé
--- | ---
`PDO::FETCH_GROUP` | Les résultats sont regroupés par la première colonne.
`PDO::FETCH_UNIQUE` | Les résultats sont (uniquement) indexés par la première colonne.

## Gestion des noms de colonnes dupliqués

Il est possible que les résultats contiennent plusieurs colonnes utilisant le même nom. Par exemple, lors de la jointure de 2 tables contenant toutes deux une colonne avec le même nom.

Étant donné que les structures PHP telles que les tableaux et les objets ne prennent pas en charge plusieurs clés ou propriétés utilisant le même nom, le tableau ou l'objet retourné contiendra uniquement 1 des valeurs utilisant le même nom.

La valeur retournée pour un nom dupliqué donné doit être considérée comme indéfinie.

Pour éviter ce problème, nommez explicitement les colonnes en utilisant un alias. Par exemple :

    SELECT table1.created_at AS t1_created_at,
           table2.created_at AS t2_created_at
    FROM table1
    JOIN table2 ON table1.table2id = table2.id

Voir également `PDO::FETCH_NAMED`, `PDO::ATTR_FETCH_TABLE_NAMES` et `PDO::ATTR_FETCH_CATALOG_NAMES`.

## Définir le mode de récupération par défaut

Il est possible de définir le mode de récupération par défaut pour toutes les requêtes en utilisant `PDO::ATTR_DEFAULT_FETCH_MODE` avec PDO::__construct() or PDO::setAttribute().

Le mode de récupération par défaut est initialement défini sur PDOStatement::setFetchMode(). Cela affecte la réutilisation en tant que requête préparée et l'itération (en utilisant `foreach`).

Attention

PDOStatement::setAttribute() ne peut pas être utilisé pour définir le mode de récupération par défaut. Il n'accepte que les attributs spécifiques au pilote et ignore silencieusement les attributs qui ne sont pas reconnus.

## PDO::FETCH_DEFAULT (int)

Disponible à partir de PHP 8.0.7.

Ceci est une valeur spéciale qui utilise le mode de récupération par défaut actuel pour une PDOStatement. C'est particulièrement utile comme valeur par défaut pour les paramètres de méthode lors de l'extension de PDOStatement pour une utilisation avec `PDO::ATTR_STATEMENT_CLASS`.

Cette valeur ne peut pas être utilisée avec `PDO::ATTR_DEFAULT_FETCH_MODE`.

## PDO::FETCH_ASSOC (int)

`PDO::FETCH_ASSOC` retourne un tableau indexé par le nom de la colonne uniquement.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_ASSOC);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_BOTH (int)

Ceci est le mode de récupération par défaut.

`PDO::FETCH_BOTH` retourne un tableau indexé à la fois par le numéro de colonne et par le nom. Cela signifie que chaque valeur retournée est dupliquée pour chaque ligne de résultat.

Le numéro de colonne commence à 0 et est déterminé par l'ordre des colonnes de résultat dans la requête, et non (par exemple) par l'ordre dans lequel les colonnes sont définies dans la table.

> Note: L'utilisation de l'index de colonne numérique n'est pas recommandée car cela peut changer lorsque la requête est modifiée, ou lorsque le schéma de la table est modifié lors de l'utilisation de `SELECT *`.

> Note: Le nombre d'entrées indexées par le nom peut ne pas correspondre au nombre d'entrées indexées par le numéro dans les cas où plusieurs colonnes retournées utilisent le même nom.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_BOTH);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [id] => 104,
        [0] => 104,
        [name] => Chris,
        [1] => Chris,
        [country] => Ukraine,
        [2] => Ukraine
    )

## PDO::FETCH_NAMED (int)

`PDO::FETCH_NAMED` renvoie des résultats dans le même format que `PDO::FETCH_ASSOC` sauf que lorsque plusieurs colonnes utilisent le même nom, toutes les valeurs sont retournées sous forme de liste.

Pour plus d'informations sur la gestion des noms de colonnes dupliqués et les alternatives, voir la section sur la gestion des noms dupliqués ci-dessus.

L'ordre dans lequel les valeurs dupliquées sont retournées doit être considéré comme indéfini. Il n'y a aucun moyen de savoir d'où provient chaque valeur.

    <?php
    $stmt = $pdo->query(
        "SELECT users.*, referrer.name
         FROM users
         LEFT JOIN users AS referrer ON users.referred_by = referrer.userid
         WHERE userid = 109"
    );
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [userid] => 109
        [name] => Array
            (
                [0] => Toni
                [1] => Chris
            )
        [country] => Germany
        [referred_by] = 104
    )

## PDO::FETCH_NUM (int)

`PDO::FETCH_NUM` renvoie un tableau indexé par le numéro de colonne uniquement. Le numéro de colonne commence à 0 et est déterminé par l'ordre des colonnes de résultat dans la requête, et non (par exemple) par l'ordre dans lequel les colonnes sont définies dans la table.

> Note: L'utilisation de l'index de colonne numérique n'est pas recommandée car cela peut changer lorsque la requête est modifiée, ou lorsque le schéma de la table est modifié lors de l'utilisation de `SELECT *`.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => 104
        [1] => Chris
        [2] => Ukraine
    )

## PDO::FETCH_COLUMN (int)

`PDO::FETCH_COLUMN` renvoie des valeurs d'une seule colonne. Utiliser le deuxième argument pour PDOStatement::setFetchMode() ou PDOStatement::fetchAll() pour spécifier quelle colonne est retournée.

Si la colonne spécifiée n'existe pas, une ValueError sera levée.

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN);
    print_r($row);

    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN, 1);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => Chris
        [1] => Jamie
        [2] => Robin
    )

    Array
    (
        [0] => Ukraine
        [1] => England
        [2] => Germany
    )

## PDO::FETCH_KEY_PAIR (int)

`PDO::FETCH_KEY_PAIR` renvoie des paires de valeurs, indexées par la première colonne. Les résultats doivent contenir uniquement 2 colonnes. Ce mode de récupération n'a de sens qu'avec PDOStatement::fetchAll().

> Note: Si la première colonne n'est pas unique, des valeurs seront perdues. Les valeurs perdues doivent être considérées comme indéfinies.

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [Chris] => Ukraine
        [Jamie] => England
        [Robin] => Germany
    )

## PDO::FETCH_FUNC (int)

Spécifier une fonction pour créer la valeur retournée. Ce mode ne peut être utilisé qu'avec PDOStatement::fetchAll().

La fonction reçoit les valeurs en tant que paramètres. Il n'y a aucun moyen de récupérer le nom de la colonne à laquelle une valeur donnée était associée. Il faut s'assurer que l'ordre des colonnes dans la requête correspond à celui attendu par la fonction.

> Note: Les effets de `PDO::FETCH_GROUP` et `PDO::FETCH_UNIQUE` sont appliqués aux résultats avant que la fonction ne soit appelée.

    <?php
    function valueCreator($col1, $col2, $col3)
    {
        return [
            'col1' => $col1,
            'col2' => strtoupper($col2),
            'col3' => $col3,
            'customKey' => 'customValue',
        ];
    }

    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_FUNC, valueCreator(...));
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => Array
            (
                [col1] => 104
                [col2] => SAM
                [col3] => Ukraine
                [customKey] => customValue
            )

        [1] => Array
            (
                [col1] => 105
                [col2] => JAMIE
                [col3] => England
                [customKey] => customValue
            )

        [2] => Array
            (
                [col1] => 107
                [col2] => ROBIN
                [col3] => Germany
                [customKey] => customValue
            )

    )

## PDO::FETCH_OBJ (int)

`PDO::FETCH_OBJ` renvoie un objet stdClass.

Voir aussi PDOStatement::fetchObject() et `PDO::FETCH_CLASS`.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_OBJ);
    print_r($row);

L'exemple ci-dessus va afficher :

    stdClass Object
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_CLASS (int)

Renvoie un objet d'une classe spécifiée. Pour des comportements supplémentaires, voir les options de drapeau.

Si une propriété n'existe pas avec le nom d'une colonne retournée, elle sera déclarée dynamiquement. Ce comportement est obsolète et entraînera une erreur à partir de PHP 9.0.

Voir aussi PDOStatement::fetchObject().

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

Résultat de l'exemple ci-dessus est similaire à :

    Constructor called with 0 args
    Properties set when constructor called? Yes
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_CLASSTYPE (int)

Ce mode de récupération peut uniquement être utilisé en combinaison avec `PDO::FETCH_CLASS` (et ses autres options).

Lorsque ce mode de récupération est utilisé, PDO utilisera la première colonne retournée comme nom de la classe à retourner.

Si la classe spécifiée ne peut pas être trouvée, un objet stdClass sera retourné, sans avertissement ni erreur.

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT 'TestEntity', userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE);
    $result = $stmt->fetch();
    var_dump($result);

Résultat de l'exemple ci-dessus est similaire à :

    Constructor called with 0 args
    Properties set when constructor called? Yes
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_PROPS_LATE (int)

Ce mode de récupération peut uniquement être utilisé en combinaison avec `PDO::FETCH_CLASS` (et ses autres options).

Lorsque ce mode de récupération est utilisé, le constructeur sera appelé avant que les propriétés ne soient définies.

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

Résultat de l'exemple ci-dessus est similaire à :

    Constructor called with 0 args
    Properties set when constructor called? No
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_SERIALIZE (int)

Avertissement

Cette fonctionnalité est OBSOLÈTE depuis PHP 8.1.0. Son utilisation est fortement déconseillée.

Ce mode de récupération peut uniquement être utilisé en combinaison avec `PDO::FETCH_CLASS` (et ses autres options).

Lorsque ce mode de récupération est utilisé, la classe spécifiée doit être Serializable.

Attention

Cette fonctionnalité ne prend pas en charge une chaîne contenant un objet sérialisé complet (avec serialize()).

Attention

Ce mode de récupération n'appelle pas le constructeur.

    <?php
    class TestEntity implements Serializable
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with " . count(func_get_args()) . " args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }

        public function serialize()
        {
            return join(
                "|",
                [$this->userid, $this->name, $this->country, $this->referred_by_userid]
            );
        }

        public function unserialize(string $data)
        {
            $parts = explode("|", $data);
            $this->userid = (int) $parts[0];
            $this->name = $parts[1];
            $this->country = $parts[2];

            $refId = $parts[3];
            $this->referred_by_userid = ($refId === "" ? null : (int) $refId);
        }
    }

    print "Set up record (constructor called manually):\n";
    $db->exec(
        "CREATE TABLE serialize (
            sdata TEXT
        )"
    );

    $origObj = new TestEntity();
    $origObj->userid = 200;
    $origObj->name = 'Seri';
    $origObj->country = 'Syria';
    $origObj->referred_by_userid = null;

    $insert = $db->prepare("INSERT INTO serialize (sdata) VALUES (:sdata)");
    $insert->execute(['sdata' => $origObj->serialize()]);

    print "\nRetrieve result:\n";
    $query = "SELECT sdata FROM serialize";
    $stmt = $db->query($query);
    // NOTE: Le constructeur n'est jamais appelé
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_SERIALIZE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

Résultat de l'exemple ci-dessus est similaire à :

    Deprecated: TestEntity implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in Standard input code on line 2
    Set up record (constructor called manually):
    Constructor called with 0 args
    Properties set when constructor called? No

    Retrieve result:
    Deprecated: PDOStatement::setFetchMode(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 58

    Deprecated: PDOStatement::fetch(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 59
    object(TestEntity)#5 (4) {
      ["userid"]=>
      int(200)
      ["name"]=>
      string(4) "Seri"
      ["country"]=>
      string(5) "Syria"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_BOUND (int)

Ce mode de récupération ne peut pas être utilisé avec PDOStatement::fetchAll().

Ce mode de récupération ne renvoie pas directement un résultat, mais lie des valeurs à des variables spécifiées avec PDOStatement::bindColumn(). La méthode fetch appelée renvoie `true`.

> Note: Lors de l'utilisation d'instructions préparées, pour fonctionner correctement, les variables doivent être liées après l'exécution de la requête.

    <?php
    $query = "SELECT users.userid, users.name, users.country, referrer.name
        FROM users
        LEFT JOIN users AS referrer ON users.referred_by_userid = referrer.userid";
    $stmt = $db->prepare($query);
    $stmt->execute();

    $stmt->bindColumn('userid', $userId);
    $stmt->bindColumn('name', $name);
    $stmt->bindColumn('country', $country);
    // Lie par position de colonne pour résoudre le nom de colonne dupliqué
    // Pour éviter que cela ne casse si la requête est modifiée, utiliser un alias SQL à la place
    // Par exemple : referrer.name AS referrer_name
    $stmt->bindColumn(4, $referrerName);

    while ($stmt->fetch(\PDO::FETCH_BOUND)) {
        print join("\t", [$userId, $name, $country, ($referrerName ?? 'NULL')]) . "\n";
    }

L'exemple ci-dessus va afficher :

    104	Chris	Ukraine	NULL
    105	Jamie	England	NULL
    107	Robin	Germany	Chris
    108	Sean	Ukraine	NULL
    109	Toni	Germany	NULL
    110	Toni	Germany	NULL

## PDO::FETCH_INTO (int)

Ce mode de récupération ne peut pas être utilisé avec PDOStatement::fetchAll().

Ce mode de récupération met à jour les propriétés de l'objet spécifié. L'objet est renvoyé en cas de succès.

Si une propriété n'existe pas avec le nom d'une colonne renvoyée, elle sera déclarée dynamiquement. Ce comportement est obsolète et entraînera une erreur à partir de PHP 9.0.

Les propriétés doivent être `public` et ne peuvent pas être `readonly`.

Attention

Il n'y a aucun moyen de changer l'objet à mettre à jour sans utiliser PDOStatement::setFetchMode() entre la récupération de chaque enregistrement.

    <?php

    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;
    }

    $obj = new TestEntity();

    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");

    $stmt->setFetchMode(\PDO::FETCH_INTO, $obj);
    $result = $stmt->fetch();

    var_dump($result);

Résultat de l'exemple ci-dessus est similaire à :

    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_LAZY (int)

Ce mode de récupération ne peut pas être utilisé avec PDOStatement::fetchAll().

Ce mode de récupération renvoie un objet PDORow qui fournit un accès à la fois de type tableau et de type objet aux valeurs (c'est-à-dire qu'il combine le comportement de `PDO::FETCH_BOTH` et `PDO::FETCH_OBJ`), récupérées de manière paresseuse.

Cela peut fournir un accès efficace en mémoire (du côté PHP) aux résultats non mis en mémoire tampon sur le serveur de base de données. Que PDO utilise ou non un tampon côté client pour les résultats dépend du pilote spécifique à la base de données utilisé (et de sa configuration).

Attention

PDORow renverra `NULL` sans aucun avertissement ou erreur lors de l'accès à des propriétés ou des clés qui ne sont pas définies. Cela peut rendre des erreurs telles que des fautes de frappe ou des requêtes ne renvoyant pas les données attendues plus difficiles à repérer et à déboguer.

Attention

L'objet PDORow renvoyé est mis à jour chaque fois qu'un résultat est récupéré.

    <?php
    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
    $result = $stmt->fetch(\PDO::FETCH_LAZY);

    print "ID: ". $result[0] ."\n";
    print "Name: {$result->name}\n";
    print "Country: " . $result['country'] ."\n";
    // Renvoie NULL. Aucun avertissement ou erreur n'est levé.
    print "Does not exist: " . var_export($result->does_not_exist, true) . "\n";

    $differentResult = $stmt->fetch(\PDO::FETCH_LAZY);
    // L'objet PDORow précédemment récupéré pointe maintenant vers le nouveau résultat récupéré
    print "ID: ". $result[0] ."\n";

L'exemple ci-dessus va afficher :

    ID: 104
    Name: Chris
    Country: Ukraine
    Does not exist: NULL
    ID: 105

## PDO::FETCH_GROUP (int)

`PDO::FETCH_GROUP` renvoie des listes de tableaux associatifs, indexés par une colonne (non unique). Ce mode de récupération ne fonctionne qu'avec PDOStatement::fetchAll().

Lorsqu'il est combiné avec `PDO::FETCH_UNIQUE`, les deux modes utiliseront la même colonne, rendant la combinaison de ces modes inutile.

Cette récupération doit être combinée avec l'un des `PDO::FETCH_ASSOC`, `PDO::FETCH_BOTH`, `PDO::FETCH_NAMED`, `PDO::FETCH_NUM`, `PDO::FETCH_COLUMN` ou `PDO::FETCH_FUNC`.

Si aucun mode de récupération de la liste ci-dessus n'est donné, le mode de récupération par défaut actuel pour la PDOStatement sera utilisé.

    <?php
    $stmt = $pdo->query("SELECT country, userid, name FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                    )
            )
    )

Dans l'exemple ci-dessus, il est notable que la première colonne est omise du tableau pour chaque ligne, n'étant disponible que comme clé. Elle peut être incluse en répétant la colonne, comme dans l'exemple suivant :

    <?php
    $stmt = $pdo->query("SELECT country, userid, name, country FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                        [country] => Ukraine
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                        [country] => Ukraine
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                        [country] => England
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                        [country] => Germany
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                        [country] => Germany
                    )
            )
    )

## PDO::FETCH_UNIQUE (int)

`PDO::FETCH_UNIQUE` utilise la première colonne pour indexer les enregistrements, renvoyant 1 enregistrement par valeur d'index. Ce mode de récupération ne fonctionne qu'avec PDOStatement::fetchAll().

Lorsqu'il est combiné avec `PDO::FETCH_GROUP`, les deux modes utiliseront la même colonne, rendant la combinaison de ces modes inutile.

Cette récupération doit être combinée avec l'un des `PDO::FETCH_ASSOC`, `PDO::FETCH_BOTH`, `PDO::FETCH_NAMED`, `PDO::FETCH_NUM`, `PDO::FETCH_COLUMN` ou `PDO::FETCH_FUNC`.

Si aucun mode de récupération de la liste ci-dessus n'est donné, le mode de récupération par défaut actuel pour la PDOStatement sera utilisé.

Lorsqu'il est utilisé avec une colonne qui est connue pour être unique (comme l'ID d'enregistrement), ce mode offre la possibilité de renvoyer rapidement des résultats indexés par cette valeur.

> Note: Si la première colonne n'est pas unique, des valeurs seront perdues. La ou les valeur(s) qui sont perdues doivent être considérées comme indéfinies.

Attention

Le filtrage des enregistrements doit être effectué dans SQL si possible.La base de données utilisera des index pour optimiser ce processus et ne renvoyer que les enregistrements requis. Sélectionner plus d'enregistrements que nécessaire dans la base de données peut augmenter considérablement l'utilisation de la mémoire et le temps de requête pour des ensembles de résultats plus volumineux.

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [104] => Array
            (
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [name] => Robin
                [country] => Germany
            )

    )

Dans l'exemple ci-dessus, il est notable que la première colonne est omise du tableau pour chaque ligne, n'étant disponible que comme clé. Elle peut être incluse en répétant la colonne, comme dans l'exemple suivant :

    <?php
    $stmt = $pdo->query("SELECT userid, userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

L'exemple ci-dessus va afficher :

    Array
    (
        [104] => Array
            (
                [userid] => 104
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [userid] => 105
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [userid] => 107
                [name] => Robin
                [country] => Germany
            )

    )

## Curseur

Voir aussi `PDO::ATTR_CURSOR_NAME`.

`PDO::FETCH_ORI_NEXT` (int)
  Récupère la ligne suivante dans le jeu de résultats. Valide uniquement pour les curseurs défilables.
`PDO::FETCH_ORI_PRIOR` (int)
  Récupère la ligne précédente dans le jeu de résultats. Valide uniquement pour les curseurs défilables.
`PDO::FETCH_ORI_FIRST` (int)
  Récupère la première ligne dans le jeu de résultats. Valide uniquement pour les curseurs défilables.
`PDO::FETCH_ORI_LAST` (int)
  Récupère la dernière ligne dans le jeu de résultats. Valide uniquement pour les curseurs défilables.
`PDO::FETCH_ORI_ABS` (int)
  Récupère la ligne demandée par numéro de ligne dans le jeu de résultats. Valide uniquement pour les curseurs défilables.
`PDO::FETCH_ORI_REL` (int)
  Récupère la ligne demandée par position relative par rapport à la position actuelle du curseur dans le jeu de résultats. Valide uniquement pour les curseurs défilables.
`PDO::CURSOR_FWDONLY` (int)
  Crée un objet PDOStatement avec un curseur à sens unique. C'est le choix de curseur par défaut, car c'est le modèle d'accès aux données le plus rapide et le plus courant en PHP.
`PDO::CURSOR_SCROLL` (int)
  Crée un objet PDOStatement avec un curseur défilable. Passez les constantes `PDO::FETCH_ORI_*` pour contrôler les lignes récupérées du jeu de résultats.

## Autre constante

`PDO::PARAM_BOOL` (int)
  Représente un type de données booléen.
`PDO::PARAM_NULL` (int)
  Représente le type de données SQL NULL.
`PDO::PARAM_INT` (int)
  Représente le type de données SQL INTEGER.
`PDO::PARAM_STR` (int)
  Représente le type de données SQL CHAR, VARCHAR ou tout autre type de données de chaîne de caractères.
`PDO::PARAM_STR_NATL` (int)
  Drapeau pour indiquer qu'une chaîne utilise le jeu de caractères national. Disponible à partir de PHP 7.2.0
`PDO::PARAM_STR_CHAR` (int)
  Drapeau pour indiquer qu'une chaîne utilise le jeu de caractères régulier. Disponible à partir de PHP 7.2.0
`PDO::PARAM_LOB` (int)
  Représente le type de données SQL large object.
`PDO::PARAM_STMT` (int)
  Représente un type de jeu d'enregistrements (recordset). Actuellement, aucun pilote ne prend en charge ce type.
`PDO::PARAM_INPUT_OUTPUT` (int)
  Spécifie que le paramètre est un paramètre INOUT pour une procédure stockée. Cette constante doit être utilisée avec un opérateur OU bit à bit avec des constantes `PDO::PARAM_*`.
`PDO::ATTR_AUTOCOMMIT` (bool)
  Si cette valeur est `false`, PDO tente de désactiver l'autocommit afin que la connexion commence une transaction. À partir de PHP 8.4.0, cette constante est de type bool ; elle était auparavant de type int.
`PDO::ATTR_PREFETCH` (int)
  Définit la taille de prélecture permet de trouver un équilibre entre la vitesse et l'utilisation de la mémoire pour l'application. Toutes les combinaisons de bases de données/pilotes ne prennent pas en charge la définition de la taille de prélecture. Une taille de prélecture plus grande entraîne une augmentation des performances au prix d'une utilisation de la mémoire plus élevée. Le pilote PDO_PGSQL traite plutôt cet attribut comme un commutateur : à partir de PHP 8.5.0, une valeur de `0` active la lecture paresseuse (ligne par ligne) ; voir la documentation du pilote PDO_PGSQL pour plus de détails.
`PDO::ATTR_TIMEOUT` (int)
  Définit la valeur du délai d'attente en secondes pour les communications avec la base de données.
`PDO::ATTR_ERRMODE` (int)
  Voir la section sur les erreurs et la gestion des erreurs pour plus d'informations sur cet attribut.
`PDO::ATTR_SERVER_VERSION` (int)
  Cette valeur est en lecture seule ; elle renverra des informations sur la version du serveur de base de données auquel PDO est connecté.
`PDO::ATTR_CLIENT_VERSION` (int)
  Cette valeur est en lecture seule ; elle renverra des informations sur la version des bibliothèques clientes utilisées par le pilote PDO.
`PDO::ATTR_SERVER_INFO` (int)
  Cette valeur est en lecture seule ; elle renverra des informations sur la version du serveur de base de données auquel PDO est connecté.
`PDO::ATTR_CONNECTION_STATUS` (int)
`PDO::ATTR_CASE` (int)
  Force les noms de colonnes à une casse spécifique, comme spécifié par les constantes `PDO::CASE_*`.
`PDO::ATTR_CURSOR_NAME` (int)
  Obtenir ou définir le nom à utiliser pour un curseur. Le plus utile lors de l'utilisation de curseurs défilables et de mises à jour positionnées.
`PDO::ATTR_CURSOR` (int)
  Sélectionne le type de curseur. PDO prend actuellement en charge soit `PDO::CURSOR_FWDONLY` soit `PDO::CURSOR_SCROLL`. À moins d'avoir besoin de curseurs défilables, il convient d'utiliser le mode de curseur `PDO::CURSOR_FWDONLY`.
`PDO::ATTR_DRIVER_NAME` (int)
  Renvoie le nom du pilote.

  Exemple #1 Utilisation de `PDO::ATTR_DRIVER_NAME`

      <?php
       if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
         echo "Running on mysql; doing something mysql specific here\n";
       }
       ?>

`PDO::ATTR_ORACLE_NULLS` (int)
  Convertit les chaînes vides en valeurs NULL SQL lors des récupérations de données.
`PDO::ATTR_PERSISTENT` (int)
  Demande une connexion persistante, plutôt que de créer une nouvelle connexion. Voir connections et gestion des connexions pour plus d'informations sur cet attribut.
`PDO::ATTR_STATEMENT_CLASS` (int)
  Définit le nom de la classe des déclarations retournées.
`PDO::ATTR_FETCH_CATALOG_NAMES` (int)
  Ajoute le nom du catalogue contenant chaque nom de colonne renvoyé dans le jeu de résultats. Le nom du catalogue et le nom de la colonne sont séparés par un caractère décimal (.). La prise en charge de cet attribut se fait au niveau du pilote ; il peut ne pas être pris en charge par le pilote.
`PDO::ATTR_FETCH_TABLE_NAMES` (int)
  Ajoute le nom de la table contenant chaque nom de colonne renvoyé dans le jeu de résultats. Le nom de la table et le nom de la colonne sont séparés par un caractère décimal (.). La prise en charge de cet attribut se fait au niveau du pilote ; il peut ne pas être pris en charge par le pilote utilisé.
`PDO::ATTR_STRINGIFY_FETCHES` (int)
  Force toutes les valeurs récupérées (sauf `null`) à être traitées comme des chaînes. Les valeurs `null` restent inchangées à moins que `PDO::ATTR_ORACLE_NULLS` ne soit défini sur `PDO::NULL_TO_STRING`.
`PDO::ATTR_MAX_COLUMN_LEN` (int)
  Définit la longueur maximale des noms de colonnes.
`PDO::ATTR_DEFAULT_FETCH_MODE` (int)
`PDO::ATTR_EMULATE_PREPARES` (bool)
  Active ou désactive l'émulation des requêtes préparées. Certains pilotes ne supportent pas les requêtes préparées natives ou n'ont qu'un support limité de celles-ci. Lorsqu'elle vaut `true`, PDO émule toujours les requêtes préparées ; lorsqu'elle vaut `false`, il utilise les requêtes préparées natives du pilote. À partir de PHP 8.4.0, cette constante est de type bool ; elle était auparavant de type int.
`PDO::ATTR_DEFAULT_STR_PARAM` (int)
  Définit le type de paramètre de chaîne par défaut, cela peut être l'un de `PDO::PARAM_STR_NATL` et `PDO::PARAM_STR_CHAR`. Disponible à partir de PHP 7.2.0.
`PDO::ERRMODE_SILENT` (int)
  Ne pas lever d'erreur ou d'exception si une erreur se produit. Le développeur est censé vérifier explicitement les erreurs. Avant PHP 8.0.0, ceci est le mode par défaut. Voir erreur et gestion des erreurs pour plus d'informations sur cet attribut.
`PDO::ERRMODE_WARNING` (int)
  Émet un message PHP `E_WARNING` si une erreur se produit. Voir erreur et gestion des erreurs pour plus d'informations sur cet attribut.
`PDO::ERRMODE_EXCEPTION` (int)
  Lève une PDOException si une erreur se produit. Ceci est le mode par défaut à partir de PHP 8.0.0. Voir erreur et gestion des erreurs pour plus d'informations sur cet attribut.
`PDO::CASE_NATURAL` (int)
  Laisser les noms de colonnes tels que retournés par le pilote de base de données.
`PDO::CASE_LOWER` (int)
  Force les noms de colonnes à être en minuscules.
`PDO::CASE_UPPER` (int)
  Force les noms de colonnes à être en majuscules.
`PDO::NULL_NATURAL` (int)
`PDO::NULL_EMPTY_STRING` (int)
`PDO::NULL_TO_STRING` (int)
`PDO::ERR_NONE` (string)
  Correspond à SQLSTATE `'00000'`, ce qui signifie que l'instruction SQL a été émise avec succès sans erreurs ni avertissements. Cette constante est pour la commodité lors de la vérification de PDO::errorCode() ou PDOStatement::errorCode() pour déterminer si une erreur s'est produite. On saura généralement si c'est le cas en examinant le code de retour de la méthode qui a déclenché la condition d'erreur de toute façon.
`PDO::PARAM_EVT_ALLOC` (int)
  Événement d'allocation.
`PDO::PARAM_EVT_FREE` (int)
  Événement de désallocation.
`PDO::PARAM_EVT_EXEC_PRE` (int)
  Événement déclenché avant l'exécution d'une instruction préparée.
`PDO::PARAM_EVT_EXEC_POST` (int)
  Événement déclenché après l'exécution d'une instruction préparée.
`PDO::PARAM_EVT_FETCH_PRE` (int)
  Événement déclenché avant la récupération d'un résultat d'un ensemble de résultats.
`PDO::PARAM_EVT_FETCH_POST` (int)
  Événement déclenché après la récupération d'un résultat d'un ensemble de résultats.
`PDO::PARAM_EVT_NORMALIZE` (int)
  Événement déclenché lors de l'enregistrement d'un paramètre lié permettant au pilote de normaliser le nom du paramètre.
`PDO::SQLITE_DETERMINISTIC` (int)
  Avertissement

  Cette constante est OBSOLÈTE à partir de PHP 8.5.0. Utiliser `Pdo\Sqlite::DETERMINISTIC` à la place.

  Spécifie qu'une fonction créée avec PDO::sqliteCreateFunction() est déterministe, c'est-à-dire qu'elle renvoie toujours le même résultat donné les mêmes entrées dans une seule instruction SQL. (Disponible à partir de PHP 7.1.4.)

# Connexions et gestionnaire de connexion

Les connexions sont établies en créant des instances de la classe de base de PDO. Peu importe quel pilote l'on veut utiliser ; l'on utilise toujours le nom de la classe PDO. Le constructeur accepte des paramètres pour spécifier la source de la base de données (connue en tant que DSN) et optionnellement, le nom d'utilisateur et le mot de passe (s'il y en a un).

Exemple #1 Connexion à MySQL

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    ?>

S'il y a des erreurs de connexion, un objet `PDOException` est lancé. Il est possible d'attraper cette exception pour gérer cette erreur, ou laisser le gestionnaire global d'exception défini via la fonction set_exception_handler() la traiter.

Exemple #2 Gestion des erreurs de connexion

    <?php
    try {
        $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    } catch (PDOException $e) {
        // tenter de réessayer la connexion après un certain délai, par exemple
    }

Avertissement

Comme toutes les autres exceptions, PDOException peut être capturée soit explicitement, par une instruction `catch`, soit implicitement via set_exception_handler(). Sinon, le comportement par défaut consistant à convertir une exception non capturée en une `E_FATAL_ERROR` se produira. L'erreur fatale contiendra un backtrace qui peut laisser échapper des détails sur la connexion. Ainsi, l'option php.ini `display_errors` doit être définie à `0` sur un serveur de production.

Lorsque la connexion à la base de données a réussi, une instance de la classe PDO est retournée au script. La connexion est active tant que l'objet PDO l'est. Pour clore la connexion, il faut détruire l'objet en s'assurant que toutes ses références sont effacées. Il est possible de faire cela en assignant `null` à la variable gérant l'objet. Si on ne le fait pas explicitement, PHP fermera automatiquement la connexion lorsque le script arrivera à la fin.

> Note: S'il existe encore d'autres références à cette instance PDO (par exemple, à partir d'une instance PDOStatement ou d'autres variables référençant la même instance PDO), celles-ci doivent également être supprimées (par exemple, en affectant `null` à la variable qui référence le PDOStatement).

Exemple #3 Fermeture d'une connexion

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    // utiliser la connexion ici
    $sth = $dbh->query('SELECT * FROM foo');

    // et maintenant, on la ferme !
    $sth = null;
    $dbh = null;
    ?>

Beaucoup d'applications web utilisent des connexions persistantes aux serveurs de base de données. Les connexions persistantes ne sont pas fermées à la fin du script, mais sont mises en cache et réutilisées lorsqu'un autre script demande une connexion en utilisant les mêmes paramètres. Le cache des connexions persistantes permet d'éviter d'établir une nouvelle connexion à chaque fois qu'un script doit accéder à une base de données, rendant l'application web plus rapide.

Exemple #4 Connexions persistantes

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
        PDO::ATTR_PERSISTENT => true
    ));
    ?>

La valeur de l'option `PDO::ATTR_PERSISTENT` est convertie en booléen (activer/désactiver les connexions persistantes), sauf si c'est une chaîne de caractères non-numérique, auquel cas ceci autorise l'utilisation de plusieurs pools de connexions persistantes. Ceci est utile si les connexions différentes utilisent des paramètres incompatibles, par exemple, des valeurs différentes de `PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`.

> Note:

> Pour utiliser des connexions persistantes, il faut utiliser la valeur `PDO::ATTR_PERSISTENT` dans le tableau des options du pilote passé au constructeur PDO. Si l'on définit cet attribut avec la méthode PDO::setAttribute() après l'instanciation de l'objet, le pilote n'utilisera pas les connexions persistantes.

Avertissement

PDO ne fait aucun nettoyage des connexions persistantes. Les tables temporaires, verrous, transactions et autres changements d'état peuvent rester de l'utilisation précédente de la connexion, causant des problèmes inattendus. Voir la section Connexions de base de données persistantes pour plus d'informations.

> Note:

> Lors de l'utilisation du pilote PDO ODBC et que la bibliothèque ODBC prend en charge le bassin de connexion ODBC (unixODBC et Windows le supportent tous les deux ; peut être plus), alors il est recommandé de ne pas utiliser les connexions persistantes PDO, mais plutôt laisser le bassin de connexion ODBC mettre en cache les connexions. Le bassin de connexion ODBC est partagé avec les autres modules dans le processus ; si PDO met en cache la connexion, alors cette connexion ne sera jamais retournée par le bassin de connexion ODBC, faisant que plusieurs connexions sont créées pour les autres modules.

# Transactions et validation automatique (autocommit)

Maintenant que l'on est connecté via PDO, il faut comprendre comment PDO gère les transactions avant d'exécuter des requêtes. Si l'on n'a jamais utilisé les transactions, elles offrent 4 fonctionnalités majeures : Atomicité, Consistance, Isolation et Durabilité (ACID). En d'autres termes, n'importe quel travail mené à bien dans une transaction, même s'il est effectué par étapes, est garanti d'être appliqué à la base de données sans risque, et sans interférence pour les autres connexions, quand il est validé. Le travail des transactions peut également être automatiquement annulé à la demande (en supposant que l'on n'ait encore rien validé), ce qui rend la gestion des erreurs bien plus simple dans les scripts.

Les transactions sont typiquement implémentées pour appliquer toutes les modifications en une seule fois ; ceci a le bel effet d'améliorer radicalement l'efficacité des mises à jour. En d'autres termes, les transactions rendent les scripts plus rapides et potentiellement plus robustes (il faut les utiliser correctement pour jouir de ces bénéfices).

Malheureusement, toutes les bases de données ne prennent pas en charge les transactions, donc PDO doit s'exécuter en mode "autocommit" lorsque l'on ouvre pour la première fois la connexion. Le mode "autocommit" signifie que toutes les requêtes que l'on exécute ont leurs transactions implicites, si la base de données le prend en charge ou aucune transaction si la base de données ne les prend pas en charge. En cas de besoin d'une transaction, il faut utiliser la méthode PDO::beginTransaction() pour l'initialiser. Si le pilote utilisé ne prend pas en charge les transactions, une exception PDO sera lancée (en accord avec le gestionnaire d'erreurs : ceci est toujours une erreur sérieuse). Une fois que l'on est dans une transaction, il faut utiliser la fonction PDO::commit() ou la fonction PDO::rollBack() pour la terminer, suivant le succès du code durant la transaction.

Avertissement

PDO ne vérifie la possibilité d'utiliser des transactions qu'au niveau du pilote. Si certaines conditions à l'exécution empêchent les transactions de fonctionner, PDO::beginTransaction() retournera tout de même `true` sans erreur si le serveur accepte de démarrer une transaction.

Un exemple serait d'utiliser des transactions sur des tables au format MyISAM du serveur de base de données MySQL.

Avertissement

Commit implicite avec des déclarations DDL : Certaines bases de données émettent automatiquement un `COMMIT` implicite lorsqu'une déclaration de langage de définition de base de données (DDL), telle que `DROP TABLE` ou `CREATE TABLE`, est exécutée dans une transaction. Cela signifie que toutes les modifications précédentes effectuées dans la même transaction seront automatiquement validées et ne peuvent pas être annulées.

`MySQL` et `Oracle` sont des exemples de bases de données qui présentent ce comportement.

Exemple #1 Exemple de Commit implicite

    <?php
    $pdo->beginTransaction();
    $pdo->exec("INSERT INTO users (name) VALUES ('Rasmus')");
    $pdo->exec("CREATE TABLE test (id INT PRIMARY KEY)"); // Un COMMIT implicite se produit ici
    $pdo->rollBack(); // Cela N'annulera PAS l'INSERT/CREATE pour MySQL ou Oracle
    ?>

Meilleure pratique : Évitez d'exécuter des déclarations DDL à l'intérieur des transactions lors de l'utilisation des bases de données qui imposent ce comportement. Si nécessaire, séparez les opérations DDL de la logique transactionnelle.

Lorsque le script se termine ou lorsque la connexion est sur le point de se fermer, si l'on a une transaction en cours, PDO l'annulera automatiquement. Ceci est une mesure de sécurité afin de garantir l'intégrité des données dans le cas où le script se termine d'une façon inattendue. Si on ne valide pas explicitement la transaction, alors, on présume que quelque chose s'est mal passé et l'annulation de la transaction intervient afin de garantir la sécurité des données.

Avertissement

L'annulation automatique intervient si l'on a initialisé la transaction via PDO::beginTransaction(). Si l'on a manuellement exécuté une requête qui commence une transaction, PDO n'a aucun moyen de le savoir et donc, n'annulera pas automatiquement cette transaction si quelque chose s'est mal passé.

Exemple #2 Exécution d'un groupe dans une transaction

Dans l'exemple suivant, supposons que nous allons créer un jeu d'entrées pour un nouvel employé, dont le numéro d'ID sera 23. En plus des données de base sur cette personne, nous devons également lui enregistrer son salaire. Il est très simple d'effectuer deux mises à jour séparées, mais en les enfermant dans les appels des fonctions PDO::beginTransaction() et PDO::commit(), nous garantissons que personne ne pourra voir ces modifications tant qu'elles ne seront pas complètes. Si quelque chose tourne mal, le bloc de capture annulera toutes les modifications effectuées depuis le début de la transaction et affichera un message d'erreur.

    <?php
    try {
      $dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',
          array(PDO::ATTR_PERSISTENT => true));
      echo "Connecté\n";
    } catch (Exception $e) {
      die("Impossible de se connecter : " . $e->getMessage());
    }

    try {
      $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

      $dbh->beginTransaction();
      $dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')");
      $dbh->exec("insert into salarychange (id, amount, changedate)
          values (23, 50000, NOW())");
      $dbh->commit();

    } catch (Exception $e) {
      $dbh->rollBack();
      echo "Échec : " . $e->getMessage();
    }
    ?>

On n'est pas limités dans le nombre de mises à jour dans une transaction ; il est également possible d'y effectuer des requêtes complexes et bien sûr, utiliser ces informations pour construire d'autres mises à jour et requêtes ; durant l'activité de la transaction, l'on est sûrs que personne d'autre ne peut effectuer des modifications alors que l'on est au milieu des modifications. Pour plus d'informations sur les transactions, se reporter à la documentation fournie par la base de données.

# Requêtes préparées et procédures stockées

La plupart des bases de données supportent le concept des requêtes préparées. Qu'est-ce donc ? Il est possible de les voir comme une sorte de modèle compilé pour le SQL que l'on veut exécuter, qui peut être personnalisé en utilisant des variables en guise de paramètres. Les requêtes préparées offrent deux fonctionnalités essentielles :

- La requête ne doit être analysée (ou préparée) qu'une seule fois, mais peut être exécutée plusieurs fois avec des paramètres identiques ou différents. Lorsque la requête est préparée, la base de données va analyser, compiler et optimiser son plan pour exécuter la requête. Pour les requêtes complexes, ce processus peut prendre assez de temps, ce qui peut ralentir les applications si l'on doit répéter la même requête plusieurs fois avec différents paramètres. En utilisant les requêtes préparées, l'on évite ainsi de répéter le cycle analyse/compilation/optimisation. Pour résumer, les requêtes préparées utilisent moins de ressources et s'exécutent plus rapidement.
- Les paramètres pour préparer les requêtes n'ont pas besoin d'être entre guillemets ; le pilote gère cela. Si l'application utilise exclusivement les requêtes préparées, il est possible d'être sûr qu'aucune injection SQL n'est possible (Cependant, si l'on construit d'autres parties de la requête en se basant sur des entrées utilisateurs, l'on continue à prendre un risque).

Les requêtes préparées sont tellement pratiques que c'est l'unique fonctionnalité que PDO émule pour les pilotes qui ne les prennent pas en charge. Ceci assure de pouvoir utiliser la même technique pour accéder aux données, sans se soucier des capacités de la base de données.

Exemple #1 Insertions répétitives en utilisant les requêtes préparées

Cet exemple effectue une requête INSERT en y substituant un `nom` et une `valeur` pour les marqueurs nommés.

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (:name, :value)");
    $stmt->bindParam(':name', $name);
    $stmt->bindParam(':value', $value);

    // insertion d'une ligne
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // insertion d'une autre ligne avec des valeurs différentes
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Exemple #2 Insertions répétées en utilisant des requêtes préparées

Cet exemple effectue une requête INSERT en y substituant un `nom` et une `valeur` pour les marqueurs `?`.

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (?, ?)");
    $stmt->bindParam(1, $name);
    $stmt->bindParam(2, $value);

    // insertion d'une ligne
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // insertion d'une autre ligne avec différentes valeurs
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Exemple #3 Récupération des données en utilisant des requêtes préparées

Cet exemple récupère des données basées sur la valeur d'une clé fournie par un formulaire. L'entrée utilisateur est automatiquement échappée, il n'y a donc aucun risque d'attaque par injection SQL.

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name = ?");
    $stmt->execute([$_GET['name']]);
    foreach ($stmt as $row) {
      print_r($row);
    }
    ?>

Exemple #4 Appel d'une procédure stockée avec un paramètre de sortie

Si le pilote de la base de données le prend en charge, il est également possible de lier des paramètres aussi bien pour l'entrée que pour la sortie. Les paramètres de sortie sont utilisés typiquement pour récupérer les valeurs d'une procédure stockée. Les paramètres de sortie sont un peu plus complexes à utiliser que les paramètres d'entrée car on doit savoir la longueur qu'un paramètre donné pourra atteindre lorsqu'on le lie. Si la valeur retournée est plus longue que la taille que l'on aura suggérée, une erreur sera émise.

    <?php
    $stmt = $dbh->prepare("CALL sp_returns_string(?)");
    $stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000);

    // Appel de la procédure stockée
    $stmt->execute();

    print "La procédure a retourné : $return_value\n";
    ?>

Exemple #5 Appel d'une procédure stockée avec un paramètre d'entrée/sortie

Il faut également spécifier les paramètres qui gèrent les valeurs aussi bien pour l'entrée que pour la sortie ; la syntaxe est similaire aux paramètres de sortie. Dans le prochain exemple, la chaîne 'Bonjour' est passée à la procédure stockée et lorsqu'elle retourne la valeur, 'Bonjour' est remplacée par la valeur retournée par la procédure.

    <?php
    $stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)");
    $value = 'hello';
    $stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000);

    // appel de la procédure stockée
    $stmt->execute();

    print "La procédure a retourné : $value\n";
    ?>

Exemple #6 Utilisation invalide de marqueur

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE '%?%'");
    $stmt->execute([$_GET['name']]);

    // un marqueur doit être utilisé à la place d'une valeur complète
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE ?");
    $stmt->execute(["%$_GET[name]%"]);
    ?>

# Les erreurs et leur gestion

PDO offre 3 façons différentes de gérer les erreurs afin de mieux s'adapter à l'application.

- `PDO::ERRMODE_SILENT`

  Antérieur à PHP 8.0.0, c'est le mode par défaut. PDO définit simplement le code d'erreur à inspecter grâce aux méthodes PDO::errorCode() et PDO::errorInfo() sur les objets représentant les requêtes, mais aussi ceux représentant les bases de données ; si l'erreur résulte d'un appel à l'objet représentant la requête, il est possible d'appeler la méthode PDOStatement::errorCode() ou la méthode PDOStatement::errorInfo() sur l'objet. Si l'erreur résulte d'un appel sur l'objet représentant une base de données, il est également possible d'appeler ces deux mêmes méthodes sur l'objet.

- `PDO::ERRMODE_WARNING`

  En plus de définir le code d'erreur, PDO émettra un message E_WARNING traditionnel. Cette configuration est utile lors des tests et du débogage, pour voir le problème sans interrompre l'application.

- `PDO::ERRMODE_EXCEPTION`

  À partir de PHP 8.0.0, c'est le mode par défaut. En plus de définir le code d'erreur, PDO lancera une exception PDOException et y définira les propriétés afin de représenter le code d'erreur et les informations complémentaires. Cette configuration est également utile lors du débogage, car elle va « contourner » le point critique du code, montrer rapidement le problème rencontré (il faut se rappeler : les transactions sont automatiquement annulées si l'exception fait que le script se termine).

  Le mode "exception" est également très utile car ainsi, il est possible de structurer le gestionnaire d'erreur plus clairement qu'avec les alertes traditionnelles PHP et, ce, avec moins de code que lorsque l'on exécute le code en mode silence, et que l'on vérifie systématiquement les valeurs retournées après chaque appel à la base de données.

  Voir le chapitre sur les exceptions pour plus d'informations sur les exceptions en PHP.

PDO utilise les codes erreurs SQL-92 SQLSTATE ; chaque pilote PDO est responsable de lier ses codes natifs aux codes SQLSTATE appropriés. La méthode PDO::errorCode() retourne un code SQLSTATE unique. En cas de besoin d'informations spécifiques sur l'erreur, PDO propose également la méthode PDO::errorInfo() qui retourne un tableau contenant le code SQLSTATE, le code d'erreur spécifique du pilote et la chaîne décrivant l'erreur provenant du pilote.

Exemple #1 Création d'une instance PDO et définition du mode d'erreur

    <?php
    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);
    $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    // Cela provoquera une PDOException (lorsque la table n'existe pas).
    $dbh->query("SELECT wrongcolumn FROM wrongtable");
    ?>

L'exemple ci-dessus va afficher :

    Fatal error: Uncaught PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'testdb.wrongtable' doesn't exist in /tmp/pdo_test.php:10
    Stack trace:
    #0 /tmp/pdo_test.php(10): PDO->query('SELECT wrongcol...')
    #1 {main}
      thrown in /tmp/pdo_test.php on line 10

> Note:

> PDO::__construct() lance toujours une exception PDOException si la connexion échoue, quelle que soit la configuration de `PDO::ATTR_ERRMODE`.

Exemple #2 Crée une instance PDO et définit le mode d'erreur depuis le constructeur

    <?php
    $dsn = 'mysql:dbname=test;host=127.0.0.1';
    $user = 'googleguy';
    $password = 'googleguy';

    $dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING));

    // Ceci fera que PDO lancera une erreur de niveau E_WARNING au lieu d'une exception (lorsque la table n'existe pas)
    $dbh->query("SELECT wrongcolumn FROM wrongtable");
    ?>

L'exemple ci-dessus va afficher :

    Warning: PDO::query(): SQLSTATE[42S02]: Base table or view not found: 1146 Table 'test.wrongtable' doesn't exist in
    /tmp/pdo_test.php on line 9

# Les gros objets (LOB)

À un moment dans l'application, il serait possible d'avoir besoin de stocker de grosses données dans la base de données. « Gros » signifie typiquement des données d'environ 4 ko ou plus, bien que certaines bases de données peuvent gérer plus de 32 ko avant que les données deviennent « grosses ». Les gros objets peuvent être de nature textuelle ou binaire. PDO permet de travailler avec ce type de grosses données en utilisant le code type `PDO::PARAM_LOB` dans les appels aux fonctions PDOStatement::bindParam() ou PDOStatement::bindColumn(). `PDO::PARAM_LOB` demande à PDO de transformer les données en un flux que l'on pourra manipuler en utilisant l'API PHP des flux.

Exemple #1 Affichage d'une image depuis une base de données

Cet exemple lie un LOB dans une variable nommée $lob et l'envoie au navigateur en utilisant la fonction fpassthru(). Étant donné qu'un LOB est représenté en un flux, les fonctions comme fgets(), fread() et stream_get_contents() peuvent être utilisées sur ce flux.

    <?php
    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
    $stmt = $db->prepare("select contenttype, imagedata from images where id=?");
    $stmt->execute(array($_GET['id']));
    $stmt->bindColumn(1, $type, PDO::PARAM_STR, 256);
    $stmt->bindColumn(2, $lob, PDO::PARAM_LOB);
    $stmt->fetch(PDO::FETCH_BOUND);

    header("Content-Type: $type");
    fpassthru($lob);
    ?>

Exemple #2 Insertion d'une image dans une base de données

Cet exemple ouvre un fichier et passe le pointeur de fichier à PDO pour l'insérer en tant que LOB. PDO fera son possible pour récupérer le contenu du fichier et l'insérer dans la base de données de la manière la plus efficace possible.

    <?php
    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)");
    $id = get_new_id(); // fonction pour allouer un nouvel ID

    // assumons que nous récupérons un fichier depuis un formulaire
    // il est possible de trouver plus de détails dans la documentation de PHP

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();
    ?>

Exemple #3 Insertion d'une image dans une base de données Oracle

Oracle requiert une syntaxe légèrement différente pour y insérer un LOB depuis un fichier. Il est également essentiel d'effectuer l'insertion au sein d'une transaction, sinon, le nouveau LOB sera inséré avec une longueur de zéro :

    <?php
    $db = new PDO('oci:', 'scott', 'tiger');
    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) " .
    "VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?");
    $id = get_new_id(); // fonction pour allouer un nouvel ID

    // assumons que nous récupérons un fichier depuis un formulaire
    // il est possible de trouver plus de détails dans la documentation de PHP

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();
    ?>

# La classe PDO

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

## Introduction

Représente une connexion entre PHP et un serveur de base de données.

## Synopsis de la classe

class PDO {
/* Constantes */
public const int PARAM_NULL;
public const int PARAM_BOOL = 5;
public const int PARAM_INT = 1;
public const int PARAM_STR = 2;
public const int PARAM_LOB = 3;
public const int PARAM_STMT = 4;
public const int PARAM_INPUT_OUTPUT;
public const int PARAM_STR_NATL;
public const int PARAM_STR_CHAR;
public const int PARAM_EVT_ALLOC;
public const int PARAM_EVT_FREE;
public const int PARAM_EVT_EXEC_PRE;
public const int PARAM_EVT_EXEC_POST;
public const int PARAM_EVT_FETCH_PRE;
public const int PARAM_EVT_FETCH_POST;
public const int PARAM_EVT_NORMALIZE;
public const int FETCH_DEFAULT;
public const int FETCH_LAZY;
public const int FETCH_ASSOC;
public const int FETCH_NUM;
public const int FETCH_BOTH;
public const int FETCH_OBJ;
public const int FETCH_BOUND;
public const int FETCH_COLUMN;
public const int FETCH_CLASS;
public const int FETCH_INTO;
public const int FETCH_FUNC;
public const int FETCH_GROUP;
public const int FETCH_UNIQUE;
public const int FETCH_KEY_PAIR;
public const int FETCH_CLASSTYPE;
public const int FETCH_SERIALIZE;
public const int FETCH_PROPS_LATE;
public const int FETCH_NAMED;
public const int ATTR_AUTOCOMMIT;
public const int ATTR_PREFETCH;
public const int ATTR_TIMEOUT;
public const int ATTR_ERRMODE;
public const int ATTR_SERVER_VERSION;
public const int ATTR_CLIENT_VERSION;
public const int ATTR_SERVER_INFO;
public const int ATTR_CONNECTION_STATUS;
public const int ATTR_CASE;
public const int ATTR_CURSOR_NAME;
public const int ATTR_CURSOR;
public const int ATTR_ORACLE_NULLS;
public const int ATTR_PERSISTENT;
public const int ATTR_STATEMENT_CLASS;
public const int ATTR_FETCH_TABLE_NAMES;
public const int ATTR_FETCH_CATALOG_NAMES;
public const int ATTR_DRIVER_NAME;
public const int ATTR_STRINGIFY_FETCHES;
public const int ATTR_MAX_COLUMN_LEN;
public const int ATTR_EMULATE_PREPARES;
public const int ATTR_DEFAULT_FETCH_MODE;
public const int ATTR_DEFAULT_STR_PARAM;
public const int ERRMODE_SILENT;
public const int ERRMODE_WARNING;
public const int ERRMODE_EXCEPTION;
public const int CASE_NATURAL;
public const int CASE_LOWER;
public const int CASE_UPPER;
public const int NULL_NATURAL;
public const int NULL_EMPTY_STRING;
public const int NULL_TO_STRING;
public const string ERR_NONE;
public const int FETCH_ORI_NEXT;
public const int FETCH_ORI_PRIOR;
public const int FETCH_ORI_FIRST;
public const int FETCH_ORI_LAST;
public const int FETCH_ORI_ABS;
public const int FETCH_ORI_REL;
public const int CURSOR_FWDONLY;
public const int CURSOR_SCROLL;
/* Méthodes */
public function __construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function beginTransaction(): bool
public function commit(): bool
public static function connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function errorCode(): ?string
public function errorInfo(): array
public function exec(string `$statement`): int|false
public function getAttribute(int `$attribute`): mixed
public static function getAvailableDrivers(): array
public function inTransaction(): bool
public function lastInsertId(?string `$name` = `null`): string|false
public function prepare(string `$query`, array `$options` = []): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function rollBack(): bool
public function setAttribute(int `$attribute`, mixed `$value`): bool
}

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont désormais typées.

# PDO::beginTransaction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::beginTransaction — Démarre une transaction

### Description

public function PDO::beginTransaction(): bool

PDO::beginTransaction() désactive le mode `autocommit`. Lorsque l'autocommit est désactivé, les modifications faites sur la base de données via les instances des objets PDO ne sont pas appliquées tant qu'on ne met pas fin à la transaction en appelant la fonction PDO::commit(). L'appel de PDO::rollBack() annulera toutes les modifications faites à la base de données et remettra la connexion en mode autocommit.

Quelques bases de données, dont MySQL, exécuteront automatiquement un COMMIT lorsqu'une requête de définition de langage de base de données (DDL) comme DROP TABLE ou CREATE TABLE est exécutée dans une transaction. Ce COMMIT implicite empêchera d'annuler toutes autres modifications faites dans cette transaction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Lance l'exception PDOException si une transaction a déjà démarrée ou que le pilote ne prend pas en charge les transactions.

> Note: Une exception sera émise même si l'attribut `PDO::ATTR_ERRMODE` ne vaut pas `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Annule une transaction

L'exemple suivant commence une transaction et exécute deux requêtes qui modifient la base de données avant d'annuler les modifications. Sur MySQL, cependant, la requête DROP TABLE validera automatiquement la transaction, donc, aucune des modifications de la transaction ne sera annulée.

    <?php
    /* Démarre une transaction, désactivation de l'auto-commit */
    $dbh->beginTransaction();

    /* Modification du schéma de la base ainsi que des données */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
    SET name = 'hamburger'");

    /* On s'aperçoit d'une erreur et on annule les modifications */
    $dbh->rollBack();

    /* La connexion à la base de données est maintenant de retour en mode auto-commit */
    ?>

### Voir aussi

- PDO::commit() - Valide une transaction
- PDO::rollBack() - Annule une transaction
- Transactions et auto-commit

# PDO::commit

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::commit — Valide une transaction

### Description

public function PDO::commit(): bool

PDO::commit() valide une transaction, remet la connexion en mode `autocommit` en attendant l'appel à la fonction PDO::beginTransaction() pour débuter une nouvelle transaction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Une exception PDOException sera lancée si aucune transaction n'est active.

> Note: Une exception sera émise même si l'attribut `PDO::ATTR_ERRMODE` ne vaut pas `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Valide une transaction basique

    <?php
    /* Commence une transaction, désactivation de l'auto-commit */
    $dbh->beginTransaction();

    /* Insérer plusieurs enregistrements sur une base tout-ou-rien */
    $sql = 'INSERT INTO fruit
        (name, colour, calories)
        VALUES (?, ?, ?)';

    $sth = $dbh->prepare($sql);

    foreach ($fruits as $fruit) {
        $sth->execute(array(
            $fruit->name,
            $fruit->colour,
            $fruit->calories,
        ));
    }

    /* Valider les modifications */
    $dbh->commit();

    /* La connexion à la base de données est maintenant de retour en mode auto-commit */
    ?>

Exemple #2 Valide une transaction DDL

    <?php
    /* Commence une transaction, désactivation de l'auto-commit */
    $dbh->beginTransaction();

    /* Modification du schéma de la base de données */
    $sth = $dbh->exec("DROP TABLE fruit");

    /* Valide les modifications */
    $dbh->commit();

    /* La connexion à la base de données est maintenant de retour en mode auto-commit */
    ?>

> Note: Toutes les bases de données n'autorisent pas les transactions à fonctionner sur des déclarations DDL: certaines vont générer des erreurs, tandis que d'autres (y compris MySQL) vont automatiquement valider la transaction après que la première déclaration DDL aura été rencontrée.

### Voir aussi

- PDO::beginTransaction() - Démarre une transaction
- PDO::rollBack() - Annule une transaction
- Transactions et auto-commit

# PDO::connect

(PHP 8 >= 8.4.0)

PDO::connect — Connecte à une base de données et retourne une sous-classe PDO pour les pilotes qui le supportent

### Description

public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static

Crée une instance d'une sous-classe de PDO pour la base de données connectée si elle existe, sinon retourne une instance générique de PDO.

### Liste de paramètres

`dsn`

  Le `Data Source Name`, ou DSN, qui contient les informations requises pour se connecter à la base.

  En général, un DSN est constitué du nom du pilote PDO, suivi d'une syntaxe spécifique au pilote. Plus de détails sont disponibles dans la documentation PDO de chaque pilote.

  Le paramètre `dsn` supporte trois méthodes différentes pour spécifier les arguments nécessaires à la création de la base de données :

  Appel pilote

    `dsn` contient le DSN complet.

  Appel URI

    `dsn` est constitué de `uri:` suivi par une URI qui définit la localisation du fichier contenant la chaîne de DSN. L'URI peut spécifier un fichier local ou distant.

    `uri:file:///path/to/dsnfile`

  Aliasing

    `dsn` est constitué d'un nom `name` qui correspond à `pdo.dsn.`name`` dans le fichier php.ini, et qui définit la chaîne DSN.

    > Note:

    > L'alias doit être défini dans le fichier php.ini, et non pas dans un fichier .htaccess ou httpd.conf

`username`

  Le nom d'utilisateur pour la chaîne DSN. Ce paramètre est optionnel pour certains pilotes PDO.

`password`

  Le mot de passe de la chaîne DSN. Ce paramètre est optionnel pour certains pilotes PDO.

`options`

  Un tableau clé=>valeur avec les options spécifiques de connexion.

### Valeurs de retour

Renvoie une instance d'une sous-classe de PDO pour le pilote PDO correspondant si elle existe, ou une instance générique de PDO.

### Erreurs / Exceptions

Une exception PDOException est levée si la tentative de connexion à la base de données demandée échoue, indépendamment du `PDO::ATTR_ERRMODE` actuellement défini.

### Voir aussi

- Pdo\Dblib
- Pdo\Firebird
- Pdo\Mysql
- Pdo\Odbc
- Pdo\Pgsql
- Pdo\Sqlite
- PDO::__construct() - Crée une instance PDO qui représente une connexion à la base

# PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::__construct — Crée une instance PDO qui représente une connexion à la base

### Description

public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)

Crée un objet PDO qui représente une connexion à la base.

### Liste de paramètres

`dsn`

  Le `Data Source Name`, ou DSN, qui contient les informations requises pour se connecter à la base.

  En général, un DSN est constitué du nom du pilote PDO, suivi d'une syntaxe spécifique au pilote. Plus de détails sont disponibles dans la documentation PDO de chaque pilote.

  Le paramètre `dsn` supporte trois méthodes différentes pour spécifier les arguments nécessaires à la création de la base de données :

  Appel pilote

    `dsn` contient le DSN complet.

  Appel URI

    `dsn` est constitué de `uri:` suivi par une URI qui définit la localisation du fichier contenant la chaîne de DSN. L'URI peut spécifier un fichier local ou distant.

    `uri:file:///path/to/dsnfile`

  Aliasing

    `dsn` est constitué d'un nom `name` qui correspond à `pdo.dsn.`name`` dans le fichier php.ini, et qui définit la chaîne DSN.

    > Note:

    > L'alias doit être défini dans le fichier php.ini, et non pas dans un fichier .htaccess ou httpd.conf

`username`

  Le nom d'utilisateur pour la chaîne DSN. Ce paramètre est optionnel pour certains pilotes PDO.

`password`

  Le mot de passe de la chaîne DSN. Ce paramètre est optionnel pour certains pilotes PDO.

`options`

  Un tableau clé=>valeur avec les options spécifiques de connexion.

### Erreurs / Exceptions

Une exception PDOException est levée si la tentative de connexion à la base de données demandée échoue, indépendamment du `PDO::ATTR_ERRMODE` actuellement défini.

### Exemples

Exemple #1 Crée une instance PDO via une invocation de pilote

    <?php

    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Exemple #2 Crée une instance PDO via une invocation URI

L'exemple ci-dessous suppose que le fichier /usr/local/dbconnect existe avec des droits d'accès qui permettent à PHP d'y accéder. Le fichier contient alors le DSN de PDO, pour se connecter à une base de données DB2, avec le pilote PDO_ODBC :

    odbc:DSN=SAMPLE;UID=john;PWD=mypass

Le script PHP peut alors créer une connexion de base de données, en passant dans l'URL le paramètre `uri:` et en pointant sur l'URI du fichier :

    <?php

    $dsn = 'uri:file:///usr/local/dbconnect';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Exemple #3 Crée une instance PDO avec un alias

L'exemple ci-dessous suppose que le fichier php.ini contient la directive suivante pour activer une connexion à un serveur MySQL, avec l'alias `mydb`:

    [PDO]
    pdo.dsn.mydb="mysql:dbname=testdb;host=localhost"

    <?php

    $dsn = 'mydb';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

# PDO::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorCode — Retourne le SQLSTATE associé avec la dernière opération sur la base de données

### Description

public function PDO::errorCode(): ?string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

PDO::errorCode() retourne un SQLSTATE, un identifiant alphanumérique de cinq caractères défini dans le standard ANSI SQL. Brièvement, un SQLSTATE consiste en une valeur de classe de deux caractères suivi par une valeur de sous-classe de trois caractères. Une valeur de classe de 01 indique une alerte et est accompagnée par un code de retour SQL_SUCCESS_WITH_INFO. Les valeurs de classes autre que '01', mis à part la classe 'IM', indiquent une erreur. La classe 'IM' est spécifique aux alertes et aux erreurs qui sont issues de l'implémentation elle-même de PDO (ou peut-être ODBC, lors de l'utilisation du driver ODBC). La valeur de sous-classe '000' dans n'importe quelle classe, indique qu'il n'y a pas de sous-classe pour cet SQLSTATE.

PDO::errorCode() retourne uniquement les codes erreurs pour les opérations exécutées directement sur le gestionnaire de la base de données. Si l'on crée un objet PDOStatement avec la fonction PDO::prepare() ou la fonction PDO::query() et que l'on invoque une erreur sur le gestionnaire de requête, PDO::errorCode() ne retournera pas cette erreur. Il faut appeler PDOStatement::errorCode() pour retourner le code erreur pour une opération exécutée sur un gestionnaire de requête particulier.

Retourne `null` si aucune opération n'a été exécutée sur la base de données.

### Exemples

Exemple #1 Récupération d'un code SQLSTATE

    <?php
    /* Provoque une erreur -- la table BONES n'existe pas */
    $dbh->exec("INSERT INTO bones(skull) VALUES ('lucy')");

    echo "\nPDO::errorCode(): ", $dbh->errorCode();
    ?>

L'exemple ci-dessus va afficher :

    PDO::errorCode(): 42S02

### Voir aussi

- PDO::errorInfo() - Retourne les informations associées à l'erreur lors de la dernière opération sur la base de données
- PDOStatement::errorCode() - Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête
- PDOStatement::errorInfo() - Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête

# PDO::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorInfo — Retourne les informations associées à l'erreur lors de la dernière opération sur la base de données

### Description

public function PDO::errorInfo(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

PDO::errorInfo() retourne un tableau contenant des informations sur l'erreur survenue lors de la dernière opération exécutée par ce gestionnaire de base de données. Le tableau contient les champs suivants :

Élément | Information
--- | ---
0 | Code d'erreur SQLSTATE (un identifiant alphanumérique de cinq caractères défini dans le standard ANSI SQL).
1 | Code d'erreur spécifique au driver.
2 | Message d'erreur spécifique au driver.

> Note:

> Si le code d'erreur SQLSTATE n'est pas défini ou s'il n'y a pas d'erreur spécifique du driver, l'élément suivant l'élément 0 sera défini à `null`.

PDO::errorInfo() retourne uniquement les informations des erreurs pour les opérations exécutées directement sur un gestionnaire de base de données. Si l'on crée un objet PDOStatement avec la fonction PDO::prepare() ou la fonction PDO::query() et que l'on invoque une erreur sur le gestionnaire de requête, PDO::errorInfo() ne retournera pas l'erreur depuis le gestionnaire de requête. Il faut appeler la fonction PDOStatement::errorInfo() pour retourner les informations sur l'erreur pour une opération exécutée sur un gestionnaire de requête particulier.

### Exemples

Exemple #1 Affiche les champs d'erreurs pour une connexion PDO_ODBC sur une base de données DB2

    <?php
    /* Provoque une erreur -- mauvaise syntaxe SQL */
    $stmt = $dbh->prepare('mauvaise syntaxe sql');
    if (!$stmt) {
       echo "\nPDO::errorInfo():\n";
       print_r($dbh->errorInfo());
    }
    ?>

L'exemple ci-dessus va afficher :

    PDO::errorInfo():
    Array
    (
        [0] => 42S02
        [1] => -204
        [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "DANIELS.BONES" is an undefined name.  SQLSTATE=42704
    )

### Voir aussi

- PDO::errorCode() - Retourne le SQLSTATE associé avec la dernière opération sur la base de données
- PDOStatement::errorCode() - Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête
- PDOStatement::errorInfo() - Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête

# PDO::exec

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::exec — Exécute une requête SQL et retourne le nombre de lignes affectées

### Description

public function PDO::exec(string `$statement`): int|false

PDO::exec() exécute une requête SQL dans un appel d'une seule fonction, retourne le nombre de lignes affectées par la requête.

PDO::exec() ne retourne pas de résultat pour une requête SELECT. Pour une requête SELECT dont on aurait besoin une seule fois dans le programme, utiliser plutôt la fonction PDO::query(). Pour une requête dont on aurait besoin plusieurs fois, il convient de préparer un objet PDOStatement avec la fonction PDO::prepare() et exécutez la requête avec la fonction PDOStatement::execute().

### Liste de paramètres

`statement`

  La requête à préparer et à exécuter.

  Les données contenues dans la requête doivent être échappées proprement.

### Valeurs de retour

PDO::exec() retourne le nombre de lignes qui ont été modifiées ou effacées par la requête SQL exécutée. Si aucune ligne n'est affectée, la fonction PDO::exec() retournera `0`.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

L'exemple suivant se fonde inexactement sur la valeur retournée par PDO::exec(), où une requête qui n'affecte aucune ligne revient à appeler die() :

    <?php
    $db->exec() or die(print_r($db->errorInfo(), true)); // incorrect
    ?>

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Exécution d'une requête DELETE

Compte le nombre de lignes effacées pour une requête DELETE avec aucune clause WHERE.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    /* Effacement de toutes les lignes de la table FRUIT */
    $count = $dbh->exec("DELETE FROM fruit");

    /* Retourne le nombre de lignes effacées */
    print "Effacement de $count lignes.\n";
    ?>

L'exemple ci-dessus va afficher :

    Effacement de 1 lignes.

### Voir aussi

- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDO::query() - Prépare et Exécute une requête SQL sans marque substitutive
- PDOStatement::execute() - Exécute une requête préparée

# PDO::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::getAttribute — Récupère un attribut d'une connexion à une base de données

### Description

public function PDO::getAttribute(int `$attribute`): mixed

Cette fonction retourne la valeur d'un attribut d'une connexion à une base de données. Pour récupérer les attributs PDOStatement, se référer à la fonction PDOStatement::getAttribute().

Il est à noter que quelques bases de données/drivers combinés ne supportent pas tous les attributs de connexion.

### Liste de paramètres

`attribute`

  Une des constantes `PDO::ATTR_*`. Les attributs génériques qui sont appliqués aux connexions sont les suivantes :

  - `PDO::ATTR_AUTOCOMMIT`
  - `PDO::ATTR_CASE`
  - `PDO::ATTR_CLIENT_VERSION`
  - `PDO::ATTR_CONNECTION_STATUS`
  - `PDO::ATTR_DRIVER_NAME`
  - `PDO::ATTR_ERRMODE`
  - `PDO::ATTR_ORACLE_NULLS`
  - `PDO::ATTR_PERSISTENT`
  - `PDO::ATTR_PREFETCH`
  - `PDO::ATTR_SERVER_INFO`
  - `PDO::ATTR_SERVER_VERSION`
  - `PDO::ATTR_TIMEOUT`
  Certains pilotes peuvent faire usage d'attributs supplémentaires spécifiques au pilote. Il est à noter que les attributs spécifiques au pilote ne doivent pas être utilisés avec d'autres pilotes.

### Valeurs de retour

Un appel réussi retourne la valeur de l'attribut PDO demandé. Un appel qui a échoué retourne la valeur `null`.

### Erreurs / Exceptions

La méthode PDO::getAttribute() peut générer une exception PDOException lorsque le pilote sous-jacent ne prend pas en charge l'`attribute` demandé.

### Exemples

Exemple #1 Récupération des attributs de connexion à une base de données

    <?php
    $conn = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
    $attributes = array(
    "AUTOCOMMIT", "ERRMODE", "CASE", "CLIENT_VERSION", "CONNECTION_STATUS",
    "ORACLE_NULLS", "PERSISTENT", "PREFETCH", "SERVER_INFO", "SERVER_VERSION",
    "TIMEOUT"
    );

    foreach ($attributes as $val) {
       echo "PDO::ATTR_$val: ";
       echo $conn->getAttribute(constant("PDO::ATTR_$val")) . "\n";
    }
    ?>

### Voir aussi

- PDO::setAttribute() - Configure un attribut PDO
- PDOStatement::getAttribute() - Récupère un attribut de requête
- PDOStatement::setAttribute() - Définit un attribut de requête

# PDO::getAvailableDrivers

# pdo_drivers

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.3)

PDO::getAvailableDrivers -- pdo_drivers — Retourne la liste des pilotes PDO disponibles

### Description

public static function PDO::getAvailableDrivers(): array
function pdo_drivers(): array

Cette fonction retourne la liste de tous les pilotes PDO disponibles qui peuvent être utilisés avec le paramètre `DSN` de la fonction PDO::__construct().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

PDO::getAvailableDrivers() retourne un tableau de nom de pilotes. Si aucun pilote n'est disponible, il retourne un tableau vide.

### Exemples

Exemple #1 Exemple avec PDO::getAvailableDrivers()

    <?php
    print_r(PDO::getAvailableDrivers());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => mysql
        [1] => sqlite
    )

# PDO::inTransaction

(PHP 5 >= 5.3.3, Bundled pdo_pgsql, PHP 7, PHP 8)

PDO::inTransaction — Vérifie si l'on est dans une transaction

### Description

public function PDO::inTransaction(): bool

Vérifie si une transaction est actuellement active dans le pilote. Cette méthode ne fonctionne que pour les pilotes de base de données qui supportent les transactions.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si une transaction est actuellement active, `false` sinon.

# PDO::lastInsertId

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::lastInsertId — Retourne l'identifiant de la dernière ligne insérée ou la valeur d'une séquence

### Description

public function PDO::lastInsertId(?string `$name` = `null`): string|false

Retourne l'identifiant de la dernière ligne insérée, ou la dernière valeur d'une séquence d'objets, dépendamment du driver utilisé. Par exemple, PDO_PGSQL permet de spécifier le nom de n'importe quel objet séquence pour le paramètre `name`.

> Note:

> Cette méthode peut ne pas retourner un résultat significatif suivant les drivers PDO utilisés, car la base de données utilisée peut ne pas supporter la notion de champs auto-incrémenté ou de séquences.

### Liste de paramètres

`name`

  Nom de la séquence d'objets depuis laquelle l'identifiant doit être retourné.

### Valeurs de retour

Si un nom de séquence n'est pas spécifié pour le paramètre `name`, PDO::lastInsertId() retourne une chaîne représentant l'identifiant de la ligne de la dernière ligne insérée dans la base de données.

Si un nom de séquence est spécifié pour le paramètre `name`, PDO::lastInsertId() retourne une chaîne représentant la dernière valeur depuis la séquence d'objets spécifiée.

Si le driver PDO ne supporte pas cette fonctionnalité, PDO::lastInsertId() lancera un SQLSTATE `IM001`.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

# PDO::prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)

PDO::prepare — Prépare une requête à l'exécution et retourne un objet

### Description

public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false

Prépare une requête SQL à être exécutée par la méthode PDOStatement::execute(). Le modèle de déclaration peut contenir zéro ou plusieurs paramètres nommés (`:nom`) ou marqueurs (`?`) pour lesquels les valeurs réelles seront substituées lorsque la requête sera exécutée. L'utilisation à la fois des paramètres nommés ainsi que les marqueurs est impossible dans un modèle de déclaration ; seul l'un ou l'autre style de paramètre. Il faut utiliser ces paramètres pour lier les entrées utilisateurs et ne pas les inclure directement dans la requête.

Il faut inclure un marqueur avec un nom unique pour chaque valeur que l'on souhaite passer dans la requête lorsque l'on appelle PDOStatement::execute(). Il n'est pas possible d'utiliser un marqueur avec deux noms identiques dans une requête préparée, à moins que le mode émulation ne soit actif.

> Note:

> Les marqueurs de paramètres peuvent représenter uniquement un littéral de données complet. Ni une partie de littéral, ni un mot clé, ni un identifiant, ni toute autre requête arbitraire ne peuvent être liés en utilisant les paramètres. Par exemple, il n'est pas possible d'associer plusieurs valeurs à un seul marqueur de nom entrant, dans la clause IN() d'une requête SQL.

Appeler PDO::prepare() et PDOStatement::execute() pour les requêtes qui doivent être exécutées plusieurs fois avec différentes valeurs de paramètres optimisent les performances de l'application en autorisant le pilote à négocier côté client et/ou serveur avec le cache des requêtes et les meta-informations. De plus appeler PDO::prepare() et PDOStatement::execute() aident à prévenir les attaques par injection SQL en éliminant le besoin de protéger les paramètres manuellement.

PDO émule les requêtes préparées / les paramètres liés pour les pilotes qui ne le supportent pas nativement, et peut également réécrire les paramètres nommés ou les marqueurs en quelque chose de plus approprié, si le pilote supporte un style et pas l'autre.

> Note: L'analyseur utilisé pour les déclarations préparées émulées et pour réécrire les paramètres nommés ou du style point d'interrogation supporte l'échappement antislash non standard pour les guillemets simples et doubles. Cela signifie que les guillemets de fin précédés d'un antislash ne sont pas reconnus comme tels, ce qui peut entraîner une mauvaise détection des paramètres provoquant l'échec de la déclaration préparée lors de son exécution. Un contournement est de ne pas utiliser les requêtes émulées pour de telles requêtes SQL, et d'éviter de réécrire les paramètres en utilisant un style de paramètre qui est supporté nativement par le pilote.

À partir de PHP 7.4.0, les points d'interrogation peuvent être échappés en les dédoublant. Cela signifie que la chaîne `??` sera traduite en `?` lors de l'envoi de la requête à la base de données.

### Liste de paramètres

`query`

  Doit être un modèle de requête SQL valide pour le serveur de base de données ciblée.

`options`

  Ce tableau contient une ou plusieurs paires clé=>valeur pour définir les valeurs des attributs pour l'objet PDOStatement que cette méthode retourne. Il est possible d'utiliser ceci pour définir la valeur `PDO::ATTR_CURSOR` à `PDO::CURSOR_SCROLL` pour demander un curseur scrollable. Quelques pilotes ont des options spécifiques qui peuvent être définies au moment de la préparation.

### Valeurs de retour

Si le serveur de base de données prépare avec succès cette requête, PDO::prepare() retourne un objet PDOStatement. Si le serveur de base de données ne réussit pas à préparer la requête, PDO::prepare() retourne `false` ou émet une exception PDOException (suivant le gestionnaire des erreurs).

> Note:

> L'émulation de requêtes préparées ne communique pas avec le serveur de base de données. Aussi, la fonction PDO::prepare() ne vérifie pas la requête.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Modèle de déclaration SQL avec des paramètres nommés

    <?php
    /* Exécute une requête préparée en passant un tableau de valeurs */
    $sql = 'SELECT nom, couleur, calories
        FROM fruit
    WHERE calories < :calories AND couleur = :couleur';
    $sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
    $sth->execute(['calories' => 150, 'couleur' => 'red']);
    $red = $sth->fetchAll();
    /* Les clés du tableau peuvent être préfixées par des deux-points ":" également (facultatif) */
    $sth->execute([':calories' => 175, ':couleur' => 'yellow']);
    $yellow = $sth->fetchAll();
    ?>

Exemple #2 Modèle de déclaration SQL avec des marqueurs

    <?php
    /* Exécute une requête préparée en passant un tableau de valeurs */
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < ? AND couleur = ?');
    $sth->execute([150, 'rouge']);
    $red = $sth->fetchAll();
    $sth->execute([175, 'jaune']);
    $yellow = $sth->fetchAll();
    ?>

Exemple #3 Modèle de déclaration SQL avec un point d'interrogation échappé

    <?php
    /* note: ceci n'est valable que pour les bases de données PostgreSQL */
    $sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
    $sth->execute(['feature']);
    $featureIssues = $sth->fetchAll();
    $sth->execute(['performance']);
    $performanceIssues = $sth->fetchAll();
    ?>

### Voir aussi

- PDO::exec() - Exécute une requête SQL et retourne le nombre de lignes affectées
- PDO::query() - Prépare et Exécute une requête SQL sans marque substitutive
- PDOStatement::execute() - Exécute une requête préparée

# PDO::query

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::query — Prépare et Exécute une requête SQL sans marque substitutive

### Description

public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false

PDO::query() prépare et exécute une requête SQL en un seul appel de fonction, retournant la requête en tant qu'objet PDOStatement.

Pour une requête qu'il faut exécuter plusieurs fois, on réalisera de meilleures performances si l'on prépare l'objet PDOStatement en utilisant la fonction PDO::prepare() et exécute la requête via plusieurs appels à la fonction PDOStatement::execute().

Si on ne récupère pas toutes les données du jeu de résultats avant d'exécuter le prochain appel à PDO::query(), l'appel peut échouer. Appeler PDOStatement::closeCursor() pour libérer les ressources de la base de données associées à l'objet PDOStatement avant d'exécuter le prochain appel à la fonction PDO::query().

> Note:

> Si `query` contient des marqueurs de substitution, la requête doit être préparée et exécutée séparément en utilisant les méthodes PDO::prepare() et PDOStatement::execute().

### Liste de paramètres

`query`

  La requête SQL à préparer et à exécuter.

  Si le SQL contient des marqueurs de substitution, PDO::prepare() et PDOStatement::execute() doivent être utilisés à la place. Alternativement, le SQL peut être préparé manuellement avant d'appeler PDO::query(), avec les données correctement formatées en utilisant PDO::quote() si le pilote le supporte.

`fetchMode`

  Le mode de récupération par défaut pour le PDOStatement retourné. Ceci doit être une des constantes `PDO::FETCH_*`.

  Si cet argument est passé à la fonction, le reste des arguments seront traités comme si PDOStatement::setFetchMode() avait été appelé sur l'objet de la requête résultante. Les arguments suivants dépendent du mode de récupération sélectionné.

### Valeurs de retour

Retourne un objet PDOStatement ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 SQL sans marqueurs de substitution peut être exécuté en utilisant PDO::query()

    <?php
    $sql =  'SELECT name, color, calories FROM fruit ORDER BY name';
    foreach  ($conn->query($sql) as $row) {
        print $row['name'] . "\t";
        print  $row['color'] . "\t";
        print $row['calories'] . "\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    apple   red     150
    banana  yellow  250
    kiwi    brown   75
    lemon   yellow  25
    orange  orange  300
    pear    green   150
    watermelon      pink    90

### Voir aussi

- PDO::exec() - Exécute une requête SQL et retourne le nombre de lignes affectées
- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::execute() - Exécute une requête préparée

# PDO::quote

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.1)

PDO::quote — Protège une chaîne pour l'utiliser dans une requête SQL PDO

### Description

public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false

PDO::quote() place des guillemets simples autour d'une chaîne d'entrée et protège les caractères spéciaux présents dans la chaîne d'entrée, en utilisant le style de protection approprié au pilote courant.

Lors de l'utilisation de cette fonction pour construire des requêtes SQL, l'on est vivement invités à utiliser PDO::prepare() pour préparer les requêtes SQL avec des paramètres liés au lieu d'utiliser PDO::quote() pour interpréter les entrées utilisateur dans la requête SQL. Les requêtes préparées avec des paramètres liés sont non seulement plus portables, plus souples et plus sécuritaires, mais bien plus rapides à exécuter que d'interpréter les requêtes, étant donné que les côtés client et serveur peuvent mettre en cache une version compilée de la requête.

Tous les pilotes PDO n'implémentent pas cette méthode (comme PDO_ODBC). Utiliser les requêtes préparées à la place.

Attention

# Sécurité : le jeu de caractères par défaut

Le jeu de caractères doit être défini soit au niveau du serveur, soit lors de la connexion à la base de données (suivant le driver utilisé) pour qu'il affecte la méthode PDO::quote(). Voir la documentation spécifique au driver pour plus d'informations.

### Liste de paramètres

`string`

  La chaîne à protéger.

`type`

  Le type de données pour les drivers qui ont des styles particuliers de protection. Fournit un indice au type de donnée pour les pilotes qui ont un style d'échappement différent. Par exemple `PDO_PARAM_LOB` indique au pilote d'échapper des données binaires.

### Valeurs de retour

Retourne une chaîne protégée, qui est théoriquement sûre à utiliser dans une requête SQL. Retourne `false` si le pilote ne supporte pas ce type de protections.

### Exemples

Exemple #1 Protection d'une chaîne normale

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Chaîne simple */
    $string = 'Nice';
    print "Chaîne non échappée : $string\n";
    print "Chaîne échappée : " . $conn->quote($string) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    Chaîne non échappée : Nice
    Chaîne échappée: 'Nice'

Exemple #2 Protection d'une chaîne dangereuse

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Chaîne dangereuse */
    $string = 'Chaîne \' particulière';
    print "Chaîne non échappée : $string\n";
    print "Chaîne échappée :" . $conn->quote($string) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    Chaîne non échappée : Chaîne ' particulière
    Chaîne échappée : 'Chaîne '' particulière'

Exemple #3 Protection d'une chaîne complexe

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Chaîne complexe */
    $string = "Co'mpl''exe \"ch'\"aîne";
    print "Chaîne non échappée : $string\n";
    print "Chaîne échappée : " . $conn->quote($string) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    Chaîne non échappée: Co'mpl''exe "ch'"aîne
    Chaîne échappée: 'Co''mpl''''exe "ch''"aîne'

### Voir aussi

- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::execute() - Exécute une requête préparée

# PDO::rollBack

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::rollBack — Annule une transaction

### Description

public function PDO::rollBack(): bool

Annule la transaction courante, initiée par la fonction PDO::beginTransaction().

Si la base de données est en mode autocommit, cette fonction restaurera le mode autocommit après l'annulation de la transaction.

Quelques bases de données, dont MySQL, exécuteront automatiquement un COMMIT lorsqu'une requête de définition de langage de base de données (DDL) comme DROP TABLE ou CREATE TABLE est exécutée dans une transaction. Ce COMMIT implicite empêchera d'annuler toutes autres modifications faites dans cette transaction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Une exception PDOException sera lancée si aucune transaction n'est active.

> Note: Une exception sera émise même si l'attribut `PDO::ATTR_ERRMODE` ne vaut pas `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Annulation d'une transaction

L'exemple suivant commence une transaction et exécute deux requêtes qui modifient la base de données avant d'annuler les modifications. Sur MySQL, cependant, la requête DROP TABLE validera automatiquement la transaction, donc, aucune des modifications de la transaction ne sera annulée.

    <?php
    /* Début d'une transaction, désactivation du mode autocommit */
    $dbh->beginTransaction();

    /* Modifie le schéma de la base de données ainsi que des données */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
        SET name = 'hamburger'");

    /* On s'aperçoit d'une erreur et on annule les modifications */
    $dbh->rollBack();

    /* La connexion à la base de données revient en mode autocommit */
    ?>

### Voir aussi

- PDO::beginTransaction() - Démarre une transaction
- PDO::commit() - Valide une transaction
- Transactions et auto-commit

# PDO::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::setAttribute — Configure un attribut PDO

### Description

public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool

Configure un attribut du gestionnaire de base de données. Certains des attributs génériques sont listés ci-dessous ; certains pilotes disposent de configurations supplémentaires. Il est à noter que les attributs spécifiques à un pilote ne doivent pas être utilisés avec d'autres pilotes.

`PDO::ATTR_CASE`

  Force les noms de colonnes à une casse particulière. Peut prendre une des valeurs suivantes :

  `PDO::CASE_LOWER`
    Force les noms de colonnes en minuscule.
  `PDO::CASE_NATURAL`
    Laisse les noms de colonnes tels que retournés par le pilote de base de données.
  `PDO::CASE_UPPER`
    Force les noms de colonnes en majuscule.
`PDO::ATTR_ERRMODE`

  Le mode pour reporter les erreurs de PDO. Peut prendre une des valeurs suivantes :

  `PDO::ERRMODE_SILENT`
    Définit juste les codes d'erreurs.
  `PDO::ERRMODE_WARNING`
    Émet des diagnostics `E_WARNING`.
  `PDO::ERRMODE_EXCEPTION`
    Lance des PDOExceptions.
`PDO::ATTR_ORACLE_NULLS`

  > Note: Cet attribut est disponible avec tous les pilotes, pas juste Oracle.

  Détermine si et comment `null` et les chaînes vides devraient être converties. Peut prendre une des valeurs suivantes :

  `PDO::NULL_NATURAL`
    Aucune conversion n'est effectuée.
  `PDO::NULL_EMPTY_STRING`
    Les chaînes vides sont converties en `null`.
  `PDO::NULL_TO_STRING`
    `null` est convertie en chaîne vide.
`PDO::ATTR_STRINGIFY_FETCHES`

  Contrôle si les valeurs récupérées (sauf `null`) sont converties en chaînes. Accepte une valeur de type bool : `true` pour activer et `false` pour désactiver (valeur par défaut). Les valeurs `null` restent inchangées, sauf si `PDO::ATTR_ORACLE_NULLS` est défini sur `PDO::NULL_TO_STRING`.

`PDO::ATTR_STATEMENT_CLASS`

  Configure la classe de résultat dérivée de PDOStatement et définie par l'utilisateur. Nécessite `array(string classname, array(mixed constructor_args))`.

  Attention

  Ne peut être utilisé avec les instances persistantes de PDO.

`PDO::ATTR_TIMEOUT`

  Spécifie la durée du timeout en secondes. Prend une valeur de type int.

  > Note:

  > Pas tous les pilotes supportent cette option, et sa signification peut différer en fonction des pilotes. Par exemple, SQLite attendra pendant cette période pour obtenir un verrou en écriture, mais d'autres pilotes peuvent interpréter ceci comme un timeout de connexion ou de lecture.

`PDO::ATTR_AUTOCOMMIT`

  > Note: Uniquement disponible pour les pilotes OCI, Firebird, et MySQL.

  Détermine si chaque requête est autocommit. Prend une valeur de type bool: `true` pour activer et `false` pour désactiver. Par défaut, `true`.

`PDO::ATTR_EMULATE_PREPARES`

  > Note: Uniquement disponible pour les pilotes OCI, Firebird, et MySQL.

  Configure l'activation ou désactivation des requêtes préparées émulées. Certains pilotes ne supportent pas les requêtes préparées nativement ou ont un support limité. Si défini à `true` PDO émulera toujours les requêtes préparées, sinon PDO tentera d'utiliser les requêtes préparées natives. Dans le cas où le pilote ne peut pas préparer la requête courante, PDO se rabattra toujours sur l'émulation des requêtes préparées.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`

  > Note: Uniquement disponible pour le pilote MySQL.

  Configure l'utilisation des requêtes tampons. Prend une valeur de type bool: `true` pour activer et `false` pour désactiver. Par défaut, `true`.

`PDO::ATTR_DEFAULT_FETCH_MODE`

  Définit le mode de récupération. Une description des modes et comment les utiliser est disponible sur la documentation de PDOStatement::fetch().

### Liste de paramètres

`attribute`

  L'attribut à modifier.

`value`

  La valeur à laquelle définir l'`attribute`, ceci peut nécessiter un type spécifique dépendant de l'attribut.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- PDO::getAttribute() - Récupère un attribut d'une connexion à une base de données
- PDOStatement::getAttribute() - Récupère un attribut de requête
- PDOStatement::setAttribute() - Définit un attribut de requête

## Sommaire

- PDO::beginTransaction — Démarre une transaction
- PDO::commit — Valide une transaction
- PDO::connect — Connecte à une base de données et retourne une sous-classe PDO pour les pilotes qui le supportent
- PDO::__construct — Crée une instance PDO qui représente une connexion à la base
- PDO::errorCode — Retourne le SQLSTATE associé avec la dernière opération sur la base de données
- PDO::errorInfo — Retourne les informations associées à l'erreur lors de la dernière opération sur la base de données
- PDO::exec — Exécute une requête SQL et retourne le nombre de lignes affectées
- PDO::getAttribute — Récupère un attribut d'une connexion à une base de données
- PDO::getAvailableDrivers — Retourne la liste des pilotes PDO disponibles
- PDO::inTransaction — Vérifie si l'on est dans une transaction
- PDO::lastInsertId — Retourne l'identifiant de la dernière ligne insérée ou la valeur d'une séquence
- PDO::prepare — Prépare une requête à l'exécution et retourne un objet
- PDO::query — Prépare et Exécute une requête SQL sans marque substitutive
- PDO::quote — Protège une chaîne pour l'utiliser dans une requête SQL PDO
- PDO::rollBack — Annule une transaction
- PDO::setAttribute — Configure un attribut PDO

# La classe PDOStatement

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Introduction

Représente une requête préparée et, une fois exécutée, le jeu de résultats associé.

## Synopsis de la classe

class PDOStatement implements IteratorAggregate {
/* Propriétés */
public string $queryString;
/* Méthodes */
public function bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool
public function closeCursor(): bool
public function columnCount(): int
public function debugDumpParams(): ?bool
public function errorCode(): ?string
public function errorInfo(): array
public function execute(?array `$params` = `null`): bool
public function fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed
public function fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array
public function fetchColumn(int `$column` = 0): mixed
public function fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false
public function getAttribute(int `$name`): mixed
public function getColumnMeta(int `$column`): array|false
public function getIterator(): Iterator
public function nextRowset(): bool
public function rowCount(): int
public function setAttribute(int `$attribute`, mixed `$value`): bool
public function setFetchMode(int `$mode`): true
public function setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true
}

## Propriétés

queryString

  chaîne de caractères utilisée pour la requête.

## Historique

Version | Description
--- | ---
8.0.0 | La classe PDOStatement implémente désormais IteratorAggregate au lieu de Traversable.

# PDOStatement::bindColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindColumn — Lie une colonne à une variable PHP

### Description

public function PDOStatement::bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

PDOStatement::bindColumn() fait en sorte qu'une variable PHP soit liée à une colonne données dans le jeu de résultats dans une requête. Chaque appel à la fonction PDOStatement::fetch() ou PDOStatement::fetchAll() met à jour toutes les variables qui sont liées aux colonnes.

> Note:

> Étant donné que les informations sur les colonnes ne sont pas toujours disponibles à PDO tant que la requête n'est pas exécutée, les applications portables doivent appeler cette fonction après la fonction PDOStatement::execute().

> Cependant, pour pouvoir lier une colonne de type LOB avec un flux lors de l'utilisation du pilote PostGreSQL, les applications doivent appeler cette méthode avant d'appeler PDOStatement::execute(), sous peine de recevoir l'objet OID sous forme d'entier.

### Liste de paramètres

`column`

  Numéro de la colonne (en commençant à 1) ou nom de la colonne dans le jeu de résultats. Lors de l'utilisation des noms de colonnes, il faut s'assurer que le nom corresponde à la casse de la colonne, comme retourné par le pilote.

`var`

  Nom de la variable PHP à laquelle la colonne doit être liée.

`type`

  Type du paramètre, spécifié par les constantes `PDO::PARAM_*`.

`maxLength`

  Une astuce pour la pré-allocation.

`driverOptions`

  Paramètres optionnels pour la bibliothèque.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Lie l'affichage du jeu de résultats à des variables PHP

Lier les colonnes du jeu de résultats aux variables PHP est une façon agréable de rendre les données contenues dans chaque ligne immédiatement disponibles à l'application. L'exemple suivant montre comment PDO autorise à lier et récupérer les colonnes avec une variété d'options.

    <?php
    $stmt = $dbh->prepare('SELECT name, colour, calories FROM fruit');
    $stmt->execute();

    /* Lie par les numéros de colonnes */
    $stmt->bindColumn(1, $name);
    $stmt->bindColumn(2, $colour);

    /* Lie par les noms de colonnes */
    $stmt->bindColumn('calories', $cals);
    while ($stmt->fetch(PDO::FETCH_BOUND)) {
        print $name . "\t" . $colour . "\t" . $cals . "\n";
    }
    readData($dbh);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    pomme   rouge     150
    banane  jaune  175
    kiwi    vert   75
    orange  orange  150
    mangue   rouge     200
    fraise      rouge     25

### Voir aussi

- PDOStatement::execute() - Exécute une requête préparée
- PDOStatement::fetch() - Récupère la ligne suivante d'un jeu de résultats PDO
- PDOStatement::fetchAll() - Récupère les lignes restantes d'un ensemble de résultats
- PDOStatement::fetchColumn() - Retourne une colonne depuis la ligne suivante d'un jeu de résultats

# PDOStatement::bindParam

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindParam — Lie un paramètre à un nom de variable spécifique

### Description

public function PDOStatement::bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

Lie une variable PHP à un marqueur nommé ou interrogatif correspondant dans une requête SQL utilisée pour préparer la requête. Contrairement à PDOStatement::bindValue(), la variable est liée en tant que référence et ne sera évaluée qu'au moment de l'appel à la fonction PDOStatement::execute().

La plupart des paramètres sont des paramètres d'entrées, et sont utilisés en lecture seule pour construire la requête (mais peuvent néanmoins être transtypés en fonction de `type`). Quelques drivers supportent l'invocation de procédures stockées qui retournent des données en tant que paramètres de sortie, et quelques autres en tant que paramètres entrées / sorties qui sont envoyés ensemble et sont mis à jour pour les recevoir.

### Liste de paramètres

`param`

  Identifiant. Pour une requête préparée utilisant des marqueurs nommés, ce sera le nom du paramètre sous la forme :name. Pour une requête préparée utilisant les marqueurs interrogatifs, ce sera la position indexée +1 du paramètre.

`var`

  Nom de la variable PHP à lier au paramètre de la requête SQL.

`type`

  Type explicite de données pour le paramètre utilisant les constantes `PDO::PARAM_*`. Pour retourner un paramètre INOUT depuis une procédure stockée, utiliser l'opérateur OR pour définir les bits `PDO::PARAM_INPUT_OUTPUT` pour le paramètre `type`.

`maxLength`

  Longueur du type de données. Pour indiquer qu'un paramètre est un paramètre OUT depuis une procédure stockée, il faut explicitement définir la longueur. Significatif uniquement lorsque le paramètre `type` est `PDO::PARAM_INPUT_OUTPUT`.

`driverOptions`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Exécution d'une requête préparée avec des emplacements nommés

    <?php
    /* Exécution d'une requête préparée en liant des variables PHP */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < :calories AND couleur = :couleur');
    $sth->bindParam('calories', $calories, PDO::PARAM_INT);
    /* Les noms peuvent aussi être préfixés par des deux-points ":" (facultatif) */
    $sth->bindParam(':couleur', $couleur, PDO::PARAM_STR);
    $sth->execute();
    ?>

Exemple #2 Exécution d'une requête préparée avec des marqueurs de positionnement

    <?php
    /* Exécution d'une requête préparée en liant des variables PHP */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < ? AND couleur = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindParam(2, $couleur, PDO::PARAM_STR);
    $sth->execute();
    ?>

Exemple #3 Appel d'une procédure stockée avec un paramètre INOUT

    <?php
    /* Appel d'une procédure stockée avec un paramètre INOUT */
    $couleur = 'rouge';
    $sth = $dbh->prepare('CALL puree_fruit(?)');
    $sth->bindParam(1, $couleur, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 12);
    $sth->execute();
    print "Après avoir pressé le fruit, la couleur est : $couleur";
    ?>

### Voir aussi

- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::execute() - Exécute une requête préparée
- PDOStatement::bindValue() - Associe une valeur à un paramètre

# PDOStatement::bindValue

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

PDOStatement::bindValue — Associe une valeur à un paramètre

### Description

public function PDOStatement::bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool

Associe une valeur à un nom correspondant ou à un point d'interrogation (comme paramètre fictif) dans la requête SQL qui a été utilisé pour préparer la requête.

### Liste de paramètres

`param`

  Identifiant du paramètre. Pour une requête préparée utilisant les marqueurs, cela sera un nom de paramètre de la forme :nom. Pour une requête préparée utilisant les points d'interrogation (comme paramètre fictif), cela sera la position du paramètre, indexée à partir de 1.

`value`

  La valeur à associer au paramètre.

`type`

  Type de données explicite pour le paramètre utilisant les constantes `PDO::PARAM_*`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Exécute une requête préparée avec des marqueurs nommés

    <?php
    /* Exécute une requête préparée en associant des variables PHP */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < :calories AND couleur = :couleur');

    /* Définit la valeur d'un paramètre en utilisant son nom */
    $sth->bindValue('calories', $calories, PDO::PARAM_INT);
    /* Optionnellement, les noms des paramètres peuvent être préfixés par des deux points " :" */
    $sth->bindValue(':couleur', $couleur, PDO::PARAM_STR);
    $sth->execute();
    ?>

Exemple #2 Exécute une requête préparée avec des points d'interrogation comme paramètre fictif

    <?php
    /* Exécute une requête préparée en associant des variables PHP */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < ? AND couleur = ?');
    $sth->bindValue(1, $calories, PDO::PARAM_INT);
    $sth->bindValue(2, $couleur, PDO::PARAM_STR);
    $sth->execute();
    ?>

### Voir aussi

- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::execute() - Exécute une requête préparée
- PDOStatement::bindParam() - Lie un paramètre à un nom de variable spécifique

# PDOStatement::closeCursor

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::closeCursor — Ferme le curseur, permettant à la requête d'être de nouveau exécutée

### Description

public function PDOStatement::closeCursor(): bool

PDOStatement::closeCursor() libère la connexion au serveur, permettant ainsi à d'autres requêtes SQL d'être exécutées, mais laisse la requête dans un état lui permettant d'être de nouveau exécutée.

Cette méthode est utile pour les drivers de base de données qui ne supportent pas l'exécution d'objet PDOStatement lorsqu'un objet PDOStatement exécuté précédemment a encore des lignes non récupérées. Si le driver de base de données souffre de cette limitation, le problème se manifestera de lui-même dans une erreur en dehors de la séquence.

PDOStatement::closeCursor() est implémenté soit en tant que méthode optionnelle spécifique au pilote, avec un maximum d'efficacité, ou en tant que solution générique si aucune fonction spécifique au pilote n'est installée. Sémantiquement, la fonction générique PDO revient à écrire le code suivant dans le script PHP :

    <?php
    do {
        while ($stmt->fetch())
            ;
        if (!$stmt->nextRowset())
            break;
    } while (true);
    ?>

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Exemple avec PDOStatement::closeCursor()

Dans l'exemple suivant, l'objet PDOStatement $stmt retourne de multiples lignes, mais l'application récupère uniquement la première ligne, laissant l'objet PDOStatement dans l'état où il lui reste des lignes non récupérées. Pour s'assurer que l'application fonctionnera avec tous les drivers de base de données, l'auteur insère un appel à la fonction PDOStatement::closeCursor() sur $stmt avant l'exécution d'objet PDOStatement $otherStmt.

    <?php
    /* Création d'un objet PDOStatement */
    $stmt = $dbh->prepare('SELECT foo FROM bar');

    /* Création d'un second objet PDOStatement */
    $otherStmt = $dbh->prepare('SELECT foobaz FROM foobar');

    /* Exécute la première requête */
    $stmt->execute();

    /* Récupération de la première ligne uniquement depuis le résultat */
    $stmt->fetch();

    /* L'appel suivant à closeCursor() peut être requis par quelques drivers */
    $stmt->closeCursor();

    /* Maintenant, nous pouvons exécuter la deuxième requête */
    $otherStmt->execute();
    ?>

### Voir aussi

- PDOStatement::execute() - Exécute une requête préparée

# PDOStatement::columnCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::columnCount — Retourne le nombre de colonnes dans le jeu de résultats

### Description

public function PDOStatement::columnCount(): int

Utiliser la fonction PDOStatement::columnCount() pour retourner le nombre de colonnes dans le jeu de résultats représenté par l'objet PDOStatement.

Si l'objet PDOStatement a été retourné par la fonction PDO::query(), le nombre de colonnes est immédiatement disponible.

Si l'objet PDOStatement a été retourné par la fonction PDO::prepare(), un compte précis des colonnes ne sera pas disponible tant que l'on n'invoquera pas la fonction PDOStatement::execute().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de colonnes dans le jeu de résultats représenté par l'objet PDOStatement, même si le jeu de résultats est vide. S'il n'y a pas de jeu de résultats, PDOStatement::columnCount() retournera `0`.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Comptage des colonnes

Cet exemple démontre comment PDOStatement::columnCount() fonctionne avec ou sans jeu de résultats.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    $sth = $dbh->prepare("SELECT nom, couleur FROM fruit");

    /* Compte le nombre de colonnes dans le jeu de résultats (inexistant) */
    $colcount = $sth->columnCount();
    print "Avant execute(), le jeu de résultats avait $colcount colonnes (devrait être 0)\n";

    $sth->execute();

    /* Compte le nombre de colonnes dans le jeu de résultats */
    $colcount = $sth->columnCount();
    print "Après execute(), le jeu de résultats a $colcount colonnes (devrait être 2)\n";

    ?>

L'exemple ci-dessus va afficher :

    Avant execute(), le jeu de résultats avait 0 colonnes (devrait être 0)
    Après execute(), le jeu de résultats a 2 colonnes (devrait être 2)

### Voir aussi

- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::execute() - Exécute une requête préparée
- PDOStatement::rowCount() - Retourne le nombre de lignes affectées par le dernier appel à la fonction PDOStatement::execute()

# PDOStatement::debugDumpParams

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::debugDumpParams — Détaille une commande préparée SQL

### Description

public function PDOStatement::debugDumpParams(): ?bool

Détaille les informations contenues dans une commande préparée, directement sur la sortie standard. Les informations sont notamment la requête `SQL` utilisée, le nombre de paramètres utilisés (`Params`), la liste des paramètres, avec le nom de clé ou leur position, leur nom, leur position dans la requête (si cette dernière information n'est pas supportée par le pilote PDO, c'est toujours -1), un type (`param_type`) sous forme d'entier, et une valeur booléenne `is_param`.

Ceci est une fonction de débogage, qui affiche directement des informations sur la sortie standard.

Astuce

Comme pour toutes les fonctions qui affichent directement des résultats au navigateur, les fonctions de gestion des sorties peuvent être utilisées pour capturer la sortie de cette fonction et l'enregistrer dans une chaîne de caractères (par exemple).

Les paramètres affichés sont ceux qui ont été ajoutés dans la requête jusqu'au moment de l'appel. Les paramètres surnuméraires sont ignorés.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `null`, ou `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
7.2.0 | PDOStatement::debugDumpParams() retourne maintenant le SQL envoyé à la base de données, y compris la requête complète, RAW (y compris les espaces réservés remplacés avec leurs valeurs délimitées). Il est à noter que cela ne sera disponible que si les instructions préparées émulées sont activées.

### Exemples

Exemple #1 Exemple avec PDOStatement::debugDumpParams() et des paramètres nommés

    <?php
    /* exécution d'une commande préparée avec liaison avec variables PHP */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');
    $sth->bindParam(':calories', $calories, PDO::PARAM_INT);
    $sth->bindValue(':colour', $colour, PDO::PARAM_STR, 12);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

L'exemple ci-dessus va afficher :

    SQL: [96] SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour
    Params:  2
    Key: Name: [9] :calories
    paramno=-1
    name=[9] ":calories"
    is_param=1
    param_type=1
    Key: Name: [7] :colour
    paramno=-1
    name=[7] ":colour"
    is_param=1
    param_type=2

Exemple #2 Exemple avec PDOStatement::debugDumpParams() et des paramètres anonymes

    <?php

    /* exécution d'une commande préparée avec liaison avec variables PHP */
    $calories = 150;
    $colour = 'red';
    $name = 'apple';

    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindValue(2, $colour, PDO::PARAM_STR);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

L'exemple ci-dessus va afficher :

    SQL: [82] SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?
    Params:  2
    Key: Position #0:
    paramno=0
    name=[0] ""
    is_param=1
    param_type=1
    Key: Position #1:
    paramno=1
    name=[0] ""
    is_param=1
    param_type=2

### Voir aussi

- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::bindParam() - Lie un paramètre à un nom de variable spécifique
- PDOStatement::bindValue() - Associe une valeur à un paramètre

# PDOStatement::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorCode — Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête

### Description

public function PDOStatement::errorCode(): ?string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Identique à PDO::errorCode(), excepté que PDOStatement::errorCode() récupère uniquement les codes erreurs pour les opérations sur les objets PDOStatement.

### Exemples

Exemple #1 Détermine la catégorie de l'erreur qui survient

    <?php
    /* Provoque une erreur -- la table BONES n'existe pas */
    $err = $dbh->prepare('SELECT skull FROM bones');
    $err->execute();

    echo "\nPDOStatement::errorCode(): ";
    print $err->errorCode();
    ?>

L'exemple ci-dessus va afficher :

    PDOStatement::errorCode(): 42S02

### Voir aussi

- PDO::errorCode() - Retourne le SQLSTATE associé avec la dernière opération sur la base de données
- PDO::errorInfo() - Retourne les informations associées à l'erreur lors de la dernière opération sur la base de données
- PDOStatement::errorInfo() - Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête

# PDOStatement::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorInfo — Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête

### Description

public function PDOStatement::errorInfo(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

PDOStatement::errorInfo() retourne un tableau contenant des informations sur l'erreur survenue lors de la dernière opération exécutée par ce gestionnaire de requêtes. Le tableau contient les champs suivants :

Élément | Information
--- | ---
0 | Code erreur SQLSTATE (un identifiant de cinq caractères alphanumériques défini dans le standard ANSI SQL)
1 | Code erreur spécifique au driver.
2 | Message d'erreur spécifique au driver.

### Exemples

Exemple #1 Affiche les champs de errorInfo() pour une connexion PDO_ODBC sur une base de données DB2

    <?php
    /* Provoque une erreur -- la table BONES n'existe pas */
    $sth = $dbh->prepare('SELECT skull FROM bones');
    $sth->execute();

    echo "\nPDOStatement::errorInfo():\n";
    $arr = $sth->errorInfo();
    print_r($arr);
    ?>

L'exemple ci-dessus va afficher :

    PDOStatement::errorInfo():
    Array
    (
        [0] => 42S02
        [1] => -204
        [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "DANIELS.BONES" is an undefined name.  SQLSTATE=42704
    )

### Voir aussi

- PDO::errorCode() - Retourne le SQLSTATE associé avec la dernière opération sur la base de données
- PDO::errorInfo() - Retourne les informations associées à l'erreur lors de la dernière opération sur la base de données
- PDOStatement::errorCode() - Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête

# PDOStatement::execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::execute — Exécute une requête préparée

### Description

public function PDOStatement::execute(?array `$params` = `null`): bool

Exécute une requête préparée. Si la requête préparée inclut des marqueurs de positionnement, il est possible de :

- PDOStatement::bindParam() et/ou PDOStatement::bindValue() doit être appelé pour lier des variables ou des valeurs (respectivement) aux marqueurs de paramètres. Les variables liées passent leurs valeurs en entrée et reçoivent les valeurs de sortie, s'il y en a, de leurs marqueurs de positionnement respectifs

- ou passer un tableau de valeurs de paramètres, uniquement en entrée

### Liste de paramètres

`params`

  Un tableau de valeurs avec autant d'éléments qu'il y a de paramètres à associer dans la requête SQL qui sera exécutée. Toutes les valeurs sont traitées comme des constantes `PDO::PARAM_STR`.

  Les valeurs multiples ne peuvent pas être liées à un seul paramètre; par exemple, il n'est pas autorisé de lier deux valeurs à un seul paramètre nommé dans une clause IN().

  La liaison de plus de valeurs que spécifié n'est pas possible ; s'il y a plus de clés dans `params` que dans le code SQL utilisé pour PDO::prepare(), alors la requête préparée échouera et une erreur sera levée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Exécute une requête préparée avec des variables et valeurs liées

    <?php
    /* Exécute une requête préparée en liant des variables et valeurs */
    $calories = 150;
    $couleur = 'ver';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < :calories AND couleur LIKE :couleur');
    $sth->bindParam('calories', $calories, PDO::PARAM_INT);
    /* Les noms peuvent aussi être préfixés par des deux-points ":" (facultatif) */
    $sth->bindValue(':couleur', "%$couleur%");
    $sth->execute();
    ?>

Exemple #2 Exécute une requête préparée avec un tableau de valeurs nommées

    <?php
    /* Exécute une requête préparée en passant un tableau de valeurs */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < :calories AND couleur = :couleur');
    $sth->execute(array('calories' => $calories, 'couleur' => $couleur));
    /* Les clés du tableau peuvent aussi être préfixées par des deux-points ":" (facultatif) */
    $sth->execute(array(':calories' => $calories, ':couleur' => $couleur));
    ?>

Exemple #3 Exécute une requête préparée avec un tableau de valeurs positionnelles

    <?php
    /* Exécute une requête préparée en passant un tableau de valeurs */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < ? AND couleur = ?');
    $sth->execute(array($calories, $couleur));
    ?>

Exemple #4 Exécute une requête préparée avec des variables liées à un marqueur de positionnement

    <?php
    /* Exécute une requête préparée en liant des variables PHP */
    $calories = 150;
    $couleur = 'rouge';
    $sth = $dbh->prepare('SELECT nom, couleur, calories
        FROM fruit
        WHERE calories < ? AND couleur = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindParam(2, $couleur, PDO::PARAM_STR, 12);
    $sth->execute();
    ?>

Exemple #5 Exécute une requête préparée en utilisant un tableau pour les clauses IN

    <?php
    /* Exécute une commande préparée en utilisant un tableau de valeurs pour les clauses IN */
    $params = array(1, 21, 63, 171);
    /* Crée une chaîne pour les marqueurs */
    $place_holders = '?' . str_repeat(', ?', count($params) - 1);

    /*
        Ce morceau de code va préparer la requête avec assez de marqueurs pour chaque valeur
        du tableau $params. Les valeurs du tableau $params sont ensuite liées aux marqueurs
        de la requête préparée lorsque la requête est exécutée. Ce n'est pas la même chose
        que d'utiliser la méthode PDOStatement::bindParam() sachant qu'elle impose une
        référence vers les valeurs. La méthode PDOStatement::execute() ne fait que lier
        par la valeur.
    */
    $sth = $dbh->prepare("SELECT id, name FROM contacts WHERE id IN ($place_holders)");
    $sth->execute($params);
    ?>

### Notes

> Note:

> Quelques drivers nécessitent de fermer le curseur avant d'exécuter la requête suivante.

### Voir aussi

- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::bindParam() - Lie un paramètre à un nom de variable spécifique
- PDOStatement::fetch() - Récupère la ligne suivante d'un jeu de résultats PDO
- PDOStatement::fetchAll() - Récupère les lignes restantes d'un ensemble de résultats
- PDOStatement::fetchColumn() - Retourne une colonne depuis la ligne suivante d'un jeu de résultats

# PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — Récupère la ligne suivante d'un jeu de résultats PDO

### Description

public function PDOStatement::fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed

Récupère une ligne depuis un jeu de résultats associé à l'objet `PDOStatement`. Le paramètre `mode` détermine la façon dont PDO retourne la ligne.

### Liste de paramètres

`mode`

  Contrôle comment la prochaine ligne sera retournée à l'appelant. Cette valeur doit être une des constantes `PDO::FETCH_*`, et par défaut, vaut la valeur de `PDO::ATTR_DEFAULT_FETCH_MODE` (qui vaut par défaut la valeur de la constante `PDO::FETCH_BOTH`).

  - `PDO::FETCH_ASSOC`: retourne un tableau indexé par le nom de la colonne comme retourné dans le jeu de résultats

  - `PDO::FETCH_BOTH` (défaut): retourne un tableau indexé par les noms de colonnes et aussi par les numéros de colonnes, commençant à l'index 0, comme retournés dans le jeu de résultats

  - `PDO::FETCH_BOUND`: retourne `true` et assigne les valeurs des colonnes du jeu de résultats dans les variables PHP auxquelles elles sont liées avec la méthode PDOStatement::bindColumn()

  - `PDO::FETCH_CLASS`: retourne une nouvelle instance de la classe demandée. L'objet est initialisé en mappant les colonnes du jeu de résultats aux propriétés de la classe. Ce processus se produit avant que le constructeur ne soit appelé, permettant la population des propriétés, indépendamment de leur visibilité ou de leur marqueur comme `readonly`. Si une propriété n'existe pas dans la classe, la méthode magique __set() sera invoquée si elle existe ; sinon, une propriété publique dynamique sera créée. Cependant, lorsque `PDO::FETCH_PROPS_LATE` est également spécifié, le constructeur est appelé avant que les propriétés soient peuplées.

  - `PDO::FETCH_INTO` : met à jour une instance existante de la classe demandée, liant les colonnes du jeu de résultats aux noms des propriétés de la classe

  - `PDO::FETCH_LAZY` : combine `PDO::FETCH_BOTH` et `PDO::FETCH_OBJ`, et renvoie un objet PDORow qui crée les noms de propriété de l'objet au fur et à mesure de leur accès.

  - `PDO::FETCH_NAMED` : retourne un tableau de la même forme que `PDO::FETCH_ASSOC`, excepté que s'il y a plusieurs colonnes avec les mêmes noms, la valeur pointée par cette clé sera un tableau de toutes les valeurs de la ligne qui a ce nom comme colonne

  - `PDO::FETCH_NUM` : retourne un tableau indexé par le numéro de la colonne comme elle est retournée dans le jeu de résultats, commençant à 0

  - `PDO::FETCH_OBJ` : retourne un objet anonyme avec les noms de propriétés qui correspondent aux noms des colonnes retournés dans le jeu de résultats

  - `PDO::FETCH_PROPS_LATE` : lorsqu'il est utilisé avec `PDO::FETCH_CLASS`, le constructeur de la classe est appelé avant que les propriétés ne soient assignées à partir des valeurs de colonne respectives.

`cursorOrientation`

  Pour un objet PDOStatement représentant un curseur scrollable, cette valeur détermine quelle ligne sera retournée à l'appelant. Cette valeur doit être une des constantes `PDO::FETCH_ORI_*`, et par défaut, vaut `PDO::FETCH_ORI_NEXT`. Pour demander un curseur scrollable pour l'objet PDOStatement, il faut définir l'attribut `PDO::ATTR_CURSOR` à `PDO::CURSOR_SCROLL` lorsque l'on prépare la requête SQL avec la fonction PDO::prepare().

`cursorOffset`

  Pour un objet PDOStatement représentant un curseur scrollable pour lequel le paramètre `cursorOrientation` est défini à `PDO::FETCH_ORI_ABS`, cette valeur spécifie le numéro absolu de la ligne dans le jeu de résultats qui doit être récupérée.

  Pour un objet PDOStatement représentant un curseur scrollable pour lequel le paramètre `cursorOrientation` est défini à `PDO::FETCH_ORI_REL`, cette valeur spécifie la ligne à récupérer relativement à la position du curseur avant l'appel à la fonction PDOStatement::fetch().

### Valeurs de retour

La valeur retournée par cette fonction en cas de succès dépend du type récupéré. Dans tous les cas, `false` est retourné si une erreur survient ou s'il n'y a plus de lignes.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Récupération de lignes en utilisant différentes méthodes

    <?php
    $sth = $dbh->prepare("SELECT nom, couleur FROM fruit");
    $sth->execute();

    /* styles PDOStatement::fetch */
    print "PDO::FETCH_ASSOC: ";
    print "Retourne la ligne suivante en tant qu'un tableau indexé par le nom des colonnes\n";
    $result = $sth->fetch(PDO::FETCH_ASSOC);
    print_r($result);
    print "\n";

    print "PDO::FETCH_BOTH: ";
    print "Retourne la ligne suivante en tant qu'un tableau indexé par le nom et le numéro de la colonne\n";
    $result = $sth->fetch(PDO::FETCH_BOTH);
    print_r($result);
    print "\n";

    print "PDO::FETCH_LAZY: ";
    print "Retourne la ligne suivante en tant qu'objet PDORow ayant les noms de colonnes comme propriétés\n";
    $result = $sth->fetch(PDO::FETCH_LAZY);
    print_r($result);
    print "\n";

    print "PDO::FETCH_OBJ: ";
    print "Retourne la ligne suivante en tant qu'objet anonyme ayant les noms de colonnes comme propriétés\n";
    $result = $sth->fetch(PDO::FETCH_OBJ);
    print $result->nom;
    print "\n";
    ?>

L'exemple ci-dessus va afficher :

    PDO::FETCH_ASSOC: Retourne la ligne suivante en tant qu'un tableau indexé par le nom des colonnes
    Array
    (
        [nom] => apple
        [couleur] => red
    )

    PDO::FETCH_BOTH: Retourne la ligne suivante en tant qu'un tableau indexé par le nom et le numéro de la colonne
    Array
    (
        [nom] => banana
        [0] => banana
        [couleur] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Retourne la ligne suivante en tant qu'objet PDORow ayant les noms de colonnes comme propriétés PDORow Object
    (
        [nom] => orange
        [couleur] => orange
    )

    PDO::FETCH_OBJ: Retourne la ligne suivante en tant qu'objet anonyme ayant les noms de colonnes comme propriétés kiwi

Exemple #2 Récupération des lignes avec un curseur scrollable

    <?php
    function readDataForwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        }
    }
    function readDataBackwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
        do {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        } while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
    }

    print "Lecture en avant :\n";
    readDataForwards($conn);

    print "Lecture en arrière :\n";
    readDataBackwards($conn);
    ?>

L'exemple ci-dessus va afficher :

    Lecture en avant :
    21    10    5
    16    0     5
    19    20    10

    Lecture en arrière :
    19    20    10
    16    0     5
    21    10    5

Exemple #3 Ordre de construction

Lorsque des objets sont récupérés via `PDO::FETCH_CLASS`, les propriétés de l'objet sont assignées en premier, puis le constructeur de la classe est appelé. Cependant, lorsque `PDO::FETCH_PROPS_LATE` est également spécifié, cet ordre est inversé, c'est-à-dire que le constructeur est d'abord appelé, puis les propriétés sont assignées.

    <?php
    class Person
    {
        private $name;

        public function __construct()
        {
            $this->tell();
        }

        public function tell()
        {
            if (isset($this->name)) {
                echo "Je suis {$this->name}.\n";
            } else {
                echo "Je n'ai pas encore de nom.\n";
            }
        }
    }

    $sth = $dbh->query("SELECT * FROM people");
    $sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
    $person = $sth->fetch();
    $person->tell();
    $sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
    $person = $sth->fetch();
    $person->tell();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Je suis Alice.
    Je suis Alice.
    Je n'ai pas encore de nom.
    Je suis Bob.

### Voir aussi

- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::execute() - Exécute une requête préparée
- PDOStatement::fetchAll() - Récupère les lignes restantes d'un ensemble de résultats
- PDOStatement::fetchColumn() - Retourne une colonne depuis la ligne suivante d'un jeu de résultats
- PDOStatement::fetchObject() - Récupère la prochaine ligne et la retourne en tant qu'objet
- PDOStatement::setFetchMode() - Définit le mode de récupération par défaut pour cette requête

# PDOStatement::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetchAll — Récupère les lignes restantes d'un ensemble de résultats

### Description

public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array

### Liste de paramètres

`mode`

  Contrôle le contenu du tableau retourné comme documenté dans la fonction PDOStatement::fetch(). Valeur par défaut : `PDO::ATTR_DEFAULT_FETCH_MODE` (qui prend sa valeur par défaut de `PDO::FETCH_BOTH`).

  Pour retourner un tableau contenant toutes les valeurs d'une seule colonne depuis le jeu de résultats, spécifiez `PDO::FETCH_COLUMN`. Il est possible de spécifier quelle colonne l'on veut avec le paramètre `column`.

  Pour indexer le tableau résultant par la valeur d'une certaine colonne (plutôt que par des nombres consécutifs), placez le nom de cette colonne en premier dans la liste des colonnes en SQL, et utiliser `PDO::FETCH_UNIQUE`. Cette colonne doit contenir uniquement des valeurs uniques, sinon certaines données seront perdues.

  Pour regrouper les résultats sous la forme d'un tableau à trois dimensions indexé par les valeurs d'une colonne spécifiée, placez le nom de cette colonne en premier dans la liste des colonnes en SQL et utiliser `PDO::FETCH_GROUP`.

  Pour regrouper les résultats sous la forme d'un tableau à deux dimensions, utiliser un OU bit-à-bit avec `PDO::FETCH_GROUP` et `PDO::FETCH_COLUMN`. Les résultats seront regroupés par la première colonne, la valeur de l'élément du tableau étant une liste d'entrées correspondantes de la seconde colonne.

Les paramètres suivants sont dynamiques et dépendent du mode de récupération. Ils ne peuvent pas être utilisés avec des paramètres nommés.

`column`

  Utilisé avec `PDO::FETCH_COLUMN`. Renvoie la colonne indiquée indexée à 0.

`class`

  Utilisé avec `PDO::FETCH_CLASS`. Renvoie des instances de la classe spécifiée, en faisant correspondre les colonnes de chaque ligne à des propriétés nommées dans la classe.

`constructorArgs`

  Arguments du constructeur personnalisé de la classe lorsque l'argument `mode` est à `PDO::FETCH_CLASS`.

`callback`

  Utilisé avec `PDO::FETCH_FUNC`. Renvoie les résultats de l'appel de la fonction spécifiée, en utilisant les colonnes de chaque ligne comme paramètres dans l'appel.

### Valeurs de retour

PDOStatement::fetchAll() retourne un tableau contenant toutes les lignes du jeu d'enregistrements. Le tableau représente chaque ligne comme soit un tableau de valeurs des colonnes, soit un objet avec des propriétés correspondant à chaque nom de colonne. Un tableau vide est retourné s'il y a zéro résultat.

L'utilisation de cette méthode pour récupérer de gros jeux de résultats peut entraîner une charge importante sur les ressources du système et du réseau. Plutôt que de récupérer toutes les données et de les manipuler avec PHP, utiliser le serveur de base de données pour manipuler les jeux de résultats. Par exemple, utiliser les clauses `WHERE` et `ORDER BY` dans les requêtes SQL pour restreindre les résultats avant de les récupérer et de les traiter avec PHP.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette méthode retourne désormais toujours un tableau, auparavant `false` pouvait être retourné en cas d'échec.

### Exemples

Exemple #1 Récupération de toutes les lignes d'un jeu de résultats

    <?php
    $sth = $dbh->prepare("SELECT nom, couleur FROM fruit");
    $sth->execute();

    /* Récupération de toutes les lignes d'un jeu de résultats */
    print "Récupération de toutes les lignes d'un jeu de résultats :\n";
    $result = $sth->fetchAll();
    print_r($result);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Récupération de toutes les lignes d'un jeu de résultats :
    Array
    (
        [0] => Array
            (
                [nom] => apple
                [0] => apple
                [couleur] => red
                [1] => red
            )

        [1] => Array
            (
                [nom] => pear
                [0] => pear
                [couleur] => green
                [1] => green
            )

        [2] => Array
            (
                [nom] => watermelon
                [0] => watermelon
                [couleur] => pink
                [1] => pink
            )

    )

Exemple #2 Récupération de toutes les valeurs d'une seule colonne depuis un jeu de résultats

L'exemple suivant montre comment retourner toutes les valeurs d'une seule colonne depuis un jeu de résultats, même si la requête SQL retourne plusieurs colonnes par lignes.

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Récupération de toutes les valeurs de la première colonne */
    $result = $sth->fetchAll(PDO::FETCH_COLUMN, 0);
    var_dump($result);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array(3)
    (
        [0] =>
        string(5) => apple
        [1] =>
        string(4) => pear
        [2] =>
        string(10) => watermelon
    )

Exemple #3 Grouper toutes les valeurs d'une seule colonne

L'exemple suivant montre comment retourner un tableau associatif groupé par les valeurs de la colonne spécifiée d'un jeu de résultats. Le tableau contient trois clés : les valeurs `apple` et `pear` sont retournées sous la forme de tableaux qui contiennent deux couleurs différentes, tandis que `watermelon` est retourné sous la forme d'un tableau qui contient uniquement une seule couleur.

    <?php
    $insert = $dbh->prepare("INSERT INTO fruit(name, colour) VALUES (?, ?)");
    $insert->execute(array('apple', 'green'));
    $insert->execute(array('pear', 'yellow'));

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Grouper les valeurs de la première colonne */
    var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(3) {
      ["apple"]=>
        array(2) {
          [0]=>
            string(5) "green"
          [1]=>
            string(3) "red"
        }
      ["pear"]=>
        array(2) {
          [0]=>
            string(5) "green"
          [1]=>
            string(6) "yellow"
        }
      ["watermelon"]=>
        array(1) {
          [0]=>
            string(5) "pink"
        }
    }

Exemple #4 Instancier une classe pour chaque résultat

L'exemple suivant montre le comportement de `PDO::FETCH_CLASS`.

    <?php
    class fruit {
        public $name;
        public $colour;
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_CLASS, "fruit");
    var_dump($result);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(3) {
      [0]=>
      object(fruit)#1 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(5) "green"
      }
      [1]=>
      object(fruit)#2 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(6) "yellow"
      }
      [2]=>
      object(fruit)#3 (2) {
        ["name"]=>
        string(10) "watermelon"
        ["colour"]=>
        string(4) "pink"
      }
      [3]=>
      object(fruit)#4 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(3) "red"
      }
      [4]=>
      object(fruit)#5 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(5) "green"
      }
    }

Exemple #5 Appel d'une fonction pour chaque résultat

L'exemple suivant montre le comportement de `PDO::FETCH_FUNC`.

    <?php
    function fruit($name, $colour) {
        return "{$name}: {$colour}";
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_FUNC, "fruit");
    var_dump($result);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(3) {
      [0]=>
      string(12) "apple: green"
      [1]=>
      string(12) "pear: yellow"
      [2]=>
      string(16) "watermelon: pink"
      [3]=>
      string(10) "apple: red"
      [4]=>
      string(11) "pear: green"
    }

### Voir aussi

- PDO::query() - Prépare et Exécute une requête SQL sans marque substitutive
- PDOStatement::fetch() - Récupère la ligne suivante d'un jeu de résultats PDO
- PDOStatement::fetchColumn() - Retourne une colonne depuis la ligne suivante d'un jeu de résultats
- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::setFetchMode() - Définit le mode de récupération par défaut pour cette requête

# PDOStatement::fetchColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::fetchColumn — Retourne une colonne depuis la ligne suivante d'un jeu de résultats

### Description

public function PDOStatement::fetchColumn(int `$column` = 0): mixed

Retourne une colonne depuis la ligne suivante d'un jeu de résultats ou `false` s'il n'y a plus de ligne.

> Note:

> PDOStatement::fetchColumn() ne doit pas être utilisé pour récupérer des colonnes contenant des booléens, car il n'est pas possible de distinguer une valeur `false` d'un retour avec aucune ligne à récupérer. Utiliser PDOStatement::fetch() à la place.

### Liste de paramètres

`column`

  Numéro de la colonne que l'on veut récupérer depuis la ligne (commençant à 0). Si aucune valeur n'est fournie, PDOStatement::fetchColumn() récupérera la première colonne.

### Valeurs de retour

PDOStatement::fetchColumn() retourne une colonne depuis la ligne suivante d'un jeu de résultats ou `false` s'il n'y a plus de lignes.

Avertissement

Il n'y a pas de solution pour retourner une autre colonne depuis la même ligne lors de l'utilisation de la fonction PDOStatement::fetchColumn() pour récupérer les données.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Retourne la première colonne de la ligne suivante

    <?php
    $sth = $dbh->prepare("SELECT nom, couleur FROM fruit");
    $sth->execute();

    /* Récupère la première colonne depuis la première ligne d'un jeu de résultats */
    print "Récupère la première colonne depuis la première ligne d'un jeu de résultats :\n";
    $result = $sth->fetchColumn();
    print "nom=$result\n";

    print "Récupère la deuxième colonne depuis la seconde ligne d'un jeu de résultats :\n";
    $result = $sth->fetchColumn(1);
    print "couleur=$result\n";
    ?>

L'exemple ci-dessus va afficher :

    Récupère la première colonne depuis la première ligne d'un jeu de résultats :
    nom=lemon
    Récupère la deuxième colonne depuis la seconde ligne d'un jeu de résultats :
    couleur=orange

### Voir aussi

- PDO::query() - Prépare et Exécute une requête SQL sans marque substitutive
- PDOStatement::fetch() - Récupère la ligne suivante d'un jeu de résultats PDO
- PDOStatement::fetchAll() - Récupère les lignes restantes d'un ensemble de résultats
- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::setFetchMode() - Définit le mode de récupération par défaut pour cette requête

# PDOStatement::fetchObject

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.4)

PDOStatement::fetchObject — Récupère la prochaine ligne et la retourne en tant qu'objet

### Description

public function PDOStatement::fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false

Récupère la prochaine ligne et la retourne en tant qu'objet. Cette fonction est une alternative à PDOStatement::fetch() avec `PDO::FETCH_CLASS` ou le style `PDO::FETCH_OBJ`.

Lorsqu'un objet est récupéré, ses propriétés sont assignées à partir des valeurs de colonne respectives, et ensuite son constructeur est appelé.

### Liste de paramètres

`class`

  Nom de la classe créée.

`constructorArgs`

  Les éléments de ce tableau sont passés au constructeur.

### Valeurs de retour

Retourne une instance de la classe demandée avec les propriétés de noms qui correspondent aux noms des colonnes ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Voir aussi

- PDOStatement::fetch() - Récupère la ligne suivante d'un jeu de résultats PDO

# PDOStatement::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getAttribute — Récupère un attribut de requête

### Description

public function PDOStatement::getAttribute(int `$name`): mixed

Récupère un attribut de la requête. Actuellement, aucun attribut générique n'existe, mais uniquement des spécificités du driver :

- `PDO::ATTR_CURSOR_NAME` (spécificité de Firebird et d'ODBC) : Récupère le nom du curseur pour `UPDATE ... WHERE CURRENT OF`.

Il est à noter que les attributs spécifiques au pilote ne doivent pas être utilisés avec d'autres pilotes.

### Liste de paramètres

`name`

  L'attribut à interroger.

### Valeurs de retour

Retourne la valeur de l'attribut.

### Voir aussi

- PDO::getAttribute() - Récupère un attribut d'une connexion à une base de données
- PDO::setAttribute() - Configure un attribut PDO
- PDOStatement::setAttribute() - Définit un attribut de requête

# PDOStatement::getColumnMeta

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getColumnMeta — Retourne les métadonnées pour une colonne d'un jeu de résultats

### Description

public function PDOStatement::getColumnMeta(int `$column`): array|false

Récupère les métadonnées pour une colonne d'un jeu de résultats dans un tableau associatif.

Avertissement

Certains pilotes peuvent ne pas implémenter la fonction PDOStatement::getColumnMeta(), car elle est facultative. Cependant, tous les pilotes PDO documentés dans le manuel implémentent cette fonction.

### Liste de paramètres

`column`

  Le nom de la colonne dans le jeu de résultats.

### Valeurs de retour

Retourne un tableau associatif contenant les valeurs suivantes représentant les métadonnées pour une colonne :

Métadonnées d'une colonne
Nom | Valeur
--- | ---
`native_type` | Le type natif PHP utilisé pour représenter la valeur de la colonne.
`driver:decl_type` | Le type SQL utilisé pour représenter la valeur de la colonne dans la base de données. Si la colonne du jeu de résultats est le résultat d'une fonction, cette valeur n'est pas retournée par la fonction PDOStatement::getColumnMeta().
`flags` | N'importe quelle balise définie pour cette colonne.
`name` | Le nom de cette colonne, comme retourné par la base de données.
`table` | Le nom de la table de cette colonne, tel que retourné par la base de données.
`len` | La longueur de cette colonne. Normalement, `-1` pour les types autres que les nombres décimaux à virgule flottante.
`precision` | La précision numérique pour cette colonne. Normalement, `0` pour les types autres que les nombres décimaux à virgule flottante.
`pdo_type` | Le type de cette colonne comme représenté par la constante `PDO::PARAM_*`.

Retourne `false` si la colonne demandée n'existe pas dans le jeu de résultats, ou si aucun jeu de résultats n'existe.

### Exemples

Exemple #1 Récupération des métadonnées pour une colonne

L'exemple suivant montre le résultat de la récupération des métadonnées pour une colonne générée par une fonction (COUNT) dans un pilote PDO_SQLITE.

    <?php
    $select = $DB->query('SELECT COUNT(*) FROM fruit');
    $meta = $select->getColumnMeta(0);
    var_dump($meta);
    ?>

L'exemple ci-dessus va afficher :

    array(6) {
       ["native_type"]=>
       string(7) "integer"
       ["flags"]=>
          array(0) {
          }
       ["name"]=>
       string(8) "COUNT(*)"
       ["len"]=>
       int(-1)
       ["precision"]=>
       int(0)
       ["pdo_type"]=>
       int(2)
    }

### Voir aussi

- PDOStatement::columnCount() - Retourne le nombre de colonnes dans le jeu de résultats
- PDOStatement::rowCount() - Retourne le nombre de lignes affectées par le dernier appel à la fonction PDOStatement::execute()

# PDOStatement::getIterator

(PHP 8)

PDOStatement::getIterator — Renvoie un itérateur sur le jeu de résultats

### Description

public function PDOStatement::getIterator(): Iterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# PDOStatement::nextRowset

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::nextRowset — Avance à la prochaine ligne de résultats d'un gestionnaire de lignes de résultats multiples

### Description

public function PDOStatement::nextRowset(): bool

Quelques bases de données supportent les procédures stockées qui retournent plus d'une ligne de résultats (aussi connu comme des jeux de résultats). PDOStatement::nextRowset() permet d'accéder à la seconde et suivantes lignes de résultats associées avec l'objet PDOStatement. Chaque ligne de résultats a des jeux différents de colonnes depuis la ligne de résultats.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Récupération de multiples lignes de résultats retournées par une procédure stockée

L'exemple suivant montre comment appeler une procédure stockée, `MULTIPLE_ROWSETS`, qui retourne trois lignes de résultats. Une boucle do-while est utilisée pour parcourir la méthode PDOStatement::nextRowset(), qui retourne `false` et termine la boucle quand il n'y a plus de ligne de résultats disponible.

    <?php
    $sql = 'CALL multiple_rowsets()';
    $stmt = $conn->query($sql);
    $i = 1;
    do {
        $rowset = $stmt->fetchAll(PDO::FETCH_NUM);
        if ($rowset) {
            printResultSet($rowset, $i);
        }
        $i++;
    } while ($stmt->nextRowset());

    function printResultSet(&$rowset, $i) {
        print "Jeu de résultats $i:\n";
        foreach ($rowset as $row) {
            foreach ($row as $col) {
                print $col . "\t";
            }
            print "\n";
        }
        print "\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    Jeu de résultats 1:
    apple    red
    banana   yellow

    Jeu de résultats 2:
    orange   orange    150
    banana   yellow    175

    Jeu de résultats 3:
    lime     green
    apple    red
    banana   yellow

### Voir aussi

- PDOStatement::columnCount() - Retourne le nombre de colonnes dans le jeu de résultats
- PDOStatement::execute() - Exécute une requête préparée
- PDOStatement::getColumnMeta() - Retourne les métadonnées pour une colonne d'un jeu de résultats
- PDO::query() - Prépare et Exécute une requête SQL sans marque substitutive

# PDOStatement::rowCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::rowCount — Retourne le nombre de lignes affectées par le dernier appel à la fonction PDOStatement::execute()

### Description

public function PDOStatement::rowCount(): int

PDOStatement::rowCount() retourne le nombre de lignes affectées par la dernière requête DELETE, INSERT ou UPDATE exécutée par l'objet `PDOStatement` correspondant.

Si la dernière requête SQL exécutée par l'objet `PDOStatement` associé est une requête de type SELECT, quelques bases de données retourneront le nombre de lignes retournées par cette requête. Néanmoins, ce comportement n'est pas garanti pour toutes les bases de données et il ne faut pas s'y fier pour des applications portables.

> Note:

> Cette méthode retourne toujours "0" (zéro) avec le pilote PostgreSQL, quand l'attribut de déclaration `PDO::ATTR_CURSOR` est défini à `PDO::CURSOR_SCROLL`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de lignes.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Retourne le nombre de lignes effacées

PDOStatement::rowCount() retourne le nombre de lignes affectées par une requête DELETE, INSERT, ou UPDATE.

    <?php
    /* Effacement de toutes les lignes de la table FRUIT */
    $del = $dbh->prepare('DELETE FROM fruit');
    $del->execute();

    /* Retourne le nombre de lignes effacées */
    print "Retourne le nombre de lignes effacées :\n";
    $count = $del->rowCount();
    print "Effacement de $count lignes.\n";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Retourne le nombre de lignes effacées :
    Effacement de 9 lignes.

Exemple #2 Comptage des lignes retournées par une requête SELECT

Pour la plupart des bases de données, PDOStatement::rowCount() ne retourne pas le nombre de lignes affectées par une requête SELECT. À la place, utiliser PDO::query() pour faire une requête SELECT COUNT(*), puis utiliser PDOStatement::fetchColumn() pour récupérer le nombre de lignes correspondantes.

    <?php
    $sql = "SELECT COUNT(*) FROM fruit WHERE calories > 100";
    $res = $conn->query($sql);
    $count = $res->fetchColumn();

    print "Il y a " .  $count . " ligne(s) correspondante(s).";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Il y a 2 ligne(s) correspondante(s).

### Voir aussi

- PDOStatement::columnCount() - Retourne le nombre de colonnes dans le jeu de résultats
- PDOStatement::fetchColumn() - Retourne une colonne depuis la ligne suivante d'un jeu de résultats
- PDO::query() - Prépare et Exécute une requête SQL sans marque substitutive

# PDOStatement::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setAttribute — Définit un attribut de requête

### Description

public function PDOStatement::setAttribute(int `$attribute`, mixed `$value`): bool

Définit un attribut de la requête. Actuellement, aucun attribut générique n'est défini, mais uniquement des spécificités du driver :

- `PDO::ATTR_CURSOR_NAME` (spécificité de Firebird et d'ODBC) : Définit le nom du curseur pour `UPDATE ... WHERE CURRENT OF`.

Il est à noter que les attributs spécifiques au pilote ne doivent pas être utilisés avec d'autres pilotes.

### Liste de paramètres

`attribute`

  L'attribut à modifier.

`value`

  La valeur pour définir l'`attribute`, peut nécessiter un type spécifique selon l'attribut.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- PDO::getAttribute() - Récupère un attribut d'une connexion à une base de données
- PDO::setAttribute() - Configure un attribut PDO
- PDOStatement::getAttribute() - Récupère un attribut de requête

# PDOStatement::setFetchMode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setFetchMode — Définit le mode de récupération par défaut pour cette requête

### Description

public function PDOStatement::setFetchMode(int `$mode`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true

### Liste de paramètres

`mode`

  Le mode de récupération doit être une des constantes `PDO::FETCH_*`.

`colno`

  Numéro de la colonne.

`class`

  Nom de la classe.

`constructorArgs`

  Arguments du constructeur.

`object`

  Objet.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.4.0 | Le type de retour est maintenant `true`, auparavant il était bool.

### Exemples

Exemple #1 Définition du mode de récupération

L'exemple suivant montre comment PDOStatement::setFetchMode() modifie le mode de récupération par défaut pour un objet PDOStatement.

    <?php
    $stmt = $dbh->query('SELECT name, colour, calories FROM fruit');
    $stmt->setFetchMode(PDO::FETCH_NUM);
    foreach ($stmt as $row) {
        print $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    apple   red     150
    banana  yellow  250
    orange  orange  300
    kiwi    brown   75
    lemon   yellow  25
    pear    green   150

## Sommaire

- PDOStatement::bindColumn — Lie une colonne à une variable PHP
- PDOStatement::bindParam — Lie un paramètre à un nom de variable spécifique
- PDOStatement::bindValue — Associe une valeur à un paramètre
- PDOStatement::closeCursor — Ferme le curseur, permettant à la requête d'être de nouveau exécutée
- PDOStatement::columnCount — Retourne le nombre de colonnes dans le jeu de résultats
- PDOStatement::debugDumpParams — Détaille une commande préparée SQL
- PDOStatement::errorCode — Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête
- PDOStatement::errorInfo — Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête
- PDOStatement::execute — Exécute une requête préparée
- PDOStatement::fetch — Récupère la ligne suivante d'un jeu de résultats PDO
- PDOStatement::fetchAll — Récupère les lignes restantes d'un ensemble de résultats
- PDOStatement::fetchColumn — Retourne une colonne depuis la ligne suivante d'un jeu de résultats
- PDOStatement::fetchObject — Récupère la prochaine ligne et la retourne en tant qu'objet
- PDOStatement::getAttribute — Récupère un attribut de requête
- PDOStatement::getColumnMeta — Retourne les métadonnées pour une colonne d'un jeu de résultats
- PDOStatement::getIterator — Renvoie un itérateur sur le jeu de résultats
- PDOStatement::nextRowset — Avance à la prochaine ligne de résultats d'un gestionnaire de lignes de résultats multiples
- PDOStatement::rowCount — Retourne le nombre de lignes affectées par le dernier appel à la fonction PDOStatement::execute()
- PDOStatement::setAttribute — Définit un attribut de requête
- PDOStatement::setFetchMode — Définit le mode de récupération par défaut pour cette requête

# La classe PDORow

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Introduction

Représente une ligne d'un jeu de résultats retourné par PDOStatement::fetch() appelé avec le mode de récupération `PDO::FETCH_LAZY`.

Les objets de cette classe ne peuvent pas être instanciés et ne sont pas sérialisables.

La classe PDORow permet d'accéder aux données retournées comme si les modes `PDO::FETCH_OBJ` et `PDO::FETCH_BOTH` étaient utilisés. Cela signifie que les données retournées peuvent être accédées comme des propriétés d'objet, et comme un tableau indexé par le nom de la colonne et un numéro de position de colonne.

Attention

Accéder à une propriété non définie retourne `null` sans émettre de message d'avertissement.

## Synopsis de la classe

final class PDORow {
/* Propriétés */
public string $queryString;
}

## Propriétés

queryString

  La requête utilisée par PDOStatement qui a retourné l'objet PDORow.

## Erreurs / Exceptions

Lance une erreur de type Error lorsqu'on tente d'écrire ou de unset() une propriété.

# La classe PDOException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Introduction

Représente une erreur émise par PDO. Il ne faut pas lancer une exception PDOException depuis son propre code. Voir le chapitre sur les exceptions pour plus d'informations concernant les exceptions en PHP.

## Synopsis de la classe

class PDOException extends RuntimeException {
/* Propriétés */
protected int|string $code;
public ?array $errorInfo = null;
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriétés

errorInfo

  Correspond à PDO::errorInfo() ou PDOStatement::errorInfo()

code

  Code erreur `SQLSTATE`. Utiliser la méthode Exception::getCode() pour y accéder.

# Pilotes PDO

## Sommaire

- Pilote PDO CUBRID
- Pilote PDO MS SQL Server
- Pdo\Dblib
- Pilote PDO Firebird
- Pdo\Firebird
- Pilote PDO IBM
- Pilote PDO Informix
- Pilote PDO MySQL
- Pdo\Mysql
- Pilote PDO MS SQL Server
- Pilote PDO Oracle
- Pilotes PDO ODBC et DB2
- Pdo\Odbc
- Pilote PDO PostgreSQL
- Pdo\Pgsql
- Pilote PDO SQLite
- Pdo\Sqlite

Les pilotes suivants (`driver`) sont actuellement implémentés dans l'interface PDO :

Nom du pilote | Bases de données prises en charge
--- | ---
PDO_CUBRID | Cubrid
PDO_DBLIB | FreeTDS / Microsoft SQL Server / Sybase
PDO_FIREBIRD | Firebird
PDO_IBM | IBM DB2
PDO_INFORMIX | IBM Informix Dynamic Server
PDO_MYSQL | MySQL 3.x/4.x/5.x/8.x
PDO_OCI | `Oracle Call Interface`
PDO_ODBC | ODBC v3 (IBM DB2, unixODBC et win32 ODBC)
PDO_PGSQL | PostgreSQL
PDO_SQLITE | SQLite 3 et SQLite 2
PDO_SQLSRV | Microsoft SQL Server / SQL Azure

# Fonctions du pilote PDO CUBRID (PDO_CUBRID)

## Introduction

PDO_CUBRID est un pilote qui implémente l' interface PHP Data Objects (PDO) pour permettre l'accès à partir de PHP aux bases de données CUBRID.

> Note: La version actuelle de PDO_CUBRID ne prend pas en charge la connexion persistante pour le moment.

## Installation

Pour construire l'extension PDO_CUBRID, CUBRID DBMS doit être installé sur le même système que PHP. PDO_CUBRID est une extension » PECL, aussi, il faut suivre les instructions de Installation d'extensions PECL pour installer l'extension PDO_CUBRID. Lancez la commande configure pour localiser le dossier de base de CUBRID comme ceci :

       $ ./configure --with-pdo-cubrid=/path/to/CUBRID[,shared]

La commande configure prendra par défaut la valeur de la variable d'environnement CUBRID.

Aucune bibliothèque DLL pour cette extension PECL n'est actuellement disponible. Reportez-vous à la section Compilation sous Windows. Des informations sur l'installation manuelle sous Linux et Windows peuvent être trouvées dans le fichier build-guide.html du paquet CUBRID de PECL.

## Fonctionnalités de PDO_CUBRID

## Curseurs défilables

PDO_CUBRID prend en charge les curseurs défilables. Le type de curseur par défaut est forward only, et il est possible d'utiliser le paramètre driver_options dans PDO::prepare() pour changer le type de curseur.

## Délai d'expiration

PDO_CUBRID prend en charge le paramétrage du délai d'exécution de l'instruction SQL ; Il est possible d'utiliser PDO::setAttribute() pour définir la valeur du délai d'expiration.

## Mode autocommit et transaction

PDO_CUBRID prend en charge à la fois le mode autocommit et la transaction, et le mode autocommit est activé par défaut. Il est possible d'utiliser PDO::setAttribute() pour changer son état.

Lors de l'utilisation de PDO::beginTransaction() pour commencer une transaction, cela désactivera automatiquement le mode autocommit et le restaurera après PDO::commit() ou PDO::rollBack().

> Note: Avant de désactiver le mode autocommit, tout travail en attente est automatiquement validé.

## Instructions SQL multiples

PDO_CUBRID prend en charge les instructions SQL multiples. Les instructions SQL multiples sont séparées par des points-virgules (`;`).

## Informations sur le schéma

PDO_CUBRID implémente PDO::cubrid_schema() pour obtenir des informations sur le schéma.

## LOBs

PDO_CUBRID prend en charge les types de données BLOB/CLOB. Le LOB dans PDO est représenté comme un flux, il est possible de donc insérer des LOBs en liant un flux, et obtenir des LOBs en lisant un flux retourné par CUBRID PDO. Par exemple :

Exemple #1 Insérer des LOBs dans CUBRID PDO

    <?php
    $fp = fopen('lob_test.png', 'rb');

    $sql_stmt = "INSERT INTO lob_test(name, content) VALUES('lob_test.png', ?)";

    $stmt = $dbh->prepare($sql_stmt);
    $ret = $stmt->bindParam(1, $fp, PDO::PARAM_LOB);
    $ret = $stmt->execute();
    ?>

Exemple #2 Récupérer des LOBs dans CUBRID PDO

    <?php
    $sql_stmt = "SELECT content FROM lob_test WHERE name='lob_test.png'";

    $stmt = $dbh->prepare($sql_stmt);
    $stmt->execute();
    $result = $stmt->fetch(PDO::FETCH_NUM);

    header("Content-Type: image/png");
    fpassthru($result[0]);
    ?>

## Méta-colonne

La méthode PDOStatement::getColumnMeta() dans CUBRID PDO renverra un tableau associatif contenant les valeurs suivantes :

- type
- name
- table
- def
- precision
- scale
- not_null
- auto_increment
- unique_key
- multiple_key
- primary_key
- foreign_key
- reverse_index
- reverse_unique

## Type de données Collection

PDO_CUBRID prend en charge les types de données SET/MULTISET/SEQUENCE. Si on ne spécifie pas le type de données, le type de données par défaut est char. Par exemple :

Exemple #3 Insérer un ensemble dans CUBRID PDO avec le type de données par défaut.

    <?php
    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(VARCHAR))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);
    $data = array("abc","def","ghi");
    $ret = $stmt->bindParam(1, $data, PDO::PARAM_NULL);
    $ret = $stmt->execute();
    var_Dump($ret);
    ?>

Exemple #4 Spécifier le type de données lors de l'insertion d'un ensemble dans CUBRID PDO

    <?php
    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(int))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);
    $data = array(1,2,3,4);
    $ret = $stmt->bindParam(1, $data, 0,0,"int");
    $ret = $stmt->execute();
    var_Dump($ret);
    ?>

Types de données CUBRID Bind pour le cinquième paramètre de PDOStatement::bindParam() :

- CHAR
- STRING
- NCHAR
- VARNCHAR
- BIT
- VARBIT
- NUMERIC
- NUMBER
- INT
- SHORT
- BIGINT
- MONETARY
- FLOAT
- DOUBLE
- DATE
- TIME
- DATETIME
- TIMESTAMP

## Constantes pré-définies

Les constantes ci-dessous sont définies par ce pilote et seront seulement disponibles lorsque l'extension aura été compilée dans PHP ou chargée dynamiquement du moteur d'exécution. De plus, ces constantes spécifiques au pilote devraient être utilisées seulement si vous utilisez ce pilote. En utilisant les attributs spécifiques à un pilote avec un autre pilote pourrait causer un comportement inattendu. PDO::getAttribute() pourrait être utilisé pour obtenir l'attribut `PDO::ATTR_DRIVER_NAME` pour vérifier le pilote, si votre code peut fonctionner sur des pilotes multiples.

Les constantes suivantes peuvent être utilisées pour configurer les attributs de la base de données. Elles peuvent être passées à la méthode PDO::getAttribute() ou à la méthode PDO::setAttribute().

Drapeaux pour les attributs PDO::CUBRID
Constante | Description
--- | ---
`PDO::CUBRID_ATTR_ISOLATION_LEVEL` | Le niveau d'isolation de la transaction pour la connexion à la base de données.
`PDO::CUBRID_ATTR_LOCK_TIMEOUT` | Délai d'expiration de la transaction en secondes.
`PDO::CUBRID_ATTR_MAX_STRING_LENGTH` | Lecture seule. La longueur maximale de la chaîne pour les types de données bit, varbit, char, varchar, nchar, nchar lors de l'utilisation de l'API CUBRID PDO.

Les constantes suivantes peuvent être utilisées lors de la configuration du niveau d'isolation de la transaction. Elles peuvent être passées à la méthode PDO::getAttribute() ou à la méthode PDO::setAttribute().

Drapeaux pour le niveau d'isolation PDO::CUBRID
Constante | Description
--- | ---
`PDO::TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | Le niveau d'isolation le moins élevé (1). Une lecture sale, non reproductible ou fantôme peut survenir sur le tuple, mais aussi une lecture non reproductible peut survenir pour la table.
`PDO::TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | Un niveau d'isolation relativement bas (2). Une lecture sale ne peut pas survenir, par contre, une lecture non reproductible ou fantôme peut survenir.
`PDO::TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | Le niveau d'isolation par défaut pour CUBRID (3). Une lecture sale ou fantôme peut survenir sur le tuple, mais la reproductibilité de la lecture est assurée sur la table.
`PDO::TRAN_REP_CLASS_COMMIT_INSTANCE` | Un niveau d'isolation relativement bas (4). Une lecture sale ne peut survenir, mais les lectures non reproductibles ou fantôme le peuvent.
`PDO::TRAN_REP_CLASS_REP_INSTANCE` | Un niveau d'isolation relativement haut (5). Les lectures sales ou non reproductibles ne peuvent pas survenir, mais une lecture fantôme est possible.
`PDO::TRAN_SERIALIZABLE` | Le plus haut niveau d'isolation (6). Les problèmes relatifs à la concurrence (c.-à-d. lecture sale, lecture non reproductible, lecture fantôme, etc.) ne peuvent survenir.

Les constantes suivantes peuvent être utilisées pour récupérer les informations sur le schéma. Elles peuvent être passées à la fonction PDO::cubrid_schema().

Drapeaux pour le schéma CUBRID
Constante | Description
--- | ---
`PDO::CUBRID_SCH_TABLE` | Récupère le nom et le type de table CUBRID.
`PDO::CUBRID_SCH_VIEW` | Récupère le nom et le type de vue dans CUBRID.
`PDO::CUBRID_SCH_QUERY_SPEC` | Récupère la définition de la requête de la vue.
`PDO::CUBRID_SCH_ATTRIBUTE` | Récupère les attributs de la colonne de la table.
`PDO::CUBRID_SCH_TABLE_ATTRIBUTE` | Récupère les attributs de la table.
`PDO::CUBRID_SCH_METHOD` | Récupère la méthode de l'instance. C'est une méthode appelée par l'instance de la classe. Elle est utilisée plus souvent que la méthode de la classe car la plupart des opérations sont exécutées dans l'instance.
`PDO::CUBRID_SCH_TABLE_METHOD` | Récupère la méthode de la classe. C'est une méthode appelée par un objet de la classe. Elle est habituellement utilisée pour créer une nouvelle instance de la classe ou pour l'initialiser. Elle est également utilisée pour accéder ou mettre à jour les attributs de la classe.
`PDO::CUBRID_SCH_METHOD_FILE` | Récupère les informations sur le fichier où la méthode de la table est définie.
`PDO::CUBRID_SCH_SUPER_TABLE` | Récupère le nom et le type de la table dont les attributs héritent.
`PDO::CUBRID_SCH_SUB_TABLE` | Récupère le nom et le type de la table qui hérite des attributs de cette table.
`PDO::CUBRID_SCH_CONSTRAINT` | Récupère les contraintes de la table.
`PDO::CUBRID_SCH_TRIGGER` | Récupère les triggers de la table.
`PDO::CUBRID_SCH_TABLE_PRIVILEGE` | Récupère les informations sur les privilèges de la table.
`PDO::CUBRID_SCH_COL_PRIVILEGE` | Récupère les informations sur les privilèges d'une colonne.
`PDO::CUBRID_SCH_DIRECT_SUPER_TABLE` | Récupère la table directement supérieure à la table.
`PDO::CUBRID_SCH_PRIMARY_KEY` | Récupère la clé primaire de la table.
`PDO::CUBRID_SCH_IMPORTED_KEYS` | Récupère les clés importées d'une table.
`PDO::CUBRID_SCH_EXPORTED_KEYS` | Récupère les clés exportées d'une table.
`PDO::CUBRID_SCH_CROSS_REFERENCE` | Récupère les relations de référence entre 2 tables.

# DSN PDO_CUBRID

(No version information available, might only be in Git)

DSN PDO_CUBRID — Connexion aux bases de données CUBRID

### Description

Le DSN PDO_CUBRID est composé des éléments suivants, délimités par un point virgule :

préfixe DSN

  Le préfixe DSN est `cubrid:`.

`host`
  Le nom d'hôte sur lequel se trouve le serveur de base de données.
`port`
  Le port sur lequel le serveur de base de données fonctionne.
`dbname`
  Le nom de la base de données.

### Notes

> Note: Lorsque l'on établit la connexion à CUBRID, il faut fournir le nom de l'utilisateur et le mot de passe, mais pas le DSN.

### Exemples

Exemple #1 Exemples de DSN PDO_CUBRID

L'exemple suivant montre un DSN PDO_CUBRID pour une connexion à une base de données CUBRID :

    cubrid:host=localhost;port=33000;dbname=demodb

# PDO::cubrid_schema

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO::cubrid_schema — Récupère le schéma d'informations demandé

### Description

public function PDO::cubrid_schema(int `$schema_type`, string `$table_name` = ?, string `$col_name` = ?): array

Cette fonction est utilisée pour récupérer le schéma d'informations demandé depuis la base de données. Il faut désigner le paramètre `table_name`, pour récupérer les informations d'une certaine table, le paramètre `col_name`, pour récupérer les informations d'une certaine colonne (ne peut être utilisé qu'avec PDO::CUBRID_SCH_COL_PRIVILEGE).

Le résultat de cette fonction est retourné sous la forme d'un tableau à 2 dimensions (colonne(tableau associatif) * ligne (tableau numérique)). Les tables suivantes montrent les types de schéma et la structure de la colonne du tableau résultant.

Composition du résultat pour chaque type
Schéma | Numéro de la colonne | Nom de la colonne | Valeur
--- | --- | --- | ---
PDO::CUBRID_SCH_TABLE | 1 | NAME |
| 2 | TYPE | 0:system table 1:view 2:table
PDO::CUBRID_SCH_VIEW | 1 | NAME |
| 2 | TYPE | 1:view
PDO::CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
PDO::CUBRID_SCH_ATTRIBUTE / PDO::CUBRID_SCH_TABLE_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexed
| 6 | NOT NULL | 1:not null
| 7 | SHARED | 1:shared
| 8 | UNIQUE | 1:unique
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:key
PDO::CUBRID_SCH_METHOD / PDO::CUBRID_SCH_TABLE_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
PDO::CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
PDO::CUBRID_SCH_SUPER_TABLE / PDO::CUBRID_SCH_DIRECT_SUPER_TABLE / PDO::CUBRID_SCH_SUB_TABLE | 1 | CLASS_NAME |
| 2 | TYPE | 0:system table 1:view 2:table
PDO::CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:primary key
| 7 | KEY_ORDER | base:1
PDO::CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
PDO::CUBRID_SCH_TABLE_PRIVILEGE / PDO::CUBRID_SCH_COL_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
PDO::CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
PDO::CUBRID_SCH_IMPORTED_KEYS / PDO::CUBRID_SCH_EXPORTED_KEYS / PDO::CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 8 | FK_NAME |
| 9 | PK_NAME |

### Liste de paramètres

`schema_type`
  Le type du schéma que l'on souhaite récupérer.
`table_name`
  La table dont on souhaite récupérer le schéma.
`col_name`
  La colonne dont on souhaite récupérer le schéma.

### Valeurs de retour

Un tableau contenant les informations relatives au schéma, lorsque le processus s'est exécuté avec succès.

`false` sera retourné si une erreur survient.

### Exemples

Exemple #1 Exemple avec PDO::cubrid_schema()

Cet exemple montre la façon dont on récupère les clés primaires et étrangères de la table "game".

    <?php
    $pk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_PRIMARY_KEY, "game");
    print_r($pk_list);

    $fk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_IMPORTED_KEYS, "game");
    print_r($fk_list);
    ?>

L'exemple ci-dessus va afficher :

    Result:
    Array
    (
        [0] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => athlete_code
                [KEY_SEQ] => 3
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [1] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => event_code
                [KEY_SEQ] => 2
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [2] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => host_year
                [KEY_SEQ] => 1
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

    )
    Array
    (
        [0] => Array
            (
                [PKTABLE_NAME] => athlete
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => athlete_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_athlete_code
                [PK_NAME] => pk_athlete_code
            )

        [1] => Array
            (
                [PKTABLE_NAME] => event
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => event_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_event_code
                [PK_NAME] => pk_event_code
            )

    )

## Sommaire

- DSN PDO_CUBRID — Connexion aux bases de données CUBRID
- PDO::cubrid_schema — Récupère le schéma d'informations demandé

# Microsoft SQL Server et Fonctions du pilote PDO Sybase (PDO_DBLIB)

## Introduction

PDO_DBLIB est un pilote qui implémente l'interface de PHP Data Objects (PDO) pour autoriser l'accès de PHP au Microsoft SQL Server et aux bases de données Sybase par la bibliothèque FreeTDS.

Cette extension n'est plus disponible sous Windows.

Sous Windows, il est recommandé d'utiliser SqlSrv, un driver alternatif pour MS SQL disponible chez Microsoft : » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx .

S'il n'est pas possible d'utiliser SqlSrv, il est possible d'utiliser le driver PDO_ODBC pour se connecter à un serveur de bases de données Microsoft SQL et Sybase, sachant que le driver natif Windows DB-LIB est ancien, non sécurisé niveau thread et plus supporté par Microsoft.

# PDO_DBLIB DSN

(PECL PDO_DBLIB >= 0.9.0)

PDO_DBLIB DSN — Connexion au Serveur Microsoft SQL et bases de données Sybase

### Description

Le Data Source Name (DSN) de PDO_DBLIB est composé des éléments suivants :

Préfixe DSN

  Le préfixe DSN est `sybase:` si PDO_DBLIB était lié avec les bibliothèques Sybase ct-lib, `mssql:` si PDO_DBLIB était lié avec les bibliothèques de Microsoft SQL Server, ou `dblib:` si PDO_DBLIB était lié avec les bibliothèques FreeTDS.

`host`

  L'hôte sur lequel le serveur de base de données se situe.

`dbname`

  Le nom de la base de données.

`charset`

  Le jeu de caractères du client.

`appname`

  Le nom de l'application (utilisé dans `sysprocesses`). Par défaut, `"PHP Generic DB-lib"` ou `"PHP freetds"`.

`secure`

  Actuellement inutilisé.

### Exemples

Exemple #1 Exemples avec PDO_DBLIB DSN

Les exemples suivants montrent PDO_DBLIB DSN pour se connecter au Microsoft SQL Server et les bases de données Sybase :

    mssql:host=localhost;dbname=testdb
    sybase:host=localhost;dbname=testdb
    dblib:host=localhost;dbname=testdb

## Sommaire

- PDO_DBLIB DSN — Connexion au Serveur Microsoft SQL et bases de données Sybase

# La classe Pdo\Dblib

(PHP 8 >= 8.4.0)

## Introduction

Une sous-classe de PDO représentant une connexion utilisant le pilote PDO DBLib.

## Synopsis de la classe

namespace Pdo;
class Dblib extends PDO {
/* Constantes héritées */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_CONNECTION_TIMEOUT;
public const int ATTR_QUERY_TIMEOUT;
public const bool ATTR_STRINGIFY_UNIQUEIDENTIFIER;
public const int ATTR_VERSION;
public const int ATTR_TDS_VERSION;
public const int ATTR_SKIP_EMPTY_ROWSETS;
public const bool ATTR_DATETIME_CONVERT;
/* Méthodes héritées */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes pré-définies

`Pdo\Dblib::ATTR_CONNECTION_TIMEOUT`
`Pdo\Dblib::ATTR_QUERY_TIMEOUT`
`Pdo\Dblib::ATTR_STRINGIFY_UNIQUEIDENTIFIER`
  À partir de PHP 8.4.0, cette constante est de type bool ; elle était auparavant de type int.
`Pdo\Dblib::ATTR_VERSION`
`Pdo\Dblib::ATTR_TDS_VERSION`
`Pdo\Dblib::ATTR_SKIP_EMPTY_ROWSETS`
`Pdo\Dblib::ATTR_DATETIME_CONVERT`
  Cet attribut de connexion contrôle le format des chaînes pour les types datetime. Lorsqu'il vaut `false`, PDO_DBLIB retourne un type datetime sous forme de chaîne dans le format que SQL Server retourne (c'est-à-dire `"2017-10-27 10:22:44"`). Lorsqu'il vaut `true`, PDO_DBLIB convertit le type datetime en chaîne en utilisant un format défini par l'utilisateur ou par la locale, tel que spécifié dans le fichier FreeTDS locales.conf. Par défaut, cet attribut vaut `false`. À partir de PHP 8.4.0, cette constante est de type bool ; elle était auparavant de type int.

# Fonctions du pilote PDO Firebird (PDO_FIREBIRD)

## Introduction

PDO_FIREBIRD est un pilote qui implémente l'interface de `PHP Data Objects` (PDO) pour permettre l'accès de PHP aux bases de données Firebird.

## Installation

Utiliser l'option de compilation --with-pdo-firebird[=DIR] pour installer l'extension PDO Firebird, où `[=DIR]` (optionnel) représente le chemin vers le dossier d'installation de base de Firebird.

    $ ./configure --with-pdo-firebird

## Constantes pré-définies

Les constantes ci-dessous sont définies par ce pilote et seront seulement disponibles lorsque l'extension aura été compilée dans PHP ou chargée dynamiquement du moteur d'exécution. De plus, ces constantes spécifiques au pilote devraient être utilisées seulement si vous utilisez ce pilote. En utilisant les attributs spécifiques à un pilote avec un autre pilote pourrait causer un comportement inattendu. PDO::getAttribute() pourrait être utilisé pour obtenir l'attribut `PDO::ATTR_DRIVER_NAME` pour vérifier le pilote, si votre code peut fonctionner sur des pilotes multiples.

Avertissement

Les constantes listées ci-dessous sont OBSOLÈTES à partir de PHP 8.5.0. Utiliser les constantes Pdo\Firebird correspondantes à la place.

`PDO::FB_ATTR_DATE_FORMAT` (int)
  Alias de `Pdo\Firebird::ATTR_DATE_FORMAT`.
`PDO::FB_ATTR_TIME_FORMAT` (int)
  Alias de `Pdo\Firebird::ATTR_TIME_FORMAT`.
`PDO::FB_ATTR_TIMESTAMP_FORMAT` (int)
  Alias de `Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`.

# PDO_FIREBIRD DSN

(PECL PDO_FIREBIRD >= 0.1.0)

PDO_FIREBIRD DSN — Connexion aux bases de données Firebird

### Description

Le Data Source Name (DSN) de PDO_FIREBIRD est composé des éléments suivants :

Préfixe DSN

  Le préfixe DSN est `firebird:`.

`dbname`

  Le nom de la base de données.

`charset`

  Le jeu de caractères.

`role`

  Le nom du rôle SQL.

`dialect`

  Le dialecte de la base de données ; soit `1` ou `3`. S'il n'est pas spécifié, le dialecte par défaut est `3`. Disponible à partir de PHP 7.4.0.

### Exemples

Exemple #1 Exemples avec PDO_FIREBIRD DSN

L'exemple suivant montre PDO_FIREBIRD DSN pour se connecter aux bases de données Firebird :

    firebird:dbname=/chemin/vers/DATABASE.FDB

Exemple #2 Exemple avec un DSN PDO_FIREBIRD avec un port et un chemin

L'exemple suivant montre un DSN PDO_FIREBIRD pour la connexion à une base de données Firebird, en utilisant un nom d'hôte, un port et un chemin :

    firebird:dbname=hostname/port:/path/to/DATABASE.FDB

Exemple #3 Exemple avec un DSN PDO_FIREBIRD en local et un chemin vers le fichier employee.fdb sur un système Debian

L'exemple suivant montre un DSN PDO_FIREBIRD pour la connexion à une base de données Firebird employee.fdb en local :

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/employee.fdb

Exemple #4 Un DSN PDO_FIREBIRD pour se connecter à une base de données en dialecte 1

L'exemple suivant montre un DSN PDO_FIREBIRD pour se connecter à une base de données Firebird test.fdb qui a été créée en utilisant le dialecte 1. Ceci est uniquement supporté à partir de PHP 7.4.0.

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/test.fdb;charset=utf-8;dialect=1

## Sommaire

- PDO_FIREBIRD DSN — Connexion aux bases de données Firebird

# La classe Pdo\Firebird

(PHP 8 >= 8.4.0)

## Introduction

Une sous-classe de PDO représentant une connexion utilisant le pilote Firebird PDO.

## Synopsis de la classe

namespace Pdo;
class Firebird extends PDO {
/* Constantes héritées */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_DATE_FORMAT;
public const int ATTR_TIME_FORMAT;
public const int ATTR_TIMESTAMP_FORMAT;
public const int TRANSACTION_ISOLATION_LEVEL;
public const int READ_COMMITTED;
public const int REPEATABLE_READ;
public const int SERIALIZABLE;
public const int WRITABLE_TRANSACTION;
/* Méthodes */
public static function getApiVersion(): int
/* Méthodes héritées */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes pré-définies

`Pdo\Firebird::ATTR_DATE_FORMAT`
  Définit le format de date.
`Pdo\Firebird::ATTR_TIME_FORMAT`
  Définit le format de l'heure.
`Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`
  Définit le format de l'horodatage.
`Pdo\Firebird::TRANSACTION_ISOLATION_LEVEL`
  Les attributs de transaction définissent le niveau d'isolation de la transaction. Cela peut être l'un des `Pdo\Firebird::READ_COMMITTED`, `Pdo\Firebird::REPEATABLE_READ`, ou `Pdo\Firebird::SERIALIZABLE`.
`Pdo\Firebird::READ_COMMITTED`
  Drapeau indiquant que le niveau d'isolation de la transaction ANSI est read committed. C'est le comportement par défaut.
`Pdo\Firebird::REPEATABLE_READ`
  Drapeau indiquant que le niveau d'isolation de la transaction ANSI est repeatable read. Cela correspond au niveau d'isolation "snapshot" de Firebird.
`Pdo\Firebird::SERIALIZABLE`
  Drapeau indiquant que le niveau d'isolation de la transaction ANSI est serializable. Cela correspond au niveau d'isolation "snapshot table stability" de Firebird.
`Pdo\Firebird::WRITABLE_TRANSACTION`
  L'attribut booléen utilisé pour basculer le mode d'accès à la transaction entre `READ ONLY` et `READ WRITE`. Par défaut, il est `true` indiquant `READ WRITE`.

# Pdo\Firebird::getApiVersion

(PHP 8 >= 8.4.0)

Pdo\Firebird::getApiVersion — Renvoie la version de l'API

### Description

public static function Pdo\Firebird::getApiVersion(): int

Renvoie la version de l'API Firebird telle que définie par la constante C `FB_API_VER` dans ibase.h.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'API Firebird en tant qu'int.

## Sommaire

- Pdo\Firebird::getApiVersion — Renvoie la version de l'API

# Fonctions du pilote PDO IBM (PDO_IBM)

## Introduction

PDO_IBM est un driver qui implémente l'interface `PHP Data Objects` (PDO) afin d'activer l'accès à partir de PHP aux bases de données IBM.

## Installation

Pour compiler l'extension PDO_IBM, le client DB2 v9.1 ou supérieur doit être installé sur le même système que PHP. Le client DB2 peut être téléchargé depuis le site d'IBM de » développement d'applications.

> Note: Note

> Le client DB2 v9.1 ou supérieur supporte les accès directs à DB2 pour les systèmes Linux, UNIX et les serveurs Windows v8 et v9.1.

> Le client DB2 v9.1 supporte également les accès à DB2 UDB pour i5 et DB2 UDB pour les serveurs z/OS en utilisant le » produit de connexion DB2 payant.

PDO_IBM est une extension » PECL; il faut donc suivre les instructions de Installation d'extensions PECL pour installer l'extension PDO_IBM. Exécutez la commande configure afin qu'elle pointe vers le dossier contenant les fichiers d'en-têtes et les bibliothèques du client DB2 comme ceci :

     bash$ ./configure --with-pdo-ibm=/path/to/sqllib[,shared]

La commande configure utilise par défaut la valeur de la variable d'environnement DB2DIR.

## Configuration à l'exécution

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

Options de configuration PDO_IBM
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
pdo_ibm.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Ajouté dans PDO_IBM 1.5.0
pdo_ibm.i5_override_ccsid | "0" | `INI_SYSTEM` | Ajouté dans PDO_IBM 1.5.0

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`pdo_ibm.i5_dbcs_alloc` int

  Cette option affecte la stratégie d'allocation de mémoire interne sur IBM i. Par défaut, cette option est 0. Lorsque cette option est définie, des tampons sont alloués avec une taille beaucoup plus grande, au cas où la base de données serait trompeuse sur la taille des caractères lors de la conversion entre les encodages. Cette option utilise six fois plus de mémoire pour les tampons (pour tenir compte des séquences UTF-8 les plus longues), mais peut être nécessaire si des données tronquées sont renvoyées.

  - 0 - La taille minimale des tampons est allouée.

  - 1 - Une plus grande taille des tampons est allouée.

`pdo_ibm.i5_override_ccsid` int

  Le CCSID ASCII à utiliser pour la conversion de l'EBCDIC sur IBM i. En définissant ceci à 1208, l'on utilisera l'UTF-8. Par défaut, c'est 0, ce qui sélectionnera le CCSID de travail ASCII par défaut.

  Pour en savoir plus sur les CCSID sur IBM i, consulter la » documentation IBM.

# PDO_IBM DSN

(PECL PDO_IBM >= 0.9.0)

PDO_IBM DSN — Connexion aux bases de données IBM

### Description

Le nom de la source de données PDO_IBM (DSN) est basé sur le IBM CLI DSN. Les principaux composants de PDO_IBM DSN sont :

DSN prefix

  Le préfixe DSN est `ibm:`.

DSN

  Le DSN peut être une valeur parmi celles-ci :

  - a) Configuration de la source des données en utilisant le fichier db2cli.ini ou odbc.ini

  - b) Nom de base de données catalogué, c.-à-d. alias de base de données contenus dans le catalogue du client DB2

  - c) Chaîne de connexion complète dans le format suivant : `DRIVER={IBM DB2 ODBC DRIVER};DATABASE=`database`;HOSTNAME=`hostname`;PORT=`port`;PROTOCOL=TCPIP;UID=`username`;PWD=`password`;` où les paramètres représentent les valeurs suivantes :

    `database`

      Le nom de la base de données.

    `hostname`

      Le nom de l'hôte ou l'adresse IP du serveur de base de données.

    `port`

      Le port TCP/IP sur lequel la base de données écoute les requêtes.

    `username`

      Le nom d'utilisateur utilisé pour la connexion à la base de données.

    `password`

      Le mot de passe utilisé pour la connexion à la base de données.

### Exemples

Exemple #1 Exemple avec PDO_IBM DSN en utilisant db2cli.ini

L'exemple suivant montre l'utilisation de PDO_IBM DSN pour la connexion à une base de données DB2 cataloguée comme DB2_9 dans le fichier db2cli.ini :

    $db = new PDO("ibm:DSN=DB2_9", "", "");

    [DB2_9]
    Database=testdb
    Protocol=tcpip
    Hostname=11.22.33.444
    Servicename=56789

Exemple #2 Exemple avec PDO_IBM DSN en utilisant une chaîne complète de connexion

L'exemple suivant montre l'utilisation de PDO_IBM DSN pour la connexion à une base de données DB2 nommée `testdb` en utilisant la chaîne complète de connexion DB2 CLI :

    $db = new PDO("ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
    "HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;", "testuser", "tespass");

## Sommaire

- PDO_IBM DSN — Connexion aux bases de données IBM

# Fonctions du pilote PDO Informix (PDO_INFORMIX)

## Introduction

PDO_INFORMIX est un pilote qui implémente l'interface de `PHP Data Objects` (PDO) pour autoriser l'accès à PHP aux bases de données Informix.

## Installation

Pour compiler l'extension PDO_INFORMIX, le SDK Client Informix 2.81 UC1 ou supérieur doit être installé sur le même système que PHP. Le SDK Client Informix est disponible sur le » Site de Support IBM Informix.

PDO_INFORMIX est une extension » PECL, alors suivez les instructions dans Installation d'extensions PECL pour installer l'extension PDO_INFORMIX. Écrivez la commande configure pour pointer au chemin des fichiers d'en-têtes SDK Client Informix ainsi que les bibliothèques comme suit :

       bash$ ./configure --with-pdo-informix=/path/to/SDK[,shared]

La commande configure utilise par défaut la variable d'environnement INFORMIXDIR.

## Curseurs défilables

PDO_INFORMIX supporte les curseurs défilables; cependant, ils ne sont pas activés par défaut. Pour activer le support des curseurs défilables, il faut soit fixer `ENABLESCROLLABLECURSORS=1` dans les configurations de la connexion ODBC correspondante dans odbc.ini ou passer la clause `EnableScrollableCursors=1` dans la chaîne de caractères de connexion DSN.

# PDO_INFORMIX DSN

(PECL PDO_INFORMIX >= 0.1.0)

PDO_INFORMIX DSN — Connexion aux bases de données Informix

### Description

Le Data Source Name (DSN) de PDO_INFORMIX est basé sur la chaîne de caractères DSN d'Informix ODBC. Les détails sur la configuration d'un DSN Informix ODBC sont disponibles sur » `Informix Dynamic Server Information Center`. Les composants majeurs de DSN de PDO_INFORMIX sont :

DSN prefix

  Le préfixe DSN est `informix:`.

DSN

  Le DSN peut soit être une source de données de configuration en utilisant odbc.ini ou une » chaîne de caractères de connexion complète.

### Exemples

Exemple #1 Exemple DSN de PDO_INFORMIX avec odbc.ini

L'exemple suivant montre PDO_INFORMIX DSN pour se connecter à une base de données Informix cataloguée comme Infdrv33 dans odbc.ini :

    $db = new PDO("informix:DSN=Infdrv33", "", "");

    [ODBC Data Sources]
    Infdrv33=INFORMIX 3.3 32-BIT

    [Infdrv33]
    Driver=/opt/informix/csdk_2.81.UC1G2/lib/cli/iclis09b.so
    Description=INFORMIX 3.3 32-BIT
    Database=common_db
    LogonID=testuser
    pwd=testpass
    Servername=ids_server
    DB_LOCALE=en_US.819
    OPTIMIZEAUTOCOMMIT=1
    ENABLESCROLLABLECURSORS=1

Exemple #2 Exemple DSN de PDO_INFORMIX avec une chaîne de caractères de connexion

L'exemple suivant montre PDO_INFORMIX DSN pour se connecter à une base de données Informix nommée `common_db` en utilisant la syntaxe de chaîne de caractères de connexion Informix.

    $db = new PDO("informix:host=host.domain.com; service=9800;
        database=common_db; server=ids_server; protocol=onsoctcp;
        EnableScrollableCursors=1", "testuser", "tespass");

## Sommaire

- PDO_INFORMIX DSN — Connexion aux bases de données Informix

# Fonctions du pilote PDO MySQL (PDO_MYSQL)

## Introduction

PDO_MYSQL est un pilote qui implémente l'interface de PHP Data Objects (PDO) pour autoriser l'accès de PHP aux bases de données MySQL.

PDO_MYSQL utilise des requêtes préparées émulées par défaut.

MySQL 8

Si PHP est utilisé dans une version 7.1 antérieure à la version 7.1.16, ou PHP 7.2 antérieure à 7.2.4, le plugin de mot de passe doit être défini à mysql_native_password pour MySQL 8 Server, car sinon des erreurs similaires à The server requested authentication method unknown to the client [caching_sha2_password] peuvent apparaître, même si caching_sha2_password n'est pas utilisé.

Ceci est dû au fait que MySQL 8 utilise par défaut caching_sha2_password, un plugin qui n'est pas reconnu par les anciennes versions de PHP (mysqlnd). À la place il faut modifier le paramètre `default_authentication_plugin=mysql_native_password` dans my.cnf. Le plugin caching_sha2_password est pleinement supporté à partir de PHP 7.4.4. Pour les versions antérieures, l'extension mysql_xdevapi le supporte.

Avertissement

Prendre garde toutefois : certains types de tables MySQL (moteur d'enregistrement) ne supportent pas les transactions. Lorsque l'on écrit du code de base de données transactionnel en utilisant un type de table qui ne supporte pas les transactions, MySQL prétendra qu'une transaction était initiée correctement. De plus, toute requête DDL publiée enverra implicitement l'ensemble des transactions en attente.

> Note:

> Le pilote MySQL ne supporte pas proprement `PDO::PARAM_INPUT_OUTPUT` via PDOStatement::bindParam(); tandis que de tels paramètres peuvent être utilisés, ils ne seront pas mis à jour (c.à.d. la sortie actuelle est ignorée).

## Installation

Les distributions Linux incluent des versions binaires de PHP qui peuvent être installées. Même si ces binaires sont construits avec les extensions MySQL, les bibliothèques clientes doivent souvent être installées au moyen d'un paquet additionnel. Voir si c'est le cas pour le distribution.

Par exemple, sur Ubuntu le package `php5-mysql` installe les extensions PHP ext/mysql, ext/mysqli, et pdo_mysql. Sur CentOS, le package `php-mysql` installe aussi ces trois extensions PHP.

Alternativement, il est possible de compiler cette extension soi-même. Construire PHP depuis les sources permet de préciser les extensions MySQL à embarquer, mais aussi les bibliothèques clientes de chaque extension.

Lors de la compilation, utiliser --with-pdo-mysql[=DIR] pour installer l'extension PDO MySQL, où `[=DIR]` est le chemin de la bibliothèque de base de MySQL. Mysqlnd est la bibliothèque par défaut. Pour plus de détails à propos du choix de la bibliothèque, voir Choisir une bibliothèque MySQL.

Optionnellement, l'option --with-mysql-sock[=DIR] définit le chemin vers le socket Unix MySQL pour toutes les extensions MySQL, y compris PDO_MYSQL. Si non spécifié, les chemins par défaut seront utilisés.

Optionnellement, l'option --with-zlib-dir[=DIR] sera utilisée pour définir le préfixe d'installation zlib.

    $ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock

Le support SSL est activé en utilisant les constantes `Pdo\Mysql::ATTR_SSL_*`, ce qui équivaut à appeler la fonction API C » mysql_ssl_set(). De plus, SSL ne peut pas être activé avec PDO::setAttribute() car la connexion existe déjà. Voir également la documentation MySQL concernant » la connexion à MySQL avec SSL.

## Constantes pré-définies

Les constantes ci-dessous sont définies par ce pilote et seront seulement disponibles lorsque l'extension aura été compilée dans PHP ou chargée dynamiquement du moteur d'exécution. De plus, ces constantes spécifiques au pilote devraient être utilisées seulement si vous utilisez ce pilote. En utilisant les attributs spécifiques à un pilote avec un autre pilote pourrait causer un comportement inattendu. PDO::getAttribute() pourrait être utilisé pour obtenir l'attribut `PDO::ATTR_DRIVER_NAME` pour vérifier le pilote, si votre code peut fonctionner sur des pilotes multiples.

Avertissement

Les constantes listées ci-dessous sont OBSOLÈTES à partir de PHP 8.5.0. Utiliser les constantes Pdo\Mysql correspondantes à la place.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY` (int)
  Alias de `Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
`PDO::MYSQL_ATTR_LOCAL_INFILE` (int)
  Alias de `Pdo\Mysql::ATTR_LOCAL_INFILE`
`PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY` (int)
  Alias de `Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`. Disponible à partir de PHP 8.1.0.
`PDO::MYSQL_ATTR_INIT_COMMAND` (int)
  Alias de `Pdo\Mysql::ATTR_INIT_COMMAND`
`PDO::MYSQL_ATTR_READ_DEFAULT_FILE` (int)
  Alias de `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
`PDO::MYSQL_ATTR_READ_DEFAULT_GROUP` (int)
  Alias de `Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
`PDO::MYSQL_ATTR_MAX_BUFFER_SIZE` (int)
  Alias de `Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
`PDO::MYSQL_ATTR_DIRECT_QUERY` (bool)
  Alias de `PDO::ATTR_EMULATE_PREPARES` À partir de PHP 8.4.0, cette constante est de type bool ; elle était auparavant de type int.
`PDO::MYSQL_ATTR_FOUND_ROWS` (int)
  Alias de `Pdo\Mysql::ATTR_FOUND_ROWS`
`PDO::MYSQL_ATTR_IGNORE_SPACE` (int)
  Alias de `Pdo\Mysql::ATTR_IGNORE_SPACE`
`PDO::MYSQL_ATTR_COMPRESS` (int)
  Alias de `Pdo\Mysql::ATTR_COMPRESS`
`PDO::MYSQL_ATTR_SERVER_PUBLIC_KEY` (int)
  Alias de `Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
`PDO::MYSQL_ATTR_SSL_CA` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_CA`
`PDO::MYSQL_ATTR_SSL_CAPATH` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_CAPATH`
`PDO::MYSQL_ATTR_SSL_CERT` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_CERT`
`PDO::MYSQL_ATTR_SSL_CIPHER` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_CIPHER`
`PDO::MYSQL_ATTR_SSL_KEY` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_KEY`
`PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT` (int)
  Alias de `Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT` Disponible à partir de PHP 7.0.18 et PHP 7.1.4.
`PDO::MYSQL_ATTR_MULTI_STATEMENTS` (int)
  Alias de `Pdo\Mysql::ATTR_MULTI_STATEMENTS`

## Configuration à l'exécution

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

Options de configuration du driver PDO_MYSQL
Nom | Défaut | Modifiable
--- | --- | ---
pdo_mysql.default_socket | "/tmp/mysql.sock" | `INI_SYSTEM`
pdo_mysql.debug | NULL | `INI_SYSTEM`

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`pdo_mysql.default_socket` string

  Définit un socket de domaine Unix. La valeur peut aussi être définie au moment de la compilation si un socket de domaine Unix est trouvé lors de la configuration. Cette configuration INI n'est disponible que sous Unix.

`pdo_mysql.debug` bool

  Active le débogage pour le driver PDO_MYSQL. Cette configuration n'est disponible que lorsque le driver PDO_MYSQL est compilé avec mysqlnd et en mode de débogage PDO.

# PDO_MYSQL DSN

(PECL PDO_MYSQL >= 0.1.0)

PDO_MYSQL DSN — Connexion aux bases de données MySQL

### Description

Le Data Source Name (DSN) de PDO_MYSQL est composé des éléments suivants :

Préfixe DSN

  Le préfixe DSN est `mysql:`.

`host`

  L'hôte sur lequel le serveur de base de données se situe.

`port`

  Le numéro de port où le serveur de base de données est en train d'écouter.

`dbname`

  Le nom de la base de données.

`unix_socket`

  Le socket Unix MySQL (ne devrait pas être utilisé avec `host` ou `port`).

`charset`

  Le jeu de caractères. Voir la documentation sur les concepts des jeux de caractères pour plus d'informations.

### Exemples

Exemple #1 Exemples avec le DSN de PDO_MYSQL

L'exemple suivant montre le DSN PDO_MYSQL pour se connecter aux bases de données MySQL :

    mysql:host=localhost;dbname=testdb

Exemples plus complets :

    mysql:host=localhost;port=3307;dbname=testdb
    mysql:unix_socket=/tmp/mysql.sock;dbname=testdb

### Notes

> Note: Unix seulement:

> Lorsque le nom d'hôte est `"localhost"`, la connexion est faite par un socket Unix. Si PDO_MYSQL est compilé avec `libmysqlclient`, alors le fichier de socket est celui précisé à la compilation de `libmysqlclient`. Si PDO_MYSQL est compilé avec `mysqlnd`, un socket par défaut peut être indiqué via le paramètre pdo_mysql.default_socket.

## Sommaire

- PDO_MYSQL DSN — Connexion aux bases de données MySQL

# La classe Pdo\Mysql

(PHP 8 >= 8.4.0)

## Introduction

Une sous-classe de PDO représentant une connexion utilisant le pilote MySQL PDO.

Ce pilote supporte un analyseur de requêtes SQL dédié pour le dialecte MySQL. Il peut gérer les éléments suivants :

- Les littéraux à guillemets simples et doubles avec le doublement et le backslash comme mécanismes d'échappement
- Les littéraux à accent grave avec le doublement comme mécanisme d'échappement
- Deux tirets, les commentaires de style C et les commentaires de type hash

## Synopsis de la classe

class Pdo\Mysql extends PDO {
/* Constantes héritées */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_USE_BUFFERED_QUERY;
public const int ATTR_LOCAL_INFILE;
public const int ATTR_LOCAL_INFILE_DIRECTORY;
public const int ATTR_INIT_COMMAND;
public const int ATTR_MAX_BUFFER_SIZE;
public const int ATTR_READ_DEFAULT_FILE;
public const int ATTR_READ_DEFAULT_GROUP;
public const int ATTR_COMPRESS;
public const int ATTR_DIRECT_QUERY;
public const int ATTR_FOUND_ROWS;
public const int ATTR_IGNORE_SPACE;
public const int ATTR_MULTI_STATEMENTS;
public const int ATTR_SERVER_PUBLIC_KEY;
public const int ATTR_SSL_KEY;
public const int ATTR_SSL_CERT;
public const int ATTR_SSL_CA;
public const int ATTR_SSL_CAPATH;
public const int ATTR_SSL_CIPHER;
public const int ATTR_SSL_VERIFY_SERVER_CERT;
/* Méthodes */
public function getWarningCount(): int
/* Méthodes héritées */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes pré-définies

`Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
  Par défaut, toutes les requêtes sont exécutées en mode tamponné. Si cet attribut est défini à `false` sur un objet Pdo\Mysql, le pilote MySQL utilisera le mode non tamponné.

  Exemple #1 Activation du mode non tamponné MySQL

      <?php
      $pdo = new Pdo\Mysql("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
      $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

      $unbufferedResult = $pdo->query("SELECT Name FROM City");
      foreach ($unbufferedResult as $row) {
          echo $row['Name'] . PHP_EOL;
      }
      ?>

`Pdo\Mysql::ATTR_LOCAL_INFILE`
  Active `LOAD LOCAL INFILE`.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`
  Permet de restreindre le chargement de données locales aux fichiers situés dans ce répertoire désigné.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_INIT_COMMAND`
  La commande à exécuter lors de la connexion au serveur MySQL. Sera automatiquement réexécutée lors de la reconnexion.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
  Lire les options du fichier d'options nommé au lieu de my.cnf.

  > Note: Cette option n'est pas disponible si mysqlnd est utilisé, car mysqlnd ne lit pas les fichiers de configuration mysql.

`Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
  Lit les options du groupe nommé du fichier my.cnf ou le fichier spécifié avec `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`.

  > Note: Cette option n'est pas disponible si mysqlnd est utilisé, car mysqlnd ne lit pas les fichiers de configuration mysql.

`Pdo\Mysql::ATTR_COMPRESS`
  Active la compression de la communication réseau.
`Pdo\Mysql::ATTR_DIRECT_QUERY`
  Alias de `PDO::ATTR_EMULATE_PREPARES`.
`Pdo\Mysql::ATTR_FOUND_ROWS`
  Renvoie le nombre de lignes trouvées (correspondantes), pas le nombre de lignes modifiées.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_IGNORE_SPACE`
  Permet les espaces après les noms de fonctions SQL. Rend tous les noms de fonctions SQL des mots réservés.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
  La taille maximale du tampon. Par défaut, 1 Mo.

  > Note: Cette constante n'est pas supportée lorsqu'elle est compilée avec mysqlnd.

`Pdo\Mysql::ATTR_MULTI_STATEMENTS`
  Désactive l'exécution de requêtes multiples dans PDO::prepare() et PDO::query() lorsque défini à `false`.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
  RSA le chemin du fichier de clé publique utilisé avec l'authentification basée sur SHA-256.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_SSL_KEY`
  Le chemin du fichier de clé SSL.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_SSL_CERT`
  Le chemin du certificat SSL.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_SSL_CA`
  Le chemin du certificat d'autorité SSL.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_SSL_CAPATH`
  Le chemin du répertoire qui contient les certificats d'autorité SSL CA, stockés au format PEM.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_SSL_CIPHER`
  Une liste d'un ou plusieurs chiffrements autorisés à utiliser pour SSL, dans un format compris par OpenSSL. Par exemple : `DHE-RSA-AES256-SHA:AES128-SHA`

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

`Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT`
  Apporte un moyen de désactiver la vérification du certificat du serveur SSL.

  > Note: Cette option est disponible uniquement avec mysqlnd.

  > Note: Peut uniquement être utilisé dans le tableau `driver_options` lors de la construction d'une nouvelle connexion à la base de données.

# Pdo\Mysql::getWarningCount

(PHP 8 >= 8.4.0)

Pdo\Mysql::getWarningCount — Renvoie le nombre d'avertissements de la dernière requête exécutée

### Description

public function Pdo\Mysql::getWarningCount(): int

Renvoie le nombre d'avertissements de la dernière requête exécutée.

> Note: Pour récupérer les messages d'avertissement, la commande SQL suivante peut être utilisée : `SHOW WARNINGS [limit row_count]`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un int représentant le nombre d'avertissements générés par la dernière requête.

### Exemples

Exemple #1 Exemple de Pdo\Mysql::getWarningCount()

    <?php

    $conn = PDO::connect("mysql:host=localhost;dbname=test;charset=utf8mb4", 'user', 'password');

    $conn->query('SELECT 42/0');
    if ($conn->getWarningCount() > 0) {
        $result = $conn->query("SHOW WARNINGS");
        $row = $result->fetch();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

    ?>

L'exemple ci-dessus va afficher :

    Warning (1365): Division by 0

## Sommaire

- Pdo\Mysql::getWarningCount — Renvoie le nombre d'avertissements de la dernière requête exécutée

# Fonctions Microsoft du pilote PDO SQL Server (PDO_SQLSRV)

## Introduction

PDO_SQLSRV est un pilote qui implémente l'interface PDO (PHP Data Objects) pour permettre l'accès à partir de PHP aux bases de données MS SQL Server (version SQL Server 2005 et supérieures) et SQL Azure.

## Installation

La version la plus récente du pilote est disponible au téléchargement ici : » téléchargement SQLSRV. Les sources du pilote sont hébergées dans un » dépôt public.

Pour plus d'information à propos des exigences système, consulter le chapitre sur les » exigences systèmes SQLSRV.

Sur Windows, l'extension PDO_SQLSRV est activée en téléchargeant et en ajoutant les fichiers DLL appropriés dans le répertoire d'extension PHP et l'entrée correspondante dans le fichier php.ini.

Sur Linux et macOS, l'extension PDO_SQLSRV peut être installée en utilisant » PECL. Voir le » tutoriel d'installation pour plus de détails. » driver ODBC du serveur SQL Microsoft pour Linux.

## Constantes pré-définies

Les constantes ci-dessous sont définies par ce pilote et seront seulement disponibles lorsque l'extension aura été compilée dans PHP ou chargée dynamiquement du moteur d'exécution. De plus, ces constantes spécifiques au pilote devraient être utilisées seulement si vous utilisez ce pilote. En utilisant les attributs spécifiques à un pilote avec un autre pilote pourrait causer un comportement inattendu. PDO::getAttribute() pourrait être utilisé pour obtenir l'attribut `PDO::ATTR_DRIVER_NAME` pour vérifier le pilote, si votre code peut fonctionner sur des pilotes multiples.

`PDO::SQLSRV_TXN_READ_UNCOMMITTED` (int)
  Cette constante est une valeur possible pour la clé "TransactionIsolation" du DSN pour SQLSRV. Cette constante positionne le niveau d'isolation de la transaction à "Read Uncommitted".
`PDO::SQLSRV_TXN_READ_COMMITTED` (int)
  Cette constante est une valeur possible pour la clé "TransactionIsolation" du DSN pour SQLSRV. Cette constante positionne le niveau d'isolation de la transaction à "Read Committed".
`PDO::SQLSRV_TXN_REPEATABLE_READ` (int)
  Cette constante est une valeur possible pour la clé "TransactionIsolation" du DSN pour SQLSRV. Cette constante positionne le niveau d'isolation de la transaction à "Repeateable Read".
`PDO::SQLSRV_TXN_SNAPSHOT` (int)
  Cette constante est une valeur possible pour la clé "TransactionIsolation" du DSN pour SQLSRV. Cette constante positionne le niveau d'isolation de la transaction à "Snapshot".
`PDO::SQLSRV_TXN_SERIALIZABLE` (int)
  Cette constante est une valeur possible pour la clé "TransactionIsolation" du DSN pour SQLSRV. Cette constante positionne le niveau d'isolation de la transaction à "Serializable".
`PDO::SQLSRV_ENCODING_BINARY` (int)
  Spécifie que cette donnée est envoyée vers le (ou reçue du) serveur comme un flux d'octets, sans opérer d'encodage ou de traduction. Cette constante peut être utilisée dans les appels à PDOStatement::setAttribute, PDO::prepare, PDOStatement::bindColumn, et PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_SYSTEM` (int)
  Spécifie que cette donnée est envoyée vers le (ou reçue du) serveur comme un flux de caractères 8 bits, comme spécifié dans la page de code de la locale Windows active sur le système. Tout caractère multioctet, ou caractère qui n'existe pas dans cette page de code, est substitué par un simple point d'interrogation (?). Cette constante peut être utilisée dans les appels à PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, et PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_UTF8` (int)
  Spécifie que cette donnée est envoyée vers le (ou reçue du) serveur comme un flux de caractères UTF-8. Il s'agit de l'encodage par défaut. Cette constante peut être utilisée dans les appels à PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, et PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_DEFAULT` (int)
  Spécifie que cette donnée est envoyée vers le (ou reçue du) serveur en utilisant l'encodage PDO::SQLSRV_ENCODING_SYSTEM si elle est spécifiée pendant la connexion. Si elle est spécifiée dans une instruction "prepare", c'est l'encodage de la connexion qui est utilisé. Cette constante peut être utilisée dans les appels à PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, et PDOStatement::bindParam.
`PDO::SQLSRV_ATTR_QUERY_TIMEOUT` (int)
  Un entier positif ou nul représentant la durée de timeout, en secondes. Zéro (0) est la valeur par défaut et signifie qu'il n'y a pas de timeout. Cette constante peut être utilisée dans les appels à PDOStatement::setAttribute, PDO::setAttribute, et PDO::prepare.
`PDO::SQLSRV_ATTR_DIRECT_QUERY` (int)
  Indique une requête qui doit être exécutée directement, sans être préparée. Cette constante peut être utilisée dans les appels à PDO::setAttribute, et PDO::prepare. Pour plus d'informations, voir (en anglais) » Direct and Prepared Statement Execution.

# PDO_SQLSRV DSN

(PECL pdo_sqlsrv >= 2.0.1)

PDO_SQLSRV DSN — Connexion à des bases de données MS SQL Server et SQL Azure

### Description

Le fichier DSN (Data Source Name) PDO_SQLSRV est composé des éléments suivants :

préfixe DSN

  Le préfixe DSN est `sqlsrv:`.

`APP`
  Le nom de l'application, utilisé pour les traces.
`ConnectionPooling`
  Spécifie si la connexion est assignée à un pool de connexions (1 ou `true`) ou non (0 ou `false`).
`Database`
  Le nom de la base de données.
`Encrypt`
  Spécifie si la communication avec le serveur SQL Server est chiffrée (1 ou `true`) ou non chiffrée (0 ou `false`).
`Failover_Partner`
  Spécifie le serveur et l'instance de la base de données miroir (si elle est activée et configurée) à utiliser quand le serveur principal est inaccessible.
`LoginTimeout`
  Spécifie le nombre de secondes d'attente avant de stopper et mettre en erreur la tentative de connexion.
`MultipleActiveResultSets`
  Désactive, ou active explicitement, le support pour des jeux de résultats multiples (Multiple Active Result Sets, MARS).
`QuotedId`
  Spécifie s'il faut utiliser les règles SQL-92 pour les identifiants entre guillemets (1 ou `true`) ou s'il faut utiliser les règles Transact-SQL standard (0 ou `false`).
`Server`
  Le nom du serveur de base de données.
`TraceFile`
  Le chemin du fichier utilisé pour les traces.
`TraceOn`
  Spécifie si les traces ODBC sont activées (1 ou `true`) ou désactivées (0 ou `false`) à l'activation de la connexion.
`TransactionIsolation`
  Spécifie le niveau d'isolation de la transaction. Les valeurs possibles pour cette option sont PDO::SQLSRV_TXN_READ_UNCOMMITTED, PDO::SQLSRV_TXN_READ_COMMITTED, PDO::SQLSRV_TXN_REPEATABLE_READ, PDO::SQLSRV_TXN_SNAPSHOT, et PDO::SQLSRV_TXN_SERIALIZABLE.
`TrustServerCertificate`
  Spécifie si le client doit faire confiance (1 ou `true`) ou rejeter (0 ou `false`) un certificat serveur autosigné.
`WSID`
  Spécifie le nom de l'ordinateur pour les traces.

### Exemples

Exemple #1 Exemples de DSN PDO_SQLSRV

L'exemple suivant montre comment se connecter à la base de données MS SQL Server spécifiée :

    $c = new PDO("sqlsrv:Server=localhost;Database=bddtest", "Utilisateur", "MotDePasse");

L'exemple suivant montre comment se connecter à la base de données MS SQL Server spécifiée sur un port spécifique :

    $c = new PDO("sqlsrv:Server=localhost,1521;Database=bddtest", "Utilisateur", "MotDePasse");

L'exemple suivant montre comment se connecter à une base de données SQL Azure avec l'ID serveur 12345abcde. À noter que, quand on l'on se connecte à Azure avec PDO, le nom d'utilisateur sera Utilisateur@12345abcde (Utilisateur@IdServeur).

    $c = new PDO("sqlsrv:Server=12345abcde.database.windows.net;Database=bddtest", "Utilisateur@12345abcde", "MotDePasse");

## Sommaire

- PDO_SQLSRV DSN — Connexion à des bases de données MS SQL Server et SQL Azure

# Fonctions du pilote PDO Oracle (PDO_OCI)

## Installation

Si la base de données Oracle est sur la même machine que PHP, le logiciel de base de données contient déjà les bibliothèques nécessaires. Quand PHP est sur une machine différente, utiliser les bibliothèques gratuites » Oracle Instant Client. Pour plus de détails consulter la section sur Prérequis OCI8.

## PHP 8.4

Cette extension a été déplacée dans le module » PECL et ne sera plus intégrée dans PHP à partir de PHP 8.4.0

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/PDO_OCI.

## PHP < 8.4

Utiliser --with-pdo-oci[=DIR] pour installer l'extension PDO Oracle OCI, où l'optionnel `[=DIR]` est le répertoire Oracle Home. `[=DIR]` correspond par défaut à la variable d'environnement $ORACLE_HOME.

Utiliser --with-pdo-oci=instantclient,prefix,version pour un SDK Oracle Instant Client, où prefix et version sont configurés.

    // Utilisation de $ORACLE_HOME
    $ ./configure --with-pdo-oci

    // Utilisation de OIC pour Linux avec 10.2.0.3 RPMs avec le préfixe /usr
    $ ./configure --with-pdo-oci=instantclient,/usr,10.2.0.3

## Constantes pré-définies

Les constantes ci-dessous sont définies par ce pilote et seront seulement disponibles lorsque l'extension aura été compilée dans PHP ou chargée dynamiquement du moteur d'exécution. De plus, ces constantes spécifiques au pilote devraient être utilisées seulement si vous utilisez ce pilote. En utilisant les attributs spécifiques à un pilote avec un autre pilote pourrait causer un comportement inattendu. PDO::getAttribute() pourrait être utilisé pour obtenir l'attribut `PDO::ATTR_DRIVER_NAME` pour vérifier le pilote, si votre code peut fonctionner sur des pilotes multiples.

`PDO::OCI_ATTR_ACTION` (int)

  Fournit un moyen de spécifier l'action sur la session de base de données.

  Existe à partir de PHP 7.2.16 et 7.3.3

`PDO::OCI_ATTR_CLIENT_INFO` (int)

  Fournit un moyen de spécifier l'information du client sur la session de base de données.

  Existe à partir de PHP 7.2.16 et 7.3.3

`PDO::OCI_ATTR_CLIENT_IDENTIFIER` (int)

  Fournit un moyen de spécifier l'identifiant de client sur la session de base de données.

  Existe à partir de PHP 7.2.16 et 7.3.3

`PDO::OCI_ATTR_MODULE` (int)

  Fournit un moyen de spécifier le module sur la session de base de données.

  Existe à partir de PHP 7.2.16 et 7.3.3

# PDO_OCI DSN

(PECL PDO_OCI >= 0.1.0)

PDO_OCI DSN — Connexion aux bases de données Oracle

### Description

Le Data Source Name (DSN) de PDO_OCI est composé des éléments suivants :

Préfixe DSN

  Le préfixe DSN est `oci:`.

`dbname` (Oracle Instant Client)

  L'URI de la connexion Oracle Instant Client prend la forme de `dbname=//hostname:port-number/database`. Si l'on se connecte sur une base de données définie dans tnsnames.ora, utiliser seulement le nom de la base de données : `dbname=database`.

`charset`

  Le jeu de caractères côté client pour l'environnement courant.

### Exemples

Exemple #1 Exemples avec PDO_OCI DSN

Les exemples suivants montrent PDO_OCI DSN pour se connecter aux bases de données Oracle :

    // Connexion à une base de données définie dans tnsnames.ora
    oci:dbname=mydb

    // Connexion en utilisant le client Oracle Instant
    oci:dbname=//localhost:1521/mydb

## Sommaire

- PDO_OCI DSN — Connexion aux bases de données Oracle

# Fonctions du pilote PDO ODBC et DB2 (PDO_ODBC)

## Introduction

PDO_ODBC est un pilote qui implémente l'interface de PHP Data Objects (PDO) pour autoriser l'accès de PHP aux bases de données par les pilotes d'ODBC ou par la bibliothèque d'interface IBM DB2 Call Level (DB2 CLI). PDO_ODBC supporte actuellement trois "saveurs" différentes des pilotes de bases de données :

ibm-db2

  Supporte l'accès à `IBM DB2 Universal Database`, Cloudscape et Apache Derby Server à l'aide du client gratuit DB2 express-C.

unixODBC

  Supporte l'accès aux serveurs de base de données à l'aide du pilote de gestion unixODBC et les bases de données possédées par les pilotes ODBC.

generic

  Offre une option de compilation pour les pilotes de gestion ODBC qui ne sont pas explicitement supportés par PDO_ODBC.

Sur Windows, php_pdo_odbc.dll doit être activé en tant qu'extension dans php.ini. Il est lié avec le Windows ODBC Driver Manager, c'est pourquoi PHP peut se connecter à n'importe quelle base de données cataloguée comme étant un System DSN.

## Installation

PDO_ODBC sur les systèmes UNIX

1. PDO_ODBC est inclus dans les sources de PHP. Il est possible de compiler l'extension PDO_ODBC soit en statique ou en module partagé en utilisant les commandes configure suivantes.

   ibm_db2

         ./configure --with-pdo-odbc=ibm-db2,/opt/IBM/db2/V8.1/

     Pour construire PDO_ODBC avec la saveur ibm-db2, il faut avoir précédemment installé les en-têtes de développement de l'application de DB2 sur la même machine sur laquelle l'on compile PDO_ODBC. Les en-têtes de développement de l'application DB2 sont une option d'installation dans les serveurs DB2 et sont aussi disponibles en tant que `DB2 Application Development Client` gratuitement disponibles pour téléchargement à partir du » site `IBM developerWorks`.

     Si on ne spécifie pas d'emplacement pour les bibliothèques et les en-têtes de DB2 à la commande configure, PDO_ODBC prendra par défaut /home/db2inst1/sqllib.

   unixODBC

         ./configure --with-pdo-odbc=unixODBC,/usr/local

     Si on ne spécifie pas d'emplacement pour les bibliothèques et les en-têtes d'unixODBC à la commande configure, PDO_ODBC prendra par défaut /usr/local.
   generic

         ./configure --with-pdo-odbc=generic,/usr/local,libname,ldflags,cflags

## Constantes pré-définies

Les constantes ci-dessous sont définies par ce pilote et seront seulement disponibles lorsque l'extension aura été compilée dans PHP ou chargée dynamiquement du moteur d'exécution. De plus, ces constantes spécifiques au pilote devraient être utilisées seulement si vous utilisez ce pilote. En utilisant les attributs spécifiques à un pilote avec un autre pilote pourrait causer un comportement inattendu. PDO::getAttribute() pourrait être utilisé pour obtenir l'attribut `PDO::ATTR_DRIVER_NAME` pour vérifier le pilote, si votre code peut fonctionner sur des pilotes multiples.

`PDO_ODBC_TYPE` (string)
  Décrit la bibliothèque ODBC à laquelle l'extension PDO_ODBC est liée. Les valeurs possibles incluent `unixODBC`, `iODBC`, ou `generic`.

Avertissement

Les constantes listées ci-dessous sont OBSOLÈTES à partir de PHP 8.5.0. Utiliser les constantes Pdo\Odbc correspondantes à la place.

`PDO::ODBC_ATTR_USE_CURSOR_LIBRARY` (int)
  Alias de `Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`.
`PDO::ODBC_SQL_USE_IF_NEEDED` (int)
  Alias de `Pdo\Odbc::SQL_USE_IF_NEEDED`.
`PDO::ODBC_SQL_USE_DRIVER` (int)
  Alias de `Pdo\Odbc::SQL_USE_DRIVER`.
`PDO::ODBC_SQL_USE_ODBC` (int)
  Alias de `Pdo\Odbc::SQL_USE_ODBC`.
`PDO::ODBC_ATTR_ASSUME_UTF8` (bool)
  Alias de `Pdo\Odbc::ATTR_ASSUME_UTF8`.

## Configuration à l'exécution

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

Options de configuration PDO_ODBC
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
pdo_odbc.connection_pooling | "strict" | `INI_ALL` |
pdo_odbc.db2_instance_name | `null` | `INI_SYSTEM` | Cette fonctionnalité obsolète sera certainement supprimée dans le futur.

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`pdo_odbc.connection_pooling` string

  Pour mettre en commun les connexions ODBC. Peut être `"strict"`, `"relaxed"` ou `"off"` (égal à `""`). Le paramètre décrit comment la gestion de la connexion stricte devrait être lorsque les paramètres de connexion se ressemblent pour des connexions mises en commun. `strict` est la valeur par défaut recommandée et permettra l'utilisation des connexions en cache lorsque des paramètres de connexion similaires sont utilisés. `relaxed` permettra d'utiliser des connexions mises en cache lorsque des paramètres de connexion similaire seront utilisés. Cela peut augmenter l'utilisation du cache au risque de noyer les informations de connexion entre (par exemple) des serveurs virtuels.

  Cette configuration peut seulement être changée à partir du fichier php.ini et affecte le processus entier; n'importe quels autres modules chargés dans le processus qui utilisent les bibliothèques ODBC seront aussi affectés, en incluant l'extension unifiée ODBC.

  Avertissement

  `relaxed` ne devrait pas être utilisé sur les serveurs partagés, pour des raisons de sécurité.

  Astuce

  Laissez cette configuration à la valeur par défaut `strict` à moins que l'on ait une bonne raison pour la changer.

`pdo_odbc.db2_instance_name` string

  Si l'on compile PDO_ODBC en utilisant `db2`, cette configuration fixe la valeur de la variable d'environnement DB2INSTANCE sur les systèmes d'exploitation Linux et UNIX au nom spécifié de l'instance DB2. Ceci permet à PDO_ODBC de résoudre le chemin des bibliothèques DB2 et de faire des connexions cataloguées aux bases de données DB2.

  Cette configuration peut seulement être changée à partir du fichier php.ini et affecte le processus entier; n'importe quels autres modules chargés dans le processus qui utilisent les mêmes bibliothèques ODBC seront aussi affectés, incluant l'extension unifiée ODBC.

  Cette configuration n'a aucun effet sur Windows.

# PDO_ODBC DSN

(PECL PDO_ODBC >= 0.1.0)

PDO_ODBC DSN — Connexion aux bases de données ODBC ou DB2

### Description

Le Data Source Name (DSN) de PDO_ODBC est composé des éléments suivants :

Préfixe DSN

  Le préfixe DSN est `odbc:`. Si l'on se connecte à une base de données cataloguée dans le pilote d'ODBC Manager ou dans le catalogue de DB2, il est possible d'ajouter le nom du catalogue de la base de données au DSN.

DSN

  Le nom de la base de données étant catalogué dans le pilote ODBC Manager ou le catalogue DB2. Alternativement, il est possible de fournir une chaîne de connexion complète pour ODBC pour se connecter à une base de données comme décrit à » http://www.connectionstrings.com/.

`UID`

  Le nom de l'utilisateur pour la connexion. Si l'on spécifie l'utilisateur dans le DSN, PDO ignorera la valeur de l'utilisateur en argument dans le constructeur PDO.

`PWD`

  Le mot de passe de l'utilisateur pour la connexion. Si l'on spécifie le mot de passe dans le DSN, PDO ignorera la valeur du mot de passe en argument dans le constructeur PDO.

### Historique

Version | Description
--- | ---
8.4.0 | Lors du passage d'une string vide à l'argument mot de passe dans le constructeur PDO, `pwd` n'était pas inclus dans la chaîne de connexion créée jusqu'à présent, mais le comportement a été modifié pour l'inclure en tant que chaîne vide. Passer `null` pour l'argument mot de passe dans le constructeur PDO entraîne le même comportement qu'auparavant.
8.4.0 | Changement du comportement pour ignorer séparément l'argument nom d'utilisateur et l'argument mot de passe dans le constructeur PDO lorsque le DSN contient `uid` ou `pwd`. Auparavant, si l'un ou l'autre de `uid` ou `pwd` était inclus dans le DSN, les arguments nom d'utilisateur et mot de passe dans le constructeur PDO étaient ignorés.

### Exemples

Exemple #1 Exemple avec PDO_ODBC DSN (pilote ODBC Manager)

L'exemple suivant montre PDO_ODBC DSN pour se connecter à une base de données ODBC cataloguée comme étant testdb dans le pilote ODBC Manager :

    odbc:testdb

Exemple #2 Exemple avec PDO_ODBC DSN (connexion non cataloguée IBM DB2)

L'exemple suivant montre PDO_ODBC DSN pour se connecter à une base de données IBM DB2 nommée `SAMPLE` en utilisant la syntaxe complète d'ODBC DSN :

    odbc:DRIVER={IBM DB2 ODBC DRIVER};HOSTNAME=localhost;PORT=50000;DATABASE=SAMPLE;PROTOCOL=TCPIP;UID=db2inst1;PWD=ibmdb2;

Exemple #3 Exemple avec PDO_ODBC DSN (connexion non cataloguée Microsoft Access)

L'exemple suivant montre PDO_ODBC DSN pour se connecter à une base de données Microsoft Access enregistrée à `C:\db.mdb` en utilisant la syntaxe complète de ODBC DSN :

    odbc:Driver={Microsoft Access Driver (*.mdb)};Dbq=C:\\db.mdb;Uid=Admin

## Sommaire

- PDO_ODBC DSN — Connexion aux bases de données ODBC ou DB2

# La classe Pdo\Odbc

(PHP 8 >= 8.4.0)

## Introduction

Une sous-classe de PDO représentant une connexion utilisant le pilote ODBC PDO.

## Synopsis de la classe

namespace Pdo;
class Odbc extends PDO {
/* Constantes héritées */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_USE_CURSOR_LIBRARY;
public const int ATTR_ASSUME_UTF8;
public const int SQL_USE_IF_NEEDED;
public const int SQL_USE_DRIVER;
public const int SQL_USE_ODBC;
/* Méthodes héritées */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes pré-définies

`Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`

  Cette option contrôle l'utilisation de la bibliothèque de curseurs ODBC. La bibliothèque de curseurs ODBC prend en charge certaines fonctionnalités ODBC avancées (par exemple, les curseurs défilables par blocs), qui peuvent ne pas être implémentées par le pilote. Les valeurs suivantes sont prises en charge :

  `Pdo\Odbc::SQL_USE_IF_NEEDED`
    Utilise la bibliothèque de curseurs ODBC si nécessaire. C'est la valeur par défaut.
  `Pdo\Odbc::SQL_USE_DRIVER`
    Ne jamais utiliser la bibliothèque de curseurs ODBC.
  `Pdo\Odbc::SQL_USE_ODBC`
    Toujours utiliser la bibliothèque de curseurs ODBC.
`Pdo\Odbc::ATTR_ASSUME_UTF8`
  Windows seulement. Si `true`, les données de caractères encodées en UTF-16 (`CHAR`, `VARCHAR` et `LONGVARCHAR`) sont converties en UTF-8 lors de la lecture ou de l'écriture de données dans la base de données. Si `false` (la valeur par défaut), la conversion de l'encodage des caractères peut être effectuée par le pilote.

# Fonctions du pilote PDO PostgreSQL (PDO_PGSQL)

## Introduction

PDO_PGSQL est un pilote qui implémente l'interface de PHP Data Objects (PDO) pour autoriser l'accès de PHP aux bases de données PostgreSQL.

## Types de ressources

Cette extension définit une ressource de flux, retournée par Pdo\Pgsql::lobOpen().

## Installation

Utiliser l'option de compilation --with-pdo-pgsql[=DIR] pour installer l'extension PDO PostgreSQL, où `[=DIR]` (optionnel) représente le chemin vers le dossier d'installation de base de PostgreSQL ou le chemin vers le fichier pg_config.

    $ ./configure --with-pdo-pgsql

## Constantes pré-définies

Les constantes ci-dessous sont définies par ce pilote et seront seulement disponibles lorsque l'extension aura été compilée dans PHP ou chargée dynamiquement du moteur d'exécution. De plus, ces constantes spécifiques au pilote devraient être utilisées seulement si vous utilisez ce pilote. En utilisant les attributs spécifiques à un pilote avec un autre pilote pourrait causer un comportement inattendu. PDO::getAttribute() pourrait être utilisé pour obtenir l'attribut `PDO::ATTR_DRIVER_NAME` pour vérifier le pilote, si votre code peut fonctionner sur des pilotes multiples.

`PDO::PGSQL_ATTR_DISABLE_PREPARES` (int)
  Alias de `Pdo\Pgsql::ATTR_DISABLE_PREPARES`. À partir de PHP 8.5.0, cette constante est obsolète.
`PDO::PGSQL_TRANSACTION_IDLE` (int)
  Équivalent à `Pdo\Pgsql::TRANSACTION_IDLE`. À partir de PHP 8.5.0, cette constante est obsolète, car elle n'a aucun effet.
`PDO::PGSQL_TRANSACTION_ACTIVE` (int)
  Équivalent à `Pdo\Pgsql::TRANSACTION_ACTIVE`. À partir de PHP 8.5.0, cette constante est obsolète, car elle n'a aucun effet.
`PDO::PGSQL_TRANSACTION_INTRANS` (int)
  Équivalent à `Pdo\Pgsql::TRANSACTION_INTRANS`. À partir de PHP 8.5.0, cette constante est obsolète, car elle n'a aucun effet.
`PDO::PGSQL_TRANSACTION_INERROR` (int)
  Équivalent à `Pdo\Pgsql::TRANSACTION_INERROR`. À partir de PHP 8.5.0, cette constante est obsolète, car elle n'a aucun effet.
`PDO::PGSQL_TRANSACTION_UNKNOWN` (int)
  Équivalent à `Pdo\Pgsql::TRANSACTION_UNKNOWN`. À partir de PHP 8.5.0, cette constante est obsolète, car elle n'a aucun effet.

## Notes générales

> Note: Les colonnes `bytea` sont retournées sous forme de ressources de flux. Voir Objets larges (LOBs) pour savoir comment lire ces valeurs et comment lier des données avec `PDO::PARAM_LOB`.

# PDO_PGSQL DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_PGSQL >= 0.1.0)

PDO_PGSQL DSN — Connexion aux bases de données PostgreSQL

### Description

Le Data Source Name (DSN) de PDO_PGSQL est composé des éléments suivants, délimités par des espaces ou des points-virgules :

Préfixe DSN

  Le préfixe DSN est `pgsql:`.

`host`

  L'hôte sur lequel le serveur de base de données se situe.

`port`

  Le port sur lequel le serveur de base de données s'exécute.

`dbname`

  Le nom de la base de données.

`user`

  Le nom de l'utilisateur pour la connexion. Si l'on spécifie l'utilisateur dans le DSN, PDO ignorera la valeur de l'utilisateur en argument dans le constructeur PDO.

`password`

  Le mot de passe de l'utilisateur pour la connexion. Si l'on spécifie le mot de passe dans le DSN, PDO ignorera la valeur du mot de passe en argument dans le constructeur PDO.

`sslmode`
  Le mode SSL. Les valeurs acceptées sont `disable`, `allow`, `prefer`, `require`, `verify-ca`, et `verify-full` ; leur signification est décrite dans la » Documentation PostgreSQL. De nombreux services PostgreSQL hébergés exigent une connexion chiffrée, ainsi `require` ou plus strict est nécessaire pour s'y connecter.

> Note: Tous les points-virgules dans la chaîne DSN sont remplacés par des espaces, parce que PostgreSQL s'attend à ce format. Cela implique que les points-virgules dans l'un des composants (par exemple `password` ou `dbname`) ne sont pas supportés.

### Exemples

Exemple #1 Exemples avec PDO_PGSQL DSN

L'exemple suivant montre PDO_PGSQL DSN pour se connecter à une base de données PostgreSQL :

    pgsql:host=localhost;port=5432;dbname=testdb;user=bruce;password=mypass

L'exemple suivant montre PDO_PGSQL DSN pour se connecter à une base de données PostgreSQL via une socket unix /tmp/.s.PGSQL.5432 :

    pgsql:host=/tmp;port=5432;dbname=testdb;user=bruce;password=mypass

# PDO::pgsqlCopyFromArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromArray — Alias de Pdo\Pgsql::copyFromArray()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function PDO::pgsqlCopyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): bool

Cette méthode est un alias de: Pdo\Pgsql::copyFromArray().

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre `rows` accepte désormais aussi un Traversable ; antérieur à cela, seul un array était accepté.

# PDO::pgsqlCopyFromFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromFile — Alias de Pdo\Pgsql::copyFromFile()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function PDO::pgsqlCopyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): bool

Cette méthode est un alias de: Pdo\Pgsql::copyFromFile().

# PDO::pgsqlCopyToArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToArray — Alias de Pdo\Pgsql::copyToArray()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function PDO::pgsqlCopyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): array|false

Cette méthode est un alias de: Pdo\Pgsql::copyToArray().

# PDO::pgsqlCopyToFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToFile — Alias de Pdo\Pgsql::copyToFile()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function PDO::pgsqlCopyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): bool

Cette méthode est un alias de: Pdo\Pgsql::copyToFile().

# PDO::pgsqlGetNotify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetNotify — Alias de Pdo\Pgsql::getNotify()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function PDO::pgsqlGetNotify(int `$fetchMode` = PDO::FETCH_DEFAULT, int `$timeoutMilliseconds` = 0): array|false

Cette méthode est un alias de: Pdo\Pgsql::getNotify().

# PDO::pgsqlGetPid

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetPid — Alias de Pdo\Pgsql::getPid()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function PDO::pgsqlGetPid(): int

Cette méthode est un alias de: Pdo\Pgsql::getPid().

# PDO::pgsqlLOBCreate

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBCreate — Alias de Pdo\Pgsql::lobCreate()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function PDO::pgsqlLOBCreate(): string

Cette méthode est un alias de: Pdo\Pgsql::lobCreate().

# PDO::pgsqlLOBOpen

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBOpen — Alias de Pdo\Pgsql::lobOpen()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function PDO::pgsqlLOBOpen(string `$oid`, string `$mode` = "rb"): resource|false

Cette méthode est un alias de: Pdo\Pgsql::lobOpen().

# PDO::pgsqlLOBUnlink

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBUnlink — Alias de Pdo\Pgsql::lobUnlink()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function PDO::pgsqlLOBUnlink(string `$oid`): bool

Cette méthode est un alias de: Pdo\Pgsql::lobUnlink().

## Sommaire

- PDO_PGSQL DSN — Connexion aux bases de données PostgreSQL
- PDO::pgsqlCopyFromArray — Alias de Pdo\Pgsql::copyFromArray
- PDO::pgsqlCopyFromFile — Alias de Pdo\Pgsql::copyFromFile
- PDO::pgsqlCopyToArray — Alias de Pdo\Pgsql::copyToArray
- PDO::pgsqlCopyToFile — Alias de Pdo\Pgsql::copyToFile
- PDO::pgsqlGetNotify — Alias de Pdo\Pgsql::getNotify
- PDO::pgsqlGetPid — Alias de Pdo\Pgsql::getPid
- PDO::pgsqlLOBCreate — Alias de Pdo\Pgsql::lobCreate
- PDO::pgsqlLOBOpen — Alias de Pdo\Pgsql::lobOpen
- PDO::pgsqlLOBUnlink — Alias de Pdo\Pgsql::lobUnlink

# La classe Pdo\Pgsql

(PHP 8 >= 8.4.0)

## Introduction

Une sous-classe de PDO représentant une connexion utilisant le pilote PostgreSQL PDO.

Ce pilote supporte un analyseur de requêtes SQL dédié pour le dialecte PostgreSQL. Il peut gérer les éléments suivants :

- Les littéraux de chaînes simples et doubles, avec le doublement comme mécanisme d'échappement
- Les littéraux de chaînes "échappées" de style C
- Les littéraux de chaînes en dollars
- Deux tirets et les commentaires de style C (non imbriqués)
- Le support de `??` comme séquence d'échappement pour l'opérateur `?`.

## Synopsis de la classe

namespace Pdo;
class Pgsql extends PDO {
/* Constantes héritées */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int ATTR_DISABLE_PREPARES;
public const int ATTR_RESULT_MEMORY_SIZE;
public const int TRANSACTION_IDLE;
public const int TRANSACTION_ACTIVE;
public const int TRANSACTION_INTRANS;
public const int TRANSACTION_INERROR;
public const int TRANSACTION_UNKNOWN;
/* Méthodes */
public function copyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false
public function copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function escapeIdentifier(string `$input`): string
public function getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false
public function getPid(): int
public function lobCreate(): string|false
public function lobOpen(string `$oid`, string `$mode` = "rb"): resource|false
public function lobUnlink(string `$oid`): bool
public function setNoticeCallback(?callable `$callback`): void
/* Méthodes héritées */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes pré-définies

`Pdo\Pgsql::ATTR_DISABLE_PREPARES`
  Envoie la requête et les paramètres au serveur en une seule fois, évitant le besoin de créer une instruction préparée nommée séparément. Si la requête va être exécutée une seule fois, cela peut réduire la latence en évitant un aller-retour inutile au serveur.
`Pdo\Pgsql::ATTR_RESULT_MEMORY_SIZE`
  Renvoie la quantité de mémoire, en octets, allouée à l'instance de PDOStatement de résultat de requête spécifiée, ou `null` si aucun résultat n'existe avant l'exécution de la requête.
`PDO::ATTR_PREFETCH`
  À partir de PHP 8.5.0, définir cet attribut à `0` active la lecture paresseuse (ligne par ligne) : les lignes sont récupérées depuis le serveur une par une au fur et à mesure de leur lecture, au lieu de mettre en mémoire tampon l'ensemble du jeu de résultats avant le premier appel à PDOStatement::fetch(). Cela réduit l'utilisation de la mémoire pour les grands jeux de résultats. Toute autre valeur conserve le comportement par défaut avec mise en mémoire tampon. Il peut être défini par connexion avec PDO::setAttribute(), ou par instruction via les options de pilote de PDO::prepare() ou PDO::query().
  Attention

  En mode paresseux, une connexion ne peut avoir qu'une seule instruction active à la fois. L'exécution d'une autre instruction ignore silencieusement les lignes non lues de la précédente ; aucune erreur n'est levée.

`Pdo\Pgsql::TRANSACTION_IDLE`
  Avertissement

  Cette constante n'a aucun effet, et est obsolète à partir de PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_ACTIVE`
  Avertissement

  Cette constante n'a aucun effet, et est obsolète à partir de PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_INTRANS`
  Avertissement

  Cette constante n'a aucun effet, et est obsolète à partir de PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_INERROR`
  Avertissement

  Cette constante n'a aucun effet, et est obsolète à partir de PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_UNKNOWN`
  Avertissement

  Cette constante n'a aucun effet, et est obsolète à partir de PHP 8.5.0.

# Pdo\Pgsql::copyFromArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromArray — Copie des données d'un tableau PHP dans une table

### Description

public function Pdo\Pgsql::copyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copie des données du tableau `rows` dans la table `tableName` en utilisant `separator` comme délimiteur de champs et la liste `fields`.

### Liste de paramètres

`tableName`
  Une chaîne de caractères contenant le nom de la table.
`rows`
  Un array indexé (ou Traversable) de strings avec les champs séparés par `separator`.
`separator`
  Un délimiteur utilisé pour séparer les champs dans une entrée du tableau `rows`.
`nullAs`
  Comment interpréter les valeurs `NULL`.
`fields`
  La liste des champs à insérer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | `rows` accepte désormais également un Traversable ; antérieur à cela, seul un array était accepté.

### Exemples

Exemple #1 Exemple avec Pdo\Pgsql::copyFromArray()

Chaque élément de `rows` est un enregistrement dont les champs sont joints par `separator` (une tabulation par défaut).

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');

    $rows = [
        "1\tapple\t10",
        "2\tbanana\t20",
        "3\tcherry\t30",
    ];
    $db->copyFromArray('fruits', $rows);

    foreach ($db->query('SELECT * FROM fruits ORDER BY id') as $row) {
        echo "{$row['id']} {$row['name']} {$row['qty']}\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    1 apple 10
    2 banana 20
    3 cherry 30

### Voir aussi

- Pdo\Pgsql::copyToArray() - Copie des données d'une table dans un tableau PHP
- Pdo\Pgsql::copyFromFile() - Copie des données d'un fichier dans une table
- Pdo\Pgsql::copyToFile() - Copie des données d'une table dans un fichier

# Pdo\Pgsql::copyFromFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromFile — Copie des données d'un fichier dans une table

### Description

public function Pdo\Pgsql::copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copie des données d'un fichier spécifié par `filename` dans la table `tableName` en utilisant `separator` comme délimiteur de champs et la liste `fields`

### Liste de paramètres

`tableName`
  Une chaîne de caractères contenant le nom de la table.
`filename`
  Le nom du fichier d'où importer les données.
`separator`
  Un délimiteur utilisé pour séparer les champs dans une entrée du tableau `rows`.
`nullAs`
  Comment interpréter les valeurs `NULL`.
`fields`
  La liste des champs à insérer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si `filename` ne peut pas être ouvert en lecture, l'échec est signalé via la gestion des erreurs de la connexion (voir `PDO::ATTR_ERRMODE`) ; avec `PDO::ERRMODE_EXCEPTION`, une PDOException est levée.

### Exemples

Exemple #1 Exemple avec Pdo\Pgsql::copyFromFile()

Le fichier contient un enregistrement par ligne, les champs étant joints par `separator` (une tabulation par défaut).

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');

    file_put_contents('/tmp/fruits.tsv', "1\tapple\t10\n2\tbanana\t20\n");
    $db->copyFromFile('fruits', '/tmp/fruits.tsv');

    echo $db->query('SELECT count(*) FROM fruits')->fetchColumn(), "\n";
    ?>

L'exemple ci-dessus va afficher :

    2

### Voir aussi

- Pdo\Pgsql::copyToFile() - Copie des données d'une table dans un fichier
- Pdo\Pgsql::copyFromArray() - Copie des données d'un tableau PHP dans une table
- Pdo\Pgsql::copyToArray() - Copie des données d'une table dans un tableau PHP

# Pdo\Pgsql::copyToArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToArray — Copie des données d'une table dans un tableau PHP

### Description

public function Pdo\Pgsql::copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

Copie des données de `tableName` dans un tableau en utilisant `separator` comme délimiteur de champs et la liste `fields`.

### Liste de paramètres

`tableName`
  Une chaîne de caractères contenant le nom de la table.
`separator`
  Un délimiteur utilisé pour séparer les champs dans une entrée du tableau `rows`.
`nullAs`
  Comment interpréter les valeurs `NULL`.
`fields`
  La liste des champs à exporter.

### Valeurs de retour

Retourne un tableau de lignes, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec Pdo\Pgsql::copyToArray()

Chaque élément retourné est un enregistrement, les champs étant joints par `separator` et suivis d'un saut de ligne final.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');
    $db->exec("INSERT INTO fruits VALUES (1, 'apple', 10), (2, 'banana', 20)");

    $rows = $db->copyToArray('fruits');
    var_export($rows);
    ?>

L'exemple ci-dessus va afficher :

    array (
      0 => '1	apple	10
    ',
      1 => '2	banana	20
    ',
    )

### Voir aussi

- Pdo\Pgsql::copyFromArray() - Copie des données d'un tableau PHP dans une table
- Pdo\Pgsql::copyFromFile() - Copie des données d'un fichier dans une table
- Pdo\Pgsql::copyToFile() - Copie des données d'une table dans un fichier

# Pdo\Pgsql::copyToFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToFile — Copie des données d'une table dans un fichier

### Description

public function Pdo\Pgsql::copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copie des données de la table dans le fichier spécifié par `filename` en utilisant `separator` comme délimiteur de champs et la liste `fields`.

### Liste de paramètres

`tableName`
  Une chaîne de caractères contenant le nom de la table.
`filename`
  Le nom du fichier où exporter les données.
`separator`
  Un délimiteur utilisé pour séparer les champs dans une entrée du tableau `rows`.
`nullAs`
  Comment interpréter les valeurs `NULL`.
`fields`
  La liste des champs à exporter.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si `filename` ne peut pas être ouvert en écriture, ou ne peut pas être écrit, l'échec est signalé via la gestion des erreurs de la connexion (voir `PDO::ATTR_ERRMODE`) ; avec `PDO::ERRMODE_EXCEPTION`, une PDOException est levée.

### Exemples

Exemple #1 Exemple avec Pdo\Pgsql::copyToFile()

La table est écrite dans `filename`, un enregistrement par ligne, les champs étant joints par `separator`.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');
    $db->exec("INSERT INTO fruits VALUES (1, 'apple', 10), (2, 'banana', 20)");

    $db->copyToFile('fruits', '/tmp/fruits.tsv');
    echo file_get_contents('/tmp/fruits.tsv');
    ?>

L'exemple ci-dessus va afficher :

    1	apple	10
    2	banana	20

### Voir aussi

- Pdo\Pgsql::copyFromFile() - Copie des données d'un fichier dans une table
- Pdo\Pgsql::copyFromArray() - Copie des données d'un tableau PHP dans une table
- Pdo\Pgsql::copyToArray() - Copie des données d'une table dans un tableau PHP

# Pdo\Pgsql::escapeIdentifier

(PHP 8 >= 8.4.0)

Pdo\Pgsql::escapeIdentifier — Échappe une chaîne pour son utilisation en tant qu'identifiant SQL

### Description

public function Pdo\Pgsql::escapeIdentifier(string `$input`): string

Échappe une chaîne pour son utilisation en tant qu'identifiant SQL, tel qu'une table, une colonne ou un nom de fonction. Ceci est utile lorsque l'identifiant fourni par l'utilisateur pourrait contenir des caractères spéciaux qui ne seraient pas interprétés comme faisant partie de l'identifiant par l'analyseur SQL, ou lorsque l'identifiant pourrait contenir des caractères en majuscules dont la casse devrait être préservée.

### Liste de paramètres

`input`
  Une string contenant le texte à échapper.

### Valeurs de retour

Une string contenant les données échappées.

### Exemples

Exemple #1 Exemple de Pdo\Pgsql::escapeIdentifier()

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $unescapedTableName = 'UnescapedTableName';
    $pdo->exec("CREATE TABLE $unescapedTableName ()");

    $escapedTableName = $pdo->escapeIdentifier('EscapedTableName');
    $pdo->exec("CREATE TABLE $escapedTableName ()");

    $statement = $pdo->query(
      "SELECT relname FROM pg_stat_user_tables WHERE relname ilike '%tablename'"
    );

    var_export($statement->fetchAll(PDO::FETCH_COLUMN, 0));

    $tableNameWithSymbols = 'Table-Name-With-Symbols';
    $pdo->exec("CREATE TABLE $tableNameWithSymbols ()");
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array (
      0 => 'unescapedtablename',
      1 => 'EscapedTableName',
    )
    Fatal error: Uncaught PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "Table"
    LINE 1: CREATE TABLE Table-Name-With-Symbols ()

### Voir aussi

- PDO::quote() - Protège une chaîne pour l'utiliser dans une requête SQL PDO

# Pdo\Pgsql::getNotify

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getNotify — Renvoie une notification asynchrone

### Description

public function Pdo\Pgsql::getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false

Renvoie un jeu de résultats représentant une notification asynchrone en attente.

### Liste de paramètres

`fetchMode`

  Le format sous lequel le jeu de résultats doit être, une des constantes suivantes:

  - `PDO::FETCH_DEFAULT`
  - `PDO::FETCH_BOTH`
  - `PDO::FETCH_ASSOC`
  - `PDO::FETCH_NUM`
`timeoutMilliseconds`
  Le temps d'attente pour une réponse, en millisecondes.

### Valeurs de retour

Si une notification est en attente, retourne une seule ligne, sinon retourne `false`. La ligne possède un champ `message` (le nom du canal) et un champ `pid` (l'identifiant du processus du backend émetteur). Si la notification transporte une charge utile non vide, la ligne possède également un champ `payload`. Avec `PDO::FETCH_NUM`, ces champs se trouvent aux indices `0`, `1` et `2`.

### Erreurs / Exceptions

Une ValueError est lancée si `fetchMode` n'est pas une des constantes `PDO::FETCH_*` valides.

Une ValueError est lancée si `timeoutMilliseconds` est inférieur à `0`.

Une Warning est lancée si `timeoutMilliseconds` est supérieur à la valeur qui peut être contenue dans un entier signé 32 bits, auquel cas ce sera la valeur maximale d'un entier signé 32 bits.

### Exemples

Exemple #1 Exemple avec Pdo\Pgsql::getNotify()

S'abonner à un canal avec `LISTEN`, puis lire la prochaine notification en attente avec un délai d'attente d'une seconde.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    $db->exec('LISTEN messages');
    $db->exec("NOTIFY messages, 'hello'");

    $notification = $db->getNotify(PDO::FETCH_ASSOC, 1000);
    var_export($notification);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array (
      'message' => 'messages',
      'pid' => 1928,
      'payload' => 'hello',
    )

### Voir aussi

- PDO::query() - Prépare et Exécute une requête SQL sans marque substitutive
- PDOStatement::fetch() - Récupère la ligne suivante d'un jeu de résultats PDO
- PDOStatement::fetchAll() - Récupère les lignes restantes d'un ensemble de résultats

# Pdo\Pgsql::getPid

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getPid — Renvoie le PID du processus backend gérant cette connexion

### Description

public function Pdo\Pgsql::getPid(): int

Renvoie le PID du processus backend gérant cette connexion. Il est à noter que le PID appartient à un processus s'exécutant sur l'hôte du serveur, et non sur l'hôte local.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le PID sous forme d'un int.

### Exemples

Exemple #1 Exemple avec Pdo\Pgsql::getPid()

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    echo $db->getPid();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    12345

### Voir aussi

- pg_get_pid() - Lit l'identifiant de processus du serveur PostgreSQL

# Pdo\Pgsql::lobCreate

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobCreate — Créer un nouvel objet large

### Description

public function Pdo\Pgsql::lobCreate(): string|false

Pdo\Pgsql::lobCreate() crée un objet large et retourne l'OID qui le référence. Il peut être ouvert pour lire ou écrire des données avec Pdo\Pgsql::lobOpen().

L'OID peut être stocké dans des colonnes de type OID et être utilisé pour référencer l'objet large, sans que la ligne ne grossisse de manière arbitraire. L'objet large continuera d'exister dans la base de données jusqu'à ce qu'il soit supprimé en appelant Pdo\Pgsql::lobUnlink().

Les objets larges sont des objets volumineux à utiliser. En effet, il est nécessaire d'appeler Pdo\Pgsql::lobUnlink() avant de supprimer la dernière ligne référençant l'OID dans toute la base de données ; sinon, les objets larges non référencés resteront sur le serveur indéfiniment. De plus, les objets larges n'ont pas de contrôles d'accès. Une alternative est le type de colonne bytea, qui peut être jusqu'à 1 Go de taille, et ce type de colonne gère de manière transparente le stockage pour une taille de ligne optimale.

> Note: Cette fonction, et toutes les manipulations de l'objet large, doivent être appelées et effectuées dans une transaction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'OID du nouvel objet large créé en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Pdo\Pgsql::lobCreate() example

Cet exemple crée un nouvel objet large et copie le contenu d'un fichier dedans. L'OID est ensuite stocké dans une table.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $oid = $db->lobCreate();
    $stream = $db->lobOpen($oid, 'w');
    $local = fopen($filename, 'rb');
    stream_copy_to_stream($local, $stream);
    $local = null;
    $stream = null;
    $stmt = $db->prepare("INSERT INTO BLOBS (ident, oid) VALUES (?, ?)");
    $stmt->execute([$some_id, $oid]);
    $db->commit();
    ?>

### Voir aussi

- Pdo\Pgsql::lobOpen() - Ouvre un flux sur un objet large existant
- Pdo\Pgsql::lobUnlink() - Supprime un objet large
- pg_lo_create() - Crée un objet de grande taille PostgreSQL
- pg_lo_open() - Ouvre un objet de grande taille PostgreSQL

# Pdo\Pgsql::lobOpen

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobOpen — Ouvre un flux sur un objet large existant

### Description

public function Pdo\Pgsql::lobOpen(string `$oid`, string `$mode` = "rb"): resource|false

Pdo\Pgsql::lobOpen() ouvre un flux pour accéder aux données référencées par `oid`. Toutes les fonctions de système de fichiers habituelles, telles que fread(), fwrite() ou fgets() peuvent être utilisées pour manipuler le contenu du flux.

> Note: Cette fonction, et toutes les manipulations de l'objet large, doivent être appelées et effectuées dans une transaction.

### Liste de paramètres

`oid`
  Un identifiant d'objet large.
`mode`
  Le mode d'accès. Si `mode` contient `w` ou `+`, le flux est ouvert en lecture et en écriture ; sinon, il est ouvert en lecture seule. Un indicateur `b` (binaire) n'a aucun effet. La valeur par défaut `"rb"` ouvre le flux en lecture.

### Valeurs de retour

Renvoie une ressource de flux en cas de succès, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple de Pdo\Pgsql::lobOpen()

D'après l'exemple de Pdo\Pgsql::lobCreate(), ce code extrait l'objet large de la base de données et le renvoie au navigateur.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $stmt = $db->prepare("SELECT oid FROM BLOBS WHERE ident = ?");
    $stmt->execute([$some_id]);
    $stmt->bindColumn('oid', $oid, PDO::PARAM_STR);
    $stmt->fetch(PDO::FETCH_BOUND);
    $stream = $db->lobOpen($oid, 'r');
    header("Content-type: application/octet-stream");
    fpassthru($stream);
    ?>

### Voir aussi

- Pdo\Pgsql::lobCreate() - Créer un nouvel objet large
- Pdo\Pgsql::lobUnlink() - Supprime un objet large
- pg_lo_create() - Crée un objet de grande taille PostgreSQL
- pg_lo_open() - Ouvre un objet de grande taille PostgreSQL

# Pdo\Pgsql::lobUnlink

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobUnlink — Supprime un objet large

### Description

public function Pdo\Pgsql::lobUnlink(string `$oid`): bool

Supprime un objet large de la base de données identifié par OID.

> Note: Cette fonction, et toutes les manipulations de l'objet large, doivent être appelées et effectuées dans une transaction.

### Liste de paramètres

`oid`
  Un identifiant d'objet large.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Pdo\Pgsql::lobUnlink() example

Cet exemple supprime un objet large de la base de données avant de supprimer la ligne qui le référence. Il utilise la table blobs des exemples de Pdo\Pgsql::lobCreate() et Pdo\Pgsql::lobOpen().

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $db->lobUnlink($oid);
    $stmt = $db->prepare("DELETE FROM BLOBS where ident = ?");
    $stmt->execute([$some_id]);
    $db->commit();
    ?>

### Voir aussi

- Pdo\Pgsql::lobCreate() - Créer un nouvel objet large
- Pdo\Pgsql::lobOpen() - Ouvre un flux sur un objet large existant
- pg_lo_create() - Crée un objet de grande taille PostgreSQL
- pg_lo_open() - Ouvre un objet de grande taille PostgreSQL

# Pdo\Pgsql::setNoticeCallback

(PHP 8 >= 8.4.0)

Pdo\Pgsql::setNoticeCallback — Définit une fonction de rappel pour gérer les messages d'avis et d'avertissement générés par le serveur

### Description

public function Pdo\Pgsql::setNoticeCallback(?callable `$callback`): void

Définit une fonction de rappel pour gérer les messages d'avis et d'avertissement générés par le serveur. Cela inclut les messages émis par PostgreSQL lui-même, ainsi que ceux générés par les fonctions SQL définies par l'utilisateur utilisant `RAISE`. Il est à noter que la réception effective de ces messages dépend du paramètre du serveur `client_min_messages`.

### Liste de paramètres

`callback`
  Si `null` est passé, la fonction de rappel est réinitialisée à son état par défaut.

  Sinon, la fonction de rappel est un rappel avec la signature suivante:

  function handler(string `$message`): void
  `message`
    Un message généré par le serveur.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple de Pdo\Pgsql::setNoticeCallback()

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $pdo->exec('CREATE TABLE parent(id int primary key)');
    $pdo->exec('CREATE TABLE child(id int references parent)');

    $pdo->setNoticeCallback(function ($message) {
        echo $message;
    });

    $pdo->exec('TRUNCATE parent CASCADE');
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    NOTICE:  truncate cascades to table "child"

## Sommaire

- Pdo\Pgsql::copyFromArray — Copie des données d'un tableau PHP dans une table
- Pdo\Pgsql::copyFromFile — Copie des données d'un fichier dans une table
- Pdo\Pgsql::copyToArray — Copie des données d'une table dans un tableau PHP
- Pdo\Pgsql::copyToFile — Copie des données d'une table dans un fichier
- Pdo\Pgsql::escapeIdentifier — Échappe une chaîne pour son utilisation en tant qu'identifiant SQL
- Pdo\Pgsql::getNotify — Renvoie une notification asynchrone
- Pdo\Pgsql::getPid — Renvoie le PID du processus backend gérant cette connexion
- Pdo\Pgsql::lobCreate — Créer un nouvel objet large
- Pdo\Pgsql::lobOpen — Ouvre un flux sur un objet large existant
- Pdo\Pgsql::lobUnlink — Supprime un objet large
- Pdo\Pgsql::setNoticeCallback — Définit une fonction de rappel pour gérer les messages d'avis et d'avertissement générés par le serveur

# Fonctions du pilote PDO SQLite (PDO_SQLITE)

## Introduction

PDO_SQLITE est un pilote qui implémente l'interface de PHP Data Objects (PDO) pour autoriser l'accès de PHP aux bases de données SQLite 3.

> Note:

> PDO_SQLITE autorise l'utilisation de chaînes en dehors des flux avec `PDO::PARAM_LOB`.

## Installation

Le driver PDO PDO_SQLITE est actif par défaut. Pour le désactiver, utiliser l'option de compilation --without-pdo-sqlite[=DIR], où `[=DIR]` (optionnel) représente le chemin vers le dossier d'installation de base de sqlite. À partir de PHP 7.4.0 » libsqlite ≥ 3.5.0 est requis. Auparavant, la libsqlite intégrée pouvait être utilisée à la place, et était par défaut, si `[=DIR]` était omis.

> Note: Installation supplémentaire sur Windows à partir de PHP 7.4.0

> Afin de faire fonctionner cette extension, quelques bibliothèques DLL doivent être disponibles via le PATH du système Windows. Lisez la F.A.Q intitulée "Comment ajouter mon dossier PHP à mon PATH Windows" pour plus d'informations. Le fait de copier les bibliothèques DLL depuis le dossier PHP dans le dossier système Windows fonctionne également (car le dossier système est par défaut dans le PATH système), mais cette méthode n'est pas recommandée. Cette extension nécessite que les fichiers suivants se trouvent dans le PATH : libsqlite3.dll.

# PDO_SQLITE DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_SQLITE >= 0.2.0)

PDO_SQLITE DSN — Connexion aux bases de données SQLite

### Description

Le Data Source Name (DSN) de PDO_SQLITE est composé des éléments suivants :

Préfixe DSN (SQLite 3)

  Le préfixe DSN est `sqlite:`.

  - Pour accéder à une base de données sur le disque, il faut ajouter le chemin absolu au préfixe DSN.

  - Pour créer une base de données en mémoire, il faut ajouter `:memory:` au préfixe DSN.

  - Si le DSN ne contient que le préfixe DSN, une base de données temporaire sera créée, et qui sera supprimée lorsque la connexion sera fermée.

### Exemples

Exemple #1 Exemples avec PDO_SQLITE DSN

Les exemples suivant montrent PDO_SQLITE DSN pour se connecter aux bases de données SQLite :

    sqlite:/opt/databases/mydb.sq3
    sqlite::memory:
    sqlite:

# PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — Alias de Pdo\Sqlite::createAggregate()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

public function PDO::sqliteCreateAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Cette méthode est un alias de: Pdo\Sqlite::createAggregate().

# PDO::sqliteCreateCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

PDO::sqliteCreateCollation — Alias de Pdo\Sqlite::createCollation()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

public function PDO::sqliteCreateCollation(string `$name`, callable `$callback`): bool

Cette méthode est un alias de: Pdo\Sqlite::createCollation().

# PDO::sqliteCreateFunction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateFunction — Alias de Pdo\Sqlite::createFunction()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

public function PDO::sqliteCreateFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

Cette méthode est un alias de: Pdo\Sqlite::createFunction().

### Historique

Version | Description
--- | ---
7.1.4 | Le paramètre `flags` a été ajouté.

## Sommaire

- PDO_SQLITE DSN — Connexion aux bases de données SQLite
- PDO::sqliteCreateAggregate — Alias de Pdo\Sqlite::createAggregate
- PDO::sqliteCreateCollation — Alias de Pdo\Sqlite::createCollation
- PDO::sqliteCreateFunction — Alias de Pdo\Sqlite::createFunction

# La classe Pdo\Sqlite

(PHP 8 >= 8.4.0)

## Introduction

Une sous-classe de PDO représentant une connexion utilisant le pilote SQLite PDO.

Ce pilote supporte un analyseur de requêtes SQL dédié pour le dialecte SQLite. Il peut gérer les éléments suivants :

- Les littéraux de chaînes entre guillemets simples, doubles et backticks, avec le doublement comme mécanisme d'échappement.
- Les citations entre crochets pour les identifiants.
- Deux tirets et les commentaires de style C (non imbriqués).

## Synopsis de la classe

class Pdo\Sqlite extends PDO {
/* Constantes héritées */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Constantes */
public const int DETERMINISTIC;
public const int OPEN_READONLY;
public const int OPEN_READWRITE;
public const int OPEN_CREATE;
public const int ATTR_OPEN_FLAGS;
public const int ATTR_READONLY_STATEMENT;
public const int ATTR_EXTENDED_RESULT_CODES;
/* Méthodes */
public function createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool
public function loadExtension(string `$name`): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
/* Méthodes héritées */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Constantes pré-définies

`Pdo\Sqlite::DETERMINISTIC`
`Pdo\Sqlite::OPEN_READONLY`
`Pdo\Sqlite::OPEN_READWRITE`
`Pdo\Sqlite::OPEN_CREATE`
`Pdo\Sqlite::ATTR_OPEN_FLAGS`
`Pdo\Sqlite::ATTR_READONLY_STATEMENT`
`Pdo\Sqlite::ATTR_EXTENDED_RESULT_CODES`

# Pdo\Sqlite::createAggregate

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createAggregate — Enregistre une fonction utilisateur d'agrégation pour une utilisation dans les instructions SQL

### Description

public function Pdo\Sqlite::createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Cette méthode est similaire à Pdo\Sqlite::createFunction() sauf qu'elle enregistre des fonctions qui peuvent être utilisées pour calculer un résultat agrégé sur l'ensemble des lignes d'une requête.

La principale différence entre cette méthode et Pdo\Sqlite::createFunction() est que deux fonctions sont nécessaires pour gérer l'agrégation.

Astuce

En utilisant cette méthode, il est possible de remplacer les fonctions SQL natives.

### Liste de paramètres

`name`
  Le nom de la fonction utilisé dans les instructions SQL.
`step`
  La fonction de rappel appelée pour chaque ligne de l'ensemble de résultats. La fonction de rappel doit accumuler le résultat et le stocker dans le contexte d'agrégation.

  Cette fonction doit être définie comme suit :

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`
    `null` pour la première ligne ; sur les lignes suivantes, elle aura la valeur qui a été précédemment retournée par la fonction de rappel ; il faut utiliser ceci pour maintenir l'état de l'agrégation.
  `rownumber`
    Le numéro de la ligne actuelle.
  `value`
    Le premier argument passé à l'agrégation.
  `values`
    Les arguments supplémentaires passés à l'agrégation.
  La valeur de retour de cette fonction sera utilisée comme argument `context` dans l'appel suivant de la fonction de rappel ou de finalisation.
`finalize`
  La fonction de rappel pour agréger les données "étape" de chaque ligne. Une fois que toutes les lignes ont été traitées, cette fonction sera appelée, et elle devrait ensuite prendre les données du contexte d'agrégation et retourner le résultat. Cette fonction de rappel doit retourner un type compris par SQLite (c'est-à-dire un type scalaire).

  Cette fonction doit être définie comme suit :

  function fini(mixed `$context`, int `$rowcount`): mixed
  `context`

    Contient la valeur de retour du tout dernier appel à la fonction de rappel.

  `rowcount`

    Contient le nombre de lignes sur lesquelles l'agrégation a été effectuée.

  La valeur de retour de cette fonction sera utilisée comme valeur de retour pour l'agrégation.
`numArgs`
  Indication au parseur SQLite si la fonction de rappel accepte un nombre prédéterminé d'arguments.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Pdo\Sqlite::createAggregate() example

Dans cet exemple, nous allons créer une fonction d'agrégation personnalisée nommée `max_length` qui peut être utilisée dans les requêtes SQL.

Dans cet exemple, nous allons créer une fonction d'agrégation nommée `max_length` qui va calculer la longueur de la chaîne la plus longue dans l'une des colonnes de la table. Pour chaque ligne, la fonction `max_len_step` est appelée et passe un paramètre `$context`. Le paramètre de contexte est comme n'importe quelle autre variable PHP et peut être défini pour contenir un array ou même un object. Dans cet exemple, nous l'utilisons pour contenir la longueur maximale que nous avons vue jusqu'à présent ; si la $string a une longueur plus longue que la longueur maximale actuelle, nous mettons à jour le contexte pour contenir cette nouvelle longueur maximale.

Après que toutes les lignes ont été traitées, SQLite appelle la fonction `max_len_finalize` pour déterminer le résultat agrégé. Il est possible d'effectuer un certain type de calcul basé sur les données dans `$context`. Dans cet exemple de base, le résultat a été calculé au fur et à mesure que la requête progressait, donc la valeur de contexte peut être directement retournée.

    <?php
    $data = [
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
    ];
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->execute(array($str));
    }
    $insert = null;

    function max_len_step($context, $row_number, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $row_count)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

    ?>

Astuce

Il n'est PAS recommandé de stocker une copie des valeurs dans le contexte et des traiter à la fin, car on obligerait SQLite à utiliser beaucoup de mémoire pour traiter la requête - imaginez combien de mémoire l'on aurait besoin si un million de lignes étaient stockées en mémoire, chacune contenant une chaîne de 32 octets de longueur.

### Voir aussi

- Pdo\Sqlite::createFunction() - Enregistre une fonction utilisateur pour une utilisation dans les instructions SQL
- Pdo\Sqlite::createCollation() - Enregistre une fonction utilisateur de tri pour une utilisation dans les instructions SQL
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createCollation

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createCollation — Enregistre une fonction utilisateur de tri pour une utilisation dans les instructions SQL

### Description

public function Pdo\Sqlite::createCollation(string `$name`, callable `$callback`): bool

Cette méthode est similaire à Pdo\Sqlite::createFunction() sauf qu'elle enregistre des fonctions qui sont utilisées pour trier des chaînes.

### Liste de paramètres

`name`
  Le nom de la fonction de tri SQL à créer ou redéfinir.
`callback`
  La fonction de rappel qui définit le comportement d'un tri. Elle doit accepter deux strings et retourner `-1`, `0`, ou `1` si la première chaîne est triée avant, identique, ou après la seconde chaîne respectivement. Une fonction interne qui se comporte de cette manière est strcmp().

  Cette fonction doit être définie comme suit :

  function collation(string `$string1`, string `$string2`): int

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de Pdo\Sqlite::createCollation()

    <?php
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->sqliteCreateCollation('NATURAL_CMP', 'strnatcmp');
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1") as $row) {
      echo $row['col1'] . "\n";
    }
    echo "\n";
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP") as $row) {
      echo $row['col1'] . "\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    a1
    a10
    a2

    a1
    a2
    a10

### Voir aussi

- Pdo\Sqlite::createFunction() - Enregistre une fonction utilisateur pour une utilisation dans les instructions SQL
- Pdo\Sqlite::createAggregate() - Enregistre une fonction utilisateur d'agrégation pour une utilisation dans les instructions SQL
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createFunction

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createFunction — Enregistre une fonction utilisateur pour une utilisation dans les instructions SQL

### Description

public function Pdo\Sqlite::createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

Cette méthode permet les fonctions PHP d'être enregistrées avec SQLite en tant que fonction définie par l'utilisateur, de sorte qu'elles puissent être appelées dans les requêtes SQL. La fonction définie peut être utilisée dans n'importe quelle requête SQL qui permet des appels de fonction, par exemple `SELECT`, `UPDATE`, ou des déclencheurs.

Astuce

En utilisant cette méthode, il est possible de remplacer les fonctions SQL natives.

### Liste de paramètres

`function_name`
  Le nom de la fonction utilisé dans les instructions SQL.
`callback`
  La fonction de rappel pour gérer la fonction SQL définie.

  > Note: La fonction de rappel doit retourner un type compris par SQLite (c'est-à-dire type scalaire).

  Cette fonction doit être définie comme :

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    Le premier argument passé à la fonction SQL.

  `values`

    Les arguments supplémentaires passés à la fonction SQL.

`num_args`
  Le nombre d'arguments que la fonction SQL prend. Si ce paramètre est `-1`, alors la fonction SQL peut prendre n'importe quel nombre d'arguments.
`flags`
  Un masque de bits de drapeaux. Actuellement, seul `Pdo\Sqlite::DETERMINISTIC` est supporté, ce qui spécifie que la fonction retourne toujours le même résultat étant donné les mêmes entrées dans une seule instruction SQL.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Pdo\Sqlite::createFunction() example

Dans cet exemple, nous avons une fonction qui calcule la somme SHA256 d'une chaîne, puis la renverse. Lorsque l'instruction SQL est exécutée, elle retourne la valeur du nom de fichier transformé par notre fonction. Les données retournées dans $rows contiennent le résultat traité.

La beauté de cette technique est qu'il n'est pas nécessaire de traiter le résultat en utilisant une boucle `foreach` après l'exécution de la requête.

    <?php
    function sha256_and_reverse($string)
    {
        return strrev(hash('sha256', $string));
    }

    $db = new Pdo\Sqlite('sqlite::sqlitedb');
    $db->createFunction('sha256rev', 'sha256_and_reverse', 1);
    $rows = $db->query('SELECT sha256rev(filename) FROM files')->fetchAll();
    ?>

### Voir aussi

- Pdo\Sqlite::createAggregate() - Enregistre une fonction utilisateur d'agrégation pour une utilisation dans les instructions SQL
- Pdo\Sqlite::createCollation() - Enregistre une fonction utilisateur de tri pour une utilisation dans les instructions SQL
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::loadExtension

(PHP 8 >= 8.4.0)

Pdo\Sqlite::loadExtension — Description

### Description

public function Pdo\Sqlite::loadExtension(string `$name`): void
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Description.

### Liste de paramètres

`name`
  Description.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Quand cette fonction émet-elle des erreurs de niveau `E_*`, et/ou lance-t-elle des Exceptions.

### Exemples

Exemple #1 Exemple de Pdo\Sqlite::loadExtension()

Description.

    <?php
    echo "Exemple de code";
    ?>

L'exemple ci-dessus va afficher :

    Exemple de code

### Notes

> Note: Toutes les notes qui ne trouvent pas leur place ailleurs doivent être placées ici.

### Voir aussi

- ClassName::otherMethodName()
- some_function()

# Pdo\Sqlite::openBlob

(PHP 8 >= 8.4.0)

Pdo\Sqlite::openBlob — Description

### Description

public function Pdo\Sqlite::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Description.

### Liste de paramètres

`table`
  Description.
`column`
  Description.
`rowid`
  Description.
`dbname`
  Description.
`flags`
  L'un des `Pdo\Sqlite::OPEN_*`

### Valeurs de retour

Description.

### Erreurs / Exceptions

Quand cette fonction émet-elle des erreurs de niveau `E_*`, et/ou lance-t-elle des Exceptions.

### Exemples

Exemple #1 Exemple de Pdo\Sqlite::openBlob()

Description.

    <?php
    echo "Exemple de code";
    ?>

L'exemple ci-dessus va afficher :

    Exemple de code

### Notes

> Note: Toutes les notes qui ne trouvent pas leur place ailleurs doivent être placées ici.

### Voir aussi

- ClassName::otherMethodName()
- some_function()

## Sommaire

- Pdo\Sqlite::createAggregate — Enregistre une fonction utilisateur d'agrégation pour une utilisation dans les instructions SQL
- Pdo\Sqlite::createCollation — Enregistre une fonction utilisateur de tri pour une utilisation dans les instructions SQL
- Pdo\Sqlite::createFunction — Enregistre une fonction utilisateur pour une utilisation dans les instructions SQL
- Pdo\Sqlite::loadExtension — Description
- Pdo\Sqlite::openBlob — Description

- Installation/Configuration
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
  - Modes de récupération
- Connexions et gestionnaire de connexion
- Transactions et validation automatique (autocommit)
- Requêtes préparées et procédures stockées
- Les erreurs et leur gestion
- Les gros objets (LOB)
- PDO — La classe PDO
  - PDO::beginTransaction — Démarre une transaction
  - PDO::commit — Valide une transaction
  - PDO::connect — Connecte à une base de données et retourne une sous-classe PDO pour les pilotes qui le supportent
  - PDO::__construct — Crée une instance PDO qui représente une connexion à la base
  - PDO::errorCode — Retourne le SQLSTATE associé avec la dernière opération sur la base de données
  - PDO::errorInfo — Retourne les informations associées à l'erreur lors de la dernière opération sur la base de données
  - PDO::exec — Exécute une requête SQL et retourne le nombre de lignes affectées
  - PDO::getAttribute — Récupère un attribut d'une connexion à une base de données
  - PDO::getAvailableDrivers — Retourne la liste des pilotes PDO disponibles
  - PDO::inTransaction — Vérifie si l'on est dans une transaction
  - PDO::lastInsertId — Retourne l'identifiant de la dernière ligne insérée ou la valeur d'une séquence
  - PDO::prepare — Prépare une requête à l'exécution et retourne un objet
  - PDO::query — Prépare et Exécute une requête SQL sans marque substitutive
  - PDO::quote — Protège une chaîne pour l'utiliser dans une requête SQL PDO
  - PDO::rollBack — Annule une transaction
  - PDO::setAttribute — Configure un attribut PDO
- PDOStatement — La classe PDOStatement
  - PDOStatement::bindColumn — Lie une colonne à une variable PHP
  - PDOStatement::bindParam — Lie un paramètre à un nom de variable spécifique
  - PDOStatement::bindValue — Associe une valeur à un paramètre
  - PDOStatement::closeCursor — Ferme le curseur, permettant à la requête d'être de nouveau exécutée
  - PDOStatement::columnCount — Retourne le nombre de colonnes dans le jeu de résultats
  - PDOStatement::debugDumpParams — Détaille une commande préparée SQL
  - PDOStatement::errorCode — Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête
  - PDOStatement::errorInfo — Récupère les informations sur l'erreur associée lors de la dernière opération sur la requête
  - PDOStatement::execute — Exécute une requête préparée
  - PDOStatement::fetch — Récupère la ligne suivante d'un jeu de résultats PDO
  - PDOStatement::fetchAll — Récupère les lignes restantes d'un ensemble de résultats
  - PDOStatement::fetchColumn — Retourne une colonne depuis la ligne suivante d'un jeu de résultats
  - PDOStatement::fetchObject — Récupère la prochaine ligne et la retourne en tant qu'objet
  - PDOStatement::getAttribute — Récupère un attribut de requête
  - PDOStatement::getColumnMeta — Retourne les métadonnées pour une colonne d'un jeu de résultats
  - PDOStatement::getIterator — Renvoie un itérateur sur le jeu de résultats
  - PDOStatement::nextRowset — Avance à la prochaine ligne de résultats d'un gestionnaire de lignes de résultats multiples
  - PDOStatement::rowCount — Retourne le nombre de lignes affectées par le dernier appel à la fonction PDOStatement::execute()
  - PDOStatement::setAttribute — Définit un attribut de requête
  - PDOStatement::setFetchMode — Définit le mode de récupération par défaut pour cette requête
- PDORow — La classe PDORow
- PDOException — La classe PDOException
- Pilotes PDO
  - Pilote PDO CUBRID — Fonctions du pilote PDO CUBRID (PDO_CUBRID)
  - Pilote PDO MS SQL Server — Microsoft SQL Server et Fonctions du pilote PDO Sybase (PDO_DBLIB)
  - Pdo\Dblib — La classe Pdo\Dblib
  - Pilote PDO Firebird — Fonctions du pilote PDO Firebird (PDO_FIREBIRD)
  - Pdo\Firebird — La classe Pdo\Firebird
  - Pilote PDO IBM — Fonctions du pilote PDO IBM (PDO_IBM)
  - Pilote PDO Informix — Fonctions du pilote PDO Informix (PDO_INFORMIX)
  - Pilote PDO MySQL — Fonctions du pilote PDO MySQL (PDO_MYSQL)
  - Pdo\Mysql — La classe Pdo\Mysql
  - Pilote PDO MS SQL Server — Fonctions Microsoft du pilote PDO SQL Server (PDO_SQLSRV)
  - Pilote PDO Oracle — Fonctions du pilote PDO Oracle (PDO_OCI)
  - Pilotes PDO ODBC et DB2 — Fonctions du pilote PDO ODBC et DB2 (PDO_ODBC)
  - Pdo\Odbc — La classe Pdo\Odbc
  - Pilote PDO PostgreSQL — Fonctions du pilote PDO PostgreSQL (PDO_PGSQL)
  - Pdo\Pgsql — La classe Pdo\Pgsql
  - Pilote PDO SQLite — Fonctions du pilote PDO SQLite (PDO_SQLITE)
  - Pdo\Sqlite — La classe Pdo\Sqlite

- DBA — Couche d'abstraction de base de données (style dbm)
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Dba\Connection — La classe Dba\Connection
  - Fonctions DBA
- ODBC — ODBC (Unifié)
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions ODBC
  - Odbc\Connection — La classe Odbc\Connection
  - Odbc\Result — La classe Odbc\Result
- PDO — PHP Data Objects
  - Installation/Configuration
  - Constantes pré-définies
  - Connexions et gestionnaire de connexion
  - Transactions et validation automatique (autocommit)
  - Requêtes préparées et procédures stockées
  - Les erreurs et leur gestion
  - Les gros objets (LOB)
  - PDO — La classe PDO
  - PDOStatement — La classe PDOStatement
  - PDORow — La classe PDORow
  - PDOException — La classe PDOException
  - Pilotes PDO

# Extensions spécifiques des fabricants de bases de données

# CUBRID

# Introduction

Ces fonctions autorisent à accéder aux serveurs de base de données CUBRID. Plus d'informations sur CUBRID peuvent être trouvées sur le site de » CUBRID.

La documentation sur CUBRID peut être trouvée » ici.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Afin d'avoir accès à ces fonctions, il faut installer CUBRID, et compiler la bibliothèque PHP CUBRID avec le support CUBRID.

## Installation

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/cubrid.

Aucune bibliothèque DLL pour cette extension PECL n'est actuellement disponible. Reportez-vous à la section Compilation sous Windows.

Pour plus d'informations sur l'installation manuelle sous Linux et Windows, consulter le fichier build-guide.html inclus dans le paquet.

## Configuration à l'exécution

Il n'y a pas actuellement de configuration au moment de l'exécution.

## Types de ressources

Il y a 4 types de ressources utilisés dans CUBRID. La première est l'identifiant du lien pour une connexion à la base de données, la seconde est une ressource qui contient le résultat d'une requête, et les deux dernières, une ressource qui contient les résultats d'une requête pour les types de données BLOB/CLOB.

## Identifiant de connexion

Un identifiant de connexion retourné par les fonctions cubrid_connect(), cubrid_connect_with_url(), cubrid_pconnect() et cubrid_pconnect_with_url().

## Identifiant de requête

Un identifiant de requête retourné par la fonction cubrid_prepare() et par la fonction cubrid_execute().

## Identifiant LOB

Un identifiant LOB retourné par la fonction cubrid_lob_get().

## Identifiant LOB2

Un identifiant LOB retourné par la fonction cubrid_lob2_new() ou récupéré depuis le jeu de résultats.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Les constantes suivantes peuvent être utilisées lors de l'exécution de requête SQL. Elles peuvent être passées aux fonctions cubrid_prepare() et cubrid_execute().

Drapeaux d'exécution SQL CUBRID
Constante | Description
--- | ---
`CUBRID_INCLUDE_OID` | Détermine si l'on doit récupérer l'OID lors de l'exécution de la requête.
`CUBRID_ASYNC` | Exécute la requête en mode asynchrone.
`CUBRID_EXEC_QUERY_ALL` | Exécute la requête en mode synchrone. Ce drapeau doit être défini lors de l'exécution de requêtes SQL multiples.

Les constantes suivantes peuvent être utilisées lors de la récupération des résultats afin d'en spécifier le comportement. Elles peuvent être passées aux fonctions cubrid_fetch() et cubrid_fetch_array().

Drapeaux de récupération CUBRID
Constante | Description
--- | ---
`CUBRID_NUM` | Récupère le résultat de la requête sous la forme d'un tableau numérique (dont les index commencent à 0).
`CUBRID_ASSOC` | Récupère le résultat de la requête sous la forme d'un tableau associatif.
`CUBRID_BOTH` | Récupère le résultat de la requête à la fois sous la forme d'un tableau numérique et sous la forme d'un tableau associatif (valeur par défaut).
`CUBRID_OBJECT` | Récupère le résultat de la requête sous la forme d'un objet.
`CUBRID_LOB` | La constante CUBRID_LOB peut être utilisée lorsque l'on veut utiliser un objet LOB. Elle peut être passée aux fonctions cubrid_fetch(), cubrid_fetch_row(), cubrid_fetch_array(), cubrid_fetch_assoc() et cubrid_fetch_object().

Les constantes suivantes peuvent être utilisées lors du positionnement du curseur dans les résultats de la requête. Elles peuvent être passées à ou retournées par la fonction cubrid_move_cursor().

Drapeaux sur le positionnement du curseur CUBRID
Constante | Description
--- | ---
`CUBRID_CURSOR_FIRST` | Déplace le curseur courant à la première position du résultat.
`CUBRID_CURSOR_CURRENT` | Déplace le curseur courant à une valeur par défaut si l'origine n'est pas spécifiée.
`CUBRID_CURSOR_LAST` | Déplace le curseur courant à la dernière position du résultat.
`CUBRID_CURSOR_SUCCESS` | La valeur retournée par la fonction cubrid_move_cursor() en cas de succès. Ce drapeau a été supprimé depuis la version 8.4.1.
`CUBRID_NO_MORE_DATA` | La valeur retournée par la fonction cubrid_move_cursor() si une erreur survient. Ce drapeau a été supprimé depuis la version 8.4.1.
`CUBRID_CURSOR_ERROR` | La valeur retournée par la fonction cubrid_move_cursor() si une erreur survient. Ce drapeau a été supprimé depuis la version 8.4.1.

Les constantes suivantes peuvent être utilisées lors de la définition du mode auto-commit pour la connexion à la base de données. Elles peuvent être passées à la fonction cubrid_set_autocommit() ou retournées par la fonction cubrid_get_autocommit().

Drapeaux CUBRID pour le mode auto-commit
Constante | Description
--- | ---
`CUBRID_AUTOCOMMIT_TRUE` | Active le mode auto-commit.
`CUBRID_AUTOCOMMIT_FALSE` | Désactive le mode auto-commit.

Les constantes suivantes peuvent être utilisées lors de la définition des paramètres à la base de données. Elles peuvent être passées à la fonction cubrid_set_db_parameter().

Drapeaux des paramètres CUBRID
Constante | Description
--- | ---
`CUBRID_PARAM_ISOLATION_LEVEL` | Niveau d'isolation de la transaction pour la connexion à la base de données.
`CUBRID_PARAM_LOCK_TIMEOUT` | Délai d'expiration de la transaction en secondes.

Les constantes suivantes peuvent être utilisées pour définir le niveau d'isolation de la transaction. Elles peuvent être passées à la fonction cubrid_set_db_parameter() ou retournées par la fonction cubrid_get_db_parameter().

Drapeaux CUBRID pour le niveau d'isolation
Constante | Description
--- | ---
`TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | Le niveau d'isolation le plus faible (1). Une lecture de données modifiées, non-répétables, ou fantômes peut survenir sur le tuple et, de plus, une lecture non-répétable peut survenir sur la table.
`TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | Un niveau d'isolation relativement bas (2). Une lecture de données modifiées ne peut pas survenir, mais une lecture de données non-répétables ou fantômes peut survenir.
`TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | Le niveau d'isolation par défaut pour CUBRID (3). Une lecture de données modifiées, non répétables ou fantômes peut survenir sur le tuple, mais la lecture de données répétables est assurée pour la table.
`TRAN_REP_CLASS_COMMIT_INSTANCE` | Un niveau d'isolation relativement bas (4). Une lecture de données modifiées ne peut pas survenir, mais une lecture de données non-répétables ou fantômes peut survenir.
`TRAN_REP_CLASS_REP_INSTANCE` | Un niveau d'isolation relativement haut (5). Une lecture de données modifiées ou non-répétables ne peut pas survenir, mais une lecture de données fantômes peut survenir.
`TRAN_SERIALIZABLE` | Le niveau d'isolation le plus haut (6). Les problèmes liés à la concurrence (c.-à-d. lecture de données modifiées, non-répétables, fantômes, etc.) ne peuvent pas survenir.

Les constantes suivantes peuvent être utilisées pour récupérer les informations de schéma. Elles peuvent être passées à la fonction cubrid_schema().

Drapeaux pour les schémas CUBRID
Constante | Description
--- | ---
`CUBRID_SCH_CLASS` | Récupère le nom et le type de la table dans CUBRID.
`CUBRID_SCH_VCLASS` | Récupère le nom et le type de la vue dans CUBRID.
`CUBRID_SCH_QUERY_SPEC` | Récupère la définition de la requête pour une vue.
`CUBRID_SCH_ATTRIBUTE` | Récupère les attributs d'une colonne d'une table.
`CUBRID_SCH_CLASS_ATTRIBUTE` | Récupère les attributs d'une table.
`CUBRID_SCH_METHOD` | Récupère la méthode de l'instance. La méthode de l'instance est la méthode appelée par une instance de classe. Elle est plus souvent utilisée qu'une méthode de classe car la plupart des opérations sont exécutées dans l'instance.
`CUBRID_SCH_CLASS_METHOD` | Récupère la méthode de classe. La méthode de classe est la méthode appelée par un objet de la classe. Elle est habituellement utilisée pour créer une nouvelle instance de la classe ou pour l'initialiser. Elle est également utilisée pour accéder ou mettre à jour les attributs de la classe.
`CUBRID_SCH_METHOD_FILE` | Récupère les informations du fichier définissant la méthode de la table.
`CUBRID_SCH_SUPERCLASS` | Récupère le nom et le type de la table pour laquelle la table hérite ses attributs.
`CUBRID_SCH_SUBCLASS` | Récupère le nom et le type de la table héritant des attributs.
`CUBRID_SCH_CONSTRAINT` | Récupère les contraintes de la table.
`CUBRID_SCH_TRIGGER` | Récupère les triggers de la table.
`CUBRID_SCH_CLASS_PRIVILEGE` | Récupère les informations quant aux privilèges de la table.
`CUBRID_SCH_ATTR_PRIVILEGE` | Récupère les informations de privilèges d'une colonne.
`CUBRID_SCH_DIRECT_SUPER_CLASS` | Récupère la table super direct de la table.
`CUBRID_SCH_PRIMARY_KEY` | Récupère la clé primaire de la table.
`CUBRID_SCH_IMPORTED_KEYS` | Récupère les clés importées de la table.
`CUBRID_SCH_EXPORTED_KEYS` | Récupère les clés exportées de la table.
`CUBRID_SCH_CROSS_REFERENCE` | Récupère les références des liens de 2 tables.

Les constantes suivantes peuvent être utilisées lors du rapport des erreurs. Elles peuvent être retournées par la fonction cubrid_error_code_facility().

Code de facilité des erreurs CUBRID
Constante | Description
--- | ---
`CUBRID_FACILITY_DBMS` | L'erreur est survenue dans la base de données CUBRID.
`CUBRID_FACILITY_CAS` | L'erreur est survenue dans le courtier CUBRID.
`CUBRID_FACILITY_CCI` | L'erreur est survenue dans le cci CUBRID.
`CUBRID_FACILITY_CLIENT` | L'erreur est survenue dans le client PHP CUBRID.

# Exemples

Ce qui suit est un simple exemple qui établit une connexion entre PHP et CUBRID. Cette section expose les fonctions les plus basiques et utiles. Le code suivant nécessite une connexion à la base de données CUBRID, ce qui signifie que le serveur CUBRID ainsi que le courtier CUBRID doivent être en fonctionnement.

L'exemple ci-dessous utilise la base de données demodb comme exemple. Par défaut, elle est créée durant l'installation. Il faut s'assurer que c'est bien le cas.

Exemple #1 Exemple de récupération de données

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc-kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * Définit les informations du serveur pour une connexion CUBRID.
             * host_ip est l'adresse IP pointant l'installation du courtier CUBRID (localhost
             * dans cet exemple), ainsi que le numéro de port à utiliser pour le courtier CUBRID.
             * Le numéro du port est celui par défaut fourni lors de l'installation.
             * Pour plus de détails, lisez le "Guide d'administration"
             */
            $host_ip = "localhost";
            $host_port = 33000;
            $db_name = "demodb";
            /**
             * Connexion au serveur CUBRID. N'effectue pas la connexion immédiatement,
             * mais ne fait que retenir les informations de connexions. La raison
             * pour laquelle la connexion ne s'effectue pas immédiatement est pour
             * gérer les transactions plus efficacement sur des architectures en 3 parties.
             */
            $cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

            if (!$cubrid_con) {
                echo "Erreur de connexion à la base de données";
                exit;
            }
        ?>
        <?php
            $sql = "select sports, count(players) as players from event group by sports";
            /**
             * Interroge le serveur CUBRID afin de récupérer les résultats de la requête SQL.
             * Maintenant, nous effectuons réellement la connexion au serveur CUBRID.
             */
            $result = cubrid_execute($cubrid_con, $sql);

            if ($result) {
                /**
                 * Récupère les noms des colonnes depuis le jeu de résultats créé par la requête SQL.
                 */
                $columns = cubrid_column_names($result);
                /**
                 * Récupère le nombre de colonnes depuis le jeu de résultats créé par la requête SQL.
                 */
                $num_fields = cubrid_num_cols($result);
                /**
                 * Liste les noms des colonnes depuis le jeu de résultats directement sur l'écran.
                 */
                echo "<tr>";

                while (list($key, $colname) = each($columns)) {
                    echo "<td align=center>$colname</td>";
                }

                echo "</tr>";

                /**
                 * Récupère les résultats depuis le jeu de résultats.
                 */
                while ($row = cubrid_fetch($result)) {
                    echo "<tr>";

                    for ($i = 0; $i < $num_fields; $i++) {
                        echo "<td align=center>";
                        echo $row[$i];
                        echo "</td>";
                    }

                    echo "</tr>";
                }
            }
            /**
             * Le module PHP dans CUBRID fonctionne en architecture 3 parties.
             * Lors de l'appel à une requête de type SELECT dans une transaction, elle
             * sera exécutée comme faisant partie de la transaction. Aussi, si la
             * transaction est annulée avant l'appel à la requête SELECT, elle sera
             * exécutée avec des performances moindres.
             */
            cubrid_commit($cubrid_con);
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

Exemple #2 Exemple d'insertion de données

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc- kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * host_ip est l'adresse IP pointant l'installation du courtier CUBRID.
             * host_port est le numéro du port du courtier CUBRID.
             * db_name est le nom de la base de données CUBRID.
             */
            $host_ip = "localhost";
            $host_port = 33000;
            $db_name = "demodb";
            $cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

            if (!$cubrid_con) {
                echo "Erreur lors de la connexion à la base de données";
                exit;
            }
        ?>
        <?php
            $sql = "insert into olympic (host_year,host_nation,host_city,"
                . "opening_date,closing_date) values (2008, 'China', 'Beijing',"
                . "to_date('08-08-2008','mm-dd- yyyy'),to_date('08-24-2008','mm-dd-yyyy')) ;";
            $result = cubrid_execute($cubrid_con, $sql);
            if ($result) {
                /**
                 * Traitement réussi, nous pouvons commiter.
                 */
                cubrid_commit($cubrid_con);
                echo "Insertion avec succès";
            } else {
                /**
                 * Une erreur est survenue, aussi, le message d'erreur est affiché et le rollback est appelé.
                 */
                echo cubrid_error_msg();
                cubrid_rollback($cubrid_con);
            }
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

# Fonctions CUBRID

# cubrid_bind

(PECL CUBRID >= 8.3.0)

cubrid_bind — Lie des valeurs à une requête préparée

### Description

function cubrid_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

La fonction cubrid_bind() est utilisée pour lier les valeurs à un marqueur correspondant, nommé ou non d'une requête SQL qui a été passée à la fonction cubrid_prepare(). Si le paramètre `bind_value_type` n'est pas fourni, le type chaîne de caractères sera le type par défaut.

> Note: Si le type de données à lier est BLOB/CLOB, CUBRID tentera de lier les données comme un flux PHP. Si le type de la valeur à lier n'est pas un flux, CUBRID la convertira en chaîne, et l'utilisera comme chemin complet et nom de fichier sur le système de fichiers client. Si le type de données à lier explicitement est ENUM, l'argument `bind_value` doit être l'élément ENUM sous forme de chaîne de caractères. En environnement partagé CUBRID, `bind_value_type` doit être inclus dans la fonction cubrid_bind().

La liste suivante montre les types des valeurs substituées.

Types de données liées CUBRID
Support | Type de liage | Type correspondant SQL
--- | --- | ---
Supporté | STRING | CHAR, VARCHAR
| NCHAR | NCHAR, NVARCHAR
| BIT | BIT, VARBIT
| NUMERIC or NUMBER | SHORT, INT, NUMERIC
| FLOAT | FLOAT
| DOUBLE | DOUBLE
| TIME | TIME
| DATE | DATE
| TIMESTAMP | TIMESTAMP
| OBJECT | OBJECT
| ENUM | ENUM
| BLOB | BLOB
| CLOB | CLOB
| NULL | NULL
Non supporté | SET | SET
| MULTISET | MULTISET
| SEQUENCE | SEQUENCE

### Liste de paramètres

`req_identifier`
  Identifiant de requête, retourné par la fonction cubrid_prepare().
`bind_index`
  Position des paramètres liés. Commence avec 1.
`bind_value`
  Valeur effective à lier.
`bind_value_type`
  Un type de valeur à lier (il est omis par défaut et en interne, le type chaîne de caractères sera utilisé. Cependant, il faut spécifier le type exact de la valeur comme argument lorsque l'on utilise NCHAR, BIT, ou BLOB/CLOB).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.3.1 | Ajout du support des types BLOB/CLOB.

### Exemples

Exemple #1 Exemple avec cubrid_bind()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE sports='Basketball' and gender='M'");
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $game_req = cubrid_prepare($conn, "SELECT athlete_code FROM game WHERE host_year=1992 and event_code=? and nation_code='USA'");
    cubrid_bind($game_req, 1, $event_code, "number");
    cubrid_execute($game_req);

    printf("--- Dream Team (1992 United States men's Olympic basketball team) ---\n");
    while ($athlete_code = cubrid_fetch_array($game_req, CUBRID_NUM)) {
        $athlete_req = cubrid_prepare($conn, "SELECT name FROM athlete WHERE code=? AND nation_code='USA' AND event='Basketball' AND gender='M'");
        cubrid_bind($athlete_req, 1, $athlete_code[0], "number");
        cubrid_execute($athlete_req);
        $row = cubrid_fetch_assoc($athlete_req);
        printf("%s\n", $row["name"]);
    }

    cubrid_close_request($game_req);
    cubrid_close_request($athlete_req);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    --- Dream Team (1992 United States men's Olympic basketball team) ---
    Stockton John
    Robinson David
    Pippen Scottie
    Mullin C.
    Malone Karl
    Laettner C.
    Jordan Michael
    Johnson Earvin
    Ewing Patrick
    Drexler Clyde
    Bird Larry
    Barkley Charles

Exemple #2 Exemple avec cubrid_bind() et les types BLOB/CLOB

    <?php
    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (doc_content CLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(doc_content) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        $fp = fopen("book.txt", "rb");

        cubrid_bind($req, 1, $fp, "clob");
        cubrid_execute($req);
    }
    ?>

Exemple #3 Exemple avec cubrid_bind() et BLOB/CLOB

    <?php
    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (image BLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(image) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        cubrid_bind($req, 1, "cubrid_logo.png", "blob");
        cubrid_execute($req);
    }
    ?>

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_prepare() - Prépare une requête SQL pour son exécution

# cubrid_close_prepare

(PECL CUBRID >= 8.3.0)

cubrid_close_prepare — Ferme le gestionnaire de requête

### Description

function cubrid_close_prepare(resource `$req_identifier`): bool

La fonction cubrid_close_prepare() ferme le gestionnaire de requête fourni par l'argument `req_identifier` et libère la région mémoire associée. C'est un alias de la fonction cubrid_close_request().

### Liste de paramètres

`req_identifier`
  Identifiant de requête.

### Valeurs de retour

`true` en cas de succès.

### Exemples

Exemple #1 Exemple avec cubrid_close_prepare()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
    if ($con) {
       echo "Connexion réalisée avec succès";
       $req = cubrid_execute ( $con, "select * from members",
                               CUBRID_INCLUDE_OID | CUBRID_ASYNC);
       if ($req) {
          while ( list ($id, $name) = cubrid_fetch ($req) ){
             echo $id;
             echo $name;
          }
          cubrid_close_prepare($req); // vous pouvez aussi utiliser cubrid_close_request($req)
       }
       cubrid_disconnect($con);
    }
    ?>

### Voir aussi

- cubrid_close_request() - Ferme le gestionnaire de requête

# cubrid_close_request

(PECL CUBRID >= 8.3.0)

cubrid_close_request — Ferme le gestionnaire de requête

### Description

function cubrid_close_request(resource `$req_identifier`): bool

La fonction cubrid_close_request() ferme le gestionnaire de requête fourni par l'argument `req_identifier` et libère la mémoire associée. C'est un alias de la fonction cubrid_close_prepare().

### Liste de paramètres

`req_identifier`
  Identifiant de requête.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec cubrid_close_request()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
    if ($con) {
       echo "Connexion réalisée avec succès";
       $req = cubrid_execute ( $con, "select * from members",
                               CUBRID_INCLUDE_OID | CUBRID_ASYNC);
       if ($req) {
          while ( list ($id, $name) = cubrid_fetch ($req) ){
             echo $id;
             echo $name;
          }
          cubrid_close_request($req); // ou vous pouvez utiliser cubrid_close_prepare($req)
       }
       cubrid_disconnect($con);
    }
    ?>

### Voir aussi

- cubrid_close_prepare() - Ferme le gestionnaire de requête

# cubrid_col_get

(PECL CUBRID >= 8.3.0)

cubrid_col_get — Récupère le contenu des éléments d'un type de collection en utilisant l'OID

### Description

function cubrid_col_get(resource `$conn_identifier`, string `$oid`, string `$attr_name`): array

La fonction cubrid_col_get() est utilisée pour récupérer le contenu des attributs des éléments d'un type de collection (set, multiset, sequence), sous la forme d'un tableau.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance à utiliser pour la lecture.
`attr_name`
  Nom de l'attribut que l'on veut lire depuis l'instance.

### Valeurs de retour

Un tableau (numérique, commençant à 0) contenant les éléments voulus lorsque l'opération a été réalisée avec succès.

`false` (afin de distinguer les erreurs et le fait que les attributs ont une collection vide ou nul ; en cas d'erreur, un message d'alerte sera affiché ; dans ce cas, il est possible de récupérer l'erreur en utilisant la fonction cubrid_error_code()), lorsque l'opération a échoué.

### Exemples

Exemple #1 Exemple avec cubrid_col_get()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_col_size

(PECL CUBRID >= 8.3.0)

cubrid_col_size — Récupère le nombre d'éléments dans un type de colonne d'une collection en utilisant l'OID

### Description

function cubrid_col_size(resource `$conn_identifier`, string `$oid`, string `$attr_name`): int

La fonction cubrid_col_size() est utilisée pour récupérer le nombre d'éléments dans un attribut de type de collection (set, multiset, sequence).

### Liste de paramètres

`conn_identifier`
  Un identifiant de connexion.
`oid`
  OID de l'instance à utiliser.
`attr_name`
  Nom de l'attribut à utiliser.

### Valeurs de retour

Nombre d'éléments, lorsque l'opération est un succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.3.1 | Modification de la valeur retournée : lorsque l'opération échoue, la fonction retourne maintenant `false` au lieu de -1.

### Exemples

Exemple #1 Exemple avec cubrid_col_size()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_column_names

(PECL CUBRID >= 8.3.0)

cubrid_column_names — Récupère les noms de colonnes du résultat

### Description

function cubrid_column_names(resource `$req_identifier`): array

La fonction cubrid_column_names() est utilisée pour récupérer les noms de colonnes du résultat de la requête en utilisant le paramètre `req_identifier`.

### Liste de paramètres

`req_identifier`
  Identifiant de requête.

### Valeurs de retour

Un tableau de chaînes de caractères contenant les noms des colonnes lorsque l'opération est un succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_column_names()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Voir aussi

- cubrid_prepare() - Prépare une requête SQL pour son exécution
- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_column_types() - Récupère les types de colonnes du résultat

# cubrid_column_types

(PECL CUBRID >= 8.3.0)

cubrid_column_types — Récupère les types de colonnes du résultat

### Description

function cubrid_column_types(resource `$req_identifier`): array

La fonction cubrid_column_types() récupère les types de colonnes du résultat de la requête en utilisant le paramètre `req_identifier`.

### Liste de paramètres

`req_identifier`
  Identifiant de requête.

### Valeurs de retour

Un tableau de chaînes de caractères contenant les types de colonnes, lorsque l'opération est un succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_column_types()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Voir aussi

- cubrid_column_names() - Récupère les noms de colonnes du résultat
- cubrid_prepare() - Prépare une requête SQL pour son exécution
- cubrid_execute() - Exécute une requête SQL préparée

# cubrid_commit

(PECL CUBRID >= 8.3.0)

cubrid_commit — Valide une transaction

### Description

function cubrid_commit(resource `$conn_identifier`): bool

La fonction cubrid_commit() est utilisée pour valider une transaction pointée par le paramètre `conn_identifier`. La connexion au serveur sera fermée après l'appel à la fonction cubrid_commit() ; cependant, le gestionnaire de connexion restera valide.

En CUBRID PHP, le mode auto-commit est désactivé par défaut pour la gestion des transactions. Il est possible de définir en utilisant la fonction cubrid_set_autocommit(). Il est possible de récupérer son statut en utilisant la fonction cubrid_get_autocommit(). Avant de commencer une transaction, il ne faut pas oublier de désactiver le mode auto-commit.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_commit()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;

    cubrid_set_autocommit($conn,false);

    if (!cubrid_execute($conn, $sql)) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Voir aussi

- cubrid_rollback() - Annule une transaction
- cubrid_get_autocommit() - Récupère le mode auto-commit de la connexion
- cubrid_set_autocommit() - Définit le mode auto-commit pour la connexion

# cubrid_connect

(PECL CUBRID >= 8.3.1)

cubrid_connect — Ouvre une connexion au serveur CUBRID

### Description

function cubrid_connect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

La fonction cubrid_connect() est utilisée pour établir l'environnement pour une connexion au serveur en utilisant l'adresse du serveur, le numéro du port, le nom de la base de données, le nom d'utilisateur et son mot de passe. Si le nom d'utilisateur et le mot de passe ne sont pas fournis, alors une connexion "PUBLIC" sera effectuée par défaut.

### Liste de paramètres

`host`
  Nom d'hôte ou adresse IP du serveur CUBRID CAS.
`port`
  Numéro du port du serveur CUBRID CAS (BROKER_PORT est configuré dans le fichier $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Nom de la base de données.
`userid`
  Nom d'utilisateur pour la base de données. Si non fourni, la valeur par défaut est "public".
`passwd`
  Mot de passe pour l'utilisateur. Si non fourni, la valeur par défaut est "".
`new_link`
  Si un second appel est effectué à la fonction cubrid_connect() avec les mêmes arguments, aucune nouvelle connexion ne sera établie, et l'identifiant de la connexion déjà ouverte sera retourné à la place. Le paramètre `new_link` modifie ce comportement et fera que la fonction cubrid_connect() ouvre toujours une nouvelle connexion, y compris si la fonction cubrid_connect() a déjà été appelée avec les mêmes arguments.

### Valeurs de retour

Un identifiant de connexion, lorsque l'opération a été réalisée avec succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_connect()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Voir aussi

- cubrid_pconnect() - Ouvre une connexion persistante vers un serveur CUBRID
- cubrid_connect_with_url() - Établit l'environnement pour une connexion au serveur CUBRID
- cubrid_pconnect_with_url() - Ouvre une connexion persistante vers un serveur CUBRID
- cubrid_disconnect() - Ferme la connexion à la base de données
- cubrid_close() - Ferme une connexion CUBRID

# cubrid_connect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_connect_with_url — Établit l'environnement pour une connexion au serveur CUBRID

### Description

function cubrid_connect_with_url(
string `$conn_url`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

La fonction cubrid_connect_with_url() est utilisée pour préparer l'environnement pour la connexion au serveur en utilisant les informations de connexion passées avec des arguments dans l'URL. Si la fonctionnalité HA est active pour CUBRID, il faut spécifier les informations de connexion du serveur de secours, qui sera utilisé comme backup lorsqu'une erreur survient. Si le nom d'utilisateur et le mot de passe ne sont pas fournis, alors la connexion "PUBLIC" sera établie par défaut.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : Un nom d'hôte ou une adresse IP vers la base de données principale
- db_name : Un nom de base de données
- db_user : Un nom d'utilisateur pour la base de données
- db_password : Le mot de passe associé à l'utilisateur
- alhosts : spécifie le courtier d'information pour le serveur de secours, qui sera utilisé comme backup lorsqu'il devient impossible de se connecter au serveur courant. Il est possible de spécifier plusieurs courtiers comme backup et la connexion aux courtiers se fera dans l'ordre d'alhosts
- rctime : un intervalle pendant lequel il sera tenté de se connecter au courtier actif lorsqu'une erreur survient. Après qu'une erreur est survenue, le système se connecte au courtier spécifié par althosts, met fin à la transaction, et tente une connexion au courtier actif de la base de données principale à chaque intervalle rctime. La valeur par défaut est 600 secondes.
- login_timeout : Valeur du délai maximal d'attente (unité : milliseconde) pour l'identification à la base de données. Par défaut, cette valeur vaut 0, ce qui signifie que l'on attend indéfiniment.
- query_timeout : Valeur du délai maximal d'attente (unité : milliseconde) pour l'exécution de la requête. Une fois cette valeur atteinte, un message pour annuler la requête en cours est envoyé au serveur. La valeur retournée peut dépendre de la configuration de disconnect_on_query_timeout ; même si le message pour annuler la requête a été envoyé au serveur, la requête peut réussir.
- disconnect_on_query_timeout : Configure une valeur déterminant si l'on doit retourner immédiatement une erreur pour les fonctions exécutées après le délai maximal d'attente. La valeur par défaut est `false`.

> Note: Les caractères `?` et `:` utilisés comme identifiants dans les URLs de connexion PHP ne peuvent être inclus dans le mot de passe. Voici un exemple de mot de passe invalide, car utilisant les caractères "`?:`" dans l'URL de connexion. $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Les mots de passe contenant le caractère `?` ou le caractère `:` peuvent être passés en tant que paramètre séparé. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_connect_with_url($url, "dba", "12?"); Si le nom d'utilisateur ou le mot de passe est vide, l'on ne doit pas supprimer les "`:`" ; voici un exemple : $url = "CUBRID:localhost:33000:demodb:::";

### Liste de paramètres

`conn_url`
  Une chaîne de caractères contenant les informations de connexion au serveur.
`userid`
  Le nom d'utilisateur de la base de données.
`passwd`
  Le mot de passe de l'utilisateur.
`new_link`
  Si un second appel est effectué à la fonction cubrid_connect_with_url() avec les mêmes arguments, aucune nouvelle connexion ne sera établie, et l'identifiant de la connexion déjà ouverte sera retourné à la place. Le paramètre `new_link` modifie ce comportement et fera que la fonction cubrid_connect_with_url() ouvre toujours une nouvelle connexion, y compris si la fonction cubrid_connect_with_url() a déjà été appelée avec les mêmes arguments.

### Valeurs de retour

Identifiant de connexion, en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_connect_with_url()

    <?php
    $conn_url = "CUBRID:localhost:33000:demodb:dba::";
    $con = cubrid_connect_with_url($conn_url);

    if ($con) {
       echo "Connexion avec succès.";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

Exemple #2 Exemple avec cubrid_connect_with_url()

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?login_timeout=100";
    $con = cubrid_connect_with_url ($conn_url);

    if ($con) {
       echo "Connexion avec succès.";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

### Voir aussi

- cubrid_connect() - Ouvre une connexion au serveur CUBRID
- cubrid_pconnect() - Ouvre une connexion persistante vers un serveur CUBRID
- cubrid_pconnect_with_url() - Ouvre une connexion persistante vers un serveur CUBRID
- cubrid_disconnect() - Ferme la connexion à la base de données
- cubrid_close() - Ferme une connexion CUBRID

# cubrid_current_oid

(PECL CUBRID >= 8.3.0)

cubrid_current_oid — Récupère l'OID de la localisation du curseur courant

### Description

function cubrid_current_oid(resource `$req_identifier`): string

La fonction cubrid_current_oid() est utilisée pour récupérer l'OID de la localisation du curseur courant. Pour utiliser la fonction cubrid_current_oid(), la requête exécutée doit être une requête de mise à jour, et l'option `CUBRID_INCLUDE_OID` doit être incluse lors de l'exécution de la requête.

### Liste de paramètres

`req_identifier`
  Identifiant de requête.

### Valeurs de retour

OID de la localisation du curseur courant, lorsque l'opération est un succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_current_oid()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $res = cubrid_get($conn, $oid);

    print_r($res);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [s_name] => X
        [f_name] => Mixed
    )

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée

# cubrid_disconnect

(PECL CUBRID >= 8.3.0)

cubrid_disconnect — Ferme la connexion à la base de données

### Description

function cubrid_disconnect(resource `$conn_identifier` = ?): bool

La fonction cubrid_disconnect() ferme le gestionnaire de connexion et se déconnecte du serveur. S'il existe des gestionnaires de requêtes non fermés, à ce moment là, ils le seront. Cette fonction est similaire à la fonction cubrid_close().

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_disconnect()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
       echo "Connexion réussie";

       $req = cubrid_execute( $con, "create table person(id int,name char(10))");
       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }

       $req = cubrid_execute( $con, "insert into person values(1,'James')");
       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

### Voir aussi

- cubrid_close() - Ferme une connexion CUBRID
- cubrid_connect() - Ouvre une connexion au serveur CUBRID
- cubrid_connect_with_url() - Établit l'environnement pour une connexion au serveur CUBRID

# cubrid_drop

(PECL CUBRID >= 8.3.0)

cubrid_drop — Supprime une instance en utilisant son OID

### Description

function cubrid_drop(resource `$conn_identifier`, string `$oid`): bool

La fonction cubrid_drop() est utilisée pour supprimer une instance de la base de données en utilisant le paramètre `oid` de l'instance.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  Oid de l'instance que l'on veut supprimer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("--- Before Drop: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    if (cubrid_drop($conn, $oid)) {
        cubrid_commit($conn);
    } else {
        cubrid_rollback($conn);
    }

    cubrid_close_request($req);

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("\n--- After Drop: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    --- Before Drop: ---
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

    --- After Drop: ---
    array(4) {
      ["a"]=>
      string(1) "2"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "4"
        [1]=>
        string(1) "5"
        [2]=>
        string(1) "7"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "44"
        [1]=>
        string(2) "55"
        [2]=>
        string(2) "66"
        [3]=>
        string(3) "666"
      }
      ["d"]=>
      string(10) "b         "
    }

### Voir aussi

- cubrid_is_instance() - Vérifie si une instance existe

# cubrid_error_code

(PECL CUBRID >= 8.3.0)

cubrid_error_code — Récupère le code erreur de la dernière erreur survenue

### Description

function cubrid_error_code(): int

La fonction cubrid_error_code() est utilisée pour récupérer le code erreur survenue lors de l'exécution de l'API. Habituellement, elle récupère le code erreur lorsque l'API retourne `false`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le code erreur de la dernière erreur survenue, ou `0` (zéro) si aucune erreur n'est survenue.

### Exemples

Exemple #1 Exemple avec cubrid_error_code()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_prepare($conn , "SELECT * FROM code WHERE s_name=?");

    $req = @cubrid_execute($req);
    if (!$req) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

L'exemple ci-dessus va afficher :

    Error facility: 4
    Error code: -30015
    Error msg: Some parameter not binded

### Voir aussi

- cubrid_error_code_facility() - Récupère le niveau du code erreur
- cubrid_error_msg() - Récupère le message d'erreur de la dernière erreur survenue

# cubrid_error_code_facility

(PECL CUBRID >= 8.3.0)

cubrid_error_code_facility — Récupère le niveau du code erreur

### Description

function cubrid_error_code_facility(): int

La fonction cubrid_error_code_facility() est utilisée pour récupérer le niveau du code erreur (niveau dans lequel l'erreur est survenue) depuis le code erreur d'une erreur survenue lors de l'exécution de l'API. Habituellement, il est possible de récupérer le code erreur lorsque l'API retourne `false`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le niveau du code d'erreur survenue : `CUBRID_FACILITY_DBMS`, `CUBRID_FACILITY_CAS`, `CUBRID_FACILITY_CCI`, `CUBRID_FACILITY_CLIENT`.

### Exemples

Exemple #1 Exemple avec cubrid_error_code_facility()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = @cubrid_execute($conn, "SELECT * FROM unknown");
    if (!$req) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

L'exemple ci-dessus va afficher :

    Error facility: 1
    Error code: -493
    Error msg: Syntax: In line 1, column 15 before END OF STATEMENT
    Syntax error: unexpected 'unknown'

### Voir aussi

- cubrid_error_code() - Récupère le code erreur de la dernière erreur survenue
- cubrid_error_msg() - Récupère le message d'erreur de la dernière erreur survenue

# cubrid_error_msg

(PECL CUBRID >= 8.3.0)

cubrid_error_msg — Récupère le message d'erreur de la dernière erreur survenue

### Description

function cubrid_error_msg(): string

La fonction cubrid_error_msg() est utilisée pour récupérer le message d'erreur survenu lors de l'utilisation de l'API CUBRID. Habituellement, elle récupère le message d'erreur lorsque l'API retourne `false`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le message d'erreur survenu.

### Exemples

Exemple #1 Exemple avec cubrid_error_msg()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    if (!@cubrid_schema($conn, 100000)) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

L'exemple ci-dessus va afficher :

    Error facility: 2
    Error code: -10015
    Error msg: Invalid T_CCI_SCH_TYPE value

### Voir aussi

- cubrid_error_code() - Récupère le code erreur de la dernière erreur survenue
- cubrid_error_code_facility() - Récupère le niveau du code erreur

# cubrid_execute

(PECL CUBRID >= 8.3.0)

cubrid_execute — Exécute une requête SQL préparée

### Description

function cubrid_execute(resource `$conn_identifier`, string `$sql`, int `$option` = 0): resource
function cubrid_execute(resource `$request_identifier`, int `$option` = 0): bool

La fonction cubrid_execute() est utilisée pour exécuter une requête SQL. Elle exécute la requête en utilisant le paramètre `conn_identifier` et SQL, puis, retourne l'identifiant de requête créé. Elle est utilisée pour une exécution simple de requête, où le liage de paramètre n'est pas nécessaire. De plus, la fonction cubrid_execute() est utilisée pour exécuter la requête préparée en utilisant cubrid_prepare() et cubrid_bind(). À ce point, il faut spécifier les arguments `request_identifier` et `option`.

L'`option` est utilisée pour déterminer si l'on doit récupérer l'OID après l'exécution de la requête, et si l'on doit exécuter la requête en mode asynchrone ou non. `CUBRID_INCLUDE_OID` et `CUBRID_ASYNC` (ou `CUBRID_EXEC_QUERY_ALL` si l'on veut exécuter plusieurs requêtes SQL) peuvent être spécifiés en utilisant l'opérateur OR bit à bit. Si l'opérateur n'est pas spécifié, aucun des deux ne sera sélectionné. Si le drapeau `CUBRID_EXEC_QUERY_ALL` est défini, le mode synchrone (sync_mode) sera utilisé pour récupérer les résultats de la requête, et dans un tel cas, les règles suivantes seront appliquées :

- La valeur retournée sera le résultat de la première requête.
- Si une erreur survient dans une des requêtes, l'exécution sera vue comme étant un échec.
- Pour une requête composée de q1 q2 et q3, si une erreur survient dans q2 alors que q1 a été exécutée avec succès, le résultat de q1 reste valide. Ainsi, l'exécution avec succès d'une précédente requête ne sera pas annulée lorsqu'une erreur survient.
- Si une requête est exécutée avec succès, le résultat de la seconde requête peut être obtenu en utilisant la fonction cubrid_next_result().

Si le premier paramètre est `request_identifier` pour exécuter la fonction cubrid_prepare(), il est possible de spécifier une option, `CUBRID_ASYNC` uniquement.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`sql`
  SQL à exécuter.
`option`
  Option d'exécution de la requête : `CUBRID_INCLUDE_OID`, `CUBRID_ASYNC`, `CUBRID_EXEC_QUERY_ALL`.
`request_identifier`
  Identifiant de requête pour la fonction cubrid_prepare().

### Valeurs de retour

Un identifiant de requête, lorsque l'opération a été réalisée avec succès et que le premier paramètre est l'identifiant de connexion ; `true`, lorsque l'opération a été réalisée avec succès et que le premier paramètre est l'identifiant de requête, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Ajout d'une nouvelle option : `CUBRID_EXEC_QUERY_ALL`.

### Exemples

Exemple #1 Exemple avec cubrid_execute()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE name='100m Butterfly' and gender='M'", CUBRID_ASYNC);
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $history_req = cubrid_prepare($conn, "SELECT * FROM history WHERE event_code=?");
    cubrid_bind($history_req, 1, $event_code, "number");
    cubrid_execute($history_req);

    printf("%-20s %-9s %-10s %-5s\n", "athlete", "host_year", "score", "unit");
    while ($row = cubrid_fetch_array($history_req, CUBRID_ASSOC)) {
        printf("%-20s %-9s %-10s %-5s\n",
            $row["athlete"], $row["host_year"], $row["score"], $row["unit"]);
    }

    cubrid_close_request($history_req);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    athlete              host_year score      unit
    Phelps Michael       2004      51.25      time

### Voir aussi

- cubrid_prepare() - Prépare une requête SQL pour son exécution
- cubrid_bind() - Lie des valeurs à une requête préparée
- cubrid_next_result() - Récupère le résultat de la prochaine requête lors de l'exécution de requêtes SQL multiples
- cubrid_close_request() - Ferme le gestionnaire de requête
- cubrid_commit() - Valide une transaction
- cubrid_rollback() - Annule une transaction

# cubrid_fetch

(PECL CUBRID >= 8.3.0)

cubrid_fetch — Récupère la prochaine ligne du jeu de résultats

### Description

function cubrid_fetch(resource `$result`, int `$type` = CUBRID_BOTH): mixed

La fonction cubrid_fetch() est utilisée pour récupérer une seule ligne depuis le résultat de la requête. Le curseur se déplace automatiquement sur la prochaine ligne une fois la récupération effectuée.

### Liste de paramètres

`result`
  Le paramètre `result` provient de l'appel à la fonction cubrid_execute()
`type`
  Type du tableau à retourner : CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH, CUBRID_OBJECT. Si l'on veut utiliser un objet LOB, il est possible d'utiliser CUBRID_LOB.

### Valeurs de retour

Tableau ou objet de résultat, en cas de succès.

`false` lorsqu'il n'y a plus de ligne de disponible, NULL si une erreur survient.

Le résultat peut être sous la forme d'un tableau ou d'un objet ; le type de résultat peut être défini grâce au paramètre `type`. La variable `type` peut être définie à une des valeurs suivantes :

- CUBRID_NUM : Tableau numérique (en commençant à l'indice 0)
- CUBRID_ASSOC : Tableau associatif
- CUBRID_BOTH : Tableau numérique et associatif (valeur par défaut)
- CUBRID_OBJECT : Objet dont les noms des attributs correspondent aux noms des colonnes du résultat de la requête

Lorsque l'argument `type` est omis, le résultat sera retourné en utilisant l'option CUBRID_BOTH par défaut. Lorsque l'on veut recevoir le résultat de la requête sous la forme d'un objet, le nom de la colonne du résultat doit être conforme aux règles de nommage des identifiants en PHP. Par exemple, les noms de colonnes comme "count(*)" ne peuvent être acceptés dans le type objet.

### Exemples

Exemple #1 Exemple avec cubrid_fetch()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT * FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch($req)) {
        printf("%-40s %-10s %-6s %-20s\n",
            $row["name"], $row["area"], $row["seats"], $row["address"]);
    }

    // Si vous voulez utiliser un objet LOB, vous pouvez utiliser
    // cubrid_fetch($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_fetch_array() - Récupère une ligne de résultat sous forme de tableau associatif, de tableau numérique, ou les deux
- cubrid_fetch_row() - Retourne un tableau numérique avec les valeurs de la ligne courante
- cubrid_fetch_assoc() - Retourne un tableau associatif correspondant à la ligne récupérée
- cubrid_fetch_object() - Récupère la prochaine ligne et la retourne sous la forme d'un objet

# cubrid_free_result

(PECL CUBRID >= 8.3.0)

cubrid_free_result — Libère la mémoire occupée par les données de résultat

### Description

function cubrid_free_result(resource `$req_identifier`): bool

Cette fonction libère la mémoire occupée par les données de résultat. Elle retourne `true` en cas de succès, `false` sinon. Il est à noter que cette fonction ne libère que le buffer de récupération du client, et que si l'on veut libérer toute la mémoire, il faut utiliser la fonction cubrid_close_request().

### Liste de paramètres

`req_identifier`
  Identifiant de requête.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_free_result()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM history WHERE host_year=2004 ORDER BY event_code");
    $row = cubrid_fetch_assoc($req);
    var_dump($row);

    cubrid_free_result($req);
    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(5) {
      ["event_code"]=>
      string(5) "20005"
      ["athlete"]=>
      string(12) "Hayes Joanna"
      ["host_year"]=>
      string(4) "2004"
      ["score"]=>
      string(5) "12.37"
      ["unit"]=>
      string(4) "time"
    }

# cubrid_get

(PECL CUBRID >= 8.3.0)

cubrid_get — Récupère une colonne en utilisant son OID

### Description

function cubrid_get(resource `$conn_identifier`, string `$oid`, mixed `$attr` = ?): mixed

La fonction cubrid_get() est utilisée pour récupérer l'attribut de l'instance représentée par l'`oid` fourni. Il est possible de récupérer un seul attribut en utilisant le type de données "chaîne de caractères" de l'argument `attr` ou plusieurs attributs en utilisant le type de données "tableau" de l'argument `attr`.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance depuis laquelle l'on veut lire.
`attr`
  Nom de l'attribut que l'on veut lire.

### Valeurs de retour

Le contenu de l'attribut demandé, lorsque l'opération a réussi : lorsque le paramètre `attr` est défini comme type de données "chaîne de caractères", le résultat est retourné sous la forme d'une chaîne de caractères ; lorsque le paramètre `attr` est défini comme type de données "tableau" (tableau numérique commençant à 0), le résultat est retourné sous la forme d'un tableau associatif. Lorsque le paramètre `attr` est omis, alors tous les attributs seront retournés dans un tableau.

`false` si une erreur survient ou si le résultat vaut `null` (si une erreur survient, pour distinguer d'une chaîne vide, un message d'alerte sera émis. Il est possible de récupérer l'erreur en utilisant la fonction cubrid_error_code()).

### Exemples

Exemple #1 Exemple avec cubrid_get()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Voir aussi

- cubrid_put() - Met à jour une colonne suivant son OID

# cubrid_get_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_get_autocommit — Récupère le mode auto-commit de la connexion

### Description

function cubrid_get_autocommit(resource `$conn_identifier`): bool

La fonction cubrid_get_autocommit() est utilisée pour récupérer le statut du mode auto-commit de la connexion à la base de données CUBRID.

En CUBRID 8.4.0, le mode auto-commit est désactivé par défaut pour la gestion des transactions.

En CUBRID 8.4.1, le mode auto-commit est activé par défaut pour la gestion des transactions.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.

### Valeurs de retour

`true`, lorsque le mode auto-commit est actif.

`false`, lorsque le mode auto-commit est inactif.

`null` Si une erreur survient.

### Voir aussi

- cubrid_set_autocommit() - Définit le mode auto-commit pour la connexion
- cubrid_commit() - Valide une transaction

# cubrid_get_charset

(PECL CUBRID >= 8.3.0)

cubrid_get_charset — Retourne le jeu de caractères utilisé sur la connexion CUBRID courante

### Description

function cubrid_get_charset(resource `$conn_identifier`): string

Cette fonction retourne le jeu de caractères sur la connexion CUBRID courante et est similaire à la fonction CUBRID compatible MySQL cubrid_client_encoding().

### Liste de paramètres

`conn_identifier`
  La connexion CUBRID.

### Valeurs de retour

Une chaîne de caractères représentant le jeu de caractères sur la connexion CUBRID en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_get_charset()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('Connexion impossible.');
    }

    printf("Jeu de caractères CUBRID courant : %s\n", cubrid_get_charset($con));

    ?>

L'exemple ci-dessus va afficher :

    Jeu de caractères CUBRID courant : iso8859-1

### Voir aussi

- cubrid_client_encoding() - Retourne le jeu de caractères utilisé sur la connexion CUBRID courante

# cubrid_get_class_name

(PECL CUBRID >= 8.3.0)

cubrid_get_class_name — Récupère le nom de la classe en utilisant son OID

### Description

function cubrid_get_class_name(resource `$conn_identifier`, string `$oid`): string

La fonction cubrid_get_class_name() est utilisée pour récupérer le nom de la classe depuis l'`oid`. Ce mécanisme ne fonctionne pas lors de la sélection de données depuis des tables systèmes, comme db_class.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance dont l'on veut vérifier l'existence.

### Valeurs de retour

Le nom de la classe, en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_get_class_name()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $class_name = cubrid_get_class_name($conn, $oid);

    print_r($class_name);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    code

### Voir aussi

- cubrid_is_instance() - Vérifie si une instance existe
- cubrid_drop() - Supprime une instance en utilisant son OID

# cubrid_get_client_info

(PECL CUBRID >= 8.3.0)

cubrid_get_client_info — Retourne la version de la bibliothèque cliente

### Description

function cubrid_get_client_info(): string

Cette fonction retourne une chaîne de caractères représentant la version de la bibliothèque cliente.

### Liste de paramètres

### Valeurs de retour

Une chaîne de caractères représentant la version de la bibliothèque cliente en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_get_client_info()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

L'exemple ci-dessus va afficher :

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

# cubrid_get_db_parameter

(PECL CUBRID >= 8.3.0)

cubrid_get_db_parameter — Retourne les paramètres de la base de données CUBRID

### Description

function cubrid_get_db_parameter(resource `$conn_identifier`): array

Cette fonction retourne les paramètres de la base de données CUBRID, ou `false` si une erreur survient. Elle retourne un tableau associatif avec les valeurs des paramètres suivants :

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`
- `PARAM_MAX_STRING_LENGTH`
- `PARAM_AUTO_COMMIT`

Paramètres de la base de données
Paramètre | Description
--- | ---
PARAM_ISOLATION_LEVEL | Le niveau d'isolation de la transaction.
LOCK_TIMEOUT | CUBRID fournit la fonctionnalité de verrou du délai d'expiration, qui définit le temps d'attente (en secondes) pour le verrou tant que la configuration du verrou de la transaction est autorisée. La valeur par défaut du paramètre lock_timeout_in_secs vaut -1, qui signifie que l'application cliente attendra indéfiniment tant que le verrou de transaction est autorisé.
PARAM_AUTO_COMMIT | En CUBRID PHP, le mode auto-commit est désactivé par défaut pour le gestionnaire de transaction. Il peut être défini par la fonction cubrid_set_autocommit().

La table suivante montre les niveaux d'isolation de 1 à 6 :

Niveaux d'isolation supportés par CUBRID
Nom | Description
--- | ---
SERIALIZABLE (6) | Dans ce niveau d'isolation, les problèmes de concurrence (c.-à-d. lecture de données modifiées, lecture répétée de données, lecture de données fantôme, etc.) ne peuvent pas survenir.
REPEATABLE READ CLASS avec REPEATABLE READ INSTANCES (5) | Une autre transaction T2 ne peut pas mettre à jour le schéma de la table A tant que la transaction T1 lit la table A. La transaction T1 peut rencontrer des données fantômes de l'enregistrement R qui a été inséré par la transaction T2 lorsqu'elle récupère à plusieurs reprises un enregistrement spécifique.
REPEATABLE READ CLASS with READ COMMITTED INSTANCES (or CURSOR STABILITY) (4) | Une autre transaction T2 ne peut pas mettre à jour le schéma de la table A alors qu'une transaction T1 lit la table A. La transaction T1 peut rencontrer des lectures répétées de données qui ont été mises à jour, et validées par une autre transaction T2 lorsqu'elle récupère à plusieurs reprises l'enregistrement R.
REPEATABLE READ CLASS with READ UNCOMMITTED INSTANCES (3) | Niveau d'isolation par défaut. Une transaction T2 ne peut pas mettre à jour le schéma de la table A alors qu'une transaction T1 lit la table A. La transaction T1 peut rencontrer des données non mises à jour pour l'enregistrement qui a été mis à jour mais non encore validé par la transaction T2.
READ COMMITTED CLASS with READ COMMITTED INSTANCES (2) | La transaction T1 peut rencontrer des lectures répétées de données pour la table qui a été mise à jour et validée par la transaction T2 alors qu'elle lit plusieurs fois la table A. La transaction T1 peut rencontrer des lectures répétées de données pour l'enregistrement qui a été mis à jour et validé par la transaction T2 alors qu'elle récupère à plusieurs reprises l'enregistrement R.
READ COMMITTED CLASS with READ UNCOMMITTED INSTANCES (1) | La transaction T1 peut rencontrer des lectures répétées de données pour la table qui a été mise à jour et validée par la transaction T2 alors qu'elle lit à plusieurs reprises la table A. La transaction T1 peut rencontrer des données non mises à jour pour l'enregistrement qui a été mis à jour mais non validé par la transaction T2.

### Liste de paramètres

`conn_identifier`
  La connexion CUBRID. Si l'identifiant de connexion n'est pas spécifié, le dernier lien ouvert avec la fonction cubrid_connect() sera utilisé.

### Valeurs de retour

Un tableau associatif contenant les paramètres de la base de données CUBRID en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Modification de LOCK_TIMEOUT en PARAM_LOCK_TIMEOUT, de MAX_STRING_LENGTH en PARAM_MAX_STRING_LENGTH dans le résultat.

### Exemples

Exemple #1 Exemple avec cubrid_get_db_parameter()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

L'exemple ci-dessus va afficher :

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Voir aussi

- cubrid_set_db_parameter() - Définit les paramètres de base de données CUBRID
- cubrid_get_autocommit() - Récupère le mode auto-commit de la connexion

# cubrid_get_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_get_query_timeout — Récupère la valeur du délai d'attente maximal d'une requête

### Description

function cubrid_get_query_timeout(resource `$req_identifier`): int

La fonction cubrid_get_query_timeout() est utilisée pour récupérer le délai d'attente maximal d'une requête.

### Liste de paramètres

`req_identifier`
  Un identifiant de requête.

### Valeurs de retour

Retourne la valeur du délai d'attente maximal pour la requête en cas de succès, en millisecondes, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_get_query_timeout()

    <?php

    $host = "localhost";
    $port = 33000;
    $db = "demodb";

    $conn =
    cubrid_connect_with_url("CUBRID:$host:$port:$db:::?login_timeout=50000&query_timeout=5000&disconnect_on_query_timeout=yes");

    $req = cubrid_prepare($conn, "SELECT * FROM code");

    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_set_query_timeout($req, 1000);
    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_close($conn);
    ?>

L'exemple ci-dessus va afficher :

    int(5000)
    int(1000)

### Voir aussi

- cubrid_set_query_timeout() - Définit le délai maximal d'exécution d'une requête

# cubrid_get_server_info

(PECL CUBRID >= 8.3.0)

cubrid_get_server_info — Retourne la version du serveur CUBRID

### Description

function cubrid_get_server_info(resource `$conn_identifier`): string

Cette fonction retourne une chaîne de caractères représentant la version du serveur CUBRID.

### Liste de paramètres

`conn_identifier`
  L'identifiant de connexion CUBRID.

### Valeurs de retour

Une chaîne de caractères représentant la version du serveur CUBRID en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_get_server_info()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

L'exemple ci-dessus va afficher :

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

# cubrid_insert_id

(PECL CUBRID >= 8.3.0)

cubrid_insert_id — Retourne l'identifiant généré pour la dernière mise à jour de la colonne `AUTO_INCREMENT`

### Description

function cubrid_insert_id(resource `$conn_identifier` = ?): string

La fonction cubrid_insert_id() récupère l'identifiant généré pour la colonne AUTO_INCREMENT mise à jour par la précédente requête INSERT. Elle retourne 0 si la précédente requête ne génère pas de nouvelles lignes, ou `false` si une erreur survient.

> Note: CUBRID supporte AUTO_INCREMENT pour plus d'une colonne dans une table. Dans la plupart des cas, il n'y en a qu'une seule. S'il y en a plusieurs, cette fonction ne doit pas être utilisée y compris si elle retourne une valeur.

### Liste de paramètres

`conn_identifier`
  L'identifiant de connexion précédemment obtenu depuis un appel à la fonction cubrid_connect().

### Valeurs de retour

Une chaîne de caractères représentant l'identifiant généré pour la colonne AUTO_INCREMENT par la précédente requête en cas de succès.

0 si la précédente requête n'a généré aucune nouvelle ligne.

`false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Modification de la valeur retournée (d'un tableau vers une chaîne de caractères) ; Suppression du premier paramètre class_name.

### Exemples

Exemple #1 Exemple avec cubrid_insert_id()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d int AUTO_INCREMENT(1, 2), t varchar)");

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($conn, "INSERT INTO cubrid_test(t) VALUES('cubrid_test')");
    }

    $id = cubrid_insert_id();
    var_dump($id);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    string(2) "19"

# cubrid_is_instance

(PECL CUBRID >= 8.3.0)

cubrid_is_instance — Vérifie si une instance existe

### Description

function cubrid_is_instance(resource `$conn_identifier`, string `$oid`): int

La fonction cubrid_is_instance() est utilisée pour vérifier si l'instance pointée par l'`oid` fournie existe ou non.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance dont l'on veut vérifier l'existence.

### Valeurs de retour

1, si l'instance existe.

0, si l'instance n'existe pas.

-1, si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_is_instance()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT host_year, medal, game_date
    FROM game
    WHERE athlete_code IN
        (SELECT code FROM athlete WHERE name='Thorpe Ian');
    EOD;

    $req = cubrid_execute($conn, $sql, CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);

    $res = cubrid_is_instance ($conn, $oid);
    if ($res == 1) {
        echo "Instance pointed by $oid exists.\n";
    } else if ($res == 0){
        echo "Instance pointed by $oid doesn't exist.\n";
    } else {
        echo "error\n";
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Instance pointed by @0|0|0 doesn't exist.

### Voir aussi

- cubrid_drop() - Supprime une instance en utilisant son OID
- cubrid_get_class_name() - Récupère le nom de la classe en utilisant son OID

# cubrid_lob_close

(PECL CUBRID >= 8.3.1)

cubrid_lob_close — Ferme un BLOB/CLOB

### Description

function cubrid_lob_close(array `$lob_identifier_array`): bool

La fonction cubrid_lob_close() est utilisée pour fermer tous les BLOB/CLOB retournés depuis la fonction cubrid_lob_get().

### Liste de paramètres

`lob_identifier_array`
  Un tableau d'identifiants LOB retournés par la fonction cubrid_lob_get().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lob_close()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Doc size: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob_get() - Récupère les données BLOB/CLOB
- cubrid_lob_size() - Récupère la taille des données BLOB/CLOB
- cubrid_lob_export() - Exporte des données BLOB/CLOB vers un fichier
- cubrid_lob_send() - Lit les données BLOB/CLOB et les envoie au navigateur

# cubrid_lob_export

(PECL CUBRID >= 8.3.1)

cubrid_lob_export — Exporte des données BLOB/CLOB vers un fichier

### Description

function cubrid_lob_export(resource `$conn_identifier`, resource `$lob_identifier`, string `$path_name`): bool

La fonction cubrid_lob_export() est utilisée pour récupérer les données BLOB/CLOB depuis la base de données CUBRID, et sauvegarde leurs contenus dans un fichier. Pour utiliser cette fonction, il faut utiliser d'abord la fonction cubrid_lob_get() pour récupérer les informations des BLOB/CLOB depuis CUBRID.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`lob_identifier`
  Identifiant LOB.
`path_name`
  Chemin vers le fichier.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lob_export()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Doc size: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob_get() - Récupère les données BLOB/CLOB
- cubrid_lob_close() - Ferme un BLOB/CLOB
- cubrid_lob_size() - Récupère la taille des données BLOB/CLOB
- cubrid_lob_send() - Lit les données BLOB/CLOB et les envoie au navigateur

# cubrid_lob_get

(PECL CUBRID >= 8.3.1)

cubrid_lob_get — Récupère les données BLOB/CLOB

### Description

function cubrid_lob_get(resource `$conn_identifier`, string `$sql`): array

La fonction cubrid_lob_get() est utilisée pour récupérer les données d'informations méta BLOB/CLOB depuis la base de données CUBRID (CUBRID récupère les BLOB/CLOB en exécutant une requête SQL), et retourne tous les LOBs sous la forme d'un tableau de ressources. Il faut s'assurer que le SQL récupère uniquement une seule colonne et que le type de données est bien BLOB ou CLOB.

Il est important de noter que l'utilisation de la fonction cubrid_lob_close() libère les LOBs si on n'en a plus besoin.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`sql`
  Requête SQL à exécuter.

### Valeurs de retour

Retourne un tableau de ressources LOB en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lob_get()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Doc size: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob_close() - Ferme un BLOB/CLOB
- cubrid_lob_size() - Récupère la taille des données BLOB/CLOB
- cubrid_lob_export() - Exporte des données BLOB/CLOB vers un fichier
- cubrid_lob_send() - Lit les données BLOB/CLOB et les envoie au navigateur

# cubrid_lob_send

(PECL CUBRID >= 8.3.1)

cubrid_lob_send — Lit les données BLOB/CLOB et les envoie au navigateur

### Description

function cubrid_lob_send(resource `$conn_identifier`, resource `$lob_identifier`): bool

La fonction cubrid_lob_send() lit des données BLOB/CLOB et les passe au navigateur. Pour utiliser cette fonction, il faut utiliser d'abord la fonction cubrid_lob_get() pour récupérer les informations des BLOB/CLOB depuis CUBRID.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`lob_identifier`
  Identifiant LOB.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lob_send()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");

    cubrid_lob_send($conn, $lobs[0]);
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob_get() - Récupère les données BLOB/CLOB
- cubrid_lob_close() - Ferme un BLOB/CLOB
- cubrid_lob_size() - Récupère la taille des données BLOB/CLOB
- cubrid_lob_export() - Exporte des données BLOB/CLOB vers un fichier

# cubrid_lob_size

(PECL CUBRID >= 8.3.1)

cubrid_lob_size — Récupère la taille des données BLOB/CLOB

### Description

function cubrid_lob_size(resource `$lob_identifier`): string

La fonction cubrid_lob_size() est utilisée pour récupérer la taille des données BLOB/CLOB.

### Liste de paramètres

`lob_identifier`
  Identifiant LOB.

### Valeurs de retour

Une chaîne représentant la taille des données LOB, lorsque l'opération a réussi, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le type de la valeur retournée a changé. Avant, c'était un entier, maintenant, c'est une chaîne de caractères.

### Exemples

Exemple #1 Exemple avec cubrid_lob_size()

    <?php
    $lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
    echo "Taille de la documentation :".cubrid_lob_size($lobs[0]);
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    ?>

### Voir aussi

- cubrid_lob_get() - Récupère les données BLOB/CLOB
- cubrid_lob_close() - Ferme un BLOB/CLOB
- cubrid_lob_export() - Exporte des données BLOB/CLOB vers un fichier
- cubrid_lob_send() - Lit les données BLOB/CLOB et les envoie au navigateur

# cubrid_lob2_bind

(PECL CUBRID >= 8.4.1)

cubrid_lob2_bind — Lie un objet LOB ou une chaîne de caractères à un objet LOB comme paramètre d'une requête préparée

### Description

function cubrid_lob2_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

La fonction cubrid_lob2_bind() est utilisée pour lier des données BLOB/CLOB à un marqueur correspondant dans une requête SQL passée à la fonction cubrid_prepare(). Si le paramètre `bind_value_type` n'est pas fourni, la chaîne sera par défaut "BLOB". Mais si l'on utilise d'abord la fonction cubrid_lob2_new(), le paramètre `bind_value_type` deviendra cohérent avec le paramètre `type` dans la fonction cubrid_lob2_new().

### Liste de paramètres

`req_identifier`
  Identifiant de la requête, résultant de la fonction cubrid_prepare().
`bind_index`
  Position du paramètre lié. Commence à 1.
`bind_value`
  Valeur effective pour le liage.
`bind_value_type`
  Doit être "BLOB" ou "CLOB" et n'est pas sensible à la casse. S'il n'est pas fourni, la valeur par défaut sera "BLOB".

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lob2_bind()

    <?php
    // Table : test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");

    cubrid_bind($req,1, 3);

    $lob = cubrid_lob2_new($conn, 'CLOB');
    cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_bind($req, 1, 4);

    cubrid_lob2_bind($req, 2, 'CUBRID LOB2 TEST', 'CLOB');

    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob2_new() - Crée un nouvel objet LOB
- cubrid_lob2_close() - Ferme un objet LOB

# cubrid_lob2_close

(PECL CUBRID >= 8.4.1)

cubrid_lob2_close — Ferme un objet LOB

### Description

function cubrid_lob2_close(resource `$lob_identifier`): bool

La fonction cubrid_lob2_close() est utilisée pour fermer un objet LOB, retourné par la fonction cubrid_lob2_new() ou récupéré depuis le jeu de résultats.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, résultant de la fonction cubrid_lob2_new() ou récupéré depuis le jeu de résultats.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- cubrid_lob2_new() - Crée un nouvel objet LOB

# cubrid_lob2_export

(PECL CUBRID >= 8.4.1)

cubrid_lob2_export — Exporte un objet LOB vers un fichier

### Description

function cubrid_lob2_export(resource `$lob_identifier`, string `$file_name`): bool

La fonction cubrid_lob2_export() est utilisée pour sauvegarder les données BLOB/CLOB dans un fichier. Pour utiliser cette fonction, il faut tout d'abord utiliser la fonction cubrid_lob2_new() ou récupérer un objet LOB depuis la base de données CUBRID. Si le fichier existe déjà, l'opération échouera. Cette fonction ne modifiera pas la position du curseur de l'objet LOB. Elle opère sur l'objet LOB dans sa totalité.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB résultant de la fonction cubrid_lob2_new() ou récupéré depuis le jeu de résultats.
`filename`
  Nom du fichier dans lequel l'on souhaite enregistrer les données BLOB/CLOB. Le chemin vers le fichier peut également être spécifié.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lob2_export()

    <?php
    // Table : test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $req = cubrid_prepare($conn, "select * from doc");

    cubrid_execute($req);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);

    $row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);

    cubrid_lob2_export($row[1], "doc_3.txt");

    cubrid_lob2_close($row[1]);
    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob2_new() - Crée un nouvel objet LOB
- cubrid_lob2_close() - Ferme un objet LOB
- cubrid_lob2_import() - Importe des données BLOB/CLOB depuis un fichier
- cubrid_lob2_bind() - Lie un objet LOB ou une chaîne de caractères à un objet LOB comme paramètre d'une requête préparée

# cubrid_lob2_import

(PECL CUBRID >= 8.4.1)

cubrid_lob2_import — Importe des données BLOB/CLOB depuis un fichier

### Description

function cubrid_lob2_import(resource `$lob_identifier`, string `$file_name`): bool

La fonction cubrid_lob2_import() est utilisée pour importer des données BLOB/CLOB depuis un fichier. Pour utiliser cette fonction, il faut d'abord utiliser la fonction cubrid_lob2_new() ou récupérer un objet LOB depuis la base de données CUBRID. Si le fichier n'existe pas, l'opération échouera. Cette fonction n'impacte pas la position du curseur dans l'objet LOB ; elle opère sur l'objet LOB dans sa totalité.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, résultat de la fonction cubrid_lob2_new() ou récupéré depuis le jeu de résultats.
`filename`
  Le nom du fichier depuis lequel les données BLOB/CLOB doivent être importées. Le chemin vers le fichier est également supporté.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lob2_export()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // ou cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);
    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob2_new() - Crée un nouvel objet LOB
- cubrid_lob2_close() - Ferme un objet LOB
- cubrid_lob2_export() - Exporte un objet LOB vers un fichier
- cubrid_lob2_bind() - Lie un objet LOB ou une chaîne de caractères à un objet LOB comme paramètre d'une requête préparée

# cubrid_lob2_new

(PECL CUBRID >= 8.4.1)

cubrid_lob2_new — Crée un nouvel objet LOB

### Description

function cubrid_lob2_new(resource `$conn_identifier` = ?, string `$type` = "BLOB"): resource

La fonction cubrid_lob2_new() est utilisée pour créer un nouvel objet LOB (à la fois BLOB et CLOB). Cette fonction doit être utilisée avant de lier un objet LOB.

### Liste de paramètres

`conn_identifier`
  Un identifiant de connexion. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction cubrid_connect() ou la fonction cubrid_connect_with_url() sera utilisée.
`type`
  Peut être "BLOB" ou "CLOB", et n'est pas sensible à la casse. La valeur par défaut est "BLOB".

### Valeurs de retour

Un identifiant LOB en cas de succès, ou `false` si une erreur survient.

### Voir aussi

- cubrid_lob2_close() - Ferme un objet LOB

# cubrid_lob2_read

(PECL CUBRID >= 8.4.1)

cubrid_lob2_read — Lit des données BLOB/CLOB

### Description

function cubrid_lob2_read(resource `$lob_identifier`, int `$len`): string

La fonction cubrid_lob2_read() lit `len` octets depuis les données LOB, et retourne les octets lus.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, résultant de la fonction cubrid_lob2_new() ou récupéré depuis le jeu de résultats.
`len`
  Quantité de données à lire depuis les données LOB.

### Valeurs de retour

Retourne le contenu en tant que chaîne de caractères, `false` quand il n'y a plus de données, ou `null` si une erreur survient.

### Exemples

Exemple #1 Exemple 1 avec cubrid_lob2_read()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    print "position now is " . cubrid_lob2_tell($row[1]) . "\n";

    cubrid_lob2_seek($row[1], 10, CUBRID_CURSOR_FIRST);

    print "\nPosition après déplacement : " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 12);

    print "\nPosition après lecture : " . cubrid_lob2_tell($row[1]) . "\n";

    print $data . "\n";

    cubrid_lob2_seek($row[1], 5, CUBRID_CURSOR_CURRENT);

    print "\nPosition après un nouveau déplacement : " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 20);
    print $data . "\n";

    cubrid_disconnect($conn);
    ?>

Exemple #2 Exemple 2 avec cubrid_lob2_read()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    while (true) {
        if ($data = cubrid_lob2_read($row[1], 1024)) {
            print $data . "\n";
        }
        elseif ($data === false) {
            print "Il n'y a plus de données\n";
            break;
        }
        else {
            print "Une erreur est survenue\n";
            break;
        }
    }

    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob2_write() - Écrit dans un objet LOB
- cubrid_lob2_seek() - Déplace le curseur d'un objet LOB
- cubrid_lob2_seek64() - Déplace le curseur d'un objet LOB
- cubrid_lob2_tell() - Récupère la position du curseur dans un objet LOB
- cubrid_lob2_tell64() - Récupère la position du curseur dans l'objet LOB
- cubrid_lob2_size() - Récupère la taille d'un objet LOB
- cubrid_lob2_size64() - Récupère la taille d'un objet LOB

# cubrid_lob2_seek

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek — Déplace le curseur d'un objet LOB

### Description

function cubrid_lob2_seek(resource `$lob_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

La fonction cubrid_lob2_seek() est utilisée pour déplacer la position du curseur d'un objet LOB d'un pas spécifié par l'argument `offset`, et dans la direction spécifiée par l'argument `origin`.

Pour définir l'argument `origin`, il est possible d'utiliser la constante `CUBRID_CURSOR_FIRST` pour déplacer en avant la position du curseur de `offset` unités depuis le début. Dans ce cas, `offset` doit être une valeur positive.

Si l'on utilise la constante `CUBRID_CURSOR_CURRENT` pour le paramètre `origin`, il est possible de se déplacer en avant ou en arrière. L'argument `offset` peut être négatif ou positif.

Si l'on utilise la constante `CUBRID_CURSOR_LAST` pour le paramètre `origin`, il est possible de se déplacer en arrière de `offset` unités depuis la fin de l'objet LOB ; l'argument `offset` peut seulement être positif dans ce cas.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, résultant de la fonction cubrid_lob2_new() ou récupéré depuis le jeu de résultats.
`offset`
  Nombre d'unités à utiliser pour déplacer le curseur.
`origin`
  Ce paramètre peut prendre les valeurs suivantes : CUBRID_CURSOR_FIRST : Se déplace en avant depuis le début. CUBRID_CURSOR_CURRENT : Se déplace en avant ou en arrière, depuis la position courante. CUBRID_CURSOR_LAST : Se déplace en arrière depuis la fin de l'objet LOB.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lob2_seek()

    <?php
    // test_lob (id INT, contents CLOB)
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");
    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Hello world");

    cubrid_lob2_seek($lob, 0, CUBRID_CURSOR_LAST);
    cubrid_lob2_write($lob, "beautiful");

    cubrid_lob2_seek($lob, 15, CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 5);

    echo $data."\n";

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob2_read() - Lit des données BLOB/CLOB
- cubrid_lob2_write() - Écrit dans un objet LOB
- cubrid_lob2_seek64() - Déplace le curseur d'un objet LOB
- cubrid_lob2_tell() - Récupère la position du curseur dans un objet LOB
- cubrid_lob2_tell64() - Récupère la position du curseur dans l'objet LOB
- cubrid_lob2_size() - Récupère la taille d'un objet LOB
- cubrid_lob2_size64() - Récupère la taille d'un objet LOB

# cubrid_lob2_seek64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek64 — Déplace le curseur d'un objet LOB

### Description

function cubrid_lob2_seek64(resource `$lob_identifier`, string `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

La fonction cubrid_lob2_seek64() est utilisée pour déplacer la position du curseur dans un objet LOB d'une valeur fournie par le paramètre `offset`, dans la direction fournie par le paramètre `origin`. Si la position `offset` est plus grande que la capacité de stockage d'un entier, il est possible d'utiliser cette fonction.

Pour définir le paramètre `origin`, il est possible d'utiliser la constante `CUBRID_CURSOR_FIRST` pour définir la position du curseur à laquelle on ajoute `offset` unités depuis le début. Dans ce cas, `offset` doit être une valeur positive.

Si l'on utilise `CUBRID_CURSOR_CURRENT` pour le paramètre `origin`, il est possible de se déplacer vers l'arrière, comme vers l'avant. Et le paramètre `offset` pourra être positif ou négatif.

Si l'on utilise la constante `CUBRID_CURSOR_LAST` pour le paramètre `origin`, il est possible de se déplacer en arrière de `offset` unités depuis la fin de l'objet LOB et le paramètre `offset` ne pourra être que positif.

> Note: Si l'on utilise cette fonction pour déplacer la position du curseur d'un objet LOB, il est recommandé de passer le paramètre `offset` sous la forme d'une chaîne de caractères.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, récupéré depuis la fonction cubrid_lob2_new() ou depuis le jeu de résultats.
`offset`
  Nombre d'unités de déplacement du curseur.
`origin`
  Ce paramètre peut prendre les valeurs suivantes : CUBRID_CURSOR_FIRST : déplace le curseur vers l'avant en partant du début. CUBRID_CURSOR_CURRENT : déplace le curseur vers l'arrière et vers l'avant depuis la position courante. CUBRID_CURSOR_LAST : déplace le curseur vers l'arrière depuis la fin de l'objet LOB.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lob2_seek64()

    <?php
    // test_lob (id INT, contents CLOB)
    // La longueur des données de doc_1.txt doit être supérieure à 20101029056306120215.

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // or cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);

    $req = cubrid_execute($conn, "select * from test_lob");
    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob = $row[1];

    cubrid_lob2_seek64($lob, "20101029056306120215", CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 20);
    echo $data."\n";
    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob2_read() - Lit des données BLOB/CLOB
- cubrid_lob2_write() - Écrit dans un objet LOB
- cubrid_lob2_seek() - Déplace le curseur d'un objet LOB
- cubrid_lob2_tell() - Récupère la position du curseur dans un objet LOB
- cubrid_lob2_tell64() - Récupère la position du curseur dans l'objet LOB
- cubrid_lob2_size() - Récupère la taille d'un objet LOB
- cubrid_lob2_size64() - Récupère la taille d'un objet LOB

# cubrid_lob2_size

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size — Récupère la taille d'un objet LOB

### Description

function cubrid_lob2_size(resource `$lob_identifier`): int

La fonction cubrid_lob2_size() est utilisée pour récupérer la taille d'un objet LOB.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, récupéré depuis la fonction cubrid_lob2_new() ou depuis le jeu de résultats.

### Valeurs de retour

Retourne la taille de l'objet LOB en cas de succès, ou `false` si une erreur survient.

### Voir aussi

- cubrid_lob2_read() - Lit des données BLOB/CLOB
- cubrid_lob2_write() - Écrit dans un objet LOB
- cubrid_lob2_seek() - Déplace le curseur d'un objet LOB
- cubrid_lob2_seek64() - Déplace le curseur d'un objet LOB
- cubrid_lob2_tell() - Récupère la position du curseur dans un objet LOB
- cubrid_lob2_tell64() - Récupère la position du curseur dans l'objet LOB
- cubrid_lob2_size64() - Récupère la taille d'un objet LOB

# cubrid_lob2_size64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size64 — Récupère la taille d'un objet LOB

### Description

function cubrid_lob2_size64(resource `$lob_identifier`): string

La fonction cubrid_lob2_size64() est utilisée pour récupérer la taille d'un objet LOB. Si la taille de l'objet LOB est plus grande que la capacité de stockage d'un entier, il est possible d'utiliser cette fonction, et elle retournera la taille sous la forme d'une chaîne de caractères.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, récupéré depuis la fonction cubrid_lob2_new() ou depuis le jeu de résultats.

### Valeurs de retour

Retourne la taille d'un objet LOB sous la forme d'une chaîne de caractères en cas de succès, ou `false` si une erreur survient.

### Voir aussi

- cubrid_lob2_read() - Lit des données BLOB/CLOB
- cubrid_lob2_write() - Écrit dans un objet LOB
- cubrid_lob2_seek() - Déplace le curseur d'un objet LOB
- cubrid_lob2_seek64() - Déplace le curseur d'un objet LOB
- cubrid_lob2_tell() - Récupère la position du curseur dans un objet LOB
- cubrid_lob2_tell64() - Récupère la position du curseur dans l'objet LOB
- cubrid_lob2_size() - Récupère la taille d'un objet LOB

# cubrid_lob2_tell

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell — Récupère la position du curseur dans un objet LOB

### Description

function cubrid_lob2_tell(resource `$lob_identifier`): int

La fonction cubrid_lob2_tell() est utilisée pour récupérer la position du curseur dans l'objet LOB.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, récupéré depuis la fonction cubrid_lob2_new() ou depuis le jeu de résultats.

### Valeurs de retour

Retourne la position du curseur dans l'objet LOB en cas de succès, ou `false` si une erreur survient.

### Voir aussi

- cubrid_lob2_read() - Lit des données BLOB/CLOB
- cubrid_lob2_write() - Écrit dans un objet LOB
- cubrid_lob2_seek() - Déplace le curseur d'un objet LOB
- cubrid_lob2_seek64() - Déplace le curseur d'un objet LOB
- cubrid_lob2_tell64() - Récupère la position du curseur dans l'objet LOB
- cubrid_lob2_size() - Récupère la taille d'un objet LOB
- cubrid_lob2_size64() - Récupère la taille d'un objet LOB

# cubrid_lob2_tell64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell64 — Récupère la position du curseur dans l'objet LOB

### Description

function cubrid_lob2_tell64(resource `$lob_identifier`): string

La fonction cubrid_lob2_tell64() est utilisée pour récupérer la position du curseur dans l'objet LOB. Si la taille de l'objet LOB est plus grande que la capacité de stockage d'un entier, il est possible d'utiliser cette fonction et elle retournera l'information sous la forme d'une chaîne de caractères.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, récupéré depuis la fonction cubrid_lob2_new() ou depuis le jeu de résultats.

### Valeurs de retour

Retourne la position du curseur dans l'objet LOB, sous la forme d'une chaîne de caractères en cas de succès, ou `false` si une erreur survient.

### Voir aussi

- cubrid_lob2_read() - Lit des données BLOB/CLOB
- cubrid_lob2_write() - Écrit dans un objet LOB
- cubrid_lob2_seek() - Déplace le curseur d'un objet LOB
- cubrid_lob2_seek64() - Déplace le curseur d'un objet LOB
- cubrid_lob2_tell() - Récupère la position du curseur dans un objet LOB
- cubrid_lob2_size() - Récupère la taille d'un objet LOB
- cubrid_lob2_size64() - Récupère la taille d'un objet LOB

# cubrid_lob2_write

(PECL CUBRID >= 8.4.1)

cubrid_lob2_write — Écrit dans un objet LOB

### Description

function cubrid_lob2_write(resource `$lob_identifier`, string `$buf`): bool

La fonction cubrid_lob2_write() lit les données depuis le paramètre `buf` et les stocke dans l'objet LOB. Il est à noter que cette fonction ne peut ajouter actuellement que des caractères.

### Liste de paramètres

`lob_identifier`
  Un identifiant LOB, récupéré depuis la fonction cubrid_lob2_new() ou depuis le jeu de résultats.
`buf`
  Les données qui doivent être écrites dans l'objet LOB.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple 1 avec cubrid_lob2_write()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Hello world");

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

Exemple #2 Exemple 2 avec cubrid_lob2_write()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(1, ?)");
    $lob1 = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob1, "cubrid php driver");
    cubrid_lob2_bind($req, 1, $lob1);
    cubrid_execute($req);

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob2 = $row[1];
    cubrid_lob2_seek($lob2, 0, CUBRID_CURSOR_LAST);

    $pos = cubrid_lob2_tell($lob2);
    print "Position avant écriture : $pos\n";

    cubrid_lob2_write($lob2, "Hello world");

    $pos = cubrid_lob2_tell($lob2);
    print "Position après écriture : $pos\n";

    cubrid_disconnect($conn);
    ?>

### Voir aussi

- cubrid_lob2_read() - Lit des données BLOB/CLOB
- cubrid_lob2_seek() - Déplace le curseur d'un objet LOB
- cubrid_lob2_seek64() - Déplace le curseur d'un objet LOB
- cubrid_lob2_tell() - Récupère la position du curseur dans un objet LOB
- cubrid_lob2_tell64() - Récupère la position du curseur dans l'objet LOB
- cubrid_lob2_size() - Récupère la taille d'un objet LOB
- cubrid_lob2_size64() - Récupère la taille d'un objet LOB

# cubrid_lock_read

(PECL CUBRID >= 8.3.0)

cubrid_lock_read — Place un verrou de lecture sur l'OID fourni

### Description

function cubrid_lock_read(resource `$conn_identifier`, string `$oid`): bool

La fonction cubrid_lock_read() est utilisée pour placer un verrou de lecture sur l'instance pointée par l'`oid` fournie.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance dont l'on veut verrouiller la lecture.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lock_read()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_read($conn, $oid);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Voir aussi

- cubrid_lock_write() - Place un verrou d'écriture sur l'OID fourni

# cubrid_lock_write

(PECL CUBRID >= 8.3.0)

cubrid_lock_write — Place un verrou d'écriture sur l'OID fourni

### Description

function cubrid_lock_write(resource `$conn_identifier`, string `$oid`): bool

La fonction cubrid_lock_write() est utilisée pour placer un verrou d'écriture sur l'instance pointée par l'`oid` fournie.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance sur laquelle placer un verrou d'écriture.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_lock_write()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_write($conn, $oid);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Voir aussi

- cubrid_lock_read() - Place un verrou de lecture sur l'OID fourni

# cubrid_move_cursor

(PECL CUBRID >= 8.3.0)

cubrid_move_cursor — Déplace le curseur dans le résultat

### Description

function cubrid_move_cursor(resource `$req_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

La fonction cubrid_move_cursor() est utilisée pour déplacer le curseur courant suivant le paramètre `req_identifier` de la valeur du paramètre `offset` et dans la direction définie par le paramètre `origin`. Pour définir le paramètre `origin`, il est possible d'utiliser `CUBRID_CURSOR_FIRST` pour la première partie du résultat, `CUBRID_CURSOR_CURRENT` pour la position courante du résultat, ou `CUBRID_CURSOR_LAST` pour la dernière partie du résultat. Si l'argument `origin` n'est pas explicitement désigné, alors la fonction utilisera `CUBRID_CURSOR_CURRENT` comme valeur par défaut.

Si la valeur courante du déplacement du curseur est au-delà des limites valides, alors le curseur se déplace à la prochaine position après l'intervalle valide du curseur. Par exemple, si on le déplace de 20 unités dans le résultat dont la taille est de 10, alors le curseur se place sur la 11ème place et retournera `CUBRID_NO_MORE_DATA`.

### Liste de paramètres

`req_identifier`
  Identifiant de requête.
`offset`
  Nombre d'unités que l'on veut utiliser pour le déplacement.
`origin`
  Cible où l'on veut déplacer le curseur, soit `CUBRID_CURSOR_FIRST`, `CUBRID_CURSOR_CURRENT`, `CUBRID_CURSOR_LAST`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_move_cursor()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_move_cursor($req, 1, CUBRID_CURSOR_LAST);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_CURRENT);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(2) {
      [0]=>
      string(1) "G"
      [1]=>
      string(4) "Gold"
    }
    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée

# cubrid_next_result

(PECL CUBRID >= 8.4.0)

cubrid_next_result — Récupère le résultat de la prochaine requête lors de l'exécution de requêtes SQL multiples

### Description

function cubrid_next_result(resource `$result`): bool

La fonction cubrid_next_result() est utilisée pour récupérer les résultats de la prochaine requête si plusieurs requêtes SQL sont exécutées et que le drapeau `CUBRID_EXEC_QUERY_ALL` est défini lors de l'utilisation de la fonction cubrid_execute().

### Liste de paramètres

`result`
  Le paramètre `result` provient de l'appel à la fonction cubrid_execute()

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_next_result()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $sql_stmt = "SELECT * FROM code; SELECT * FROM history WHERE host_year=2004 AND event_code=20281";
    $res = cubrid_execute($conn, $sql_stmt, CUBRID_EXEC_QUERY_ALL);

    get_result_info($res);
    cubrid_next_result($res);
    get_result_info($res);

    function get_result_info($req)
    {
        printf("\n------------ get_result_info --------------------\n");

        $row_num = cubrid_num_rows($req);
        $col_num = cubrid_num_cols($req);

        $column_name_list = cubrid_column_names($req);
        $column_type_list = cubrid_column_types($req);

        $column_last_name = cubrid_field_name($req, $col_num - 1);
        $column_last_table = cubrid_field_table($req, $col_num - 1);

        $column_last_type = cubrid_field_type($req, $col_num - 1);
        $column_last_len = cubrid_field_len($req, $col_num - 1);

        $column_1_flags = cubrid_field_flags($req, 1);

        printf("%-30s %d\n", "Row count:", $row_num);
        printf("%-30s %d\n", "Column count:", $col_num);
        printf("\n");

        printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Len");
        printf("------------------------------------------------------------------------------\n");

        $size = count($column_name_list);
        for($i = 0; $i < $size; $i++) {
            $column_len = cubrid_field_len($req, $i);
            printf("%-30s %-30s %-15s\n", $column_name_list[$i], $column_type_list[$i], $column_len);
        }
        printf("\n\n");

        printf("%-30s %s\n", "Last Column Name:", $column_last_name);
        printf("%-30s %s\n", "Last Column Table:", $column_last_table);
        printf("%-30s %s\n", "Last Column Type:", $column_last_type);
        printf("%-30s %d\n", "Last Column Len:", $column_last_len);
        printf("%-30s %s\n", "Second Column Flags:", $column_1_flags);

        printf("\n\n");
    }
    ?>

L'exemple ci-dessus va afficher :

    ------------ get_result_info --------------------
    Row count:                     6
    Column count:                  2

    Column Names                   Column Types                   Column Len
    ------------------------------------------------------------------------------
    s_name                         char                           1
    f_name                         varchar                        6

    Last Column Name:              f_name
    Last Column Table:             code
    Last Column Type:              varchar
    Last Column Len:               6
    Second Column Flags:

    ------------ get_result_info --------------------
    Row count:                     4
    Column count:                  5

    Column Names                   Column Types                   Column Len
    ------------------------------------------------------------------------------
    event_code                     integer                        11
    athlete                        varchar                        40
    host_year                      integer                        11
    score                          varchar                        10
    unit                           varchar                        5

    Last Column Name:              unit
    Last Column Table:             history
    Last Column Type:              varchar
    Last Column Len:               5
    Second Column Flags:           not_null primary_key unique_key

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée

# cubrid_num_cols

(PECL CUBRID >= 8.3.0)

cubrid_num_cols — Récupère le nombre de colonnes du jeu de résultats

### Description

function cubrid_num_cols(resource `$result`): int

La fonction cubrid_num_cols() est utilisée pour récupérer le nombre de colonnes depuis le résultat de la requête. Elle ne peut être utilisée que lorsque la requête est de type `SELECT`.

### Liste de paramètres

`result`
  Le résultat.

### Valeurs de retour

Nombre de colonnes en cas de succès.

`false`, si la requête SQL n'est pas de type SELECT.

### Exemples

Exemple #1 Exemple avec cubrid_num_cols()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Row Num: 6
    Column Num: 2

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_num_rows() - Récupère le nombre de lignes d'un jeu de résultats

# cubrid_num_rows

(PECL CUBRID >= 8.3.0)

cubrid_num_rows — Récupère le nombre de lignes d'un jeu de résultats

### Description

function cubrid_num_rows(resource `$result`): int

La fonction cubrid_num_rows() est utilisée pour récupérer le nombre de lignes depuis le jeu de résultats. L'on ne peut l'utiliser que lorsque la requête est de type `SELECT`. Lorsque l'on veut savoir ce type de valeur pour une requête de type `INSERT`, `UPDATE` ou `DELETE`, il faut utiliser la fonction cubrid_affected_rows().

Note : La fonction cubrid_num_rows() ne peut être utilisée que sur les requêtes synchrones ; elle retourne 0 sur des requêtes asynchrones.

### Liste de paramètres

`result`
  Le paramètre `result` provient d'un appel à la fonction cubrid_execute(), la fonction cubrid_query() ou la fonction cubrid_prepare().

### Valeurs de retour

Nombre de lignes en cas de succès.

0 lorsque la requête a été effectuée en mode asynchrone.

-1, si la requête SQL n'est pas de type SELECT.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_num_rows()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Row Num: 6
    Column Num: 2

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_num_cols() - Récupère le nombre de colonnes du jeu de résultats
- cubrid_affected_rows() - Récupère le nombre de lignes affectées par la dernière requête SQL

# cubrid_pconnect

(PECL CUBRID >= 8.3.1)

cubrid_pconnect — Ouvre une connexion persistante vers un serveur CUBRID

### Description

function cubrid_pconnect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?
): resource

Établit une connexion persistante vers un serveur CUBRID.

cubrid_pconnect() agit de la même façon que cubrid_connect() avec deux différences majeures.

Tout d'abord, lors de la connexion, la fonction tentera d'abord de trouver un lien (persistant) déjà ouvert avec le même nom d'hôte, sur le même port, utilisant la même base de données dbname ainsi que le même userid. Si un tel lien est trouvé, son identifiant sera retourné au lieu d'ouvrir une nouvelle connexion.

Ensuite, la connexion vers le serveur SQL ne sera pas fermée lorsque la fin du script est atteinte. Au lieu de cela, le lien restera ouvert pour une utilisation future (cubrid_close() ou cubrid_disconnect() ne fermera pas les liens établis avec cubrid_pconnect()).

Ce type de lien est donc appelé 'persistant'.

### Liste de paramètres

`host`
  Nom de l'hôte ou adresse IP du serveur CUBRID CAS.
`port`
  Numéro du port du serveur CUBRID CAS (BROKER_PORT configuré dans $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Nom de la base de données.
`userid`
  Nom d'utilisateur pour la base de données.
`passwd`
  Mot de passe à associer avec le nom d'utilisateur.

### Valeurs de retour

Identifiant de connexion en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_pconnect()

    <?php
    printf("%-30s %s\n", "version de CUBRID PHP :", cubrid_version());

    printf("\n");

    $conn = cubrid_pconnect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Erreur de connexion ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Infos Server :", $server_info);
    printf("%-30s %s\n", "Infos Client:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Jeux de caractères CUBRID :", $charset);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Voir aussi

- cubrid_connect() - Ouvre une connexion au serveur CUBRID
- cubrid_connect_with_url() - Établit l'environnement pour une connexion au serveur CUBRID
- cubrid_pconnect_with_url() - Ouvre une connexion persistante vers un serveur CUBRID
- cubrid_disconnect() - Ferme la connexion à la base de données
- cubrid_close() - Ferme une connexion CUBRID

# cubrid_pconnect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_pconnect_with_url — Ouvre une connexion persistante vers un serveur CUBRID

### Description

function cubrid_pconnect_with_url(string `$conn_url`, string `$userid` = ?, string `$passwd` = ?): resource

Établit une connexion persistante vers un serveur CUBRID.

cubrid_pconnect_with_url() agit de la même façon que la fonction cubrid_connect_with_url(), avec deux différences majeures.

Tout d'abord, lors de la connexion, la fonction tentera tout d'abord de trouver un lien (persistant) déjà ouvert avec le même hôte, sur le même port, sur la même base de données dbname et utilisant le même userid. Si une telle connexion est trouvée, son identifiant sera retourné au lieu d'ouvrir une nouvelle connexion.

Ensuite, la connexion vers le serveur SQL ne sera pas fermée lorsque la fin du script sera atteinte. Au lieu de cela, la connexion restera ouverte pour une utilisation future (la fonction cubrid_close() ou la fonction cubrid_disconnect() ne fermera pas la connexion établie par la fonction cubrid_pconnect_with_url()).

Ce type de lien était appelé, auparavant, 'persistant'.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : Un nom d'hôte ou une adresse IP du serveur maître de base de données
- db_name : Un nom de base de données
- db_user : Un nom d'utilisateur de la base de données
- db_password : Un mot de passe pour l'utilisateur de la base de données
- alhosts : Spécifie l'information du broker du serveur, qui sera utilisé comme point de sortie lorsqu'il est impossible de se connecter au serveur actif. Il est possible de spécifier plusieurs brokers dans ce cas, et la connexion aux brokers sera tentée dans l'ordre de la configuration alhosts
- rctime : Un intervalle de temps à attendre avant de tenter une connexion vers un broker lorsqu'une erreur survient. Après qu'une erreur soit survenue, le système tentera une connexion vers un broker spécifié par althosts, termine la transaction, et ensuite, tente de se connecter au broker actif du serveur maître de base de données. La valeur par défaut est de 600 secondes.
- login_timeout : Valeur du délai maximal d'attente (unité : milliseconde) pour l'identification à la base de données. Par défaut, cette valeur vaut 0, ce qui signifie que l'on attend indéfiniment.
- query_timeout : Valeur du délai maximal d'attente (unité : milliseconde) pour l'exécution de la requête. Une fois cette valeur atteinte, un message pour annuler la requête envoyée au serveur est envoyé. La valeur retournée peut dépendre de la configuration de disconnect_on_query_timeout ; même si le message pour annuler la requête a été envoyé au serveur, la requête peut réussir.
- disconnect_on_query_timeout : Configure une valeur déterminant si l'on doit retourner immédiatement une erreur pour les fonctions exécutées après le délai maximal d'attente. La valeur par défaut est `false`.

> Note: Les caractères `?` et `:` utilisés comme identifiants dans les URLs de connexion PHP ne peuvent être inclus dans le mot de passe. Voici un exemple de mot de passe invalide, car utilisant les caractères "`?:`" dans l'URL de connexion. $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Les mots de passe contenant le caractère `?` ou le caractère `:` peuvent être passés en tant que paramètre séparé. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_pconnect_with_url ($url, "dba", "12?"); Si le nom d'utilisateur ou le mot de passe est vide, l'on ne doit pas supprimer les "`:`" ; voici un exemple : $url = "CUBRID:localhost:33000:demodb:::";

### Liste de paramètres

`conn_url`
  Une chaîne de caractères qui contient les informations de connexion pour le serveur.
`userid`
  Nom d'utilisateur pour la base de données.
`passwd`
  Mot de passe pour l'utilisateur.

### Valeurs de retour

Identifiant de connexion, lorsque le processus réussit, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_pconnect_with_url() sans propriétés

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
       echo "Connexion réussie";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_disconnect ($con);
    }
    ?>

Exemple #2 Exemple avec cubrid_pconnect_with_url() et des propriétés dans l'URL

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?althost=10.34.63.132:33088&rctime=100";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
       echo "Connexion réussie";
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_disconnect ($con);
    }
    ?>

### Voir aussi

- cubrid_connect() - Ouvre une connexion au serveur CUBRID
- cubrid_connect_with_url() - Établit l'environnement pour une connexion au serveur CUBRID
- cubrid_pconnect() - Ouvre une connexion persistante vers un serveur CUBRID
- cubrid_disconnect() - Ferme la connexion à la base de données
- cubrid_close() - Ferme une connexion CUBRID

# cubrid_prepare

(PECL CUBRID >= 8.3.0)

cubrid_prepare — Prépare une requête SQL pour son exécution

### Description

function cubrid_prepare(resource `$conn_identifier`, string `$prepare_stmt`, int `$option` = 0): resource

La fonction cubrid_prepare() compile une requête SQL pour un gestionnaire de connexion donné et retourne un gestionnaire qui représente la requête pré-compilée.

Une requête préparée peut être exécutée plusieurs fois, ce qui est efficace pour une exécution répétée ou pour traiter de gros volumes de données. Une seule requête peut être utilisée, et un paramètre peut être marqué par un point d'interrogation (`?`) à l'emplacement approprié dans la requête SQL. Un paramètre est ajouté lors de la liaison d'une valeur dans la clause `VALUES` d'une instruction `INSERT` ou dans la clause `WHERE`. Il est à noter qu'une valeur ne peut être liée à un paramètre qu'en utilisant la fonction cubrid_bind().

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`prepare_stmt`
  Requête préparée.
`option`
  OID retourné par l'option `CUBRID_INCLUDE_OID`.

### Valeurs de retour

Identifiant de requête en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_prepare()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT g.event_code, e.name
    FROM game g
    JOIN event e ON g.event_code=e.code
    WHERE host_year = ? AND event_code NOT IN (SELECT event_code FROM game WHERE host_year=?) GROUP BY event_code;
    EOD;

    $req = cubrid_prepare($conn, $sql);

    cubrid_bind($req, 1, 2004);
    cubrid_bind($req, 2, 2000);
    cubrid_execute($req);

    $row_num = cubrid_num_rows($req);
    printf("There are %d event that exits in 2004 olympic but not in 2000. For example:\n\n", $row_num);

    printf("%-15s %s\n", "Event_code", "Event_name");
    printf("----------------------------\n");

    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);
    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    There are 27 event that exits in 2004 olympic but not in 2000. For example:

    Event_code      Event_name
    ----------------------------
    20063           +91kg
    20070           64kg

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_bind() - Lie des valeurs à une requête préparée

# cubrid_put

(PECL CUBRID >= 8.3.0)

cubrid_put — Met à jour une colonne suivant son OID

### Description

function cubrid_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr` = ?,
mixed `$value`
): bool

La fonction cubrid_put() est utilisée pour mettre à jour un attribut de l'instance pointée par l'`oid` fournie.

Il est possible de mettre à jour un seul attribut en utilisant une chaîne de caractères dans le paramètre `attr`. Dans ce cas, il est possible d'utiliser un entier, un nombre à virgule flottante, ou une chaîne de caractères comme `value`. Pour mettre à jour plusieurs attributs, il faut ignorer le paramètre `attr` et définir l'argument `value` en utilisant un tableau associatif.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance que l'on veut mettre à jour.
`attr`
  Nom de l'attribut que l'on veut mettre à jour.
`value`
  Nouvelle valeur que l'on veut assigner à l'attribut.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_put()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Voir aussi

- cubrid_get() - Récupère une colonne en utilisant son OID
- cubrid_set_add() - Insère un seul élément pour définir le type d'une colonne
- cubrid_set_drop() - Supprime un élément
- cubrid_seq_insert() - Insère un élément dans une séquence
- cubrid_seq_drop() - Supprime un élément d'une séquence
- cubrid_seq_put() - Met à jour la valeur d'un élément d'une séquence

# cubrid_rollback

(PECL CUBRID >= 8.3.0)

cubrid_rollback — Annule une transaction

### Description

function cubrid_rollback(resource `$conn_identifier`): bool

La fonction cubrid_rollback() annule la transaction en cours pointée par le paramètre `conn_identifier`.

La connexion au serveur est fermée après l'appel à la fonction cubrid_rollback(). Cependant, le gestionnaire de connexion reste actif.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_rollback()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");
    cubrid_set_autocommit($conn,false);

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;

    if (!cubrid_execute($conn, $sql)) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Voir aussi

- cubrid_commit() - Valide une transaction
- cubrid_disconnect() - Ferme la connexion à la base de données

# cubrid_schema

(PECL CUBRID >= 8.3.0)

cubrid_schema — Récupère des informations sur un schéma

### Description

function cubrid_schema(
resource `$conn_identifier`,
int `$schema_type`,
string `$class_name` = ?,
string `$attr_name` = ?
): array

La fonction cubrid_schema() est utilisée pour récupérer des informations d'un schéma depuis la base de données. Pour récupérer les informations d'une classe particulière, il faut définir `class_name`, pour récupérer les informations sur un attribut particulier (seulement utilisable avec `CUBRID_SCH_ATTR_PRIVILEGE`), il faut définir `attr_name`.

Le résultat de la fonction cubrid_schema() est retourné sous la forme d'un tableau à 2 dimensions (colonne (tableau associatif) * lignes (tableau numérique)). Les tables suivantes montrent les types d'un schéma ainsi que la structure d'une colonne du tableau résultant, suivant le type de schéma demandé.

Composition du résultat pour chaque type
Schéma | Numéro de colonne | Nom de la colonne | Valeur
--- | --- | --- | ---
CUBRID_SCH_CLASS | 1 | NAME |
| 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_VCLASS | 1 | NAME |
| 2 | TYPE | 1:vclass
CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
CUBRID_SCH_ATTRIBUTE / CUBRID_SCH_CLASS_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexed
| 6 | NOT NULL | 1:not null
| 7 | SHARED | 1:shared
| 8 | UNIQUE | 1:unique
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:key
CUBRID_SCH_METHOD / CUBRID_SCH_CLASS_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
CUBRID_SCH_SUPERCLASS / CUBRID_SCH_DIRECT_SUPER_CLASS / CUBRID_SCH_SUBCLASS | 1 | CLASS_NAME |
| 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:primary key
| 7 | KEY_ORDER | base:1
CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
CUBRID_SCH_CLASS_PRIVILEGE / CUBRID_SCH_ATTR_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
CUBRID_SCH_IMPORTED_KEYS / CUBRID_SCH_EXPORTED_KEYS / CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 8 | FK_NAME |
| 9 | PK_NAME |

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`schema_type`
  Données du schéma à récupérer.
`class_name`
  Classe pour laquelle l'on souhaite connaître le schéma.
`attr_name`
  Attribut pour lequel l'on souhaite connaître le schéma.

### Valeurs de retour

Un tableau contenant les informations sur le schéma en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.3.1 | Modification de la valeur retournée : lorsque la fonction échoue, la valeur retournée est maintenant `false` au lieu de -1.

### Exemples

Exemple #1 Exemple avec cubrid_schema()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    printf("\n--- Primary Key ---\n");
    $pk = cubrid_schema($conn, CUBRID_SCH_PRIMARY_KEY, "game");
    var_dump($pk);

    printf("\n--- Foreign Keys ---\n");
    $fk = cubrid_schema($conn, CUBRID_SCH_IMPORTED_KEYS, "game");
    var_dump($fk);

    printf("\n--- Column Attribute ---\n");
    $attr = cubrid_schema($conn, CUBRID_SCH_ATTRIBUTE, "stadium", "area");
    var_dump($attr);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    --- Primary Key ---
    array(3) {
      [0]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "3"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [1]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "2"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [2]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(9) "host_year"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
    }

    --- Foreign Keys ---
    array(2) {
      [0]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(7) "athlete"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(20) "fk_game_athlete_code"
        ["PK_NAME"]=>
        string(15) "pk_athlete_code"
      }
      [1]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(5) "event"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(18) "fk_game_event_code"
        ["PK_NAME"]=>
        string(13) "pk_event_code"
      }
    }

    --- Column Attribute ---
    array(1) {
      [0]=>
      array(13) {
        ["ATTR_NAME"]=>
        string(4) "area"
        ["DOMAIN"]=>
        string(1) "7"
        ["SCALE"]=>
        string(1) "2"
        ["PRECISION"]=>
        string(2) "10"
        ["INDEXED"]=>
        string(1) "0"
        ["NON_NULL"]=>
        string(1) "0"
        ["SHARED"]=>
        string(1) "0"
        ["UNIQUE"]=>
        string(1) "0"
        ["DEFAULT"]=>
        NULL
        ["ATTR_ORDER"]=>
        string(1) "4"
        ["CLASS_NAME"]=>
        string(7) "stadium"
        ["SOURCE_CLASS"]=>
        string(7) "stadium"
        ["IS_KEY"]=>
        string(1) "0"
      }
    }

# cubrid_seq_drop

(PECL CUBRID >= 8.3.0)

cubrid_seq_drop — Supprime un élément d'une séquence

### Description

function cubrid_seq_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`
): bool

La fonction cubrid_seq_drop() est utilisée pour supprimer un élément de la base de données en se basant sur la séquence de types d'attributs fournie.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance à utiliser.
`attr_name`
  Nom de l'attribut depuis lequel l'élément doit être supprimé.
`index`
  Index de l'élément à supprimer (en commençant à 1).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_seq_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_drop($conn, $oid, "c", 4);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(3) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
    }

### Voir aussi

- cubrid_seq_insert() - Insère un élément dans une séquence
- cubrid_seq_put() - Met à jour la valeur d'un élément d'une séquence

# cubrid_seq_insert

(PECL CUBRID >= 8.3.0)

cubrid_seq_insert — Insère un élément dans une séquence

### Description

function cubrid_seq_insert(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

La fonction cubrid_seq_insert() est utilisée pour insérer un élément dans une séquence de types d'attributs.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance à utiliser.
`attr_name`
  Nom de l'attribut à insérer.
`index`
  Position de l'élément pour son insertion (en commençant à 1).
`seq_element`
  Contenu de l'élément à insérer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_seq_insert()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_insert($conn, $oid, "c", 5, "44");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(5) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
      [4]=>
      string(2) "44"
    }

### Voir aussi

- cubrid_seq_drop() - Supprime un élément d'une séquence
- cubrid_seq_put() - Met à jour la valeur d'un élément d'une séquence

# cubrid_seq_put

(PECL CUBRID >= 8.3.0)

cubrid_seq_put — Met à jour la valeur d'un élément d'une séquence

### Description

function cubrid_seq_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

La fonction cubrid_seq_put() est utilisée pour mettre à jour le contenu d'un élément dans une séquence de types d'attributs.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance à utiliser.
`attr_name`
  Nom de l'attribut à utiliser.
`index`
  Index (en commençant à 1) de l'élément à mettre à jour.
`seq_element`
  Nouveau contenu à placer dans l'élément.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_seq_put()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_put($conn, $oid, "c", 1, "111");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(4) {
      [0]=>
      string(3) "111"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }

### Voir aussi

- cubrid_seq_drop() - Supprime un élément d'une séquence
- cubrid_seq_insert() - Insère un élément dans une séquence

# cubrid_set_add

(PECL CUBRID >= 8.3.0)

cubrid_set_add — Insère un seul élément pour définir le type d'une colonne

### Description

function cubrid_set_add(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

La fonction cubrid_set_add() est utilisée pour insérer un seul élément dans un jeu de types d'attributs.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance à utiliser.
`attr_name`
  Nom de l'attribut dans lequel le nouvel élément sera inséré.
`set_element`
  Contenu de l'élément à insérer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_set_add()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_add($conn, $oid, "b", "4");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(4) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
      [3]=>
      string(1) "4"
    }

### Voir aussi

- cubrid_seq_drop() - Supprime un élément d'une séquence

# cubrid_set_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_set_autocommit — Définit le mode auto-commit pour la connexion

### Description

function cubrid_set_autocommit(resource `$conn_identifier`, bool `$mode`): bool

La fonction cubrid_set_autocommit() est utilisée pour définir le mode auto-commit pour la connexion à la base de données CUBRID.

En CUBRID PHP, le mode auto-commit est désactivé par défaut pour la gestion des transactions. Lorsque le mode auto-commit passe d'Off à On, tous les travaux en attente sont automatiquement validés.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`mode`
  Le mode auto-commit. Les constantes suivantes peuvent être utilisées :
  - `CUBRID_AUTOCOMMIT_FALSE`
  - `CUBRID_AUTOCOMMIT_TRUE`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- cubrid_get_autocommit() - Récupère le mode auto-commit de la connexion
- cubrid_commit() - Valide une transaction

# cubrid_set_db_parameter

(PECL CUBRID >= 8.4.0)

cubrid_set_db_parameter — Définit les paramètres de base de données CUBRID

### Description

function cubrid_set_db_parameter(resource `$conn_identifier`, int `$param_type`, int `$param_value`): bool

La fonction cubrid_set_db_parameter() est utilisée pour définir les paramètres de base de données CUBRID. Elle peut définir les paramètres de base de données CUBRID suivants :

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`

> Note: Le mode auto-commit peut être défini en utilisant la fonction cubrid_set_autocommit().

### Liste de paramètres

`conn_identifier`
  La connexion CUBRID. Si l'identifiant de connexion n'est pas spécifié, le dernier lien ouvert par la fonction cubrid_connect() sera utilisé.
`param_type`
  Type de paramètre de la base de données.
`param_value`
  Niveau d'isolation (1-6) ou la valeur du délai d'expiration (en secondes).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_get_db_parameter()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $params = cubrid_get_db_parameter($conn);
    var_dump($params);

    cubrid_set_autocommit($conn, CUBRID_AUTOCOMMIT_TRUE);
    cubrid_set_db_parameter($conn, CUBRID_PARAM_ISOLATION_LEVEL, 2);

    $params_new = cubrid_get_db_parameter($conn);
    var_dump($params_new);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(3)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(0)
    }
    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(2)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(1)
    }

### Voir aussi

- cubrid_get_db_parameter() - Retourne les paramètres de la base de données CUBRID
- cubrid_set_autocommit() - Définit le mode auto-commit pour la connexion

# cubrid_set_drop

(PECL CUBRID >= 8.3.0)

cubrid_set_drop — Supprime un élément

### Description

function cubrid_set_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

La fonction cubrid_set_drop() est utilisée pour supprimer un élément depuis un attribut donné de la base de données.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  OID de l'instance à utiliser.
`attr_name`
  Nom de l'attribut depuis lequel l'élément sera supprimé.
`set_element`
  Contenu de l'élément à supprimer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_set_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_drop($conn, $oid, "b", "1");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(2) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "3"
    }

### Voir aussi

- cubrid_set_add() - Insère un seul élément pour définir le type d'une colonne

# cubrid_set_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_set_query_timeout — Définit le délai maximal d'exécution d'une requête

### Description

function cubrid_set_query_timeout(resource `$req_identifier`, int `$timeout`): bool

La fonction cubrid_set_query_timeout() est utilisée pour définir le délai maximal d'exécution d'une requête.

### Liste de paramètres

`req_identifier`
  Identifiant de requête.
`timeout`
  Délai maximal, en millisecondes.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- cubrid_get_query_timeout() - Récupère la valeur du délai d'attente maximal d'une requête

# cubrid_version

(PECL CUBRID >= 8.3.0)

cubrid_version — Récupère la version du module PHP CUBRID

### Description

function cubrid_version(): string

La fonction cubrid_version() est utilisée pour récupérer la version du module PHP CUBRID.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Information sur la version (c.-à-d. "8.3.1.0001").

### Exemples

Exemple #1 Exemple avec cubrid_version()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb", "dba");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

L'exemple ci-dessus va afficher :

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Voir aussi

- cubrid_error_code() - Récupère le code erreur de la dernière erreur survenue
- cubrid_error_code_facility() - Récupère le niveau du code erreur

## Sommaire

- cubrid_bind — Lie des valeurs à une requête préparée
- cubrid_close_prepare — Ferme le gestionnaire de requête
- cubrid_close_request — Ferme le gestionnaire de requête
- cubrid_col_get — Récupère le contenu des éléments d'un type de collection en utilisant l'OID
- cubrid_col_size — Récupère le nombre d'éléments dans un type de colonne d'une collection en utilisant l'OID
- cubrid_column_names — Récupère les noms de colonnes du résultat
- cubrid_column_types — Récupère les types de colonnes du résultat
- cubrid_commit — Valide une transaction
- cubrid_connect — Ouvre une connexion au serveur CUBRID
- cubrid_connect_with_url — Établit l'environnement pour une connexion au serveur CUBRID
- cubrid_current_oid — Récupère l'OID de la localisation du curseur courant
- cubrid_disconnect — Ferme la connexion à la base de données
- cubrid_drop — Supprime une instance en utilisant son OID
- cubrid_error_code — Récupère le code erreur de la dernière erreur survenue
- cubrid_error_code_facility — Récupère le niveau du code erreur
- cubrid_error_msg — Récupère le message d'erreur de la dernière erreur survenue
- cubrid_execute — Exécute une requête SQL préparée
- cubrid_fetch — Récupère la prochaine ligne du jeu de résultats
- cubrid_free_result — Libère la mémoire occupée par les données de résultat
- cubrid_get — Récupère une colonne en utilisant son OID
- cubrid_get_autocommit — Récupère le mode auto-commit de la connexion
- cubrid_get_charset — Retourne le jeu de caractères utilisé sur la connexion CUBRID courante
- cubrid_get_class_name — Récupère le nom de la classe en utilisant son OID
- cubrid_get_client_info — Retourne la version de la bibliothèque cliente
- cubrid_get_db_parameter — Retourne les paramètres de la base de données CUBRID
- cubrid_get_query_timeout — Récupère la valeur du délai d'attente maximal d'une requête
- cubrid_get_server_info — Retourne la version du serveur CUBRID
- cubrid_insert_id — Retourne l'identifiant généré pour la dernière mise à jour de la colonne AUTO_INCREMENT
- cubrid_is_instance — Vérifie si une instance existe
- cubrid_lob_close — Ferme un BLOB/CLOB
- cubrid_lob_export — Exporte des données BLOB/CLOB vers un fichier
- cubrid_lob_get — Récupère les données BLOB/CLOB
- cubrid_lob_send — Lit les données BLOB/CLOB et les envoie au navigateur
- cubrid_lob_size — Récupère la taille des données BLOB/CLOB
- cubrid_lob2_bind — Lie un objet LOB ou une chaîne de caractères à un objet LOB comme paramètre d'une requête préparée
- cubrid_lob2_close — Ferme un objet LOB
- cubrid_lob2_export — Exporte un objet LOB vers un fichier
- cubrid_lob2_import — Importe des données BLOB/CLOB depuis un fichier
- cubrid_lob2_new — Crée un nouvel objet LOB
- cubrid_lob2_read — Lit des données BLOB/CLOB
- cubrid_lob2_seek — Déplace le curseur d'un objet LOB
- cubrid_lob2_seek64 — Déplace le curseur d'un objet LOB
- cubrid_lob2_size — Récupère la taille d'un objet LOB
- cubrid_lob2_size64 — Récupère la taille d'un objet LOB
- cubrid_lob2_tell — Récupère la position du curseur dans un objet LOB
- cubrid_lob2_tell64 — Récupère la position du curseur dans l'objet LOB
- cubrid_lob2_write — Écrit dans un objet LOB
- cubrid_lock_read — Place un verrou de lecture sur l'OID fourni
- cubrid_lock_write — Place un verrou d'écriture sur l'OID fourni
- cubrid_move_cursor — Déplace le curseur dans le résultat
- cubrid_next_result — Récupère le résultat de la prochaine requête lors de l'exécution de requêtes SQL multiples
- cubrid_num_cols — Récupère le nombre de colonnes du jeu de résultats
- cubrid_num_rows — Récupère le nombre de lignes d'un jeu de résultats
- cubrid_pconnect — Ouvre une connexion persistante vers un serveur CUBRID
- cubrid_pconnect_with_url — Ouvre une connexion persistante vers un serveur CUBRID
- cubrid_prepare — Prépare une requête SQL pour son exécution
- cubrid_put — Met à jour une colonne suivant son OID
- cubrid_rollback — Annule une transaction
- cubrid_schema — Récupère des informations sur un schéma
- cubrid_seq_drop — Supprime un élément d'une séquence
- cubrid_seq_insert — Insère un élément dans une séquence
- cubrid_seq_put — Met à jour la valeur d'un élément d'une séquence
- cubrid_set_add — Insère un seul élément pour définir le type d'une colonne
- cubrid_set_autocommit — Définit le mode auto-commit pour la connexion
- cubrid_set_db_parameter — Définit les paramètres de base de données CUBRID
- cubrid_set_drop — Supprime un élément
- cubrid_set_query_timeout — Définit le délai maximal d'exécution d'une requête
- cubrid_version — Récupère la version du module PHP CUBRID

# Fonctions CUBRID compatibles MySQL

# cubrid_affected_rows

(PECL CUBRID >= 8.3.0)

cubrid_affected_rows — Récupère le nombre de lignes affectées par la dernière requête SQL

### Description

function cubrid_affected_rows(resource `$conn_identifier` = ?): int
function cubrid_affected_rows(resource `$req_identifier` = ?): int

La fonction cubrid_affected_rows() est utilisée pour récupérer le nombre de lignes affectées par la dernière requête Cubrid (INSERT, DELETE, UPDATE).

### Liste de paramètres

`conn_identifier`
  La connexion CUBRID. Si l'identifiant de connexion n'est pas spécifié, le dernier lien ouvert par cubrid_connect() est utilisé.
`req_identifier`
  L'identifiant de requête ; il peut être retourné soit de la fonction cubrid_prepare(), soit de la fonction cubrid_execute(). Si l'identifiant de requête n'est pas spécifié, le dernier identifiant de requête utilisé par la fonction cubrid_prepare() ou la fonction cubrid_execute() sera utilisé.

### Valeurs de retour

Nombre de lignes affectées par la dernière requête SQL, lorsqu'elle a réussi.

-1, lorsque la dernière requête n'était pas de type INSERT, DELETE ou UPDATE.

`false`, lorsque l'identifiant de requête n'est pas spécifié et qu'il n'y a aucune requête précédente.

### Exemples

Exemple #1 Exemple avec cubrid_affected_rows()

    <?php
    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    cubrid_execute($conn, "DROP TABLE IF EXISTS cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d varchar)");
    $sql_stmt = "INSERT INTO cubrid_test(d) VALUES('php-test')";
    $req = cubrid_prepare($conn, $sql_stmt);

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($req);
    }
    cubrid_commit($conn);

    $req = cubrid_execute($conn, "DELETE FROM cubrid_test WHERE d='php-test'", CUBRID_ASYNC);
    var_dump(cubrid_affected_rows());
    var_dump(cubrid_affected_rows($conn));
    var_dump(cubrid_affected_rows($req));

    cubrid_disconnect($conn);

    print "done!";
    ?>

L'exemple ci-dessus va afficher :

    int(10)
    int(10)
    int(10)
    done!

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée

# cubrid_client_encoding

(PECL CUBRID >= 8.3.1)

cubrid_client_encoding — Retourne le jeu de caractères utilisé sur la connexion CUBRID courante

### Description

function cubrid_client_encoding(resource `$conn_identifier` = ?): string

Cette fonction retourne le jeu de caractères utilisé sur la connexion CUBRID courante et est similaire à la fonction cubrid_get_charset().

### Liste de paramètres

`conn_identifier`
  La connexion CUBRID. Si l'identifiant de connexion n'est pas spécifié, la dernière connexion ouverte avec la fonction cubrid_connect() sera utilisée.

### Valeurs de retour

Une chaîne de caractères qui représente le jeu de caractères sur la connexion CUBRID en cas de succès.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_client_encoding()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('Connexion impossible.');
    }

    printf("Jeu de caractères courant CUBRID : %s\n", cubrid_client_encoding($con));

    ?>

L'exemple ci-dessus va afficher :

    Jeu de caractères courant CUBRID : iso8859-1

### Voir aussi

- cubrid_get_charset() - Retourne le jeu de caractères utilisé sur la connexion CUBRID courante

# cubrid_close

(PECL CUBRID >= 8.3.1)

cubrid_close — Ferme une connexion CUBRID

### Description

function cubrid_close(resource `$conn_identifier` = ?): bool

La fonction cubrid_close() met fin à la transaction courante, ferme le gestionnaire de connexion et déconnecte le serveur. S'il existe des gestionnaires de requêtes non clos à ce moment-là, ils seront tous clos. Cette fonction est similaire à la fonction cubrid_disconnect().

### Liste de paramètres

`conn_identifier`
  L'identifiant de connexion CUBRID. Si l'identifiant de connexion n'est pas spécifié, la dernière connexion ouverte avec la fonction cubrid_connect() sera utilisée.

### Valeurs de retour

`true`, lorsque l'opération a été réalisée avec succès.

`false`, lorsque l'opération a échoué.

### Exemples

Exemple #1 Exemple avec cubrid_close()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
       echo "connexion avec succès";
       $req = cubrid_execute ( $con, "insert into person values(1,'James')");
       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_close ($con);
    }
    ?>

### Voir aussi

- cubrid_disconnect() - Ferme la connexion à la base de données
- cubrid_connect() - Ouvre une connexion au serveur CUBRID
- cubrid_connect_with_url() - Établit l'environnement pour une connexion au serveur CUBRID

# cubrid_data_seek

(PECL CUBRID >= 8.3.0)

cubrid_data_seek — Déplace le pointeur de lignes interne du résultat CUBRID

### Description

function cubrid_data_seek(resource `$result`, int `$row_number`): bool

Cette fonction déplace le pointeur de lignes interne du résultat CUBRID (associé avec l'identifiant de résultat spécifié) pour pointer sur un numéro de ligne spécifique. Il y a des fonctions, comme la fonction cubrid_fetch_assoc(), qui utilisent la valeur courante stockée de `row_number`.

### Liste de paramètres

`result`
  Le résultat.
`row_number`
  Numéro de ligne désiré pour le nouveau pointeur de résultat.

### Valeurs de retour

Retourne `true` en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_data_seek()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_data_seek($req, 0);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 2);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 4);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }
    array(2) {
      [0]=>
      string(1) "S"
      [1]=>
      string(6) "Silver"
    }

# cubrid_db_name

(PECL CUBRID >= 8.3.1)

cubrid_db_name — Récupère le nom de la base de données depuis les résultats de cubrid_list_dbs

### Description

function cubrid_db_name(array `$result`, int `$index`): string

Récupère le nom de la base de données depuis un appel à la fonction cubrid_list_dbs().

### Liste de paramètres

`result`
  Le pointeur de résultat depuis un appel à la fonction cubrid_list_dbs().
`index`
  L'index dans le jeu de résultats.

### Valeurs de retour

Retourne le nom de la base de données en cas de succès, et `false` si une erreur survient. Si `false` est retourné, utiliser la fonction cubrid_error() pour déterminer la nature de l'erreur.

### Exemples

Exemple #1 Exemple avec cubrid_db_name()

    <?php
    error_reporting(E_ALL);

    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $db_list = cubrid_list_dbs($conn);

    $i = 0;
    $cnt = count($db_list);
    while ($i < $cnt) {
        echo cubrid_db_name($db_list, $i) . "\n";
        $i++;
    }
    ?>

L'exemple ci-dessus va afficher :

    demodb

### Voir aussi

- cubrid_list_dbs() - Retourne un tableau contenant la liste de toutes les bases de données CUBRID existantes

# cubrid_errno

(PECL CUBRID >= 8.3.1)

cubrid_errno — Retourne la valeur numérique d'un message d'erreur

### Description

function cubrid_errno(resource `$conn_identifier` = ?): int

Retourne le numéro de l'erreur issue depuis la dernière fonction CUBRID.

La fonction cubrid_errno() est utilisée pour récupérer le code erreur de la dernière erreur survenue lors d'une exécution de l'API. Habituellement, elle retourne le code erreur lorsque l'API retourne `false`.

### Liste de paramètres

`conn_identifier`
  L'identifiant de connexion CUBRID. Si l'identifiant de connexion n'est pas spécifié, la dernière connexion ouverte avec la fonction cubrid_connect() sera utilisée.

### Valeurs de retour

Retourne le numéro de l'erreur issue lors de la dernière fonction CUBRID, ou `0` (zéro) si aucune erreur n'est survenue.

### Exemples

Exemple #1 Exemple avec cubrid_errno()

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Code erreur : ", cubrid_errno($con);
        echo "Message d'erreur : ", cubrid_error($con);
    }
    ?>

L'exemple ci-dessus va afficher :

    Code erreur : -493 Message d'erreur : Syntax: Unknown class "person". select id, [name] from person

### Voir aussi

- cubrid_error() - Récupère le message de l'erreur
- cubrid_error_code() - Récupère le code erreur de la dernière erreur survenue
- cubrid_error_msg() - Récupère le message d'erreur de la dernière erreur survenue

# cubrid_error

(PECL CUBRID >= 8.3.1)

cubrid_error — Récupère le message de l'erreur

### Description

function cubrid_error(resource `$connection` = ?): string

La fonction cubrid_error() est utilisée pour récupérer le message de l'erreur survenue lors de l'utilisation de l'API CUBRID. Habituellement, elle récupère le message de l'erreur lorsque l'API retourne `false`.

### Liste de paramètres

`connection`
  La connexion CUBRID.

### Valeurs de retour

Le message de l'erreur survenue.

### Exemples

Exemple #1 Exemple avec cubrid_error()

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Code de l'erreur : ", cubrid_errno($con);
        echo "Message de l'erreur : ", cubrid_error($con);
    }
    ?>

L'exemple ci-dessus va afficher :

    Code de l'erreur : -493 Message de l'erreur : Syntax: Unknown class "person". select id, [name] from person

### Voir aussi

- cubrid_errno() - Retourne la valeur numérique d'un message d'erreur
- cubrid_error_code() - Récupère le code erreur de la dernière erreur survenue
- cubrid_error_msg() - Récupère le message d'erreur de la dernière erreur survenue

# cubrid_fetch_array

(PECL CUBRID >=8.3.0)

cubrid_fetch_array — Récupère une ligne de résultat sous forme de tableau associatif, de tableau numérique, ou les deux

### Description

function cubrid_fetch_array(resource `$result`, int `$type` = CUBRID_BOTH): array

La fonction cubrid_fetch_array() est utilisée pour récupérer une seule ligne depuis le résultat de la requête et retourne un tableau. Le curseur se déplace automatiquement sur la prochaine ligne une fois le résultat récupéré.

### Liste de paramètres

`result`
  Le paramètre `Result` provient d'un appel à la fonction cubrid_execute()
`type`
  Type du tableau récupéré : CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH. S'il est nécessaire d'utiliser un objet LOB, il est possible d'utiliser CUBRID_LOB.

### Valeurs de retour

Retourne un tableau de chaînes de caractères correspondant à la ligne récupérée, lorsque l'opération a réussi.

`false` lorsqu'il n'y a plus de ligne, NULL lorsqu'une erreur survient.

Le type du tableau retourné dépend de la façon dont le type a été défini. En utilisant CUBRID_BOTH (valeur par défaut), on récupérera un tableau contenant à la fois des indices associatifs et numériques ; il est possible de choisir explicitement ce type via l'argument `type`. La variable `type` peut être définie à une des valeurs suivantes :

- CUBRID_NUM : Tableau numérique (en commençant à l'indice 0)
- CUBRID_ASSOC : Tableau associatif
- CUBRID_BOTH : Tableau associatif et numérique (valeur par défaut)

### Exemples

Exemple #1 Exemple avec cubrid_fetch_array()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_array($req, CUBRID_NUM)) {
        printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // Si vous voulez utiliser un objet LOB, vous pouvez utiliser
    // cubrid_fetch_array($req, CUBRID_NUM | CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_fetch() - Récupère la prochaine ligne du jeu de résultats
- cubrid_fetch_row() - Retourne un tableau numérique avec les valeurs de la ligne courante
- cubrid_fetch_assoc() - Retourne un tableau associatif correspondant à la ligne récupérée
- cubrid_fetch_object() - Récupère la prochaine ligne et la retourne sous la forme d'un objet

# cubrid_fetch_assoc

(PECL CUBRID >= 8.3.0)

cubrid_fetch_assoc — Retourne un tableau associatif correspondant à la ligne récupérée

### Description

function cubrid_fetch_assoc(resource `$result`, int `$type` = ?): array

Cette fonction retourne un tableau associatif correspondant à la ligne récupérée, puis, déplace le pointeur de données interne sur la prochaine ligne. La fonction retourne `false` s'il n'y a plus de résultat de disponible.

### Liste de paramètres

`result`
  Le paramètre `result` provient d'un appel à la fonction cubrid_execute()
`type`
  Le type ne peut être que CUBRID_LOB ; ce paramètre sera utilisé uniquement lorsqu'il est nécessaire d'utiliser un objet LOB.

### Valeurs de retour

Un tableau associatif, en cas de succès.

`false` lorsqu'il n'y a plus de ligne, NULL si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_fetch_assoc()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_assoc($req)) {
        printf("%-40s %-10s %-6s %-20s\n",
            $row["name"], $row["area"], $row["seats"], $row["address"]);
    }

    // Si vous voulez utiliser un objet LOB, vous pouvez utiliser
    // cubrid_fetch_assoc($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_fetch() - Récupère la prochaine ligne du jeu de résultats
- cubrid_fetch_row() - Retourne un tableau numérique avec les valeurs de la ligne courante
- cubrid_fetch_array() - Récupère une ligne de résultat sous forme de tableau associatif, de tableau numérique, ou les deux
- cubrid_fetch_object() - Récupère la prochaine ligne et la retourne sous la forme d'un objet

# cubrid_fetch_field

(PECL CUBRID >= 8.3.1)

cubrid_fetch_field — Récupère des informations sur une colonne et les retourne sous la forme d'un objet

### Description

function cubrid_fetch_field(resource `$result`, int `$field_offset` = 0): object

Cette fonction retourne un objet avec certaines propriétés d'une colonne spécifique. Les propriétés de l'objet sont :

`name`
  Nom de la colonne
`table`
  Nom de la table contenant cette colonne
`def`
  Valeur par défaut de la colonne
`max_length`
  Longueur maximale de la colonne
`not_null`
  1 si la colonne ne peut être NULL
`primary_key`
  1 si la colonne est une clé primaire
`unique_key`
  1 si la colonne est une clé unique
`multiple_key`
  1 si la colonne est une clé non-unique
`numeric`
  1 si la colonne est de type numérique
`blob`
  1 si la colonne est de type BLOB
`type`
  Le type de la colonne
`unsigned`
  1 si la colonne n'est pas signée
`zerofill`
  1 si la colonne est complétée par des zéros

### Liste de paramètres

`result`
  Le paramètre `result` provient d'un appel à la fonction cubrid_execute()
`field_offset`
  La position numérique du champ. Si la position du champ n'est pas spécifiée, le prochain champ (qui n'a pas encore été récupéré par cette fonction) est récupéré. Le paramètre `field_offset` commence à zéro.

### Valeurs de retour

Un objet avec certaines propriétés d'une colonne spécifique, en cas de succès.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_fetch_field()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Propriétés des champs ---\n");
    printf("%-30s %s\n", "name:", $field->name);
    printf("%-30s %s\n", "table:", $field->table);
    printf("%-30s \"%s\"\n", "default value:", $field->def);
    printf("%-30s %d\n", "max length:", $field->max_length);
    printf("%-30s %d\n", "not null:", $field->not_null);
    printf("%-30s %d\n", "primary key:", $field->primary_key);
    printf("%-30s %d\n", "unique key:", $field->unique_key);
    printf("%-30s %d\n", "multiple key:", $field->multiple_key);
    printf("%-30s %d\n", "numeric:", $field->numeric);
    printf("%-30s %d\n", "blob:", $field->blob);
    printf("%-30s %s\n", "type:", $field->type);
    printf("%-30s %d\n", "unsigned:", $field->unsigned);
    printf("%-30s %d\n", "zerofill:", $field->zerofill);

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16681"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-9-30"
    }

    --- Propriétés des champs ---
    name:                          athlete_code
    table:                         game
    default value:                 ""
    max length:                    0
    not null:                      1
    primary key:                   1
    unique key:                    1
    multiple key:                  0
    numeric:                       1
    blob:                          0
    type:                          integer
    unsigned:                      0
    zerofill:                      0

# cubrid_fetch_lengths

(PECL CUBRID >= 8.3.0)

cubrid_fetch_lengths — Retourne un tableau contenant les longueurs des valeurs de chaque champ de la ligne courante

### Description

function cubrid_fetch_lengths(resource `$result`): array

Cette fonction retourne un tableau numérique avec les longueurs des valeurs de chaque champ depuis la ligne courante du jeu de résultats, ou retourne `false` si une erreur survient.

> Note: Si le type de données du champ est BLOB/CLOB, il faut utiliser la fonction cubrid_lob_size() afin d'en connaître sa longueur.

### Liste de paramètres

`result`
  Le paramètre `result` provient d'un appel à la fonction cubrid_execute()

### Valeurs de retour

Un tableau numérique en cas de succès.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_fetch_lengths()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $row = cubrid_fetch_row($result);
    print_r($row);

    $lens = cubrid_fetch_lengths($result);
    print_r($lens);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => 2004
        [1] => 20085
        [2] => 15118
        [3] => 30134
        [4] => AUS
        [5] => G
        [6] => 2004-8-20
    )
    Array
    (
        [0] => 4
        [1] => 5
        [2] => 5
        [3] => 5
        [4] => 3
        [5] => 1
        [6] => 10
    )

# cubrid_fetch_object

(PECL CUBRID >= 8.3.0)

cubrid_fetch_object — Récupère la prochaine ligne et la retourne sous la forme d'un objet

### Description

function cubrid_fetch_object(
resource `$result`,
string `$class_name` = ?,
array `$params` = ?,
int `$type` = ?
): object

Cette fonction retourne un objet avec les noms des colonnes du jeu de résultats comme propriétés. Les valeurs de ces propriétés sont extraites depuis la ligne courante du jeu de résultats.

### Liste de paramètres

`result`
  Le paramètre `result` provient d'un appel à la fonction cubrid_execute()
`class_name`
  Le nom de la classe à instancier, à définir les propriétés et à retourner. Si non spécifié, un objet stdClass est retourné.
`params`
  Un tableau de paramètres optionnels à passer au constructeur de la classe `class_name`.
`type`
  Le type ne peut être que CUBRID_LOB ; ce paramètre sera utilisé uniquement lorsqu'il est nécessaire d'utiliser un objet lob.

### Valeurs de retour

Un objet en cas de succès.

`false` lorsqu'il n'y a plus de ligne, NULL si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_fetch_object()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $res = cubrid_execute($conn, "SELECT * FROM code");

    var_dump(cubrid_fetch_object($res));

    class demodb_code {
        public $s_name = null;
        public $f_name = null;

        public function toString() {
            var_dump($this);
        }
    }

    var_dump(cubrid_fetch_object($res, "demodb_code"));

    // Si vous voulez utiliser un objet LOB, vous pouvez utiliser
    // cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name'), CUBRID_LOB)

    class demodb_code_construct extends demodb_code {
        public function __construct($s, $f) {
            $this->s_name = $s;
            $this->f_name = $f;
        }
    }

    var_dump(cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name')));

    // Si vous voulez utiliser un objet LOB, vous pouvez utiliser
    // cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name'), CUBRID_LOB)

    var_dump(cubrid_fetch_object($res));

    cubrid_close_request($res);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "X"
      ["f_name"]=>
      string(5) "Mixed"
    }
    object(demodb_code)#1 (2) {
      ["s_name"]=>
      string(1) "W"
      ["f_name"]=>
      string(5) "Woman"
    }
    object(demodb_code_construct)#1 (2) {
      ["s_name"]=>
      string(6) "s_name"
      ["f_name"]=>
      string(6) "f_name"
    }
    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "B"
      ["f_name"]=>
      string(6) "Bronze"
    }

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_fetch() - Récupère la prochaine ligne du jeu de résultats
- cubrid_fetch_array() - Récupère une ligne de résultat sous forme de tableau associatif, de tableau numérique, ou les deux
- cubrid_fetch_assoc() - Retourne un tableau associatif correspondant à la ligne récupérée
- cubrid_fetch_row() - Retourne un tableau numérique avec les valeurs de la ligne courante

# cubrid_fetch_row

(PECL CUBRID >= 8.3.0)

cubrid_fetch_row — Retourne un tableau numérique avec les valeurs de la ligne courante

### Description

function cubrid_fetch_row(resource `$result`, int `$type` = ?): array

Cette fonction retourne un tableau numérique avec les valeurs de la ligne courante depuis le jeu de résultats, en commençant à 0 et déplace le pointeur interne de données.

### Liste de paramètres

`result`
  Le paramètre `result` provient d'un appel à la fonction cubrid_execute()
`type`
  Le type ne peut être que CUBRID_LOB ; ce paramètre sera utilisé uniquement lorsqu'il est nécessaire d'utiliser un objet lob.

### Valeurs de retour

Un tableau numérique en cas de succès.

`false` lorsqu'il n'y a plus de ligne, NULL si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_fetch_row()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_row($req)) {
        printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // Si vous souhaitez utiliser un objet lob, vous pouvez utiliser
    // cubrid_fetch_row($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Voir aussi

- cubrid_execute() - Exécute une requête SQL préparée
- cubrid_fetch() - Récupère la prochaine ligne du jeu de résultats
- cubrid_fetch_array() - Récupère une ligne de résultat sous forme de tableau associatif, de tableau numérique, ou les deux
- cubrid_fetch_assoc() - Retourne un tableau associatif correspondant à la ligne récupérée
- cubrid_fetch_object() - Récupère la prochaine ligne et la retourne sous la forme d'un objet

# cubrid_field_flags

(PECL CUBRID >= 8.3.0)

cubrid_field_flags — Retourne une chaîne avec les drapeaux de la position du champ fourni

### Description

function cubrid_field_flags(resource `$result`, int `$field_offset`): string

Cette fonction retourne une chaîne de caractères avec les drapeaux de la position du champ fourni, séparés par un espace. Il est possible d'utiliser la fonction explode() pour récupérer chaque drapeau. Les drapeaux disponibles sont : `not_null`, `primary_key`, `unique_key`, `foreign_key`, `auto_increment`, `shared`, `reverse_index`, `reverse_unique` et `timestamp`.

### Liste de paramètres

`result`
  Le paramètre `result` provient de l'appel à la fonction cubrid_execute()
`field_offset`
  La position numérique du champ. `field_offset` commence à zéro (0). Si `field_offset` n'existe pas, une erreur de niveau `E_WARNING` sera également émise.

### Valeurs de retour

Une chaîne de caractères avec les drapeaux, en cas de succès.

`false` si la valeur de field_offset est invalide.

-1 si la requête SQL n'est pas de type SELECT.

### Exemples

Exemple #1 Exemple avec cubrid_field_flags()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Field Name", "Field Flags");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Field Name                     Field Flags
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_len

(PECL CUBRID >= 8.3.0)

cubrid_field_len — Récupère la longueur maximale du champ spécifié

### Description

function cubrid_field_len(resource `$result`, int `$field_offset`): int

Cette fonction retourne la longueur maximale du champ spécifié en cas de succès, ou `false` si une erreur survient.

### Liste de paramètres

`result`
  Le paramètre `result` provient de l'appel à la fonction cubrid_execute()
`field_offset`
  La position numérique du champ. `field_offset` commence à 0. Si `field_offset` n'existe pas, une erreur de niveau `E_WARNING` sera également émise.

### Valeurs de retour

La longueur maximale, en cas de succès.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_field_len()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

# cubrid_field_name

(PECL CUBRID >= 8.3.0)

cubrid_field_name — Retourne le nom du champ spécifié

### Description

function cubrid_field_name(resource `$result`, int `$field_offset`): string

Cette fonction retourne le nom du champ spécifié par son index en cas de succès, ou `false` si une erreur survient.

### Liste de paramètres

`result`
  Le paramètre `result` provient de l'appel à la fonction cubrid_execute()
`field_offset`
  La position numérique du champ. `field_offset` commence à zéro (0). Si `field_offset` n'existe pas, une erreur de niveau `E_WARNING` sera également émise.

### Valeurs de retour

Nom du champ spécifié par son index en cas de succès.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_field_name()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Field Name", "Field Flags");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Field Name                     Field Flags
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_seek

(PECL CUBRID >= 8.3.0)

cubrid_field_seek — Déplace le curseur du jeu de résultats à une position spécifiée

### Description

function cubrid_field_seek(resource `$result`, int `$field_offset` = 0): bool

Cette fonction déplace le curseur du jeu de résultats à une position spécifiée. La position est utilisée par la fonction cubrid_fetch_field() si elle n'inclut pas une position de champ. La fonction retourne `true` en cas de succès, `false` sinon.

### Liste de paramètres

`result`
  Le paramètre `result` provient de l'appel à la fonction cubrid_execute()
`field_offset`
  La position numérique du champ. `field_offset` commence à zéro (0). Si `field_offset` n'existe pas, une erreur de niveau `E_WARNING` sera également émise.

### Valeurs de retour

`true` en cas de succès.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_field_seek()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Field Properties ---\n");
    printf("%-30s %s\n", "name:", $field->name);
    printf("%-30s %s\n", "table:", $field->table);
    printf("%-30s \"%s\"\n", "default value:", $field->def);
    printf("%-30s %d\n", "max length:", $field->max_length);
    printf("%-30s %d\n", "not null:", $field->not_null);
    printf("%-30s %d\n", "unique key:", $field->unique_key);
    printf("%-30s %d\n", "multiple key:", $field->multiple_key);
    printf("%-30s %d\n", "numeric:", $field->numeric);
    printf("%-30s %s\n", "type:", $field->type);

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16132"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-09-30"
    }

    --- Field Properties ---
    name:                          athlete_code
    table:                         game
    default value:                 ""
    max length:                    0
    not null:                      1
    unique key:                    1
    multiple key:                  0
    numeric:                       1
    type:                          integer

# cubrid_field_table

(PECL CUBRID >= 8.3.0)

cubrid_field_table — Retourne le nom de la table d'un champ spécifié

### Description

function cubrid_field_table(resource `$result`, int `$field_offset`): string

Cette fonction retourne le nom de la table d'un champ spécifié. Ceci est utile lors de l'utilisation d'une requête SELECT volumineuse avec des jointures.

### Liste de paramètres

`result`
  `result` provient d'un appel à cubrid_execute()
`field_offset`
  La position numérique du champ. `field_offset` commence à zéro (0). Si `field_offset` n'existe pas, une erreur de niveau `E_WARNING` sera également émise.

### Valeurs de retour

Nom de la table du champ spécifié, en cas de succès.

`false` lorsque la valeur de field_offset est invalide.

-1 si la requête SQL n'est pas de type SELECT.

### Exemples

Exemple #1 Exemple avec cubrid_field_table()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-15s %-15s %s\n",
            cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Field Table     Field Name      Field Type
    code            s_name          char
    code            f_name          varchar

# cubrid_field_type

(PECL CUBRID >= 8.3.0)

cubrid_field_type — Retourne le type de la colonne correspondant à la position du champ fourni

### Description

function cubrid_field_type(resource `$result`, int `$field_offset`): string

Cette fonction retourne le type de la colonne correspondant à la position du champ fourni. Le type du champ retourné peut être un parmi les suivants : "int", "real", "string", etc.

### Liste de paramètres

`result`
  `result` provient d'un appel à cubrid_execute()
`field_offset`
  Position numérique du champ. Le paramètre `field_offset` commence à zéro (0). Si `field_offset` n'existe pas, une erreur de niveau `E_WARNING` sera également émise.

### Valeurs de retour

Le type de la colonne en cas de succès.

`false` Lorsque la valeur de field_offset est invalide.

-1 si la requête SQL n'est pas de type SELECT.

### Exemples

Exemple #1 Exemple avec cubrid_field_type()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-15s %-15s %s\n",
            cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Field Table     Field Name      Field Type
    code            s_name          char
    code            f_name          varchar

# cubrid_list_dbs

(PECL CUBRID >= 8.3.0)

cubrid_list_dbs — Retourne un tableau contenant la liste de toutes les bases de données CUBRID existantes

### Description

function cubrid_list_dbs(resource `$conn_identifier` = ?): array

Cette fonction retourne un tableau contenant la liste de toutes les bases de données CUBRID existantes.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion CUBRID.

### Valeurs de retour

Un tableau numérique contenant toutes les bases de données CUBRID existantes en cas de succès.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_list_dbs()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $db_list = cubrid_list_dbs($conn);
    var_dump($db_list);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      [0]=>
      string(6) "demodb"
    }

# cubrid_num_fields

(PECL CUBRID >= 8.3.0)

cubrid_num_fields — Retourne le nombre de colonnes dans le jeu de résultats

### Description

function cubrid_num_fields(resource `$result`): int

Cette fonction retourne le nombre de colonnes dans le jeu de résultats en cas de succès, ou `false` si une erreur survient.

### Liste de paramètres

`result`
  Le paramètre `result` provient d'un appel à la fonction cubrid_execute(), cubrid_query() ou cubrid_prepare()

### Valeurs de retour

Nombre de colonnes en cas de succès.

-1 si la requête SQL n'est pas de type SELECT.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_num_fields()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_fields($req);

    printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    Row Num: 6
    Column Num: 2

# cubrid_ping

(PECL CUBRID >= 8.3.1)

cubrid_ping — Ping une connexion au serveur ou se reconnecte s'il n'y a plus de connexion active

### Description

function cubrid_ping(resource `$conn_identifier` = ?): bool

Vérifie si la connexion au serveur est toujours active.

### Liste de paramètres

`conn_identifier`
  L'identifiant de connexion CUBRID. Si l'identifiant de connexion n'est pas spécifié, la dernière connexion ouverte avec la fonction cubrid_connect() sera utilisée.

### Valeurs de retour

Retourne `true` si la connexion au serveur CUBRID est active, `false` sinon.

### Exemples

Exemple #1 Exemple avec cubrid_ping()

    <?php
    set_time_limit(0);

    $conn = cubrid_connect('localhost', 33000, 'demodb');

    /* Supposons que la requête prend beaucoup de temps */
    $sql = "select * from athlete";
    $result = cubrid_query($sql);
    if (!$result) {
        echo 'La requête #1 a échoué, on sort.';
        exit;
    }

    /* Assurons-nous que la connexion est toujours active, sinon, on se reconnecte */
    if (!cubrid_ping($conn)) {
        echo 'Connexion perdue, on sort après la requête #1';
        exit;
    }
    cubrid_free_result($result);

    /* La connexion est toujours active, on peut exécuter une autre requête */
    $sql2 = "select * from code";
    $result2 = cubrid_query($sql2);
    ?>

# cubrid_query

(PECL CUBRID >= 8.3.1)

cubrid_query — Envoie une requête CUBRID

### Description

function cubrid_query(string `$query`, resource `$conn_identifier` = ?): resource

La fonction cubrid_query() envoie une seule requête (l'envoi de plusieurs requêtes n'est pas supporté) à la base de données active sur le serveur associé avec le paramètre `conn_identifier` fourni.

### Liste de paramètres

`query`
  Une requête SQL Les données de la requête doivent être proprement échappées.
`conn_identifier`
  La connexion CUBRID. Si l'identifiant de connexion n'est pas spécifié, la dernière connexion ouverte avec la fonction cubrid_connect() sera utilisée.

### Valeurs de retour

Pour les requêtes de type SELECT, SHOW, DESCRIBE, EXPLAIN et autres requêtes retournant un jeu de résultats, cubrid_query() retourne une resource en cas de succès, ou `false` si une erreur survient.

Pour les autres requêtes (INSERT, UPDATE, DELETE, DROP, etc.), cubrid_query() retourne `true` en cas de succès, ou `false` si une erreur survient.

La ressource de résultats retournée doit être passée à la fonction cubrid_fetch_array(), et autres fonctions gérant les ressources de résultats, afin d'accéder aux données retournées.

La fonction cubrid_num_rows() permet de trouver le nombre de lignes retournées par une requête SELECT ou la fonction cubrid_affected_rows() afin de savoir le nombre de lignes affectées par une requête DELETE, INSERT, REPLACE, ou UPDATE.

La fonction cubrid_query() échoue et retourne `false` si l'utilisateur n'a pas l'autorisation d'accéder à la table utilisée dans la requête.

### Exemples

Exemple #1 Requête invalide

La requête suivante n'est littéralement pas valide, aussi, la fonction cubrid_query() échoue et retourne `false`.

    <?php
    $conn = cubrid_connect('localhost', 33000, 'demodb');

    $result = cubrid_query('SELECT * WHERE 1=1');
    if (!$result) {
        die('Requête invalide : ' . cubrid_error());
    }

    ?>

Exemple #2 Requête valide

La requête suivante est valide, aussi, la fonction cubrid_query() retourne une ressource.

    <?php
    // Ces variables pourraient être fournies par un utilisateur, par exemple
    $firstname = 'fred';
    $lastname  = 'fox';

    $conn = cubrid_connect('localhost', 33000, 'demodb');

    cubrid_execute($conn,"DROP TABLE if exists friends");
    cubrid_execute($conn,"create table friends(firstname varchar,lastname varchar,address char(24),age int)");
    cubrid_execute($conn,"insert into friends values('fred','fox','home-1','20')");
    cubrid_execute($conn,"insert into friends values('blue','cat','home-2','21')");

    // Requête formelle
    // C'est la meilleure façon d'exécuter une requête SQL
    // Pour plus d'exemples, voir la fonction cubrid_real_escape_string()
    $query = sprintf("SELECT firstname, lastname, address, age FROM friends WHERE firstname='%s' AND lastname='%s'",
    cubrid_real_escape_string($firstname),
    cubrid_real_escape_string($lastname));

    // Exécution de la requête
    $result = cubrid_query($query);

    // Vérifie le résultat
    // Montre la requête envoyée à CUBRID, et l'erreur. Utile pour le débogage.
    if (!$result) {
        $message  = 'Requête invalide : ' . cubrid_error() . "\n";
        $message .= 'Requête complète : ' . $query;
        die($message);
    }

    // Utilisation du résultat
    // Le fait de tenter d'afficher $result ne vous donnera pas accès à l'information de la ressource
    // Une des fonctions de traitement des résultats CUBRID doit être utilisée
    // Voir aussi cubrid_result(), cubrid_fetch_array(), cubrid_fetch_row(), etc.
    while ($row = cubrid_fetch_assoc($result)) {
        echo $row['firstname'];
        echo $row['lastname'];
        echo $row['address'];
        echo $row['age'];
    }

    // Libère les ressources associées avec le jeu de résultats
    // Ceci est fait automatiquement à la fin du script
    cubrid_free_result($result);
    ?>

### Voir aussi

- cubrid_connect() - Ouvre une connexion au serveur CUBRID
- cubrid_error() - Récupère le message de l'erreur
- cubrid_real_escape_string() - Échappe les caractères spéciaux d'une chaîne pour l'utiliser dans une requête SQL
- cubrid_result() - Retourne la valeur d'un champ d'une ligne spécifique
- cubrid_fetch_assoc() - Retourne un tableau associatif correspondant à la ligne récupérée
- cubrid_unbuffered_query() - Exécute une requête sans placer les résultats en mémoire vive

# cubrid_real_escape_string

(PECL CUBRID >= 8.3.0)

cubrid_real_escape_string — Échappe les caractères spéciaux d'une chaîne pour l'utiliser dans une requête SQL

### Description

function cubrid_real_escape_string(string `$unescaped_string`, resource `$conn_identifier` = ?): string

Cette fonction retourne la version échappée de la chaîne fournie. Elle ajoute des antislashes aux caractères suivants : `'`. En général, les guillemets simples sont utilisés pour entourer la chaîne. Les doubles guillemets peuvent être utilisés également suivant la valeur d'ansi_quotes, qui est un paramètre des requêtes SQL. Si la valeur d'ansi_quotes est "no", les guillemets doubles seront gérés comme un caractère de la chaîne et non un identifiant. La valeur par défaut est "yes". Si l'on veut inclure un guillemet simple comme caractère d'une chaîne, il faut le spécifier 2 fois.

### Liste de paramètres

`unescaped_string`
  La chaîne de caractères à échapper.
`conn_identifier`
  L'identifiant de connexion CUBRID. Si l'identifiant de connexion n'est pas spécifié, la dernière connexion ouverte avec la fonction cubrid_connect() sera utilisée.

### Valeurs de retour

La version échappée de la chaîne de caractères fournie en cas de succès.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_real_escape_string()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $unescaped_str = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~';
    $escaped_str = cubrid_real_escape_string($unescaped_str);

    $len = strlen($unescaped_str);

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (t char($len))");
    cubrid_execute($conn, "INSERT INTO cubrid_test (t) VALUES('$escaped_str')");

    $req = cubrid_execute($conn, "SELECT * FROM cubrid_test");
    $row = cubrid_fetch_assoc($req);

    var_dump($row);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["t"]=>
      string(95) " !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
    }

# cubrid_result

(PECL CUBRID >= 8.3.0)

cubrid_result — Retourne la valeur d'un champ d'une ligne spécifique

### Description

function cubrid_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Cette fonction retourne la valeur d'un champ spécifique d'une ligne spécifique depuis un jeu de résultats.

### Liste de paramètres

`result`
  Le paramètre `result` provient d'un appel à la fonction cubrid_execute()
`row`
  Le numéro de la ligne depuis le résultat à récupérer. Ce numéro commence à partir de 0.
`field`
  Le nom ou la position du champ `field` à récupérer. Ce peut être la position du champ, son nom, ou le nom de la table suivi d'un point, suivi du nom du champ (tablename.fieldname). Si le nom de la colonne est un alias ('select foo as bar from...'), utiliser l'alias au lieu du nom de la colonne. Si non défini, le premier champ sera récupéré.

### Valeurs de retour

La valeur du champ spécifié en cas de succès (`null` si la valeur est `null`).

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_result()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $result = cubrid_result($req, 0);
    var_dump($result);

    $result = cubrid_result($req, 0, 1);
    var_dump($result);

    $result = cubrid_result($req, 5, "f_name");
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

L'exemple ci-dessus va afficher :

    string(1) "X"
    string(5) "Mixed"
    string(4) "Gold"

# cubrid_unbuffered_query

(PECL CUBRID >= 8.3.0)

cubrid_unbuffered_query — Exécute une requête sans placer les résultats en mémoire vive

### Description

function cubrid_unbuffered_query(string `$query`, resource `$conn_identifier` = ?): resource

Cette fonction exécute une requête sans attendre que tous les résultats aient été récupérés. La fonction retournera lorsque les résultats seront générés.

### Liste de paramètres

`query`
  Une requête SQL.
`conn_identifier`
  Identifiant de connexion. Si non fourni, la dernière connexion ouverte avec la fonction cubrid_connect() sera utilisée.

### Valeurs de retour

Pour les requêtes de type SELECT, SHOW, DESCRIBE ou EXPLAIN, la fonction retournera une ressource d'identifiant de requête en cas de succès.

Pour les autres types de requêtes SQL (UPDATE, DELETE, DROP, etc.), la fonction retournera `true` en cas de succès.

`false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec cubrid_unbuffered_query()

    <?php
        $link = cubrid_connect("localhost", 30000, "demodb", "dba", "");
        if (!$link)
        {
            die('Impossible de se connecter.');
        }
        $query = "select * from code";
        $result = cubrid_unbuffered_query($query, $link);

        while ($row = cubrid_fetch($result))
        {
            var_dump($row);
        }

        cubrid_close_request($result);
        cubrid_disconnect($link);
    ?>

### Notes

> Note: Les bénéfices de la fonction cubrid_unbuffered_query() ont un prix : il n'est pas possible d'utiliser cubrid_num_rows() et cubrid_data_seek() sur le jeu de résultats retourné depuis cubrid_unbuffered_query().

## Sommaire

- cubrid_affected_rows — Récupère le nombre de lignes affectées par la dernière requête SQL
- cubrid_client_encoding — Retourne le jeu de caractères utilisé sur la connexion CUBRID courante
- cubrid_close — Ferme une connexion CUBRID
- cubrid_data_seek — Déplace le pointeur de lignes interne du résultat CUBRID
- cubrid_db_name — Récupère le nom de la base de données depuis les résultats de cubrid_list_dbs
- cubrid_errno — Retourne la valeur numérique d'un message d'erreur
- cubrid_error — Récupère le message de l'erreur
- cubrid_fetch_array — Récupère une ligne de résultat sous forme de tableau associatif, de tableau numérique, ou les deux
- cubrid_fetch_assoc — Retourne un tableau associatif correspondant à la ligne récupérée
- cubrid_fetch_field — Récupère des informations sur une colonne et les retourne sous la forme d'un objet
- cubrid_fetch_lengths — Retourne un tableau contenant les longueurs des valeurs de chaque champ de la ligne courante
- cubrid_fetch_object — Récupère la prochaine ligne et la retourne sous la forme d'un objet
- cubrid_fetch_row — Retourne un tableau numérique avec les valeurs de la ligne courante
- cubrid_field_flags — Retourne une chaîne avec les drapeaux de la position du champ fourni
- cubrid_field_len — Récupère la longueur maximale du champ spécifié
- cubrid_field_name — Retourne le nom du champ spécifié
- cubrid_field_seek — Déplace le curseur du jeu de résultats à une position spécifiée
- cubrid_field_table — Retourne le nom de la table d'un champ spécifié
- cubrid_field_type — Retourne le type de la colonne correspondant à la position du champ fourni
- cubrid_list_dbs — Retourne un tableau contenant la liste de toutes les bases de données CUBRID existantes
- cubrid_num_fields — Retourne le nombre de colonnes dans le jeu de résultats
- cubrid_ping — Ping une connexion au serveur ou se reconnecte s'il n'y a plus de connexion active
- cubrid_query — Envoie une requête CUBRID
- cubrid_real_escape_string — Échappe les caractères spéciaux d'une chaîne pour l'utiliser dans une requête SQL
- cubrid_result — Retourne la valeur d'un champ d'une ligne spécifique
- cubrid_unbuffered_query — Exécute une requête sans placer les résultats en mémoire vive

# Fonctions et alias CUBRID obsolètes

# cubrid_load_from_glo

(PECL CUBRID >= 8.3.0)

cubrid_load_from_glo — Lie une donnée

### Description

function cubrid_load_from_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

La fonction cubrid_load_from_glo() est utilisée pour lire une donnée depuis une instance glo, et la sauvegarde dans un fichier donné.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  Oid de l'instance glo depuis laquelle l'on veut lire la donnée.
`file_name`
  Nom du fichier où la sauvegarde de la donnée doit s'effectuer.

### Valeurs de retour

`true` lorsque le processus est un succès.

`false` lorsque le processus a échoué.

### Exemples

Exemple #1 Exemple avec cubrid_load_from_glo()

    <?php
    $req = cubrid_execute ($con, "select image from person where id=1");
    if ($req) {
       list ($oid) = cubrid_fetch($req);
       cubrid_close_request($req);
       $res = cubrid_load_from_glo ($con, $oid, "output.jpg");
       if ($res) {
          echo "image changée avec succès";
       }
    }
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : cubrid_load_from_glo()

> Note: Cette fonction a été supprimée depuis CUBRID 3.1.

### Voir aussi

- cubrid_new_glo() - Crée une instance glo
- cubrid_save_to_glo() - Sauvegarde un fichier dans une instance glo
- cubrid_send_glo() - Lit les données depuis une instance glo

# cubrid_new_glo

(PECL CUBRID >= 8.3.0)

cubrid_new_glo — Crée une instance glo

### Description

function cubrid_new_glo(resource `$conn_identifier`, string `$class_name`, string `$file_name`): string

La fonction cubrid_new_glo() est utilisée pour créer une instance glo dans la classe demandée (classe glo). Le glo créé est de type LO, et est stocké dans le fichier `file_name`.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`class_name`
  Nom de la classe dans laquelle l'on veut créer le glo.
`file_name`
  Le nom du fichier dans lequel l'on veut sauvegarder le nouveau glo créé.

### Valeurs de retour

OID de l'instance créée en cas de succès.

`false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec cubrid_new_glo()

    <?php
    $oid = cubrid_new_glo ($con, "glo", "input.jpg");
    if ($oid){
       // Le type de la colonne "image" est "object"
       $req = cubrid_execute ($con, "insert into person(image) values($oid)");
       if ($req) {
          echo "image insérée avec succès";
          cubrid_close_request ($req);
          cubrid_commit($con);
       }
    }
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : cubrid_new_glo()

> Note: Cette fonction a été supprimée depuis CUBRID 3.1.

### Voir aussi

- cubrid_save_to_glo() - Sauvegarde un fichier dans une instance glo
- cubrid_load_from_glo() - Lie une donnée
- cubrid_send_glo() - Lit les données depuis une instance glo

# cubrid_save_to_glo

(PECL CUBRID >= 8.3.0)

cubrid_save_to_glo — Sauvegarde un fichier dans une instance glo

### Description

function cubrid_save_to_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

La fonction cubrid_save_to_glo() est utilisée pour sauvegarder un fichier dans une instance glo.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  Oid de l'instance glo dans laquelle le fichier sera sauvegardé.
`file_name`
  Le nom du fichier à sauvegarder.

### Valeurs de retour

`true` en cas de succès.

`false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec cubrid_save_to_glo()

    <?php
    $req = cubrid_execute ($con, "select image from person where id=1");
    if ($req) {
       list ($oid) = cubrid_fetch($req);
       cubrid_close_request($req);
       $res = cubrid_save_to_glo ($con, $oid, "input.jpg");
       if ($res) {
          echo "image changée avec succès";
       }
    }
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : cubrid_save_to_glo()

> Note: Cette fonction a été supprimée depuis CUBRID 3.1.

### Voir aussi

- cubrid_new_glo() - Crée une instance glo
- cubrid_load_from_glo() - Lie une donnée
- cubrid_send_glo() - Lit les données depuis une instance glo

# cubrid_send_glo

(PECL CUBRID >= 8.3.0)

cubrid_send_glo — Lit les données depuis une instance glo

### Description

function cubrid_send_glo(resource `$conn_identifier`, string `$oid`): int

La fonction cubrid_send_glo() est utilisée pour lire les données depuis une instance glo et les envoie à la sortie standard de PHP.

### Liste de paramètres

`conn_identifier`
  Identifiant de connexion.
`oid`
  Oid de l'instance glo depuis laquelle les données sont lues.

### Valeurs de retour

`true` en cas de succès.

`false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec cubrid_send_glo()

    <?php
    $req = cubrid_execute ($con, "select image from person where id =1");
    if ($req) {
      list ($oid) = cubrid_fetch($req);
      cubrid_close_request($req);
      Header ("Content-type: image/jpeg");
      cubrid_send_glo ($con, $oid);
    }
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : cubrid_send_glo()

> Note: Cette fonction a été supprimée depuis CUBRID 3.1.

### Voir aussi

- cubrid_new_glo() - Crée une instance glo
- cubrid_save_to_glo() - Sauvegarde un fichier dans une instance glo
- cubrid_load_from_glo() - Lie une donnée

## Sommaire

- cubrid_load_from_glo — Lie une donnée
- cubrid_new_glo — Crée une instance glo
- cubrid_save_to_glo — Sauvegarde un fichier dans une instance glo
- cubrid_send_glo — Lit les données depuis une instance glo

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Exemples
- Fonctions CUBRID
  - cubrid_bind — Lie des valeurs à une requête préparée
  - cubrid_close_prepare — Ferme le gestionnaire de requête
  - cubrid_close_request — Ferme le gestionnaire de requête
  - cubrid_col_get — Récupère le contenu des éléments d'un type de collection en utilisant l'OID
  - cubrid_col_size — Récupère le nombre d'éléments dans un type de colonne d'une collection en utilisant l'OID
  - cubrid_column_names — Récupère les noms de colonnes du résultat
  - cubrid_column_types — Récupère les types de colonnes du résultat
  - cubrid_commit — Valide une transaction
  - cubrid_connect — Ouvre une connexion au serveur CUBRID
  - cubrid_connect_with_url — Établit l'environnement pour une connexion au serveur CUBRID
  - cubrid_current_oid — Récupère l'OID de la localisation du curseur courant
  - cubrid_disconnect — Ferme la connexion à la base de données
  - cubrid_drop — Supprime une instance en utilisant son OID
  - cubrid_error_code — Récupère le code erreur de la dernière erreur survenue
  - cubrid_error_code_facility — Récupère le niveau du code erreur
  - cubrid_error_msg — Récupère le message d'erreur de la dernière erreur survenue
  - cubrid_execute — Exécute une requête SQL préparée
  - cubrid_fetch — Récupère la prochaine ligne du jeu de résultats
  - cubrid_free_result — Libère la mémoire occupée par les données de résultat
  - cubrid_get — Récupère une colonne en utilisant son OID
  - cubrid_get_autocommit — Récupère le mode auto-commit de la connexion
  - cubrid_get_charset — Retourne le jeu de caractères utilisé sur la connexion CUBRID courante
  - cubrid_get_class_name — Récupère le nom de la classe en utilisant son OID
  - cubrid_get_client_info — Retourne la version de la bibliothèque cliente
  - cubrid_get_db_parameter — Retourne les paramètres de la base de données CUBRID
  - cubrid_get_query_timeout — Récupère la valeur du délai d'attente maximal d'une requête
  - cubrid_get_server_info — Retourne la version du serveur CUBRID
  - cubrid_insert_id — Retourne l'identifiant généré pour la dernière mise à jour de la colonne AUTO_INCREMENT
  - cubrid_is_instance — Vérifie si une instance existe
  - cubrid_lob_close — Ferme un BLOB/CLOB
  - cubrid_lob_export — Exporte des données BLOB/CLOB vers un fichier
  - cubrid_lob_get — Récupère les données BLOB/CLOB
  - cubrid_lob_send — Lit les données BLOB/CLOB et les envoie au navigateur
  - cubrid_lob_size — Récupère la taille des données BLOB/CLOB
  - cubrid_lob2_bind — Lie un objet LOB ou une chaîne de caractères à un objet LOB comme paramètre d'une requête préparée
  - cubrid_lob2_close — Ferme un objet LOB
  - cubrid_lob2_export — Exporte un objet LOB vers un fichier
  - cubrid_lob2_import — Importe des données BLOB/CLOB depuis un fichier
  - cubrid_lob2_new — Crée un nouvel objet LOB
  - cubrid_lob2_read — Lit des données BLOB/CLOB
  - cubrid_lob2_seek — Déplace le curseur d'un objet LOB
  - cubrid_lob2_seek64 — Déplace le curseur d'un objet LOB
  - cubrid_lob2_size — Récupère la taille d'un objet LOB
  - cubrid_lob2_size64 — Récupère la taille d'un objet LOB
  - cubrid_lob2_tell — Récupère la position du curseur dans un objet LOB
  - cubrid_lob2_tell64 — Récupère la position du curseur dans l'objet LOB
  - cubrid_lob2_write — Écrit dans un objet LOB
  - cubrid_lock_read — Place un verrou de lecture sur l'OID fourni
  - cubrid_lock_write — Place un verrou d'écriture sur l'OID fourni
  - cubrid_move_cursor — Déplace le curseur dans le résultat
  - cubrid_next_result — Récupère le résultat de la prochaine requête lors de l'exécution de requêtes SQL multiples
  - cubrid_num_cols — Récupère le nombre de colonnes du jeu de résultats
  - cubrid_num_rows — Récupère le nombre de lignes d'un jeu de résultats
  - cubrid_pconnect — Ouvre une connexion persistante vers un serveur CUBRID
  - cubrid_pconnect_with_url — Ouvre une connexion persistante vers un serveur CUBRID
  - cubrid_prepare — Prépare une requête SQL pour son exécution
  - cubrid_put — Met à jour une colonne suivant son OID
  - cubrid_rollback — Annule une transaction
  - cubrid_schema — Récupère des informations sur un schéma
  - cubrid_seq_drop — Supprime un élément d'une séquence
  - cubrid_seq_insert — Insère un élément dans une séquence
  - cubrid_seq_put — Met à jour la valeur d'un élément d'une séquence
  - cubrid_set_add — Insère un seul élément pour définir le type d'une colonne
  - cubrid_set_autocommit — Définit le mode auto-commit pour la connexion
  - cubrid_set_db_parameter — Définit les paramètres de base de données CUBRID
  - cubrid_set_drop — Supprime un élément
  - cubrid_set_query_timeout — Définit le délai maximal d'exécution d'une requête
  - cubrid_version — Récupère la version du module PHP CUBRID
- Fonctions CUBRID compatibles MySQL
  - cubrid_affected_rows — Récupère le nombre de lignes affectées par la dernière requête SQL
  - cubrid_client_encoding — Retourne le jeu de caractères utilisé sur la connexion CUBRID courante
  - cubrid_close — Ferme une connexion CUBRID
  - cubrid_data_seek — Déplace le pointeur de lignes interne du résultat CUBRID
  - cubrid_db_name — Récupère le nom de la base de données depuis les résultats de cubrid_list_dbs
  - cubrid_errno — Retourne la valeur numérique d'un message d'erreur
  - cubrid_error — Récupère le message de l'erreur
  - cubrid_fetch_array — Récupère une ligne de résultat sous forme de tableau associatif, de tableau numérique, ou les deux
  - cubrid_fetch_assoc — Retourne un tableau associatif correspondant à la ligne récupérée
  - cubrid_fetch_field — Récupère des informations sur une colonne et les retourne sous la forme d'un objet
  - cubrid_fetch_lengths — Retourne un tableau contenant les longueurs des valeurs de chaque champ de la ligne courante
  - cubrid_fetch_object — Récupère la prochaine ligne et la retourne sous la forme d'un objet
  - cubrid_fetch_row — Retourne un tableau numérique avec les valeurs de la ligne courante
  - cubrid_field_flags — Retourne une chaîne avec les drapeaux de la position du champ fourni
  - cubrid_field_len — Récupère la longueur maximale du champ spécifié
  - cubrid_field_name — Retourne le nom du champ spécifié
  - cubrid_field_seek — Déplace le curseur du jeu de résultats à une position spécifiée
  - cubrid_field_table — Retourne le nom de la table d'un champ spécifié
  - cubrid_field_type — Retourne le type de la colonne correspondant à la position du champ fourni
  - cubrid_list_dbs — Retourne un tableau contenant la liste de toutes les bases de données CUBRID existantes
  - cubrid_num_fields — Retourne le nombre de colonnes dans le jeu de résultats
  - cubrid_ping — Ping une connexion au serveur ou se reconnecte s'il n'y a plus de connexion active
  - cubrid_query — Envoie une requête CUBRID
  - cubrid_real_escape_string — Échappe les caractères spéciaux d'une chaîne pour l'utiliser dans une requête SQL
  - cubrid_result — Retourne la valeur d'un champ d'une ligne spécifique
  - cubrid_unbuffered_query — Exécute une requête sans placer les résultats en mémoire vive
- Fonctions et alias CUBRID obsolètes
  - cubrid_load_from_glo — Lie une donnée
  - cubrid_new_glo — Crée une instance glo
  - cubrid_save_to_glo — Sauvegarde un fichier dans une instance glo
  - cubrid_send_glo — Lit les données depuis une instance glo

# dBase

# Introduction

> Note:

> Cette extension a été déplacée dans le module » PECL et ne sera plus intégrée dans PHP à partir de PHP 5.3.0.

Ces fonctions permettent d'accéder aux enregistrements des bases de données au format dBase (dbf).

Avertissement

Il est recommandé de ne pas utiliser les fichiers dBase comme la base de données de production. Il est recommandé d'utiliser » SQLite ou d'opter plutôt pour un vrai serveur SQL à la place ; » MySQL ou » PostgreSQL sont des choix communs en PHP. Le support dBase est présent en PHP uniquement pour permettre d'importer et d'exporter des données depuis et vers la base de données, car ce format de fichier est habituellement compris par les tableurs Windows.

Attention

À partir de dbase 7.0.0 les bases de données sont automatiquement verrouillées via flock(). Il n'y avait aucun support pour le verrouillage précédemment, donc deux processus de serveur web concomitants modifiant le même fichier dBase auraient très probablement ruiné la base de données. Ceci peut se produire même avec dbase 7.0.0+ sur les systèmes qui implémentent le verrouillage au niveau du processus avec les SAPI multithreadés.

Les fichiers dBase sont de simples fichiers séquentiels, d'un nombre d'enregistrements fixe. Les enregistrements sont ajoutés à la fin du fichier et les enregistrements effacés sont conservés tant que l'on n'appelle pas la fonction dbase_pack().

Seuls les fichiers dbf levels 3 (dBASE III+) - 5 (dBASE V) sont supportés. Les types de champs dBase disponibles sont :

Types de champs disponibles
Champ | Type dBase | Format | Informations complémentaires
--- | --- | --- | ---
`M` | Memo | n/a | Ce type n'est pas supporté par PHP, et sera ignoré
`D` | Date | `YYYYMMDD` | La taille du champ est limitée à 8
`T` | DateTime | `YYYYMMDDhhmmss.uuu` | (FoxPro) Aucune vérification de validité n'est faite. Disponible à partir de dbase 7.0.0.
`N` | Number | Un nombre | Il faut déclarer une taille et une précision (le nombre de chiffres après le point décimal).
`F` | Float | Un nombre flottant | Identique à `N`.
`C` | chaîne de caractères | Une chaîne de caractères | Il faut déclarer une taille. Lors de la récupération des données, la chaîne sera complétée d'espaces afin d'atteindre la taille déclarée. Les chaîne de caractères trop longues seront tronquées silencieusement lors de l'enregistrement.
`L` | booléen | `T` ou `Y` pour `true`, `F` ou `N` pour `false`, `?` pour non initialisée. | À partir de dbase 7.0.0, retourné en tant que bool (`true` ou `false`), ou `null` pour les champs non initialisés. Précédemment, retourné en tant que int (`1` ou `0`).

> Note:

> À partir de dbase 7.0.0 les champs nullable sont supportés pour les bases de données `DBASE_TYPE_FOXPRO`. Si un champ est nullable, passer `null` définira le drapeau respectif, et lors d'une récupération ultérieure la valeur du champ sera `null`.

> Note:

> Il n'y a aucun support des index ou des champs memo.

# Installation/Configuration

## Sommaire

- Installation
- Types de ressources

## Installation

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/dbase.

## Types de ressources

À partir de dbase 7.0.0, le type de ressource `dbase` est défini, qui est retourné par dbase_open() et dbase_create().

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`DBASE_VERSION` (string)
  La version de l'extension (Disponible à partir de dbase 7.0.0)
`DBASE_RDONLY` (int)
  Ouvre une base de données en lecture seule. Utilisé avec dbase_open(). (Disponible à partir de dbase 7.0.0)
`DBASE_RDWR` (int)
  Ouvre une base de données en lecture et écriture. Utilisé avec dbase_open(). (Disponible à partir de dbase 7.0.0)
`DBASE_TYPE_DBASE` (int)
  Crée une base de données style dBASE. Utilisé avec dbase_create(). (Disponible à partir de dbase 7.0.0)
`DBASE_TYPE_FOXPRO` (int)
  Crée une base de données style FoxPro. Utilisé avec dbase_create(). (Disponible à partir de dbase 7.0.0)

# Fonctions dBase

## Exemples

La plupart des exemples de cette documentation nécessitent une base de données dBase. Nous utiliserons /tmp/test.dbf qui est créée dans l'exemple de la fonction dbase_create().

# dbase_add_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_add_record — Ajoute un enregistrement dans une base de données dBase

### Description

function dbase_add_record(resource `$database`, array `$data`): bool

dbase_add_record() ajoute les données fournies dans la base de données dBase spécifiée.

### Liste de paramètres

`database`

  La ressource de base de données, retournée par dbase_open() ou dbase_create().

`data`

  Un tableau de données indexé. Le nombre d'éléments doit être égal au nombre de champs dans la base de données, sinon la fonction dbase_add_record() échouera.

  > Note:

  > Si l'on utilise dbase_get_record() pour retourner une valeur pour ce paramètre, il ne faut pas oublier de réinitialiser la clé nommée `deleted`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | `database` est maintenant une resource au lieu d'un int.

### Exemples

Exemple #1 Insertion d'un enregistrement dans une base de données dBase

    <?php

    // Ouverture en mode lecture-écriture
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      dbase_add_record($db, array(
        date('Ymd'),
        'Maxim Topolov',
        '23',
        'max@example.com',
        'T'));
      dbase_close($db);
    }

    ?>

### Voir aussi

- dbase_delete_record() - Efface un enregistrement dans une base dBase
- dbase_replace_record() - Remplace un enregistrement dans une base dBase

# dbase_close

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_close — Ferme une base dBase

### Description

function dbase_close(resource `$database`): bool

dbase_close() ferme la base de données correspondant à la ressource `database`.

### Liste de paramètres

`database`

  La ressource de base de données, retournée par dbase_open() ou dbase_create().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | `database` est maintenant une resource au lieu d'un int.

### Exemples

Exemple #1 Ferme un fichier de base de données dBase

    <?php

    // Ouverture en mode lecture-écriture
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
    // Lecture des données ..

    dbase_close($db);
    }

    ?>

### Voir aussi

- dbase_open() - Ouvre une base dBase
- dbase_create() - Crée une base de données dBase

# dbase_create

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_create — Crée une base de données dBase

### Description

function dbase_create(string `$path`, array `$fields`, int `$type` = DBASE_TYPE_DBASE): resource

dbase_create() crée une base de données dBase avec la définition fournie. Si le fichier existe déjà, il n'est pas tronqué. dbase_pack() peut être appelé pour forcer une troncature.

> Note: Cette fonction est affectée par la directive de configuration open_basedir.

### Liste de paramètres

`path`

  Le chemin vers la base de données. Il peut être un chemin relatif ou absolu vers le fichier où dBase stockera les données.

`fields`

  Un tableau de tableaux, chaque tableau décrit le format d'un champ de la base de données. Chaque champ est constitué d'un nom, d'un caractère indiquant le type du champ et optionnellement, une longueur, une précision et un drapeau nullable. Les champs supportés sont énumérés dans la section d'introduction.

  > Note:

  > Les noms des champs sont limités en longueur et ne doivent pas excéder 10 caractères.

`type`

  Le type de base de données à créer. Soit `DBASE_TYPE_DBASE` ou `DBASE_TYPE_FOXPRO`.

### Valeurs de retour

Retourne une ressource de base de données si la base de données a été créée avec succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | Le paramètre `type` a été ajouté.
PECL dbase 7.0.0 | Le type de retour de `dbase_identifier` est désormais une resource au lieu d'un int.

### Exemples

Exemple #1 Création d'un fichier de base de données dBase

    <?php

    // Base de données "definition"
    $def = array(
      array("date",     "D"),
      array("name",     "C",  50),
      array("age",      "N",   3, 0),
      array("email",    "C", 128),
      array("ismember", "L")
    );

    // Création
    if (!dbase_create('/tmp/test.dbf', $def)) {
      echo "Erreur, impossible de créer la base de données\n";
    }

    ?>

### Voir aussi

- dbase_open() - Ouvre une base dBase
- dbase_close() - Ferme une base dBase

# dbase_delete_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_delete_record — Efface un enregistrement dans une base dBase

### Description

function dbase_delete_record(resource `$database`, int `$number`): bool

Marque l'enregistrement donné pour être effacé de la base de données.

> Note:

> Pour effacer réellement l'enregistrement de la base de données, il faut appeler la fonction dbase_pack().

### Liste de paramètres

`database`

  La ressource de base de données, retournée par dbase_open() ou dbase_create().

`number`

  Un entier compris entre 1 et le nombre maximal d'enregistrements dans la base de données (tel que retourné par la fonction dbase_numrecords()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | `database` est maintenant une resource au lieu d'un int.

### Voir aussi

- dbase_add_record() - Ajoute un enregistrement dans une base de données dBase
- dbase_replace_record() - Remplace un enregistrement dans une base dBase

# dbase_get_header_info

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_header_info — Récupère des informations d'en-tête d'une base de données dBase

### Description

function dbase_get_header_info(resource `$database`): array

dbase_get_header_info() retourne des informations sur la structure des colonnes de la base de données référencée par la ressource `database`.

### Liste de paramètres

`database`

  La ressource de base de données, retournée par dbase_open() ou dbase_create().

### Valeurs de retour

Un tableau indexé avec une entrée pour chaque colonne de la base de données. L'index du tableau commence à 0.

Chaque élément du tableau contient un tableau associatif contenant les informations sur les colonnes, comme décrit ici :

name
  Le nom de la colonne
type
  Le nom lisible du type de la colonne (c.-à-d. date, booléen, etc.) Les types de champs supportés sont énumérés dans la section d'introduction.
length
  Le nombre d'octets que cette colonne peut contenir
precision
  Le nombre de décimales pour la colonne
format
  Un format printf() suggéré pour la colonne
offset
  La position de la colonne depuis le début de la ligne

Si les informations d'en-tête de la base de données ne peuvent pas être lues, `false` est retourné.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | `database` est maintenant une resource au lieu d'un int.

### Exemples

Exemple #1 Affiche les informations d'en-tête pour un fichier de base de données dBase

    <?php
    // Chemin vers le fichier dBase
    $db_path = "/tmp/test.dbf";

    // Ouvre le fichier dBase
    $dbh = dbase_open($db_path, 0)
    or die("Erreur ! Impossible d'ouvrir le fichier dBase '$db_path'.");

    // Récupération des informations des colonnes
    $column_info = dbase_get_header_info($dbh);

    // Affichage des informations
    print_r($column_info);
    ?>

# dbase_get_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record — Lit un enregistrement dans une base dBase

### Description

function dbase_get_record(resource `$database`, int `$number`): array

dbase_get_record() retourne les données de l'enregistrement `number` dans un tableau.

### Liste de paramètres

`database`

  La ressource de base de données, retournée par dbase_open() ou dbase_create().

`number`

  L'index de l'enregistrement entre `1` et `dbase_numrecords($dbase_identifier)`.

### Valeurs de retour

Un tableau indexé avec l'enregistrement. Ce tableau inclut également une clé associée nommée `deleted` qui est définie à 1 si l'enregistrement a été marqué pour effacement (voir dbase_delete_record()).

Chaque champs est converti en type PHP approprié, sauf :

- Les dates sont conservées comme chaînes de caractères.
- Les valeurs DateTime sont converties en chaînes de caractères.
- Les entiers en dehors de l'intervalle `PHP_INT_MIN`..`PHP_INT_MAX` sont retournés comme chaînes de caractères.
- Avant dbase 7.0.0, les booléens (`L`) étaient convertis en `1` ou `0`.

En cas d'erreur, dbase_get_record() retourne `false`.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | `database` est maintenant une resource au lieu d'un int.

### Voir aussi

- dbase_get_record_with_names() - Lit un enregistrement dans une base dBase, sous la forme d'un tableau associatif

# dbase_get_record_with_names

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record_with_names — Lit un enregistrement dans une base dBase, sous la forme d'un tableau associatif

### Description

function dbase_get_record_with_names(resource `$database`, int `$number`): array

Récupère un enregistrement d'une base de données dBase en tant qu'un tableau associatif.

### Liste de paramètres

`database`

  La ressource de base de données, retournée par dbase_open() ou dbase_create().

`number`

  L'index de l'enregistrement entre `1` et `dbase_numrecords($dbase_identifier)`.

### Valeurs de retour

L'enregistrement, sous la forme d'un tableau associatif. Ceci inclut également une clé nommée `deleted` qui est définie à 1 si l'enregistrement a été marqué pour effacement (voir la fonction dbase_delete_record()). Par conséquent il n'est pas possible de récupérer la valeur d'un champ nommé `deleted` avec cette fonction.

Chaque champs est converti en type PHP approprié, sauf :

- Les dates sont conservées comme chaînes de caractères.
- Les valeurs DateTime sont converties en chaînes de caractères.
- Les entiers en dehors de l'intervalle `PHP_INT_MIN`..`PHP_INT_MAX` sont retournés comme chaînes de caractères.
- Avant dbase 7.0.0, les booléens (`L`) étaient convertis en `1` ou `0`.

En cas d'erreur, dbase_get_record_with_names() retourne `false`.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | `database` est maintenant une resource au lieu d'un int.

### Exemples

Exemple #1 Liste tous les membres enregistrés dans la base de données

    <?php
    // Ouverture en mode lecture seule
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
        $row = dbase_get_record_with_names($db, $i);
        if ($row['ismember'] == 1) {
          echo "Membre #$i: " . trim($row['name']) . "\n";
        }
      }
    }
    ?>

### Voir aussi

- dbase_get_record() - Lit un enregistrement dans une base dBase

# dbase_numfields

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numfields — Compte le nombre de champs d'une base dBase

### Description

function dbase_numfields(resource `$database`): int

Retourne le nombre de champs (colonnes) de la base de données spécifiée.

> Note:

> Les champs sont numérotés de 0 à `dbase_numfields($db)-1`, tandis que les enregistrements sont numérotés de 1 à `dbase_numrecords($db)`.

### Liste de paramètres

`database`

  La ressource de base de données, retournée par dbase_open() ou dbase_create().

### Valeurs de retour

Le nombre de champs de la base de données, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | `database` est maintenant une resource au lieu d'un int.

### Exemples

Exemple #1 Exemple avec dbase_numfields()

    <?php

    $rec = dbase_get_record($db, $recno);
    $nf  = dbase_numfields($db);
    for ($i = 0; $i < $nf; $i++) {
      echo $rec[$i], "\n";
    }

    ?>

### Voir aussi

- dbase_numrecords() - Compte le nombre d'enregistrements dans une base dBase

# dbase_numrecords

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numrecords — Compte le nombre d'enregistrements dans une base dBase

### Description

function dbase_numrecords(resource `$database`): int

Récupère le nombre d'enregistrements (lignes) dans la base spécifiée.

> Note:

> Les enregistrements marqués comme supprimés sont aussi comptés.

> Note:

> Les numéros de champ sont numérotés de 0 à `dbase_numfields($db)-1`, tandis que les numéros d'enregistrements sont numérotés de 1 à `dbase_numrecords($db)`.

### Liste de paramètres

`database`

  Une ressource de base de données, retournée par dbase_open() ou dbase_create().

### Valeurs de retour

Le nombre d'enregistrements dans la base de données ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | Le paramètre `database` est maintenant une resource au lieu d'un int.

### Exemples

Exemple #1 Lecture de tous les enregistrements de la base de données

    <?php

    // Ouverture en mode lecture seule
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
        $record_numbers = dbase_numrecords($db);
        for ($i = 1; $i <= $record_numbers; $i++) {
            $record = dbase_get_record($db, $i);
            if (!$record['deleted']) {
                // faire quelque chose avec l'enregistrement $record
            } else {
                // faire quelque chose avec l'enregistrement supprimé $record ou l'ignorer
            }
        }
    }

    ?>

### Voir aussi

- dbase_numfields() - Compte le nombre de champs d'une base dBase

# dbase_open

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_open — Ouvre une base dBase

### Description

function dbase_open(string `$path`, int `$mode`): resource|false

dbase_open() ouvre une base de données dBase avec un mode d'accès donné.

> Note: Cette fonction est affectée par la directive de configuration open_basedir.

### Liste de paramètres

`path`

  Le chemin vers la base de données. Il peut être un chemin relatif ou absolu vers le fichier où dBase stockera les données.

`mode`

  Un entier correspondant à celui utilisé pour l'appel système open() (Typiquement, 0 signifie lecture seule, 1 signifie écriture seule, et 2 signifie lecture et écriture).

  > Note:

  > Il n'est pas possible d'ouvrir un fichier dBase en mode écriture seule, car la fonction échouera lors de la lecture des informations d'en-têtes et donc, l'on ne peut pas utiliser 1 comme `mode`.

  À partir de dbase 7.0.0 `DBASE_RDONLY` et `DBASE_RDWR` peuvent être utilisés, respectivement, pour définir le `mode`.

### Valeurs de retour

Retourne une ressource de base de données en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | La valeur retournée est maintenant une resource au lieu d'un int.

### Exemples

Exemple #1 Ouverture d'un fichier de base de données dBase

    <?php

    // Ouverture en lecture seule
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
    // lecture des données ..

    dbase_close($db);
    }

    ?>

### Voir aussi

- dbase_create() - Crée une base de données dBase
- dbase_close() - Ferme une base dBase

# dbase_pack

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_pack — Compacte une base dBase

### Description

function dbase_pack(resource `$database`): bool

Compacte la base de données spécifiée en supprimant définitivement tous les enregistrements marqués pour l'effacement à l'aide de dbase_delete_record(). Il est à noter que le fichier sera tronqué après un compactage réussi (contrairement à la commande PACK de dBASE III).

### Liste de paramètres

`database`

  La ressource de base de données, retournée par dbase_open() ou dbase_create().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | `database` est maintenant une resource au lieu d'un int.

### Exemples

Exemple #1 Vide une base de données dBase

    <?php

    // Ouverture en mode lecture-écriture
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
        dbase_delete_record($db, $i);
      }
    // Compacte la base de données
    dbase_pack($db);
    }

    ?>

### Voir aussi

- dbase_delete_record() - Efface un enregistrement dans une base dBase

# dbase_replace_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_replace_record — Remplace un enregistrement dans une base dBase

### Description

function dbase_replace_record(resource `$database`, array `$data`, int `$number`): bool

Remplace l'enregistrement passé dans la base de données avec les données fournies.

### Liste de paramètres

`database`

  La ressource de base de données, retournée par dbase_open() ou dbase_create().

`data`

  Un tableau indexé des données. Le nombre d'éléments doit être égal au nombre de champs dans la base de données, sinon la fonction dbase_replace_record() échouera.

  > Note:

  > Si l'on utilise dbase_get_record() pour retourner la valeur de ce paramètre, il ne faut pas oublier de réinitialiser la clé nommée `deleted`.

`number`

  Un entier entre 1 et le nombre total d'enregistrements dans la base de données (comme retourné par la fonction dbase_numrecords()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL dbase 7.0.0 | Le paramètre `database` est maintenant une resource au lieu d'un int.

### Exemples

Exemple #1 Mise à jour d'un enregistrement dans une base de données

    <?php

    // Ouverture en mode lecture-écriture
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      // Récupération de l'ancienne ligne
      $row = dbase_get_record_with_names($db, 1);

      // Supprime l'entrée effacée
      unset($row['deleted']);

      // Convertir la ligne en un tableau indexé
      $row = array_values($row);

      // Mise à jour de la date du champ avec le timestamp courant
      $row['date'] = date('Ymd');

      // Remplacer l'enregistrement
      dbase_replace_record($db, $row, 1);
      dbase_close($db);
    }

    ?>

### Notes

> Note:

> Les résultats de champs booléen sont des éléments de valeur de type entier (`0` ou `1`) quand récupérés via dbase_get_record() ou dbase_get_record_with_names(). Si elles sont réécrites, ceci fera que la valeur deviendra `0`, des précautions doivent donc être prises pour ajuster correctement les valeurs.

### Voir aussi

- dbase_add_record() - Ajoute un enregistrement dans une base de données dBase
- dbase_delete_record() - Efface un enregistrement dans une base dBase

## Sommaire

- dbase_add_record — Ajoute un enregistrement dans une base de données dBase
- dbase_close — Ferme une base dBase
- dbase_create — Crée une base de données dBase
- dbase_delete_record — Efface un enregistrement dans une base dBase
- dbase_get_header_info — Récupère des informations d'en-tête d'une base de données dBase
- dbase_get_record — Lit un enregistrement dans une base dBase
- dbase_get_record_with_names — Lit un enregistrement dans une base dBase, sous la forme d'un tableau associatif
- dbase_numfields — Compte le nombre de champs d'une base dBase
- dbase_numrecords — Compte le nombre d'enregistrements dans une base dBase
- dbase_open — Ouvre une base dBase
- dbase_pack — Compacte une base dBase
- dbase_replace_record — Remplace un enregistrement dans une base dBase

- Installation/Configuration
  - Installation
  - Types de ressources
- Constantes pré-définies
- Fonctions dBase
  - dbase_add_record — Ajoute un enregistrement dans une base de données dBase
  - dbase_close — Ferme une base dBase
  - dbase_create — Crée une base de données dBase
  - dbase_delete_record — Efface un enregistrement dans une base dBase
  - dbase_get_header_info — Récupère des informations d'en-tête d'une base de données dBase
  - dbase_get_record — Lit un enregistrement dans une base dBase
  - dbase_get_record_with_names — Lit un enregistrement dans une base dBase, sous la forme d'un tableau associatif
  - dbase_numfields — Compte le nombre de champs d'une base dBase
  - dbase_numrecords — Compte le nombre d'enregistrements dans une base dBase
  - dbase_open — Ouvre une base dBase
  - dbase_pack — Compacte une base dBase
  - dbase_replace_record — Remplace un enregistrement dans une base dBase

# Firebird/InterBase

# Introduction

Avertissement

Cette extension est considérée comme morte et non maintenue. Cependant, le code source de cette extension est toujours disponible dans le GIT de PECL : » https://github.com/php/pecl-database-interbase.

Firebird est une base de données relationnelle offrant la plupart des fonctionnalités décrites dans la norme ISO SQL-2003, qui fonctionne sous environnements Linux, Windows, et la plupart des systèmes Unix. Firebird offre une excellente simultanéité, de hautes performances et un langage efficace pour l'écriture des procédures stockées et des déclencheurs. Il est utilisé sur des systèmes de production depuis 1981.

Interbase est le nom de la variante commerciale de cette base de données créée par Embarcadero/Inprise. Pour plus d'informations sur Interbase, allez à » http://www.embarcadero.com/products/interbase.

Firebird est un projet commercialement indépendant (fondation) de programmeurs C++, conseillers techniques, supportant le développement et assurant la compatibilité multi-plate-forme de la base de données relationnelle basée sur le code source offert par Inprise Corp. (maintenant connu sous le nom de Embarcadero) sous la licence "InterBase Public License v.1.0 le 25 Juillet 2000". Pour plus d'informations sur Firebird, allez à » http://www.firebirdsql.org/.

> Note: Cette extension a été déplacée dans le module » PECL et ne sera plus intégrée dans PHP à partir de PHP 7.4.0 Cette extension supporte Interbase version 6 et suivantes ainsi que Firebird version 2 et suivantes.

# Installation/Configuration

## Sommaire

- Installation
- Configuration à l'exécution

## Installation

Cette extension a été déplacée dans le module » PECL et ne sera plus intégrée dans PHP à partir de PHP 7.4.0

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://github.com/FirebirdSQL/php-firebird.

Pour activer le support de Firebird/InterBase, il faut compiler PHP avec l'option --with-interbase[=DIR], où DIR est le dossier d'installation de Firebird/InterBase (qui est par défaut, /usr).

> Note: Note aux utilisateurs Win32/Win64
> Afin de faire fonctionner cette extension, quelques bibliothèques DLL doivent être disponibles via le PATH du système Windows. Lisez la F.A.Q intitulée "Comment ajouter mon dossier PHP à mon PATH Windows" pour plus d'informations. Le fait de copier les bibliothèques DLL depuis le dossier PHP dans le dossier système Windows fonctionne également (car le dossier système est par défaut dans le PATH système), mais cette méthode n'est pas recommandée. Cette extension nécessite que les fichiers suivants se trouvent dans le PATH : fbclient.dll,gds32.dll

> Lors de l'installation d'un serveur Firebird/InterBase sur la même machine que celle faisant fonctionner PHP, il faudra déjà cette bibliothèque et fbclient.dll,gds32.dll (gds32.dll est généré depuis l'installeur) devrait déjà être dans le PATH.

## Configuration à l'exécution

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

Options de configuration iBase
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
ibase.allow_persistent | "1" | `INI_SYSTEM` |
ibase.max_persistent | "-1" | `INI_SYSTEM` |
ibase.max_links | "-1" | `INI_SYSTEM` |
ibase.default_db | NULL | `INI_SYSTEM` |
ibase.default_user | NULL | `INI_ALL` |
ibase.default_password | NULL | `INI_ALL` |
ibase.default_charset | NULL | `INI_ALL` |
ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | `INI_ALL` |
ibase.dateformat | "%Y-%m-%d" | `INI_ALL` |
ibase.timeformat | "%H:%M:%S" | `INI_ALL` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`ibase.allow_persistent` bool
  Accepte ou non les connexions persistantes à Firebird/Interbase.
`ibase.max_persistent` int
  Le nombre maximal de connexions persistantes Firebird/Interbase par processus. Les nouvelles connexions avec ibase_pconnect() ne seront pas persistantes si ce nombre maximal est atteint.
`ibase.max_links` int
  Le nombre maximal de connexions Firebird/Interbase par processus, incluant les connexions persistantes.
`ibase.default_db` string
  Le nom de la base de données par défaut lorsque ibase_[p]connect() est appelé sans base de données spécifique. Si cette valeur est définie et que le mode sécurisé (safe mode) SQL est activé, aucune connexion à d'autres bases de données que celle-ci ne sera autorisée.
`ibase.default_user` string
  Le nom d'utilisateur utilisé lors de la connexion à la base de données lorsqu'aucun n'est spécifié.
`ibase.default_password` string
  Le mot de passe utilisé lors de la connexion à la base de données lorsqu'aucun n'est spécifié.
`ibase.default_charset` string
  Le jeu de caractères utilisé lors de la connexion à la base de données lorsqu'aucun n'est spécifié.
`ibase.timestampformat` string
`ibase.dateformat` string
`ibase.timeformat` string
  Ces directives sont utilisées pour définir les formats de dates et d'heures qui seront utilisés lorsque des dates/heures seront retournées d'un jeu de résultats, ou lors de traitement d'arguments en paramètres dates/heures.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Les constantes suivantes peuvent être passées à ibase_trans() pour spécifier le comportement des transactions.

Constantes Firebird/InterBase
Constante | Description
--- | ---
IBASE_DEFAULT | Définit le comportement par défaut. Ce comportement est déterminé par la bibliothèque cliente, qui est définie comme IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT dans la plupart des cas.
IBASE_READ | Démarre une transaction en lecture seule
IBASE_WRITE | Démarre une transaction en lecture / écriture
IBASE_CONSISTENCY | Démarre une transaction avec le niveau d'isolation défini à 'consistency', ce qui signifie que la transaction courante ne peut lire depuis des tables qui ont été modifiées par d'autres transactions.
IBASE_CONCURRENCY | Démarre une transaction avec le niveau d'isolation défini à 'concurrency' (ou 'snapshot'), ce qui signifie que la transaction peut accéder à toutes les tables, mais ne peut pas voir les modifications apportées par d'autres transactions une fois que la transaction a débuté.
IBASE_COMMITTED | Démarre une transaction avec le niveau d'isolation défini à 'read committed'. Ce flag doit être associé avec soit la constante `IBASE_REC_VERSION`, soit la constante `IBASE_REC_NO_VERSION`. Ce niveau d'isolation permet d'accéder aux modifications effectuées après le début de la transaction. Si la constante `IBASE_REC_NO_VERSION` est spécifiée, seulement la dernière version des lignes pourra être lue. Si la constante `IBASE_REC_VERSION` est spécifiée, une ligne peut toujours être lue lorsqu'une modification est en attente dans une transaction concurrente.
IBASE_WAIT | Indique que la transaction peut attendre, puis réessayer lorsqu'un conflit apparaît.
IBASE_NOWAIT | Indique que la transaction échouera immédiatement lorsqu'un conflit apparaît.

Les constantes suivantes peuvent être passées aux fonctions ibase_fetch_row(), ibase_fetch_assoc() ou ibase_fetch_object() pour spécifier leurs comportements.

Constantes Firebird/InterBase
Constante | Description
--- | ---
IBASE_FETCH_BLOBS | Aussi disponible sous le nom `IBASE_TEXT` pour des raisons de compatibilité ascendante. Permet de lire le contenu d'un BLOB "inline" au lieu de le parcourir en utilisant un identifiant de BLOB.
IBASE_FETCH_ARRAYS | Permet de lire un tableau "inline". Sinon, les identifiants de tableaux sont retournés. Les identifiants de tableaux ne peuvent être passés uniquement comme arguments aux requêtes INSERT, car aucune fonction pour traiter les identifiants de tableaux n'est actuellement disponible.
IBASE_UNIXTIME | Permet de retourner les champs date et heure non pas comme des chaînes de caractères mais comme des timestamps UNIX (le nombre de secondes depuis l'époque UNIX, qui est le 1-Jan-1970 0:00 UTC). Cela peut être problématique si l'on utilise des dates antérieures à 1970 sur quelques systèmes.

Les constantes suivantes sont utilisées pour passer des requêtes et des options à l'API (ibase_server_info(), ibase_db_info(), ibase_backup(), ibase_restore() et ibase_maintain_db()). Il est possible de consulter le manuel Firebird/InterBase pour plus d'informations sur la signification de ces options.

`IBASE_BKP_IGNORE_CHECKSUMS`
  Options pour ibase_backup()
`IBASE_BKP_IGNORE_LIMBO`
  Options pour ibase_backup()
`IBASE_BKP_METADATA_ONLY`
  Options pour ibase_backup()
`IBASE_BKP_NO_GARBAGE_COLLECT`
  Options pour ibase_backup()
`IBASE_BKP_OLD_DESCRIPTIONS`
  Options pour ibase_backup()
`IBASE_BKP_NON_TRANSPORTABLE`
  Options pour ibase_backup()
`IBASE_BKP_CONVERT`
  Options pour ibase_backup()
`IBASE_RES_DEACTIVATE_IDX`
  Options pour ibase_restore()
`IBASE_RES_NO_SHADOW`
  Options pour ibase_restore()
`IBASE_RES_NO_VALIDITY`
  Options pour ibase_restore()
`IBASE_RES_ONE_AT_A_TIME`
  Options pour ibase_restore()
`IBASE_RES_REPLACE`
`IBASE_RES_CREATE`
  Options pour ibase_restore()
`IBASE_RES_USE_ALL_SPACE`
  Options pour ibase_restore()
`IBASE_PRP_PAGE_BUFFERS`
`IBASE_PRP_SWEEP_INTERVAL`
`IBASE_PRP_SHUTDOWN_DB`
`IBASE_PRP_DENY_NEW_TRANSACTIONS`
`IBASE_PRP_DENY_NEW_ATTACHMENTS`
`IBASE_PRP_RESERVE_SPACE`
`IBASE_PRP_RES_USE_FULL`
`IBASE_PRP_RES`
`IBASE_PRP_WRITE_MODE`
`IBASE_PRP_WM_ASYNC`
`IBASE_PRP_WM_SYNC`
`IBASE_PRP_ACCESS_MODE`
`IBASE_PRP_AM_READONLY`
`IBASE_PRP_AM_READWRITE`
`IBASE_PRP_SET_SQL_DIALECT`
`IBASE_PRP_ACTIVATE`
`IBASE_PRP_DB_ONLINE`
`IBASE_RPR_CHECK_DB`
`IBASE_RPR_IGNORE_CHECKSUM`
`IBASE_RPR_KILL_SHADOWS`
`IBASE_RPR_MEND_DB`
`IBASE_RPR_VALIDATE_DB`
`IBASE_RPR_FULL`
`IBASE_RPR_SWEEP_DB`
  Options de ibase_maintain_db()
`IBASE_STS_DATA_PAGES`
`IBASE_STS_DB_LOG`
`IBASE_STS_HDR_PAGES`
`IBASE_STS_IDX_PAGES`
`IBASE_STS_SYS_RELATIONS`
  Options de ibase_db_info()
`IBASE_SVC_SERVER_VERSION`
  Options pour ibase_server_info()
`IBASE_SVC_IMPLEMENTATION`
  Options pour ibase_server_info()
`IBASE_SVC_GET_ENV`
  Options pour ibase_server_info()
`IBASE_SVC_GET_ENV_LOCK`
`IBASE_SVC_GET_ENV_MSG`
`IBASE_SVC_USER_DBPATH`
`IBASE_SVC_SVR_DB_INFO`
`IBASE_SVC_GET_USERS`
  Options pour ibase_server_info()

# Fonctions Firebird/InterBase

# fbird_add_user

(PHP 5, PHP 7 < 7.4.0)

fbird_add_user — Alias de ibase_add_user()

### Description

Cette fonction est un alias de : ibase_add_user().

### Voir aussi

- fbird_modify_user() - Alias de ibase_modify_user
- fbird_delete_user() - Alias de ibase_delete_user

# fbird_affected_rows

(PHP 5, PHP 7 < 7.4.0)

fbird_affected_rows — Alias de ibase_affected_rows()

### Description

Cette fonction est un alias de : ibase_affected_rows().

### Voir aussi

- fbird_query() - Alias de ibase_query
- fbird_execute() - Alias de ibase_execute

# fbird_backup

(PHP 5, PHP 7 < 7.4.0)

fbird_backup — Alias de ibase_backup()

### Description

Cette fonction est un alias de : ibase_backup().

# fbird_blob_add

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_add — Alias de ibase_blob_add()

### Description

Cette fonction est un alias de : ibase_blob_add().

### Voir aussi

- fbird_blob_cancel() - Annule la création d'un blob
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_create() - Alias de ibase_blob_create
- fbird_blob_import() - Alias de ibase_blob_import

# fbird_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_cancel — Annule la création d'un blob

### Description

function fbird_blob_cancel(resource `$blob_handle`): bool

Cette fonction jetera un BLOB s'il n'a pas encore été fermé par fbird_blob_close().

### Liste de paramètres

`blob_handle`
  Un gestionnaire de BLOB ouvert avec fbird_blob_create().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_create() - Alias de ibase_blob_create
- fbird_blob_import() - Alias de ibase_blob_import

# fbird_blob_close

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_close — Alias de ibase_blob_close()

### Description

Cette fonction est un alias de : ibase_blob_close().

### Voir aussi

- fbird_blob_create() - Alias de ibase_blob_create
- fbird_blob_cancel() - Annule la création d'un blob
- fbird_blob_open() - Alias de ibase_blob_open
- fbird_blob_import() - Alias de ibase_blob_import

# fbird_blob_create

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_create — Alias de ibase_blob_create()

### Description

Cette fonction est un alias de : ibase_blob_create().

### Voir aussi

- fbird_blob_add() - Alias de ibase_blob_add
- fbird_blob_cancel() - Annule la création d'un blob
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_import() - Alias de ibase_blob_import

# fbird_blob_echo

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_echo — Alias de ibase_blob_echo()

### Description

Cette fonction est un alias de : ibase_blob_echo().

### Voir aussi

- fbird_blob_open() - Alias de ibase_blob_open
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_get() - Alias de ibase_blob_get

# fbird_blob_get

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_get — Alias de ibase_blob_get()

### Description

Cette fonction est un alias de : ibase_blob_get().

### Voir aussi

- fbird_blob_open() - Alias de ibase_blob_open
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_echo() - Alias de ibase_blob_echo

# fbird_blob_import

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_import — Alias de ibase_blob_import()

### Description

Cette fonction est un alias de : ibase_blob_import().

### Voir aussi

- fbird_blob_add() - Alias de ibase_blob_add
- fbird_blob_cancel() - Annule la création d'un blob
- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_create() - Alias de ibase_blob_create

# fbird_blob_info

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_info — Alias de ibase_blob_info()

### Description

Cette fonction est un alias de : ibase_blob_info().

# fbird_blob_open

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_open — Alias de ibase_blob_open()

### Description

Cette fonction est un alias de : ibase_blob_open().

### Voir aussi

- fbird_blob_close() - Alias de ibase_blob_close
- fbird_blob_echo() - Alias de ibase_blob_echo
- fbird_blob_get() - Alias de ibase_blob_get

# fbird_close

(PHP 5, PHP 7 < 7.4.0)

fbird_close — Alias de ibase_close()

### Description

Cette fonction est un alias de : ibase_close().

### Voir aussi

- fbird_connect() - Alias de ibase_connect
- fbird_pconnect() - Alias de ibase_pconnect

# fbird_commit

(PHP 5, PHP 7 < 7.4.0)

fbird_commit — Alias de ibase_commit()

### Description

Cette fonction est un alias de : ibase_commit().

# fbird_commit_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_commit_ret — Alias de ibase_commit_ret()

### Description

Cette fonction est un alias de : ibase_commit_ret().

# fbird_connect

(PHP 5, PHP 7 < 7.4.0)

fbird_connect — Alias de ibase_connect()

### Description

Cette fonction est un alias de : ibase_connect().

### Voir aussi

- fbird_pconnect() - Alias de ibase_pconnect
- fbird_close() - Alias de ibase_close

# fbird_db_info

(PHP 5, PHP 7 < 7.4.0)

fbird_db_info — Alias de ibase_db_info()

### Description

Cette fonction est un alias de : ibase_db_info().

# fbird_delete_user

(PHP 5, PHP 7 < 7.4.0)

fbird_delete_user — Alias de ibase_delete_user()

### Description

Cette fonction est un alias de : ibase_delete_user().

### Voir aussi

- fbird_add_user() - Alias de ibase_add_user
- fbird_modify_user() - Alias de ibase_modify_user

# fbird_drop_db

(PHP 5, PHP 7 < 7.4.0)

fbird_drop_db — Alias de ibase_drop_db()

### Description

Cette fonction est un alias de : ibase_drop_db().

### Voir aussi

- fbird_connect() - Alias de ibase_connect
- fbird_pconnect() - Alias de ibase_pconnect

# fbird_errcode

(PHP 5, PHP 7 < 7.4.0)

fbird_errcode — Alias de ibase_errcode()

### Description

Cette fonction est un alias de : ibase_errcode().

### Voir aussi

- fbird_errmsg() - Alias de ibase_errmsg

# fbird_errmsg

(PHP 5, PHP 7 < 7.4.0)

fbird_errmsg — Alias de ibase_errmsg()

### Description

Cette fonction est un alias de : ibase_errmsg().

### Voir aussi

- fbird_errcode() - Alias de ibase_errcode

# fbird_execute

(PHP 5, PHP 7 < 7.4.0)

fbird_execute — Alias de ibase_execute()

### Description

Cette fonction est un alias de : ibase_execute().

### Voir aussi

- fbird_query() - Alias de ibase_query

# fbird_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_assoc — Alias de ibase_fetch_assoc()

### Description

Cette fonction est un alias de : ibase_fetch_assoc().

### Voir aussi

- fbird_fetch_row() - Alias de ibase_fetch_row
- fbird_fetch_object() - Alias de ibase_fetch_object

# fbird_fetch_object

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_object — Alias de ibase_fetch_object()

### Description

Cette fonction est un alias de : ibase_fetch_object().

### Voir aussi

- fbird_fetch_row() - Alias de ibase_fetch_row
- fbird_fetch_assoc() - Alias de ibase_fetch_assoc

# fbird_fetch_row

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_row — Alias de ibase_fetch_row()

### Description

Cette fonction est un alias de : ibase_fetch_row().

### Voir aussi

- fbird_fetch_assoc() - Alias de ibase_fetch_assoc
- fbird_fetch_object() - Alias de ibase_fetch_object

# fbird_field_info

(PHP 5, PHP 7 < 7.4.0)

fbird_field_info — Alias de ibase_field_info()

### Description

Cette fonction est un alias de : ibase_field_info().

### Voir aussi

- fbird_num_fields() - Alias de ibase_num_fields

# fbird_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_free_event_handler — Alias de ibase_free_event_handler()

### Description

Cette fonction est un alias de : ibase_free_event_handler().

### Voir aussi

- fbird_set_event_handler() - Alias de ibase_set_event_handler

# fbird_free_query

(PHP 5, PHP 7 < 7.4.0)

fbird_free_query — Alias de ibase_free_query()

### Description

Cette fonction est un alias de : ibase_free_query().

# fbird_free_result

(PHP 5, PHP 7 < 7.4.0)

fbird_free_result — Alias de ibase_free_result()

### Description

Cette fonction est un alias de : ibase_free_result().

# fbird_gen_id

(PHP 5, PHP 7 < 7.4.0)

fbird_gen_id — Alias de ibase_gen_id()

### Description

Cette fonction est un alias de : ibase_gen_id().

# fbird_maintain_db

(PHP 5, PHP 7 < 7.4.0)

fbird_maintain_db — Alias de ibase_maintain_db()

### Description

Cette fonction est un alias de : ibase_maintain_db().

# fbird_modify_user

(PHP 5, PHP 7 < 7.4.0)

fbird_modify_user — Alias de ibase_modify_user()

### Description

Cette fonction est un alias de : ibase_modify_user().

### Voir aussi

- fbird_add_user() - Alias de ibase_add_user
- fbird_delete_user() - Alias de ibase_delete_user

# fbird_name_result

(PHP 5, PHP 7 < 7.4.0)

fbird_name_result — Alias de ibase_name_result()

### Description

Cette fonction est un alias de : ibase_name_result().

### Voir aussi

- fbird_prepare() - Alias de ibase_prepare
- fbird_execute() - Alias de ibase_execute

# fbird_num_fields

(PHP 5, PHP 7 < 7.4.0)

fbird_num_fields — Alias de ibase_num_fields()

### Description

Cette fonction est un alias de : ibase_num_fields().

### Voir aussi

- fbird_field_info() - Alias de ibase_field_info

# fbird_num_params

(PHP 5, PHP 7 < 7.4.0)

fbird_num_params — Alias de ibase_num_params()

### Description

Cette fonction est un alias de : ibase_num_params().

### Voir aussi

- fbird_prepare() - Alias de ibase_prepare
- fbird_param_info() - Alias de ibase_param_info

# fbird_param_info

(PHP 5, PHP 7 < 7.4.0)

fbird_param_info — Alias de ibase_param_info()

### Description

Cette fonction est un alias de : ibase_param_info().

### Voir aussi

- fbird_field_info() - Alias de ibase_field_info
- fbird_num_params() - Alias de ibase_num_params

# fbird_pconnect

(PHP 5, PHP 7 < 7.4.0)

fbird_pconnect — Alias de ibase_pconnect()

### Description

Cette fonction est un alias de : ibase_pconnect().

### Voir aussi

- fbird_close() - Alias de ibase_close
- fbird_connect() - Alias de ibase_connect

# fbird_prepare

(PHP 5, PHP 7 < 7.4.0)

fbird_prepare — Alias de ibase_prepare()

### Description

Cette fonction est un alias de : ibase_prepare().

# fbird_query

(PHP 5, PHP 7 < 7.4.0)

fbird_query — Alias de ibase_query()

### Description

Cette fonction est un alias de : ibase_query().

### Voir aussi

- fbird_errmsg() - Alias de ibase_errmsg
- fbird_fetch_row() - Alias de ibase_fetch_row
- fbird_fetch_object() - Alias de ibase_fetch_object
- fbird_free_result() - Alias de ibase_free_result

# fbird_restore

(PHP 5, PHP 7 < 7.4.0)

fbird_restore — Alias de ibase_restore()

### Description

Cette fonction est un alias de : ibase_restore().

# fbird_rollback

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback — Alias de ibase_rollback()

### Description

Cette fonction est un alias de : ibase_rollback().

# fbird_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback_ret — Alias de ibase_rollback_ret()

### Description

Cette fonction est un alias de : ibase_rollback_ret().

# fbird_server_info

(PHP 5, PHP 7 < 7.4.0)

fbird_server_info — Alias de ibase_server_info()

### Description

Cette fonction est un alias de : ibase_server_info().

# fbird_service_attach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_attach — Alias de ibase_service_attach()

### Description

Cette fonction est un alias de : ibase_service_attach().

# fbird_service_detach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_detach — Alias de ibase_service_detach()

### Description

Cette fonction est un alias de : ibase_service_detach().

# fbird_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_set_event_handler — Alias de ibase_set_event_handler()

### Description

Cette fonction est un alias de : ibase_set_event_handler().

### Voir aussi

- fbird_free_event_handler() - Alias de ibase_free_event_handler
- fbird_wait_event() - Alias de ibase_wait_event

# fbird_trans

(PHP 5, PHP 7 < 7.4.0)

fbird_trans — Alias de ibase_trans()

### Description

Cette fonction est un alias de : ibase_trans().

# fbird_wait_event

(PHP 5, PHP 7 < 7.4.0)

fbird_wait_event — Alias de ibase_wait_event()

### Description

Cette fonction est un alias de : ibase_wait_event().

### Voir aussi

- fbird_set_event_handler() - Alias de ibase_set_event_handler
- fbird_free_event_handler() - Alias de ibase_free_event_handler

# ibase_add_user

(PHP 5, PHP 7 < 7.4.0)

ibase_add_user — Ajoute un utilisateur à une base de données de sécurité

### Description

function ibase_add_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Liste de paramètres

`service_handle`
  Le gestionnaire sur le service du serveur de base de données.
`user_name`
  L'identifiant pour le nouvel utilisateur de la base de données.
`password`
  Le mot de passe pour le nouvel utilisateur.
`first_name`
  Le prénom pour le nouvel utilisateur de la base de données.
`middle_name`
  Le deuxième prénom pour le nouvel utilisateur de la base de données.
`last_name`
  Le nom de famille pour le nouvel utilisateur de la base de données.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- ibase_modify_user() - Modifie un utilisateur dans une base de données de sécurité
- ibase_delete_user() - Efface un utilisateur d'une base de données de sécurité

# ibase_affected_rows

(PHP 5, PHP 7 < 7.4.0)

ibase_affected_rows — Retourne le nombre de lignes affectées par la dernière requête iBase

### Description

function ibase_affected_rows(resource `$link_identifier` = ?): int

Retourne le nombre de lignes qui ont été affectées par la dernière requête (INSERT, UPDATE ou DELETE) qui a été exécutée dans le contexte de transaction spécifié par `link_identifier`.

### Liste de paramètres

`link_identifier`
  Un contexte de transaction. Si `link_identifier` est une ressource de connexion, la transaction par défaut est utilisée.

### Valeurs de retour

Retourne le nombre de lignes, sous la forme d'un entier.

### Voir aussi

- ibase_query() - Exécute une requête sur une base iBase
- ibase_execute() - Exécute une requête iBase préparée

# ibase_backup

(PHP 5, PHP 7 < 7.4.0)

ibase_backup — Lance une tâche de sauvegarde dans le gestionnaire de services et retourne immédiatement

### Description

function ibase_backup(
resource `$service_handle`,
string `$source_db`,
string `$dest_file`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Cette fonction transmet les arguments au serveur de base de données (distant). Là, il commence un nouveau processus de sauvegarde. Par conséquent, le résultat ne sera aucune réponse.

### Liste de paramètres

`service_handle`
  Une connexion au serveur de base de données créée précédemment.
`source_db`
  Le chemin absolu vers la base de données sur le serveur de base de données. Il est également possible d'utiliser un alias de base de données.
`dest_file`
  Le chemin absolu vers le fichier de sauvegarde sur le serveur de base de données.
`options`

  Options supplémentaires à transmettre au serveur de base de données pour la sauvegarde. Le paramètre `options` peut être une combinaison des constantes suivantes : `IBASE_BKP_IGNORE_CHECKSUMS`, `IBASE_BKP_IGNORE_LIMBO`, `IBASE_BKP_METADATA_ONLY`, `IBASE_BKP_NO_GARBAGE_COLLECT`, `IBASE_BKP_OLD_DESCRIPTIONS`, `IBASE_BKP_NON_TRANSPORTABLE` ou `IBASE_BKP_CONVERT`. Lire la section à propos des Constantes pré-définies pour plus d'information.

`verbose`
  Étant donné que le processus de sauvegarde est effectué sur le serveur de base de données, l’on n’a aucune chance d’obtenir sa sortie. Cet argument est inutile.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Le processus de sauvegarde étant effectué sur le serveur (distant), cette fonction ne fait que lui transmettre les arguments. Tant que les arguments sont légaux, le résultat ne sera pas `false`.

### Exemples

Exemple #1 Exemple avec ibase_backup()

    <?php

    // S'attacher au serveur par adresse ip et port.
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Débuter le processus de sauvegarde sur le serveur de base de données
    // Sauvegarde la base de données employee en utilisant le chemin complet vers /srv/backup/employees.fbk
    // N'utilise pas d'argument spéciaux
    ibase_backup($service, '/srv/firebird/employees.fdb', '/srv/backup/employees.fbk');

    // Libère la connexion attachée
    ibase_service_detach ($service);
    ?>

Exemple #2 Exemple de ibase_backup() avec des arguments

    <?php

    // S'attacher au serveur par nom et port par défaut
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Débuter le processus de sauvegarde sur le serveur de base de données
    // Sauvegarde la base de données employee en utilisant un alias vers /srv/backup/employees.fbk.
    // Sauvegarde uniquement les métadonnées. Ne crée pas une sauvegarde transportable.
    ibase_backup($service, 'employees.fdb', '/srv/backup/employees.fbk', IBASE_BKP_METADATA_ONLY | IBASE_BKP_NON_TRANSPORTABLE);

    // Libère la connexion attachée
    ibase_service_detach ($service);
    ?>

### Voir aussi

- ibase_restore() - Lance une tâche de restauration dans le gestionnaire de services et retourne immédiatement

# ibase_blob_add

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_add — Ajoute des données dans un BLOB iBase fraîchement créé

### Description

function ibase_blob_add(resource `$blob_handle`, string `$data`): void

ibase_blob_add() ajoute les données `data` dans le BLOB `blob_handle`, créé avec ibase_blob_create().

### Liste de paramètres

`blob_handle`
  Une ressource blob, ouverte avec la fonction ibase_blob_create().
`data`
  Les données à ajouter.

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- ibase_blob_cancel() - Annule la création d'un BLOB iBase
- ibase_blob_close() - Ferme un BLOB iBase
- ibase_blob_create() - Crée un BLOB iBase pour ajouter des données
- ibase_blob_import() - Crée un BLOB iBase, y copie un fichier et le referme

# ibase_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_cancel — Annule la création d'un BLOB iBase

### Description

function ibase_blob_cancel(resource `$blob_handle`): bool

ibase_blob_cancel() annule la création du BLOB `blob_handle`, créé par ibase_blob_create() s'il n'a pas encore été fermé avec ibase_blob_close().

### Liste de paramètres

`blob_handle`
  Une ressource blob, ouverte avec la fonction ibase_blob_create().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- ibase_blob_close() - Ferme un BLOB iBase
- ibase_blob_create() - Crée un BLOB iBase pour ajouter des données
- ibase_blob_import() - Crée un BLOB iBase, y copie un fichier et le referme

# ibase_blob_close

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_close — Ferme un BLOB iBase

### Description

function ibase_blob_close(resource `$blob_handle`): mixed

ibase_blob_close() ferme le BLOB `blob_handle`, ouvert en lecture avec ibase_open_blob() ou en écriture avec ibase_blob_create().

### Liste de paramètres

`blob_handle`
  Une ressource blob, ouverte avec la fonction ibase_blob_create() ou la fonction ibase_blob_open().

### Valeurs de retour

Si le BLOB était lu, ibase_blob_close() retourne `true` en cas de succès, s'il était en cours de modification, ibase_blob_close() retourne une chaîne de caractères contenant l'identifiant du BLOB qui lui a été assigné par la base de données. En cas d'échec, cette fonction retournera `false`.

### Voir aussi

- ibase_blob_cancel() - Annule la création d'un BLOB iBase
- ibase_blob_open() - Ouvre un BLOB iBase pour récupérer des parties de données

# ibase_blob_create

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_create — Crée un BLOB iBase pour ajouter des données

### Description

function ibase_blob_create(resource `$link_identifier` = `null`): resource|false

ibase_blob_create() crée un nouveau BLOB à remplir avec des données, sur la connexion InterBase `link_identifier`.

### Liste de paramètres

`link_identifier`
  Un identifiant de connexion à InterBase. S'il est omis, la dernière connexion ouverte sera utilisée.

### Valeurs de retour

Retourne un identifiant de BLOB à utiliser avec ibase_blob_add() ou `false` si une erreur survient.

### Voir aussi

- ibase_blob_add() - Ajoute des données dans un BLOB iBase fraîchement créé
- ibase_blob_cancel() - Annule la création d'un BLOB iBase
- ibase_blob_close() - Ferme un BLOB iBase
- ibase_blob_import() - Crée un BLOB iBase, y copie un fichier et le referme

# ibase_blob_echo

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_echo — Affiche le contenu d'un BLOB iBase au navigateur

### Description

function ibase_blob_echo(string `$blob_id`): bool
function ibase_blob_echo(resource `$link_identifier`, string `$blob_id`): bool

ibase_blob_echo() ouvre le BLOB `blob_id` en lecture et envoie son contenu directement vers la sortie standard (le navigateur dans la plupart des cas).

### Liste de paramètres

`link_identifier`
  Un identifiant de connexion à InterBase. S'il est omis, la dernière connexion ouverte sera utilisée.
`blob_id`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- ibase_blob_open() - Ouvre un BLOB iBase pour récupérer des parties de données
- ibase_blob_close() - Ferme un BLOB iBase
- ibase_blob_get() - Lit len octets de données dans un BLOB iBase ouvert

# ibase_blob_get

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_get — Lit `len` octets de données dans un BLOB iBase ouvert

### Description

function ibase_blob_get(resource `$blob_handle`, int `$len`): string

ibase_blob_get() retourne au plus `len` octets du BLOB `blob_handle` qui a été ouvert en lecture par ibase_blob_open().

> Note: Il n'est pas possible de lire dans un BLOB ouvert en écriture par ibase_blob_create().

### Liste de paramètres

`blob_handle`
  Une ressource blob, ouverte avec la fonction ibase_blob_open().
`len`
  La taille des données retournées.

### Valeurs de retour

Retourne au plus, `len` octets du BLOB, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ibase_blob_get()

    <?php
    $result    = ibase_query("SELECT blob_value FROM table");
    $data      = ibase_fetch_object($result);
    $blob_data = ibase_blob_info($data->BLOB_VALUE);
    $blob_hndl = ibase_blob_open($data->BLOB_VALUE);
    echo         ibase_blob_get($blob_hndl, $blob_data[0]);
    ?>

Cet exemple ne fait pas plus qu'un `ibase_blob_echo( $data->BLOB_VALUE )`, mais il montre comment récupérer les informations dans une $variable pour les manipuler comme on le souhaite.

### Voir aussi

- ibase_blob_open() - Ouvre un BLOB iBase pour récupérer des parties de données
- ibase_blob_close() - Ferme un BLOB iBase
- ibase_blob_echo() - Affiche le contenu d'un BLOB iBase au navigateur

# ibase_blob_import

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_import — Crée un BLOB iBase, y copie un fichier et le referme

### Description

function ibase_blob_import(resource `$link_identifier`, resource `$file_handle`): string
function ibase_blob_import(resource `$file_handle`): string

ibase_blob_import() crée un nouveau BLOB sur la connexion iBase `link_identifier`, y copie le fichier `file_handle` en entier, le referme et en retourne l'identifiant assigné

### Liste de paramètres

`link_identifier`
  Un identifiant de connexion à InterBase. S'il est omis, la dernière connexion ouverte sera utilisée.
`file_handle`
  La ressource de fichier, retournée par la fonction fopen().

### Valeurs de retour

Retourne l'identifiant du BLOB en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ibase_blob_import()

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $filename = '/tmp/bar';

    $fd = fopen($filename, 'r');
    if ($fd) {

        $blob = ibase_blob_import($dbh, $fd);
        fclose($fd);

        if (!is_string($blob)) {
            // échec de l'importation
        } else {
            $query = "INSERT INTO foo (name, data) VALUES ('$filename', ?)";
            $prepared = ibase_prepare($dbh, $query);
            if (!ibase_execute($prepared, $blob)) {
                // échec de l'insertion de l'enregistrement
            }
        }
    } else {
        // impossible d'ouvrir le fichier
    }
    ?>

### Voir aussi

- ibase_blob_add() - Ajoute des données dans un BLOB iBase fraîchement créé
- ibase_blob_cancel() - Annule la création d'un BLOB iBase
- ibase_blob_close() - Ferme un BLOB iBase
- ibase_blob_create() - Crée un BLOB iBase pour ajouter des données

# ibase_blob_info

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_info — Retourne la taille d'un BLOB iBase et d'autres informations utiles

### Description

function ibase_blob_info(resource `$link_identifier`, string `$blob_id`): array
function ibase_blob_info(string `$blob_id`): array

Retourne la taille d'un BLOB iBase et d'autres informations utiles.

### Liste de paramètres

`link_identifier`
  Un identifiant de connexion à InterBase. S'il est omis, la dernière connexion ouverte sera utilisée.
`blob_id`
  L'identifiant du BLOB.

### Valeurs de retour

Retourne un tableau contenant des informations à propos du BLOB `blob_id`. Les informations sont la taille du BLOB, le nombre de segments qu'il contient, la taille du segment le plus large, et indiquent s'il s'agit d'un BLOB stream ou segmenté.

# ibase_blob_open

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_open — Ouvre un BLOB iBase pour récupérer des parties de données

### Description

function ibase_blob_open(resource `$link_identifier`, string `$blob_id`): resource|false
function ibase_blob_open(string `$blob_id`): resource|false

Ouvre un BLOB iBase pour récupérer des parties de données.

### Liste de paramètres

`link_identifier`
  Un identifiant de connexion à InterBase. S'il est omis, la dernière connexion ouverte sera utilisée.
`blob_id`
  L'identifiant du BLOB.

### Valeurs de retour

Retourne une ressource BLOB pour une utilisation avec la fonction ibase_blob_get() ou `false` si une erreur survient.

### Voir aussi

- ibase_blob_close() - Ferme un BLOB iBase
- ibase_blob_echo() - Affiche le contenu d'un BLOB iBase au navigateur
- ibase_blob_get() - Lit len octets de données dans un BLOB iBase ouvert

# ibase_close

(PHP 5, PHP 7 < 7.4.0)

ibase_close — Ferme une connexion à une base de données Interbase

### Description

function ibase_close(resource `$connection_id` = `null`): bool

Ferme une connexion à une base de données Interbase. Cette fonction prend comme argument l'identifiant de connexion `connection_id` retourné par ibase_connect(). Les transactions par défaut sont validées et les autres sont annulées.

### Liste de paramètres

`connection_id`
  Un identifiant de connexion à InterBase, retourné par la fonction ibase_connect(). S'il est omis, la dernière connexion ouverte sera utilisée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- ibase_connect() - Ouvre une connexion à une base de données
- ibase_pconnect() - Ouvre une connexion persistante à une base de données InterBase

# ibase_commit

(PHP 5, PHP 7 < 7.4.0)

ibase_commit — Valide une transaction iBase

### Description

function ibase_commit(resource `$link_or_trans_identifier` = `null`): bool

Valide une transaction iBase.

### Liste de paramètres

`link_or_trans_identifier`
  Appelée sans argument, elle valide la transaction par défaut de la connexion par défaut. Si l'argument `link_or_trans_identifier` est un identifiant de connexion, sa transaction par défaut est validée. Si l'argument `link_or_trans_identifier` est un identifiant de transaction, celle-ci sera validée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ibase_commit_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_commit_ret — Valide une transaction iBase sans la refermer

### Description

function ibase_commit_ret(resource `$link_or_trans_identifier` = `null`): bool

Valide une transaction iBase sans la refermer.

### Liste de paramètres

`link_or_trans_identifier`
  Appelée sans argument, elle valide la transaction par défaut de la connexion par défaut. Si l'argument `link_or_trans_identifier` est un identifiant de connexion, sa transaction par défaut est validée. Si l'argument `link_or_trans_identifier` est un identifiant de transaction, celle-ci sera validée. Le contexte de transaction sera retenu et, donc, les requêtes exécutées dans cette transaction ne seront pas invalidées.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ibase_connect

(PHP 5, PHP 7 < 7.4.0)

ibase_connect — Ouvre une connexion à une base de données

### Description

function ibase_connect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Ouvre une connexion à une base de données Firebird/InterBase.

Si un deuxième appel est fait avec ibase_connect(), en passant les mêmes arguments, une nouvelle connexion ne sera pas ouverte, mais la connexion déjà ouverte sera retournée. La connexion sera fermée dès que le script se termine, à moins qu'elle ne soit fermée explicitement avec ibase_close(), durant le script.

### Liste de paramètres

`database`
  `database` doit être un chemin valide jusqu'à un fichier de base de données sur le serveur sur lequel il réside. Si le serveur est distant, il faut le préfixer avec un nom d'hôte 'hostname:' (TCP/IP), 'hostname/port:' (TCP/IP avec un serveur interbase sur un port TCP personnalisé), '//hostname/' (NetBEUI) en fonction du protocole de communication utilisé.
`username`
  Le nom d'utilisateur. Peut être défini avec la directive `ibase.default_user` du fichier php.ini.
`password`
  Le mot de passe correspondant à l'utilisateur `username`. Peut être défini avec la directive `ibase.default_password` du fichier php.ini.
`charset`
  `charset` est le jeu de caractères par défaut pour la base de données.
`buffers`
  `buffers` est le nombre de buffers de base de données à allouer pour le cache serveur. S'il est passé à 0 ou omis, le serveur le choisira de lui-même.
`dialect`
  `dialect` sélectionne le dialecte SQL pour les requêtes exécutées avec cette connexion et, par défaut, il utilise le meilleur dialecte disponible.
`role`
  Ne fonctionne qu'avec InterBase 5 et supérieur.
`sync`

### Valeurs de retour

Retourne un identifiant de connexion Firebird/InterBase en cas de succès, ou `false` si une erreur survient.

### Erreurs / Exceptions

Si l'on a quelques erreurs comme `"arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets"` (cela se produit lors de la tentative d'utiliser des caractères accentués) lorsque l'on utilise ibase_connect() et après ibase_query(), il faut spécifier un jeu de caractères correct (c.-à-d. `ISO8859_1` ou le jeu de caractères courant).

### Exemples

Exemple #1 Exemple avec ibase_connect()

    <?php
    $host = 'localhost:/path/to/your.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email, "\n";
    }
    ibase_free_result($sth);
    ibase_close($dbh);
    ?>

### Voir aussi

- ibase_pconnect() - Ouvre une connexion persistante à une base de données InterBase
- ibase_close() - Ferme une connexion à une base de données Interbase

# ibase_db_info

(PHP 5, PHP 7 < 7.4.0)

ibase_db_info — Demande des statistiques sur une base de données Interbase

### Description

function ibase_db_info(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): string
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

# ibase_delete_user

(PHP 5, PHP 7 < 7.4.0)

ibase_delete_user — Efface un utilisateur d'une base de données de sécurité

### Description

function ibase_delete_user(resource `$service_handle`, string `$user_name`): bool

### Liste de paramètres

`service_handle`
  Le gestionnaire sur le service du serveur de base de données.
`user_name`
  L'identifiant de l'utilisateur qui doit être supprimé de la base de données.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- ibase_add_user() - Ajoute un utilisateur à une base de données de sécurité
- ibase_modify_user() - Modifie un utilisateur dans une base de données de sécurité

# ibase_drop_db

(PHP 5, PHP 7 < 7.4.0)

ibase_drop_db — Supprime une base de données iBase

### Description

function ibase_drop_db(resource `$connection` = `null`): bool

ibase_drop_db() supprime une base de données qui a été ouverte par ibase_connect() ou ibase_pconnect(). La base de données est refermée et supprimée du serveur.

### Liste de paramètres

`connection`
  Un identifiant de connexion à InterBase. S'il est omis, la dernière connexion ouverte sera utilisée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- ibase_connect() - Ouvre une connexion à une base de données
- ibase_pconnect() - Ouvre une connexion persistante à une base de données InterBase

# ibase_errcode

(PHP 5, PHP 7 < 7.4.0)

ibase_errcode — Retourne le code d'erreur iBase

### Description

function ibase_errcode(): int

Retourne le code erreur résultant de l'appel le plus récent à une fonction InterBase.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code erreur, sous la forme d'un entier, ou `false` si aucune erreur n'est survenue.

### Voir aussi

- ibase_errmsg() - Retourne un message d'erreur

# ibase_errmsg

(PHP 5, PHP 7 < 7.4.0)

ibase_errmsg — Retourne un message d'erreur

### Description

function ibase_errmsg(): string

Retourne une chaîne contenant les messages d'erreurs.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le message d'erreur, sous la forme d'une chaîne de caractères, ou `false` si aucune erreur n'est survenue.

### Voir aussi

- ibase_errcode() - Retourne le code d'erreur iBase

# ibase_execute

(PHP 5, PHP 7 < 7.4.0)

ibase_execute — Exécute une requête iBase préparée

### Description

function ibase_execute(resource `$query`, mixed `...$values`): resource

Exécute une requête iBase préparée.

ibase_execute() est beaucoup plus efficace que ibase_query(), si l'on effectue plusieurs fois la même requête en ne changeant que quelques paramètres.

### Liste de paramètres

`query`
  Une requête InterBase, préparée avec la fonction ibase_prepare().
`values`

### Valeurs de retour

Si la requête émet une erreur, la fonction retournera `false`. Si la requête réussit, et qu'il y a un jeu de résultats (pouvant être vide), la fonction retourne un identifiant de résultats. Si la requête réussit et qu'il n'y a pas de résultat, la fonction retourne `true`.

> Note: ibase_execute() retourne le nombre d'enregistrements affectés par la requête (si supérieur à 0). Pour une requête qui réussit mais qui ne renvoie aucun enregistrement (p. ex. un UPDATE sur un enregistrement inexistant), ibase_execute() retournera `true`.

### Exemples

Exemple #1 Exemple avec ibase_execute()

    <?php

    $dbh = ibase_connect($host, $username, $password);

    $updates = array(
        1 => 'Eric',
        5 => 'Filip',
        7 => 'Larry'
    );

    $query = ibase_prepare($dbh, "UPDATE FOO SET BAR = ? WHERE BAZ = ?");

    foreach ($updates as $baz => $bar) {
        ibase_execute($query, $bar, $baz);
    }

    ?>

### Voir aussi

- ibase_query() - Exécute une requête sur une base iBase

# ibase_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_assoc — Récupère une ligne du résultat d'une requête dans un tableau associatif

### Description

function ibase_fetch_assoc(resource `$result`, int `$fetch_flag` = 0): array

Récupère une ligne du résultat d'une requête dans un tableau associatif.

ibase_fetch_assoc() récupère une ligne de données à partir de `result`. Si deux ou plus colonnes ont le même nom de champ, la dernière colonne prendra précédence. Pour accéder aux autres colonnes du même nom, il faut soit le faire avec leurs indices numériques en utilisant ibase_fetch_row() ou en utilisant des alias dans la requête.

### Liste de paramètres

`result`
  Le jeu de résultats.
`fetch_flag`
  `fetch_flag` est une combinaison des constantes `IBASE_TEXT` et `IBASE_UNIXTIME`. Passer `IBASE_TEXT` fait retourner le contenu du BLOB au lieu de l'ID du BLOB. Passer `IBASE_UNIXTIME` fait retourner les valeurs date/time sous forme de timestamps UNIX au lieu de chaînes formatées.

### Valeurs de retour

Retourne un tableau associatif qui correspond à la ligne récupérée. Les appels suivants renvoient la ligne qui suit dans le jeu de résultats, ou `false` s'il n'y a plus de lignes.

### Voir aussi

- ibase_fetch_row() - Lit une ligne d'une base Interbase
- ibase_fetch_object() - Lit une ligne dans une base Interbase dans un objet

# ibase_fetch_object

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_object — Lit une ligne dans une base Interbase dans un objet

### Description

function ibase_fetch_object(resource `$result_id`, int `$fetch_flag` = 0): object

Lit une ligne dans une base Interbase et la place dans un pseudo objet.

Les prochains appels à la fonction ibase_fetch_object() retournent la prochaine ligne du jeu de résultats.

### Liste de paramètres

`result_id`
  Un identifiant de résultat InterBase, obtenu soit par la fonction ibase_query(), soit par la fonction ibase_execute().
`fetch_flag`
  `fetch_flag` est une combinaison des constantes `IBASE_TEXT` et `IBASE_UNIXTIME`. Passer `IBASE_TEXT` fait retourner le contenu du BLOB au lieu de l'ID du BLOB. Passer `IBASE_UNIXTIME` fait retourner les valeurs date/time sous forme de timestamps UNIX au lieu de chaînes formatées.

### Valeurs de retour

Retourne un objet contenant les informations de la ligne, ou `false` s'il n'y a plus de ligne.

### Exemples

Exemple #1 Exemple avec ibase_fetch_object()

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email . "\n";
    }
    ibase_close($dbh);
    ?>

### Voir aussi

- ibase_fetch_row() - Lit une ligne d'une base Interbase
- ibase_fetch_assoc() - Récupère une ligne du résultat d'une requête dans un tableau associatif

# ibase_fetch_row

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_row — Lit une ligne d'une base Interbase

### Description

function ibase_fetch_row(resource `$result_identifier`, int `$fetch_flag` = 0): array

ibase_fetch_row() récupère une ligne de données depuis le jeu de résultats donné.

Les appels suivants à ibase_fetch_row() vont retourner la prochaine ligne dans le résultat, ou bien `false` s'il n'y a plus de ligne.

### Liste de paramètres

`result_identifier`
  Un identifiant de résultat InterBase.
`fetch_flag`
  `fetch_flag` est une combinaison des constantes `IBASE_TEXT` et `IBASE_UNIXTIME`. Passer `IBASE_TEXT` fait retourner le contenu du BLOB au lieu de l'ID du BLOB. Passer `IBASE_UNIXTIME` fait retourner les valeurs date/time sous forme de timestamps UNIX au lieu de chaînes formatées.

### Valeurs de retour

Retourne un tableau correspondant à la ligne récupérée, ou `false` s'il n'y a plus de ligne. Chaque colonne du résultat est stockée dans une position du tableau, en commençant à 0.

### Voir aussi

- ibase_fetch_assoc() - Récupère une ligne du résultat d'une requête dans un tableau associatif
- ibase_fetch_object() - Lit une ligne dans une base Interbase dans un objet

# ibase_field_info

(PHP 5, PHP 7 < 7.4.0)

ibase_field_info — Lit les informations sur un champ iBase

### Description

function ibase_field_info(resource `$result`, int `$field_number`): array

Retourne un tableau contenant les informations d'un champ, après qu'une requête de type sélection ait été exécutée.

### Liste de paramètres

`result`
  Un identifiant de résultat InterBase.
`field_number`
  Position du champ.

### Valeurs de retour

Retourne un tableau contenant les clés suivantes : `name`, `alias`, `relation`, `length` et `type`.

### Exemples

Exemple #1 Exemple avec ibase_field_info()

    <?php
    $rs = ibase_query("SELECT * FROM tablename");
    $coln = ibase_num_fields($rs);
    for ($i = 0; $i < $coln; $i++) {
        $col_info = ibase_field_info($rs, $i);
        echo "nom : ". $col_info['name']. "\n";
        echo "alias : ". $col_info['alias']. "\n";
        echo "relation : ". $col_info['relation']. "\n";
        echo "taille : ". $col_info['length']. "\n";
        echo "type : ". $col_info['type']. "\n";
    }
    ?>

### Voir aussi

- ibase_num_fields() - Retourne le nombre de colonnes dans un résultat iBase

# ibase_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_free_event_handler — Libère un gestionnaire d'événements iBase

### Description

function ibase_free_event_handler(resource `$event`): bool

ibase_free_event_handler() annule le gestionnaire d'événements enregistré, spécifié par `event`. La fonction de rappel ne sera plus exécutée pour les événements qu'elle devait prendre en charge.

### Liste de paramètres

`event`
  Une ressource d'événement, créée par la fonction ibase_set_event_handler().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- ibase_set_event_handler() - Enregistre une fonction de rappel sur un événement interBase

# ibase_free_query

(PHP 5, PHP 7 < 7.4.0)

ibase_free_query — Libère la mémoire réservée par une requête préparée

### Description

function ibase_free_query(resource `$query`): bool

Libère la mémoire réservée par une requête préparée.

### Liste de paramètres

`query`
  Une requête préparée avec la fonction ibase_prepare().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ibase_free_result

(PHP 5, PHP 7 < 7.4.0)

ibase_free_result — Libère un résultat iBase

### Description

function ibase_free_result(resource `$result_identifier`): bool

Libère un résultat iBase.

### Liste de paramètres

`result_identifier`
  Un jeu de résultats, créé par la fonction ibase_query() ou par la fonction ibase_execute().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ibase_gen_id

(PHP 5, PHP 7 < 7.4.0)

ibase_gen_id — Incrémente le générateur donné et retourne sa nouvelle valeur

### Description

function ibase_gen_id(string `$generator`, int `$increment` = 1, resource `$link_identifier` = `null`): mixed
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Valeurs de retour

Retourne une nouvelle valeur générée sous la forme d'un entier ou d'une chaîne de caractères si la valeur est trop grosse.

# ibase_maintain_db

(PHP 5, PHP 7 < 7.4.0)

ibase_maintain_db — Exécute une commande de maintenance sur une base de données Interbase

### Description

function ibase_maintain_db(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ibase_modify_user

(PHP 5, PHP 7 < 7.4.0)

ibase_modify_user — Modifie un utilisateur dans une base de données de sécurité

### Description

function ibase_modify_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Liste de paramètres

`service_handle`
  Le gestionnaire sur le service du serveur de base de données.
`user_name`
  L'identifiant de l'utilisateur de base de données à modifier.
`password`
  Le nouveau mot de passe de l'utilisateur.
`first_name`
  Le nouveau prénom de l'utilisateur.
`middle_name`
  Le nouveau deuxième prénom de l'utilisateur.
`last_name`
  Le nouveau nom de famille de l'utilisateur.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- ibase_add_user() - Ajoute un utilisateur à une base de données de sécurité
- ibase_delete_user() - Efface un utilisateur d'une base de données de sécurité

# ibase_name_result

(PHP 5, PHP 7 < 7.4.0)

ibase_name_result — Assigne un nom à un jeu de résultats iBase

### Description

function ibase_name_result(resource `$result`, string `$name`): bool

Assigne un nom à un jeu de résultats. Ce nom peut être utilisé plus tard dans les requêtes de type `UPDATE|DELETE ... WHERE CURRENT OF` `name`.

### Liste de paramètres

`result`
  Un jeu de résultats InterBase.
`name`
  Le nom à assigner.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ibase_name_result()

    <?php
    $result = ibase_query("SELECT field1,field2 FROM table FOR UPDATE");
    ibase_name_result($result, "my_cursor");

    $updateqry = ibase_prepare("UPDATE table SET field2 = ? WHERE CURRENT OF my_cursor");

    for ($i = 0; ibase_fetch_row($result); ++$i) {
        ibase_execute($updateqry, $i);
    }
    ?>

### Voir aussi

- ibase_prepare() - Prépare une requête iBase pour lier les paramètres et l'exécuter ultérieurement
- ibase_execute() - Exécute une requête iBase préparée

# ibase_num_fields

(PHP 5, PHP 7 < 7.4.0)

ibase_num_fields — Retourne le nombre de colonnes dans un résultat iBase

### Description

function ibase_num_fields(resource `$result_id`): int

Retourne le nombre de colonnes dans un résultat iBase.

### Liste de paramètres

`result_id`
  Un identifiant de résultat InterBase.

### Valeurs de retour

Retourne le nombre de champs, sous la forme d'un entier.

### Exemples

Exemple #1 Exemple avec ibase_num_fields()

    <?php
    $rs = ibase_query("SELECT * FROM tablename");
    $coln = ibase_num_fields($rs);
    for ($i = 0; $i < $coln; $i++) {
        $col_info = ibase_field_info($rs, $i);
        echo "nom : " . $col_info['name'] . "\n";
        echo "alias : " . $col_info['alias'] . "\n";
        echo "relation : " . $col_info['relation'] . "\n";
        echo "taille : " . $col_info['length'] . "\n";
        echo "type : " . $col_info['type'] . "\n";
    }
    ?>

### Voir aussi

- ibase_field_info() - Lit les informations sur un champ iBase

# ibase_num_params

(PHP 5, PHP 7 < 7.4.0)

ibase_num_params — Retourne le nombre de paramètres dans une requête préparée iBase

### Description

function ibase_num_params(resource `$query`): int

ibase_num_params() retourne le nombre de paramètres dans la requête spécifiée par `query`. C'est le nombre d'arguments de substitution qui doivent être présents lors de l'appel de ibase_execute().

### Liste de paramètres

`query`
  La requête préparée.

### Valeurs de retour

Retourne le nombre de paramètres, sous la forme d'un entier.

### Voir aussi

- ibase_prepare() - Prépare une requête iBase pour lier les paramètres et l'exécuter ultérieurement
- ibase_param_info() - Retourne des informations à propos d'un paramètre dans une requête préparée iBase

# ibase_param_info

(PHP 5, PHP 7 < 7.4.0)

ibase_param_info — Retourne des informations à propos d'un paramètre dans une requête préparée iBase

### Description

function ibase_param_info(resource `$query`, int `$param_number`): array

Retourne un tableau avec des informations à propos d'un paramètre après qu'une requête ait été préparée.

### Liste de paramètres

`query`
  Un gestionnaire de requête préparée InterBase.
`param_number`
  La position du paramètre.

### Valeurs de retour

Retourne un tableau contenant les clés suivantes : `name`, `alias`, `relation`, `length` et `type`.

### Voir aussi

- ibase_field_info() - Lit les informations sur un champ iBase
- ibase_num_params() - Retourne le nombre de paramètres dans une requête préparée iBase

# ibase_pconnect

(PHP 5, PHP 7 < 7.4.0)

ibase_pconnect — Ouvre une connexion persistante à une base de données InterBase

### Description

function ibase_pconnect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Ouvre une connexion persistante à une base de données InterBase.

ibase_pconnect() se comporte similairement à ibase_connect(), avec deux différences majeures.

La première est que, lors de la connexion, la fonction va essayer de trouver une connexion (persistante) déjà ouverte. Si elle la trouve, cette dernière sera retournée, plutôt qu'une nouvelle connexion. Sinon, une nouvelle connexion sera ouverte.

La deuxième est que la connexion ne sera pas fermée à la fin du script, mais restera ouverte pour utilisation ultérieure. (ibase_close() ne fermera pas une connexion ouverte avec ibase_pconnect()). Ce type de lien est alors dit 'persistant'.

### Liste de paramètres

`database`
  L'argument `database` doit être un chemin valide vers le fichier de la base de données sur le serveur où il réside. Si le serveur n'est pas local, il doit être préfixé avec soit 'hostname:' (TCP/IP), '//hostname/' (NetBEUI) ou 'hostname@' (IPX/SPX), suivant le protocole utilisé.
`username`
  Le nom d'utilisateur. Peut être défini avec la directive `ibase.default_user` du php.ini.
`password`
  Le mot de passe pour l'utilisateur `username`. Peut être défini avec la directive `ibase.default_password` du php.ini.
`charset`
  `charset` est le jeu de caractères par défaut pour la base de données.
`buffers`
  `buffers` est le nombre de buffers de la base de données à allouer pour le cache côté serveur. Si ce paramètre vaut 0 ou s'il est omis, le serveur choisira lui-même ce nombre.
`dialect`
  `dialect` sélectionne le dialecte SQL par défaut pour toutes les requêtes exécutées dans la connexion, et vaudra par défaut, le plus haut supporté par la bibliothèque cliente. Ne fonctionne qu'avec InterBase 6 et supérieur.
`role`
  Ne fonctionne qu'avec InterBase 5 et supérieur.
`sync`

### Valeurs de retour

Retourne un identifiant de connexion InterBase en cas de succès, ou `false` si une erreur survient.

### Voir aussi

- ibase_close() - Ferme une connexion à une base de données Interbase
- ibase_connect() - Ouvre une connexion à une base de données

# ibase_prepare

(PHP 5, PHP 7 < 7.4.0)

ibase_prepare — Prépare une requête iBase pour lier les paramètres et l'exécuter ultérieurement

### Description

function ibase_prepare(string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$trans`, string `$query`): resource

Prépare une requête afin d'y lier ultérieurement des paramètres ainsi que de l'exécuter (via la fonction ibase_execute()).

### Liste de paramètres

`query`
  Une requête InterBase.
`link_identifier`
  Un identifiant de connexion Interbase retourné par ibase_connect(). Si omis, le dernier lien ouvert est adopté.
`trans`
  Un gestionnaire de transaction InterBase auquel la requête doit être associée. Si omis, la transaction par défaut de la connexion est adoptée.

### Valeurs de retour

Retourne un gestionnaire de requête préparée, ou `false` si une erreur survient.

# ibase_query

(PHP 5, PHP 7 < 7.4.0)

ibase_query — Exécute une requête sur une base iBase

### Description

function ibase_query(resource `$link_identifier` = ?, string `$query`, int `$bind_args` = ?): resource

Exécute une requête sur une base iBase.

### Liste de paramètres

`link_identifier`
  Un identifiant de connexion à InterBase. S'il est omis, la dernière connexion ouverte sera utilisée.
`query`
  Une requête InterBase.
`bind_args`

### Valeurs de retour

Si la requête émet une erreur, la fonction retournera `false`. Si la requête est exécutée avec succès, et qu'il y a un jeu de résultats (même vide), la fonction retournera un identifiant de résultat. Si la requête est exécutée avec succès, et qu'il n'y a pas de résultat, la fonction retournera `true`.

> Note: Dans les versions 5.0.0 de PHP et suivantes, ibase_query() retourne le nombre d'enregistrements affectés par les requêtes `INSERT`, `UPDATE` et `DELETE`. Dans un souci de compatibilité ascendante, ibase_query() retournera `true` si la requête réussit mais ne renvoie aucun enregistrement.

### Erreurs / Exceptions

En cas de réception d'une erreur du type `"arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets"` (ceci survient lors de la tentative d'utiliser des caractères accentués) avec la fonction ibase_query(), c'est qu'il faut choisir un jeu de caractères (c.-à-d. `ISO8859_1` ou le jeu courant).

### Exemples

Exemple #1 Exemple avec ibase_query()

    <?php

    $host = 'localhost:/path/to/your.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';

    $sth = ibase_query($dbh, $stmt) or die(ibase_errmsg());

    ?>

### Voir aussi

- ibase_errmsg() - Retourne un message d'erreur
- ibase_fetch_row() - Lit une ligne d'une base Interbase
- ibase_fetch_object() - Lit une ligne dans une base Interbase dans un objet
- ibase_free_result() - Libère un résultat iBase

# ibase_restore

(PHP 5, PHP 7 < 7.4.0)

ibase_restore — Lance une tâche de restauration dans le gestionnaire de services et retourne immédiatement

### Description

function ibase_restore(
resource `$service_handle`,
string `$source_file`,
string `$dest_db`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Cette fonction transmet les arguments au serveur de base de données (distant). Là, il commence un nouveau processus de restauration. Par conséquent, le résultat ne sera aucune réponse.

### Liste de paramètres

`service_handle`
  Une connexion au serveur de base de données créée précédemment.
`source_file`
  Le chemin absolu sur le serveur où le fichier de sauvegarde est situé.
`dest_db`
  Le chemin pour créer la nouvelle base de données sur le serveur. Il est également possible d'utiliser un alias de base de données.
`options`

  Options supplémentaires à transmettre au serveur de base de données pour la restauration. Le paramètre `options` peut être une combinaison des constantes suivantes : `IBASE_RES_DEACTIVATE_IDX`, `IBASE_RES_NO_SHADOW`, `IBASE_RES_NO_VALIDITY`, `IBASE_RES_ONE_AT_A_TIME`, `IBASE_RES_REPLACE`, `IBASE_RES_CREATE`, `IBASE_RES_USE_ALL_SPACE`, `IBASE_PRP_PAGE_BUFFERS`, `IBASE_PRP_SWEEP_INTERVAL`, `IBASE_RES_CREATE`. Lire la section à propos des Constantes pré-définies pour plus d'information.

`verbose`
  Étant donné que le processus de restauration est effectué sur le serveur de base de données, l’on n’a aucune chance d’obtenir sa sortie. Cet argument est inutile.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Le processus de restauration étant effectué sur le serveur (distant), cette fonction ne fait que lui transmettre les arguments. Tant que les arguments sont légaux, le résultat ne sera pas `false`.

### Exemples

Exemple #1 Exemple avec ibase_restore()

    <?php
    // S'attacher au serveur par adresse ip et port.
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Débuter le processus de restauration sur le serveur de base de données
    // Restaurer la sauvegarde de employee vers la nouvelle base de données emps.fdb
    // N'utilise pas d'argument spéciaux
    ibase_restore($service, '/srv/backup/employees.fbk', '/srv/firebird/emps.fdb');

    // Libère la connexion attachée
    ibase_service_detach ($service);
    ?>

Exemple #2 Exemple de ibase_restore() avec des arguments

    <?php

    // S'attacher au serveur par nom et port par défaut
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Débuter le processus de restauration sur le serveur de base de données
    // Restaure la base de données employee en utilisant un alias.
    // Restaure sans index, Remplace la base de données existante.
    ibase_restore($service, '/srv/backup/employees.fbk', 'employees.fdb', IBASE_RES_DEACTIVATE_IDX | IBASE_RES_REPLACE);

    // Libère la connexion attachée
    ibase_service_detach ($service);
    ?>

### Voir aussi

- ibase_backup() - Lance une tâche de sauvegarde dans le gestionnaire de services et retourne immédiatement

# ibase_rollback

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback — Annule une transaction interBase

### Description

function ibase_rollback(resource `$link_or_trans_identifier` = `null`): bool

Annule une transaction interBase.

### Liste de paramètres

`link_or_trans_identifier`
  Lorsque ibase_rollback() est appelée sans argument, elle annule la transaction par défaut du lien par défaut. Si l'argument `link_or_trans_identifier` est un identifiant de connexion, la transaction par défaut de cette connexion sera annulée. Si l'argument `link_or_trans_identifier` est un identifiant de transaction, celle-ci sera annulée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ibase_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback_ret — Annule une transaction sans la fermer

### Description

function ibase_rollback_ret(resource `$link_or_trans_identifier` = `null`): bool

Annule une transaction sans la fermer.

### Liste de paramètres

`link_or_trans_identifier`
  Si ibase_rollback_ret() est appelée sans argument, elle annule la transaction par défaut du lien par défaut. Si l'argument `link_or_trans_identifier` est un identifiant de connexion, la transaction par défaut de cette connexion sera annulée. Si l'argument `link_or_trans_identifier` est un identifiant de transaction, celle-ci sera annulée. Le contexte de transaction sera retenu et, donc, les requêtes exécutées dans cette transaction ne seront pas invalidées.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ibase_server_info

(PHP 5, PHP 7 < 7.4.0)

ibase_server_info — Sollicite des informations à propos d'un serveur de base de données

### Description

function ibase_server_info(resource `$service_handle`, int `$action`): string

### Liste de paramètres

`service_handle`
  Une connexion au serveur de base de données créée précédemment.
`action`
  Une constante valide.

### Valeurs de retour

Retourne des types différents en fonction du contexte.

### Exemples

Exemple #1 Exemple avec ibase_service_attach()

    <?php
        // S'attacher au serveur Firebird distant
        if (($service = ibase_service_attach('10.1.1.254/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Attaché avec succès.

            // Afficher les informations
            echo "Server version: " . ibase_server_info($service, IBASE_SVC_SERVER_VERSION) . "\n";
            echo "Server implementation: " . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION) . "\n";
            echo "Server users: " . print_r(ibase_server_info($service, IBASE_SVC_GET_USERS), true) . "\n";
            echo "Server directory: " . ibase_server_info($service, IBASE_SVC_GET_ENV) . "\n";
            echo "Server lock path: " . ibase_server_info($service, IBASE_SVC_GET_ENV_LOCK) . "\n";
            echo "Server lib path: " . ibase_server_info($service, IBASE_SVC_GET_ENV_MSG) . "\n";
            echo "Path of user db: " . ibase_server_info($service, IBASE_SVC_USER_DBPATH) . "\n";
            echo "Established connections: " . print_r(ibase_server_info($service, IBASE_SVC_SVR_DB_INFO),true) . "\n";

            // Se détacher du serveur (déconnexion)
            ibase_service_detach($service);

        }
        else {
            // Afficher un message en cas d'erreur
            $conn_error = ibase_errmsg();
            die($conn_error);
        }
    ?>

L'exemple ci-dessus va afficher :

    Server version: LI-V3.0.4.33054 Firebird 3.0
    Server implementation: Firebird/Linux/AMD/Intel/x64
    Server users: Array
    (
        [0] => Array
            (
                [user_name] => SYSDBA
                [first_name] => Sql
                [middle_name] => Server
                [last_name] => Administrator
                [user_id] => 0
                [group_id] => 0
            )

    )

    Server directory: /etc/firebird/
    Server lock path: /tmp/firebird/
    Server lib path: /usr/lib64/firebird/lib/
    Path of user db: /var/lib/firebird/secdb/security3.fdb
    Established connections: Array
    (
        [attachments] => 3
        [databases] => 2
        [0] => /srv/firebird/poss.fdb
        [1] => /srv/firebird/employees.fdb
    )

# ibase_service_attach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_attach — Connexion au gestionnaire de service

### Description

function ibase_service_attach(string `$host`, string `$dba_username`, string `$dba_password`): resource|false

### Liste de paramètres

`host`
  Le nom ou l'adresse IP de l'hôte de la base de données. Il est possible de définir le port en ajoutant '/' et le numéro du port. Si aucun port est spécifié, le port 3050 sera utilisé.
`dba_username`
  Le nom de tout utilisateur valide.
`dba_password`
  Le mot de passe de l'utilisateur.

### Valeurs de retour

Retourne un identifiant de lien Interbase / Firebird en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ibase_service_attach()

    <?php
        // S'attacher au serveur Firebird distant par une adresse ip
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Attaché avec succès.
            // Récupérer la version du serveur (qqch comme 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Récupérer l'implémentation serveur (qqch comme 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Se détacher du serveur (déconnexion)
            ibase_service_detach($service);

            // Afficher les informations
            echo "Server version: " . $server_version . "<br/>";
            echo "Server implementation: " . $server_implementation;
        }
        else {
            // Afficher un message en cas d'erreur
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

Exemple #2 Exemple deibase_service_attach() en utilisant la syntaxe `hostname/port`

    <?php
        // S'attacher au serveur Firebird distant par nom. Utilise le Port 3050.
        if (($service = ibase_service_attach('FB-SRV-01.contoso.local/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Attaché avec succès.
            // Récupérer la version du serveur (qqch comme 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Récupérer l'implémentation serveur (qqch comme 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Se détacher du serveur (déconnexion)
            ibase_service_detach($service);

            // Afficher les informations
            echo "Server version: " . $server_version . "<br/>";
            echo "Server implementation: " . $server_implementation;
        }
        else {
            // Afficher un message en cas d'erreur
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

### Voir aussi

- ibase_service_detach() - Déconnexion du gestionnaire de service

# ibase_service_detach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_detach — Déconnexion du gestionnaire de service

### Description

function ibase_service_detach(resource `$service_handle`): bool

### Liste de paramètres

`service_handle`
  Une connexion au serveur de base de données créée précédemment.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ibase_service_detach()

    <?php
        // S'attacher au serveur Firebird distant par une adresse ip
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Attaché avec succès.
            // Récupérer la version du serveur (qqch comme 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Récupérer l'implémentation serveur (qqch comme 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Se détacher du serveur (déconnexion)
            if(ibase_service_detach($service) == FALSE) {
                echo "Erreur lors de la déconnexion du service.";
            }
            else {
                echo "Déconnexion du service réussie.";
            }

        }
        else {
            // Afficher un message en cas d'erreur
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

# ibase_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_set_event_handler — Enregistre une fonction de rappel sur un événement interBase

### Description

function ibase_set_event_handler(callable `$event_handler`, string `$event_name`, string `...$even_names`): resource
function ibase_set_event_handler(
resource `$connection`,
callable `$event_handler`,
string `$event_name`,
string `...$event_names`
): resource

ibase_set_event_handler() enregistre la fonction utilisateur PHP `event_handler` en tant que gestionnaire d'événements pour les événements spécifiés.

### Liste de paramètres

`event_handler`
  Fonction de rappel appelée avec le nom de l'événement et la ressource de connexion en tant qu'arguments dès qu'un événement spécifié est posté dans la base de données. La fonction de rappel `event_handler` doit retourner `false` si le gestionnaire doit être annulé. Toute autre valeur de retour est ignorée. Cette fonction accepte jusqu'à 15 arguments d'événement.
`event_name`
  Le nom de l'événement.
`event_names`
  15 événements tout au plus sont autorisés.

### Valeurs de retour

La valeur retournée est une ressource d'événement. Elle peut être utilisée pour libérer le gestionnaire d'événements en utilisant ibase_free_event_handler().

### Exemples

Exemple #1 Exemple avec ibase_set_event_handler()

    <?php

    function event_handler($event_name, $link)
    {
        if ($event_name == "NEW ORDER") {
            // Traitement du nouvel ordre
            ibase_query($link, "UPDATE orders SET status='handled'");
        } else if ($event_name == "DB_SHUTDOWN") {
            // Libération du gestionnaire
            return false;
        }
    }

    ibase_set_event_handler($link, "event_handler", "NEW_ORDER", "DB_SHUTDOWN");
    ?>

### Voir aussi

- ibase_free_event_handler() - Libère un gestionnaire d'événements iBase
- ibase_wait_event() - Attend un événement interBase

# ibase_trans

(PHP 5, PHP 7 < 7.4.0)

ibase_trans — Démarre une transaction interBase

### Description

function ibase_trans(int `$trans_args` = ?, resource `$link_identifier` = ?): resource
function ibase_trans(resource `$link_identifier` = ?): resource

Démarre une transaction interBase.

> Note: Le premier appel à ibase_trans() ne retournera pas la transaction par défaut pour la connexion courante. Toutes les transactions commencées par ibase_trans() seront annulées à la fin de l'exécution du script si elles n'ont pas été validées ou annulées par respectivement les fonctions ibase_commit() ou ibase_rollback().

> Note: ibase_trans() accepte plusieurs paramètres `trans_args` et `link_identifier`. Ceci permet d'effectuer des transactions sur plusieurs connexions à des bases de données différentes, qui seront validées en utilisant l'algorithme `2-phase`. Cela signifie qu'il est possible de mettre à jour plusieurs bases de données. Cela ne veut PAS dire qu'il est possible d'utiliser plusieurs bases de données dans une même requête ! Si l'on utilise les transactions sur plusieurs base de données, il faut spécifier `link_id` et `transaction_id` dans les fonctions ibase_query() et ibase_prepare().

### Liste de paramètres

`trans_args`
  `trans_args` peut être une combinaison des constantes suivantes : `IBASE_READ`, `IBASE_WRITE`, `IBASE_COMMITTED`, `IBASE_CONSISTENCY`, `IBASE_CONCURRENCY`, `IBASE_REC_VERSION`, `IBASE_REC_NO_VERSION`, `IBASE_WAIT` et `IBASE_NOWAIT`.
`link_identifier`
  Un identifiant de connexion à InterBase. S'il est omis, la dernière connexion ouverte sera utilisée.

### Valeurs de retour

Retourne une ressource de transaction, ou `false` si une erreur survient.

# ibase_wait_event

(PHP 5, PHP 7 < 7.4.0)

ibase_wait_event — Attend un événement interBase

### Description

function ibase_wait_event(string `$event_name`, string `...$event_names`): string
function ibase_wait_event(resource `$connection`, string `$event_name`, string `...$event_names`): string

ibase_wait_event() suspend l'exécution du script jusqu'à ce que l'un des événements spécifiés soit posté par la base de données. Le nom de l'événement qui a été posté est alors retourné. Cette fonction accepte jusqu'à 15 arguments événements.

### Liste de paramètres

`event_name`
  Le nom de l'événement.
`event_names`

### Valeurs de retour

Retourne le nom de l'événement qui a été posté.

### Voir aussi

- ibase_set_event_handler() - Enregistre une fonction de rappel sur un événement interBase
- ibase_free_event_handler() - Libère un gestionnaire d'événements iBase

## Sommaire

- fbird_add_user — Alias de ibase_add_user
- fbird_affected_rows — Alias de ibase_affected_rows
- fbird_backup — Alias de ibase_backup
- fbird_blob_add — Alias de ibase_blob_add
- fbird_blob_cancel — Annule la création d'un blob
- fbird_blob_close — Alias de ibase_blob_close
- fbird_blob_create — Alias de ibase_blob_create
- fbird_blob_echo — Alias de ibase_blob_echo
- fbird_blob_get — Alias de ibase_blob_get
- fbird_blob_import — Alias de ibase_blob_import
- fbird_blob_info — Alias de ibase_blob_info
- fbird_blob_open — Alias de ibase_blob_open
- fbird_close — Alias de ibase_close
- fbird_commit — Alias de ibase_commit
- fbird_commit_ret — Alias de ibase_commit_ret
- fbird_connect — Alias de ibase_connect
- fbird_db_info — Alias de ibase_db_info
- fbird_delete_user — Alias de ibase_delete_user
- fbird_drop_db — Alias de ibase_drop_db
- fbird_errcode — Alias de ibase_errcode
- fbird_errmsg — Alias de ibase_errmsg
- fbird_execute — Alias de ibase_execute
- fbird_fetch_assoc — Alias de ibase_fetch_assoc
- fbird_fetch_object — Alias de ibase_fetch_object
- fbird_fetch_row — Alias de ibase_fetch_row
- fbird_field_info — Alias de ibase_field_info
- fbird_free_event_handler — Alias de ibase_free_event_handler
- fbird_free_query — Alias de ibase_free_query
- fbird_free_result — Alias de ibase_free_result
- fbird_gen_id — Alias de ibase_gen_id
- fbird_maintain_db — Alias de ibase_maintain_db
- fbird_modify_user — Alias de ibase_modify_user
- fbird_name_result — Alias de ibase_name_result
- fbird_num_fields — Alias de ibase_num_fields
- fbird_num_params — Alias de ibase_num_params
- fbird_param_info — Alias de ibase_param_info
- fbird_pconnect — Alias de ibase_pconnect
- fbird_prepare — Alias de ibase_prepare
- fbird_query — Alias de ibase_query
- fbird_restore — Alias de ibase_restore
- fbird_rollback — Alias de ibase_rollback
- fbird_rollback_ret — Alias de ibase_rollback_ret
- fbird_server_info — Alias de ibase_server_info
- fbird_service_attach — Alias de ibase_service_attach
- fbird_service_detach — Alias de ibase_service_detach
- fbird_set_event_handler — Alias de ibase_set_event_handler
- fbird_trans — Alias de ibase_trans
- fbird_wait_event — Alias de ibase_wait_event
- ibase_add_user — Ajoute un utilisateur à une base de données de sécurité
- ibase_affected_rows — Retourne le nombre de lignes affectées par la dernière requête iBase
- ibase_backup — Lance une tâche de sauvegarde dans le gestionnaire de services et retourne immédiatement
- ibase_blob_add — Ajoute des données dans un BLOB iBase fraîchement créé
- ibase_blob_cancel — Annule la création d'un BLOB iBase
- ibase_blob_close — Ferme un BLOB iBase
- ibase_blob_create — Crée un BLOB iBase pour ajouter des données
- ibase_blob_echo — Affiche le contenu d'un BLOB iBase au navigateur
- ibase_blob_get — Lit len octets de données dans un BLOB iBase ouvert
- ibase_blob_import — Crée un BLOB iBase, y copie un fichier et le referme
- ibase_blob_info — Retourne la taille d'un BLOB iBase et d'autres informations utiles
- ibase_blob_open — Ouvre un BLOB iBase pour récupérer des parties de données
- ibase_close — Ferme une connexion à une base de données Interbase
- ibase_commit — Valide une transaction iBase
- ibase_commit_ret — Valide une transaction iBase sans la refermer
- ibase_connect — Ouvre une connexion à une base de données
- ibase_db_info — Demande des statistiques sur une base de données Interbase
- ibase_delete_user — Efface un utilisateur d'une base de données de sécurité
- ibase_drop_db — Supprime une base de données iBase
- ibase_errcode — Retourne le code d'erreur iBase
- ibase_errmsg — Retourne un message d'erreur
- ibase_execute — Exécute une requête iBase préparée
- ibase_fetch_assoc — Récupère une ligne du résultat d'une requête dans un tableau associatif
- ibase_fetch_object — Lit une ligne dans une base Interbase dans un objet
- ibase_fetch_row — Lit une ligne d'une base Interbase
- ibase_field_info — Lit les informations sur un champ iBase
- ibase_free_event_handler — Libère un gestionnaire d'événements iBase
- ibase_free_query — Libère la mémoire réservée par une requête préparée
- ibase_free_result — Libère un résultat iBase
- ibase_gen_id — Incrémente le générateur donné et retourne sa nouvelle valeur
- ibase_maintain_db — Exécute une commande de maintenance sur une base de données Interbase
- ibase_modify_user — Modifie un utilisateur dans une base de données de sécurité
- ibase_name_result — Assigne un nom à un jeu de résultats iBase
- ibase_num_fields — Retourne le nombre de colonnes dans un résultat iBase
- ibase_num_params — Retourne le nombre de paramètres dans une requête préparée iBase
- ibase_param_info — Retourne des informations à propos d'un paramètre dans une requête préparée iBase
- ibase_pconnect — Ouvre une connexion persistante à une base de données InterBase
- ibase_prepare — Prépare une requête iBase pour lier les paramètres et l'exécuter ultérieurement
- ibase_query — Exécute une requête sur une base iBase
- ibase_restore — Lance une tâche de restauration dans le gestionnaire de services et retourne immédiatement
- ibase_rollback — Annule une transaction interBase
- ibase_rollback_ret — Annule une transaction sans la fermer
- ibase_server_info — Sollicite des informations à propos d'un serveur de base de données
- ibase_service_attach — Connexion au gestionnaire de service
- ibase_service_detach — Déconnexion du gestionnaire de service
- ibase_set_event_handler — Enregistre une fonction de rappel sur un événement interBase
- ibase_trans — Démarre une transaction interBase
- ibase_wait_event — Attend un événement interBase

- Installation/Configuration
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Fonctions Firebird/InterBase
  - fbird_add_user — Alias de ibase_add_user
  - fbird_affected_rows — Alias de ibase_affected_rows
  - fbird_backup — Alias de ibase_backup
  - fbird_blob_add — Alias de ibase_blob_add
  - fbird_blob_cancel — Annule la création d'un blob
  - fbird_blob_close — Alias de ibase_blob_close
  - fbird_blob_create — Alias de ibase_blob_create
  - fbird_blob_echo — Alias de ibase_blob_echo
  - fbird_blob_get — Alias de ibase_blob_get
  - fbird_blob_import — Alias de ibase_blob_import
  - fbird_blob_info — Alias de ibase_blob_info
  - fbird_blob_open — Alias de ibase_blob_open
  - fbird_close — Alias de ibase_close
  - fbird_commit — Alias de ibase_commit
  - fbird_commit_ret — Alias de ibase_commit_ret
  - fbird_connect — Alias de ibase_connect
  - fbird_db_info — Alias de ibase_db_info
  - fbird_delete_user — Alias de ibase_delete_user
  - fbird_drop_db — Alias de ibase_drop_db
  - fbird_errcode — Alias de ibase_errcode
  - fbird_errmsg — Alias de ibase_errmsg
  - fbird_execute — Alias de ibase_execute
  - fbird_fetch_assoc — Alias de ibase_fetch_assoc
  - fbird_fetch_object — Alias de ibase_fetch_object
  - fbird_fetch_row — Alias de ibase_fetch_row
  - fbird_field_info — Alias de ibase_field_info
  - fbird_free_event_handler — Alias de ibase_free_event_handler
  - fbird_free_query — Alias de ibase_free_query
  - fbird_free_result — Alias de ibase_free_result
  - fbird_gen_id — Alias de ibase_gen_id
  - fbird_maintain_db — Alias de ibase_maintain_db
  - fbird_modify_user — Alias de ibase_modify_user
  - fbird_name_result — Alias de ibase_name_result
  - fbird_num_fields — Alias de ibase_num_fields
  - fbird_num_params — Alias de ibase_num_params
  - fbird_param_info — Alias de ibase_param_info
  - fbird_pconnect — Alias de ibase_pconnect
  - fbird_prepare — Alias de ibase_prepare
  - fbird_query — Alias de ibase_query
  - fbird_restore — Alias de ibase_restore
  - fbird_rollback — Alias de ibase_rollback
  - fbird_rollback_ret — Alias de ibase_rollback_ret
  - fbird_server_info — Alias de ibase_server_info
  - fbird_service_attach — Alias de ibase_service_attach
  - fbird_service_detach — Alias de ibase_service_detach
  - fbird_set_event_handler — Alias de ibase_set_event_handler
  - fbird_trans — Alias de ibase_trans
  - fbird_wait_event — Alias de ibase_wait_event
  - ibase_add_user — Ajoute un utilisateur à une base de données de sécurité
  - ibase_affected_rows — Retourne le nombre de lignes affectées par la dernière requête iBase
  - ibase_backup — Lance une tâche de sauvegarde dans le gestionnaire de services et retourne immédiatement
  - ibase_blob_add — Ajoute des données dans un BLOB iBase fraîchement créé
  - ibase_blob_cancel — Annule la création d'un BLOB iBase
  - ibase_blob_close — Ferme un BLOB iBase
  - ibase_blob_create — Crée un BLOB iBase pour ajouter des données
  - ibase_blob_echo — Affiche le contenu d'un BLOB iBase au navigateur
  - ibase_blob_get — Lit len octets de données dans un BLOB iBase ouvert
  - ibase_blob_import — Crée un BLOB iBase, y copie un fichier et le referme
  - ibase_blob_info — Retourne la taille d'un BLOB iBase et d'autres informations utiles
  - ibase_blob_open — Ouvre un BLOB iBase pour récupérer des parties de données
  - ibase_close — Ferme une connexion à une base de données Interbase
  - ibase_commit — Valide une transaction iBase
  - ibase_commit_ret — Valide une transaction iBase sans la refermer
  - ibase_connect — Ouvre une connexion à une base de données
  - ibase_db_info — Demande des statistiques sur une base de données Interbase
  - ibase_delete_user — Efface un utilisateur d'une base de données de sécurité
  - ibase_drop_db — Supprime une base de données iBase
  - ibase_errcode — Retourne le code d'erreur iBase
  - ibase_errmsg — Retourne un message d'erreur
  - ibase_execute — Exécute une requête iBase préparée
  - ibase_fetch_assoc — Récupère une ligne du résultat d'une requête dans un tableau associatif
  - ibase_fetch_object — Lit une ligne dans une base Interbase dans un objet
  - ibase_fetch_row — Lit une ligne d'une base Interbase
  - ibase_field_info — Lit les informations sur un champ iBase
  - ibase_free_event_handler — Libère un gestionnaire d'événements iBase
  - ibase_free_query — Libère la mémoire réservée par une requête préparée
  - ibase_free_result — Libère un résultat iBase
  - ibase_gen_id — Incrémente le générateur donné et retourne sa nouvelle valeur
  - ibase_maintain_db — Exécute une commande de maintenance sur une base de données Interbase
  - ibase_modify_user — Modifie un utilisateur dans une base de données de sécurité
  - ibase_name_result — Assigne un nom à un jeu de résultats iBase
  - ibase_num_fields — Retourne le nombre de colonnes dans un résultat iBase
  - ibase_num_params — Retourne le nombre de paramètres dans une requête préparée iBase
  - ibase_param_info — Retourne des informations à propos d'un paramètre dans une requête préparée iBase
  - ibase_pconnect — Ouvre une connexion persistante à une base de données InterBase
  - ibase_prepare — Prépare une requête iBase pour lier les paramètres et l'exécuter ultérieurement
  - ibase_query — Exécute une requête sur une base iBase
  - ibase_restore — Lance une tâche de restauration dans le gestionnaire de services et retourne immédiatement
  - ibase_rollback — Annule une transaction interBase
  - ibase_rollback_ret — Annule une transaction sans la fermer
  - ibase_server_info — Sollicite des informations à propos d'un serveur de base de données
  - ibase_service_attach — Connexion au gestionnaire de service
  - ibase_service_detach — Déconnexion du gestionnaire de service
  - ibase_set_event_handler — Enregistre une fonction de rappel sur un événement interBase
  - ibase_trans — Démarre une transaction interBase
  - ibase_wait_event — Attend un événement interBase

# Fonctions IBM DB2, Cloudscape et Apache Derby

# Introduction

Ces fonctions permettent d'accéder aux bases de données IBM DB2 Universal Database, IBM Cloudscape et Apache Derby en utilisant l'interface DB2 Call Level Interface (DB2 CLI).

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Pour se connecter à des bases de données IBM DB2 Universal Database pour linux, UNIX et Windows ou IBM Cloudscape ou Apache Derby, il faut installer un client IBM DB2 Universal Database sur le même ordinateur qui utilise PHP. Cette extension a été développée et testée avec DB2 Version 8.2.

Pour se connecter à des bases de données IBM DB2 Universal Database pour z/OS ou iSeries, on aura aussi besoin d'IBM DB2 Connect ou l'équivalent d'un programme DRDA.

## Prérequis pour Linux et Unix

L'utilisateur appelant l'exécutable PHP ou module SAPI doit spécifier l'instance DB2 avant d'accéder à ces fonctions. Il est possible de spécifier le nom de l'instance DB2 dans php.ini en utilisant l'option de configuration `ibm_db2.instance_name` ou il est possible d'approvisionner le profil de l'instance DB2 avant d'appeler l'exécutable PHP.

Si l'on a créé une instance DB2 nommée `db2inst1` dans /home/db2inst1, par exemple, il est possible d'ajouter la ligne suivante au php.ini :

    ibm_db2.instance_name=db2inst1

Si l'on ne spécifie pas cette option dans php.ini, il faut exécuter la commande suivante pour modifier les variables d'environnement pour autoriser l'accès à DB2 :

    bash$ source /home/db2inst1/sqllib/db2profile

Pour permettre à PHP sur le serveur web d'accéder à ces fonctions, il faut ajouter la même commande au script de démarrage du serveur Web (typiquement /etc/init.d/httpd ou /etc/init.d/apache).

## Installation

Pour compiler l'extension ibm_db2, les fichiers d'en-tête et de bibliothèques de l'application de développement de DB2 doivent être présents sur le système. DB2 ne les installe pas par défaut, il pourrait donc être nécessaire de retourner à l'installation de DB2 et ajouter cette option. Le client de développement d'application DB2 inclut les fichiers d'en-tête et est disponible librement au téléchargement depuis le » support du site de la base de données universelle.

Si les fichiers d'en-têtes et de bibliothèques de l'application de développement de DB2 sont ajoutés sur un système Linux ou Unix où DB2 est déjà installé, la commande db2iupdt -e devra être lancée pour mettre à jour les liens symboliques vers les fichiers d'en-têtes et de bibliothèques des instances DB2.

ibm_db2 est une extension » PECL, alors suivez les instructions présentes dans Installation d'extensions PECL pour installer l'extension ibm_db2 pour PHP. Tapez la commande configure pour pointer vers l'emplacement des fichiers d'en-têtes et de bibliothèques de DB2 comme suit :

    bash$ ./configure --with-IBM_DB2=/chemin/vers/DB2

La commande configure prend la valeur par défaut de /opt/IBM/db2/V8.1.

> Note: Note pour les utilisateurs d'IIS
> Si le driver ibm_db2 est utilisé avec IIS (Microsoft Internet Information Server), il pourrait être nécessaire de prendre les mesures suivantes :

> - Installer DB2 avec le système de sécurité étendu.
> - Ajouter le chemin vers le binaire PHP à la variable d'environnement PATH du système (Par défaut : `C:\php\`).
> - Créer une autre variable d'environnement contenant le chemin vers le fichier PHP.INI (p. ex. : `PHPRC = C:\php\`).
> - Ajouter l'utilisateur IUSR_COMPUTERNAME au groupe DB2USERS.

## Configuration à l'exécution

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

Options de configuration DB2
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
ibm_db2.binmode | "1" | `INI_ALL` |
ibm_db2.i5_all_pconnect | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.6.5.
ibm_db2.i5_allow_commit | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.4.9.
ibm_db2.i5_blank_userid | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.9.7.
ibm_db2.i5_char_trim | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 2.1.0.
ibm_db2.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.5.0.
ibm_db2.i5_guard_profile | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.9.7.
ibm_db2.i5_ignore_userid | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.8.0.
ibm_db2.i5_job_sort | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.8.4.
ibm_db2.i5_log_verbose | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.9.7.
ibm_db2.i5_max_pconnect | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.9.7.
ibm_db2.i5_override_ccsid | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.9.7.
ibm_db2.i5_servermode_subsystem | NULL | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.9.7.
ibm_db2.i5_sys_naming | "0" | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.9.7.
ibm_db2.instance_name | NULL | `INI_SYSTEM` | Disponible à partir d'ibm_db2 1.0.2.

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

`ibm_db2.binmode` (int)

  Cette option contrôle le mode utilisé pour convertir à partir ou vers les données binaires dans l'application PHP.

  - 1 (DB2_BINARY)
  - 2 (DB2_CONVERT)
  - 3 (DB2_PASSTHRU)
`ibm_db2.i5_all_pconnect` (int)

  Cette option force toutes les connexions à être persistantes sur IBM i. Fondamentalement, tous les appels à db2_connect() deviennent automatiquement des appels à db2_pconnect(). Par défaut, cette option est `0`. Cette option est fournie pour des raisons de commodité dans les cas où les connexions persistantes sont plus rapides. Elle ne devrait pas être utilisée dans de nouvelles applications.

  - 0 - Les connexions persistantes et non persistantes peuvent être établies.
  - 1 - Toutes les connexions sont persistantes.
`ibm_db2.i5_allow_commit` int

  Cette option contrôle le mode d'isolation de la transaction utilisé. Par défaut, cette option est `0`, donc le contrôle d'engagement n'est pas utilisé. Cette option peut être remplacée lors de la connexion si la clé de tableau `i5_commit` est définie dans le tableau d'options de connexion passé à db2_connect() ou db2_pconnect().

  - 0 - contrôle d'engagement n'est pas utilisé.
  - 1 - lecture non validée, lecture sale possible.
  - 2 - lecture validée, lecture sale impossible.
  - 3 - lecture répétable, lecture sale et lecture non répétable sont impossibles.
  - 4 - sérialisable, lecture sale, lecture non répétable, et fantôme sont impossibles.
`ibm_db2.i5_blank_userid` int

  Cela contrôle si un identifiant utilisateur vide doit être autorisé sur IBM i. Par défaut, cette option est `0`. Contrairement à `ibm_db2.i5_ignore_userid`, cette option ne force pas tous les identifiants d'utilisateur à être vides ou à modifier le comportement du travail, mais permet simplement de passer un identifiant d'utilisateur vide, pour se connecter à Db2 en tant qu'utilisateur actuel.

  - 0 - Ne permet pas de passer un identifiant utilisateur vide.
  - 1 - Permet de passer un identifiant utilisateur vide.
`ibm_db2.i5_char_trim` int

  Cette option contrôle si la fin des chaînes est tronquée sur IBM i. Étant donné que de nombreuses tables utilisent des tailles de colonnes fixes remplies d'espaces, cela est fourni par commodité. Par défaut, cette option est `0`.

  - 0 - Les colonnes ne sont pas tronquées.
  - 1 - Les espaces à la fin des colonnes de caractères retournées sont supprimés.
`ibm_db2.i5_dbcs_alloc` (int)

  Cette option affecte la stratégie d'allocation de mémoire tampon interne sur IBM i. Par défaut, cette option est `0`. Lorsque cette option est définie, les tampons sont alloués avec une taille beaucoup plus grande, au cas où la base de données sous-estimerait la taille d'une chaîne lors de la conversion entre les encodages. Cette option utilise six fois plus de mémoire pour les tampons (pour prendre en compte les séquences UTF-8 les plus grandes possibles), mais peut être nécessaire si des données tronquées sont renvoyées.

  - 0 - Des tampons de taille minimale sont alloués.
  - 1 - Des tampons de taille plus grande sont alloués.
`ibm_db2.i5_guard_profile` int

  Cette option vérifie si le profil utilisateur de la base de données a été changé lors de la connexion à une connexion de base de données persistante sur IBM i, et si c'est le cas, elle se déconnecte de la base de données. Par défaut, cette option est définie sur `0`.

  - 0 - Ne pas vérifier les changements de profil.
  - 1 - Vérifier les changements de profil et se déconnecter le cas échéant.
`ibm_db2.i5_log_verbose` int

  Cette option définit si les messages diagnostiques SQL tels que les avertissements et les erreurs sont toujours envoyés dans le journal d'erreurs PHP sur IBM i. Normalement, seul un bref message en cas d'échec est envoyé (tel que "l'exécution de la déclaration a échoué") dans le journal d'erreurs PHP, car cette option est définie sur `0` par défaut. Il est à noter qu'il est toujours possible, et recommandé, d'appeler manuellement db2_stmt_errormsg() pour vérifier si les fonctions échouent.

  - 0 - Ne journalise que des messages brefs.
  - 1 - Journalise le message diagnostique SQL en plus du message bref.
`ibm_db2.i5_ignore_userid` (int)

  Cette option ignore l'ID utilisateur lors de la connexion à la base de données lors de l'exécution sur IBM i, et exécute la fonctionnalité SQL/CLI à l'intérieur du travail PHP, au lieu d'un travail séparé. Par défaut, cette option est `0`. Lorsqu'elle est activée, elle n'utilise plus un travail de serveur de base de données séparé, et utilise toujours le profil utilisateur actuel pour la base de données, ignorant le nom d'utilisateur et le mot de passe transmis à db2_connect() et db2_pconnect().

  - 0 : db2_(p)connect avec un identifiant utilisateur et un mot de passe spécifique 0 - Utilise les informations d'identification spécifiées et utilise un travail de serveur SQL/CLI.
  - 1 : db2_(p)connect avec un identifiant utilisateur et un mot de passe vide 1 - Utilise toujours des informations d'identification vides et exécute SQL/CLI dans le travail PHP.
`ibm_db2.i5_job_sort` int

  Contrôle l'option de tri des travaux sur IBM i. Par défaut, cette option est `0`. Cela correspond à l'attribut `SQL_ATTR_CONN_SORT_SEQUENCE` d'IBM i SQL/CLI.

  - 0 - Utilise l'option de tri `*HEX`, triant par octets.
  - 1 - Utilise la séquence de tri de travail définie pour le travail PHP.
  - 2 - Utilise la séquence de tri de travail définie pour le travail de base de données.
`ibm_db2.i5_max_pconnect` int
  Cela affectera combien de fois une connexion persistante peut être réutilisée lors de l'exécution sur IBM i. Par défaut, cela est réglé sur `0`, ce qui signifie qu'une connexion persistante peut toujours être réutilisée. Cette option peut aider à contourner les problèmes dans un travail de base de données de longue durée (c'est-à-dire si une procédure perd de la mémoire), mais n'est évidemment pas une solution à long terme.
`ibm_db2.i5_override_ccsid` int
  Le CCSID PASE à utiliser pour les conversions de caractères d'EBCDIC sur IBM i. Par défaut, c'est `0`, ce qui sélectionnera le CCSID de travail PASE par défaut, provenant des paramètres de localisation PASE. Par exemple, en le réglant sur `1208`, on utilisera l'UTF-8. Cela ne doit être modifié que si le CCSID du travail PASE n'est pas le CCSID attendu, et que la localisation ne peut pas être modifiée. Pour en savoir plus sur les CCSID sur IBM i, consulter la » documentation IBM. Pour savoir comment les localisations sur IBM i PASE sont mappées sur les CCSID, consulter la » documentation IBM.
`ibm_db2.i5_sys_naming` int

  Cette option contrôle le mode de nommage lors de la connexion à un système IBM i. Par défaut, cette option est `0`. Le mode de nommage affecte la résolution des noms et la syntaxe autorisée pour les noms. Lorsqu'il est réglé sur `0`, cela utilise des points pour qualifier les noms et utilise la bibliothèque ou l'ID utilisateur par défaut pour résoudre les noms. Lorsqu'il est réglé sur `1`, cela utilise des barres obliques pour qualifier les noms et utilise la liste de bibliothèques de travail pour résoudre les noms.

  - 0 - Utilise le mode de nommage SQL ("SCHEMA.TABLE").
  - 1 - Utilise le mode de nommage système ("LIBRARY/FILE").
  Pour en savoir plus sur les modes de nommage sur IBM i, consulter la » documentation IBM.
`ibm_db2.i5_servermode-subsystem` string
  Cette option modifie le sous-système sous lequel les travaux du serveur de base de données s'exécutent sur IBM i. Par défaut, cette option est `null`, donc les travaux s'exécuteront sous le sous-système par défaut pour les travaux QSQSRVR.
`ibm_db2.instance_name` string

  Sur les systèmes d'exploitation Linux et UNIX, cette option définit le nom de l'instance à utiliser pour les connexions de base de données cataloguées. Par défaut, cette option est `null`. Si cette option est définie, sa valeur remplace le réglage de la variable d'environnement DB2INSTANCE.

  Cette option est ignorée sur les systèmes d'exploitation Windows.

## Types de ressources

L'extension ibm_db2 retourne des ressources de connexion, des ressources de déclaration et des ressources de jeu de résultats.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`DB2_BINARY` (int)
  Spécifie que les données binaires seront retournées telles quelles. Ceci est le mode par défaut.
`DB2_CONVERT` (int)
  Spécifie que les données binaires seront converties en hexadécimal et retournées comme une chaîne ASCII.
`DB2_PASSTHRU` (int)
  Spécifie que les données binaires seront converties en valeur `null`.
`DB2_SCROLLABLE` (int)
  Spécifie un curseur de défilement pour une ressource de requête. Ce mode permet un accès aléatoire aux lignes d'un jeu de résultats, mais présentement, il est supporté seulement par IBM DB2 Universal Database.
`DB2_FORWARD_ONLY` (int)
  Spécifie un curseur unidirectionnel pour une ressource de requête. Il s'agit du type de curseur par défaut, supporté sur tous les serveurs de base de données.
`DB2_PARAM_IN` (int)
  Spécifie que la variable PHP devrait être liée comme paramètre ENTRANT pour une procédure stockée.
`DB2_PARAM_OUT` (int)
  Spécifie que la variable PHP devrait être liée comme paramètre SORTANT pour une procédure stockée.
`DB2_PARAM_INOUT` (int)
  Spécifie que la variable PHP devrait être liée comme paramètre ENTRANT/SORTANT pour une procédure stockée.
`DB2_PARAM_FILE` (int)
  Spécifie que la colonne devrait être liée directement à un fichier en entrée.
`DB2_AUTOCOMMIT_ON` (int)
  Spécifie que l'autocommit devrait être activé.
`DB2_AUTOCOMMIT_OFF` (int)
  Spécifie que l'autocommit devrait être désactivé.
`DB2_DOUBLE` (int)
  Spécifie que la variable devrait être liée à un type DOUBLE, FLOAT ou REAL.
`DB2_LONG` (int)
  Spécifie que la variable devrait être liée à un type SMALLINT, INTEGER ou BIGINT.
`DB2_CHAR` (int)
  Spécifie que la variable devrait être liée à un type CHAR ou VARCHAR.
`DB2_CASE_NATURAL` (int)
  Spécifie que les noms de colonnes seront retournés dans leur casse naturelle.
`DB2_CASE_LOWER` (int)
  Spécifie que les noms de colonnes seront retournés en minuscules.
`DB2_CASE_UPPER` (int)
  Spécifie que les noms de colonnes seront retournés en majuscules.
`DB2_DEFERRED_PREPARE_ON` (int)
  Spécifie que la préparation différée devrait être activée pour la ressource de requête spécifiée.
`DB2_DEFERRED_PREPARE_OFF` (int)
  Spécifie que la préparation différée devrait être désactivée pour la ressource de requête spécifiée.

# Fonctions IBM DB2

# db2_autocommit

(PECL ibm_db2 >= 1.0.0)

db2_autocommit — Retourne ou modifie l'état AUTOCOMMIT de la connexion à la base de données

### Description

function db2_autocommit(resource `$connection`, int `$value` = ?): int|bool

Modifie ou lit le comportement de AUTOCOMMIT de la connexion spécifiée.

### Liste de paramètres

`connection`
  Une variable de connexion à une base de données valide retournée par db2_connect() ou db2_pconnect().
`value`

  Une des constantes suivantes :

  `DB2_AUTOCOMMIT_OFF`
    Désactive AUTOCOMMIT.
  `DB2_AUTOCOMMIT_ON`
    Active AUTOCOMMIT.

### Valeurs de retour

Lorsque db2_autocommit() reçoit seulement `connection` comme paramètre, la fonction retourne un entier représentant l'état courant de AUTOCOMMIT de la connexion fournie. Une valeur de `DB2_AUTOCOMMIT_OFF` signifie que AUTOCOMMIT est désactivé, tandis qu'une valeur de `DB2_AUTOCOMMIT_ON` signifie que AUTOCOMMIT est activé.

Lorsque db2_autocommit() reçoit les deux paramètres `connection` et `autocommit`, la fonction essaie de modifier l'état AUTOCOMMIT à l'état `autocommit` de la connexion fournie. Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Récupération de la valeur de AUTOCOMMIT pour une connexion

Dans l'exemple suivant, une connexion qui a été initialisée avec l'état AUTOCOMMIT désactivé est testée avec la fonction db2_autocommit().

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- AUTOCOMMIT est désactivé.";
    } else {
        print "$ac -- AUTOCOMMIT est activé.";
    }
    ?>

L'exemple ci-dessus va afficher :

    0 -- AUTOCOMMIT est désactivé.

Exemple #2 Modification de la valeur de AUTOCOMMIT pour une connexion

Dans l'exemple suivant, une connexion qui a été préalablement initialisée avec l'état AUTOCOMMIT désactivé a son comportement changé lors de l'activation de l'état AUTOCOMMIT.

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);

    // Active AUTOCOMMIT
    $rc = db2_autocommit($conn, DB2_AUTOCOMMIT_ON);
    if ($rc) {
        print "Activation AUTOCOMMIT réussie.\n";
    }

    // Vérification de l'état AUTOCOMMIT
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- AUTOCOMMIT est désactivé.";
    } else {
        print "$ac -- AUTOCOMMIT est activé.";
    }
    ?>

L'exemple ci-dessus va afficher :

    Activation AUTOCOMMIT réussie.
    1 -- AUTOCOMMIT est activé.

### Voir aussi

- db2_connect() - Retourne une connexion à une base de données
- db2_pconnect() - Retourne une connexion persistante à une base de données

# db2_bind_param

(PECL ibm_db2 >= 1.0.0)

db2_bind_param — Associe une variable PHP à un paramètre d'une requête SQL

### Description

function db2_bind_param(
resource `$stmt`,
int `$parameter_number`,
string `$variable_name`,
int `$parameter_type` = `DB2_PARAM_IN`,
int `$data_type` = 0,
int `$precision` = -1,
int `$scale` = 0
): bool

Associe une variable PHP à un paramètre d'une requête SQL dans une ressource de requête retournée par db2_prepare(). Cette fonction donne plus de contrôle sur le type de paramètre, le type de données, la précision et l'échelle du paramètre que le simple fait de passer la variable comme élément du tableau d'entrée optionnel de db2_execute().

### Liste de paramètres

`stmt`
  Une requête préparée retournée par db2_prepare().
`parameter_number`
  Spécifie la position du paramètre commençant à l'indice 1 dans la requête préparée.
`variable_name`
  Une chaîne spécifiant le nom de la variable PHP à associer au paramètre spécifié par `parameter_number`.
`parameter_type`
  Une constante spécifiant si la variable PHP devrait être associée au paramètre SQL en tant que paramètre entrant (`DB2_PARAM_IN`), que paramètre sortant (`DB2_PARAM_OUT`) ou en tant que paramètre qui accepte les entrées et les sorties (`DB2_PARAM_INOUT`). Pour éviter une surconsommation de la mémoire, il est aussi possible de spécifier `DB2_PARAM_FILE` pour attacher la variable PHP au nom du fichier qui contient les données de l'objet large (BLOB, CLOB ou DBCLOB).
`data_type`
  Une constante spécifiant le type de données SQL auquel la variable PHP devrait être associée : l'une des valeurs `DB2_BINARY`, `DB2_CHAR`, `DB2_DOUBLE` ou `DB2_LONG`.
`precision`
  Spécifie la précision à laquelle la variable devrait être associée à la base de données. Ce paramètre peut également être utilisé pour récupérer des valeurs de sortie XML pour les procédures stockées. Une valeur non négative spécifie la taille maximale des données XML qui seront récupérées depuis la base de données. Si ce paramètre n'est pas utilisé, une taille par défaut de 1 Mo sera définie pour récupérer les valeurs de sortie XML depuis la procédure stockée.
`scale`
  Spécifie l'échelle à laquelle la variable devrait être associée à la base de données.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Association de variables PHP à une requête préparée

La requête SQL dans l'exemple suivant utilise deux paramètres d'entrée dans la clause WHERE. Nous appelons db2_bind_param() pour associer deux variables PHP aux paramètres SQL correspondants. Il est à noter que les variables PHP n'ont pas besoin d'être déclarées ou assignées avant l'appel à db2_bind_param() ; dans cet exemple, `$lower_limit` est assignée avant l'appel à db2_bind_param(), mais `$upper_limit` est assignée après l'appel à db2_bind_param(). Les variables doivent être associées et, pour les paramètres qui acceptent une entrée, une valeur doit leur être assignée, avant d'appeler db2_execute().

    <?php

    $sql = 'SELECT name, breed, weight FROM animals
        WHERE weight > ? AND weight < ?';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    // Nous pouvons déclarer la variable avant d'appeler db2_bind_param()
    $lower_limit = 1;

    db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);

    // Nous pouvons aussi déclarer la variable après l'appel de db2_bind_param()
    $upper_limit = 15.0;

    if (db2_execute($stmt)) {
        while ($row = db2_fetch_array($stmt)) {
            print "{$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

L'exemple ci-dessus va afficher :

    Pook, cat, 3.2
    Rickety Ride, goat, 9.7
    Peaches, dog, 12.3

Exemple #2 Appel de procédures stockées avec des paramètres IN et OUT

La procédure stockée match_animal dans l'exemple suivant accepte trois paramètres différents :

1. un paramètre d'entrée (IN) qui accepte le nom du premier animal en entrée
2. un paramètre d'entrée-sortie (INOUT) qui accepte le nom du second animal en entrée et retourne la chaîne `TRUE` si un animal de la base de données correspond à ce nom
3. un paramètre de sortie (OUT) qui retourne la somme des poids des deux animaux identifiés

De plus, la procédure stockée retourne un jeu de résultats contenant les animaux listés par ordre alphabétique, en commençant par l'animal correspondant à la valeur d'entrée du premier paramètre et en terminant par l'animal correspondant à la valeur d'entrée du second paramètre.

    <?php

    $sql = 'CALL match_animal(?, ?, ?)';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    $name = "Peaches";
    $second_name = "Rickety Ride";
    $weight = 0;

    db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "second_name", DB2_PARAM_INOUT);
    db2_bind_param($stmt, 3, "weight", DB2_PARAM_OUT);

    print "Valeurs des paramètres associés _avant_ CALL :\n";
    print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

    if (db2_execute($stmt)) {
        print "Valeurs des paramètres associés _après_ CALL :\n";
        print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

        print "Résultats :\n";
        while ($row = db2_fetch_array($stmt)) {
            print "  {$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

L'exemple ci-dessus va afficher :

    Valeurs des paramètres associés _avant_ CALL :
      1: Peaches 2: Rickety Ride 3: 0

    Valeurs des paramètres associés _après_ CALL :
      1: Peaches 2: TRUE 3: 22

    Résultats :
      Peaches, dog, 12.3
      Pook, cat, 3.2
      Rickety Ride, goat, 9.7

Exemple #3 Insertion d'un objet large binaire (BLOB) provenant directement d'un fichier

Les données pour les objets larges sont normalement enregistrées dans des fichiers, comme des documents XML ou des fichiers audio. Plutôt que de lire le fichier en entier dans une variable de PHP et ensuite associer la variable PHP dans la requête SQL, il est possible d'éviter certains surcoûts de mémoire en associant le fichier directement au paramètre d'entrée de la requête SQL. L'exemple suivant démontre comment associer un fichier directement dans une colonne BLOB.

    <?php
    $stmt = db2_prepare($conn, "INSERT INTO animal_pictures(picture) VALUES (?)");

    $picture = "/opt/albums/spook/grooming.jpg";
    $rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
    $rc = db2_execute($stmt);
    ?>

### Voir aussi

- db2_execute() - Exécute une requête SQL préparée
- db2_prepare() - Prépare une requête SQL à être exécutée

# db2_client_info

(PECL ibm_db2 >= 1.1.1)

db2_client_info — Retourne un objet avec des propriétés qui décrivent le client de base de données DB2

### Description

function db2_client_info(resource `$connection`): stdClass|false

Cette fonction retourne un objet avec des propriétés en lecture seule qui retournent des informations à propos du client de base de données DB2. La table suivante liste les propriétés du client DB2 :

Propriétés du client DB2
Nom de la propriété | Type de retour | Description
--- | --- | ---
APPL_CODEPAGE | entier | Le code page de l'application.
CONN_CODEPAGE | entier | Le code page pour la connexion courante.
DATA_SOURCE_NAME | chaîne de caractères | Le nom de la source de données (DSN) utilisé pour créer la connexion courante à la base de données.
DRIVER_NAME | chaîne de caractères | Le nom de la bibliothèque qui implémente la spécification `DB2 Call Level Interface` (CLI).
DRIVER_ODBC_VER | chaîne de caractères | La version d'ODBC que le client DB2 supporte. Ceci retourne une chaîne de caractères `"MM.mm"` où MM est la version majeure et mm est la version mineure. Le client DB2 retourne toujours `"03.51"`.
DRIVER_VER | chaîne de caractères | La version du client, dans la forme d'une chaîne de caractères `"MM.mm.uuuu"` où MM est la version majeure, mm est la version mineure et uuuu est la mise à jour. Par exemple, `"08.02.0001"` représente la version majeure 8, la version mineure 2, et la mise à jour 1.
ODBC_SQL_CONFORMANCE | chaîne de caractères | Le niveau de grammaire SQL ODBC supporté par le client : MINIMUM Supporte le minimum de grammaire SQL d'ODBC. CORE Supporte le noyau de grammaire SQL d'ODBC. EXTENDED Supporte la grammaire étendue SQL d'ODBC.
ODBC_VER | chaîne de caractères | La version d'ODBC que le gestionnaire de pilote ODBC supporte. Cela retourne une chaîne de caractères `"MM.mm.rrrr"` où MM est la version majeure, mm est la version mineure et rrrr est la mise à jour. Le client DB2 retourne toujours `"03.01.0000"`.

### Liste de paramètres

`connection`
  Spécifie la connexion cliente DB2 active.

### Valeurs de retour

Retourne un objet si l'appel est réussi, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec db2_client_info()

Pour récupérer des informations à propos du client, il faut passer une ressource de connexion de base de données valide à la fonction db2_client_info().

    <?php
    $conn = db2_connect( 'SAMPLE', 'db2inst1', 'ibmdb2' );
    $client = db2_client_info( $conn );

    if ($client) {
        echo "DRIVER_NAME: ";   var_dump( $client->DRIVER_NAME );
        echo "DRIVER_VER: ";   var_dump( $client->DRIVER_VER );
        echo "DATA_SOURCE_NAME: ";   var_dump( $client->DATA_SOURCE_NAME );
        echo "DRIVER_ODBC_VER: ";   var_dump( $client->DRIVER_ODBC_VER );
        echo "ODBC_VER: ";    var_dump( $client->ODBC_VER );
        echo "ODBC_SQL_CONFORMANCE: ";  var_dump( $client->ODBC_SQL_CONFORMANCE );
        echo "APPL_CODEPAGE: ";   var_dump( $client->APPL_CODEPAGE );
        echo "CONN_CODEPAGE: ";   var_dump( $client->CONN_CODEPAGE );
    }
    else {
        echo "Erreur de récupération des informations du client.
         Peut-être que la connexion à la base de données était invalide.";
    }
    db2_close($conn);

    ?>

L'exemple ci-dessus va afficher :

    DRIVER_NAME: string(8) "libdb2.a"
    DRIVER_VER: string(10) "08.02.0001"
    DATA_SOURCE_NAME: string(6) "SAMPLE"
    DRIVER_ODBC_VER: string(5) "03.51"
    ODBC_VER: string(10) "03.01.0000"
    ODBC_SQL_CONFORMANCE: string(8) "EXTENDED"
    APPL_CODEPAGE: int(819)
    CONN_CODEPAGE: int(819)

### Voir aussi

- db2_server_info() - Retourne un objet avec des propriétés qui décrivent le serveur de base de données DB2

# db2_close

(PECL ibm_db2 >= 1.0.0)

db2_close — Ferme une connexion de base de données

### Description

function db2_close(resource `$connection`): bool

Cette fonction ferme la connexion client DB2 initialisée avec db2_connect() et libère les ressources correspondantes du serveur de base de données.

En tentant de fermer une connexion client DB2 persistante initialisée avec db2_pconnect(), la requête de fermeture est ignorée et la connexion client DB2 persistante reste disponible pour de prochains appels.

### Liste de paramètres

`connection`
  Spécifie une connexion client DB2 active.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Fermeture d'une connexion

L'exemple suivant montre une tentative réussie de fermeture de connexion d'une base de données IBM DB2, Cloudscape ou Apache Derby.

    <?php
    $conn = db2_connect('SAMPLE', 'db2inst1', 'ibmdb2');
    $rc = db2_close($conn);
    if ($rc) {
        echo "La connexion a été correctement fermée.";
    }
    ?>

L'exemple ci-dessus va afficher :

    La connexion a été correctement fermée.

### Voir aussi

- db2_connect() - Retourne une connexion à une base de données
- db2_pclose() - Ferme une connexion persistante à la base de données
- db2_pconnect() - Retourne une connexion persistante à une base de données

# db2_column_privileges

(PECL ibm_db2 >= 1.0.0)

db2_column_privileges — Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table

### Description

function db2_column_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, passez `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les tables. Pour concorder avec tous les schémas, passez `null` ou une chaîne vide.
`table_name`
  Le nom de la table ou de la vue. Pour obtenir toutes les tables dans la base de données, passez `null` ou une chaîne vide.
`column_name`
  Le nom de la colonne. Pour obtenir toutes les colonnes de la table, passez `null` ou une chaîne vide.

### Valeurs de retour

Retourne une ressource avec le jeu de résultats contenant les lignes qui décrivent les privilèges des colonnes concordant avec les paramètres spécifiés. Les lignes sont composées des colonnes suivantes :

Nom de la colonne | Description
--- | ---
TABLE_CAT | Nom du catalogue. La valeur est `null` si la table ne possède pas de catalogue.
TABLE_SCHEM | Nom du schéma.
TABLE_NAME | Nom de la table ou de la vue.
COLUMN_NAME | Nom de la colonne.
GRANTOR | ID d'autorisation de l'utilisateur qui a donné le privilège.
GRANTEE | ID d'autorisation de l'utilisateur à qui le privilège a été donné.
PRIVILEGE | Le privilège pour la colonne.
IS_GRANTABLE | Si GRANTEE a la permission d'accorder ce privilège à d'autres utilisateurs.

### Voir aussi

- db2_columns() - Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_foreign_keys() - Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_primary_keys() - Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedure_columns() - Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_procedures() - Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_special_columns() - Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_statistics() - Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_table_privileges() - Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
- db2_tables() - Retourne la liste des tables et leurs métadonnées

# db2_columns

(PECL ibm_db2 >= 1.0.0)

db2_columns — Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table

### Description

function db2_columns(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, passez `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les tables. Pour concorder avec tous les schémas, passez `'%'`.
`table_name`
  Le nom de la table ou de la vue. Pour obtenir toutes les tables dans la base de données, passez `null` ou une chaîne vide.
`column_name`
  Le nom de la colonne. Pour obtenir toutes les colonnes de la table, passez `null` ou une chaîne vide.

### Valeurs de retour

Retourne une ressource avec le jeu de résultats contenant les lignes qui décrivent les colonnes concordant avec les paramètres spécifiés. Les lignes sont composées des colonnes suivantes :

Nom de la colonne | Description
--- | ---
TABLE_CAT | Nom du catalogue. La valeur est `null` si la table ne possède pas de catalogue.
TABLE_SCHEM | Nom du schéma.
TABLE_NAME | Nom de la table ou de la vue.
COLUMN_NAME | Nom de la colonne.
DATA_TYPE | Le type de données SQL pour la colonne, représenté comme un entier.
TYPE_NAME | Une chaîne représentant le type de données pour la colonne.
COLUMN_SIZE | Un entier représentant la grandeur de la colonne.
BUFFER_LENGTH | Nombre maximal d'octets nécessaires pour enregistrer des données de cette colonne.
DECIMAL_DIGITS | L'échelle de la colonne ou `null` lorsque l'échelle n'est pas applicable.
NUM_PREC_RADIX | Un entier pouvant être `10` (représentant un type de données numérique exact), `2` (représentant un type de données numérique approximatif) ou `null` (représentant un type de données pour lequel la base n'est pas applicable).
NULLABLE | Un entier représentant si la colonne peut être nulle ou pas.
REMARKS | Description de la colonne.
COLUMN_DEF | Valeur par défaut de la colonne.
SQL_DATA_TYPE | Un entier représentant la grandeur de la colonne.
SQL_DATETIME_SUB | Retourne un entier représentant un code de sous-type `datetime` ou `null` pour les types de données SQL auxquels cela ne s'applique pas.
CHAR_OCTET_LENGTH | Longueur maximale en octets pour une colonne de type caractère, qui concorde avec COLUMN_SIZE pour les données d'un jeu de caractères sur un octet, ou `null` pour les types de données non-caractères.
ORDINAL_POSITION | La position de la colonne commençant à 1 dans la table.
IS_NULLABLE | Une chaîne dont la valeur 'YES' signifie que la colonne peut être nulle et 'NO' signifie que la colonne ne peut être nulle.

### Voir aussi

- db2_column_privileges() - Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_foreign_keys() - Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_primary_keys() - Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedure_columns() - Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_procedures() - Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_special_columns() - Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_statistics() - Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_table_privileges() - Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
- db2_tables() - Retourne la liste des tables et leurs métadonnées

# db2_commit

(PECL ibm_db2 >= 1.0.0)

db2_commit — Valide la transaction

### Description

function db2_commit(resource `$connection`): bool

Valide une transaction en cours sur la ressource de connexion spécifiée et commence une nouvelle transaction. Les applications PHP ont normalement le mode AUTOCOMMIT activé par défaut, donc db2_commit() n'est pas nécessaire tant que AUTOCOMMIT n'est pas désactivé pour la ressource de connexion.

### Liste de paramètres

`connection`
  Une variable ressource de connexion à la base de données valide retournée par db2_connect() ou db2_pconnect().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- db2_autocommit() - Retourne ou modifie l'état AUTOCOMMIT de la connexion à la base de données
- db2_rollback() - Annule une transaction

# db2_conn_error

(PECL ibm_db2 >= 1.0.0)

db2_conn_error — Retourne une chaîne contenant la valeur de SQLSTATE retournée par la dernière tentative de connexion

### Description

function db2_conn_error(?resource `$connection` = `null`): string

db2_conn_error() retourne la valeur de SQLSTATE représentant la raison pour laquelle la dernière tentative de connexion à la base de données a échoué. Comme db2_connect() retourne `false` en cas de tentative de connexion échouée, il ne faut passer aucun paramètre à db2_conn_error() pour obtenir la valeur de SQLSTATE.

Si par contre la connexion était réussie mais est devenue invalide avec le temps, il est possible de passer le paramètre de connexion `connection` pour obtenir la valeur de SQLSTATE pour la connexion spécifique.

Pour comprendre les valeurs de SQLSTATE, il est possible de taper la commande suivante dans le processeur de ligne de commandes de DB2 : `db2 '? `sqlstate-value`'`. Il est aussi possible d'appeler la fonction db2_conn_errormsg() pour obtenir un message d'erreur explicite ainsi que la valeur de SQLCODE associée.

### Liste de paramètres

`connection`
  Une ressource de connexion associée à la connexion qui a préalablement été réussie, mais qui est devenue invalide avec le temps.

### Valeurs de retour

Retourne la valeur de SQLSTATE résultant d'une mauvaise tentative de connexion. Retourne une chaîne vide s'il n'y a pas d'erreur associée avec la dernière tentative de connexion.

### Exemples

Exemple #1 Récupération de la valeur de SQLSTATE pour une tentative de connexion échouée

L'exemple suivant montre comment retourner une valeur de SQLSTATE après un passage forcé d'un paramètre invalide à la fonction db2_connect().

    <?php
    $conn = db2_connect('mauvaisnom', 'mauvaisutilisateur', 'mauvaismotdepasse');
    if (!$conn) {
        print "Valeur de SQLSTATE : " . db2_conn_error();
    }
    ?>

L'exemple ci-dessus va afficher :

    Valeur de SQLSTATE : 08001

### Voir aussi

- db2_conn_errormsg() - Retourne le dernier message d'erreur de connexion ainsi que la valeur de SQLCODE
- db2_connect() - Retourne une connexion à une base de données
- db2_stmt_error() - Retourne une chaîne contenant la valeur de SQLSTATE retournée par une requête SQL
- db2_stmt_errormsg() - Retourne le dernier message d'erreur d'une requête SQL

# db2_conn_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_conn_errormsg — Retourne le dernier message d'erreur de connexion ainsi que la valeur de SQLCODE

### Description

function db2_conn_errormsg(?resource `$connection` = `null`): string

db2_conn_errormsg() retourne un message d'erreur et la valeur de SQLCODE représentant la raison pour laquelle la dernière tentative de connexion à la base de données a échoué. Comme db2_connect() retourne `false` en cas d'une tentative de connexion échouée, il ne faut passer aucun paramètre à db2_conn_errormsg() pour obtenir le message d'erreur et la valeur de SQLCODE associés.

Si par contre la connexion était réussie mais est devenue invalide avec le temps, il est possible de passer le paramètre de connexion `connection` pour obtenir le message d'erreur et la valeur de SQLCODE pour la connexion spécifique.

### Liste de paramètres

`connection`
  Une ressource de connexion associée à la connexion qui a préalablement été réussie, mais qui est devenue invalide avec le temps.

### Valeurs de retour

Retourne une chaîne contenant le message d'erreur et la valeur de SQLCODE résultant d'une mauvaise tentative de connexion. Retourne une chaîne vide s'il n'y a pas d'erreur associée avec la dernière tentative de connexion.

### Exemples

Exemple #1 Récupération du message d'erreur retourné par une tentative de connexion échouée

L'exemple suivant montre comment retourner un message d'erreur ainsi que la valeur de SQLCODE après un passage forcé d'un paramètre invalide à la fonction db2_connect().

    <?php
    $conn = db2_connect('badname', 'baduser', 'badpassword');
    if (!$conn) {
        print db2_conn_errormsg();
    }
    ?>

L'exemple ci-dessus va afficher :

    [IBM][CLI Driver] SQL1013N  The database alias name
    or database name "BADNAME" could not be found.  SQLSTATE=42705
     SQLCODE=-1013

### Voir aussi

- db2_conn_error() - Retourne une chaîne contenant la valeur de SQLSTATE retournée par la dernière tentative de connexion
- db2_connect() - Retourne une connexion à une base de données
- db2_stmt_error() - Retourne une chaîne contenant la valeur de SQLSTATE retournée par une requête SQL
- db2_stmt_errormsg() - Retourne le dernier message d'erreur d'une requête SQL

# db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — Retourne une connexion à une base de données

### Description

function db2_connect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Crée une nouvelle connexion à une base de données IBM DB2 Universal Database, IBM Cloudscape ou Apache Derby.

### Liste de paramètres

`database`
  Pour une connexion cataloguée de la base de données, `database` représente l'alias de la base de données dans le catalogue client DB2

  Pour une connexion non cataloguée de la base de données, `database` représente une chaîne complète de connexion qui est dans le format suivant :

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Note:

  > Lors de la connexion à Db2 sur IBM i, les appels système sous-jacents » SQLDriverConnect, n'acceptent que DSN, UID et PWD pour la » chaîne de connexion. Comme suit :

  >     DSN=database;UID=username;PWD=password;

  où les paramètres représentent les valeurs suivantes :
  `database`
    Le nom de la base de données.
  `hostname`
    L'adresse Internet ou IP du serveur de base de données.
  `port`
    Le port TCP/IP sur lequel la base de données écoute les connexions.
  `username`
    Le nom d'utilisateur utilisé pour la connexion à la base de données.
  `password`
    Le mot de passe utilisé pour la connexion à la base de données.
`username`
  Le nom d'utilisateur utilisé pour la connexion à la base de données. Pour les connexions non cataloguées, il faut passer une valeur `null` ou une chaîne vide.
`password`
  Le mot de passe utilisé pour la connexion à la base de données. Pour les connexions non cataloguées, il faut passer une valeur `null` ou une chaîne vide.
`options`

  Un tableau associatif des options de connexion qui affecteront le comportement de la connexion, où les valeurs des clés incluent :

  `autocommit`
    La valeur `DB2_AUTOCOMMIT_ON` active l'autocommit sur cette connexion. La valeur `DB2_AUTOCOMMIT_OFF` désactive l'autocommit pour cette connexion.
  `DB2_ATTR_CASE`
    Passer la valeur `DB2_CASE_NATURAL` spécifie que les noms de colonnes seront retournés dans leurs casses naturelles. Passer la valeur `DB2_CASE_LOWER` spécifie que les noms de colonnes seront retournés en minuscule. Passer la valeur `DB2_CASE_UPPER` spécifie que les noms de colonnes seront retournés en majuscule.
  `CURSOR`
    Passer la valeur `DB2_FORWARD_ONLY` spécifie un curseur uniquement suivant pour une ressource de requête. C'est le type de curseur par défaut et est supporté sur tous les serveurs de base de données. Passer la valeur `DB2_SCROLLABLE` spécifie un curseur défilant pour une ressource de requête. Ce mode permet un accès aléatoire aux lignes dans un jeu de résultats, mais actuellement, n'est supporté que par la base de données IBM DB2 Universal.

  La nouvelle option suivante est disponible pour les versions ibm_db2 1.7.0 et suivantes.

  `trustedcontext`
    Le fait de passer la valeur DB2_TRUSTED_CONTEXT_ENABLE active le contexte de confiance pour ce gestionnaire de connexion. Ce paramètre ne peut être défini avec la fonction db2_set_option(). Cette clé fonctionne uniquement si la base de données est cataloguée (même si la base de données est locale), ou si l'on spécifie le DSN complet lors de la création de la connexion. Pour cataloguer la base de données, utiliser les commandes suivantes :

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
        db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
        db2 "update dbm cfg using svcename <SERVICENAME>"
        db2set DB2COMM=TCPIP

  Les nouvelles options i5/OS suivantes sont disponibles dans les versions ibm_db2 1.5.1 et suivantes.

  `i5_lib`
    Un caractère qui indique la bibliothèque par défaut qui sera utilisée pour résoudre les références aux fichiers non qualifiées. Ceci n'est pas valide si la connexion utilise un mode de système de nom.
  `i5_naming`
    La valeur `DB2_I5_NAMING_ON` active le mode de nommage système iSeries de DB2 UDB CLI. Les fichiers sont qualifiés en utilisant le délimiteur slash (/). Les fichiers non qualifiés sont résolus en utilisant la liste de bibliothèque pour le travail. La valeur `DB2_I5_NAMING_OFF` désactive le mode de nommage par défaut de DB2 UDB CLI, qui est le nommage SQL. Les fichiers sont qualifiés en utilisant le délimiteur point (.). Les fichiers non qualifiés sont résolus en utilisant soit la bibliothèque par défaut, soit l'ID de l'utilisateur courant.
  `i5_commit`

    L'attribut `i5_commit` devrait être fixé avant l'appel à db2_connect(). Si la valeur est changée après que la connexion a été établie et que la connexion est à une source de données distante, le changement ne prendra effet qu'au prochain appel réussi de db2_connect() pour le gestionnaire de connexion.

    > Note: La configuration php.ini `ibm_db2.i5_allow_commit`==0 ou `DB2_I5_TXN_NO_COMMIT` est par défaut, mais peut être remplacée avec l'option `i5_commit`.

    `DB2_I5_TXN_NO_COMMIT` : le contrôle de validation n'est pas utilisé. `DB2_I5_TXN_READ_UNCOMMITTED` : Les lectures sales, non répétables et fantômes sont possibles. `DB2_I5_TXN_READ_COMMITTED` : Les lectures sales ne sont pas possibles. Les lectures non répétables et fantômes sont possibles. `DB2_I5_TXN_REPEATABLE_READ` : Les lectures sales et non répétables ne sont pas possibles. Les lectures fantômes sont possibles. `DB2_I5_TXN_SERIALIZABLE` : les transactions sont sérialisées. Les lectures sales, non répétables et fantômes ne sont pas possibles.
  `i5_query_optimize`
    `DB2_FIRST_IO` Toutes les requêtes sont optimisées avec le but de retourner la première page aussi vite que possible. Ce but fonctionne bien lorsque les données de sortie sont contrôlées par un utilisateur qui est le plus susceptible d'annuler une requête après avoir vu la première page des données. Les requêtes sont codées avec une clause `"OPTIMIZE FOR nnn ROWS"` afin de honorer le but spécifié par la clause. `DB2_ALL_IO` Toutes les requêtes sont optimisées avec le but d'exécuter la requête entière jusqu'à la fin dans le plus petit intervalle de temps. C'est une bonne option lorsque les données de sortie d'une requête sont en train d'être écrites vers un fichier ou un rapport ou encore lorsque l'interface met en file d'attente les données. Les requêtes sont codées avec une clause `"OPTIMIZE FOR nnn ROWS"` afin de honorer le but spécifié par la clause. C'est la valeur par défaut.
  `i5_dbcs_alloc`
    La valeur `DB2_I5_DBCS_ALLOC_ON` active le canevas d'allocation DB2 6X pour l'accroissement des tailles des colonnes en traduction DBCS. La valeur `DB2_I5_DBCS_ALLOC_OFF` désactive le canevas d'allocation DB2 6X pour l'accroissement des tailles des colonnes en traduction DBCS. Note : la configuration php.ini `ibm_db2.i5_dbcs_alloc`==0 ou `DB2_I5_DBCS_ALLOC_OFF` est par défaut mais peut être remplacée avec l'option `i5_dbcs_alloc`.
  `i5_date_fmt`
    `DB2_I5_FMT_ISO` : le format de date de l'organisation internationale de normalisation (ISO) `"yyyy-mm-dd"` est utilisé. Ceci est la valeur par défaut. `DB2_I5_FMT_USA` : le format de date des États-Unis `"mm/dd/yyyy"` est utilisé. `DB2_I5_FMT_EUR` : le format de date européen `"dd.mm.yyyy"` est utilisé. `DB2_I5_FMT_JIS` : le format de date de la norme industrielle japonaise (JIS) `"yyyy-mm-dd"` est utilisé. `DB2_I5_FMT_MDY` : le format de date `"mm/dd/yyyy"` est utilisé. `DB2_I5_FMT_DMY` : le format de date `"dd/mm/yyyy"` est utilisé. `DB2_I5_FMT_YMD` : le format de date `"yy/mm/dd"` est utilisé. `DB2_I5_FMT_JUL` : le format de date julien `"yy/ddd"` est utilisé. `DB2_I5_FMT_JOB` : la valeur par défaut est utilisée.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` : un slash ( / ) est utilisé en tant que séparateur de date. Ceci est la valeur par défaut. `DB2_I5_SEP_DASH` : un tiret ( - ) est utilisé en tant que séparateur de date. `DB2_I5_SEP_PERIOD` : un point ( . ) est utilisé en tant que séparateur de date. `DB2_I5_SEP_COMMA` : une virgule ( , ) est utilisée en tant que séparateur de date. `DB2_I5_SEP_BLANK` : un espace blanc est utilisé en tant que séparateur de date. `DB2_I5_SEP_JOB` : la valeur par défaut est utilisée.
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` : le format de l'heure de l'organisation internationale de normalisation (ISO) `"hh.mm.ss"` est utilisé. Ceci est la valeur par défaut. `DB2_I5_FMT_USA` : le format de l'heure des États-Unis `"hh:mmxx"` est utilisé, où `"xx"` vaut `"AM"` ou `"PM"`. `DB2_I5_FMT_EUR` : le format de l'heure européen `"hh.mm.ss"` est utilisé. `DB2_I5_FMT_JIS` : le format de l'heure de la norme industrielle japonaise `"hh:mm:ss"` est utilisé. `DB2_I5_FMT_HMS` : le format `"hh:mm:ss"` est utilisé.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` : un deux-points ( : ) est utilisé en tant que séparateur d'heure. Ceci est la valeur par défaut. `DB2_I5_SEP_PERIOD` : un point ( . ) est utilisé en tant que séparateur d'heure. `DB2_I5_SEP_COMMA` : une virgule ( , ) est utilisée en tant que séparateur d'heure. `DB2_I5_SEP_BLANK` : un espace blanc est utilisé en tant que séparateur d'heure. `DB2_I5_SEP_JOB` : la valeur par défaut est utilisée.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` : un point ( . ) est utilisé en tant que séparateur de décimale. Ceci est la valeur par défaut. `DB2_I5_SEP_COMMA` : une virgule ( , ) est utilisée en tant que séparateur de décimale. `DB2_I5_SEP_JOB` : la valeur par défaut est utilisée.

  La nouvelle option i5/OS suivante est disponible à partir de la version ibm_db2 1.8.0.

  `i5_libl`
    Une chaîne indiquant la liste de bibliothèques à utiliser pour résoudre les références de fichiers non qualifiés. Spécifier la liste en séparant les valeurs par un espace, comme ceci : 'i5_libl'=>"MYLIB YOURLIB ANYLIB".

    > Note: `i5_libl` appelle `qsys2/qcmdexc('cmd',cmdlen)`, qui n'est disponible qu'à partir de i5/OS V5R4.

### Valeurs de retour

Retourne la ressource de connexion si la tentative de connexion réussit. Si la tentative de connexion échoue, db2_connect() retourne `false`.

### Exemples

Exemple #1 Création d'une connexion cataloguée

Les connexions cataloguées nécessitent que l'on ait préalablement catalogué la base de données spécifiée à l'aide du processeur de ligne de commandes DB2 (`"Command Line Processor"` : CLP) ou avec l'assistant de configuration de DB2.

    <?php
    $database = 'EXEMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        echo "Connexion réussie.";
        db2_close($conn);
    }
    else {
        echo "Connexion échouée.";
    }
    ?>

L'exemple ci-dessus va afficher :

    Connexion réussie.

Exemple #2 Création d'une connexion non cataloguée

Une connexion non cataloguée permet de se connecter dynamiquement à une base de données.

    <?php
    $database = 'EXEMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $hostname = 'localhost';
    $port = 50000;

    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
      "HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;";
    $conn = db2_connect($conn_string, '', '');

    if ($conn) {
        echo "Connexion réussie.";
        db2_close($conn);
    }
    else {
        echo "Connexion échouée.";
    }
    ?>

L'exemple ci-dessus va afficher :

    Connexion réussie.

Exemple #3 Création d'une connexion avec autocommit désactivé par défaut

Le fait de passer un tableau d'option à db2_connect() permet de modifier le comportement par défaut de la connexion.

    <?php
    $database = 'EXEMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

    $conn = db2_connect($database, $user, $password, $options);

    if ($conn) {
        echo "Connexion réussie.\n";
        if (db2_autocommit($conn)) {
             echo "Autocommit est activé.\n";
        }
        else {
             echo "Autocommit est désactivé.\n";
        }
        db2_close($conn);
    }
    else {
        echo "Connexion échouée.";
    }
    ?>

L'exemple ci-dessus va afficher :

    Connexion réussie.
    Autocommit est désactivé.

Exemple #4 Meilleure performance i5/OS

Pour obtenir les meilleures performances de l'application PHP i5/OS ibm_db2 1.5.1, utiliser l'hôte par défaut, l'identifiant utilisateur et le mot de passe pour l'appel à db2_connect().

    <?php
      $library = "ADC";
      $i5 = db2_connect("", "", "", array("i5_lib"=>"qsys2"));
      $result = db2_exec($i5,
           "select * from systables where table_schema = '$library'");
      while ($row = db2_fetch_both($result)) {
         echo $row['TABLE_NAME']."</br>";
      }
      db2_close($i5);
    ?>

L'exemple ci-dessus va afficher :

    ANIMALS
    NAMES
    PICTURES

Exemple #5 Utilisation du contexte de confiance

L'exemple suivant montre comment activer le contexte de confiance, changer d'utilisateur et récupérer l'ID de l'utilisateur courant.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
      PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
    $options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_connect($dsn, "", "", $options);
    if($tc_conn) {
        echo "Connexion explicite de confiance réussie.\n";

        if(db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            //Code en tant qu'utilisateur 1.

            //Passage à l'utilisateur de confiance.
            $parameters = array("trusted_user" => $tc_user,
              "trusted_password" => $tcuser_pass);
            $res = db2_set_option ($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            //Code en tant qu'utilisateur de confiance.

            if($userBefore != $userAfter) {
                echo "L'utilisateur a changé." . "\n";
            }
        }

        db2_close($tc_conn);
    }
    else {
        echo "La connexion explicite de confiance a échoué.\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    Connexion explicite de confiance réussie.
    L'utilisateur a changé.

### Voir aussi

- db2_close() - Ferme une connexion de base de données
- db2_pconnect() - Retourne une connexion persistante à une base de données

# db2_cursor_type

(PECL ibm_db2 >= 1.0.0)

db2_cursor_type — Retourne le type de curseur utilisé par une ressource d'instruction

### Description

function db2_cursor_type(resource `$stmt`): int

Retourne le type de curseur utilisé par une ressource d'instruction. Cette fonction permet de déterminer si l'on travaille avec un curseur à avance seul ou un curseur flottant.

### Liste de paramètres

`stmt`
  Une ressource d'instruction valide.

### Valeurs de retour

Retourne `DB2_FORWARD_ONLY` si la ressource d'instruction utilise un curseur à avance seul ou `DB2_SCROLLABLE` si la ressource d'instruction utilise un curseur flottant.

### Voir aussi

- db2_prepare() - Prépare une requête SQL à être exécutée

# db2_escape_string

(PECL ibm_db2 >= 1.6.0)

db2_escape_string — Utilisé pour échapper certains caractères

### Description

function db2_escape_string(string `$string_literal`): string

Place des antislashs devant les caractères spéciaux à la chaîne de caractères passée en argument.

### Liste de paramètres

`string_literal`
  Une chaîne de caractères qui contient des caractères spéciaux qui doivent être modifiés. Les caractères qui sont transformés à l'aide d'un antislash sont `\x00`, `\n`, `\r`, `\`, `'`, `"` et `\x1a`.

### Valeurs de retour

Retourne `string_literal` avec les caractères spéciaux mentionnés ci-dessus précédés par des antislashs.

### Exemples

Exemple #1 Exemple avec db2_escape_string()

Résultat suite à l'utilisation de la fonction db2_escape_string()

    <?php

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $str[0] = "Tous les caractères : \x00 , \n , \r , \ , ' , \" , \x1a .";
        $str[1] = "Antislash (\). Apostrophe ('). Guillemet (\")";
        $str[2] = "Le caractère NULL \0 doit être transformé aussi";
        $str[3] = "Caractères intéressants : \x1a , \x00 .";
        $str[4] = "Rien à transformer";
        $str[5] = 200676;
        $str[6] = "";

        foreach( $str as $string ) {
            echo "db2_escape_string: " . db2_escape_string($string). "\n";
        }
    }
    ?>

L'exemple ci-dessus va afficher :

    db2_escape_string: Tous les caractères : \0 , \n , \r , \\ , \' , \" , \Z .
    db2_escape_string: Antislash (\\). Apostrophe (\'). Guillemet (\")
    db2_escape_string: Le caractère NULL \0 doit être transformé aussi
    db2_escape_string: Caractères intéressants : \Z , \0 .
    db2_escape_string: Rien à transformer
    db2_escape_string: 200676
    db2_escape_string:

### Voir aussi

- db2_prepare() - Prépare une requête SQL à être exécutée

# db2_exec

(PECL ibm_db2 >= 1.0.0)

db2_exec — Exécute une requête SQL directement

### Description

function db2_exec(resource `$connection`, string `$statement`, array `$options` = []): resource|false

Exécute une requête SQL directement.

Pour intercaler des variables PHP dans la requête SQL, il faut comprendre que c'est l'une des plus communes failles de sécurité. Il est recommandé d'appeler la fonction db2_prepare() pour préparer une requête SQL qui contient des marqueurs pour des variables d'entrée. Ensuite, il est possible d'appeler la fonction db2_execute() pour passer les valeurs d'entrée et ainsi éviter les attaques par injections SQL.

Pour appeler à plusieurs reprises la même requête SQL avec des paramètres différents, il est préférable d'appeler la fonction db2_prepare() et db2_execute() pour permettre au serveur de base de données de réutiliser son plan d'accès et ainsi augmenter l'efficacité de l'accès à la base de données.

### Liste de paramètres

`connection`
  Une variable ressource de connexion valide retournée par db2_connect() ou db2_pconnect().
`statement`
  Une requête SQL. La requête ne peut contenir de marqueur.
`options`
  Un tableau associatif contenant les options de la requête. Il est possible d'utiliser ce paramètre pour demander un curseur flottant sur les serveurs de base de données qui supportent cette fonctionnalité. Pour une description des options valides, se reporter à la fonction db2_set_option().

### Valeurs de retour

Retourne une variable ressource si la requête SQL était envoyée correctement ou `false` si la base de données n'a pas réussi à exécuter la requête SQL.

### Exemples

Exemple #1 Création d'une table avec db2_exec()

L'exemple suivant utilise la fonction db2_exec() pour envoyer un ensemble de requêtes DDL afin de créer une table.

    <?php
    $conn = db2_connect($database, $user, $password);

    // Crée la table de test
    $create = 'CREATE TABLE animaux (id INTEGER, race VARCHAR(32),
        nom CHAR(16), poids DECIMAL(7,2))';
    $result = db2_exec($conn, $create);
    if ($result) {
        print "La table a été créée correctement.\n";
    }

    // Remplit la table de test
    $animaux = array(
        array(0, 'chat', 'Pook', 3.2),
        array(1, 'chien', 'Peaches', 12.3),
        array(2, 'cheval', 'Smarty', 350.0),
        array(3, 'cyprin doré', 'Bubbles', 0.1),
        array(4, 'perruche', 'Gizmo', 0.2),
        array(5, 'chèvre', 'Rickety Ride', 9.7),
        array(6, 'lama', 'Sweater', 150)
    );

    foreach ($animaux as $animal) {
        $rc = db2_exec($conn, "INSERT INTO animaux (id, race, nom, poids)
          VALUES ({$animal[0]}, '{$animal[1]}', '{$animal[2]}', {$animal[3]})");
        if ($rc) {
            print "Insertion... ";
        }
    }
    ?>

L'exemple ci-dessus va afficher :

    La table a été créée correctement.
    Insertion... Insertion... Insertion... Insertion... Insertion... Insertion... Insertion...

Exemple #2 Exécution d'une requête SELECT avec un curseur flottant

L'exemple suivant montre comment demander un curseur flottant pour une requête SQL envoyée avec la fonction db2_exec().

    <?php
    $conn = db2_connect($database, $user, $password);
    $sql = "SELECT nom FROM animaux
        WHERE poids < 10.0
        ORDER BY nom";
    if ($conn) {
        require_once 'prepare.inc';
        $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
        while ($row = db2_fetch_array($stmt)) {
            print "$row[0]\n";
        }
    }
    ?>

L'exemple ci-dessus va afficher :

    Bubbles
    Gizmo
    Pook
    Rickety Ride

Exemple #3 Retourne des données XML en tant que ResultSet SQL

L'exemple suivant démontre comment utiliser des documents enregistrés dans une colonne XML en utilisant la base de données SAMPLE. En utilisant un simple SQL/XML, cet exemple retourne quelques nœuds dans un document XML dans un format ResultSet SQL dont la plupart des utilisateurs sont familiers.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = \'Kathy Smith\'
        ';
    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE\n");
    }
    db2_close($conn);

    ?>

L'exemple ci-dessus va afficher :

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Exemple #4 Exécuter un "JOIN" avec des données XML

L'exemple suivant fonctionne avec des documents enregistrés dans deux colonnes XML différentes de la base de données SAMPLE. Cela crée deux tables temporaires provenant des documents XML de deux colonnes XML différentes et retourne un ResultSet SQL avec les informations contenant le statut de livraison pour un client.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
        SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
        FROM
        XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" BIGINT PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) as A,
        PURCHASEORDER AS B,
        XMLTABLE (
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
        COLUMNS
        "PONUM"  BIGINT PATH \'@PoNum\',
        "STATUS" VARCHAR (50) PATH \'@Status\'
        ) as C
        WHERE A.CID = B.CUSTID AND
     B.POID = C.PONUM AND
     A.NAME = \'Kathy Smith\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
    }

    db2_close($conn);

    ?>

L'exemple ci-dessus va afficher :

    1001     Kathy Smith     905-555-7258     5002     Shipped

Exemple #5 Retourne des données SQL faisant partie d'un document XML large

L'exemple suivant utilise une portion des documents de PRODUCT.DESCRIPTION dans la base de données SAMPLE. Cela crée un document XML contenant la description du produit (données XML) et les informations concernant le prix (données SQL).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
            for $prod in $doc/product
            where $prod/description/price < 10.00
            order by $prod/description/price ascending
            return(
                <promoitem> {
                    $prod,
                    <startdate> {$start} </startdate>,
                    <enddate> {$end} </enddate>,
                    <promoprice> {$promo} </promoprice>
                } </promoitem>
            )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = \'100-100-01\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_array($stmt)){
     printf("$row[0]\n");
    }
    db2_close($conn);

    ?>

L'exemple ci-dessus va afficher :

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Voir aussi

- db2_execute() - Exécute une requête SQL préparée
- db2_prepare() - Prépare une requête SQL à être exécutée

# db2_execute

(PECL ibm_db2 >= 1.0.0)

db2_execute — Exécute une requête SQL préparée

### Description

function db2_execute(resource `$stmt`, array `$parameters` = []): bool

db2_execute() exécute une requête SQL qui a été préparée par db2_prepare().

Si la requête SQL retourne un jeu de résultats, par exemple, une requête SELECT ou un CALL à une procédure stockée retournant un ou plusieurs jeux de résultats, il est possible de récupérer une ligne en tant que tableau à partir de la ressource `stmt` en utilisant db2_fetch_assoc(), db2_fetch_both() ou db2_fetch_array(). Alternativement, il est possible d'utiliser db2_fetch_row() pour déplacer le pointeur du jeu de résultats à la ligne suivante et récupérer une colonne à la fois de cette ligne avec la fonction db2_result().

Se référer à db2_prepare() pour une brève discussion sur les avantages de l'utilisation de db2_prepare() et db2_execute() plutôt que db2_exec().

### Liste de paramètres

`stmt`
  Une requête préparée retournée par db2_prepare().
`parameters`
  Un tableau des paramètres d'entrée qui contient les marqueurs de variables contenus dans la requête préparée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Préparation et exécution d'une requête SQL avec des marqueurs

L'exemple suivant prépare une requête INSERT qui accepte quatre marqueurs, ensuite itère sur le tableau contenant les valeurs d'entrées qui sera passé à la fonction db2_execute().

    <?php
    $pet = array(0, 'cat', 'Pook', 3.2);

    $insert = 'INSERT INTO animals (id, breed, name, weight)
        VALUES (?, ?, ?, ?)';

    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        $result = db2_execute($stmt, $pet);
        if ($result) {
            print "Ajout d'un nouvel animal réussi.";
        }
    }
    ?>

L'exemple ci-dessus va afficher :

    Ajout d'un nouvel animal réussi.

Exemple #2 Appel d'une procédure stockée avec un paramètre de SORTIE

L'exemple suivant prépare une requête CALL qui accepte un marqueur qui représente un paramètre de SORTIE, lie la variable PHP `$my_pets` au paramètre en utilisant la fonction db2_bind_param() et appelle la fonction db2_execute() pour exécuter la requête CALL. Une fois que la requête CALL a été exécutée, la valeur de `$num_pets` change pour refléter la valeur retournée par la procédure stockée pour ce paramètre de SORTIE.

    <?php
    $num_pets = 0;
    $res = db2_prepare($conn, "CALL count_my_pets(?)");
    $rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT);
    $rc = db2_execute($res);
    print "Je possède $num_pets animaux !";
    ?>

L'exemple ci-dessus va afficher :

    Je possède 7 animaux !

Exemple #3 Retourne des données XML en tant que ResultSet SQL

L'exemple suivant démontre comment utiliser des documents enregistrés dans une colonne XML en utilisant la base de données SAMPLE. En utilisant un simple SQL/XML, cet exemple retourne quelques nœuds dans un document XML dans un format ResultSet SQL dont la plupart des utilisateurs sont familiers.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = ?
        ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
            printf("$row->CID     $row->NAME     $row->PHONE\n");
        }
    }
    db2_close($conn);

    ?>

L'exemple ci-dessus va afficher :

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Exemple #4 Exécuter un "JOIN" avec des données XML

L'exemple suivant fonctionne avec des documents enregistrés dans deux colonnes différentes dans la base de données SAMPLE. Cela crée deux tables temporaires provenant des documents XML de deux différentes colonnes XML et retourne un ResultSet SQL avec les informations contenant le statut de livraison pour un client.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
    FROM
    XMLTABLE(
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
    COLUMNS
    "CID" BIGINT PATH \'@Cid\',
    "NAME" VARCHAR (50) PATH \'name\',
    "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
    ) as A,
    PURCHASEORDER AS B,
    XMLTABLE (
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
    COLUMNS
    "PONUM"  BIGINT PATH \'@PoNum\',
    "STATUS" VARCHAR (50) PATH \'@Status\'
    ) as C
    WHERE A.CID = B.CUSTID AND
            B.POID = C.PONUM AND
            A.NAME = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
            printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
        }
    }

    db2_close($conn);

    ?>

L'exemple ci-dessus va afficher :

    1001     Kathy Smith     905-555-7258     5002     Shipped

Exemple #5 Retourne des données SQL faisant partie d'un document XML large

L'exemple suivant utilise une portion des documents de PRODUCT.DESCRIPTION dans la base de données SAMPLE. Cela crée un document XML contenant la description du produit (données XML) et les informations concernant le prix (données SQL).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
            for $prod in $doc/product
            where $prod/description/price < 10.00
            order by $prod/description/price ascending
            return(
                <promoitem> {
                    $prod,
                    <startdate> {$start} </startdate>,
                    <enddate> {$end} </enddate>,
                    <promoprice> {$promo} </promoprice>
                } </promoitem>
            )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $pid = "100-100-01";

    if ($stmt) {
        db2_bind_param($stmt, 1, "pid", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_array($stmt)){
            printf("$row[0]\n");
        }
    }

    db2_close($conn);

    ?>

L'exemple ci-dessus va afficher :

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Voir aussi

- db2_exec() - Exécute une requête SQL directement
- db2_fetch_array() - Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats
- db2_fetch_assoc() - Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats
- db2_fetch_both() - Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats
- db2_fetch_row() - Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée
- db2_prepare() - Prépare une requête SQL à être exécutée
- db2_result() - Retourne une colonne d'une ligne d'un jeu de résultats

# db2_fetch_array

(PECL ibm_db2 >= 1.0.1)

db2_fetch_array — Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats

### Description

function db2_fetch_array(resource `$stmt`, int `$row_number` = -1): array|false

Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats. Les indices du tableau sont numériques et commencent par zéro.

### Liste de paramètres

`stmt`
  Une ressource `stmt` valide contenant le jeu de résultats.
`row_number`
  Demande une ligne spécifique indexée numériquement qui commence par la valeur 1 au jeu de résultats. En fournissant ce paramètre, une alerte PHP sera générée si le jeu de résultats utilise un curseur d'avancement seul.

### Valeurs de retour

Retourne un tableau à indices numériques commençant à 0 indexé avec la position des colonnes. Cet indice pointe vers des données de la ligne suivante ou la ligne demandée dans le jeu de résultats. Retourne `false` s'il n'y a pas de ligne disponible dans le jeu de résultats ou si la ligne demandée par `row_number` n'existe pas dans le jeu de résultats.

### Exemples

Exemple #1 Itère avec un curseur d'avancement seul

Si l'on appelle db2_fetch_array() sans le numéro d'une ligne spécifique, la ligne suivante sera automatiquement récupérée dans le jeu de résultats.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_array($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
    }
    ?>

L'exemple ci-dessus va afficher :

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

Exemple #2 Récupération de lignes spécifiques avec db2_fetch_array() provenant d'un curseur flottant

Si le jeu de résultats utilise un curseur flottant, il est possible d'appeler la fonction db2_fetch_array() avec un numéro de ligne spécifique. L'exemple suivant récupère chaque ligne paire dans le jeu de résultats, commençant avec la deuxième ligne.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_array($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
        $i = $i + 2;
    }
    ?>

L'exemple ci-dessus va afficher :

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

### Voir aussi

- db2_fetch_assoc() - Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats
- db2_fetch_both() - Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats
- db2_fetch_object() - Retourne un objet avec les propriétés représentant des colonnes dans la ligne extraite
- db2_fetch_row() - Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée
- db2_result() - Retourne une colonne d'une ligne d'un jeu de résultats

# db2_fetch_assoc

(PECL ibm_db2 >= 1.0.0)

db2_fetch_assoc — Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats

### Description

function db2_fetch_assoc(resource `$stmt`, int `$row_number` = -1): array|false

Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats.

### Liste de paramètres

`stmt`
  Une ressource `stmt` valide contenant le jeu de résultats.
`row_number`
  Demande une ligne spécifique indexée numériquement qui commence par la valeur 1 dans le jeu de résultats. En fournissant ce paramètre, une alerte PHP sera générée si le jeu de résultats utilise un curseur d'avancement seul.

### Valeurs de retour

Retourne un tableau associatif avec les valeurs des colonnes indexées par le nom des colonnes représentant la ligne suivante ou la ligne demandée dans le jeu de résultats. Retourne `false` s'il n'y a pas de ligne disponible dans le jeu de résultats ou si la ligne demandée par `row_number` n'existe pas dans le jeu de résultats.

### Exemples

Exemple #1 Itère avec un curseur d'avancement seul

Si l'on appelle db2_fetch_assoc() sans le numéro d'une ligne spécifique, la ligne suivante sera automatiquement récupérée dans le jeu de résultats.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_assoc($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NOM'], $row['RACE'], $row['POIDS']);
    }
    ?>

L'exemple ci-dessus va afficher :

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

Exemple #2 Récupération de lignes spécifiques avec db2_fetch_assoc() provenant d'un curseur flottant

Si le jeu de résultats utilise un curseur flottant, il est possible d'appeler la fonction db2_fetch_assoc() avec un numéro de ligne spécifique. L'exemple suivant récupère chaque ligne paire dans le jeu de résultats, commençant avec la deuxième ligne.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_assoc($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NOM'], $row['RACE'], $row['POIDS']);
        $i = $i + 2;
    }
    ?>

L'exemple ci-dessus va afficher :

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

### Voir aussi

- db2_fetch_array() - Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats
- db2_fetch_both() - Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats
- db2_fetch_object() - Retourne un objet avec les propriétés représentant des colonnes dans la ligne extraite
- db2_fetch_row() - Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée
- db2_result() - Retourne une colonne d'une ligne d'un jeu de résultats

# db2_fetch_both

(PECL ibm_db2 >= 1.0.0)

db2_fetch_both — Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats

### Description

function db2_fetch_both(resource `$stmt`, int `$row_number` = -1): array|false

Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats. Il est à noter que la ligne retournée par db2_fetch_both() nécessite plus de mémoire que les tableaux simplement indexés retournés par db2_fetch_assoc() ou db2_fetch_array().

### Liste de paramètres

`stmt`
  Une ressource `stmt` valide contenant le jeu de résultats.
`row_number`
  Demande une ligne spécifique indexée numériquement qui commence par la valeur 1 dans le jeu de résultats. Fournir ce paramètre génère une alerte PHP si le jeu de résultats utilise un curseur d'avancement seul.

### Valeurs de retour

Retourne un tableau associatif avec les valeurs des colonnes indexées par le nom des colonnes et le numéro des colonnes commençant par 0. Le tableau représente la ligne suivante ou la ligne demandée du jeu de résultats. Retourne `false` s'il n'y a pas de ligne disponible dans le jeu de résultats ou si la ligne demandée par `row_number` n'existe pas dans le jeu de résultats.

### Exemples

Exemple #1 Itération avec un curseur d'avancement seul

Si l'on appelle db2_fetch_both() sans le numéro d'une ligne spécifique, la ligne suivante du jeu de résultats sera automatiquement récupérée. L'exemple suivant accède aux colonnes retournées dans le tableau à la fois par nom de colonne et par indice numérique.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_both($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row[0], $row['RACE'], $row[3]);
    }
    ?>

L'exemple ci-dessus va afficher :

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

Exemple #2 Récupération de lignes spécifiques avec db2_fetch_both() provenant d'un curseur flottant

Si le jeu de résultats utilise un curseur flottant, il est possible d'appeler la fonction db2_fetch_both() avec un numéro de ligne spécifique. L'exemple suivant récupère chaque ligne paire dans le jeu de résultats, commençant avec la deuxième ligne.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_both($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row['NOM'], $row[2], $row['POIDS']);
        $i = $i + 2;
    }
    ?>

L'exemple ci-dessus va afficher :

    0     Pook             chat                                   3.20
    5     Rickety Ride     chèvre                                 9.70
    2     Smarty           cheval                               350.00

### Voir aussi

- db2_fetch_array() - Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats
- db2_fetch_assoc() - Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats
- db2_fetch_object() - Retourne un objet avec les propriétés représentant des colonnes dans la ligne extraite
- db2_fetch_row() - Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée
- db2_result() - Retourne une colonne d'une ligne d'un jeu de résultats

# db2_fetch_object

(PECL ibm_db2 >= 1.0.0)

db2_fetch_object — Retourne un objet avec les propriétés représentant des colonnes dans la ligne extraite

### Description

function db2_fetch_object(resource `$stmt`, int `$row_number` = -1): stdClass|false

Retourne un objet dans lequel chaque propriété représente une colonne retournée dans la ligne extraite du jeu de résultats.

### Liste de paramètres

`stmt`
  Une ressource `stmt` valide contenant le jeu de résultats.
`row_number`
  Demande une ligne spécifique commençant à l'index 1 du jeu de résultats. Le passage de ce paramètre entraîne une alerte PHP si le jeu de résultats utilise un curseur unidirectionnel.

### Valeurs de retour

Retourne un objet représentant une seule ligne dans le jeu de résultats. Les propriétés de l'objet correspondent au nom des colonnes dans le jeu de résultats.

Les serveurs IBM DB2, Cloudscape et Apache Derby mettent normalement les noms des colonnes en majuscules, par conséquent, les propriétés de l'objet refléteront cette casse.

Si la requête SELECT appelle une fonction scalaire pour modifier la valeur d'une colonne, les serveurs de base de données retournent le numéro de colonne en tant que nom de colonne dans le jeu de résultats. Si l'on préfère un nom de colonne et une propriété d'objet plus descriptifs, il est possible d'utiliser la clause AS pour assigner un nom à la colonne dans le jeu de résultats.

Retourne `false` si aucune ligne n'a été récupérée.

### Exemples

Exemple #1 Exemple avec db2_fetch_object()

L'exemple suivant envoie une requête SELECT avec une fonction scalaire, RTRIM, qui supprime les espaces à partir de la fin de la colonne. Au lieu de créer un objet avec les propriétés "RACE" et "2", la clause AS est utilisée dans la requête SELECT pour assigner le nom "nom" à la colonne modifiée. Le serveur de base de données met les noms des colonnes en majuscules, l'objet aura donc les propriétés "RACE" et "NOM".

    <?php
    $conn = db2_connect($database, $user, $password);

    $sql = "SELECT race, RTRIM(nom) AS nom
        FROM animaux
        WHERE id = ?";

    if ($conn) {
        $stmt = db2_prepare($conn, $sql);
        db2_execute($stmt, array(0));

        while ($pet = db2_fetch_object($stmt)) {
            echo "Viens ici, {$pet->NOM}, mon petit {$pet->RACE} !";
        }
        db2_close($conn);
    }
    ?>

L'exemple ci-dessus va afficher :

    Viens ici, Pook, mon petit chat !

### Voir aussi

- db2_fetch_array() - Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats
- db2_fetch_assoc() - Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats
- db2_fetch_both() - Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats
- db2_fetch_row() - Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée
- db2_result() - Retourne une colonne d'une ligne d'un jeu de résultats

# db2_fetch_row

(PECL ibm_db2 >= 1.0.0)

db2_fetch_row — Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée

### Description

function db2_fetch_row(resource `$stmt`, int `$row_number` = -1): bool

La fonction db2_fetch_row() peut être utilisée pour itérer à travers un jeu de résultats ou pour pointer à une ligne spécifique d'un jeu de résultats si l'on a demandé un curseur défilant.

Pour obtenir des champs individuels du jeu de résultats, il faut appeler la fonction db2_result().

Au lieu d'appeler les fonctions db2_fetch_row() et db2_result(), la plupart des applications vont appeler la fonction db2_fetch_assoc(), db2_fetch_both() ou db2_fetch_array() pour avancer le pointeur dans le jeu de résultats et retourner une ligne complète en tant que tableau.

### Liste de paramètres

`stmt`
  Une ressource `stmt` valide.
`row_number`
  Avec des curseurs défilants, il est possible de demander un numéro de ligne spécifique du jeu de résultats. Les numéros des lignes commencent à l'indice 1.

### Valeurs de retour

Retourne `true` si la ligne demandée existe dans le jeu de résultats. Retourne `false` si la ligne demandée n'existe pas dans le jeu de résultats.

### Exemples

Exemple #1 Itération à travers un jeu de résultats

L'exemple suivant démontre comment itérer à travers un jeu de résultats avec la fonction db2_fetch_row() et récupérer les colonnes du jeu de résultats avec db2_result().

    <?php
    $sql = 'SELECT nom, race FROM animaux WHERE poids < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $nom = db2_result($stmt, 0);
        $race = db2_result($stmt, 1);
        print "$nom $race";
    }
    ?>

L'exemple ci-dessus va afficher :

    chat Pook
    cyprin doré Bubbles
    perruche Gizmo
    chèvre Rickety Ride

Exemple #2 Alternatives recommandées sur i5/OS à db2_fetch_row/db2_result

Sur i5/OS, il est recommandé d'utiliser db2_fetch_both(), db2_fetch_array() ou db2_fetch_object() au lieu de db2_fetch_row()/db2_result(). En général, db2_fetch_row()/db2_result() ont plus de problèmes avec divers types de colonnes lors de la traduction `EBCDIC` vers `ASCII`, y compris une possible troncature dans les applications `DBCS`. Il est également possible de trouver les performances de db2_fetch_both(), db2_fetch_array() et db2_fetch_object() supérieures à celles de db2_fetch_row()/db2_result().

    <?php
      $conn = db2_connect("","","");
      $sql = 'SELECT SPECIFIC_SCHEMA, SPECIFIC_NAME, ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE, ROUTINE_CREATED, ROUTINE_BODY, IN_PARMS, OUT_PARMS, INOUT_PARMS, PARAMETER_STYLE, EXTERNAL_NAME, EXTERNAL_LANGUAGE FROM QSYS2.SYSROUTINES FETCH FIRST 2 ROWS ONLY';
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_both($stmt)){
        echo "<br>db2_fetch_both {$row['SPECIFIC_NAME']} {$row['ROUTINE_CREATED']} {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_array($stmt)){
        echo "<br>db2_fetch_array {$row[1]}  {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_object($stmt)){
        echo "<br>db2_fetch_object {$row->SPECIFIC_NAME} {$row->ROUTINE_CREATED}";
      }
      db2_close($conn);
    ?>

L'exemple ci-dessus va afficher :

    db2_fetch_both MATCH_ANIMAL 2006-08-25-17.10.23.775000 2006-08-25-17.10.23.775000
    db2_fetch_both MULTIRESULTS 2006-10-17-10.11.05.308000 2006-10-17-10.11.05.308000
    db2_fetch_array MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_array MULTIRESULTS 2006-10-17-10.11.05.308000
    db2_fetch_object MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_object MULTIRESULTS 2006-10-17-10.11.05.308000

### Voir aussi

- db2_fetch_array() - Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats
- db2_fetch_assoc() - Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats
- db2_fetch_both() - Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats
- db2_fetch_object() - Retourne un objet avec les propriétés représentant des colonnes dans la ligne extraite
- db2_result() - Retourne une colonne d'une ligne d'un jeu de résultats

# db2_field_display_size

(PECL ibm_db2 >= 1.0.0)

db2_field_display_size — Retourne le maximum d'octets requis pour afficher une colonne

### Description

function db2_field_display_size(resource `$stmt`, int|string `$column`): int|false

Retourne le maximum d'octets requis pour afficher une colonne dans un jeu de résultats.

### Liste de paramètres

`stmt`
  Spécifie la ressource contenant le jeu de résultats.
`column`
  Spécifie la colonne dans le jeu de résultats. Cela peut être un entier commençant à la position 0 représentant le numéro de la colonne ou une chaîne contenant le nom de la colonne.

### Valeurs de retour

Retourne une valeur entière avec le maximum d'octets requis pour afficher la colonne spécifiée. Si la colonne n'existe pas dans le jeu de résultats, db2_field_display_size() retourne `false`.

### Voir aussi

- db2_field_name() - Retourne le nom de la colonne du jeu de résultats
- db2_field_num() - Retourne la position de la colonne nommée dans un jeu de résultats
- db2_field_precision() - Retourne la précision de la colonne indiquée du jeu de résultats
- db2_field_scale() - Retourne l'échelle de la colonne indiquée du jeu de résultats
- db2_field_type() - Retourne le type de données de la colonne indiquée du jeu de résultats
- db2_field_width() - Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats

# db2_field_name

(PECL ibm_db2 >= 1.0.0)

db2_field_name — Retourne le nom de la colonne du jeu de résultats

### Description

function db2_field_name(resource `$stmt`, int|string `$column`): string|false

Retourne le nom de la colonne du jeu de résultats

### Liste de paramètres

`stmt`
  Spécifie la ressource contenant le jeu de résultats.
`column`
  Spécifie la colonne dans le jeu de résultats. Cela peut être un entier commençant à la position 0 représentant le numéro de la colonne ou une chaîne contenant le nom de la colonne.

### Valeurs de retour

Retourne une chaîne contenant le nom de la colonne spécifiée. Si la colonne spécifiée n'existe pas dans le jeu de résultats, db2_field_name() retourne `false`.

### Voir aussi

- db2_field_display_size() - Retourne le maximum d'octets requis pour afficher une colonne
- db2_field_num() - Retourne la position de la colonne nommée dans un jeu de résultats
- db2_field_precision() - Retourne la précision de la colonne indiquée du jeu de résultats
- db2_field_scale() - Retourne l'échelle de la colonne indiquée du jeu de résultats
- db2_field_type() - Retourne le type de données de la colonne indiquée du jeu de résultats
- db2_field_width() - Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats

# db2_field_num

(PECL ibm_db2 >= 1.0.0)

db2_field_num — Retourne la position de la colonne nommée dans un jeu de résultats

### Description

function db2_field_num(resource `$stmt`, int|string `$column`): int|false

Retourne la position de la colonne nommée dans un jeu de résultats.

### Liste de paramètres

`stmt`
  Spécifie une ressource d'instruction contenant un jeu de résultats.
`column`
  Spécifie la colonne dans le jeu de résultats. Cela peut être un entier commençant à la position 0 représentant le numéro de la colonne ou une chaîne contenant le nom de la colonne.

### Valeurs de retour

Retourne un entier contenant la position commençant à 0 de la colonne nommée dans le jeu de résultats. Si la colonne spécifiée n'existe pas dans le jeu de résultats, db2_field_num() retourne `false`.

### Voir aussi

- db2_field_display_size() - Retourne le maximum d'octets requis pour afficher une colonne
- db2_field_name() - Retourne le nom de la colonne du jeu de résultats
- db2_field_precision() - Retourne la précision de la colonne indiquée du jeu de résultats
- db2_field_scale() - Retourne l'échelle de la colonne indiquée du jeu de résultats
- db2_field_type() - Retourne le type de données de la colonne indiquée du jeu de résultats
- db2_field_width() - Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats

# db2_field_precision

(PECL ibm_db2 >= 1.0.0)

db2_field_precision — Retourne la précision de la colonne indiquée du jeu de résultats

### Description

function db2_field_precision(resource `$stmt`, int|string `$column`): int|false

Retourne la précision de la colonne indiquée du jeu de résultats.

### Liste de paramètres

`stmt`
  Spécifie la ressource contenant le jeu de résultats.
`column`
  Spécifie la colonne dans le jeu de résultats. Cela peut être un entier commençant à la position 0 représentant le numéro de la colonne ou une chaîne contenant le nom de la colonne.

### Valeurs de retour

Retourne un entier contenant la précision de la colonne spécifiée. Si la colonne spécifiée n'existe pas dans le jeu de résultats, db2_field_precision() retourne `false`.

### Voir aussi

- db2_field_display_size() - Retourne le maximum d'octets requis pour afficher une colonne
- db2_field_name() - Retourne le nom de la colonne du jeu de résultats
- db2_field_num() - Retourne la position de la colonne nommée dans un jeu de résultats
- db2_field_scale() - Retourne l'échelle de la colonne indiquée du jeu de résultats
- db2_field_type() - Retourne le type de données de la colonne indiquée du jeu de résultats
- db2_field_width() - Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats

# db2_field_scale

(PECL ibm_db2 >= 1.0.0)

db2_field_scale — Retourne l'échelle de la colonne indiquée du jeu de résultats

### Description

function db2_field_scale(resource `$stmt`, int|string `$column`): int|false

Retourne l'échelle de la colonne indiquée du jeu de résultats.

### Liste de paramètres

`stmt`
  Spécifie la ressource contenant le jeu de résultats.
`column`
  Spécifie la colonne dans le jeu de résultats. Cela peut être un entier commençant à la position 0 représentant le numéro de la colonne ou une chaîne contenant le nom de la colonne.

### Valeurs de retour

Retourne un entier contenant l'échelle de la colonne spécifiée. Si la colonne spécifiée n'existe pas dans le jeu de résultats, db2_field_scale() retourne `false`.

### Voir aussi

- db2_field_display_size() - Retourne le maximum d'octets requis pour afficher une colonne
- db2_field_name() - Retourne le nom de la colonne du jeu de résultats
- db2_field_num() - Retourne la position de la colonne nommée dans un jeu de résultats
- db2_field_precision() - Retourne la précision de la colonne indiquée du jeu de résultats
- db2_field_type() - Retourne le type de données de la colonne indiquée du jeu de résultats
- db2_field_width() - Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats

# db2_field_type

(PECL ibm_db2 >= 1.0.0)

db2_field_type — Retourne le type de données de la colonne indiquée du jeu de résultats

### Description

function db2_field_type(resource `$stmt`, int|string `$column`): string|false

Retourne le type de données de la colonne indiquée du jeu de résultats.

### Liste de paramètres

`stmt`
  Spécifie la ressource contenant le jeu de résultats.
`column`
  Spécifie la colonne dans le jeu de résultats. Cela peut être un entier commençant à la position 0 représentant le numéro de la colonne ou une chaîne contenant le nom de la colonne.

### Valeurs de retour

Retourne une chaîne contenant le type de données défini de la colonne spécifiée. Si la colonne spécifiée n'existe pas dans le jeu de résultats, db2_field_type() retourne `false`.

### Voir aussi

- db2_field_display_size() - Retourne le maximum d'octets requis pour afficher une colonne
- db2_field_name() - Retourne le nom de la colonne du jeu de résultats
- db2_field_num() - Retourne la position de la colonne nommée dans un jeu de résultats
- db2_field_precision() - Retourne la précision de la colonne indiquée du jeu de résultats
- db2_field_scale() - Retourne l'échelle de la colonne indiquée du jeu de résultats
- db2_field_width() - Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats

# db2_field_width

(PECL ibm_db2 >= 1.0.0)

db2_field_width — Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats

### Description

function db2_field_width(resource `$stmt`, int|string `$column`): int|false

Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats. Il s'agit de la largeur maximale de la colonne pour un type de données de longueur fixe, ou de la largeur réelle de la colonne pour un type de données de longueur variable.

### Liste de paramètres

`stmt`
  Spécifie la ressource contenant le jeu de résultats.
`column`
  Spécifie la colonne dans le jeu de résultats. Cela peut être un entier commençant à la position 0 représentant le numéro de la colonne ou une chaîne contenant le nom de la colonne.

### Valeurs de retour

Retourne un entier contenant la largeur du caractère spécifié ou de la colonne de type binaire dans le jeu de résultats. Si la colonne spécifiée n'existe pas dans le jeu de résultats, db2_field_width() retourne `false`.

### Voir aussi

- db2_field_display_size() - Retourne le maximum d'octets requis pour afficher une colonne
- db2_field_name() - Retourne le nom de la colonne du jeu de résultats
- db2_field_num() - Retourne la position de la colonne nommée dans un jeu de résultats
- db2_field_precision() - Retourne la précision de la colonne indiquée du jeu de résultats
- db2_field_scale() - Retourne l'échelle de la colonne indiquée du jeu de résultats
- db2_field_type() - Retourne le type de données de la colonne indiquée du jeu de résultats

# db2_foreign_keys

(PECL ibm_db2 >= 1.0.0)

db2_foreign_keys — Retourne un jeu de résultats listant les clés étrangères d'une table

### Description

function db2_foreign_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

Retourne un jeu de résultats listant les clés étrangères d'une table.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, passez `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les tables. Si `schema` est `null`, db2_foreign_keys() fait concorder le schéma pour la connexion courante.
`table_name`
  Le nom de la table.

### Valeurs de retour

Retourne une ressource d'instruction avec un jeu de résultats contenant des lignes décrivant les clés étrangères de la table spécifiée. Le jeu de résultats est composé des colonnes suivantes :

Nom de la colonne | Description
--- | ---
PKTABLE_CAT | Nom du catalogue de la table contenant la clé primaire. La valeur est `null` si la table n'a pas de catalogue.
PKTABLE_SCHEM | Nom du schéma de la table contenant la clé primaire.
PKTABLE_NAME | Nom de la table contenant la clé primaire.
PKCOLUMN_NAME | Nom de la colonne contenant la clé primaire.
FKTABLE_CAT | Nom du catalogue de la table contenant la clé étrangère. La valeur est `null` si la table n'a pas de catalogue.
FKTABLE_SCHEM | Nom du schéma de la table contenant la clé étrangère.
FKTABLE_NAME | Nom de la table contenant la clé étrangère.
FKCOLUMN_NAME | Nom de la colonne contenant la clé étrangère.
KEY_SEQ | Position commençant à 1 de la colonne dans la clé.
UPDATE_RULE | Entier représentant l'action appliquée à la clé étrangère lorsqu'une opération SQL est de type UPDATE.
DELETE_RULE | Entier représentant l'action appliquée à la clé étrangère lorsqu'une opération SQL est de type DELETE.
FK_NAME | Nom de la clé étrangère.
PK_NAME | Nom de la clé primaire.
DEFERRABILITY | Un entier représentant si le mode différé de la clé étrangère est SQL_INITIALLY_DEFERRED, SQL_INITIALLY_IMMEDIATE ou SQL_NOT_DEFERRABLE.

### Voir aussi

- db2_column_privileges() - Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_columns() - Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_primary_keys() - Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedure_columns() - Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_procedures() - Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_special_columns() - Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_statistics() - Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_table_privileges() - Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
- db2_tables() - Retourne la liste des tables et leurs métadonnées

# db2_free_result

(PECL ibm_db2 >= 1.0.0)

db2_free_result — Libère la mémoire associée à un jeu de résultats

### Description

function db2_free_result(resource `$stmt`): bool

Libère les ressources système et de base de données qui sont associées à un jeu de résultats. Ces ressources sont libérées implicitement lorsqu'un script se termine, mais il est possible d'appeler db2_free_result() pour libérer explicitement les ressources du jeu de résultats avant la fin du script.

### Liste de paramètres

`stmt`
  Une ressource d'instruction valide.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- db2_free_stmt() - Libère les ressources associées à la ressource d'instruction indiquée

# db2_free_stmt

(PECL ibm_db2 >= 1.0.0)

db2_free_stmt — Libère les ressources associées à la ressource d'instruction indiquée

### Description

function db2_free_stmt(resource `$stmt`): bool

Libère les ressources du système et de base de données associées à une ressource d'instruction. Ces ressources sont libérées implicitement lorsqu'un script se termine, mais il est possible d'appeler db2_free_stmt() pour libérer explicitement les ressources d'instruction avant la fin du script.

### Liste de paramètres

`stmt`
  Une ressource d'instruction valide.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- db2_free_result() - Libère la mémoire associée à un jeu de résultats

# db2_get_option

(PECL ibm_db2 >= 1.6.0)

db2_get_option — Récupère la valeur d'une option pour une ressource d'instruction ou une ressource de connexion

### Description

function db2_get_option(resource `$resource`, string `$option`): string|false

Récupère la valeur d'une option spécifiée pour une ressource d'instruction ou une ressource de connexion.

### Liste de paramètres

`resource`
  Une ressource d'instruction valide retournée par db2_prepare() ou une ressource de connexion valide retournée par db2_connect() ou db2_pconnect().
`option`

  Des options d'instruction ou de connexion valides. Les nouvelles options suivantes sont disponibles à partir de la version 1.6.0 d'ibm_db2. Elles fournissent d'utiles informations de traçage qui peuvent être fixées pendant l'exécution avec db2_get_option().

  > Note: Les anciennes versions d'ibm_db2 ne supportent pas ces nouvelles options. Lorsqu'une valeur dans chaque option est fixée, certains serveurs peuvent ne pas prendre en charge la valeur totale fournie et peuvent tronquer cette valeur. Pour s'assurer que les données spécifiées dans chaque option sont converties correctement lors de la transmission vers une base de données, utiliser seulement les caractères de A à Z, 0 à 9 et les caractères de soulignement (_) ou point (.).

  `userid`

    `SQL_ATTR_INFO_USERID` : un pointeur vers une chaîne de caractères utilisée pour identifier l'identifiant de l'usager (ID) envoyé vers le serveur de base de données lors de l'utilisation de DB2 Connect.

    > Note: DB2 pour les serveurs z/OS et OS/390 supporte jusqu'à 16 caractères. Le user-id ne doit pas être confondu avec le user-id d'authentification ; il sert uniquement à des fins d'identification et n'est pas utilisé pour des autorisations.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR` : un pointeur vers une chaîne de caractères utilisée pour identifier le compte du client envoyé vers le serveur de base de données lors de l'utilisation de DB2 Connect.

    > Note: DB2 pour les serveurs z/OS et OS/390 supporte jusqu'à 200 caractères.

  `applname`

    `SQL_ATTR_INFO_APPLNAME` : un pointeur vers une chaîne de caractères utilisée pour identifier le nom de l'application du client envoyé vers le serveur de base de données lors de l'utilisation de DB2 Connect.

    > Note: DB2 pour les serveurs z/OS et OS/390 supporte jusqu'à 32 caractères.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME` : un pointeur vers une chaîne de caractères utilisée pour identifier le nom de la machine du client envoyé vers le serveur de base de données lors de l'utilisation de DB2 Connect.

    > Note: DB2 pour les serveurs z/OS et OS/390 supporte jusqu'à 18 caractères.

La table suivante spécifie quelles options sont compatibles avec les types de ressources disponibles :

Matrice ressource-paramètre
Clé | Valeur | Type de ressource
--- | --- | ---
|  | Connexion | Instruction | Jeu de résultats
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Valeurs de retour

Retourne la configuration courante de la connexion fournie en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Définit et récupère les paramètres au travers d'une ressource de connexion

    <?php
    /* Paramètres de Connexion */
    $database = 'SAMPLE';
    $user     = 'db2inst1';
    $password = 'ibmdb2';

    /* Récupération de la Ressource de Connexion */
    $conn = db2_connect($database, $user, $password);

    echo "Attributs de connexion passés avec la chaîne de caractères de connexion :\n";

    /* Crée un tableau associatif d'options avec les paires clé/valeur valides */
    /* Assigne les attributs à partir de la chaîne de caractères de connexion */
    /* Accède aux options spécifiées */
    $options1 = array('userid' => 'db2inst1');
    $conn1 = db2_connect($database, $user, $password, $options1);
    $val = db2_get_option($conn1, 'userid');
    echo $val . "\n";

    $options2 = array('acctstr' => 'account');
    $conn2 = db2_connect($database, $user, $password, $options2);
    $val = db2_get_option($conn2, 'acctstr');
    echo $val . "\n";

    $options3 = array('applname' => 'myapp');
    $conn3 = db2_connect($database, $user, $password, $options3);
    $val = db2_get_option($conn3, 'applname');
    echo $val . "\n";

    $options4 = array('wrkstnname' => 'workstation');
    $conn4 = db2_connect($database, $user, $password, $options4);
    $val = db2_get_option($conn4, 'wrkstnname');
    echo $val . "\n";

    echo "Attributs après la connexion :\n";

    /* Crée un tableau associatif d'options avec les paires clé/valeur valides */
    /* Assigne les attributs après que la connexion soit faite */
    /* Accède aux options spécifiées */
    $options5 = array('userid' => 'db2inst1');
    $conn5 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn5, $options5, 1);
    $val = db2_get_option($conn5, 'userid');
    echo $val . "\n";

    $options6 = array('acctstr' => 'account');
    $conn6 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn6, $options6, 1);
    $val = db2_get_option($conn6, 'acctstr');
    echo $val . "\n";

    $options7 = array('applname' => 'myapp');
    $conn7 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn7, $options7, 1);
    $val = db2_get_option($conn7, 'applname');
    echo $val . "\n";

    $options8 = array('wrkstnname' => 'workstation');
    $conn8 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn8, $options8, 1);
    $val = db2_get_option($conn8, 'wrkstnname');
    echo $val . "\n";
    ?>

L'exemple ci-dessus va afficher :

    Attributs de connexion passés avec la chaîne de caractères de connexion :
    db2inst1
    account
    myapp
    workstation
    Attributs après la connexion :
    db2inst1
    account
    myapp
    workstation

### Voir aussi

- db2_connect() - Retourne une connexion à une base de données
- db2_cursor_type() - Retourne le type de curseur utilisé par une ressource d'instruction
- db2_exec() - Exécute une requête SQL directement
- db2_set_option() - Fixe des options pour une ressource de connexion ou une ressource d'instruction
- db2_pconnect() - Retourne une connexion persistante à une base de données
- db2_prepare() - Prépare une requête SQL à être exécutée

# db2_last_insert_id

(PECL ibm_db2 >= 1.7.1)

db2_last_insert_id — Retourne le dernier ID généré par la dernière requête d'insertion

### Description

function db2_last_insert_id(resource `$resource`): ?string

Retourne le dernier identifiant autogénéré par la dernière requête d'insertion pour la connexion en cours.

Le résultat de cette fonction n'est pas affecté par les événements suivants :

- Une commande unique INSERT avec une clause VALUES pour une table qui ne dispose pas de colonne d'identité.
- Une commande INSERT multiple avec clause VALUES.
- Une commande INSERT avec un SELECT.
- Une commande ROLLBACK TO SAVEPOINT.

### Liste de paramètres

`resource`
  Une ressource de connexion valide, créée par db2_connect() ou db2_pconnect(). La valeur de ce paramètre ne peut pas être une ressource d'instruction ou un jeu de résultats.

### Valeurs de retour

Retourne l'identifiant autogénéré qui a pu être exécuté correctement sur cette connexion.

### Exemples

Exemple #1 Exemple avec db2_last_insert_id()

L'exemple suivant montre comment retourner un identifiant automatique

    <?php

    $database = "SAMPLE";
    $user = "db2inst1";
    $password = "ibmdb2";

    $conn = db2_connect($database, $user, $password);
    if($conn) {
        $createTable = "CREATE TABLE lastInsertID
          (id integer GENERATED BY DEFAULT AS IDENTITY, name varchar(20))";
        $insertTable = "INSERT INTO lastInsertID (name) VALUES ('Temp Name')";

        $stmt = @db2_exec($conn, $createTable);

        /* Vérification de l'insertion d'une ligne unique */
        $stmt = db2_exec($conn, $insertTable);
        $ret =  db2_last_insert_id($conn);
        if($ret) {
            echo "Dernier ID inséré : " . $ret . "\n";
        } else {
            echo "Pas d'ID inséré récemment.\n";
        }

        db2_close($conn);
    }
    else {
        echo "La connexion a échoué.";
    }
    ?>

L'exemple ci-dessus va afficher :

    Dernier ID inséré : 1

# db2_lob_read

(PECL ibm_db2 >= 1.6.0)

db2_lob_read — Récupère une taille définie par l'utilisateur de fichiers LOB à chaque invocation

### Description

function db2_lob_read(resource `$stmt`, int `$colnum`, int `$length`): string|false

La fonction db2_lob_read() permet d'itérer à travers une colonne spécifique d'un jeu de résultats et de récupérer une taille définie par l'utilisateur de données LOB.

### Liste de paramètres

`stmt`
  Une ressource `stmt` valide contenant des données LOB.
`colnum`
  Un numéro de colonne valide dans le jeu de résultats de la ressource `stmt`.
`length`
  La taille des données LOB à récupérer depuis la ressource `stmt`.

### Valeurs de retour

Retourne la quantité de données spécifiée par l'utilisateur. Retourne `false` si les données ne peuvent être récupérées.

### Exemples

Exemple #1 Itère à travers différents types de données

    <?php

    /* Paramètres de Connexion */
    $db = 'SAMPLE';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Récupération de la Ressource de Connexion */
    $conn = db2_connect($db,$username,$password);

    if ($conn) {
        $drop = 'DROP TABLE clob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE clob_stream (id INTEGER, my_clob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO clob_stream (id,my_clob) VALUES (1, ?)");
        $variable = "THIS IS A CLOB TEST. THIS IS A CLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_clob FROM clob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Lecture des grands objets */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Boucle $i : $data\n";
            $i = $i + 1;
        }

        $drop = 'DROP TABLE blob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE blob_stream (id INTEGER, my_blob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO blob_stream (id,my_blob) VALUES (1, ?)");
        $variable = "THIS IS A BLOB TEST. THIS IS A BLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_blob FROM blob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Lecture des grands objets */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Boucle $i : $data\n";
            $i = $i + 1;
        }
    } else {
        echo 'aucune connexion : ' . db2_conn_errormsg();
    }

    ?>

L'exemple ci-dessus va afficher :

    Boucle 0 : THIS I
    Boucle 1 : S A CL
    Boucle 2 : OB TES
    Boucle 3 : T. THI
    Boucle 4 : S IS A
    Boucle 5 :  CLOB
    Boucle 6 : TEST.
    Boucle 0 : THIS I
    Boucle 1 : S A BL
    Boucle 2 : OB TES
    Boucle 3 : T. THI
    Boucle 4 : S IS A
    Boucle 5 :  BLOB
    Boucle 6 : TEST.

### Voir aussi

- db2_bind_param() - Associe une variable PHP à un paramètre d'une requête SQL
- db2_exec() - Exécute une requête SQL directement
- db2_execute() - Exécute une requête SQL préparée
- db2_fetch_row() - Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée
- db2_prepare() - Prépare une requête SQL à être exécutée
- db2_result() - Retourne une colonne d'une ligne d'un jeu de résultats

# db2_next_result

(PECL ibm_db2 >= 1.0.0)

db2_next_result — Demande le prochain jeu de résultats d'une procédure stockée

### Description

function db2_next_result(resource `$stmt`): resource|false

Une procédure stockée peut retourner aucun ou plusieurs jeux de résultats. Il faut gérer le premier jeu de résultats de la même manière que l'on gère les résultats retournés par une simple requête SELECT ; pour obtenir le deuxième jeu de résultats et les suivants à partir d'une procédure stockée, il faut appeler la fonction db2_next_result() et retourner le résultat dans une variable PHP au nom unique.

### Liste de paramètres

`stmt`
  Une requête préparée retournée par db2_exec() ou db2_execute().

### Valeurs de retour

Retourne une nouvelle ressource d'instruction contenant le jeu de résultats suivant si la procédure stockée a retourné un autre jeu de résultats. Retourne `false` si la procédure stockée n'a pas retourné d'autre jeu de résultats.

### Exemples

Exemple #1 Appel d'une procédure stockée qui retourne plusieurs jeux de résultats

Dans l'exemple suivant, une procédure stockée qui retourne trois jeux de résultats est appelée. Le premier jeu de résultats est récupéré directement à partir de la même ressource d'instruction sur laquelle la requête CALL a été invoquée, alors que le deuxième et le troisième jeux de résultats sont récupérés à partir des ressources d'instruction retournées par les appels à la fonction db2_next_result().

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
      $stmt = db2_exec($conn, 'CALL multiResults()');

      print "Récupération du premier jeu de résultats\n";
      while ($row = db2_fetch_array($stmt)) {
        var_dump($row);
      }

      print "\nRécupération du deuxième jeu de résultats\n";
      $res = db2_next_result($stmt);
      if ($res) {
        while ($row = db2_fetch_array($res)) {
          var_dump($row);
        }
      }

      print "\nRécupération du troisième jeu de résultats\n";
      $res2 = db2_next_result($stmt);
      if ($res2) {
        while ($row = db2_fetch_array($res2)) {
          var_dump($row);
        }
      }

      db2_close($conn);
    }
    ?>

L'exemple ci-dessus va afficher :

    Récupération du premier jeu de résultats
    array(2) {
      [0]=>
      string(16) "Bubbles         "
      [1]=>
      int(3)
    }
    array(2) {
      [0]=>
      string(16) "Gizmo           "
      [1]=>
      int(4)
    }

    Récupération du deuxième jeu de résultats
    array(4) {
      [0]=>
      string(16) "Sweater         "
      [1]=>
      int(6)
      [2]=>
      string(5) "lama"
      [3]=>
      string(6) "150.00"
    }
    array(4) {
      [0]=>
      string(16) "Smarty          "
      [1]=>
      int(2)
      [2]=>
      string(5) "cheval"
      [3]=>
      string(6) "350.00"
    }

    Récupération du troisième jeu de résultats
    array(1) {
      [0]=>
      string(16) "Bubbles         "
    }
    array(1) {
      [0]=>
      string(16) "Gizmo           "
    }

# db2_num_fields

(PECL ibm_db2 >= 1.0.0)

db2_num_fields — Retourne le nombre de champs contenus dans un jeu de résultats

### Description

function db2_num_fields(resource `$stmt`): int|false

Retourne le nombre de champs contenus dans le jeu de résultats. Cette fonction est très utile lorsqu'on gère des jeux de résultats retournés par des requêtes générées dynamiquement ou pour des jeux de résultats retournés par des procédures d'enregistrement, là où l'application ne peut faire autrement pour obtenir et utiliser ces résultats.

### Liste de paramètres

`stmt`
  Une ressource d'instruction valide contenant un jeu de résultats.

### Valeurs de retour

Retourne un entier représentant le nombre de champs dans le jeu de résultats associé avec la ressource d'instruction spécifiée. Retourne `false` si la ressource d'instruction n'est pas une valeur d'entrée valide.

### Exemples

Exemple #1 Récupération du nombre de champs dans un jeu de résultats

L'exemple suivant démontre comment obtenir le nombre de champs retournés dans le jeu de résultats.

    <?php

    $sql = "SELECT id, nom, race, poids FROM animaux ORDER BY race";
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, $sql);
    $columns = db2_num_fields($stmt);

    echo "Il y a {$columns} colonnes dans le jeu de résultats.";
    ?>

L'exemple ci-dessus va afficher :

    Il y a 4 colonnes dans le jeu de résultats.

### Voir aussi

- db2_execute() - Exécute une requête SQL préparée
- db2_field_display_size() - Retourne le maximum d'octets requis pour afficher une colonne
- db2_field_name() - Retourne le nom de la colonne du jeu de résultats
- db2_field_num() - Retourne la position de la colonne nommée dans un jeu de résultats
- db2_field_precision() - Retourne la précision de la colonne indiquée du jeu de résultats
- db2_field_scale() - Retourne l'échelle de la colonne indiquée du jeu de résultats
- db2_field_type() - Retourne le type de données de la colonne indiquée du jeu de résultats
- db2_field_width() - Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats

# db2_num_rows

(PECL ibm_db2 >= 1.0.0)

db2_num_rows — Retourne le nombre de lignes affectées par une requête SQL

### Description

function db2_num_rows(resource `$stmt`): int|false

Retourne le nombre de lignes supprimées, ajoutées, mises à jour par une requête SQL.

Afin de déterminer le nombre de lignes que retournera une requête SELECT, il faut exécuter la requête SELECT COUNT(*) avec les mêmes prédicats que la requête SELECT prévue et récupérer la valeur.

Si la logique de l'application vérifie le nombre de lignes retournées par une requête SELECT et effectue un branchement si le nombre de lignes est 0, il est recommandé de modifier l'application pour tenter de retourner la première ligne avec db2_fetch_assoc(), db2_fetch_both(), db2_fetch_array() ou db2_fetch_row(), et d'effectuer le branchement si la fonction retourne `false`.

> Note: Lors de l'envoi d'une requête SELECT avec un curseur flottant, db2_num_rows() retourne le nombre de lignes retournées par la requête SELECT. Cependant, le temps système associé aux curseurs flottants dégrade considérablement les performances de l'application, ainsi, si cela est la seule raison pour laquelle l'on envisage d'utiliser des curseurs flottants, il est recommandé d'utiliser un curseur à avancement seul et soit d'appeler SELECT COUNT(*), soit de s'appuyer sur la valeur de retour de type bool des fonctions de récupération pour obtenir une fonctionnalité équivalente avec des performances bien meilleures.

### Liste de paramètres

`stmt`
  Une ressource `stmt` valide contenant le jeu de résultats.

### Valeurs de retour

Retourne le nombre de lignes affectées par la dernière requête SQL envoyée par une fonction qui exécute les requêtes SQL, ou `false` si une erreur survient

# db2_pclose

(PECL ibm_db2 >= 1.8.0)

db2_pclose — Ferme une connexion persistante à la base de données

### Description

function db2_pclose(resource `$connection`): bool

Cette fonction ferme une connexion client DB2, créée avec db2_pconnect(), et rend les ressources correspondantes au serveur de base de données.

> Note: Cette fonction n'est disponible que sur i5/OS en réponse à des requêtes d'administration i5/OS.

Si l'on a une connexion client DB2 persistante créée avec la fonction db2_pconnect(), il est possible d'utiliser cette fonction pour fermer la connexion. Pour éviter des coûts de performance significatifs liés à la connexion, cette fonction ne devrait être utilisée que dans de rares cas, lorsque la connexion persistante ne répond plus ou qu'elle ne sera plus nécessaire pendant une longue période.

### Liste de paramètres

`connection`
  Spécifie une connexion client DB2 active.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Fermer une connexion DB2 persistante

L'exemple ci-dessous montre comment fermer une connexion sur un serveur IBM DB2 i5/OS.

    <?php
    $conn = db2_pconnect('', '', '');
    $rc = db2_pclose($conn);
    if ($rc) {
        echo "La connexion a été correctement fermée.";
    }
    ?>

L'exemple ci-dessus va afficher :

    La connexion a été correctement fermée.

### Voir aussi

- db2_close() - Ferme une connexion de base de données
- db2_pconnect() - Retourne une connexion persistante à une base de données

# db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — Retourne une connexion persistante à une base de données

### Description

function db2_pconnect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Retourne une connexion persistante à une base de données IBM DB2 Universal Database, IBM Cloudscape ou Apache Derby.

Pour plus d'informations sur les connexions persistantes, voir Connexions persistantes aux bases de données.

Appeler db2_close() sur une connexion persistante retourne toujours `true`, mais la connexion sous-jacente du client DB2 demeure ouverte et attend de servir la prochaine requête correspondante de la fonction db2_pconnect().

Les utilisateurs de versions 1.9.0 ou plus d'ibm_db2 doivent savoir que l'extension exécutera un rollback sur une transaction dans une connexion persistante à la fin de la requête, terminant ainsi la transaction. Ceci évite un blocage transactionnel vers la requête suivante sur la même connexion si l'exécution du script se termine avant la transaction.

### Liste de paramètres

`database`
  Pour une connexion cataloguée à une base de données, `database` représente l'alias de la base de données dans le catalogue du client DB2.

  Pour une connexion non cataloguée à une base de données, `database` représente une chaîne de connexion complète au format suivant :

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Note:

  > Lors de la connexion à Db2 sur IBM i, les appels système sous-jacents » SQLDriverConnect, n'acceptent que DSN, UID et PWD pour la » chaîne de connexion. Comme suit :

  >     DSN=database;UID=username;PWD=password;

  où les paramètres représentent les valeurs suivantes :
  `database`
    Le nom de la base de données.
  `hostname`
    Le nom d'hôte ou l'adresse IP du serveur de la base de données.
  `port`
    Le port TCP/IP sur lequel la base de données écoute les requêtes.
  `username`
    Le nom d'utilisateur utilisé pour la connexion à la base de données.
  `password`
    Le mot de passe utilisé pour la connexion à la base de données.
`username`
  Le nom d'utilisateur utilisé pour la connexion à la base de données.
`password`
  Le mot de passe utilisé pour la connexion à la base de données.
`options`

  Un tableau associatif des options de connexion qui affecteront le comportement de la connexion, où les valeurs des clés incluent :

  `autocommit`
    La valeur `DB2_AUTOCOMMIT_ON` active l'autocommit sur cette connexion. La valeur `DB2_AUTOCOMMIT_OFF` désactive l'autocommit pour cette connexion.
  `DB2_ATTR_CASE`
    Passer la valeur `DB2_CASE_NATURAL` spécifie que les noms de colonnes seront retournés dans leurs casses naturelles. Passer la valeur `DB2_CASE_LOWER` spécifie que les noms de colonnes seront retournés en minuscule. Passer la valeur `DB2_CASE_UPPER` spécifie que les noms de colonnes seront retournés en majuscule.
  `CURSOR`
    Passer la valeur `DB2_FORWARD_ONLY` spécifie un curseur uniquement suivant pour une ressource de requête. C'est le type de curseur par défaut et est supporté sur tous les serveurs de base de données. Passer la valeur `DB2_SCROLLABLE` spécifie un curseur scrollable pour une ressource de requête. Ce mode permet un accès aléatoire aux lignes dans un jeu de résultats, mais actuellement, n'est supporté que par la base de données IBM DB2 Universal.

  Les options suivantes sont disponibles à partir d'ibm_db2 version 1.7.0.

  `trustedcontext`
    En passant la valeur DB2_TRUSTED_CONTEXT_ENABLE, le contexte de confiance est activé pour cette connexion. Ce paramètre ne peut pas être activé avec db2_set_option(). Cette option ne fonctionne que si la base est cataloguée, même si la base est locale, ou si l'on spécifie un DSN complet lors de la création de la connexion. Pour cataloguer la base, utiliser la commande suivante :

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
        db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
        db2 "update dbm cfg using svcename <SERVICENAME>"
        db2set DB2COMM=TCPIP

  Les options i5/OS suivantes sont disponibles à partir d'ibm_db2 version 1.5.1.

  Astuce

  Des attributs de connexion contradictoires, en conjonction avec des connexions persistantes, peuvent produire des résultats indéterminés sur i5/OS. La politique du site doit être établie pour toutes les applications utilisant chaque profil utilisateur de connexion persistante. La valeur par défaut DB2_AUTOCOMMIT_ON est recommandée avec les connexions persistantes.

  `i5_lib`
    Une valeur de type caractère qui indique la bibliothèque par défaut qui sera utilisée pour résoudre les références de fichiers non qualifiées. Cette option n'est pas valide si la connexion utilise le mode de nommage système.
  `i5_naming`
    `DB2_I5_NAMING_ON` active le mode de nommage système de DB2 UDB CLI iSeries. Les fichiers sont alors qualifiés avec le délimiteur slash (/). Les fichiers non qualifiés sont résolus en utilisant la liste de bibliothèque de la tâche. `DB2_I5_NAMING_OFF` active le mode de nommage par défaut, qui est le nommage SQL. Les fichiers sont alors qualifiés avec le point (.) . Les fichiers non qualifiés sont résolus avec la bibliothèque par défaut, ou bien l'identifiant de l'utilisateur courant.
  `i5_commit`

    L'attribut `i5_commit` doit être configuré avant l'appel à db2_pconnect(). Si la valeur est changée après la connexion, et que la connexion s'effectue sur des données distantes, alors ce changement n'aura pas d'effets, jusqu'au prochain appel réussi à db2_pconnect().

    > Note: La directive du php.ini `ibm_db2.i5_allow_commit`==0 ou `DB2_I5_TXN_NO_COMMIT` est la valeur par défaut, mais peut être remplacée par l'option `i5_commit`.

    `DB2_I5_TXN_NO_COMMIT` : le contrôle de validation n'est pas utilisé. `DB2_I5_TXN_READ_UNCOMMITTED` : les lectures incohérentes, ou non répétables et les fantômes sont possibles. `DB2_I5_TXN_READ_COMMITTED` : les lectures incohérentes ne sont pas possibles. Les lectures non répétables et les fantômes sont possibles. `DB2_I5_TXN_REPEATABLE_READ` : les lectures incohérentes et les lectures non répétables ne sont pas possibles. Les fantômes sont possibles. `DB2_I5_TXN_SERIALIZABLE` : les transactions sont sérialisables. Les lectures incohérentes, les lectures non répétables et les fantômes ne sont pas possibles.
  `i5_query_optimize`
    `DB2_FIRST_IO` : toutes les requêtes sont optimisées dans le but de retourner la première page le plus rapidement possible. Cet objectif fonctionne bien lorsque le résultat est contrôlé par un utilisateur qui a de bonnes chances d'annuler la requête après avoir vu les premières réponses. Les requêtes codées avec une clause `OPTIMIZE FOR nnn ROWS` respectent aussi cet objectif. `DB2_ALL_IO` : toutes les requêtes sont optimisées dans le but de traiter la requête complète le plus rapidement possible. C'est une bonne option lorsque le résultat de la requête doit être écrit dans un fichier ou un rapport, ou que l'interface accumule toutes les données de sortie. Les requêtes codées avec la clause `OPTIMIZE FOR nnn ROWS` respectent aussi cet objectif. C'est le comportement par défaut.
  `i5_dbcs_alloc`
    `DB2_I5_DBCS_ALLOC_ON` active le schéma d'allocation DB2 6X pour la croissance des tailles de colonnes de translation DBCS.

    `DB2_I5_DBCS_ALLOC_OFF` désactive le schéma d'allocation DB2 6X pour la croissance des tailles de colonnes de translation DBCS.

    > Note: La directive du php.ini `ibm_db2.i5_dbcs_alloc`==0 ou `DB2_I5_DBCS_ALLOC_OFF` est la valeur par défaut, mais peut être remplacée par l'option `i5_dbcs_alloc`.

  `i5_date_fmt`
    `DB2_I5_FMT_ISO` : le format de date ISO (`International Organization for Standardization`) est utilisé : `yyyy-mm-dd`. C'est le format par défaut. `DB2_I5_FMT_USA` : le format des États-Unis d'Amérique est utilisé : `mm/dd/yyyy`. `DB2_I5_FMT_EUR` : le format de date européen `dd.mm.yyyy` est utilisé. `DB2_I5_FMT_JIS` : le format standard industriel japonais `yyyy-mm-dd` est utilisé. `DB2_I5_FMT_MDY` : le format de date `mm/dd/yyyy` est utilisé. `DB2_I5_FMT_DMY` : le format de date `dd/mm/yyyy` est utilisé. `DB2_I5_FMT_YMD` : le format de date `yy/mm/dd` est utilisé. `DB2_I5_FMT_JUL` : le format de date julien `yy/ddd` est utilisé. `DB2_I5_FMT_JOB` : le format de date par défaut est utilisé.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` : un slash ( / ) est utilisé comme séparateur de date. C'est le format par défaut. `DB2_I5_SEP_DASH` : un tiret ( - ) est utilisé comme séparateur de date. `DB2_I5_SEP_PERIOD` : un point ( . ) est utilisé comme séparateur de date. `DB2_I5_SEP_COMMA` : une virgule ( , ) est utilisée comme séparateur de date. `DB2_I5_SEP_BLANK` : un espace est utilisé comme séparateur de date. `DB2_I5_SEP_JOB` : la configuration par défaut est utilisée.
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` : le format d'heure ISO (`International Organization for Standardization`) est utilisé : `hh.mm.ss`. C'est le format par défaut. `DB2_I5_FMT_USA` : le format des États-Unis d'Amérique est utilisé : `hh:mmxx` est utilisé, où `xx` vaut `AM` ou `PM`. `DB2_I5_FMT_EUR` : le format d'heure européen `hh.mm.ss` est utilisé. `DB2_I5_FMT_JIS` : le format standard industriel japonais est utilisé `hh:mm:ss`. `DB2_I5_FMT_HMS` : le format `hh:mm:ss` est utilisé.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` : un deux-points ( : ) est utilisé comme séparateur d'heure. C'est la valeur par défaut. `DB2_I5_SEP_PERIOD` : un point ( . ) est utilisé comme séparateur d'heure. `DB2_I5_SEP_COMMA` : une virgule ( , ) est utilisée comme séparateur d'heure. `DB2_I5_SEP_BLANK` : un espace est utilisé comme séparateur d'heure. `DB2_I5_SEP_JOB` : le séparateur par défaut est utilisé.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` : un point ( . ) est utilisé comme séparateur décimal. C'est le séparateur par défaut. `DB2_I5_SEP_COMMA` : une virgule ( , ) est utilisée comme séparateur décimal. `DB2_I5_SEP_JOB` : le séparateur par défaut est utilisé.

  L'option i5/OS suivante est disponible à partir d'ibm_db2 version 1.8.0.

  `i5_libl`

    Une valeur de type caractère qui indique la liste de bibliothèques qui sera utilisée pour résoudre les références de fichiers non qualifiées. Spécifier la liste de bibliothèques sous la forme d'éléments séparés par des espaces : `'i5_libl'=>"MYLIB YOURLIB ANYLIB"`.

    > Note: i5_libl appelle `qsys2/qcmdexc('cmd',cmdlen)`, qui n'est disponible qu'à partir d'i5/OS V5R4.

### Valeurs de retour

Retourne la ressource de connexion si la tentative de connexion réussit. db2_pconnect() essaie de réutiliser une ressource de connexion existante qui correspond parfaitement aux paramètres tels que la base de données `database`, l'utilisateur `username` et le mot de passe `password`. Si la tentative de connexion échoue, db2_pconnect() retourne `false`

### Historique

Version | Description
--- | ---
PECL ibm_db2 1.9.0 | Les transactions actives sur des connexions persistantes seront annulées à la fin de chaque requête.
PECL ibm_db2 1.8.0 | L'option `i5_libl` est disponible pour les utilisateurs d'i5/OS.
PECL ibm_db2 1.7.0 | L'option `trustedcontext` est disponible.
PECL ibm_db2 1.5.1 | Les options `i5_lib`, `i5_naming`, `i5_commit`, `i5_query_optimize`, `i5_dbcs_alloc`, `i5_date_fmt`, `i5_date_sep`, `i5_time_fmt`, `i5_time_sep` et `i5_decimal_sep` sont disponibles pour les utilisateurs d'i5/OS.

### Exemples

Exemple #1 Exemple d'utilisation de db2_pconnect()

Dans l'exemple suivant, le premier appel à db2_pconnect() retourne une nouvelle ressource de connexion persistante. Le second appel à la fonction db2_pconnect() retourne une ressource de connexion persistante qui réutilise la première ressource de connexion.

    <?php
    $database = 'EXEMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $pconn = db2_pconnect($database, $user, $password);

    if ($pconn) {
        echo "Connexion persistante réussie.";
    }
    else {
        echo "Connexion persistante échouée.";
    }

    $pconn2 = db2_pconnect($database, $user, $password);
    if ($pconn) {
        echo "Deuxième connexion persistante réussie.";
    }
    else {
        echo "Deuxième connexion persistante échouée.";
    }
    ?>

L'exemple ci-dessus va afficher :

    Connexion persistante réussie.
    Deuxième connexion persistante réussie.

Exemple #2 Utilisation de contextes de confiance DB2

L'exemple suivant montre comment activer le contexte de confiance, changer d'utilisateur et obtenir l'identifiant de l'utilisateur courant.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
      PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
    $options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_pconnect($dsn, "", "", $options);
    if($tc_conn) {
        echo "Connexion de confiance réussie.\n";

        if(db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            //Travail par l'utilisateur 1.

            //Bascule sur l'utilisateur de confiance.
            $parameters = array("trusted_user" => $tc_user,
              "trusted_password" => $tcuser_pass);
            $res = db2_set_option ($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            //Travail supplémentaire en tant qu'utilisateur de confiance.

            if($userBefore != $userAfter) {
                echo "Utilisateur changé." . "\n";
            }
        }

        db2_close($tc_conn);
    }
    else {
        echo "Connexion de confiance échouée.\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    Connexion de confiance réussie.
    Utilisateur changé.

### Voir aussi

- db2_connect() - Retourne une connexion à une base de données

# db2_prepare

(PECL ibm_db2 >= 1.0.0)

db2_prepare — Prépare une requête SQL à être exécutée

### Description

function db2_prepare(resource `$connection`, string `$statement`, array `$options` = []): resource|false

db2_prepare() crée une requête SQL préparée qui peut inclure aucun ou plusieurs marqueurs (caractères `?`) représentant les paramètres d'entrée, sortie ou d'entrée/sortie. Il est possible de passer des paramètres à la requête préparée en utilisant la fonction db2_bind_param(), s'il n'y a que des entrées, il est possible d'utiliser db2_execute().

Il y a trois principaux avantages d'utiliser les requêtes préparées dans l'application :

- Performance : lors de la préparation d'une requête, le serveur de base de données crée un plan d'accès optimisé pour la récupération des données avec la requête. Par la suite, l'envoi de la requête préparée avec db2_execute() permet à la requête de réutiliser le plan d'accès et ainsi d'éviter les surcharges du processeur à chaque envoi de requête qui créerait dynamiquement un nouveau plan d'accès.
- Sécurité : lors de la préparation d'une requête, l'on peut inclure des marqueurs pour les valeurs d'entrées. Lors de l'exécution d'une requête préparée avec ces valeurs d'entrées, le serveur de base de données vérifie chaque valeur d'entrée pour s'assurer que les types concordent avec la définition de la colonne ou du paramètre de définition.
- Fonctionnalité avancée : Les marqueurs permettent non seulement de passer des valeurs d'entrées dans les requêtes SQL préparées, mais permettent aussi de récupérer des paramètres de SORTIE et d'ENTRÉE/SORTIE des procédures stockées en utilisant la fonction db2_bind_param().

### Liste de paramètres

`connection`
  Une variable ressource de connexion valide retournée par db2_connect() ou db2_pconnect().
`statement`
  Une requête SQL qui peut contenir un ou plusieurs marqueurs.
`options`
  Un tableau associatif contenant les options de la requête. Il est possible d'utiliser ce paramètre pour demander un curseur flottant sur les serveurs de base de données qui supportent cette fonctionnalité. Pour une description des options valides, se reporter à la fonction db2_set_option().

### Valeurs de retour

Retourne une ressource d'instruction si la requête SQL a été analysée et préparée avec succès par le serveur de base de données. Retourne `false` si le serveur de base de données a retourné une erreur. Il est possible de déterminer quelle erreur a été retournée en appelant la fonction db2_stmt_error() ou db2_stmt_errormsg().

### Exemples

Exemple #1 Préparation et exécution d'une requête SQL avec des marqueurs

L'exemple suivant prépare une requête INSERT qui accepte quatre marqueurs, ensuite itère sur le tableau contenant les valeurs d'entrées qui sera passé à la fonction db2_execute().

    <?php
    $animaux = array(
        array(0, 'chat', 'Pook', 3.2),
        array(1, 'chien', 'Peaches', 12.3),
        array(2, 'cheval', 'Smarty', 350.0),
    );

    $insert = 'INSERT INTO animaux (id, race, nom, poids)
        VALUES (?, ?, ?, ?)';
    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        foreach ($animaux as $animal) {
            $result = db2_execute($stmt, $animal);
        }
    }
    ?>

### Voir aussi

- db2_bind_param() - Associe une variable PHP à un paramètre d'une requête SQL
- db2_execute() - Exécute une requête SQL préparée
- db2_stmt_error() - Retourne une chaîne contenant la valeur de SQLSTATE retournée par une requête SQL
- db2_stmt_errormsg() - Retourne le dernier message d'erreur d'une requête SQL

# db2_primary_keys

(PECL ibm_db2 >= 1.0.0)

db2_primary_keys — Retourne un jeu de résultats listant les clés primaires d'une table

### Description

function db2_primary_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

Retourne un jeu de résultats listant les clés primaires d'une table.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, passez `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les tables. Si `schema` est `null`, db2_primary_keys() fait concorder le schéma pour la connexion courante.
`table_name`
  Le nom de la table.

### Valeurs de retour

Retourne une ressource d'instruction avec un jeu de résultats contenant des lignes décrivant les clés primaires pour la table spécifiée. Le jeu de résultats est composé des colonnes suivantes :

Nom de la colonne | Description
--- | ---
TABLE_CAT | Nom du catalogue de la table contenant la clé primaire. La valeur est `null` si la table n'a pas de catalogue.
TABLE_SCHEM | Nom du schéma de la table contenant la clé primaire.
TABLE_NAME | Nom de la table contenant la clé primaire.
COLUMN_NAME | Nom de la colonne contenant la clé primaire.
KEY_SEQ | Position commençant à 1 de la colonne dans la clé.
PK_NAME | Nom de la clé primaire.

### Voir aussi

- db2_column_privileges() - Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_columns() - Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_foreign_keys() - Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_procedure_columns() - Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_procedures() - Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_special_columns() - Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_statistics() - Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_table_privileges() - Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
- db2_tables() - Retourne la liste des tables et leurs métadonnées

# db2_procedure_columns

(PECL ibm_db2 >= 1.0.0)

db2_procedure_columns — Retourne un jeu de résultats listant les paramètres de procédure stockée

### Description

function db2_procedure_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`,
?string `$parameter`
): resource

Retourne un jeu de résultats listant les paramètres pour une ou plusieurs procédures stockées.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, passez `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les procédures. Ce paramètre accepte un motif de recherche contenant `_` et `%` en tant que caractères génériques.
`procedure`
  Le nom de la procédure. Ce paramètre accepte un motif de recherche contenant `_` et `%` en tant que caractères génériques.
`parameter`
  Le nom du paramètre. Ce paramètre accepte un motif de recherche contenant `_` et `%` en tant que caractères génériques. Si ce paramètre est `null`, tous les paramètres pour les procédures stockées spécifiées sont retournés.

### Valeurs de retour

Retourne une ressource d'instruction avec un jeu de résultats contenant les lignes qui décrivent les paramètres pour les procédures stockées qui correspondent aux paramètres spécifiés. Les lignes sont composées des colonnes suivantes :

Nom de la colonne | Description
--- | ---
PROCEDURE_CAT | Le catalogue qui contient la procédure. La valeur est `null` si cette table n'a pas de catalogue.
PROCEDURE_SCHEM | Nom du schéma qui contient la procédure stockée.
PROCEDURE_NAME | Nom de la procédure.
COLUMN_NAME | Nom du paramètre.
COLUMN_TYPE | Un entier représentant le type du paramètre :
Valeur de retour | Type de paramètre
--- | ---
1 (SQL_PARAM_INPUT) | Paramètre d'entrée (IN).
2 (SQL_PARAM_INPUT_OUTPUT) | Paramètre d'entrée/sortie (INOUT).
3 (SQL_PARAM_OUTPUT) | Paramètre de sortie (OUT).
DATA_TYPE | Le type de données SQL pour le paramètre représenté en tant qu'entier.
TYPE_NAME | Une chaîne représentant le type de données pour le paramètre.
COLUMN_SIZE | Un entier représentant la taille du paramètre.
BUFFER_LENGTH | Nombre maximal d'octets nécessaires pour stocker les données de ce paramètre.
DECIMAL_DIGITS | L'échelle du paramètre, ou `null` lorsque l'échelle n'est pas applicable.
NUM_PREC_RADIX | Un entier pouvant être `10` (représentant un type de données numérique exact), `2` (représentant un type de données numérique approché) ou `null` (représentant un type de données pour lequel la base n'est pas applicable).
NULLABLE | Un entier indiquant si le paramètre peut être nul ou non.
REMARKS | Description du paramètre.
COLUMN_DEF | Valeur par défaut du paramètre.
SQL_DATA_TYPE | Un entier représentant la taille du paramètre.
SQL_DATETIME_SUB | Retourne un entier représentant un code de sous-type `datetime`, ou `null` pour les types de données SQL auxquels cela ne s'applique pas.
CHAR_OCTET_LENGTH | Longueur maximale en octets pour un paramètre de type de données caractère, qui correspond à COLUMN_SIZE pour les données d'un jeu de caractères mono-octet, ou `null` pour les types de données non caractères.
ORDINAL_POSITION | La position du paramètre, indexée à partir de 1, dans l'instruction `CALL`.
IS_NULLABLE | Une valeur de chaîne où 'YES' signifie que le paramètre accepte ou retourne des valeurs `null`, et 'NO' signifie que le paramètre n'accepte ou ne retourne pas de valeurs `null`.

### Voir aussi

- db2_column_privileges() - Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_columns() - Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_foreign_keys() - Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_primary_keys() - Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedures() - Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_special_columns() - Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_statistics() - Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_table_privileges() - Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
- db2_tables() - Retourne la liste des tables et leurs métadonnées

# db2_procedures

(PECL ibm_db2 >= 1.0.0)

db2_procedures — Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données

### Description

function db2_procedures(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`
): resource

Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, il faut passer `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les procédures. Ce paramètre accepte un motif de recherche contenant `_` et `%` comme caractères génériques.
`procedure`
  Le nom de la procédure. Ce paramètre accepte un motif de recherche contenant `_` et `%` comme caractères génériques.

### Valeurs de retour

Retourne une ressource d'instruction avec un jeu de résultats contenant les lignes qui décrivent les procédures stockées qui correspondent aux paramètres spécifiés. Les lignes sont composées des colonnes suivantes :

Nom de la colonne | Description
--- | ---
PROCEDURE_CAT | Le catalogue qui contient la procédure. La valeur est `null` si la table n'a pas de catalogue.
PROCEDURE_SCHEM | Nom du schéma qui contient la procédure stockée.
PROCEDURE_NAME | Nom de la procédure.
NUM_INPUT_PARAMS | Nombre de paramètres d'entrée (IN) pour la procédure stockée.
NUM_OUTPUT_PARAMS | Nombre de paramètres de sortie (OUT) pour la procédure stockée.
NUM_RESULT_SETS | Nombre de jeux de résultats retournés par la procédure stockée.
REMARKS | Commentaires concernant la procédure stockée.
PROCEDURE_TYPE | Retourne toujours `1`, indiquant que la procédure stockée ne retourne aucune valeur de retour.

### Voir aussi

- db2_column_privileges() - Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_columns() - Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_foreign_keys() - Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_primary_keys() - Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedure_columns() - Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_special_columns() - Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_statistics() - Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_table_privileges() - Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
- db2_tables() - Retourne la liste des tables et leurs métadonnées

# db2_result

(PECL ibm_db2 >= 1.0.0)

db2_result — Retourne une colonne d'une ligne d'un jeu de résultats

### Description

function db2_result(resource `$stmt`, int|string `$column`): ?mixed

Utiliser db2_result() pour retourner une valeur d'une colonne spécifique dans la ligne courante d'un jeu de résultats. Il faut appeler db2_fetch_row() avant d'appeler db2_result() pour enregistrer les valeurs pointées du jeu de résultats.

### Liste de paramètres

`stmt`
  Une ressource `stmt` valide.
`column`
  Soit un entier correspondant au champ commençant à l'indice 0 dans le jeu de résultats, soit une chaîne représentant le nom de la colonne.

### Valeurs de retour

Retourne la valeur du champ demandé si le champ existe dans le jeu de résultats. Retourne `null` si le champ n'existe pas, et émet une alerte.

### Exemples

Exemple #1 Exemple d'utilisation de db2_result()

L'exemple suivant démontre comment itérer à travers un jeu de résultats avec la fonction db2_fetch_row() et récupérer les colonnes du jeu de résultats avec db2_result().

    <?php
    $sql = 'SELECT nom, race FROM animaux WHERE poids < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $nom = db2_result($stmt, 0);
        $race = db2_result($stmt, 'RACE');
        print "$nom $race";
    }
    ?>

L'exemple ci-dessus va afficher :

    chat Pook
    cyprin doré Bubbles
    perruche Gizmo
    chèvre Rickety Ride

### Voir aussi

- db2_fetch_array() - Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats
- db2_fetch_assoc() - Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats
- db2_fetch_both() - Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats
- db2_fetch_object() - Retourne un objet avec les propriétés représentant des colonnes dans la ligne extraite
- db2_fetch_row() - Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée

# db2_rollback

(PECL ibm_db2 >= 1.0.0)

db2_rollback — Annule une transaction

### Description

function db2_rollback(resource `$connection`): bool

Annule une transaction en cours sur la ressource de connexion spécifiée et commence une nouvelle transaction. Les applications PHP utilisent normalement le mode AUTOCOMMIT par défaut, donc db2_rollback() n'a normalement aucun effet tant que AUTOCOMMIT n'a pas été désactivé pour la ressource de connexion.

### Liste de paramètres

`connection`
  Une variable ressource de connexion à la base de données valide retournée par db2_connect() ou db2_pconnect().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Annulation d'une instruction DELETE

Dans l'exemple suivant, le nombre de lignes dans une table est compté, le mode AUTOCOMMIT est désactivé sur une connexion de base de données, toutes les lignes de la table sont supprimées et le compteur retourne `0` pour prouver que les lignes ont bien été supprimées. Ensuite, db2_rollback() est invoquée, et le nombre de lignes mis à jour dans la table est retourné pour montrer que le nombre est le même qu'avant l'exécution de l'instruction DELETE. Le retour à l'état original de la table démontre que l'annulation de la transaction a réussi.

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Désactive AUTOCOMMIT
        db2_autocommit($conn, DB2_AUTOCOMMIT_OFF);

        // Supprime toutes les lignes de ANIMALS
        db2_exec($conn, "DELETE FROM animals");

        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Annule l'instruction DELETE
        db2_rollback( $conn );

        $stmt = db2_exec( $conn, "SELECT count(*) FROM animals" );
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";
        db2_close($conn);
    }
    ?>

L'exemple ci-dessus va afficher :

    7
    0
    7

### Voir aussi

- db2_autocommit() - Retourne ou modifie l'état AUTOCOMMIT de la connexion à la base de données
- db2_commit() - Valide la transaction

# db2_server_info

(PECL ibm_db2 >= 1.1.1)

db2_server_info — Retourne un objet avec des propriétés qui décrivent le serveur de base de données DB2

### Description

function db2_server_info(resource `$connection`): stdClass|false

Cette fonction retourne un objet avec des propriétés en lecture seule qui retournent des informations à propos du serveur de base de données IBM DB2, Cloudscape ou Apache Derby. La table suivante liste les propriétés du serveur de base de données :

Propriétés serveur de base de données
Nom de la propriété | Type de retour | Description
--- | --- | ---
DBMS_NAME | chaîne de caractères | Le nom du serveur de base de données sur lequel l'on est connecté. Pour des serveurs DB2, c'est une combinaison de `DB2` suivi par le système d'exploitation sur lequel le serveur de base de données fonctionne.
DBMS_VER | chaîne de caractères | La version du serveur de la base de données, dans la forme d'une chaîne de caractères `"MM.mm.uuuu"` où MM est la version majeure, mm est la version mineure et uuuu est la mise à jour. Par exemple, `"08.02.0001"` représente la version majeure 8, la version mineure 2, la mise à jour 1.
DB_CODEPAGE | entier | Le code page de la base de données sur laquelle l'on est connecté.
DB_NAME | chaîne de caractères | Le nom de la base de données sur laquelle l'on est connecté.
DFT_ISOLATION | chaîne de caractères | Le niveau par défaut d'isolation de transaction supporté par le serveur : UR Lecture non validée (`Uncommitted read`) : les changements sont immédiatement visibles par toutes les transactions concurrentes. CS Stabilité du curseur (`Cursor stability`) : une ligne lue par une transaction peut être modifiée et validée par une seconde transaction concurrente. RS Stabilité de lecture (`Read stability`) : une transaction peut ajouter ou supprimer des lignes qui correspondent à une condition de recherche ou à une transaction en attente. RR Lecture répétée (`Repeatable read`) : les données affectées par les transactions en attente ne sont pas disponibles aux autres transactions. NC Aucune validation (`No commit`) : tout changement est visible à la fin d'une opération réussie. Les validations explicites et retours arrières ne sont pas autorisés.
IDENTIFIER_QUOTE_CHAR | chaîne de caractères | Le caractère utilisé pour délimiter un identifiant.
INST_NAME | chaîne de caractères | L'instance sur le serveur de base de données qui contient la base de données.
ISOLATION_OPTION | tableau | Un tableau des options d'isolation supportées par le serveur de base de données. Les options d'isolation sont décrites dans la propriété DFT_ISOLATION.
KEYWORDS | tableau | Un tableau des mots-clés réservés par le serveur de base de données.
LIKE_ESCAPE_CLAUSE | booléen | `true` si le serveur de base de données supporte l'utilisation des caractères de remplacement `%` et `_`. `false` si le serveur de base de données ne supporte pas ces caractères de remplacement.
MAX_COL_NAME_LEN | entier | Taille maximale d'un nom de colonne supportée par le serveur de base de données, exprimée en octets.
MAX_IDENTIFIER_LEN | entier | Taille maximale d'un identifiant SQL supportée par les serveurs de base de données, exprimée en caractères.
MAX_INDEX_SIZE | entier | Taille maximale des colonnes combinées dans un index supportée par le serveur de base de données, exprimée en octets.
MAX_PROC_NAME_LEN | entier | Taille maximale d'un nom de procédure supportée par le serveur de base de données, exprimée en octets.
MAX_ROW_SIZE | entier | Taille maximale d'une ligne dans la table de base supportée par le serveur de base de données, exprimée en octets.
MAX_SCHEMA_NAME_LEN | entier | Taille maximale d'un nom de schéma supportée par le serveur de base de données, exprimée en octets.
MAX_STATEMENT_LEN | entier | Taille maximale d'une requête SQL supportée par le serveur de base de données, exprimée en octets.
MAX_TABLE_NAME_LEN | entier | Taille maximale d'un nom de table supportée par le serveur de base de données, exprimée en octets.
NON_NULLABLE_COLUMNS | booléen | `true` si le serveur de base de données supporte les colonnes qui peuvent être définies comme NOT NULL, `false` si le serveur de base de données ne supporte pas les colonnes définies comme NOT NULL.
PROCEDURES | booléen | `true` si le serveur de base de données supporte l'utilisation de la requête CALL pour appeler les procédures stockées, `false` si le serveur de base de données ne supporte pas la requête CALL.
SPECIAL_CHARS | chaîne de caractères | Une chaîne de caractères contenant tous les caractères autres que les lettres (majuscules et minuscules), les chiffres et le caractère souligné qui peuvent être utilisés en tant que nom d'identifiant.
SQL_CONFORMANCE | chaîne de caractères | Le niveau de conformité à la spécification ANSI/ISO SQL-92 offert par le serveur de base de données : ENTRY Niveau d'entrée de conformité SQL-92. FIPS127 Conformité transitoire FIPS-127-2. FULL Niveau complet de conformité SQL-92. INTERMEDIATE Niveau intermédiaire de conformité SQL-92.

### Liste de paramètres

`connection`
  Spécifie la connexion cliente DB2 active.

### Valeurs de retour

Retourne un objet si l'appel est réussi, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec db2_server_info()

Pour récupérer des informations à propos du serveur, il faut passer une ressource de connexion de base de données valide à la fonction db2_server_info().

    <?php

    $conn = db2_connect('sample', 'db2inst1', 'ibmdb2');

    $server = db2_server_info( $conn );

    if ($server) {
        echo "DBMS_NAME: ";                 var_dump( $server->DBMS_NAME );
        echo "DBMS_VER: ";                  var_dump( $server->DBMS_VER );
        echo "DB_CODEPAGE: ";               var_dump( $server->DB_CODEPAGE );
        echo "DB_NAME: ";                   var_dump( $server->DB_NAME );
        echo "INST_NAME: ";                 var_dump( $server->INST_NAME );
        echo "SPECIAL_CHARS: ";             var_dump( $server->SPECIAL_CHARS );
        echo "KEYWORDS: ";                  var_dump( sizeof($server->KEYWORDS) );
        echo "DFT_ISOLATION: ";             var_dump( $server->DFT_ISOLATION );
        echo "ISOLATION_OPTION: ";
        $il = '';
        foreach( $server->ISOLATION_OPTION as $opt )
        {
           $il .= $opt." ";
        }
        var_dump( $il );
        echo "SQL_CONFORMANCE: ";           var_dump( $server->SQL_CONFORMANCE );
        echo "PROCEDURES: ";                var_dump( $server->PROCEDURES );
        echo "IDENTIFIER_QUOTE_CHAR: ";     var_dump( $server->IDENTIFIER_QUOTE_CHAR );
        echo "LIKE_ESCAPE_CLAUSE: ";        var_dump( $server->LIKE_ESCAPE_CLAUSE );
        echo "MAX_COL_NAME_LEN: ";          var_dump( $server->MAX_COL_NAME_LEN );
        echo "MAX_ROW_SIZE: ";              var_dump( $server->MAX_ROW_SIZE );
        echo "MAX_IDENTIFIER_LEN: ";        var_dump( $server->MAX_IDENTIFIER_LEN );
        echo "MAX_INDEX_SIZE: ";            var_dump( $server->MAX_INDEX_SIZE );
        echo "MAX_PROC_NAME_LEN: ";         var_dump( $server->MAX_PROC_NAME_LEN );
        echo "MAX_SCHEMA_NAME_LEN: ";       var_dump( $server->MAX_SCHEMA_NAME_LEN );
        echo "MAX_STATEMENT_LEN: ";         var_dump( $server->MAX_STATEMENT_LEN );
        echo "MAX_TABLE_NAME_LEN: ";        var_dump( $server->MAX_TABLE_NAME_LEN );
        echo "NON_NULLABLE_COLUMNS: ";      var_dump( $server->NON_NULLABLE_COLUMNS );

        db2_close($conn);
    }
    ?>

L'exemple ci-dessus va afficher :

    DBMS_NAME: string(9) "DB2/LINUX"
    DBMS_VER: string(10) "08.02.0000"
    DB_CODEPAGE: int(1208)
    DB_NAME: string(6) "SAMPLE"
    INST_NAME: string(8) "db2inst1"
    SPECIAL_CHARS: string(2) "@#"
    KEYWORDS: int(179)
    DFT_ISOLATION: string(2) "CS"
    ISOLATION_OPTION: string(12) "UR CS RS RR "
    SQL_CONFORMANCE: string(7) "FIPS127"
    PROCEDURES: bool(true)
    IDENTIFIER_QUOTE_CHAR: string(1) """
    LIKE_ESCAPE_CLAUSE: bool(true)
    MAX_COL_NAME_LEN: int(30)
    MAX_ROW_SIZE: int(32677)
    MAX_IDENTIFIER_LEN: int(18)
    MAX_INDEX_SIZE: int(1024)
    MAX_PROC_NAME_LEN: int(128)
    MAX_SCHEMA_NAME_LEN: int(30)
    MAX_STATEMENT_LEN: int(2097152)
    MAX_TABLE_NAME_LEN: int(128)
    NON_NULLABLE_COLUMNS: bool(true)

### Voir aussi

- db2_client_info() - Retourne un objet avec des propriétés qui décrivent le client de base de données DB2

# db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — Fixe des options pour une ressource de connexion ou une ressource d'instruction

### Description

function db2_set_option(resource `$resource`, array `$options`, int `$type`): bool

Fixe des options pour une ressource d'instruction ou une ressource de connexion. Il n'est pas possible de fixer des options pour des ressources de jeu de résultats.

### Liste de paramètres

`resource`
  Une ressource d'instruction valide retournée par db2_prepare() ou une ressource de connexion valide retournée par db2_connect() ou db2_pconnect().
`options`

  Un tableau associatif contenant des options d'instruction ou de connexion valides. Ce paramètre peut être utilisé pour changer les valeurs d'autocommit, les types de curseur (flottant ou à avance seule) et pour spécifier la casse des noms de colonne (minuscule, majuscule ou naturelle) qui apparaîtra dans le jeu de résultats.

  `autocommit`
    Passer `DB2_AUTOCOMMIT_ON` active l'autocommit pour la ressource de connexion spécifiée. Passer `DB2_AUTOCOMMIT_OFF` désactive l'autocommit pour la ressource de connexion spécifiée.
  `cursor`
    Passer `DB2_FORWARD_ONLY` spécifie un curseur à avance seule pour une ressource d'instruction. Ceci est le type de curseur par défaut, et il est supporté par tous les serveurs de base de données. Passer `DB2_SCROLLABLE` spécifie un curseur flottant pour une ressource d'instruction. Les curseurs flottants permettent aux lignes du jeu de résultats d'être accessibles dans un ordre non séquentiel, mais ils ne sont supportés que par les bases de données IBM DB2 Universal Database.
  `binmode`
    Passer `DB2_BINARY` spécifie que des données binaires seront retournées comme telles. Ceci est le mode par défaut. Ceci est équivalent à la configuration `ibm_db2.binmode=1` dans php.ini. Passer `DB2_CONVERT` spécifie que les données binaires seront converties en encodage hexadécimal et seront retournées ainsi. Ceci est équivalent à la configuration `ibm_db2.binmode=2` dans php.ini. Passer `DB2_PASSTHRU` spécifie que les données binaires seront converties en `null`. Ceci est équivalent à la configuration `ibm_db2.binmode=3` dans php.ini.
  `db2_attr_case`
    Passer `DB2_CASE_LOWER` spécifie que les noms des colonnes dans le jeu de résultats seront retournés en minuscules. Passer `DB2_CASE_UPPER` spécifie que les noms des colonnes dans le jeu de résultats seront retournés en majuscules. Passer `DB2_CASE_NATURAL` spécifie que les noms de colonnes dans le jeu de résultats seront retournés en casse naturelle.
  `deferred_prepare`
    Passer `DB2_DEFERRED_PREPARE_ON` active la préparation différée sur la ressource d'instruction spécifiée. Passer `DB2_DEFERRED_PREPARE_OFF` désactive la préparation différée sur la ressource d'instruction spécifiée.

  Les nouvelles options suivantes i5/OS sont disponibles à partir de la version 1.5.1 d'ibm_db2. Ces options s'appliquent uniquement lorsque PHP et ibm_db2 fonctionnent nativement sur un système i5.

  `i5_fetch_only`
    `DB2_I5_FETCH_ON` : les curseurs sont en lecture seule et ne peuvent être utilisés pour positionner des mises à jour et des suppressions. Ceci est la valeur par défaut à moins que la variable d'environnement `SQL_ATTR_FOR_FETCH_ONLY` ait été mise à `SQL_FALSE`. `DB2_I5_FETCH_OFF` : les curseurs peuvent être positionnés pour des mises à jour et des suppressions.

  La nouvelle option suivante est disponible à partir de ibm_db2 version 1.8.0.

  `rowcount`
    `DB2_ROWCOUNT_PREFETCH_ON` - Le client peut demander un comptage complet des lignes avant de les récupérer, ce qui signifie que la fonction db2_num_rows() retourne le nombre de lignes sélectionnées même si un curseur `ROLLFORWARD_ONLY` est utilisé. `DB2_ROWCOUNT_PREFETCH_OFF` - Le client ne peut pas demander un comptage complet des lignes avant de les récupérer.

  Les options suivantes sont nouvelles, et disponibles à partir de ibm_db2 version 1.7.0.

  `trusted_user`
    Pour basculer l'utilisateur vers un utilisateur de confiance, il faut passer l'identifiant utilisateur (chaîne de caractères) de l'utilisateur de confiance comme valeur de cette clé. Cette option ne peut être configurée que sur une ressource de connexion. Pour utiliser cette option, un contexte de confiance doit être activé sur la ressource de connexion.
  `trusted_password`
    Le mot de passe (chaîne de caractères) qui correspond à l'utilisateur spécifié par la clé trusted_user.

  Les options suivantes sont nouvelles, et disponibles à partir de ibm_db2 version 1.6.0. Ces options fournissent des informations de suivi utiles, accessibles pendant l'exécution via db2_get_option().

  > Note: Lorsque la valeur de chaque option est sur le point d'être définie, quelques serveurs peuvent ne pas gérer la totalité de la longueur fournie et peuvent tronquer la valeur. Pour s'assurer que les données spécifiées dans chaque option seront converties correctement lorsqu'elles seront transmises au système, utiliser seulement les caractères d'A à Z, 0 à 9, les soulignés (`_`) et les points (`.`).

  `userid`

    `SQL_ATTR_INFO_USERID` : un pointeur vers une chaîne de caractères terminée par `null` utilisée pour identifier l'ID utilisateur du client envoyé au serveur de base de données hôte lors de l'utilisation de DB2 Connect.

    > Note: DB2 pour les serveurs z/OS et OS/390 supporte une longueur jusqu'à 16 caractères. L'ID utilisateur ne doit pas être confondu avec l'ID utilisateur d'identification, il est utilisé pour les processus d'identification uniquement et non pour ceux d'autorisation.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR` : un pointeur vers une chaîne de caractères terminée par `null` utilisée pour identifier la chaîne de comptabilité du client à envoyer au serveur de base de données hôte lors de l'utilisation de DB2 Connect.

    > Note: DB2 pour les serveurs z/OS et OS/390 supporte une longueur jusqu'à 200 caractères.

  `applname`

    `SQL_ATTR_INFO_APPLNAME` : un pointeur vers une chaîne de caractères terminée par `null` utilisée pour identifier le nom de l'application client à envoyer au serveur de base de données hôte lors de l'utilisation de DB2 Connect.

    > Note: DB2 pour les serveurs z/OS et OS/390 supporte une longueur jusqu'à 32 caractères.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME` : un pointeur vers une chaîne de caractères terminée par `null` utilisée pour identifier le nom de la station de travail du client à envoyer au serveur de base de données hôte lors de l'utilisation de DB2 Connect.

    > Note: DB2 pour les serveurs z/OS et OS/390 supporte une longueur jusqu'à 18 caractères.

`type`
  Un entier qui spécifie le type de ressource qui a été passé à la fonction. Le type de ressource et cette valeur doivent correspondre. Passer `1` en tant que valeur spécifie qu'une ressource de connexion a été passée à la fonction. Passer n'importe quel entier différent de `1` en tant que valeur spécifie qu'une ressource d'instruction a été passée à la fonction.

Le tableau suivant spécifie quelles options sont compatibles avec quels types de ressources :

Matrice ressource-paramètre
Clé | Valeur | Type de ressource
--- | --- | ---
|  | Connexion | Instruction | Jeu de résultats
autocommit | `DB2_AUTOCOMMIT_ON` | X | - | -
autocommit | `DB2_AUTOCOMMIT_OFF` | X | - | -
cursor | `DB2_SCROLLABLE` | - | X | -
cursor | `DB2_FORWARD_ONLY` | - | X | -
binmode | `DB2_BINARY` | X | X | -
binmode | `DB2_CONVERT` | X | X | -
binmode | `DB2_PASSTHRU` | X | X | -
db2_attr_case | `DB2_CASE_LOWER` | X | X | -
db2_attr_case | `DB2_CASE_UPPER` | X | X | -
db2_attr_case | `DB2_CASE_NATURAL` | X | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_ON` | - | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_OFF` | - | X | -
i5_fetch_only | `DB2_I5_FETCH_ON` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_ON` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_OFF` | - | X | -
trusted_user | `<USER NAME> (String)` | X | - | -
trusted_password | `<PASSWORD> (String)` | X | - | -
i5_fetch_only | `DB2_I5_FETCH_OFF` | - | X | -
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Fixer un paramètre à une ressource de connexion

    <?php
    /* Paramètres de Connexion */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Chaînes de caractères de Connexion */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Récupération de la Ressource de Connexion */
    $conn = db2_connect($conn_string, '', '');

    /* Crée le tableau associatif d'options avec des paires clé-valeur valides */
    $options = array('autocommit' => DB2_AUTOCOMMIT_ON);

    /* Appel de la fonction en utilisant le type correct de ressource, le tableau
    * d'options et la valeur type */
    $result = db2_set_option($conn, $options, 1);

    /* Vérifie si toutes les options peuvent être fixées correctement */
    if($result)
    {
       echo 'Options fixées correctement';
    }
    else
    {
       echo 'Impossible de fixer les options';
    }
    ?>

L'exemple ci-dessus va afficher :

    Options fixées correctement

Exemple #2 Fixe des paramètres multiples avec une ressource de connexion

    <?php
    /* Paramètres de Connexion */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Chaînes de caractères de Connexion */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Récupération de la Ressource de Connexion */
    $conn = db2_connect($conn_string, '', '');

    /* Crée le tableau associatif d'options avec des paires clé-valeur valides */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'binmode' => DB2_PASSTHRU,
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    /* Appel de la fonction en utilisant le type correct de ressource, le tableau
    * d'options et la valeur type */
    $result = db2_set_option($conn, $options, 1);

    /* Vérifie si toutes les options peuvent être fixées correctement */
    if($result)
    {
      echo 'Options fixées correctement';
    }
    else
    {
      echo 'Impossible de fixer les options';
    }
    ?>

L'exemple ci-dessus va afficher :

    Options fixées correctement

Exemple #3 Fixe des paramètres multiples avec une clé invalide

    <?php
    /* Paramètres de Connexion */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Chaînes de caractères de Connexion */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Récupération de la Ressource de Connexion */
    $conn = db2_connect($conn_string, '', '');

    /* Crée le tableau associatif d'options avec des paires clé-valeur valides */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'MY_INVALID_KEY' => DB2_PASSTHRU,
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    /* Appel de la fonction en utilisant le type correct de ressource, le tableau
    * d'options et la valeur type */
    $result = db2_set_option($conn, $options, 1);

    /* Vérifie si toutes les options peuvent être fixées correctement */
    if($result)
    {
       echo 'Options fixées correctement';
    }
    else
    {
       echo 'Impossible de fixer les options';
    }
    ?>

L'exemple ci-dessus va afficher :

    Impossible de fixer les options

Exemple #4 Fixe des paramètres multiples avec une valeur invalide

    <?php
    /* Paramètres de Connexion */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Chaînes de caractères de Connexion */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Récupération de la Ressource de Connexion */
    $conn = db2_connect($conn_string, '', '');

    /* Crée le tableau associatif d'options avec des paires clé-valeur valides */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'binmode' => 'INVALID_VALUE',
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    /* Appel de la fonction en utilisant le type correct de ressource, le tableau
    * d'options et la valeur type */
    $result = db2_set_option($conn, $options, 1);

    /* Vérifie si toutes les options peuvent être fixées correctement */
    if($result)
    {
       echo 'Options fixées correctement';
    }
    else
    {
       echo 'Impossible de fixer les options';
    }
    ?>

L'exemple ci-dessus va afficher :

    Impossible de fixer les options

Exemple #5 Fixe des paramètres multiples avec une ressource de connexion et un mauvais type

    <?php
    /* Paramètres de Connexion */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Chaînes de caractères de Connexion */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Récupération de la Ressource de Connexion */
    $conn = db2_connect($conn_string, '', '');

    /* Crée le tableau associatif d'options avec des paires clé-valeur valides */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'binmode' => DB2_PASSTHRU,
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    /* Appel de la fonction en utilisant le type correct de ressource, le tableau
    * d'options et la valeur type invalide */
    $result = db2_set_option($conn, $options, 2);

    /* Vérifie si toutes les options peuvent être fixées correctement */
    if($result)
    {
      echo 'Options fixées correctement';
    }
    else
    {
      echo 'Impossible de fixer les options';
    }
    ?>

L'exemple ci-dessus va afficher :

    Impossible de fixer les options

Exemple #6 Fixe des paramètres multiples avec une mauvaise ressource

    <?php
    /* Paramètres de Connexion */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Chaînes de caractères de Connexion */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Récupération de la Ressource de Connexion */
    $conn = db2_connect($conn_string, '', '');

    /* Crée le tableau associatif d'options avec des paires clé-valeur valides */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
    'binmode' => DB2_PASSTHRU,
    'db2_attr_case' => DB2_CASE_UPPER,
    'cursor' => DB2_SCROLLABLE);

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

    /* Appel de la fonction en utilisant le type incorrect de ressource, mais le tableau
    * d'options et la valeur type valide */
    $result = db2_set_option($stmt, $options, 1);

    /* Vérifie si toutes les options peuvent être fixées correctement */
    if($result)
    {
      echo 'Options fixées correctement';
    }
    else
    {
      echo 'Impossible de fixer les options';
    }
    ?>

L'exemple ci-dessus va afficher :

    Impossible de fixer les options

Exemple #7 Tout mettre ensemble

    <?php
    /* Paramètres de Connexion */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Chaînes de caractères de Connexion */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Récupération de la Ressource de Connexion */
    $conn = db2_connect($conn_string, '', '');

    /* Crée le tableau associatif d'options avec des paires clé-valeur valides */
    $options = array('db2_attr_case' => DB2_CASE_LOWER,
    'cursor' => DB2_SCROLLABLE);

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

    /* Appel de la fonction en utilisant le type correct de ressource, le tableau
    * d'options et la valeur type */
    $option_result = db2_set_option($stmt, $options, 2);
    $result = db2_execute($stmt, array('000130', '000140'));

    /* Récupère la ligne 2 avant la ligne 1 puisque nous avons un curseur flottant */
    print_r(db2_fetch_assoc($stmt, 2));
    print '<br /><br />';
    print_r(db2_fetch_assoc($stmt, 1));

    ?>

L'exemple ci-dessus va afficher :

    Array
    (
         [empno] => 000140
         [firstnme] => HEATHER
         [midinit] => A
         [lastname] => NICHOLLS
         [workdept] => C01
         [phoneno] => 1793
         [hiredate] => 1976-12-15
         [job] => ANALYST
         [edlevel] => 18
         [sex] => F
         [birthdate] => 1946-01-19
         [salary] => 28420.00
         [bonus] => 600.00
         [comm] => 2274.00
    )

    Array
    (
         [empno] => 000130
         [firstnme] => DELORES
         [midinit] => M
         [lastname] => QUINTANA
         [workdept] => C01
         [phoneno] => 4578
         [hiredate] => 1971-07-28
         [job] => ANALYST
         [edlevel] => 16
         [sex] => F
         [birthdate] => 1925-09-15
         [salary] => 23800.00
         [bonus] => 500.00
         [comm] => 1904.00
    )

Exemple #8 Les curseurs i5/OS sont en lecture seule

    <?php
    $conn = db2_connect("", "", "", array("i5_lib"=>"nobody"));
    $stmt = db2_prepare($conn, 'select * from names where first = ?');
    $name = "first2";
    db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
    $options = array("i5_fetch_only"=>DB2_I5_FETCH_ON);
    db2_set_option($stmt,$options,0);
    if (db2_execute($stmt)) {
       while ($row = db2_fetch_array($stmt)) {
          echo "{$row[0]} {$row[1]}";
       }
    }
    ?>

L'exemple ci-dessus va afficher :

    first2 last2

### Voir aussi

- db2_connect() - Retourne une connexion à une base de données
- db2_pconnect() - Retourne une connexion persistante à une base de données
- db2_exec() - Exécute une requête SQL directement
- db2_prepare() - Prépare une requête SQL à être exécutée
- db2_cursor_type() - Retourne le type de curseur utilisé par une ressource d'instruction

# db2_special_columns

(PECL ibm_db2 >= 1.0.0)

db2_special_columns — Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table

### Description

function db2_special_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$table_name`,
int `$scope`
): resource

Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, passez `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les tables.
`table_name`
  Le nom de la table.
`scope`

  Un entier représentant le temps minimal pour lequel l'identifiant unique de la ligne est valide. Cela peut être une des valeurs suivantes :

  Valeur Entier | Constante SQL | Description
  --- | --- | ---
  0 | SQL_SCOPE_CURROW | L'identifiant de la ligne est valide seulement lorsque le curseur est positionné sur la ligne.
  1 | SQL_SCOPE_TRANSACTION | L'identifiant de la ligne est valide pour la durée de la transaction.
  2 | SQL_SCOPE_SESSION | L'identifiant de la ligne est valide pour la durée de la connexion.

### Valeurs de retour

Retourne une ressource d'instruction avec un jeu de résultats contenant des lignes avec des informations uniques pour une table. Les lignes sont composées des colonnes suivantes :

Nom de la colonne | Description
--- | ---
SCOPE |
Valeur Entier | Constante SQL | Description
--- | --- | ---
0 | SQL_SCOPE_CURROW | L'identifiant de la ligne est valide seulement lorsque le curseur est positionné sur la ligne.
1 | SQL_SCOPE_TRANSACTION | L'identifiant de la ligne est valide pour la durée de la transaction.
2 | SQL_SCOPE_SESSION | L'identifiant de la ligne est valide pour la durée de la connexion.
COLUMN_NAME | Nom de la colonne unique.
DATA_TYPE | Le type de données SQL pour la colonne.
TYPE_NAME | Une chaîne représentant le type de données SQL pour la colonne.
COLUMN_SIZE | Un entier représentant la taille de la colonne.
BUFFER_LENGTH | Nombre maximal d'octets nécessaires pour stocker les données de cette colonne.
DECIMAL_DIGITS | L'échelle de la colonne, ou `null` lorsque l'échelle n'est pas applicable.
NUM_PREC_RADIX | Un entier pouvant être `10` (représentant un type de données numérique exact), `2` (représentant un type de données numérique approximatif) ou `null` (représentant un type de données pour lequel la base n'est pas applicable).
PSEUDO_COLUMN | Retourne toujours 1.

### Voir aussi

- db2_column_privileges() - Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_columns() - Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_foreign_keys() - Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_primary_keys() - Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedure_columns() - Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_procedures() - Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_statistics() - Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_table_privileges() - Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
- db2_tables() - Retourne la liste des tables et leurs métadonnées

# db2_statistics

(PECL ibm_db2 >= 1.0.0)

db2_statistics — Retourne un jeu de résultats listant les index et statistiques d'une table

### Description

function db2_statistics(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`,
bool `$unique`
): resource

Retourne un jeu de résultats listant les index et statistiques d'une table.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, il faut passer `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les tables visées. Si le paramètre est `null`, les statistiques et les index sont retournés pour le schéma de l'utilisateur en cours.
`table_name`
  Le nom de la table.
`unique`
  Quand `unique` est `true`, les informations relatives à tous les index de la table sont renvoyées. Sinon, seules les informations relatives aux index uniques de la table sont renvoyées.

### Valeurs de retour

Retourne une ressource d'instruction avec un jeu de résultats contenant des lignes décrivant les statistiques et les index pour les tables de base correspondant aux paramètres spécifiés. Les lignes sont composées des colonnes suivantes :

Nom de la colonne | Description
--- | ---
TABLE_CAT | Le catalogue qui contient la table. La valeur est `null` si cette table n'a pas de catalogue.
TABLE_SCHEM | Nom du schéma qui contient la table.
TABLE_NAME | Nom de la table.
NON_UNIQUE | Un entier indiquant si l'index interdit les valeurs uniques ou si la ligne représente des statistiques sur la table elle-même :
Valeur de retour | Type de paramètre
--- | ---
0 (SQL_FALSE) | L'index autorise les valeurs dupliquées.
1 (SQL_TRUE) | Les valeurs de l'index doivent être uniques.
`null` | La ligne contient des informations statistiques à propos de la table.
INDEX_QUALIFIER | Une chaîne de caractères représentant le qualificatif qui devrait être préfixé à INDEX_NAME pour qualifier complètement l'index.
INDEX_NAME | Une chaîne représentant le nom de l'index.
TYPE | Un entier représentant le type d'informations contenues dans cette ligne du jeu de résultats :
Valeur de retour | Type de paramètre
--- | ---
0 (SQL_TABLE_STAT) | La ligne contient des informations statistiques à propos de la table.
1 (SQL_INDEX_CLUSTERED) | La ligne contient des informations à propos d'un index groupé.
2 (SQL_INDEX_HASH) | La ligne contient des informations à propos d'un index haché.
3 (SQL_INDEX_OTHER) | La ligne contient des informations à propos d'un type d'index qui n'est ni groupé ni haché.
ORDINAL_POSITION | La position (commençant à 1) de la colonne dans l'index. `null` si la ligne contient des informations statistiques à propos de la table.
COLUMN_NAME | Le nom de la colonne dans l'index. `null` si la ligne contient des informations statistiques à propos de la table.
ASC_OR_DESC | `A` si la colonne est triée en ordre croissant, `D` si la colonne est triée en ordre décroissant, `null` si la ligne contient des informations statistiques à propos de la table.
CARDINALITY | Si la ligne contient des informations à propos d'un index, cette colonne contiendra un entier représentant le nombre de valeurs uniques dans l'index. Si la ligne contient des informations à propos de la table, cette colonne contiendra un entier représentant le nombre de lignes dans la table.
PAGES | Si la ligne contient des informations à propos d'un index, cette colonne contiendra un entier représentant le nombre de pages utilisées pour enregistrer l'index. Si la ligne contient des informations à propos de la table, cette colonne contiendra un entier représentant le nombre de pages utilisées pour enregistrer la table.
FILTER_CONDITION | Retourne toujours `null`.

### Voir aussi

- db2_column_privileges() - Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_columns() - Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_foreign_keys() - Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_primary_keys() - Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedure_columns() - Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_procedures() - Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_special_columns() - Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_table_privileges() - Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
- db2_tables() - Retourne la liste des tables et leurs métadonnées

# db2_stmt_error

(PECL ibm_db2 >= 1.0.0)

db2_stmt_error — Retourne une chaîne contenant la valeur de SQLSTATE retournée par une requête SQL

### Description

function db2_stmt_error(?resource `$stmt` = `null`): string

Retourne une chaîne contenant la valeur de SQLSTATE retournée par une requête SQL.

Si aucune ressource d'instruction n'est passée en argument à la fonction db2_stmt_error(), le pilote retourne la valeur de SQLSTATE associée avec la dernière tentative de retour d'une ressource d'instruction, par exemple, provenant de db2_prepare() ou db2_exec().

Pour comprendre les valeurs de SQLSTATE, il est possible de taper la commande suivante dans le processeur de ligne de commandes de DB2 : `db2 '? `sqlstate-value`'`. Il est aussi possible d'appeler la fonction db2_stmt_errormsg() pour obtenir un message d'erreur explicite ainsi que la valeur de SQLCODE associée.

### Liste de paramètres

`stmt`
  Une ressource d'instruction valide.

### Valeurs de retour

Retourne une chaîne contenant la valeur de SQLSTATE.

### Voir aussi

- db2_conn_error() - Retourne une chaîne contenant la valeur de SQLSTATE retournée par la dernière tentative de connexion
- db2_conn_errormsg() - Retourne le dernier message d'erreur de connexion ainsi que la valeur de SQLCODE
- db2_stmt_errormsg() - Retourne le dernier message d'erreur d'une requête SQL

# db2_stmt_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_stmt_errormsg — Retourne le dernier message d'erreur d'une requête SQL

### Description

function db2_stmt_errormsg(?resource `$stmt` = `null`): string

Retourne le dernier message d'erreur d'une requête SQL.

Si aucune ressource d'instruction n'est passée en argument à db2_stmt_errormsg(), le pilote retourne le message d'erreur associé avec la dernière tentative de retour d'une ressource d'instruction, par exemple, provenant de db2_prepare() ou db2_exec().

### Liste de paramètres

`stmt`
  Une ressource d'instruction valide.

### Valeurs de retour

Retourne une chaîne contenant le message d'erreur et la valeur SQLCODE pour la dernière erreur survenue lors de l'exécution d'une requête SQL.

### Voir aussi

- db2_conn_error() - Retourne une chaîne contenant la valeur de SQLSTATE retournée par la dernière tentative de connexion
- db2_conn_errormsg() - Retourne le dernier message d'erreur de connexion ainsi que la valeur de SQLCODE
- db2_stmt_error() - Retourne une chaîne contenant la valeur de SQLSTATE retournée par une requête SQL

# db2_table_privileges

(PECL ibm_db2 >= 1.0.0)

db2_table_privileges — Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données

### Description

function db2_table_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`
): resource

Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, passer `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les tables. Ce paramètre accepte un motif de recherche contenant `_` et `%` en tant que caractères génériques.
`table_name`
  Le nom de la table. Ce paramètre accepte un motif de recherche contenant `_` et `%` en tant que caractères génériques.

### Valeurs de retour

Retourne une ressource d'instruction avec un jeu de résultats contenant les lignes décrivant les privilèges des tables qui correspondent aux paramètres spécifiés. Les lignes sont composées des colonnes suivantes :

Nom de la colonne | Description
--- | ---
TABLE_CAT | Le catalogue qui contient la table. La valeur est `null` si cette table n'a pas de catalogues.
TABLE_SCHEM | Nom du schéma qui contient la table.
TABLE_NAME | Nom de la table.
GRANTOR | ID d'autorisation de l'utilisateur qui a accordé le privilège.
GRANTEE | ID d'autorisation de l'utilisateur à qui le privilège a été accordé.
PRIVILEGE | Le privilège qui a été accordé. Cela peut être l'un des suivants : ALTER, CONTROL, DELETE, INDEX, INSERT, REFERENCES, SELECT ou UPDATE.
IS_GRANTABLE | Une chaîne valant "YES" ou "NO" indiquant si le bénéficiaire peut accorder le privilège à d'autres utilisateurs.

### Voir aussi

- db2_column_privileges() - Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_columns() - Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_foreign_keys() - Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_primary_keys() - Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedure_columns() - Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_procedures() - Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_special_columns() - Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_statistics() - Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_tables() - Retourne la liste des tables et leurs métadonnées

# db2_tables

(PECL ibm_db2 >= 1.0.0)

db2_tables — Retourne la liste des tables et leurs métadonnées

### Description

function db2_tables(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$table_type` = `null`
): resource

Retourne un jeu de résultats listant les tables et les métadonnées associées dans une base de données.

### Liste de paramètres

`connection`
  Une connexion valide à une base de données IBM DB2, Cloudscape ou Apache Derby.
`qualifier`
  Un qualificatif pour les bases de données DB2 qui fonctionnent sur les serveurs OS/390 ou z/OS. Pour les autres bases de données, passez `null` ou une chaîne vide.
`schema`
  Le schéma qui contient les tables. Ce paramètre accepte un motif de recherche contenant `_` et `%` en tant que caractères génériques.
`table_name`
  Le nom de la table. Ce paramètre accepte un motif de recherche contenant `_` et `%` en tant que caractères génériques.
`table_type`
  Une liste d'identifiants de type de table délimitée par des virgules. Pour correspondre à tous les types de tables, passez `null` ou une chaîne vide. Les identifiants de type de table valides incluent : ALIAS, HIERARCHY TABLE, INOPERATIVE VIEW, NICKNAME, MATERIALIZED QUERY TABLE, SYSTEM TABLE, TABLE, TYPED TABLE, TYPED VIEW et VIEW.

### Valeurs de retour

Retourne une ressource d'instruction avec un jeu de résultats contenant les lignes décrivant les tables qui correspondent aux paramètres spécifiés. Les lignes sont composées des colonnes suivantes :

Nom de la colonne | Description
--- | ---
TABLE_CAT | Le catalogue qui contient la table. La valeur est `null` si cette table n'a pas de catalogues.
TABLE_SCHEM | Nom du schéma qui contient la table.
TABLE_NAME | Nom de la table.
TABLE_TYPE | Identifiant de type de table pour la table.
REMARKS | Description de la table.

### Voir aussi

- db2_column_privileges() - Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_columns() - Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_foreign_keys() - Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_primary_keys() - Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedure_columns() - Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_procedures() - Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_special_columns() - Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_statistics() - Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_table_privileges() - Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données

## Sommaire

- db2_autocommit — Retourne ou modifie l'état AUTOCOMMIT de la connexion à la base de données
- db2_bind_param — Associe une variable PHP à un paramètre d'une requête SQL
- db2_client_info — Retourne un objet avec des propriétés qui décrivent le client de base de données DB2
- db2_close — Ferme une connexion de base de données
- db2_column_privileges — Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
- db2_columns — Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
- db2_commit — Valide la transaction
- db2_conn_error — Retourne une chaîne contenant la valeur de SQLSTATE retournée par la dernière tentative de connexion
- db2_conn_errormsg — Retourne le dernier message d'erreur de connexion ainsi que la valeur de SQLCODE
- db2_connect — Retourne une connexion à une base de données
- db2_cursor_type — Retourne le type de curseur utilisé par une ressource d'instruction
- db2_escape_string — Utilisé pour échapper certains caractères
- db2_exec — Exécute une requête SQL directement
- db2_execute — Exécute une requête SQL préparée
- db2_fetch_array — Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats
- db2_fetch_assoc — Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats
- db2_fetch_both — Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats
- db2_fetch_object — Retourne un objet avec les propriétés représentant des colonnes dans la ligne extraite
- db2_fetch_row — Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée
- db2_field_display_size — Retourne le maximum d'octets requis pour afficher une colonne
- db2_field_name — Retourne le nom de la colonne du jeu de résultats
- db2_field_num — Retourne la position de la colonne nommée dans un jeu de résultats
- db2_field_precision — Retourne la précision de la colonne indiquée du jeu de résultats
- db2_field_scale — Retourne l'échelle de la colonne indiquée du jeu de résultats
- db2_field_type — Retourne le type de données de la colonne indiquée du jeu de résultats
- db2_field_width — Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats
- db2_foreign_keys — Retourne un jeu de résultats listant les clés étrangères d'une table
- db2_free_result — Libère la mémoire associée à un jeu de résultats
- db2_free_stmt — Libère les ressources associées à la ressource d'instruction indiquée
- db2_get_option — Récupère la valeur d'une option pour une ressource d'instruction ou une ressource de connexion
- db2_last_insert_id — Retourne le dernier ID généré par la dernière requête d'insertion
- db2_lob_read — Récupère une taille définie par l'utilisateur de fichiers LOB à chaque invocation
- db2_next_result — Demande le prochain jeu de résultats d'une procédure stockée
- db2_num_fields — Retourne le nombre de champs contenus dans un jeu de résultats
- db2_num_rows — Retourne le nombre de lignes affectées par une requête SQL
- db2_pclose — Ferme une connexion persistante à la base de données
- db2_pconnect — Retourne une connexion persistante à une base de données
- db2_prepare — Prépare une requête SQL à être exécutée
- db2_primary_keys — Retourne un jeu de résultats listant les clés primaires d'une table
- db2_procedure_columns — Retourne un jeu de résultats listant les paramètres de procédure stockée
- db2_procedures — Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
- db2_result — Retourne une colonne d'une ligne d'un jeu de résultats
- db2_rollback — Annule une transaction
- db2_server_info — Retourne un objet avec des propriétés qui décrivent le serveur de base de données DB2
- db2_set_option — Fixe des options pour une ressource de connexion ou une ressource d'instruction
- db2_special_columns — Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
- db2_statistics — Retourne un jeu de résultats listant les index et statistiques d'une table
- db2_stmt_error — Retourne une chaîne contenant la valeur de SQLSTATE retournée par une requête SQL
- db2_stmt_errormsg — Retourne le dernier message d'erreur d'une requête SQL
- db2_table_privileges — Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
- db2_tables — Retourne la liste des tables et leurs métadonnées

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Fonctions IBM DB2
  - db2_autocommit — Retourne ou modifie l'état AUTOCOMMIT de la connexion à la base de données
  - db2_bind_param — Associe une variable PHP à un paramètre d'une requête SQL
  - db2_client_info — Retourne un objet avec des propriétés qui décrivent le client de base de données DB2
  - db2_close — Ferme une connexion de base de données
  - db2_column_privileges — Retourne un jeu de résultats listant les colonnes et leurs privilèges d'une table
  - db2_columns — Retourne un jeu de résultats listant les colonnes et leurs métadonnées d'une table
  - db2_commit — Valide la transaction
  - db2_conn_error — Retourne une chaîne contenant la valeur de SQLSTATE retournée par la dernière tentative de connexion
  - db2_conn_errormsg — Retourne le dernier message d'erreur de connexion ainsi que la valeur de SQLCODE
  - db2_connect — Retourne une connexion à une base de données
  - db2_cursor_type — Retourne le type de curseur utilisé par une ressource d'instruction
  - db2_escape_string — Utilisé pour échapper certains caractères
  - db2_exec — Exécute une requête SQL directement
  - db2_execute — Exécute une requête SQL préparée
  - db2_fetch_array — Retourne un tableau, indexé par la position des colonnes, représentant une ligne du jeu de résultats
  - db2_fetch_assoc — Retourne un tableau, indexé par nom de colonne, représentant une ligne du jeu de résultats
  - db2_fetch_both — Retourne un tableau, indexé par nom de colonne et position, représentant une ligne du jeu de résultats
  - db2_fetch_object — Retourne un objet avec les propriétés représentant des colonnes dans la ligne extraite
  - db2_fetch_row — Modifie le pointeur du jeu de résultats à la prochaine ligne ou à la ligne demandée
  - db2_field_display_size — Retourne le maximum d'octets requis pour afficher une colonne
  - db2_field_name — Retourne le nom de la colonne du jeu de résultats
  - db2_field_num — Retourne la position de la colonne nommée dans un jeu de résultats
  - db2_field_precision — Retourne la précision de la colonne indiquée du jeu de résultats
  - db2_field_scale — Retourne l'échelle de la colonne indiquée du jeu de résultats
  - db2_field_type — Retourne le type de données de la colonne indiquée du jeu de résultats
  - db2_field_width — Retourne la largeur de la valeur courante de la colonne indiquée du jeu de résultats
  - db2_foreign_keys — Retourne un jeu de résultats listant les clés étrangères d'une table
  - db2_free_result — Libère la mémoire associée à un jeu de résultats
  - db2_free_stmt — Libère les ressources associées à la ressource d'instruction indiquée
  - db2_get_option — Récupère la valeur d'une option pour une ressource d'instruction ou une ressource de connexion
  - db2_last_insert_id — Retourne le dernier ID généré par la dernière requête d'insertion
  - db2_lob_read — Récupère une taille définie par l'utilisateur de fichiers LOB à chaque invocation
  - db2_next_result — Demande le prochain jeu de résultats d'une procédure stockée
  - db2_num_fields — Retourne le nombre de champs contenus dans un jeu de résultats
  - db2_num_rows — Retourne le nombre de lignes affectées par une requête SQL
  - db2_pclose — Ferme une connexion persistante à la base de données
  - db2_pconnect — Retourne une connexion persistante à une base de données
  - db2_prepare — Prépare une requête SQL à être exécutée
  - db2_primary_keys — Retourne un jeu de résultats listant les clés primaires d'une table
  - db2_procedure_columns — Retourne un jeu de résultats listant les paramètres de procédure stockée
  - db2_procedures — Retourne un jeu de résultats listant les procédures stockées enregistrées dans une base de données
  - db2_result — Retourne une colonne d'une ligne d'un jeu de résultats
  - db2_rollback — Annule une transaction
  - db2_server_info — Retourne un objet avec des propriétés qui décrivent le serveur de base de données DB2
  - db2_set_option — Fixe des options pour une ressource de connexion ou une ressource d'instruction
  - db2_special_columns — Retourne un jeu de résultats listant les identifiants uniques des lignes d'une table
  - db2_statistics — Retourne un jeu de résultats listant les index et statistiques d'une table
  - db2_stmt_error — Retourne une chaîne contenant la valeur de SQLSTATE retournée par une requête SQL
  - db2_stmt_errormsg — Retourne le dernier message d'erreur d'une requête SQL
  - db2_table_privileges — Retourne un jeu de résultats listant les tables et les privilèges qui leur sont associés dans une base de données
  - db2_tables — Retourne la liste des tables et leurs métadonnées

# L'extension MongoDB

Cette extension est développée au-dessus des bibliothèques » libmongoc et » libbson. Elle fournit une API minimale pour les fonctionnalités de base du pilote : commandes, requêtes, écritures, gestion de connexion, et sérialisation BSON.

Les bibliothèques PHP côté utilisateur qui dépendent de cette extension peuvent fournir des API de plus haut niveau, telles que des constructeurs de requêtes, des méthodes d'aide pour les commandes individuelles, et GridFS. Les développeurs d'applications devraient envisager d'utiliser cette extension en conjonction avec la » bibliothèque MongoDB PHP, qui implémente les mêmes API de plus haut niveau que l'on trouve dans les pilotes MongoDB pour d'autres langages. Cette séparation des préoccupations permet à l'extension de se concentrer sur les fonctionnalités essentielles pour lesquelles une implémentation d'extension est primordiale pour les performances.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

Depuis la version 1.21.0, l'extension nécessite PHP 8.1 ou supérieur. Les versions précédentes de l'extension permettent la compatibilité avec les anciennes versions de PHP.

L'extension nécessite » libbson et » libmongoc, et utilisera les versions incluses par défaut. Les bibliothèques système peuvent également être utilisées, comme discuté dans la documentation d'installation manuelle.

L'extension, via libmongoc, dépend optionnellement d'une bibliothèque TLS (par exemple OpenSSL) et l'utilisera si elle est disponible. Si le processus de construction ne parvient pas à trouver une bibliothèque TLS, les utilisateurs doivent vérifier que le paquet de développement approprié (par exemple `libssl-dev`) et » pkg-config sont tous deux installés. Le processus de détection et de configuration des bibliothèques TLS est discuté plus en détail dans la documentation d'installation manuelle.

» Cyrus SASL est une dépendance optionnelle pour prendre en charge l'authentification Kerberos et sera utilisée si elle est disponible.

> Note: À cause de problèmes potentiels de représentation des entiers 64 bits sur des plateformes 32 bits, il est conseillé aux utilisateurs d'utiliser des environnements 64 bits. Lors de l'utilisation d'une plateforme 32 bits, il faut être conscient que tout entier 64 bits lu depuis la base de données sera retourné sous la forme d'une instance MongoDB\BSON\Int64 au lieu d'un type entier PHP.

## Installation

## Installer l'extension de MongoDB PHP avec PIE

> Note: L'installeur d'Extensions pour PHP (PHP Installer for Extensions - PIE) est un nouvel outil qui remplacera PECL. Nous recommandons d'utiliser PIE pour installer les extensions. Plus d'informations sur » https://github.com/php/pie

Pour installer l'extension MongoDB avec PIE, exécutez la commande suivante :

    pie install mongodb/mongodb-extension

## Installer l'extension de MongoDB PHP avec PECL

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/mongodb

Linux, Unix et les utilisateurs de macOS peuvent exécuter la commande suivante pour installer l'extension :

    $ sudo pecl install mongodb

Sur les systèmes avec plusieurs versions de PHP installées (par exemple, macOS par défaut, Homebrew, » XAMPP), chaque version de PHP aura sa propre commande pecl et fichier php.ini. De plus, chaque environnement PHP (par exemple CLI, web) peut utiliser des fichiers php.ini séparés.

Depuis la version 1.17.0 de l'extension, PECL demandera diverses options de `configure`. Pour installer l'extension avec les options par défaut dans un script non interactif, une entrée vide peut être envoyée à `pecl install` en utilisant la commande `yes` :

    $ yes '' | sudo pecl install mongodb

Une liste complète des options `configure` supportées peut être trouvée dans le fichier `package.xml` inclus dans le paquet PECL. Pour installer l'extension avec des options de `configure` spécifiques dans un script non interactif, l'option `--configureoptions` pour `pecl install` peut être utilisée :

    $ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb

Par défaut l'installation de l'extension via PECL utilisera les versions incluses de » libbson, » libmongoc, et » libmongocrypt et essayera automatiquement de configurer.

> Note: Si le processus de construction échoue à trouver une bibliothèque SSL, vérifiez que les paquets de développement (par exemple `libssl-dev`) et » pkg-config sont tous deux installés. Si cela ne résout pas le problème, envisagez d'utiliser le processus d'installation manuel.

Pour finir, ajoutez la ligne suivante au fichier php.ini pour chaque environnement qui aura besoin d'utiliser l'extension :

    extension=mongodb.so

## Installer l'extension de MongoDB PHP sur macOS avec Homebrew

» Homebrew 1.5.0 a déprécié le » tap Homebrew/php et a supprimé les formules pour les extensions PHP individuelles. À l'avenir, les utilisateurs de macOS sont invités à installer la formule » php et à suivre les instructions d'installation standard de PECL en utilisant la commande pecl fournie par l'installation PHP Homebrew.

Sinon, le » tap shivammathur/extensions fourni des formules pour les extensions PHP individuelles. Par exemple, pour installer l'extension pour PHP 8.4, exécutez :

    $ brew install shivammathur/extensions/mongodb@8.4

Il est à noter que seule la dernière version de l'extension est disponible dans brew.

> Note: Installer les dépendances requises
> Pour garantir que le support SSL peut être configuré correctement, il faut s'assurer que les formules `openssl` et `pkgconf` sont installées. Si l'un de ces paquets est manquant, l'extension sera compilée avec Secure Transport, ce qui peut entraîner des problèmes de compatibilité.

## Installer l'extension de MongoDB PHP sur Windows

Les binaires précompilés sont attachés aux » versions Github du projet. Les archives sont publiées pour diverses combinaisons de version PHP, de sécurité des threads (TS ou NTS) et d'architecture (x86 ou x64). Déterminez l'archive correcte pour l'environnement PHP et extrayez le fichier php_mongodb.dll dans le répertoire d'extension ("ext" par défaut).

Ajouter la ligne suivante au fichier php.ini pour chaque environnement qui aura besoin d'utiliser l'extension :

    extension=php_mongodb.dll

L'échec de sélection du binaire correct entraînera une erreur lors de la tentative de chargement de l'extension DLL à l'exécution :

    PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

Il faut s'assurer que la DLL téléchargée correspond aux propriétés d'exécution PHP suivantes :

- Version de PHP(`PHP_VERSION`)
- Sécurité des threads (`PHP_ZTS`)
- Architecture (`PHP_INT_SIZE`)

En plus des constantes mentionnées ci-dessus, ces propriétés peuvent également être déduites de phpinfo(). Si un système a plusieurs exécutions PHP installées, vérifiez que la sortie de phpinfo() est pour l'environnement correct.

> Note: Dépendances additionnelles DLL pour les utilisateurs Windows
> Afin de faire fonctionner cette extension, quelques bibliothèques DLL doivent être disponibles via le PATH du système Windows. Lisez la F.A.Q intitulée "Comment ajouter mon dossier PHP à mon PATH Windows" pour plus d'informations. Le fait de copier les bibliothèques DLL depuis le dossier PHP dans le dossier système Windows fonctionne également (car le dossier système est par défaut dans le PATH système), mais cette méthode n'est pas recommandée. Cette extension nécessite que les fichiers suivants se trouvent dans le PATH : libsasl.dll

## Installation manuelle de l'extension de MongoDB PHP

Pour les développeurs et les utilisateurs intéressés par les dernières corrections de bogues, l'extension peut être compilée à partir du dernier code source sur » Github. Exécuter les commandes suivantes pour cloner et construire le projet :

    $ git clone https://github.com/mongodb/mongo-php-driver.git
    $ cd mongo-php-driver
    $ git submodule update --init
    $ phpize
    $ ./configure
    $ make all
    $ sudo make install

Sur les systèmes avec plusieurs versions de PHP installées (par exemple, macOS par défaut, Homebrew, » XAMPP), chaque version de PHP aura sa propre commande phpize et fichier php.ini. De plus, chaque environnement PHP (par exemple CLI, web) peut utiliser des fichiers php.ini séparés.

Par défaut, l'extension utilisera les versions incluses de » libbson, » libmongoc, et » libmongocrypt et essayera de configurer automatiquement. Si ces bibliothèques sont déjà installées en tant que bibliothèques système, l'extension peut les utiliser en spécifiant `--with-mongodb-system-libs=yes` comme option à `configure`.

Pour une liste complète des options `configure`, exécutez configure --help.

Lorsqu'on utilise les versions groupées de libmongoc et libmongocrypt, l'extension tentera également de sélectionner une bibliothèque SSL selon l'option `configure` `--with-mongodb-ssl`. À partir de la version 1.17.0 de l'extension, OpenSSL est toujours préféré par défaut. Auparavant, Secure Transport était le défaut sur macOS et OpenSSL était le défaut sur toutes les autres plates-formes.

> Note: Si le processus de construction échoue à trouver une bibliothèque SSL, vérifiez que les paquets de développement (par exemple `libssl-dev`) et » pkg-config sont tous deux installés. Lorsqu'on utilise Homebrew sur macOS, il est courant qu'un système ait plusieurs versions d'OpenSSL installées. Pour garantir que la version d'OpenSSL souhaitée est sélectionnée, la variable d'environnement `PKG_CONFIG_PATH` peut être utilisée pour contrôler le chemin de recherche de `pkg-config`.

La dernière étape de construction, make install, indiquera où mongodb.so a été installé, similaire à :

    Installing shared extensions:     /usr/lib/php/extensions/debug-non-zts-20220829/

Il faut s'assurer que l'option extension_dir dans php.ini pointe vers le répertoire où mongodb.so a été installé. L'option peut être interrogée en exécutant :

    $ php -i | grep extension_dir
      extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
                       /usr/lib/php/extensions/debug-non-zts-20220829

Si les répertoires diffèrent, modifiez extension_dir dans php.ini ou déplacez manuellement mongodb.so dans le répertoire correct.

Pour finir, ajoutez la ligne suivante au fichier php.ini pour chaque environnement qui aura besoin d'utiliser l'extension :

    extension=mongodb.so

## Configuration à l'exécution

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

Options de configuration de mongodb
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
mongodb.debug | "" | `INI_ALL` |

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

`mongodb.debug` string
  Cette option peut être utilisée pour activer ou désactiver le journal de débogage de niveau trace dans l'extension (et libmongoc). Spécifier une chaîne vide, `"0"`, `"off"`, `"no"`, ou `"false"` pour désactiver le journal. Spécifier `"stderr"` ou `"stdout"` pour journaliser vers `stderr` ou `stdout`, respectivement. Spécifier `"1"`, `"on"`, `"yes"`, ou `"true"` pour journaliser dans un nouveau fichier temporaire dans le répertoire temporaire système par défaut (c'est-à-dire sys_get_temp_dir()). Spécifier une autre chaîne pour journaliser dans un nouveau fichier temporaire dans ce répertoire. Si le répertoire ne peut pas être utilisé, le répertoire temporaire système par défaut sera utilisé à la place.

  > Note: Il est à noter que le journal de débogage peut contenir des informations sensibles, telles que les informations d'identification du serveur MongoDB et les documents complets écrits ou lus à partir du serveur. Il est recommandé de vérifier tout journal de débogage avant de le partager avec d'autres personnes.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`MONGODB_VERSION` (string)
  Numéro de version de l'extension au format x.y.z
`MONGODB_STABILITY` (string)
  Stabilité actuelle (alpha/beta/stable)

# Tutoriels

## Sommaire

- Utiliser la bibliothèque PHP pour MongoDB (PHPLIB)
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

Dans cette section, on trouvera plusieurs tutoriels sur l'utilisation du pilote MongoDB pour PHP.

## Utiliser la bibliothèque PHP pour MongoDB (PHPLIB)

Après la configuration initiale de l'extension, nous allons continuer à expliquer comment démarrer avec la bibliothèque utilisateur correspondante pour écrire notre premier projet.

## Installer la bibliothèque PHP avec Composer

La dernière chose que nous devons installer pour commencer l'application elle-même est la bibliothèque PHP.

La bibliothèque doit être installée avec » Composer, un gestionnaire de paquets pour PHP. Les instructions pour installer Composer sur différentes plateformes peuvent être trouvées sur son site web.

Installer la bibliothèque en exécutant:

    $ composer require mongodb/mongodb

Cela produira une sortie similaire à:

    ./composer.json has been created
    Loading composer repositories with package information
    Updating dependencies (including require-dev)
      - Installing mongodb/mongodb (1.0.0)
        Downloading: 100%

    Writing lock file
    Generating autoload files

Composer va créer plusieurs fichiers: `composer.json`, `composer.lock`, et un répertoire `vendor` qui contiendra la bibliothèque et toutes les autres dépendances que le projet pourrait nécessiter.

## Utiliser la bibliothèque PHP

En plus de gérer les dépendances, Composer fournira également un autochargement (pour les classes de ces dépendances). Il faut s'assurer qu'il est inclus au début du script ou dans le code d'amorçage de l'application :

    <?php
    // Ce chemin doit pointer vers l'autochargeur de Composer
    require 'vendor/autoload.php';

Avec cela fait, il est maintenant possible d'utiliser n'importe quelle fonctionnalité comme décrit dans la » documentation de la bibliothèque.

Si on a utilisé des pilotes MongoDB dans d'autres langages, l'API de la bibliothèque devrait sembler familière. Elle contient une classe » Client pour se connecter à MongoDB, une classe » Database pour les opérations au niveau de la base de données (par exemple, les commandes, la gestion des collections), et une classe » Collection pour les opérations au niveau de la collection (par exemple, les méthodes » CRUD, la gestion des index).

En tant qu'exemple, voici comment on insère un document dans la collection beers de la base de données demo:

    <?php
    require 'vendor/autoload.php'; // inclure l'autochargeur de Composer

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

    echo "Inserted with Object ID '{$result->getInsertedId()}'";
    ?>

Comme le document inséré ne contenait pas de champ `_id`, l'extension va générer un MongoDB\BSON\ObjectId pour que le serveur l'utilise comme `_id`. Cette valeur est également disponible pour l'appelant via l'objet de résultat retourné par la méthode `insertOne`.

Après l'insertion, il est possible d'interroger les données qu'on vient d'insérer. Pour cela, on utilise la méthode `find`, qui retourne un curseur itérable:

    <?php
    require 'vendor/autoload.php'; // inclure l'autochargeur de Composer

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

    foreach ($result as $entry) {
        echo $entry['_id'], ': ', $entry['name'], "\n";
    }
    ?>

Tandis que les exemples ne le montrent pas, les documents BSON et les tableaux sont désérialisés en tant que classes spéciales dans la bibliothèque par défaut. Ces classes étendent ArrayObject pour la facilité d'utilisation et implémentent les interfaces MongoDB\BSON\Serializable et MongoDB\BSON\Unserializable de l'extension pour garantir que les valeurs conservent leur type lorsqu'elles sont sérialisées de nouveau en BSON. Cela évite un inconvénient de l'ancienne extension `mongo` où les tableaux pourraient se transformer en documents, et vice versa. Voir la spécification Persister des données pour plus d'informations sur la façon dont les valeurs sont converties entre PHP et BSON.

## Surveillance de la performance de l'application (Application Performance Monitoring - APM)

L'extension contient une API d'observations événements, qui permet aux applications de surveiller les commandes et les activités internes liées à la » Spécification de découverte et de surveillance du serveur. Ce tutoriel démontrera la surveillance des commandes en utilisant l'interface MongoDB\Driver\Monitoring\CommandSubscriber.

L'interface MongoDB\Driver\Monitoring\CommandSubscriber définit trois méthodes: `commandStarted`, `commandSucceeded`, et `commandFailed`. Chacune de ces trois méthodes accepte un seul argument `event` d'une classe spécifique pour l'événement respectif. Par exemple, l'argument `$event` de `commandSucceeded` est un objet MongoDB\Driver\Monitoring\CommandSucceededEvent.

Dans ce tutoriel, nous allons implémenter un observateur qui crée une liste de tous les profils de requête et le temps moyen qu'ils ont pris.

## Structure des classes d'observations

Nous commençons par le cadre de notre observateur:

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
        {
        }

        public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
        {
        }

        public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
        {
        }
    }

    ?>

## Enregistrement de l'observateur

Une fois qu'un objet observateur est instancié, il doit être enregistré avec le système de surveillance de l'extension. Cela se fait en appelant MongoDB\Driver\Monitoring\addSubscriber() ou MongoDB\Driver\Manager::addSubscriber() pour enregistrer l'observateur globalement ou avec un Manager spécifique, respectivement.

    <?php

    \MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

    ?>

## Implémenter la logique

Avec l'objet enregistré, la seule chose qui reste est d'implémenter la logique dans la classe observatrice. Pour corréler les deux événements qui composent une commande exécutée avec succès (commandStarted et commandSucceeded), chaque objet d'événement expose un champ `requestId`.

Pour enregistrer le temps moyen par forme de requête, nous allons commencer par vérifier une commande `find` dans l'événement commandStarted. Nous allons ensuite ajouter un élément à la propriété `pendingCommands` indexé par son `requestId` et avec sa valeur représentant la forme de requête.

Si nous recevons un événement commandSucceeded correspondant avec le même `requestId`, nous ajoutons la durée de l'événement (depuis `durationMicros`) au temps total et incrémentons le compteur d'opérations.

Si un événement commandFailed correspondant est rencontré, nous supprimons simplement l'entrée de la propriété `pendingCommands`.

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        private $pendingCommands = [];
        private $queryShapeStats = [];

        /* Créer une forme de requête à partir de l'argument de filtre. Pour l'instant, il ne prend en compte que
         * les champs de premier niveau */
        private function createQueryShape( array $filter )
        {
            return json_encode( array_keys( $filter ) );
        }

        public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
        {
            if ( 'find' === $event->getCommandName() )
            {
                $queryShape = $this->createQueryShape( (array) $event->getCommand()->filter );
                $this->pendingCommands[$event->getRequestId()] = $queryShape;
            }
        }

        public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
        {
            $requestId = $event->getRequestId();
            if ( array_key_exists( $requestId, $this->pendingCommands ) )
            {
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['count']++;
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['duration'] += $event->getDurationMicros();
                unset( $this->pendingCommands[$requestId] );
            }
        }

        public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
        {
            if ( array_key_exists( $event->getRequestId(), $this->pendingCommands ) )
            {
                unset( $this->pendingCommands[$event->getRequestId()] );
            }
        }

        public function __destruct()
        {
            foreach( $this->queryShapeStats as $shape => $stats )
            {
                echo "Shape: ", $shape, " (", $stats['count'], ")\n  ",
                    $stats['duration'] / $stats['count'], "µs\n\n";
            }
        }
    }

    $m = new \MongoDB\Driver\Manager( 'mongodb://localhost:27016' );

    /* Ajouter l'observateur */
    \MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

    /* Faire une série de requêtes */
    $query = new \MongoDB\Driver\Query( [
        'region_slug' => 'scotland-highlands', 'age' => [ '$gte' => 20 ]
    ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    $query = new \MongoDB\Driver\Query( [
        'region_slug' => 'scotland-lowlands', 'age' => [ '$gte' => 15 ]
    ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    $query = new \MongoDB\Driver\Query( [ 'region_slug' => 'scotland-lowlands' ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    ?>

# Explications de l'architecture du pilote et des fonctionnalités spéciales

## Sommaire

- Architecture
- Connections
- Persister des données

## Aperçu de l'architecture

Cet article explique comment tous les différents composants du pilote PHP s'emboîtent, des bibliothèques système de base, à l'extension, et aux bibliothèques PHP en haut.

En haut de cette pile se trouve une » bibliothèque PHP, qui distribue un » package Composer. Cette bibliothèque fournit une API cohérente avec d'autres » drivers MongoDB et implémente diverses » spécifications croisées. Bien que l'extension puisse être utilisée directement, la bibliothèque a un surcoût minimal et devrait être une dépendance commune pour la plupart des applications construites avec MongoDB.

En dessous de cette bibliothèque se trouve une extension PHP, qui est distribuée via » PECL. L'extension forme la colle entre PHP et nos bibliothèques système (» libmongoc, » libbson, et » libmongocrypt). Son API publique fournit uniquement les fonctionnalités les plus essentielles :

- Gestion de connexions
- Encodage et décodage BSON
- Sérialisation et désérialisation de documents (support des bibliothèques ODM)
- Exécution de commandes, requêtes, et opérations d'écriture
- Gestion des curseurs pour les résultats de commandes et de requêtes

Code source du pilote et projets JIRA
Project | GitHub | JIRA
--- | --- | ---
Bibliothèques PHP | » mongodb/mongo-php-library | » PHPLIB
Extensions PHP | » mongodb/mongo-php-driver | » PHPC

## Gestion de la connexion et de la persistance

> Note: Sur les plate-formes Unix, l'extension MongoDB est sensible aux scripts qui utilisent l'appel système fork() sans pour autant appeler exec(). Vous ne devez pas ré-utliser des instances MongoDB\Driver\Manager dans une processus fils issue d'un fork.

## Connexions et topologie persistante (version PHP depuis 1.2.0)

Toutes les versions de l'extension depuis 1.2.0 conservent l'objet client » libmongoc dans le processus PHP, ce qui lui permet de réutiliser les connexions de base de données, les états d'authentification, et les informations de topologie à travers plusieurs requêtes.

Lorsque MongoDB\Driver\Manager::__construct() est invoqué, un hachage est créé à partir de ses arguments (c'est-à-dire la chaîne URI et le tableau d'options). L'extension tentera de trouver un objet client » libmongoc persisté précédemment pour ce hachage. Si un client existant ne peut pas être trouvé pour le hachage, un nouveau client sera créé et persisté pour une utilisation future. Ce comportement peut être désactivé via l'option du pilote `"disableClientPersistence"`.

Chaque client contient ses propres connexions de base de données et une vue de la topologie du serveur (par exemple, autonome, ensemble de réplicas, grappe de fragments). En persistant le client entre les requêtes PHP, l'extension est capable de réutiliser les connexions de base de données établies et d'éliminer le besoin de » découvrir la topologie du serveur à chaque requête.

Considérez l'exemple suivant :

    <?php

    $managers = [
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017'),
        new MongoDB\Driver\Manager('mongodb://rs1.example.com,rs2.example.com/', ['replicaSet' => 'myReplicaSet']),
    ];

    foreach ($managers as $manager) {
        $manager->executeCommand('test', new MongoDB\Driver\Command(['ping' => 1]));
    }

    ?>

Les deux premiers objets Manager partageront le même client » libmongoc car leurs arguments de constructeur sont identiques. Les troisième et quatrième objets utiliseront chacun leur propre client. Au total, trois clients seront créés et le processus PHP exécutant ce script ouvrira deux connexions à `127.0.0.1` et une connexion à chacun de `rs1.example.com` et `rs2.example.com`. Si l'extension découvre des membres supplémentaires de l'ensemble de réplicas après avoir émis des commandes `hello`, elle ouvrira des connexions supplémentaires à ces serveurs également.

Si les mêmes connexions sont réutilisées par le même processus PHP, les trois clients seront réutilisés et aucune nouvelle connexion ne sera établie. En fonction de la durée écoulée depuis la dernière requête servie, l'extension peut avoir besoin d'émettre des commandes `hello` supplémentaires pour mettre à jour sa vue des topologies.

## Persistance des sockets (versions PHP avant 1.2.0)

Les versions de l'extension avant 1.2.0 utilisent l'API des flux PHP pour les connexions de base de données, utilisant une API dans » libmongoc pour désigner des gestionnaires personnalisés pour la communication par socket ; cependant, un nouveau client libmongoc est créé pour chaque MongoDB\Driver\Manager. En conséquence, l'extension persiste les connexions de base de données individuelles mais pas l'état d'authentification ou les informations de topologie. Cela signifie que l'extension doit émettre des commandes au début de chaque requête pour s'authentifier et » découvrir la topologie du serveur.

Les connexions de base de données sont persistées par un hachage dérivé de l'hôte du serveur, du port et de la chaîne URI utilisée pour construire le MongoDB\Driver\Manager. Les options du tableau du constructeur ne sont pas incluses dans ce hachage.

> Note: Les versions de l'extension >= 1.1.8 et < 1.2.0 ne persistent pas les sockets pour les connexions SSL. Voir » PHPC-720 pour plus d'informations.

Malgré ses lacunes avec les connexions SSL persistantes et les informations de topologie, cette version de l'extension supporte toutes les options de contexte SSL puisqu'elle utilise l'API des flux PHP.

## Sérialisation et désérialisation des variables PHP dans MongoDB

Ce document explique comment les structures composées (c'est-à-dire les documents, les tableaux et les objets) sont converties entre les valeurs BSON et PHP.

## Sérialisation en BSON

## Tableaux

Si un tableau est un tableau compact — c'est-à-dire un tableau vide ou les clés commencent à 0 et sont séquentielles sans trous : tableau BSON.

Si le tableau n'est pas compact — c'est-à-dire qu'il a des clés associatives (chaînes), que les clés ne commencent pas à 0, ou qu'il y a des trous : objet BSON.

Un document de niveau supérieur (racine), toujours sérialisé en tant que document BSON.

## Exemples

Ces exemples sérialisent en tant que tableau BSON :

    [ 8, 5, 2, 3 ] => [ 8, 5, 2, 3 ]
    [ 0 => 4, 1 => 9 ] => [ 4, 9 ]

Ces exemples sérialisent en tant qu'objet BSON :

    [ 0 => 1, 2 => 8, 3 => 12 ] => { "0" : 1, "2" : 8, "3" : 12 }
    [ "foo" => 42 ] => { "foo" : 42 }
    [ 1 => 9, 0 => 10 ] => { "1" : 9, "0" : 10 }

Il est à noter que les cinq exemples sont des extraits d'un document complet, et ne représentent qu'une valeur à l'intérieur d'un document.

## Objets

Si un objet est de la classe stdClass, sérialiser en tant que document BSON.

Si un objet est une classe supportée qui implémente MongoDB\BSON\Type, alors utiliser la logique de sérialisation BSON pour ce type spécifique. Les instances de MongoDB\BSON\Type (à l'exclusion de MongoDB\BSON\Serializable) ne peuvent être sérialisées que comme valeur de champ de document. Tenter de sérialiser un tel objet en tant que document racine lèvera une MongoDB\Driver\Exception\UnexpectedValueException.

Si un objet est d'une classe inconnue implémentant l'interface MongoDB\BSON\Type, alors une MongoDB\Driver\Exception\UnexpectedValueException est lancée.

Si un objet est d'une classe autre, sans implémenter une interface spéciale, sérialiser en tant que document BSON. Garder seulement les propriétés public, et ignorer les propriétés protected et private.

Si un objet est d'une classe qui implémente MongoDB\BSON\Serializable, appeler MongoDB\BSON\Serializable::bsonSerialize() et utiliser le tableau ou stdClass retourné pour sérialiser en tant que document BSON ou tableau. Le type BSON sera déterminé par les règles suivantes :

1. Les documents racines doivent être sérialisés en tant que document BSON.
2. Les objets MongoDB\BSON\Persistable doivent être sérialisés en tant que document BSON.
3. Si MongoDB\BSON\Serializable::bsonSerialize() retourne un tableau compact, sérialiser en tant que tableau BSON.
4. Si MongoDB\BSON\Serializable::bsonSerialize() retourne un tableau non-compact ou stdClass, sérialiser en tant qu'objet BSON.
5. Si MongoDB\BSON\Serializable::bsonSerialize() ne retourne pas un tableau ou stdClass, lance une exception MongoDB\Driver\Exception\UnexpectedValueException.

Si un objet est d'une classe qui implémente l'interface MongoDB\BSON\Persistable (qui implique MongoDB\BSON\Serializable), obtenir les propriétés de manière similaire aux paragraphes précédents, mais aussi ajouter une propriété __pclass en tant que valeur binaire, avec un sous-type `0x80` et des données portant le nom de la classe entièrement qualifié de l'objet qui est sérialisé.

La propriété __pclass est ajoutée au tableau ou à l'objet retourné par MongoDB\BSON\Serializable::bsonSerialize(), ce qui signifie qu'elle écrasera toute clé/propriété __pclass dans la valeur de retour de MongoDB\BSON\Serializable::bsonSerialize(). Si l'on veut éviter ce comportement et définir sa propre valeur __pclass, il ne faut pas implémenter MongoDB\BSON\Persistable et devriez plutôt implémenter MongoDB\BSON\Serializable directement.

## Exemples

    <?php

    class stdClass
    {
        public $foo = 42;
    } // => {"foo": 42}

    class MyClass
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';
    } // => {"foo": 42}

    class AnotherClass1 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "wine"}

    class AnotherClass2 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;

        public function bsonSerialize(): self
        {
            return $this;
        }
    } // => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not return an array or stdClass")

    class AnotherClass3 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    /**
     * Nesting Serializable classes
     */

    class AnotherClass4 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "2": "bar"}

    class ContainerClass1 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass4();
        }

        function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "2": "bar"}}

    class AnotherClass5 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return array_values($this->elements);
        }
    } // => {"0": "foo", "1": "bar"} en tant que classe racine
      //        ["foo", "bar"] en tant que valeur imbriquée

    class ContainerClass2 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass5();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": ["foo", "bar"]}

    class AnotherClass6 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        function bsonSerialize(): object
        {
            return (object) $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    class ContainerClass3 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass6();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "1": "bar"}}

    class UpperClass implements MongoDB\BSON\Persistable
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';

        private $data;

        public function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "wine", "__pclass": {"$type": "80", "$binary": "VXBwZXJDbGFzcw=="}}

    ?>

## Deserialization from BSON

Avertissement

Les documents BSON peuvent techniquement contenir des clés dupliquées car les documents sont stockés en tant qu'une liste de paire clé-valeur ; cependant, les applications devrait s'abstenir de générer des documents avec des clés dupliquées car le comportement du serveur et du pilote peut être indéfinie. Puisque les objets et tableaux PHP ne peuvent pas avoir de clés dupliquées, les données pourraient aussi être perdu lors du décodage d'un document BSON avec des clés dupliquées.

L'ancienne extension `mongo` désérialisait les documents BSON et les tableaux BSON en tant que tableaux PHP. Tant que les tableaux PHP sont pratiques à utiliser, ce comportement était problématique car différents types BSON pouvaient être désérialisés en la même valeur PHP (par exemple `{"0": "foo"}` et `["foo"]`) et rendait impossible d'inférer le type BSON original. Par défaut, l'extension `mongodb` adresse cette préoccupation en s'assurant que les tableaux BSON et les documents BSON sont convertis en tableaux et objets PHP, respectivement.

Pour les types composés, il existe trois types de données :

root
  réfère à un document BSON de niveau supérieur seulement
document
  réfère à des documents BSON imbriqués seulement
array
  réfère à un tableau BSON

A part les trois types collectifs, il est aussi possible de configurer des champs spécifiques dans le document pour mapper les types de données mentionnés ci-dessous. Par exemple, le type de carte suivant permet de mapper chaque document intégré dans un tableau `"addresses"` à une classe Address et chaque champ `"city"` dans ces documents d'adresse intégrés à une classe City:

    [
        'fieldPaths' => [
            'addresses.$' => 'MyProject\Address',
            'addresses.$.city' => 'MyProject\City',
        ],
    ]

Chacun de ces trois types de données, ainsi que les mappages spécifiques aux champs, peuvent être mappés contre différents types PHP. Les valeurs de mappage possibles sont:

non défini ou NULL (par défaut)

  - Un tableau BSON sera désérialisé en un array PHP.
  - Un document BSON (racine ou imbriqué) sans propriété __pclass [1]

    Une propriété __pclass n'est considérée comme existante que si une propriété portant ce nom existe, et qu'elle est une valeur binaire, et que le sous-type de la valeur binaire est 0x80. Si une de ces trois conditions n'est pas remplie, la propriété __pclass n'existe pas et doit être traitée comme toute autre propriété normale.

    devient un objet stdClass, avec chaque clé de document BSON définie comme une propriété de stdClass publique.
  - Un document BSON (racine ou imbriqué) avec une propriété __pclass [1] devient un objet PHP de la classe nommée par la propriété __pclass. Si la classe nommée implémente l'interface MongoDB\BSON\Persistable, alors les propriétés du document BSON, y compris la propriété __pclass, sont envoyées sous forme de tableau associatif à la fonction MongoDB\BSON\Unserializable::bsonUnserialize() pour initialiser les propriétés de l'objet. Si la classe nommée n'existe pas ou n'implémente pas l'interface MongoDB\BSON\Persistable, stdClass sera utilisé et chaque clé de document BSON (y compris __pclass) sera définie comme une propriété publique de stdClass. La fonctionnalité __pclass repose sur le fait que la propriété soit partie d'un document MongoDB récupéré. Si l'on utilise une projection lors de la recherche de documents, il faut inclure le champ __pclass dans la projection pour que cette fonctionnalité fonctionne.
`"array"`
  Transforme un tableau BSON en un array PHP. Il n'y aura pas de traitement spécial d'une propriété __pclass [1] mais elle peut être définie comme un élément dans le tableau retourné si elle était présente dans le document BSON.
`"object"` ou `"stdClass"`
  Transforme un tableau BSON ou un document BSON en un objet stdClass. Il n'y aura pas de traitement spécial d'une propriété __pclass [1] mais elle peut être définie comme une propriété publique dans l'objet retourné si elle était présente dans le document BSON.
`"bson"`
  Transforme un tableau BSON en un MongoDB\BSON\PackedArray et un document BSON en un MongoDB\BSON\Document, indépendamment du fait que le document BSON ait une propriété __pclass [1].

  > Note: La valeur `bson` n'est disponible que pour les trois types racines, et non dans les mappages spécifiques aux champs.

toutes les autres chaînes de caractères
  Définit le nom de la classe à laquelle le document BSON doit être désérialisé. Pour les documents BSON qui incluent des propriétés __pclass, cette classe prendra la priorité. Si la classe nommée n'existe pas, n'est pas concrète (c'est-à-dire qu'elle est abstraite ou une interface), ou n'implémente pas l'interface MongoDB\BSON\Unserializable, une exception MongoDB\Driver\Exception\InvalidArgumentException est lancée. Si l'objet BSON a une propriété __pclass et que cette classe existe et implémente MongoDB\BSON\Persistable, elle prendra le pas sur la classe fournie dans la carte de type. Les propriétés du document BSON, y compris la propriété __pclass, seront envoyées sous forme de tableau associatif à la fonction MongoDB\BSON\Unserializable::bsonUnserialize() pour initialiser les propriétés de l'objet.

## TypeMaps

Les TypeMaps peuvent être définis via la méthode MongoDB\Driver\Cursor::setTypeMap() sur un objet MongoDB\Driver\Cursor, ou l'argument `$typeMap` de MongoDB\BSON\toPHP(), MongoDB\BSON\Document::toPHP(), et MongoDB\BSON\PackedArray::toPHP(). Chacune des trois classes (racine, document, et array) peut être définie individuellement, en plus des types spécifiques aux champs.

Si la valeur dans le TypeMap est NULL, cela signifie la même chose que la valeur par défaut pour cet élément.

## Exemples

Ces exemples utilisent les classes suivantes:

MyClass
  qui n'implémente aucune interface
YourClass
  qui implémente MongoDB\BSON\Unserializable
OurClass
  qui implémente MongoDB\BSON\Persistable
TheirClass
  qui étend OurClass

La méthode MongoDB\BSON\Unserializable::bsonUnserialize() d'YourClass, OurClass, TheirClass itère sur le tableau et définit les propriétés sans modifications. Elle ajoute aussi la propriété `$unserialized` à `true`:

    <?php

    function bsonUnserialize( array $map )
    {
        foreach ( $map as $k => $value )
        {
            $this->$k = $value;
        }
        $this->unserialized = true;
    }

    /* typemap: [] (all defaults) */
    { "foo": "yes", "bar" : false }
      -> stdClass { $foo => 'yes', $bar => false }

    { "foo": "no", "array" : [ 5, 6 ] }
      -> stdClass { $foo => 'no', $array => [ 5, 6 ] }

    { "foo": "no", "obj" : { "embedded" : 3.14 } }
      -> stdClass { $foo => 'no', $obj => stdClass { $embedded => 3.14 } }

    { "foo": "yes", "__pclass": "MyClass" }
      -> stdClass { $foo => 'yes', $__pclass => 'MyClass' }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "MyClass" } }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'MyClass') }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "YourClass") }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass') }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "OurClass") }
      -> OurClass { $foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized => true }

    { "foo": "yes", "__pclass": { "$type" : "44", "$binary" : "YourClass") }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x44, 'YourClass') }

    /* typemap: [ "root" => "MissingClass" ] */
    { "foo": "yes" }
      -> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not exist")

    /* typemap: [ "root" => "MyClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement Unserializable interface")

    /* typemap: [ "root" => "MongoDB\BSON\Unserializable" ] */
    { "foo": "yes" }
      -> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a concrete class")

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MongoDB\BSON\Unserializable" } }
      -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MongoDB\BSON\Unserializable"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
      -> OurClass { $foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
      -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

    /* typemap: [ "root" => "OurClass" ] */
    { foo: "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
      -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

    /* typemap: [ 'root' => 'YourClass' ] */
    { foo: "yes", "__pclass" : { "$type": "80", "$binary": "YourClass" } }
      -> YourClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), $unserialized => true }

    /* typemap: [ 'root' => 'array', 'document' => 'array' ] */
    { "foo": "yes", "bar" : false }
      -> [ "foo" => "yes", "bar" => false ]

    { "foo": "no", "array" : [ 5, 6 ] }
      -> [ "foo" => "no", "array" => [ 5, 6 ] ]

    { "foo": "no", "obj" : { "embedded" : 3.14 } }
      -> [ "foo" => "no", "obj" => [ "embedded => 3.14 ] ]

    { "foo": "yes", "__pclass": "MyClass" }
      -> [ "foo" => "yes", "__pclass" => "MyClass" ]

    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> [ "foo" => "yes", "__pclass" => Binary(0x80, "MyClass") ]

    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
      -> [ "foo" => "yes", "__pclass" => Binary(0x80, "OurClass") ]

    /* typemap: [ 'root' => 'object', 'document' => 'object' ] */
    { "foo": "yes", "__pclass": { "$type": "80", "$binary": "MyClass" } }
      -> stdClass { $foo => "yes", "__pclass" => Binary(0x80, "MyClass") }

# Sécurité

## Sommaire

- Attaques par injection de requêtes
- Attaque par injection de scripts

## Attaques par injection de requêtes

Si on passe des paramètres `$_GET` (ou `$_POST`) aux requêtes, il faut s'assurer de convertir en chaînes de caractères avant. Les utilisateurs peuvent insérer des tableaux associatifs dans les requêtes GET et POST, qui pourraient alors devenir des requêtes $ indésirables.

Un exemple assez anodin : supposez qu'on cherche les informations d'un utilisateur avec la requête http://www.example.com?username=bob. L'application crée la requête `$q = new \MongoDB\Driver\Query( [ 'username' => $_GET['username'] ])`.

Cela fonctionne bien, mais quelqu'un pourrait subvertir cela en passant http://www.example.com?username[$ne]=foo, que PHP transformera magiquement en un tableau associatif, transformant la requête en `$q = new \MongoDB\Driver\Query( [ 'username' => [ '$ne' => 'foo' ] ] )`, qui renverra tous les utilisateurs dont le nom n'est pas "foo" (tous les utilisateurs, probablement).

C'est une attaque assez facile à contrer : il faut s'assurer que les paramètres `$_GET` et `$_POST` sont du type attendu avant d'envoyer à la base de données. PHP dispose de la fonction filter_var() pour aider.

À noter que ce type d'attaque peut être utilisé avec n'importe quelle interaction avec la base de données qui localise un document, y compris les mises à jour, les upserts, les suppressions et les commandes findAndModify.

Voir » la documentation principale pour plus d'informations sur les problèmes de type injection SQL avec MongoDB.

## Attaque par injection de scripts

Lors de l'utilisation de JavaScript, il faut s'assurer que toutes les variables qui traversent la frontière PHP-JavaScript sont passées dans le champ `scope` de MongoDB\BSON\Javascript, et non interpolées dans la chaîne JavaScript. Cela peut se produire lorsque on utilise des clauses `$where` dans les requêtes, les commandes mapReduce et group, et à tout autre moment où il est possible de passer du JavaScript à la base de données.

Par exemple, supposons que nous avons un JavaScript pour saluer un utilisateur dans les logs de la base de données. Nous pourrions faire :

    <?php
    $m = new MongoDB\Driver\Manager;

    // Ne faites pas ça !!!
    $username = $_GET['field'];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Hello, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Cependant, que se passe-t-il si un utilisateur malveillant passe du JavaScript ?

    <?php
    $m = new MongoDB\Driver\Manager;

    // Ne faites pas ça !!!
    $username = $_GET['field'];
    // $username équivaut à "'); db.users.drop(); print('"

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Hello, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Maintenant MongoDB exécute la chaîne JavaScript `"print('Hello, '); db.users.drop(); print('!');"`. Cette attaque est facile à éviter : utiliser `args` pour passer des variables de PHP à JavaScript :

    <?php
    $m = new MongoDB\Driver\Manager;

    $_GET['field'] = 'derick';
    $args = [ $_GET['field'] ];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "function greet(username) { print('Hello, ' + username + '!'); }",
        'args' => $args,
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Cela ajoute un argument à la portée JavaScript, qui est utilisé comme argument pour la fonction `greet`. Maintenant si quelqu'un essaie d'envoyer du code malveillant, MongoDB imprimera inoffensivement `Hello, '); db.dropDatabase(); print('!`.

Utiliser des arguments aide à empêcher l'exécution d'entrées malveillantes par la base de données. Cependant, il faut s'assurer que le code ne retourne pas et n'exécute pas l'entrée de toute façon ! Il est préférable d'éviter d'exécuter quelconque JavaScript sur le serveur en premier lieu.

Il est recommandé de rester à l'écart de la clause » $where dans les requêtes, car elle impacte significativement les performances. Dans la mesure du possible, utiliser soit des opérateurs de requête normaux, soit le » Framework d'agrégation.

Une alternative à » MapReduce, qui utilise JavaScript, est le » Framework d'agrégation. Contrairement à Map/Reduce, il utilise un langage idiomatique pour construire des requêtes, sans avoir à écrire et utiliser l'approche JavaScript plus lente que Map/Reduce nécessite.

La » commande eval a été dépréciée depuis MongoDB 3.0, et devrait également être évitée.

# Classes de l'extension MongoDB

## Sommaire

- MongoDB\Driver\Manager
- MongoDB\Driver\Command
- MongoDB\Driver\Query
- MongoDB\Driver\BulkWrite
- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\Session
- MongoDB\Driver\ClientEncryption
- MongoDB\Driver\ServerApi
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Cursor
- MongoDB\Driver\CursorId
- MongoDB\Driver\CursorInterface
- MongoDB\Driver\Server
- MongoDB\Driver\ServerDescription
- MongoDB\Driver\TopologyDescription
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError
- MongoDB\Driver\WriteResult
- MongoDB\Driver\BulkWriteCommandResult

# La classe MongoDB\Driver\Manager

(mongodb >=1.0.0)

## Introduction

Le MongoDB\Driver\Manager est le point d'entrée principal de l'extension. Il est responsable de maintenir les connexions à MongoDB (qu'il s'agisse d'un serveur autonome, d'un ensemble de réplicas ou d'un cluster partagé).

Aucune connexion à MongoDB n'est établie lors de l'instanciation du Manager. Cela signifie que la MongoDB\Driver\Manager peut toujours être construit, même si un ou plusieurs serveurs MongoDB sont hors service.

Toute écriture ou requête peut lancer des exceptions de connexion car les connexions sont créées de manière paresseuse. Un serveur MongoDB peut également devenir indisponible pendant la durée de vie du script. Il est donc important que toutes les actions sur le Manager soient enveloppées dans des instructions try/catch.

## Synopsis de la classe

final class MongoDB\Driver\Manager {
/* Méthodes */
final public function addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function __construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)
final public function createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getEncryptedFieldsMap(): array|object|null
final public function getReadConcern(): MongoDB\Driver\ReadConcern
final public function getReadPreference(): MongoDB\Driver\ReadPreference
final public function getServers(): array
final public function getWriteConcern(): MongoDB\Driver\WriteConcern
final public function removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server
final public function startSession(?array `$options` = `null`): MongoDB\Driver\Session
}

## Exemples

Exemple #1 Usage basique de MongoDB\Driver\Manager::__construct()

var_dump()er un MongoDB\Driver\Manager affichera divers détails sur le Manager qui ne sont pas normalement exposés. Cela peut être utile pour déboguer comment le pilote voit la configuration MongoDB, et quelles options sont utilisées.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\Driver\Manager)#1 (2) {
      ["uri"]=>
      string(26) "mongodb://127.0.0.1:27017/"
      ["cluster"]=>
      array(0) {
      }
    }

# MongoDB\Driver\Manager::addSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::addSubscriber — Enregistre un observateur d'événements de surveillance avec ce manager

### Description

final public function MongoDB\Driver\Manager::addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Enregistre un observateur d'événements de surveillance avec ce Manager. L'observateur sera notifié de tous les événements pour ce Manager.

> Note: Si `subscriber` est déjà enregistré avec ce manager, cette fonction ne fait rien. Si `subscriber` est également enregistré globalement, il ne sera notifié qu'une seule fois de chaque événement pour ce manager.

### Liste de paramètres

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Un observateur d'événements de surveillance à enregistrer avec ce Manager.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\InvalidArgumentException si `subscriber` est un MongoDB\Driver\Monitoring\LogSubscriber, car les observateurs ne peuvent être enregistrés que globalement.

### Voir aussi

- MongoDB\Driver\Manager::removeSubscriber() - Enlève un observateur d'événements de surveillance de ce Manager
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Manager::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Manager::__construct — Crée un nouveau Manager MongoDB

### Description

final public function MongoDB\Driver\Manager::__construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)

Construit un nouvel objet MongoDB\Driver\Manager avec les options spécifiées.

> Note: Avec la » Spécification de découverte et de surveillance du serveur, ce constructeur n'effectue pas d'E/S. Les connexions seront initialisées à la demande, lors de l'exécution de la première opération.

> Note: Lorsque des options d'URI SSL ou TLS sont spécifiées via la chaîne de connexion ou le paramètre `uriOptions`, l'extension activera implicitement TLS pour ses connexions. Pour éviter cela, désactivez explicitement l'option `tls` ou ne spécifiez aucune option TLS.

> Note: Sur les plate-formes Unix, l'extension MongoDB est sensible aux scripts qui utilisent l'appel système fork() sans pour autant appeler exec(). Vous ne devez pas ré-utliser des instances MongoDB\Driver\Manager dans une processus fils issue d'un fork.

### Liste de paramètres

`uri`
  Une URI de connexion » mongodb://:

      mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[defaultAuthDb][?options]]

  Par défaut, `"mongodb://127.0.0.1:27017"` si non spécifié. Pour les détails sur les options d'URI prises en charge, voir » Options de chaîne de connexion dans le manuel MongoDB. » Options de pool de connexions ne sont pas prises en charge, car l'extension n'implémente pas de pools de connexions. L'`uri` est une URL, donc tous les caractères spéciaux dans ses composants doivent être encodés en URL selon la » RFC 3986. Cela est particulièrement pertinent pour le nom d'utilisateur et le mot de passe, qui peuvent souvent inclure des caractères spéciaux tels que `@`, `:` ou `%`. Lors de la connexion via un socket de domaine Unix, le chemin du socket peut contenir des caractères spéciaux tels que des barres obliques et doit être encodé. La fonction rawurlencode() peut être utilisée pour encoder les parties constitutives de l'URI. Le composant `defaultAuthDb` peut être utilisé pour spécifier la base de données associée aux informations d'identification de l'utilisateur; cependant, l'option d'URI `authSource` aura la priorité si elle est spécifiée. Si ni `defaultAuthDb` ni `authSource` ne sont spécifiés, la base de données `admin` sera utilisée par défaut. Le composant `defaultAuthDb` n'a aucun effet en l'absence d'informations d'identification utilisateur.
`uriOptions`
  Options supplémentaires » de chaîne de connexion, qui écraseront toute option portant le même nom dans le paramètre `uri`.

  uriOptions
  Option | Type | Description
  --- | --- | ---
  appname | string | MongoDB 3.4+ a la capacité d'annoter les connexions avec des métadonnées fournies par le client connecté. Ces métadonnées sont incluses dans les journaux du serveur lors de l'établissement d'une connexion et également enregistrées dans les journaux de requêtes lentes lorsque le profilage de la base de données est activé. Cette option peut être utilisée pour spécifier un nom d'application, qui sera inclus dans les métadonnées. La valeur ne peut pas dépasser 128 caractères de longueur.
  authMechanism | string | Le mécanisme d'authentification que MongoDB utilisera pour authentifier la connexion. Pour plus de détails et une liste des valeurs prises en charge, voir » Options d'authentification dans le manuel MongoDB.
  authMechanismProperties | array | Les propriétés spécifiques au mécanisme d'authentification sélectionné. Pour plus de détails et une liste des propriétés prises en charge, voir la » Spécification d'authentification du pilote. Note: Lorsque non spécifiée dans la chaîne d'URI, cette option est exprimée comme un tableau de paires clé/valeur. Les clés et valeurs de ce tableau doivent être des chaînes.
  authSource | string | Le nom de la base de données associée aux informations d'identification de l'utilisateur. Par défaut au composant de la base de données de l'URI de connexion, ou à la base de données `admin` si les deux sont non spécifiés. Pour les mécanismes d'authentification qui ne prennent pas en charge la notion de base de données (e.g. GSSAPI), cela devrait être `"$external"`.
  compressors | string | Une liste priorisée et délimitée par des virgules de compresseurs que le client souhaite utiliser. Les messages ne sont compressés que si le client et le serveur partagent des compresseurs en commun, et le compresseur utilisé dans chaque direction dépendra de la configuration individuelle du serveur ou du pilote. Voir la » Spécification de compression de pilote pour plus d'informations.
  connectTimeoutMS | int | Le temps en millisecondes pour tenter une connexion avant d'expirer. Par défaut à 10 000 millisecondes.
  directConnection | bool | Cette option peut être utilisée pour contrôler le comportement de découverte de l'ensemble de réplicas lorsqu'un seul hôte est fourni dans la chaîne de connexion. Par défaut, fournir un seul membre dans la chaîne de connexion établira une connexion directe ou découvrira des membres supplémentaires selon que l'option d'URI `"replicaSet"` est omise ou présente, respectivement. Spécifier `false` pour forcer la découverte à se produire (si `"replicaSet"` est omis) ou spécifiez `true` pour forcer une connexion directe (si `"replicaSet"` est présent).
  enableOverloadRetargeting | bool | Lorsque définie à `true`, force la sélection du serveur après une `SystemOverloadedError`. Par défaut à `false`.
  heartbeatFrequencyMS | int | Spécifie l'intervalle en millisecondes entre les vérifications de la topologie MongoDB, compté de la fin de la vérification précédente jusqu'au début de la suivante. Par défaut à 60 000 millisecondes. Pour la » Spécification de découverte et de surveillance du serveur, cette valeur ne peut pas être inférieure à 500 millisecondes.
  journal | bool | Correspond à l'option `journal` du write concern par défaut. Si `true`, les écritures nécessiteront un accusé de réception de MongoDB indiquant que l'opération a été écrite dans le journal. Pour plus de détails, voir MongoDB\Driver\WriteConcern.
  loadBalanced | bool | Spécifie si le pilote se connecte à un cluster MongoDB via un équilibreur de charge. Si `true`, le pilote ne peut se connecter qu'à un seul hôte (spécifié par la chaîne de connexion ou la recherche SRV), l'option d'URI `"directConnection"` ne peut pas être `true`, et l'option d'URI `"replicaSet"` doit être omise. Par défaut à `false`.
  localThresholdMS | int | La taille en millisecondes de la fenêtre de latence pour la sélection parmi plusieurs instances MongoDB appropriées lors de la résolution d'une préférence de lecture. Par défaut à 15 millisecondes.
  maxAdaptiveRetries | int | Cette option peut être utilisée pour modifier le nombre maximum de tentatives lorsqu'une `SystemOverloadedError` se produit. Doit être un entier positif; par défaut à `2`.
  maxStalenessSeconds | int | Correspond à l'option `maxStalenessSeconds` de la préférence de lecture. Spécifie, en secondes, la durée de validité maximale d'une instance secondaire avant que le client ne cesse de l'utiliser pour les opérations de lecture. Par défaut, il n'y a pas de durée de validité maximale et les clients ne tiendront pas compte du délai d'une instance secondaire lors du choix de la direction d'une opération de lecture. Pour plus de détails, voir MongoDB\Driver\ReadPreference. Si spécifié, la durée de validité maximale doit être un entier signé de 32 bits supérieur ou égal à `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS` (par exemple 90 secondes).
  password | string | Le mot de passe de l'utilisateur en cours d'authentification. Cette option est utile si le mot de passe contient des caractères spéciaux, qui devraient autrement être encodés en URL pour l'URI de connexion.
  readConcernLevel | string | Correspond à l'option `level` de la préférence de lecture. Spécifie le niveau d'isolation de lecture. Pour plus de détails, voir MongoDB\Driver\ReadConcern.
  readPreference | string | Correspond à l'option `mode` de la préférence de lecture. Par défaut à `"primary"`. Pour plus de détails, voir MongoDB\Driver\ReadPreference.
  readPreferenceTags | array | Correspond à l'option `tagSets` de la préférence de lecture. Les ensembles de balises permettent de cibler les opérations de lecture sur des membres spécifiques d'un ensemble de réplicas. Pour plus de détails, voir MongoDB\Driver\ReadPreference. Note: Lorsque non spécifiée dans la chaîne d'URI, cette option est exprimée comme un tableau conforme au format attendu par MongoDB\Driver\ReadPreference::__construct().
  replicaSet | string | Spécifie le nom de l'ensemble de réplicas.
  retryReads | bool | Spécifie si le pilote doit automatiquement réessayer certaines opérations de lecture qui échouent en raison d'erreurs réseau transitoires ou d'élections d'ensemble de réplicas. Cette fonctionnalité nécessite MongoDB 3.6+. Par défaut à `true`. Voir la » Spécification de lecture réessayable pour plus d'informations.
  retryWrites | bool | Spécifie si le pilote doit automatiquement réessayer certaines opérations d'écriture qui échouent en raison d'erreurs réseau transitoires ou d'élections d'ensemble de réplicas. Cette fonctionnalité nécessite MongoDB 3.6+. Par défaut à `true`. Voir » Écritures réessayables dans le manuel MongoDB pour plus d'informations.
  serverSelectionTimeoutMS | int | Spécifie combien de temps en millisecondes bloquer pour la sélection du serveur avant de lancer une exception. Par défaut à 30 000 millisecondes.
  serverSelectionTryOnce | bool | Lorsque `true`, indique au pilote de scanner le déploiement MongoDB exactement une fois après un échec de sélection du serveur, puis de sélectionner un serveur ou de lancer une exception. Lorsque `false`, le pilote bloque et recherche un serveur jusqu'à la valeur de `"serverSelectionTimeoutMS"`. Par défaut à `true`.
  socketCheckIntervalMS | int | Si un socket n'a pas été utilisé récemment, le pilote doit le vérifier via une commande `hello` avant de l'utiliser pour toute opération. Par défaut à 5 000 millisecondes.
  socketTimeoutMS | int | Le temps en millisecondes pour tenter un envoi ou une réception sur un socket avant d'expirer. Par défaut à 300 000 millisecondes (c.-à-d. cinq minutes).
  srvMaxHosts | int | Le nombre maximum de résultats SRV à sélectionner aléatoirement lors de la première population de la liste de semences ou, lors du sondage SRV, l'ajout de nouveaux hôtes à la topologie. Par défaut à `0` (c.-à-d. pas de maximum).
  srvServiceName | string | Le nom de service à utiliser pour la recherche SRV dans la liste de semences initiale et le sondage SRV. Par défaut à `"mongodb"`.
  tls | bool | Initialise la connexion avec TLS/SSL si `true`. Par défaut à `false`.
  tlsAllowInvalidCertificates | bool | Spécifie si le pilote doit générer une erreur lorsque le certificat TLS du serveur est invalide. Par défaut à `false`. Avertissement Désactiver la validation du certificat créant une vulnérabilité.
  tlsAllowInvalidHostnames | bool | Spécifie si le pilote doit générer une erreur lorsqu'il y a un désaccord entre le nom d'hôte du serveur et le nom d'hôte spécifié par le certificat TLS. Par défaut à `false`. Avertissement Désactive la validation du certificat créant une vulnérabilité. Autoriser les noms d'hôte invalides peut exposer le pilote à une » attaque de l'homme du milieu.
  tlsCAFile | string | Le chemin du fichier contenant un seul certificat ou un ensemble de certificats d'autorités à considérer comme fiables lors de l'établissement d'une connexion TLS. Le magasin de certificats système sera utilisé par défaut.
  tlsCertificateKeyFile | string | Le chemin du fichier de certificat client ou du fichier de clé privée client; dans le cas où les deux sont nécessaires, les fichiers doivent être concaténés.
  tlsCertificateKeyFilePassword | string | Le mot de passe pour déchiffrer la clé privée client (c.-à-d. l'option d'URI `"tlsCertificateKeyFile"`) à utiliser pour les connexions TLS.
  tlsDisableCertificateRevocationCheck | bool | Si `true`, le pilote n'essaiera pas de vérifier l'état de révocation du certificat (e.g. OCSP, CRL). Par défaut à `false`.
  tlsDisableOCSPEndpointCheck | bool | Si `true`, le pilote n'essaiera pas de contacter un point de terminaison de répondeur OCSP si nécessaire (c.-à-d. une réponse OCSP n'est pas agrafée). Par défaut à `false`.
  tlsInsecure | bool | Détend les contraintes TLS autant que possible. Spécifier `true` pour que cette option ait le même effet que de spécifier `true` pour les options d'URI `"tlsAllowInvalidCertificates"` et `"tlsAllowInvalidHostnames"`. Par défaut à `false`. Avertissement Désactive la validation du certificat créant une vulnérabilité. Autoriser les noms d'hôte invalides peut exposer le pilote à une » attaque de l'homme du milieu.
  username | string | Le nom d'utilisateur de l'utilisateur en cours d'authentification. Cette option est utile si le nom d'utilisateur contient des caractères spéciaux, qui devraient autrement être encodés en URL pour l'URI de connexion.
  w | int|string | Correspond à l'option `w` du write concern par défaut. Pour plus de détails, voir MongoDB\Driver\WriteConcern.
  wTimeoutMS | int|string | Correspond à l'option `wtimeout` du write concern par défaut. Spécifie une limite de temps, en millisecondes, pour le write concern. Pour plus de détails, voir MongoDB\Driver\WriteConcern. Si spécifié, `wTimeoutMS` doit être un entier signé de 32 bits supérieur ou égal à zéro.
  zlibCompressionLevel | int | Spécifie le niveau de compression à utiliser pour le compresseur zlib. Cette option n'a aucun effet si `zlib` n'est pas inclus dans l'option d'URI `"compressors"`. Voir la » Spécification de compression de pilote pour plus d'informations.

`driverOptions`

  driverOptions
  Option | Type | Description
  --- | --- | ---
  autoEncryption | array | Apporte des options pour activer le chiffrement côté client au niveau des champs. La liste des options est décrite dans la table en dessous. Note: Le chiffrement automatique est une fonctionnalité d'entreprise qui ne s'applique qu'aux opérations sur une collection. Le chiffrement automatique n'est pas pris en charge pour les opérations sur une base de données ou une vue, et les opérations qui ne sont pas contournées entraîneront une erreur (voir » libmongocrypt: La liste d'autorisation de chiffrement automatique). Pour contourner le chiffrement automatique pour toutes les opérations, définissez `bypassAutoEncryption` à `true`. Le chiffrement automatique nécessite que l'utilisateur authentifié ait le privilège d'action » listCollections. Le chiffrement explicite et automatique est une fonctionnalité de la communauté. Le pilote peut toujours déchiffrer automatiquement lorsque `bypassAutoEncryption` est `true`.
  ca_dir | string | Le chemin du répertoire de certificats correctement hachés. Le magasin de certificats système sera utilisé par défaut.
  crl_file | string | Le chemin du fichier de liste de révocation de certificat.
  disableClientPersistence | bool | Si `true`, ce Manager utilisera un nouveau client libmongoc, qui ne sera pas persisté ou partagé avec d'autres objets Manager. Lorsque cet objet Manager est libéré, son client sera détruit et toutes les connexions seront fermées. Par défaut à `false`. Note: Désactiver la persistance du client n'est généralement pas recommandé.
  driver | array | Autorise un niveau supérieur de bibliothèque à ajouter ses propres métadonnées à la poignée de main du serveur. Par défaut, l'extension soumet son propre nom, version et plateforme (c.-à-d. version PHP) dans la poignée de main. Les chaînes peuvent être spécifiées pour les clés `"name"`, `"version"` et `"platform"` de ce tableau, et seront ajoutées au champ respectif(s) de la poignée de main du serveur. Note: Les informations de poignée de main sont limitées à 512 octets. L'extension tronquera les données de poignée de main pour s'adapter à cette chaîne de 512 octets. Les bibliothèques de niveau supérieur sont encouragées à conserver leurs propres métadonnées concises.
  serverApi | MongoDB\Driver\ServerApi | Cette option est utilisée pour déclarer une version d'API serveur pour le Manager. Si omis, aucune version d'API n'est déclarée.

  Les options suivantes sont prises en charge:

  Options pour le chiffrement automatique
  Option | Type | Description
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | Le Manager utilisé pour router les requêtes de clés de données à un cluster MongoDB différent. Par défaut, le Manager et cluster courant et utilisé.
  keyVaultNamespace | chaîne de caractères | Un nom d'espace complètement qualifié (par exemple `"databaseName.collectionName"`) dénotant la collection qui contient toutes les clés de données utilisé pour le chiffrement et déchiffrement. Cette option est requise.
  kmsProviders | tableau | Un document contenant la configuration d'un ou plusieurs fournisseurs KMS, qui sont utilisés pour chiffrer les clés de données. Les fournisseurs supporté sont `"aws"`, `"azure"`, `"gcp"` et `"local"`, et au moins un doit être spécifié. Si un document vide est spécifié pour `"aws"`, `"azure"`, ou `"gcp"`, le pilote tentera de configurer le fournisseur en utilisant » Automatic Credentials. Le format pour `"aws"` est le suivant :
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  Le format pour `"azure"` est le suivant :
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"

      }
  Le format pour `"gcp"` est le suivant :
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Defaults to "oauth2.googleapis.com"

      }
  Le format pour `"kmip"` est le suivant :
      kmip: {
          endpoint: <string>
      }
  Le format pour `"local"` est le suivant :
      local: {
          // 96-byte master key used to encrypt/decrypt data keys
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Un document contenant la configuration TLS d'un ou plusieurs fournisseurs KMS. Les fournisseurs supporté sont `"aws"`, `"azure"`, `"gcp"` et `"kmip"`. Tous les fournisseurs supportent les options suivantes :
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }
  schemaMap | array|object | Mappe les espaces de noms de collection à un schéma JSON local. Ceci est utilisé pour configurer le chiffrement automatique. Voir » Règles de chiffrement automatique dans le manuel MongoDB pour plus d'informations. Il est une erreur de spécifier une collection à la fois dans `schemaMap` et `encryptedFieldsMap`. Note: Fournir un `schemaMap` fournit plus de sécurité que de se fier aux schémas JSON obtenus du serveur. Cela protège contre un serveur malveillant annonçant un faux schéma JSON, qui pourrait tromper le client en envoyant des données non chiffrées qui devraient être chiffrées. Note: Les schémas fournis dans le `schemaMap` s'appliquent uniquement à la configuration du chiffrement automatique pour le chiffrement côté client. D'autres règles de validation dans le schéma JSON ne seront pas appliquées par le pilote et entraîneront une erreur.
  bypassAutoEncryption | bool | Si `true`, `mongocryptd` ne sera pas lancé automatiquement. Ceci est utilisé pour désactiver le chiffrement automatique. Par défaut à `false`.
  bypassQueryAnalysis | bool | Si `true`, l'analyse automatique des commandes sortantes sera désactivée et `mongocryptd` ne sera pas lancé automatiquement. Cela permet le cas d'utilisation du chiffrement explicite pour interroger des champs indexés sans nécessiter la bibliothèque `crypt_shared` sous licence entreprise ou le processus `mongocryptd`. Par défaut à `false`.
  encryptedFieldsMap | array|object | Mappe les espaces de noms de collection à un document `encryptedFields`. Ceci est utilisé pour configurer le chiffrement interrogeable. Voir » Chiffrement de champ et interrogeabilité dans le manuel MongoDB pour plus d'informations. Il est une erreur de spécifier une collection à la fois dans `encryptedFieldsMap` et `schemaMap`. Note: Fournir un `encryptedFieldsMap` fournit plus de sécurité que de se fier aux `encryptedFields` obtenus du serveur. Cela protège contre un serveur malveillant annonçant un faux `encryptedFields`.
  extraOptions | array | Le `extraOptions` se rapportent au processus `mongocryptd`. Les options suivantes sont prises en charge: `mongocryptdURI` (string): URI pour se connecter à un processus `mongocryptd` existant. Par défaut à `"mongodb://localhost:27020"`. `mongocryptdBypassSpawn` (bool): Si `true`, empêche le pilote de lancer `mongocryptd`. Par défaut à `false`. `mongocryptdSpawnPath` (string): Chemin absolu pour rechercher le binaire `mongocryptd`. Par défaut à une chaîne vide et consulte les chemins système. `mongocryptdSpawnArgs` (array): Tableau d'arguments de chaîne à passer à `mongocryptd` lors du lancement. Par défaut à `["--idleShutdownTimeoutSecs=60"]`. `cryptSharedLibPath` (string): Chemin absolu vers la bibliothèque partagée `crypt_shared`. Par défaut à une chaîne vide et consulte les chemins système. `cryptSharedLibRequired` (bool): Si `true`, exige que le pilote charge `crypt_shared`. Par défaut à `false`. Voir la » Spécification de chiffrement côté client pour plus d'informations.

  > Note: Le chiffrement automatique est une fonctionnalité d'entreprise qui ne s'applique qu'aux opérations sur une collection. Le chiffrement automatique n'est pas pris en charge pour les opérations sur une base de données ou une vue, et les opérations qui ne sont pas contournées entraîneront une erreur. Pour contourner le chiffrement automatique pour toutes les opérations, définissez `bypassAutoEncryption=true` dans `autoEncryption`. Pour plus d'informations sur les opérations autorisées, voir la » Spécification de chiffrement côté client.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une exception MongoDB\Driver\Exception\RuntimeException si le format de l'`uri` est invalide

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | L'option d'URI `"canonicalizeHostname"` a été supprimée. Utiliser la propriété `"CANONICALIZE_HOST_NAME"` de l'option d'URI `"authMechanismProperties"` plutôt. L'option d'URI `"gssapiServiceName"` a été supprimée. Utiliser la propriété `"SERVICE_NAME"` de l'option d'URI `"authMechanismProperties"` plutôt. L'option d'URI `"safe"` a été supprimée. Utiliser les options d'URI `"w"` et `"wTimeoutMS"` plutôt. L'option d'URI `"ssl"` a été supprimée. Utiliser l'option d'URI `"tls"` plutôt. L'option de pilote `"allow_invalid_hostname"` a été supprimée. Utiliser l'option d'URI `"tlsAllowInvalidHostnames"` plutôt. L'option de pilote `"ca_file"` a été supprimée. Utiliser l'option d'URI `"tlsCAFile"` plutôt. L'option de pilote `"context"` a été supprimée. Toutes les options de contexte ont été dépréciées en faveur des diverses options d'URI liées à TLS. L'option de pilote `"pem_file"` a été supprimée. Utiliser l'option d'URI `"tlsCertificateKeyFile"` plutôt. L'option de pilote `"pem_pwd"` a été supprimée. Utiliser l'option d'URI `"tlsCertificateKeyFilePassword"` plutôt. L'option de pilote `"weak_cert_validation"` a été supprimée. Utiliser l'option d'URI `"tlsAllowInvalidCertificates"` plutôt.
PECL mongodb 1.16.0 | Le fournisseur AWS KMS pour le chiffrement côté client accepte désormais une option `"sessionToken"`, qui peut être utilisée pour s'authentifier avec des informations d'identification AWS temporaires. Ajout de `"tlsDisableOCSPEndpointCheck"` au champ `"tlsOptions"` de l'option de pilote `"autoEncryption"`. Si un document vide est spécifié pour le fournisseur KMS `"azure"` ou `"gcp"`, le pilote tentera de configurer le fournisseur en utilisant » les informations d'identification automatiques.
PECL mongodb 1.15.0 | Si un document vide est spécifié pour le fournisseur KMS `"aws"`, le pilote tentera de configurer le fournisseur en utilisant » les informations d'identification automatiques.
PECL mongodb 1.14.0 | Ajout des options de chiffrement côté client `"bypassQueryAnalysis"` et `"encryptedFieldsMap"`. Des options supplémentaires concernant `crypt_shared` sont désormais prises en charge dans l'option de chiffrement côté client `"extraOptions"`.
PECL mongodb 1.13.0 | Ajout des options d'URI `"srvMaxHosts"` et `"srvServiceName"`.
PECL mongodb 1.12.0 | KMIP est désormais pris en charge en tant que fournisseur KMS pour le chiffrement côté client et peut être configuré dans le champ `"kmsProviders"` de l'option de pilote `"autoEncryption"`. De plus, les options TLS pour les fournisseurs KMS peuvent désormais être configurées dans le champ `"tlsOptions"` de l'option de pilote `"autoEncryption"`.
PECL mongodb 1.11.0 | Ajout de l'option d'URI `"loadBalanced"`.
PECL mongodb 1.10.0 | Ajout de l'option de pilote `"disableClientPersistence"`. Azure et GCP sont désormais pris en charge en tant que fournisseurs KMS pour le chiffrement côté client et peuvent être configurés dans le champ `"kmsProviders"` de l'option de pilote `"autoEncryption"`. Les chaînes encodées en base64 sont désormais acceptées en tant qu'alternative à MongoDB\BSON\Binary pour les options dans `"kmsProviders"`.
PECL mongodb 1.8.0 | Ajout des options d'URI `"directConnection"`, `"tlsDisableCertificateRevocationCheck"` et `"tlsDisableOCSPEndpointCheck"`. Ajout de l'option de pilote `"driver"`.
PECL mongodb 1.7.0 | Ajout de l'option de pilote `"autoEncryption"`. Spécifier n'importe quelle option SSL ou TLS via le paramètre `driverOptions` activera désormais implicitement TLS, comme c'est le cas pour les options d'URI correspondantes.
PECL mongodb 1.6.0 | Ajout des options d'URI `"retryReads"`, `"tls"`, `"tlsAllowInvalidCertificates"`, `"tlsAllowInvalidHostnames"`, `"tlsCAFile"`, `"tlsCertificateKeyFile"`, `"tlsCertificateKeyFilePassword"`, et `"tlsInsecure"`. L'option d'URI `"retryWrites"` est désormais à `true` par défaut. Spécifier une option d'URI SSL ou TLS via la chaîne de connexion ou le paramètre `uriOptions` activera désormais implicitement TLS à moins que `ssl` ou `tls` ne soit `false`. TLS n'est pas implicitement activé pour les options dans le paramètre `driverOptions`, ce qui est inchangé par rapport aux versions précédentes.
PECL mongodb 1.5.0 | `"wtimeoutMS"` est désormais toujours validé et appliqué au write concern. Auparavant, l'option était ignorée si `"w"` était <= 1, car le délai s'applique uniquement à la réplication.
PECL mongodb 1.4.0 | Ajout des options d'URI `"compressors"`, `"retryWrites"`, et `"zlibCompressionLevel"`.
PECL mongodb 1.3.0 | L'argument `uriOptions` accepte désormais les options `"authMechanism"` et `"authMechanismProperties"`. Auparavant, ces options n'étaient prises en charge que dans l'argument `uri`.
PECL mongodb 1.2.0 | L'argument `uri` est désormais facultatif et par défaut à `"mongodb://`. Le port par défaut reste `27017`. Ajout de l'option d'URI `"appname"`. Ajout des options de pilote `"allow_invalid_hostname"`, `"ca_file"`, `"ca_dir"`, `"clr_file"`, `"pem_file"`, `"pem_pwd"`, et `"weak_cert_validation"`. L'API des flux PHP n'est plus utilisée pour la communication par socket. L'option `"connectTimeoutMS"` de l'URI est désormais par défaut à 10 secondes au lieu de default_socket_timeout dans les versions précédentes. De plus, l'extension ne prend plus en charge toutes les options de contexte SSL via l'option de pilote `"context"`.
PECL mongodb 1.1.0 | L'argument `uri` est désormais facultatif et par défaut à `"mongodb://localhost:27017/"`.

### Exemples

Exemple #1 Exemples basiques MongoDB\Driver\Manager::__construct()

Connexion à un nœud MongoDB autonome:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");

    ?>

Connexion à un nœud MongoDB autonome via un socket de domaine Unix. Le chemin du socket peut inclure des caractères spéciaux tels que des barres obliques et doit être encodé avec rawurlencode().

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));

    ?>

Connexion à un ensemble de réplicas:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    ?>

Connexion à un cluster fragmenté (c'est-à-dire un ou plusieurs instances mongos):

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");

    ?>

Connexion à MongoDB avec des informations d'authentification pour un utilisateur et une base de données particuliers:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://myusername:mypassword@example.com/?authSource=databaseName");

    ?>

Connexion à MongoDB avec des informations d'authentification pour un utilisateur et une base de données particuliers, où le nom d'utilisateur ou le mot de passe inclut des caractères spéciaux (par exemple `@`, `:`, `%`). Dans l'exemple suivant, la chaîne de mot de passe `myp@ss:w%rd` a été manuellement échappée; cependant, rawurlencode() peut également être utilisé pour échapper les composants d'URI qui peuvent contenir des caractères spéciaux.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://myusername:myp%40ss%3Aw%25rd@example.com/?authSource=databaseName");

    ?>

Connexion à MongoDB avec l'authentification X509:

    <?php

    $manager = new MongoDB\Driver\Manager(
        "mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",
        [],
        [
            "pem_file" => "/path/to/client.pem",
        ]
    );
    ?>

### Voir aussi

- Gestion de la connexion et de la persistance
- » Format de chaîne de connexion MongoDB

# MongoDB\Driver\Manager::createClientEncryption

(mongodb >=1.7.0)

MongoDB\Driver\Manager::createClientEncryption — Créer un nouvel objet ClientEncryption

### Description

final public function MongoDB\Driver\Manager::createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption

Construit un nouvel objet MongoDB\Driver\ClientEncryption avec les options spécifiées.

### Liste de paramètres

`options`

  options
  Option | Type | Description
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | Le Manager utilisé pour router les requêtes de clés de données à un cluster MongoDB différent. Par défaut, le Manager et cluster courant et utilisé.
  keyVaultNamespace | chaîne de caractères | Un nom d'espace complètement qualifié (par exemple `"databaseName.collectionName"`) dénotant la collection qui contient toutes les clés de données utilisé pour le chiffrement et déchiffrement. Cette option est requise.
  kmsProviders | tableau | Un document contenant la configuration d'un ou plusieurs fournisseurs KMS, qui sont utilisés pour chiffrer les clés de données. Les fournisseurs supporté sont `"aws"`, `"azure"`, `"gcp"` et `"local"`, et au moins un doit être spécifié. Si un document vide est spécifié pour `"aws"`, `"azure"`, ou `"gcp"`, le pilote tentera de configurer le fournisseur en utilisant » Automatic Credentials. Le format pour `"aws"` est le suivant :
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  Le format pour `"azure"` est le suivant :
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"

      }
  Le format pour `"gcp"` est le suivant :
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Defaults to "oauth2.googleapis.com"

      }
  Le format pour `"kmip"` est le suivant :
      kmip: {
          endpoint: <string>
      }
  Le format pour `"local"` est le suivant :
      local: {
          // 96-byte master key used to encrypt/decrypt data keys
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Un document contenant la configuration TLS d'un ou plusieurs fournisseurs KMS. Les fournisseurs supporté sont `"aws"`, `"azure"`, `"gcp"` et `"kmip"`. Tous les fournisseurs supportent les options suivantes :
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }

### Valeurs de retour

Renvoie une nouvelle instance de MongoDB\Driver\ClientEncryption.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une exception MongoDB\Driver\Exception\RuntimeException si l'extension a été compilée sans le support de libmongocrypt

### Historique

Version | Description
--- | ---
PECL mongodb 1.16.0 | Le fournisseur AWS KMS pour le chiffrement côté client accepte désormais une option `"sessionToken"`, qui peut être utilisée pour s'authentifier avec des informations d'identification AWS temporaires. Ajout de `"tlsDisableOCSPEndpointCheck"` à l'option `"tlsOptions"`. Si un document vide est spécifié pour le fournisseur KMS `"azure"` ou `"gcp"`, le pilote tentera de configurer le fournisseur en utilisant » Les informations d'identification automatiques.
PECL mongodb 1.15.0 | Si un document vide est spécifié pour le fournisseur KMS `"aws"`, le pilote tentera de configurer le fournisseur en utilisant » Les informations d'identification automatiques.
PECL mongodb 1.12.0 | KMIP est désormais pris en charge en tant que fournisseur KMS pour le chiffrement côté client et peut être configuré dans l'option `"kmsProviders"`. Ajout de l'option `"tlsOptions"`.
PECL mongodb 1.10.0 | Azure et GCP sont désormais pris en charge en tant que fournisseurs KMS pour le chiffrement côté client et peuvent être configurés dans l'option `"kmsProviders"`. Les chaînes encodées en base64 sont désormais acceptées en tant qu'alternative à MongoDB\BSON\Binary pour les options dans `"kmsProviders"`.

### Voir aussi

- MongoDB\Driver\ClientEncryption::__construct() - Créer un nouvel objet ClientEncryption
- » Chiffrement côté client explicite (manuel) dans le manuel MongoDB

# MongoDB\Driver\Manager::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeBulkWrite — Exécute une ou plusieurs opérations d'écriture

### Description

final public function MongoDB\Driver\Manager::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Exécute une ou plusieurs opérations d'écriture sur le serveur primaire.

Un MongoDB\Driver\BulkWrite peut être construit avec une ou plusieurs opérations d'écriture de types variés (par exemple, mises à jour, suppressions et insertions). Le pilote tentera d'envoyer les opérations du même type au serveur en aussi peu de requêtes que possible pour optimiser les allers-retours.

La valeur par défaut de l'option `"writeConcern"` sera déduite à partir d'une transaction active (indiquée par l'option `"session"`), suivie de l' URI de connexion.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`bulk` (MongoDB\Driver\BulkWrite)
  Écriture(s) à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

### Valeurs de retour

Retourne un MongoDB\Driver\WriteResult en cas de succès.

### Erreurs / Exceptions

- Lance une MongoDB\Driver\Exception\InvalidArgumentException si `bulk` ne contient aucune opération d'écriture.
- Lance une MongoDB\Driver\Exception\InvalidArgumentException si `bulk` a déjà été exécuté. Les objets MongoDB\Driver\BulkWrite ne peuvent pas être exécutés plusieurs fois.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une exception MongoDB\Driver\BulkWriteException lors d'une erreur d'une opération en écriture (une erreur WriteError et WriteConcern)
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Le paramètre `options` n'accepte plus une instance de MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Passer un objet MongoDB\Driver\WriteConcern en tant qu'`options` est obsolète et sera supprimé dans la 2.0.
PECL mongodb 1.4.4 | Une MongoDB\Driver\Exception\InvalidArgumentException sera lancée si l'option `"session"` est utilisée en combinaison avec un `"writeConcern"` non-acknowledged.
PECL mongodb 1.4.0 | Le troisième paramètre est maintenant un tableau d'`options`. Pour des raisons de compatibilité ascendante, ce paramètre acceptera toujours un objet MongoDB\Driver\WriteConcern.
PECL mongodb 1.3.0 | Une MongoDB\Driver\Exception\InvalidArgumentException est maintenant lancée si `bulk` ne contient aucune opération d'écriture. Précédemment, une MongoDB\Driver\Exception\BulkWriteException était lancée.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\Manager::executeBulkWrite()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite();

    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);

    $bulk->update(['x' => 2], ['$set' => ['x' => 1]], ['multi' => false, 'upsert' => false]);
    $bulk->update(['x' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);
    $bulk->update(['_id' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);

    $bulk->insert(['_id' => 4, 'x' => 2]);

    $bulk->delete(['x' => 1], ['limit' => 1]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 100);
    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Matched  %d document(s)\n", $result->getMatchedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());
    printf("Upserted %d document(s)\n", $result->getUpsertedCount());
    printf("Deleted  %d document(s)\n", $result->getDeletedCount());

    foreach ($result->getUpsertedIds() as $index => $id) {
        printf('upsertedId[%d]: ', $index);
        var_dump($id);
    }

    /* Si le WriteConcern n'a pas pu être satisfait */
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf("%s (%d): %s\n", $writeConcernError->getMessage(), $writeConcernError->getCode(), var_export($writeConcernError->getInfo(), true));
    }

    /* Si une écriture n'a pas pu se faire du tout */
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Operation#%d: %s (%d)\n", $writeError->getIndex(), $writeError->getMessage(), $writeError->getCode());
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Inserted 3 document(s)
    Matched  1 document(s)
    Updated  1 document(s)
    Upserted 2 document(s)
    Deleted  1 document(s)
    upsertedId[3]: object(MongoDB\BSON\ObjectId)#5 (1) {
      ["oid"]=>
      string(24) "54d3adc3ce7a792f4d703756"
    }
    upsertedId[4]: int(3)

### Voir aussi

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWrite() - Exécute une ou plusieurs opérations d'écriture sur ce serveur

# MongoDB\Driver\Manager::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Manager::executeBulkWriteCommand — Exécute les opérations d'écriture en utilisant la commande bulkWrite

### Description

final public function MongoDB\Driver\Manager::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Exécute une ou plusieurs opérations d'écriture sur le serveur principal en utilisant la commande » bulkWrite introduite dans MongoDB 8.0.

Une MongoDB\Driver\BulkWriteCommand peut être construite avec une ou plusieurs opérations d'écriture de types variés (par exemple, des insertions, des mises à jour et des suppressions). Chaque opération d'écriture peut cibler une différente collection.

La valeur par défaut pour l'option `"writeConcern"` sera déduite d'une transaction active (indiquée par l'option `"session"`), suivie de l'URI de connexion.

### Liste de paramètres

`bulk` (MongoDB\Driver\BulkWriteCommand)
  Écriture(s) à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

### Valeurs de retour

Retourne un MongoDB\Driver\BulkWriteCommandResult en cas de succès.

### Erreurs / Exceptions

- Lance une MongoDB\Driver\Exception\InvalidArgumentException si `bulk` ne contient pas d'opérations d'écriture valides.
- Lance une MongoDB\Driver\Exception\InvalidArgumentException si `bulk` a déjà été exécutée. Les objets MongoDB\Driver\BulkWriteCommand ne peuvent pas être exécutés plusieurs fois.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une exception MongoDB\Driver\Exception\BulkWriteCommandException lors d'une erreur d'écriture (par exemple, échec de commande, erreur d'écriture ou d'écriture préoccupante)
- Lance MongoDB\Driver\Exception\RuntimeException en cas d'autre erreur.

### Exemples

Exemple #1 Opérations d'écriture mixtes

Les opérations d'écriture mixées (par exemple, insertion, mise à jour et suppression) seront envoyées au serveur en utilisant une seule commande » bulkWrite

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Supprime les documents des deux collections
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Ajoute les documents des deux collections
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Met à jour un document dans "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());

    ?>

L'exemple ci-dessus va afficher :

    Inserted 3 document(s)
    Updated  1 document(s)

Exemple #2 Opération d'écriture ordonnée qui provoque une erreur

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Inserted %d document(s)\n", $result->getInsertedCount());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Inserted 2 document(s)

### Voir aussi

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWriteCommand() - Exécute des opérations d'écriture sur ce serveur en utilisant la commande bulkWrite

# MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommand — Exécute une commande de base de données

### Description

final public function MongoDB\Driver\Manager::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Sélectionne un serveur en fonction de l'option `"readPreference"` et exécute la commande sur ce serveur.

Cette méthode n'applique aucune logique spéciale à la commande. Les valeurs par défaut des options `"readPreference"`, `"readConcern"` et `"writeConcern"` seront déduites à partir d'une transaction active (indiquée par l'option `"session"`). S'il n'y a pas de transaction active, une préférence de lecture primaire sera utilisée pour la sélection du serveur.

Les valeurs par défaut ne seront pas déduites à partir de l'URI de connexion. Il est donc recommandé aux utilisateurs d'utiliser des méthodes de commande de lecture et/ou d'écriture spécifiques si possible.

### Liste de paramètres

`db` (string)
  Le nom de la base de données sur laquelle la commande sera exécutée.
`command` (MongoDB\Driver\Command)
  La commande à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Une préoccupation de lecture à appliquer à l'opération. Cette option est disponible dans MongoDB 3.2+ et se traduira par une exception au moment de l'exécution si elle est spécifiée pour une version plus ancienne du serveur.
  readPreference | MongoDB\Driver\ReadPreference | Une préférence de lecture à utiliser pour sélectionner un serveur pour l'opération.
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

  Avertissement

  Si vous utilisez une `"session"` qui a une transaction en cours, vous ne pouvez pas spécifier l'option `"readConcern"` ou `"writeConcern"`. Tenter de faire ceci lancera une exception MongoDB\Driver\Exception\InvalidArgumentException. À la place vous devriez définir ces options quand vous créez la transaction avec MongoDB\Driver\Session::startTransaction().

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs (par exemple: commande invalide, délivrance d'une commande d'écriture à un secondaire).

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Le paramètre `options` n'accepte plus une instance de MongoDB\Driver\ReadPreference.
PECL mongodb 1.21.0 | Passer un objet MongoDB\Driver\ReadPreference en tant qu'`options` est obsolète et sera supprimé dans la 2.0.
PECL mongodb 1.4.4 | Une MongoDB\Driver\Exception\InvalidArgumentException sera lancée si l'option `"session"` est utilisée en combinaison avec une préférence d'écriture non reconnue.
PECL mongodb 1.4.0 | Ce troisième paramètre est maintenant un tableau d'`options`. Pour des raisons de compatibilité ascendante, ce paramètre acceptera toujours un objet MongoDB\Driver\ReadPreference.

### Exemples

Exemple #1 MongoDB\Driver\Manager::executeCommand() avec une commande retournant un seul document de résultat

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $command = new MongoDB\Driver\Command(['ping' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* La commande ping retourne un seul document de résultat, nous devons donc
     * accéder au premier résultat dans le curseur. */
    $response = $cursor->toArray()[0];

    var_dump($response);

    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["ok"]=>
      float(1)
    }

Exemple #2 MongoDB\Driver\Manager::executeCommand() avec une commande retournant un curseur

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1, 'y' => 'foo']);
    $bulk->insert(['x' => 2, 'y' => 'bar']);
    $bulk->insert(['x' => 3, 'y' => 'bar']);
    $manager->executeBulkWrite('db.collection', $bulk);

    $command = new MongoDB\Driver\Command([
        'aggregate' => 'collection',
        'pipeline' => [
            ['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
        ],
        'cursor' => new stdClass,
    ]);
    $cursor = $manager->executeCommand('db', $command);

    /* La commande d'agrégation peut éventuellement retourner ses résultats dans
     * un curseur au lieu d'un seul document de résultat. Dans ce cas, nous pouvons
     * itérer directement sur le curseur pour accéder à ces résultats. */
    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

L'exemple ci-dessus va afficher :

    object(stdClass)#6 (2) {
      ["_id"]=>
      string(3) "bar"
      ["sum"]=>
      int(10)
    }
    object(stdClass)#7 (2) {
      ["_id"]=>
      string(3) "foo"
      ["sum"]=>
      int(2)
    }

Exemple #3 Limiter le temps d'exécution d'une commande

Le temps d'exécution d'une commande peut être limité en spécifiant une valeur pour `"maxTimeMS"` dans le document MongoDB\Driver\Command. Il est à noter que cette limite de temps est appliquée côté serveur et ne prend pas en compte la latence du réseau. Voir » Terminer les opérations en cours dans le manuel MongoDB pour plus d'informations.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $command = new MongoDB\Driver\Command([
        'count' => 'collection',
        'query' => ['x' => ['$gt' => 1]],
        'maxTimeMS' => 1000,
    ]);

    $cursor = $manager->executeCommand('db', $command);

    var_dump($cursor->toArray()[0]);

    ?>

Si la commande ne parvient pas à se terminer après une seconde d'exécution sur le serveur, une MongoDB\Driver\Exception\ExecutionTimeoutException sera lancée.

### Notes

> Note: Si un `readPreference` secondaire est utilisé, il est de la responsabilité de l'appelant de s'assurer que la `command` peut être exécutée sur un secondaire. Aucune validation n'est effectuée par le pilote.

> Note: Cette méthode n'utilise pas par défaut la préférence de lecture de l'URI de connexion MongoDB. Les applications qui en ont besoin devraient envisager d'utiliser MongoDB\Driver\Manager::executeReadCommand().

### Voir aussi

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeReadCommand() - Exécute une commande de base de données qui lit
- MongoDB\Driver\Manager::executeReadWriteCommand() - Exécute une commande de base de données qui lit et écrit
- MongoDB\Driver\Manager::executeWriteCommand() - Exécute une commande de base de données qui écrit
- MongoDB\Driver\Server::executeCommand() - Exécute une commande de base de données sur ce serveur

# MongoDB\Driver\Manager::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeQuery — Exécute une requête de base de données

### Description

final public function MongoDB\Driver\Manager::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Sélectionne un serveur en fonction de l'option `"readPreference"` et exécute la requête sur ce serveur.

Les valeurs par défaut de l'option `"readPreference"` et de l'option `"readConcern"` de la requête seront déduites à partir d'une transaction active (indiquée par l'option `"session"`), suivie de l'URI de connexion.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`query` (MongoDB\Driver\Query)
  La requête à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Une préférence de lecture à utiliser pour sélectionner un serveur pour l'opération.
  session | MongoDB\Driver\Session | Une session à associer à l'opération.

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs (par exemple: opérateurs de requête invalides).

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Le paramètre `options` n'accepte plus une instance de MongoDB\Driver\ReadPreference.
PECL mongodb 1.21.0 | Passer un objet MongoDB\Driver\ReadPreference en tant qu'`options` est obsolète et sera supprimé dans la 2.0.
PECL mongodb 1.4.0 | Le troisième paramètre est maintenant un tableau `options`. Pour des raisons de compatibilité ascendante, ce paramètre acceptera toujours un objet MongoDB\Driver\ReadPreference.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\Manager::executeQuery()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'projection' => ['_id' => 0],
        'sort' => ['x' => -1],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

L'exemple ci-dessus va afficher :

    object(stdClass)#6 (1) {
      ["x"]=>
      int(3)
    }
    object(stdClass)#7 (1) {
      ["x"]=>
      int(2)
    }

Exemple #2 Limiter le temps d'exécution d'une requête

L'option `"maxTimeMS"` de la classe MongoDB\Driver\Query peut être utilisée pour limiter le temps d'exécution d'une requête. Il est à noter que cette limite de temps est appliquée côté serveur et ne prend pas en compte la latence réseau. Voir » Terminer les opérations en cours dans le manuel MongoDB pour plus d'informations.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'maxTimeMS' => 1000,
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Si la requête ne parvient pas à se terminer après une seconde d'exécution sur le serveur, une MongoDB\Driver\Exception\ExecutionTimeoutException sera lancée.

### Voir aussi

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Server::executeQuery() - Exécute une requête de base de données sur ce serveur

# MongoDB\Driver\Manager::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadCommand — Exécute une commande de base de données qui lit

### Description

final public function MongoDB\Driver\Manager::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Sélectionne un serveur en fonction de l'option `"readPreference"` et exécute la commande sur ce serveur.

Cette méthode appliquera une logique spécifique aux commandes qui lisent (par exemple » distinct). Les valeurs par défaut des options `"readPreference"` et `"readConcern"` seront déduites à partir d'une transaction active (indiquée par l'option `"session"`), suivie de l' URI de connexion.

### Liste de paramètres

`db` (string)
  Le nom de la base de données sur laquelle la commande sera exécutée.
`command` (MongoDB\Driver\Command)
  La commande à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Une préoccupation de lecture à appliquer à l'opération. Cette option est disponible dans MongoDB 3.2+ et se traduira par une exception au moment de l'exécution si elle est spécifiée pour une version plus ancienne du serveur.
  readPreference | MongoDB\Driver\ReadPreference | Une préférence de lecture à utiliser pour sélectionner un serveur pour l'opération.
  session | MongoDB\Driver\Session | Une session à associer à l'opération.

  Avertissement

  Si vous utilisez une `"session"` qui a une transaction en cours, vous ne pouvez pas spécifier l'option `"readConcern"` ou `"writeConcern"`. Tenter de faire ceci lancera une exception MongoDB\Driver\Exception\InvalidArgumentException. À la place vous devriez définir ces options quand vous créez la transaction avec MongoDB\Driver\Session::startTransaction().

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs (par exemple: commande invalide).

### Voir aussi

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Exécute une commande de base de données
- MongoDB\Driver\Manager::executeReadWriteCommand() - Exécute une commande de base de données qui lit et écrit
- MongoDB\Driver\Manager::executeWriteCommand() - Exécute une commande de base de données qui écrit
- MongoDB\Driver\Server::executeReadCommand() - Exécute une commande de base de données qui lit sur ce serveur

# MongoDB\Driver\Manager::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadWriteCommand — Exécute une commande de base de données qui lit et écrit

### Description

final public function MongoDB\Driver\Manager::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Exécute une commande sur le serveur primaire.

Cette méthode appliquera une logique spécifique aux commandes qui lisent et écrivent (par exemple » aggregate). Les valeurs par défaut des options `"readConcern"` et `"writeConcern"` seront déduites à partir d'une transaction active (indiquée par l'option `"session"`), suivie de l' URI de connexion.

### Liste de paramètres

`db` (string)
  Le nom de la base de données sur laquelle la commande sera exécutée.
`command` (MongoDB\Driver\Command)
  La commande à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Une préoccupation de lecture à appliquer à l'opération. Cette option est disponible dans MongoDB 3.2+ et se traduira par une exception au moment de l'exécution si elle est spécifiée pour une version plus ancienne du serveur.
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

  Avertissement

  Si vous utilisez une `"session"` qui a une transaction en cours, vous ne pouvez pas spécifier l'option `"readConcern"` ou `"writeConcern"`. Tenter de faire ceci lancera une exception MongoDB\Driver\Exception\InvalidArgumentException. À la place vous devriez définir ces options quand vous créez la transaction avec MongoDB\Driver\Session::startTransaction().

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs (par exemple: commande invalide).

### Historique

Version | Description
--- | ---
PECL mongodb 1.4.4 | Une MongoDB\Driver\Exception\InvalidArgumentException sera lancée si l'option `"session"` est utilisée en combinaison avec un critère de lecture ou d'écriture non reconnu.

### Voir aussi

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Exécute une commande de base de données
- MongoDB\Driver\Manager::executeReadCommand() - Exécute une commande de base de données qui lit
- MongoDB\Driver\Manager::executeWriteCommand() - Exécute une commande de base de données qui écrit
- MongoDB\Driver\Server::executeReadWriteCommand() - Exécute une commande de base de données qui lit et écrit sur ce serveur

# MongoDB\Driver\Manager::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeWriteCommand — Exécute une commande de base de données qui écrit

### Description

final public function MongoDB\Driver\Manager::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Exécute la commande sur le serveur primaire.

Cette méthode appliquera une logique spécifique aux commandes qui écrivent (par exemple » drop). Les valeurs par défaut de l'option `"writeConcern"` seront déduites à partir d'une transaction active (indiquée par l'option `"session"`), suivie de l'URI de connexion.

> Note: Cette méthode n'est pas destinée à être utilisée pour exécuter » insert, » update, ou » delete. Il est recommandé aux utilisateurs d'utiliser MongoDB\Driver\Manager::executeBulkWrite() pour ces opérations.

### Liste de paramètres

`db` (string)
  Le nom de la base de données sur laquelle la commande sera exécutée.
`command` (MongoDB\Driver\Command)
  La commande à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

  Avertissement

  Si vous utilisez une `"session"` qui a une transaction en cours, vous ne pouvez pas spécifier l'option `"readConcern"` ou `"writeConcern"`. Tenter de faire ceci lancera une exception MongoDB\Driver\Exception\InvalidArgumentException. À la place vous devriez définir ces options quand vous créez la transaction avec MongoDB\Driver\Session::startTransaction().

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs (par exemple: commande invalide).

### Historique

Version | Description
--- | ---
PECL mongodb 1.4.4 | Une MongoDB\Driver\Exception\InvalidArgumentException sera lancée si l'option `"session"` est utilisée en combinaison avec un `"writeConcern"` non reconnu.

### Voir aussi

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Exécute une commande de base de données
- MongoDB\Driver\Manager::executeReadCommand() - Exécute une commande de base de données qui lit
- MongoDB\Driver\Manager::executeReadWriteCommand() - Exécute une commande de base de données qui lit et écrit
- MongoDB\Driver\Server::executeWriteCommand() - Exécute une commande de base de données qui écrit sur ce serveur

# MongoDB\Driver\Manager::getEncryptedFieldsMap

(mongodb >=1.14.0)

MongoDB\Driver\Manager::getEncryptedFieldsMap — Renvoie l'option de chiffrement automatique encryptedFieldsMap pour le Manager

### Description

final public function MongoDB\Driver\Manager::getEncryptedFieldsMap(): array|object|null

Renvoie l'option de chiffrement automatique `encryptedFieldsMap` pour le Manager, si spécifiée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'option de chiffrement automatique `encryptedFieldsMap` pour le Manager, ou `null` si elle n'a pas été spécifiée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Manager::__construct() - Crée un nouveau Manager MongoDB

# MongoDB\Driver\Manager::getReadConcern

(mongodb >=1.1.0)

MongoDB\Driver\Manager::getReadConcern — Renvoie le ReadConcern pour le Manager

### Description

final public function MongoDB\Driver\Manager::getReadConcern(): MongoDB\Driver\ReadConcern

Renvoie le MongoDB\Driver\ReadConcern pour le Manager, qui est dérivé de ses options URI. C'est le ReadConcern par défaut pour les requêtes et commandes exécutées sur le Manager.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le MongoDB\Driver\ReadConcern pour le Manager.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple MongoDB\Driver\Manager::getReadConcern()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readConcernLevel=local');
    var_dump($manager->getReadConcern());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\Driver\ReadConcern)#2 (0) {
    }
    object(MongoDB\Driver\ReadConcern)#1 (1) {
      ["level"]=>
      string(5) "local"
    }

### Voir aussi

- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Manager::__construct() - Crée un nouveau Manager MongoDB

# MongoDB\Driver\Manager::getReadPreference

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getReadPreference — Renvoie le ReadPreference pour le Manager

### Description

final public function MongoDB\Driver\Manager::getReadPreference(): MongoDB\Driver\ReadPreference

Renvoie le MongoDB\Driver\ReadPreference pour le Manager, qui est dérivé de ses options URI. C'est le ReadPreference par défaut pour les requêtes et commandes exécutées sur le Manager.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le MongoDB\Driver\ReadPreference pour le Manager.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\Manager::getReadPreference()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadPreference());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=');
    var_dump($manager->getReadPreference());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\Driver\ReadPreference)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(18) "secondaryPreferred"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#3 (2) {
          ["dc"]=>
          string(2) "ny"
          ["rack"]=>
          string(1) "1"
        }
        [1]=>
        object(stdClass)#4 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [2]=>
        object(stdClass)#5 (0) {
        }
      }
    }

### Voir aussi

- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::__construct() - Crée un nouveau Manager MongoDB

# MongoDB\Driver\Manager::getServers

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getServers — Retourner les serveurs auxquels ce gestionnaire est connecté

### Description

final public function MongoDB\Driver\Manager::getServers(): array

Retourne un tableau d'instances MongoDB\Driver\Server auxquelles ce gestionnaire est connecté.

> Note: Étant donné que le pilote se connecte paresseusement à la base de données, cette méthode peut retourner un tableau vide s'il est appelé avant d'exécuter une opération sur le MongoDB\Driver\Manager.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau d'instances MongoDB\Driver\Server auxquelles ce gestionnaire est connecté.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Manager::getServers()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    /* The driver connects to the database server lazily, so Manager::getServers()
     * may initially return an empty array. */
    var_dump($manager->getServers());

    $command = new MongoDB\Driver\Command(['ping' => 1]);
    $manager->executeCommand('db', $command);

    var_dump($manager->getServers());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(0) {
    }
    array(1) {
      [0]=>
      object(MongoDB\Driver\Server)#3 (10) {
        ["host"]=>
        string(9) "localhost"
        ["port"]=>
        int(27017)
        ["type"]=>
        int(1)
        ["is_primary"]=>
        bool(false)
        ["is_secondary"]=>
        bool(false)
        ["is_arbiter"]=>
        bool(false)
        ["is_hidden"]=>
        bool(false)
        ["is_passive"]=>
        bool(false)
        ["last_hello_response"]=>
        array(8) {
          ["isWritablePrimary"]=>
          bool(true)
          ["maxBsonObjectSize"]=>
          int(16777216)
          ["maxMessageSizeBytes"]=>
          int(48000000)
          ["maxWriteBatchSize"]=>
          int(1000)
          ["localTime"]=>
          object(MongoDB\BSON\UTCDateTime)#4 (1) {
            ["milliseconds"]=>
            int(1447267964517)
          }
          ["maxWireVersion"]=>
          int(3)
          ["minWireVersion"]=>
          int(0)
          ["ok"]=>
          float(1)
        }
        ["round_trip_time"]=>
        int(554)
      }
    }

### Voir aussi

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::selectServer() - Sélectionne un serveur correspondant à une préférence de lecture

# MongoDB\Driver\Manager::getWriteConcern

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getWriteConcern — Renvoie le WriteConcern pour le Manager

### Description

final public function MongoDB\Driver\Manager::getWriteConcern(): MongoDB\Driver\WriteConcern

Renvoie le MongoDB\Driver\WriteConcern pour le Manager, qui est dérivé de ses options URI. C'est le WriteConcern par défaut pour les écritures et commandes exécutées sur le Manager.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le MongoDB\Driver\WriteConcern pour le Manager.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\Manager::getWriteConcern()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getWriteConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?w=majority&wtimeoutMS=2000');
    var_dump($manager->getWriteConcern());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\Driver\WriteConcern)#2 (0) {
    }
    object(MongoDB\Driver\WriteConcern)#1 (2) {
      ["w"]=>
      string(8) "majority"
      ["wtimeout"]=>
      int(2000)
    }

### Voir aussi

- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::__construct() - Crée un nouveau Manager MongoDB

# MongoDB\Driver\Manager::removeSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::removeSubscriber — Enlève un observateur d'événements de surveillance de ce Manager

### Description

final public function MongoDB\Driver\Manager::removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Enlève un observateur d'événements de surveillance de ce Manager.

> Note: Si `subscriber` n'est pas déjà enregistré avec ce Manager, cette fonction ne fait rien.

### Liste de paramètres

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Un observateur d'événements de surveillance à enlever de ce Manager.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\removeSubscriber() - Retire un abonnement de surveillance d'événement global
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Manager::selectServer

(mongodb >=1.0.0)

MongoDB\Driver\Manager::selectServer — Sélectionne un serveur correspondant à une préférence de lecture

### Description

final public function MongoDB\Driver\Manager::selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server

Sélectionne un MongoDB\Driver\Server correspondant à `readPreference`. Si `readPreference` est `null` ou omis, le serveur primaire sera sélectionné par défaut. Cela peut être utilisé pour pré-sélectionner un serveur afin d'effectuer une vérification de version avant d'exécuter une opération.

> Note: Contrairement à MongoDB\Driver\Manager::getServers(), cette méthode initialisera les connexions de base de données et effectuera la découverte de serveurs si nécessaire. Voir la » Spécification de sélection de serveur pour plus d'informations.

### Liste de paramètres

`readPreference` (MongoDB\Driver\ReadPreference)
  Les préférences de lecture à utiliser pour sélectionner un serveur. Si `null` ou omis, le serveur primaire sera sélectionné par défaut.

### Valeurs de retour

Renvoie un MongoDB\Driver\Server correspondant à la préférence de lecture.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException si un serveur correspondant à la préférence de lecture n'a pas pu être trouvé.

### Historique

Version | Description
--- | ---
PECL mongodb 1.11.0 | Le `readPreference` est maintenant optionnel. Si `null` ou omis, le serveur primaire sera sélectionné par défaut.

### Voir aussi

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::getServers() - Retourner les serveurs auxquels ce gestionnaire est connecté
- » Spécification de sélection de serveur

# MongoDB\Driver\Manager::startSession

(mongodb >=1.4.0)

MongoDB\Driver\Manager::startSession — Démarre une nouvelle session client pour être utilisée avec ce client

### Description

final public function MongoDB\Driver\Manager::startSession(?array `$options` = `null`): MongoDB\Driver\Session

Crée une MongoDB\Driver\Session pour les options données. La session peut ensuite être spécifiée lors de l'exécution de commandes, de requêtes et d'opérations d'écriture.

> Note: Une MongoDB\Driver\Session ne peut être utilisée qu'avec le MongoDB\Driver\Manager à partir duquel elle a été créée.

### Liste de paramètres

`options`

  options
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  causalConsistency | bool | Configure la cohérence causale dans une session. Si `true`, chaque opération dans la session sera ordonnée de manière causale après l'opération de lecture ou d'écriture précédente. Définir à `false` pour désactiver la cohérence causale. Voir » Consistance causale dans le manuel MongoDB pour plus d'informations. | `true`
  defaultTransactionOptions | array | Les options par défaut à appliquer aux transactions nouvellement créées. Ces options sont utilisées sauf si elles sont remplacées lorsqu'une transaction est démarrée avec une valeur différente pour chaque option.
  options
  Option | Type | Description
  --- | --- | ---
  maxCommitTimeMS | integer | Le temps maximum en millisecondes pour permettre à une seule commande `commitTransaction` de s'exécuter. Si spécifié, `maxCommitTimeMS` doit être un entier 32 bits signé supérieur ou égal à zéro.
  readConcern | MongoDB\Driver\ReadConcern | Une préoccupation de lecture à appliquer à l'opération. Cette option est disponible dans MongoDB 3.2+ et se traduira par une exception au moment de l'exécution si elle est spécifiée pour une version plus ancienne du serveur.
  readPreference | MongoDB\Driver\ReadPreference | Une préférence de lecture à utiliser pour sélectionner un serveur pour l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.
  Cette option est disponible dans MongoDB 4.0+. | `[]`
  snapshot | bool | Configure les lectures instantanées dans une session. Si `true`, un horodatage sera obtenu à partir de la première opération de lecture prise en charge dans la session (c'est-à-dire `find`, `aggregate`, ou `distinct` non fragmenté). Les opérations de lecture ultérieures dans la session utiliseront ensuite un niveau de cohérence de lecture `"snapshot"` pour lire des données majoritairement engagées à partir de cet horodatage. Définissez à `false` pour désactiver les lectures instantanées. Les lectures instantanées nécessitent MongoDB 5.0+ et ne peuvent pas être utilisées avec la cohérence causale, les transactions ou les opérations d'écriture. Si `"snapshot"` est `true`, `"causalConsistency"` sera par défaut à `false`. Voir » Read Concern "instantanés" dans le manuel MongoDB pour plus d'informations. | `false`

### Valeurs de retour

Renvoie une MongoDB\Driver\Session.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\InvalidArgumentException si les options `"causalConsistency"` et `"snapshot"` sont toutes les deux `true`.
- Lance une MongoDB\Driver\Exception\RuntimeException si la session ne peut pas être créée (par exemple, libmongoc ne prend pas en charge le chiffrement).

### Historique

Version | Description
--- | ---
PECL mongodb 1.11.0 | L'option `"snapshot"` a été ajoutée.
PECL mongodb 1.6.0 | L'option `"maxCommitTimeMS"` a été ajoutée à `"defaultTransactionOptions"`.
PECL mongodb 1.5.0 | L'option `"defaultTransactionOptions"` a été ajoutée.

### Voir aussi

- MongoDB\Driver\Session
- » Consistance causale dans le manuel MongoDB

## Sommaire

- MongoDB\Driver\Manager::addSubscriber — Enregistre un observateur d'événements de surveillance avec ce manager
- MongoDB\Driver\Manager::__construct — Crée un nouveau Manager MongoDB
- MongoDB\Driver\Manager::createClientEncryption — Créer un nouvel objet ClientEncryption
- MongoDB\Driver\Manager::executeBulkWrite — Exécute une ou plusieurs opérations d'écriture
- MongoDB\Driver\Manager::executeBulkWriteCommand — Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\Manager::executeCommand — Exécute une commande de base de données
- MongoDB\Driver\Manager::executeQuery — Exécute une requête de base de données
- MongoDB\Driver\Manager::executeReadCommand — Exécute une commande de base de données qui lit
- MongoDB\Driver\Manager::executeReadWriteCommand — Exécute une commande de base de données qui lit et écrit
- MongoDB\Driver\Manager::executeWriteCommand — Exécute une commande de base de données qui écrit
- MongoDB\Driver\Manager::getEncryptedFieldsMap — Renvoie l'option de chiffrement automatique encryptedFieldsMap pour le Manager
- MongoDB\Driver\Manager::getReadConcern — Renvoie le ReadConcern pour le Manager
- MongoDB\Driver\Manager::getReadPreference — Renvoie le ReadPreference pour le Manager
- MongoDB\Driver\Manager::getServers — Retourner les serveurs auxquels ce gestionnaire est connecté
- MongoDB\Driver\Manager::getWriteConcern — Renvoie le WriteConcern pour le Manager
- MongoDB\Driver\Manager::removeSubscriber — Enlève un observateur d'événements de surveillance de ce Manager
- MongoDB\Driver\Manager::selectServer — Sélectionne un serveur correspondant à une préférence de lecture
- MongoDB\Driver\Manager::startSession — Démarre une nouvelle session client pour être utilisée avec ce client

# La classe MongoDB\Driver\Command

(mongodb >=1.0.0)

## Introduction

La classe MongoDB\Driver\Command est un objet de valeur qui représente une commande de base de données.

Pour fournir des Command Helpers, l'objet MongoDB\Driver\Command doit être composé.

## Synopsis de la classe

final class MongoDB\Driver\Command {
/* Méthodes */
final public function __construct(array|object `$document`, ?array `$commandOptions` = `null`)
}

## Exemples

Exemple #1 Composé MongoDB\Driver\Command pour fournir un assistant pour créer des collections

    <?php
    class CreateCollection {
        protected $cmd = array();

        function __construct($collectionName) {
            $this->cmd["create"] = (string) $collectionName;
        }
        function setCappedCollection($maxBytes, $maxDocuments = false) {
            $this->cmd["capped"] = true;
            $this->cmd["size"]   = (int) $maxBytes;

            if ($maxDocuments) {
                $this->cmd["max"] = (int) $maxDocuments;
            }
        }
        function usePowerOf2Sizes($bool) {
            if ($bool) {
                $this->cmd["flags"] = 1;
            } else {
                $this->cmd["flags"] = 0;
            }
        }
        function setFlags($flags) {
            $this->cmd["flags"] = (int) $flags;
        }
        function getCommand() {
            return new MongoDB\Driver\Command($this->cmd);
        }
        function getCollectionName() {
            return $this->cmd["create"];
        }
    }

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $createCollection = new CreateCollection("cappedCollection");
    $createCollection->setCappedCollection(64 * 1024);

    try {
        $command = $createCollection->getCommand();
        $cursor = $manager->executeCommand("databaseName", $command);
        $response = $cursor->toArray()[0];
        var_dump($response);

        $collstats = ["collstats" => $createCollection->getCollectionName()];
        $cursor = $manager->executeCommand("databaseName", new MongoDB\Driver\Command($collstats));
        $response = $cursor->toArray()[0];
        var_dump($response);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    ?>

L'exemple ci-dessus va afficher :

    object(MongoDB\Driver\Command)#3 (1) {
      ["command"]=>
      array(3) {
        ["create"]=>
        string(16) "cappedCollection"
        ["capped"]=>
        bool(true)
        ["size"]=>
        int(65536)
      }
    }
    array(1) {
      ["ok"]=>
      float(1)
    }
    array(16) {
      ["ns"]=>
      string(29) "databaseName.cappedCollection"
      ["count"]=>
      int(0)
      ["size"]=>
      int(0)
      ["numExtents"]=>
      int(1)
      ["storageSize"]=>
      int(65536)
      ["nindexes"]=>
      int(1)
      ["lastExtentSize"]=>
      float(65536)
      ["paddingFactor"]=>
      float(1)
      ["paddingFactorNote"]=>
      string(101) "paddingFactor is unused and unmaintained in 2.8. It remains hard coded to 1.0 for compatibility only."
      ["userFlags"]=>
      int(0)
      ["capped"]=>
      bool(true)
      ["max"]=>
      int(9223372036854775807)
      ["maxSize"]=>
      int(65536)
      ["totalIndexSize"]=>
      int(8176)
      ["indexSizes"]=>
      object(stdClass)#4 (1) {
        ["_id_"]=>
        int(8176)
      }
      ["ok"]=>
      float(1)
    }

# MongoDB\Driver\Command::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Command::__construct — Crée une nouvelle commande

### Description

final public function MongoDB\Driver\Command::__construct(array|object `$document`, ?array `$commandOptions` = `null`)

Construit un nouveau MongoDB\Driver\Command, qui est un objet valeur immuable qui représente une commande de base de données. La commande peut alors être exécutée avec MongoDB\Driver\Manager::executeCommand().

Le document de commande complet, qui inclut le nom de la commande et ses options, doit être exprimé dans le paramètre `document`. Le paramètre `commandOptions` est utilisé uniquement pour spécifier les options liées à l'exécution de la commande et le résultat MongoDB\Driver\Cursor.

### Liste de paramètres

`document`
  Le document de commande complet, qui sera envoyé au serveur.
`commandOptions`

  > Note: Ne pas utiliser ce paramètre pour spécifier les options décrites dans la référence de la commande dans le manuel MongoDB. Ce paramètre ne doit être utilisé que pour les options explicitement énumérées ci-dessous.

  commandOptions
  Option | Type | Description
  --- | --- | ---
  maxAwaitTimeMS | int | Entier positif indiquant la limite de temps en millisecondes pour que le serveur bloque une opération getMore si aucune donnée n'est disponible. Cette option ne doit être utilisée qu'en conjonction avec les commandes qui retournent un curseur à queue (par exemple » Change Streams).

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 1.4.0 | Ajout d'un deuxième argument `commandOptions`, qui prend en charge l'option `"maxAwaitTimeMS"`.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Command::__construct()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(array("buildinfo" => 1));

    try {
        $cursor = $manager->executeCommand("admin", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(13) {
      ["version"]=>
      string(14) "2.8.0-rc2-pre-"
      ["gitVersion"]=>
      string(62) "b743d7158f7642f4da6b7eac8320374b3b88dc2e modules: subscription"
      ["OpenSSLVersion"]=>
      string(25) "OpenSSL 1.0.1f 6 Jan 2014"
      ["sysInfo"]=>
      string(104) "Linux infant 3.16.0-24-generic #32-Ubuntu SMP Tue Oct 28 13:07:32 UTC 2014 x86_64 BOOST_LIB_VERSION=1_49"
      ["loaderFlags"]=>
      string(91) "-fPIC -pthread -Wl,-z,now -rdynamic -Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -Wl,-E"
      ["compilerFlags"]=>
      string(301) "-Wnon-virtual-dtor -Woverloaded-virtual -std=c++11 -fPIC -fno-strict-aliasing -ggdb -pthread -Wall -Wsign-compare -Wno-unknown-pragmas -Winvalid-pch -pipe -Werror -O3 -Wno-unused-local-typedefs -Wno-unused-function -Wno-deprecated-declarations -Wno-unused-but-set-variable -fno-builtin-memcmp -std=c99"
      ["allocator"]=>
      string(8) "tcmalloc"
      ["versionArray"]=>
      array(4) {
        [0]=>
        int(2)
        [1]=>
        int(8)
        [2]=>
        int(0)
        [3]=>
        int(-8)
      }
      ["javascriptEngine"]=>
      string(2) "V8"
      ["bits"]=>
      int(64)
      ["debug"]=>
      bool(false)
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["ok"]=>
      float(1)
    }

Exemple #2 Exemple avec MongoDB\Driver\Command::__construct()

Les commandes peuvent également accepter des options, dans le cadre de la structure normale qu'on crée pour envoyer au serveur. Par exemple, l'option `maxTimeMS` peut être passée avec la plupart des commandes pour restreindre la durée pendant laquelle une commande spécifique peut s'exécuter sur le serveur.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(
        array(
            "distinct" => "beer",
            "key" => "beer_name",
            "maxTimeMS" => 10,
        )
    );

    try {
        $cursor = $manager->executeCommand("beerdb", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

operation exceeded time limit

### Voir aussi

- MongoDB\Driver\Manager::executeCommand() - Exécute une commande de base de données
- MongoDB\Driver\Cursor

## Sommaire

- MongoDB\Driver\Command::__construct — Crée une nouvelle commande

# La classe MongoDB\Driver\Query

(mongodb >=1.0.0)

## Introduction

La classe MongoDB\Driver\Query est un objet de valeur qui représente une requête de base de données.

## Synopsis de la classe

final class MongoDB\Driver\Query {
/* Méthodes */
final public function __construct(array|object `$filter`, ?array `$queryOptions` = `null`)
}

# MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__construct — Créer une nouvelle requête

### Description

final public function MongoDB\Driver\Query::__construct(array|object `$filter`, ?array `$queryOptions` = `null`)

Construit un nouvel objet MongoDB\Driver\Query, qui est un objet de valeur immuable qui représente une requête de base de données. La requête peut ensuite être exécutée avec MongoDB\Driver\Manager::executeQuery().

### Liste de paramètres

`filter` (array|object)
  L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

  > Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

`queryOptions`

  queryOptions
  Option | Type | Description
  --- | --- | ---
  allowDiskUse | bool | Autorise MongoDB à utiliser des fichiers temporaires sur le disque pour stocker des données dépassant la limite de mémoire système de 100 mégaoctets lors du traitement d'une opération de tri bloquante.
  allowPartialResults | bool | Pour les requêtes sur une collection fragmentée, retourne des résultats partiels du mongos si certains fragments ne sont pas disponibles au lieu de générer une erreur. Retombe sur l'option dépréciée `"partial"` si non spécifiée.
  awaitData | bool | Utiliser en conjonction avec l'option `"tailable"` pour bloquer temporairement une opération getMore sur le curseur si à la fin des données plutôt que de ne pas retourner de données. Après une période d'attente, la requête se termine normalement.
  batchSize | int | Le nombre de documents à retourner dans le premier lot. Par défaut à 101. Une taille de lot de 0 signifie que le curseur sera établi, mais aucun document ne sera retourné dans le premier lot. Dans les versions de MongoDB antérieures à 3.2, où les requêtes utilisent le protocole de filaire hérité OP_QUERY, une taille de lot de 1 fermera le curseur indépendamment du nombre de documents.
  collation | array|object | » Collation permet aux utilisateurs de spécifier des règles spécifiques au langage pour la comparaison des chaînes, par exemple, des règles pour les majuscules ou les accents. Lors de la spécification d'une collation, le champ `"locale"` est obligatoire ; tous les autres champs de la collation sont optionnels. Pour la description de ces champs, reportez-vous au » document Collation. Si la collation n'est pas spécifiée mais que la collection a une collation par défaut, l'opération utilisera la collation spécifiée pour la collection. Si aucune collation n'est spécifiée pour la collection ou pour l'opération, MongoDB utilisera le binaire simple de comparaison utilisé dans les versions précédentes pour les comparaisons des chaînes. Cette option est disponible en MongoDB 3.4+ et une exception sera émise au moment de l'exécution si elle est spécifiée dans une version antérieure.
  comment | mixed | Un commentaire arbitraire pour aider à tracer l'opération à travers le profil de la base de données, la sortie currentOp et les journaux. Le commentaire peut être n'importe quel type BSON valide pour MongoDB 4.4+. Les versions de serveur antérieures ne prennent en charge que les valeurs de chaîne. Retombe sur l'option dépréciée `"$comment"` si non spécifiée.
  exhaust | bool | Le flux de données en aval à pleine puissance dans plusieurs paquets "more", en supposant que le client lira entièrement toutes les données interrogées. Plus rapide lorsqu'on tire beaucoup de données et qu'on sait qu'on veut tout tirer. Remarque : le client n'est pas autorisé à ne pas lire toutes les données sauf s'il ferme la connexion. Cette option n'est pas prise en charge par la commande find dans MongoDB 3.2+ et forcera le pilote à utiliser la version du protocole de filaire hérité (c'est-à-dire OP_QUERY).
  explain | bool | Si `true` le curseur MongoDB\Driver\Cursor retourné contiendra un seul document qui décrit le processus et les index utilisés pour retourner la requête. Retombe sur l'option dépréciée `"$explain"` si non spécifiée. Cette option n'est pas prise en charge par la commande find dans MongoDB 3.2+ et ne sera respectée que lors de l'utilisation de la version du protocole de filaire hérité (c'est-à-dire OP_QUERY). La commande » explain doit être utilisée sur MongoDB 3.0+.
  hint | string|array|object | Spécification de l'index. Spécifiez soit le nom de l'index en tant que chaîne, soit le modèle de clé d'index. Si spécifié, le système de requête ne considérera que les plans utilisant l'index suggéré. Retombe sur l'option dépréciée `"hint"` si non spécifiée.
  let | array|object | Dictionnaire des noms et des valeurs des paramètres. Les valeurs doivent être des constantes ou des expressions fermées qui ne font pas référence aux champs du document. Les paramètres peuvent ensuite être accédés en tant que variables dans un contexte d'expression agrégée (par exemple `$$var`). Cette option est disponible dans MongoDB 5.0+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version antérieure du serveur.
  limit | int | Le nombre maximum de documents à retourner. Si non spécifié, alors par défaut à aucune limite. Une limite de 0 est équivalente à ne pas définir de limite.
  max | array|object | La limite supérieure exclusive pour un index spécifique. Retombe sur l'option dépréciée `"$max"` si non spécifiée.
  maxAwaitTimeMS | int | Entier positif indiquant la limite de temps en millisecondes pour le serveur pour bloquer une opération getMore si aucune donnée n'est disponible. Cette option ne doit être utilisée qu'en conjonction avec les options `"tailable"` et `"awaitData"`.
  maxTimeMS | int | La limite de temps cumulative en millisecondes pour le traitement des opérations sur le curseur. MongoDB arrête l'opération au premier point d'interruption le plus proche. Retombe sur l'option dépréciée `"$maxTimeMS"` si non spécifiée.
  min | array|object | La limite inférieure inclusive pour un index spécifique. Retombe sur l'option dépréciée `"$min"` si non spécifiée.
  noCursorTimeout | bool | Empêche le serveur de mettre fin aux curseurs inactifs après une période d'inactivité (10 minutes).
  projection | array|object | Les » spécifications de projection pour déterminer quels champs inclure dans les documents retournés. Lors de l'utilisation de la fonctionnalité ODM pour désérialiser les documents en tant que leur classe PHP d'origine, il faut s'assurer d'inclure le champ __pclass dans la projection. Cela est nécessaire pour que la désérialisation fonctionne et sans cela, l'extension renverra (par défaut) un objet stdClass à la place.
  readConcern | MongoDB\Driver\ReadConcern | Un read concern à appliquer à l'opération. Par défaut, le read concern de l'URI de connexion MongoDB sera utilisé. Cette option est disponible dans MongoDB 3.2+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version de serveur plus ancienne.
  returnKey | bool | Si `true`, ne retourne que les clés d'index dans les documents résultants. La valeur par défaut est `false`. Si `true` et que la commande find n'utilise pas d'index, les documents retournés seront vides. Retombe sur l'option dépréciée `"$returnKey"` si non spécifiée.
  showRecordId | bool | Détermine si l'identifiant d'enregistrement doit être retourné pour chaque document. Si `true`, ajoute un champ `"$recordId"` de premier niveau aux documents retournés. Retombe sur l'option dépréciée `"$showDiskLoc"` si non spécifiée.
  singleBatch | bool | Détermine si le curseur doit être fermé après le premier lot. Par défaut à `false`.
  skip | int | Nombre de documents à sauter. Par défaut à 0.
  sort | array|object | La spécification de tri pour l'ordonnancement des résultats. Retombe sur l'option dépréciée `"$orderby"` si non spécifiée.
  tailable | bool | Renvoie un curseur tailable pour une collection capée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | L'option `"partial"` a été supprimée. Utiliser `"allowPartialResults"` à la place. L'option `"maxScan"` a été supprimée. Le support pour cette option a été supprimé dans MongoDB 4.2. L'option `"modifiers"` a été supprimée. Cette option était utilisée pour les modificateurs d'ancienne requête, qui sont tous dépréciés. L'option `"oplogReplay"` a été supprimée. Cela est ignoré dans MongoDB 4.4 et plus récent. L'option `"snapshot"` a été supprimée. Son support a été supprimé dans MongoDB 4.0. Une valeur négative pour l'option `"limit"` n'implique plus `true` pour l'option `"singleBatch"`. Pour ne recevoir qu'un seul lot de résultats, combinez une valeur positive `"limit"` avec l'option `"singleBatch"`.
PECL mongodb 1.14.0 | Ajout de l'option `"let"`. L'option `"comment"` accepte désormais n'importe quel type.
PECL mongodb 1.8.0 | Ajout de l'option `"allowDiskUse"`. L'option `"oplogReplay"` est dépréciée.
PECL mongodb 1.5.0 | Les options `"maxScan"` et `"snapshot"` sont dépréciées.
PECL mongodb 1.3.0 | Ajout de l'option `"maxAwaitTimeMS"`
PECL mongodb 1.2.0 | Ajout des options `"allowPartialResults"`, `"collation"`, `"comment"`, `"hint"`, `"max"`, `"maxScan"`, `"maxTimeMS"`, `"min"`, `"returnKey"`, `"showRecordId"`, et `"snapshot"`. Renommer l'option `"partial"` en `"allowPartialResults"`. Pour la compatibilité ascendante, `"partial"` sera toujours lu si `"allowPartialResults"` n'est pas spécifié. Supprime l'option `"secondaryOk"` obsolète. Pour les requêtes utilisant le protocole de filaire hérité OP_QUERY, le pilote définira le bit `secondaryOk` selon les besoins conformément à la » Spécification de sélection du serveur.
PECL mongodb 1.1.0 | Ajout de l'option `"readConcern"`.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\Query::__construct()

    <?php
    /* Sélectionne uniquement les documents écrits par "bjori" avec au moins 100 vues */
    $filter = [
        'author' => 'bjori',
        'views' => [
            '$gte' => 100,
        ],
    ];

    $options = [
        /* Retourne uniquement les champs suivants dans les documents correspondants */
        'projection' => [
            'title' => 1,
            'article' => 1,
        ],
        /* Retourne les documents dans l'ordre décroissant des vues */
        'sort' => [
            'views' => -1
        ],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $readPreference = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    $cursor = $manager->executeQuery('databaseName.collectionName', $query, ['readPreference' => $readPreference]);

    foreach($cursor as $document) {
        var_dump($document);
    }

    ?>

### Voir aussi

- MongoDB\Driver\Manager::executeQuery() - Exécute une requête de base de données
- MongoDB\Driver\Cursor

## Sommaire

- MongoDB\Driver\Query::__construct — Créer une nouvelle requête

# La classe MongoDB\Driver\BulkWrite

(mongodb >=1.0.0)

## Introduction

Le MongoDB\Driver\BulkWrite collecte une ou plusieurs opérations d'écriture qui devraient être envoyées au serveur. Après avoir ajouté un nombre quelconque d'opérations d'insertion, de mise à jour et de suppression, la collection peut être exécutée via MongoDB\Driver\Manager::executeBulkWrite().

Les opérations d'écriture peuvent être ordonnées (par défaut) ou non ordonnées. Les opérations d'écriture ordonnées sont envoyées au serveur, dans l'ordre fourni, pour une exécution sérielle. Si une écriture échoue, toutes les opérations restantes seront annulées. Les opérations non ordonnées sont envoyées au serveur dans un ordre arbitraire où elles peuvent être exécutées en parallèle. Toutes les erreurs qui se produisent sont signalées après que toutes les opérations ont été tentées.

## Synopsis de la classe

final class MongoDB\Driver\BulkWrite implements Countable {
/* Méthodes */
public function __construct(?array `$options` = `null`)
public function count(): int
public function delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void
public function insert(array|object `$document`): mixed
public function update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void
}

## Exemples

Exemple #1 Opérations d'écriture mixtes regroupées par type

Les opérations d'écriture mixtes (c'est-à-dire les insertions, les mises à jour et les suppressions) seront assemblées en commandes d'écriture typées à envoyer séquentiellement au serveur.

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->insert(['_id' => 3, 'x' => 3]);
    $bulk->delete(['x' => 1]);

    ?>

Résulte en quatre commandes d'écriture (c'est-à-dire des allers-retours) exécutées. Puisque les opérations sont ordonnées, la troisième insertion ne peut pas être envoyée avant que la mise à jour précédente ne soit exécutée.

Exemple #2 Opérations d'écriture ordonnées causant une erreur

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3, 'hello' => 'world']);
    $bulk->update(['_id' => 3], ['$set' => ['hello' => 'earth']]);
    $bulk->insert(['_id' => 4, 'hello' => 'pluto']);
    $bulk->update(['_id' => 4], ['$set' => ['hello' => 'moon']]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 5]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 1000);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Vérifie si l'écriture n'a pas pu être satisfaite
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Vérifie si une opération d'écriture n'a pas pu être complétée
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operation#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Other error: %s\n", $e->getMessage());
        exit;
    }

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());

    ?>

L'exemple ci-dessus va afficher :

    Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Inserted 4 document(s)
    Updated  2 document(s)

Si le write concern ne peut pas être satisfait, l'exemple ci-dessus affichera quelque chose comme:

    waiting for replication timed out (64): array (
      'wtimeout' => true,
    )
    Operation#7: E11000 duplicate key error index: databaseName.collectionName.$_id_ dup key: { : 3 } (11000)
    Inserted 4 document(s)
    Updated  2 document(s)

Si on exécute l'exemple ci-dessus, mais qu'on permet des écritures non ordonnées:

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    /* ... */

    ?>

L'exemple ci-dessus va afficher :

    Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Operation#8: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 4 } (11000)
    Inserted 5 document(s)
    Updated  2 document(s)

## Voir aussi

- MongoDB\Driver\Manager::executeBulkWrite()
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWrite::__construct

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::__construct — Créer un nouveau BulkWrite

### Description

public function MongoDB\Driver\BulkWrite::__construct(?array `$options` = `null`)

Construit un nouveau MongoDB\Driver\BulkWrite, qui est un objet mutable auquel une ou plusieurs opérations d'écriture peuvent être ajoutées. Les écritures peuvent ensuite être exécutées avec MongoDB\Driver\Manager::executeBulkWrite().

### Liste de paramètres

`options` (array)

  options
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  bypassDocumentValidation | bool | Si `true`, permet aux opérations d'insertion et de mise à jour de contourner la validation au niveau du document. Cette option est disponible dans MongoDB 3.2+ et est ignorée pour les anciennes versions du serveur, qui ne prennent pas en charge la validation au niveau du document. | `false`
  comment | mixed | Un commentaire arbitraire pour aider à tracer l'opération à travers le profil du serveur de base de données, la sortie currentOp et les journaux. Cette option est disponible dans MongoDB 4.4+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version de serveur plus ancienne.
  let | array|object | Dictionnaire des noms et des valeurs des paramètres. Les valeurs doivent être des constantes ou des expressions fermées qui ne font pas référence aux champs du document. Les paramètres peuvent ensuite être accédés en tant que variables dans un contexte d'expression agrégée (par exemple `$$var`). Cette option est disponible dans MongoDB 5.0+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version antérieure du serveur.
  ordered | bool | Les opérations ordonnées (`true`) sont exécutées séquentiellement sur le serveur MongoDB, tandis que les opérations non ordonnées (`false`) sont envoyées au serveur dans un ordre arbitraire et peuvent être exécutées en parallèle. | `true`

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 1.14.0 | Ajout des options `"comment"` et `"let"`.
PECL mongodb 1.1.0 | Ajout de l'option `"bypassDocumentValidation"`.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWrite::__construct()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(
        ['x' => 2],
        ['$set' => ['x' => 1]],
        ['limit' => 1, 'upsert' => false]
    );
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->update(
        ['_id' => 3],
        ['$set' => ['x' => 3]],
        ['limit' => 1, 'upsert' => true]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(1);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Vérifie si l'écriture n'a pas pu être effectuée
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Vérifie si certaines opérations d'écriture n'ont pas été effectuées du tout
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operation#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Other error: %s\n", $e->getMessage());
        exit;
    }

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());
    printf("Upserted %d document(s)\n", $result->getUpsertedCount());
    printf("Deleted  %d document(s)\n", $result->getDeletedCount());

    ?>

L'exemple ci-dessus va afficher :

    Inserted 2 document(s)
    Updated  1 document(s)
    Upserted 1 document(s)
    Deleted  1 document(s)

### Voir aussi

- MongoDB\Driver\Manager::executeBulkWrite() - Exécute une ou plusieurs opérations d'écriture
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::count

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::count — Compte le nombre d'opérations d'écriture dans le lot

### Description

public function MongoDB\Driver\BulkWrite::count(): int

Renvoie le nombre d'opérations d'écriture ajoutées à l'objet MongoDB\Driver\BulkWrite.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre d'opérations d'écriture ajoutées à l'objet MongoDB\Driver\BulkWrite.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 1.2.0 | Renvoie le nombre d'opérations d'écriture ajoutées à l'objet MongoDB\Driver\BulkWrite. Les versions antérieures renvoyaient le nombre d'aller-retours client-serveur nécessaires pour exécuter toutes les opérations d'écriture.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWrite::count()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->delete(['x' => 1]);

    var_dump(count($bulk));

    ?>

L'exemple ci-dessus va afficher :

    int(4)

# MongoDB\Driver\BulkWrite::delete

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::delete — Ajoute une opération de suppression au lot

### Description

public function MongoDB\Driver\BulkWrite::delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void

Ajoute une opération de suppression au MongoDB\Driver\BulkWrite.

### Liste de paramètres

`filter` (array|object)
  L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

  > Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

`deleteOptions`

  deleteOptions
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  collation | array|object | » Collation permet aux utilisateurs de spécifier des règles spécifiques au langage pour la comparaison des chaînes, par exemple, des règles pour les majuscules ou les accents. Lors de la spécification d'une collation, le champ `"locale"` est obligatoire ; tous les autres champs de la collation sont optionnels. Pour la description de ces champs, reportez-vous au » document Collation. Si la collation n'est pas spécifiée mais que la collection a une collation par défaut, l'opération utilisera la collation spécifiée pour la collection. Si aucune collation n'est spécifiée pour la collection ou pour l'opération, MongoDB utilisera le binaire simple de comparaison utilisé dans les versions précédentes pour les comparaisons des chaînes. Cette option est disponible en MongoDB 3.4+ et une exception sera émise au moment de l'exécution si elle est spécifiée dans une version antérieure.
  hint | string|array|object | Spécification d'index. Spécifiez soit le nom de l'index en tant que chaîne soit le modèle de clé d'index. Si spécifié, le système de requête ne considérera que les plans utilisant l'index suggéré. Cette option est disponible dans MongoDB 4.4+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version de serveur plus ancienne.
  limit | bool | Supprime tous les documents correspondants (`false`), ou seulement le premier document correspondant (`true`) | `false`

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 1.8.0 | Ajout de l'option `"hint"`.
PECL mongodb 1.2.0 | Ajout de l'option `"collation"`.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWrite::delete()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->delete(['x' => 2], ['limit' => 0]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Voir aussi

- MongoDB\Driver\Manager::executeBulkWrite() - Exécute une ou plusieurs opérations d'écriture
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::insert

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::insert — Ajoute une opération d'insertion au lot

### Description

public function MongoDB\Driver\BulkWrite::insert(array|object `$document`): mixed

Ajoute une opération d'insertion au MongoDB\Driver\BulkWrite.

### Liste de paramètres

`document` (array|object)
  Le document à insérer.

### Valeurs de retour

Renvoie l'`_id` du document inséré. Si le `document` n'avait pas d'`_id`, le MongoDB\BSON\ObjectId généré pour l'insertion sera renvoyé.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 1.3.0 | L'`_id` du document inséré est toujours renvoyé. Auparavant, la méthode ne renvoyait une valeur que si un MongoDB\BSON\ObjectId était généré.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWrite::insert()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insert($doc1);
    $id2 = $bulk->insert($doc2);
    $id3 = $bulk->insert($doc3);

    var_dump($id1, $id2, $id3);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
        string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Voir aussi

- MongoDB\Driver\Manager::executeBulkWrite() - Exécute une ou plusieurs opérations d'écriture
- MongoDB\Driver\WriteResult
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Persistable

# MongoDB\Driver\BulkWrite::update

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::update — Ajoute une opération de mise à jour au lot

### Description

public function MongoDB\Driver\BulkWrite::update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void

Ajoute une opération de mise à jour au MongoDB\Driver\BulkWrite.

### Liste de paramètres

`filter` (array|object)
  L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

  > Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

`newObj` (array|object)
  Un document contenant des opérateurs de mise à jour (par exemple `$set`), un document de remplacement (c'est-à-dire seulement des expressions `field:valeur`), ou une » pipeline d'agrégation.
`updateOptions`

  updateOptions
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  arrayFilters | array | Un tableau de documents de filtre qui détermine quels éléments de tableau à modifier pour une opération de mise à jour sur un champ de tableau. Voir » Spécifier des arrayFilters pour les opérations de mise à jour de tableau dans le manuel MongoDB pour plus d'informations. Cette option est disponible dans MongoDB 3.6+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version de serveur plus ancienne.
  collation | array|object | » Collation permet aux utilisateurs de spécifier des règles spécifiques au langage pour la comparaison des chaînes, par exemple, des règles pour les majuscules ou les accents. Lors de la spécification d'une collation, le champ `"locale"` est obligatoire ; tous les autres champs de la collation sont optionnels. Pour la description de ces champs, reportez-vous au » document Collation. Si la collation n'est pas spécifiée mais que la collection a une collation par défaut, l'opération utilisera la collation spécifiée pour la collection. Si aucune collation n'est spécifiée pour la collection ou pour l'opération, MongoDB utilisera le binaire simple de comparaison utilisé dans les versions précédentes pour les comparaisons des chaînes. Cette option est disponible en MongoDB 3.4+ et une exception sera émise au moment de l'exécution si elle est spécifiée dans une version antérieure.
  hint | string|array|object | Spécification d'index. Spécifiez soit le nom de l'index en tant que chaîne soit le modèle de clé d'index. Si spécifié, le système de requête ne considérera que les plans utilisant l'index suggéré. Cette option est disponible dans MongoDB 4.2+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version de serveur plus ancienne.
  multi | bool | Met à jour uniquement le premier document correspondant si `false`, ou tous les documents correspondants si `true`. Cette option ne peut pas être `true` si `newObj` est un document de remplacement. | `false`
  sort | array|object | Spécifie quel document l'opération met à jour si la requête correspond à plusieurs documents. Le premier document correspondant par l'ordre de tri sera mis à jour. Cette option ne peut pas être utilisée si `"multi"` est `true`. Cette option est disponible dans MongoDB 8.0+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version de serveur plus ancienne.
  upsert | bool | Si `filter` ne correspond pas à un document existant, insère un unique document. Le document sera créé à partir de `newObj` s'il s'agit d'un document de remplacement (c'est-à-dire aucun opérateurs de mise à jour); sinon, les opérateurs dans `newObj` seront appliqués à `filter` pour créer le nouveau document. | `false`

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 1.21.0 | Ajout de l'option `"sort"`.
PECL mongodb 1.7.0 | Ajout de l'option `"hint"`.
PECL mongodb 1.6.0 | Le paramètre `newObj` accepte désormais un pipeline d'agrégation. Cette fonctionnalité nécessite MongoDB 4.2+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version de serveur plus ancienne.
PECL mongodb 1.5.0 | Utiliser l'option `"arrayFilters"` entraînera une exception au moment de l'exécution si elle n'est pas prise en charge par le serveur. Auparavant, aucune exception n'était levée et l'option pouvait être ignorée.
PECL mongodb 1.4.0 | Ajout de l'option `"arrayFilters"`.
PECL mongodb 1.2.0 | Ajout de l'option `"collation"`.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWrite::update()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->update(
        ['x' => 2],
        ['$set' => ['y' => 3]],
        ['multi' => false, 'upsert' => false]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Voir aussi

- MongoDB\Driver\Manager::executeBulkWrite() - Exécute une ou plusieurs opérations d'écriture
- MongoDB\Driver\WriteResult

## Sommaire

- MongoDB\Driver\BulkWrite::__construct — Créer un nouveau BulkWrite
- MongoDB\Driver\BulkWrite::count — Compte le nombre d'opérations d'écriture dans le lot
- MongoDB\Driver\BulkWrite::delete — Ajoute une opération de suppression au lot
- MongoDB\Driver\BulkWrite::insert — Ajoute une opération d'insertion au lot
- MongoDB\Driver\BulkWrite::update — Ajoute une opération de mise à jour au lot

# La classe MongoDB\Driver\BulkWriteCommand

(mongodb >=2.1.0)

## Introduction

MongoDB\Driver\BulkWriteCommand récupère une ou plusieurs opérations d'écriture qui doivent être envoyées au serveur à l'aide de la commande » bulkWrite introduite dans MongoDB 8.0. Après avoir ajouté un nombre quelconque d'opérations d'écriture, d'opérations de modification et d'opérations de suppression, la commande peut être exécutée via MongoDB\Driver\Manager::executeBulkWriteCommand().

Contrairement à MongoDB\Driver\BulkWrite, où toutes les opérations d'écriture doivent cibler la même collection, chaque opération d'écriture dans MongoDB\Driver\BulkWriteCommand peut cibler une collection différente.

Les opérations d'écriture peuvent être triées (par défaut) ou non triées. Les opérations triées sont envoyées au serveur, dans l'ordre fourni, pour une exécution sérielle. Si une écriture échoue, toutes les opérations restantes seront annulées. Les opérations non triées sont envoyées au serveur dans un ordre arbitraire où elles peuvent être exécutées en parallèle. Toutes les erreurs qui se produisent sont signalées après que toutes les opérations ont été tentées.

## Synopsis de la classe

final class MongoDB\Driver\BulkWriteCommand implements Countable {
/* Méthodes */
public function __construct(?array `$options` = `null`)
public function count(): int
public function deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function insertOne(string `$namespace`, array|object `$document`): mixed
public function replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void
public function updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
public function updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
}

## Exemples

Exemple #1 Opérations d'écriture mixtes

Les opérations d'écriture mixtes (par exemple, insertions, mises à jour et suppressions) seront envoyées au serveur à l'aide d'une seule commande » bulkWrite.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Delete documents from both collections
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insert documents into two collections
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Update a document in "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("%d document(s) ont été inséré(s)\n", $result->getInsertedCount());
    printf("%d document(s) ont été mis à jour(s)\n", $result->getModifiedCount());

    ?>

L'exemple ci-dessus va afficher :

    3 document(s) ont été inséré(s)
    1 document(s) ont été mis à jour(s)

Exemple #2 Opérations d'écriture ordonnées causant une erreur

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("%d document(s) ont été inséré(s)\n", $result->getInsertedCount());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    2 document(s) ont été inséré(s)

## Voir aussi

- MongoDB\Driver\Manager::executeBulkWriteCommand()
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWriteCommand::__construct

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::__construct — Créer une nouvelle BulkWriteCommand

### Description

public function MongoDB\Driver\BulkWriteCommand::__construct(?array `$options` = `null`)

Construit une nouvelle MongoDB\Driver\BulkWriteCommand, qui peut être utilisée pour effectuer de nombreuses opérations d'insertions, de mises à jour et de suppressions sur plusieurs collections dans une seule requête à l'aide de la commande » bulkWrite introduite dans MongoDB 8.0. Cela diffère de MongoDB\Driver\BulkWrite, qui est supporté par toutes les versions du serveur mais limité à une seule collection.

Après que toutes les opérations d'écriture ont été ajoutées, cet objet peut être exécuté avec MongoDB\Driver\Manager::executeBulkWriteCommand().

### Liste de paramètres

`options` (array)

  options
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  bypassDocumentValidation | bool | Si `true`, permet aux opérations d'insertion et de mise à jour de contourner la validation au niveau du document. | `false`
  comment | mixed | Un commentaire arbitraire pour aider à tracer l'opération à travers le profileur de base de données, la sortie currentOp et les journaux.
  let | array|object | Dictionnaire des noms et des valeurs des paramètres. Les valeurs doivent être des constantes ou des expressions fermées qui ne font pas référence aux champs du document. Les paramètres peuvent ensuite être accédés en tant que variables dans un contexte d'expression agrégée (par exemple `$$var`). Cette option est disponible dans MongoDB 5.0+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version antérieure du serveur.
  ordered | bool | Si les opérations dans cette écriture groupée doivent être exécutées dans l'ordre dans lequel elles ont été spécifiées. Si `false`, les écritures continueront à être exécutées si une écriture individuelle échoue. Si `true`, les écritures s'arrêteront si une écriture individuelle échoue. | `true`
  verboseResults | bool | Si les détails des résultats de chaque opération réussie doivent être inclus dans le résultat dans la MongoDB\Driver\BulkWriteCommandResult retournée. | `false`

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommand::__construct()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Supprime les documents de deux collections
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Ajoute les documents de deux collections
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Modifie un document dans "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("%d document(s) ont été inséré(s)\n", $result->getInsertedCount());
    printf("%d document(s) ont été mis à jour(s)\n", $result->getModifiedCount());

    ?>

L'exemple ci-dessus va afficher :

    3 document(s) ont été inséré(s)
    1 document(s) ont été mis à jour(s)

### Voir aussi

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::count

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::count — Compte le nombre d'opérations d'écriture dans la BulkWriteCommand

### Description

public function MongoDB\Driver\BulkWriteCommand::count(): int

Renvoie le nombre d'opérations d'écriture ajoutées à l'objet MongoDB\Driver\BulkWriteCommand.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre d'opérations d'écriture ajoutées à l'objet MongoDB\Driver\BulkWriteCommand.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommand::count()

    <?php

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1, 'x' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2, 'x' => 2]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->deleteMany('db.coll', ['x' => 1]);

    var_dump(count($bulk));

    ?>

L'exemple ci-dessus va afficher :

    int(4)

# MongoDB\Driver\BulkWriteCommand::deleteMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteMany — Ajoute une opération deleteMany

### Description

public function MongoDB\Driver\BulkWriteCommand::deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Ajoute une opération deleteMany à la MongoDB\Driver\BulkWriteCommand. Tous les documents qui correspondent à `filter` dans la collection identifiée par `namespace` seront supprimés.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`filter` (array|object)
  L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

  > Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

`options`

  options
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  collation | array|object | » Collation permet aux utilisateurs de spécifier des règles spécifiques au langage pour la comparaison des chaînes, par exemple, des règles pour les majuscules ou les accents. Lors de la spécification d'une collation, le champ `"locale"` est obligatoire ; tous les autres champs de la collation sont optionnels. Pour la description de ces champs, reportez-vous au » document Collation. Si la collation n'est pas spécifiée mais que la collection a une collation par défaut, l'opération utilisera la collation spécifiée pour la collection. Si aucune collation n'est spécifiée pour la collection ou pour l'opération, MongoDB utilisera le binaire simple de comparaison utilisé dans les versions précédentes pour les comparaisons des chaînes. Cette option est disponible en MongoDB 3.4+ et une exception sera émise au moment de l'exécution si elle est spécifiée dans une version antérieure.
  hint | string|array|object | Spécification de l'index. Spécifiez soit le nom de l'index sous forme de chaîne ou le modèle de clé de l'index. Si spécifié, le système de requête ne considérera que les plans utilisant l'index suggéré.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommand::deleteMany()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', ['x' => ['$gt' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Voir aussi

- MongoDB\Driver\BulkWriteCommand::deleteOne() - Ajoute une opération deleteOne
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::deleteOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteOne — Ajoute une opération deleteOne

### Description

public function MongoDB\Driver\BulkWriteCommand::deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Ajoute une opération deleteOne à la MongoDB\Driver\BulkWriteCommand. Le premier document qui correspond à `filter` dans la collection identifiée par `namespace` sera supprimé.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`filter` (array|object)
  L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

  > Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

`options`

  options
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  collation | array|object | » Collation permet aux utilisateurs de spécifier des règles spécifiques au langage pour la comparaison des chaînes, par exemple, des règles pour les majuscules ou les accents. Lors de la spécification d'une collation, le champ `"locale"` est obligatoire ; tous les autres champs de la collation sont optionnels. Pour la description de ces champs, reportez-vous au » document Collation. Si la collation n'est pas spécifiée mais que la collection a une collation par défaut, l'opération utilisera la collation spécifiée pour la collection. Si aucune collation n'est spécifiée pour la collection ou pour l'opération, MongoDB utilisera le binaire simple de comparaison utilisé dans les versions précédentes pour les comparaisons des chaînes. Cette option est disponible en MongoDB 3.4+ et une exception sera émise au moment de l'exécution si elle est spécifiée dans une version antérieure.
  hint | string|array|object | Spécification de l'index. Spécifiez soit le nom de l'index sous forme de chaîne ou le modèle de clé de l'index. Si spécifié, le système de requête ne considérera que les plans utilisant l'index suggéré.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommand::deleteOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Voir aussi

- MongoDB\Driver\BulkWriteCommand::deleteMany() - Ajoute une opération deleteMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::insertOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::insertOne — Ajoute une opération insertOne

### Description

public function MongoDB\Driver\BulkWriteCommand::insertOne(string `$namespace`, array|object `$document`): mixed

Ajoute une opération insertOne à la MongoDB\Driver\BulkWriteCommand. Le document sera inséré dans la collection identifiée par `namespace`.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`document` (array|object)
  Le document à insérer.

### Valeurs de retour

Retourne le `_id` du document inséré. Si le `document` n'avait pas de `_id`, le MongoDB\BSON\ObjectId généré pour l'insertion sera retourné.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommand::insertOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insertOne('db.coll', $doc1);
    $id2 = $bulk->insertOne('db.coll', $doc2);
    $id3 = $bulk->insertOne('db.coll', $doc3);

    var_dump($id1, $id2, $id3);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Voir aussi

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON\ObjectId

# MongoDB\Driver\BulkWriteCommand::replaceOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::replaceOne — Ajoute une opération replaceOne

### Description

public function MongoDB\Driver\BulkWriteCommand::replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void

Ajoute une opération replaceOne à la MongoDB\Driver\BulkWriteCommand. Le premier document à correspondre à `filter` dans la collection identifiée par `namespace` sera remplacé.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`filter` (array|object)
  L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

  > Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

`replacement` (array|object)
  Un document de remplacement.
`options`

  options
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  collation | array|object | » Collation permet aux utilisateurs de spécifier des règles spécifiques au langage pour la comparaison des chaînes, par exemple, des règles pour les majuscules ou les accents. Lors de la spécification d'une collation, le champ `"locale"` est obligatoire ; tous les autres champs de la collation sont optionnels. Pour la description de ces champs, reportez-vous au » document Collation. Si la collation n'est pas spécifiée mais que la collection a une collation par défaut, l'opération utilisera la collation spécifiée pour la collection. Si aucune collation n'est spécifiée pour la collection ou pour l'opération, MongoDB utilisera le binaire simple de comparaison utilisé dans les versions précédentes pour les comparaisons des chaînes. Cette option est disponible en MongoDB 3.4+ et une exception sera émise au moment de l'exécution si elle est spécifiée dans une version antérieure.
  hint | string|array|object | Spécification de l'index. Spécifiez soit le nom de l'index sous forme de chaîne ou le modèle de clé de l'index. Si spécifié, le système de requête ne considérera que les plans utilisant l'index suggéré.
  sort | array|object | Spécifier quel document l'opération remplace si la requête correspond à plusieurs documents. Le premier document correspondant à l'ordre de tri sera remplacé.
  upsert | bool | Si `filter` ne correspond à aucun document, insère un document unique. Le document sera créé depuis `replacement`. | `false`

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommand::replaceOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->replaceOne('db.coll', ['x' => 1], ['x' => 1, 'y' => 2]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Voir aussi

- MongoDB\Driver\BulkWriteCommand::updateOne() - Ajoute une opération updateOne
- MongoDB\Driver\BulkWriteCommand::updateMany() - Ajoute une opération updateMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateMany — Ajoute une opération updateMany

### Description

public function MongoDB\Driver\BulkWriteCommand::updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Ajoute une opération updateMany à la MongoDB\Driver\BulkWriteCommand. Tous les documents correspondant à `filter` dans la collection identifiée par `namespace` seront mis à jour.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`filter` (array|object)
  L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

  > Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

`update` (array|object)
  Un document contenant soit des opérateurs de mise à jour (par exemple `$set`) ou une » pipeline d'agrégation.
`options`

  options
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  arrayFilters | array | Un tableau de documents de filtre qui détermine quels éléments de tableau à modifier pour une opération de mise à jour sur un champ de tableau. Voir » Spécifier arrayFilters pour les opérations de mise à jour de tableau dans le manuel MongoDB pour plus d'informations.
  collation | array|object | » Collation permet aux utilisateurs de spécifier des règles spécifiques au langage pour la comparaison des chaînes, par exemple, des règles pour les majuscules ou les accents. Lors de la spécification d'une collation, le champ `"locale"` est obligatoire ; tous les autres champs de la collation sont optionnels. Pour la description de ces champs, reportez-vous au » document Collation. Si la collation n'est pas spécifiée mais que la collection a une collation par défaut, l'opération utilisera la collation spécifiée pour la collection. Si aucune collation n'est spécifiée pour la collection ou pour l'opération, MongoDB utilisera le binaire simple de comparaison utilisé dans les versions précédentes pour les comparaisons des chaînes. Cette option est disponible en MongoDB 3.4+ et une exception sera émise au moment de l'exécution si elle est spécifiée dans une version antérieure.
  hint | string|array|object | Spécification de l'index. Spécifiez soit le nom de l'index sous forme de chaîne ou par le modèle de clé de l'index. Si spécifié, le système de requête ne considérera que les plans utilisant l'index suggéré.
  upsert | bool | Si `filter` ne correspond à aucun document existant, insérer un document unique. Le document sera créé en appliquant les opérateurs dans `update` à toutes les valeurs de champ dans `filter`. | `false`

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommand::updateMany()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateMany('db.coll', ['x' => ['$gt' => 1]], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Voir aussi

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Ajoute une opération replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany()
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateOne — Ajoute une opération updateOne

### Description

public function MongoDB\Driver\BulkWriteCommand::updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Ajoute une opération updateOne à la MongoDB\Driver\BulkWriteCommand. Le premier document à correspondre à `filter` dans la collection identifiée par `namespace` sera mis à jour.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`filter` (array|object)
  L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

  > Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

`update` (array|object)
  Un document contenant soit des opérateurs de mise à jour (par exemple `$set`) ou une » pipeline d'agrégation.
`options`

  options
  Option | Type | Description | Défaut
  --- | --- | --- | ---
  arrayFilters | array | Un tableau de documents de filtre qui détermine quels éléments de tableau doivent être modifiés pour une opération de mise à jour sur un champ de tableau. Voir » Spécifier arrayFilters pour les opérations de mise à jour de tableau dans la documentation MongoDB pour plus d'informations.
  collation | array|object | » Collation permet aux utilisateurs de spécifier des règles spécifiques au langage pour la comparaison des chaînes, par exemple, des règles pour les majuscules ou les accents. Lors de la spécification d'une collation, le champ `"locale"` est obligatoire ; tous les autres champs de la collation sont optionnels. Pour la description de ces champs, reportez-vous au » document Collation. Si la collation n'est pas spécifiée mais que la collection a une collation par défaut, l'opération utilisera la collation spécifiée pour la collection. Si aucune collation n'est spécifiée pour la collection ou pour l'opération, MongoDB utilisera le binaire simple de comparaison utilisé dans les versions précédentes pour les comparaisons des chaînes. Cette option est disponible en MongoDB 3.4+ et une exception sera émise au moment de l'exécution si elle est spécifiée dans une version antérieure.
  hint | string|array|object | Spécification de l'index. Spécifiez soit le nom de l'index sous forme de chaîne ou le modèle de clé de l'index. Si spécifié, le système de requête ne considérera que les plans utilisant l'index suggéré.
  sort | array|object | Spécifie quel document l'opération met à jour si la requête correspond à plusieurs documents. Le premier document correspondant à l'ordre de tri sera mis à jour.
  upsert | bool | Si `filter` ne correspond à aucun document existant, insérer un document unique. Le document sera créé en appliquant les opérateurs dans `update` à toutes les valeurs de champ dans `filter`. | `false`

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommand::updateOne()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Voir aussi

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Ajoute une opération replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany() - Ajoute une opération updateMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

## Sommaire

- MongoDB\Driver\BulkWriteCommand::__construct — Créer une nouvelle BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::count — Compte le nombre d'opérations d'écriture dans la BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::deleteMany — Ajoute une opération deleteMany
- MongoDB\Driver\BulkWriteCommand::deleteOne — Ajoute une opération deleteOne
- MongoDB\Driver\BulkWriteCommand::insertOne — Ajoute une opération insertOne
- MongoDB\Driver\BulkWriteCommand::replaceOne — Ajoute une opération replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany — Ajoute une opération updateMany
- MongoDB\Driver\BulkWriteCommand::updateOne — Ajoute une opération updateOne

# La classe MongoDB\Driver\Session

(mongodb >=1.4.0)

## Introduction

La classe MongoDB\Driver\Session représente une session client et est retournée par MongoDB\Driver\Manager::startSession(). Les commandes, les requêtes et les opérations d'écriture peuvent ensuite être associées à la session.

## Synopsis de la classe

final class MongoDB\Driver\Session {
/* Constantes */
const string TRANSACTION_NONE = none;
const string TRANSACTION_STARTING = starting;
const string TRANSACTION_IN_PROGRESS = in_progress;
const string TRANSACTION_COMMITTED = committed;
const string TRANSACTION_ABORTED = aborted;
/* Méthodes */
final public function abortTransaction(): void
final public function advanceClusterTime(array|object `$clusterTime`): void
final public function advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void
final public function commitTransaction(): void
final private function __construct()
final public function endSession(): void
final public function getClusterTime(): ?object
final public function getLogicalSessionId(): object
final public function getOperationTime(): ?MongoDB\BSON\Timestamp
final public function getServer(): ?MongoDB\Driver\Server
final public function getTransactionOptions(): ?array
final public function getTransactionState(): string
final public function isDirty(): bool
final public function isInTransaction(): bool
final public function startTransaction(?array `$options` = `null`): void
}

## Constantes pré-définies

`MongoDB\Driver\Session::TRANSACTION_NONE`
  Il n'y a pas de transaction en cours.
`MongoDB\Driver\Session::TRANSACTION_STARTING`
  Une transaction a été démarrée, mais aucune opération n'a été envoyée au serveur.
`MongoDB\Driver\Session::TRANSACTION_IN_PROGRESS`
  Une transaction est en cours.
`MongoDB\Driver\Session::TRANSACTION_COMMITTED`
  Une transaction a été validée.
`MongoDB\Driver\Session::TRANSACTION_ABORTED`
  Une transaction a été annulée.

# MongoDB\Driver\Session::abortTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::abortTransaction — Annule une transaction

### Description

final public function MongoDB\Driver\Session::abortTransaction(): void

Termine la transaction multi-document et annule toutes les modifications de données effectuées par les opérations dans la transaction. C'est-à-dire que la transaction se termine sans enregistrer aucune des modifications apportées par les opérations dans la transaction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\RuntimeException si la transaction ne peut pas être annulée (par exemple, une transaction n'a pas été démarrée).

### Voir aussi

- MongoDB\Driver\Manager::startSession() - Démarre une nouvelle session client pour être utilisée avec ce client
- MongoDB\Driver\Session::commitTransaction() - Valide la transaction
- MongoDB\Driver\Session::startTransaction() - Commence une transaction

# MongoDB\Driver\Session::advanceClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceClusterTime — Avance le temps du cluster pour cette session

### Description

final public function MongoDB\Driver\Session::advanceClusterTime(array|object `$clusterTime`): void

Avance le temps du cluster pour cette session. Si le temps du cluster est inférieur ou égal au temps du cluster actuel de la session, cette fonction ne fait rien.

En utilisant cette méthode en conjonction avec MongoDB\Driver\Session::advanceOperationTime() pour copier les temps du cluster et des opérations d'une autre session il est possible de s'assurer que les opérations dans cette session sont cohérentes avec la dernière opération dans l'autre session.

### Liste de paramètres

`clusterTime`
  Le temps du cluster est un document contenant un horodatage logique et une signature de serveur. Typiquement, cette valeur sera obtenue en appelant MongoDB\Driver\Session::getClusterTime() sur un autre objet de session.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Session::advanceOperationTime() - Avance le temps d'opération pour cette session
- MongoDB\Driver\Session::getClusterTime() - Renvoie le temps du cluster pour cette session

# MongoDB\Driver\Session::advanceOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceOperationTime — Avance le temps d'opération pour cette session

### Description

final public function MongoDB\Driver\Session::advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void

Avance le temps d'opération pour cette session. Si le temps d'opération est inférieur ou égal au temps d'opération actuel de la session, cette fonction ne fait rien.

En utilisant cette méthode en conjonction avec MongoDB\Driver\Session::advanceClusterTime() pour copier les temps d'opération et de cluster d'une autre session il est possible de s'assurer que les opérations dans cette session sont cohérentes avec la dernière opération dans l'autre session.

### Liste de paramètres

`operationTime`
  Le temps d'opération est un horodatage logique. Typiquement, cette valeur sera obtenue en appelant MongoDB\Driver\Session::getOperationTime() sur un autre objet de session.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Session::advanceClusterTime() - Avance le temps du cluster pour cette session
- MongoDB\Driver\Session::getClusterTime() - Renvoie le temps du cluster pour cette session

# MongoDB\Driver\Session::commitTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::commitTransaction — Valide la transaction

### Description

final public function MongoDB\Driver\Session::commitTransaction(): void

Sauvegarde les modifications apportées par les opérations dans la transaction multi-document et termine la transaction. Jusqu'à la validation, aucune des modifications de données apportées par les opérations dans la transaction n'est visible en dehors de la transaction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\CommandException si le serveur ne peut pas valider la transaction (par exemple, en raison de conflits, de problèmes de réseau). Si le document retourné par la méthode MongoDB\Driver\Exception\CommandException::getResultDocument() de l'exception contient un élément `"errorLabels"`, et que ce tableau contient une valeur `"TransientTransactionError"` ou `"UnknownTransactionCommitResult"`, il est sûr de re-essayer la totalité de la transaction. Dans les versions plus récentes de l'extension, MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() devrait être utilisé pour tester cette situation à la place.
- Lance une MongoDB\Driver\Exception\RuntimeException si la transaction ne peut pas être validée (par exemple, une transaction n'a pas été démarrée).

### Voir aussi

- MongoDB\Driver\Manager::startSession() - Démarre une nouvelle session client pour être utilisée avec ce client
- MongoDB\Driver\Session::abortTransaction() - Annule une transaction
- MongoDB\Driver\Session::startTransaction() - Commence une transaction
- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() - Retourne si un label d'erreur est associé avec une exception

# MongoDB\Driver\Session::__construct

(mongodb >=1.4.0)

MongoDB\Driver\Session::__construct — Créer une nouvelle session (inutilisée)

### Description

final private function MongoDB\Driver\Session::__construct()

Les objets MongoDB\Driver\Session sont retournés par MongoDB\Driver\Manager::startSession() et ne peuvent pas être construits directement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- MongoDB\Driver\Manager::startSession() - Démarre une nouvelle session client pour être utilisée avec ce client

# MongoDB\Driver\Session::endSession

(mongodb >=1.5.0)

MongoDB\Driver\Session::endSession — Termine une session

### Description

final public function MongoDB\Driver\Session::endSession(): void

Cette méthode ferme une session existante. Si une transaction était associée à cette session, la transaction sera annulée. Après avoir appelé cette méthode, les applications ne doivent pas invoquer d'autres méthodes sur la session.

> Note: Les sessions sont également fermées lors du ramassage de miettes. Il ne devrait pas être nécessaire d'appeler cette méthode dans des circonstances normales.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Manager::startSession() - Démarre une nouvelle session client pour être utilisée avec ce client
- MongoDB\Driver\Session::abortTransaction() - Annule une transaction
- MongoDB\Driver\Session::commitTransaction() - Valide la transaction
- MongoDB\Driver\Session::startTransaction() - Commence une transaction

# MongoDB\Driver\Session::getClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getClusterTime — Renvoie le temps du cluster pour cette session

### Description

final public function MongoDB\Driver\Session::getClusterTime(): ?object

Renvoie le temps du cluster pour cette session. Si la session n'a pas été utilisée pour une opération et MongoDB\Driver\Session::advanceClusterTime() n'a pas été appelé, le temps du cluster sera `null`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le temps du cluster pour cette session, ou `null` si la session n'a pas de temps du cluster.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Session::advanceClusterTime() - Avance le temps du cluster pour cette session

# MongoDB\Driver\Session::getLogicalSessionId

(mongodb >=1.4.0)

MongoDB\Driver\Session::getLogicalSessionId — Renvoie l'identifiant de session logique pour cette session

### Description

final public function MongoDB\Driver\Session::getLogicalSessionId(): object

Renvoie l'identifiant de session logique pour cette session, qui peut être utilisé pour identifier les opérations de cette session sur le serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de session logique pour cette session.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Session::getOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getOperationTime — Renvoie le temps d'opération pour cette session

### Description

final public function MongoDB\Driver\Session::getOperationTime(): ?MongoDB\BSON\Timestamp

Renvoie le temps d'opération pour cette session. Si la session n'a pas été utilisée pour une opération et MongoDB\Driver\Session::advanceOperationTime() n'a pas été appelé, le temps d'opération sera `null`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le temps d'opération pour cette session, ou `null` si la session n'a pas de temps d'opération.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Session::advanceOperationTime() - Avance le temps d'opération pour cette session

# MongoDB\Driver\Session::getServer

(mongodb >=1.6.0)

MongoDB\Driver\Session::getServer — Renvoie le serveur auquel cette session est épinglée

### Description

final public function MongoDB\Driver\Session::getServer(): ?MongoDB\Driver\Server

Renvoie le MongoDB\Driver\Server auquel cette session est épinglée. Si la session n'est pas épinglée à un serveur, `null` sera renvoyé.

La session d'épinglage est principalement utilisée pour les transactions éclatées, car toutes les commandes dans une transaction éclatée doivent être envoyées à la même instance mongos. Cette méthode est destinée à être utilisée par des bibliothèques construites au-dessus de l'extension pour permettre l'utilisation d'un serveur épinglé au lieu d'invoquer la sélection du serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le MongoDB\Driver\Server auquel cette session est épinglée, ou `null` si la session n'est pas épinglée à un serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Session::getTransactionOptions

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionOptions — Renvoie les options pour la transaction en cours

### Description

final public function MongoDB\Driver\Session::getTransactionOptions(): ?array

Renvoie les options pour la transaction en cours.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un array contenant les options de transaction actuelles, ou `null` si aucune transaction n'est en cours.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Session::getTransactionState() - Renvoie l'état de la transaction actuelle pour cette session

# MongoDB\Driver\Session::getTransactionState

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionState — Renvoie l'état de la transaction actuelle pour cette session

### Description

final public function MongoDB\Driver\Session::getTransactionState(): string

Renvoie l'état de la transaction pour cette session.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'état de la transaction actuelle pour cette session.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Session::isInTransaction() - Renvoie si une transaction multi-document est en cours
- MongoDB\Driver\Session::getTransactionOptions() - Renvoie les options pour la transaction en cours

# MongoDB\Driver\Session::isDirty

(mongodb >=1.13.0)

MongoDB\Driver\Session::isDirty — Renvoie si la session a été marquée comme sale

### Description

final public function MongoDB\Driver\Session::isDirty(): bool

Renvoie si la session a été marquée comme sale (c'est-à-dire qu'elle a été utilisée avec une commande qui a rencontré une erreur réseau).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie si la session a été marquée comme sale.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Session::isInTransaction

(mongodb >=1.6.0)

MongoDB\Driver\Session::isInTransaction — Renvoie si une transaction multi-document est en cours

### Description

final public function MongoDB\Driver\Session::isInTransaction(): bool

Renvoie si une transaction multi-document est actuellement en cours pour cette session. Une transaction est considérée comme "en cours" si elle a été démarrée mais n'a pas été validée ou annulée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si une transaction est actuellement en cours pour cette session, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Session::getTransactionState() - Renvoie l'état de la transaction actuelle pour cette session

# MongoDB\Driver\Session::startTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::startTransaction — Commence une transaction

### Description

final public function MongoDB\Driver\Session::startTransaction(?array `$options` = `null`): void

Commence une transaction multi-document associée à la session. À un moment donné, on ne peut avoir qu'une seule transaction ouverte pour une session. Après avoir commencé une transaction, l'objet de session doit être passé à chaque opération via l'option `"session"` (par exemple MongoDB\Driver\Manager::executeBulkWrite()) pour associer cette opération à la transaction.

Les transactions peuvent être confirmées via MongoDB\Driver\Session::commitTransaction(), et annulées avec MongoDB\Driver\Session::abortTransaction(). Les transactions sont également automatiquement annulées lorsque la session est fermée par le ramasse-miettes ou en appelant explicitement MongoDB\Driver\Session::endSession().

### Liste de paramètres

`options`
  Les options peuvent être passées en argument à cette méthode. Chaque élément de ce tableau d'options remplace l'option correspondante de l'option `"defaultTransactionOptions"`, si définie lors du démarrage de la session avec MongoDB\Driver\Manager::startSession().

  options
  Option | Type | Description
  --- | --- | ---
  maxCommitTimeMS | integer | Le temps maximum en millisecondes pour permettre à une seule commande `commitTransaction` de s'exécuter. Si spécifié, `maxCommitTimeMS` doit être un entier 32 bits signé supérieur ou égal à zéro.
  readConcern | MongoDB\Driver\ReadConcern | Une préoccupation de lecture à appliquer à l'opération. Cette option est disponible dans MongoDB 3.2+ et se traduira par une exception au moment de l'exécution si elle est spécifiée pour une version plus ancienne du serveur.
  readPreference | MongoDB\Driver\ReadPreference | Une préférence de lecture à utiliser pour sélectionner un serveur pour l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\CommandException si la transaction n'a pas pu être démarrée en raison d'un problème côté serveur (par exemple, un verrou n'a pas pu être obtenu).
- Lance une MongoDB\Driver\Exception\RuntimeException si la transaction n'a pas pu être démarrée (par exemple, une transaction était déjà en cours).

### Historique

Version | Description
--- | ---
PECL mongodb 1.6.0 | L'option `"maxCommitTimeMS"` a été ajoutée.

### Voir aussi

- MongoDB\Driver\Manager::startSession() - Démarre une nouvelle session client pour être utilisée avec ce client
- MongoDB\Driver\Session::commitTransaction() - Valide la transaction
- MongoDB\Driver\Session::abortTransaction() - Annule une transaction

## Sommaire

- MongoDB\Driver\Session::abortTransaction — Annule une transaction
- MongoDB\Driver\Session::advanceClusterTime — Avance le temps du cluster pour cette session
- MongoDB\Driver\Session::advanceOperationTime — Avance le temps d'opération pour cette session
- MongoDB\Driver\Session::commitTransaction — Valide la transaction
- MongoDB\Driver\Session::__construct — Créer une nouvelle session (inutilisée)
- MongoDB\Driver\Session::endSession — Termine une session
- MongoDB\Driver\Session::getClusterTime — Renvoie le temps du cluster pour cette session
- MongoDB\Driver\Session::getLogicalSessionId — Renvoie l'identifiant de session logique pour cette session
- MongoDB\Driver\Session::getOperationTime — Renvoie le temps d'opération pour cette session
- MongoDB\Driver\Session::getServer — Renvoie le serveur auquel cette session est épinglée
- MongoDB\Driver\Session::getTransactionOptions — Renvoie les options pour la transaction en cours
- MongoDB\Driver\Session::getTransactionState — Renvoie l'état de la transaction actuelle pour cette session
- MongoDB\Driver\Session::isDirty — Renvoie si la session a été marquée comme sale
- MongoDB\Driver\Session::isInTransaction — Renvoie si une transaction multi-document est en cours
- MongoDB\Driver\Session::startTransaction — Commence une transaction

# La classe MongoDB\Driver\ClientEncryption

(mongodb >=1.7.0)

## Introduction

La classe MongoDB\Driver\ClientEncryption gère la création de clés de données pour le chiffrement côté client, ainsi que le chiffrement et le déchiffrement manuels des valeurs.

## Synopsis de la classe

final class MongoDB\Driver\ClientEncryption {
/* Constantes */
const string AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC = AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic;
const string AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM = AEAD_AES_256_CBC_HMAC_SHA_512-Random;
const string ALGORITHM_INDEXED = Indexed;
const string ALGORITHM_UNINDEXED = Unindexed;
const string ALGORITHM_RANGE = Range;
const string QUERY_TYPE_EQUALITY = equality;
const string QUERY_TYPE_RANGE = range;
/* Méthodes */
final public function addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function __construct(array `$options`)
final public function createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function decrypt(MongoDB\BSON\Binary `$value`): mixed
final public function deleteKey(MongoDB\BSON\Binary `$keyId`): object
final public function encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function encryptExpression(array|object `$expr`, ?array `$options` = `null`): object
final public function getKey(MongoDB\BSON\Binary `$keyId`): ?object
final public function getKeyByAltName(string `$keyAltName`): ?object
final public function getKeys(): MongoDB\Driver\Cursor
final public function removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object
}

## Constantes pré-définies

`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC`
  Spécifie un algorithme pour » le chiffrement déterministe, qui est adapté aux requêtes.
`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM`
  Spécifie un algorithme pour » le chiffrement aléatoire.
`MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`
  Spécifie un algorithme pour une charge utile indexée et chiffrée, qui peut être utilisée avec le chiffrement de requêtes. Pour insérer ou interroger avec une charge utile indexée et chiffrée, le MongoDB\Driver\Manager doit être configuré avec l'option de pilote `"autoEncryption"`. L'option de chiffrement automatique `"bypassQueryAnalysis"` peut être `true`. L'option de chiffrement automatique `"bypassAutoEncryption"` doit être `false`.
`MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`
  Spécifie un algorithme pour une charge utile non indexée et chiffrée.
`MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  Spécifie un algorithme pour une charge utile chiffrée par plage, qui peut être utilisée avec le chiffrement de requêtes. Pour interroger avec une charge utile chiffrée par plage, le MongoDB\Driver\Manager doit être configuré avec l'option de pilote `"autoEncryption"`. L'option de chiffrement automatique `"bypassQueryAnalysis"` peut être `true`. L'option de chiffrement automatique `"bypassAutoEncryption"` doit être `false`.

  > Note: L'extension ne prend pas encore en charge les requêtes de plage pour les types de champ BSON Decimal128.

`MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`
  Spécifie un type de requête d'égalité, qui est utilisé en conjonction avec `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`.
`MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`
  Spécifie un type de requête de plage, qui est utilisé en conjonction avec `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Suppression de `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` et `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.20.0 | Ajout `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE` et `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`. Déprécié `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` et `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.16.0 | Ajout `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` et `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.14.0 | Ajout `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`, `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`, et `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`.

## Voir aussi

- MongoDB\Driver\Manager::createClientEncryption()

# MongoDB\Driver\ClientEncryption::addKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::addKeyAltName — Ajoute un nom alternatif à un document clé

### Description

final public function MongoDB\Driver\ClientEncryption::addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Ajoute `keyAltName` à l'ensemble des noms alternatifs pour le document clé avec l'UUID donné `keyId`.

### Liste de paramètres

`keyId`
  Une instance MongoDB\BSON\Binary avec le sous-type 4 (UUID) identifiant le document clé.
`keyAltName`
  Nom alternatif à ajouter au document clé.

### Valeurs de retour

Renvoie la version précédente du document clé, ou `null` si aucun document correspondant n'a été trouvé.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs.

### Voir aussi

- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Renvoie un document clé par un nom alternatif
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Enlève un nom alternatif d'un document clé

# MongoDB\Driver\ClientEncryption::__construct

(mongodb >=1.14.0)

MongoDB\Driver\ClientEncryption::__construct — Créer un nouvel objet ClientEncryption

### Description

final public function MongoDB\Driver\ClientEncryption::__construct(array `$options`)

Construit un nouvel objet MongoDB\Driver\ClientEncryption avec les options spécifiées.

### Liste de paramètres

`options`

  options
  Option | Type | Description
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | Le gestionnaire utilisé pour router les requêtes de clé de données. Cette option est requise (contrairement à MongoDB\Driver\Manager::createClientEncryption()).
  keyVaultNamespace | chaîne de caractères | Un nom d'espace complètement qualifié (par exemple `"databaseName.collectionName"`) dénotant la collection qui contient toutes les clés de données utilisé pour le chiffrement et déchiffrement. Cette option est requise.
  kmsProviders | tableau | Un document contenant la configuration d'un ou plusieurs fournisseurs KMS, qui sont utilisés pour chiffrer les clés de données. Les fournisseurs supporté sont `"aws"`, `"azure"`, `"gcp"` et `"local"`, et au moins un doit être spécifié. Si un document vide est spécifié pour `"aws"`, `"azure"`, ou `"gcp"`, le pilote tentera de configurer le fournisseur en utilisant » Automatic Credentials. Le format pour `"aws"` est le suivant :
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  Le format pour `"azure"` est le suivant :
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"

      }
  Le format pour `"gcp"` est le suivant :
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Defaults to "oauth2.googleapis.com"

      }
  Le format pour `"kmip"` est le suivant :
      kmip: {
          endpoint: <string>
      }
  Le format pour `"local"` est le suivant :
      local: {
          // 96-byte master key used to encrypt/decrypt data keys
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Un document contenant la configuration TLS d'un ou plusieurs fournisseurs KMS. Les fournisseurs supporté sont `"aws"`, `"azure"`, `"gcp"` et `"kmip"`. Tous les fournisseurs supportent les options suivantes :
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\RuntimeException si l'extension n'a pas été compilée avec le support libmongocrypt

### Historique

Version | Description
--- | ---
PECL mongodb 1.16.0 | Le fournisseur AWS KMS pour le chiffrement côté client accepte désormais une option `"sessionToken"`, qui peut être utilisée pour s'authentifier avec des informations d'identification AWS temporaires. Ajout de `"tlsDisableOCSPEndpointCheck"` à l'option `"tlsOptions"`. Si un document vide est spécifié pour le fournisseur KMS `"azure"` ou `"gcp"`, le pilote tentera de configurer le fournisseur en utilisant les » Les informations d'identification automatiques.
PECL mongodb 1.15.0 | Si un document vide est spécifié pour le fournisseur KMS `"aws"`, le pilote tentera de configurer le fournisseur en utilisant les » Les informations d'identification automatiques.

### Voir aussi

- MongoDB\Driver\Manager::createClientEncryption() - Créer un nouvel objet ClientEncryption
- » Le chiffrement côté client explicite (manuel) dans le manuel MongoDB

# MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::createDataKey — Créer un document clé

### Description

final public function MongoDB\Driver\ClientEncryption::createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary

Crée un nouveau document clé et l'insère dans la collection de coffre de clés.

### Liste de paramètres

`kmsProvider`
  Le fournisseur KMS (par exemple `"local"`, `"aws"`) qui sera utilisé pour chiffrer le nouveau document clé.
`options`

  Options de données de clé
  Option | Type | Description
  --- | --- | ---
  masterKey | array | Le document masterKey identifie une clé spécifique à KMS utilisée pour chiffrer le nouveau document clé. Cette option est requise à moins que `kmsProvider` soit `"local"`.
  Options du fournisseur `"aws"`
  Option | Type | Description
  --- | --- | ---
  region | string | Requis.
  key | string | Requis. Le nom de ressource Amazon (ARN) de la clé maîtresse du client AWS (CMK).
  endpoint | string | Optionnel. Un identifiant d'hôte alternatif pour envoyer les demandes KMS. Peut inclure le numéro de port.
  Options du fournisseur `"azure"`
  Option | Type | Description
  --- | --- | ---
  keyVaultEndpoint | string | Requis. Hôte avec port optionnel (par exemple, "example.vault.azure.net").
  keyName | string | Requis.
  keyVersion | string | Optionnel. Une version spécifique de la clé nommée. Par défaut, la version primaire de la clé est utilisée.
  Options du fournisseur `"gcp"`
  Option | Type | Description
  --- | --- | ---
  projectId | string | Requis.
  location | string | Requis.
  keyRing | string | Requis.
  keyName | string | Requis.
  keyVersion | string | Optionnel. Une version spécifique de la clé nommée. Par défaut, la version primaire de la clé est utilisée.
  endpoint | string | Optionnel. Hôte avec port optionnel. La valeur par défaut est "cloudkms.googleapis.com".
  Options du fournisseur `"kmip"`
  Option | Type | Description
  --- | --- | ---
  keyId | string | Optionnel. Identifiant unique d'un objet géré de 96 octets de données secrètes KMIP. S'il n'est pas spécifié, le pilote crée un objet géré aléatoire de 96 octets de données secrètes KMIP.
  endpoint | string | Optionnel. Hôte avec port optionnel.
  delegated | bool | Optionnel. Si vrai, cette clé devrait être déchiffrer par le serveur KMIP.
  keyAltNames | array | Une liste optionnelle de noms alternatifs de chaîne utilisés pour référencer une clé. Si une clé est créée avec des noms alternatifs, alors le chiffrement peut se référer à la clé par le nom alternatif unique au lieu de par `_id`.
  keyMaterial | MongoDB\BSON\Binary | Une valeur optionnelle de 96 octets à utiliser comme matériel de clé pour le document clé en cours de création. Si keyMaterial est donné, le matériel de clé personnalisé est utilisé pour chiffrer et déchiffrer les données. Sinon, le matériel de clé pour le nouveau document clé est généré à partir d'un dispositif aléatoire cryptographiquement sécurisé.

### Valeurs de retour

Renvoie un identifiant du nouveau document clé en tant qu'objet MongoDB\BSON\Binary avec le sous-type 4 (UUID).

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs.

### Historique

Version | Description
--- | ---
PECL mongodb 1.20.0 | Ajout de `"delegated"` aux options masterKey du fournisseur KMIP.
PECL mongodb 1.15.0 | Ajout de l'option `"keyMaterial"`.
PECL mongodb 1.10.0 | Azure et GCP sont désormais pris en charge en tant que fournisseurs KMS pour le chiffrement côté client.

# MongoDB\Driver\ClientEncryption::decrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::decrypt — Déchiffre une valeur

### Description

final public function MongoDB\Driver\ClientEncryption::decrypt(MongoDB\BSON\Binary `$value`): mixed

Déchiffre la valeur.

### Liste de paramètres

`value`
  Une instance de MongoDB\BSON\Binary avec le sous-type 6 contenant la valeur chiffrée.

### Valeurs de retour

Renvoie la valeur déchiffrée telle qu'elle a été passée à MongoDB\Driver\ClientEncryption::encrypt().

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\EncryptionException si une erreur se produit lors du déchiffrement de la valeur

### Voir aussi

- MongoDB\Driver\ClientEncryption::encrypt() - Chiffre une valeur

# MongoDB\Driver\ClientEncryption::deleteKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::deleteKey — Supprime un document clé

### Description

final public function MongoDB\Driver\ClientEncryption::deleteKey(MongoDB\BSON\Binary `$keyId`): object

Enlève le document clé avec l'UUID donné `keyId` de la collection de coffre de clés.

### Liste de paramètres

`keyId`
  Une instance de MongoDB\BSON\Binary avec le sous-type 4 (UUID) identifiant le document clé.

### Valeurs de retour

Renvoie le résultat de l'opération interne `deleteOne` sur la collection de coffre de clés.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs.

# MongoDB\Driver\ClientEncryption::encrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::encrypt — Chiffre une valeur

### Description

final public function MongoDB\Driver\ClientEncryption::encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary

Chiffre la valeur.

### Liste de paramètres

`value`
  La valeur à chiffrer. Toute valeur qui peut être insérée dans MongoDB peut être chiffrée en utilisant cette méthode.
`options`

  Options de chiffrement
  Option | Type | Description
  --- | --- | ---
  algorithm | string | L'algorithme de chiffrement à utiliser. Cette option est requise. Spécifiez l'une des constantes suivantes de ClientEncryption : `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | Le facteur de contention pour évaluer les requêtes avec des charges utiles chiffrées indexées. Cette option s'applique uniquement et ne peut être spécifiée que lorsque `algorithm` est `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` ou `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Identifie un document de collection de coffre à clés par `keyAltName`. Cette option est mutuellement exclusive avec `keyId` et l'une des deux est requise.
  keyId | MongoDB\BSON\Binary | Identifie une clé de données par `_id`. La valeur est un UUID (sous-type binaire 4). Cette option est mutuellement exclusive avec `keyAltName` et l'une des deux est requise.
  queryType | string | Le type de requête pour évaluer les requêtes avec des charges utiles chiffrées indexées. Spécifiez l'une des constantes suivantes de ClientEncryption : `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` Cette option s'applique uniquement et ne peut être spécifiée que lorsque `algorithm` est `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` ou `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Options d'index pour un champ de chiffrement interrogeable prenant en charge les requêtes "range". Les options ci-dessous doivent correspondre aux valeurs définies dans `encryptedFields` de la collection cible. Pour les types de champ BSON double et decimal128, `min`, `max` et `precision` doivent être tous définis ou tous non définis.
  Options d'index de plage
  Option | Type | Description
  --- | --- | ---
  min | mixed | Requis si `precision` est défini. La valeur BSON minimale de la plage.
  max | mixed | Requis si `precision` est défini. La valeur BSON maximale de la plage.
  sparsity | int | Optionnel.Entier positif sur 64 bits.
  precision | int | Facultatif. Entier positif sur 32 bits spécifiant la précision à utiliser pour le chiffrement explicite. Peut uniquement être défini pour les types de champ BSON double ou decimal128.
  trimFactor | int | Optionnel. Entier positif sur 32 bits.

### Valeurs de retour

Renvoie la valeur chiffrée en tant qu'objet MongoDB\BSON\Binary de sous-type 6.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\EncryptionException si une erreur se produit lors du chiffrement de la valeur

### Historique

Version | Description
--- | ---
PECL mongodb 1.20.0 | Ajouté l'option de plage `"trimFactor"`. L'option de plage `"sparsity"` est désormais optionnelle.
PECL mongodb 1.16.0 | Ajouté l'option `"rangeOpts"`.
PECL mongodb 1.14.0 | Ajout des options `"contentionFactor"` et `"queryType"`.

### Voir aussi

- MongoDB\Driver\ClientEncryption::decrypt() - Déchiffre une valeur
- MongoDB\Driver\ClientEncryption::encryptExpression() - Chiffre une expression de correspondance ou d'agrégation

# MongoDB\Driver\ClientEncryption::encryptExpression

(mongodb >=1.16.0)

MongoDB\Driver\ClientEncryption::encryptExpression — Chiffre une expression de correspondance ou d'agrégation

### Description

final public function MongoDB\Driver\ClientEncryption::encryptExpression(array|object `$expr`, ?array `$options` = `null`): object

Chiffre une expression de correspondance ou d'agrégation pour interroger un index de plage.

Pour interroger avec une charge utile chiffrée par plage, l'option de pilote MongoDB\Driver\Manager doit être configurée avec l'option de pilote `"autoEncryption"`. L'option de chiffrement automatique `"bypassQueryAnalysis"` peut être `true`. L'option de chiffrement automatique `"bypassAutoEncryption"` doit être `false`.

> Note: L'extension ne prend pas encore en charge les requêtes de plage pour les types de champ BSON Decimal128.

### Liste de paramètres

`expr`
  L'expression de correspondance ou d'agrégation à chiffrer. Les expressions doivent utiliser au moins un des opérateurs `$gt`, `$gte`, `$lt` ou `$lte`. Un opérateur `$and` de premier niveau est requis, même si un seul opérateur de comparaison est utilisé. Un exemple d'expression de correspondance prise en charge (s'applique aux requêtes et à l'étape d'agrégation `$match`) est le suivant :

      [
          '$and' => [
              [ '<field>' => [ '$gt'  => '<value1>' ] ],
              [ '<field>' => [ '$lte' => '<value2>' ] ],
          ],
      ]

  Un exemple d'expression d'agrégation prise en charge est le suivant :

      [
          '$and' => [
              [ '$gte' => [ '<fieldPath>', '<value1>' ] ],
              [ '$lt'  => [ '<fieldPath>', '<value2>' ] ],
          ],
      ]

`options`

  Options de chiffrement
  Option | Type | Description
  --- | --- | ---
  algorithm | string | L'algorithme de chiffrement à utiliser. Cette option est requise. Spécifiez l'une des constantes suivantes de ClientEncryption : `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | Le facteur de contention pour évaluer les requêtes avec des charges utiles chiffrées indexées. Cette option s'applique uniquement et ne peut être spécifiée que lorsque `algorithm` est `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` ou `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Identifie un document de collection de coffre à clés par `keyAltName`. Cette option est mutuellement exclusive avec `keyId` et l'une des deux est requise.
  keyId | MongoDB\BSON\Binary | Identifie une clé de données par `_id`. La valeur est un UUID (sous-type binaire 4). Cette option est mutuellement exclusive avec `keyAltName` et l'une des deux est requise.
  queryType | string | Le type de requête pour évaluer les requêtes avec des charges utiles chiffrées indexées. Spécifiez l'une des constantes suivantes de ClientEncryption : `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` Cette option s'applique uniquement et ne peut être spécifiée que lorsque `algorithm` est `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` ou `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Options d'index pour un champ de chiffrement interrogeable prenant en charge les requêtes "range". Les options ci-dessous doivent correspondre aux valeurs définies dans `encryptedFields` de la collection cible. Pour les types de champ BSON double et decimal128, `min`, `max` et `precision` doivent être tous définis ou tous non définis.
  Options d'index de plage
  Option | Type | Description
  --- | --- | ---
  min | mixed | Requis si `precision` est défini. La valeur BSON minimale de la plage.
  max | mixed | Requis si `precision` est défini. La valeur BSON maximale de la plage.
  sparsity | int | Optionnel.Entier positif sur 64 bits.
  precision | int | Facultatif. Entier positif sur 32 bits spécifiant la précision à utiliser pour le chiffrement explicite. Peut uniquement être défini pour les types de champ BSON double ou decimal128.
  trimFactor | int | Optionnel. Entier positif sur 32 bits.

### Valeurs de retour

Renvoie l'expression chiffrée en tant qu'objet.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\EncryptionException si une erreur se produit lors du chiffrement de l'expression

### Historique

Version | Description
--- | ---
PECL mongodb 1.20.0 | Ajouté l'option de plage `"trimFactor"`. L'option de plage `"sparsity"` est désormais optionnelle.

### Voir aussi

- MongoDB\Driver\Manager::__construct() - Crée un nouveau Manager MongoDB
- MongoDB\Driver\ClientEncryption::encrypt() - Chiffre une valeur

# MongoDB\Driver\ClientEncryption::getKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKey — Renvoie un document clé

### Description

final public function MongoDB\Driver\ClientEncryption::getKey(MongoDB\BSON\Binary `$keyId`): ?object

Trouve un document clé unique dans la collection de coffre de clés avec l'UUID donné `keyId`.

### Liste de paramètres

`keyId`
  Une instance de MongoDB\BSON\Binary avec le sous-type 4 (UUID) identifiant le document clé.

### Valeurs de retour

Renvoie le document clé, ou `null` si aucun document n'a été trouvé.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs.

# MongoDB\Driver\ClientEncryption::getKeyByAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeyByAltName — Renvoie un document clé par un nom alternatif

### Description

final public function MongoDB\Driver\ClientEncryption::getKeyByAltName(string `$keyAltName`): ?object

Trouve un document clé unique dans la collection de coffre de clés avec le nom alternatif donné `keyAltName`.

### Liste de paramètres

`keyAltName`
  Le nom alternatif pour le document clé.

### Valeurs de retour

Renvoie le document clé, ou `null` si aucun document n'a été trouvé.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs.

### Voir aussi

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Ajoute un nom alternatif à un document clé
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Enlève un nom alternatif d'un document clé

# MongoDB\Driver\ClientEncryption::getKeys

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeys — Renvoie tous les documents clés

### Description

final public function MongoDB\Driver\ClientEncryption::getKeys(): MongoDB\Driver\Cursor

Trouve tous les documents clés dans la collection de coffre de clés.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs.

# MongoDB\Driver\ClientEncryption::removeKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::removeKeyAltName — Enlève un nom alternatif d'un document clé

### Description

final public function MongoDB\Driver\ClientEncryption::removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Enlève `keyAltName` de l'ensemble des noms alternatifs pour le document clé avec l'UUID donné `keyId`.

### Liste de paramètres

`keyId`
  Une instance de MongoDB\BSON\Binary avec le sous-type 4 (UUID) identifiant le document clé.
`keyAltName`
  Le nom alternatif à enlever du document clé.

### Valeurs de retour

Renvoie la version précédente du document clé, ou `null` si aucun document n'a été trouvé.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs.

### Voir aussi

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Ajoute un nom alternatif à un document clé
- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Renvoie un document clé par un nom alternatif

# MongoDB\Driver\ClientEncryption::rewrapManyDataKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Ré-emballe les clés de données

### Description

final public function MongoDB\Driver\ClientEncryption::rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object

Ré-emballe (c'est-à-dire déchiffre et rechiffre) zéro ou plusieurs clés de données dans la collection de coffre de clés qui correspondent au `filter` donné.

Si l'option `"provider"` n'est pas spécifiée, les clés de données correspondantes seront ré-emballées avec leur fournisseur KMS actuel. Sinon, les clés de données correspondantes seront rechiffrées selon les options `"provider"` et `"masterKey"` spécifiées.

### Liste de paramètres

`filter` (array|object)
  L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

  > Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

`options`

  Options de RewrapManyDataKey
  Option | Type | Description
  --- | --- | ---
  provider | string | Le fournisseur KMS (par exemple `"local"`, `"aws"`) qui sera utilisé pour rechiffrer les clés de données correspondantes. Si un fournisseur KMS n'est pas spécifié, les clés de données correspondantes seront rechiffrées avec leur fournisseur KMS actuel.
  masterKey | array | La clé masterKey identifie une clé spécifique à un KMS utilisée pour chiffrer la nouvelle clé de données. Cette option ne doit pas être spécifiée sans l'option `"provider"`. Cette option est requise si `"provider"` est spécifié et n'est pas `"local"`.
  Options du fournisseur `"aws"`
  Option | Type | Description
  --- | --- | ---
  region | string | Requis.
  key | string | Requis. Le nom de ressource Amazon (ARN) de la clé maîtresse du client AWS (CMK).
  endpoint | string | Optionnel. Un identifiant d'hôte alternatif pour envoyer les demandes KMS. Peut inclure le numéro de port.
  Options du fournisseur `"azure"`
  Option | Type | Description
  --- | --- | ---
  keyVaultEndpoint | string | Requis. Hôte avec port optionnel (par exemple, "example.vault.azure.net").
  keyName | string | Requis.
  keyVersion | string | Optionnel. Une version spécifique de la clé nommée. Par défaut, la version primaire de la clé est utilisée.
  Options du fournisseur `"gcp"`
  Option | Type | Description
  --- | --- | ---
  projectId | string | Requis.
  location | string | Requis.
  keyRing | string | Requis.
  keyName | string | Requis.
  keyVersion | string | Optionnel. Une version spécifique de la clé nommée. Par défaut, la version primaire de la clé est utilisée.
  endpoint | string | Optionnel. Hôte avec port optionnel. La valeur par défaut est "cloudkms.googleapis.com".
  Options du fournisseur `"kmip"`
  Option | Type | Description
  --- | --- | ---
  keyId | string | Optionnel. Identifiant unique d'un objet géré de 96 octets de données secrètes KMIP. S'il n'est pas spécifié, le pilote crée un objet géré aléatoire de 96 octets de données secrètes KMIP.
  endpoint | string | Optionnel. Hôte avec port optionnel.
  delegated | bool | Optionnel. Si vrai, cette clé devrait être déchiffrer par le serveur KMIP.

### Valeurs de retour

Renvoie un objet, qui aura éventuellement une propriété `bulkWriteResult` contenant le résultat de l'opération `bulkWrite` interne sous forme d'un objet. Si aucune clé de données n'a correspondu au filtre ou si l'écriture n'a pas été acquittée, la propriété `bulkWriteResult` sera `null`.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\EncryptionException si une erreur se produit lors du déchiffrement ou du rechiffrement d'une clé de données.
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs.

### Historique

Version | Description
--- | ---
PECL mongodb 1.20.0 | Ajout de `"delegated"` aux options masterKey du fournisseur KMIP.

## Sommaire

- MongoDB\Driver\ClientEncryption::addKeyAltName — Ajoute un nom alternatif à un document clé
- MongoDB\Driver\ClientEncryption::__construct — Créer un nouvel objet ClientEncryption
- MongoDB\Driver\ClientEncryption::createDataKey — Créer un document clé
- MongoDB\Driver\ClientEncryption::decrypt — Déchiffre une valeur
- MongoDB\Driver\ClientEncryption::deleteKey — Supprime un document clé
- MongoDB\Driver\ClientEncryption::encrypt — Chiffre une valeur
- MongoDB\Driver\ClientEncryption::encryptExpression — Chiffre une expression de correspondance ou d'agrégation
- MongoDB\Driver\ClientEncryption::getKey — Renvoie un document clé
- MongoDB\Driver\ClientEncryption::getKeyByAltName — Renvoie un document clé par un nom alternatif
- MongoDB\Driver\ClientEncryption::getKeys — Renvoie tous les documents clés
- MongoDB\Driver\ClientEncryption::removeKeyAltName — Enlève un nom alternatif d'un document clé
- MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Ré-emballe les clés de données

# La classe MongoDB\Driver\ServerApi

(mongodb >=1.10.0)

## Introduction

## Synopsis de la classe

final class MongoDB\Driver\ServerApi implements MongoDB\BSON\Serializable, Serializable {
/* Constantes */
const string MongoDB\Driver\ServerAPI::V1 = "1";
/* Méthodes */
final public function bsonSerialize(): stdClass
final public function __construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)
}

## Constantes pré-définies

`MongoDB\Driver\ServerApi::V1`
  Version 1 de l'API serveur.

## Exemples

Exemple #1 Déclarer une version d'API sur un gestionnaire

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* La commande buildInfo retourne un document unique, nous devons donc accéder
     * au premier résultat du curseur. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

L'exemple ci-dessus va afficher :

    4.9.0-alpha7-49-gb968ca0

Exemple #2 Déclare une version d'API stricte sur un gestionnaire

L'exemple suivant définit le drapeau `strict`, qui indique au serveur de rejeter toute commande qui ne fait pas partie de la version d'API déclarée. Cela entraîne une erreur lors de l'exécution de la commande buildInfo.

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1, true);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* La commande buildInfo retourne un document unique, nous devons donc accéder
     * au premier résultat du curseur. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

L'exemple ci-dessus va afficher :

    Provided apiStrict:true, but the command buildInfo is not in API Version 1

# MongoDB\Driver\ServerApi::bsonSerialize

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::bsonSerialize — Renvoie un objet pour la sérialisation BSON

### Description

final public function MongoDB\Driver\ServerApi::bsonSerialize(): stdClass

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un objet pour la sérialisation du ServerApi en BSON.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\BSON\Serializable::bsonSerialize() - Fournit un tableau ou un document à sérialiser en tant que BSON

# MongoDB\Driver\ServerApi::__construct

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::__construct — Créer une nouvelle instance de ServerApi

### Description

final public function MongoDB\Driver\ServerApi::__construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)

Crée une nouvelle instance de MongoDB\Driver\ServerApi utilisée pour déclarer une version d'API lors de la création d'un MongoDB\Driver\Manager.

### Liste de paramètres

`version`
  Une version d'API de serveur. Les versions d'API prises en charge sont fournies sous forme de constantes dans MongoDB\Driver\ServerApi. La seule version d'API prise en charge est `MongoDB\Driver\ServerApi::V1`.
`strict`
  Si le paramètre `strict` est défini sur `true`, le serveur renverra une erreur pour toute commande qui ne fait pas partie de la version d'API spécifiée. Si aucune valeur n'est fournie, la valeur par défaut du serveur (`false`) est utilisée.
`deprecationErrors`
  Si le paramètre `deprecationErrors` est défini sur `true`, le serveur renverra une erreur lors de l'utilisation d'une commande qui est obsolète dans la version d'API spécifiée. Si aucune valeur n'est fournie, la valeur par défaut du serveur (`false`) est utilisée.

## Sommaire

- MongoDB\Driver\ServerApi::bsonSerialize — Renvoie un objet pour la sérialisation BSON
- MongoDB\Driver\ServerApi::__construct — Créer une nouvelle instance de ServerApi

# La classe MongoDB\Driver\WriteConcern

(mongodb >=1.0.0)

## Introduction

MongoDB\Driver\WriteConcern décrit le niveau d'accusé de réception demandé par MongoDB pour les opérations d'écriture à un `mongod` autonome ou à des ensembles de réplicas ou à des clusters fragmentés. Dans les clusters fragmentés, les instances de `mongos` transmettent le write concern aux fragments.

## Synopsis de la classe

final class MongoDB\Driver\WriteConcern implements MongoDB\BSON\Serializable, Serializable {
/* Constantes */
const string MAJORITY = "majority";
/* Propriétés */
public readonly string|int|null $w;
public readonly ?bool $j;
public readonly int $wtimeout;
/* Méthodes */
final public function bsonSerialize(): stdClass
final public function __construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)
final public function getJournal(): ?bool
final public function getW(): string|int|null
final public function getWtimeout(): int
final public function isDefault(): bool
}

## Propriétés

w
  La valeur du write concern (nombre entier de nœuds, la chaîne `"majority"`, ou un nom personnalisé d'étiquette de write concern), ou `null` si non définie.
j
  Indique si les opérations d'écriture doivent être validées dans le journal avant d'être acquittées, ou `null` si non spécifié.
wtimeout
  Le délai d'attente en millisecondes pour l'accusé de réception du write concern. Une valeur de `0` signifie attendre indéfiniment.

## Constantes pré-définies

`MongoDB\Driver\WriteConcern::MAJORITY`
  La majorité de tous les membres du jeu de répliques ; les arbitres, les membres non-votants, les membres passifs, les membres cachés, et les membres en attente sont tous inclus dans la définition d'un write concern de la majorité.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.
PECL mongodb 1.7.0 | Implémente Serializable.
PECL mongodb 1.2.0 | Implémente MongoDB\BSON\Serializable.

# MongoDB\Driver\WriteConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\WriteConcern::bsonSerialize — Renvoie un objet pour la sérialisation BSON

### Description

final public function MongoDB\Driver\WriteConcern::bsonSerialize(): stdClass

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un objet pour la sérialisation du WriteConcern en BSON.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 MongoDB\Driver\WriteConcern::bsonSerialize() avec le write concern majority

    <?php

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#2 (1) {
      ["w"]=>
      string(8) "majority"
    }

    { "w" : "majority" }

Exemple #2 MongoDB\Driver\WriteConcern::bsonSerialize() avec le wtimeout et le journal

    <?php

    $wc = new MongoDB\Driver\WriteConcern(2, 1000, true);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#2 (3) {
      ["w"]=>
      int(2)
      ["j"]=>
      bool(true)
      ["wtimeout"]=>
      int(1000)
    }

    { "w" : 2, "j" : true, "wtimeout" : 1000 }

### Voir aussi

- MongoDB\BSON\Serializable::bsonSerialize() - Fournit un tableau ou un document à sérialiser en tant que BSON
- » Référence de Write Concern

# MongoDB\Driver\WriteConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::__construct — Construit un WriteConcern

### Description

final public function MongoDB\Driver\WriteConcern::__construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)

Construit un nouveau MongoDB\Driver\WriteConcern, qui est un objet de valeur immuable.

### Liste de paramètres

`w`

  Write concern
  Valeur | Description
  --- | ---
  1 | Demande l'accusé de réception que l'opération d'écriture s'est propagée au `mongod` autonome ou au principal dans un jeu de réplicas. Il s'agit du write concern par défaut pour MongoDB.
  0 | Ne demande aucun accusé de réception de l'opération d'écriture. Toutefois, cela peut renvoyer des informations sur les exceptions de socket et les erreurs de mise en réseau à l'application.
  <entier supérieur à 1> | Les nombres supérieurs à 1 sont valides uniquement pour les jeux de réplicas pour demander l'accusé de réception à partir du nombre spécifié de membres, y compris le principal.
  `MongoDB\Driver\WriteConcern::MAJORITY` | Demande l'accusé de réception que les opérations d'écriture se sont propagées à la majorité des nœuds votants, y compris le principal, et ont été écrites dans le journal sur disque pour ces nœuds. Avant MongoDB 3.0, il s'agit de la majorité des membres du jeu de réplicas (et pas seulement des nœuds votants).
  string | Une valeur de chaîne est interprétée comme un jeu de balises. Demande l'accusé de réception que les opérations d'écriture se sont propagées à un membre de jeu de réplicas avec la balise spécifiée.

`wtimeout`
  Délai d'attente maximal (en millisecondes) avant que les secondaires n'échouent. `wtimeout` fera que les opérations en écriture vont retourner une erreur (WriteConcernError) après le délai spécifié, même si le write concern requis finit par être satisfait. Lorsque ces opérations en écriture retournent, MongoDB ne va pas annuler les modifications de données réussies effectuées avant que le write concern n'ait dépassé le délai limite `wtimeout`. Si spécifié, `wtimeout` doit être un entier signé 64 bits supérieur ou égal à zéro.

  Délai d'attente du write concern
  Valeur | Description
  --- | ---
  0 | Bloc indéfiniment. C'est le comportement par défaut.
  <entier supérieur à 0> | Nombre de millisecondes à attendre avant de retourner.

`journal`
  Attente avant que mongod n'applique l'écriture au journal.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\InvalidArgumentException si `w` est invalide ou `wtimeout` est négatif ou supérieure aux limites d'un entier signé 32 bits.

### Historique

Version | Description
--- | ---
PECL mongodb 1.7.0 | Le paramètre `wTimeout` accepte désormais des valeurs 64-bit.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteConcern::__construct()

    <?php

    /* Demande une confirmation des requêtes en écriture pour la majorité des nœuds
       du jeux de réplication */
    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 500);

    /* Demande une confirmation des requêtes en écriture, configurée par la balise
       "MultipleDC" */
    $wc = new MongoDB\Driver\WriteConcern("MultipleDC", 500);

    ?>

### Voir aussi

- » Write Concern reference

# MongoDB\Driver\WriteConcern::getJournal

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getJournal — Renvoie l'option "journal" du WriteConcern

### Description

final public function MongoDB\Driver\WriteConcern::getJournal(): ?bool

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'option "journal" du WriteConcern.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\WriteConcern::getJournal()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, true);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, false);
    var_dump($wc->getJournal());

    ?>

L'exemple ci-dessus va afficher :

    NULL
    bool(true)
    bool(false)

### Voir aussi

- » Référence de Write Concern

# MongoDB\Driver\WriteConcern::getW

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getW — Renvoie l'option "w" du WriteConcern

### Description

final public function MongoDB\Driver\WriteConcern::getW(): string|int|null

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'option "w" du WriteConcern.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\WriteConcern::getW()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getW());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->getW());

    ?>

L'exemple ci-dessus va afficher :

    int(1)
    string(8) "majority"

### Voir aussi

- » Référence de Write Concern

# MongoDB\Driver\WriteConcern::getWtimeout

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getWtimeout — Renvoie l'option "wtimeout" du WriteConcern

### Description

final public function MongoDB\Driver\WriteConcern::getWtimeout(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'option "wtimeout" du WriteConcern.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 1.7.0 | Sur les systèmes 32 bits, cette méthode tronquera toujours la valeur `wTimeout` si elle dépasse la plage 32 bits. Dans ce cas, un avertissement sera émis.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\WriteConcern::getWtimeout()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getWtimeout());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 3000);
    var_dump($wc->getWtimeout());

    ?>

L'exemple ci-dessus va afficher :

    int(0)
    int(3000)

### Voir aussi

- » Référence de Write Concern

# MongoDB\Driver\WriteConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\WriteConcern::isDefault — Vérifie si c'est le WriteConcern par défaut

### Description

final public function MongoDB\Driver\WriteConcern::isDefault(): bool

Renvoie si c'est le WriteConcern par défaut (c'est-à-dire sans options spécifiées). Cette méthode est principalement destinée à être utilisée en conjonction avec MongoDB\Driver\Manager::getWriteConcern() pour déterminer si le Manager a été construit sans aucune option de WriteConcern.

Le pilote n'inclura pas de WriteConcern par défaut dans ses opérations d'écriture (par exemple MongoDB\Driver\Manager::executeBulkWrite()) afin de permettre au serveur d'appliquer son propre WriteConcern par défaut, qui peut avoir été » modifié. Les bibliothèques qui accèdent au WriteConcern du Manager pour l'inclure dans leurs propres commandes d'écriture devraient utiliser cette méthode pour s'assurer que les WriteConcern par défaut ne sont pas définis.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si c'est le WriteConcern par défaut et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\WriteConcern::isDefault()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?w=majority');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(false)
    bool(true)

### Voir aussi

- MongoDB\Driver\Manager::getWriteConcern() - Renvoie le WriteConcern pour le Manager
- » Modifier le Write Concern par défaut dans le manuel MongoDB
- » Référence de Write Concern

## Sommaire

- MongoDB\Driver\WriteConcern::bsonSerialize — Renvoie un objet pour la sérialisation BSON
- MongoDB\Driver\WriteConcern::__construct — Construit un WriteConcern
- MongoDB\Driver\WriteConcern::getJournal — Renvoie l'option "journal" du WriteConcern
- MongoDB\Driver\WriteConcern::getW — Renvoie l'option "w" du WriteConcern
- MongoDB\Driver\WriteConcern::getWtimeout — Renvoie l'option "wtimeout" du WriteConcern
- MongoDB\Driver\WriteConcern::isDefault — Vérifie si c'est le WriteConcern par défaut

# La classe MongoDB\Driver\ReadPreference

(mongodb >=1.0.0)

## Introduction

## Synopsis de la classe

final class MongoDB\Driver\ReadPreference implements MongoDB\BSON\Serializable, Serializable {
/* Propriétés */
public readonly string $mode;
public readonly ?array $tags;
public readonly int $maxStalenessSeconds;
public readonly ?object $hedge;
/* Constantes */
const string PRIMARY = primary;
const string PRIMARY_PREFERRED = primaryPreferred;
const string SECONDARY = secondary;
const string SECONDARY_PREFERRED = secondaryPreferred;
const string NEAREST = nearest;
const int NO_MAX_STALENESS = -1;
const int SMALLEST_MAX_STALENESS_SECONDS = 90;
/* Méthodes */
final public function bsonSerialize(): stdClass
final public function __construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)
final public function getHedge(): ?object
final public function getMaxStalenessSeconds(): int
final public function getMode(): int
final public function getModeString(): string
final public function getTagSets(): array
}

## Propriétés

mode
  Le mode de préférence de lecture sous forme de chaîne (par exemple `"primary"`, `"secondary"`).
tags
  La liste des jeux d'étiquettes utilisés par la préférence de lecture, ou `null` si aucun jeu d'étiquettes n'a été spécifié.
maxStalenessSeconds
  L'obsolescence maximale en secondes pour les lectures, ou `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` si aucune obsolescence maximale n'a été spécifiée.
hedge
  Un document spécifiant les options de couverture (hedge) pour la préférence de lecture, ou `null` si aucune option de couverture n'a été spécifiée.
  Avertissement

  Cette propriété est obsolète car les lectures couvertes (hedged reads) sont obsolètes dans MongoDB 8.0.

## Constantes pré-définies

`MongoDB\Driver\ReadPreference::PRIMARY`
  Toutes les opérations lues à partir du jeu de réplicas actuel primaire. Il s'agit de la préférence de lecture par défaut pour MongoDB.
`MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`
  Dans la plupart des situations, les opérations sont lues à partir du primaire, mais s'il n'est pas disponible, les opérations sont lues à partir de membres secondaires.
`MongoDB\Driver\ReadPreference::SECONDARY`
  Toutes les opérations sont lues à partir des membres secondaires du jeu de réplicas.
`MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED`
  Dans la plupart des cas, les opérations sont lues par des membres secondaires, mais si aucun membre secondaire n'est disponible, les opérations sont lues à partir du primaire.
`MongoDB\Driver\ReadPreference::NEAREST`
  Les opérations sont lues à partir du membre du jeu de réplicas avec la latence de réseau la moins élevée, quel que soit le type du membre.
`MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`
  La valeur par défaut de l'option `"maxStalenessSeconds"` est de ne spécifier aucune limite sur l'obsolescence maximale, ce qui signifie que le pilote ne prendra pas en compte le décalage d'un secondaire lors du choix de l'endroit où diriger une opération de lecture.
`MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`
  La valeur minimale de l'option `"maxStalenessSeconds"` est de 90 secondes. Le pilote estime l'obsolescence des secondes en vérifiant périodiquement la dernière date d'écriture de chaque membre du jeu de réplicas. Comme ces contrôles sont peu fréquents, l'estimation de l'obsolescence est grossière. Ainsi, le pilote ne peut pas appliquer une valeur d'obsolescence maximale inférieure à 90 secondes.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.
PECL mongodb 2.0.0 | Supprimer les constantes `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED`, et `MongoDB\Driver\ReadPreference::RP_NEAREST`. La méthode getMode() a également été supprimée.
PECL mongodb 1.20.0 | Les constantes `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED`, et `MongoDB\Driver\ReadPreference::RP_NEAREST` sont obsolètes.
PECL mongodb 1.7.0 | Ajout des constantes `MongoDB\Driver\ReadPreference::PRIMARY`, `MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::SECONDARY`, `MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED`, `MongoDB\Driver\ReadPreference::NEAREST`. Implémente Serializable.
PECL mongodb 1.2.0 | Ajout des constantes `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` et `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`. Implémente MongoDB\BSON\Serializable.

# MongoDB\Driver\ReadPreference::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::bsonSerialize — Renvoie un objet pour la sérialisation BSON

### Description

final public function MongoDB\Driver\ReadPreference::bsonSerialize(): stdClass

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un objet pour la sérialisation de la ReadPreference en BSON.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 MongoDB\Driver\ReadPreference::bsonSerialize() avec une préférence de lecture primaire

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }

    { "mode" : "primary" }

Exemple #2 MongoDB\Driver\ReadPreference::bsonSerialize() avec une préférence de lecture secondaire

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        [
            ['dc' => 'ny'],
            ['dc' => 'sf', 'use' => 'reporting'],
            []
        ]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#1 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [1]=>
        object(stdClass)#5 (2) {
          ["dc"]=>
          string(2) "sf"
          ["use"]=>
          string(9) "reporting"
        }
        [2]=>
        object(stdClass)#4 (0) {
        }
      }
    }

    { "mode" : "secondary", "tags" : [ { "dc" : "ny" }, { "dc" : "sf", "use" : "reporting" }, {  } ] }

Exemple #3 MongoDB\Driver\ReadPreference::bsonSerialize() avec une préférence de lecture secondaire et un délai maximal

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        null,
        ['maxStalenessSeconds' => 120]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }

    { "mode" : "secondary", "maxStalenessSeconds" : 120 }

### Voir aussi

- MongoDB\BSON\Serializable::bsonSerialize() - Fournit un tableau ou un document à sérialiser en tant que BSON
- » Référence de Read Preference

# MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Créer un nouveau ReadPreference

### Description

final public function MongoDB\Driver\ReadPreference::__construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)

Construit un nouveau MongoDB\Driver\ReadPreference, qui est un objet de valeur immuable.

### Liste de paramètres

`mode`

  Mode de préférence de lecture
  Valeur | Description
  --- | ---
  `"primary"` | Toutes les opérations lues à partir du jeu de réplicas actuel primaire. Il s'agit de la préférence de lecture par défaut pour MongoDB.
  `"primaryPreferred"` | Dans la plupart des situations, les opérations sont lues à partir du primaire, mais s'il n'est pas disponible, les opérations sont lues à partir d'un membre secondaire.
  `"secondary"` | Toutes les opérations sont lues à partir des membres secondaires du jeu de réplicas.
  `"secondaryPreferred"` | Dans la plupart des cas, les opérations sont lues par des membres secondaires, mais si aucun membre secondaire n'est disponible, les opérations sont lues à partir du primaire.
  `"nearest"` | Opérations lues à partir du membre du jeu de réplicas ayant la latence réseau la moins élevée, quel que soit le type du membre.

`tagSets`
  Les jeux de tag permettent de cibler des opérations de lecture sur des membres spécifiques d'un jeu de réplicas. Ce paramètre doit être un tableau de tableaux associatifs, qui contiennent chacun zéro ou plusieurs paires clé/valeur. Lors de la sélection d'un serveur pour une opération de lecture, le pilote tente de sélectionner un nœud comportant toutes les balises d'un ensemble (c'est-à-dire le tableau associatif de paires clé/valeur). Si la sélection échoue, le pilote essaiera les jeux suivants. Un jeu de balises vide (`array()`) correspond à n'importe quel nœud et peut être utilisé comme secours. Les tags ne sont pas compatibles avec le mode `"primary"` et, en général, s'appliquent uniquement lors de la sélection d'un membre secondaire d'un jeu pour une opération de lecture. Toutefois, le mode `"nearest"`, lorsqu'il est combiné avec un jeu de balises, sélectionne le membre correspondant avec la latence réseau la plus basse. Ce membre peut être primaire ou secondaire.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  hedge | object|array | Spécifie si l'on doit utiliser ou non » les lectures couvertes, qui sont supportées depuis MongoDB 4.4+ pour les requêtes partagées. Les lectures couvertes côté serveur sont disponibles pour toutes les préférences de lecture non primaires, et sont activées par défaut lors de l'utilisation du mode `"nearest"`. Cette option permet d'activer explicitement les lectures couvertes côté serveur pour les préférences de lecture non primaires en spécifiant `['enabled' => true]`, ou de désactiver explicitement les lectures couvertes côté serveur pour la préférence de lecture `"nearest"` en spécifiant `['enabled' => false]`.
  maxStalenessSeconds | entier | Spécifie un décalage de réplication maximal, ou "obsolescence", pour les lectures des secondaires. Lorsque l'obsolescence estimée d'un secondaire dépasse cette valeur, le pilote cesse de l'utiliser pour les opérations de lecture. Si elle est spécifiée, l'obsolescence maximale doit être un entier signé 32 bits supérieur ou égal à `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`. Par défaut, `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`, ce qui signifie que le pilote ne prendra pas en compte le décalage d'un secondaire lors du choix de l'endroit où diriger une opération de lecture. Cette option n'est pas compatible avec le mode `"primary"`. La spécification d'une obsolescence maximale requiert également que toutes les instances MongoDB du déploiement utilisent MongoDB 3.4+. Une exception sera levée au moment de l'exécution si toutes les instances de MongoDB dans le déploiement sont d'une version de serveur plus ancienne.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\InvalidArgumentException si `mode` est incorrect.
- Lève une exception MongoDB\Driver\Exception\InvalidArgumentException si `tagSets` est fourni pour une préférence de lecture primaire ou est incorrect (c.-à-d. pas un tableau de zéro ou plus de documents).
- Lève une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"maxStalenessSeconds"` est fournie pour une préférence de lecture primaire ou est hors de la plage.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Passer un int pour l'argument `mode` n'est plus pris en charge.
PECL mongodb 1.20.0 | Passer un int pour l'argument `mode` est DÉPRÉCIÉ.
PECL mongodb 1.8.0 | Ajout de l'option `"hedge"`.
PECL mongodb 1.3.0 | L'argument `mode` accepte maintenant une valeur de chaîne, ce qui est compatible avec l'option URI `"readPreference"` pour MongoDB\Driver\Manager::__construct()
PECL mongodb 1.2.0 | Ajout d'un troisième argument d'`options`, qui prend en charge l'option `"maxStalenessSeconds"` .

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\ReadPreference::__construct()

    <?php

    /* Préférez un nœud secondaire mais retombez sur un primaire. */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED));

    /* Préférez un nœud dans le centre de données de New York avec la latence la plus basse. */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST, [['dc' => 'ny']]));

    /* Nécessite un nœud secondaire dont le décalage de réplication se trouve dans les deux minutes */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['maxStalenessSeconds' => 120]));

    /* Active explicitement le serveur des lectures croisées */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['hedge' => ['enabled' => true]]));
    ?>

L'exemple ci-dessus va afficher :

    object(MongoDB\Driver\ReadPreference)#1 (1) {
      ["mode"]=>
      string(18) "secondaryPreferred"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(7) "nearest"
      ["tags"]=>
      array(1) {
        [0]=>
        object(stdClass)#2 (1) {
          ["dc"]=>
          string(2) "ny"
        }
      }
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["hedge"]=>
      object(stdClass)#1 (1) {
        ["enabled"]=>
        bool(true)
      }
    }

### Voir aussi

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getHedge

(mongodb >=1.8.0)

MongoDB\Driver\ReadPreference::getHedge — Renvoie l'option "hedge" du ReadPreference

### Description

final public function MongoDB\Driver\ReadPreference::getHedge(): ?object

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'option "hedge" du ReadPreference.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- » Référence de Read Preference

# MongoDB\Driver\ReadPreference::getMaxStalenessSeconds

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Renvoie l'option "maxStalenessSeconds" du ReadPreference

### Description

final public function MongoDB\Driver\ReadPreference::getMaxStalenessSeconds(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'option "maxStalenessSeconds" du ReadPreference. Si aucun délai maximal n'a été spécifié, `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` sera retourné.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\ReadPreference::getMaxStalenessSeconds()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::NO_MAX_STALENESS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => 1000,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    ?>

L'exemple ci-dessus va afficher :

    int(-1)
    int(-1)
    int(90)
    int(1000)

### Voir aussi

- » Référence de Read Preference

# MongoDB\Driver\ReadPreference::getMode

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getMode — Renvoie l'option "mode" du ReadPreference

Avertissement

Cette fonction a été DÉPRÉCIÉE depuis la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications devraient utiliser MongoDB\Driver\ReadPreference::getModeString() à la place.

### Description

final public function MongoDB\Driver\ReadPreference::getMode(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'option "mode" du ReadPreference.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette méthode a été supprimée.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\ReadPreference::getMode()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getMode());

    ?>

L'exemple ci-dessus va afficher :

    int(1)
    int(5)
    int(2)
    int(6)
    int(10)

### Voir aussi

- MongoDB\Driver\ReadPreference::getModeString() - Renvoie l'option "mode" du ReadPreference
- » Référence de Read Preference

# MongoDB\Driver\ReadPreference::getModeString

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::getModeString — Renvoie l'option "mode" du ReadPreference

### Description

final public function MongoDB\Driver\ReadPreference::getModeString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'option "mode" du ReadPreference en tant que chaîne.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\ReadPreference::getModeString()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getModeString());

    ?>

L'exemple ci-dessus va afficher :

    string(7) "primary"
    string(16) "primaryPreferred"
    string(9) "secondary"
    string(18) "secondaryPreferred"
    string(7) "nearest"

### Voir aussi

- MongoDB\Driver\ReadPreference::getMode() - Renvoie l'option "mode" du ReadPreference
- » Référence de Read Preference

# MongoDB\Driver\ReadPreference::getTagSets

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getTagSets — Renvoie l'option "tagSets" de ReadPreference

### Description

final public function MongoDB\Driver\ReadPreference::getTagSets(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'option "tagSets" de ReadPreference.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\ReadPreference::getTagSets()

    <?php

    $mode = MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED;

    /* Null et un tableau vide indiquent tous deux l'absence de préférence de jeu de balises. */
    $rp = new MongoDB\Driver\ReadPreference($mode, null);
    var_dump($rp->getTagSets());

    $rp = new MongoDB\Driver\ReadPreference($mode, []);
    var_dump($rp->getTagSets());

    /* Préférer un nœud à New York, mais revenir à tout nœud disponible. */
    $rp = new MongoDB\Driver\ReadPreference($mode, [['dc' => 'ny']]);
    var_dump($rp->getTagSets());

    /* Préférer un nœud à New York, suivi d'un nœud à San Francisco
       étiqueté pour le reporting, et enfin revenir à tout nœud disponible. */
    $rp = new MongoDB\Driver\ReadPreference($mode, [
      ['dc' => 'ny'],
      ['dc' => 'sf', 'use' => 'reporting'],
      [],
    ]);
    var_dump($rp->getTagSets());

    ?>

L'exemple ci-dessus va afficher :

    array(0) {
    }
    array(0) {
    }
    array(2) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(0) {
      }
    }
    array(3) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(2) {
        ["dc"]=>
        string(2) "sf"
        ["use"]=>
        string(9) "reporting"
      }
      [2]=>
      array(0) {
      }
    }

### Voir aussi

- » Référence de Read Preference

## Sommaire

- MongoDB\Driver\ReadPreference::bsonSerialize — Renvoie un objet pour la sérialisation BSON
- MongoDB\Driver\ReadPreference::__construct — Créer un nouveau ReadPreference
- MongoDB\Driver\ReadPreference::getHedge — Renvoie l'option "hedge" du ReadPreference
- MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Renvoie l'option "maxStalenessSeconds" du ReadPreference
- MongoDB\Driver\ReadPreference::getMode — Renvoie l'option "mode" du ReadPreference
- MongoDB\Driver\ReadPreference::getModeString — Renvoie l'option "mode" du ReadPreference
- MongoDB\Driver\ReadPreference::getTagSets — Renvoie l'option "tagSets" de ReadPreference

# La classe MongoDB\Driver\ReadConcern

(mongodb >=1.1.0)

## Introduction

MongoDB\Driver\ReadConcern contrôle le niveau d'isolation pour les opérations de lecture pour les ensembles de réplicas et les fragments d'ensembles de réplicas. Cette option nécessite MongoDB 3.2 ou ultérieur.

## Synopsis de la classe

final class MongoDB\Driver\ReadConcern implements MongoDB\BSON\Serializable, Serializable {
/* Propriétés */
public readonly ?string $level;
/* Constantes */
const string AVAILABLE = "available";
const string LINEARIZABLE = "linearizable";
const string LOCAL = "local";
const string MAJORITY = "majority";
const string SNAPSHOT = "snapshot";
/* Méthodes */
final public function bsonSerialize(): stdClass
final public function __construct(?string `$level` = `null`)
final public function getLevel(): ?string
final public function isDefault(): bool
}

## Propriétés

level
  Le niveau de lecture. `null` si aucun niveau n'a été spécifié.

## Constantes pré-définies

`MongoDB\Driver\ReadConcern::AVAILABLE`
  Par défaut pour les lectures sur les secondaires lorsque `afterClusterTime` et `level` ne sont pas spécifiés. La requête renvoie les données les plus récentes de l'instance. Ne garantit pas que les données ont été écrites sur la majorité des membres de l'ensemble de réplicas (c'est-à-dire qu'elles peuvent être annulées). Pour les collections non fragmentées (y compris les collections dans un déploiement autonome ou un déploiement de réplicas), les lectures `"local"` et `"available"` se comportent de manière identique. Pour un cluster partagé, la lecture `"available"` fournit une plus grande tolérance aux partitions car elle n'attend pas pour garantir des garanties de cohérence. Cependant, une requête avec une lecture `"available"` peut renvoyer des documents orphelins si le fragment est en cours de migration de morceaux car la lecture `"available"`, contrairement à la lecture `"local"`, ne contacte pas le primaire du fragment ni les serveurs de configuration pour obtenir des métadonnées mises à jour.
`MongoDB\Driver\ReadConcern::LINEARIZABLE`
  La requête renvoie les données qui reflètent toutes les écritures réussies émises avec un niveau d'écriture de `"majority"` et reconnu avant le début de l'opération de lecture. Pour les ensembles de réplicas qui fonctionnent avec `writeConcernMajorityJournalDefault` défini sur `true`, la lecture linéarisable renvoie des données qui ne seront jamais annulées. Avec `writeConcernMajorityJournalDefault` défini sur `false`, MongoDB n'attendra pas que les écritures `w: "majority"` soient durables avant d'accuser réception des écritures. En tant que tel, les opérations d'écriture `"majority"` pourraient éventuellement être annulées en cas de perte d'un membre de l'ensemble de réplicas. Il est possible de spécifier un niveau de lecture linéarisable pour les opérations de lecture sur le primaire uniquement. La lecture linéarisable garantit que les opérations de lecture spécifient un filtre de requête qui identifie de manière unique un seul document.
  Astuce

  Toujours utiliser `maxTimeMS` avec une lecture linéarisable en cas de non-disponibilité de la majorité des membres porteurs de données. `maxTimeMS` garantit que l'opération ne bloque pas indéfiniment et garantit plutôt que l'opération renvoie une erreur si le niveau de lecture ne peut pas être satisfait.

  La lecture linéarisable nécessite MongoDB 3.4.
`MongoDB\Driver\ReadConcern::LOCAL`
  Défaut pour les lectures sur le primaire si `level` n'est pas spécifié et pour les lectures sur les secondaires si `level` n'est pas spécifié mais que `afterClusterTime` est spécifié. La requête renvoie les données les plus récentes de l'instance. Ne garantit pas que les données ont été écrites sur la majorité des membres de l'ensemble de réplicas (c'est-à-dire qu'elles peuvent être annulées).
`MongoDB\Driver\ReadConcern::MAJORITY`
  La requête renvoie les données les plus récentes reconnues comme ayant été écrites sur la majorité des membres de l'ensemble de réplicas. Pour utiliser le niveau de lecture `"majority"`, les ensembles de réplicas doivent utiliser le moteur de stockage WiredTiger et le protocole d'élection version 1.
`MongoDB\Driver\ReadConcern::SNAPSHOT`
  La lecture `"snapshot"` est disponible pour les transactions multi-documents, et à partir de MongoDB 5.0, pour certaines opérations de lecture en dehors des transactions multi-documents. Si la transaction ne fait pas partie d'une session cohérente, lors de la validation de la transaction avec un niveau d'écriture `"majority"`, les opérations de transaction sont garanties d'avoir lu à partir d'un instantané des données majoritairement engagées. Si la transaction fait partie d'une session cohérente, lors de la validation de la transaction avec un niveau d'écriture `"majority"`, les opérations de transaction sont garanties d'avoir lu à partir d'un instantané des données majoritairement engagées qui assure la cohérence causale avec l'opération immédiatement précédent le début de la transaction. En dehors des transactions multi-documents, le niveau de lecture `"snapshot"` est disponible sur les primaires et les secondaires pour les opérations de lecture suivantes : `find`, `aggregate` et `distinct` (sur les collections non fragmentées). Toutes les autres commandes de lecture interdisent `"snapshot"`.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.
PECL mongodb 1.11.0 | Ajout de la constante `MongoDB\Driver\ReadConcern::SNAPSHOT`.
PECL mongodb 1.7.0 | Implémente Serializable.
PECL mongodb 1.4.0 | Ajout de la constante `MongoDB\Driver\ReadConcern::MAJORITY`.
PECL mongodb 1.2.0 | Ajout de la constante `MongoDB\Driver\ReadConcern::LINEARIZABLE` Implémente MongoDB\BSON\Serializable.

## Voir aussi

- » Référence de lecture

# MongoDB\Driver\ReadConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadConcern::bsonSerialize — Renvoie un objet pour la sérialisation BSON

### Description

final public function MongoDB\Driver\ReadConcern::bsonSerialize(): stdClass

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un objet pour la sérialisation du ReadConcern en BSON.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 MongoDB\Driver\ReadConcern::bsonSerialize() avec un read concern vide

    <?php

    $rc = new MongoDB\Driver\ReadConcern;
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#2 (0) {
    }

    { }

Exemple #2 MongoDB\Driver\ReadConcern::bsonSerialize() avec un read concern local

    <?php

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#2 (1) {
      ["level"]=>
      string(5) "local"
    }

    { "level" : "local" }

### Voir aussi

- MongoDB\BSON\Serializable::bsonSerialize() - Fournit un tableau ou un document à sérialiser en tant que BSON
- » Référence de Read Concern

# MongoDB\Driver\ReadConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::__construct — Créer un nouveau ReadConcern

### Description

final public function MongoDB\Driver\ReadConcern::__construct(?string `$level` = `null`)

Construit un nouvel MongoDB\Driver\ReadConcern, qui est un objet de valeur immuable.

### Liste de paramètres

`level`
  Le » niveau du read concern. Il est possible d'utiliser, sans toutefois s'y limiter, une des constantes de classe.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\ReadConcern::__construct()

    <?php

    /* Niveau de lecture isolé non spécifié (utilise le comportement par défaut du serveur) */
    $rc = new MongoDB\Driver\ReadConcern();

    /* Requête avec un niveau de lecture isolé à partir d'un seul nœud de l'ensemble de réplicas */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);

    /* Requête avec un niveau de lecture isolé à partir d'une majorité des nœuds de l'ensemble de réplicas */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);

    ?>

### Voir aussi

- » Référence de Read Concern

# MongoDB\Driver\ReadConcern::getLevel

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::getLevel — Renvoie l'option "level" du ReadConcern

### Description

final public function MongoDB\Driver\ReadConcern::getLevel(): ?string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'option "level" du ReadConcern.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\ReadConcern::getLevel()

    <?php

    $rc = new MongoDB\Driver\ReadConcern();
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->getLevel());

    ?>

L'exemple ci-dessus va afficher :

    NULL
    string(5) "local"
    string(8) "majority"

### Voir aussi

- » Référence de Read Concern

# MongoDB\Driver\ReadConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\ReadConcern::isDefault — Vérifie si c'est le read concern par défaut

### Description

final public function MongoDB\Driver\ReadConcern::isDefault(): bool

Renvoie si c'est le read concern par défaut (c'est-à-dire sans options spécifiées). Cette méthode est principalement destinée à être utilisée en conjonction avec MongoDB\Driver\Manager::getReadConcern() pour déterminer si le Manager a été construit sans aucune option de read concern.

Le pilote n'inclura pas de read concern par défaut dans ses opérations de lecture (par exemple MongoDB\Driver\Manager::executeQuery()) afin de permettre au serveur d'appliquer son propre défaut. Les bibliothèques qui accèdent au read concern du Manager pour l'inclure dans leurs propres commandes de lecture devraient utiliser cette méthode pour s'assurer que les read concerns par défaut sont laissés non définis.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si c'est le read concern par défaut et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\ReadConcern::isDefault()

    <?php

    $rc = new MongoDB\Driver\ReadConcern(null);
    var_dump($rc->isDefault());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?readConcernLevel=majority');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Voir aussi

- MongoDB\Driver\Manager::getReadConcern() - Renvoie le ReadConcern pour le Manager
- » Référence de Read Concern

## Sommaire

- MongoDB\Driver\ReadConcern::bsonSerialize — Renvoie un objet pour la sérialisation BSON
- MongoDB\Driver\ReadConcern::__construct — Créer un nouveau ReadConcern
- MongoDB\Driver\ReadConcern::getLevel — Renvoie l'option "level" du ReadConcern
- MongoDB\Driver\ReadConcern::isDefault — Vérifie si c'est le read concern par défaut

# La classe MongoDB\Driver\Cursor

(mongodb >=1.0.0)

## Introduction

La classe MongoDB\Driver\Cursor encapsule le résultat d'une commande ou d'une requête MongoDB, pouvant être retournée par, respectivement, MongoDB\Driver\Manager::executeCommand() ou MongoDB\Driver\Manager::executeQuery().

## Synopsis de la classe

final class MongoDB\Driver\Cursor implements MongoDB\Driver\CursorInterface {
/* Méthodes */
final private function __construct()
public function current(): array|object|null
final public function getId(): MongoDB\BSON\Int64
final public function getServer(): MongoDB\Driver\Server
final public function isDead(): bool
public function key(): int
public function next(): void
public function rewind(): void
final public function setTypeMap(array `$typemap`): void
final public function toArray(): array
public function valid(): bool
}

## Historique

Version | Description
--- | ---
PECL mongodb 1.9.0 | Implémente Iterator.
PECL mongodb 1.6.0 | Implémentation de MongoDB\Driver\CursorInterface, qui étend Traversable.

## Exemples

Exemple #1 Lecture d'un jeu de résultats

MongoDB\Driver\Manager::executeCommand() et MongoDB\Driver\Manager::executeQuery() les deux renvoient leur (s) résultat (s) en tant qu'objet MongoDB\Driver\Cursor. Cet objet peut être utilisé pour itérer au sein du jeu de résultats de la commande ou de la requête.

Parce que MongoDB\Driver\Cursor implémente l'interface Traversable, il est possible de simplement itérer sur le jeu de résultats avec `foreach`.

    <?php

    $manager = new MongoDB\Driver\Manager();

    /* Insérez des documents afin que notre requête renvoie des informations */
    $bulkWrite = new MongoDB\Driver\BulkWrite;
    $bulkWrite->insert(['name' => 'Ceres', 'size' => 946, 'distance' => 2.766]);
    $bulkWrite->insert(['name' => 'Vesta', 'size' => 525, 'distance' => 2.362]);
    $manager->executeBulkWrite("test.asteroids", $bulkWrite);

    /* Requête pour tous les éléments de la collection */
    $query = new MongoDB\Driver\Query( [] );

    /* Interrogez la collection  "asteroids" de la base de données "test" */
    $cursor = $manager->executeQuery("test.asteroids", $query);

    /* $cursor contient maintenant un objet qui entoure le jeu de résultats.
     * Utiliser foreach() pour itérer sur tous les résultats */
    foreach($cursor as $document) {
        print_r($document);
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc2
            )

        [name] => Ceres
        [size] => 946
        [distance] => 2.766
    )
    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc3
            )

        [name] => Vesta
        [size] => 525
        [distance] => 2.362
    )

Exemple #2 Lecture d'un jeu de résultats pour un curseur à queue

Les » curseurs à queue sont un type spécial de curseur MongoDB qui permet au client de lire quelques résultats et d'attendre jusqu'à ce que plus de documents deviennent disponibles. Ces curseurs sont principalement utilisés avec » Capped Collections et » Change Streams.

Bien que les curseurs normaux puissent être parcourus une fois avec `foreach`, cette approche ne fonctionnera pas avec les curseurs à queue. Lorsque `foreach` est utilisé avec un curseur à queue, la boucle s'arrêtera à la fin du jeu de résultats initial. Tenter de continuer l'itération sur le curseur avec une seconde `foreach` lèverait une exception, car PHP tente de rembobiner le curseur. Comme pour les objets result dans d'autres pilotes de base de données, les curseurs dans MongoDB prennent uniquement en charge l'itération en avant, ce qui signifie qu'ils ne peuvent pas être rembobinés.

Afin de lire en continu à partir d'un curseur de queue, l'objet Cursor doit être enveloppé avec un IteratorIterator. Cela permet à l'application de contrôler directement l'itération du curseur, d'éviter de rembobiner par inadvertance le curseur et de décider quand attendre les nouveaux résultats ou arrêter complètement l'itération.

Afin de démontrer un curseur en action, deux scripts seront utilisés: un "Producer" et un "Consumer". Le script Producer créera une nouvelle collection plafonnée à l'aide de la commande » Create et procédera à l'insertion d'un nouveau document dans cette collection chaque seconde.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $manager->executeCommand('test', new MongoDB\Driver\Command([
        'create' => 'asteroids',
        'capped' => true,
        'size' => 1048576,
    ]));

    while (true) {
        $bulkWrite = new MongoDB\Driver\BulkWrite;
        $bulkWrite->insert(['createdAt' => new MongoDB\BSON\UTCDateTime]);
        $manager->executeBulkWrite('test.asteroids', $bulkWrite);

        sleep(1);
    }

    ?>

Avec le script Producer toujours en cours d'exécution, un deuxième script consommateur peut être exécuté pour lire les documents insérés à l'aide d'un curseur de queue, indiqué par les options `tailable` et `awaitData` à MongoDB\Driver\Query::__construct().

    <?php

    $manager = new MongoDB\Driver\Manager;

    $query = new MongoDB\Driver\Query([], [
        'tailable' => true,
        'awaitData' => true,
    ]);

    $cursor = $manager->executeQuery('test.asteroids', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();

    while (true) {
        if ($iterator->valid()) {
            $document = $iterator->current();
            printf("Consumed document created at: %s\n", $document->createdAt);
        }

        $iterator->next();
    }

    ?>

Le script consommateur va commencer par imprimer rapidement tous les documents disponibles dans la collection plafonnée (comme si `foreach` avait été utilisé); toutefois, il ne se terminera pas à la fin du jeu de résultats initial. Étant donné que le curseur est en file d'attente, l'appel de IteratorIterator::next() se bloque et attend des résultats supplémentaires. IteratorIterator::valid() est également utilisé pour vérifier s'il y a effectivement des données disponibles à lire à chaque étape.

> Note: Cet exemple utilise l'option de requête `awaitData` pour indiquer au serveur de bloquer pendant une courte période (par exemple une seconde) à la fin du jeu de résultats avant de retourner une réponse au pilote. Ceci est utilisé pour empêcher le pilote d'interroger agressivement le serveur lorsqu'il n'y a aucun résultat disponible. L'option `maxAwaitTimeMS` peut être utilisée conjointement avec `tailable` et `awaitData` pour spécifier la durée pendant laquelle le serveur doit se bloquer lorsqu'il atteint la fin du jeu de résultats.

## Erreurs / Exceptions

Lors de l'itération sur l'objet Cursor, les données BSON sont converties en variables PHP. Cette itération peut provoquer les exceptions suivantes:

- Lève une exception MongoDB\Driver\Exception\InvalidArgumentException si une classe dans le mappage de type ne peut pas être instanciée ou n'implémente pas MongoDB\BSON\Unserializable.
- Lance une exception MongoDB\Driver\Exception\UnexpectedValueException si l'entrée ne contient pas exactement un document BSON. Les raisons possibles comprennent, mais ne sont pas limitées à, BSON invalide, des données supplémentaires (après avoir lu un document BSON), ou une erreur imprévu de » libbson.

# MongoDB\Driver\Cursor::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::__construct — Créer un nouveau curseur (non utilisé)

### Description

final private function MongoDB\Driver\Cursor::__construct()

Les objets MongoDB\Driver\Cursor sont retournés en tant que résultat d'une commande ou d'une requête exécutée et ne peuvent pas être construits directement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- MongoDB\Driver\Manager::executeCommand() - Exécute une commande de base de données
- MongoDB\Driver\Manager::executeQuery() - Exécute une requête de base de données
- MongoDB\Driver\Server::executeCommand() - Exécute une commande de base de données sur ce serveur
- MongoDB\Driver\Server::executeQuery() - Exécute une requête de base de données sur ce serveur

# MongoDB\Driver\Cursor::current

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::current — Renvoie l'élément courant

### Description

public function MongoDB\Driver\Cursor::current(): array|object|null

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le document résultant actuel sous forme de tableau ou d'objet, en fonction du type de carte du curseur. Si l'itération n'a pas commencé ou si la position actuelle n'est pas valide, `null` sera renvoyé.

### Voir aussi

- Iterator::current() - Retourne l'élément courant

# MongoDB\Driver\Cursor::getId

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getId — Retourne l'ID de ce curseur

### Description

final public function MongoDB\Driver\Cursor::getId(): MongoDB\BSON\Int64

Renvoie l'ID de ce curseur, qui identifie de manière unique le curseur sur le serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'ID de ce curseur. L'ID sera retourné sous la forme d'un objet MongoDB\BSON\Int64.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Le type de retour a été changé en MongoDB\BSON\Int64. Le paramètre `asInt64` a été supprimé.
PECL mongodb 1.20.0 | Dépréciation du retour d'un MongoDB\Driver\CursorId. Ajout de l'argument `asInt64` pour faciliter la migration vers les versions futures. Si `asInt64` est `true`, l'ID sera retourné sous la forme d'un MongoDB\BSON\Int64.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Cursor::getId()

    <?php

    /* Dans cet exemple, nous introduisons plusieurs documents dans la collection et
     * spécifions un BatchSize plus petit pour garantir que le premier lot ne contient
     * qu'un sous-ensemble de nos résultats et que le curseur reste ouvert sur le
     * serveur. */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getId(true));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\BSON\Int64)#5 (1) {
      ["integer"]=>
      string(11) "94810124093"
    }

### Voir aussi

- MongoDB\BSON\Int64

# MongoDB\Driver\Cursor::getServer

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getServer — Retourne le serveur associé à ce curseur

### Description

final public function MongoDB\Driver\Cursor::getServer(): MongoDB\Driver\Server

Retourne le MongoDB\Driver\Server associé à ce curseur. Il s'agit du serveur qui a exécuté la MongoDB\Driver\Query ou MongoDB\Driver\Command.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le MongoDB\Driver\Server associé à ce curseur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Cursor::getServer()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getServer());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\Driver\Server)#5 (10) {
      ["host"]=>
      string(9) "localhost"
      ["port"]=>
      int(27017)
      ["type"]=>
      int(1)
      ["is_primary"]=>
      bool(false)
      ["is_secondary"]=>
      bool(false)
      ["is_arbiter"]=>
      bool(false)
      ["is_hidden"]=>
      bool(false)
      ["is_passive"]=>
      bool(false)
      ["last_hello_response"]=>
      array(8) {
        ["isWritablePrimary"]=>
        bool(true)
        ["maxBsonObjectSize"]=>
        int(16777216)
        ["maxMessageSizeBytes"]=>
        int(48000000)
        ["maxWriteBatchSize"]=>
        int(1000)
        ["localTime"]=>
        object(MongoDB\BSON\UTCDateTime)#6 (1) {
          ["milliseconds"]=>
          int(1446505367907)
        }
        ["maxWireVersion"]=>
        int(3)
        ["minWireVersion"]=>
        int(0)
        ["ok"]=>
        float(1)
      }
      ["round_trip_time"]=>
      int(584)
    }

### Voir aussi

- MongoDB\Driver\Server

# MongoDB\Driver\Cursor::isDead

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::isDead — Vérifie si le curseur est épuisé ou peut avoir des résultats supplémentaires

### Description

final public function MongoDB\Driver\Cursor::isDead(): bool

Vérifie s'il n'y a plus aucun résultat supplémentaire disponible sur le curseur. Cette méthode est similaire à la méthode » cursor.isExhausted() dans le shell MongoDB et son utilité primaire est lors de l'itération de » curseurs de queue.

Un curseur n'a plus de résultats supplémentaires et est considéré "mort" s'il satisfait l'une des conditions ci-dessous:

- Le lot actuel a été complètement itéré et l'ID du curseur est zéro (c.à.d. il est impossible de délivrer un » getMore).
- Une erreur a été rencontrée lors de l'itération du curseur.
- Le curseur a atteint sa limite configurée.

Par sa conception, il n'est pas toujours possible de déterminer si un curseur a des résultats supplémentaires. Les cas où un curseur peut avoir plus de données disponibles sont les suivants :

- Il y a des documents supplémentaires dans le lot courant, qui sont tamponnés du côté client. Itérer récupérera un document du tampon local.
- Il n'y a pas de documents supplémentaires dans le lot courant (c.à.d. tampon local), mais l'ID du curseur est différent de zéro. Itérer sollicitera plus de documents depuis le serveur via une opération » getMore, qui retournera ou pas des résultats supplémentaires et / ou indiquera que le curseur a été fermé sur le serveur en retournant zéro pour son ID.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si c'est confirmé qu'aucun résultat supplémentaire n'est disponible sur le curseur, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Cursor::isDead()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Voir aussi

- » Tailable Cursors in the MongoDB manual
- » cursor.isExhausted() in the MongoDB manual

# MongoDB\Driver\Cursor::key

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::key — Renvoie le numéro de l'index du résultat courant dans le curseur

### Description

public function MongoDB\Driver\Cursor::key(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'index numérique du résultat actuel dans le curseur.

### Voir aussi

- Iterator::key() - Retourne la clé de l'élément courant

# MongoDB\Driver\Cursor::next

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::next — Avance le curseur vers le résultat suivant

### Description

public function MongoDB\Driver\Cursor::next(): void

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Déplace la position actuelle vers l'élément suivant dans le curseur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification

### Voir aussi

- Iterator::next() - Se déplace sur l'élément suivant

# MongoDB\Driver\Cursor::rewind

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::rewind — Rembobine le curseur jusqu'au premier résultat

### Description

public function MongoDB\Driver\Cursor::rewind(): void

Si le curseur a avancé au-delà de sa première position, il ne peut plus être rembobiné.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`null`.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\LogicException si cette méthode est appelée après que le curseur a avancé au-delà de sa première position.

### Voir aussi

- Iterator::rewind() - Replace l'itérateur sur le premier élément

# MongoDB\Driver\Cursor::setTypeMap

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::setTypeMap — Définit un type de carte à utiliser pour la désérialisation BSON

### Description

final public function MongoDB\Driver\Cursor::setTypeMap(array `$typemap`): void

Définit la configuration de mappage de type à utiliser lors de la désérialisation des résultats BSON en valeurs PHP.

### Liste de paramètres

`typeMap` (array)
  Configuration du type de carte.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

Lors de l'itération sur le curseur, les exceptions suivantes peuvent également être levées en raison d'une configuration de mappage de type incorrecte :

- Lève une exception MongoDB\Driver\Exception\InvalidArgumentException si une classe dans le mappage de type ne peut pas être instanciée ou n'implémente pas MongoDB\BSON\Unserializable.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Cursor::setTypeMap()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $id = $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query(['_id' => $id]);
    $cursor = $manager->executeQuery('db.collection', $query);
    $cursor->setTypeMap(['root' => 'array']);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(2) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#6 (1) {
        ["oid"]=>
        string(24) "56424fb76118fd3267180741"
      }
      ["x"]=>
      int(1)
    }

### Voir aussi

- Persister des données

# MongoDB\Driver\Cursor::toArray

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::toArray — Retourne un tableau contenant tous les résultats pour ce curseur

### Description

final public function MongoDB\Driver\Cursor::toArray(): array

Itère le curseur et retourne ses résultats dans un tableau. MongoDB\Driver\Cursor::setTypeMap() peut être utilisé pour contrôler comment les documents sont désérialisés en valeurs PHP.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau contenant tous les résultats pour ce curseur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Cursor::toArray()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query([]);
    $cursor = $manager->executeQuery('db.collection', $query);

    var_dump($cursor->toArray());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(3) {
      [0]=>
      object(stdClass)#6 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#5 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf61"
        }
        ["x"]=>
        int(1)
      }
      [1]=>
      object(stdClass)#8 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#7 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf62"
        }
        ["x"]=>
        int(2)
      }
      [2]=>
      object(stdClass)#10 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#9 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf63"
        }
        ["x"]=>
        int(3)
      }
    }

### Voir aussi

- MongoDB\Driver\Cursor::setTypeMap() - Définit un type de carte à utiliser pour la désérialisation BSON

# MongoDB\Driver\Cursor::valid

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::valid — Vérifie si la position actuelle du curseur est valide

### Description

public function MongoDB\Driver\Cursor::valid(): bool

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si la position actuelle du curseur est valide, sinon `false`.

### Voir aussi

- Iterator::valid() - Vérifie si la position courante est valide

## Sommaire

- MongoDB\Driver\Cursor::__construct — Créer un nouveau curseur (non utilisé)
- MongoDB\Driver\Cursor::current — Renvoie l'élément courant
- MongoDB\Driver\Cursor::getId — Retourne l'ID de ce curseur
- MongoDB\Driver\Cursor::getServer — Retourne le serveur associé à ce curseur
- MongoDB\Driver\Cursor::isDead — Vérifie si le curseur est épuisé ou peut avoir des résultats supplémentaires
- MongoDB\Driver\Cursor::key — Renvoie le numéro de l'index du résultat courant dans le curseur
- MongoDB\Driver\Cursor::next — Avance le curseur vers le résultat suivant
- MongoDB\Driver\Cursor::rewind — Rembobine le curseur jusqu'au premier résultat
- MongoDB\Driver\Cursor::setTypeMap — Définit un type de carte à utiliser pour la désérialisation BSON
- MongoDB\Driver\Cursor::toArray — Retourne un tableau contenant tous les résultats pour ce curseur
- MongoDB\Driver\Cursor::valid — Vérifie si la position actuelle du curseur est valide

# La classe MongoDB\Driver\CursorId

(mongodb >=1.0.0)

## Introduction

La classe MongoDB\Driver\CursorID est un objet valeur qui représente un identificateur de curseur. Les instances de cette classe sont retournées par MongoDB\Driver\Cursor::getId().

Avertissement

Cette classe a été DÉPRÉCIÉE depuis la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications devraient mettre à jour leur utilisation de MongoDB\Driver\Cursor::getId() pour retourner MongoDB\BSON\Int64 à la place.

## Synopsis de la classe

final class MongoDB\Driver\CursorId implements Serializable, Stringable {
/* Méthodes */
final private function __construct()
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe a été supprimée.
PECL mongodb 1.20.0 | Cette classe a été dépréciée et sera supprimée dans la version 2.0.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.
PECL mongodb 1.7.0 | Implémente Serializable.

# MongoDB\Driver\CursorId::__construct

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__construct — Créer un nouveau CursorId (non utilisé)

### Description

final private function MongoDB\Driver\CursorId::__construct()

Les objets MongoDB\Driver\CursorId sont retournés par MongoDB\Driver\Cursor::getId() et ne peuvent pas être construits directement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- MongoDB\Driver\Cursor::getId() - Retourne l'ID de ce curseur

# MongoDB\Driver\CursorId::__toString

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__toString — Représentation sous forme de chaîne de l'ID de curseur

### Description

final public function MongoDB\Driver\CursorId::__toString(): string

Retourne la représentation sous forme de chaîne de caractères de l'ID de curseur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de caractères de l'ID de curseur.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\CursorId::__toString()

    <?php

    /* Dans cet exemple, nous introduisons plusieurs documents dans la collection et
     * spécifions un BatchSize plus petit pour garantir que le premier lot ne contient
     * qu'un sous-ensemble de nos résultats et que le curseur reste ouvert sur le
     * serveur. */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump((string) $cursor->getId());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(11) "98061641158"

### Voir aussi

- MongoDB\Driver\Cursor::getId() - Retourne l'ID de ce curseur

## Sommaire

- MongoDB\Driver\CursorId::__construct — Créer un nouveau CursorId (non utilisé)
- MongoDB\Driver\CursorId::__toString — Représentation sous forme de chaîne de l'ID de curseur

# L'interface MongoDB\Driver\CursorInterface

(mongodb >=1.6.0)

## Introduction

Cette interface est implémentée par MongoDB\Driver\Cursor pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateur.

## Synopsis de la classe

class MongoDB\Driver\CursorInterface implements Iterator {
/* Méthodes */
abstract public function getId(): MongoDB\BSON\Int64
abstract public function getServer(): MongoDB\Driver\Server
abstract public function isDead(): bool
abstract public function setTypeMap(array `$typemap`): void
abstract public function toArray(): array
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette interface étend désormais Iterator. Les types de retour précédemment déclarés comme étant tentatifs sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\Driver\CursorInterface::getId

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getId — Renvoie l'ID du curseur

### Description

abstract public function MongoDB\Driver\CursorInterface::getId(): MongoDB\BSON\Int64

Renvoie l'ID de ce curseur, qui identifie de manière unique le curseur sur le serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'ID de ce curseur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 1.20.0 | Ajout de MongoDB\BSON\Int64 au type de retour provisoire pour cette méthode. MongoDB\Driver\CursorId sera supprimé du type de retour dans la version 2.0.

### Voir aussi

- MongoDB\Driver\Cursor::getId() - Retourne l'ID de ce curseur
- MongoDB\Driver\CursorId
- MongoDB\BSON\Int64

# MongoDB\Driver\CursorInterface::getServer

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getServer — Renvoie le serveur associé à ce curseur

### Description

abstract public function MongoDB\Driver\CursorInterface::getServer(): MongoDB\Driver\Server

Renvoie le MongoDB\Driver\Server associé à ce curseur. C'est le serveur qui a exécuté la MongoDB\Driver\Query ou MongoDB\Driver\Command.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le MongoDB\Driver\Server pour ce curseur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Cursor::getServer() - Retourne le serveur associé à ce curseur
- MongoDB\Driver\Server

# MongoDB\Driver\CursorInterface::isDead

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::isDead — Renvoie si le curseur peut avoir des résultats supplémentaires

### Description

abstract public function MongoDB\Driver\CursorInterface::isDead(): bool

Vérifie si le curseur peut avoir des résultats supplémentaires à lire. Un curseur est initialement "vivant" mais peut devenir "mort" pour l'une des raisons suivantes :

- Avancer un curseur non-tailable n'a pas renvoyé de document
- Le curseur a rencontré une erreur
- Le curseur a lu son dernier lot jusqu'à la fin
- Le curseur a atteint sa limite configurée

C'est principalement utile avec les curseurs tailables.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si des résultats supplémentaires ne sont pas disponibles, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Cursor::isDead() - Vérifie si le curseur est épuisé ou peut avoir des résultats supplémentaires

# MongoDB\Driver\CursorInterface::setTypeMap

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::setTypeMap — Définit une carte de type à utiliser pour la désérialisation BSON

### Description

abstract public function MongoDB\Driver\CursorInterface::setTypeMap(array `$typemap`): void

Définit la configuration type map à utiliser lors de la désérialisation des résultats BSON en valeurs PHP.

### Liste de paramètres

`typeMap` (array)
  Configuration du type de carte.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Cursor::setTypeMap() - Définit un type de carte à utiliser pour la désérialisation BSON
- Persister des données

# MongoDB\Driver\CursorInterface::toArray

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::toArray — Renvoie un tableau contenant tous les résultats de ce curseur

### Description

abstract public function MongoDB\Driver\CursorInterface::toArray(): array

Itère le curseur et renvoie ses résultats dans un tableau. MongoDB\Driver\CursorInterface::setTypeMap() peut être utilisé pour contrôler comment les documents sont désérialisés en valeurs PHP.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un array contenant tous les résultats de ce curseur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Cursor::toArray() - Retourne un tableau contenant tous les résultats pour ce curseur
- MongoDB\Driver\CursorInterface::setTypeMap() - Définit une carte de type à utiliser pour la désérialisation BSON

## Sommaire

- MongoDB\Driver\CursorInterface::getId — Renvoie l'ID du curseur
- MongoDB\Driver\CursorInterface::getServer — Renvoie le serveur associé à ce curseur
- MongoDB\Driver\CursorInterface::isDead — Renvoie si le curseur peut avoir des résultats supplémentaires
- MongoDB\Driver\CursorInterface::setTypeMap — Définit une carte de type à utiliser pour la désérialisation BSON
- MongoDB\Driver\CursorInterface::toArray — Renvoie un tableau contenant tous les résultats de ce curseur

# La classe MongoDB\Driver\Server

(mongodb >=1.0.0)

## Introduction

## Synopsis de la classe

final class MongoDB\Driver\Server {
/* Constantes */
const int TYPE_UNKNOWN = 0;
const int TYPE_STANDALONE = 1;
const int TYPE_MONGOS = 2;
const int TYPE_POSSIBLE_PRIMARY = 3;
const int TYPE_RS_PRIMARY = 4;
const int TYPE_RS_SECONDARY = 5;
const int TYPE_RS_ARBITER = 6;
const int TYPE_RS_OTHER = 7;
const int TYPE_RS_GHOST = 8;
const int TYPE_LOAD_BALANCER = 9;
/* Méthodes */
final private function __construct()
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getHost(): string
final public function getInfo(): array
final public function getLatency(): ?integer
final public function getPort(): int
final public function getServerDescription(): MongoDB\Driver\ServerDescription
final public function getTags(): array
final public function getType(): int
final public function isArbiter(): bool
final public function isHidden(): bool
final public function isPassive(): bool
final public function isPrimary(): bool
final public function isSecondary(): bool
}

## Constantes pré-définies

`MongoDB\Driver\Server::TYPE_UNKNOWN`
  Type de serveur inconnu, retourné par MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_STANDALONE`
  Type de serveur autonome, retourné par MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_MONGOS`
  Type de serveur Mongos, retourné par MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_POSSIBLE_PRIMARY`
  Type de serveur primaire possible du jeu de réplique, retourné par MongoDB\Driver\Server::getType(). Un serveur peut être identifié comme un possible primaire s'il n'a pas encore été vérifié, mais un autre membre du jeu de réplique pense qu'il est le primaire.
`MongoDB\Driver\Server::TYPE_RS_PRIMARY`
  Type de serveur primaire du jeu de réplique, retourné par MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_SECONDARY`
  Type de serveur secondaire du jeu de réplique, retourné par MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_ARBITER`
  Type de serveur arbitre de jeu de réplique, retourné par MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_OTHER`
  Type de serveur autre de jeu de réplique, retourné par MongoDB\Driver\Server::getType(). Ces serveurs peuvent être masqués, en cours de démarrage ou en cours de récupération. Ils ne peuvent pas être interrogés, mais leurs listes d'hôtes sont utiles pour découvrir la configuration actuelle du jeu de réplique.
`MongoDB\Driver\Server::TYPE_RS_GHOST`
  Type de serveur fantôme de jeu de réplique, retourné par MongoDB\Driver\Server::getType(). Les serveurs peuvent être identifiés comme tels dans au moins trois situations : brièvement pendant le démarrage du serveur ; dans un jeu de réplique non initialisé ; ou lorsque le serveur est évité (c'est-à-dire supprimé de la config du jeu de réplique). Ils ne peuvent pas être interrogés et leur liste d'hôtes ne peut pas être utilisée pour découvrir la configuration actuelle du jeu de réplique ; toutefois, le client peut surveiller ce serveur dans l'espoir qu'il change vers un état plus utile.
`MongoDB\Driver\Server::TYPE_LOAD_BALANCER`
  Type de serveur de Load balancer, retourné par MongoDB\Driver\Server::getType().

## Historique

Version | Description
--- | ---
PECL mongodb 1.11.0 | Ajout de la constante `MongoDB\Driver\Server::TYPE_LOAD_BALANCER`.

# MongoDB\Driver\Server::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Server::__construct — Créer un nouveau serveur (non utilisé)

### Description

final private function MongoDB\Driver\Server::__construct()

Les objets MongoDB\Driver\Server sont créés en interne par MongoDB\Driver\Manager lorsqu'une connexion de base de données est établie et peut être retournée par MongoDB\Driver\Manager::getServers() et MongoDB\Driver\Manager::selectServer().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- MongoDB\Driver\Manager::getServers() - Retourner les serveurs auxquels ce gestionnaire est connecté
- MongoDB\Driver\Manager::selectServer() - Sélectionne un serveur correspondant à une préférence de lecture

# MongoDB\Driver\Server::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeBulkWrite — Exécute une ou plusieurs opérations d'écriture sur ce serveur

### Description

final public function MongoDB\Driver\Server::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Exécute une ou plusieurs opérations en écriture sur ce serveur.

Un objet MongoDB\Driver\BulkWrite peut être construit avec une ou plusieurs opérations de types différents (c.-à-d. mise à jour, suppression, et insertion). Le driver va tenter d'envoyer les opérations de même type au serveur en un minimum de requête possible afin d'optimiser les aller/retour.

La valeur par défaut pour l'option `"writeConcern"` sera déduite d'une transaction active (indiquée par l'option `"session"`), puis par le URI de connexion.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`bulk` (MongoDB\Driver\BulkWrite)
  Écriture(s) à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

### Valeurs de retour

Retourne un MongoDB\Driver\WriteResult en cas de succès.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si `bulk` ne contient aucune opération d'écriture.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si `bulk` a déjà été exécuté. Les objets MongoDB\Driver\BulkWrite ne peuvent pas être exécutés plusieurs fois.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une exception MongoDB\Driver\BulkWriteException lors d'une erreur d'une opération en écriture (une erreur WriteError et WriteConcern)
- Lance une exception MongoDB\Driver\Exception\RuntimeException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Le paramètre `options` n'accepte désormais plus d'instance MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Passer un objet MongoDB\Driver\WriteConcern en tant qu'`options` est obsolète et sera supprimé dans la 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException sera lancé si l'option `"session"` est utilisée conjointement avec un write concern non reconnu.
PECL mongodb 1.4.0 | Le troisième paramètre est maintenant un tableau d'`options`. Pour la compatibilité ascendante, ce paramètre acceptera toujours un objet MongoDB\Driver\WriteConcern.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException est maintenant levé si `bulk` ne contient pas d'opérations d'écriture. Auparavant, une MongoDB\Driver\Exception\BulkWriteException était levée.

### Notes

> Note: Il est de la responsabilité de l'appelant de s'assurer que le serveur est capable d'exécuter l'opération d'écriture. Par exemple, l'exécution d'une opération d'écriture sur un secondaire (à l'exclusion de sa base de données "local") échouera.

### Voir aussi

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWrite() - Exécute une ou plusieurs opérations d'écriture

# MongoDB\Driver\Server::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Server::executeBulkWriteCommand — Exécute des opérations d'écriture sur ce serveur en utilisant la commande bulkWrite

### Description

final public function MongoDB\Driver\Server::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Exécute une ou plusieurs opérations d'écriture sur ce serveur en utilisant la commande » bulkWrite introduite dans MongoDB 8.0.

Une MongoDB\Driver\BulkWriteCommand peut être construite avec une ou plusieurs opérations d'écriture de types variés (par exemple, des insertions, mises à jour et suppressions). Chaque opération d'écriture peut cibler une différente collection.

La valeur par défaut pour l'option `"writeConcern"` sera déduite d'une transaction active (indiquée par l'option `"session"`), suivie de l'URI de connexion.

### Liste de paramètres

`bulk` (MongoDB\Driver\BulkWriteCommand)
  Écriture(s) à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

### Valeurs de retour

Retourne un MongoDB\Driver\BulkWriteCommandResult en cas de succès.

### Erreurs / Exceptions

- Lance une MongoDB\Driver\Exception\InvalidArgumentException si `bulk` ne contient pas d'opérations d'écriture valides.
- Lance une MongoDB\Driver\Exception\InvalidArgumentException si `bulk` a déjà été exécutée. Les objets MongoDB\Driver\BulkWriteCommand ne peuvent pas être exécutés plusieurs fois.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une exception MongoDB\Driver\Exception\BulkWriteCommandException lors d'une erreur d'écriture (par exemple, échec de commande, erreur d'écriture ou d'écriture préoccupante)
- Lance MongoDB\Driver\Exception\RuntimeException en cas d'autre erreur.

### Voir aussi

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite

# MongoDB\Driver\Server::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeCommand — Exécute une commande de base de données sur ce serveur

### Description

final public function MongoDB\Driver\Server::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Exécute une commande sur ce serveur.

Cette méthode n'applique aucune logique spéciale à la commande. Les valeurs par défaut pour les options `"readPreference"`, `"readConcern"`, et `"writeConcern"` seront déduites d'une transaction active (indiquée par l'option `"session"`). S'il n'y a pas de transaction active, une préférence de lecture primaire sera utilisée pour la sélection du serveur.

Les valeurs par défaut ne seront pas déduites de l'URI de connexion. Il est donc recommandé aux utilisateurs d'utiliser des méthodes de commande de lecture et/ou d'écriture spécifiques si possible.

> Note: L'option `readPreference` ne contrôle pas le serveur vers lequel le pilote émet l'opération; il sera toujours exécuté sur cet objet serveur. Au lieu de cela, il peut être utilisé lors de l'émission de l'opération à un secondaire (à partir d'une connexion de jeu de répliques, pas autonome) ou le nœud Mongos pour s'assurer que le pilote définit le protocole de fil en conséquence ou ajoute la préférence de lecture à l'opération, respectivement.

### Liste de paramètres

`db` (string)
  Le nom de la base de données sur laquelle la commande sera exécutée.
`command` (MongoDB\Driver\Command)
  La commande à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Une préoccupation de lecture à appliquer à l'opération. Cette option est disponible dans MongoDB 3.2+ et se traduira par une exception au moment de l'exécution si elle est spécifiée pour une version plus ancienne du serveur.
  readPreference | MongoDB\Driver\ReadPreference | Une préférence de lecture à utiliser pour sélectionner un serveur pour l'opération.
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

  Avertissement

  Si vous utilisez une `"session"` qui a une transaction en cours, vous ne pouvez pas spécifier l'option `"readConcern"` ou `"writeConcern"`. Tenter de faire ceci lancera une exception MongoDB\Driver\Exception\InvalidArgumentException. À la place vous devriez définir ces options quand vous créez la transaction avec MongoDB\Driver\Session::startTransaction().

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une exception MongoDB\Driver\Exception\RuntimeException si une erreur survient (c.-à-d. commande invalide, l'envoi d'une commande en écriture sur un secondaire).

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Le paramètre `options` n'accepte désormais plus d'instance MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Passer un objet MongoDB\Driver\ReadPreference en tant qu'`options` est obsolète et sera supprimé dans la 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException sera lancé si l'option `"session"` est utilisée conjointement avec un write concern non reconnu.
PECL mongodb 1.4.0 | Le troisième paramètre est maintenant un tableau d'`options`. Pour la compatibilité ascendante, ce paramètre acceptera toujours un objet MongoDB\Driver\ReadPreference.

### Notes

> Note: Il est de la responsabilité de l'appelant de s'assurer que le serveur est capable d'exécuter l'opération d'écriture. Par exemple, l'exécution d'une opération d'écriture sur un secondaire (à l'exclusion de sa base de données "local") échouera.

### Voir aussi

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeReadCommand() - Exécute une commande de base de données qui lit sur ce serveur
- MongoDB\Driver\Server::executeReadWriteCommand() - Exécute une commande de base de données qui lit et écrit sur ce serveur
- MongoDB\Driver\Server::executeWriteCommand() - Exécute une commande de base de données qui écrit sur ce serveur
- MongoDB\Driver\Manager::executeCommand() - Exécute une commande de base de données

# MongoDB\Driver\Server::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeQuery — Exécute une requête de base de données sur ce serveur

### Description

final public function MongoDB\Driver\Server::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Exécute la requête sur ce serveur.

Les valeurs par défaut pour l'option `"readPreference"` et l'option `"readConcern"` de la requête seront déduites d'une transaction active (indiquée par l'option `"session"`), puis par l'URI de connexion.

> Note: L'option `readPreference` ne contrôle pas le serveur vers lequel le pilote émet l'opération; il sera toujours exécuté sur cet objet serveur. Au lieu de cela, il peut être utilisé lors de l'émission de l'opération à un secondaire (à partir d'une connexion de jeu de répliques, pas autonome) ou le nœud Mongos pour s'assurer que le pilote définit le protocole de fil en conséquence ou ajoute la préférence de lecture à l'opération, respectivement.

### Liste de paramètres

`namespace` (string)
  Un espace de noms totalement qualifié (e.g. `"databaseName.collectionName"`)
`query` (MongoDB\Driver\Query)
  La requête à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Une préférence de lecture à utiliser pour sélectionner un serveur pour l'opération.
  session | MongoDB\Driver\Session | Une session à associer à l'opération.

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une exception MongoDB\Driver\Exception\RuntimeException si une erreur survient (c.-à-d. opérateurs de requête invalides).

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Le paramètre `options` n'accepte désormais plus d'instance MongoDB\Driver\WriteConcern.
PECL mongodb 1.21.0 | Passer un objet MongoDB\Driver\ReadPreference en tant qu'`options` est obsolète et sera supprimé dans la 2.0.
PECL mongodb 1.4.0 | Le troisième paramètre est maintenant un tableau d'`options`. Pour la compatibilité ascendante, ce paramètre acceptera toujours un objet MongoDB\Driver\ReadPreference.

### Voir aussi

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::executeQuery() - Exécute une requête de base de données

# MongoDB\Driver\Server::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadCommand — Exécute une commande de base de données qui lit sur ce serveur

### Description

final public function MongoDB\Driver\Server::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Exécute la commande sur ce serveur, indépendamment de l'option `"readPreference"`.

Cette méthode appliquera une logique spécifique aux commandes de lecture (par exemple » distinct). Les valeurs par défaut pour les options `"readPreference"` et `"readConcern"` seront déduites d'une transaction active (indiquée par l'option `"session"`), suivie de l' URI de connexion.

> Note: L'option `readPreference` ne contrôle pas le serveur vers lequel le pilote émet l'opération; il sera toujours exécuté sur cet objet serveur. Au lieu de cela, il peut être utilisé lors de l'émission de l'opération à un secondaire (à partir d'une connexion de jeu de répliques, pas autonome) ou le nœud Mongos pour s'assurer que le pilote définit le protocole de fil en conséquence ou ajoute la préférence de lecture à l'opération, respectivement.

### Liste de paramètres

`db` (string)
  Le nom de la base de données sur laquelle la commande sera exécutée.
`command` (MongoDB\Driver\Command)
  La commande à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Une préoccupation de lecture à appliquer à l'opération. Cette option est disponible dans MongoDB 3.2+ et se traduira par une exception au moment de l'exécution si elle est spécifiée pour une version plus ancienne du serveur.
  readPreference | MongoDB\Driver\ReadPreference | Une préférence de lecture à utiliser pour sélectionner un serveur pour l'opération.
  session | MongoDB\Driver\Session | Une session à associer à l'opération.

  Avertissement

  Si vous utilisez une `"session"` qui a une transaction en cours, vous ne pouvez pas spécifier l'option `"readConcern"` ou `"writeConcern"`. Tenter de faire ceci lancera une exception MongoDB\Driver\Exception\InvalidArgumentException. À la place vous devriez définir ces options quand vous créez la transaction avec MongoDB\Driver\Session::startTransaction().

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs (par exemple: commande invalide).

### Voir aussi

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Exécute une commande de base de données sur ce serveur
- MongoDB\Driver\Server::executeReadWriteCommand() - Exécute une commande de base de données qui lit et écrit sur ce serveur
- MongoDB\Driver\Server::executeWriteCommand() - Exécute une commande de base de données qui écrit sur ce serveur
- MongoDB\Driver\Manager::executeReadCommand() - Exécute une commande de base de données qui lit

# MongoDB\Driver\Server::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadWriteCommand — Exécute une commande de base de données qui lit et écrit sur ce serveur

### Description

final public function MongoDB\Driver\Server::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Exécute la commande sur ce serveur.

Cette méthode appliquera une logique spécifique aux commandes de lecture et d'écriture (par exemple » aggregate). Les valeurs par défaut pour les options `"readConcern"` et `"writeConcern"` seront déduites d'une transaction active (indiquée par l'option `"session"`), suivie de l' URI de connexion.

### Liste de paramètres

`db` (string)
  Le nom de la base de données sur laquelle la commande sera exécutée.
`command` (MongoDB\Driver\Command)
  La commande à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Une préoccupation de lecture à appliquer à l'opération. Cette option est disponible dans MongoDB 3.2+ et se traduira par une exception au moment de l'exécution si elle est spécifiée pour une version plus ancienne du serveur.
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

  Avertissement

  Si vous utilisez une `"session"` qui a une transaction en cours, vous ne pouvez pas spécifier l'option `"readConcern"` ou `"writeConcern"`. Tenter de faire ceci lancera une exception MongoDB\Driver\Exception\InvalidArgumentException. À la place vous devriez définir ces options quand vous créez la transaction avec MongoDB\Driver\Session::startTransaction().

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs (par exemple: commande invalide).

### Historique

Version | Description
--- | ---
PECL mongodb 1.4.4 | Une MongoDB\Driver\Exception\InvalidArgumentException va être lancée si l'option `"session"` est utilisée en combinaison avec un writeConcern non reconnu.

### Notes

> Note: Il est de la responsabilité de l'appelant de s'assurer que le serveur est capable d'exécuter l'opération d'écriture. Par exemple, l'exécution d'une opération d'écriture sur un secondaire (à l'exclusion de sa base de données "local") échouera.

### Voir aussi

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Exécute une commande de base de données sur ce serveur
- MongoDB\Driver\Server::executeReadCommand() - Exécute une commande de base de données qui lit sur ce serveur
- MongoDB\Driver\Server::executeWriteCommand() - Exécute une commande de base de données qui écrit sur ce serveur
- MongoDB\Driver\Manager::executeReadWriteCommand() - Exécute une commande de base de données qui lit et écrit

# MongoDB\Driver\Server::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeWriteCommand — Exécute une commande de base de données qui écrit sur ce serveur

### Description

final public function MongoDB\Driver\Server::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Exécute la commande sur ce serveur.

Cette méthode appliquera une logique spécifique aux commandes qui écrivent (par exemple » drop). La valeur par défaut pour l'option `"writeConcern"` sera déduite d'une transaction active (indiquée par l'option `"session"`), suivie de l' URI de connexion.

> Note: Cette méthode n'est pas destinée à être utilisée pour exécuter » insert, » update, ou » delete commandes. Les utilisateurs sont encouragés à utiliser MongoDB\Driver\Server::executeBulkWrite() pour ces opérations.

### Liste de paramètres

`db` (string)
  Le nom de la base de données sur laquelle la commande sera exécutée.
`command` (MongoDB\Driver\Command)
  La commande à exécuter.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Une session à associer à l'opération.
  writeConcern | MongoDB\Driver\WriteConcern | Une préoccupation d'écriture à appliquer à l'opération.

  Avertissement

  Si vous utilisez une `"session"` qui a une transaction en cours, vous ne pouvez pas spécifier l'option `"readConcern"` ou `"writeConcern"`. Tenter de faire ceci lancera une exception MongoDB\Driver\Exception\InvalidArgumentException. À la place vous devriez définir ces options quand vous créez la transaction avec MongoDB\Driver\Session::startTransaction().

### Valeurs de retour

Retourne un MongoDB\Driver\Cursor en cas de succès.

### Erreurs / Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si l'option `"session"` est utilisée conjointement avec une préoccupation d'écriture non reconnu.
- Lance une exception MongoDB\Driver\AuthenticationException si une identification est nécessaire mais qu'elle échoue
- Lance une exception MongoDB\Driver\ConnectionException si la connexion au serveur échoue pour une autre raison qu'en raison d'un problème d'identification
- Lance une MongoDB\Driver\Exception\RuntimeException sur d'autres erreurs (par exemple: commande invalide).

### Historique

Version | Description
--- | ---
PECL mongodb 1.4.4 | Une MongoDB\Driver\Exception\InvalidArgumentException va être lancée si l'option `"session"` est utilisée en combinaison avec un writeConcern non reconnu.

### Notes

> Note: Il est de la responsabilité de l'appelant de s'assurer que le serveur est capable d'exécuter l'opération d'écriture. Par exemple, l'exécution d'une opération d'écriture sur un secondaire (à l'exclusion de sa base de données "local") échouera.

### Voir aussi

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Exécute une commande de base de données sur ce serveur
- MongoDB\Driver\Server::executeReadCommand() - Exécute une commande de base de données qui lit sur ce serveur
- MongoDB\Driver\Server::executeReadWriteCommand() - Exécute une commande de base de données qui lit et écrit sur ce serveur
- MongoDB\Driver\Manager::executeWriteCommand() - Exécute une commande de base de données qui écrit

# MongoDB\Driver\Server::getHost

(mongodb >=1.0.0)

MongoDB\Driver\Server::getHost — Retourne le nom d'hôte du serveur

### Description

final public function MongoDB\Driver\Server::getHost(): string

Retourne le nom d'hôte du serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nom d'hôte du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Server::getHost()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

    $server = $manager->selectServer();

    var_dump($server->getHost());

    ?>

L'exemple ci-dessus va afficher :

    string(9) "localhost"

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur
- MongoDB\Driver\ServerDescription::getHost() - Renvoie le nom d'hôte de ce serveur

# MongoDB\Driver\Server::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\Server::getInfo — Retourne un tableau d'informations décrivant ce serveur

### Description

final public function MongoDB\Driver\Server::getInfo(): array

Retourne un tableau d'informations décrivant le serveur. Ce tableau est dérivé de la réponse la plus récente à la commande » hello obtenue par la » surveillance du serveur.

> Note: Lorsque le pilote est connecté à un équilibreur de charge, cette méthode retourne la réponse à la commande » hello du serveur de backing lors de la poignée de main initiale de la connexion. Cela contraste avec d'autres méthodes (par exemple, MongoDB\Driver\Server::getType()), qui renverront des informations sur l'équilibreur de charge lui-même.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau d'informations décrivant ce serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Server::getInfo()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/');

    $rp = new MongoDB\Driver\ReadPreference('primary');
    $server = $manager->selectServer($rp);

    var_dump($server->getInfo());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(23) {
      ["helloOk"]=>
      bool(true)
      ["topologyVersion"]=>
      array(2) {
        ["processId"]=>
        object(MongoDB\BSON\ObjectId)#4 (1) {
          ["oid"]=>
          string(24) "617b6d696a3a89d2f77e6df0"
        }
        ["counter"]=>
        int(6)
      }
      ["hosts"]=>
      array(1) {
        [0]=>
        string(15) "localhost:27017"
      }
      ["setName"]=>
      string(3) "rs0"
      ["setVersion"]=>
      int(1)
      ["ismaster"]=>
      bool(true)
      ["secondary"]=>
      bool(false)
      ["primary"]=>
      string(15) "localhost:27017"
      ["me"]=>
      string(15) "localhost:27017"
      ["electionId"]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "7fffffff0000000000000001"
      }
      ["lastWrite"]=>
      array(4) {
        ["opTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#6 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["lastWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#7 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
        ["majorityOpTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#8 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["majorityWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#9 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
      }
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["maxMessageSizeBytes"]=>
      int(48000000)
      ["maxWriteBatchSize"]=>
      int(100000)
      ["localTime"]=>
      object(MongoDB\BSON\UTCDateTime)#10 (1) {
        ["milliseconds"]=>
        string(13) "1635478992136"
      }
      ["logicalSessionTimeoutMinutes"]=>
      int(30)
      ["connectionId"]=>
      int(3)
      ["minWireVersion"]=>
      int(0)
      ["maxWireVersion"]=>
      int(13)
      ["readOnly"]=>
      bool(false)
      ["ok"]=>
      float(1)
      ["$clusterTime"]=>
      array(2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#11 (2) {
          ["increment"]=>
          string(1) "1"
          ["timestamp"]=>
          string(10) "1635478989"
        }
        ["signature"]=>
        array(2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#12 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          int(0)
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#13 (2) {
        ["increment"]=>
        string(1) "1"
        ["timestamp"]=>
        string(10) "1635478989"
      }
    }

### Historique

Version | Description
--- | ---
PECL mongodb 1.11.0 | Lorsque le pilote est connecté à un équilibreur de charge, cette méthode renvoie la réponse de la commande `hello` du serveur de backing à partir de la poignée de main de connexion initiale.

### Voir aussi

- MongoDB\Driver\ServerDescription::getHelloResponse() - Renvoie la réponse "hello" la plus récente du serveur
- Commande » hello dans le manuel de MongoDB
- » Spécification de la découverte et de la surveillance des serveurs

# MongoDB\Driver\Server::getLatency

(mongodb >=1.0.0)

MongoDB\Driver\Server::getLatency — Retourne la latence de ce serveur en millisecondes

### Description

final public function MongoDB\Driver\Server::getLatency(): ?integer

Retourne la latence de ce serveur en millisecondes. C'est la mesure cliente du temps d'un » aller/retour d'une commande `hello`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la latence du serveur en millisecondes, ou `null` si aucune latence n'a été mesurée (par exemple, le client est connecté à un équilibreur de charge).

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 1.11.0 | Cette méthode retournera `null` si aucune latence n'a été mesurée. Dans les versions antérieures, un nombre entier était toujours retourné et une valeur non définie pouvait être signalée comme `-1`.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Server::getLatency()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

    $server = $manager->selectServer();

    var_dump($server->getLatency());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(592)

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur
- MongoDB\Driver\ServerDescription::getRoundTripTime() - Renvoie le temps de trajet aller-retour du serveur en millisecondes
- » La spécification sur la découverte et la surveillance d'un serveur

# MongoDB\Driver\Server::getPort

(mongodb >=1.0.0)

MongoDB\Driver\Server::getPort — Retourne le port sur lequel le serveur écoute

### Description

final public function MongoDB\Driver\Server::getPort(): int

Retourne le port sur lequel le serveur écoute.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le port sur lequel le serveur écoute.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Server::getPort()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

    $server = $manager->selectServer();

    var_dump($server->getPort());

    ?>

L'exemple ci-dessus va afficher :

    int(27017)

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur
- MongoDB\Driver\ServerDescription::getPort() - Renvoie le port sur lequel ce serveur écoute

# MongoDB\Driver\Server::getServerDescription

(mongodb >=1.13.0)

MongoDB\Driver\Server::getServerDescription — Renvoie une ServerDescription pour ce serveur

### Description

final public function MongoDB\Driver\Server::getServerDescription(): MongoDB\Driver\ServerDescription

Renvoie une MongoDB\Driver\ServerDescription pour ce serveur. C'est un objet de valeur immuable qui décrira le serveur au moment où cette méthode est appelée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une MongoDB\Driver\ServerDescription pour ce serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Server::getTags

(mongodb >=1.0.0)

MongoDB\Driver\Server::getTags — Renvoie un tableau de tags décrivant ce serveur dans un ensemble de réplicas

### Description

final public function MongoDB\Driver\Server::getTags(): array

Renvoie un array de » tags utilisés pour décrire ce serveur dans un ensemble de réplicas. L'array contiendra zéro ou plusieurs paires clé et valeur de type string.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un array de tags utilisés pour décrire ce serveur dans un ensemble de réplicas.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur

# MongoDB\Driver\Server::getType

(mongodb >=1.0.0)

MongoDB\Driver\Server::getType — Retourne un entier représentant le type du serveur

### Description

final public function MongoDB\Driver\Server::getType(): int

Retourne un entier représentant le type du serveur. La valeur correspondra avec une constante MongoDB\Driver\Server.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier représentant le type du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur
- MongoDB\Driver\ServerDescription::getType() - Renvoie une chaîne de caractères indiquant le type de ce serveur

# MongoDB\Driver\Server::isArbiter

(mongodb >=1.0.0)

MongoDB\Driver\Server::isArbiter — Vérifie si ce serveur est un membre arbitre d'un ensemble de réplicas

### Description

final public function MongoDB\Driver\Server::isArbiter(): bool

Renvoie si ce serveur est un » membre arbitre d'un ensemble de réplicas.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si ce serveur est un membre arbitre d'un ensemble de réplicas, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur

# MongoDB\Driver\Server::isHidden

(mongodb >=1.0.0)

MongoDB\Driver\Server::isHidden — Renvoie si ce serveur est un membre caché d'un ensemble de réplicas

### Description

final public function MongoDB\Driver\Server::isHidden(): bool

Renvoie si ce serveur est un » membre caché d'un ensemble de réplicas.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si ce serveur est un membre caché d'un ensemble de réplicas, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur

# MongoDB\Driver\Server::isPassive

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPassive — Vérifie si le serveur est un membre passif du jeu de réplication

### Description

final public function MongoDB\Driver\Server::isPassive(): bool

Retourne si le serveur est un » membre passif d'un jeu de réplication (c.-à-d. sa priorité est `0`).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si le serveur est un membre passif d'un jeu de réplication, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur

# MongoDB\Driver\Server::isPrimary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPrimary — Vérifie si ce serveur est un membre principal d'un ensemble de réplicas

### Description

final public function MongoDB\Driver\Server::isPrimary(): bool

Renvoie si ce serveur est un » membre principal d'un ensemble de réplicas.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si ce serveur est un membre principal d'un ensemble de réplicas, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur

# MongoDB\Driver\Server::isSecondary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isSecondary — Vérifie si ce serveur est un membre secondaire d'un ensemble de réplicas

### Description

final public function MongoDB\Driver\Server::isSecondary(): bool

Renvoie si ce serveur est un » membre secondaire d'un ensemble de réplicas.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si ce serveur est un membre secondaire d'un ensemble de réplicas, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur

## Sommaire

- MongoDB\Driver\Server::__construct — Créer un nouveau serveur (non utilisé)
- MongoDB\Driver\Server::executeBulkWrite — Exécute une ou plusieurs opérations d'écriture sur ce serveur
- MongoDB\Driver\Server::executeBulkWriteCommand — Exécute des opérations d'écriture sur ce serveur en utilisant la commande bulkWrite
- MongoDB\Driver\Server::executeCommand — Exécute une commande de base de données sur ce serveur
- MongoDB\Driver\Server::executeQuery — Exécute une requête de base de données sur ce serveur
- MongoDB\Driver\Server::executeReadCommand — Exécute une commande de base de données qui lit sur ce serveur
- MongoDB\Driver\Server::executeReadWriteCommand — Exécute une commande de base de données qui lit et écrit sur ce serveur
- MongoDB\Driver\Server::executeWriteCommand — Exécute une commande de base de données qui écrit sur ce serveur
- MongoDB\Driver\Server::getHost — Retourne le nom d'hôte du serveur
- MongoDB\Driver\Server::getInfo — Retourne un tableau d'informations décrivant ce serveur
- MongoDB\Driver\Server::getLatency — Retourne la latence de ce serveur en millisecondes
- MongoDB\Driver\Server::getPort — Retourne le port sur lequel le serveur écoute
- MongoDB\Driver\Server::getServerDescription — Renvoie une ServerDescription pour ce serveur
- MongoDB\Driver\Server::getTags — Renvoie un tableau de tags décrivant ce serveur dans un ensemble de réplicas
- MongoDB\Driver\Server::getType — Retourne un entier représentant le type du serveur
- MongoDB\Driver\Server::isArbiter — Vérifie si ce serveur est un membre arbitre d'un ensemble de réplicas
- MongoDB\Driver\Server::isHidden — Renvoie si ce serveur est un membre caché d'un ensemble de réplicas
- MongoDB\Driver\Server::isPassive — Vérifie si le serveur est un membre passif du jeu de réplication
- MongoDB\Driver\Server::isPrimary — Vérifie si ce serveur est un membre principal d'un ensemble de réplicas
- MongoDB\Driver\Server::isSecondary — Vérifie si ce serveur est un membre secondaire d'un ensemble de réplicas

# La classe MongoDB\Driver\ServerDescription

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\ServerDescription est un objet de valeur qui représente un serveur auquel le pilote est connecté. Les instances de cette classe sont retournées par les méthodes MongoDB\Driver\Server::getServerDescription() et MongoDB\Driver\Monitoring\ServerChangedEvent.

## Synopsis de la classe

final class MongoDB\Driver\ServerDescription {
/* Constantes */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_STANDALONE = "Standalone";
const string TYPE_MONGOS = "Mongos";
const string TYPE_POSSIBLE_PRIMARY = "PossiblePrimary";
const string TYPE_RS_PRIMARY = "RSPrimary";
const string TYPE_RS_SECONDARY = "RSSecondary";
const string TYPE_RS_ARBITER = "RSArbiter";
const string TYPE_RS_OTHER = "RSOther";
const string TYPE_RS_GHOST = "RSGhost";
const string TYPE_LOAD_BALANCER = "LoadBalancer";
/* Méthodes */
final public function getHelloResponse(): array
final public function getHost(): string
final public function getLastUpdateTime(): int
final public function getPort(): int
final public function getRoundTripTime(): ?int
final public function getType(): string
}

## Constantes pré-définies

`MongoDB\Driver\ServerDescription::TYPE_UNKNOWN`
  Le type de serveur inconnu, retourné par MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_STANDALONE`
  Le type de serveur autonome, retourné par MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_MONGOS`
  Le type de serveur Mongos, retourné par MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_POSSIBLE_PRIMARY`
  Le type de serveur primaire possible d'un ensemble de réplicas, retourné par MongoDB\Driver\ServerDescription::getType(). Un serveur peut être identifié comme un primaire possible s'il n'a pas encore été vérifié mais qu'un autre serveur de la réplique pense qu'il est le primaire.
`MongoDB\Driver\ServerDescription::TYPE_RS_PRIMARY`
  Le type de serveur primaire d'un ensemble de réplicas, retourné par MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_SECONDARY`
  Le type de serveur secondaire d'un ensemble de réplicas, retourné par MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_ARBITER`
  Le type de serveur arbitre d'un ensemble de réplicas, retourné par MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_OTHER`
  Le type de serveur d'un ensemble de réplicas autre que primaire, secondaire ou arbitre, retourné par MongoDB\Driver\ServerDescription::getType(). Ces serveurs peuvent être cachés, démarrer ou récupérer. Ils ne peuvent pas être interrogés, mais leurs listes d'hôtes sont utiles pour découvrir la configuration actuelle de l'ensemble de réplicas.
`MongoDB\Driver\ServerDescription::TYPE_RS_GHOST`
  Le type de serveur fantôme d'un ensemble de réplicas, retourné par MongoDB\Driver\ServerDescription::getType(). Les serveurs peuvent être identifiés comme tels dans au moins trois situations : brièvement pendant le démarrage du serveur ; dans un ensemble de réplicas non initialisé ; ou lorsque le serveur est écarté (c'est-à-dire retiré de la configuration de l'ensemble de réplicas). Ils ne peuvent pas être interrogés, ni leur liste d'hôtes utilisée pour découvrir la configuration actuelle de l'ensemble de réplicas ; cependant, le client peut surveiller ce serveur dans l'espoir qu'il passe à un état plus utile.
`MongoDB\Driver\ServerDescription::TYPE_LOAD_BALANCER`
  Le type de serveur équilibreur de charge, retourné par MongoDB\Driver\ServerDescription::getType().

# MongoDB\Driver\ServerDescription::getHelloResponse

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHelloResponse — Renvoie la réponse "hello" la plus récente du serveur

### Description

final public function MongoDB\Driver\ServerDescription::getHelloResponse(): array

Renvoie un tableau d'informations décrivant le serveur. Ce tableau est dérivé de la réponse » hello la plus récente (au moment où la MongoDB\Driver\ServerDescription a été construite) obtenue via » la surveillance du serveur.

> Note: Lorsque le pilote est connecté à un équilibreur de charge, cette méthode renverra un tableau vide car les équilibreurs de charge ne sont pas surveillés. Cela contraste avec MongoDB\Driver\Server::getInfo(), qui renverrait la réponse du » hello de la commande de poignée de main de connexion initiale du serveur de base.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un tableau d'informations décrivant ce serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getInfo() - Retourne un tableau d'informations décrivant ce serveur
- » hello commande dans le manuel MongoDB
- » Découverte et surveillance des serveurs

# MongoDB\Driver\ServerDescription::getHost

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHost — Renvoie le nom d'hôte de ce serveur

### Description

final public function MongoDB\Driver\ServerDescription::getHost(): string

Renvoie le nom d'hôte de ce serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte de ce serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getHost() - Retourne le nom d'hôte du serveur

# MongoDB\Driver\ServerDescription::getLastUpdateTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getLastUpdateTime — Renvoie l'heure de la dernière mise à jour du serveur en microsecondes

### Description

final public function MongoDB\Driver\ServerDescription::getLastUpdateTime(): int

Renvoie l'heure de la dernière mise à jour du serveur en microsecondes.

> Note: La valeur renvoyée est un horodatage monotone, qui commence à un point arbitraire. En tant que tel, il est uniquement adapté pour être comparé avec d'autres valeurs de retour de MongoDB\Driver\ServerDescription::getLastUpdateTime().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'heure de la dernière mise à jour du serveur en microsecondes.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\ServerDescription::getPort

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getPort — Renvoie le port sur lequel ce serveur écoute

### Description

final public function MongoDB\Driver\ServerDescription::getPort(): int

Renvoie le port sur lequel ce serveur écoute.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port sur lequel ce serveur écoute.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getPort() - Retourne le port sur lequel le serveur écoute

# MongoDB\Driver\ServerDescription::getRoundTripTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getRoundTripTime — Renvoie le temps de trajet aller-retour du serveur en millisecondes

### Description

final public function MongoDB\Driver\ServerDescription::getRoundTripTime(): ?int

Renvoie le temps de trajet aller-retour du serveur en millisecondes. Il s'agit de la mesure du client de la durée d'une commande » hello.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le temps de trajet aller-retour du serveur en millisecondes.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getLatency() - Retourne la latence de ce serveur en millisecondes

# MongoDB\Driver\ServerDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getType — Renvoie une chaîne de caractères indiquant le type de ce serveur

### Description

final public function MongoDB\Driver\ServerDescription::getType(): string

Renvoie une string indiquant le type de ce serveur. La valeur sera corrélée à une constante MongoDB\Driver\ServerDescription.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un string indiquant le type de ce serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Server::getType() - Retourne un entier représentant le type du serveur

## Sommaire

- MongoDB\Driver\ServerDescription::getHelloResponse — Renvoie la réponse "hello" la plus récente du serveur
- MongoDB\Driver\ServerDescription::getHost — Renvoie le nom d'hôte de ce serveur
- MongoDB\Driver\ServerDescription::getLastUpdateTime — Renvoie l'heure de la dernière mise à jour du serveur en microsecondes
- MongoDB\Driver\ServerDescription::getPort — Renvoie le port sur lequel ce serveur écoute
- MongoDB\Driver\ServerDescription::getRoundTripTime — Renvoie le temps de trajet aller-retour du serveur en millisecondes
- MongoDB\Driver\ServerDescription::getType — Renvoie une chaîne de caractères indiquant le type de ce serveur

# La classe MongoDB\Driver\TopologyDescription

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\TopologyDescription est un objet de valeur qui représente une topologie à laquelle le pilote est connecté. Les instances de cette classe sont retournées par les méthodes de MongoDB\Driver\Monitoring\TopologyChangedEvent.

## Synopsis de la classe

final class MongoDB\Driver\TopologyDescription {
/* Constantes */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_SINGLE = "Single";
const string TYPE_SHARDED = "Sharded";
const string TYPE_REPLICA_SET_NO_PRIMARY = "ReplicaSetNoPrimary";
const string TYPE_REPLICA_SET_WITH_PRIMARY = "ReplicaSetWithPrimary";
const string TYPE_LOAD_BALANCED = "LoadBalanced";
/* Méthodes */
final public function getServers(): array
final public function getType(): string
final public function hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool
final public function hasWritableServer(): bool
}

## Constantes pré-définies

`MongoDB\Driver\TopologyDescription::TYPE_UNKNOWN`
  Topologie inconnue, retournée par MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SINGLE`
  Seul serveur (c'est-à-dire connexion directe), retourné par MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SHARDED`
  Cluster partagé, retourné par MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_NO_PRIMARY`
  Ensemble de réplicas sans serveur primaire, retourné par MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_WITH_PRIMARY`
  Ensemble de réplicas avec un serveur primaire, retourné par MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_LOAD_BALANCED`
  Topologie équilibrée, retournée par MongoDB\Driver\TopologyDescription::getType().

# MongoDB\Driver\TopologyDescription::getServers

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getServers — Renvoie les serveurs de la topologie

### Description

final public function MongoDB\Driver\TopologyDescription::getServers(): array

Renvoie un tableau d'objets MongoDB\Driver\ServerDescription correspondant aux serveurs connus dans la topologie.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un tableau d'objets MongoDB\Driver\ServerDescription correspondant aux serveurs connus dans la topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\TopologyDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getType — Renvoie une chaîne de caractères dénotant le type de cette topologie

### Description

final public function MongoDB\Driver\TopologyDescription::getType(): string

Renvoie un string dénotant le type de cette topologie. La valeur sera corrélée avec une constante de MongoDB\Driver\TopologyDescription.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un string dénotant le type de cette topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\TopologyDescription::hasReadableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasReadableServer — Renvoie si la topologie a un serveur lisible

### Description

final public function MongoDB\Driver\TopologyDescription::hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool

Renvoie si la topologie a un serveur lisible ou, si `readPreference` est spécifié, un serveur correspondant à la préférence de lecture spécifiée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie si la topologie a un serveur lisible ou, si `readPreference` est spécifié, un serveur correspondant à la préférence de lecture spécifiée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\TopologyDescription::hasWritableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasWritableServer — Retourne si la topologie dispose d'un serveur en écriture

### Description

final public function MongoDB\Driver\TopologyDescription::hasWritableServer(): bool

Retourne si la topologie dispose d'un serveur en écriture.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne si la topologie dispose d'un serveur en écriture.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\TopologyDescription::getServers — Renvoie les serveurs de la topologie
- MongoDB\Driver\TopologyDescription::getType — Renvoie une chaîne de caractères dénotant le type de cette topologie
- MongoDB\Driver\TopologyDescription::hasReadableServer — Renvoie si la topologie a un serveur lisible
- MongoDB\Driver\TopologyDescription::hasWritableServer — Retourne si la topologie dispose d'un serveur en écriture

# La classe MongoDB\Driver\WriteConcernError

(mongodb >=1.0.0)

## Introduction

La classe MongoDB\Driver\WriteConcernError contient des informations relatives à une erreur de write concern et peut être retournée par MongoDB\Driver\WriteResult::getWriteConcernError().

## Synopsis de la classe

final class MongoDB\Driver\WriteConcernError {
/* Propriétés */
public readonly string $message;
public readonly int $code;
public readonly ?object $info;
/* Méthodes */
final public function getCode(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Propriétés

message
  Le message d'erreur.
code
  Le code d'erreur.
info
  Informations supplémentaires sur l'erreur, ou `null` si non disponible.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\WriteConcernError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getCode — Retourne le code d'erreur de WriteConcernError

### Description

final public function MongoDB\Driver\WriteConcernError::getCode(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code d'erreur de WriteConcernError

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteConcernError::getCode()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getCode());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(64)

### Voir aussi

- » Référence Write Concern

# MongoDB\Driver\WriteConcernError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getInfo — Retourne le document de métadonnées pour WriteConcernError

### Description

final public function MongoDB\Driver\WriteConcernError::getInfo(): ?object

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le document de métadonnées pour WriteConcernError, ou `null` si aucune métadonnée n'est disponible.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteConcernError::getInfo()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getInfo());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#1 (1) {
      ["wtimeout"]=>
      bool(true)
    }

### Voir aussi

- » Référence Write Concern

# MongoDB\Driver\WriteConcernError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getMessage — Renvoie le message d'erreur du WriteConcernError

### Description

final public function MongoDB\Driver\WriteConcernError::getMessage(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le message d'erreur du WriteConcernError

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteConcernError::getMessage()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getMessage());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(33) "waiting for replication timed out"

### Voir aussi

- » Référence Write Concern

## Sommaire

- MongoDB\Driver\WriteConcernError::getCode — Retourne le code d'erreur de WriteConcernError
- MongoDB\Driver\WriteConcernError::getInfo — Retourne le document de métadonnées pour WriteConcernError
- MongoDB\Driver\WriteConcernError::getMessage — Renvoie le message d'erreur du WriteConcernError

# La classe MongoDB\Driver\WriteError

(mongodb >=1.0.0)

## Introduction

La classe MongoDB\Driver\WriteError contient des informations sur une erreur d'écriture et peut être retournée en tant qu'élément d'un tableau à partir de MongoDB\Driver\WriteResult::getWriteErrors().

## Synopsis de la classe

final class MongoDB\Driver\WriteError {
/* Propriétés */
public readonly string $message;
public readonly int $code;
public readonly int $index;
public readonly ?object $info;
/* Méthodes */
final public function getCode(): int
final public function getIndex(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Propriétés

message
  Le message d'erreur.
code
  Le code d'erreur.
index
  L'index de l'opération d'écriture au sein du MongoDB\Driver\BulkWrite qui a provoqué l'erreur.
info
  Informations supplémentaires sur l'erreur, ou `null` si non disponible.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\WriteError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getCode — Retourne le code d'erreur de WriteError

### Description

final public function MongoDB\Driver\WriteError::getCode(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code d'erreur de WriteError

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteError::getCode()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getCode());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(11000)

# MongoDB\Driver\WriteError::getIndex

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getIndex — Retourne l'index de l'opération d'écriture correspondant à ce WriteError

### Description

final public function MongoDB\Driver\WriteError::getIndex(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'index de l'opération d'écriture (à partir de MongoDB\Driver\BulkWrite) correspondant à ce WriteError.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteError::getIndex()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getIndex());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(1)

### Voir aussi

- MongoDB\Driver\BulkWrite

# MongoDB\Driver\WriteError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getInfo — Retourne le document de métadonnées pour WriteError

### Description

final public function MongoDB\Driver\WriteError::getInfo(): ?object

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le document de métadonnées pour WriteError, ou `null` s'il n'y a pas de métadonnées disponibles.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\WriteError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getMessage — Renvoie le message d'erreur du WriteError

### Description

final public function MongoDB\Driver\WriteError::getMessage(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le message d'erreur du WriteError.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteError::getMessage()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getMessage());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"

## Sommaire

- MongoDB\Driver\WriteError::getCode — Retourne le code d'erreur de WriteError
- MongoDB\Driver\WriteError::getIndex — Retourne l'index de l'opération d'écriture correspondant à ce WriteError
- MongoDB\Driver\WriteError::getInfo — Retourne le document de métadonnées pour WriteError
- MongoDB\Driver\WriteError::getMessage — Renvoie le message d'erreur du WriteError

# La classe MongoDB\Driver\WriteResult

(mongodb >=1.0.0)

## Introduction

La classe MongoDB\Driver\WriteResult contient les informations sur une exécution MongoDB\Driver\BulkWrite et peut être retournée par MongoDB\Driver\Manager::executeBulkWrite().

## Synopsis de la classe

final class MongoDB\Driver\WriteResult {
/* Propriétés */
public readonly ?int $insertedCount;
public readonly ?int $matchedCount;
public readonly ?int $modifiedCount;
public readonly ?int $deletedCount;
public readonly ?int $upsertedCount;
public readonly MongoDB\Driver\Server $server;
public readonly array $upsertedIds;
public readonly array $writeErrors;
public readonly ?MongoDB\Driver\WriteConcernError $writeConcernError;
public readonly ?MongoDB\Driver\WriteConcern $writeConcern;
public readonly array $errorReplies;
/* Méthodes */
final public function getDeletedCount(): int
final public function getInsertedCount(): int
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getServer(): MongoDB\Driver\Server
final public function getUpsertedCount(): int
final public function getUpsertedIds(): array
final public function getWriteConcernError(): ?MongoDB\Driver\WriteConcernError
final public function getWriteErrors(): array
final public function isAcknowledged(): bool
}

## Propriétés

insertedCount
  Le nombre de documents insérés (à l'exclusion des upserts), ou `null` si le write concern n'a pas demandé d'accusé de réception.
matchedCount
  Le nombre de documents correspondant aux opérations de mise à jour et de remplacement, ou `null` si le write concern n'a pas demandé d'accusé de réception.
modifiedCount
  Le nombre de documents modifiés par les opérations de mise à jour et de remplacement, ou `null` si le write concern n'a pas demandé d'accusé de réception ou si le serveur n'a pas signalé cette information.
deletedCount
  Le nombre de documents supprimés, ou `null` si le write concern n'a pas demandé d'accusé de réception.
upsertedCount
  Le nombre de documents upsertés, ou `null` si le write concern n'a pas demandé d'accusé de réception.
server
  Le serveur qui a exécuté l'écriture groupée.
upsertedIds
  Un tableau de valeurs `_id` pour les documents upsertés. Les clés du tableau correspondent à l'index de l'opération d'écriture depuis MongoDB\Driver\BulkWrite.
writeErrors
  Un tableau de MongoDB\Driver\WriteError pour toutes les erreurs d'écriture survenues lors de l'exécution.
writeConcernError
  Le MongoDB\Driver\WriteConcernError survenu, ou `null` si aucune erreur de write concern n'est survenue.
writeConcern
  La MongoDB\Driver\WriteConcern utilisée pour l'écriture groupée, ou `null` si non disponible.
errorReplies
  Un tableau de documents de réponse d'erreur du serveur.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\WriteResult::getDeletedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getDeletedCount — Renvoie le nombre de documents supprimés

### Description

final public function MongoDB\Driver\WriteResult::getDeletedCount(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre de documents supprimés.

### Erreurs / Exceptions

- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.
- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette méthode déclenche désormais une exception lorsqu'elle est appelée pour une écriture non reconnue, au lieu de retourner `null`.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteResult::getDeletedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getDeletedCount());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(1)

### Voir aussi

- MongoDB\Driver\WriteResult::isAcknowledged() - Retourne si l'écriture a été reconnue

# MongoDB\Driver\WriteResult::getInsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getInsertedCount — Renvoie le nombre de documents insérés (à l'exception d'Upserts)

### Description

final public function MongoDB\Driver\WriteResult::getInsertedCount(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre de documents insérés (à l'exception d'Upserts).

### Erreurs / Exceptions

- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.
- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette méthode déclenche désormais une exception lorsqu'elle est appelée pour une écriture non reconnue, au lieu de retourner `null`.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteResult::getInsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getInsertedCount());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(1)

### Voir aussi

- MongoDB\Driver\WriteResult::isAcknowledged() - Retourne si l'écriture a été reconnue

# MongoDB\Driver\WriteResult::getMatchedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getMatchedCount — Renvoie le nombre de documents sélectionnés pour la mise à jour

### Description

final public function MongoDB\Driver\WriteResult::getMatchedCount(): int

Si l'opération de mise à jour n'entraîne aucune modification du document (par exemple, en définissant la valeur d'un champ sur sa valeur actuelle), le nombre correspondant peut être supérieur à la valeur retournée par MongoDB\Driver\WriteResult::getModifiedCount().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de documents sélectionnés pour la mise à jour.

### Erreurs / Exceptions

- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.
- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette méthode déclenche désormais une exception lorsqu'elle est appelée pour une écriture non reconnue, au lieu de retourner `null`.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteResult::getMatchedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getMatchedCount());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(1)

### Voir aussi

- MongoDB\Driver\WriteResult::getModifiedCount() - Renvoie le nombre de documents existants mis à jour
- MongoDB\Driver\WriteResult::isAcknowledged() - Retourne si l'écriture a été reconnue

# MongoDB\Driver\WriteResult::getModifiedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getModifiedCount — Renvoie le nombre de documents existants mis à jour

### Description

final public function MongoDB\Driver\WriteResult::getModifiedCount(): int

Si l'opération de mise à jour n'entraîne aucune modification du document (par exemple, en définissant la valeur d'un champ sur sa valeur actuelle), le nombre modifié peut être inférieur à la valeur retournée par MongoDB\Driver\WriteResult::getMatchedCount().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de documents existants mis à jour.

### Erreurs / Exceptions

- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.
- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette méthode déclenche désormais une exception lorsqu'elle est appelée pour une écriture non reconnue, au lieu de retourner `null`.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteResult::getModifiedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getModifiedCount());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(1)

### Voir aussi

- MongoDB\Driver\WriteResult::getMatchedCount() - Renvoie le nombre de documents sélectionnés pour la mise à jour
- MongoDB\Driver\WriteResult::isAcknowledged() - Retourne si l'écriture a été reconnue

# MongoDB\Driver\WriteResult::getServer

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getServer — Retourne le serveur associé à ce résultat d'écriture

### Description

final public function MongoDB\Driver\WriteResult::getServer(): MongoDB\Driver\Server

Retourne le MongoDB\Driver\Server associé à ce résultat d'écriture. Il s'agit du serveur qui a exécuté le MongoDB\Driver\BulkWrite.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le MongoDB\Driver\Server associé à ce résultat d'écriture.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteResult::getServer()

    <?php

    $manager = new MongoDB\Driver\Manager;
    $server = $manager->selectServer();

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $result = $server->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getServer() == $server);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    bool(true)

### Voir aussi

- MongoDB\Driver\Server

# MongoDB\Driver\WriteResult::getUpsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedCount — Renvoie le nombre de documents insérés par un upsert

### Description

final public function MongoDB\Driver\WriteResult::getUpsertedCount(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre de documents insérés par un upsert.

### Erreurs / Exceptions

- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.
- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette méthode déclenche désormais une exception lorsqu'elle est appelée pour une écriture non reconnue, au lieu de retourner `null`.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteResult::getUpsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedCount());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(2)

### Voir aussi

- MongoDB\Driver\WriteResult::getUpsertedIds() - Retourne un tableau d'identificateurs pour les documents upserted
- MongoDB\Driver\WriteResult::isAcknowledged() - Retourne si l'écriture a été reconnue

# MongoDB\Driver\WriteResult::getUpsertedIds

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedIds — Retourne un tableau d'identificateurs pour les documents upserted

### Description

final public function MongoDB\Driver\WriteResult::getUpsertedIds(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau d'identificateurs (par exemple la valeur du champ `"_id"`) pour les documents upserted. Les clés de tableau correspondent à l'index de l'opération d'écriture (à partir de MongoDB\Driver\BulkWrite) responsable du upsert.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteResult::getUpsertedIds()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedIds());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(2) {
      [2]=>
      object(MongoDB\BSON\ObjectId)#4 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880b"
      }
      [3]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880c"
      }
    }

### Voir aussi

- MongoDB\Driver\WriteResult::getUpsertedCount() - Renvoie le nombre de documents insérés par un upsert
- MongoDB\Driver\WriteResult::isAcknowledged() - Retourne si l'écriture a été reconnue

# MongoDB\Driver\WriteResult::getWriteConcernError

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteConcernError — Retourne toute erreur de WriteConcern qui s'est produite

### Description

final public function MongoDB\Driver\WriteResult::getWriteConcernError(): ?MongoDB\Driver\WriteConcernError

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un MongoDB\Driver\WriteConcernError si une erreur de write concern a été rencontrée pendant l'opération d'écriture, et `null` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\WriteResult::getWriteConcernError()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\Driver\WriteConcernError)#6 (3) {
      ["message"]=>
      string(33) "waiting for replication timed out"
      ["code"]=>
      int(64)
      ["info"]=>
      object(stdClass)#7 (1) {
        ["wtimeout"]=>
        bool(true)
      }
    }

### Voir aussi

- MongoDB\Driver\WriteConcern
- » Référence Write Concern

# MongoDB\Driver\WriteResult::getWriteErrors

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteErrors — Retourne toutes les erreurs d'écriture qui se sont produites

### Description

final public function MongoDB\Driver\WriteResult::getWriteErrors(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau d'objets MongoDB\Driver\WriteError pour toutes les erreurs d'écriture rencontrées pendant l'opération d'écriture. Le tableau sera vide si aucune erreur d'écriture n'est survenue.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 MongoDB\Driver\WriteResult::getWriteErrors() avec une seule erreur

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* Par défaut, les opérations d'écriture en bloc sont exécutées en série dans
     * l'ordre et l'exécution s'arrêtera après la première erreur.
     */
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
    }

Exemple #2 MongoDB\Driver\WriteResult::getWriteErrors() avec plusieurs erreurs

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* L'option "ordered" peut être utilisée pour permettre aux opérations
     * d'écriture en bloc de continuer à s'exécuter après la première erreur.
     */
    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(2) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
      [1]=>
      object(MongoDB\Driver\WriteError)#6 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 4 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(5)
        ["info"]=>
        NULL
      }
    }

### Voir aussi

- MongoDB\Driver\WriteError

# MongoDB\Driver\WriteResult::isAcknowledged

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::isAcknowledged — Retourne si l'écriture a été reconnue

### Description

final public function MongoDB\Driver\WriteResult::isAcknowledged(): bool

Si l'écriture a été reconnue, d'autres champs de comptage seront disponibles pour l'objet MongoDB\Driver\WriteResult.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'écriture a été reconnue, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 MongoDB\Driver\WriteResult::isAcknowledged() avec le write concern reconnu

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->isAcknowledged());

    ?>

L'exemple ci-dessus va afficher :

    bool(true)

Exemple #2 MongoDB\Driver\WriteResult::isAcknowledged() avec le write concern non reconnu

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

L'exemple ci-dessus va afficher :

    bool(false)

### Voir aussi

- MongoDB\Driver\WriteConcern
- » Référence Write Concern

## Sommaire

- MongoDB\Driver\WriteResult::getDeletedCount — Renvoie le nombre de documents supprimés
- MongoDB\Driver\WriteResult::getInsertedCount — Renvoie le nombre de documents insérés (à l'exception d'Upserts)
- MongoDB\Driver\WriteResult::getMatchedCount — Renvoie le nombre de documents sélectionnés pour la mise à jour
- MongoDB\Driver\WriteResult::getModifiedCount — Renvoie le nombre de documents existants mis à jour
- MongoDB\Driver\WriteResult::getServer — Retourne le serveur associé à ce résultat d'écriture
- MongoDB\Driver\WriteResult::getUpsertedCount — Renvoie le nombre de documents insérés par un upsert
- MongoDB\Driver\WriteResult::getUpsertedIds — Retourne un tableau d'identificateurs pour les documents upserted
- MongoDB\Driver\WriteResult::getWriteConcernError — Retourne toute erreur de WriteConcern qui s'est produite
- MongoDB\Driver\WriteResult::getWriteErrors — Retourne toutes les erreurs d'écriture qui se sont produites
- MongoDB\Driver\WriteResult::isAcknowledged — Retourne si l'écriture a été reconnue

# La classe MongoDB\Driver\BulkWriteCommandResult

(mongodb >=2.1.0)

## Introduction

La classe MongoDB\Driver\BulkWriteCommandResult encapsule les informations sur une MongoDB\Driver\BulkWriteCommand exécuté et renvoyé par MongoDB\Driver\Manager::executeBulkWriteCommand().

## Synopsis de la classe

final class MongoDB\Driver\BulkWriteCommandResult {
/* Méthodes */
final public function getDeletedCount(): int
final public function getDeleteResults(): ?MongoDB\BSON\Document
final public function getInsertedCount(): int
final public function getInsertResults(): ?MongoDB\BSON\Document
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getUpdateResults(): ?MongoDB\BSON\Document
final public function getUpsertedCount(): int
final public function isAcknowledged(): bool
}

# MongoDB\Driver\BulkWriteCommandResult::getDeletedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Renvoie le nombre de documents supprimés

### Description

final public function MongoDB\Driver\BulkWriteCommandResult::getDeletedCount(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre total de documents supprimés par toutes les opérations.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommandResult::getDeletedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeletedCount());

    ?>

L'exemple ci-dessus va afficher :

    int(3)

### Voir aussi

- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults() - Renvoie les résultats détaillés des suppressions réussies
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Renvoie si l'écriture a été reconnue

# MongoDB\Driver\BulkWriteCommandResult::getDeleteResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Renvoie les résultats détaillés des suppressions réussies

### Description

final public function MongoDB\Driver\BulkWriteCommandResult::getDeleteResults(): ?MongoDB\BSON\Document

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un document contenant les résultats de chaque opération de suppression réussie, ou `null` si les résultats détaillés n'ont pas été demandés. Les clés du document correspondront à l'index de l'opération d'écriture de MongoDB\Driver\BulkWriteCommand.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommandResult::getDeleteResults()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeleteResults()->toPHP());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#7 (1) {
      ["4"]=>
      object(stdClass)#6 (1) {
        ["deletedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "3"
        }
      }
    }

### Voir aussi

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount() - Renvoie le nombre de documents supprimés
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Renvoie si l'écriture a été reconnue

# MongoDB\Driver\BulkWriteCommandResult::getInsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Renvoie le nombre de documents insérés

### Description

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertedCount(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre total de documents insérés (excluant les upserts) par toutes les opérations.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommandResult::getInsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getInsertedCount());

    ?>

L'exemple ci-dessus va afficher :

    int(1)

### Voir aussi

- MongoDB\Driver\BulkWriteCommandResult::getInsertResults() - Renvoie les résultats détaillés des insertions réussies
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Renvoie si l'écriture a été reconnue

# MongoDB\Driver\BulkWriteCommandResult::getInsertResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Renvoie les résultats détaillés des insertions réussies

### Description

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertResults(): ?MongoDB\BSON\Document

Depuis que les champs `_id` des documents insérés sont générés par l'extension, la valeur de `insertedId` dans chaque résultat correspondra à la valeur de retour de MongoDB\Driver\BulkWriteCommand::insertOne() pour l'opération d'insertion correspondante.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un document contenant les résultats de chaque opération d'insertion ou `null` si les résultats détaillés n'ont pas été demandés. Les clés du document correspondront à l'index de l'opération d'écriture de MongoDB\Driver\BulkWriteCommand.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommandResult::getInsertResults()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);

    $generatedId = $bulk->insertOne('db.coll', ['x' => 1]);

    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($generatedId);

    var_dump($result->getInsertResults()->toPHP());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f7ee69783dcce702097b41"
    }
    object(stdClass)#8 (1) {
      ["0"]=>
      object(stdClass)#7 (1) {
        ["insertedId"]=>
        object(MongoDB\BSON\ObjectId)#6 (1) {
          ["oid"]=>
          string(24) "67f7ee69783dcce702097b41"
        }
      }
    }

### Voir aussi

- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount() - Renvoie le nombre de documents insérés
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Renvoie si l'écriture a été reconnue
- MongoDB\Driver\BulkWriteCommand::insertOne() - Ajoute une opération insertOne

# MongoDB\Driver\BulkWriteCommandResult::getMatchedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Renvoie le nombre de documents sélectionnés pour la mise à jour

### Description

final public function MongoDB\Driver\BulkWriteCommandResult::getMatchedCount(): int

Si l'opération de mise à jour ne fait aucun changement au document (par exemple, en définissant la valeur d'un champ à sa valeur actuelle), le nombre de documents peut être plus grand que la valeur renvoyée par MongoDB\Driver\BulkWriteCommandResult::getModifiedCount().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre total de documents sélectionnés pour la mise à jour par toutes les opérations.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommandResult::getMatchedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getMatchedCount());

    ?>

L'exemple ci-dessus va afficher :

    int(1)

### Voir aussi

- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Renvoie le nombre de documents existants mis à jour
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Renvoie les résultats détaillés des mises à jour réussies
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Renvoie si l'écriture a été reconnue

# MongoDB\Driver\BulkWriteCommandResult::getModifiedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Renvoie le nombre de documents existants mis à jour

### Description

final public function MongoDB\Driver\BulkWriteCommandResult::getModifiedCount(): int

Si l'opération de mise à jour ne fait aucun changement au document (par exemple, en définissant la valeur d'un champ à sa valeur actuelle), le nombre de documents peut être plus petit que la valeur renvoyée par MongoDB\Driver\BulkWriteCommandResult::getMatchedCount().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre total de documents existants mis à jour par toutes les opérations.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommandResult::getModifiedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getModifiedCount());

    ?>

L'exemple ci-dessus va afficher :

    int(1)

### Voir aussi

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Renvoie le nombre de documents sélectionnés pour la mise à jour
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Renvoie les résultats détaillés des mises à jour réussies
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Renvoie si l'écriture a été reconnue

# MongoDB\Driver\BulkWriteCommandResult::getUpdateResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Renvoie les résultats détaillés des mises à jour réussies

### Description

final public function MongoDB\Driver\BulkWriteCommandResult::getUpdateResults(): ?MongoDB\BSON\Document

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un document contenant les résultats de chaque opération de mise à jour réussie, ou `null` si les résultats détaillés n'ont pas été demandés. Les clés du document correspondront à l'index de l'opération d'écriture de MongoDB\Driver\BulkWriteCommand.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommandResult::getUpdateResults()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpdateResults()->toPHP());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#16 (3) {
      ["1"]=>
      object(stdClass)#7 (2) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#6 (1) {
          ["integer"]=>
          string(1) "1"
        }
      }
      ["2"]=>
      object(stdClass)#11 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#8 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#9 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#10 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d575"
        }
      }
      ["3"]=>
      object(stdClass)#15 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#12 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#13 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#14 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d576"
        }
      }
    }

### Voir aussi

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Renvoie le nombre de documents sélectionnés pour la mise à jour
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Renvoie le nombre de documents existants mis à jour
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount() - Renvoie le nombre de documents insérés/mis à jour
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Renvoie si l'écriture a été reconnue

# MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Renvoie le nombre de documents insérés/mis à jour

### Description

final public function MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nombre total de documents insérés/mis à jour par toutes les opérations.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\LogicException si l'écriture n’a pas été reconnue.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpsertedCount());

    ?>

L'exemple ci-dessus va afficher :

    int(2)

### Voir aussi

- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Renvoie les résultats détaillés des mises à jour réussies
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Renvoie si l'écriture a été reconnue

# MongoDB\Driver\BulkWriteCommandResult::isAcknowledged

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Renvoie si l'écriture a été reconnue

### Description

final public function MongoDB\Driver\BulkWriteCommandResult::isAcknowledged(): bool

Si l'écriture a été reconnue, les autres champs seront disponibles sur l'objet MongoDB\Driver\BulkWriteCommandResult.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si l'écriture a été reconnue, et `false` sinon.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() avec un write concern reconnu

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->isAcknowledged());

    ?>

L'exemple ci-dessus va afficher :

    bool(true)

Exemple #2 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() avec un write concern non reconnu

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

L'exemple ci-dessus va afficher :

    bool(false)

### Voir aussi

- MongoDB\Driver\WriteConcern
- » Write Concern reference

## Sommaire

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Renvoie le nombre de documents supprimés
- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Renvoie les résultats détaillés des suppressions réussies
- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Renvoie le nombre de documents insérés
- MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Renvoie les résultats détaillés des insertions réussies
- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Renvoie le nombre de documents sélectionnés pour la mise à jour
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Renvoie le nombre de documents existants mis à jour
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Renvoie les résultats détaillés des mises à jour réussies
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Renvoie le nombre de documents insérés/mis à jour
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Renvoie si l'écriture a été reconnue

# Classes et fonctions BSON de MongoDB

## Sommaire

- Fonctions
- MongoDB\BSON\Document
- MongoDB\BSON\PackedArray
- MongoDB\BSON\Iterator
- MongoDB\BSON\Binary
- MongoDB\BSON\VectorType
- MongoDB\BSON\Decimal128
- MongoDB\BSON\Javascript
- MongoDB\BSON\MaxKey
- MongoDB\BSON\MinKey
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Regex
- MongoDB\BSON\Timestamp
- MongoDB\BSON\UTCDatetime
- MongoDB\BSON\Type
- MongoDB\BSON\Persistable
- MongoDB\BSON\Serializable
- MongoDB\BSON\Unserializable
- MongoDB\BSON\BinaryInterface
- MongoDB\BSON\Decimal128Interface
- MongoDB\BSON\JavascriptInterface
- MongoDB\BSON\MaxKeyInterface
- MongoDB\BSON\MinKeyInterface
- MongoDB\BSON\ObjectIdInterface
- MongoDB\BSON\RegexInterface
- MongoDB\BSON\TimestampInterface
- MongoDB\BSON\UTCDateTimeInterface
- MongoDB\BSON\DBPointer
- MongoDB\BSON\Int64
- MongoDB\BSON\Symbol
- MongoDB\BSON\Undefined

# Fonctions

# MongoDB\BSON\fromJSON

(mongodb >=1.0.0)

MongoDB\BSON\fromJSON — Retourne la représentation BSON d'une valeur JSON

Avertissement

Cette fonction a été DÉPRÉCIÉE depuis la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications devraient utiliser MongoDB\BSON\Document::fromJSON() à la place.

### Description

function MongoDB\BSON\fromJSON(string `$json`): string

Convertit une chaîne » JSON étendu en sa représentation BSON.

### Liste de paramètres

`json` (string)
  Valeur JSON à convertir.

### Valeurs de retour

Le document sérialisé BSON en tant que chaîne binaire.

### Erreurs / Exceptions

- Lève une exception MongoDB\Driver\Exception\UnexpectedValueException si la valeur JSON ne peut pas être convertie en BSON (par exemple en raison d'une erreur de syntaxe).

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette fonction a été supprimée.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\fromJSON()

    <?php

    $json = '{ "_id": { "$oid": "563143b280d2387c91807965" } }';
    $bson = MongoDB\BSON\fromJSON($json);
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

L'exemple ci-dessus va afficher :

    object(stdClass)#2 (1) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#1 (1) {
        ["oid"]=>
        string(24) "563143b280d2387c91807965"
      }
    }

### Voir aussi

- MongoDB\BSON\Document::fromJSON() - Construit une nouvelle instance de document depuis une chaîne de caractères JSON
- MongoDB\BSON\toJSON() - Retourne la représentation JSON étendue héritée d'une valeur BSON
- » MongoDB JSON étendu
- » MongoDB BSON

# MongoDB\BSON\fromPHP

(mongodb >=1.0.0)

MongoDB\BSON\fromPHP — Retourne la représentation BSON d'une valeur PHP

Avertissement

Cette fonction a été DÉPRÉCIÉE depuis la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications devraient utiliser MongoDB\BSON\Document::fromPHP() à la place.

### Description

function MongoDB\BSON\fromPHP(array|object `$value`): string

Sérialise un tableau ou objet PHP (par exemple document) en sa représentation » BSON. La chaîne binaire retournée décrira un document BSON.

### Liste de paramètres

`value` (array|object)
  La valeur PHP à sérialiser.

### Valeurs de retour

Le document BSON sérialisé en tant que chaîne binaire.

### Erreurs / Exceptions

- Lance MongoDB\Driver\Exception\UnexpectedValueException si la valeur PHP ne peut pas être convertie en BSON. Les raisons possibles incluent, mais sans s'y limiter à, rencontrer une instance inattendue de MongoDB\BSON\Type ou MongoDB\BSON\Serializable::bsonSerialize() échouant à retourner un tableau ou une stdClass.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette fonction a été supprimée.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\fromPHP()

    <?php

    $bson = MongoDB\BSON\fromPHP(['foo' => 1]);
    echo bin2hex($bson), "\n";

    ?>

L'exemple ci-dessus va afficher :

    0e00000010666f6f000100000000

### Voir aussi

- MongoDB\BSON\Document::fromPHP() - Construit une nouvelle instance de document depuis des données PHP
- MongoDB\BSON\toPHP() - Renvoie la représentation PHP d'une valeur BSON
- » MongoDB BSON
- Persister des données

# MongoDB\BSON\toCanonicalExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toCanonicalExtendedJSON — Renvoie la représentation JSON étendue canonique d'une valeur BSON

Avertissement

Cette fonction a été DÉPRÉCIÉE depuis la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications devraient utiliser MongoDB\BSON\Document::toCanonicalExtendedJSON() à la place.

### Description

function MongoDB\BSON\toCanonicalExtendedJSON(string `$bson`): string

Convertit une chaîne BSON en sa » représentation JSON étendue canonique. Le format canonique privilégie la fidélité des types au détriment de la concision de la sortie et est le plus adapté pour produire une sortie qui peut être convertie en BSON sans perte d'informations de type (par exemple, les types numériques resteront différenciés).

### Liste de paramètres

`bson` (string)
  Le BSON à convertir.

### Valeurs de retour

Le JSON converti.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\Exception\UnexpectedValueException si l'entrée ne contient pas exactement un document BSON. Les raisons possibles comprennent, mais ne sont pas limitées à, BSON invalide, des données supplémentaires (après avoir lu un document BSON), ou une erreur imprévu de » libbson.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette fonction a été supprimée.

### Exemples

Exemple #1 Exemple de MongoDB\BSON\toCanonicalExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toCanonicalExtendedJSON($bson), "\n";
    }

    ?>

L'exemple ci-dessus va afficher :

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Voir aussi

- MongoDB\BSON\Document::fromJSON() - Construit une nouvelle instance de document depuis une chaîne de caractères JSON
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Renvoie la représentation Canonique Etendue JSON du document BSON
- MongoDB\BSON\fromJSON() - Retourne la représentation BSON d'une valeur JSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » Spécification de JSON étendu
- » MongoDB BSON

# MongoDB\BSON\toJSON

(mongodb >=1.0.0)

MongoDB\BSON\toJSON — Retourne la représentation JSON étendue héritée d'une valeur BSON

Avertissement

Cette fonction a été DÉPRÉCIÉE depuis la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications devraient utiliser MongoDB\BSON\Document::toCanonicalExtendedJSON() ou MongoDB\BSON\Document::toRelaxedExtendedJSON() à la place.

### Description

function MongoDB\BSON\toJSON(string `$bson`): string

Convertit une chaîne BSON en sa » représentation JSON étendue héritée.

> Note: Il existe plusieurs formats JSON pour représenter BSON. Cette fonction implémente le "strict mode" défini dans » MongoDB Extended JSON, qui a été remplacé par les formats canoniques et étendues définis dans la » spécification JSON étendue et implémenté par MongoDB\BSON\toCanonicalExtendedJSON() et MongoDB\BSON\toRelaxedExtendedJSON(), respectivement.

Avertissement

» JSON ne prend pas en charge `NAN` et `INF` et le format JSON étendu de MongoDB ne définit pas une autre représentation pour ces valeurs (» libbson va produire `nan` et `inf` littéralement, qui ne peuvent pas être analysés comme JSON valide). Si on travaille avec BSON qui peut contenir des nombres non finis, utiliser svp MongoDB\BSON\toCanonicalExtendedJSON() ou MongoDB\BSON\toRelaxedExtendedJSON().

### Liste de paramètres

`bson` (string)
  Valeur BSON à convertir.

### Valeurs de retour

La valeur JSON convertie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\Exception\UnexpectedValueException si l'entrée ne contient pas exactement un document BSON. Les raisons possibles comprennent, mais ne sont pas limitées à, BSON invalide, des données supplémentaires (après avoir lu un document BSON), ou une erreur imprévu de » libbson.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette fonction a été supprimée.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\toJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toJSON($bson), "\n";
    }

    ?>

L'exemple ci-dessus va afficher :

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : nan }
    { "pos_inf" : inf }
    { "neg_inf" : -inf }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : "Zm9v", "$type" : "00" } }
    { "date" : { "$date" : 1445990400000 } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regex" : "pattern", "$options" : "i" } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Voir aussi

- MongoDB\BSON\fromJSON() - Retourne la représentation BSON d'une valeur JSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Etendu
- » MongoDB BSON

# MongoDB\BSON\toPHP

(mongodb >=1.0.0)

MongoDB\BSON\toPHP — Renvoie la représentation PHP d'une valeur BSON

Avertissement

Cette fonction a été DÉPRÉCIÉE depuis la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications devraient utiliser MongoDB\BSON\Document::toPHP() à la place.

### Description

function MongoDB\BSON\toPHP(string `$bson`, array `$typeMap` = array()): array|object

Désérialise un document BSON (c'est-à-dire une chaîne binaire) en sa représentation PHP. Le paramètre `typeMap` peut être utilisé pour contrôler les types PHP utilisés pour convertir les tableaux et documents BSON (à la fois racine et intégrés).

Avertissement

Les documents BSON peuvent techniquement contenir des clés dupliquées car les documents sont stockés en tant qu'une liste de paire clé-valeur ; cependant, les applications devrait s'abstenir de générer des documents avec des clés dupliquées car le comportement du serveur et du pilote peut être indéfinie. Puisque les objets et tableaux PHP ne peuvent pas avoir de clés dupliquées, les données pourraient aussi être perdu lors du décodage d'un document BSON avec des clés dupliquées.

### Liste de paramètres

`bson` (string)
  La valeur BSON à désérialiser.
`typeMap` (array)
  Configuration du type de carte.

### Valeurs de retour

La valeur PHP non sérialisée.

### Erreurs / Exceptions

- Lance une MongoDB\Driver\Exception\InvalidArgumentException si une classe dans la table de types ne peut pas être instanciée ou n'implémente pas MongoDB\BSON\Unserializable.
- Lance une exception MongoDB\Driver\Exception\UnexpectedValueException si l'entrée ne contient pas exactement un document BSON. Les raisons possibles comprennent, mais ne sont pas limitées à, BSON invalide, des données supplémentaires (après avoir lu un document BSON), ou une erreur imprévu de » libbson.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette fonction a été supprimée.
PECL mongodb 1.4.0 | Si l'entrée contient un type BSON non pris en charge ou obsolète, l'extension ne générera plus un avertissement dans le journal de débogage, mais créera plutôt un objet représentant ce type.
PECL mongodb 1.3.2 | MongoDB\Driver\Exception\UnexpectedValueException ne lance plus d'exception si l'entrée contient un type BSON non pris en charge ou obsolète. Ces types seront ignorés (comme ils l'étaient dans les versions antérieures à 1.3.0), bien que l'extension écrira désormais un avertissement dans le journal de débogage (voir : mongodb.debug).
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\UnexpectedValueException est lancée si l'entrée contient un type BSON non pris en charge ou obsolète. Auparavant, de tels types étaient ignorés.

### Exemples

Exemple #1 Exemple de MongoDB\BSON\toPHP()

    <?php

    $bson = hex2bin('0e00000010666f6f000100000000');
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

L'exemple ci-dessus va afficher :

    object(stdClass)#1 (1) {
      ["foo"]=>
      int(1)
    }

### Voir aussi

- MongoDB\BSON\Document::toPHP() - Renvoie la représentation PHP du document BSON
- MongoDB\BSON\fromPHP() - Retourne la représentation BSON d'une valeur PHP
- » MongoDB BSON
- Persister des données

# MongoDB\BSON\toRelaxedExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toRelaxedExtendedJSON — Renvoie la représentation JSON étendue détendue d'une valeur BSON

Avertissement

Cette fonction a été DÉPRÉCIÉE depuis la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications devraient utiliser MongoDB\BSON\Document::toRelaxedExtendedJSON() à la place.

### Description

function MongoDB\BSON\toRelaxedExtendedJSON(string `$bson`): string

Convertit une chaîne BSON en sa représentation » JSON étendue détendue. Le format détendu privilégie l'utilisation des types primitifs JSON au détriment de la fidélité des types et est le plus adapté pour produire une sortie qui peut être facilement consommée par des API web et des humains.

### Liste de paramètres

`bson` (string)
  La chaîne BSON à convertir.

### Valeurs de retour

La valeur JSON convertie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\Exception\UnexpectedValueException si l'entrée ne contient pas exactement un document BSON. Les raisons possibles comprennent, mais ne sont pas limitées à, BSON invalide, des données supplémentaires (après avoir lu un document BSON), ou une erreur imprévu de » libbson.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette fonction a été supprimée.

### Exemples

Exemple #1 Exemple de MongoDB\BSON\toRelaxedExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toRelaxedExtendedJSON($bson), "\n";
    }

    ?>

L'exemple ci-dessus va afficher :

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : "2015-10-28T00:00:00Z" } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Voir aussi

- MongoDB\BSON\Document::fromJSON() - Construit une nouvelle instance de document depuis une chaîne de caractères JSON
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Renvoie la représentation relaxée étendue JSON du document BSON
- MongoDB\BSON\fromJSON() - Retourne la représentation BSON d'une valeur JSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- » JSON étendu
- » MongoDB BSON

## Sommaire

- MongoDB\BSON\fromJSON — Retourne la représentation BSON d'une valeur JSON
- MongoDB\BSON\fromPHP — Retourne la représentation BSON d'une valeur PHP
- MongoDB\BSON\toCanonicalExtendedJSON — Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toJSON — Retourne la représentation JSON étendue héritée d'une valeur BSON
- MongoDB\BSON\toPHP — Renvoie la représentation PHP d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON — Renvoie la représentation JSON étendue détendue d'une valeur BSON

# La classe MongoDB\BSON\Document

(mongodb >=1.16.0)

## Introduction

Représente un document BSON. Cette classe est utilisée lors de la lecture de données en tant que BSON brut et ne peut pas être modifiée.

## Synopsis de la classe

final class MongoDB\BSON\Document implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Méthodes */
final private function __construct()
final static public function fromBSON(string `$bson`): MongoDB\BSON\Document
final static public function fromJSON(string `$json`): MongoDB\BSON\Document
final static public function fromPHP(object|array `$value`): MongoDB\BSON\Document
final public function get(string `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(string `$key`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.17.0 | Implémente MongoDB\BSON\Type.

# MongoDB\BSON\Document::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Document::__construct — Construit un nouveau document BSON (inutilisée)

### Description

final private function MongoDB\BSON\Document::__construct()

Les objets MongoDB\BSON\Document sont créés à travers des méthodes de fabrique statiques et ne peuvent pas être instanciés directement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- MongoDB\BSON\Document::fromPHP() - Construit une nouvelle instance de document depuis des données PHP
- MongoDB\BSON\Document::fromBSON() - Construit une nouvelle instance de document depuis une chaîne de caractères BSON
- MongoDB\BSON\Document::fromJSON() - Construit une nouvelle instance de document depuis une chaîne de caractères JSON
- » Types BSON

# MongoDB\BSON\Document::fromBSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromBSON — Construit une nouvelle instance de document depuis une chaîne de caractères BSON

### Description

final static public function MongoDB\BSON\Document::fromBSON(string `$bson`): MongoDB\BSON\Document

### Liste de paramètres

`bson` (string)
  Une chaîne de caractères contenant un document au format BSON.

### Valeurs de retour

Retourne une nouvelle instance de MongoDB\BSON\Document.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\UnexpectedValueException si `bson` est une chaîne de caractères invalide ou contenant plus d'un seul document

### Voir aussi

- MongoDB\BSON\Document::fromPHP() - Construit une nouvelle instance de document depuis des données PHP
- MongoDB\BSON\Document::fromJSON() - Construit une nouvelle instance de document depuis une chaîne de caractères JSON
- » BSON Types

# MongoDB\BSON\Document::fromJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromJSON — Construit une nouvelle instance de document depuis une chaîne de caractères JSON

### Description

final static public function MongoDB\BSON\Document::fromJSON(string `$json`): MongoDB\BSON\Document

Convertit une chaîne de caractères » JSON étendue en sa représentation BSON.

### Liste de paramètres

`json` (string)
  La valeur JSON à convertir.

### Valeurs de retour

Retourne une nouvelle instance de MongoDB\BSON\Document.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance MongoDB\Driver\Exception\UnexpectedValueException si la valeur JSON ne peut pas être convertie en document BSON (par exemple en raison d'une erreur de syntaxe).

### Voir aussi

- MongoDB\BSON\Document::fromPHP() - Construit une nouvelle instance de document depuis des données PHP
- MongoDB\BSON\Document::fromBSON() - Construit une nouvelle instance de document depuis une chaîne de caractères BSON
- » MongoDB JSON étendu
- » Type BSON

# MongoDB\BSON\Document::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromPHP — Construit une nouvelle instance de document depuis des données PHP

### Description

final static public function MongoDB\BSON\Document::fromPHP(object|array `$value`): MongoDB\BSON\Document

### Liste de paramètres

`value` (object|array)
  Un objet PHP ou un tableau contenant le document. Lorsqu'on passe un tableau avec des clés numériques, les valeurs numériques sont converties en chaînes de caractères et utilisées comme clés de document.

### Valeurs de retour

Retourne une nouvelle instance de MongoDB\BSON\Document.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\BSON\Document::fromBSON() - Construit une nouvelle instance de document depuis une chaîne de caractères BSON
- MongoDB\BSON\Document::fromJSON() - Construit une nouvelle instance de document depuis une chaîne de caractères JSON
- » Types BSON

# MongoDB\BSON\Document::get

(mongodb >=1.16.0)

MongoDB\BSON\Document::get — Retourne la valeur d'une clé dans un document

### Description

final public function MongoDB\BSON\Document::get(string `$key`): mixed

### Liste de paramètres

`key` (string)
  La clé à récupérer dans le document.

### Valeurs de retour

Renvoie la valeur associée à la clé donnée. Si la clé n'est pas présente dans le document, une exception est lancée.

> Note: Lorsqu'une valeur encodée en tant qu'entier 64 bits est rencontrée dans le document BSON, la valeur de retour de cette méthode sera une instance de MongoDB\BSON\Int64.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\RuntimeException si la clé n'est pas présente dans le document.

### Voir aussi

- MongoDB\BSON\Document::has() - Renvoie si une clé est présente dans le document
- » Types BSON

# MongoDB\BSON\Document::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\Document::getIterator — Renvoie un itérateur pour le document BSON

### Description

final public function MongoDB\BSON\Document::getIterator(): MongoDB\BSON\Iterator

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une instance de MongoDB\BSON\Iterator qui peut être utilisée pour itérer sur toutes les clés du document.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\UnexpectedValueException si l'itérateur BSON ne peut pas être initialisé.

### Voir aussi

- » Types BSON

# MongoDB\BSON\Document::has

(mongodb >=1.16.0)

MongoDB\BSON\Document::has — Renvoie si une clé est présente dans le document

### Description

final public function MongoDB\BSON\Document::has(string `$key`): bool

### Liste de paramètres

`key` (string)
  La clé à rechercher dans le document.

### Valeurs de retour

Renvoie `true` si la clé est présente dans le document sinon `false`.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\BSON\Document::get() - Retourne la valeur d'une clé dans un document
- » Types BSON

# MongoDB\BSON\Document::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetExists — Renvoie si une clé est présente dans le document

### Description

final public function MongoDB\BSON\Document::offsetExists(mixed `$key`): bool

### Liste de paramètres

`key`
  La clé à rechercher dans le document.

### Valeurs de retour

Renvoie `true` si la clé est présente dans le document sinon `false`.

### Voir aussi

- ArrayAccess::offsetExists() - Indique si une position existe dans un tableau
- MongoDB\BSON\Document::has() - Renvoie si une clé est présente dans le document

# MongoDB\BSON\Document::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetGet — Retourne la valeur d'une clé dans un document

### Description

final public function MongoDB\BSON\Document::offsetGet(mixed `$key`): mixed

### Liste de paramètres

`key`
  La clé à récupérer dans le document.

### Valeurs de retour

Renvoie la valeur associée à la clé donnée. Si la clé n'est pas présente dans le document, une exception est lancée.

> Note: Lorsqu'une valeur encodée en tant qu'entier 64 bits est rencontrée dans le document BSON, la valeur de retour de cette méthode sera une instance de MongoDB\BSON\Int64.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\RuntimeException si la clé n'est pas présente dans le document.

### Voir aussi

- ArrayAccess::offsetGet() - Position à lire
- MongoDB\BSON\Document::get() - Retourne la valeur d'une clé dans un document

# MongoDB\BSON\Document::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetSet — Implémentation d'ArrayAccess

### Description

final public function MongoDB\BSON\Document::offsetSet(mixed `$key`, mixed `$value`): void

Change la valeur à la `key` spécifiée pour `value`.

### Liste de paramètres

`key`
  L'index à définir.
`value`
  La nouvelle valeur pour la `key`.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance toujours une MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetUnset — Implémentation d'ArrayAccess

### Description

final public function MongoDB\BSON\Document::offsetUnset(mixed `$key`): void

Retire la valeur à l'index spécifié.

### Liste de paramètres

`key`
  L'index à retirer.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance toujours une MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::toCanonicalExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toCanonicalExtendedJSON — Renvoie la représentation Canonique Etendue JSON du document BSON

### Description

final public function MongoDB\BSON\Document::toCanonicalExtendedJSON(): string

Convertit le document BSON en sa représentation » Canonique Étendue JSON. Le format canonique préfère la fidélité des types au détriment de la sortie concise et est le plus adapté pour produire une sortie qui peut être convertie en BSON sans perte d'informations de type (par exemple, les types numériques resteront différenciés).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne contenant la » représentation Canonical Extended JSON du document BSON.

### Exemples

Exemple #1 Exemple de MongoDB\BSON\Document::toCanonicalExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0 ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toCanonicalExtendedJSON(), "\n";
    }

    ?>

L'exemple ci-dessus va afficher :

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Voir aussi

- MongoDB\BSON\Document::fromJSON() - Construit une nouvelle instance de document depuis une chaîne de caractères JSON
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Renvoie la représentation relaxée étendue JSON du document BSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- » Canonique Etendue JSON
- » Types BSON

# MongoDB\BSON\Document::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::toPHP — Renvoie la représentation PHP du document BSON

### Description

final public function MongoDB\BSON\Document::toPHP(?array `$typeMap` = `null`): array|object

Désérialise le document BSON en sa représentation PHP. Le paramètre `typeMap` peut être utilisé pour contrôler les types PHP utilisés pour convertir les tableaux et documents BSON (racine et intégrés).

Avertissement

Les documents BSON peuvent techniquement contenir des clés dupliquées car les documents sont stockés en tant qu'une liste de paire clé-valeur ; cependant, les applications devrait s'abstenir de générer des documents avec des clés dupliquées car le comportement du serveur et du pilote peut être indéfinie. Puisque les objets et tableaux PHP ne peuvent pas avoir de clés dupliquées, les données pourraient aussi être perdu lors du décodage d'un document BSON avec des clés dupliquées.

### Liste de paramètres

`typeMap` (array)
  Configuration du type de carte.

### Valeurs de retour

La valeur décodée PHP.

> Note: Lorsqu'une valeur encodée en tant qu'entier 64 bits est rencontrée dans le document BSON, la valeur de retour de cette méthode sera une instance de MongoDB\BSON\Int64.

### Erreurs / Exceptions

- Lance une MongoDB\Driver\Exception\InvalidArgumentException si un type dans la carte de type ne peut pas être instancié ou n'implémente pas MongoDB\BSON\Unserializable.

### Voir aussi

- MongoDB\BSON\toPHP() - Renvoie la représentation PHP d'une valeur BSON
- » Types BSON

# MongoDB\BSON\Document::toRelaxedExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toRelaxedExtendedJSON — Renvoie la représentation relaxée étendue JSON du document BSON

### Description

final public function MongoDB\BSON\Document::toRelaxedExtendedJSON(): string

Convertit le document BSON en sa représentation » Relaxée Étendue JSON. Le format relaxé préfère l'utilisation des primitives de type JSON au détriment de la fidélité des types et est le plus adapté pour produire une sortie qui peut être facilement consommée par les API web et les humains.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne contenant la » représentation Relaxed Extended JSON du document BSON.

### Exemples

Exemple #1 Exemple de MongoDB\BSON\Document::toRelaxedExtendedJSON()

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0 ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toRelaxedExtendedJSON(), "\n";
    }

    ?>

L'exemple ci-dessus va afficher :

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : "2015-10-28T00:00:00Z" } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Voir aussi

- MongoDB\BSON\Document::fromJSON() - Construit une nouvelle instance de document depuis une chaîne de caractères JSON
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Renvoie la représentation Canonique Etendue JSON du document BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » Spécification JSON étendue
- » Types BSON

# MongoDB\BSON\Document::__toString

(mongodb >=1.16.0)

MongoDB\BSON\Document::__toString — Renvoie la représentation en chaîne de caractères de ce document BSON

### Description

final public function MongoDB\BSON\Document::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la représentation en chaîne de caractères de ce document BSON.

### Voir aussi

- » Types BSON

## Sommaire

- MongoDB\BSON\Document::__construct — Construit un nouveau document BSON (inutilisée)
- MongoDB\BSON\Document::fromBSON — Construit une nouvelle instance de document depuis une chaîne de caractères BSON
- MongoDB\BSON\Document::fromJSON — Construit une nouvelle instance de document depuis une chaîne de caractères JSON
- MongoDB\BSON\Document::fromPHP — Construit une nouvelle instance de document depuis des données PHP
- MongoDB\BSON\Document::get — Retourne la valeur d'une clé dans un document
- MongoDB\BSON\Document::getIterator — Renvoie un itérateur pour le document BSON
- MongoDB\BSON\Document::has — Renvoie si une clé est présente dans le document
- MongoDB\BSON\Document::offsetExists — Renvoie si une clé est présente dans le document
- MongoDB\BSON\Document::offsetGet — Retourne la valeur d'une clé dans un document
- MongoDB\BSON\Document::offsetSet — Implémentation d'ArrayAccess
- MongoDB\BSON\Document::offsetUnset — Implémentation d'ArrayAccess
- MongoDB\BSON\Document::toCanonicalExtendedJSON — Renvoie la représentation Canonique Etendue JSON du document BSON
- MongoDB\BSON\Document::toPHP — Renvoie la représentation PHP du document BSON
- MongoDB\BSON\Document::toRelaxedExtendedJSON — Renvoie la représentation relaxée étendue JSON du document BSON
- MongoDB\BSON\Document::__toString — Renvoie la représentation en chaîne de caractères de ce document BSON

# La classe MongoDB\BSON\PackedArray

(mongodb >=1.16.0)

## Introduction

Représente un tableau BSON. Cette classe est utilisée lors de la lecture de données en tant que BSON brut et ne peut pas être modifiée.

## Synopsis de la classe

final class MongoDB\BSON\PackedArray implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Méthodes */
final private function __construct()
final static public function fromJSON(string `$json`): MongoDB\BSON\PackedArray
final static public function fromPHP(array `$value`): MongoDB\BSON\PackedArray
final public function get(int `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(int `$index`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.17.0 | Implémente MongoDB\BSON\Type.
PECL mongodb 1.17.0 | MongoDB\BSON\PackedArray ne peut pas être sérialisé dans des contextes où un document BSON est attendu. Dans les versions précédentes, le tableau BSON aurait été converti en document.

# MongoDB\BSON\PackedArray::__construct

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__construct — Construit un nouveau tableau BSON (inutilisé)

### Description

final private function MongoDB\BSON\PackedArray::__construct()

Les objets MongoDB\BSON\PackedArray sont créés avec des méthodes de fabrique statiques et ne peuvent pas être instanciés directement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- MongoDB\BSON\PackedArray::fromPHP() - Construit une nouvelle instance de tableau BSON depuis des données PHP
- » Types BSON

# MongoDB\BSON\PackedArray::fromJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::fromJSON — Construit une nouvelle instance de tableau BSON à partir d'une chaîne JSON

### Description

final static public function MongoDB\BSON\PackedArray::fromJSON(string `$json`): MongoDB\BSON\PackedArray

Convertit une chaîne » JSON étendu en sa représentation BSON.

### Liste de paramètres

`json` (string)
  La valeur JSON à convertir.

### Valeurs de retour

Renvoie une nouvelle instance de MongoDB\BSON\PackedArray.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\UnexpectedValueException si la valeur JSON ne peut pas être convertie en tableau BSON (par exemple, en raison d'une erreur de syntaxe).

### Exemples

Exemple #1 Exemple de MongoDB\BSON\PackedArray::fromJSON()

    <?php

    $json = '[ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]';
    $packedArray = MongoDB\BSON\PackedArray::fromJSON($json);
    var_dump($packedArray);

    ?>

L'exemple ci-dessus va afficher :

    object(MongoDB\BSON\PackedArray)#1 (2) {
      ["data"]=>
      string(68) "MQAAAAIwAAQAAABmb28AEDEAewAAABIyAP////8AAAAABzMAVjFafGEY/RuSAnCxAA=="
      ["value"]=>
      array(4) {
        [0]=>
        string(3) "foo"
        [1]=>
        int(123)
        [2]=>
        int(4294967295)
        [3]=>
        object(MongoDB\BSON\ObjectId)#2 (1) {
          ["oid"]=>
          string(24) "56315a7c6118fd1b920270b1"
        }
      }
    }

### Voir aussi

- MongoDB\BSON\PackedArray::fromPHP() - Construit une nouvelle instance de tableau BSON depuis des données PHP
- » Json étendu de MongoDB
- » Types BSON

# MongoDB\BSON\PackedArray::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::fromPHP — Construit une nouvelle instance de tableau BSON depuis des données PHP

### Description

final static public function MongoDB\BSON\PackedArray::fromPHP(array `$value`): MongoDB\BSON\PackedArray

### Liste de paramètres

`value` (array)
  Le tableau PHP à convertir en tableau BSON. Le tableau doit être une liste (c'est-à-dire avoir des clés numériques séquentielles commençant par `0`).

### Valeurs de retour

Retourne une nouvelle instance de MongoDB\BSON\PackedArray.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\InvalidArgumentException si le tableau donné n'est pas une liste (c'est-à-dire il a des clés numériques séquentielles commençant par `0`).

### Voir aussi

- » Types BSON

# MongoDB\BSON\PackedArray::get

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::get — Renvoie la valeur d'un index du tableau

### Description

final public function MongoDB\BSON\PackedArray::get(int `$key`): mixed

### Liste de paramètres

`key` (int)
  L'index à récupérer du tableau.

### Valeurs de retour

Renvoie la valeur associée à l'index donné. Si l'index n'est pas présent dans le tableau, une exception est lancée.

> Note: Lorsqu'une valeur encodée en tant qu'entier 64 bits est rencontrée dans le tableau BSON, la valeur de retour de cette méthode sera une instance de MongoDB\BSON\Int64.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\RuntimeException si l'index n'est pas présent dans le tableau.

### Voir aussi

- MongoDB\BSON\PackedArray::has() - Renvoie si un index est présent dans le tableau
- » Types BSON

# MongoDB\BSON\PackedArray::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::getIterator — Renvoie l'itérateur pour le tableau BSON

### Description

final public function MongoDB\BSON\PackedArray::getIterator(): MongoDB\BSON\Iterator

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une instance de MongoDB\BSON\Iterator qui peut être utilisée pour itérer sur tous les index du tableau.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\UnexpectedValueException si l'itérateur BSON ne peut pas être instancié.

### Voir aussi

- » Types BSON

# MongoDB\BSON\PackedArray::has

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::has — Renvoie si un index est présent dans le tableau

### Description

final public function MongoDB\BSON\PackedArray::has(int `$index`): bool

### Liste de paramètres

`index` (int)
  L'index à chercher dans le tableau.

### Valeurs de retour

Renvoie `true` si l'index est présent dans le tableau sinon `false`.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\BSON\PackedArray::get() - Renvoie la valeur d'un index du tableau
- » Types BSON

# MongoDB\BSON\PackedArray::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetExists — Renvoie si un index est présent dans le tableau

### Description

final public function MongoDB\BSON\PackedArray::offsetExists(mixed `$key`): bool

### Liste de paramètres

`key`
  L'index à chercher dans le tableau.

### Valeurs de retour

Renvoie `true` si l'index est présent dans le tableau sinon `false`.

### Voir aussi

- ArrayAccess::offsetExists() - Indique si une position existe dans un tableau
- MongoDB\BSON\PackedArray::has() - Renvoie si un index est présent dans le tableau

# MongoDB\BSON\PackedArray::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetGet — Renvoie la valeur d'un index du tableau

### Description

final public function MongoDB\BSON\PackedArray::offsetGet(mixed `$key`): mixed

### Liste de paramètres

`key`
  L'index à récupérer du tableau. Seulement int est supporté.

### Valeurs de retour

Renvoie la valeur associée à l'index donné. Si l'index n'est pas présent dans le tableau, une exception est lancée.

> Note: Lorsqu'une valeur encodée en tant qu'entier 64 bits est rencontrée dans le tableau BSON, la valeur de retour de cette méthode sera une instance de MongoDB\BSON\Int64.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\RuntimeException si l'index n'est pas présent dans le tableau.

### Voir aussi

- ArrayAccess::offsetGet() - Position à lire
- MongoDB\BSON\PackedArray::get() - Renvoie la valeur d'un index du tableau

# MongoDB\BSON\PackedArray::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetSet — Implémentation de ArrayAccess

### Description

final public function MongoDB\BSON\PackedArray::offsetSet(mixed `$key`, mixed `$value`): void

Change la valeur de `key` pour `value`.

### Liste de paramètres

`key`
  L'index à modifier.
`value`
  La nouvelle valeur de `key`.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance toujours une MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetUnset — Implémentation de ArrayAccess

### Description

final public function MongoDB\BSON\PackedArray::offsetUnset(mixed `$key`): void

Retire la valeur à l'index donné.

### Liste de paramètres

`key`
  La valeur à retirer.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance toujours une MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::toCanonicalExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Renvoie la représentation JSON étendue canonique du tableau BSON

### Description

final public function MongoDB\BSON\PackedArray::toCanonicalExtendedJSON(): string

Convertit le tableau BSON en sa représentation » JSON étendue canonique. Le format canonique privilégie la fidélité des types au détriment de la concision de la sortie et est le plus adapté pour produire une sortie qui peut être convertie en BSON sans perte d'informations de type (par exemple, les types numériques resteront différenciés).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une chaîne contenant la représentation » JSON étendue canonique du tableau BSON.

### Exemples

Exemple #1 Exemple de MongoDB\BSON\PackedArray::toCanonicalExtendedJSON()

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toCanonicalExtendedJSON(), "\n";

    ?>

L'exemple ci-dessus va afficher :

    [ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### Voir aussi

- MongoDB\BSON\PackedArray::fromJSON() - Construit une nouvelle instance de tableau BSON à partir d'une chaîne JSON
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue relaxée du tableau BSON
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- » Spécification du JSON étendu
- » Types BSON

# MongoDB\BSON\PackedArray::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::toPHP — Renvoie la représentation PHP du tableau BSON

### Description

final public function MongoDB\BSON\PackedArray::toPHP(?array `$typeMap` = `null`): array|object

### Liste de paramètres

`typeMap` (array)
  Configuration du type de carte.

### Valeurs de retour

La valeur décodée en PHP.

> Note: Lorsqu'une valeur encodée en tant qu'entier 64 bits est rencontrée dans le tableau BSON, la valeur de retour de cette méthode sera une instance de MongoDB\BSON\Int64.

### Erreurs / Exceptions

- Lance une MongoDB\Driver\Exception\InvalidArgumentException si une classe dans le type map ne peut pas être instanciée ou n'implémente pas MongoDB\BSON\Unserializable.

### Voir aussi

- MongoDB\BSON\toPHP() - Renvoie la représentation PHP d'une valeur BSON
- » Types BSON

# MongoDB\BSON\PackedArray::toRelaxedExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Renvoie la représentation JSON étendue relaxée du tableau BSON

### Description

final public function MongoDB\BSON\PackedArray::toRelaxedExtendedJSON(): string

Convertit le tableau BSON en sa représentation » JSON étendue relaxée. Le format relaxé préfère l'utilisation des types primitifs JSON au détriment de la fidélité des types et est le plus adapté pour produire une sortie qui peut être facilement consommée par des API web et des humains.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une chaîne contenant la représentation » JSON étendue relaxée du tableau BSON.

### Exemples

Exemple #1 Exemple de MongoDB\BSON\PackedArray::toRelaxedExtendedJSON()

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toRelaxedExtendedJSON(), "\n";

    ?>

L'exemple ci-dessus va afficher :

    [ "foo", 123, 4294967295, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### Voir aussi

- MongoDB\BSON\PackedArray::fromJSON() - Construit une nouvelle instance de tableau BSON à partir d'une chaîne JSON
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique du tableau BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » Spécification du JSON étendu
- » Types BSON

# MongoDB\BSON\PackedArray::__toString

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__toString — Renvoie la représentation en chaîne de caractères pour ce tableau BSON

### Description

final public function MongoDB\BSON\PackedArray::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la représentation en chaîne de caractères de ce tableau BSON.

### Voir aussi

- » Types BSON

## Sommaire

- MongoDB\BSON\PackedArray::__construct — Construit un nouveau tableau BSON (inutilisé)
- MongoDB\BSON\PackedArray::fromJSON — Construit une nouvelle instance de tableau BSON à partir d'une chaîne JSON
- MongoDB\BSON\PackedArray::fromPHP — Construit une nouvelle instance de tableau BSON depuis des données PHP
- MongoDB\BSON\PackedArray::get — Renvoie la valeur d'un index du tableau
- MongoDB\BSON\PackedArray::getIterator — Renvoie l'itérateur pour le tableau BSON
- MongoDB\BSON\PackedArray::has — Renvoie si un index est présent dans le tableau
- MongoDB\BSON\PackedArray::offsetExists — Renvoie si un index est présent dans le tableau
- MongoDB\BSON\PackedArray::offsetGet — Renvoie la valeur d'un index du tableau
- MongoDB\BSON\PackedArray::offsetSet — Implémentation de ArrayAccess
- MongoDB\BSON\PackedArray::offsetUnset — Implémentation de ArrayAccess
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Renvoie la représentation JSON étendue canonique du tableau BSON
- MongoDB\BSON\PackedArray::toPHP — Renvoie la représentation PHP du tableau BSON
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Renvoie la représentation JSON étendue relaxée du tableau BSON
- MongoDB\BSON\PackedArray::__toString — Renvoie la représentation en chaîne de caractères pour ce tableau BSON

# La classe MongoDB\BSON\Iterator

(mongodb >=1.16.0)

## Introduction

Itérateur utilisé pour parcourir un document ou un tableau BSON.

## Synopsis de la classe

final class MongoDB\BSON\Iterator implements Iterator {
/* Méthodes */
final private function __construct()
public function current(): mixed
public function key(): string|int
public function next(): void
public function rewind(): void
public function valid(): bool
}

# MongoDB\BSON\Iterator::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::__construct — Construit un nouvel itérateur BSON (inutilisée)

### Description

final private function MongoDB\BSON\Iterator::__construct()

Les objets MongoDB\BSON\Iterator sont créés en appelant MongoDB\BSON\Document::getIterator() ou MongoDB\BSON\PackedArray::getIterator() et ne peuvent pas être instanciés directement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- MongoDB\BSON\Document::getIterator() - Renvoie un itérateur pour le document BSON
- MongoDB\BSON\PackedArray::getIterator() - Renvoie l'itérateur pour le tableau BSON
- » Types BSON

# MongoDB\BSON\Iterator::current

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::current — Renvoie l'élément actuel

### Description

public function MongoDB\BSON\Iterator::current(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la valeur de l'élément actuel.

> Note: Lorsqu'une valeur encodée en tant qu'entier 64 bits dans la structure BSON est rencontrée, la valeur de retour de cette méthode sera une instance de MongoDB\BSON\Int64.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\LogicException si l'itérateur n'est pas valide.

### Voir aussi

- Iterator::current() - Retourne l'élément courant

# MongoDB\BSON\Iterator::key

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::key — Renvoie la clé de l'élément actuel

### Description

public function MongoDB\BSON\Iterator::key(): string|int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la clé de l'élément actuel. Lors de l'itération d'un document BSON, la clé sera toujours une string. Lors de l'itération d'un tableau BSON, la clé sera un int.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\LogicException si l'itérateur n'est pas valide.

### Voir aussi

- Iterator::key() - Retourne la clé de l'élément courant

# MongoDB\BSON\Iterator::next

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::next — Avance l'itérateur à l'élément suivant

### Description

public function MongoDB\BSON\Iterator::next(): void

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- Iterator::next() - Se déplace sur l'élément suivant

# MongoDB\BSON\Iterator::rewind

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::rewind — Rembobine l'itérateur au premier élément

### Description

public function MongoDB\BSON\Iterator::rewind(): void

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- Iterator::rewind() - Replace l'itérateur sur le premier élément

# MongoDB\BSON\Iterator::valid

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::valid — Vérifie si la position courante est valide

### Description

public function MongoDB\BSON\Iterator::valid(): bool

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si la position courante de l'itérateur est valide, sinon `false`.

### Voir aussi

- Iterator::valid() - Vérifie si la position courante est valide

## Sommaire

- MongoDB\BSON\Iterator::__construct — Construit un nouvel itérateur BSON (inutilisée)
- MongoDB\BSON\Iterator::current — Renvoie l'élément actuel
- MongoDB\BSON\Iterator::key — Renvoie la clé de l'élément actuel
- MongoDB\BSON\Iterator::next — Avance l'itérateur à l'élément suivant
- MongoDB\BSON\Iterator::rewind — Rembobine l'itérateur au premier élément
- MongoDB\BSON\Iterator::valid — Vérifie si la position courante est valide

# La classe MongoDB\BSON\Binary

(mongodb >=1.0.0)

## Introduction

Type BSON pour les données binaires (c.-à-d. tableau d'octets). Les valeurs binaires ont également un sous-type, qui est utilisé pour indiquer quel type de données se trouve dans le tableau d'octets. Les sous-types de zéro à 127 sont prédéfinis ou réservés. Les sous-types de 128-255 sont définis par l'utilisateur.

## Synopsis de la classe

final class MongoDB\BSON\Binary implements MongoDB\BSON\BinaryInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Constantes */
const int TYPE_GENERIC = 0;
const int TYPE_FUNCTION = 1;
const int TYPE_OLD_BINARY = 2;
const int TYPE_OLD_UUID = 3;
const int TYPE_UUID = 4;
const int TYPE_MD5 = 5;
const int TYPE_ENCRYPTED = 6;
const int TYPE_COLUMN = 7;
const int TYPE_SENSITIVE = 8;
const int TYPE_VECTOR = 9;
const int TYPE_USER_DEFINED = 128;
/* Méthodes */
final public function __construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)
final public static function fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary
final public function getData(): string
final public function getType(): int
final public function getVectorType(): MongoDB\BSON\VectorType
final public function jsonSerialize(): mixed
final public function toArray(): array
final public function __toString(): string
}

## Constantes pré-définies

`MongoDB\BSON\Binary::TYPE_GENERIC`
  Données binaires génériques.
`MongoDB\BSON\Binary::TYPE_FUNCTION`
  Fonction.
`MongoDB\BSON\Binary::TYPE_OLD_BINARY`
  Données binaires génériques (déconseillées en faveur de `MongoDB\BSON\Binary::TYPE_GENERIC`).
`MongoDB\BSON\Binary::TYPE_OLD_UUID`
  Identificateur universellement unique (déconseillé en faveur de `MongoDB\BSON\Binary::TYPE_UUID`). Lors de l'utilisation de ce type, les données du binaire doivent être de 16 octets de longueur. Historiquement, d'autres pilotes encodent des valeurs avec ce type en fonction de leurs conventions linguistiques (par exemple, variable endianness), ce qui le rend non-portable. Le pilote PHP n'applique aucune manipulation spéciale pour coder ou décoder des données avec ce type.
`MongoDB\BSON\Binary::TYPE_UUID`
  Identificateur universellement unique. Lors de l'utilisation de ce type, les données du binaire doivent être de 16 octets de longueur et encodées selon » RFC 4122.
`MongoDB\BSON\Binary::TYPE_MD5`
  Hachage MD5. Lors de l'utilisation de ce type, les données du binaire doivent être de 16 octets de longueur.
`MongoDB\BSON\Binary::TYPE_ENCRYPTED`
  Valeur chiffrée. Ce sous type est utilisé pour le chiffrement côté client.
`MongoDB\BSON\Binary::TYPE_COLUMN`
  Donnée de colonne. Ce sous type est utilisé pour les collections de série temporelle.
`MongoDB\BSON\Binary::TYPE_SENSITIVE`
  Données sensibles. Ce sous type est utilisé pour les données sensibles qui devraient être exclues des journaux d'évènements côté serveur si possible.
`MongoDB\BSON\Binary::TYPE_VECTOR`
  Données vectorielles. Ce sous-type est utilisé pour stocker efficacement des données vectorielles pour une utilisation avec la recherche vectorielle de MongoDB.
`MongoDB\BSON\Binary::TYPE_USER_DEFINED`
  Type défini par l'utilisateur. Alors que les types entre 0 et 127 sont prédéfinis ou réservés, les types entre 128 et 255 sont définis par l'utilisateur et peuvent être utilisés pour n'importe quoi.

## Historique

Version | Description
--- | ---
PECL mongodb 2.2.0 | Ajout de `MongoDB\BSON\Binary::TYPE_VECTOR`, ainsi que des fonctions MongoDB\BSON\Binary::fromVector(), MongoDB\BSON\Binary::getVectorType() et MongoDB\BSON\Binary::toArray().
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.17.0 | Ajout de `MongoDB\BSON\Binary::TYPE_SENSITIVE`.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+. Ajout de `MongoDB\BSON\Binary::TYPE_COLUMN`.
PECL mongodb 1.7.0 | Ajout de `MongoDB\BSON\Binary::TYPE_ENCRYPTED`.
PECL mongodb 1.3.0 | Implémente MongoDB\BSON\BinaryInterface.
PECL mongodb 1.2.0 | Implémente Serializable et JsonSerializable.

# MongoDB\BSON\Binary::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Binary::__construct — Construit un nouveau binaire

### Description

final public function MongoDB\BSON\Binary::__construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)

### Liste de paramètres

`data` (string)
  Les données binaires.
`type` (int)
  Entier 8 bits non signé indiquant le type de données. Par défaut, la valeur est `MongoDB\BSON\Binary::TYPE_GENERIC` si elle n'est pas spécifiée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\InvalidArgumentException si `type` n'est pas un entier non signé de 8 bits.
- Lève une exception MongoDB\Driver\Exception\InvalidArgumentException si `type` est `MongoDB\BSON\Binary::TYPE_UUID` ou `MongoDB\BSON\Binary::TYPE_OLD_UUID` et `data` n'a pas exactement 16 octets de longueur.

### Historique

Version | Description
--- | ---
PECL mongodb 1.15.0 | Le paramètre `type` est désormais facultatif et a pour valeur par défaut `MongoDB\BSON\Binary::TYPE_GENERIC` s'il n'est pas spécifié.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException est levée si `type` est `MongoDB\BSON\Binary::TYPE_UUID` ou `MongoDB\BSON\Binary::TYPE_OLD_UUID` et `data` n'a pas exactement 16 octets de longueur.
PECL mongodb 1.1.3 | MongoDB\Driver\Exception\InvalidArgumentException est levée si `type` n'est pas un entier non signé de 8 bits.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Binary::__construct()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary);

    ?>

L'exemple ci-dessus va afficher :

    object(MongoDB\BSON\Binary)#1 (2) {
      ["data"]=>
      string(3) "foo"
      ["type"]=>
      int(0)
    }

### Voir aussi

- » Les types BSON

# MongoDB\BSON\Binary::fromVector

(mongodb >=2.2.0)

MongoDB\BSON\Binary::fromVector — Crée un nouveau binaire avec le sous-type `MongoDB\BSON\Binary::SUBTYPE_VECTOR` à partir du tableau et du type de vecteur donnés

### Description

final public static function MongoDB\BSON\Binary::fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary

### Liste de paramètres

`vector` (array)

  Un tableau de valeurs représentant les données vectorielles. Le type de chaque valeur doit correspondre au type indiqué par le paramètre `vectorType`:

  - pour `MongoDB\BSON\VectorType::Float32`, chaque valeur doit être un float
  - pour `MongoDB\BSON\VectorType::Int8`, chaque valeur doit être un int de 8 bits, c'est-à-dire de `-127` à `128`
  - pour `MongoDB\BSON\VectorType::PackedBit`, chaque valeur doit être un bool ou un int de 1 bit, c'est-à-dire `0` ou `1`
`vectorType` (MongoDB\BSON\VectorType)
  Le type de donnée du vecteur.

### Valeurs de retour

Renvoie un nouveau binaire avec le sous-type `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\BSON\Binary::toArray() - Renvoie le vecteur sous forme de tableau pour un binaire avec le sous-type MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::getVectorType() - Renvoie le type de données pour un binaire avec le sous-type vecteur
- MongoDB\BSON\VectorType
- » BSON Types

# MongoDB\BSON\Binary::getData

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getData — Retourne les données de Binary

### Description

final public function MongoDB\BSON\Binary::getData(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les données de Binary.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Binary::getData()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getData());

    ?>

L'exemple ci-dessus va afficher :

    string(3) "foo"

### Voir aussi

- » Types BSON

# MongoDB\BSON\Binary::getType

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getType — Retourne le type de Binary

### Description

final public function MongoDB\BSON\Binary::getType(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le type de Binary.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Binary::getType()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getType());

    ?>

L'exemple ci-dessus va afficher :

    int(0)

### Voir aussi

- » Types BSON

# MongoDB\BSON\Binary::getVectorType

(mongodb >=2.2.0)

MongoDB\BSON\Binary::getVectorType — Renvoie le type de données pour un binaire avec le sous-type vecteur

### Description

final public function MongoDB\BSON\Binary::getVectorType(): MongoDB\BSON\VectorType

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le type de données du vecteur binaire.

### Erreurs / Exceptions

- Lève une MongoDB\Driver\Exception\LogicException si le sous-type n'est pas `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- » Types BSON
- MongoDB\BSON\VectorType

# MongoDB\BSON\Binary::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\Binary::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\Binary.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\Binary::toArray

(mongodb >=2.2.0)

MongoDB\BSON\Binary::toArray — Renvoie le vecteur sous forme de tableau pour un binaire avec le sous-type `MongoDB\BSON\Binary::SUBTYPE_VECTOR`

### Description

final public function MongoDB\BSON\Binary::toArray(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un tableau contenant les données vectorielles.

### Erreurs / Exceptions

- Lève une MongoDB\Driver\Exception\LogicException si le sous-type n'est pas `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\BSON\Binary::fromVector() - Crée un nouveau binaire avec le sous-type MongoDB\BSON\Binary::SUBTYPE_VECTOR à partir du tableau et du type de vecteur donnés
- » Types BSON

# MongoDB\BSON\Binary::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Binary::__toString — Retourne les données de Binary

### Description

final public function MongoDB\BSON\Binary::__toString(): string

Cette méthode est un alias de: MongoDB\BSON\Binary::getData().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les données de Binary.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Binary::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC));

    ?>

L'exemple ci-dessus va afficher :

    string(3) "foo"

### Voir aussi

- MongoDB\BSON\Binary::getData() - Retourne les données de Binary
- » Types BSON

## Sommaire

- MongoDB\BSON\Binary::__construct — Construit un nouveau binaire
- MongoDB\BSON\Binary::fromVector — Crée un nouveau binaire avec le sous-type MongoDB\BSON\Binary::SUBTYPE_VECTOR à partir du tableau et du type de vecteur donnés
- MongoDB\BSON\Binary::getData — Retourne les données de Binary
- MongoDB\BSON\Binary::getType — Retourne le type de Binary
- MongoDB\BSON\Binary::getVectorType — Renvoie le type de données pour un binaire avec le sous-type vecteur
- MongoDB\BSON\Binary::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\Binary::toArray — Renvoie le vecteur sous forme de tableau pour un binaire avec le sous-type MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::__toString — Retourne les données de Binary

# L'énumération MongoDB\BSON\VectorType

(mongodb >=2.2.0)

## Introduction

L'énumération MongoDB\BSON\VectorType est utilisée pour spécifier le type de données vectorielles stockées dans une MongoDB\BSON\Binary avec le sous-type `MongoDB\BSON\Binary::TYPE_VECTOR`.

## Synopsis d'Enum

enum MongoDB\BSON\VectorType
{
case Float32 ; // Chaque élément dans le vecteur est une valeur à virgule flottante de 32 bits.
case Int8 ; // Chaque élément dans le vecteur est une valeur entière de 8 bits.
case PackedBit ; // Chaque élément dans le vecteur est une valeur de 1 bit. Lors de la création de vecteurs de ce type, il est possible de passer soit des valeurs bool, soit des valeurs int de 1 bit, c'est-à-dire `0` ou `1`.
}

# La classe MongoDB\BSON\Decimal128

(mongodb >=1.2.0)

## Introduction

Type BSON pour le » format à virgule flottante Decimal128, qui supporte les nombres avec jusqu'à 34 chiffres décimaux (c.-à-d. chiffres significatifs) et une plage d'exposants de −6143 à +6144.

Contrairement au type BSON double (c.-à-d. float en PHP), qui ne stocke qu'une approximation des valeurs décimales, le type de données décimal stocke la valeur exacte. Par exemple, `MongoDB\BSON\Decimal128('9.99')` a une valeur précise de 9.99 alors qu'un double 9.99 aurait une valeur approximative de 9.9900000000000002131628….

> Note: MongoDB\BSON\Decimal128 n'est compatible qu'avec MongoDB 3.4+. Si vous tentez d'utiliser le type BSON avec une ancienne version de MongoDB, une erreur sera émise.

## Synopsis de la classe

final class MongoDB\BSON\Decimal128 implements MongoDB\BSON\Decimal128Interface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final public function __construct(string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.
PECL mongodb 1.3.0 | Implémente MongoDB\BSON\Decimal128Interface.
PECL mongodb 1.2.0 | Implémente Serializable et JsonSerializable.

# MongoDB\BSON\Decimal128::__construct

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__construct — Construit un nouveau Decimal128

### Description

final public function MongoDB\BSON\Decimal128::__construct(string `$value`)

> Note: MongoDB\BSON\Decimal128 n'est compatible qu'avec MongoDB 3.4+. Si vous tentez d'utiliser le type BSON avec une ancienne version de MongoDB, une erreur sera émise.

### Liste de paramètres

`value` (chaîne de caractères)
  Une chaîne décimale

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance MongoDB\Driver\Exception\InvalidArgumentException si `value` n'est pas une chaîne décimale valide.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Decimal128::__construct()

    <?php

    var_dump(new MongoDB\BSON\Decimal128(1234.5678));
    var_dump(new MongoDB\BSON\Decimal128(NAN));
    var_dump(new MongoDB\BSON\Decimal128(INF));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(9) "1234.5678"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(3) "NaN"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(8) "Infinity"
    }

### Voir aussi

- » Format de virgule flottante Decimal128
- » Types BSON

# MongoDB\BSON\Decimal128::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\Decimal128::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\Decimal128.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\Decimal128::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__toString — Retourne la représentation sous forme de chaîne de caractères de Decimal128

### Description

final public function MongoDB\BSON\Decimal128::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de caractères de Decimal128.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Decimal128::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Decimal128(1234.5678));
    var_dump((string) new MongoDB\BSON\Decimal128(NAN));
    var_dump((string) new MongoDB\BSON\Decimal128(INF));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(9) "1234.5678"
    string(3) "NaN"
    string(8) "Infinity"

### Voir aussi

- » Format de virgule flottante Decimal128
- » Types BSON

## Sommaire

- MongoDB\BSON\Decimal128::__construct — Construit un nouveau Decimal128
- MongoDB\BSON\Decimal128::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\Decimal128::__toString — Retourne la représentation sous forme de chaîne de caractères de Decimal128

# La classe MongoDB\BSON\Javascript

(mongodb >=1.0.0)

## Introduction

Type BSON pour le code JavaScript. Un document d'étendue optionnel peut être spécifié qui mappe les identificateurs aux valeurs et définit l'étendue dans laquelle le code doit être évalué par le serveur.

> Note: Ce type BSON est principalement utilisé lors de l'exécution de commandes de base de données qui prennent une fonction JavaScript comme paramètre, tel que » mapReduce.

## Synopsis de la classe

final class MongoDB\BSON\Javascript implements MongoDB\BSON\JavascriptInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final public function __construct(string `$code`, array|object|null `$scope` = `null`)
final public function getCode(): string
final public function getScope(): ?object
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.
PECL mongodb 1.3.0 | Implémente MongoDB\BSON\JavascriptInterface.
PECL mongodb 1.2.0 | Implémente Serializable et JsonSerializable.

# MongoDB\BSON\Javascript::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Javascript::__construct — Construit un nouvel objet Javascript

### Description

final public function MongoDB\BSON\Javascript::__construct(string `$code`, array|object|null `$scope` = `null`)

### Liste de paramètres

`code` (string)
  Le code Javascript.
`scope` (array|object)
  La portée du Javascript.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève MongoDB\Driver\Exception\InvalidArgumentException si `code` contient un octet nul.

### Historique

Version | Description
--- | ---
PECL mongodb 1.2.0 | MongoDB\Driver\Exception\InvalidArgumentException est levée si `code` contient un octet nul. Auparavant, les valeurs étaient tronquées au premier octet nul.

### Exemples

Exemple #1 MongoDB\BSON\Javascript::__construct() example

    <?php

    $code = new MongoDB\BSON\Javascript('function() { return 1; }');
    var_dump($code);

    $codews = new MongoDB\BSON\Javascript('function() { return foo; }', ['foo' => 'bar']);
    var_dump($codews);

    ?>

L'exemple ci-dessus va afficher :

    object(MongoDB\BSON\Javascript)#1 (2) {
      ["javascript"]=>
      string(24) "function() { return 1; }"
      ["scope"]=>
      object(stdClass)#2 (0) {
      }
    }
    object(MongoDB\BSON\Javascript)#2 (2) {
      ["javascript"]=>
      string(26) "function() { return foo; }"
      ["scope"]=>
      object(stdClass)#1 (1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Voir aussi

- » Les types BSON

# MongoDB\BSON\Javascript::getCode

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getCode — Retourne le code Javascript

### Description

final public function MongoDB\BSON\Javascript::getCode(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code Javascript.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Javascript::getCode()

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getCode());

    ?>

L'exemple ci-dessus va afficher :

    string(33) "function foo(bar) { return bar; }"

### Voir aussi

- » Types BSON

# MongoDB\BSON\Javascript::getScope

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getScope — Retourne le document de portée de Javascript

### Description

final public function MongoDB\BSON\Javascript::getScope(): ?object

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le document de portée de Javascript, ou `null` s'il n'a pas de portée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Javascript::getScope()

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getScope());

    $js = new MongoDB\BSON\Javascript('function foo() { return foo; }', ['foo' => 42]);
    var_dump($js->getScope());

    ?>

L'exemple ci-dessus va afficher :

    NULL
    object(stdClass)#1 (1) {
      ["foo"]=>
      int(42)
    }

### Voir aussi

- » Types BSON

# MongoDB\BSON\Javascript::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\Javascript::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\Javascript.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\Javascript::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::__toString — Retourne le code Javascript

### Description

final public function MongoDB\BSON\Javascript::__toString(): string

Cette méthode est un alias de: MongoDB\BSON\Javascript::getCode().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code Javascript.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Javascript::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Javascript('function foo(bar) { return bar; }'));

    ?>

L'exemple ci-dessus va afficher :

    string(33) "function foo(bar) { return bar; }"

### Voir aussi

- MongoDB\BSON\Javascript::getCode() - Retourne le code Javascript
- » Types BSON

## Sommaire

- MongoDB\BSON\Javascript::__construct — Construit un nouvel objet Javascript
- MongoDB\BSON\Javascript::getCode — Retourne le code Javascript
- MongoDB\BSON\Javascript::getScope — Retourne le document de portée de Javascript
- MongoDB\BSON\Javascript::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\Javascript::__toString — Retourne le code Javascript

# La classe MongoDB\BSON\MaxKey

(mongodb >=1.0.0)

## Introduction

Type BSON spécial qui compare la plus grande valeur possible de toutes les autres valeurs d'éléments BSON possibles.

> Note: Il s'agit d'un type interne de MongoDB utilisé pour l'indexation et la défragmentation.

## Synopsis de la classe

final class MongoDB\BSON\MaxKey implements MongoDB\BSON\MaxKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Méthodes */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.3.0 | Implémente MongoDB\BSON\MaxKeyInterface.
PECL mongodb 1.2.0 | Implémente Serializable et JsonSerializable.

# MongoDB\BSON\MaxKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MaxKey::__construct — Construit un nouveau MaxKey

### Description

final public function MongoDB\BSON\MaxKey::__construct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\MaxKey::__construct()

    <?php

    var_dump(new MongoDB\BSON\MaxKey());

    ?>

L'exemple ci-dessus va afficher :

    object(MongoDB\BSON\MaxKey)#1 (0) {
    }

### Voir aussi

- » Types BSON

# MongoDB\BSON\MaxKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\MaxKey::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\MaxKey.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

## Sommaire

- MongoDB\BSON\MaxKey::__construct — Construit un nouveau MaxKey
- MongoDB\BSON\MaxKey::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

# La classe MongoDB\BSON\MinKey

(mongodb >=1.0.0)

## Introduction

Type BSON spécial qui compare la plus petite valeur possible de toutes les autres valeurs d'éléments BSON possibles.

> Note: Il s'agit d'un type interne de MongoDB utilisé pour l'indexation et la défragmentation.

## Synopsis de la classe

final class MongoDB\BSON\MinKey implements MongoDB\BSON\MinKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Méthodes */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.3.0 | Implémente MongoDB\BSON\MinKeyInterface.
PECL mongodb 1.2.0 | Implémente Serializable et JsonSerializable.

# MongoDB\BSON\MinKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MinKey::__construct — Construit un nouveau MinKey

### Description

final public function MongoDB\BSON\MinKey::__construct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\MinKey::__construct()

    <?php

    var_dump(new MongoDB\BSON\MinKey());

    ?>

L'exemple ci-dessus va afficher :

    object(MongoDB\BSON\MinKey)#1 (0) {
    }

### Voir aussi

- » Types BSON

# MongoDB\BSON\MinKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\MinKey::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\MinKey.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

## Sommaire

- MongoDB\BSON\MinKey::__construct — Construit un nouveau MinKey
- MongoDB\BSON\MinKey::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

# La classe MongoDB\BSON\ObjectId

(mongodb >=1.0.0)

## Introduction

Type BSON pour un » ObjectId. La valeur se compose de 12 octets, où les quatre premiers octets sont un timestamp qui reflètent la création de l'ObjectId. Plus précisément, la valeur se compose de :

- une valeur de 4 octets représentant les secondes depuis l'époque UNIX,
- un nombre aléatoire de 5 octets unique à une machine et un processus, et
- un compteur de 3 octets, commençant par une valeur aléatoire.

Dans MongoDB, chaque document stocké dans une collection requiert un champ `_id` unique qui agit comme clé primaire. Si un document inséré omet le champ `_id`, l'extension génère automatiquement un ObjectId pour le champ `_id`.

L'utilisation d'ObjectId pour le champ `_id` fournit les avantages supplémentaires suivants:

- L'heure de création de l'ObjectId peut être accédée à l'aide de la méthode MongoDB\BSON\ObjectId::getTimestamp().
- Le tri sur un champ `_id` qui stocke des valeurs ObjectId équivaut à peu près au tri par date de création.

## Synopsis de la classe

final class MongoDB\BSON\ObjectId implements MongoDB\BSON\ObjectIdInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final public function __construct(?string `$id` = `null`)
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.
PECL mongodb 1.3.0 | Renommé de `MongoDB\BSON\ObjectID` vers `MongoDB\BSON\ObjectId`. Implémente MongoDB\BSON\ObjectIdInterface.
PECL mongodb 1.2.0 | Implémente Serializable et JsonSerializable.

# MongoDB\BSON\ObjectId::__construct

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__construct — Construit un nouvel ObjectId

### Description

final public function MongoDB\BSON\ObjectId::__construct(?string `$id` = `null`)

### Liste de paramètres

`id` (string)
  Une chaîne héxadécimale de 24 caractères. Si elle n'est pas fournie, l'extension génèrera un ObjectId.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une exception MongoDB\Driver\Exception\InvalidArgumentException si `id` n'est pas une chaîne héxadécimale de 24 caractères.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\ObjectId::__construct()

    <?php

    var_dump(new MongoDB\BSON\ObjectId());

    var_dump(new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "56732d3dda14d81214634921"
    }
    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "000000000000000000000001"
    }

### Voir aussi

- » La référence ObjectId
- » Le type BSON : ObjectId

# MongoDB\BSON\ObjectId::getTimestamp

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::getTimestamp — Retourne le composant d'horodatage d'ObjectId

### Description

final public function MongoDB\BSON\ObjectId::getTimestamp(): int

Le composant d'horodatage d'un ObjectId est ses 32 bits les plus significatifs, qui dénote le nombre de secondes depuis l'epoch Unix. Cette valeur est lue comme un entier 32-bit non signé avec un ordre d'octets big-endian.

> Note: Étant donné que le type entier de PHP est signé, certaines valeurs retournées par cette méthode peuvent apparaître sous forme d'entiers négatifs sur les plates-formes 32 bits. Le formateur "%u" de sprintf() peut être utilisé pour obtenir une représentation sous forme de chaîne de la valeur décimale non signée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le composant d'horodatage d'ObjectId.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\ObjectId::getTimestamp()

    <?php

    var_dump((new MongoDB\BSON\ObjectId())->getTimestamp());

    var_dump((new MongoDB\BSON\ObjectId('0000002a0000000000000000'))->getTimestamp());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    integer(1484854719)
    integer(42)

### Voir aussi

- » Référence ObjectId
- » Types BSON : ObjectId

# MongoDB\BSON\ObjectId::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\ObjectId::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\ObjectId.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\ObjectId::__toString

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__toString — Retourne la représentation hexadécimale de cet ObjectId

### Description

final public function MongoDB\BSON\ObjectId::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation hexadécimale de cet ObjectId.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\ObjectId::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\ObjectId());
    var_dump((string) new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(24) "56731b49da14d8747d701211"
    string(24) "000000000000000000000001"

### Voir aussi

- » La référence ObjectId
- » Le type BSON : ObjectId

## Sommaire

- MongoDB\BSON\ObjectId::__construct — Construit un nouvel ObjectId
- MongoDB\BSON\ObjectId::getTimestamp — Retourne le composant d'horodatage d'ObjectId
- MongoDB\BSON\ObjectId::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\ObjectId::__toString — Retourne la représentation hexadécimale de cet ObjectId

# La classe MongoDB\BSON\Regex

(mongodb >=1.0.0)

## Introduction

Type BSON pour un modèle d'expression régulière et » flags facultatif.

> Note: Ce type BSON est principalement utilisé lors de l'interrogation de la base de données. Alternativement, l'opérateur de requête » $regex peut être utilisé.

## Synopsis de la classe

final class MongoDB\BSON\Regex implements MongoDB\BSON\RegexInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final public function __construct(string `$pattern`, string `$flags` = "")
final public function getFlags(): string
final public function getPattern(): string
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.
PECL mongodb 1.3.0 | Implémente MongoDB\BSON\RegexInterface.
PECL mongodb 1.2.0 | Implémente Serializable et JsonSerializable.

# MongoDB\BSON\Regex::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__construct — Construit une nouvelle REGEX

### Description

final public function MongoDB\BSON\Regex::__construct(string `$pattern`, string `$flags` = "")

### Liste de paramètres

`pattern` (string)
  Le masque de l'expression régulière.

  > Note: Le masque ne doit pas être entouré de caractères délimitants.

`flags` (string)
  Les » drapeaux de l'expression régulière. Les caractères de cet argument seront triés par ordre alphabétique.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lève une exception MongoDB\Driver\Exception\InvalidArgumentException si `pattern` ou `flags` contient un octet nul.

### Historique

Version | Description
--- | ---
PECL mongodb 1.2.0 | L'argument `flags` est optionnel et la valeur par défaut est une chaîne vide. Les caractères dans l'argument `flags` seront triés par ordre alphabétique lorsqu'une Regex est construite. Auparavant, les caractères étaient stockés dans l'ordre fourni. MongoDB\Driver\Exception\InvalidArgumentException est levé si `pattern` ou `flags` contient un octet nul. Auparavant, les valeurs étaient tronquées au premier octet nul.

### Exemples

Exemple #1 MongoDB\BSON\Regex::__construct() example

    <?php

    $regex = new MongoDB\BSON\Regex('^foo', 'i');
    var_dump($regex);

    ?>

L'exemple ci-dessus va afficher :

    object(MongoDB\BSON\Regex)#1 (2) {
      ["pattern"]=>
      string(4) "^foo"
      ["flags"]=>
      string(1) "i"
    }

### Voir aussi

- » Les types BSON
- » Les drapeaux supportés pour les expressions régulières

# MongoDB\BSON\Regex::getFlags

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getFlags — Retourne les drapeaux de la REGEX

### Description

final public function MongoDB\BSON\Regex::getFlags(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les drapeaux de la REGEX.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec BSON\Regex::getFlags()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getFlags());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(1) "i"

### Voir aussi

- » Les types BSON
- » Les drapeaux supportés des expressions régulières

# MongoDB\BSON\Regex::getPattern

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getPattern — Retourne le masque du REGEX

### Description

final public function MongoDB\BSON\Regex::getPattern(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le masque du REGEX.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec BSON\Regex::getPattern()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getPattern());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(5) "regex"

### Voir aussi

- » Les types BSON

# MongoDB\BSON\Regex::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\Regex::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\Regex.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\Regex::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__toString — Retourne la chaîne représentant cette REGEX

### Description

final public function MongoDB\BSON\Regex::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la chaîne représentant cette REGEX.

### Exemples

Exemple #1 Exemple avec BSON\Regex::__toString()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump((string) $regex);

    ?>

L'exemple ci-dessus va afficher :

    string(8) "/regex/i"

### Voir aussi

- » Les types BSON

## Sommaire

- MongoDB\BSON\Regex::__construct — Construit une nouvelle REGEX
- MongoDB\BSON\Regex::getFlags — Retourne les drapeaux de la REGEX
- MongoDB\BSON\Regex::getPattern — Retourne le masque du REGEX
- MongoDB\BSON\Regex::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\Regex::__toString — Retourne la chaîne représentant cette REGEX

# La classe MongoDB\BSON\Timestamp

(mongodb >=1.0.0)

## Introduction

Représente un » horodatage BSON, la valeur se compose d'un horodatage de 4 octets (c.-à-d. secondes depuis l'époque) et d'une incrémentation de 4 octets.

> Note: Il s'agit d'un type MongoDB interne utilisé pour la réplication et la fragmentation. Il n'est pas prévu pour le stockage de date générale (MongoDB\BSON\UTCDateTime doit être utilisé à la place).

## Synopsis de la classe

final class MongoDB\BSON\Timestamp implements MongoDB\BSON\TimestampInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final public function __construct(int `$increment`, int `$timestamp`)
final public function getIncrement(): int
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.
PECL mongodb 1.3.0 | Implémente MongoDB\BSON\TimestampInterface.
PECL mongodb 1.2.0 | Implémente Serializable et JsonSerializable.

# MongoDB\BSON\Timestamp::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__construct — Construit un nouveau Timestamp

### Description

final public function MongoDB\BSON\Timestamp::__construct(int `$increment`, int `$timestamp`)

### Liste de paramètres

`increment` (int)
  Entier de 32-bit qui indique l'ordinal incrémentiel pour les opérations dans une seconde donnée.
`timestamp` (int)
  Entier de 32-bit indiquant des secondes depuis l'époque UNIX.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Timestamp::__construct()

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);

    ?>

L'exemple ci-dessus va afficher :

    object(MongoDB\BSON\Timestamp)#1 (2) {
      ["increment"]=>
      int(1234)
      ["timestamp"]=>
      int(5678)
    }

### Voir aussi

- » Le type BSON : Timestamps

# MongoDB\BSON\Timestamp::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getIncrement — Retourne le composant d'incrémentation de ce Timestamp

### Description

final public function MongoDB\BSON\Timestamp::getIncrement(): int

Le composant d'incrémentation d'un Timestamp est ses 32 bits les moins significatifs, qui désignent l'ordinal incrémentant pour les opérations pour une seconde donnée. Cette valeur est lue comme un entier 32-bits non signé avec un ordre d'octet big-endian.

> Note: Étant donné que le type entier de PHP est signé, certaines valeurs retournées par cette méthode peuvent apparaître sous forme d'entiers négatifs sur les plates-formes 32 bits. Le formateur "%u" de sprintf() peut être utilisé pour obtenir une représentation sous forme de chaîne de la valeur décimale non signée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le composant d'incrémentation de ce Timestamp.

Avertissement

Sur les systèmes 32 bits cette méthode peut retourner un nombre négatif. Bien que les parties d'incrémentation et d'horodatages du type BSON timestamp consiste de deux valeurs 32-bits non signé, PHP ne peut les représenter sur les plateformes 32-bit.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- » Types BSON : Timestamps

# MongoDB\BSON\Timestamp::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getTimestamp — Retourne le composant d'horodatage de Timestamp

### Description

final public function MongoDB\BSON\Timestamp::getTimestamp(): int

Le composant d'horodatage d'un Timestamp est ses 32 bits les plus significatifs, qui dénote le nombre de secondes depuis l'epoch Unix. Cette valeur est lue comme un entier 32-bit non signé avec un ordre d'octets big-endian.

> Note: Étant donné que le type entier de PHP est signé, certaines valeurs retournées par cette méthode peuvent apparaître sous forme d'entiers négatifs sur les plates-formes 32 bits. Le formateur "%u" de sprintf() peut être utilisé pour obtenir une représentation sous forme de chaîne de la valeur décimale non signée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le composant d'horodatage de Timestamp.

Avertissement

Sur les systèmes 32-bits cette méthode peut retourner un nombre négatif. Bien que les parties d'incrémentation et d'horodatage du type timestamp BSON consiste de deux valeurs 32-bits non signé, PHP ne peut pas les représenter sur les plateformes 32-bits.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- » Types BSON : Timestamps

# MongoDB\BSON\Timestamp::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\Timestamp::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\Timestamp.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\Timestamp::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__toString — Retourne la représentation sous forme de chaîne de cet horodatage

### Description

final public function MongoDB\BSON\Timestamp::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de cet horodatage.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Timestamp::__toString()

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);
    var_dump((string) $timestamp);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(11) "[1234:5678]"

### Voir aussi

- » Le type BSON : Timestamps

## Sommaire

- MongoDB\BSON\Timestamp::__construct — Construit un nouveau Timestamp
- MongoDB\BSON\Timestamp::getIncrement — Retourne le composant d'incrémentation de ce Timestamp
- MongoDB\BSON\Timestamp::getTimestamp — Retourne le composant d'horodatage de Timestamp
- MongoDB\BSON\Timestamp::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\Timestamp::__toString — Retourne la représentation sous forme de chaîne de cet horodatage

# La classe MongoDB\BSON\UTCDatetime

(mongodb >=1.0.0)

## Introduction

Représente une » date BSON. La valeur est un entier de 64 bits qui représente le nombre de millisecondes depuis l'époque UNIX (1 janvier 1970). Les valeurs négatives représentent des dates avant le 1970.

## Synopsis de la classe

final class MongoDB\BSON\UTCDateTime implements MongoDB\BSON\UTCDateTimeInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final public function __construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)
final public function jsonSerialize(): mixed
final public function MongoDB\BSON\UTCDatetime::toDateTime(): DateTime
final public function toDateTimeImmutable(): DateTimeImmutable
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.
PECL mongodb 1.3.0 | Implémente MongoDB\BSON\UTCDateTimeInterface.
PECL mongodb 1.2.0 | Implémente Serializable et JsonSerializable.

# MongoDB\BSON\UTCDateTime::__construct

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__construct — Construit un nouveau UTCDateTime

### Description

final public function MongoDB\BSON\UTCDateTime::__construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)

### Liste de paramètres

`milliseconds` (int|MongoDB\BSON\Int64|DateTimeInterface|null)
  Nombre de millisecondes depuis l'époque UNIX (1 janvier 1970). Les valeurs négatives représentent des dates avant le 1970. Cette valeur peut être fournie en tant qu'entier 64 bits. Pour la compatibilité sur les systèmes 32 bits, ce paramètre peut également être fourni comme une MongoDB\BSON\Int64. Si l'argument est un DateTimeInterface, le nombre de millisecondes depuis l'époque UNIX sera dérivé de cette valeur. Si cet argument est `null`, l'heure actuelle sera utilisée par défaut.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Le paramètre `milliseconds` n'accepte désormais plus de string ou de float.
PECL mongodb 1.20.0 | L'argument `milliseconds` accepte désormais un objet MongoDB\BSON\Int64 (pour compatibilité avec les plateformes 32 bits). Spécifier une string ou un float est déprécié.
PECL mongodb 1.2.0 | L'argument `milliseconds` est facultatif et par défaut à `null` (c'est-à-dire l'heure actuelle). L'argument accepte également un DateTimeInterface, qui peut être utilisé pour calculer le nombre de millisecondes depuis l'époque UNIX. Auparavant, seuls les types entier, nombre décimal et chaîne de caractères étaient acceptés.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\UTCDatetime::__construct()

    <?php

    var_dump(new MongoDB\BSON\UTCDateTime);

    var_dump(new MongoDB\BSON\UTCDateTime(new DateTime));

    var_dump(new MongoDB\BSON\UTCDateTime(1416445411987));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1416445411987"
    }

### Voir aussi

- » BSON Types: Date

# MongoDB\BSON\UTCDateTime::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\UTCDateTime::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\UTCDateTime.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\UTCDateTime::toDateTime

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::toDateTime — Retourne la représentation DateTime de ce UTCDateTime

### Description

final public function MongoDB\BSON\UTCDatetime::toDateTime(): DateTime

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation DateTime de ce UTCDateTime. Le DateTime retourné utilisera le fuseau horaire UTC.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\UTCDatetime::toDateTime()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTime();
    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Voir aussi

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Renvoie la représentation DateTimeImmutable de cette UTCDateTime
- » Le type BSON : Date

# MongoDB\BSON\UTCDateTime::toDateTimeImmutable

(mongodb >=1.20.0)

MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Renvoie la représentation DateTimeImmutable de cette UTCDateTime

### Description

final public function MongoDB\BSON\UTCDateTime::toDateTimeImmutable(): DateTimeImmutable

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la représentation DateTimeImmutable de cette UTCDateTime. Le DateTimeImmutable renvoyé utilisera le fuseau horaire UTC.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Exemples

Exemple #1 Exemple de MongoDB\BSON\UTCDatetime::toDateTimeImmutable()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTimeImmutable();
    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Voir aussi

- MongoDB\BSON\UTCDateTime::toDateTime() - Retourne la représentation DateTime de ce UTCDateTime
- » Types BSON : Date

# MongoDB\BSON\UTCDateTime::__toString

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__toString — Retourne la représentation sous forme de chaîne de ce UTCDateTime

### Description

final public function MongoDB\BSON\UTCDateTime::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de ce UTCDateTime.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\UTCDatetime::__toString()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    var_dump((string) $utcdatetime);

    ?>

L'exemple ci-dessus va afficher :

    string(13) "1416445411987"

### Voir aussi

- » BSON Types: Date

## Sommaire

- MongoDB\BSON\UTCDateTime::__construct — Construit un nouveau UTCDateTime
- MongoDB\BSON\UTCDateTime::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\UTCDateTime::toDateTime — Retourne la représentation DateTime de ce UTCDateTime
- MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Renvoie la représentation DateTimeImmutable de cette UTCDateTime
- MongoDB\BSON\UTCDateTime::__toString — Retourne la représentation sous forme de chaîne de ce UTCDateTime

# L'interface MongoDB\BSON\Type

(mongodb >=1.0.0)

## Introduction

Interface de base abstraite qui ne doit pas être implémentée directement.

## Sommaire de l'Interface

class MongoDB\BSON\Type {
}

Cette interface n'a pas de méthodes. Son seul but est d'être l'interface de base pour toutes les classes de type BSON.

# La classe MongoDB\BSON\Persistable

(mongodb >=1.0.0)

## Introduction

Les classes peuvent implémenter cette interface pour avoir la possibilité d'utiliser les ODM automatique (les objets de cartographie des documents) de cette extension. Pendant la sérialisation, l'extension va injecter une propriété __pclass contenant le nom de la classe PHP dans les données retournées par MongoDB\BSON\Serializable::bsonSerialize(). Pendant la désérialisation, la même propriété __pclass sera utilisée pour demander à la classe PHP (indépendamment de la configuration type map) de se construire avant que MongoDB\BSON\Unserializable::bsonUnserialize() ne soit invoquée. Voir Persister des données pour plus d'informations.

> Note: Même si MongoDB\BSON\Serializable::bsonSerialize() veut retourner un tableau séquentiel, l'injection de la propriété __pclass fera que l'objet sera sérialisé comme document BSON.

## Sommaire de l'Interface

class MongoDB\BSON\Persistable implements MongoDB\BSON\Unserializable, MongoDB\BSON\Serializable {
/* Méthodes */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document
/* Méthodes héritées */
abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void
}

# MongoDB\BSON\Persistable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Persistable::bsonSerialize — Fournit un tableau ou un document à sérialiser en tant que BSON

### Description

abstract public function MongoDB\BSON\Persistable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document

Appelée lors de la sérialisation de l'objet en BSON. La méthode doit retourner un array, stdClass, ou MongoDB\BSON\Document.

La valeur de retour sera toujours sérialisée en tant que document BSON. Le document sérialisé inclura un champ contenant le nom de la classe de l'objet. Pour cette raison, il n'est pas possible de retourner une instance de MongoDB\BSON\PackedArray dans cette méthode.

Les utilisateurs sont encouragés à inclure une propriété _id (par exemple un MongoDB\BSON\ObjectId initialisé dans le constructeur) lors du retour de données pour un document racine BSON. En l'absence d'une propriété _id, l'extension ou le serveur générera un MongoDB\BSON\ObjectId pour les opérations d'insertion ou d'upsert, respectivement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un array, stdClass, ou MongoDB\BSON\Document à sérialiser en tant que document BSON.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.17.0 | Cette méthode peut maintenant également retourner des instances de MongoDB\BSON\Document en plus de array et stdClass.

### Voir aussi

- MongoDB\BSON\Serializable::bsonSerialize() - Fournit un tableau ou un document à sérialiser en tant que BSON
- MongoDB\BSON\Unserializable::bsonUnserialize() - Construit l'objet à partir d'un tableau ou d'un document BSON
- MongoDB\BSON\Persistable
- Persister des données

## Sommaire

- MongoDB\BSON\Persistable::bsonSerialize — Fournit un tableau ou un document à sérialiser en tant que BSON

# La classe MongoDB\BSON\Serializable

(mongodb >=1.0.0)

## Introduction

Les classes qui implémentent cette interface peuvent retourner des données à sérialiser comme un tableau ou un document BSON, à la place des propriétés publiques de l'objet.

## Sommaire de l'Interface

class MongoDB\BSON\Serializable implements MongoDB\BSON\Type {
/* Méthodes */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Fournit un tableau ou un document à sérialiser en tant que BSON

### Description

abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray

Appelé pendant la sérialisation de l'objet à BSON. La méthode doit retourner un tableau, stdClass, MongoDB\BSON\Document ou MongoDB\BSON\PackedArray.

Les documents racine (par exemple, un MongoDB\BSON\Serializable passé à MongoDB\BSON\Document::fromPHP()) seront toujours sérialisés en tant que document BSON. Pour les valeurs de champ, les tableaux associatifs et les instances stdClass seront sérialisés en tant que document BSON et les tableaux séquentiels (c'est-à-dire les index numériques séquentiels commençant à `0`) seront sérialisés en tant que tableau BSON.

Les utilisateurs sont encouragés à inclure une propriété _id (par exemple un MongoDB\BSON\ObjectId initialisé dans le constructeur) lors du retour des données pour un document racine BSON. En l'absence d'une propriété _id, l'extension ou le serveur générera un MongoDB\BSON\ObjectId pour les opérations d'insertion ou de mise à jour, respectivement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

tableau, stdClass, MongoDB\BSON\Document, ou MongoDB\BSON\PackedArray à sérialiser en tant que tableau ou document BSON.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.17.0 | Le type de retour n'est plus array|object. Plutôt qu'un object, le type de retour spécifie désormais stdClass. Les classes implémentant cette interface doivent être modifiées pour ne plus utiliser le type de retour object. Le type de retour étant prévisionnel, un avertissement de dépréciation est émis en PHP 8.1 ou ultérieur si les implémentations n'utilisent pas le bon type de retour. Additionnellement aux changements ci-dessus, l'extension supporte désormais de retourner des instances de MongoDB\BSON\Document et MongoDB\BSON\PackedArray. À noter que toute instance de MongoDB\BSON\PackedArray sera silencieusement convertie en objet lorsqu'il est stocké comme document racine. Ces instances sont stockées sous forme de tableaux lorsqu'elles sont utilisées comme valeur de champ intégrée.

### Exemples

Exemple #1 MongoDB\BSON\Serializable::bsonSerialize() renvoyant un tableau associatif pour le document racine

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        private $id;

        function __construct()
        {
            $this->id = new MongoDB\BSON\ObjectId;
        }

        function bsonSerialize(): array
        {
            return ['_id' => $this->id, 'foo' => 'bar'];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyDocument)->toRelaxedExtendedJSON(), "\n";

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    { "_id" : { "$oid" : "56cccdcada14d8755a58c591" }, "foo" : "bar" }

Exemple #2 MongoDB\BSON\Serializable::bsonSerialize() renvoyant un tableau séquentiel pour le document racine

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyArray)->toRelaxedExtendedJSON(), "\n";

    ?>

L'exemple ci-dessus va afficher :

    { "0" : 1, "1" : 2, "2" : 3 }

Exemple #3 MongoDB\BSON\Serializable::bsonSerialize() renvoyant un tableau associatif pour le champ de document

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return ['foo' => 'bar'];
        }
    }

    $value = ['document' => new MyDocument];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

L'exemple ci-dessus va afficher :

    { "document" : { "foo" : "bar" } }

Exemple #4 MongoDB\BSON\Serializable::bsonSerialize() renvoyant un tableau séquentiel pour le champ de document

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    $value = ['array' => new MyArray];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

L'exemple ci-dessus va afficher :

    { "array" : [ 1, 2, 3 ] }

### Voir aussi

- MongoDB\BSON\Unserializable::bsonUnserialize() - Construit l'objet à partir d'un tableau ou d'un document BSON
- MongoDB\BSON\Persistable
- Persister des données

## Sommaire

- MongoDB\BSON\Serializable::bsonSerialize — Fournit un tableau ou un document à sérialiser en tant que BSON

# L'interface MongoDB\BSON\Unserializable

(mongodb >=1.0.0)

## Introduction

Les classes qui implémentent cette interface peuvent être spécifiées dans une carte de type pour les tableaux et les documents BSON désérialisés (à la fois racine et embarqué).

## Sommaire de l'Interface

class MongoDB\BSON\Unserializable {
/* Méthodes */
abstract public function bsonUnserialize(array `$data`): void
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\BSON\Unserializable::bsonUnserialize

(mongodb >=1.0.0)

MongoDB\BSON\Unserializable::bsonUnserialize — Construit l'objet à partir d'un tableau ou d'un document BSON

### Description

abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void

Appelé lors de la désérialisation de l'objet à partir de BSON. Les propriétés du tableau ou du document BSON seront transmises à la méthode sous la forme d'un tableau.

Il ne faut pas oublier de rechercher une propriété _id lors de la gestion des données à partir d'un document BSON.

> Note: Cette méthode agit comme le constructeur de l'objet. La méthode __construct() ne sera pas appelée après cette méthode.

### Liste de paramètres

`data` (array)
  Propriétés ayant le tableau ou le document BSON.

### Valeurs de retour

La valeur de retour de cette méthode est ignorée.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Unserializable::bsonUnserialize()

    <?php

    class MyDocument implements MongoDB\BSON\Unserializable
    {
        private $data = [];

        function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }
    }

    $bson = MongoDB\BSON\Document::fromJSON('{ "foo": "bar" }');

    var_dump($bson->toPHP(['root' => 'MyDocument']));

    ?>

L'exemple ci-dessus va afficher :

    object(MyDocument)#1 (1) {
      ["data":"MyDocument":private]=>
      array(1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Voir aussi

- MongoDB\BSON\Serializable::bsonSerialize() - Fournit un tableau ou un document à sérialiser en tant que BSON
- MongoDB\BSON\Persistable
- Persister des données

## Sommaire

- MongoDB\BSON\Unserializable::bsonUnserialize — Construit l'objet à partir d'un tableau ou d'un document BSON

# L'interface MongoDB\BSON\BinaryInterface

(mongodb >=1.3.0)

## Introduction

Cette interface est implémentée par MongoDB\BSON\Binary pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateurs.

## Synopsis de la classe

class MongoDB\BSON\BinaryInterface {
/* Méthodes */
abstract public function getData(): string
abstract public function getType(): int
abstract public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\BSON\BinaryInterface::getData

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getData — Retourne les données de BinaryInterface

### Description

abstract public function MongoDB\BSON\BinaryInterface::getData(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les données de BinaryInterface.

### Voir aussi

- MongoDB\BSON\Binary::getData() - Retourne les données de Binary

# MongoDB\BSON\BinaryInterface::getType

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getType — Retourne le type de BinaryInterface

### Description

abstract public function MongoDB\BSON\BinaryInterface::getType(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le type de BinaryInterface.

### Voir aussi

- MongoDB\BSON\Binary::getType() - Retourne le type de Binary

# MongoDB\BSON\BinaryInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::__toString — Retourne les données de BinaryInterface

### Description

abstract public function MongoDB\BSON\BinaryInterface::__toString(): string

Cette méthode est un alias de: MongoDB\BSON\BinaryInterface::getData().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les données de BinaryInterface.

### Voir aussi

- MongoDB\BSON\BinaryInterface::getData() - Retourne les données de BinaryInterface
- MongoDB\BSON\Binary::__toString() - Retourne les données de Binary

## Sommaire

- MongoDB\BSON\BinaryInterface::getData — Retourne les données de BinaryInterface
- MongoDB\BSON\BinaryInterface::getType — Retourne le type de BinaryInterface
- MongoDB\BSON\BinaryInterface::__toString — Retourne les données de BinaryInterface

# L'interface MongoDB\BSON\Decimal128Interface

(mongodb >=1.3.0)

## Introduction

Cette interface est implémentée par MongoDB\BSON\Decimal128 pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateurs.

## Synopsis de la classe

class MongoDB\BSON\Decimal128Interface {
/* Méthodes */
abstract public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\BSON\Decimal128Interface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\Decimal128Interface::__toString — Retourne une représentation sous chaîne de caractères de Decimal128Interface

### Description

abstract public function MongoDB\BSON\Decimal128Interface::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une représentation sous chaîne de caractères de Decimal128Interface.

### Voir aussi

- MongoDB\BSON\Decimal128::__toString() - Retourne la représentation sous forme de chaîne de caractères de Decimal128

## Sommaire

- MongoDB\BSON\Decimal128Interface::__toString — Retourne une représentation sous chaîne de caractères de Decimal128Interface

# L'interface MongoDB\BSON\JavascriptInterface

(mongodb >=1.3.0)

## Introduction

Cette interface est implémentée par MongoDB\BSON\Javascript pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateurs.

## Synopsis de la classe

class MongoDB\BSON\JavascriptInterface {
/* Méthodes */
abstract public function getCode(): string
abstract public function getScope(): ?object
abstract public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\BSON\JavascriptInterface::getCode

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getCode — Retourne le code de JavascriptInterface

### Description

abstract public function MongoDB\BSON\JavascriptInterface::getCode(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code de JavascriptInterface.

### Voir aussi

- MongoDB\BSON\Javascript::getCode() - Retourne le code Javascript

# MongoDB\BSON\JavascriptInterface::getScope

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getScope — Retourne le document de portée de JavascriptInterface

### Description

abstract public function MongoDB\BSON\JavascriptInterface::getScope(): ?object

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le document de portée de JavascriptInterface.

### Voir aussi

- MongoDB\BSON\Javascript::getScope() - Retourne le document de portée de Javascript

# MongoDB\BSON\JavascriptInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::__toString — Retourne le code de JavascriptInterface

### Description

abstract public function MongoDB\BSON\JavascriptInterface::__toString(): string

Cette méthode est un alias de: MongoDB\BSON\JavascriptInterface::getCode().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code de JavascriptInterface.

### Voir aussi

- MongoDB\BSON\JavascriptInterface::getCode() - Retourne le code de JavascriptInterface
- MongoDB\BSON\Javascript::__toString() - Retourne le code Javascript

## Sommaire

- MongoDB\BSON\JavascriptInterface::getCode — Retourne le code de JavascriptInterface
- MongoDB\BSON\JavascriptInterface::getScope — Retourne le document de portée de JavascriptInterface
- MongoDB\BSON\JavascriptInterface::__toString — Retourne le code de JavascriptInterface

# L'interface MongoDB\BSON\MaxKeyInterface

(mongodb >=1.3.0)

## Introduction

Cette interface est implémentée par MongoDB\BSON\MaxKey pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateurs.

## Synopsis de la classe

class MongoDB\BSON\MaxKeyInterface {
}

Cette interface ne contient pas de méthodes.

# L'interface MongoDB\BSON\MinKeyInterface

(mongodb >=1.3.0)

## Introduction

Cette interface est implémentée par MongoDB\BSON\MinKey pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateurs.

## Synopsis de la classe

class MongoDB\BSON\MinKeyInterface {
}

Cette interface ne contient pas de méthodes.

# L'interface MongoDB\BSON\ObjectIdInterface

(mongodb >=1.3.0)

## Introduction

Cette interface est implémentée par MongoDB\BSON\ObjectId pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateurs.

## Synopsis de la classe

class MongoDB\BSON\ObjectIdInterface {
/* Méthodes */
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\BSON\ObjectIdInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::getTimestamp — Retourne le composant d'horodatage d'ObjectIdInterface

### Description

abstract public function MongoDB\BSON\ObjectIdInterface::getTimestamp(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le composant d'horodatage d'ObjectIdInterface.

### Voir aussi

- MongoDB\BSON\ObjectId::getTimestamp() - Retourne le composant d'horodatage d'ObjectId

# MongoDB\BSON\ObjectIdInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::__toString — Retourne la représentation hexadécimale d'ObjectIdInterface

### Description

abstract public function MongoDB\BSON\ObjectIdInterface::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation hexadécimale d'ObjectIdInterface.

### Voir aussi

- MongoDB\BSON\ObjectId::__toString() - Retourne la représentation hexadécimale de cet ObjectId

## Sommaire

- MongoDB\BSON\ObjectIdInterface::getTimestamp — Retourne le composant d'horodatage d'ObjectIdInterface
- MongoDB\BSON\ObjectIdInterface::__toString — Retourne la représentation hexadécimale d'ObjectIdInterface

# L'interface MongoDB\BSON\RegexInterface

(mongodb >=1.3.0)

## Introduction

Cette interface est implémentée par MongoDB\BSON\Regex pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateurs.

## Synopsis de la classe

class MongoDB\BSON\RegexInterface {
/* Méthodes */
abstract public function getFlags(): string
abstract public function getPattern(): string
abstract public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\BSON\RegexInterface::getFlags

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getFlags — Retourne les drapeaux de RegexInterface

### Description

abstract public function MongoDB\BSON\RegexInterface::getFlags(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les drapeaux de RegexInterface.

### Voir aussi

- MongoDB\BSON\Regex::getFlags() - Retourne les drapeaux de la REGEX

# MongoDB\BSON\RegexInterface::getPattern

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getPattern — Retourne le masque de RegexInterface

### Description

abstract public function MongoDB\BSON\RegexInterface::getPattern(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le masque de RegexInterface.

### Voir aussi

- MongoDB\BSON\Regex::getPattern() - Retourne le masque du REGEX

# MongoDB\BSON\RegexInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::__toString — Retourne la représentation sous forme de chaîne de caractères de cette RegexInterface

### Description

abstract public function MongoDB\BSON\RegexInterface::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de caractères de cette RegexInterface.

### Voir aussi

- MongoDB\BSON\Regex::__toString() - Retourne la chaîne représentant cette REGEX

## Sommaire

- MongoDB\BSON\RegexInterface::getFlags — Retourne les drapeaux de RegexInterface
- MongoDB\BSON\RegexInterface::getPattern — Retourne le masque de RegexInterface
- MongoDB\BSON\RegexInterface::__toString — Retourne la représentation sous forme de chaîne de caractères de cette RegexInterface

# L'interface MongoDB\BSON\TimestampInterface

(mongodb >=1.3.0)

## Introduction

Cette interface est implémentée par MongoDB\BSON\Timestamp pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateurs.

## Synopsis de la classe

class MongoDB\BSON\TimestampInterface {
/* Méthodes */
abstract public function getIncrement(): int
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\BSON\TimestampInterface::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getIncrement — Retourne le composant d'incrémentation de ce TimestampInterface

### Description

abstract public function MongoDB\BSON\TimestampInterface::getIncrement(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le composant d'incrémentation de ce TimestampInterface.

Avertissement

Sur les systèmes 32 bits cette méthode peut retourner un nombre négatif. Bien que les parties d'incrémentation et d'horodatages du type BSON timestamp consiste de deux valeurs 32-bits non signé, PHP ne peut les représenter sur les plateformes 32-bit.

### Voir aussi

- MongoDB\BSON\Timestamp::getIncrement() - Retourne le composant d'incrémentation de ce Timestamp

# MongoDB\BSON\TimestampInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getTimestamp — Retourne le composant d'horodatage de TimestampInterface

### Description

abstract public function MongoDB\BSON\TimestampInterface::getTimestamp(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le composant d'horodatage de TimestampInterface.

Avertissement

Sur les systèmes 32-bits cette méthode peut retourner un nombre négatif. Bien que les parties d'incrémentation et d'horodatage du type timestamp BSON consiste de deux valeurs 32-bits non signé, PHP ne peut pas les représenter sur les plateformes 32-bits.

### Voir aussi

- MongoDB\BSON\Timestamp::getTimestamp() - Retourne le composant d'horodatage de Timestamp

# MongoDB\BSON\TimestampInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::__toString — Retourne la représentation sous forme de chaîne de caractères de TimestampInterface

### Description

abstract public function MongoDB\BSON\TimestampInterface::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de caractères de TimestampInterface.

### Voir aussi

- MongoDB\BSON\Timestamp::__toString() - Retourne la représentation sous forme de chaîne de cet horodatage

## Sommaire

- MongoDB\BSON\TimestampInterface::getIncrement — Retourne le composant d'incrémentation de ce TimestampInterface
- MongoDB\BSON\TimestampInterface::getTimestamp — Retourne le composant d'horodatage de TimestampInterface
- MongoDB\BSON\TimestampInterface::__toString — Retourne la représentation sous forme de chaîne de caractères de TimestampInterface

# L'interface MongoDB\BSON\UTCDateTimeInterface

(mongodb >=1.3.0)

## Introduction

Cette interface est implémentée par MongoDB\BSON\UTCDateTime pour être utilisée comme type de paramètre, de retour ou de propriété dans les classes utilisateurs.

## Synopsis de la classe

class MongoDB\BSON\UTCDateTimeInterface {
/* Méthodes */
abstract public function toDateTime(): DateTime
abstract public function toDateTimeImmutable(): DateTimeImmutable
abstract public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\BSON\UTCDateTimeInterface::toDateTime

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTime — Retourne la représentation DateTime d'UTCDateTimeInterface

### Description

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTime(): DateTime

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation DateTime de cette UTCDateTimeInterface. Le DateTime devrait utiliser le fuseau horaire UTC.

### Voir aussi

- MongoDB\BSON\UTCDateTime::toDateTime() - Retourne la représentation DateTime de ce UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable

(mongodb >=2.0.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Renvoie la représentation DateTimeImmutable de cette UTCDateTimeInterface

### Description

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable(): DateTimeImmutable

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la représentation DateTimeImmutable de cette UTCDateTimeInterface. La DateTimeImmutable retournée utilisera le fuseau horaire UTC.

### Voir aussi

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Renvoie la représentation DateTimeImmutable de cette UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::__toString — Retourne la représentation sous forme de chaîne de caractères d'UTCDateTimeInterface

### Description

abstract public function MongoDB\BSON\UTCDateTimeInterface::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de caractères d'UTCDateTimeInterface.

### Voir aussi

- MongoDB\BSON\UTCDateTime::__toString() - Retourne la représentation sous forme de chaîne de ce UTCDateTime

## Sommaire

- MongoDB\BSON\UTCDateTimeInterface::toDateTime — Retourne la représentation DateTime d'UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Renvoie la représentation DateTimeImmutable de cette UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::__toString — Retourne la représentation sous forme de chaîne de caractères d'UTCDateTimeInterface

# La classe MongoDB\BSON\DBPointer

(mongodb >=1.4.0)

## Introduction

Le type BSON pour le type "DBPointer". Ce type BSON est déprécié, et cette classe ne peut pas être instanciée. Elle sera créée à partir d'un type BSON DBPointer lors de la conversion BSON en PHP, et peut également être convertie en BSON lors du stockage de documents dans la base de données.

## Synopsis de la classe

final class MongoDB\BSON\DBPointer implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.

# MongoDB\BSON\DBPointer::__construct

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__construct — Construit un nouveau DBPointer (inutilisé)

### Description

final private function MongoDB\BSON\DBPointer::__construct()

Les objets MongoDB\BSON\DBPointer sont créés à travers une conversion depuis un type BSON obsolète et ne peuvent pas être construits directement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- » Types BSON

# MongoDB\BSON\DBPointer::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\DBPointer::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\DBPointer.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\DBPointer::__toString

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__toString — Retourne une chaîne vide

### Description

final public function MongoDB\BSON\DBPointer::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne vide.

### Voir aussi

- » Types BSON

## Sommaire

- MongoDB\BSON\DBPointer::__construct — Construit un nouveau DBPointer (inutilisé)
- MongoDB\BSON\DBPointer::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\DBPointer::__toString — Retourne une chaîne vide

# La classe MongoDB\BSON\Int64

(mongodb >=1.5.0)

## Introduction

Type BSON pour un entier 64 bits. Lors du décodage BSON en données PHP, cette classe est utilisée lorsqu'un entier 64 bits ne peut pas être représenté en tant qu'entier PHP sur des plateformes 32 bits. Ces objets supportent les opérateurs arithmétiques, bit à bit, et comparaison surchargés.

Lors du travail avec des données BSON brutes à travers les classes MongoDB\BSON\Document, MongoDB\BSON\PackedArray, et MongoDB\BSON\Iterator, tout entier 64 bits sera retourné en tant qu'instance de cette classe, indépendamment de la plateforme et de la possibilité de représenter la valeur en tant qu'entier PHP. Cela garantit que les valeurs peuvent être parcourues sans changer le type.

Lors de l'encodage BSON, les objets de cette classe seront convertis en un type entier 64 bits, même lorsque la valeur pourrait tenir dans un entier 32 bits. Cela permet de stocker explicitement des valeurs en tant qu'entiers 64 bits dans BSON.

## Synopsis de la classe

final class MongoDB\BSON\Int64 implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final public function __construct(int|string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.16.0 | Cette classe peut maintenant être instanciée sur toutes les plateformes. Ajout du support pour les opérateurs arithmétiques, bit à bit, et de comparaison surchargés.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.

# MongoDB\BSON\Int64::__construct

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__construct — Construit un nouveau Int64

### Description

final public function MongoDB\BSON\Int64::__construct(int|string `$value`)

Crée une nouvelle instance de MongoDB\BSON\Int64 pour la valeur entière donnée.

### Liste de paramètres

`value` (int|string)
  La valeur à assigner à l'instance de Int64. Cette valeur peut être fournie en tant que int ou string, ce dernier étant requis sur les plateformes 32 bits pour représenter les valeurs 64 bits.

### Historique

Version | Description
--- | ---
PECL mongodb 1.16.0 | Cette méthode a été rendue publique pour prendre en charge la création d'instances Int64 lors de la manipulation de BSON brut.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.
- Lance une MongoDB\Driver\Exception\InvalidArgumentException si la chaîne `value` ne peut pas être analysée en tant qu'un entier 64 bits.

### Voir aussi

- » Types BSON

# MongoDB\BSON\Int64::jsonSerialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\Int64::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\Int64.

> Note: La sortie est concordante avec la fonction MongoDB\BSON\toCanonicalExtendedJSON(), qui utilise le format JSON étendu » canonical. Ceci diffère des autres classes BSON, qui utilisent le format JSON étendu hérité du pilote spécifique (MongoDB\BSON\toJSON()), afin de s'assurer que les valeurs entières 64-bit soient correctement représentées sur les plateformes 32-bits.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\Int64::__toString

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__toString — Retourne la représentation sous forme de chaîne de caractères d'Int64

### Description

final public function MongoDB\BSON\Int64::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de caractères d'Int64.

### Exemples

Exemple #1 Exemple avec MongoDB\BSON\Int64::__toString()

    <?php

    $int64 = new MongoDB\BSON\Int64('9223372036854775807');

    var_dump((string) $int64);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(19) "9223372036854775807"

### Voir aussi

- » Types BSON

## Sommaire

- MongoDB\BSON\Int64::__construct — Construit un nouveau Int64
- MongoDB\BSON\Int64::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\Int64::__toString — Retourne la représentation sous forme de chaîne de caractères d'Int64

# La classe MongoDB\BSON\Symbol

(mongodb >=1.4.0)

## Introduction

Type BSON pour le type "Symbol". Ce type BSON est déprécié, et cette classe ne peut pas être instanciée. Elle sera créée à partir d'un type symbol BSON lors de la conversion BSON en PHP, et peut également être convertie en BSON lors du stockage de documents dans la base de données.

## Synopsis de la classe

final class MongoDB\BSON\Symbol implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.

# MongoDB\BSON\Symbol::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__construct — Construit un nouveau Symbol (inutilisé)

### Description

final private function MongoDB\BSON\Symbol::__construct()

Les objets MongoDB\BSON\Symbol sont créés à travers une conversion depuis un type BSON obsolète et ne peuvent pas être construits directement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- » Types BSON

# MongoDB\BSON\Symbol::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\Symbol::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\Symbol.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\Symbol::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__toString — Retourne la représentation sous forme de chaîne de caractères de Symbol

### Description

final public function MongoDB\BSON\Symbol::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la représentation sous forme de chaîne de caractères de Symbol.

### Voir aussi

- » Types BSON

## Sommaire

- MongoDB\BSON\Symbol::__construct — Construit un nouveau Symbol (inutilisé)
- MongoDB\BSON\Symbol::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\Symbol::__toString — Retourne la représentation sous forme de chaîne de caractères de Symbol

# La classe MongoDB\BSON\Undefined

(mongodb >=1.4.0)

## Introduction

Type BSON pour le type "Undefined". Ce type BSON est déprécié, et cette classe ne peut pas être instanciée. Elle sera créée à partir d'un type BSON undefined lors de la conversion BSON en PHP, et peut également être convertie en BSON lors du stockage de documents dans la base de données.

## Synopsis de la classe

final class MongoDB\BSON\Undefined implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Méthodes */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe n’implémente plus l'interface Serializable.
PECL mongodb 1.12.0 | Implémente Stringable pour PHP 8.0+.

# MongoDB\BSON\Undefined::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__construct — Construit un nouveau Undefined (inutilisé)

### Description

final private function MongoDB\BSON\Undefined::__construct()

Les objets MongoDB\BSON\Undefined sont créés à travers une conversion depuis un type BSON obsolète et ne peuvent pas être construits directement.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- » Types BSON

# MongoDB\BSON\Undefined::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::jsonSerialize — Retourne une représentation qui peut être convertie en JSON

### Description

final public function MongoDB\BSON\Undefined::jsonSerialize(): mixed

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne des données qui peuvent être sérialisées par json_encode() pour produire une représentation JSON étendue de MongoDB\BSON\Undefined.

> Note: La sortie est cohérente avec la fonction MongoDB\BSON\toJSON(), qui utilise le format JSON étendu spécifique au pilote. Cela ne correspond pas nécessairement aux représentations JSON étendues » décontractées ou » canoniques utilisées par MongoDB\BSON\toRelaxedExtendedJSON() et MongoDB\BSON\toCanonicalExtendedJSON(), respectivement.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- JsonSerializable::jsonSerialize() - Spécifie les données qui doivent être sérialisées en JSON
- json_encode() - Retourne la représentation JSON d'une valeur
- MongoDB\BSON\toCanonicalExtendedJSON() - Renvoie la représentation JSON étendue canonique d'une valeur BSON
- MongoDB\BSON\toRelaxedExtendedJSON() - Renvoie la représentation JSON étendue détendue d'une valeur BSON
- » MongoDB JSON Étendue

# MongoDB\BSON\Undefined::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__toString — Retourne une chaîne vide

### Description

final public function MongoDB\BSON\Undefined::__toString(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne vide.

### Voir aussi

- » Types BSON

## Sommaire

- MongoDB\BSON\Undefined::__construct — Construit un nouveau Undefined (inutilisé)
- MongoDB\BSON\Undefined::jsonSerialize — Retourne une représentation qui peut être convertie en JSON
- MongoDB\BSON\Undefined::__toString — Retourne une chaîne vide

# Classes de surveillance et fonctions abonnées

## Sommaire

- Fonctions
- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\LogSubscriber
- MongoDB\Driver\Monitoring\SDAMSubscriber
- MongoDB\Driver\Monitoring\Subscriber

# Fonctions

# MongoDB\Driver\Monitoring\addSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\addSubscriber — Enregistre un abonnement de surveillance d'événement

### Description

function MongoDB\Driver\Monitoring\addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Enregistre un abonnement de surveillance d'événement global. Les abonnés seront notifiés de tous les événements dans l'extension pour tout type de Manager.

> Note: Si `subscriber` est déjà enregistré globalement, cette fonction est un no-op. Si `subscriber` est aussi enregistré pour un ou plusieurs Managers, ils seront toujours notifiés qu'une seule fois par événement pour chaque Manager.

### Liste de paramètres

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Un objet d'abonnement de surveillance d'événement à enregistrer globalement.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\removeSubscriber() - Retire un abonnement de surveillance d'événement global
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\removeSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\removeSubscriber — Retire un abonnement de surveillance d'événement global

### Description

function MongoDB\Driver\Monitoring\removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Retire un abonnement de surveillance d'événement global.

> Note: Si `subscriber` n'est pas déjà enregistré globalement, cette fonction est un no-op.

### Liste de paramètres

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Un abonnement de surveillance d'événement à retirer globalement.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::removeSubscriber() - Enlève un observateur d'événements de surveillance de ce Manager
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

## Sommaire

- MongoDB\Driver\Monitoring\addSubscriber — Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Monitoring\removeSubscriber — Retire un abonnement de surveillance d'événement global

# La classe MongoDB\Driver\Monitoring\CommandFailedEvent

(mongodb >=1.3.0)

## Introduction

La classe MongoDB\Driver\Monitoring\CommandFailedEvent contient les informations sur une commande ayant échoué.

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\CommandFailedEvent {
/* Propriétés */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly Exception $error;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Méthodes */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Propriétés

host
  Le nom d'hôte du serveur ayant exécuté la commande.
port
  Le port du serveur ayant exécuté la commande.
commandName
  Le nom de la commande.
databaseName
  Le nom de la base de données.
duration
  La durée de la commande en microsecondes. La durée est une valeur calculée qui inclut le temps d'envoi du message et de réception de la réponse du serveur.
error
  L'exception qui a été levée lorsque la commande a échoué.
reply
  Le document de réponse d'échec retourné par le serveur.
operationId
  L'identifiant d'opération. Il peut être utilisé pour relier des évènements entre eux, comme les écritures groupées (bulk writes), qui peuvent dispatcher plusieurs commandes.
requestId
  L'identifiant de requête. Il peut être utilisé pour associer cet MongoDB\Driver\Monitoring\CommandFailedEvent avec un MongoDB\Driver\Monitoring\CommandStartedEvent correspondant.
serviceId
  L'identifiant de service, ou `null` si le serveur ne le prend pas en charge (c'est-à-dire qu'il n'utilise pas le mode équilibrage de charge).
serverConnectionId
  L'identifiant de connexion au serveur, ou `null` s'il n'est pas disponible.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly. La propriété duration remplace la méthode getDurationMicros().

# MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Renvoie le nom de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName(): string

Renvoie le nom de la commande (par exemple `"find"`, `"aggregate"`).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom de la commande.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Renvoie le nom de la base de données sur laquelle la commande a été exécutée

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la base de données sur laquelle la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Renvoie la durée de la commande en microsecondes

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros(): int

La durée de la commande est une valeur calculée qui inclut le temps pour envoyer le message et recevoir la réponse du serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la durée de la commande en microsecondes.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getError

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Renvoie l'exception associée à la commande échouée

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getError(): Exception

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'Exception associée à la commande échouée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Renvoie le nom d'hôte du serveur pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getHost(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte du serveur sur lequel la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Renvoie l'identifiant de l'opération de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId(): string

L'id de l'opération est généré par l'extension et peut être utilisé pour lier des événements ensemble tels que des opérations d'écriture en masse, qui peuvent avoir été divisées en plusieurs commandes au niveau du protocole.

> Note: Depuis que plusieurs commandes peuvent partager le même ID d'opération, il n'est pas fiable d'utiliser cette valeur pour associer des objets d'événement les uns aux autres. L'ID de requête renvoyé par MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() devrait être utilisé à la place.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de l'opération de la commande.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Renvoie l'identifiant de l'opération de la commande
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Renvoie l'identifiant de la requête de la commande
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Renvoie le port du serveur pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getPort(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port du serveur sur lequel la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getReply

(mongodb >=1.5.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Renvoie le document de réponse de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getReply(): object

Le document de réponse sera converti de BSON en PHP en utilisant les règles de désérialisation par défaut (par exemple, les documents BSON seront convertis en stdClass).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le document de réponse de la commande sous forme d'un objet stdClass.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)
- Persister des données

# MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Renvoie l'identifiant de la requête de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId(): string

L'identifiant de la requête est généré par l'extension et peut être utilisé pour associer cet MongoDB\Driver\Monitoring\CommandFailedEvent avec un MongoDB\Driver\Monitoring\CommandStartedEvent précédent.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de la requête de la commande.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Renvoie l'identifiant de la requête de la commande
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Renvoie le serveur sur lequel la commande a été exécutée

Avertissement

Cette méthode a été DÉPRÉCIÉE à partir de la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications doivent utiliser MongoDB\Driver\Monitoring\CommandFailedEvent::getHost() et MongoDB\Driver\Monitoring\CommandFailedEvent::getPort() à la place.

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServer(): MongoDB\Driver\Server

Renvoie le MongoDB\Driver\Server sur lequel la commande a été exécutée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le MongoDB\Driver\Server sur lequel la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette méthode a été supprimée.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Renvoie le serveur sur lequel la commande a été exécutée
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Renvoie l'identifiant de connexion du serveur pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId(): ?int

Renvoie l'identifiant de connexion du serveur pour la commande. L'identifiant de connexion du serveur est distinct du serveur (c'est-à-dire MongoDB\Driver\Monitoring\CommandFailedEvent::getServer()) et est renvoyé dans le champ "connectionId" d'une réponse de commande `hello` MongoDB 4.2+.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de connexion du serveur, ou `null` s'il n'est pas disponible.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Renvoie l'identifiant du service de l'équilibreur de charge pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Lorsque le pilote est connecté à un cluster MongoDB via un équilibreur de charge, l'identifiant du service correspond au champ `serviceId` dans la réponse de la commande `hello`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant du service de l'équilibreur de charge, ou `null` si le pilote n'est pas connecté à un équilibreur de charge.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Renvoie le nom de la commande
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Renvoie le nom de la base de données sur laquelle la commande a été exécutée
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Renvoie la durée de la commande en microsecondes
- MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Renvoie l'exception associée à la commande échouée
- MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Renvoie le nom d'hôte du serveur pour la commande
- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Renvoie l'identifiant de l'opération de la commande
- MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Renvoie le port du serveur pour la commande
- MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Renvoie le document de réponse de la commande
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Renvoie l'identifiant de la requête de la commande
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Renvoie le serveur sur lequel la commande a été exécutée
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Renvoie l'identifiant de connexion du serveur pour la commande
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Renvoie l'identifiant du service de l'équilibreur de charge pour la commande

# La classe MongoDB\Driver\Monitoring\CommandStartedEvent

(mongodb >=1.3.0)

## Introduction

La classe MongoDB\Driver\Monitoring\CommandStartedEvent contient les informations sur une commande ayant démarrée.

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\CommandStartedEvent {
/* Propriétés */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly object $command;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Méthodes */
final public function getCommand(): object
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Propriétés

host
  Le nom d'hôte du serveur ayant exécuté la commande.
port
  Le port du serveur ayant exécuté la commande.
commandName
  Le nom de la commande.
databaseName
  Le nom de la base de données.
command
  Le document de la commande.
operationId
  L'identifiant d'opération. Il peut être utilisé pour relier des évènements entre eux, comme les écritures groupées (bulk writes), qui peuvent dispatcher plusieurs commandes.
requestId
  L'identifiant de requête. Il peut être utilisé pour associer cet MongoDB\Driver\Monitoring\CommandStartedEvent avec un MongoDB\Driver\Monitoring\CommandSucceededEvent ou un MongoDB\Driver\Monitoring\CommandFailedEvent correspondant.
serviceId
  L'identifiant de service, ou `null` si le serveur ne le prend pas en charge (c'est-à-dire qu'il n'utilise pas le mode équilibrage de charge).
serverConnectionId
  L'identifiant de connexion au serveur, ou `null` s'il n'est pas disponible.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Renvoie le document de commande

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand(): object

Le document renvoyé sera converti de BSON en PHP en utilisant les règles de désérialisation par défaut (par exemple, les documents BSON seront convertis en stdClass).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le document de commande sous forme d'objet stdClass.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)
- Persister des données

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Renvoie le nom de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName(): string

Renvoie le nom de la commande (par exemple, `"find"`, `"aggregate"`).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom de la commande.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Renvoie la base de données sur laquelle la commande a été exécutée

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la base de données sur laquelle la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Renvoie le nom d'hôte du serveur pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getHost(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte du serveur sur lequel la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Renvoie l'identifiant de l'opération de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId(): string

L'identifiant de l'opération est généré par l'extension et peut être utilisé pour lier des événements ensemble, tels que des opérations d'écriture en masse, qui peuvent avoir été divisées en plusieurs commandes au niveau du protocole.

> Note: Depuis que plusieurs commandes peuvent partager le même identifiant d'opération, il n'est pas fiable d'utiliser cette valeur pour associer des objets d'événement les uns aux autres. L'identifiant de la requête renvoyé par MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() devrait être utilisé à la place.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de l'opération de la commande.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId() - Renvoie l'identifiant de l'opération de la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId() - Renvoie l'identifiant de l'opération de la commande
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Renvoie l'identifiant de la requête de la commande
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Renvoie le port du serveur pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getPort(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port du serveur sur lequel la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Renvoie l'identifiant de la requête de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId(): string

L'identifiant de la requête est généré par l'extension et peut être utilisé pour associer cet événement MongoDB\Driver\Monitoring\CommandStartedEvent avec un MongoDB\Driver\Monitoring\CommandFailedEvent ou MongoDB\Driver\Monitoring\CommandSucceededEvent ultérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de la requête de la commande.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Renvoie l'identifiant de la requête de la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Renvoie l'identifiant de la requête de la commande
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Renvoie le serveur sur lequel la commande a été exécutée

Avertissement

Cette méthode a été DÉPRÉCIÉE à partir de la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications doivent utiliser MongoDB\Driver\Monitoring\CommandStartedEvent::getHost() et MongoDB\Driver\Monitoring\CommandStartedEvent::getPort() à la place.

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServer(): MongoDB\Driver\Server

Renvoie le MongoDB\Driver\Server sur lequel la commande a été exécutée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le MongoDB\Driver\Server sur lequel la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette méthode a été supprimée.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer() - Renvoie le serveur sur lequel la commande a été exécutée
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer() - Renvoie le serveur sur lequel la commande a été exécutée
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Renvoie l'identifiant de connexion du serveur pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId(): ?int

Renvoie l'identifiant de connexion du serveur pour la commande. L'identifiant de connexion du serveur est distinct du serveur (c'est-à-dire MongoDB\Driver\Monitoring\CommandStartedEvent::getServer()) et est renvoyé dans le champ "connectionId" d'une réponse de commande `hello` MongoDB 4.2+.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de connexion du serveur, ou `null` s'il n'est pas disponible.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Renvoie l'identifiant du service de l'équilibreur de charge pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Lorsque le pilote est connecté à un cluster MongoDB via un équilibreur de charge, l'identifiant de service correspond au champ `serviceId` dans la réponse de la commande `hello`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant du service de l'équilibreur de charge, ou `null` si le pilote n'est pas connecté à un équilibreur de charge.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Renvoie le document de commande
- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Renvoie le nom de la commande
- MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Renvoie la base de données sur laquelle la commande a été exécutée
- MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Renvoie le nom d'hôte du serveur pour la commande
- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Renvoie l'identifiant de l'opération de la commande
- MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Renvoie le port du serveur pour la commande
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Renvoie l'identifiant de la requête de la commande
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Renvoie le serveur sur lequel la commande a été exécutée
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Renvoie l'identifiant de connexion du serveur pour la commande
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Renvoie l'identifiant du service de l'équilibreur de charge pour la commande

# La classe MongoDB\Driver\Monitoring\CommandSucceededEvent

(mongodb >=1.3.0)

## Introduction

La classe MongoDB\Driver\Monitoring\CommandSucceededEvent encapsule des informations sur une commande réussie.

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\CommandSucceededEvent {
/* Propriétés */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Méthodes */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Propriétés

host
  Le nom d'hôte du serveur ayant exécuté la commande.
port
  Le port du serveur ayant exécuté la commande.
commandName
  Le nom de la commande.
databaseName
  Le nom de la base de données.
duration
  La durée de la commande en microsecondes. La durée est une valeur calculée qui inclut le temps d'envoi du message et de réception de la réponse du serveur.
reply
  Le document de réponse retourné par le serveur.
operationId
  L'identifiant d'opération. Il peut être utilisé pour relier des évènements entre eux, comme les écritures groupées (bulk writes), qui peuvent dispatcher plusieurs commandes.
requestId
  L'identifiant de requête. Il peut être utilisé pour associer cet MongoDB\Driver\Monitoring\CommandSucceededEvent avec un MongoDB\Driver\Monitoring\CommandStartedEvent correspondant.
serviceId
  L'identifiant de service, ou `null` si le serveur ne le prend pas en charge (c'est-à-dire qu'il n'utilise pas le mode équilibrage de charge).
serverConnectionId
  L'identifiant de connexion au serveur, ou `null` s'il n'est pas disponible.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly. La propriété duration remplace la méthode getDurationMicros().

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Renvoie le nom de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName(): string

Renvoie le nom de la commande (par exemple `"find"`, `"aggregate"`).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom de la commande.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Renvoie le nom de la base de données sur laquelle la commande a été exécutée

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom de la base de données sur laquelle la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Renvoie la durée de la commande en microsecondes

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros(): int

La durée de la commande est une valeur calculée qui inclut le temps pour envoyer le message et recevoir la réponse du serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la durée de la commande en microsecondes.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Renvoie le nom d'hôte du serveur pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte du serveur sur lequel la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Renvoie l'identifiant de l'opération de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId(): string

L'identifiant de l'opération est généré par l'extension et peut être utilisé pour lier des événements ensemble tels que des opérations d'écriture en masse, qui peuvent avoir été divisées en plusieurs commandes au niveau du protocole.

> Note: Depuis que plusieurs commandes peuvent partager le même identifiant d'opération, il n'est pas fiable d'utiliser cette valeur pour associer des objets d'événement les uns aux autres. L'identifiant de la requête renvoyé par MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() devrait être utilisé à la place.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de l'opération de la commande.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Renvoie l'identifiant de l'opération de la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Renvoie l'identifiant de la requête de la commande
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Renvoie le port du serveur pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port du serveur sur lequel la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Renvoie le document de réponse de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply(): object

Le document de réponse sera converti de BSON à PHP en utilisant les règles de désérialisation par défaut (par exemple, les documents BSON seront convertis en stdClass).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le document de réponse de la commande sous forme d'un objet stdClass.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)
- Persister des données

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Renvoie l'identifiant de la requête de la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId(): string

L'identifiant de la requête est généré par l'extension et peut être utilisé pour associer cet MongoDB\Driver\Monitoring\CommandSucceededEvent avec un MongoDB\Driver\Monitoring\CommandStartedEvent précédent.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de la requête de la commande.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Renvoie l'identifiant de la requête de la commande
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Renvoie le serveur sur lequel la commande a été exécutée

Avertissement

Cette méthode a été DÉPRÉCIÉE à partir de la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Les applications doivent utiliser MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost() et MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort() à la place.

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer(): MongoDB\Driver\Server

Renvoie le MongoDB\Driver\Server sur lequel la commande a été exécutée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le MongoDB\Driver\Server sur lequel la commande a été exécutée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette méthode a été supprimée.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Renvoie le serveur sur lequel la commande a été exécutée
- MongoDB\Driver\Cursor::getServer() - Retourne le serveur associé à ce curseur
- MongoDB\Driver\WriteResult::getServer() - Retourne le serveur associé à ce résultat d'écriture
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Renvoie l'identifiant de connexion du serveur pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId(): ?int

Renvoie l'identifiant de connexion du serveur pour la commande. L'identifiant de connexion du serveur est distinct du serveur (c'est-à-dire MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer()) et est renvoyé dans le champ "connectionId" d'une réponse de commande `hello` MongoDB 4.2+.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de connexion du serveur, ou `null` s'il n'est pas disponible.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Renvoie l'identifiant du service de l'équilibreur de charge pour la commande

### Description

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Lorsque le pilote est connecté à un cluster MongoDB via un équilibreur de charge, l'identifiant du service correspond au champ `serviceId` dans la réponse de la commande `hello`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant du service de l'équilibreur de charge, ou `null` si le pilote n'est pas connecté à un équilibreur de charge.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Renvoie le nom de la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Renvoie le nom de la base de données sur laquelle la commande a été exécutée
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Renvoie la durée de la commande en microsecondes
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Renvoie le nom d'hôte du serveur pour la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Renvoie l'identifiant de l'opération de la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Renvoie le port du serveur pour la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Renvoie le document de réponse de la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Renvoie l'identifiant de la requête de la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Renvoie le serveur sur lequel la commande a été exécutée
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Renvoie l'identifiant de connexion du serveur pour la commande
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Renvoie l'identifiant du service de l'équilibreur de charge pour la commande

# La classe MongoDB\Driver\Monitoring\ServerChangedEvent

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\Monitoring\ServerChangedEvent encapsule des informations sur une description de serveur modifiée. Par exemple, le type d'un serveur passant de secondaire à primaire entraînerait un changement de la description de ce serveur.

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\ServerChangedEvent {
/* Propriétés */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\ServerDescription $newDescription;
public readonly MongoDB\Driver\ServerDescription $previousDescription;
/* Méthodes */
final public function getHost(): string
final public function getNewDescription(): MongoDB\Driver\ServerDescription
final public function getPort(): int
final public function getPreviousDescription(): MongoDB\Driver\ServerDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriétés

host
  Le nom d'hôte du serveur.
port
  Le port du serveur.
topologyId
  L'identifiant de la topologie.
newDescription
  La nouvelle description du serveur.
previousDescription
  La description antérieure du serveur.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Renvoie le nom d'hôte du serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getHost(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Renvoie la nouvelle description du serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription(): MongoDB\Driver\ServerDescription

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la nouvelle MongoDB\Driver\ServerDescription du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Renvoie le port sur lequel ce serveur écoute

### Description

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPort(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port sur lequel ce serveur écoute.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Renvoie la description précédente du serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription(): MongoDB\Driver\ServerDescription

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la MongoDB\Driver\ServerDescription précédente du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Renvoie l'ID de topologie associé à ce serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'ID de topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Renvoie le nom d'hôte du serveur
- MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Renvoie la nouvelle description du serveur
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Renvoie le port sur lequel ce serveur écoute
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Renvoie la description précédente du serveur
- MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Renvoie l'ID de topologie associé à ce serveur

# La classe MongoDB\Driver\Monitoring\ServerClosedEvent

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\Monitoring\ServerClosedEvent encapsule des informations sur un serveur fermé. Cela correspond à un serveur existant étant retiré de la topologie.

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\ServerClosedEvent {
/* Propriétés */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Méthodes */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriétés

host
  Le nom d'hôte du serveur.
port
  Le port du serveur.
topologyId
  L'identifiant de la topologie.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Renvoie le nom d'hôte du serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getHost(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Renvoie le port sur lequel ce serveur écoute

### Description

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getPort(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port sur lequel ce serveur écoute.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Renvoie l'ID de topologie associé à ce serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'ID de topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Renvoie le nom d'hôte du serveur
- MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Renvoie le port sur lequel ce serveur écoute
- MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Renvoie l'ID de topologie associé à ce serveur

# La classe MongoDB\Driver\Monitoring\ServerOpeningEvent

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\Monitoring\ServerOpeningEvent encapsule des informations sur un serveur ouvert. Cela correspond à un nouveau serveur étant ajouté à la topologie.

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\ServerOpeningEvent {
/* Propriétés */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Méthodes */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriétés

host
  Le nom d'hôte du serveur.
port
  Le port du serveur.
topologyId
  L'identifiant de la topologie.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Renvoie le nom d'hôte du serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Renvoie le port sur lequel ce serveur écoute

### Description

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port sur lequel ce serveur écoute.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Renvoie l'ID de topologie associé à ce serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'ID de topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Renvoie le nom d'hôte du serveur
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Renvoie le port sur lequel ce serveur écoute
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Renvoie l'ID de topologie associé à ce serveur

# La classe MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent encapsule des informations sur un échec de battement de cœur de serveur (c'est-à-dire » hello commande émise par le biais de » surveillance du serveur).

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent {
/* Propriétés */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly Exception $error;
/* Méthodes */
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Propriétés

host
  Le nom d'hôte du serveur.
port
  Le port du serveur.
awaited
  Indique si le battement de cœur a utilisé un protocole en flux. L'extension n'utilise pas le protocole en flux pour la surveillance, cette méthode retournera donc toujours `false`.
duration
  La durée du battement de cœur en microsecondes. La durée est une valeur calculée qui inclut le temps d'envoi du message et de réception de la réponse du serveur.
error
  L'exception qui a été levée lors de l'échec du battement de cœur.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly. La propriété duration remplace la méthode getDurationMicros().

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Renvoie la durée du signal périodique en microsecondes

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros(): int

La durée du signal périodique est une valeur calculée qui inclut le temps pour envoyer le message et recevoir la réponse du serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la durée du signal périodique en microsecondes.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Renvoie l'exception associée au signal périodique échoué

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError(): Exception

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'Exception associée au signal périodique échoué.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Renvoie le nom d'hôte du serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Renvoie le port sur lequel ce serveur écoute

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port sur lequel ce serveur écoute.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Renvoie si le signal périodique a utilisé un protocole de diffusion de flux

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited(): bool

Renvoie si le signal périodique a utilisé un protocole de diffusion de flux. L'extension n'utilise pas le protocole de diffusion de flux pour la surveillance, donc cette méthode renverra toujours `false`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `false`.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Renvoie la durée du signal périodique en microsecondes
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Renvoie l'exception associée au signal périodique échoué
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Renvoie le nom d'hôte du serveur
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Renvoie le port sur lequel ce serveur écoute
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Renvoie si le signal périodique a utilisé un protocole de diffusion de flux

# La classe MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent encapsule des informations sur un battement de cœur de serveur démarré (c'est-à-dire » commande hello émise par le biais de » la surveillance du serveur).

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent {
/* Propriétés */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
/* Méthodes */
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Propriétés

host
  Le nom d'hôte du serveur.
port
  Le port du serveur.
awaited
  Indique si le battement de cœur a utilisé un protocole en flux. L'extension n'utilise pas le protocole en flux pour la surveillance, cette méthode retournera donc toujours `false`.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Renvoie le nom d'hôte du serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Renvoie le port sur lequel ce serveur écoute

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port sur lequel ce serveur écoute.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Renvoie si le signal périodique a utilisé un protocole de diffusion de flux

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited(): bool

Renvoie si le signal périodique a utilisé un protocole de diffusion de flux. L'extension n'utilise pas le protocole de diffusion de flux pour la surveillance, donc cette méthode renverra toujours `false`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `false`.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Renvoie le nom d'hôte du serveur
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Renvoie le port sur lequel ce serveur écoute
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Renvoie si le signal périodique a utilisé un protocole de diffusion de flux

# La classe MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent encapsule des informations sur un battement de cœur de serveur réussi (c'est-à-dire » commande hello émise via » la surveillance du serveur).

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent {
/* Propriétés */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly object $reply;
/* Méthodes */
final public function getDurationMicros(): int
final public function getHost(): string
final public function getPort(): int
final public function getReply(): object
final public function isAwaited(): bool
}

## Propriétés

host
  Le nom d'hôte du serveur.
port
  Le port du serveur.
awaited
  Indique si le battement de cœur a utilisé un protocole de streaming. L'extension n'utilise pas le protocole de streaming pour la surveillance, donc cette méthode retournera toujours `false`.
duration
  La durée en microsecondes du battement de cœur. La durée est une valeur calculée qui inclut le temps d'envoi du message et de réception de la réponse depuis le serveur.
reply
  Le document de réponse retourné par le serveur.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout de propriétés publiques readonly. La propriété duration remplace la méthode getDurationMicros().

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Renvoie la durée du signal périodique en microsecondes

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros(): int

La durée du signal périodique est une valeur calculée qui inclut le temps pour envoyer le message et recevoir la réponse du serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la durée du signal périodique en microsecondes.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Renvoie le nom d'hôte du serveur

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost(): string

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le nom d'hôte du serveur.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Renvoie le port sur lequel ce serveur écoute

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort(): int

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le port sur lequel ce serveur écoute.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Renvoie le document de réponse du heartbeat

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply(): object

Le document de réponse sera converti de BSON en PHP en utilisant les règles de désérialisation par défaut (par exemple, les documents BSON seront convertis en stdClass).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le document de réponse du heartbeat sous forme d'un objet stdClass.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- Surveillance de la performance de l'application (Application Performance Monitoring - APM)
- Persister des données

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Renvoie si le signal périodique a utilisé un protocole de diffusion de flux

### Description

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited(): bool

Renvoie si le signal périodique a utilisé un protocole de diffusion de flux. L'extension n'utilise pas le protocole de diffusion de flux pour la surveillance, donc cette méthode renverra toujours `false`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `false`.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Renvoie la durée du signal périodique en microsecondes
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Renvoie le nom d'hôte du serveur
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Renvoie le port sur lequel ce serveur écoute
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Renvoie le document de réponse du heartbeat
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Renvoie si le signal périodique a utilisé un protocole de diffusion de flux

# La classe MongoDB\Driver\Monitoring\TopologyChangedEvent

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\Monitoring\TopologyChangedEvent encapsule des informations sur une description de topologie modifiée. Par exemple, la découverte d'un nouveau primaire dans un ensemble de répliques entraînerait un changement de la description de la topologie.

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\TopologyChangedEvent {
/* Propriétés */
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\TopologyDescription $newDescription;
public readonly MongoDB\Driver\TopologyDescription $previousDescription;
/* Méthodes */
final public function getNewDescription(): MongoDB\Driver\TopologyDescription
final public function getPreviousDescription(): MongoDB\Driver\TopologyDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriétés

topologyId
  L'identifiant de la topologie.
newDescription
  La nouvelle description de la topologie.
previousDescription
  La description antérieure de la topologie.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Renvoie la nouvelle description de la topologie

### Description

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription(): MongoDB\Driver\TopologyDescription

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la nouvelle MongoDB\Driver\TopologyDescription pour la topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Renvoie la description précédente de la topologie

### Description

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription(): MongoDB\Driver\TopologyDescription

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la description précédente MongoDB\Driver\TopologyDescription pour la topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Renvoie l'identifiant de la topologie

### Description

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de la topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Renvoie la nouvelle description de la topologie
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Renvoie la description précédente de la topologie
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Renvoie l'identifiant de la topologie

# La classe MongoDB\Driver\Monitoring\TopologyClosedEvent

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\Monitoring\TopologyClosedEvent encapsule des informations sur une topologie fermée.

> Note: En raison du comportement de gestion et de persistance des connexions du pilote, cet événement ne peut être observé que lorsqu'un MongoDB\Driver\Manager est créé avec l'option du pilote `"disableClientPersistence"` et libéré avant la fermeture de la requête (RSHUTDOWN).

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\TopologyClosedEvent {
/* Propriétés */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Méthodes */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriétés

topologyId
  L'identifiant de la topologie.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Renvoie l'identifiant de la topologie

### Description

final public function MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de la topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Renvoie l'identifiant de la topologie

# La classe MongoDB\Driver\Monitoring\TopologyOpeningEvent

(mongodb >=1.13.0)

## Introduction

La classe MongoDB\Driver\Monitoring\TopologyOpeningEvent encapsule des informations sur une topologie ouverte.

> Note: En raison du comportement de gestion et de persistance des connexions du pilote, cet événement peut ne pas être observé si un MongoDB\Driver\Manager utilise un client » libmongoc précédemment persistant.

## Synopsis de la classe

final class MongoDB\Driver\Monitoring\TopologyOpeningEvent {
/* Propriétés */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Méthodes */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Propriétés

topologyId
  L'identifiant de la topologie.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | Ajout des propriétés publiques readonly.

# MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Renvoie l'identifiant de la topologie

### Description

final public function MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie l'identifiant de la topologie.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

## Sommaire

- MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Renvoie l'identifiant de la topologie

# L'interface MongoDB\Driver\Monitoring\CommandSubscriber

(mongodb >=1.3.0)

## Introduction

Les classes peuvent implémenter cette interface pour enregistrer un observateur d'événements qui est notifié pour chaque événement de commande démarré, réussi et échoué. Voir Surveillance de la performance de l'application (Application Performance Monitoring - APM) pour plus d'informations.

## Sommaire de l'Interface

class MongoDB\Driver\Monitoring\CommandSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Méthodes */
abstract public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void
abstract public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void
abstract public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Méthode de notification pour une commande échouée

### Description

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void

Si l'observateur est enregistré, cette méthode est appelée lorsqu'une commande échoue.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\CommandFailedEvent)
  Un objet d'événement encapsulant des informations sur la commande échouée.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Méthode de notification pour une commande démarrée

### Description

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void

Si l'observateur est enregistré, cette méthode est appelée lorsqu'une commande est envoyée au serveur.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\CommandStartedEvent)
  Un objet d'événement encapsulant des informations sur la commande démarrée.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Méthode de notification pour une commande réussie

### Description

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void

Si l'observateur est enregistré, cette méthode est appelée lorsqu'une commande réussit.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\CommandSucceededEvent)
  Un objet d'événement encapsulant des informations sur la commande réussie.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager
- Surveillance de la performance de l'application (Application Performance Monitoring - APM)

## Sommaire

- MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Méthode de notification pour une commande échouée
- MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Méthode de notification pour une commande démarrée
- MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Méthode de notification pour une commande réussie

# L'interface MongoDB\Driver\Monitoring\LogSubscriber

(mongodb >=1.17.0)

## Introduction

Les classes implémentant cette interface peuvent être enregistrées en tant qu'observateurs et recevoir des messages de journalisation de l'extension. Cela est similaire à la journalisation de débogage basée sur des flux (c'est-à-dire mongodb.debug) sauf que les messages de journalisation de niveau trace ne sont pas reçus.

Comme avec la journalisation basée sur des flux, il est seulement possible d'enregistrer un journalisateur globalement en utilisant MongoDB\Driver\Monitoring\addSubscriber(). L'extension n'est pas capable de distinguer les messages de journalisation pour des objets MongoDB\Driver\Manager individuels.

## Sommaire de l'Interface

class MongoDB\Driver\Monitoring\LogSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Constantes */
const int LEVEL_ERROR = 0;
const int LEVEL_CRITICAL = 1;
const int LEVEL_WARNING = 2;
const int LEVEL_MESSAGE = 3;
const int LEVEL_INFO = 4;
const int LEVEL_DEBUG = 5;
/* Méthodes */
abstract public function log(int `$level`, string `$domain`, string `$message`): void
}

## Constantes pré-définies

`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_ERROR`
  Le niveau de journalisation d'erreur. Une condition d'erreur que l'extension n'est pas capable de rapporter via son API. C'est le niveau de journalisation le plus sévère de l'extension.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_CRITICAL`
  Le niveau de journalisation critique. Une condition d'erreur avec une sévérité légèrement inférieure. Cette constante existe pour la cohérence avec libmongoc; cependant, l'extension est peu susceptible de l'utiliser en pratique.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_WARNING`
  Le niveau de journalisation d'avertissement. Indique une situation où un comportement indésirable de l'application peut se produire.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_MESSAGE`
  Le niveau de journalisation de message ou de notification. Indique un événement inhabituel mais non problématique.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_INFO`
  Le niveau de journalisation d'information. Informations de haut niveau sur le comportement normal du pilote.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_DEBUG`
  Le niveau de journalisation de débogage. Informations détaillées qui peuvent être utiles lors du débogage d'une application.

# MongoDB\Driver\Monitoring\LogSubscriber::log

(mongodb >=1.17.0)

MongoDB\Driver\Monitoring\LogSubscriber::log — Méthode de notification pour un message de journal

### Description

abstract public function MongoDB\Driver\Monitoring\LogSubscriber::log(int `$level`, string `$domain`, string `$message`): void

Si l'observateur est enregistré, cette méthode est appelée pour chaque message de journal enregistré.

### Liste de paramètres

`level`
  Le niveau de gravité. Ce sera l'une des constantes d'interface.
`domain`
  Le nom du composant du pilote qui a émis le message de journal.
`message`
  Le message de journal.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement

## Sommaire

- MongoDB\Driver\Monitoring\LogSubscriber::log — Méthode de notification pour un message de journal

# L'interface MongoDB\Driver\Monitoring\SDAMSubscriber

(mongodb >=1.13.0)

## Introduction

Les classes peuvent implémenter cette interface pour enregistrer un observateur d'événements qui est notifié pour divers événements SDAM. Voir les spécifications » Découverte et surveillance de serveur et » Surveillance de SDAM pour plus d'informations.

## Sommaire de l'Interface

class MongoDB\Driver\Monitoring\SDAMSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Méthodes */
abstract public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void
abstract public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void
abstract public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void
abstract public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void
abstract public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void
abstract public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void
abstract public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void
abstract public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void
abstract public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void
}

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Les types de retour précédemment déclarés comme provisoires sont désormais appliqués.
PECL mongodb 1.15.0 | Les types de retours des méthodes sont déclarés comme provisoires en PHP 8.0 et ultérieur, ce qui déclenche des avis de dépréciation dans le code qui implémente cette interface sans déclarer les types de retours appropriés. L'attribut `#[ReturnTypeWillChange]` peut être ajouté pour ignorer la notice de dépréciation.

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Méthode de notification pour un changement de description de serveur

### Description

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void

Si un observateur est enregistré, cette méthode est appelée lorsqu'une description de serveur change. Par exemple, le type d'un serveur passant de secondaire à primaire entraînerait un changement de la description de ce serveur.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\ServerChangedEvent)
  Un objet d'événement encapsulant des informations sur la description de serveur modifiée.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Méthode de notification pour la fermeture d'un serveur

### Description

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void

Si un observateur est enregistré, cette méthode est appelée lorsqu'un serveur existant est retiré de la topologie.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\ServerClosedEvent)
  Un objet d'événement encapsulant des informations sur le serveur fermé.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Méthode de notification pour un échec de battement de cœur de serveur

### Description

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void

Si un observateur est enregistré, cette méthode est appelée lorsqu'un battement de cœur de serveur (c'est-à-dire une commande » hello émise par le biais de » surveillance de serveur) échoue.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent)
  Un objet d'événement encapsulant des informations sur l'échec de battement de cœur de serveur.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Méthode de notification pour un battement de cœur de serveur démarré

### Description

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void

Si un observateur est enregistré, cette méthode est appelée lorsqu'un battement de cœur de serveur (c'est-à-dire une commande » hello émise par le biais de » surveillance de serveur) est envoyé au serveur.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent)
  Un objet d'événement encapsulant des informations sur le battement de cœur de serveur démarré.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Méthode de notification pour un battement de cœur de serveur réussi

### Description

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void

Si un observateur est enregistré, cette méthode est appelée lorsqu'un battement de cœur de serveur (c'est-à-dire une commande » hello émise par le biais de » surveillance de serveur) réussit.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent)
  Un objet d'événement encapsulant des informations sur le battement de cœur de serveur réussi.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Méthode de notification pour l'ouverture d'un serveur

### Description

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void

Si un observateur est enregistré, cette méthode est appelée lorsqu'un nouveau serveur est ajouté à la topologie.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\ServerOpeningEvent)
  Un objet d'événement encapsulant des informations sur le serveur ouvert.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Méthode de notification pour un changement de description de topologie

### Description

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void

Si un observateur est enregistré, cette méthode est appelée lorsqu'une description de topologie change. Par exemple, la découverte d'un nouveau primaire dans un ensemble de répliques entraînerait un changement de la description de la topologie.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\TopologyChangedEvent)
  Un objet d'événement encapsulant des informations sur la description de topologie modifiée.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Méthode de notification pour la fermeture de topologie

### Description

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void

Si un observateur est enregistré, cette méthode est appelée lorsqu'une topologie est fermée.

> Note: En raison du comportement du pilote de gestion et de persistance des connexions, cet événement ne peut être observé que lorsqu'un MongoDB\Driver\Manager est créé avec l'option du pilote `"disableClientPersistence"` et libéré avant la fermeture de la requête (RSHUTDOWN).

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\TopologyClosedEvent)
  Un objet d'événement encapsulant des informations sur la topologie fermée.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Méthode de notification pour l'ouverture de topologie

### Description

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void

Si un observateur est enregistré, cette méthode est appelée lorsqu'une topologie est ouverte.

> Note: En raison du comportement du pilote de gestion et de persistance des connexions, cet événement peut ne pas être observé si un MongoDB\Driver\Manager utilise un client » libmongoc précédemment persistant.

### Liste de paramètres

`event` (MongoDB\Driver\Monitoring\TopologyOpeningEvent)
  Un objet d'événement encapsulant des informations sur la topologie ouverte.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

- Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

### Voir aussi

- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Enregistre un abonnement de surveillance d'événement
- MongoDB\Driver\Manager::addSubscriber() - Enregistre un observateur d'événements de surveillance avec ce manager

## Sommaire

- MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Méthode de notification pour un changement de description de serveur
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Méthode de notification pour la fermeture d'un serveur
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Méthode de notification pour un échec de battement de cœur de serveur
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Méthode de notification pour un battement de cœur de serveur démarré
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Méthode de notification pour un battement de cœur de serveur réussi
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Méthode de notification pour l'ouverture d'un serveur
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Méthode de notification pour un changement de description de topologie
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Méthode de notification pour la fermeture de topologie
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Méthode de notification pour l'ouverture de topologie

# L'interface MongoDB\Driver\Monitoring\Subscriber

(mongodb >=1.3.0)

## Introduction

L'interface de base pour les observateurs d'événements. Elle est utilisée comme type de paramètre dans les fonctions MongoDB\Driver\Monitoring\addSubscriber() et MongoDB\Driver\Monitoring\removeSubscriber() et ne doit pas être implémentée directement.

## Sommaire de l'Interface

class MongoDB\Driver\Monitoring\Subscriber {
}

Cette interface n'a pas de méthodes. Son seul but est d'être l'interface de base pour tous les observateurs d'événements.

# Les classes d'exception

## Sommaire

- MongoDB\Driver\Exception\AuthenticationException
- MongoDB\Driver\Exception\BulkWriteException
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\Exception\CommandException
- MongoDB\Driver\Exception\ConnectionException
- MongoDB\Driver\Exception\ConnectionTimeoutException
- MongoDB\Driver\Exception\EncryptionException
- MongoDB\Driver\Exception\Exception
- MongoDB\Driver\Exception\ExecutionTimeoutException
- MongoDB\Driver\Exception\InvalidArgumentException
- MongoDB\Driver\Exception\LogicException
- MongoDB\Driver\Exception\RuntimeException
- MongoDB\Driver\Exception\ServerException
- MongoDB\Driver\Exception\SSLConnectionException
- MongoDB\Driver\Exception\UnexpectedValueException
- MongoDB\Driver\Exception\WriteException
- Arbre de classes

# La classe MongoDB\Driver\Exception\AuthenticationException

(mongodb >= 1.0.0)

## Introduction

Levée lorsque le pilote ne parvient pas à s'authentifier auprès du serveur.

## Synopsis de la classe

class MongoDB\Driver\Exception\AuthenticationException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe MongoDB\Driver\Exception\BulkWriteException

(mongodb >= 1.0.0)

## Introduction

Levée lorsqu'une opération d'écriture en bloc échoue.

## Synopsis de la classe

class MongoDB\Driver\Exception\BulkWriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriétés */
public readonly MongoDB\Driver\WriteResult $writeResult;
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriétés

writeResult
  Le MongoDB\Driver\WriteResult associé à l'opération d'écriture échouée.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | La propriété writeResult est désormais public readonly.
PECL mongodb 2.0.0 | Cette classe étend désormais MongoDB\Driver\Exception\ServerException au lieu de MongoDB\Driver\Exception\WriteException.

# MongoDB\Driver\Exception\BulkWriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Renvoie le WriteResult pour l'opération d'écriture échouée

### Description

final public function MongoDB\Driver\Exception\BulkWriteException::getWriteResult(): MongoDB\Driver\WriteResult

Renvoie le MongoDB\Driver\WriteResult pour l'opération d'écriture échouée. Les méthodes MongoDB\Driver\WriteResult::getWriteErrors() et MongoDB\Driver\WriteResult::getWriteConcernError() peuvent être utilisées pour obtenir des détails supplémentaires sur l'erreur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le MongoDB\Driver\WriteResult pour l'opération d'écriture échouée.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\Exception\BulkWriteException::getWriteResult()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Voir aussi

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Exécute une ou plusieurs opérations d'écriture

## Sommaire

- MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Renvoie le WriteResult pour l'opération d'écriture échouée

# La classe MongoDB\Driver\Exception\BulkWriteCommandException

(mongodb >=2.1.0)

## Introduction

Exception lancée lors de l'exécution échouée d'une MongoDB\Driver\BulkWriteCommand. Les méthodes de la classe apportent plus de détails sur les erreurs qui se sont produites, incluant les erreurs de réponse et les résultats partiels de l'écriture en masse.

## Synopsis de la classe

class MongoDB\Driver\Exception\BulkWriteCommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriétés */
private ?MongoDB\BSON\Document $errorReply;
private ?MongoDB\Driver\BulkWriteCommandResult $partialResult;
private array $writeConcernErrors;
private array $writeErrors;
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
final public function getErrorReply(): ?MongoDB\BSON\Document
final public function getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult
final public function getWriteConcernErrors(): array
final public function getWriteErrors(): array
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriétés

errorReply
  Chacune des erreurs du plus haut niveau qui ont eu lieu lors de l'essai de la communication avec le serveur ou de l'exécution de l'écriture en masse. Cette valeur peut être `null` si l'exception a été lancée à cause d'erreurs survenant lors d'écritures individuelles.
partialResult
  Une MongoDB\Driver\BulkWriteCommandResult apporte le résultat de toutes les opérations qui ont été effectuées avant l'erreur. Cette valeur peut être `null` s'il ne peut pas être déterminé qu'au moins une écriture a été effectuée avec succès (et reconnue).
writeConcernErrors
  Un tableau de chacun des MongoDB\Driver\WriteConcernErrors qui se sont produits lors de l'exécution de l'écriture en masse. Cette liste peut avoir plusieurs entrées si plus d'une commande serveur a été requise pour exécuter l'écriture en masse.
writeErrors
  Un tableau de chacun des MongoDB\Driver\WriteErrors qui se sont produits lors de l'exécution de l'écriture individuelle. Les clés de tableau correspondent à l'index de l'opération d'écriture de MongoDB\Driver\BulkWriteCommand. Cette liste va contenir au plus une entrée si l'écriture en masse était ordonnée.

# MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Renvoie une erreur de commande de niveau supérieur

### Description

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply(): ?MongoDB\BSON\Document

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une erreur de commande de niveau supérieur qui s'est produite lors de l'essai de communication avec le serveur ou d'exécution de l'écriture en masse. Cette valeur peut être `null` si l'exception a été lancée en raison d'erreurs survenant sur des écritures individuelles.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply()

    <?php

    $manager = new MongoDB\Driver\Manager;

    // Cet exemple utilise configureFailPoint pour simuler une erreur de commande de niveau supérieur
    $manager->executeCommand('admin', new MongoDB\Driver\Command([
        'configureFailPoint' => 'failCommand',
        'mode' => ['times' => 1],
        'data' => [
            'failCommands' => ['bulkWrite'],
            'errorCode' => 8, /* UnknownError */
        ],
    ]));

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getErrorReply()?->toPHP());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)#12 (6) {
      ["ok"]=>
      float(0)
      ["errmsg"]=>
      string(43) "Failing command via 'failCommand' failpoint"
      ["code"]=>
      int(8)
      ["codeName"]=>
      string(12) "UnknownError"
      ["$clusterTime"]=>
      object(stdClass)#10 (2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#6 (2) {
          ["increment"]=>
          string(1) "7"
          ["timestamp"]=>
          string(10) "1744319389"
        }
        ["signature"]=>
        object(stdClass)#9 (2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#7 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          object(MongoDB\BSON\Int64)#8 (1) {
            ["integer"]=>
            string(1) "0"
          }
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#11 (2) {
        ["increment"]=>
        string(1) "7"
        ["timestamp"]=>
        string(10) "1744319389"
      }
    }

### Voir aussi

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite

# MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Renvoie le résultat de toutes les opérations d'écriture réussies

### Description

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un MongoDB\Driver\BulkWriteCommandResult apportant les résultats de chacune des opérations réussies qui ont été faites avant que l'erreur ne soit rencontrée. La valeur retournée sera `null` si on ne peut pas déterminer si au moins une écriture a été effectuée avec succès (et reconnue).

### Exemples

Exemple #1 Résultat partiel si au moins une écriture est réussie

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

L'exemple ci-dessus va afficher :

    int(1)

Exemple #2 Aucun résultat partiel si aucune écriture n'est réussie

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $manager->executeBulkWriteCommand($bulk);

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

L'exemple ci-dessus va afficher :

    NULL

### Voir aussi

- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Renvoie les erreurs de write concern

### Description

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de chacun des MongoDB\Driver\WriteConcernErrors qui se sont produits lors de l'exécution de l'écriture en masse. Cette liste peut avoir plusieurs entrées si plus d'une commande de serveur était nécessaire pour exécuter l'écriture en masse.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(50);

    try {
        $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteConcernErrors());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteConcernError)#6 (3) {
        ["message"]=>
        string(29) "Not enough data-bearing nodes"
        ["code"]=>
        int(100)
        ["info"]=>
        object(stdClass)#8 (1) {
          ["writeConcern"]=>
          object(stdClass)#7 (3) {
            ["w"]=>
            int(50)
            ["wtimeout"]=>
            int(0)
            ["provenance"]=>
            string(14) "clientSupplied"
          }
        }
      }
    }

### Voir aussi

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Renvoie les erreurs d'écriture

### Description

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors(): array

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de MongoDB\Driver\WriteErrors qui se sont produits lors de l'exécution de l'écriture individuelle. Les clés de tableau correspondent à l'index de l'opération d'écriture dans MongoDB\Driver\BulkWriteCommand. Cette liste contiendra au plus une entrée si l'écriture en masse était ordonnée.

### Exemples

Exemple #1 Exemple de MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteErrors());
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(2) {
      [2]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
      [3]=>
      object(MongoDB\Driver\WriteError)#7 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#8 (0) {
        }
      }
    }

### Voir aussi

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Exécute les opérations d'écriture en utilisant la commande bulkWrite
- MongoDB\Driver\WriteError

## Sommaire

- MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Renvoie une erreur de commande de niveau supérieur
- MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Renvoie le résultat de toutes les opérations d'écriture réussies
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Renvoie les erreurs de write concern
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Renvoie les erreurs d'écriture

# La classe MongoDB\Driver\Exception\CommandException

(mongodb >= 1.5.0)

## Introduction

Lancée lorsqu'une commande échoue.

## Synopsis de la classe

class MongoDB\Driver\Exception\CommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriétés */
public readonly object $resultDocument;
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
final public function getResultDocument(): object
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriétés

resultDocument
  Le document résultant associé à la commande échouée.

## Historique

Version | Description
--- | ---
PECL mongodb 2.3.0 | La propriété resultDocument est désormais public readonly.

# MongoDB\Driver\Exception\CommandException::getResultDocument

(mongodb >= 1.5.0)

MongoDB\Driver\Exception\CommandException::getResultDocument — Retourne le document résultant pour la commande échouée

### Description

final public function MongoDB\Driver\Exception\CommandException::getResultDocument(): object

Retourne le document résultant pour la commande échouée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le document résultant pour la commande échouée.

### Voir aussi

- MongoDB\Driver\Manager::executeCommand() - Exécute une commande de base de données

## Sommaire

- MongoDB\Driver\Exception\CommandException::getResultDocument — Retourne le document résultant pour la commande échouée

# La classe MongoDB\Driver\Exception\ConnectionException

(mongodb >= 1.0.0)

## Introduction

Classe de base pour les exceptions levées lorsque le pilote ne parvient pas à établir une connexion de base de données.

## Synopsis de la classe

class MongoDB\Driver\Exception\ConnectionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe MongoDB\Driver\Exception\ConnectionTimeoutException

(mongodb >= 1.0.0)

## Introduction

Lancée lorsque le pilote échoue à établir une connexion à la base de données dans un délai spécifié (connectTimeoutMS) ou lorsque la sélection du serveur échoue (serverSelectionTimeoutMS).

## Synopsis de la classe

final class MongoDB\Driver\Exception\ConnectionTimeoutException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe MongoDB\Driver\Exception\EncryptionException

(mongodb >= 1.7.0)

## Introduction

La classe de base pour les exceptions lancées lors du chiffrement côté client.

## Synopsis de la classe

class MongoDB\Driver\Exception\EncryptionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# L'interface MongoDB\Driver\Exception\Exception

(mongodb >= 1.0.0)

## Introduction

Interface commune pour toutes les exceptions de l'extension. Cette interface est également utilisée par la bibliothèque, et peut être utilisée pour identifier toute exception provenant du pilote PHP de MongoDB (c'est-à-dire l'extension et la bibliothèque).

## Synopsis de la classe

class MongoDB\Driver\Exception\Exception {
}

# La classe MongoDB\Driver\Exception\ExecutionTimeoutException

(mongodb >= 1.0.0)

## Introduction

Lancée lorsqu'une requête ou une commande échoue à se terminer dans un délai spécifié (par exemple » maxTimeMS).

## Synopsis de la classe

final class MongoDB\Driver\Exception\ExecutionTimeoutException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Historique

Version | Description
--- | ---
PECL mongodb 1.5.0 | Cette classe étend maintenant MongoDB\Driver\Exception\ServerException à la place de MongoDB\Driver\Exception\RuntimeException.

# La classe MongoDB\Driver\Exception\InvalidArgumentException

(mongodb >= 1.0.0)

## Introduction

Levée lorsqu'une méthode de pilote reçoit des arguments non valides (par exemple, des types d'options non valides).

## Synopsis de la classe

class MongoDB\Driver\Exception\InvalidArgumentException extends InvalidArgumentException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe MongoDB\Driver\Exception\LogicException

(mongodb >= 1.0.0)

## Introduction

Lancée lorsque le pilote est incorrectement utilisé (par exemple, rembobiner un curseur).

## Synopsis de la classe

class MongoDB\Driver\Exception\LogicException extends LogicException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe MongoDB\Driver\Exception\RuntimeException

(mongodb >= 1.0.0)

## Introduction

Levée lorsque le pilote rencontre une erreur d'exécution (par exemple, erreur interne de » libmongoc).

## Synopsis de la classe

class MongoDB\Driver\Exception\RuntimeException extends RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propriétés */
protected ?array $errorLabels;
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
final public function hasErrorLabel(string `$errorLabel`): bool
/* Méthodes héritées */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriétés

errorLabels
  Contient un tableau d'étiquettes d'erreur à parcourir avec une exception. Par exemple, les étiquettes d'erreur peuvent être utilisées pour détecter si une transaction peut être réessayée en toute sécurité si l'étiquette `TransientTransactionError` est présente. L'existence d'une étiquette d'erreur spécifique doit être testée avec MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(), au lieu d'interpréter manuellement la propriété `errorLabels`.

## Historique

Version | Description
--- | ---
PECL mongodb 1.6.0 | La méthode MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() et la propriété MongoDB\Driver\Exception\RuntimeException::errorLabels ont été ajoutées.

# MongoDB\Driver\Exception\RuntimeException::hasErrorLabel

(mongodb >= 1.6.0)

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Retourne si un label d'erreur est associé avec une exception

### Description

final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool

Retourne si le `errorLabel` a été défini pour cette exception. Les labels d'erreurs sont définis soit par le serveur soit par l'extension pour indiquer des situations spécifiques où on voudrait décider comment on gèrera une exception spécifique. Une situation commune serait de déterminer si l'on peut relancer une transaction qui a échoué à cause d'une erreur passagère (telle qu'une erreur de réseau, ou un conflit de transaction) sans encombre. Des exemples de labels d'erreurs sont `TransientTransactionError` et `UnknownTransactionCommitResult`.

### Liste de paramètres

`errorLabel`
  Le nom de l'`errorLabel` à vérifier.

### Valeurs de retour

Si le `errorLabel` fourni est associé avec cette exception.

### Voir aussi

- MongoDB\Driver\Session::commitTransaction() - Valide la transaction
- » Documentation MongoDB sur les transactions

## Sommaire

- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Retourne si un label d'erreur est associé avec une exception

# La classe MongoDB\Driver\Exception\ServerException

(mongodb >= 1.5.0)

## Introduction

La classe de base pour les exceptions lancées par le serveur. Le code de cette exception et de ses sous-classes correspondra au code d'erreur d'origine du serveur.

## Synopsis de la classe

class MongoDB\Driver\Exception\ServerException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe MongoDB\Driver\Exception\SSLConnectionException

(mongodb >= 1.0.0)

Avertissement

Cette classe d'exception est DÉPRÉCIÉE depuis la version 1.5.0 de l'extension et a été supprimée dans la version 2.0. Cette exception n'a jamais été lancée par l'extension. Les applications devraient utiliser MongoDB\Driver\Exception\ConnectionException à la place.

## Introduction

Levée lorsque le pilote ne parvient pas à établir une connexion SSL avec le serveur.

## Synopsis de la classe

final class MongoDB\Driver\Exception\SSLConnectionException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe MongoDB\Driver\Exception\UnexpectedValueException

(mongodb >= 1.0.0)

## Introduction

Lancée lorsque le pilote rencontre une valeur inattendue (par exemple lors de la sérialisation ou de la désérialisation BSON).

## Synopsis de la classe

class MongoDB\Driver\Exception\UnexpectedValueException extends UnexpectedValueException implements MongoDB\Driver\Exception\Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe MongoDB\Driver\Exception\WriteException

(mongodb >= 1.0.0)

Avertissement

Cette classe d'exception est DÉPRÉCIÉE depuis la version 1.20.0 de l'extension et a été supprimée dans la version 2.0. Cette exception n'a jamais été directement lancée par l'extension. Les applications devraient utiliser MongoDB\Driver\Exception\BulkWriteException à la place.

## Introduction

Classe de base pour les exceptions levées par une opération d'écriture défaillante. L'exception encapsule un objet MongoDB\Driver\WriteResult .

## Synopsis de la classe

abstract class MongoDB\Driver\Exception\WriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Propriétés */
protected MongoDB\Driver\WriteResult $writeResult;
/* Propriétés héritées */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Méthodes héritées */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriétés

writeResult
  MongoDB\Driver\WriteResult associé à l'opération d'écriture défaillante.

## Historique

Version | Description
--- | ---
PECL mongodb 2.0.0 | Cette classe a été supprimée.
PECL mongodb 1.20.0 | Cette classe a été dépréciée et sera supprimée dans la version 2.0.
PECL mongodb 1.5.0 | Cette classe étend maintenant MongoDB\Driver\Exception\ServerException à la place de MongoDB\Driver\Exception\RuntimeException.

# MongoDB\Driver\Exception\WriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\WriteException::getWriteResult — Retourne le WriteResult pour l'opération d'écriture qui a échoué

### Description

final public function MongoDB\Driver\Exception\WriteException::getWriteResult(): MongoDB\Driver\WriteResult

Retourne le MongoDB\Driver\WriteResult pour l'opération d'écriture qui a échoué. Les méthodes MongoDB\Driver\WriteResult::getWriteErrors() et MongoDB\Driver\WriteResult::getWriteConcernError() peuvent être utilisées pour récupérer plus de détails à propos de l'échec.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le MongoDB\Driver\WriteResult pour l'opération d'écriture qui a échoué.

### Exemples

Exemple #1 Exemple avec MongoDB\Driver\Exception\WriteException::getWriteResult()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\WriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Voir aussi

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Exécute une ou plusieurs opérations d'écriture

## Sommaire

- MongoDB\Driver\Exception\WriteException::getWriteResult — Retourne le WriteResult pour l'opération d'écriture qui a échoué

# L'arbre des exceptions MongoDB

La hiérarchie de classes pour les exceptions MongoDB est modélisée d'après celle des Exceptions SPL. Les classes de base étendent leur homologue SPL et toutes les classes d'exception de l'extension implémentent l'interface MongoDB\Driver\Exception\Exception.

- MongoDB\Driver\Exception\LogicException (extends LogicException)
- MongoDB\Driver\Exception\InvalidArgumentException (extends InvalidArgumentException)
- MongoDB\Driver\Exception\UnexpectedValueException (extends UnexpectedValueException)
- MongoDB\Driver\Exception\RuntimeException (extends RuntimeException)
  - MongoDB\Driver\Exception\ConnectionException
    - MongoDB\Driver\Exception\AuthenticationException
    - MongoDB\Driver\Exception\ConnectionTimeoutException
    - MongoDB\Driver\Exception\SSLConnectionException (dépréciée)
  - MongoDB\Driver\Exception\EncryptionException
  - MongoDB\Driver\Exception\ServerException
    - MongoDB\Driver\Exception\BulkWriteCommandException
    - MongoDB\Driver\Exception\CommandException
    - MongoDB\Driver\Exception\ExecutionTimeoutException
    - MongoDB\Driver\Exception\WriteException (dépréciée)
      - MongoDB\Driver\Exception\BulkWriteException

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Tutoriels
  - Utiliser la bibliothèque PHP pour MongoDB (PHPLIB)
  - Surveillance de la performance de l'application (Application Performance Monitoring - APM)
- Architecture et fonctionnalités spéciales — Explications de l'architecture du pilote et des fonctionnalités spéciales
  - Architecture — Aperçu de l'architecture
  - Connections — Gestion de la connexion et de la persistance
  - Persister des données — Sérialisation et désérialisation des variables PHP dans MongoDB
- Sécurité
  - Attaques par injection de requêtes
  - Attaque par injection de scripts
- MongoDB\Driver — Classes de l'extension MongoDB
  - MongoDB\Driver\Manager — La classe MongoDB\Driver\Manager
  - MongoDB\Driver\Command — La classe MongoDB\Driver\Command
  - MongoDB\Driver\Query — La classe MongoDB\Driver\Query
  - MongoDB\Driver\BulkWrite — La classe MongoDB\Driver\BulkWrite
  - MongoDB\Driver\BulkWriteCommand — La classe MongoDB\Driver\BulkWriteCommand
  - MongoDB\Driver\Session — La classe MongoDB\Driver\Session
  - MongoDB\Driver\ClientEncryption — La classe MongoDB\Driver\ClientEncryption
  - MongoDB\Driver\ServerApi — La classe MongoDB\Driver\ServerApi
  - MongoDB\Driver\WriteConcern — La classe MongoDB\Driver\WriteConcern
  - MongoDB\Driver\ReadPreference — La classe MongoDB\Driver\ReadPreference
  - MongoDB\Driver\ReadConcern — La classe MongoDB\Driver\ReadConcern
  - MongoDB\Driver\Cursor — La classe MongoDB\Driver\Cursor
  - MongoDB\Driver\CursorId — La classe MongoDB\Driver\CursorId
  - MongoDB\Driver\CursorInterface — L'interface MongoDB\Driver\CursorInterface
  - MongoDB\Driver\Server — La classe MongoDB\Driver\Server
  - MongoDB\Driver\ServerDescription — La classe MongoDB\Driver\ServerDescription
  - MongoDB\Driver\TopologyDescription — La classe MongoDB\Driver\TopologyDescription
  - MongoDB\Driver\WriteConcernError — La classe MongoDB\Driver\WriteConcernError
  - MongoDB\Driver\WriteError — La classe MongoDB\Driver\WriteError
  - MongoDB\Driver\WriteResult — La classe MongoDB\Driver\WriteResult
  - MongoDB\Driver\BulkWriteCommandResult — La classe MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON — Classes et fonctions BSON de MongoDB
  - Fonctions
  - MongoDB\BSON\Document — La classe MongoDB\BSON\Document
  - MongoDB\BSON\PackedArray — La classe MongoDB\BSON\PackedArray
  - MongoDB\BSON\Iterator — La classe MongoDB\BSON\Iterator
  - MongoDB\BSON\Binary — La classe MongoDB\BSON\Binary
  - MongoDB\BSON\VectorType — L'énumération MongoDB\BSON\VectorType
  - MongoDB\BSON\Decimal128 — La classe MongoDB\BSON\Decimal128
  - MongoDB\BSON\Javascript — La classe MongoDB\BSON\Javascript
  - MongoDB\BSON\MaxKey — La classe MongoDB\BSON\MaxKey
  - MongoDB\BSON\MinKey — La classe MongoDB\BSON\MinKey
  - MongoDB\BSON\ObjectId — La classe MongoDB\BSON\ObjectId
  - MongoDB\BSON\Regex — La classe MongoDB\BSON\Regex
  - MongoDB\BSON\Timestamp — La classe MongoDB\BSON\Timestamp
  - MongoDB\BSON\UTCDatetime — La classe MongoDB\BSON\UTCDatetime
  - MongoDB\BSON\Type — L'interface MongoDB\BSON\Type
  - MongoDB\BSON\Persistable — La classe MongoDB\BSON\Persistable
  - MongoDB\BSON\Serializable — La classe MongoDB\BSON\Serializable
  - MongoDB\BSON\Unserializable — L'interface MongoDB\BSON\Unserializable
  - MongoDB\BSON\BinaryInterface — L'interface MongoDB\BSON\BinaryInterface
  - MongoDB\BSON\Decimal128Interface — L'interface MongoDB\BSON\Decimal128Interface
  - MongoDB\BSON\JavascriptInterface — L'interface MongoDB\BSON\JavascriptInterface
  - MongoDB\BSON\MaxKeyInterface — L'interface MongoDB\BSON\MaxKeyInterface
  - MongoDB\BSON\MinKeyInterface — L'interface MongoDB\BSON\MinKeyInterface
  - MongoDB\BSON\ObjectIdInterface — L'interface MongoDB\BSON\ObjectIdInterface
  - MongoDB\BSON\RegexInterface — L'interface MongoDB\BSON\RegexInterface
  - MongoDB\BSON\TimestampInterface — L'interface MongoDB\BSON\TimestampInterface
  - MongoDB\BSON\UTCDateTimeInterface — L'interface MongoDB\BSON\UTCDateTimeInterface
  - MongoDB\BSON\DBPointer — La classe MongoDB\BSON\DBPointer
  - MongoDB\BSON\Int64 — La classe MongoDB\BSON\Int64
  - MongoDB\BSON\Symbol — La classe MongoDB\BSON\Symbol
  - MongoDB\BSON\Undefined — La classe MongoDB\BSON\Undefined
- MongoDB\Driver\Monitoring — Classes de surveillance et fonctions abonnées
  - Fonctions
  - MongoDB\Driver\Monitoring\CommandFailedEvent — La classe MongoDB\Driver\Monitoring\CommandFailedEvent
  - MongoDB\Driver\Monitoring\CommandStartedEvent — La classe MongoDB\Driver\Monitoring\CommandStartedEvent
  - MongoDB\Driver\Monitoring\CommandSucceededEvent — La classe MongoDB\Driver\Monitoring\CommandSucceededEvent
  - MongoDB\Driver\Monitoring\ServerChangedEvent — La classe MongoDB\Driver\Monitoring\ServerChangedEvent
  - MongoDB\Driver\Monitoring\ServerClosedEvent — La classe MongoDB\Driver\Monitoring\ServerClosedEvent
  - MongoDB\Driver\Monitoring\ServerOpeningEvent — La classe MongoDB\Driver\Monitoring\ServerOpeningEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent — La classe MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent — La classe MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent — La classe MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  - MongoDB\Driver\Monitoring\TopologyChangedEvent — La classe MongoDB\Driver\Monitoring\TopologyChangedEvent
  - MongoDB\Driver\Monitoring\TopologyClosedEvent — La classe MongoDB\Driver\Monitoring\TopologyClosedEvent
  - MongoDB\Driver\Monitoring\TopologyOpeningEvent — La classe MongoDB\Driver\Monitoring\TopologyOpeningEvent
  - MongoDB\Driver\Monitoring\CommandSubscriber — L'interface MongoDB\Driver\Monitoring\CommandSubscriber
  - MongoDB\Driver\Monitoring\LogSubscriber — L'interface MongoDB\Driver\Monitoring\LogSubscriber
  - MongoDB\Driver\Monitoring\SDAMSubscriber — L'interface MongoDB\Driver\Monitoring\SDAMSubscriber
  - MongoDB\Driver\Monitoring\Subscriber — L'interface MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Exception — Les classes d'exception
  - MongoDB\Driver\Exception\AuthenticationException — La classe MongoDB\Driver\Exception\AuthenticationException
  - MongoDB\Driver\Exception\BulkWriteException — La classe MongoDB\Driver\Exception\BulkWriteException
  - MongoDB\Driver\Exception\BulkWriteCommandException — La classe MongoDB\Driver\Exception\BulkWriteCommandException
  - MongoDB\Driver\Exception\CommandException — La classe MongoDB\Driver\Exception\CommandException
  - MongoDB\Driver\Exception\ConnectionException — La classe MongoDB\Driver\Exception\ConnectionException
  - MongoDB\Driver\Exception\ConnectionTimeoutException — La classe MongoDB\Driver\Exception\ConnectionTimeoutException
  - MongoDB\Driver\Exception\EncryptionException — La classe MongoDB\Driver\Exception\EncryptionException
  - MongoDB\Driver\Exception\Exception — L'interface MongoDB\Driver\Exception\Exception
  - MongoDB\Driver\Exception\ExecutionTimeoutException — La classe MongoDB\Driver\Exception\ExecutionTimeoutException
  - MongoDB\Driver\Exception\InvalidArgumentException — La classe MongoDB\Driver\Exception\InvalidArgumentException
  - MongoDB\Driver\Exception\LogicException — La classe MongoDB\Driver\Exception\LogicException
  - MongoDB\Driver\Exception\RuntimeException — La classe MongoDB\Driver\Exception\RuntimeException
  - MongoDB\Driver\Exception\ServerException — La classe MongoDB\Driver\Exception\ServerException
  - MongoDB\Driver\Exception\SSLConnectionException — La classe MongoDB\Driver\Exception\SSLConnectionException
  - MongoDB\Driver\Exception\UnexpectedValueException — La classe MongoDB\Driver\Exception\UnexpectedValueException
  - MongoDB\Driver\Exception\WriteException — La classe MongoDB\Driver\Exception\WriteException
  - Arbre de classes — L'arbre des exceptions MongoDB

# Plugins et drivers MySQL

PHP offre plusieurs drivers et plugins MySQL pour accéder et gérer MySQL.

Les différences et les fonctionnalités des extensions MySQL sont décrites dans le résumé de cette section.

Les extensions listées prennent en charge le protocole MySQL. Des exemples de serveurs de bases de données compatibles sont » MariaDB Server, » MySQL Server, » Percona Server pour MySQL, et » TiDB.

# Aperçu des drivers PHP MySQL

# Introduction

Il y a plusieurs APIs PHP pour accéder à une base de données MySQL. Les utilisateurs peuvent choisir entre les extensions mysqli ou PDO_MySQL.

Ce guide explique la terminologie utilisée pour décrire chacune d'elles, fournit des informations quant aux choix de l'API à utiliser, ainsi que des informations permettant d'aider à choisir la bibliothèque MySQL à utiliser avec l'API.

# Aperçu de la terminologie

Cette section fournit une introduction aux options qui sont disponibles lors du développement d'une application PHP qui doit interagir avec une base de données MySQL.

Qu'est-ce qu'une API ?

Une interface de programmation d'application, ou API, définit les classes, les méthodes, les fonctions et les variables dont l'application a besoin pour réaliser les tâches désirées. Dans le cas des applications PHP qui ont besoin de communiquer avec des bases de données, les APIs nécessaires sont habituellement exposées via des extensions PHP.

Les APIs peuvent être procédurales ou orientées objet. Avec une API procédurale, on appelle des fonctions pour réaliser les tâches, avec une API orientée objet, on instancie les classes, puis l'on appelle les méthodes sur les objets résultants. La seconde interface est généralement préférée car elle est plus moderne et permet de mieux organiser le code source.

Lors de l'écriture d'applications PHP qui ont besoin de se connecter à un serveur MySQL, il y a plusieurs options de l'API disponibles. Ce document va aborder ce qui est disponible, et comment choisir la meilleure solution pour l'application.

Qu'est-ce qu'un connecteur ?

Dans la documentation MySQL, le terme connecteur se réfère à la partie du programme qui autorise l'application à se connecter au serveur de base de données MySQL. MySQL fournit des connecteurs pour bon nombre de langages, incluant PHP.

Si l'application PHP a besoin de communiquer avec un serveur de base de données, il faut écrire le code PHP pour effectuer des tâches comme se connecter au serveur de base de données, requêter la base de données ainsi que d'autres tâches relatives à la base de données. Le programme est requis pour fournir l'API à utiliser par l'application PHP, mais aussi pour gérer la communication entre l'application et le serveur de base de données, en utilisant des bibliothèques intermédiaires au besoin. Ce programme est généralement appelé connecteur, vu qu'il autorise l'application à se connecter au serveur de base de données.

Qu'est-ce qu'un driver ?

Un driver est une partie de programme dont le but est de communiquer avec un type spécifique de serveur de base de données. Le driver peut également appeler une bibliothèque, comme la bibliothèque cliente MySQL ou le driver natif MySQL. Ces bibliothèques implémentent le protocole bas niveau utilisé pour communiquer avec le serveur de base de données MySQL.

Par le biais d'un exemple, la couche d'abstraction de base de données PHP Data Objects (PDO) peut utiliser un des drivers spécifiques aux bases de données. Un des drivers disponibles est le driver PDO MYSQL, qui fournit une interface avec le serveur MySQL.

Quelques fois, des personnes utilisent les termes connecteur et driver à l'envers, ce qui peut porter à confusion. Dans la documentation MySQL, le terme driver est réservé au programme qui fournit la partie spécifique à la base de données d'un connecteur.

Qu'est-ce qu'une extension ?

Dans la documentation PHP, on trouvera un autre terme - extension. Le code PHP est constitué d'un cœur, avec des extensions optionnelles permettant d'étendre les fonctionnalités du cœur. Les extensions PHP relatives aux bases de données, comme l'extension `mysqli`, sont implémentées en utilisant le framework des extensions PHP.

Typiquement, une extension expose une API au programmeur PHP, lui permettant quelques facilités lors de la programmation. Cependant, quelques extensions qui utilisent le framework d'extension PHP n'exposent aucune API au programmeur PHP.

L'extension driver PDO MySQL, par exemple, n'expose aucune API au programmeur PHP, mais fournit une interface à la couche PDO.

Les termes API et extension ne doivent pas être vus comme signifiant la même chose, car une extension n'expose pas forcément une API au programmeur.

# Choisir une API

PHP offre des APIs différentes pour se connecter à MySQL. Ci-dessous, l'on trouvera les APIs fournies par les extensions mysqli et PDO. Chaque exemple de code crée une connexion à un serveur MySQL s'exécutant sur le domaine "example.com", en utilisant le nom d'utilisateur "user", le mot de passe "password". Et une requête est exécutée pour saluer l'utilisateur.

Exemple #1 Comparaison des APIs MySQL

    <?php
    // mysqli
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT 'Bonjour, cher utilisateur de MySQL !' AS _message FROM DUAL");
    $row = $result->fetch_assoc();
    echo htmlentities($row['_message']);

    // PDO
    $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
    $statement = $pdo->query("SELECT 'Bonjour, cher utilisateur de MySQL !' AS _message FROM DUAL");
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['_message']);

Exemple #2 Comparaison des instructions préparées

    <?php
    // mysqli
    $mysqli = new mysqli("example.com", "utilisateur", "motdepasse", "base de données");
    $statement = $mysqli->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $result = $statement->get_result();
    $row = $result->fetch_assoc();
    echo htmlentities($row['District']);

    // PDO
    $pdo = new PDO('mysql:host=example.com;dbname=base de données', 'utilisateur', 'motdepasse');
    $statement = $pdo->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['District']);

Comparaison des fonctionnalités

La performance globale des deux extensions peut être considérée comme identique. Malgré tout, la performance de l'extension constitue seulement une fraction du temps total d'exécution d'une requête web PHP. Souvent, l'impact est inférieur à 0.1%.

| ext/mysqli | PDO_MySQL
--- | --- | ---
Introduite en PHP version | 5.0 | 5.1
Inclus avec PHP 7.x et 8.x | Oui | Oui
Statut du développement | Active | Active
Cycle de vie | Active | Active
Recommandé pour de nouveaux projets | Oui | Oui
Interface orientée objet | Oui | Oui
Interface procédurale | Oui | Non
L'API supporte les requêtes non-bloquantes, asynchrones avec mysqlnd | Oui | Non
Connexions persistantes disponibles | Oui | Oui
L'API supporte les jeux de caractères | Oui | Oui
L'API supporte les requêtes préparées côté serveur | Oui | Oui
L'API supporte les requêtes préparées côté client | Non | Oui
L'API supporte les procédures stockées | Oui | Oui
L'API supporte les requêtes multiples | Oui | La plupart
L'API supporte les transactions | Oui | Oui
Les transactions peuvent être contrôlées avec SQL | Oui | Oui
Supporte toutes les fonctionnalités de MySQL 5.1+ | Oui | La plupart

# Choisir une bibliothèque

Les extensions PHP mysqli et PDO_MySQL sont des enveloppes légères d'une bibliothèque cliente C. Les extensions peuvent soit utiliser la bibliothèque mysqlnd, soit la bibliothèque `libmysqlclient`. Le choix de la bibliothèque se fait au moment de la compilation.

La bibliothèque mysqlnd fait partie de la distribution de PHP. Elle offre des fonctionnalités comme les connexions paresseuses, la mise en cache de requêtes, qui ne sont pas disponibles avec libmysqlclient, aussi, il est recommandé d'utiliser la bibliothèque interne mysqlnd. Voir la documentation de mysqlnd pour plus d'informations, ainsi qu'une liste des fonctionnalités qu'elle offre.

Exemple #1 Commande de configuration pour l'utilisation de mysqlnd ou de libmysqlclient

    // Recommandé, compilation avec mysqlnd
    $ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd

    // Alternativement recommandé, compilation avec mysqlnd
    $ ./configure --with-mysqli --with-pdo-mysql

    // Non recommandé, compilation avec libmysqlclient
    $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config

Comparaison des fonctionnalités des bibliothèques

Il est recommandé d'utiliser la bibliothèque mysqlnd au lieu de la bibliothèque client serveur MySQL (libmysqlclient). Les deux bibliothèques sont supportées et améliorées en permanence.

| Driver natif MySQL (mysqlnd) | Bibliothèque client serveur MySQL (`libmysqlclient`)
--- | --- | ---
Fait partie de la distribution de PHP | Oui | Non
Introduit en version de PHP | 5.3.0 | N/A
Licence | PHP Licence 3.01 | Double-licence
Statut de développement | Actif | Actif
Cycle de vie | Pas de fin annoncée | Pas de fin annoncée
Compilé par défaut (pour toutes les extensions MySQL) | Oui | Non
Support du protocole de compression | Oui | Oui
Support de SSL | Oui | Oui
Support des pipes nommés | Oui | Oui
Requêtes non bloquantes, asynchrones | Oui | Non
Statistiques sur les performances | Oui | Non
LOAD LOCAL INFILE respecte la directive open_basedir | Oui | Non
Utilisation du système de gestion de la mémoire native de PHP (c.-à-d., suit les limites mémoires de PHP) | Oui | Non
Retourne les colonnes numériques sous la forme de double (COM_QUERY) | Oui | Non
Retourne les colonnes numériques sous la forme de chaînes de caractères (COM_QUERY) | Oui | Oui
API du plugin | Oui | Limité
Reconnexion automatique | Non | Optionnel

# Concepts

## Sommaire

- Requêtes mises ou non en mémoire tampon
- Jeux de caractères

Ces concepts sont spécifiques aux drivers MySQL pour PHP.

## Requêtes mises ou non en mémoire tampon

Les requêtes utilisent par défaut le mode Mémoire tampon. Cela signifie que le résultat des requêtes est immédiatement transféré du serveur MySQL à PHP et est ensuite conservé dans la mémoire du processus PHP. Cela permet des opérations complémentaires comme compter le nombre de résultats, et déplacer le pointeur de résultat actuel. Il permet également d'exécuter des requêtes supplémentaires sur la même connexion tout en travaillant sur le jeu de résultats. L'inconvénient de la mise en mémoire tampon est que des jeux de résultats importants peuvent demander beaucoup plus de mémoire. La mémoire restera occupée jusqu'à ce que toutes les références sur les jeux de résultats soient désactivées ou que les jeux de résultats soient explicitement libérés, ce qui arrive de manière automatique à la fin du processus. La terminologie "store result" est également utilisée avec le mode mémoire tampon, vu que la totalité des résultats est stockée en une seule fois.

> Note: Lorsqu'on utilise libmysqlclient comme bibliothèque, la limite mémoire de PHP ne comptera pas la mémoire utilisée pour les jeux de résultats à moins que les données ne soient lues dans les variables PHP. Avec mysqlnd, la mémoire utilisée comprendra le jeu de résultats complet.

Les requêtes n'utilisant pas la mémoire tampon, les requêtes MySQL exécutent leur requête et puis attendent que les données du serveur MySQL soient récupérées. Cela utilise moins de mémoire côté PHP, mais peut augmenter la charge sur le serveur. À moins que le jeu de résultats complet ait été récupéré depuis le serveur, aucune autre requête ne peut être envoyée sur la même connexion. Les requêtes n'utilisant pas la mémoire tampon peuvent également faire référence à un "use result". Une fois que toutes les lignes de l'ensemble de résultats ont été récupérées, l'ensemble de résultats disparaît et il n'est plus possible de le parcourir à nouveau.

Suivant ces caractéristiques, les requêtes non mises en mémoire tampon doivent être utilisées uniquement lorsqu'on s'attend à obtenir un grand ensemble de résultats qui sera traité séquentiellement. Les requêtes non mises en mémoire tampon présentent plusieurs pièges qui les rendent plus difficiles à utiliser, par exemple le nombre de lignes dans l'ensemble de résultats n'est pas connu avant que la dernière ligne ne soit récupérée.

En raison du fait que les requêtes sont mises en mémoire tampon par défaut, les exemples ci-dessous vont montrer comment exécuter des requêtes, avec chaque API, sans mise en mémoire tampon.

Exemple #1 Exemple de requêtes n'utilisant pas la mémoire tampon : mysqli

    <?php
    $mysqli  = new mysqli("localhost", "my_user", "my_password", "world");
    $unbufferedResult = $mysqli->query("SELECT Name FROM City", MYSQLI_USE_RESULT);

    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

Exemple #2 Exemple de requêtes n'utilisant pas la mémoire tampon : pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
    $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

    $unbufferedResult = $pdo->query("SELECT Name FROM City");
    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

## Jeux de caractères

Idéalement, un jeu de caractères propre doit être défini au niveau du serveur, opération décrite dans la section » Configuration du jeu de caractères du manuel MySQL Server. Alternativement, chaque API MySQL offre une méthode pour définir le jeu de caractères lors de l'exécution.

Attention

# Le jeu de caractères et l'échappement des caractères

Le jeu de caractères doit être compris et défini, sachant qu'il a un effet sur chaque action, et a des implications au niveau de la sécurité. Par exemple, le mécanisme d'échappement (c.-à-d. mysqli_real_escape_string() pour mysqli, et PDO::quote() pour PDO_MySQL) va utiliser cette configuration. Il est important de garder en tête que ces fonctions n'utiliseront pas le jeu de caractères défini avec une requête, aussi, l'exemple suivant n'aura aucun effet sur le jeu de caractères :

Exemple #1 Problèmes lors de la définition du jeu de caractères avec SQL

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    // N'affectera PAS $mysqli->real_escape_string();
    $mysqli->query("SET NAMES utf8mb4");

    // N'affectera PAS $mysqli->real_escape_string();
    $mysqli->query("SET CHARACTER SET utf8mb4");

    // Mais, ceci affectera $mysqli->real_escape_string();
    $mysqli->set_charset('utf8mb4');

    // Mais, ceci NE l'affectera PAS (UTF-8 par rapport à utf8mb4) -- ne pas utiliser les tirets ici
    $mysqli->set_charset('UTF-8');
    ?>

Ci-dessous les exemples qui démontrent la façon de modifier proprement le jeu de caractères lors de l'exécution en utilisant chacune des APIs.

> Note: Confusion possible avec UTF-8
> Dû au fait que les noms des jeux de caractères dans MySQL ne contiennent pas de tiret, la chaîne "utf8" est correcte dans MySQL et définira le jeu de caractères en UTF-8. La chaîne "UTF-8" n'est pas correcte, et utiliser "utf-8" échouera à modifier le jeu de caractères.

Exemple #2 Exemple de définition du jeu de caractères : mysqli

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    echo 'Jeu de caractères initial : ' . $mysqli->character_set_name() . "\n";

    if (!$mysqli->set_charset('utf8mb4')) {
        printf("Erreur lors du chargement du jeu de caractères utf8mb4 : %s\n", $mysqli->error);
        exit;
    }

    echo 'Votre jeu de caractères actuel est : ' . $mysqli->character_set_name() . "\n";
    ?>

Exemple #3 Exemple de définition du jeu de caractères : pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world;charset=utf8mb4", 'my_user', 'my_pass');
    ?>

- Aperçu de la terminologie
- Choisir une API
- Choisir une bibliothèque
- Concepts
  - Requêtes mises ou non en mémoire tampon
  - Jeux de caractères

# Extension mysqli

# Introduction

L'extension `mysqli` permet d'accéder aux fonctionnalités fournies par MySQL 4.1 et supérieur. Pour plus d'informations sur le serveur de base de données MySQL, se rendre sur » http://www.mysql.com/

Une liste des logiciels disponibles permettant d'utiliser MySQL à partir de PHP peut être trouvée sur Introduction

La documentation MySQL est disponible sur » http://dev.mysql.com/doc/.

Des morceaux du manuel MySQL ont été inclus dans la documentation PHP avec la permission d'Oracle Corporation.

Les exemples utilisent soit la base de données » world, soit la base de données » sakila, qui sont libres d'accès.

# Introduction

Cette section fournit des informations sur les solutions qui sont disponibles quand on développe une application PHP qui a besoin de s'interfacer avec une base de données MySQL.

Qu'est-ce qu'une API?

Une Interface de programmation d'application, une `Application Programming Interface`, ou encore API, définit les classes, méthodes, fonctions et variables dont une application va faire usage pour exécuter différentes tâches. Dans le cas des applications PHP, les communications avec une base de données se font généralement par une API qui est exposée dans une extension PHP.

Les API peuvent être procédurales ou orientées objet. Avec une API procédurale, il est possible d'appeler les fonctions pour exécuter des commandes; avec une API orientée objet, il faut créer des objets et appeler les méthodes de ces objets. Des deux, c'est la dernière qui est généralement préférée, car elle est plus moderne et conduit à du code plus organisé.

Lors de l'écriture d'applications PHP qui doivent se connecter à MySQL, il y a plusieurs API disponibles. Ce document présente ces API, et donne les informations pour choisir la meilleure solution pour l'application.

Qu'est-ce qu'un connecteur?

Dans la documentation MySQL, le terme connector fait référence à un logiciel qui permet à une application de se connecter à une base de données MySQL. MySQL fournit des connecteurs pour toute une collection de langages, y compris PHP.

Si l'application PHP a besoin de communiquer avec un serveur de base de données, il faut écrire du code pour pouvoir se connecter, envoyer des requêtes au serveur, etc. Un logiciel est nécessaire pour assurer l'interface que PHP va utiliser et gérer les communications entre l'application et le serveur de base de données : éventuellement, des bibliothèques intermédiaires sont nécessaires. Ces logiciels sont appelés de manière générique des connecteurs, car ils permettent de se connecter à un serveur de base de données.

Qu'est-ce qu'un pilote ?

Un pilote est un logiciel qui est conçu pour communiquer avec un type particulier de base de données. Un pilote peut aussi être appelé une bibliothèque, telle que la `MySQL Client Library` ou le MySQL Native Driver. Ces bibliothèques implémentent le protocole de bas niveau pour communiquer avec un serveur MySQL.

Par exemple, la couche d'abstraction de base de données PHP Data Objects (PDO) utilise un ou plusieurs pilotes de base de données. Un de ces pilotes est le pilote PDO MYSQL, qui permet de faire l'interface avec MySQL.

Parfois, les développeurs utilisent les termes de connecteur et de pilote de manière interchangeable, et cela peut être confus. Dans les documentations MySQL, le terme de pilote est réservé aux logiciels qui sont la face spécifique avec la base de données du paquet.

Qu'est-ce qu'une extension?

Dans la documentation PHP, on rencontrera un autre terme : extension. Le code PHP est constitué d'un cœur, avec des extensions optionnelles. Les extensions liées à MySQL de PHP, telles que l'extension `mysqli` et l'extension de pilote PDO MySQL, sont implémentées en utilisant le framework d'extension PHP.

Une extension expose typiquement une API à un développeur PHP, pour lui permettre de faciliter sa programmation. Cependant, certaines extensions qui utilisent le framework PHP n'exposent pas d'API au développeur PHP.

L'extension de pilote PDO MySQL, par exemple, n'expose pas d'API au développeur PHP, mais fournit une interface à la couche PDO.

Les termes API et extension ne devraient pas signifier la même chose, car une extension PHP ne fournit pas d'API particulière au développeur PHP.

Quelles sont les API PHP pour MySQL ?

Il y a deux API principales pour se connecter à MySQL :

- L'extension mysqli

- PHP Data Objects (PDO)

Chacune a ses avantages et ses inconvénients. Les sections suivantes tendent à donner une présentation rapide de chaque API.

Qu'est-ce que l'extension mysqli de PHP ?

L'extension `mysqli`, ou, comme elle est parfois appelée, l'extension MySQL améliorée (i pour `improved` en anglais), a été développée pour tirer parti des nouvelles fonctionnalités des systèmes MySQL version 4.1.3 et plus récent. L'extension `mysqli` est incluse dans PHP depuis les versions 5.

L'extension `mysqli` a un grand nombre d'avantages et d'améliorations par rapport à l'extension `mysql` :

- Interface orientée objet

- Support des commandes préparées

- Support des commandes multiples

- Support des transactions

- Capacités de débogage avancées

En plus d'une interface orientée objet, l'extension propose aussi une interface procédurale.

L'extension `mysqli` est compilée avec le framework PHP, et son code source est rangé dans le dossier ext/mysqli.

Pour plus d'informations sur l'extension `mysqli`, voir MySQLi.

Qu'est-ce que l'extension PDO de PHP ?

`PHP Data Objects`, ou PDO, est une couche d'abstraction de base de données, spécifique à PHP. PDO propose une API cohérente pour les applications PHP, indépendamment du type de base de données avec laquelle on travaille. En théorie, lors de l'utilisation de PDO, il est possible de changer de base de données, disons de Firebird à MySQL, et ne faire que des changements mineurs au code PHP.

D'autres exemples de couches d'abstraction de base de données incluent JDBC pour Java et DBI pour Perl.

Si PDO a ses avantages, comme une API propre, simple et portable, ses inconvénients principaux sont qu'elle ne permet pas d'utiliser toutes les fonctionnalités avancées des dernières versions de MySQL. Par exemple, PDO ne permet pas de faire des requêtes multiples.

PDO est implémenté en utilisant le framework PHP, et son code source est rangé dans le dossier ext/pdo.

Pour plus d'informations sur PDO, voir PDO.

Qu'est-ce que le pilote MySQL pour PDO ?

Le pilote PDO MYSQL n'est pas une API en tant que tel, au moins du point de vue du développeur PHP. En fait, le pilote PDO MYSQL fait partie de PDO, et fournit les fonctionnalités particulières à MySQL. Le développeur appelle l'API PDO, mais PDO utilise le pilote PDO MYSQL pour assurer les communications avec MySQL.

Le pilote PDO MYSQL fait partie de la grande famille des pilotes PDO. Les autres pilotes disponibles assurent les communications avec Firebird et PostgreSQL, entre autres.

Le pilote PDO MYSQL est implémenté avec le framework d'extension de PHP. Son code source est situé dans le dossier ext/pdo_mysql. Il n'expose aucune API au développeur PHP.

Pour plus de détails sur le pilote PDO de MySQL, voir Pilote PDO MySQL.

Qu'est-ce que le pilote natif MySQL de PHP ?

Pour communiquer avec le serveur MySQL, l'extension `mysqli` et le pilote PDO MYSQL utilisent tous une bibliothèque bas niveau qui implémente le protocole MySQL. Par le passé, la seule bibliothèque disponible était la `MySQL Client Library`, aussi appelée `libmysqlclient`.

Cependant, l'interface présentée par `libmysqlclient` n'était pas optimisée pour les communications avec PHP, et `libmysqlclient` était conçue à l'origine en C, pour des applications de même type. Pour cette raison, le pilote MySQL natif `mysqlnd` a été développé comme une alternative à `libmysqlclient` pour les applications PHP.

L'extension `mysqli` et le pilote MySQL natif peuvent tous deux être configurés individuellement pour utiliser soit `libmysqlclient` soit `mysqlnd`. Comme `mysqlnd` a été conçu spécifiquement pour utiliser le système PHP, il propose de nombreux avantages et améliorations par rapport à `libmysqlclient`. On est vivement encouragés à en profiter.

Le MySQL Native Driver est implémenté sur la base du framework d'extension PHP. Le code source est dans ext/mysqlnd. Il n'expose aucune nouvelle API au développeur PHP.

Comparaison des fonctionnalités

La table suivante compare les fonctionnalités des méthodes principales pour se connecter à MySQL depuis PHP :

Comparaison des options MySQL API pour PHP
| Extension mysqli | PDO (avec le pilote PDO MySQL Driver et MySQL Native Driver)
--- | --- | ---
Version d'introduction en PHP | 5.0 | 5.0
Statut de développement MySQL | Développement actif | Développement actif
L'API supporte les jeux de caractères | Oui | Oui
L'API supporte les commandes préparées côté serveur | Oui | Oui
L'API supporte les commandes préparées côté client | Non | Oui
L'API supporte les procédures stockées | Oui | Oui
L'API supporte les commandes multiples | Oui | La plupart
Toutes les fonctionnalités MySQL 4.1 et plus récent | Oui | La plupart

# Guide de démarrage rapide

## Sommaire

- Interface procédurale et orientée objet
- Connexions
- Exécution des requêtes
- Les requêtes préparées
- Les procédures stockées
- Requêtes multiples
- Support API pour les transactions
- Les méta-données

Ce guide de démarrage rapide va aider à se familiariser avec l'API PHP MySQL.

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.

Requis : Il faut être familier avec le langage de programmation PHP, le langage SQL ainsi qu'avoir quelques bases avec le serveur MySQL.

## Interface procédurale et orientée objet

L'extension mysqli fournit 2 interfaces. Elle supporte la programmation procédurale mais aussi, la programmation orientée objet.

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.

Exemple #1 Migration facile depuis l'ancienne extension mysql

    <?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'];

L'exemple ci-dessus va afficher :

    Please do not use the deprecated mysql extension for new development. Use the mysqli extension instead.

L'interface orientée objet

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.

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.

Exemple #2 Interface procédurale et orientée objet

    <?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'];

L'exemple ci-dessus va afficher :

    A world full of choices to please everybody.

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.

Mixage des styles

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.

Exemple #3 Mauvais style de codage

    <?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'];
    }

L'exemple ci-dessus va afficher :

    Possible but bad style.

Voir aussi

- mysqli::__construct()
- mysqli::query()
- mysqli_result::fetch_assoc()
- $mysqli::connect_errno
- $mysqli::connect_error
- $mysqli::errno
- $mysqli::error
- Le résumé des fonctions de l'extension MySQLi

## Connexions

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.

Le nom d'hôte `localhost` 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, `127.0.0.1` doit être utilisé au lieu de `localhost`.

Exemple #1 Signification spéciale de localhost

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

L'exemple ci-dessus va afficher :

    Localhost via UNIX socket
    127.0.0.1 via TCP/IP

Paramètres par défaut d'une connexion

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.

Exemple #2 Paramètres par défaut

    mysqli.default_host=192.168.2.27
    mysqli.default_user=root
    mysqli.default_pw=""
    mysqli.default_port=3306
    mysqli.default_socket=/tmp/mysql.sock

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.

Valeurs par défaut internes à la bibliothèque pour la connexion

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 `localhost`. 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 `/tmp/mysql.sock` sera tentée.

Sous les systèmes Windows, le nom d'hôte `.` 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 `\\.\pipe\MySQL`.

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éfinie, la bibliothèque utilisera le port `3306`.

La bibliothèque mysqlnd et la bibliothèque cliente MySQL (libmysqlclient) implémentent la même logique pour déterminer les valeurs par défaut.

Options de connexion

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.

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 mysqli_init() ou mysqli::__construct(), définition des options demandées en utilisant mysqli::options(), et connexion au réseau avec mysqli::real_connect().

File d'attente de connexion

L'extension mysqli supporte les connexions persistantes aux bases 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.

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.

Les connexions persistantes

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 mysqli.allow_persistent. Le nombre total de connexions ouvertes par un script peut être limité avec la directive mysqli.max_links. Le nombre maximal de connexions persistantes par processus PHP peut être restreint avec la directive mysqli.max_persistent. Veuillez noter que le serveur web peut engendrer plusieurs processus PHP.

Une plainte courante contre les connexions persistantes est que leur statut n'est pas réinitialisé 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 `persistent` peut être compris comme une promesse sur le fait que le statut persiste réellement.

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 mysqli::change_user() 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.

La fonction mysqli::change_user() est une opération couteuse. Pour de meilleures performances, les utilisateurs peuvent vouloir re-compiler l'extension avec le drapeau de compilation `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`.

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.

Voir aussi

- mysqli_init()
- mysqli::__construct()
- mysqli::options()
- mysqli::real_connect()
- mysqli::change_user()
- $mysqli::host_info
- Les options de configuration MySQLi
- Les connexions persistantes aux bases de données

## Exécution des requêtes

Les requêtes peuvent être exécutées avec les fonctions mysqli::query(), mysqli::real_query() et mysqli::multi_query(). La fonction mysqli::query() 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 mysqli::query() est identique à appeler la fonction mysqli::real_query() suivie d'un appel à la fonction mysqli::store_result().

Exemple #1 Exécution des requêtes

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

Jeux de résultats en mémoire tampon

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 mysqli::query() combine à la fois l'exécution de la requête et la mise en mémoire tampon du jeu de résultats.

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.

Exemple #2 Navigation dans des résultats mis en mémoire tampon

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

L'exemple ci-dessus va afficher :

    Ordre inversé...
     id = 3
     id = 2
     id = 1
    Ordre du jeu de résultats...
     id = 1
     id = 2
     id = 3

Jeux de résultats non mis en mémoire tampon

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.

Exemple #3 Navigation dans des résultats non mis en mémoire tampon

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

Types de données des valeurs du jeu de résultats

Les fonctions mysqli::query(), mysqli::real_query() et mysqli::multi_query() sont utilisées pour exécuter des requêtes non-préparées. Au niveau du protocole client-serveur MySQL, la commande `COM_QUERY` 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 d'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. À la place de cela, toutes les valeurs sont fournies sous la forme de chaînes de caractères PHP.

Exemple #4 Le protocole texte retourne des chaînes de caractères par défaut

    <?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']));

L'exemple ci-dessus va afficher :

    id = 1 (string)
    label = a (string)

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 `MYSQLI_OPT_INT_AND_FLOAT_NATIVE`, lors de l'utilisation de 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.

Exemple #5 Types natifs des données avec mysqlnd et l'option de connexion

    <?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']));

L'exemple ci-dessus va afficher :

    id = 1 (integer)
    label = a (string)

Voir aussi

- mysqli::__construct()
- mysqli::options()
- mysqli::real_connect()
- mysqli::query()
- mysqli::multi_query()
- mysqli::use_result()
- mysqli::store_result()

## Les requêtes préparées

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.

Flux de travail de base

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.

Le serveur MySQL supporte le mode anonyme, avec des marqueurs de position utilisant le caractère `?`.

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.

Exemple #1 Première étape : la préparation

    <?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" signifie que $id est lié comme un entier et $label comme une chaîne

    $stmt->execute();

Exécution répétée

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.

Exemple #2 Requête de type INSERT préparée une seule fois, et exécutée plusieurs fois

    <?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" signifie que $id est lié comme un entier et $label comme une chaîne

    $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));

L'exemple ci-dessus va afficher :

    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++"
      }
    }

Chaque requête préparée occupe des ressources sur le serveur. Elles doivent être fermées explicitement immédiatement après utilisation. Si l'on ne le fait pas, la requête sera fermée lorsque le gestionnaire de requête sera libéré par PHP.

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 `SELECT` n'est pas exécutée comme requête préparée dans l'exemple ci-dessus.

De plus, il faut 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.

Exemple #3 Moins d'aller-retour en utilisant les multi-INSERTs SQL

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

Types de données des valeurs du jeu de résultats

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 `INT` SQL seront fournis comme variables de type entier PHP.

Exemple #4 Types de données natifs

    <?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']));

L'exemple ci-dessus va afficher :

    id = 1 (integer)
    label = PHP (string)

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.

Récupération des résultats en utilisant des variables liées

Les résultats depuis les requêtes préparées peuvent être récupérés en liant les variables de sortie, ou en interrogeant l'objet mysqli_result.

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.

Exemple #5 Liage des variables de sortie

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

L'exemple ci-dessus va afficher :

    id = 1 (integer), label = a (string)

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 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 `mysqli`.

Il est également possible de mettre en mémoire tampon les résultats d'une requête préparée en utilisant la fonction mysqli_stmt::store_result().

Récupération des résultats en utilisant l'interface mysqli_result

Au lieu d'utiliser des résultats liés, les résultats peuvent aussi être récupérés via l'interface mysqli_result. La fonction mysqli_stmt::get_result() retourne un jeu de résultats mis en mémoire tampon.

Exemple #6 Utilisation de mysqli_result pour récupérer les résultats

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

L'exemple ci-dessus va afficher :

    array(1) {
      [0]=>
      array(2) {
        ["id"]=>
        int(1)
        ["label"]=>
        string(3) "PHP"
      }
    }

L'utilisation de l'interface mysqli_result offre d'autres avantages d'un point de vue flexibilité dans la navigation dans le jeu de résultats côté client.

Exemple #7 Jeu de résultats mis en mémoire tampon pour plus de flexibilité dans la lecture

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

L'exemple ci-dessus va afficher :

    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"
    }

Échappement et injection SQL

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 mysqli_stmt::bind_param() pour plus d'informations.

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. À noter : qu'un formatage 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.

Émulation côté client de la préparation d'une requête

L'API n'inclut pas d'émulation côté client de la préparation d'une requête.

Voir aussi

- mysqli::__construct()
- mysqli::query()
- mysqli::prepare()
- mysqli_stmt::prepare()
- mysqli_stmt::execute()
- mysqli_stmt::bind_param()
- mysqli_stmt::bind_result()

## Les procédures stockées

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 `CALL` est utilisée pour exécuter une procédure stockée.

Paramètre

Les procédures stockées peuvent avoir des paramètres `IN`, `INOUT` et `OUT`, suivant la version de MySQL. L'interface mysqli n'a pas de notion spécifique des différents types de paramètres.

Paramètre IN

Les paramètres d'entrée sont fournis avec la requête `CALL`. Il faut s'assurer d'échapper correctement les valeurs.

Exemple #1 Appel d'une procédure stockée

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

L'exemple ci-dessus va afficher :

    array(1) {
      ["id"]=>
      string(1) "1"
    }

Paramètre INOUT/OUT

Les valeurs des paramètres `INOUT`/`OUT` sont accédées en utilisant les variables de session.

Exemple #2 Utilisation des variables de session

    <?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'];

L'exemple ci-dessus va afficher :

    Hi!

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.

Gestion des jeux de résultats

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 mysqli::query(). La fonction mysqli::query() 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 mysqli::query() échoue lors de la récupération des jeux de résultats attendus de l'utilisateur.

Les jeux de résultats retournés depuis une procédure stockée sont récupérés en utilisant la fonction mysqli::real_query() ou mysqli::multi_query(). 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 `CALL`. 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.

Exemple #3 Récupération des résultats issus d'une procédure stockée

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

L'exemple ci-dessus va afficher :

    ---
    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"
      }
    }

Utilisation des requêtes préparées

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 supportent pas la préparation des requêtes SQL `CALL`.

Exemple #4 Procédures stockées et requête préparée

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

L'exemple ci-dessus va afficher :

    ---
    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)
      }
    }

Bien sûr, l'utilisation de l'API de liage pour la récupération est également supportée.

Exemple #5 Procédures stockées et requête préparée en utilisant l'API de liage

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

L'exemple ci-dessus va afficher :

    id = 1
    id = 2
    id = 3
    id = 2
    id = 3
    id = 4

Voir aussi

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## Requêtes multiples

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.

Les requêtes multiples ou multirequêtes doivent être exécutées avec la fonction mysqli::multi_query(). 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.

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.

Exemple #1 Requêtes multiples

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

L'exemple ci-dessus va afficher :

    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "0"
      }
    }
    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "1"
      }
    }

D'un point de vue de la sécurité

Les fonctions mysqli::query() et mysqli::real_query() 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 `; DROP DATABASE mysql` ou `; SELECT SLEEP(999)`. Si l'attaquant arrive à ajouter ce genre de SQL dans la chaîne de requête mais que mysqli::multi_query() n'est pas utilisé, le serveur n'exécutera que la première requête, mais pas la seconde représentant la requête SQL malicieuse.

Exemple #2 Injection SQL

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

L'exemple ci-dessus va afficher :

    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

Prepared statements

L'utilisation des requêtes multiples avec des requêtes préparées n'est pas supportée.

Voir aussi

- mysqli::query()
- mysqli::multi_query()
- mysqli_result::next-result()
- mysqli_result::more-results()

## Support API pour les transactions

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.

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 `autocommit` et pour valider et annuler les transactions.

Exemple #1 Définir le mode `autocommit` via SQL ou via l'API

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

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 `autocommit`, pour valider ou annuler une transaction.

Exemple #2 Validation et annulation d'une transaction

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

Veuillez noter que le serveur MySQL ne peut pas annuler toutes les requêtes. Quelques requêtes requièrent une validation implicite.

Voir aussi

- mysqli::autocommit()
- mysqli::begin_transaction()
- mysqli::commit()
- mysqli::rollback()

## Les méta-données

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 accessibles via l'interface `mysqli`. 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.

Les méta-données peuvent être consultées via l'interface mysqli_result.

Exemple #1 Accès aux méta-données du jeu de résultats

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

L'exemple ci-dessus va afficher :

    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)
      }
    }

Requêtes préparées

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 mysqli_result utilisable est retourné par la fonction mysqli_stmt::result_metadata().

Exemple #2 Méta-données via des requêtes préparées

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

Voir aussi

- mysqli::query()
- mysqli_result::fetch_fields()

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

Pour que ces fonctions soient disponibles, il faut compiler PHP avec le support de l'extension mysqli.

MySQL 8

Si PHP est utilisé antérieur à sa version 7.1.16, ou PHP 7.2 antérieur à 7.2.4, le plugin de mot de passe doit être défini à mysql_native_password pour MySQL 8 Server car sinon des erreurs similaires à The server requested authentication method unknown to the client [caching_sha2_password] peuvent apparaître même si caching_sha2_password n'est pas utilisé.

Ceci est dû au fait que MySQL 8 utilise par défaut caching_sha2_password, un plugin qui n'est pas reconnu par les anciennes versions de PHP (mysqlnd). À la place il faut modifier le paramètre `default_authentication_plugin=mysql_native_password` dans my.cnf. Le plugin caching_sha2_password est pleinement supporté à partir de PHP 7.4.4. Pour les versions antérieures, l'extension mysql_xdevapi le supporte.

## Installation

L'extension `mysqli` a été introduite dans PHP 5.0.0. Le pilote natif MySQL (MySQL Native Driver) a été introduit dans PHP 5.3.0.

## Installation sur Linux

Les distributions Linux incluent des versions binaires de PHP qui peuvent être installées. Même si ces binaires sont construits avec les extensions MySQL, les bibliothèques clientes doivent souvent être installées au moyen d'un paquet additionnel. Voir si c'est le cas pour la distribution.

Par exemple, sur Ubuntu le package `php5-mysql` installe les extensions PHP ext/mysql, ext/mysqli, et pdo_mysql. Sur CentOS, le package `php-mysql` installe aussi ces trois extensions PHP.

Alternativement, il est possible de compiler cette extension soi-même. Construire PHP depuis les sources permet de préciser les extensions MySQL à embarquer, mais aussi les bibliothèques clientes de chaque extension.

Le driver natif MySQL est la bibliothèque cliente recommandée, vu qu'il apporte un gain de performance et donne l'accès à des fonctionnalités qui ne sont pas disponibles lors de l'utilisation de la bibliothèque cliente MySQL. Se reporter à la section Qu'est-ce que le driver natif MySQL de PHP ? pour une brève description des avantages du driver natif MySQL.

`/path/to/mysql_config` représente le chemin du programme `mysql_config` fourni avec MySQL serveur.

Matrice de support pour la compilation mysqli
Version PHP | Défaut | Options de configuration : mysqlnd | Options de configuration : `libmysqlclient` | Historique
--- | --- | --- | --- | ---
5.4.x et ultérieur | mysqlnd | --with-mysqli | --with-mysqli=/path/to/mysql_config | mysqlnd par défaut
5.3.x | libmysqlclient | --with-mysqli=mysqlnd | --with-mysqli=/path/to/mysql_config | mysqlnd est supporté
5.0.x, 5.1.x, 5.2.x | libmysqlclient | Indisponible | --with-mysqli=/path/to/mysql_config | mysqlnd n'est pas supporté

Il est à noter qu'il est possible de mélanger les extensions MySQL ainsi que les bibliothèques clientes. Par exemple, il est possible d'activer l'extension MySQL pour utiliser la bibliothèque cliente MySQL (libmysqlclient) tout en configurant l'extension `mysqli` pour utiliser le driver natif MySQL. Toutes les combinaisons d'extensions et bibliothèques clientes sont possibles.

## Installation sur les systèmes Windows

Sur Windows, la DLL php_mysqli.dll doit être activée dans le fichier php.ini.

Pour activer une extension PHP (telle que php_mysqli.dll), la directive PHP extension_dir doit pointer vers le dossier contenant les extensions PHP. Voir aussi Installation manuelle sous Windows . Par exemple, `extension_dir` pourrait valoir c:\php\ext.

> Note:

> Si lorsqu'on démarre le serveur web, une erreur telle que `"Unable to load dynamic library './php_mysqli.dll'"` se produit, c'est que php_mysqli.dll ne peut être trouvée sur le système.

## Configuration à l'exécution

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

Options de configuration MySQLi
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
mysqli.allow_local_infile | "0" | `INI_SYSTEM` | Antérieur à PHP 7.2.16 et 7.3.3 la valeur par défaut était "1".
mysqli.local_infile_directory |  | `INI_SYSTEM` | Disponible à partir de PHP 8.1.0.
mysqli.allow_persistent | "1" | `INI_SYSTEM` |
mysqli.max_persistent | "-1" | `INI_SYSTEM` |
mysqli.max_links | "-1" | `INI_SYSTEM` |
mysqli.default_port | "3306" | `INI_ALL` |
mysqli.default_socket | NULL | `INI_ALL` |
mysqli.default_host | NULL | `INI_ALL` |
mysqli.default_user | NULL | `INI_ALL` |
mysqli.default_pw | NULL | `INI_ALL` |
mysqli.reconnect | "0" | `INI_SYSTEM` | Supprimée à partir de PHP 8.2.0
mysqli.rollback_on_cached_plink | "0" | `INI_SYSTEM` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

Pour plus de détails et de définitions concernant les constantes INI_* ci-dessus, se reporter au chapitre sur les modifications de configuration.

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

`mysqli.allow_local_infile` bool

  Autorise l'accès, à partir de PHP, aux fichiers locaux chargés avec LOAD DATA

`mysqli.local_infile_directory` string

  Autorise un chargement restreint LOCAL DATA vers des fichiers se trouvant dans le dossier désigné.

`mysqli.allow_persistent` int

  Active la possibilité de créer des connexions persistantes en utilisant la fonction mysqli_connect().

`mysqli.max_persistent` int

  Nombre maximal de connexions persistantes pouvant être réalisé. Définir à 0 pour "illimité".

`mysqli.max_links` int

  Le nombre maximal de connexions MySQL par processus, incluant les connexions persistantes.

`mysqli.default_port` int

  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 du 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.

`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.

`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.

`mysqli.reconnect` int

  Reconnexion automatique si la connexion est interrompue.

  > Note: Cette directive php.ini avait été ignorée par le pilote mysqlnd et a été supprimée à partir de PHP 8.2.0.

`mysqli.rollback_on_cached_plink` bool

  Si cette option est activée, la fermeture d'une connexion permanente annule toutes les transactions en attente de cette connexion avant d'être replacée dans le pool de connexions persistantes. Sinon, les transactions en attente seront restaurées uniquement lorsque la connexion est réutilisée ou lorsqu'elle est réellement fermée.

Les utilisateurs ne peuvent changer `MYSQL_OPT_READ_TIMEOUT` via un appel de l'API ou au runtime. À noter que même si c'est possible, il y aura des différences sur la manière dont `libmysqlclient` et les flux vont interpréter la valeur de `MYSQL_OPT_READ_TIMEOUT`.

# L'extension mysqli et les connexions persistantes

L'idée derrière les connexions persistantes est que les connexions entre les clients et la base peuvent être réutilisées par un autre processus client, au lieu d'être détruites et recréées de nombreuses fois. Cela réduit le coût de création des connexions à chaque fois que l'une d'entre elles est requise, car les connexions sont mises en cache pour être recyclées.

Contrairement à l'extension MySQL, MySQLi ne fournit pas de fonction séparée pour ouvrir des connexions persistantes. Pour ouvrir une connexion persistante, il faut ajouter `p:` au nom de l'hôte lors de la connexion.

Le problème des connexions persistantes est qu'elles peuvent être laissées dans un état imprévisible, par les clients. Par exemple, un verrou de table peut avoir été posé avant que le client ne se déconnecte inopinément. Un nouveau client va alors prendre la connexion, mais tel quel. Il faudrait alors que le nouveau venu effectue un nettoyage en profondeur de la connexion avant de pouvoir la réutiliser sans parasitage, ce qui est un inconvénient pour le programmeur.

La connexion persistante de l'extension `mysqli` fournit une méthode de nettoyage automatique. Le nettoyage est effectué par `mysqli` et inclut :

- L'annulation des transactions actives.

- La fermeture et destruction des tables temporaires.

- Le déverrouillage des tables

- La remise à la valeur par défaut des variables de session

- La libération des commandes préparées (cela arrive toujours avec PHP)

- La fermeture du gestionnaire

- La libération des verrous posés par GET_LOCK()

Cela assure que la connexion persistante est dans une condition correcte avant d'être remise dans le groupe de connexion, et qu'un client différent la reprenne.

L'extension `mysqli` effectue ce nettoyage en appelant automatiquement la fonction C `mysql_change_user()`.

Le nettoyage automatique a ses avantages et ses inconvénients. L'avantage est que le programmeur n'a pas besoin de s'en inquiéter, car il est appelé automatiquement. Cependant, l'inconvénient est que ce code peut éventuellement être un peu plus lent, car il doit être appelé à chaque fois que la connexion est retournée dans le groupe d'attente.

Il est possible de désactiver le nettoyage du code, en compilant PHP avec l'option `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`.

> Note:

> L'extension `mysqli` supporte les connexions persistantes avec le MySQL Native Driver et avec la bibliothèque MySQL.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`MYSQLI_READ_DEFAULT_GROUP` (int)

  Lit les options dans le groupe my.cnf ou dans le fichier spécifié par `MYSQLI_READ_DEFAULT_FILE`.

`MYSQLI_READ_DEFAULT_FILE` (int)

  Lit les options dans le fichier spécifié, plutôt que dans my.cnf.

`MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Indique au serveur que le client peut gérer le mode sandbox pour les mots de passe expirés. Peut être utilisé avec mysqli_options().
`MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` (int)
  Si activée, cette option spécifie le répertoire à partir duquel le chargement de données `LOCAL` côté client est autorisé dans les instructions `LOAD DATA LOCAL`.
`MYSQLI_OPT_CONNECT_TIMEOUT` (int)

  Durée d'expiration de la connexion, en secondes.

`MYSQLI_OPT_READ_TIMEOUT` (int)

  Durée d'expiration du résultat d'exécution d'une commande en secondes. Disponible à partir de PHP 7.2.0.

`MYSQLI_OPT_LOCAL_INFILE` (int)

  Active la commande `LOAD LOCAL INFILE`.

`MYSQLI_OPT_INT_AND_FLOAT_NATIVE` (int)

  Convertit les colonnes de type entier et nombre à virgule flottante en nombres PHP. Seulement valide pour mysqlnd.

`MYSQLI_OPT_NET_CMD_BUFFER_SIZE` (int)

  La taille du buffer interne command/network. Seulement valide pour mysqlnd.

`MYSQLI_OPT_NET_READ_BUFFER_SIZE` (int)

  Taille en octets de la portion maximale à lire, lors de la lecture du corps d'un paquet de commande MySQL. Seulement valide pour mysqlnd.

`MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` (int)

`MYSQLI_INIT_COMMAND` (int)

  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_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Indique au serveur que le client peut gérer le mode sandbox pour les mots de passe expirés. Peut être utilisé avec mysqli_real_connect().
`MYSQLI_CLIENT_FOUND_ROWS` (int)
  Retourne le nombre de lignes correspondantes, pas le nombre de lignes affectées.
`MYSQLI_CLIENT_SSL_VERIFY_SERVER_CERT` (int)
  Vérifie le certificat du serveur.
`MYSQLI_CLIENT_SSL` (int)

  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` (int)

  Utilise le protocole compressé.

`MYSQLI_CLIENT_INTERACTIVE` (int)

  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` (int)

  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` (int)

  Interdit la syntaxe `db_name.tbl_name.col_name`.

`MYSQLI_CLIENT_MULTI_QUERIES`

  Permet plusieurs requêtes séparées par un point-virgule dans un seul appel à la fonction mysqli_query().

`MYSQLI_STORE_RESULT` (int)

  Pour les résultats mis en tampon. Elle a une valeur de `0`.

`MYSQLI_STORE_RESULT_COPY_DATA` (int)
  À partir de PHP 8.1, cette constante n'a plus aucun effet. Avant PHP 8.1, cette constante était utilisée pour copier les résultats du tampon interne `mysqlnd` dans les variables PHP récupérées. Par défaut, `mysqlnd` utilisera une logique de référence pour éviter de copier et dupliquer les résultats tenus en mémoire. Pour certains ensembles de résultats, par exemple, des ensembles de résultats avec de nombreuses petites lignes, l'approche de copie peut réduire l'utilisation globale de la mémoire car les variables PHP contenant les résultats peuvent être libérées plus tôt. Disponible uniquement avec `mysqlnd`. Obsolète à partir de PHP 8.4.0.
`MYSQLI_USE_RESULT` (int)

  Pour les résultats non-mis en tampon. Elle a une valeur de `1`.

`MYSQLI_ASSOC` (int)

  Les colonnes sont retournées dans le tableau, avec leurs noms comme index.

`MYSQLI_NUM` (int)

  Les colonnes sont retournées dans le tableau, avec leurs numéros comme index.

`MYSQLI_BOTH` (int)

  Les colonnes sont retournées dans le tableau, avec leurs noms et leurs numéros comme index.

`MYSQLI_NOT_NULL_FLAG` (int)

  Indique qu'un champ est défini comme `NOT NULL`.

`MYSQLI_PRI_KEY_FLAG` (int)

  Le champ est une clé primaire.

`MYSQLI_UNIQUE_KEY_FLAG` (int)

  Le champ est un index unique.

`MYSQLI_MULTIPLE_KEY_FLAG` (int)

  Le champ fait partie d'un index.

`MYSQLI_BLOB_FLAG` (int)

  Le champ est de type `BLOB`.

`MYSQLI_UNSIGNED_FLAG` (int)

  Le champ est de type `UNSIGNED`.

`MYSQLI_ZEROFILL_FLAG` (int)

  Le champ est de type `ZEROFILL`.

`MYSQLI_AUTO_INCREMENT_FLAG` (int)

  Le champ est de type `AUTO_INCREMENT`.

`MYSQLI_TIMESTAMP_FLAG` (int)

  Le champ est de type `TIMESTAMP`.

`MYSQLI_SET_FLAG` (int)

  Le champ est de type `SET`.

`MYSQLI_NUM_FLAG` (int)

  Le champ est de type `NUMERIC`.

`MYSQLI_PART_KEY_FLAG` (int)

  Le champ fait partie d'un index multiple.

`MYSQLI_GROUP_FLAG` (int)

  Le champ fait partie de la clause `GROUP BY`.

`MYSQLI_NO_DEFAULT_VALUE_FLAG` (int)
  Une colonne n'a pas de clause `DEFAULT` dans sa définition. Cela ne s'applique pas aux colonnes `NULL` ou `AUTO_INCREMENT` car ces colonnes ont respectivement une valeur par défaut de `NULL` et une valeur par défaut implicite.
`MYSQLI_TYPE_DECIMAL` (int)

  Le champ est de type `DECIMAL`.

`MYSQLI_TYPE_NEWDECIMAL` (int)

  Le champ est de type `DECIMAL` ou `NUMERIC`.

`MYSQLI_TYPE_BIT` (int)

  Le champ est de type `BIT`.

`MYSQLI_TYPE_TINY` (int)

  Le champ est de type `TINYINT`.

`MYSQLI_TYPE_SHORT` (int)

  Le champ est de type `SMALLINT`.

`MYSQLI_TYPE_LONG` (int)

  Le champ est de type `INT`.

`MYSQLI_TYPE_FLOAT` (int)

  Le champ est de type `FLOAT`.

`MYSQLI_TYPE_DOUBLE` (int)

  Le champ est de type `DOUBLE`.

`MYSQLI_TYPE_NULL` (int)

  Le champ est de type `DEFAULT NULL`.

`MYSQLI_TYPE_TIMESTAMP` (int)

  Le champ est de type `TIMESTAMP`.

`MYSQLI_TYPE_LONGLONG` (int)

  Le champ est de type `BIGINT`.

`MYSQLI_TYPE_INT24` (int)

  Le champ est de type `MEDIUMINT`.

`MYSQLI_TYPE_DATE` (int)

  Le champ est de type `DATE`.

`MYSQLI_TYPE_TIME` (int)

  Le champ est de type `TIME`.

`MYSQLI_TYPE_DATETIME` (int)

  Le champ est de type `DATETIME`.

`MYSQLI_TYPE_YEAR` (int)

  Le champ est de type `YEAR`.

`MYSQLI_TYPE_NEWDATE` (int)

  Le champ est de type `DATE`.

`MYSQLI_TYPE_INTERVAL` (int)

  Alias de `MYSQLI_TYPE_ENUM`. Supprimé à partir de PHP 8.4.0.

`MYSQLI_TYPE_ENUM` (int)

  Le champ est de type `ENUM`.

`MYSQLI_TYPE_SET` (int)

  Le champ est de type `SET`.

`MYSQLI_TYPE_TINY_BLOB` (int)

  Le champ est de type `TINYBLOB`.

`MYSQLI_TYPE_MEDIUM_BLOB` (int)

  Le champ est de type `MEDIUMBLOB`.

`MYSQLI_TYPE_LONG_BLOB` (int)

  Le champ est de type `LONGBLOB`.

`MYSQLI_TYPE_BLOB` (int)

  Le champ est de type `BLOB`.

`MYSQLI_TYPE_VAR_STRING` (int)

  Le champ est de type `VARCHAR`.

`MYSQLI_TYPE_STRING` (int)

  Le champ est de type `CHAR` ou `BINARY`.

`MYSQLI_TYPE_CHAR` (int)

  Le champ est de type `TINYINT`. Pour `CHAR`, voir `MYSQLI_TYPE_STRING`.

`MYSQLI_TYPE_GEOMETRY` (int)

  Le champ est de type `GEOMETRY`.

`MYSQLI_TYPE_JSON` (int)

  Le champ est de type `JSON`. Uniquement valide pour mysqlnd et MySQL 5.7.8 et ultérieur.

`MYSQLI_TYPE_VECTOR` (int)

  Le champ est défini comme `VECTOR`.

`MYSQLI_NEED_DATA`

  Il reste des variables à relier.

`MYSQLI_ENUM_FLAG` (int)

  Le champ est défini comme `ENUM`.

`MYSQLI_BINARY_FLAG` (int)

  Le champ est défini comme `BINARY`.

`MYSQLI_CURSOR_TYPE_FOR_UPDATE` (int)

  Supprimé à partir de PHP 8.4.0.

`MYSQLI_CURSOR_TYPE_NO_CURSOR` (int)

`MYSQLI_CURSOR_TYPE_READ_ONLY` (int)

  Supprimé à partir de PHP 8.4.0.

`MYSQLI_CURSOR_TYPE_SCROLLABLE` (int)

  Supprimé à partir de PHP 8.4.0.

`MYSQLI_STMT_ATTR_CURSOR_TYPE` (int)

`MYSQLI_STMT_ATTR_PREFETCH_ROWS` (int)

  Supprimé à partir de PHP 8.4.0.

`MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH` (int)

`MYSQLI_SET_CHARSET_NAME` (int)

`MYSQLI_REPORT_INDEX` (int)

  Rapporte si un mauvais index ou aucun index n'est utilisé dans une requête.

`MYSQLI_REPORT_ERROR` (int)

  Rapporte les erreurs depuis des appels aux fonctions mysqli.

`MYSQLI_REPORT_STRICT` (int)

  Lance une exception `mysqli_sql_exception` pour les erreurs au lieu d'alertes.

`MYSQLI_REPORT_ALL` (int)

  Active toutes les options.

`MYSQLI_REPORT_OFF` (int)

  Désactive toutes les options.

`MYSQLI_DEBUG_TRACE_ENABLED` (int)

  Définit à 1 si la fonctionnalité mysqli_debug() est activée.

`MYSQLI_SERVER_PUBLIC_KEY` (int)

`MYSQLI_REFRESH_GRANT` (int)

  Rafraîchit les tables GRANT. Obsolète à partir de PHP 8.4.0.

`MYSQLI_REFRESH_LOG` (int)

  Vide les logs, identique à exécuter la requête SQL `FLUSH LOGS`. Obsolète à partir de PHP 8.4.0.

`MYSQLI_REFRESH_TABLES` (int)

  Vide le cache des tables, identique à exécuter la requête SQL `FLUSH TABLES`. Obsolète à partir de PHP 8.4.0.

`MYSQLI_REFRESH_HOSTS` (int)

  Vide le cache des hôtes, identique à exécuter la requête SQL `FLUSH HOSTS`. Obsolète à partir de PHP 8.4.0.

`MYSQLI_REFRESH_REPLICA` (int)

  Alias de la constante `MYSQLI_REFRESH_SLAVE`. Disponible à partir de PHP 8.1.0. Obsolète à partir de PHP 8.4.0.

`MYSQLI_REFRESH_STATUS` (int)

  Réinitialise le statut des variables, identique à exécuter la requête SQL `FLUSH STATUS`. Obsolète à partir de PHP 8.4.0.

`MYSQLI_REFRESH_THREADS` (int)

  Vide le cache des threads. Obsolète à partir de PHP 8.4.0.

`MYSQLI_REFRESH_SLAVE` (int)

  Sur un serveur esclave de réplication : réinitialise les informations du serveur maître, et redémarre l'esclave. Identique à exécuter la requête SQL `RESET SLAVE`. Obsolète à partir de PHP 8.4.0.

`MYSQLI_REFRESH_MASTER` (int)

  Sur un serveur maître de réplication : supprime les fichiers binaires de logs listés dans l'index binaire des logs, et tronque le fichier index. Identique à exécuter la requête SQL `RESET MASTER`. Obsolète à partir de PHP 8.4.0.

`MYSQLI_REFRESH_BACKUP_LOG` (int)
  Ferme et rouvre les fichiers de journal de sauvegarde. Obsolète à partir de PHP 8.4.0.
`MYSQLI_TRANS_COR_AND_CHAIN` (int)

  Ajout de "AND CHAIN" à mysqli_commit() ou mysqli_rollback().

`MYSQLI_TRANS_COR_AND_NO_CHAIN` (int)

  Ajout de "AND NO CHAIN" à mysqli_commit() ou mysqli_rollback().

`MYSQLI_TRANS_COR_RELEASE` (int)

  Ajout de "RELEASE" à mysqli_commit() ou mysqli_rollback().

`MYSQLI_TRANS_COR_NO_RELEASE` (int)

  Ajout de "NO RELEASE" à mysqli_commit() ou mysqli_rollback().

`MYSQLI_TRANS_START_READ_ONLY` (int)

  Débute la transaction en tant que "START TRANSACTION READ ONLY".

`MYSQLI_TRANS_START_READ_WRITE` (int)

  Débute la transaction en tant que "START TRANSACTION READ WRITE" avec mysqli_begin_transaction().

`MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT` (int)

  Débute la transaction en tant que "START TRANSACTION WITH CONSISTENT SNAPSHOT" avec mysqli_begin_transaction().

`MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` (int)

  Requiert MySQL 5.6.5 ou ultérieur.

`MYSQLI_IS_MARIADB` (bool)

  Si l'extension mysqli a été construite contre une bibliothèque client MariaDB. Disponible à partir de PHP 8.1.2.

`MYSQLI_ASYNC` (int)
  La requête est exécutée de manière asynchrone et aucun ensemble de résultats n'est immédiatement retourné. Disponible uniquement avec `mysqlnd`.
`MYSQLI_ON_UPDATE_NOW_FLAG` (int)
  Si un champ est mis à jour, il recevra la valeur temporelle actuelle.

# Notes

Quelques notes sur l'implémentation :

1. Le support de `MYSQL_TYPE_GEOMETRY` a été ajouté à l'extension MySQLI en PHP 5.3.

2. Il est à noter qu'il y a des différences internes d'implémentations entre `libmysqlclient` et `mysqlnd` pour gérer les colonnes de type `MYSQL_TYPE_GEOMETRY`. D'un point de vue général, `mysqlnd` alloue beaucoup moins de mémoire. Par exemple, s'il y a une colonne de type `POINT` dans le jeu de résultats, `libmysqlclient` allouera environ 4GB de RAM alors qu'il ne faut que 50 octets pour gérer une colonne de type `POINT` en mémoire. L'allocation mémoire est encore plus faible que 50 octets lors de l'utilisation de `mysqlnd`.

# Le sommaire des fonctions de l'extension MySQLi

Sommaire des méthodes mysqli
Classe mysqli
Interface POO | Interface procédurale | Alias (Ne plus utiliser) | Description
--- | --- | --- | ---
Propriétés
$mysqli::affected_rows | mysqli_affected_rows() | N/A | Retourne le nombre de lignes affectées par la dernière opération MySQL
$mysqli::client_info | mysqli_get_client_info() | N/A | Retourne la version du client MySQL sous la forme d'une chaîne de caractères
$mysqli::client_version | mysqli_get_client_version() | N/A | Retourne l'information sur la version du client MySQL sous la forme d'un entier
$mysqli::connect_errno | mysqli_connect_errno() | N/A | Retourne le code d'erreur de la connexion MySQL
$mysqli::connect_error | mysqli_connect_error() | N/A | Retourne le message d'erreur de la connexion MySQL
$mysqli::errno | mysqli_errno() | N/A | Retourne le code d'erreur de connexion MySQL
$mysqli::error | mysqli_error() | N/A | Retourne le message d'erreur de connexion MySQL
$mysqli::field_count | mysqli_field_count() | N/A | Retourne le nombre de colonnes pour la dernière requête
$mysqli::host_info | mysqli_get_host_info() | N/A | Retourne une chaîne contenant le type de connexion utilisée
$mysqli::protocol_version | mysqli_get_proto_info() | N/A | Retourne la version du protocole MySQL utilisé
$mysqli::server_info | mysqli_get_server_info() | N/A | Retourne la version du serveur MySQL
$mysqli::server_version | mysqli_get_server_version() | N/A | Retourne un entier représentant la version du serveur MySQL
$mysqli::info | mysqli_info() | N/A | Retourne des informations à propos de la dernière requête exécutée
$mysqli::insert_id | mysqli_insert_id() | N/A | Retourne l'identifiant automatiquement généré par la dernière requête
$mysqli::sqlstate | mysqli_sqlstate() | N/A | Retourne l'erreur SQLSTATE de la dernière opération MySQL
$mysqli::warning_count | mysqli_warning_count() | N/A | Retourne le nombre d'avertissements générés par la dernière requête
Méthodes
mysqli::autocommit() | mysqli_autocommit() | N/A | Active ou désactive le mode auto-commit
mysqli::change_user() | mysqli_change_user() | N/A | Change l'utilisateur de la connexion spécifiée
mysqli::character_set_name() | mysqli_character_set_name() | N/A | Retourne le jeu de caractères courant pour la connexion
mysqli::close() | mysqli_close() | N/A | Ferme une connexion
mysqli::commit() | mysqli_commit() | N/A | Valide la transaction courante
mysqli::__construct() | mysqli_connect() | N/A | Ouvre une connexion à un serveur MySQL
mysqli::debug() | mysqli_debug() | N/A | Effectue des actions de débogage
mysqli::dump_debug_info() | mysqli_dump_debug_info() | N/A | Écrit les informations de débogage dans les logs
mysqli::get_charset() | mysqli_get_charset() | N/A | Retourne un objet représentant le jeu de caractères
mysqli::get_connection_stats() | mysqli_get_connection_stats() | N/A | Retourne des statistiques sur la connexion du client. Disponible uniquement avec mysqlnd.
mysqli::get_client_info() | mysqli_get_client_info() | N/A | Retourne une chaîne contenant la version du client MySQL
N/A | mysqli_get_client_stats() | N/A | Retourne les statistiques du client MySQL. Disponible uniquement avec mysqlnd.
mysqli::get_server_info() | mysqli_get_server_info() | N/A | Retourne une chaîne représentant la version du serveur MySQL sur laquelle l'extension MySQLi est connectée
mysqli::get_warnings() | mysqli_get_warnings() | N/A | Non documenté
mysqli::init() | mysqli_init() | N/A | Initialise MySQLi et retourne un objet à utiliser avec mysqli_real_connect()
mysqli::kill() | mysqli_kill() | N/A | Demande au serveur de terminer un thread MySQL
mysqli::more_results() | mysqli_more_results() | N/A | Vérifie s'il y a d'autres jeux de résultats MySQL disponibles
mysqli::multi_query() | mysqli_multi_query() | N/A | Exécute une requête MySQL multiple
mysqli::next_result() | mysqli_next_result() | N/A | Prépare le prochain résultat d'une requête multiple
mysqli::options() | mysqli_options() | mysqli_set_opt() | Définit les options
mysqli::ping() | mysqli_ping() | N/A | Ping la connexion au serveur et reconnecte si elle n'existe plus
mysqli::prepare() | mysqli_prepare() | N/A | Prépare une requête SQL pour l'exécution
mysqli::query() | mysqli_query() | N/A | Exécute une requête sur la base de données
mysqli::real_connect() | mysqli_real_connect() | N/A | Ouvre une connexion à un serveur MySQL
mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | Protège les caractères spéciaux d'une chaîne pour l'utiliser dans une requête
mysqli::real_query() | mysqli_real_query() | N/A | Exécute une requête SQL
mysqli::refresh() | mysqli_refresh() | N/A | Ré-initialise les tables ou les caches, ou réinitialise les informations de réplication du serveur
mysqli::rollback() | mysqli_rollback() | N/A | Annule la transaction courante
mysqli::select_db() | mysqli_select_db() | N/A | Sélectionne une base de données par défaut pour les requêtes
mysqli::set_charset() | mysqli_set_charset() | N/A | Définit le jeu de caractères par défaut du client
mysqli::ssl_set() | mysqli_ssl_set() | N/A | Utilisée pour établir une connexion sécurisée avec SSL
mysqli::stat() | mysqli_stat() | N/A | Obtient le statut courant du système
mysqli::stmt_init() | mysqli_stmt_init() | N/A | Initialise une commande MySQL
mysqli::store_result() | mysqli_store_result() | N/A | Transfère un jeu de résultats à partir de la dernière requête
mysqli::thread_id() | mysqli_thread_id() | N/A | Retourne l'identifiant du thread pour la connexion courante
mysqli::thread_safe() | mysqli_thread_safe() | N/A | Indique si le support des threads est activé ou pas
mysqli::use_result() | mysqli_use_result() | N/A | Initialise la récupération d'un jeu de résultats

Résumé des méthodes mysqli_stmt
MySQL_STMT
Interface POO | Interface procédurale | Alias (Ne plus utiliser) | Description
--- | --- | --- | ---
Propriétés
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | N/A | Le nombre total de lignes modifiées, effacées ou insérées par la dernière
$mysqli_stmt::errno | mysqli_stmt_errno() | N/A | Le code erreur de la dernière requête
$mysqli_stmt::error | mysqli_stmt_error() | N/A | Le message d'erreur de la dernière requête
$mysqli_stmt::field_count | mysqli_stmt_field_count() | N/A | Le nombre de champs présents dans la requête donnée
$mysqli_stmt::insert_id | mysqli_stmt_insert_id() | N/A | L'ID généré par la dernière requête INSERT
$mysqli_stmt::num_rows | mysqli_stmt_num_rows() | N/A | Le nombre de lignes d'un résultat MySQL
$mysqli_stmt::param_count | mysqli_stmt_param_count() | N/A | Le nombre de paramètres d'une commande SQL
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | N/A | Le code SQLSTATE de la dernière opération MySQL
Méthodes
mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | N/A | Récupère la valeur courante d'un attribut de requête
mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | N/A | Modifie le comportement d'une requête préparée
mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | N/A | Lie des variables à une requête MySQL
mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | N/A | Lie des variables à un jeu de résultats
mysqli_stmt::close() | mysqli_stmt_close() | N/A | Termine une requête préparée
mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | N/A | Déplace le pointeur de résultat
mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | Exécute une requête préparée
mysqli_stmt::fetch() | mysqli_stmt_fetch() | N/A | Lit des résultats depuis une requête MySQL préparée dans des variables liées
mysqli_stmt::free_result() | mysqli_stmt_free_result() | N/A | Libère le résultat MySQL de la mémoire
mysqli_stmt::get_result() | mysqli_stmt_get_result() | N/A | Récupère le jeu de résultats depuis une requête préparée. Disponible uniquement avec mysqlnd.
mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | N/A | Non documenté
mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | Vérifie s'il y a plus de résultats de requête à partir d'une requête multiple
mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | Lit le résultat suivant à partir d'une requête multiple
mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | N/A | Voir aussi la propriété $mysqli_stmt->num_rows
mysqli_stmt::prepare() | mysqli_stmt_prepare() | N/A | Prépare une requête SQL pour l'exécution
mysqli_stmt::reset() | mysqli_stmt_reset() | N/A | Annule une requête préparée
mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | N/A | Retourne les métadonnées de préparation de requête MySQL
mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | N/A | Envoie des données MySQL par paquets
mysqli_stmt::store_result() | mysqli_stmt_store_result() | N/A | Stocke un jeu de résultats depuis une requête préparée

Résumé des méthodes mysqli_result
mysqli_result
Interface POO | Interface procédurale | Alias (Ne plus utiliser) | Description
--- | --- | --- | ---
Propriétés
$mysqli_result::current_field | mysqli_field_tell() | N/A | La position courante d'un champ dans un pointeur de résultat
$mysqli_result::field_count | mysqli_num_fields() | N/A | Le nombre de champs dans un résultat
$mysqli_result::lengths | mysqli_fetch_lengths() | N/A | Les tailles des champs dans un résultat
$mysqli_result::num_rows | mysqli_num_rows() | N/A | Le nombre de lignes dans un résultat
Méthodes
mysqli_result::data_seek() | mysqli_data_seek() | N/A | Déplace le pointeur interne de résultat
mysqli_result::fetch_all() | mysqli_fetch_all() | N/A | Lit toutes les lignes de résultats dans un tableau associatif, numérique, ou les deux. Disponible uniquement avec mysqlnd.
mysqli_result::fetch_array() | mysqli_fetch_array() | N/A | Retourne une ligne de résultat sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux
mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | N/A | Récupère une ligne de résultat sous forme de tableau associatif
mysqli_result::fetch_column() | mysqli_fetch_column() | N/A | Récupère une seule colonne de la ligne suivante d'un ensemble de résultats
mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | N/A | Récupère les métadonnées d'un champ unique
mysqli_result::fetch_field() | mysqli_fetch_field() | N/A | Retourne le prochain champ dans le jeu de résultats
mysqli_result::fetch_fields() | mysqli_fetch_fields() | N/A | Retourne un tableau d'objets représentant les champs dans le résultat
mysqli_result::fetch_object() | mysqli_fetch_object() | N/A | Retourne la ligne courante d'un jeu de résultats sous forme d'objet
mysqli_result::fetch_row() | mysqli_fetch_row() | N/A | Récupère une ligne de résultat sous forme de tableau indexé
mysqli_result::field_seek() | mysqli_field_seek() | N/A | Déplace le pointeur de résultat sur le champ spécifié
mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | N/A | Libère la mémoire associée à un résultat

Résumé des méthodes mysqli_driver
MySQL_Driver
Interface POO | Interface procédurale | Alias (Ne plus utiliser) | Description
--- | --- | --- | ---
Propriétés
$mysqli_driver::mysqli_report | mysqli_report() | N/A | Définit le mode du rapport d'erreur de mysqli
Méthodes
mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | N/A | Non documenté
mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | N/A | Non documenté

> Note:

> Les alias sont fournis pour assurer la compatibilité ascendante. Ne pas les utiliser dans de nouveaux projets.

# La classe mysqli

(PHP 5, PHP 7, PHP 8)

## Introduction

Représente une connexion entre PHP et une base de données MySQL.

## Synopsis de la classe

class mysqli {
/* Propriétés */
public readonly int|string $affected_rows;
public readonly string $client_info;
public readonly int $client_version;
public readonly int $connect_errno;
public readonly ?string $connect_error;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly int $field_count;
public readonly string $host_info;
public readonly ?string $info;
public readonly int|string $insert_id;
public readonly string $server_info;
public readonly int $server_version;
public readonly string $sqlstate;
public readonly int $protocol_version;
public readonly int $thread_id;
public readonly int $warning_count;
/* Méthodes */
public function __construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function autocommit(bool `$enable`): bool
public function begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool
public function change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool
public function character_set_name(): string
public function close(): true
public function commit(int `$flags` = 0, ?string `$name` = `null`): bool
public function connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool
public function debug(string `$options`): true
public function dump_debug_info(): bool
public function execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool
public function get_charset(): ?object
#[\Deprecated]
public function get_client_info(): string
public function get_connection_stats(): array
public function get_server_info(): string
public function get_warnings(): mysqli_warning|false
#[\Deprecated]
public function init(): ?bool
#[\Deprecated]
public function kill(int `$process_id`): bool
public function more_results(): bool
public function multi_query(string `$query`): bool
public function next_result(): bool
public function options(int `$option`, string|int `$value`): bool
#[\Deprecated]
public function ping(): bool
public static function poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false
public function prepare(string `$query`): mysqli_stmt|false
public function query(string `$query`, int `$result_mode` = MYSQLI_STORE_RESULT): mysqli_result|bool
public function real_connect(
?string `$hostname` = null,
?string `$username` = null,
#[\SensitiveParameter]?string `$password` = null,
?string `$database` = null,
?int `$port` = null,
?string `$socket` = null,
int `$flags` = 0
): bool
public function real_escape_string(string `$string`): string
public function real_query(string `$query`): bool
public function reap_async_query(): mysqli_result|bool
#[\Deprecated]
public function refresh(int `$flags`): bool
public function release_savepoint(string `$name`): bool
public function rollback(int `$flags` = 0, ?string `$name` = null): bool
public function savepoint(string `$name`): bool
public function select_db(string `$database`): bool
public function set_charset(string `$charset`): bool
public function ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true
public function stat(): string|false
public function stmt_init(): mysqli_stmt|false
public function store_result(int `$mode` = 0): mysqli_result|false
public function thread_safe(): bool
public function use_result(): mysqli_result|false
}

# mysqli::$affected_rows

# mysqli_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli::$affected_rows -- mysqli_affected_rows — Retourne le nombre de lignes affectées par la dernière opération MySQL

### Description

Style orienté objet

int|string $mysqli->affected_rows;

Style procédural

function mysqli_affected_rows(mysqli `$mysql`): int|string

Retourne le nombre de lignes affectées par la dernière requête `INSERT`, `UPDATE`, `REPLACE` ou `DELETE`. Fonctionne comme mysqli_num_rows() pour les requêtes `SELECT`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Un entier plus grand que zéro indique le nombre de lignes affectées ou recherchées. Zéro indique qu'aucun enregistrement n'a été modifié par une requête du type `UPDATE`, aucune ligne ne correspond à la clause `WHERE` dans la requête ou bien qu'aucune requête n'a été exécutée. `-1` indique que la requête a retourné une erreur ou que mysqli_affected_rows() a été appelé sur une requête `SELECT` non-tampon.

> Note:

> Si le nombre de lignes affectées est plus grand que la valeur maximale (`PHP_INT_MAX`) que peut prendre un entier, le nombre de lignes affectées sera retourné en tant que chaîne de caractères.

### Exemples

Exemple #1 Exemple avec $mysqli->affected_rows

Style orienté objet

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Insertion d'une ligne */
    $mysqli->query("CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Nombre de lignes affectées (INSERT): %d\n", $mysqli->affected_rows);

    $mysqli->query("ALTER TABLE Language ADD Status int default 0");

    /* Modification d'une ligne */
    $mysqli->query("UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Nombre de lignes affectées (UPDATE): %d\n", $mysqli->affected_rows);

    /* Effacement d'une ligne */
    $mysqli->query("DELETE FROM Language WHERE Percentage < 50");
    printf("Nombre de lignes affectées (DELETE): %d\n", $mysqli->affected_rows);

    /* Sélection de toutes les lignes */
    $result = $mysqli->query("SELECT CountryCode FROM Language");
    printf("Nombre de lignes affectées (SELECT): %d\n", $mysqli->affected_rows);

    /* Delete table Language */
    $mysqli->query("DROP TABLE Language");
    ?>

Style procédural

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Insertion d'une ligne */
    mysqli_query($link, "CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Nombre de lignes affectées (INSERT): %d\n", mysqli_affected_rows($link));

    mysqli_query($link, "ALTER TABLE Language ADD Status int default 0");

    /* Modification d'une ligne */
    mysqli_query($link, "UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Nombre de lignes affectées (UPDATE): %d\n", mysqli_affected_rows($link));

    /* Effacement d'une ligne */
    mysqli_query($link, "DELETE FROM Language WHERE Percentage < 50");
    printf("Nombre de lignes affectées (DELETE): %d\n", mysqli_affected_rows($link));

    /* Selection de toutes les lignes */
    $result = mysqli_query($link, "SELECT CountryCode FROM Language");
    printf("Nombre de lignes affectées (SELECT): %d\n", mysqli_affected_rows($link));

    /* Effacement de la table "language" */
    mysqli_query($link, "DROP TABLE Language");
    ?>

Les exemples ci-dessus vont afficher :

    Nombre de lignes affectées (INSERT): 984
    Nombre de lignes affectées (UPDATE): 168
    Nombre de lignes affectées (DELETE): 815
    Nombre de lignes affectées (SELECT): 169

### Voir aussi

- mysqli_num_rows() - Retourne le nombre de lignes dans le jeu de résultats
- mysqli_info() - Retourne des informations à propos de la dernière requête exécutée

# mysqli::autocommit

# mysqli_autocommit

(PHP 5, PHP 7, PHP 8)

mysqli::autocommit -- mysqli_autocommit — Active ou désactive le mode auto-commit

### Description

Style orienté objet

public function mysqli::autocommit(bool `$enable`): bool

Style procédural

function mysqli_autocommit(mysqli `$mysql`, bool `$enable`): bool

Active ou désactive le mode auto-commit pour les requêtes sur la connexion.

Pour vérifier l'état de l'auto-commit, utiliser la commande SQL `SELECT @@autocommit`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`enable`

  Si l'on doit activer ou non l'auto-commit.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Exemple avec mysqli::autocommit()

Style orienté objet

    <?php

    /* Demande à mysqli de lancer une exception si une erreur survient */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Le moteur de table supporte les transactions */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Désactive l'autocommit */
    $mysqli->autocommit(false);

    $result = $mysqli->query("SELECT @@autocommit");
    $row = $result->fetch_row();
    printf("L'Autocommit vaut %s\n", $row[0]);

    try {
        /* Prépare une requête d'insertion */
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);

        /* Insère plusieurs valeurs */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        $stmt->execute();
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        $stmt->execute();

        /* Commit les données dans la base de données. Ceci n'active pas l'autocommit */
        $mysqli->commit();
        print "Validation de 2 lignes dans la base de données\n";

        $result = $mysqli->query("SELECT @@autocommit");
        $row = $result->fetch_row();
        printf("L'autocommit vaut %s\n", $row[0]);

        /* Tente d'insérer plusieurs valeurs */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        $stmt->execute();
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        $stmt->execute();

        /* Le fait de définir autocommit=true va déclencher le commit */
        $mysqli->autocommit(true);

        print "Validation de 2 lignes dans la base de données\n";
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Style procédural

    <?php

    /* Demande à mysqli de lancer une exception si une erreur survient */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Le moteur de table supporte les transactions */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Désactive l'autocommit */
    mysqli_autocommit($mysqli, false);

    $result = mysqli_query($mysqli, "SELECT @@autocommit");
    $row = mysqli_fetch_row($result);
    printf("L'Autocommit vaut %s\n", $row[0]);

    try {
        /* Prépare une requête d'insertion */
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);

        /* Insère plusieurs valeurs */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        mysqli_stmt_execute($stmt);
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        mysqli_stmt_execute($stmt);

        /* Commit les données dans la base de données. Ceci n'active pas l'autocommit */
        mysqli_commit($mysqli);
        print "Validation de 2 lignes dans la base de données\n";

        $result = mysqli_query($mysqli, "SELECT @@autocommit");
        $row = mysqli_fetch_row($result);
        printf("L'autocommit vaut %s\n", $row[0]);

        /* Tente d'insérer plusieurs valeurs */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        mysqli_stmt_execute($stmt);
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        mysqli_stmt_execute($stmt);

        /* Le fait de définir autocommit=true va déclencher le commit */
        mysqli_autocommit($mysqli, true);

        print "Validation de 2 lignes dans la base de données\n";
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

Les exemples ci-dessus vont afficher :

    L'autocommit vaut 0
    Validation de 2 lignes dans la base de données
    L'autocommit vaut 0
    Validation de 2 lignes dans la base de données
    L'autocommit vaut 0
    Validation de 2 lignes dans la base de données
    L'autocommit vaut 0
    Validation de 2 lignes dans la base de données

### Notes

> Note:

> Cette fonction ne fonctionne pas avec les types de tables non transactionnelles, comme MyISAM ou ISAM.

### Voir aussi

- mysqli_begin_transaction() - Démarre une transaction
- mysqli_commit() - Valide la transaction courante
- mysqli_rollback() - Annule la transaction courante

# mysqli::begin_transaction

# mysqli_begin_transaction

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::begin_transaction -- mysqli_begin_transaction — Démarre une transaction

### Description

Style orienté objet

public function mysqli::begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool

Style procédural:

function mysqli_begin_transaction(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Commence une transaction. Nécessite le moteur InnoDB (il est actif par défaut). Pour plus de détails sur le fonctionnement des transactions MySQL, voir » http://dev.mysql.com/doc/mysql/en/commit.html.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`flags`

  Les drapeaux valides sont :

  - `MYSQLI_TRANS_START_READ_ONLY` : Commence la transaction comme "START TRANSACTION READ ONLY". Nécessite MySQL 5.6 ou supérieur.

  - `MYSQLI_TRANS_START_READ_WRITE` : Commence la transaction comme "START TRANSACTION READ WRITE". Nécessite MySQL 5.6 et supérieur.

  - `MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT` : Commence la transaction comme "START TRANSACTION WITH CONSISTENT SNAPSHOT".

`name`

  Nom du point de sauvegarde pour la transaction.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `name` est désormais nullable.

### Exemples

Exemple #1 Exemple avec mysqli::begin_transaction()

Style orienté objet

    <?php

    /* Demande à mysqli de lancer une exception si une erreur survient */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Le moteur de table supporte les transactions */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Démarre la transaction */
    $mysqli->begin_transaction();

    try {
        /* Insère plusieurs valeurs */
        $mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Tente d'insérer de mauvaises valeurs */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);
        $stmt->execute();

        /* Si le code arrive à ce point sans erreur, alors on commit les données dans
           la base de données */
        $mysqli->commit();
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Style procédural

    <?php

    /* Demande à mysqli de lancer une exception si une erreur survient */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Le moteur de table supporte les transactions */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Commence la transaction */
    mysqli_begin_transaction($mysqli);

    try {
        /* Insère plusieurs valeurs */
        mysqli_query($mysqli, "INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Tente d'insérer de mauvaises valeurs */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);
        mysqli_stmt_execute($stmt);

        /* Si le code arrive à ce point sans erreur, alors on commit les données dans
           la base de données */
        mysqli_commit($mysqli);
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

### Notes

> Note:

> Cette fonction ne fonctionne pas avec les types de table non transactionnelle (comme MyISAM ou ISAM).

### Voir aussi

- mysqli_autocommit() - Active ou désactive le mode auto-commit
- mysqli_commit() - Valide la transaction courante
- mysqli_rollback() - Annule la transaction courante

# mysqli::change_user

# mysqli_change_user

(PHP 5, PHP 7, PHP 8)

mysqli::change_user -- mysqli_change_user — Change l'utilisateur de la connexion

### Description

Style orienté objet

public function mysqli::change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool

Style procédural

function mysqli_change_user(
mysqli `$mysql`,
string `$username`,
#[\SensitiveParameter]string `$password`,
?string `$database`
): bool

Tente de se connecter à la base de données spécifiée en utilisant les identifiants fournis.

Contrairement à mysqli::connect(), cette méthode ne déconnectera pas la connexion actuelle si la nouvelle connexion ne peut pas être établie.

Pour que cette fonction réussisse, les paramètres `username` et `password` doivent être valides et l'utilisateur en question doit avoir les permissions d'accès à la base de données désirée. Si pour une raison ou une autre, l'autorisation échoue, l'utilisateur courant sera conservé.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`username`

  Le nom d'utilisateur MySQL.

`password`

  Le mot de passe MySQL.

`database`

  Le nom de la base de données. Si `null` ou une chaîne vide est passée, la connexion au serveur sera ouverte sans base de données par défaut.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Réinitialisation de la session de connexion

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("SET @a:=1");

    $mysqli->change_user("my_user", "my_password", "world");

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Base de données par défaut : %s\n", $row[0]);

    $result = $mysqli->query("SELECT @a");
    $row = $result->fetch_row();
    if ($row[0] === NULL) {
        printf("La valeur de la variable a est NULL\n");
    }

    ?>

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "SET @a:=1");

    mysqli_change_user($link, "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("Base de données par défaut : %s\n", $row[0]);

    $result = mysqli_query($link, "SELECT @a");
    $row = mysqli_fetch_row($result);
    if ($row[0] === NULL) {
        printf("La valeur de la variable a est NULL\n");
    }

    ?>

Les exemples ci-dessus vont afficher :

    Base de données par défaut : world
    La valeur de la variable a est NULL

Exemple #2 Si `database` est `null` la connexion est ouverte sans sélectionner de base de données par défaut

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->change_user("my_user", "my_password", null);

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Base de données par défaut : %s\n", $row[0]);

Les exemples ci-dessus vont afficher :

    Base de données par défaut :

### Notes

> Note:

> L'utilisation de cette commande implique toujours que la connexion soit considérée comme neuve, que la fonction réussisse ou non. Un appel à cette fonction annulera donc toutes les transactions actives, fermera les tables temporaires et déverrouillera les tables verrouillées.

### Voir aussi

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_select_db() - Sélectionne une base de données par défaut pour les requêtes

# mysqli::character_set_name

# mysqli_character_set_name

(PHP 5, PHP 7, PHP 8)

mysqli::character_set_name -- mysqli_character_set_name — Retourne le jeu de caractères courant pour la connexion

### Description

Style orienté objet

public function mysqli::character_set_name(): string

Style procédural

function mysqli_character_set_name(mysqli `$mysql`): string

Retourne le jeu de caractères courant pour la connexion spécifiée par le paramètre `link`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Le jeu de caractères courant pour la connexion courante.

### Exemples

Exemple #1 Exemple avec mysqli::character_set_name()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Définit le jeu de caractères par défaut */
    $mysqli->set_charset('utf8mb4');

    /* Affiche le jeu de caractères courant */
    $charset = $mysqli->character_set_name();
    printf("Le jeu de caractères courant est %s\n", $charset);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Définit le jeu de caractères par défaut */
    mysqli_set_charset($mysqli, 'utf8mb4');

    /* Affiche le jeu de caractères courant */
    $charset = mysqli_character_set_name($mysqli);
    printf("Le jeu de caractères courant est %s\n", $charset);

Les exemples ci-dessus vont afficher :

    Le jeu de caractères courant est utf8mb4

### Voir aussi

- mysqli_set_charset() - Définit le jeu de caractères du client
- 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::close

# mysqli_close

(PHP 5, PHP 7, PHP 8)

mysqli::close -- mysqli_close — Ferme une connexion

### Description

Style orienté objet

public function mysqli::close(): true

Style procédural

function mysqli_close(mysqli `$mysql`): true

Ferme la connexion spécifiée par le paramètre `link`.

Les connexions MySQL non-persistantes et les jeux de résultats seront automatiquement fermées quand leurs objets sont détruits. Explicitement fermer les connexions ouvertes et libérer les jeux de résultats est optionnel. Cependant, c'est une bonne idée de fermer la connexion dès que le script termine d'effectuer toutes ses opérations de base de données, s'il a encore beaucoup de traitement à faire après avoir récupéré les résultats.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction retourne désormais toujours `true`. Auparavant, elle retournait `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec mysqli::close()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    /* Ferme la connexion dès qu'elle n'est plus nécessaire */
    $mysqli->close();

    foreach ($result as $row) {
        /* Traitement des données récupérées de la base de données */
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    /* Ferme la connexion dès qu'elle n'est plus nécessaire */
    mysqli_close($mysqli);

    foreach ($result as $row) {
        /* Traitement des données récupérées de la base de données */
    }

### Notes

> Note:

> mysqli_close() ne ferme pas les connexions persistantes. Pour plus de détails, voir la page du manuel sur les connexions persistantes.

### Voir aussi

- mysqli::__construct() - Ouvre une connexion à un serveur MySQL
- mysqli_init() - Initialise MySQLi et retourne un objet à utiliser avec mysqli_real_connect()
- mysqli_real_connect() - Ouvre une connexion à un serveur MySQL
- mysqli_free_result() - Libère la mémoire associée à un résultat

# mysqli::commit

# mysqli_commit

(PHP 5, PHP 7, PHP 8)

mysqli::commit -- mysqli_commit — Valide la transaction courante

### Description

Style orienté objet

public function mysqli::commit(int `$flags` = 0, ?string `$name` = `null`): bool

Style procédural

function mysqli_commit(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Valide la transaction courante pour la base de données spécifiée par le paramètre `link`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`flags`

  Un masque de constantes `MYSQLI_TRANS_COR_*`.

`name`

  Si fourni, alors `COMMIT/*name*/` est exécuté.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
8.0.0 | `name` est désormais nullable.

### Exemples

Voir l'exemple se trouvant dans la documentation de la méthode mysqli::begin_transaction().

### Notes

> Note:

> Cette fonction ne fonctionne pas avec les types de table non transactionnelle (comme MyISAM ou ISAM).

### Voir aussi

- mysqli_autocommit() - Active ou désactive le mode auto-commit
- mysqli_begin_transaction() - Démarre une transaction
- mysqli_rollback() - Annule la transaction courante
- mysqli_savepoint() - Définit un point de sauvegarde nommé de la transaction

# mysqli::$connect_errno

# mysqli_connect_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_errno -- mysqli_connect_errno — Retourne le code d'erreur du dernier appel de connexion

### Description

Style orienté objet

int $mysqli->connect_errno;

Style procédural

function mysqli_connect_errno(): int

Retourne le code d'erreur de la dernière tentative de connexion.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un code d'erreur pour la dernière tentative de connexion, si elle échoue. Zéro signifie qu'aucune erreur n'est survenue.

Retourne le dernier code d’erreur de connexion, quelle que soit l’instance sur laquelle il est appelé.

### Exemples

Exemple #1 Exemple avec $mysqli->connect_errno

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* @ est utilisé pour supprimer les avertissements */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if ($mysqli->connect_errno) {
        /* Utiliser ici la méthode de journalisation des erreurs de son choix */
        error_log('Erreur de connexion : ' . $mysqli->connect_errno);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* @ est utilisé pour supprimer les avertissements */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if (!$link) {
        /* Utiliser ici la méthode de journalisation des erreurs de son choix */
        error_log('Erreur de connexion : ' . mysqli_connect_errno());
    }

### Voir aussi

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_connect_error() - Retourne une description de la dernière erreur de connexion
- mysqli_errno() - Retourne le dernier code d'erreur produit
- mysqli_error() - Retourne une chaîne décrivant la dernière erreur
- mysqli_sqlstate() - Retourne l'erreur SQLSTATE de la dernière opération MySQL

# mysqli::$connect_error

# mysqli_connect_error

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_error -- mysqli_connect_error — Retourne une description de la dernière erreur de connexion

### Description

Style orienté objet

?string $mysqli->connect_error;

Style procédural

function mysqli_connect_error(): ?string

Retourne le message d'erreur de la dernière tentative de connexion.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une chaîne qui décrit l'erreur ou `null` si aucune erreur ne survient.

Retourne le dernier message d’erreur de connexion, quelle que soit l’instance sur laquelle il est appelé.

### Exemples

Exemple #1 Exemple avec $mysqli->connect_error

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* @ est utilisé pour supprimer les avertissements */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if ($mysqli->connect_error) {
        /* Utiliser ici la méthode de journalisation des erreurs de son choix */
        error_log('Erreur de connexion : ' . $mysqli->connect_error);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* @ est utilisé pour supprimer les avertissements */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if (!$link) {
        /* Utiliser ici la méthode de journalisation des erreurs de son choix */
        error_log('Erreur de connexion : ' . mysqli_connect_error());
    }

### Voir aussi

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_connect_errno() - Retourne le code d'erreur du dernier appel de connexion
- mysqli_errno() - Retourne le dernier code d'erreur produit
- mysqli_error() - Retourne une chaîne décrivant la dernière erreur
- mysqli_sqlstate() - Retourne l'erreur SQLSTATE de la dernière opération MySQL

# mysqli::__construct

# mysqli::connect

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli::__construct -- mysqli::connect -- mysqli_connect — Ouvre une connexion à un serveur MySQL

### Description

Style orienté objet

public function mysqli::__construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function mysqli::connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool

Style procédural

function mysqli_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): mysqli|false

Ouvre une connexion au serveur MySQL.

### Liste de paramètres

`hostname`

  Peut être un nom d'hôte ou une adresse IP. Lorsqu'on passe `null`, la valeur est récupérée depuis mysqli.default_host. Si possible, les pipes seront utilisés à la place du protocole TCP/IP. Le protocole TCP/IP est utilisé si un nom d'hôte et numéro de port sont fournis ensemble, par exemple `localhost:3308`.

  Préfixer l'hôte par `p:` ouvre une connexion persistante. mysqli_change_user() est automatiquement appelée sur les connexions qui sont utilisées dans le pool de connexions.

`username`

  Le nom d'utilisateur MySQL ou `null` pour supposer le nom d'utilisateur en fonction de l'option ini mysqli.default_user.

`password`

  Le mot de passe MySQL ou `null` pour utiliser le mot de passe basé sur l'option ini mysqli.default_pw.

`database`

  La base de données par défaut à utiliser lors de l'exécution de requêtes ou `null`.

`port`

  Le numéro de port auquel tenter de se connecter au serveur MySQL ou `null` pour supposer le port en fonction de l'option ini mysqli.default_port.

`socket`

  Le socket ou le pipe nommé qui doit être utilisé, ou `null` pour supposer le socket en fonction de l'option ini mysqli.default_socket.

  > Note:

  > Spécifier le paramètre `socket` ne déterminera pas explicitement le type de connexion qui sera utilisé lors de la connexion au serveur MySQL. Cela est déterminé par le paramètre `hostname`.

### Valeurs de retour

mysqli::__construct() renvoie toujours un objet qui représente la connexion à un serveur MySQL, même si la connexion a échoué.

mysqli_connect() retourne un objet qui représente la connexion au serveur MySQL, ou `false` si une erreur survient.

mysqli::connect() renvoie `true` en cas de succès ou `false` si une erreur survient. Antérieur à PHP 8.1.0, renvoie `null` en cas de succès.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
8.1.0 | mysqli::connect() retourne désormais `true` au lieu de `null` en cas de succès.
7.4.0 | Tous les paramètres sont désormais nullable.

### Exemples

Exemple #1 Exemple mysqli::__construct()

Style orienté objet

    <?php
    /* Vous devriez toujours activer le rapport d'erreur pour mysqli avant une tentative de connexion */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
    /* Définir le jeu de caractère désiré après avoir établi une connexion */
    $mysqli->set_charset('utf8mb4');
    printf("Success... %s\n", $mysqli->host_info);

Style procédural

    <?php
    /* Vous devriez toujours activer le rapport d'erreur pour mysqli avant une tentative de connexion */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
    /* Définir le jeu de caractère désiré après avoir établi une connexion */
    mysqli_set_charset($mysqli, 'utf8mb4');
    printf("Success... %s\n", mysqli_get_host_info($mysqli));

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Success... localhost via TCP/IP

Exemple #2 Étendre la classe mysqli

    <?php
    class FooMysqli extends mysqli {
        public function __construct($host, $user, $pass, $db, $port, $socket, $charset) {
            mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
            parent::__construct($host, $user, $pass, $db, $port, $socket);
            $this->set_charset($charset);
        }
    }
    $db = new FooMysqli('localhost', 'my_user', 'my_password', 'my_db', 3306, null, 'utf8mb4');

Exemple #3 Gestion d'erreur manuelle

Si le rapport d'erreur est désactivé, le développeur est responsable pour vérifier et gérer les échecs

Style orienté objet

    <?php
    error_reporting(0);
    mysqli_report(MYSQLI_REPORT_OFF);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
    if ($mysqli->connect_errno) {
        throw new RuntimeException('mysqli connection error: ' . $mysqli->connect_error);
    }
    /* Définir le jeu de caractère désiré après avoir établi une connexion */
    $mysqli->set_charset('utf8mb4');
    if ($mysqli->errno) {
        throw new RuntimeException('mysqli error: ' . $mysqli->error);
    }

Style procédural

    <?php
    error_reporting(0);
    mysqli_report(MYSQLI_REPORT_OFF);
    $mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
    if (mysqli_connect_errno()) {
        throw new RuntimeException('mysqli connection error: ' . mysqli_connect_error());
    }
    /* Définir le jeu de caractère désiré après avoir établi une connexion */
    mysqli_set_charset($mysqli, 'utf8mb4');
    if (mysqli_errno($mysqli)) {
        throw new RuntimeException('mysqli error: ' . mysqli_error($mysqli));
    }

### Notes

> Note: MySQLnd s'occupe toujours du jeu de caractères par défaut du serveur. Celui-ci est envoyé durant la négociation de la connexion ou l'authentification.Libmysqlclient utilise le jeu de caractères par défaut de my.cnf ou via par un appel à mysqli_options() avant mysqli_real_connect(), mais après mysqli_init().

> Note:

> Style orienté objet uniquement : si la connexion a échoué, un objet est quand même retourné. Pour vérifier si la connexion a échoué, utiliser soit la fonction mysqli_connect_error() ou la propriété mysqli->connect_error comme dans l'exemple ci-dessus.

> Note:

> S'il est nécessaire de configurer des options, telles que le délai de connexion, mysqli_real_connect() doit être utilisé.

> Note:

> Appeler le constructeur sans paramètre a le même effet qu'appeler mysqli_init().

> Note:

> L'erreur `"Can't create TCP/IP socket (10106)"` signifie généralement que la directive de configuration variables_order ne contient pas le caractère `E`. Sous Windows, si l'environnement n'est pas copié, la variable d'environnement `SYSTEMROOT` ne sera pas disponible et PHP aura des soucis pour charger Winsock.

### Voir aussi

- mysqli_real_connect() - Ouvre une connexion à un serveur MySQL
- mysqli_options() - Définit les options
- mysqli_connect_errno() - Retourne le code d'erreur du dernier appel de connexion
- mysqli_connect_error() - Retourne une description de la dernière erreur de connexion
- mysqli_close() - Ferme une connexion

# mysqli::debug

# mysqli_debug

(PHP 5, PHP 7, PHP 8)

mysqli::debug -- mysqli_debug — Effectue des actions de débogage

### Description

Style orienté objet

public function mysqli::debug(string `$options`): true

Style procédural

function mysqli_debug(string `$options`): true

Effectue des actions de débogage en utilisant la bibliothèque de débogage Fred Fish.

### Liste de paramètres

`options`

  Une chaîne de caractères représentant l'opération de débogage à effectuer.

  La chaîne de contrôle de débogage est une séquence de champs séparés par deux points, comme suit : ``

      <field_1>:<field_2>:<field_N>

  Chaque champ se compose d'un caractère d'indicateur obligatoire suivi d'un `,` facultatif et d'une liste de modificateurs séparés par des virgules : `flag[,modifier,modifier,...,modifier]`

  Caractères de drapeau reconnus
  `options` caractère | Description
  --- | ---
  O | `MYSQLND_DEBUG_FLUSH`
  A/a | `MYSQLND_DEBUG_APPEND`
  F | `MYSQLND_DEBUG_DUMP_FILE`
  i | `MYSQLND_DEBUG_DUMP_PID`
  L | `MYSQLND_DEBUG_DUMP_LINE`
  m | `MYSQLND_DEBUG_TRACE_MEMORY_CALLS`
  n | `MYSQLND_DEBUG_DUMP_LEVEL`
  o | sortie vers un fichier
  T | `MYSQLND_DEBUG_DUMP_TIME`
  t | `MYSQLND_DEBUG_DUMP_TRACE`
  x | `MYSQLND_DEBUG_PROFILE_CALLS`

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction retourne désormais toujours `true`. Auparavant, elle retournait `false` en cas d'échec.

### Exemples

Exemple #1 Génération d'un fichier de "traces"

    <?php

    /* Génère un fichier de "trace" dans '/tmp/client.trace' sur la machine (cliente) locale : */
    mysqli_debug("d:t:o,/tmp/client.trace");

    ?>

### Notes

> Note:

> Pour utiliser la fonction mysqli_debug(), l'on doit compiler la bibliothèque cliente MySQL avec le support du débogage.

### Voir aussi

- mysqli_dump_debug_info() - Écrit les informations de débogage dans les logs
- mysqli_report() - Alias de mysqli_driver->report_mode

# mysqli::dump_debug_info

# mysqli_dump_debug_info

(PHP 5, PHP 7, PHP 8)

mysqli::dump_debug_info -- mysqli_dump_debug_info — Écrit les informations de débogage dans les logs

### Description

Style orienté objet

public function mysqli::dump_debug_info(): bool

Style procédural

function mysqli_dump_debug_info(mysqli `$mysql`): bool

Cette fonction est à utiliser par un utilisateur possédant le privilège SUPER et est utilisée pour écrire quelques informations de débogage dans le journal pour le serveur MySQL relatif à la connexion spécifiée par le paramètre `link`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- mysqli_debug() - Effectue des actions de débogage

# mysqli::$errno

# mysqli_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$errno -- mysqli_errno — Retourne le dernier code d'erreur produit

### Description

Style orienté objet

int $mysqli->errno;

Style procédural

function mysqli_errno(mysqli `$mysql`): int

Retourne le code erreur pour le dernier appel à une fonction MySQLi qui peut échouer ou réussir en respectant la connexion définie par le paramètre `link`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

La valeur du code erreur pour le dernier appel, s'il échoue. `0` signifie qu'aucune erreur n'est survenue.

### Exemples

Exemple #1 Exemple avec $mysqli->errno

Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if ($mysqli->connect_errno) {
        printf("Échec de la connexion: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Code Erreur : %d\n", $mysqli->errno);
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Code Erreur : %d\n", mysqli_errno($link));
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Code Erreur : 1193

### Voir aussi

- mysqli_connect_errno() - Retourne le code d'erreur du dernier appel de connexion
- mysqli_connect_error() - Retourne une description de la dernière erreur de connexion
- mysqli_error() - Retourne une chaîne décrivant la dernière erreur
- mysqli_sqlstate() - Retourne l'erreur SQLSTATE de la dernière opération MySQL

# mysqli::$error

# mysqli_error

(PHP 5, PHP 7, PHP 8)

mysqli::$error -- mysqli_error — Retourne une chaîne décrivant la dernière erreur

### Description

Style orienté objet

string $mysqli->error;

Style procédural

function mysqli_error(mysqli `$mysql`): string

Retourne la chaîne de caractères décrivant l'erreur survenue lors du dernier appel à une fonction MySQLi, que cet appel ait réussi ou échoué.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Une chaîne de caractères qui décrit l'erreur. Une chaîne de caractères vide si aucune erreur n'est survenue.

### Exemples

Exemple #1 Exemple avec $mysqli->error

Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if ($mysqli->connect_errno) {
        printf("Échec de la connexion: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Message d'erreur : %s\n", $mysqli->error);
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Message d'erreur : %s\n", mysqli_error($link));
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Message d'erreur : Unknown system variable 'a'

### Voir aussi

- mysqli_connect_errno() - Retourne le code d'erreur du dernier appel de connexion
- mysqli_connect_error() - Retourne une description de la dernière erreur de connexion
- mysqli_errno() - Retourne le dernier code d'erreur produit
- mysqli_sqlstate() - Retourne l'erreur SQLSTATE de la dernière opération MySQL

# mysqli::$error_list

# mysqli_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli::$error_list -- mysqli_error_list — Retourne une liste d'erreurs depuis la dernière commande exécutée

### Description

Style orienté objet

array $mysqli->error_list;

Style procédural

function mysqli_error_list(mysqli `$mysql`): array

Retourne un tableau d'erreurs depuis l'appel le plus récent à une fonction MySQLi, qu'elle ait réussi ou non.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Une liste d'erreurs, chacune sous la forme d'un tableau associatif contenant le numéro d'erreur (errno), le message d'erreur (error) et l'état SQL (sqlstate).

### Exemples

Exemple #1 Exemple avec $mysqli->error_list

Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "nobody", "");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("La connexion a échoué : %s\n", mysqli_connect_error());
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        print_r($mysqli->error_list);
    }

    /* Ferme la connexion */
    $mysqli->close();
    ?>

Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("La connexion a échoué : %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        print_r(mysqli_error_list($link));
    }

    /* Ferme la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Array
    (
        [0] => Array
            (
                [errno] => 1193
                [sqlstate] => HY000
                [error] => Unknown system variable 'a'
            )

    )

### Voir aussi

- mysqli_connect_errno() - Retourne le code d'erreur du dernier appel de connexion
- mysqli_connect_error() - Retourne une description de la dernière erreur de connexion
- mysqli_error() - Retourne une chaîne décrivant la dernière erreur
- mysqli_sqlstate() - Retourne l'erreur SQLSTATE de la dernière opération MySQL

# mysqli::execute_query

# mysqli_execute_query

(PHP 8 >= 8.2.0)

mysqli::execute_query -- mysqli_execute_query — Prépare, lie les paramètres et exécute une instruction SQL

### Description

Style orienté objet

public function mysqli::execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool

Style procédural

function mysqli_execute_query(mysqli `$mysql`, string `$query`, ?array `$params` = `null`): mysqli_result|bool

Prépare la requête SQL, lie les paramètres et l'exécute. La méthode mysqli::execute_query() est un raccourci pour mysqli::prepare(), mysqli_stmt::bind_param(), mysqli_stmt::execute(), et mysqli_stmt::get_result().

Le modèle de déclaration peut contenir zéro ou plusieurs marqueurs de paramètres (`?`) également appelés espaces réservés. Les valeurs des paramètres doivent être fournies sous forme de tableau utilisant le paramètre `params`.

Une déclaration préparée est créée sous le capot, mais elle n'est jamais exposée en dehors de la fonction. Il est impossible d'accéder aux propriétés de la déclaration comme on le ferait avec l'objet mysqli_stmt. En raison de cette limitation, les informations d'état sont copiées dans l'objet mysqli et sont disponibles en utilisant ses méthodes, par exemple mysqli_affected_rows() ou mysqli_error().

> Note:

> Dans le cas où une instruction est passée à mysqli_execute_query() qui est plus longue que `max_allowed_packet` du serveur, les codes d'erreur retournés sont différents en fonction du système d'exploitation. Le comportement est le suivant :

> - Sur Linux renvoie un code d'erreur de 1153. Le message d'erreur signifie réception d'un paquet plus grand que `max_allowed_packet` octets (got a packet bigger than `max_allowed_packet` bytes).

> - Sur Windows renvoie un code d'erreur de 2006. Ce message d'erreur signifie le serveur a disparu (server has gone away).

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`query`

  La requête, sous forme de chaîne. Elle doit consister en une seule instruction SQL.

  La déclaration SQL peut contenir zéro ou plusieurs marqueurs de paramètres représentés par un point d'interrogation (`?`) aux positions appropriées.

  > Note:

  > Les marqueurs de paramètres ne sont autorisés que dans certains endroits des instructions SQL. Par exemple, ils sont autorisés dans la liste `VALUES()` d'une instruction `INSERT` (pour spécifier les valeurs de colonnes pour une ligne), ou dans une comparaison avec une colonne dans une clause `WHERE` pour spécifier une valeur de comparaison. Cependant, ils ne sont pas autorisés pour les identifiants (tels que les noms de table ou de colonne).

`params`

  Une liste optionnelle avec autant d'éléments qu'il y a de paramètres liés dans l'instruction SQL en cours d'exécution. Chaque valeur est traitée comme une chaîne de caractères.

### Valeurs de retour

Renvoie `false` en cas d'échec. Pour les requêtes réussies qui produisent un jeu de résultats, telles que `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, renvoie un objet mysqli_result. Pour les autres requêtes réussies, renvoie `true`.

### Exemples

Exemple #1 Exemple de mysqli::execute_query()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = $mysqli->execute_query($query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = mysqli_execute_query($link, $query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Aachen (Nordrhein-Westfalen)
    Augsburg (Baijeri)
    Bergisch Gladbach (Nordrhein-Westfalen)
    Berlin (Berliini)
    Bielefeld (Nordrhein-Westfalen)

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_stmt_execute() - Exécute une requête préparée
- mysqli_stmt_bind_param() - Lie des variables à une requête MySQL
- mysqli_stmt_get_result() - Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result

# mysqli::$field_count

# mysqli_field_count

(PHP 5, PHP 7, PHP 8)

mysqli::$field_count -- mysqli_field_count — Retourne le nombre de colonnes pour la dernière requête

### Description

Style orienté objet

int $mysqli->field_count;

Style procédural

function mysqli_field_count(mysqli `$mysql`): int

Retourne le nombre de colonnes pour la dernière requête sur la connexion spécifiée par le paramètre `mysql`. Cette fonction peut être utile lors de l'utilisation de mysqli_store_result() pour déterminer si la requête aurait dû retourner un résultat vide ou non, sans en connaître la nature.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Un entier représentant le nombre de champs dans un jeu de résultats.

### Exemples

Exemple #1 Exemple avec $mysqli->field_count

Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query( "DROP TABLE IF EXISTS friends");
    $mysqli->query( "CREATE TABLE friends (id int, name varchar(20))");

    $mysqli->query( "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $mysqli->real_query("SELECT * FROM friends");

    if ($mysqli->field_count) {
        /* Une requête SELECT, SHOW ou DESCRIBE */
        $result = $mysqli->store_result();

        /* Récupération du jeu de résultats */
        $row = $result->fetch_row();

        /* Libération du jeu de résultats */
        $result->close();
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "DROP TABLE IF EXISTS friends");
    mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

    mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    mysqli_real_query($link, "SELECT * FROM friends");

    if (mysqli_field_count($link)) {
        /* Une requête SELECT, SHOW ou DESCRIBE */
        $result = mysqli_store_result($link);

        /* Récupération du jeu de résultats */
        $row = mysqli_fetch_row($result);

        /* Libération du jeu de résultats */
        mysqli_free_result($result);
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

# mysqli::get_charset

# mysqli_get_charset

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_charset -- mysqli_get_charset — Retourne un objet représentant le jeu de caractères

### Description

Style orienté objet

public function mysqli::get_charset(): ?object

Style procédural

function mysqli_get_charset(mysqli `$mysql`): ?object

Retourne un objet représentant le jeu de caractères, fournissant différentes propriétés du jeu de caractères courant.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

La fonction retourne un jeu de caractères avec les propriétés suivantes :

`charset`

  Nom du jeu de caractères

`collation`

  Nom de la collation

`dir`

  Le dossier dans lequel la description du jeu de caractères a été récupérée ou "" pour les jeux de caractères internes

`min_length`

  Longueur minimum de caractères, en octets

`max_length`

  Longueur maximale de caractères, en octets

`number`

  Numéro du jeu de caractères interne

`state`

  À partir de PHP 8.2.0, la valeur est toujours `1`

### Exemples

Exemple #1 Exemple avec mysqli::get_charset()

Style orienté objet

    <?php
      $db = mysqli_init();
      $db->real_connect("localhost","root","","test");
      $db->set_charset('latin1');
      var_dump($db->get_charset());
    ?>

Style procédural

    <?php
      $db = mysqli_init();
      mysqli_real_connect($db, "localhost","root","","test");
      mysqli_set_charset($db, 'latin1');
      var_dump(mysqli_get_charset($db));
    ?>

Les exemples ci-dessus vont afficher :

    object(stdClass)#2 (7) {
      ["charset"]=>
      string(6) "latin1"
      ["collation"]=>
      string(17) "latin1_swedish_ci"
      ["dir"]=>
      string(0) ""
      ["min_length"]=>
      int(1)
      ["max_length"]=>
      int(1)
      ["number"]=>
      int(8)
      ["state"]=>
      int(1)
    }

### Voir aussi

- mysqli_character_set_name() - Retourne le jeu de caractères courant pour la connexion
- mysqli_set_charset() - Définit le jeu de caractères du client

# mysqli::$client_info

# mysqli::get_client_info

# mysqli_get_client_info

(PHP 5, PHP 7, PHP 8)

mysqli::$client_info -- mysqli::get_client_info -- mysqli_get_client_info — Récupère des informations sur le client MySQL

### Description

Style orienté objet

string $mysqli->client_info;
#[\Deprecated]
public function mysqli::get_client_info(): string

Style procédural

function mysqli_get_client_info(?mysqli `$mysql` = null): string

Retourne une chaîne de caractères qui représente la version de la bibliothèque cliente MySQL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une chaîne de caractères représentant la version du client utilisé par l'extension MySQL.

### Historique

Version | Description
--- | ---
8.1.0 | L'appel de la mysqli_get_client_info() avec l'argument `mysql` a été déprécié. Cette fonction n'a jamais exigé un paramètre, mais l'a autorisé de manière incorrecte comme paramètre facultatif.
8.1.0 | Le style orienté objet mysqli::get_client_info() a été déprécié.

### Exemples

Exemple #1 Exemple avec mysqli_get_client_info()

    <?php

    /* Vous n'avez pas besoin d'une connexion pour déterminer
        la version du client utilisé par l'extension MySQL */

    printf("Version de la bibliothèque cliente : %s\n", mysqli_get_client_info());
    ?>

### Voir aussi

- mysqli_get_client_version() - Retourne la version du client MySQL sous forme d'un entier
- 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::$client_version

# mysqli_get_client_version

(PHP 5, PHP 7, PHP 8)

mysqli::$client_version -- mysqli_get_client_version — Retourne la version du client MySQL sous forme d'un entier

### Description

Style orienté objet

int $mysqli->client_version;

Style procédural

function mysqli_get_client_version(): int

Retourne la version du client MySQL sous la forme d'un entier.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un nombre qui représente la version de la bibliothèque cliente MySQL dans ce format : `version_principale*10000 + version_mineure *100 + sous_version`. Par exemple, la version 4.1.0 est retournée sous la forme 40100.

Cette fonction est pratique pour déterminer la version de la bibliothèque cliente pour savoir si des fonctionnalités spécifiques existent.

### Exemples

Exemple #1 Exemple avec mysqli_get_client_version()

    <?php

    /* Nous n'avons pas besoin d'une connexion pour
       déterminer la version de la bibliothèque cliente mysql */

    printf("Version de la bibliothèque cliente : %d\n", mysqli_get_client_version());
    ?>

### Voir aussi

- mysqli_get_client_info() - Récupère des informations sur le client MySQL
- 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_connection_stats

# mysqli_get_connection_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::get_connection_stats -- mysqli_get_connection_stats — Retourne des statistiques sur la connexion

### Description

Style orienté objet

public function mysqli::get_connection_stats(): array

Style procédural

function mysqli_get_connection_stats(mysqli `$mysql`): array

Retourne des statistiques sur la connexion du client.

> Note:

> Disponible uniquement avec mysqlnd.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Retourne un tableau avec les statistiques de connexion.

### Exemples

Exemple #1 Exemple avec mysqli_get_connection_stats()

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_connection_stats($link));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Voir aussi

- Description des statistiques

# mysqli::$host_info

# mysqli_get_host_info

(PHP 5, PHP 7, PHP 8)

mysqli::$host_info -- mysqli_get_host_info — Retourne une chaîne contenant le type de connexion utilisée

### Description

Style orienté objet

string $mysqli->host_info;

Style procédural

function mysqli_get_host_info(mysqli `$mysql`): string

mysqli_get_host_info() retourne une chaîne de caractères décrivant la connexion représentée par le paramètre `mysql` (incluant le nom d'hôte du serveur).

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Une chaîne de caractères représentant le nom d'hôte du serveur et le type de connexion.

### Exemples

Exemple #1 Exemple avec $mysqli->host_info

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Affichage des informations sur l'hôte */
    printf("Informations sur l'hôte : %s\n", $mysqli->host_info);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Affichage des informations sur l'hôte */
    printf("Informations sur l'hôte : %s\n", mysqli_get_host_info($link));

Les exemples ci-dessus vont afficher :

    Informations sur l'hôte : Localhost via UNIX socket

### Voir aussi

- mysqli_get_proto_info() - Retourne la version du protocole MySQL utilisé

# mysqli::$protocol_version

# mysqli_get_proto_info

(PHP 5, PHP 7, PHP 8)

mysqli::$protocol_version -- mysqli_get_proto_info — Retourne la version du protocole MySQL utilisé

### Description

Style orienté objet

string $mysqli->protocol_version;

Style procédural

function mysqli_get_proto_info(mysqli `$mysql`): int

Retourne un entier représentant la version du protocole MySQL utilisé par la connexion représentée par le paramètre `mysql`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Retourne un entier représentant la version du protocole.

### Exemples

Exemple #1 Exemple avec $mysqli->protocol_version

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Affichage de la version du protocole */
    printf("Version du protocole : %d\n", $mysqli->protocol_version);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Affichage de la version du protocole */
    printf("Version du protocole : %d\n", mysqli_get_proto_info($link));

Les exemples ci-dessus vont afficher :

    Version du protocole : 10

### Voir aussi

- mysqli_get_host_info() - Retourne une chaîne contenant le type de connexion utilisée

# mysqli::$server_info

# mysqli::get_server_info

# mysqli_get_server_info

(PHP 5, PHP 7, PHP 8)

mysqli::$server_info -- mysqli::get_server_info -- mysqli_get_server_info — Retourne la version du serveur MySQL

### Description

Style orienté objet

string $mysqli->server_info;
public function mysqli::get_server_info(): string

Style procédural

function mysqli_get_server_info(mysqli `$mysql`): string

Retourne une chaîne de caractères représentant la version du serveur MySQL auquel l'extension MySQLi est connectée (représenté par le paramètre `link`).

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Une chaîne de caractères représentant la version du serveur.

### Exemples

Exemple #1 Exemple avec $mysqli->server_info

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Affichage de la version du serveur */
    printf("Version du serveur : %s\n", $mysqli->server_info);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Affichage de la version du serveur */
    printf("Version du serveur : %s\n", mysqli_get_server_info($link));

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Version du serveur : 8.0.21

### Voir aussi

- mysqli_get_client_info() - Récupère des informations sur le client MySQL
- mysqli_get_client_version() - Retourne la version du client MySQL sous forme d'un entier
- mysqli_get_server_version() - Retourne un entier représentant la version du serveur MySQL

# mysqli::$server_version

# mysqli_get_server_version

(PHP 5, PHP 7, PHP 8)

mysqli::$server_version -- mysqli_get_server_version — Retourne un entier représentant la version du serveur MySQL

### Description

Style orienté objet

int $mysqli->server_version;

Style procédural

function mysqli_get_server_version(mysqli `$mysql`): int

La fonction mysqli_get_server_version() retourne un entier représentant la version du serveur sur lequel on est connecté (représenté par le paramètre `mysql`).

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Un entier représentant la version du serveur.

Le format de ce nombre est `main_version * 10000 + minor_version * 100 + sub_version` (c.-à-d. la version 4.1.0 retournera 40100).

### Exemples

Exemple #1 Exemple avec $mysqli->server_version

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Affichage de la version du serveur */
    printf("Version du serveur : %d\n", $mysqli->server_version);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Affichage de la version du serveur */
    printf("Version du serveur : %d\n", mysqli_get_server_version($link));

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Version du serveur : 80021

### Voir aussi

- mysqli_get_client_info() - Récupère des informations sur le client MySQL
- mysqli_get_client_version() - Retourne la version du client MySQL sous forme d'un entier
- mysqli_get_server_info() - Retourne la version du serveur MySQL

# mysqli::get_warnings

# mysqli_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_warnings -- mysqli_get_warnings — Lit le résultat de `SHOW WARNINGS`

### Description

Style orienté objet

public function mysqli::get_warnings(): mysqli_warning|false

Style procédural

function mysqli_get_warnings(mysqli `$mysql`): mysqli_warning|false

Retourne une liste simplement chaînée composée de mysqli_warning ou `false` s'il n'y a aucun avertissement. Chaque objet de la liste correspond à une ligne unique du résultat de `SHOW WARNINGS`. Appeler mysqli_warning::next() remplira l'objet avec les valeurs de la ligne suivante.

> Note: Pour récupérer les messages d'avertissement, il est recommandé d'utiliser la commande SQL `SHOW WARNINGS [LIMIT row_count]` plutôt que cette fonction.

Avertissement

La liste chaînée ne peut pas être réinitialisée ni récupérée à nouveau.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Retourne une liste simplement chaînée composée de mysqli_warning ou `false` s'il n'y a aucun avertissement.

### Exemples

Exemple #1 Parcourir la liste chaînée pour récupérer tous les avertissements

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if ($mysqli->warning_count > 0) {
        $warning = $mysqli->get_warnings();
        if ($warning !== false) {
            do {
                printf("Numéro d'erreur : %s\n", $warning->errno);
                printf("Message : %s\n", $warning->message);
            } while ($warning->next());
        }
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "user", "password", "test");

    mysqli_query($link, "SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if (mysqli_warning_count($link) > 0) {
        $warning = mysqli_get_warnings($link);
        if ($warning !== false) {
            do {
                printf("Numéro d'erreur : %s\n", $warning->errno);
                printf("Message : %s\n", $warning->message);
            } while ($warning->next());
        }
    }

Les exemples ci-dessus vont afficher :

    Numéro d'erreur : 1365
    Message : Division par 0
    Numéro d'erreur : 1292
    Message : Valeur ENTIER incorrecte tronquée : 'NULL'

# mysqli::$info

# mysqli_info

(PHP 5, PHP 7, PHP 8)

mysqli::$info -- mysqli_info — Retourne des informations à propos de la dernière requête exécutée

### Description

Style orienté objet

?string $mysqli->info;

Style procédural

function mysqli_info(mysqli `$mysql`): ?string

La fonction mysqli_info() retourne une chaîne fournissant des informations à propos de la dernière requête exécutée. La nature de cette chaîne est fournie ci-dessous :

Valeurs de retour possibles pour mysqli_info()
Type de requête | Exemple de retour
--- | ---
INSERT INTO...SELECT... | Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO...VALUES (...),(...),(...) | Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ... | Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE ... | Records: 3 Duplicates: 0 Warnings: 0
UPDATE ... | Rows matched: 40 Changed: 40 Warnings: 0

> Note:

> Les requêtes qui ne font pas partie de la liste précédente ne sont pas supportées. Dans cette situation, mysqli_info() retournera une chaîne de caractères vide.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Une chaîne de caractères donnant des informations supplémentaires à propos de la dernière requête exécutée.

### Exemples

Exemple #1 Exemple avec $mysqli->info

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    $mysqli->query("INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", $mysqli->info);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    mysqli_query($link, "INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", mysqli_info($link));

Les exemples ci-dessus vont afficher :

    Records: 150  Duplicates: 0  Warnings: 0

### Voir aussi

- mysqli_affected_rows() - Retourne le nombre de lignes affectées par la dernière opération MySQL
- mysqli_warning_count() - Retourne le nombre d'avertissements générés par la dernière requête exécutée
- mysqli_num_rows() - Retourne le nombre de lignes dans le jeu de résultats

# mysqli::init

# mysqli_init

(PHP 5, PHP 7, PHP 8)

mysqli::init -- mysqli_init — Initialise MySQLi et retourne un objet à utiliser avec mysqli_real_connect()

### Description

Style orienté objet

#[\Deprecated]
public function mysqli::init(): ?bool

Style procédural

function mysqli_init(): mysqli|false

Alloue ou initialise un objet MySQL utilisable pour les fonctions mysqli_options() et mysqli_real_connect().

> Note:

> Tous les appels suivants à n'importe quelle fonction MySQLi (exceptée de mysqli_options() et mysqli_ssl_set()) échoueront en attendant que la fonction mysqli_real_connect() soit appelée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

mysqli::init() retourne `null` en cas de succès, ou `false` si une erreur survient. mysqli_init() renvoie un objet en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La méthode mysqli::init() de style orienté objet a été dépréciée. Remplacez les appels à parent::init() par parent::__construct().

### Exemples

Voir mysqli_real_connect().

### Voir aussi

- mysqli_options() - Définit les options
- mysqli_close() - Ferme une connexion
- mysqli_real_connect() - Ouvre une connexion à un serveur MySQL
- mysqli_connect() - Alias de mysqli::__construct

# mysqli::$insert_id

# mysqli_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli::$insert_id -- mysqli_insert_id — Retourne la valeur générée pour une colonne AUTO_INCREMENT par la dernière requête

### Description

Style orienté objet

int|string $mysqli->insert_id;

Style procédural

function mysqli_insert_id(mysqli `$mysql`): int|string

Retourne l'ID généré par une requête `INSERT` ou `UPDATE` sur une table avec une colonne ayant l'attribut `AUTO_INCREMENT`. Dans le cas des requêtes multilignes `INSERT`, ceci retourne la première valeur automatiquement générée qui a été insérée avec succès.

Exécuter une requête `INSERT` ou `UPDATE` utilisant la fonction MySQL `LAST_INSERT_ID()` modifiera aussi la valeur retournée par mysqli_insert_id(). Si `LAST_INSERT_ID(expr)` a été utilisé pour générer la valeur de `AUTO_INCREMENT`, ceci retourne la valeur de la dernière `expr` à la place de la valeur générée de `AUTO_INCREMENT`.

Retourne `0` si la requête précédente n'a pas changé la valeur de `AUTO_INCREMENT`. mysqli_insert_id() doit être appelé immédiatement après que la requête ait généré la valeur.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

La valeur du champ `AUTO_INCREMENT` modifiée par la dernière requête. Retourne zéro s'il n'y a pas eu de requête sur la connexion ou si la dernière requête n'a pas modifié la valeur de l'`AUTO_INCREMENT`.

Seules les requêtes émises par la connexion courante affectent la valeur de retour. La valeur n'est pas affectée par les requêtes utilisant d'autres connexions ou clients.

> Note:

> Si le nombre est plus grand que la valeur maximale d'un entier, elle sera retournée sous forme de chaîne de caractères.

### Exemples

Exemple #1 Exemple avec $mysqli->insert_id

Style orienté objet

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    $mysqli->query($query);

    printf("Le nouvel enregistrement a l'ID %d.\n", $mysqli->insert_id);

    /* Supprime la table */
    $mysqli->query("DROP TABLE myCity");
    ?>

Style procédural

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    mysqli_query($link, $query);

    printf("Le nouvel enregistrement a l'ID %d.\n", mysqli_insert_id($link));

    /* Supprime la table */
    mysqli_query($link, "DROP TABLE myCity");
    ?>

Les exemples ci-dessus vont afficher :

    Le nouvel enregistrement a l'ID 1.

# mysqli::kill

# mysqli_kill

(PHP 5, PHP 7, PHP 8)

mysqli::kill -- mysqli_kill — Demande au serveur de terminer un thread MySQL

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.4.0. Dépendre de cette fonction est fortement déconseillé.

### Description

Style orienté objet

#[\Deprecated]
public function mysqli::kill(int `$process_id`): bool

Style procédural

#[\Deprecated]
function mysqli_kill(mysqli `$mysql`, int `$process_id`): bool

mysqli_kill() est utilisée pour demander au serveur de terminer un thread MySQL spécifié par le paramètre `process_id`. Cette valeur doit être obtenue en appelant la fonction mysqli_thread_id().

Pour arrêter une requête en cours d'exécution, utiliser la commande SQL `KILL QUERY process_id`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
8.4.0 | Les méthodes mysqli::kill() et mysqli_kill() sont désormais obsolètes. Utiliser plutôt la commande SQL `KILL`.

### Exemples

Exemple #1 Exemple avec mysqli::kill()

Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    /* Détermine l'id du thread */
    $thread_id = $mysqli->thread_id;

    /* Termine le thread */
    $mysqli->kill($thread_id);

    /* Ceci devrait produire une erreur */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Erreur : %s\n", $mysqli->error);
        exit;
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    /* Détermine l'id du thread */
    $thread_id = mysqli_thread_id($link);

    /* Termine le thread */
    mysqli_kill($link, $thread_id);

    /* Ceci devrait produire une erreur */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Erreur : %s\n", mysqli_error($link));
        exit;
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Erreur : MySQL server has gone away

### Voir aussi

- mysqli_thread_id() - Retourne l'identifiant du thread pour la connexion courante

# mysqli::more_results

# mysqli_more_results

(PHP 5, PHP 7, PHP 8)

mysqli::more_results -- mysqli_more_results — Vérifie s'il y a d'autres jeux de résultats MySQL disponibles

### Description

Style orienté objet

public function mysqli::more_results(): bool

Style procédural

function mysqli_more_results(mysqli `$mysql`): bool

Indique si un ou plusieurs jeux de résultats sont disponibles, générés par un appel antérieur à mysqli_multi_query().

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Retourne `true` si un ou plusieurs jeux de résultats (incluant les erreurs) sont disponibles à partir d'un précédent appel à la fonction mysqli_multi_query(), `false` sinon.

### Exemples

Voir mysqli_multi_query().

### Voir aussi

- mysqli_multi_query() - Exécute une ou plusieurs requêtes sur la base de données
- mysqli_next_result() - Prépare le prochain résultat d'une requête multiple
- mysqli_store_result() - Transfère un jeu de résultats à partir de la dernière requête
- mysqli_use_result() - Initialise la récupération d'un jeu de résultats

# mysqli::multi_query

# mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — Exécute une ou plusieurs requêtes sur la base de données

### Description

Style orienté objet

public function mysqli::multi_query(string `$query`): bool

Style procédural

function mysqli_multi_query(mysqli `$mysql`, string `$query`): bool

Exécute une ou plusieurs requêtes, rassemblées dans le paramètre `query` par des points-virgules.

Avertissement

# Avertissement de Sécurité : injection SQL

Si la requête contiens des variables d'entrées alors des déclarations préparées paramétrisées devrait être utilisé à la place. Alternativement, les données doivent être correctement formatées et toutes les chaînes de caractères doivent être échappées en utilisant la fonction mysqli_real_escape_string().

Les requêtes sont envoyées en un seul appel à la base de données et traitées séquentiellement. mysqli_multi_query() attend que la première requête soit terminée avant de rendre le contrôle à PHP. Entre-temps, le serveur MySQL continue de traiter les requêtes restantes de manière asynchrone par rapport à PHP et rend les résultats disponibles pour la récupération.

Il est recommandé d'utiliser une do-while pour traiter plusieurs requêtes. La connexion sera occupée jusqu'à ce que toutes les requêtes soient complétées et que leur résultat soit récupéré par PHP. Aucune autre requête ne peut être émise sur la même connexion, jusqu'à ce que toutes les requêtes soient traitées. Pour traiter la prochaine requête dans la suite, utiliser mysqli_next_result(). Si le prochain résultat n'est pas encore prêt mysqli attendra pour la réponse depuis le serveur MySQL. Pour vérifier s'il y a plus de résultats, utiliser mysqli_more_results().

Pour les requêtes qui produisent un jeu de résultat, tel que `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, mysqli_use_result() ou mysqli_store_result() peut être utilisé pour récupérer le jeu de résultat. Pour les requêtes qui ne produisent pas de jeu de résultat, les mêmes fonctions peuvent être utilisées pour récupérer les informations telles que le nombre de lignes affectées.

Astuce

Exécuter une requête `CALL` pour les procédures stockées peut produire plusieurs jeux de résultats. Si la procédure stockée contient des requêtes `SELECT`, les jeux de résultats sont retournés dans l'ordre dans lequel ils sont produits par l'exécution de la procédure. En général, l'appeleur ne peut pas savoir combien de jeux de résultats une procédure retournera et doit être préparé à récupérer plusieurs résultats. Le résultat final de la procédure est un résultat de statut qui n'inclut pas de jeu de résultat. Le statut indique si la procédure a succédé ou si une erreur s'est produite.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`query`

  Une chaîne de caractères contenant les requêtes à exécuter. Plusieurs requêtes doivent être séparées par un point-virgule.

### Valeurs de retour

Retourne `false` uniquement si la première requête échoue. Pour récupérer les sous-séquences d'erreurs issues des autres requêtes, il faut appeler d'abord la fonction mysqli_next_result().

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Exemple avec mysqli::multi_query()

Style orienté objet

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Exécution d'une requête multiple */
    $mysqli->multi_query($query);
    do {
        /* Stockage du jeu de résultats dans PHP */
        if ($result = $mysqli->store_result()) {
            while ($row = $result->fetch_row()) {
                printf("%s\n", $row[0]);
            }
        }
        /* Affichage d'une séparation */
        if ($mysqli->more_results()) {
            printf("-----------------\n");
        }
    } while ($mysqli->next_result());
    ?>

Style procédural

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Exécution d'une requête multiple */
    mysqli_multi_query($link, $query);
    do {
        /* Stockage du jeu de résultats dans PHP */
        if ($result = mysqli_store_result($link)) {
            while ($row = mysqli_fetch_row($result)) {
                printf("%s\n", $row[0]);
            }
        }
        /* Affichage d'une séparation */
        if (mysqli_more_results($link)) {
            printf("-----------------\n");
        }
    } while (mysqli_next_result($link));
    ?>

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Voir aussi

- mysqli_query() - Exécute une requête sur la base de données
- mysqli_use_result() - Initialise la récupération d'un jeu de résultats
- mysqli_store_result() - Transfère un jeu de résultats à partir de la dernière requête
- mysqli_next_result() - Prépare le prochain résultat d'une requête multiple
- mysqli_more_results() - Vérifie s'il y a d'autres jeux de résultats MySQL disponibles

# mysqli::next_result

# mysqli_next_result

(PHP 5, PHP 7, PHP 8)

mysqli::next_result -- mysqli_next_result — Prépare le prochain résultat d'une requête multiple

### Description

Style orienté objet

public function mysqli::next_result(): bool

Style procédural

function mysqli_next_result(mysqli `$mysql`): bool

Prépare le prochain jeu de résultat, initialisé par un appel antérieur à mysqli_multi_query(), et qui peut être lu par mysqli_store_result() ou mysqli_use_result().

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient. Retourne aussi `false` si la prochaine déclaration résulte en une erreur, pas comme mysqli_more_results().

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Voir mysqli_multi_query().

### Voir aussi

- mysqli_multi_query() - Exécute une ou plusieurs requêtes sur la base de données
- mysqli_more_results() - Vérifie s'il y a d'autres jeux de résultats MySQL disponibles
- mysqli_store_result() - Transfère un jeu de résultats à partir de la dernière requête
- mysqli_use_result() - Initialise la récupération d'un jeu de résultats

# mysqli::options

# mysqli_options

(PHP 5, PHP 7, PHP 8)

mysqli::options -- mysqli_options — Définit les options

### Description

Style orienté objet

public function mysqli::options(int `$option`, string|int `$value`): bool

Style procédural

function mysqli_options(mysqli `$mysql`, int `$option`, string|int `$value`): bool

Utile pour définir des options de connexion et ainsi affecter le comportement de la connexion courante.

Cette fonction peut être appelée plusieurs fois pour définir plusieurs options.

mysqli_options() doit être appelée après mysqli_init() et avant mysqli_real_connect().

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`option`

  L'option qu'on veut définir. Il peut prendre une des valeurs suivantes :

  Options valides
  Nom | Description
  --- | ---
  `MYSQLI_OPT_CONNECT_TIMEOUT` | Délai maximal de la connexion en secondes
  `MYSQLI_OPT_READ_TIMEOUT` | Résultat d'exécution durée d'expiration d'une commande en secondes. Disponible à partir de PHP 7.2.0.
  `MYSQLI_OPT_LOCAL_INFILE` | Active/désactive l'utilisation de `LOAD LOCAL INFILE`
  `MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` | Répertoire à utiliser pour `LOAD DATA LOCAL INFILE`.
  `MYSQLI_INIT_COMMAND` | Commande à exécuter après la connexion au serveur MySQL
  `MYSQLI_SET_CHARSET_NAME` | Le jeu de caractère à définir par défaut.
  `MYSQLI_READ_DEFAULT_FILE` | Lit les options depuis le nom de l'option plutôt que du fichier my.cnf Pas supporté par mysqlnd
  `MYSQLI_READ_DEFAULT_GROUP` | Lit les options du groupe depuis my.cnf ou depuis le fichier spécifié avec `MYSQL_READ_DEFAULT_FILE`. Pas supporté par mysqlnd
  `MYSQLI_SERVER_PUBLIC_KEY` | Fichier contenant la clé publique RSA utilisée avec l'authentification basée sur SHA-256.
  `MYSQLI_OPT_NET_CMD_BUFFER_SIZE` | La taille du buffer interne de commande/réseau. Uniquement valide pour mysqlnd.
  `MYSQLI_OPT_NET_READ_BUFFER_SIZE` | Taille, en octets, maximale de la partie à lire lors de la lecture du corps d'un paquet de commande MySQL. Uniquement valide pour mysqlnd.
  `MYSQLI_OPT_INT_AND_FLOAT_NATIVE` | Convertit les colonnes entières et à virgules flottantes en nombres PHP lors de l'utilisation de déclarations non préparées. Valable uniquement pour mysqlnd.
  `MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` | Si le certificat de serveur doit être vérifié ou non.
  `MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` | Si le client doit accepter les mots de passe expirés.
  `1` | Si la compression de communication réseau doit être utilisée.

`value`

  La valeur pour l'option.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Voir mysqli_real_connect().

### Notes

> Note: MySQLnd s'occupe toujours du jeu de caractères par défaut du serveur. Celui-ci est envoyé durant la négociation de la connexion ou l'authentification.Libmysqlclient utilise le jeu de caractères par défaut de my.cnf ou via par un appel à mysqli_options() avant mysqli_real_connect(), mais après mysqli_init().

### Voir aussi

- mysqli_init() - Initialise MySQLi et retourne un objet à utiliser avec mysqli_real_connect()
- mysqli_real_connect() - Ouvre une connexion à un serveur MySQL

# mysqli::ping

# mysqli_ping

(PHP 5, PHP 7, PHP 8)

mysqli::ping -- mysqli_ping — Ping la connexion au serveur et reconnecte si elle n'existe plus

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.4.0. Dépendre de cette fonction est fortement déconseillé.

### Description

Style orienté objet

#[\Deprecated]
public function mysqli::ping(): bool

Style procédural

#[\Deprecated]
function mysqli_ping(mysqli `$mysql`): bool

Vérifie si la connexion au serveur fonctionne correctement. Si elle a été refermée et que l'option globale mysqli.reconnect est activée, une reconnexion automatique est tentée.

> Note: Le paramètre php.ini mysqli.reconnect est ignoré par le pilote mysqlnd, donc les reconnexions automatique ne sont jamais tentées.

Cette fonction peut être utilisée pour que les clients qui restent longtemps ouverts sans action puissent vérifier que la connexion n'a pas été refermée par le serveur, et, le cas échéant, faire une reconnexion automatique.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
8.4.0 | Les méthodes mysqli::ping() et mysqli_ping() sont désormais obsolètes. La fonctionnalité `reconnect` n'est plus disponible à partir de PHP 8.2.0, rendant cette fonction obsolète.

### Exemples

Exemple #1 Exemple avec mysqli::ping()

Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if ($mysqli->connect_errno) {
        printf("Échec de la connexion : %s\n", $mysqli->connect_error);
        exit();
    }

    /* Vérification si la connexion est toujours active */
    if ($mysqli->ping()) {
        printf ("La connexion est Ok !\n");
    } else {
        printf ("Erreur : %s\n", $mysqli->error);
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    /* Vérification si la connexion est toujours active */
    if (mysqli_ping($link)) {
        printf ("La connexion est Ok !\n");
    } else {
        printf ("Erreur : %s\n", mysqli_error($link));
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    La connexion est Ok !

# mysqli::poll

# mysqli_poll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::poll -- mysqli_poll — Vérifie l'état de la connexion

### Description

Style orienté objet

public static function mysqli::poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Style procédural

function mysqli_poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Vérifie l'état de la connexion. La méthode peut être utilisée comme statique.

> Note:

> Disponible uniquement avec mysqlnd.

### Liste de paramètres

`read`

  Liste des connexions à vérifier pour les résultats exceptionnels qui peuvent être lus.

`error`

  Liste des connexions sur lesquelles une erreur est survenue, par exemple, des échecs de requêtes, ou des pertes de connexion.

`reject`

  Liste des connexions rejetées car des requêtes non-asynchrones y ont été exécutées et pour lesquelles la fonction pourrait sortir des résultats.

`seconds`

  Nombre de secondes d'attente maximale, doit être positif.

`microseconds`

  Nombre de micro-secondes d'attente maximale, doit être positif.

### Valeurs de retour

Retourne le nombre de connexions disponibles en cas de succès, `false` sinon.

### Erreurs / Exceptions

Une ValueError est lancée lorsque ni l'argument `read` ni l'argument `error` ne sont transmis.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une exception ValueError lorsque ni l'argument `read` ni l'argument `error` ne sont transmis.

### Exemples

Exemple #1 Exemple avec mysqli_poll()

    <?php
    $link1 = mysqli_connect();
    $link1->query("SELECT 'test'", MYSQLI_ASYNC);
    $all_links = array($link1);
    $processed = 0;
    do {
        $links = $errors = $reject = array();
        foreach ($all_links as $link) {
            $links[] = $errors[] = $reject[] = $link;
        }
        if (!mysqli_poll($links, $errors, $reject, 1)) {
            continue;
        }
        foreach ($links as $link) {
            if ($result = $link->reap_async_query()) {
                print_r($result->fetch_row());
                if (is_object($result))
                    mysqli_free_result($result);
            } else die(sprintf("Erreur MySQLi : %s", mysqli_error($link)));
            $processed++;
        }
    } while ($processed < count($all_links));
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => test
    )

### Voir aussi

- mysqli_query() - Exécute une requête sur la base de données
- mysqli_reap_async_query() - Lit un résultat pour une requête asynchrone

# mysqli::prepare

# mysqli_prepare

(PHP 5, PHP 7, PHP 8)

mysqli::prepare -- mysqli_prepare — Prépare une requête SQL pour l'exécution

### Description

Style orienté objet

public function mysqli::prepare(string `$query`): mysqli_stmt|false

Style procédural

function mysqli_prepare(mysqli `$mysql`, string `$query`): mysqli_stmt|false

Prépare la requête SQL et retourne un gestionnaire de requête à utiliser pour les futures opérations sur la requête. La requête doit être composée d'une seule requête SQL.

Les paramètres de marques doivent être liés à des variables utilisées dans les fonctions mysqli_stmt_bind_param() et/ou mysqli_stmt_bind_result() avant d'exécuter la requête ou de récupérer les lignes.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`query`

  La requête, sous la forme d'une chaîne de caractères.

  Ce paramètre peut inclure un ou plusieurs paramètres de marques dans la requête SQL avec le caractère "point d'interrogation" (`?`) à la position appropriée.

  > Note:

  > Les marques sont autorisées uniquement dans certains endroits des requêtes SQL. Par exemple, elles le sont dans la liste `VALUES()` d'une requête `INSERT` (pour spécifier les valeurs des colonnes pour une ligne), ou dans une comparaison d'une clause `WHERE` pour spécifier une valeur de comparaison. Cependant, elles ne sont pas autorisées pour les identifiants (de tables ou de colonnes).

### Valeurs de retour

mysqli_prepare() retourne un objet de traitement ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Exemple avec mysqli::prepare()

Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $city = "Amersfoort";

    /* Crée une requête préparée */
    if ($stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?")) {

        /* Lecture des marqueurs */
        $stmt->bind_param("s", $city);

        /* Exécution de la requête */
        $stmt->execute();

        /* Lecture des variables résultantes */
        $stmt->bind_result($district);

        /* Récupération des valeurs */
        $stmt->fetch();

        printf("%s est dans le district de %s\n", $city, $district);

        /* Fermeture du traitement */
        $stmt->close();
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $city = "Amersfoort";

    /* Crée une requête préparée */
    if ($stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?")) {

        /* Lecture des marqueurs */
        mysqli_stmt_bind_param($stmt, "s", $city);

        /* Exécution de la requête */
        mysqli_stmt_execute($stmt);

        /* Lecture des variables résultantes */
        mysqli_stmt_bind_result($stmt, $district);

        /* Récupération des valeurs */
        mysqli_stmt_fetch($stmt);

        printf("%s est dans le district de %s\n", $city, $district);

        /* Fermeture du traitement */
        mysqli_stmt_close($stmt);
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Amersfoort est dans le district de Utrecht

### Voir aussi

- 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_bind_param() - Lie des variables à une requête MySQL
- mysqli_stmt_bind_result() - Lie des variables à un jeu de résultats
- mysqli_stmt_get_result() - Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result
- mysqli_stmt_close() - Termine une requête préparée

# mysqli::query

# mysqli_query

(PHP 5, PHP 7, PHP 8)

mysqli::query -- mysqli_query — Exécute une requête sur la base de données

### Description

Style orienté objet

public function mysqli::query(string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Style procédural

function mysqli_query(mysqli `$mysql`, string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Exécute une requête sur la base de données.

Avertissement

# Avertissement de Sécurité : injection SQL

Si la requête contiens des variables d'entrées alors des déclarations préparées paramétrisées devrait être utilisé à la place. Alternativement, les données doivent être correctement formatées et toutes les chaînes de caractères doivent être échappées en utilisant la fonction mysqli_real_escape_string().

Pour les requêtes non-DML (qui n'est pas un INSERT, un UPDATE ou un DELETE), cette fonction est similaire à appeler mysqli_real_query() suivie de mysqli_use_result() ou mysqli_store_result().

> Note:

> Si on passe une requête à mysqli_query() qui est plus longue que `max_allowed_packet`, les codes d'erreur en retour seront différents selon que l'on utilise MySQL Native Driver (`mysqlnd`) ou la MySQL Client Library (`libmysqlclient`). Le comportement est défini comme suit:

> - `mysqlnd` sur Linux retourne un code d'erreur de 1153. Le message d'erreur sera got a packet bigger than `max_allowed_packet` bytes.

> - `mysqlnd` sur Windows retourne un code d'erreur de 2006. Le message sera du type server has gone away.

> - `libmysqlclient` sur toute plateforme retourne le code d'erreur 2006. Le message sera du type server has gone away.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`query`

  La requête, sous la forme d'une chaîne de caractères.

`result_mode`

  Le mode de résultat peut être l'une des 3 constantes indiquant comment le résultat sera retourné par le serveur MySQL.

  `MYSQLI_STORE_RESULT` (par défaut) - renvoie un objet mysqli_result avec un ensemble de résultats mis en mémoire tampon.

  `MYSQLI_USE_RESULT` - renvoie un objet mysqli_result avec un ensemble de résultats non tamponnés. Tant qu'il y a des enregistrements en attente d'être récupérés, la ligne de connexion sera occupée et tous les appels suivants renverront l'erreur `Commands out of sync`. Pour éviter l'erreur, tous les enregistrements doivent être récupérés du serveur ou l'ensemble de résultats doit être écarté en appelant la mysqli_free_result().

  `MYSQLI_ASYNC` (disponible avec mysqlnd) - la requête est exécutée de manière asynchrone et aucun ensemble de résultats n'est immédiatement renvoyé. mysqli_poll() est alors utilisée pour obtenir les résultats de telles requêtes. Utilisée en combinaison avec la constante `MYSQLI_STORE_RESULT` ou `MYSQLI_USE_RESULT`.

### Valeurs de retour

Retourne `false` en cas d'échec. Pour des requêtes réussies qui produisent un jeu de résultat tel que `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, mysqli_query() retourne un objet mysqli_result. Pour les autres types de requêtes ayant réussi, mysqli_query() retourne `true`.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Exemple avec mysqli::query()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* "Create table" ne retourne aucun jeu de résultats */
    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Table myCity créée avec succès.\n");

    /* Requête "Select" retourne un jeu de résultats */
    $result = $mysqli->query("SELECT Name FROM City LIMIT 10");
    printf("Select a retourné %d lignes.\n", $result->num_rows);

    /* Si nous avons à récupérer beaucoup de données, nous utilisons MYSQLI_USE_RESULT */
    $result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Notez que nous ne pouvons exécuter aucune fonction qui agit sur le serveur tant que
        le jeu de résultats n'est pas clos. Tous les appels retournent un 'out of sync' */
    $mysqli->query("SET @a:='this will not work'");

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* "Create table" ne retourne aucun jeu de résultats */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Table myCity créée avec succès.\n");

    /* Requête "Select" retourne un jeu de résultats */
    $result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
    printf("Select a retourné %d lignes.\n", mysqli_num_rows($result));

    /* Si nous avons à récupérer beaucoup de données, nous utilisons MYSQLI_USE_RESULT */
    $result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Notez que nous ne pouvons exécuter aucune fonction qui agit sur le serveur tant que
        le jeu de résultats n'est pas clos. Tous les appels retournent un 'out of sync' */
    mysqli_query($link, "SET @a:='this will not work'");

Les exemples ci-dessus vont afficher :

    Table myCity créée avec succès.
    Select a retourné 10 lignes.
    Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in...

### Voir aussi

- mysqli_execute_query() - Prépare, lie les paramètres et exécute une instruction SQL
- mysqli_real_query() - Exécute une requête SQL
- mysqli_multi_query() - Exécute une ou plusieurs requêtes sur la base de données
- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_free_result() - Libère la mémoire associée à un résultat

# mysqli::real_connect

# mysqli_real_connect

(PHP 5, PHP 7, PHP 8)

mysqli::real_connect -- mysqli_real_connect — Ouvre une connexion à un serveur MySQL

### Description

Style orienté objet

public function mysqli::real_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

Style procédural

function mysqli_real_connect(
mysqli `$mysql`,
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

Ouvre une connexion au serveur de base de données MySQL avec des options de connexion optionnelles.

Cette fonction diffère de mysqli_connect() :

- mysqli_real_connect() nécessite un objet valide qui doit être créé par la fonction mysqli_init().

- Il y a un paramètre `flags`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`hostname`

  Peut être un nom d'hôte ou une adresse IP. Lorsqu'on passe `null`, la valeur est récupérée depuis mysqli.default_host. Si possible, des pipes seront utilisés au lieu du protocole TCP/IP. Le protocole TCP/IP est utilisé si un nom d'hôte et un numéro de port sont fournis ensemble, par exemple `localhost:3308`.

`username`

  Le nom d'utilisateur MySQL ou `null` pour supposer le nom d'utilisateur en fonction de l'option ini mysqli.default_user.

`password`

  Le mot de passe MySQL ou `null` pour supposer le mot de passe en fonction de l'option ini mysqli.default_pw.

`database`

  La base de données par défaut à utiliser lors de l'exécution de requêtes ou `null`.

`port`

  Le numéro de port auquel tenter de se connecter au serveur MySQL ou `null` pour supposer le port en fonction de l'option ini mysqli.default_port.

`socket`

  Le socket ou le pipe nommé qui devrait être utilisé, ou `null` pour supposer le socket en fonction de l'option ini mysqli.default_socket.

  > Note:

  > Spécifier explicitement le paramètre `socket` ne détermine pas le type de méthode utilisée lors de la connexion à MySQL. La méthode est déterminée par le paramètre `hostname`.

`flags`

  Avec le paramètre `flags`, il est possible de configurer différentes directives de connexion :

  Options supportées
  Nom | Description
  --- | ---
  `MYSQLI_CLIENT_COMPRESS` | Utilise le protocole compressé
  `MYSQLI_CLIENT_FOUND_ROWS` | Retourne le nombre de lignes trouvées, pas le nombre de lignes affectées.
  `MYSQLI_CLIENT_IGNORE_SPACE` | Autorise les espaces entre les noms de fonctions et les arguments. Cela force les noms de fonctions à être des mots réservés.
  `MYSQLI_CLIENT_INTERACTIVE` | Autorise `interactive_timeout` secondes (au lieu de `wait_timeout` secondes) d'inactivité avant de fermer la connexion.
  `MYSQLI_CLIENT_SSL` | Utilise le chiffrement SSL
  `MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` | Identique à `MYSQLI_CLIENT_SSL`, mais désactive la validation des certificats SSL fournis. Cette constante n'est prévue que pour les installations utilisant le driver MySQL natif et MySQL 5.6 ou supérieur.

  > Note:

  > Pour des raisons de sécurité, l'option `MULTI_STATEMENT` n'est pas supportée en PHP. Pour exécuter plusieurs commandes, utiliser la fonction mysqli_multi_query().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
7.4.0 | Tous les paramètres sont désormais nullable.

### Exemples

Exemple #1 Exemple avec mysqli::real_connect()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_init();

    $mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    $mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    $mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Succès... ' . $mysqli->host_info . "\n";

Style orienté objet, avec extension de la classe mysqli

    <?php

    class foo_mysqli extends mysqli {
        public function __construct($host, $user, $pass, $db)
        {
            parent::__construct();

            parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
            parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

            parent::real_connect($host, $user, $pass, $db, null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);
        }
    }

    $db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');

    echo 'Succès... ' . $db->host_info . "\n";

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_init();

    mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Succès... ' . mysqli_get_host_info($link) . "\n";

Les exemples ci-dessus vont afficher :

    Succès... MySQL host info: localhost via TCP/IP

### Notes

> Note: MySQLnd s'occupe toujours du jeu de caractères par défaut du serveur. Celui-ci est envoyé durant la négociation de la connexion ou l'authentification.Libmysqlclient utilise le jeu de caractères par défaut de my.cnf ou via par un appel à mysqli_options() avant mysqli_real_connect(), mais après mysqli_init().

### Voir aussi

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_init() - Initialise MySQLi et retourne un objet à utiliser avec mysqli_real_connect()
- mysqli_options() - Définit les options
- mysqli_ssl_set() - Utilisée pour établir une connexion sécurisée avec SSL
- mysqli_close() - Ferme une connexion

# mysqli::real_escape_string

# mysqli_real_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::real_escape_string -- 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

### Description

Style orienté objet

public function mysqli::real_escape_string(string `$string`): string

Style procédural

function mysqli_real_escape_string(mysqli `$mysql`, string `$string`): string

Cette fonction est utilisée pour créer une chaîne SQL valide qui pourra être utilisée dans une requête SQL. La chaîne de caractères `string` est encodée pour produire une chaîne SQL échappée, en tenant compte du jeu de caractères courant de la connexion.

Attention

# Sécurité : Le jeu de caractères par défaut

Le jeu de caractères doit être défini soit au niveau serveur, soit avec la fonction API mysqli_set_charset() pour qu'il affecte la fonction mysqli_real_escape_string(). Voir la section sur les concepts des jeux de caractères pour plus d'informations.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`string`

  La chaîne de caractères à échapper.

  Les caractères encodés sont `NUL (ASCII 0)`, `\n`, `\r`, `\`, `'`, `"`, et ``CTRL`+`Z``.

### Valeurs de retour

Retourne une chaîne de caractères échappée.

### Exemples

Exemple #1 Exemple avec mysqli::real_escape_string()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* Cette requête avec $city échappé fonctionnera */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        $mysqli->real_escape_string($city));
    $result = $mysqli->query($query);
    printf("Select a retourné %d lignes.\n", $result->num_rows);

    /* Cette requête échouera, car $city n'a pas été échappé */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = $mysqli->query($query);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* Cette requête avec $city échappé fonctionnera */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        mysqli_real_escape_string($mysqli, $city));
    $result = mysqli_query($mysqli, $query);
    printf("Select a retourné %d lignes.\n", mysqli_num_rows($result));

    /* Cette requête échouera, car $city n'a pas été échappé */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = mysqli_query($mysqli, $query);

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Select a retourné 1 lignes.

    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 's-Hertogenbosch'' at line 1 in...

### Voir aussi

- mysqli_set_charset() - Définit le jeu de caractères du client

# mysqli::real_query

# mysqli_real_query

(PHP 5, PHP 7, PHP 8)

mysqli::real_query -- mysqli_real_query — Exécute une requête SQL

### Description

Style orienté objet

public function mysqli::real_query(string `$query`): bool

Style procédural

function mysqli_real_query(mysqli `$mysql`, string `$query`): bool

Exécute une seule requête sur la connexion à la base de données représentée par le paramètre `link` dont le résultat peut être récupéré ou stocké en utilisant les fonctions mysqli_store_result() ou mysqli_use_result().

Avertissement

# Avertissement de Sécurité : injection SQL

Si la requête contiens des variables d'entrées alors des déclarations préparées paramétrisées devrait être utilisé à la place. Alternativement, les données doivent être correctement formatées et toutes les chaînes de caractères doivent être échappées en utilisant la fonction mysqli_real_escape_string().

Pour déterminer si une requête donnée aurait dû retourner un jeu de résultats ou non, voir la fonction mysqli_field_count().

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`query`

  La requête chaîne de caractères.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Voir aussi

- mysqli_query() - Exécute une requête sur la base de données
- mysqli_store_result() - Transfère un jeu de résultats à partir de la dernière requête
- mysqli_use_result() - Initialise la récupération d'un jeu de résultats

# mysqli::reap_async_query

# mysqli_reap_async_query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::reap_async_query -- mysqli_reap_async_query — Lit un résultat pour une requête asynchrone

### Description

Style orienté objet

public function mysqli::reap_async_query(): mysqli_result|bool

Style procédural

function mysqli_reap_async_query(mysqli `$mysql`): mysqli_result|bool

Lit le résultat pour une requête asynchrone.

> Note:

> Disponible uniquement avec mysqlnd.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Retourne `false` en cas d'échec. Pour des requêtes réussies qui produisent un jeu de résultat tel que `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, mysqli_reap_async_query() retournera un objet mysqli_result. Pour les autres types de requêtes ayant réussi, mysqli_reap_async_query() retournera `true`.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Voir aussi

- mysqli_poll() - Vérifie l'état de la connexion

# mysqli::refresh

# mysqli_refresh

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::refresh -- mysqli_refresh — Rafraîchit

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.4.0. Dépendre de cette fonction est fortement déconseillé.

### Description

Style orienté objet

#[\Deprecated]
public function mysqli::refresh(int `$flags`): bool

Style procédural

#[\Deprecated]
function mysqli_refresh(mysqli `$mysql`, int `$flags`): bool

Rafraîchit les tables ou les caches, ou ré-initialise les informations du serveur de réplication.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`flags`

  Les options de rafraîchissement, en utilisant les constantes MYSQLI_REFRESH_* telles que documentées dans la documentation sur les constantes MySQLi.

  Voir aussi la documentation officielle sur » le rafraîchissement en MySQL.

### Valeurs de retour

`true` si le rafraîchissement s'est déroulé avec succès, `false` sinon.

### Historique

Version | Description
--- | ---
8.4.0 | Les méthodes mysqli::refresh() et mysqli_refresh() sont désormais obsolètes. Utiliser les commandes SQL `FLUSH` à la place.

### Voir aussi

- mysqli_poll() - Vérifie l'état de la connexion

# mysqli::release_savepoint

# mysqli_release_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::release_savepoint -- mysqli_release_savepoint — Supprime le point de sauvegarde nommé du jeu des points de sauvegarde de la transaction courante

### Description

Style orienté objet

public function mysqli::release_savepoint(string `$name`): bool

Style procédural:

function mysqli_release_savepoint(mysqli `$mysql`, string `$name`): bool

Cette fonction équivaut à exécuter `$mysqli->query("RELEASE SAVEPOINT `$name`");`. Cette fonction ne va pas déclencher un commit ou un rollback.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`name`

  L'identifiant du point de sauvegarde.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- mysqli_savepoint() - Définit un point de sauvegarde nommé de la transaction

# mysqli::rollback

# mysqli_rollback

(PHP 5, PHP 7, PHP 8)

mysqli::rollback -- mysqli_rollback — Annule la transaction courante

### Description

Style orienté objet

public function mysqli::rollback(int `$flags` = 0, ?string `$name` = `null`): bool

Style procédural

function mysqli_rollback(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Annule la transaction courante pour la base de données.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`flags`

  Un masque de constantes `MYSQLI_TRANS_COR_*`.

`name`

  Si fourni, alors `ROLLBACK/*name*/` est exécuté.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
8.0.0 | `name` est désormais nullable.

### Exemples

Voir l'exemple se trouvant dans la documentation de la méthode mysqli::begin_transaction().

### Notes

> Note:

> Cette fonction ne fonctionne pas avec les types de table non transactionnelle (comme MyISAM ou ISAM).

### Voir aussi

- mysqli_begin_transaction() - Démarre une transaction
- mysqli_commit() - Valide la transaction courante
- mysqli_autocommit() - Active ou désactive le mode auto-commit
- mysqli_release_savepoint() - Supprime le point de sauvegarde nommé du jeu des points de sauvegarde de la transaction courante

# mysqli::savepoint

# mysqli_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::savepoint -- mysqli_savepoint — Définit un point de sauvegarde nommé de la transaction

### Description

Style orienté objet

public function mysqli::savepoint(string `$name`): bool

Style procédural:

function mysqli_savepoint(mysqli `$mysql`, string `$name`): bool

Cette fonction équivaut à exécuter `$mysqli->query("SAVEPOINT `$name`");`

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`name`

  L'identifiant du point de sauvegarde

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- mysqli_release_savepoint() - Supprime le point de sauvegarde nommé du jeu des points de sauvegarde de la transaction courante

# mysqli::select_db

# mysqli_select_db

(PHP 5, PHP 7, PHP 8)

mysqli::select_db -- mysqli_select_db — Sélectionne une base de données par défaut pour les requêtes

### Description

Style orienté objet

public function mysqli::select_db(string `$database`): bool

Style procédural

function mysqli_select_db(mysqli `$mysql`, string `$database`): bool

Sélectionne la base de données par défaut (spécifiée par le paramètre `database`) pour être utilisée lors de l'exécution de requêtes sur la connexion représentée par le paramètre `mysql`.

> Note:

> Cette fonction ne doit être utilisée que pour changer la base de données par défaut pour la connexion courante. Il est possible de sélectionner la base de données par défaut avec le 4ème paramètre de la fonction mysqli_connect().

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`database`

  Le nom de la base de données.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Exemple avec mysqli::select_db()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    /* Récupère le nom de la base de données par défaut courante */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("La base de données par défaut est %s.\n", $row[0]);

    /* Change la base de données par défaut en "world" */
    $mysqli->select_db("world");

    /* Récupère le nom de la base de données par défaut courante */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("La base de données par défaut est %s.\n", $row[0]);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    /* Récupère le nom de la base de données par défaut courante */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("La base de données par défaut est %s.\n", $row[0]);

    /* Change la base de données par défaut en "world" */
    mysqli_select_db($link, "world");

    /* Récupère le nom de la base de données par défaut courante */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("La base de données par défaut est %s.\n", $row[0]);

Les exemples ci-dessus vont afficher :

    La base de données par défaut est test.
    La base de données par défaut est world.

### Voir aussi

- mysqli_connect() - Alias de mysqli::__construct
- mysqli_real_connect() - Ouvre une connexion à un serveur MySQL

# mysqli::set_charset

# mysqli_set_charset

(PHP 5 >= 5.0.5, PHP 7, PHP 8)

mysqli::set_charset -- mysqli_set_charset — Définit le jeu de caractères du client

### Description

Style orienté objet

public function mysqli::set_charset(string `$charset`): bool

Style procédural

function mysqli_set_charset(mysqli `$mysql`, string `$charset`): bool

Définit le jeu de caractères à utiliser lors de l'envoi de données depuis et vers le serveur de base de données.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`charset`

  Le jeu de caractères à définir.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Exemple avec mysqli::set_charset()

Style orienté objet

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    printf("Jeu de caractères initial : %s\n", $mysqli->character_set_name());

    /* Modification du jeu de caractères en utf8mb4 */
    $mysqli->set_charset("utf8mb4");

    printf("Jeu de caractères courant : %s\n", $mysqli->character_set_name());
    ?>

Style procédural

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test');

    printf("Jeu de caractères initial : %s\n", mysqli_character_set_name($link));

    /* Modification du jeu de caractères en utf8mb4 */
    mysqli_set_charset($link, "utf8mb4");

    printf("Jeu de caractères courant : %s\n", mysqli_character_set_name($link));
    ?>

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Jeu de caractères initial : latin1
    Jeu de caractères courant : utf8mb4

### Notes

> Note:

> C'est la meilleure façon de modifier le jeu de caractères. Il n'est pas recommandé d'utiliser la fonction mysqli_query() pour le définir (comme avec la requête `SET NAMES utf8`). Voir la section Concepts des jeux de caractères MySQL pour plus d'informations.

### Voir aussi

- mysqli_character_set_name() - Retourne le jeu de caractères courant pour la connexion
- 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
- Concepts des jeux de caractères MySQL
- » Liste des jeux de caractères supportés par MySQL

# mysqli::$sqlstate

# mysqli_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli::$sqlstate -- mysqli_sqlstate — Retourne l'erreur SQLSTATE de la dernière opération MySQL

### Description

Style orienté objet

string $mysqli->sqlstate;

Style procédural

function mysqli_sqlstate(mysqli `$mysql`): string

Retourne une chaîne contenant le code d'erreur SQLSTATE de la dernière erreur. Le code d'erreur `'00000'` signifie : "pas d'erreur". Les valeurs sont spécifiées par les normes ANSI SQL et ODBC. Pour une liste des valeurs possibles, voir : » http://dev.mysql.com/doc/mysql/en/error-handling.html.

> Note:

> Il est à noter que toutes les erreurs de MySQL n'ont pas encore de correspondance avec les erreurs SQLSTATE. La valeur `HY000` (erreur générale) est utilisée pour les erreurs sans correspondance.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Retourne une chaîne contenant le code d'erreur SQLSTATE de la dernière erreur. Le code est constitué de 5 caractères : `'00000'` représente l'absence d'erreurs.

### Exemples

Exemple #1 Exemple avec $mysqli->sqlstate

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* La table Ville existe déjà, nous devrions avoir une erreur */
    try {
        $mysqli->query("CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Erreur - SQLSTATE %s.\n", $mysqli->sqlstate);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* La table Ville existe déjà, nous devrions avoir une erreur */
    try {
        mysqli_query($link, "CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Erreur - SQLSTATE %s.\n", mysqli_sqlstate($link));
    }

Les exemples ci-dessus vont afficher :

    Erreur - SQLSTATE 42S01.

### Voir aussi

- mysqli_errno() - Retourne le dernier code d'erreur produit
- mysqli_error() - Retourne une chaîne décrivant la dernière erreur

# mysqli::ssl_set

# mysqli_ssl_set

(PHP 5, PHP 7, PHP 8)

mysqli::ssl_set -- mysqli_ssl_set — Utilisée pour établir une connexion sécurisée avec SSL

### Description

Style orienté objet

public function mysqli::ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Style procédural

function mysqli_ssl_set(
mysqli `$mysql`,
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Utilisée pour établir une connexion sécurisée avec SSL. Elle doit être appelée avant mysqli_real_connect(). Cette fonction ne fait rien du tout si le support OpenSSL n'est pas activé.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`key`

  Le chemin vers le fichier contenant la clé.

`certificate`

  Le chemin vers le fichier contenant le certificat.

`ca_certificate`

  Le chemin vers le fichier contenant l'autorité du certificat.

`ca_path`

  Le chemin vers le dossier contenant les certificats SSL CA au format PEM.

`cipher_algos`

  La liste des algorithmes de chiffrement autorisés pour le chiffrement SSL.

### Valeurs de retour

Retourne toujours `true`. Si SSL n'est pas correctement installé, mysqli_real_connect() retournera une erreur lorsqu'on tente une connexion.

### Voir aussi

- mysqli_options() - Définit les options
- mysqli_real_connect() - Ouvre une connexion à un serveur MySQL

# mysqli::stat

# mysqli_stat

(PHP 5, PHP 7, PHP 8)

mysqli::stat -- mysqli_stat — Obtient le statut courant du système

### Description

Style orienté objet

public function mysqli::stat(): string|false

Style procédural

function mysqli_stat(mysqli `$mysql`): string|false

mysqli_stat() retourne une chaîne de caractères contenant des informations similaires à la commande '`mysqladmin status`'. Cela inclut le temps de fonctionnement, exprimé en secondes et le nombre de threads courant, le nombre de commandes, les tables rechargées et ouvertes.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Une chaîne de caractères décrivant le statut du serveur. `false` est retourné si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysqli::stat()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    printf ("Statut du système : %s\n", $mysqli->stat());

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    printf("Statut du système : %s\n", mysqli_stat($link));

Les exemples ci-dessus vont afficher :

    Statut du système : Uptime: 272  Threads: 1  Questions: 5340  Slow queries: 0
    Opens: 13  Flush tables: 1  Open tables: 0  Queries per second avg: 19.632
    Memory in use: 8496K  Max memory used: 8560K

### Voir aussi

- mysqli_get_server_info() - Retourne la version du serveur MySQL

# mysqli::stmt_init

# mysqli_stmt_init

(PHP 5, PHP 7, PHP 8)

mysqli::stmt_init -- mysqli_stmt_init — Initialise une commande MySQL

### Description

Style orienté objet

public function mysqli::stmt_init(): mysqli_stmt|false

Style procédural

function mysqli_stmt_init(mysqli `$mysql`): mysqli_stmt|false

Alloue et initialise un objet de commande, à utiliser avec mysqli_stmt_prepare().

> Note:

> Tous les appels ultérieurs aux fonctions mysqli_stmt_* échoueront, tant que mysqli_stmt_prepare() n'a pas été appelée.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Retourne un objet.

### Voir aussi

- mysqli_stmt_prepare() - Prépare une requête SQL pour l'exécution

# mysqli::store_result

# mysqli_store_result

(PHP 5, PHP 7, PHP 8)

mysqli::store_result -- mysqli_store_result — Transfère un jeu de résultats à partir de la dernière requête

### Description

Style orienté objet

public function mysqli::store_result(int `$mode` = 0): mysqli_result|false

Style procédural

function mysqli_store_result(mysqli `$mysql`, int `$mode` = 0): mysqli_result|false

Transfère le jeu de résultats à partir de la dernière requête sur la connexion à la base de données spécifiée par le paramètre `mysql` pour une utilisation avec mysqli_data_seek().

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`mode`

  L'option qu'on souhaite définir. À partir de PHP 8.1, ce paramètre n'a aucun effet. Elle peut prendre l'une des valeurs suivantes :

  Options valides
  Nom | Description
  --- | ---
  `MYSQLI_STORE_RESULT_COPY_DATA` | Copie les résultats récupérés d'un buffer interne mysqlnd dans des variables PHP. Par défaut, mysqlnd utilisera une référence logique pour éviter la copie et la duplication des résultats contenus en mémoire. Pour certains jeux de résultats, par exemple, les jeux de résultats avec beaucoup de petites lignes, l'approche de la copie peut réduire l'utilisation mémoire globale car les variables PHP contenant les résultats peuvent être libérées plus tôt (disponible uniquement avec mysqlnd)

### Valeurs de retour

Retourne un résultat stocké sous la forme d'un objet ou `false` si une erreur survient.

> Note:

> mysqli_store_result() retourne `false` dans le cas où la requête ne retourne pas de jeu de résultat (si la requête est de type INSERT par exemple). Cette fonction retournera toujours `false` si le jeu de résultats ne peut être lu. Il est possible de savoir s'il y a une erreur en utilisant la fonction mysqli_error() et en regardant si elle renvoie une chaîne vide, ou si mysqli_errno() retourne zéro, ou bien si mysqli_field_count() retourne une valeur différente de zéro. Une autre raison pour que cette fonction retourne `false` est que le jeu de résultats retourné après une requête réussie appelée par mysqli_query() est trop long (la mémoire pour celui-ci ne peut être allouée). Si mysqli_field_count() retourne une valeur différente de zéro, le traitement devrait produire un jeu de résultats non vide.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
8.4.0 | Le passage du paramètre `mode` est désormais obsolète. Ce paramètre n'a eu aucun effet à partir de PHP 8.1.0.

### Exemples

Voir la fonction mysqli_multi_query().

### Notes

> Note:

> Il est toujours conseillé de libérer la mémoire allouée pour le résultat en utilisant la fonction mysqli_free_result(), lors du transfert de grands résultats en utilisant la fonction mysqli_store_result() cela devient particulièrement important.

### Voir aussi

- mysqli_real_query() - Exécute une requête SQL
- mysqli_use_result() - Initialise la récupération d'un jeu de résultats

# mysqli::$thread_id

# mysqli_thread_id

(PHP 5, PHP 7, PHP 8)

mysqli::$thread_id -- mysqli_thread_id — Retourne l'identifiant du thread pour la connexion courante

### Description

Style orienté objet

int $mysqli->thread_id;

Style procédural

function mysqli_thread_id(mysqli `$mysql`): int

La fonction mysqli_thread_id() retourne l'identifiant du thread de la connexion courante qui peut être terminé par la suite en utilisant la fonction mysqli_kill(). Si la connexion est perdue et que l'on se reconnecte avec la fonction mysqli_ping(), l'identifiant du thread sera différent. Ainsi, il faut récupérer l'identifiant du thread uniquement lorsque l'on en a besoin.

> Note:

> L'identifiant du thread est assigné sur une base de connexion par connexion. Ce qui fait que si la connexion est coupée, puis relancée, un nouvel identifiant de thread lui sera assigné.

> Pour terminer une requête en cours d'exécution, il est possible d'utiliser la commande SQL `KILL QUERY processid`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Retourne l'identifiant du thread pour la connexion courante.

### Exemples

Exemple #1 Exemple avec $mysqli->thread_id

Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    /* Détermine l'identifiant du thread */
    $thread_id = $mysqli->thread_id;

    /* Termine la connexion */
    $mysqli->kill($thread_id);

    /* Ceci doit produire une erreur */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Erreur : %s\n", $mysqli->error);
        exit;
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    /* Détermine l'identifiant du thread */
    $thread_id = mysqli_thread_id($link);

    /* Termine la connexion */
    mysqli_kill($link, $thread_id);

    /* Ceci doit produire une erreur */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Erreur : %s\n", mysqli_error($link));
        exit;
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Erreur : MySQL server has gone away

### Voir aussi

- mysqli_kill() - Demande au serveur de terminer un thread MySQL

# mysqli::thread_safe

# mysqli_thread_safe

(PHP 5, PHP 7, PHP 8)

mysqli::thread_safe -- mysqli_thread_safe — Indique si le support des threads est activé ou pas

### Description

Style orienté objet

public function mysqli::thread_safe(): bool

Style procédural

function mysqli_thread_safe(): bool

Indique si la bibliothèque cliente est compilée avec la sécurité thread.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si la bibliothèque cliente est thread-safe, `false` sinon.

# mysqli::use_result

# mysqli_use_result

(PHP 5, PHP 7, PHP 8)

mysqli::use_result -- mysqli_use_result — Initialise la récupération d'un jeu de résultats

### Description

Style orienté objet

public function mysqli::use_result(): mysqli_result|false

Style procédural

function mysqli_use_result(mysqli `$mysql`): mysqli_result|false

Utilisé pour initialiser la récupération d'un jeu de résultats à partir de la dernière requête exécutée en utilisant la fonction mysqli_real_query() sur la connexion spécifiée par le paramètre `link`.

Cette fonction ou la fonction mysqli_store_result() doivent être appelées avant que le résultat d'une requête ne puisse être récupéré, et pour éviter l'échec de la prochaine requête sur la connexion à la base de données.

> Note:

> La fonction mysqli_use_result() ne transfère pas le jeu de résultats en entier à partir de la base de données et on ne peut donc pas utiliser des fonctions telle mysqli_data_seek() pour se déplacer entre les enregistrements. Pour utiliser cette fonctionnalité, l'on doit récupérer le jeu de résultats en utilisant mysqli_store_result().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet de résultats non stockés ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Exemple avec mysqli::use_result()

Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Exécution de plusieurs requêtes */
    if ($mysqli->multi_query($query)) {
        do {
            /* Stockage du premier jeu de résultats */
            if ($result = $mysqli->use_result()) {
                while ($row = $result->fetch_row()) {
                    printf("%s\n", $row[0]);
                }
                $result->close();
            }
            /* Affichage d'une démarcation */
            if ($mysqli->more_results()) {
                printf("-----------------\n");
            }
        } while ($mysqli->next_result());
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Exécution de plusieurs requêtes */
    if (mysqli_multi_query($link, $query)) {
        do {
            /* Stockage du premier jeu de résultats */
            if ($result = mysqli_use_result($link)) {
                while ($row = mysqli_fetch_row($result)) {
                    printf("%s\n", $row[0]);
                }
                mysqli_free_result($result);
            }
            /* Affichage d'une démarcation */
            if (mysqli_more_results($link)) {
                printf("-----------------\n");
            }
        } while (mysqli_next_result($link));
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Voir aussi

- mysqli_real_query() - Exécute une requête SQL
- mysqli_store_result() - Transfère un jeu de résultats à partir de la dernière requête

# mysqli::$warning_count

# mysqli_warning_count

(PHP 5, PHP 7, PHP 8)

mysqli::$warning_count -- mysqli_warning_count — Retourne le nombre d'avertissements générés par la dernière requête exécutée

### Description

Style orienté objet

int $mysqli->warning_count;

Style procédural

function mysqli_warning_count(mysqli `$mysql`): int

Retourne le nombre d'avertissements générés par la dernière requête exécutée.

> Note: Pour récupérer les messages d'avertissement, la commande SQL suivante peut être utilisée : `SHOW WARNINGS [LIMIT row_count]`.

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().

### Valeurs de retour

Le nombre d'avertissements ou `0` s'il n'y en a pas.

### Exemples

Exemple #1 Exemple avec $mysqli->warning_count

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 42/0");

    if ($mysqli->warning_count > 0) {
        $result = $mysqli->query("SHOW WARNINGS");
        $row = $result->fetch_row();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

    ?>

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "SELECT 42/0");

    if (mysqli_warning_count($link) > 0) {
        $result = mysqli_query($link, "SHOW WARNINGS");
        $row = mysqli_fetch_row($result);
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }
    ?>

Les exemples ci-dessus vont afficher :

    Warning (1365): Division by 0

### Voir aussi

- mysqli_errno() - Retourne le dernier code d'erreur produit
- mysqli_error() - Retourne une chaîne décrivant la dernière erreur
- mysqli_sqlstate() - Retourne l'erreur SQLSTATE de la dernière opération MySQL

## Sommaire

- 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::begin_transaction — Démarre une transaction
- mysqli::change_user — Change l'utilisateur de la connexion
- mysqli::character_set_name — Retourne le jeu de caractères courant pour la connexion
- mysqli::close — Ferme une connexion
- mysqli::commit — Valide la transaction courante
- mysqli::$connect_errno — Retourne le code d'erreur du dernier appel de connexion
- mysqli::$connect_error — Retourne une description de la dernière erreur de connexion
- mysqli::__construct — Ouvre une connexion à un serveur MySQL
- mysqli::debug — Effectue des actions de débogage
- mysqli::dump_debug_info — Écrit les informations de débogage dans les logs
- mysqli::$errno — Retourne le dernier code d'erreur produit
- mysqli::$error — Retourne une chaîne décrivant la dernière erreur
- mysqli::$error_list — Retourne une liste d'erreurs depuis la dernière commande exécutée
- mysqli::execute_query — Prépare, lie les paramètres et exécute une instruction SQL
- mysqli::$field_count — Retourne le nombre de colonnes pour la dernière requête
- mysqli::get_charset — Retourne un objet représentant le jeu de caractères
- mysqli::$client_info — Récupère des informations sur le client MySQL
- mysqli::$client_version — Retourne la version du client MySQL sous forme d'un entier
- mysqli::get_connection_stats — Retourne des statistiques sur la connexion
- mysqli::$host_info — Retourne une chaîne contenant le type de connexion utilisée
- mysqli::$protocol_version — Retourne la version du protocole MySQL utilisé
- mysqli::$server_info — Retourne la version du serveur MySQL
- mysqli::$server_version — Retourne un entier représentant la version du serveur MySQL
- mysqli::get_warnings — Lit le résultat de SHOW WARNINGS
- mysqli::$info — Retourne des informations à propos de la dernière requête exécutée
- mysqli::init — Initialise MySQLi et retourne un objet à utiliser avec mysqli_real_connect()
- mysqli::$insert_id — Retourne la valeur générée pour une colonne AUTO_INCREMENT par la dernière requête
- mysqli::kill — Demande au serveur de terminer un thread MySQL
- mysqli::more_results — Vérifie s'il y a d'autres jeux de résultats MySQL disponibles
- mysqli::multi_query — Exécute une ou plusieurs requêtes sur la base de données
- mysqli::next_result — Prépare le prochain résultat d'une requête multiple
- mysqli::options — Définit les options
- mysqli::ping — Ping la connexion au serveur et reconnecte si elle n'existe plus
- mysqli::poll — Vérifie l'état de la connexion
- 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::reap_async_query — Lit un résultat pour une requête asynchrone
- mysqli::refresh — Rafraîchit
- mysqli::release_savepoint — Supprime le point de sauvegarde nommé du jeu des points de sauvegarde de la transaction courante
- mysqli::rollback — Annule la transaction courante
- mysqli::savepoint — Définit un point de sauvegarde nommé de la transaction
- mysqli::select_db — Sélectionne une base de données par défaut pour les requêtes
- mysqli::set_charset — Définit le jeu de caractères du client
- 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_init — Initialise une commande MySQL
- 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 support des threads est activé ou pas
- 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 exécutée

# La classe mysqli_stmt

(PHP 5, PHP 7, PHP 8)

## Introduction

Représente une requête préparée.

## Synopsis de la classe

class mysqli_stmt {
/* Propriétés */
public readonly int|string $affected_rows;
public readonly int|string $insert_id;
public readonly int|string $num_rows;
public readonly int $param_count;
public readonly int $field_count;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly string $sqlstate;
public int $id;
/* Méthodes */
public function __construct(mysqli `$mysql`, ?string `$query` = `null`)
public function attr_get(int `$attribute`): int
public function attr_set(int `$attribute`, int `$value`): bool
public function bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool
public function bind_result(mixed `&$var`, mixed `&...$vars`): bool
public function close(): true
public function data_seek(int `$offset`): void
public function execute(?array `$params` = `null`): bool
public function fetch(): ?bool
public function free_result(): void
public function get_result(): mysqli_result|false
public function get_warnings(): mysqli_warning|false
public function more_results(): bool
public function next_result(): bool
public function num_rows(): int|string
public function prepare(string `$query`): bool
public function reset(): bool
public function result_metadata(): mysqli_result|false
public function send_long_data(int `$param_num`, string `$data`): bool
public function store_result(): bool
}

## Propriétés

id

  Stocke l'identifiant de la requête préparée.

# mysqli_stmt::$affected_rows

# mysqli_stmt_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$affected_rows -- mysqli_stmt_affected_rows — Retourne le nombre total de lignes modifiées, effacées, insérées, ou correspondant par la dernière requête

### Description

Style orienté objet

int|string $mysqli_stmt->affected_rows;

Style procédural

function mysqli_stmt_affected_rows(mysqli_stmt `$statement`): int|string

Retourne le nombre de lignes affectées par une requête `INSERT`, `UPDATE` ou `DELETE`. Fonctionne comme mysqli_stmt_num_rows() pour les requêtes `SELECT`.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Un entier plus grand que zéro indique le nombre de lignes affectées ou recherchées. Zéro indique qu'aucun enregistrement n'a été modifié par une requête du type `UPDATE`, aucune ligne ne correspond à la clause `WHERE` dans la requête ou bien qu'aucune requête n'a été exécutée. `-1` indique que la requête a retourné une erreur ou que, pour une requête `SELECT`, mysqli_stmt_affected_rows() a été appelé avant d'appeler mysqli_stmt_store_result().

> Note:

> Si le nombre de lignes affectées est plus grand que la valeur maximale (`PHP_INT_MAX`) que peut prendre un entier, le nombre de lignes affectées sera retourné en tant que chaîne de caractères.

### Exemples

Exemple #1 Exemple de mysqli_stmt_affected_rows()

Style orienté objet

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Création d'une table temporaire */
    $mysqli->query("CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* Préparation de la requête */
    $stmt = $mysqli->prepare($query);

    /* Lie une variable à un paramètre fictif */
    $code = 'A%';
    $stmt->bind_param("s", $code);

    /* Exécution de la requête */
    $stmt->execute();

    printf("Lignes insérées : %d\n", $stmt->affected_rows);
    ?>

Style procédural

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Création d'une table temporaire */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* Préparation de la requête */
    $stmt = mysqli_prepare($link, $query);

    /* Lie une variable à un paramètre fictif */
    $code = 'A%';
    mysqli_stmt_bind_param($stmt, "s", $code);

    /* Exécution de la requête */
    mysqli_stmt_execute($stmt);

    printf("Lignes insérées : %d\n", mysqli_stmt_affected_rows($stmt));
    ?>

L'exemple ci-dessus va afficher :

    Lignes insérées : 17

### Voir aussi

- mysqli_stmt_num_rows() - Retourne le nombre de lignes extraites du serveur
- mysqli_stmt_store_result() - Stocke un ensemble de résultats dans un tampon interne

# mysqli_stmt::attr_get

# mysqli_stmt_attr_get

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_get -- mysqli_stmt_attr_get — Récupère la valeur courante d'un attribut de requête

### Description

Style orienté objet

public function mysqli_stmt::attr_get(int `$attribute`): int

Style procédural

function mysqli_stmt_attr_get(mysqli_stmt `$statement`, int `$attribute`): int

Récupère la valeur courante d'un attribut de requête.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().
`attribute`

  L'attribut qu'on veut récupérer.

### Valeurs de retour

Retourne la valeur de l'attribut.

# mysqli_stmt::attr_set

# mysqli_stmt_attr_set

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_set -- mysqli_stmt_attr_set — Modifie le comportement d'une requête préparée

### Description

Style orienté objet

public function mysqli_stmt::attr_set(int `$attribute`, int `$value`): bool

Style procédural

function mysqli_stmt_attr_set(mysqli_stmt `$statement`, int `$attribute`, int `$value`): bool

Modifie le comportement d'une requête préparée. Cette fonction peut être appelée plusieurs fois pour définir plusieurs attributs.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().
`attribute`

  L'attribut qu'on veut définir. Il peut avoir une des valeurs suivantes :

  Valeurs des attributs
  Caractère | Description
  --- | ---
  MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH | Si défini à `true`, la fonction mysqli_stmt_store_result() mettra à jour la valeur de la méta-donnée `MYSQL_FIELD->max_length`.
  MYSQLI_STMT_ATTR_CURSOR_TYPE | Type du curseur permettant l'ouverture de la requête lorsque la fonction mysqli_stmt_execute() est appelée. `value` peut valoir `MYSQLI_CURSOR_TYPE_NO_CURSOR` (par défaut) ou `MYSQLI_CURSOR_TYPE_READ_ONLY`.
  MYSQLI_STMT_ATTR_PREFETCH_ROWS | Nombre de lignes à récupérer depuis le serveur en une fois lors de l'utilisation d'un curseur. `value` peut être compris entre 1 et la valeur maximale d'un type long non-signé. Par défaut, vaut 1. Supprimé à partir de PHP 8.4.0.

  Lors de l'utilisation de l'option `MYSQLI_STMT_ATTR_CURSOR_TYPE` avec `MYSQLI_CURSOR_TYPE_READ_ONLY`, un curseur sera ouvert pour la requête lors de l'appel à la fonction mysqli_stmt_execute(). S'il y a déjà un curseur d'ouvert depuis un précédent appel à la fonction mysqli_stmt_execute(), il sera fermé avant d'en ouvrir un nouveau. La fonction mysqli_stmt_reset() ferme également tous les curseurs avant de préparer la requête pour une ré-exécution. La fonction mysqli_stmt_free_result() ferme tout curseur ouvert.

  Si on ouvre un curseur pour une requête préparée, la fonction mysqli_stmt_store_result() n'est pas nécessaire.

`value`

  La valeur à assigner à l'attribut.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Voir aussi

- » Connecteur / MySQL mysql_stmt_attr_set()

# mysqli_stmt::bind_param

# mysqli_stmt_bind_param

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_param -- mysqli_stmt_bind_param — Lie des variables à une requête MySQL

### Description

Style orienté objet

public function mysqli_stmt::bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool

Style procédural

function mysqli_stmt_bind_param(
mysqli_stmt `$statement`,
string `$types`,
mixed `&$var`,
mixed `&...$vars`
): bool

Lie les variables pour les marqueurs de paramètre dans la requête préparé par mysqli_prepare() ou mysqli_stmt_prepare().

> Note:

> Si la taille des données dépasse la taille maximale d'un paquet, (`max_allowed_packet`), il faut spécifier le caractère `b` dans le paramètre `types` et utiliser la fonction mysqli_stmt_send_long_data() pour envoyer le message par paquets.

> Note:

> Il faut être prudent lors de l'utilisation de mysqli_stmt_bind_param() avec la fonction call_user_func_array(). À noter que mysqli_stmt_bind_param() nécessite que ses paramètres soient passés par référence, alors que la fonction call_user_func_array() peut accepter comme paramètre une liste de variables qui peuvent représenter des références ou des valeurs.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().
`types`

  Une chaîne de caractères qui contient un ou plusieurs caractères qui spécifient le type de la variable à lier :

  Caractère de spécification des types
  Caractère | Description
  --- | ---
  i | correspond à une variable de type int
  d | correspond à une variable de type float
  s | correspond à une variable de type string
  b | correspond à une variable de type BLOB, qui sera envoyé par paquets

`var`
`vars`

  Le nombre de variables et la longueur de la chaîne de caractères `types` doivent correspondre aux paramètres de la requête.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Exemple avec mysqli_stmt::bind_param()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    $stmt->bind_param('sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    $stmt->execute();

    printf("%d ligne insérée.\n", $stmt->affected_rows);

    /* Nettoie la table CountryLanguage */
    $mysqli->query("DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("%d ligne supprimée.\n", $mysqli->affected_rows);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    $stmt = mysqli_prepare($link, "INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    mysqli_stmt_bind_param($stmt, 'sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    mysqli_stmt_execute($stmt);

    printf("%d ligne insérée.\n", mysqli_stmt_affected_rows($stmt));

    /* Nettoie la table CountryLanguage */
    mysqli_query($link, "DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("%d ligne supprimée.\n", mysqli_affected_rows($link));

Les exemples ci-dessus vont afficher :

    1 ligne insérée.
    1 ligne supprimée.

Exemple #2 Utilisation de `...` pour fournir des arguments

L'opérateur `...` peut être utilisé pour fournir une liste d'arguments de longueur variable, par exemple dans une clause `WHERE IN`.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("SELECT Language FROM CountryLanguage WHERE CountryCode IN (?, ?)");
    /* Utilisation de ... pour fournir des arguments */
    $stmt->bind_param('ss', ...['DEU', 'POL']);
    $stmt->execute();
    $stmt->store_result();

    printf("%d lignes trouvées.\n", $stmt->num_rows());

Les exemples ci-dessus vont afficher :

    10 lignes trouvées.

### Voir aussi

- mysqli_stmt_bind_result() - Lie des variables à un jeu de résultats
- 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_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_stmt_send_long_data() - Envoie des données MySQL par paquets
- 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::bind_result

# mysqli_stmt_bind_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_result -- mysqli_stmt_bind_result — Lie des variables à un jeu de résultats

### Description

Style orienté objet

public function mysqli_stmt::bind_result(mixed `&$var`, mixed `&...$vars`): bool

Style procédural

function mysqli_stmt_bind_result(mysqli_stmt `$statement`, mixed `&$var`, mixed `&...$vars`): bool

Associe des colonnes d'un résultat à des variables.

Lorsque mysqli_stmt_fetch() est appelée pour lire des valeurs, le protocole MySQL place les données dans les variables spécifiées `var`/`vars`.

Une colonne peut être liée ou reliée à tout moment, même après qu'un jeu de résultats ait été partiellement récupéré. La nouvelle liaison prend effet la prochaine fois que la mysqli_stmt_fetch() est appelée.

> Note:

> Toutes les colonnes doivent être liées après l'exécution de la fonction mysqli_stmt_execute() et avant l'appel à la fonction mysqli_stmt_fetch(). En fonction du type de valeur de la colonne, le type de variable PHP peut être automatiquement modifié.

> Note:

> Une colonne peut être associée ou réassociée à tout moment, même après une lecture partielle du résultat. La nouvelle association prend effet au prochain appel de mysqli_stmt_fetch().

Astuce

Cette fonction est utile pour les résultats basiques. Pour récupérer un ensemble de résultats itérable, ou récupérer chaque ligne sous forme de tableau ou d'objet, utiliser la mysqli_stmt_get_result().

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().
`var`

  La première variable à lier.

`vars`

  Variables supplémentaires à lier.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Préparation de la requête */
    $stmt = $mysqli->prepare("SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    $stmt->execute();

    /* Lier des variables à une déclaration préparée */
    $stmt->bind_result($col1, $col2);

    /* Récupération des valeurs */
    while ($stmt->fetch()) {
        printf("%s %s\n", $col1, $col2);
    }
    ?>

Exemple #2 Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Préparation de la requête */
    $stmt = mysqli_prepare($link, "SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    mysqli_stmt_execute($stmt);

    /* Lier des variables à une déclaration préparée */
    mysqli_stmt_bind_result($stmt, $col1, $col2);

    /* Récupération des valeurs */
    while (mysqli_stmt_fetch($stmt)) {
        printf("%s %s\n", $col1, $col2);
    }
    ?>

L'exemple ci-dessus va afficher :

    AFG Afghanistan
    ALB Albania
    DZA Algeria
    ASM American Samoa
    AND Andorra

### Voir aussi

- mysqli_stmt_get_result() - Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result
- mysqli_stmt_bind_param() - Lie des variables à une requête MySQL
- 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_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_stmt_prepare() - Prépare une requête SQL pour l'exécution

# mysqli_stmt::close

# mysqli_stmt_close

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::close -- mysqli_stmt_close — Termine une requête préparée

### Description

Style orienté objet

public function mysqli_stmt::close(): true

Style procédural

function mysqli_stmt_close(mysqli_stmt `$statement`): true

Ferme une requête préparée. mysqli_stmt_close() libère le pointeur utilisé par `stmt`. Si la requête est en attente ou bien que les résultats ne sont pas encore lus, cette fonction les annulera et, donc, la prochaine requête pourra être exécutée.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction retourne désormais toujours `true`. Auparavant, elle retournait `false` en cas d'échec.

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution

# mysqli_stmt::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::__construct — Construit un nouvel objet mysqli_stmt

### Description

public function mysqli_stmt::__construct(mysqli `$mysql`, ?string `$query` = `null`)

Cette méthode construit un nouvel objet mysqli_stmt.

### Liste de paramètres

`link`

  Un objet mysqli valide.

`query`

  La requête, sous la forme d'une chaîne de caractères. Si ce paramètre est `null`, alors le constructeur se comporte comme la fonction mysqli_stmt_init() ; sinon il se comportera comme la fonction mysqli_prepare().

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
8.0.0 | `query` est désormais nullable.

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_stmt_init() - Initialise une commande MySQL

# mysqli_stmt::data_seek

# mysqli_stmt_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::data_seek -- mysqli_stmt_data_seek — Ajuste le pointeur de résultat vers une ligne arbitraire dans le résultat mis en mémoire tampon.

### Description

Style orienté objet

public function mysqli_stmt::data_seek(int `$offset`): void

Style procédural

function mysqli_stmt_data_seek(mysqli_stmt `$statement`, int `$offset`): void

Cette fonction déplace le pointeur du jeu de résultats mis en mémoire tampon vers une ligne arbitraire spécifiée par le paramètre `offset`.

Cette fonction ne fonctionne que sur le jeu de résultats interne mis en mémoire tampon. mysqli_stmt_store_result() doit être appelée avant la fonction mysqli_stmt_data_seek().

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().
`offset`

  Doit prendre une valeur entre zéro et le nombre total de lignes moins 1 (0..mysqli_stmt_num_rows() - 1).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    $stmt->bind_result($name, $code);

    $stmt->store_result();

    /* Lit la ligne n°400 */
    $stmt->data_seek(399);

    $stmt->fetch();

    printf("Ville : %s  Code Pays : %s\n", $name, $code);

Exemple #2 Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $stmt = mysqli_prepare($link, $query);

    mysqli_stmt_execute($stmt);

    mysqli_stmt_bind_result($stmt, $name, $code);

    mysqli_stmt_store_result($stmt);

    /* Lit la ligne n°400 */
    mysqli_stmt_data_seek($stmt, 399);

    mysqli_stmt_fetch($stmt);

    printf("Ville : %s  Code Pays : %s\n", $name, $code);

L'exemple ci-dessus va afficher :

    Ville : Benin City  Code Pays : NGA

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_stmt_store_result() - Stocke un ensemble de résultats dans un tampon interne
- mysqli_stmt_num_rows() - Retourne le nombre de lignes extraites du serveur
- mysqli_data_seek() - Déplace le pointeur interne de résultat

# mysqli_stmt::$errno

# mysqli_stmt_errno

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$errno -- mysqli_stmt_errno — Retourne un code erreur pour la dernière requête

### Description

Style orienté objet

int $mysqli_stmt->errno;

Style procédural

function mysqli_stmt_errno(mysqli_stmt `$statement`): int

Retourne le code erreur pour la dernière requête appelée dans le traitement qui a réussi ou échoué.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Une valeur représentant un code erreur. `0` signifie qu'aucune erreur n'est survenue.

### Exemples

Exemple #1 Style orienté objet

    <?php
    /* Ouvre la connexion */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Effacement de la table */
        $mysqli->query("DROP TABLE myCountry");

        /* Exécute la requête */
        $stmt->execute();

        printf("Erreur : %d.\n", $stmt->errno);

        /* Ferme la commande */
        $stmt->close();
    }

    /* Ferme la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    /* Ouvre la connexion */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Effacement de la table */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Exécute la requête */
        mysqli_stmt_execute($stmt);

        printf("Erreur : %d.\n", mysqli_stmt_errno($stmt));

        /* Ferme la commande */
        mysqli_stmt_close($stmt);
    }

    /* Ferme la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Erreur : 1146.

### Voir aussi

- mysqli_stmt_error() - Retourne une description de la dernière erreur de traitement
- mysqli_stmt_sqlstate() - Retourne le code SQLSTATE de la dernière opération MySQL

# mysqli_stmt::$error

# mysqli_stmt_error

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$error -- mysqli_stmt_error — Retourne une description de la dernière erreur de traitement

### Description

Style orienté objet

string $mysqli_stmt->error;

Style procédural

function mysqli_stmt_error(mysqli_stmt `$statement`): string

Retourne une chaîne de caractères représentant le message d'erreur le plus récent appelé par une fonction de traitement, qu'elle ait réussi ou échoué.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Une chaîne de caractères décrivant l'erreur. Une chaîne vide si aucune erreur n'est survenue.

### Exemples

Exemple #1 Style orienté objet

    <?php
    /* Ouvre la connexion */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Effacement de la table */
        $mysqli->query("DROP TABLE myCountry");

        /* Exécute la requête */
        $stmt->execute();

        printf("Erreur : %s.\n", $stmt->error);

        /* Ferme la commande */
        $stmt->close();
    }

    /* Ferme la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    /* Ouvre la connexion */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Effacement de la table */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Exécute la requête */
        mysqli_stmt_execute($stmt);

        printf("Erreur : %s.\n", mysqli_stmt_error($stmt));

        /* Ferme la commande */
        mysqli_stmt_close($stmt);
    }

    /* Ferme la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Erreur : Table 'world.myCountry' doesn't exist.

### Voir aussi

- mysqli_stmt_errno() - Retourne un code erreur pour la dernière requête
- mysqli_stmt_sqlstate() - Retourne le code SQLSTATE de la dernière opération MySQL

# mysqli_stmt::$error_list

# mysqli_stmt_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli_stmt::$error_list -- mysqli_stmt_error_list — Retourne une liste d'erreurs pour la dernière requête exécutée

### Description

Style orienté objet

array $mysqli_stmt->error_list;

Style procédural

function mysqli_stmt_error_list(mysqli_stmt `$statement`): array

Retourne un tableau d'erreurs depuis la dernière requête exécutée, qu'elle ait réussi ou non.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Une liste d'erreurs, chacune sous la forme d'un tableau associatif contenant le numéro d'erreur (errno), le message d'erreur (error) et le statut SQL (sqlstate).

### Exemples

Exemple #1 Style orienté objet

    <?php
    /* Ouvre une connexion */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec lors de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Supprime la table */
        $mysqli->query("DROP TABLE myCountry");

        /* Exécute la requête */
        $stmt->execute();

        echo "Erreur :\n";
        print_r($stmt->error_list);

        /* Ferme la requête */
        $stmt->close();
    }

    /* Ferme la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    /* Ouvre une connexion */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec lors de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Supprime la table */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Exécute la requête */
        mysqli_stmt_execute($stmt);

        echo "Erreur :\n";
        print_r(mysqli_stmt_error_list($stmt));

        /* Ferme la requête */
        mysqli_stmt_close($stmt);
    }

    /* Ferme la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Error:
    Array
    (
        [0] => Array
            (
                [errno] => 1146
                [sqlstate] => 42S02
                [error] => Table 'world.myCountry' doesn't exist
            )

    )

### Voir aussi

- mysqli_stmt_error() - Retourne une description de la dernière erreur de traitement
- mysqli_stmt_errno() - Retourne un code erreur pour la dernière requête
- mysqli_stmt_sqlstate() - Retourne le code SQLSTATE de la dernière opération MySQL

# mysqli_stmt::execute

# mysqli_stmt_execute

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::execute -- mysqli_stmt_execute — Exécute une requête préparée

### Description

Style orienté objet

public function mysqli_stmt::execute(?array `$params` = `null`): bool

Style procédural

function mysqli_stmt_execute(mysqli_stmt `$statement`, ?array `$params` = `null`): bool

Exécute une requête qui a été préalablement préparée en utilisant la fonction mysqli_prepare(), grâce à la ressource `stmt`. Lors de l'exécution, toutes les variables de la requête seront remplacées par les données appropriées.

Si la requête est `UPDATE`, `DELETE`, ou `INSERT`, le nombre total de lignes affectées est disponible via la fonction mysqli_stmt_affected_rows(). Si la requête produit un ensemble de résultats, il peut être récupéré à l'aide de la fonction mysqli_stmt_get_result() ou en le récupérant ligne par ligne directement à partir de l'instruction à l'aide de la fonction mysqli_stmt_fetch().

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().
`params`

  Une liste facultative, en tant que tableau, avec autant d'éléments qu'il y a de paramètres liés dans l'instruction SQL en cours d'exécution. Chaque valeur est traitée comme une chaîne de caractères.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre facultatif `params` a été ajouté.

### Exemples

Exemple #1 Exécuter une instruction préparée avec des variables liées

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");

    /* Préparation de la requête */
    $stmt = $mysqli->prepare("INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Lier les variables aux paramètres */
    $stmt->bind_param("sss", $val1, $val2, $val3);
    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Exécuter l'instruction */
    $stmt->execute();
    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Exécuter l'instruction */
    $stmt->execute();

    /* Récupération de toutes les lignes de myCity */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");

    /* Préparation de la requête */
    $stmt = mysqli_prepare($link, "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Lier les variables aux paramètres */
    mysqli_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);
    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Exécuter l'instruction */
    mysqli_stmt_execute($stmt);
    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Exécuter l'instruction */
    mysqli_stmt_execute($stmt);

    /* Récupération de toutes les lignes de myCity */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Les exemples ci-dessus vont afficher :

    Stuttgart (DEU,Baden-Wuerttemberg)
    Bordeaux (FRA,Aquitaine)

Exemple #2 Exécuter une instruction préparée avec un tableau de valeurs

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $mysqli->query('CREATE TEMPORARY TABLE myCity LIKE City');

    /* Préparation de la requête */
    $stmt = $mysqli->prepare('INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Exécuter l'instruction */
    $stmt->execute(['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Récupération de toutes les lignes de myCity */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    mysqli_query($link, 'CREATE TEMPORARY TABLE myCity LIKE City');

    /* Préparation de la requête */
    $stmt = mysqli_prepare($link, 'INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Exécuter l'instruction */
    mysqli_stmt_execute($stmt, ['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Récupération de toutes les lignes de myCity */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Les exemples ci-dessus vont afficher :

    Stuttgart (DEU,Baden-Wuerttemberg)

### Voir aussi

- mysqli_execute_query() - Prépare, lie les paramètres et exécute une instruction SQL
- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_stmt_bind_param() - Lie des variables à une requête MySQL
- mysqli_stmt_get_result() - Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result

# mysqli_stmt::fetch

# mysqli_stmt_fetch

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::fetch -- mysqli_stmt_fetch — Lit des résultats depuis une requête MySQL préparée dans des variables liées

### Description

Style orienté objet

public function mysqli_stmt::fetch(): ?bool

Style procédural

function mysqli_stmt_fetch(mysqli_stmt `$statement`): ?bool

Retourne le résultat d'une requête préparée dans une variable, liée par mysqli_stmt_bind_result().

> Note:

> Il est à noter que toutes les colonnes doivent être liées par l'application avant d'appeler mysqli_stmt_fetch().

> Note:

> Les données sont transférées sans être bufferisées, sans appeler la fonction mysqli_stmt_store_result(), ce qui peut avoir un impact sur les performances (mais aussi, réduire l'utilisation mémoire).

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Valeurs de retour
Valeur | Description
--- | ---
`true` | Réussite. Les données ont été lues.
`false` | Une erreur est survenue.
`null` | Il n'y a plus de ligne à lire ou les données ont été tronquées.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = $mysqli->prepare($query)) {

        /* Exécution de la requête */
        $stmt->execute();

        /* Association des variables de résultat */
        $stmt->bind_result($name, $code);

        /* Lecture des valeurs */
        while ($stmt->fetch()) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* Fermeture de la commande */
        $stmt->close();
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = mysqli_prepare($link, $query)) {

        /* Exécution de la requête */
        mysqli_stmt_execute($stmt);

        /* Association des variables de résultat */
        mysqli_stmt_bind_result($stmt, $name, $code);

        /* Lecture des valeurs */
        while (mysqli_stmt_fetch($stmt)) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* Fermeture de la commande */
        mysqli_stmt_close($stmt);
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Rockford (USA)
    Tallahassee (USA)
    Salinas (USA)
    Santa Clarita (USA)
    Springfield (USA)

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- 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_bind_result() - Lie des variables à un jeu de résultats

# mysqli_stmt::$field_count

# mysqli_stmt_field_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$field_count -- mysqli_stmt_field_count — Retourne le nombre de colonnes dans la requête donnée

### Description

Style orienté objet

int $mysqli_stmt->field_count;

Style procédural

function mysqli_stmt_field_count(mysqli_stmt `$statement`): int

Retourne le nombre de colonnes dans la déclaration préparée.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Retourne un entier représentant le nombre de colonnes.

### Exemples

Exemple #1 Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Code=?");
    $stmt->bind_param('s', $code);
    $stmt->execute();
    $row = $stmt->get_result()->fetch_row();
    for ($i = 0; $i < $stmt->field_count; $i++) {
        printf("La valeur de la colonne numéro %d est %s", $i, $row[$i]);
    }

Exemple #2 Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = mysqli_prepare($mysqli, "SELECT Name FROM Country WHERE Code=?");
    mysqli_stmt_bind_param($stmt, 's', $code);
    mysqli_stmt_execute($stmt);
    $result = mysqli_stmt_get_result($stmt);
    $row = mysqli_fetch_row($result);
    for ($i = 0; $i < mysqli_stmt_field_count($stmt); $i++) {
        printf("La valeur de la colonne numéro %d est %s", $i, $row[$i]);
    }

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    La valeur de la colonne numéro 0 est France

### Voir aussi

- mysqli_stmt_num_rows() - Retourne le nombre de lignes extraites du serveur

# mysqli_stmt::free_result

# mysqli_stmt_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::free_result -- mysqli_stmt_free_result — Libère le résultat MySQL de la mémoire

### Description

Style orienté objet

public function mysqli_stmt::free_result(): void

Style procédural

function mysqli_stmt_free_result(mysqli_stmt `$statement`): void

Libère le résultat `stmt` de la mémoire. `stmt` a été obtenu de la fonction mysqli_stmt_store_result().

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- mysqli_stmt_store_result() - Stocke un ensemble de résultats dans un tampon interne

# mysqli_stmt::get_result

# mysqli_stmt_get_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::get_result -- mysqli_stmt_get_result — Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result

### Description

Style orienté objet

public function mysqli_stmt::get_result(): mysqli_result|false

Style procédural

function mysqli_stmt_get_result(mysqli_stmt `$statement`): mysqli_result|false

Récupère un jeu de résultats d'une déclaration préparée sous la forme d'un objet mysqli_result. Les données seront récupérées depuis le serveur MySQL vers PHP. Cette méthode ne doit être appelée que pour les requêtes qui produisent un ensemble de résultats.

> Note:

> Disponible uniquement avec mysqlnd.

> Note:

> Cette fonction ne peut pas être utilisée conjointement avec la mysqli_stmt_store_result(). Ces deux fonctions récupèrent le jeu de résultats complet du serveur MySQL.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Retourne un jeu de résultats pour les requêtes SELECT réussies, ou `false` pour d'autres requêtes DML ou en cas d'échec. La fonction mysqli_errno() peut être utilisée pour distinguer entre ces deux types d'erreurs. Retourne `false` en cas d'échec. Pour des requêtes réussies qui produisent un jeu de résultat tel que `SELECT, SHOW, DESCRIBE` ou `EXPLAIN`, mysqli_stmt_get_result() retournera un objet mysqli_result. Pour les autres types de requêtes ayant réussi, mysqli_stmt_get_result() retournera `false`. La fonction mysqli_stmt_errno() peut être utilisée pour distinguer entre les deux raisons pour `false` ; à cause d'un bogue, antérieur à PHP 7.4.13, mysqli_errno() devait être utilisé pour déterminer ceci.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = $mysqli->prepare($query);
    $stmt->bind_param("s", $continent);

    $continentList = array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        $stmt->execute();
        $result = $stmt->get_result();
        while ($row = $result->fetch_array(MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }
    ?>

Exemple #2 Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_bind_param($stmt, "s", $continent);

    $continentList= array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        mysqli_stmt_execute($stmt);
        $result = mysqli_stmt_get_result($stmt);
        while ($row = mysqli_fetch_array($result, MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }
    ?>

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Albania 3401200 Europe
    Algeria 31471000 Africa
    Afghanistan 22720000 Asia
    Anguilla 8000 North America

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_stmt_result_metadata() - Retourne les métadonnées de préparation de requête MySQL
- mysqli_stmt_fetch() - Lit des résultats depuis une requête MySQL préparée dans des variables liées
- mysqli_fetch_array() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux
- mysqli_stmt_store_result() - Stocke un ensemble de résultats dans un tampon interne

# mysqli_stmt::get_warnings

# mysqli_stmt_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli_stmt::get_warnings -- mysqli_stmt_get_warnings — Récupère le résultat de SHOW WARNINGS

### Description

Style orienté objet

public function mysqli_stmt::get_warnings(): mysqli_warning|false

Style procédural

function mysqli_stmt_get_warnings(mysqli_stmt `$statement`): mysqli_warning|false
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

# mysqli_stmt::$insert_id

# mysqli_stmt_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$insert_id -- mysqli_stmt_insert_id — Récupère l'ID généré par la dernière requête INSERT

### Description

Style orienté objet

int|string $mysqli_stmt->insert_id;

Style procédural

function mysqli_stmt_insert_id(mysqli_stmt `$statement`): int|string
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

# mysqli_stmt::more_results

# mysqli_stmt_more_results

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::more_results -- mysqli_stmt_more_results — Vérifie s'il y a encore des résultats depuis une requête multiple

### Description

Style orienté objet

public function mysqli_stmt::more_results(): bool

Style procédural:

function mysqli_stmt_more_results(mysqli_stmt `$statement`): bool

Vérifie s'il y a encore des résultats depuis une requête multiple.

> Note:

> Disponible uniquement avec mysqlnd.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Retourne `true` s'il y a encore des résultats, `false` sinon.

### Voir aussi

- mysqli_stmt::next_result() - Lit le résultat suivant depuis une requête multiple
- mysqli::multi_query() - Exécute une ou plusieurs requêtes sur la base de données

# mysqli_stmt::next_result

# mysqli_stmt_next_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::next_result -- mysqli_stmt_next_result — Lit le résultat suivant depuis une requête multiple

### Description

Style orienté objet

public function mysqli_stmt::next_result(): bool

Style procédural:

function mysqli_stmt_next_result(mysqli_stmt `$statement`): bool

Lit le résultat suivant depuis une requête multiple.

> Note:

> Antérieur à PHP 8.1.0, disponible uniquement avec mysqlnd.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Historique

Version | Description
--- | ---
8.1.0 | Désormais aussi disponible lors de la liaison avec libmysqlclient.

### Voir aussi

- mysqli_stmt::more_results() - Vérifie s'il y a encore des résultats depuis une requête multiple
- mysqli::multi_query() - Exécute une ou plusieurs requêtes sur la base de données

# mysqli_stmt::$num_rows

# mysqli_stmt::num_rows

# mysqli_stmt_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$num_rows -- mysqli_stmt::num_rows -- mysqli_stmt_num_rows — Retourne le nombre de lignes extraites du serveur

### Description

Style orienté objet

int|string $mysqli_stmt->num_rows;
public function mysqli_stmt::num_rows(): int|string

Style procédural

function mysqli_stmt_num_rows(mysqli_stmt `$statement`): int|string

Retourne le nombre de lignes mises en mémoire tampon dans l'instruction. Cette fonction ne fonctionnera qu'après l'appel de mysqli_stmt_store_result() pour mettre en mémoire tampon l'ensemble des résultats dans le handle de l'instruction.

Cette fonction retourne `0` à moins que toutes les lignes aient été récupérées du serveur.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Un entier représentant le nombre de lignes mises en mémoire tampon. Retourne `0` en mode non tamponné, sauf si toutes les lignes ont été récupérées du serveur.

> Note: Si le nombre de ligne est supérieur à `PHP_INT_MAX`, le nombre sera retourné en tant que chaîne de caractères.

### Exemples

Exemple #1 Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";

    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* Stocker le résultat dans un tampon interne */
    $stmt->store_result();

    printf("Nombre de lignes : %d.\n", $stmt->num_rows);
    ?>

Exemple #2 Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";

    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* Stocker le résultat dans un tampon interne */
    mysqli_stmt_store_result($stmt);

    printf("Nombre de lignes : %d.\n", mysqli_stmt_num_rows($stmt));
    ?>

Les exemples ci-dessus vont afficher :

    Nombre de lignes : 20.

### Voir aussi

- mysqli_stmt_store_result() - Stocke un ensemble de résultats dans un tampon interne
- mysqli_stmt_affected_rows() - Retourne le nombre total de lignes modifiées, effacées, insérées, ou correspondant par la dernière requête
- mysqli_prepare() - Prépare une requête SQL pour l'exécution

# mysqli_stmt::$param_count

# mysqli_stmt_param_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$param_count -- mysqli_stmt_param_count — Retourne le nombre de paramètres d'une commande SQL

### Description

Style orienté objet

int $mysqli_stmt->param_count;

Style procédural

function mysqli_stmt_param_count(mysqli_stmt `$statement`): int

Retourne le nombre de variables attendues par la commande préparée `stmt`.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Retourne un entier représentant le nombre de paramètres.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = $stmt->param_count;
        printf("La requête a %d variables.\n", $marker);

        /* Fermeture de la commande */
        $stmt->close();
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = mysqli_prepare($link, "SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = mysqli_stmt_param_count($stmt);
        printf("La requête a %d variables.\n", $marker);

        /* Fermeture de la commande */
        mysqli_stmt_close($stmt);
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    La requête a 2 variables.

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution

# mysqli_stmt::prepare

# mysqli_stmt_prepare

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::prepare -- mysqli_stmt_prepare — Prépare une requête SQL pour l'exécution

### Description

Style orienté objet

public function mysqli_stmt::prepare(string `$query`): bool

Style procédural

function mysqli_stmt_prepare(mysqli_stmt `$statement`, string `$query`): bool

Prépare la requête SQL `query`, pour la session de travail `stmt`.

Les variables SQL doivent être associées à une variable PHP à l'aide de la fonction mysqli_stmt_bind_param() et/ou mysqli_stmt_bind_result(), avant d'exécuter la requête.

> Note:

> Si on passe une requête à mysqli_stmt_prepare() qui est plus longue que `max_allowed_packet`, les codes d'erreur en retour seront différents selon lors de l'utilisation de MySQL Native Driver (`mysqlnd`) ou la MySQL Client Library (`libmysqlclient`). Le comportement est défini comme suit:

> - `mysqlnd` sur Linux retourne un code d'erreur de 1153. Le message d'erreur sera got a packet bigger than `max_allowed_packet` bytes.

> - `mysqlnd` sur Windows retourne un code d'erreur de 2006. Le message sera du type server has gone away.

> - `libmysqlclient` sur toute plateforme retourne le code d'erreur 2006. Le message sera du type server has gone away.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().
`query`

  La requête, sous forme de chaîne. Elle doit être constituée d'une commande SQL valide et unique.

  Ce paramètre peut inclure une ou plusieurs variables SQL, en utilisant des points d'interrogation (`?`) aux bons endroits.

  > Note:

  > Les marques sont autorisées uniquement dans certains endroits des requêtes SQL. Par exemple, elles le sont dans la liste `VALUES()` d'une requête `INSERT` (pour spécifier les valeurs des colonnes pour une ligne), ou dans une comparaison d'une clause `WHERE` pour spécifier une valeur de comparaison. Cependant, elles ne sont pas autorisées pour les identifiants (de tables ou de colonnes).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Exemple pour mysqli_stmt::prepare()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* Crée une requête préparée */
    $stmt = $mysqli->stmt_init();
    $stmt->prepare("SELECT District FROM City WHERE Name=?");

    /* Lie les paramètres aux marqueurs */
    $stmt->bind_param("s", $city);

    /* Exécute la requête */
    $stmt->execute();

    /* Lie les variables de résultat */
    $stmt->bind_result($district);

    /* Récupère la valeur */
    $stmt->fetch();

    printf("%s est dans le district de %s\n", $city, $district);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* Crée une requête préparée */
    $stmt = mysqli_stmt_init($link);
    mysqli_stmt_prepare($stmt, "SELECT District FROM City WHERE Name=?");

    /* Lie les paramètres aux marqueurs */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* Exécute la requête */
    mysqli_stmt_execute($stmt);

    /* Lie les variables de résultat */
    mysqli_stmt_bind_result($stmt, $district);

    /* Récupère la valeur */
    mysqli_stmt_fetch($stmt);

    printf("%s est dans le district de %s\n", $city, $district);

Les exemples ci-dessus vont afficher :

    Amersfoort est dans le district de Utrecht

### Voir aussi

- mysqli_stmt_init() - Initialise une commande MySQL
- 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_bind_param() - Lie des variables à une requête MySQL
- mysqli_stmt_bind_result() - Lie des variables à un jeu de résultats
- mysqli_stmt_get_result() - Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result
- mysqli_stmt_close() - Termine une requête préparée

# mysqli_stmt::reset

# mysqli_stmt_reset

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::reset -- mysqli_stmt_reset — Annule une requête préparée

### Description

Style orienté objet

public function mysqli_stmt::reset(): bool

Style procédural

function mysqli_stmt_reset(mysqli_stmt `$statement`): bool

Annule une requête préparée sur le client et sur le serveur après avoir été préparée.

Cette fonction annule la requête sur le serveur, annule les données envoyées en utilisant la fonction mysqli_stmt_send_long_data(), annule les jeux de résultats non mis en buffer mais aussi les erreurs courantes. Par contre, les jeux de résultats stockés ou liés ne sont pas annulés. Les jeux de résultats stockés sont effacés lors de l'exécution de la requête préparée (ou lorsqu'on les ferme).

Pour préparer de nouveau une requête, utiliser la fonction mysqli_stmt_prepare().

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution

# mysqli_stmt::result_metadata

# mysqli_stmt_result_metadata

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — Retourne les métadonnées de préparation de requête MySQL

### Description

Style orienté objet

public function mysqli_stmt::result_metadata(): mysqli_result|false

Style procédural

function mysqli_stmt_result_metadata(mysqli_stmt `$statement`): mysqli_result|false

Si une commande a été préparée par mysqli_prepare(), et qu'elle produira un résultat, mysqli_stmt_result_metadata() retourne l'objet de résultat qui sera utilisé pour lire les métadonnées, comme le nombre de champs et les informations de colonnes.

Ceci retourne un objet mysqli_result vide qui peut être utilisé pour accéder aux informations de métadonnées depuis la déclaration préparée sans avoir à récupérer les lignes de données réelles. Il n'est pas nécessaire d'utiliser cette fonction lors de l'utilisation de mysqli_stmt_get_result() pour récupérer l'ensemble complet des résultats d'une déclaration préparée en tant qu'objet de résultat.

> Note:

> Ce résultat peut être passé comme argument à toutes les fonctions qui demandent un champ, pour y lire les métadonnées :

> - mysqli_num_fields()

> - mysqli_fetch_field()

> - mysqli_fetch_field_direct()

> - mysqli_fetch_fields()

> - mysqli_field_count()

> - mysqli_field_seek()

> - mysqli_field_tell()

> - mysqli_free_result()

> Note: Ce jeu de résultats retourné par mysqli_stmt_result_metadata() contient uniquement les métadonnées. Il ne contient pas de lignes de résultats. Les lignes sont obtenues en appelant mysqli_stmt_get_result() sur le gestionnaire de déclaration ou avec mysqli_stmt_fetch().

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Si la déclaration ne produit pas de résultat, `false` est retourné.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("DROP TABLE IF EXISTS friends");
    $mysqli->query("CREATE TABLE friends (id int, name varchar(20))");

    $mysqli->query("INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

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

    /* Lit les méta-données de résultat */
    $result = $stmt->result_metadata();

    /* Lit les informations d'un champ, depuis les méta-données */
    $field = $result->fetch_field();

    printf("Nom du champ : %s\n", $field->name);
    ?>

Exemple #2 Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "DROP TABLE IF EXISTS friends");
    mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

    mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $stmt = mysqli_prepare($link, "SELECT id, name FROM friends");
    mysqli_stmt_execute($stmt);

    /* Lit les méta-données de résultat */
    $result = mysqli_stmt_result_metadata($stmt);

    /* Lit les informations d'un champ, depuis les méta-données */
    $field = mysqli_fetch_field($result);

    printf("Nom du champ : %s\n", $field->name);
    ?>

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_free_result() - Libère la mémoire associée à un résultat
- mysqli_stmt_get_result() - Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result

# mysqli_stmt::send_long_data

# mysqli_stmt_send_long_data

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::send_long_data -- mysqli_stmt_send_long_data — Envoie des données MySQL par paquets

### Description

Style orienté objet

public function mysqli_stmt::send_long_data(int `$param_num`, string `$data`): bool

Style procédural

function mysqli_stmt_send_long_data(mysqli_stmt `$statement`, int `$param_num`, string `$data`): bool

Envoie les données au serveur par paquets, si la taille des données excède la limite de `max_allowed_packet`. Cette fonction peut être appelée plusieurs fois pour envoyer les données textes ou binaires de champs comme les BLOB ou TEXT.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().
`param_num`

  Indique quel paramètre doit être associé avec quelles données. Les paramètres sont numérotés à partir de 0.

`data`

  Une chaîne de caractères contenant les données à envoyer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $stmt = $mysqli->prepare("INSERT INTO messages (message) VALUES (?)");
    $null = NULL;
    $stmt->bind_param("b", $null);
    $fp = fopen("messages.txt", "r");
    while (!feof($fp)) {
        $stmt->send_long_data(0, fread($fp, 8192));
    }
    fclose($fp);
    $stmt->execute();
    ?>

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_stmt_bind_param() - Lie des variables à une requête MySQL

# mysqli_stmt::$sqlstate

# mysqli_stmt_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — Retourne le code SQLSTATE de la dernière opération MySQL

### Description

Style orienté objet

string $mysqli_stmt->sqlstate;

Style procédural

function mysqli_stmt_sqlstate(mysqli_stmt `$statement`): string

Retourne une chaîne contenant le code d'erreur SQLSTATE de la commande la plus récente qui a été préparée. Le code d'erreur est constitué de 5 caractères `'00000'`. Les valeurs des codes d'erreurs sont spécifiées par les normes ANSI SQL et ODBC. Pour la liste complète des valeurs, voir le fichier » http://dev.mysql.com/doc/mysql/en/error-handling.html.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Retourne la chaîne contenant le code d'erreur SQLSTATE. Le code d'erreur est constitué de 5 caractères. `'00000'` représente l'absence d'erreur.

### Exemples

Exemple #1 Style orienté objet

    <?php
    /* Ouvre la connexion */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Effacement de la table */
        $mysqli->query("DROP TABLE myCountry");

        /* Exécution de la requête */
        $stmt->execute();

        printf("Erreur : %s.\n", $stmt->sqlstate);

        /* Fermeture de la requête */
        $stmt->close();
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    /* Ouvre la connexion */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérifie la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Effacement de la table */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Exécution de la requête */
        mysqli_stmt_execute($stmt);

        printf("Erreur : %s.\n", mysqli_stmt_sqlstate($stmt));

        /* Fermeture de la requête */
        mysqli_stmt_close($stmt);
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Erreur : 42S02.

### Notes

> Note:

> Il est à noter que toutes les erreurs MySQL n'ont pas encore de correspondance en SQLSTATE. La valeur `HY000` (erreur générale) est utilisée pour les erreurs sans correspondance.

### Voir aussi

- 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::store_result

# mysqli_stmt_store_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::store_result -- mysqli_stmt_store_result — Stocke un ensemble de résultats dans un tampon interne

### Description

Style orienté objet

public function mysqli_stmt::store_result(): bool

Style procédural

function mysqli_stmt_store_result(mysqli_stmt `$statement`): bool

Cette fonction devrait être appelée pour les requêtes qui produisent un jeu de résultats (p. ex. `SELECT, SHOW, DESCRIBE, EXPLAIN`) seulement si le jeu de résultats complet doit être mis en tampon par PHP. Chaque appel successif à mysqli_stmt_fetch() retourne les données mises en tampon.

> Note:

> Il n'est pas nécessaire d'appeler mysqli_stmt_store_result() pour d'autres types de requête, mais si l'on le fait, ce n'est pas grave et ne causera aucune perte notable de performance dans tous les cas. Il est possible de détecter dans tous les cas si la requête va produire un jeu de résultats en regardant si la fonction mysqli_stmt_result_metadata() retourne `false`.

### Liste de paramètres

`statement`
  Style procédural uniquement : Un objet mysqli_stmt retourné par la fonction mysqli_stmt_init().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* Stocker le résultat dans un tampon interne */
    $stmt->store_result();

    printf("Nombre de lignes : %d.\n", $stmt->num_rows);

Exemple #2 Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* Stocker le résultat dans un tampon interne */
    mysqli_stmt_store_result($stmt);

    printf("Nombre de lignes : %d.\n", mysqli_stmt_num_rows($stmt));

Les exemples ci-dessus vont afficher :

    Nombre de lignes : 20.

### Voir aussi

- mysqli_prepare() - Prépare une requête SQL pour l'exécution
- mysqli_stmt_result_metadata() - Retourne les métadonnées de préparation de requête MySQL
- mysqli_stmt_fetch() - Lit des résultats depuis une requête MySQL préparée dans des variables liées

## Sommaire

- mysqli_stmt::$affected_rows — Retourne le nombre total de lignes modifiées, effacées, insérées, ou correspondant par la dernière requête
- mysqli_stmt::attr_get — Récupère la valeur courante d'un attribut de requête
- mysqli_stmt::attr_set — Modifie le comportement d'une requête préparée
- 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 — Termine une requête préparée
- mysqli_stmt::__construct — Construit un nouvel objet mysqli_stmt
- mysqli_stmt::data_seek — Ajuste le pointeur de résultat vers une ligne arbitraire dans le résultat mis en mémoire tampon.
- 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::$error_list — Retourne une liste d'erreurs pour la dernière requête exécutée
- 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 colonnes dans la requête donnée
- mysqli_stmt::free_result — Libère le résultat MySQL de la mémoire
- mysqli_stmt::get_result — Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result
- mysqli_stmt::get_warnings — Récupère le résultat de SHOW WARNINGS
- mysqli_stmt::$insert_id — Récupère l'ID généré par la dernière requête INSERT
- mysqli_stmt::more_results — Vérifie s'il y a encore des résultats depuis une requête multiple
- mysqli_stmt::next_result — Lit le résultat suivant depuis une requête multiple
- mysqli_stmt::$num_rows — Retourne le nombre de lignes extraites du serveur
- mysqli_stmt::$param_count — Retourne le nombre de paramètres d'une commande SQL
- 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étadonné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 — Stocke un ensemble de résultats dans un tampon interne

# La classe mysqli_result

(PHP 5, PHP 7, PHP 8)

## Introduction

Représente le jeu de résultats obtenu depuis une requête.

## Synopsis de la classe

class mysqli_result implements IteratorAggregate {
/* Propriétés */
public readonly int $current_field;
public readonly int $field_count;
public readonly ?array $lengths;
public readonly int|string $num_rows;
public int $type;
/* Méthodes */
public function __construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)
public function data_seek(int `$offset`): bool
public function fetch_all(int `$mode` = `MYSQLI_NUM`): array
public function fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false
public function fetch_assoc(): array|null|false
public function fetch_column(int `$column` = 0): null|int|float|string|false
public function fetch_field(): object|false
public function fetch_field_direct(int `$index`): object|false
public function fetch_fields(): array
public function fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false
public function fetch_row(): array|null|false
public function field_seek(int `$index`): true
public function free(): void
public function close(): void
public function free_result(): void
public function getIterator(): Iterator
}

## Propriétés

type

  Enregistre le fait que le résultat soit mis en mémoire tampon ou non sous la forme d'un entier (`MYSQLI_STORE_RESULT` ou `MYSQLI_USE_RESULT`, respectivement).

## Historique

Version | Description
--- | ---
8.0.0 | La classe mysqli_result implémente désormais IteratorAggregate. Auparavant, seule Traversable était implémentée.

# mysqli_result::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_result::__construct — Construit un objet mysqli_result

### Description

public function mysqli_result::__construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)

Cette méthode construit un nouvel objet mysqli_result.

Ceci peut être utilisé pour créer l'objet mysqli_result après avoir appelé les fonctions mysqli_real_query() ou mysqli_multi_query(). Construire l'objet manuellement est équivalent à appeler les fonctions mysqli_store_result() ou mysqli_use_result().

### Liste de paramètres

`mysql`
  Seulement en style procédural : Un objet mysqli retourné par la fonction mysqli_connect() ou mysqli_init().
`result_mode`

  Le mode de résultat peut être une des 2 constantes indiquant comment le résultat sera retourné par le serveur MySQL.

  `MYSQLI_STORE_RESULT` (défaut) - créer un objet mysqli_result avec un jeu de résultats tamponné.

  `MYSQLI_USE_RESULT` - créer un objet mysqli_result avec un jeu de résultats non-tamponné. Tant qu'il reste des enregistrements en attente d'être récupérés, la ligne de connexion est occupée et tous les appels suivants retournent l'erreur `Commands out of sync`. Pour éviter l'erreur, tous les enregistrements doivent être récupérés du serveur ou le jeu de résultats doit être jeté en appelant mysqli_free_result(). La connexion doit rester ouverte pour que les lignes soient récupérées.

### Erreurs / Exceptions

Si le rapport d'erreurs mysqli est activé (`MYSQLI_REPORT_ERROR`) et que l'opération demandée échoue, un avertissement est généré. Si, en plus, le mode est défini sur `MYSQLI_REPORT_STRICT`, une mysqli_sql_exception est lancée à la place.

### Exemples

Exemple #1 Création d'un objet mysqli_result

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Requête SELECT retournant un jeu de résultats */
    $mysqli->real_query("SELECT Name FROM City LIMIT 10");

    $result = new mysqli_result($mysqli);
    printf("Select returned %d rows.\n", $result->num_rows);

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Select returned 10 rows.

### Voir aussi

- mysqli_multi_query() - Exécute une ou plusieurs requêtes sur la base de données
- mysqli_real_query() - Exécute une requête SQL
- mysqli_store_result() - Transfère un jeu de résultats à partir de la dernière requête
- mysqli_use_result() - Initialise la récupération d'un jeu de résultats

# mysqli_result::$current_field

# mysqli_field_tell

(PHP 5, PHP 7, PHP 8)

mysqli_result::$current_field -- mysqli_field_tell — Récupère la position courante d'un champ dans un pointeur de résultat

### Description

Style orienté objet

int $mysqli_result->current_field;

Style procédural

function mysqli_field_tell(mysqli_result `$result`): int

Retourne la position du curseur de champ utilisé par le dernier appel à la fonction mysqli_fetch_field(). Cette valeur peut être utilisée comme argument de la fonction mysqli_field_seek().

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().

### Valeurs de retour

Retourne la position courante du curseur de champ.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Récupération des informations sur le champ pour toutes les colonnes */
        while ($finfo = $result->fetch_field()) {

            /* Récupération de la position du pointeur de champ */
            $currentfield = $result->current_field;

            printf("Colonne %d :\n", $currentfield);
            printf("Nom :     %s\n", $finfo->name);
            printf("Table :    %s\n", $finfo->table);
            printf("Longueur max. : %d\n", $finfo->max_length);
            printf("Drapeaux :    %d\n", $finfo->flags);
            printf("Type :     %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Récupération des informations sur le champ pour toutes les colonnes */
        while ($finfo = mysqli_fetch_field($result)) {

            /* Récupération de la position du pointeur de champ */
            $currentfield = mysqli_field_tell($result);

            printf("Colonne %d :\n", $currentfield);
            printf("Nom :     %s\n", $finfo->name);
            printf("Table :    %s\n", $finfo->table);
            printf("Longueur max. : %d\n", $finfo->max_length);
            printf("Drapeaux :    %d\n", $finfo->flags);
            printf("Type :     %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Colonne 1 :
    Nom :           Name
    Table :         Country
    Longueur max. : 11
    Drapeaux :      1
    Type :          254

    Colonne 2 :
    Nom :           SurfaceArea
    Table      :    Country
    Longueur max. : 10
    Drapeaux :      32769
    Type :          4

### Voir aussi

- mysqli_fetch_field() - Retourne le prochain champ dans le jeu de résultats
- mysqli_field_seek() - Déplace le pointeur de résultat sur le champ spécifié

# mysqli_result::data_seek

# mysqli_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::data_seek -- mysqli_data_seek — Déplace le pointeur interne de résultat

### Description

Style orienté objet

public function mysqli_result::data_seek(int `$offset`): bool

Style procédural

function mysqli_data_seek(mysqli_result `$result`, int `$offset`): bool

La fonction mysqli_data_seek() déplace le pointeur interne de résultat associé au jeu de résultat représenté par `result`, en le faisant pointer sur la ligne spécifiée par `offset`.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().
`offset`

  Le décalage de la ligne. Le paramètre `offset` doit être compris entre zéro et mysqli_num_rows() - 1 (0..mysqli_num_rows() - 1).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysqli::data_seek()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $result = $mysqli->query($query);

    /* Recherche la ligne 401 */
    $result->data_seek(400);

    /* Récupération de cette ligne */
    $row = $result->fetch_row();
    printf("Ville: %s  Code Pays: %s\n", $row[0], $row[1]);
    ?>

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $result = mysqli_query($link, $query);

    /* Recherche la ligne 401 */
    mysqli_data_seek($result, 400);

    /* Récupération de cette ligne */
    $row = mysqli_fetch_row($result);
    printf("Ville: %s  Code Pays: %s\n", $row[0], $row[1]);

Les exemples ci-dessus vont afficher :

    Ville: Benin City  Code Pays: NGA

Exemple #2 Ajustement du pointeur de résultat lors de l'itération

Cette fonction peut être utile lors de l'itération sur l'ensemble des résultats pour imposer un ordre personnalisé ou pour rembobiner l'ensemble des résultats lors d'itérations multiples.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 15,4";
    $result = $mysqli->query($query);

    /* Interroger l'ensemble des résultats dans l'ordre inverse */
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);

        /* Récupération de cette ligne */
        $row = $result->fetch_row();
        printf("Ville: %s  Code Pays: %s\n", $row[0], $row[1]);
    }

    /* Remise à zéro du pointeur au début de l'ensemble de résultats */
    $result->data_seek(0);
    print "\n";

    /* Interroger à nouveau le même ensemble de résultats */
    while ($row = $result->fetch_row()) {
        printf("Ville: %s  Code Pays: %s\n", $row[0], $row[1]);
    }

Les exemples ci-dessus vont afficher :

    Ville: Acmbaro  Code Pays: MEX
    Ville: Abuja  Code Pays: NGA
    Ville: Abu Dhabi  Code Pays: ARE
    Ville: Abottabad  Code Pays: PAK

    Ville: Abottabad  Code Pays: PAK
    Ville: Abu Dhabi  Code Pays: ARE
    Ville: Abuja  Code Pays: NGA
    Ville: Acmbaro  Code Pays: MEX

### Notes

> Note:

> Cette fonction ne peut être utilisée qu'avec des résultats obtenus avec la fonction mysqli_store_result(), mysqli_query() ou mysqli_stmt_get_result().

### Voir aussi

- mysqli_store_result() - Transfère un jeu de résultats à partir de la dernière requête
- mysqli_fetch_row() - Récupère une ligne de résultat sous forme de tableau indexé
- mysqli_fetch_array() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux
- mysqli_fetch_assoc() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif
- mysqli_fetch_object() - Retourne la ligne suivante d'un ensemble de résultats sous forme d'objet
- mysqli_query() - Exécute une requête sur la base de données
- mysqli_num_rows() - Retourne le nombre de lignes dans le jeu de résultats

# mysqli_result::fetch_all

# mysqli_fetch_all

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_result::fetch_all -- mysqli_fetch_all — Récupère toutes les lignes de résultats dans un tableau associatif, numérique, ou les deux

### Description

Style orienté objet

public function mysqli_result::fetch_all(int `$mode` = `MYSQLI_NUM`): array

Style procédural

function mysqli_fetch_all(mysqli_result `$result`, int `$mode` = `MYSQLI_NUM`): array

Retourne un tableau deux dimensionnel de tous les résultats sous forme d'un tableau associatif, numérique, ou les deux.

> Note:

> Antérieur à PHP 8.1.0, disponible uniquement avec mysqlnd.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().
`mode`

  Ce paramètre optionnel est une constante, qui indique le type de tableau qui doit être produit à partir du résultat. Les valeurs possibles sont les constantes `MYSQLI_ASSOC`, `MYSQLI_NUM`, ou `MYSQLI_BOTH`.

### Valeurs de retour

Retourne un tableau associatif ou numérique contenant les lignes de résultat.

### Historique

Version | Description
--- | ---
8.1.0 | Désormais aussi disponible lors de la liaison avec libmysqlclient.

### Exemples

Exemple #1 Exemple avec mysqli_result::fetch_all()

Style orienté objet

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");
    $result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");
    $rows = $result->fetch_all(MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Style procédural

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");
    $result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");
    $rows = mysqli_fetch_all($result, MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Les exemples ci-dessus vont afficher :

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Voir aussi

- mysqli_fetch_array() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux
- mysqli_fetch_column() - Récupère une seule colonne de la ligne suivante d'un jeu de résultats
- mysqli_query() - Exécute une requête sur la base de données

# mysqli_result::fetch_array

# mysqli_fetch_array

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_array -- mysqli_fetch_array — Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux

### Description

Style orienté objet

public function mysqli_result::fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false

Style procédural

function mysqli_fetch_array(mysqli_result `$result`, int `$mode` = `MYSQLI_BOTH`): array|null|false

Retourne une ligne de données de l'ensemble de résultats et la renvoie sous forme de tableau. Chaque appel ultérieur à cette fonction renverra la ligne suivante dans l'ensemble de résultats, ou `null` s'il n'y a plus de lignes.

En plus d'enregistrer les données sous forme d'un tableau à indices numériques, elle peut aussi les enregistrer dans un tableau associatif, en utilisant les noms des champs comme clés.

Si deux ou plusieurs colonnes du résultat ont le même nom, la dernière colonne sera prioritaire et écrasera toutes les données précédentes. Pour accéder aux autres colonnes du même nom, l'on doit utiliser l'index numérique, ou faire un alias pour chaque colonne.

> Note: Les noms des champs retournés par cette fonction sont sensibles à la casse.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().
`mode`

  Le second argument optionnel est une constante indiquant quel type de tableau doit être renvoyé à partir de la ligne de données courante. Les valeurs possibles pour ce paramètre sont les constantes `MYSQLI_ASSOC`, `MYSQLI_NUM`, et `MYSQLI_BOTH`.

  En utilisant la constante `MYSQLI_ASSOC`, cette fonction se comportera comme la fonction mysqli_fetch_assoc(), tandis que `MYSQLI_NUM` la fera agir comme la fonction mysqli_fetch_row(). La constante `MYSQLI_BOTH`, créera elle un tableau qui sera à la fois associatif et indexé numériquement.

### Valeurs de retour

Retourne un tableau représentant la ligne récupérée, `null` s'il n'y a plus de lignes dans le jeu de résultats, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysqli_result::fetch_array()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3";
    $result = $mysqli->query($query);

    /* Tableau numérique */
    $row = $result->fetch_array(MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* Tableau associatif */
    $row = $result->fetch_array(MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* Tableau associatif et numérique */
    $row = $result->fetch_array(MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3";
    $result = mysqli_query($mysqli, $query);

    /* Tableau numérique */
    $row = mysqli_fetch_array($result, MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* Tableau associatif */
    $row = mysqli_fetch_array($result, MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* Tableau associatif et numérique */
    $row = mysqli_fetch_array($result, MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Voir aussi

- mysqli_fetch_assoc() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif
- mysqli_fetch_column() - Récupère une seule colonne de la ligne suivante d'un jeu de résultats
- mysqli_fetch_row() - Récupère une ligne de résultat sous forme de tableau indexé
- mysqli_fetch_object() - Retourne la ligne suivante d'un ensemble de résultats sous forme d'objet
- mysqli_query() - Exécute une requête sur la base de données
- mysqli_data_seek() - Déplace le pointeur interne de résultat

# mysqli_result::fetch_assoc

# mysqli_fetch_assoc

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_assoc -- mysqli_fetch_assoc — Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif

### Description

Style orienté objet

public function mysqli_result::fetch_assoc(): array|null|false

Style procédural

function mysqli_fetch_assoc(mysqli_result `$result`): array|null|false

Retourne une ligne de données de l'ensemble de résultats et la renvoie sous forme de tableau associatif. Chaque appel ultérieur à cette fonction renverra la ligne suivante dans l'ensemble de résultats, ou `null` s'il n'y a plus de lignes.

Si deux ou plusieurs colonnes du résultat ont le même nom, la dernière colonne sera prioritaire et écrasera toutes les données précédentes. Pour accéder à plusieurs colonnes portant le même nom, la mysqli_fetch_row() peut être utilisée pour récupérer le tableau indexé numériquement ou des alias peuvent être utilisés dans la liste de sélection de la requête SQL pour donner des noms différents aux colonnes.

> Note: Les noms des champs retournés par cette fonction sont sensibles à la casse.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().

### Valeurs de retour

Renvoie un tableau associatif représentant la ligne extraite, où chaque clé du tableau représente le nom d'une des colonnes du jeu de résultats, `null` s'il n'y a plus de lignes dans le jeu de résultats, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple mysqli_result::fetch_assoc()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* Récupère un tableau associatif */
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* Récupère un tableau associatif */
    while ($row = mysqli_fetch_assoc($result)) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

Exemple #2 Comparaison de l'usage de mysqli_result iterator et mysqli_result::fetch_assoc()

mysqli_result peut être itéré en utilisant un `foreach`. Le jeu de résultats sera toujours itéré à partir de la première ligne, quel que soit la position actuelle.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, CountryCode FROM City ORDER BY ID DESC';

    // Utilise un itérateur
    $result = $mysqli->query($query);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

    echo "\n==================\n";

    // N'utilise pas d'itérateur
    $result = $mysqli->query($query);
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Résultat de l'exemple ci-dessus est similaire à :

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

    ==================
    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Voir aussi

- mysqli_fetch_array() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux
- mysqli_fetch_column() - Récupère une seule colonne de la ligne suivante d'un jeu de résultats
- mysqli_fetch_row() - Récupère une ligne de résultat sous forme de tableau indexé
- mysqli_fetch_object() - Retourne la ligne suivante d'un ensemble de résultats sous forme d'objet
- mysqli_query() - Exécute une requête sur la base de données
- mysqli_data_seek() - Déplace le pointeur interne de résultat

# mysqli_result::fetch_column

# mysqli_fetch_column

(PHP 8 >= 8.1.0)

mysqli_result::fetch_column -- mysqli_fetch_column — Récupère une seule colonne de la ligne suivante d'un jeu de résultats

### Description

Style orienté objet

public function mysqli_result::fetch_column(int `$column` = 0): null|int|float|string|false

Style procédural

function mysqli_fetch_column(mysqli_result `$result`, int `$column` = 0): null|int|float|string|false

Récupère une ligne de données du jeu de résultats et retourne la colonne indexée à 0. Chaque appel ultérieur à cette fonction retournera la valeur de la prochaine ligne du jeu de résultats, ou `false` s'il n'y a plus de lignes.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().
`column`

  Le numéro indexé à 0 de la colonne qu'on souhaite récupérer de la ligne. Si aucune valeur n'est fournie, la première colonne sera retournée.

### Valeurs de retour

Renvoie une seule colonne de la ligne suivante d'un jeu de résultats ou `false` s'il n'y a plus de lignes.

Avertissement

Il n'y a aucun moyen de retourner une autre colonne de la même ligne si l'on utilise cette fonction pour récupérer des données.

### Exemples

Exemple #1 Exemple de mysqli_result::fetch_column()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

    $result = $mysqli->query($query);

    /* Récupère une seule valeur de la deuxième colonne */
    while ($Name = $result->fetch_column(1)) {
        printf("%s\n", $Name);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

    $result = mysqli_query($mysqli, $query);

    /* Récupère une seule valeur de la deuxième colonne */
    while ($Name = mysqli_fetch_column($result, 1)) {
        printf("%s\n", $Name);
    }

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Rafah
    Nablus
    Jabaliya
    Hebron
    Khan Yunis

### Voir aussi

- mysqli_fetch_all() - Récupère toutes les lignes de résultats dans un tableau associatif, numérique, ou les deux
- mysqli_fetch_array() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux
- mysqli_fetch_assoc() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif
- mysqli_fetch_object() - Retourne la ligne suivante d'un ensemble de résultats sous forme d'objet
- mysqli_fetch_row() - Récupère une ligne de résultat sous forme de tableau indexé
- mysqli_data_seek() - Déplace le pointeur interne de résultat

# mysqli_result::fetch_field

# mysqli_fetch_field

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field -- mysqli_fetch_field — Retourne le prochain champ dans le jeu de résultats

### Description

Style orienté objet

public function mysqli_result::fetch_field(): object|false

Style procédural

function mysqli_fetch_field(mysqli_result `$result`): object|false

Retourne les attributs de la prochaine colonne dans le jeu de résultats représenté par le paramètre `result` en tant qu'objet. Appelez cette fonction de façon répétitive pour récupérer les informations de toutes les colonnes.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().

### Valeurs de retour

Retourne un objet qui contient les informations d'un champ ou `false` si aucune information n'est disponible pour ce champ.

Propriétés de l'objet
Propriété | Description
--- | ---
name | Le nom de la colonne
orgname | Le nom original de la colonne si un alias a été spécifié
table | Le nom de la table à laquelle ce champ appartient (s'il n'a pas été calculé)
orgtable | Le nom original de la table si un alias a été spécifié
def | Inutilisé. Toujours une chaîne vide
db | Le nom de la base de données
catalog | Inutilisé. Toujours `"def"`
max_length | La longueur maximale du champ pour le jeu de résultats. À partir de PHP 8.1, cette valeur est toujours `0`.
length | La largeur du champ en octets. Pour les colonnes de type chaîne de caractères, la valeur de longueur varie en fonction du jeu de caractères de la connexion. Par exemple, si le jeu de caractères est `latin1`, un jeu de caractères mono-octet, la valeur de longueur pour une requête `SELECT 'abc'` est 3. Si le jeu de caractères est `utf8mb4`, un jeu de caractères multioctets dans lequel les caractères occupent jusqu'à 4 octets, la valeur de longueur est 12.
charsetnr | Le numéro du jeu de caractères pour ce champ
flags | Un entier représentant le bit-flags pour ce champ
type | Le type de données utilisées pour ce champ
decimals | Le nombre de décimales pour les champs numériques et la précision des secondes fractionnaires pour les champs temporels.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Récupère les informations d'un champ pour toutes les colonnes */
        while ($finfo = $result->fetch_field()) {

            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Récupère les informations d'un champ pour toutes les colonnes */
        while ($finfo = mysqli_fetch_field($result)) {

            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Name:     Name
    Table:    Country
    max. Len: 11
    Flags:    1
    Type:     254

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### Voir aussi

- mysqli_num_fields() - Récupère le nombre de champs dans l'ensemble de résultats
- mysqli_fetch_field_direct() - Récupère les métadonnées d'un champ unique
- mysqli_fetch_fields() - Retourne un tableau d'objets représentant les champs dans le résultat
- mysqli_field_seek() - Déplace le pointeur de résultat sur le champ spécifié

# mysqli_result::fetch_field_direct

# mysqli_fetch_field_direct

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — Récupère les métadonnées d'un champ unique

### Description

Style orienté objet

public function mysqli_result::fetch_field_direct(int `$index`): object|false

Style procédural

function mysqli_fetch_field_direct(mysqli_result `$result`, int `$index`): object|false

Retourne un objet qui contient les métadonnées d'un champ dans le jeu de résultats spécifié.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().
`index`

  Le numéro du champ. Cette valeur doit être dans l'intervalle `0` à `nombre de champs - 1`.

### Valeurs de retour

Retourne un objet qui contient les métadonnées d'un champ ou `false` si aucune métadonnée n'est spécifiée pour le champ `index`.

Propriétés de l'objet
Propriété | Description
--- | ---
name | Le nom de la colonne
orgname | Le nom original de la colonne si un alias a été spécifié
table | Le nom de la table à laquelle ce champ appartient (s'il n'a pas été calculé)
orgtable | Le nom original de la table si un alias a été spécifié
def | Inutilisé. Toujours une chaîne vide
db | Le nom de la base de données
catalog | Inutilisé. Toujours `"def"`
max_length | La longueur maximale du champ pour le jeu de résultats. À partir de PHP 8.1, cette valeur est toujours `0`.
length | La largeur du champ en octets. Pour les colonnes de type chaîne de caractères, la valeur de longueur varie en fonction du jeu de caractères de la connexion. Par exemple, si le jeu de caractères est `latin1`, un jeu de caractères mono-octet, la valeur de longueur pour une requête `SELECT 'abc'` est 3. Si le jeu de caractères est `utf8mb4`, un jeu de caractères multioctets dans lequel les caractères occupent jusqu'à 4 octets, la valeur de longueur est 12.
charsetnr | Le numéro du jeu de caractères pour ce champ
flags | Un entier représentant le bit-flags pour ce champ
type | Le type de données utilisées pour ce champ
decimals | Le nombre de décimales pour les champs numériques et la précision des secondes fractionnaires pour les champs temporels.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Récupère les informations du champ pour la colonne 'SurfaceArea' */
        $finfo = $result->fetch_field_direct(1);

        printf("Nom        : %s\n", $finfo->name);
        printf("Table      : %s\n", $finfo->table);
        printf("Taille max : %d\n", $finfo->max_length);
        printf("Flags      : %d\n", $finfo->flags);
        printf("Type       : %d\n", $finfo->type);

        $result->close();
    }

    /* Fermeture de la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Récupère les informations du champ pour la colonne 'SurfaceArea' */
        $finfo = mysqli_fetch_field_direct($result, 1);

        printf("Nom        : %s\n", $finfo->name);
        printf("Table      : %s\n", $finfo->table);
        printf("Taille max : %d\n", $finfo->max_length);
        printf("Flags      : %d\n", $finfo->flags);
        printf("Type       : %d\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* Fermeture de la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Nom        : SurfaceArea
    Table      : Country
    Taille max : 10
    Flags      : 32769
    Type       : 4

### Voir aussi

- mysqli_num_fields() - Récupère le nombre de champs dans l'ensemble de résultats
- mysqli_fetch_field() - Retourne le prochain champ dans le jeu de résultats
- mysqli_fetch_fields() - Retourne un tableau d'objets représentant les champs dans le résultat

# mysqli_result::fetch_fields

# mysqli_fetch_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_fields -- mysqli_fetch_fields — Retourne un tableau d'objets représentant les champs dans le résultat

### Description

Style orienté objet

public function mysqli_result::fetch_fields(): array

Style procédural

function mysqli_fetch_fields(mysqli_result `$result`): array

Cette fonction fonctionne comme mysqli_fetch_field() à la différence que, au lieu de retourner un objet à la fois pour chaque champ, les colonnes sont retournées en tant que tableau d'objets.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().

### Valeurs de retour

Renvoie un tableau d'objets contenant des informations sur la définition des champs.

Propriétés de l'objet
Propriété | Description
--- | ---
name | Le nom de la colonne
orgname | Le nom original de la colonne si un alias a été spécifié
table | Le nom de la table à laquelle ce champ appartient (s'il n'a pas été calculé)
orgtable | Le nom original de la table si un alias a été spécifié
def | Inutilisé. Toujours une chaîne vide
db | Le nom de la base de données
catalog | Inutilisé. Toujours `"def"`
max_length | La longueur maximale du champ pour le jeu de résultats. À partir de PHP 8.1, cette valeur est toujours `0`.
length | La largeur du champ en octets. Pour les colonnes de type chaîne de caractères, la valeur de longueur varie en fonction du jeu de caractères de la connexion. Par exemple, si le jeu de caractères est `latin1`, un jeu de caractères mono-octet, la valeur de longueur pour une requête `SELECT 'abc'` est 3. Si le jeu de caractères est `utf8mb4`, un jeu de caractères multioctets dans lequel les caractères occupent jusqu'à 4 octets, la valeur de longueur est 12.
charsetnr | Le numéro du jeu de caractères pour ce champ
flags | Un entier représentant le bit-flags pour ce champ
type | Le type de données utilisées pour ce champ
decimals | Le nombre de décimales pour les champs numériques et la précision des secondes fractionnaires pour les champs temporels.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $mysqli = new mysqli("127.0.0.1", "root", "foofoo", "sakila");

    /* vérification de la connexion */
    if ($mysqli->connect_errno) {
        printf("Échec de la connexion : %s\n", $mysqli->connect_error);
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Définir le jeu de caractère, pour montrer son impact sur certaines valeurs (par exemple, longueurs en octets)
        $mysqli->set_charset($charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "============================\n";
        echo "Jeu de caractères : $charset\n";
        echo "============================\n";

        if ($result = $mysqli->query($query)) {

            /* Récupère les informations des champs pour toutes les colonnes */
            $finfo = $result->fetch_fields();

            foreach ($finfo as $val) {
                printf("Name:      %s\n",   $val->name);
                printf("Table:     %s\n",   $val->table);
                printf("Max. Len:  %d\n",   $val->max_length);
                printf("Length:    %d\n",   $val->length);
                printf("charsetnr: %d\n",   $val->charsetnr);
                printf("Flags:     %d\n",   $val->flags);
                printf("Type:      %d\n\n", $val->type);
            }
            $result->free();
        }
    }
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    $link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");

    /* vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Définir le jeu de caractère, pour montrer son impact sur certaines valeurs (par exemple, longueurs en octets)
        mysqli_set_charset($link, $charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "============================\n";
        echo "Jeu de caractères : $charset\n";
        echo "============================\n";

        if ($result = mysqli_query($link, $query)) {

            /* Récupère les informations des champs pour toutes les colonnes */
            $finfo = mysqli_fetch_fields($result);

            foreach ($finfo as $val) {
                printf("Name:      %s\n",   $val->name);
                printf("Table:     %s\n",   $val->table);
                printf("Max. Len:  %d\n",   $val->max_length);
                printf("Length:    %d\n",   $val->length);
                printf("charsetnr: %d\n",   $val->charsetnr);
                printf("Flags:     %d\n",   $val->flags);
                printf("Type:      %d\n\n", $val->type);
            }
            mysqli_free_result($result);
        }
    }

    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    ============================
    Jeu de caractères : latin1
    ============================
    Name:      actor_id
    Table:     actor
    Max. Len:  3
    Length:    5
    charsetnr: 63
    Flags:     49699
    Type:      2

    Name:      last_name
    Table:     actor
    Max. Len:  12
    Length:    45
    charsetnr: 8
    Flags:     20489
    Type:      253

    ============================
    Jeu de caractères : utf8
    ============================
    Name:      actor_id
    Table:     actor
    Max. Len:  3
    Length:    5
    charsetnr: 63
    Flags:     49699
    Type:      2

    Name:      last_name
    Table:     actor
    Max. Len:  12
    Length:    135
    charsetnr: 33
    Flags:     20489

### Voir aussi

- mysqli_num_fields() - Récupère le nombre de champs dans l'ensemble de résultats
- mysqli_fetch_field_direct() - Récupère les métadonnées d'un champ unique
- mysqli_fetch_field() - Retourne le prochain champ dans le jeu de résultats

# mysqli_result::fetch_object

# mysqli_fetch_object

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_object -- mysqli_fetch_object — Retourne la ligne suivante d'un ensemble de résultats sous forme d'objet

### Description

Style orienté objet

public function mysqli_result::fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Style procédural

function mysqli_fetch_object(mysqli_result `$result`, string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Retourne une ligne de données dans le jeu de résultats et la renvoie sous forme d'objet, où chaque propriété représente le nom de la colonne du jeu de résultats. Chaque appel ultérieur à cette fonction renverra la ligne suivante dans l'ensemble de résultats, ou `null` s'il n'y a plus de lignes.

Si deux ou plusieurs colonnes du résultat ont le même nom, la dernière colonne sera prioritaire et écrasera toutes les données précédentes. Pour accéder à plusieurs colonnes portant le même nom, la mysqli_fetch_row() peut être utilisée pour récupérer le tableau indexé numériquement ou des alias peuvent être utilisés dans la liste de sélection de la requête SQL pour donner des noms différents aux colonnes.

> Note: Cette fonction affecte les propriétés de l'objet avant d'en appeler le constructeur.

> Note: Les noms des champs retournés par cette fonction sont sensibles à la casse.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().
`class`

  Le nom de la classe à instancier. Si non fourni, un objet stdClass sera retourné.

`constructor_args`

  Un tableau de paramètres (optionnel) à passer au constructeur de l'objet `class`.

### Valeurs de retour

Retourne un objet représentant la ligne récupérée, où chaque propriété représente le nom de la colonne du jeu de résultats, `null` s'il n'y a plus de lignes dans le jeu de résultats, ou `false` si une erreur survient.

### Erreurs / Exceptions

Une ValueError est lancée quand `constructor_args` n'est pas vide et que la classe n'a pas de constructeur.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une exception ValueError quand `constructor_args` n'est pas vide et que la classe n'a pas de constructeur ; précédemment, une exception Exception était déclenchée.
8.0.0 | `constructor_args` accepte désormais `[]` pour les constructeurs avec 0 paramètre ; auparavant une exception était lancée.

### Exemples

Exemple #1 Exemple mysqli_result::fetch_object()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    while ($obj = $result->fetch_object()) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($link, $query);

    while ($obj = mysqli_fetch_object($result)) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Voir aussi

- mysqli_fetch_array() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux
- mysqli_fetch_assoc() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif
- mysqli_fetch_column() - Récupère une seule colonne de la ligne suivante d'un jeu de résultats
- mysqli_fetch_row() - Récupère une ligne de résultat sous forme de tableau indexé
- mysqli_query() - Exécute une requête sur la base de données
- mysqli_data_seek() - Déplace le pointeur interne de résultat

# mysqli_result::fetch_row

# mysqli_fetch_row

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_row -- mysqli_fetch_row — Récupère une ligne de résultat sous forme de tableau indexé

### Description

Style orienté objet

public function mysqli_result::fetch_row(): array|null|false

Style procédural

function mysqli_fetch_row(mysqli_result `$result`): array|null|false

Récupère une ligne de données à partir du jeu de résultats représenté par `result` et le retourne en tant que tableau indexé, où chaque colonne est une case du tableau, celui-ci commençant à 0 (zéro). Chaque nouvel appel à mysqli_fetch_row() retournera la prochaine ligne dans le jeu de résultats, ou `null` s'il n'y a plus de lignes.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().

### Valeurs de retour

Retourne un tableau énuméré représentant la ligne récupérée, `null` s'il n'y a plus de lignes dans le jeu de résultats, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple mysqli_result::fetch_row()

Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* Récupère un tableau d'objets */
    while ($row = $result->fetch_row()) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* Récupère un tableau associatif */
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Les exemples ci-dessus vont afficher quelque chose de similaire à :

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Voir aussi

- mysqli_fetch_array() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux
- mysqli_fetch_assoc() - Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif
- mysqli_fetch_column() - Récupère une seule colonne de la ligne suivante d'un jeu de résultats
- mysqli_fetch_object() - Retourne la ligne suivante d'un ensemble de résultats sous forme d'objet
- mysqli_query() - Exécute une requête sur la base de données
- mysqli_data_seek() - Déplace le pointeur interne de résultat

# mysqli_result::$field_count

# mysqli_num_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::$field_count -- mysqli_num_fields — Récupère le nombre de champs dans l'ensemble de résultats

### Description

Style orienté objet

int $mysqli_result->field_count;

Style procédural

function mysqli_num_fields(mysqli_result `$result`): int

Retourne le nombre de champs dans l'ensemble de résultats.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().

### Valeurs de retour

Un int représentant le nombre de champs.

### Exemples

Exemple #1 Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Détermine le nombre de champs dans le jeu de résultats */
    $field_cnt = $result->field_count;

    printf("Le résultat a %d champs.\n", $field_cnt);
    ?>

Exemple #2 Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Détermine le nombre de champs dans le jeu de résultats */
    $field_cnt = mysqli_num_fields($result);

    printf("Le résultat a %d champs.\n", $field_cnt);
    ?>

Les exemples ci-dessus vont afficher :

    Le résultat a 4 champs.

### Voir aussi

- mysqli_fetch_field() - Retourne le prochain champ dans le jeu de résultats

# mysqli_result::field_seek

# mysqli_field_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::field_seek -- mysqli_field_seek — Déplace le pointeur de résultat sur le champ spécifié

### Description

Style orienté objet

public function mysqli_result::field_seek(int `$index`): true

Style procédural

function mysqli_field_seek(mysqli_result `$result`, int `$index`): true

Place le curseur sur le champ spécifié par le numéro `index`. Le prochain appel à la fonction mysqli_fetch_field() retournera la définition du champ de la colonne associée à cette position.

> Note:

> Pour se déplacer au début d'une ligne, passez une position ayant pour valeur zéro.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().
`index`

  Le numéro du champ. Cette valeur doit être dans l'intervalle `0` à `nombre de champs - 1`.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction retourne désormais toujours `true`. Auparavant, elle renvoyait `false` en cas d'échec.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Récupération des informations du champ pour la 2ème colonne */
        $result->field_seek(1);
        $finfo = $result->fetch_field();

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n\n", $finfo->type);

        $result->close();
    }

    /* Ferme la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Récupération des informations du champ pour la 2ème colonne */
        mysqli_field_seek($result, 1);
        $finfo = mysqli_fetch_field($result);

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* Ferme la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### Voir aussi

- mysqli_fetch_field() - Retourne le prochain champ dans le jeu de résultats

# mysqli_result::free

# mysqli_result::close

# mysqli_result::free_result

# mysqli_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_result::free -- mysqli_result::close -- mysqli_result::free_result -- mysqli_free_result — Libère la mémoire associée à un résultat

### Description

Style orienté objet

public function mysqli_result::free(): void
public function mysqli_result::close(): void
public function mysqli_result::free_result(): void

Style procédural

function mysqli_free_result(mysqli_result `$result`): void

Libère la mémoire associée à un résultat.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- mysqli_query() - Exécute une requête sur la base de données
- mysqli_stmt_get_result() - Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result
- mysqli_store_result() - Transfère un jeu de résultats à partir de la dernière requête
- mysqli_use_result() - Initialise la récupération d'un jeu de résultats

# mysqli_result::getIterator

(PHP 8)

mysqli_result::getIterator — Renvoie un itérateur externe

### Description

public function mysqli_result::getIterator(): Iterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# mysqli_result::$lengths

# mysqli_fetch_lengths

(PHP 5, PHP 7, PHP 8)

mysqli_result::$lengths -- mysqli_fetch_lengths — Retourne la longueur des colonnes de la ligne courante du jeu de résultats

### Description

Style orienté objet

?array $mysqli_result->lengths;

Style procédural

function mysqli_fetch_lengths(mysqli_result `$result`): array|false

La fonction mysqli_fetch_lengths() retourne un tableau contenant la longueur de chaque colonne de la ligne courante du jeu de résultats représenté par le paramètre `result`.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().

### Valeurs de retour

Un tableau d'entiers représentant la taille de chaque colonne (n'incluant aucun caractère null de fin). Retourne `false` si une erreur survient.

mysqli_fetch_lengths() n'est valide que pour la ligne courante du jeu de résultats. Elle retourne `false` si l'on l'appelle avant les fonctions mysqli_fetch_row(), mysqli_fetch_array(), mysqli_fetch_object() ou après avoir récupéré toutes les lignes du résultat.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $mysqli = new mysqli("localhost", "mon_user", "mon_mot_de_passe", "la_base");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = $mysqli->query($query)) {

        $row = $result->fetch_row();

        /* Affichage de la longueur des colonnes */
        foreach ($result->lengths as $i => $val) {
            printf("Le champ n°%2d a une longueur de %2d\n", $i+1, $val);
        }
        $result->close();
    }

    /* Ferme la connexion */
    $mysqli->close();
    ?>

Exemple #2 Style procédural

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Vérification de la connexion */
    if (mysqli_connect_errno()) {
        printf("Échec de la connexion : %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = mysqli_query($link, $query)) {

        $row = mysqli_fetch_row($result);

        /* Affichage de la longueur des colonnes */
        foreach (mysqli_fetch_lengths($result) as $i => $val) {
            printf("Le champ n°%2d a une longueur de %2d\n", $i+1, $val);
        }
        mysqli_free_result($result);
    }

    /* Ferme la connexion */
    mysqli_close($link);
    ?>

Les exemples ci-dessus vont afficher :

    Le champ n° 1 a une longueur de  3
    Le champ n° 2 a une longueur de  5
    Le champ n° 3 a une longueur de 13
    Le champ n° 4 a une longueur de  9
    Le champ n° 5 a une longueur de  6
    Le champ n° 6 a une longueur de  1
    Le champ n° 7 a une longueur de  6
    Le champ n° 8 a une longueur de  4
    Le champ n° 9 a une longueur de  6
    Le champ n°10 a une longueur de  6
    Le champ n°11 a une longueur de  5
    Le champ n°12 a une longueur de 44
    Le champ n°13 a une longueur de  7
    Le champ n°14 a une longueur de  3
    Le champ n°15 a une longueur de  2

# mysqli_result::$num_rows

# mysqli_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_result::$num_rows -- mysqli_num_rows — Retourne le nombre de lignes dans le jeu de résultats

### Description

Style orienté objet

int|string $mysqli_result->num_rows;

Style procédural

function mysqli_num_rows(mysqli_result `$result`): int|string

Retourne le nombre de lignes dans un jeu de résultats.

Le comportement de mysqli_num_rows() dépend de l'utilisation de jeux de résultats bufferisés ou non. Cette fonction renvoie `0` pour les ensembles de résultats non tamponnés, sauf si toutes les lignes ont été récupérées du serveur.

### Liste de paramètres

`result`
  Style procédural uniquement : Un objet mysqli_result retourné par mysqli_query(), mysqli_store_result(), mysqli_use_result(), ou mysqli_stmt_get_result().

### Valeurs de retour

Un entier représentant le nombre de lignes récupérées. Retourne `0` en mode non tamponné, sauf si toutes les lignes ont été récupérées depuis le serveur.

> Note: Si le nombre de ligne est supérieur à `PHP_INT_MAX`, le nombre sera retourné en tant que chaîne de caractères.

### Exemples

Exemple #1 Style orienté objet

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Code, Name FROM Country ORDER BY Name");

    /* Détermine le nombre de lignes du jeu de résultats */
    $row_cnt = $result->num_rows;

    printf("Le jeu de résultats a %d lignes.\n", $row_cnt);

Exemple #2 Style procédural

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Code, Name FROM Country ORDER BY Name");

    /* Détermine le nombre de lignes du jeu de résultats */
    $row_cnt = mysqli_num_rows($result);

    printf("Le jeu de résultats a %d lignes.\n", $row_cnt);
    ?>

Les exemples ci-dessus vont afficher :

    Le jeu de résultats a 239 lignes.

### Notes

> Note:

> Contrairement à la fonction mysqli_stmt_num_rows(), cette fonction n'a pas de variante de méthode orientée objet. Dans le style orienté objet, utiliser le getter de la propriété.

### Voir aussi

- mysqli_affected_rows() - Retourne le nombre de lignes affectées par la dernière opération MySQL
- mysqli_store_result() - Transfère un jeu de résultats à partir de la dernière requête
- mysqli_use_result() - Initialise la récupération d'un jeu de résultats
- mysqli_query() - Exécute une requête sur la base de données
- mysqli_stmt_num_rows() - Retourne le nombre de lignes extraites du serveur

## Sommaire

- mysqli_result::__construct — Construit un objet mysqli_result
- mysqli_result::$current_field — Récupère la position courante d'un champ dans un pointeur de résultat
- mysqli_result::data_seek — Déplace le pointeur interne de résultat
- mysqli_result::fetch_all — Récupère toutes les lignes de résultats dans un tableau associatif, numérique, ou les deux
- mysqli_result::fetch_array — Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux
- mysqli_result::fetch_assoc — Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif
- mysqli_result::fetch_column — Récupère une seule colonne de la ligne suivante d'un jeu de résultats
- mysqli_result::fetch_field — Retourne le prochain champ dans le jeu de résultats
- mysqli_result::fetch_field_direct — Récupère les métadonnées d'un champ unique
- mysqli_result::fetch_fields — Retourne un tableau d'objets représentant les champs dans le résultat
- mysqli_result::fetch_object — Retourne la ligne suivante d'un ensemble de résultats sous forme d'objet
- mysqli_result::fetch_row — Récupère une ligne de résultat sous forme de tableau indexé
- mysqli_result::$field_count — Récupère le nombre de champs dans l'ensemble de résultats
- mysqli_result::field_seek — Déplace le pointeur de résultat sur le champ spécifié
- mysqli_result::free — Libère la mémoire associée à un résultat
- mysqli_result::getIterator — Renvoie un itérateur externe
- mysqli_result::$lengths — Retourne la longueur des colonnes de la ligne courante du jeu de résultats
- mysqli_result::$num_rows — Retourne le nombre de lignes dans le jeu de résultats

# La classe mysqli_driver

(PHP 5, PHP 7, PHP 8)

## Introduction

La classe mysqli_driver est une instance du pattern monostate, c.à.d. il n'y a qu'un seul pilote qui peut accéder à travers un nombre arbitraire d'instances mysqli_driver.

## Synopsis de la classe

final class mysqli_driver {
/* Propriétés */
public readonly string $client_info;
public readonly int $client_version;
public readonly int $driver_version;
public int $report_mode;
}

## Propriétés

client_info

  La version de l'en-tête du client API

client_version

  La version du client

driver_version

  La version du pilote MySQLi

  Avertissement

  Cette propriété est obsolète à partir de PHP 8.1.0. Il est fortement déconseillé de s'appuyer sur cette propriété.

embedded

  Si le support "MySQLi Embedded" est activé

  Avertissement

  Cette propriété a été supprimée à partir de PHP 8.0.0.

reconnect

  Permet ou non la reconnexion (voir la directive INI mysqli.reconnect)

  Avertissement

  Cette propriété a été supprimée ainsi que la directive INI mysqli.reconnect à partir de PHP 8.2.0.

report_mode

  Définit à `MYSQLI_REPORT_OFF`, `MYSQLI_REPORT_ALL` ou n'importe quelle combinaison de `MYSQLI_REPORT_STRICT` (lance des exceptions lors d'erreurs), `MYSQLI_REPORT_ERROR` (rapporte les erreurs) et `MYSQLI_REPORT_INDEX` (erreurs sur les index). Voir aussi mysqli_report().

## Historique

Version | Description
--- | ---
8.2.0 | mysqli_driver::$reconnect a été supprimée.
8.1.0 | mysqli_driver::$driver_version est obsolète.
8.0.0 | mysqli_driver::$embedded a été supprimée.
7.4.0 | mysqli_driver::embedded_server_start() et mysqli_driver:embedded_server_end() ont été supprimées.

# mysqli_driver::embedded_server_end

# mysqli_embedded_server_end

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_end -- mysqli_embedded_server_end — Arrête le serveur embarqué

Avertissement

Cette fonction est a été SUPPRIMÉE à partir de PHP 7.4.0.

### Description

Style orienté objet

public function mysqli_driver::embedded_server_end(): void

Style procédural

function mysqli_embedded_server_end(): void
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

# mysqli_driver::embedded_server_start

# mysqli_embedded_server_start

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_start -- mysqli_embedded_server_start — Initialise et démarre le serveur embarqué

Avertissement

Cette fonction est a été SUPPRIMÉE à partir de PHP 7.4.0.

### Description

Style orienté objet

public function mysqli_driver::embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool

Style procédural

function mysqli_embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

# mysqli_driver::$report_mode

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_driver::$report_mode -- mysqli_report — Définit le mode du rapport d'erreur mysqli

### Description

Style orienté objet

int $mysqli_driver->report_mode;

Style procédural

function mysqli_report(int `$flags`): true

En fonction des drapeaux, ceci définit le mode du rapport d'erreur de mysqli à exception, avertissement, ou aucun. Quand défini à `MYSQLI_REPORT_ALL` ou `MYSQLI_REPORT_INDEX` ceci va aussi informer à propos des requêtes qui n'utilisent pas d'index (ou un mauvais index).

À partir de PHP 8.1.0, la valeur par défaut est `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Auparavant, elle était `MYSQLI_REPORT_OFF`.

### Liste de paramètres

`flags`

  Drapeaux supportés
  Nom | Description
  --- | ---
  `MYSQLI_REPORT_OFF` | Désactive les rapports (valeur par défaut)
  `MYSQLI_REPORT_ERROR` | Rapporte les erreurs depuis les appels aux fonctions mysqli
  `MYSQLI_REPORT_STRICT` | Lance une exception mysqli_sql_exception pour les erreurs, au lieu d'émettre des alertes
  `MYSQLI_REPORT_INDEX` | Rapporte si aucun index ou un mauvais index est utilisé dans une requête
  `MYSQLI_REPORT_ALL` | Définit toutes les options (rapporte tout)

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.1.0 | La valeur par défaut est désormais `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Auparavant, elle était `MYSQLI_REPORT_OFF`.

### Exemples

Exemple #1 Style orienté objet

    <?php

    /* Activation du rapport d'erreur */
    $driver = new mysqli_driver();
    $driver->report_mode = MYSQLI_REPORT_ALL;

    try {
        /* si la connexion échoue, une mysqli_sql_exception sera lancée */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* cette requête devrait rapporter une erreur */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* cette requête devrait rapporter un mauvais index, si la colonne population n'a pas d'index */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

Exemple #2 Style procédural

    <?php

    /* Activation du rapport d'erreur */
    mysqli_report(MYSQLI_REPORT_ALL);

    try {
        /* si la connexion échoue, une exception mysqli_sql_exception sera lancée */
        $link = mysqli_connect("localhost", "my_user", "my_password", "my_db");

        /* cette requête devrait rapporter une erreur */
        $result = mysqli_query($link, "SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* cette requête devrait rapporter un mauvais index, si la colonne population n'a pas d'index */
        $result = mysqli_query($link, "SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

Exemple #3 Rapport d'erreur à l'exception des erreurs de mauvais index

    <?php

    /* Activation du rapport d'erreur */
    $driver = new mysqli_driver();
    $driver->report_mode = MYSQLI_REPORT_ALL;

    try {
        /* si la connexion échoue, une mysqli_sql_exception sera lancée */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* cette requête devrait rapporter une erreur */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* ceci n'émettra PAS d'erreur même si aucun index est disponible */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

### Voir aussi

- mysqli_sql_exception
- set_exception_handler() - Définit une fonction utilisateur de gestion d'exceptions
- error_reporting() - Fixe le niveau de rapport d'erreurs PHP

## Sommaire

- mysqli_driver::embedded_server_end — Arrête le serveur embarqué
- mysqli_driver::embedded_server_start — Initialise et démarre le serveur embarqué
- mysqli_driver::$report_mode — Définit le mode du rapport d'erreur mysqli

# La classe mysqli_warning

(PHP 5, PHP 7, PHP 8)

## Introduction

Représente une alerte MySQL.

## Synopsis de la classe

final class mysqli_warning {
/* Propriétés */
public string $message;
public string $sqlstate;
public int $errno;
/* Méthodes */
private function __construct()
public function next(): bool
}

## Propriétés

message

  Le message

sqlstate

  Le statut SQL

errno

  Le numéro de l'erreur

# mysqli_warning::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_warning::__construct — Constructeur privé pour empêcher l'instanciation directe

### Description

private function mysqli_warning::__construct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# mysqli_warning::next

(PHP 5, PHP 7, PHP 8)

mysqli_warning::next — Récupère le prochain avertissement

### Description

public function mysqli_warning::next(): bool

Modifie les informations d'avertissement au prochain avertissement si possible.

Une fois que l'avertissement a été défini au prochain avertissement, de nouvelles valeurs pour les propriétés de `message`, `sqlstate` et `errno` de mysqli_warning sont disponibles.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si le prochain avertissement a été récupéré avec succès. S'il n'y a plus d'avertissement, retournera `false`

## Sommaire

- mysqli_warning::__construct — Constructeur privé pour empêcher l'instanciation directe
- mysqli_warning::next — Récupère le prochain avertissement

# La classe mysqli_sql_exception

(PHP 5, PHP 7, PHP 8)

## Introduction

La classe de gestion des exceptions mysqli.

## Synopsis de la classe

final class mysqli_sql_exception extends RuntimeException {
/* Propriétés */
protected string $sqlstate = "00000";
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
public function getSqlState(): string
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Propriétés

sqlstate

  Le statut SQL avec l'erreur.

# mysqli_sql_exception::getSqlState

(PHP 8 >= 8.1.2)

mysqli_sql_exception::getSqlState — Renvoie le code d'erreur SQLSTATE

### Description

public function mysqli_sql_exception::getSqlState(): string

Renvoie une chaîne contenant le code d'erreur SQLSTATE pour la dernière erreur. Le code d'erreur est composé de cinq caractères. Les valeurs sont spécifiées par ANSI SQL et ODBC. Pour une liste des valeurs possibles, voir » http://dev.mysql.com/doc/mysql/en/error-handling.html.

> Note:

> Il est à noter que toutes les erreurs MySQL ne sont pas encore mappées aux SQLSTATE. La valeur `HY000` (erreur générale) est utilisée pour les erreurs non mappées.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie une chaîne contenant le code d'erreur SQLSTATE pour la dernière erreur. Le code d'erreur est composé de cinq caractères.

## Sommaire

- mysqli_sql_exception::getSqlState — Renvoie le code d'erreur SQLSTATE

# Fonctions mysqli obsolètes et alias

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli_connect — Alias de mysqli::__construct()

### Description

Cette fonction est un alias de : mysqli::__construct()

> Note:

> Si le mode d'exception mysqli n'est pas activé et qu'une connexion échoue, alors mysqli_connect() retourne `false` au lieu d'un objet. La fonction mysqli_connect_error() peut être utilisée pour récupérer l'erreur de connexion.

# mysqli::escape_string

# mysqli_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::escape_string -- mysqli_escape_string — Alias de mysqli_real_escape_string()

### Description

Cette fonction est un alias de : mysqli_real_escape_string().

# mysqli_execute

(PHP 5, PHP 7, PHP 8)

mysqli_execute — Alias de mysqli_stmt_execute()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

Cette fonction est un alias de : mysqli_stmt_execute().

### Voir aussi

- mysqli_stmt_execute() - Exécute une requête préparée

# mysqli_get_client_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_get_client_stats — Retourne les statistiques client par processus

### Description

function mysqli_get_client_stats(): array

Retourne les statistiques client par processus.

> Note:

> Disponible uniquement avec mysqlnd.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau avec les statistiques client.

### Exemples

Exemple #1 Un exemple avec mysqli_get_client_stats()

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_client_stats());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Voir aussi

- Description des statistiques

# mysqli_get_links_stats

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

mysqli_get_links_stats — Retourne des informations sur les liens ouverts et mis en cache

### Description

function mysqli_get_links_stats(): array

La fonction mysqli_get_links_stats() retourne des informations sur les liens MySQL ouverts et mis en cache.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La fonction mysqli_get_links_stats() retourne un tableau associatif contenant trois éléments, dont les clés sont les suivantes :

`total`

  Un entier indiquant le nombre total de liens ouverts, quels que soient leurs statuts.

`active_plinks`

  Un entier représentant le nombre de connexions persistantes actives.

`cached_plinks`

  Un entier représentant le nombre de connexions persistantes inactives.

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_report — Alias de mysqli_driver->report_mode

### Description

Cette fonction est un alias de : mysqli_driver->report_mode

# mysqli::set_opt

# mysqli_set_opt

(PHP 5, PHP 7, PHP 8)

mysqli::set_opt -- mysqli_set_opt — Alias de mysqli_options()

### Description

Cette fonction est un alias de : mysqli_options().

## Sommaire

- mysqli_connect — Alias de mysqli::__construct
- mysqli::escape_string — Alias de mysqli_real_escape_string
- mysqli_execute — Alias de mysqli_stmt_execute
- mysqli_get_client_stats — Retourne les statistiques client par processus
- mysqli_get_links_stats — Retourne des informations sur les liens ouverts et mis en cache
- mysqli_report — Alias de mysqli_driver->report_mode
- mysqli::set_opt — Alias de mysqli_options

# Historique des modifications

Les modifications suivantes ont été apportées aux classes/fonctions/méthodes de cette extension.

Version | Function | Description
--- | --- | ---
8.4.0 | mysqli::kill | Les méthodes mysqli::kill et mysqli_kill sont désormais obsolètes. Utiliser plutôt la commande SQL KILL.
| mysqli::ping | Les méthodes mysqli::ping et mysqli_ping sont désormais obsolètes. La fonctionnalité reconnect n'est plus disponible à partir de PHP 8.2.0, rendant cette fonction obsolète.
| mysqli::refresh | Les méthodes mysqli::refresh et mysqli_refresh sont désormais obsolètes. Utiliser les commandes SQL FLUSH à la place.
| mysqli::store_result | Le passage du paramètre mode est désormais obsolète. Ce paramètre n'a eu aucun effet à partir de PHP 8.1.0.
8.3.0 | mysqli_result::fetch_object | Lance désormais une exception ValueError quand constructor_args n'est pas vide et que la classe n'a pas de constructeur ; précédemment, une exception Exception était déclenchée.
| mysqli::poll | Lance désormais une exception ValueError lorsque ni l'argument read ni l'argument error ne sont transmis.
8.1.0 | mysqli_driver::$report_mode | La valeur par défaut est désormais MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT. Auparavant, elle était MYSQLI_REPORT_OFF.
| mysqli_result::fetch_all | Désormais aussi disponible lors de la liaison avec libmysqlclient.
| mysqli_stmt::execute | Le paramètre facultatif params a été ajouté.
| mysqli_stmt::next_result | Désormais aussi disponible lors de la liaison avec libmysqlclient.
| mysqli::__construct | mysqli::connect retourne désormais true au lieu de null en cas de succès.
| mysqli::$client_info | L'appel de la mysqli_get_client_info avec l'argument mysql a été déprécié. Cette fonction n'a jamais exigé un paramètre, mais l'a autorisé de manière incorrecte comme paramètre facultatif.
| mysqli::$client_info | Le style orienté objet mysqli::get_client_info a été déprécié.
| mysqli::init | La méthode mysqli::init de style orienté objet a été dépréciée. Remplacez les appels à parent::init par parent::__construct.
8.0.0 | mysqli_result::fetch_object | constructor_args accepte désormais [] pour les constructeurs avec 0 paramètre ; auparavant une exception était lancée.
| mysqli_result::field_seek | Cette fonction retourne désormais toujours true. Auparavant, elle renvoyait false en cas d'échec.
| mysqli_stmt::close | Cette fonction retourne désormais toujours true. Auparavant, elle retournait false en cas d'échec.
| mysqli_stmt::__construct | query est désormais nullable.
| mysqli::begin_transaction | name est désormais nullable.
| mysqli::close | Cette fonction retourne désormais toujours true. Auparavant, elle retournait false en cas d'échec.
| mysqli::commit | name est désormais nullable.
| mysqli::debug | Cette fonction retourne désormais toujours true. Auparavant, elle retournait false en cas d'échec.
| mysqli::rollback | name est désormais nullable.
7.4.0 | mysqli::__construct | Tous les paramètres sont désormais nullable.
| mysqli::real_connect | Tous les paramètres sont désormais nullable.

- Introduction
- Guide de démarrage rapide
  - Interface procédurale et orientée objet
  - Connexions
  - Exécution des requêtes
  - Les requêtes préparées
  - Les procédures stockées
  - Requêtes multiples
  - Support API pour les transactions
  - Les méta-données
- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- L'extension mysqli et les connexions persistantes
- Constantes pré-définies
- Notes
- Le sommaire des fonctions de l'extension MySQLi
- mysqli — La classe mysqli
  - 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::begin_transaction — Démarre une transaction
  - mysqli::change_user — Change l'utilisateur de la connexion
  - mysqli::character_set_name — Retourne le jeu de caractères courant pour la connexion
  - mysqli::close — Ferme une connexion
  - mysqli::commit — Valide la transaction courante
  - mysqli::$connect_errno — Retourne le code d'erreur du dernier appel de connexion
  - mysqli::$connect_error — Retourne une description de la dernière erreur de connexion
  - mysqli::__construct — Ouvre une connexion à un serveur MySQL
  - mysqli::debug — Effectue des actions de débogage
  - mysqli::dump_debug_info — Écrit les informations de débogage dans les logs
  - mysqli::$errno — Retourne le dernier code d'erreur produit
  - mysqli::$error — Retourne une chaîne décrivant la dernière erreur
  - mysqli::$error_list — Retourne une liste d'erreurs depuis la dernière commande exécutée
  - mysqli::execute_query — Prépare, lie les paramètres et exécute une instruction SQL
  - mysqli::$field_count — Retourne le nombre de colonnes pour la dernière requête
  - mysqli::get_charset — Retourne un objet représentant le jeu de caractères
  - mysqli::$client_info — Récupère des informations sur le client MySQL
  - mysqli::$client_version — Retourne la version du client MySQL sous forme d'un entier
  - mysqli::get_connection_stats — Retourne des statistiques sur la connexion
  - mysqli::$host_info — Retourne une chaîne contenant le type de connexion utilisée
  - mysqli::$protocol_version — Retourne la version du protocole MySQL utilisé
  - mysqli::$server_info — Retourne la version du serveur MySQL
  - mysqli::$server_version — Retourne un entier représentant la version du serveur MySQL
  - mysqli::get_warnings — Lit le résultat de SHOW WARNINGS
  - mysqli::$info — Retourne des informations à propos de la dernière requête exécutée
  - mysqli::init — Initialise MySQLi et retourne un objet à utiliser avec mysqli_real_connect()
  - mysqli::$insert_id — Retourne la valeur générée pour une colonne AUTO_INCREMENT par la dernière requête
  - mysqli::kill — Demande au serveur de terminer un thread MySQL
  - mysqli::more_results — Vérifie s'il y a d'autres jeux de résultats MySQL disponibles
  - mysqli::multi_query — Exécute une ou plusieurs requêtes sur la base de données
  - mysqli::next_result — Prépare le prochain résultat d'une requête multiple
  - mysqli::options — Définit les options
  - mysqli::ping — Ping la connexion au serveur et reconnecte si elle n'existe plus
  - mysqli::poll — Vérifie l'état de la connexion
  - 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::reap_async_query — Lit un résultat pour une requête asynchrone
  - mysqli::refresh — Rafraîchit
  - mysqli::release_savepoint — Supprime le point de sauvegarde nommé du jeu des points de sauvegarde de la transaction courante
  - mysqli::rollback — Annule la transaction courante
  - mysqli::savepoint — Définit un point de sauvegarde nommé de la transaction
  - mysqli::select_db — Sélectionne une base de données par défaut pour les requêtes
  - mysqli::set_charset — Définit le jeu de caractères du client
  - 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_init — Initialise une commande MySQL
  - 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 support des threads est activé ou pas
  - 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 exécutée
- mysqli_stmt — La classe mysqli_stmt
  - mysqli_stmt::$affected_rows — Retourne le nombre total de lignes modifiées, effacées, insérées, ou correspondant par la dernière requête
  - mysqli_stmt::attr_get — Récupère la valeur courante d'un attribut de requête
  - mysqli_stmt::attr_set — Modifie le comportement d'une requête préparée
  - 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 — Termine une requête préparée
  - mysqli_stmt::__construct — Construit un nouvel objet mysqli_stmt
  - mysqli_stmt::data_seek — Ajuste le pointeur de résultat vers une ligne arbitraire dans le résultat mis en mémoire tampon.
  - 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::$error_list — Retourne une liste d'erreurs pour la dernière requête exécutée
  - 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 colonnes dans la requête donnée
  - mysqli_stmt::free_result — Libère le résultat MySQL de la mémoire
  - mysqli_stmt::get_result — Récupère un jeu de résultats depuis une requête préparée en tant qu'objet mysqli_result
  - mysqli_stmt::get_warnings — Récupère le résultat de SHOW WARNINGS
  - mysqli_stmt::$insert_id — Récupère l'ID généré par la dernière requête INSERT
  - mysqli_stmt::more_results — Vérifie s'il y a encore des résultats depuis une requête multiple
  - mysqli_stmt::next_result — Lit le résultat suivant depuis une requête multiple
  - mysqli_stmt::$num_rows — Retourne le nombre de lignes extraites du serveur
  - mysqli_stmt::$param_count — Retourne le nombre de paramètres d'une commande SQL
  - 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étadonné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 — Stocke un ensemble de résultats dans un tampon interne
- mysqli_result — La classe mysqli_result
  - mysqli_result::__construct — Construit un objet mysqli_result
  - mysqli_result::$current_field — Récupère la position courante d'un champ dans un pointeur de résultat
  - mysqli_result::data_seek — Déplace le pointeur interne de résultat
  - mysqli_result::fetch_all — Récupère toutes les lignes de résultats dans un tableau associatif, numérique, ou les deux
  - mysqli_result::fetch_array — Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif, numérique ou les deux
  - mysqli_result::fetch_assoc — Récupère la ligne suivante d'un ensemble de résultats sous forme de tableau associatif
  - mysqli_result::fetch_column — Récupère une seule colonne de la ligne suivante d'un jeu de résultats
  - mysqli_result::fetch_field — Retourne le prochain champ dans le jeu de résultats
  - mysqli_result::fetch_field_direct — Récupère les métadonnées d'un champ unique
  - mysqli_result::fetch_fields — Retourne un tableau d'objets représentant les champs dans le résultat
  - mysqli_result::fetch_object — Retourne la ligne suivante d'un ensemble de résultats sous forme d'objet
  - mysqli_result::fetch_row — Récupère une ligne de résultat sous forme de tableau indexé
  - mysqli_result::$field_count — Récupère le nombre de champs dans l'ensemble de résultats
  - mysqli_result::field_seek — Déplace le pointeur de résultat sur le champ spécifié
  - mysqli_result::free — Libère la mémoire associée à un résultat
  - mysqli_result::getIterator — Renvoie un itérateur externe
  - mysqli_result::$lengths — Retourne la longueur des colonnes de la ligne courante du jeu de résultats
  - mysqli_result::$num_rows — Retourne le nombre de lignes dans le jeu de résultats
- mysqli_driver — La classe mysqli_driver
  - mysqli_driver::embedded_server_end — Arrête le serveur embarqué
  - mysqli_driver::embedded_server_start — Initialise et démarre le serveur embarqué
  - mysqli_driver::$report_mode — Définit le mode du rapport d'erreur mysqli
- mysqli_warning — La classe mysqli_warning
  - mysqli_warning::__construct — Constructeur privé pour empêcher l'instanciation directe
  - mysqli_warning::next — Récupère le prochain avertissement
- mysqli_sql_exception — La classe mysqli_sql_exception
  - mysqli_sql_exception::getSqlState — Renvoie le code d'erreur SQLSTATE
- Fonctions mysqli obsolètes et alias
  - mysqli_connect — Alias de mysqli::__construct
  - mysqli::escape_string — Alias de mysqli_real_escape_string
  - mysqli_execute — Alias de mysqli_stmt_execute
  - mysqli_get_client_stats — Retourne les statistiques client par processus
  - mysqli_get_links_stats — Retourne des informations sur les liens ouverts et mis en cache
  - mysqli_report — Alias de mysqli_driver->report_mode
  - mysqli::set_opt — Alias de mysqli_options
- Historique des modifications

# Mysql_xdevapi

# Introduction

Cette extension fournit un accès au Document Store de MySQL à travers la DevAPI X. La DevAPI X est une API commune fournie par plusieurs connecteurs MySQL fournissant un accès facile aux tables relationnelles aussi bien qu'aux collections de documents, qui sont représentés en JSON, depuis une API avec des opérations de style CRUD.

La DevAPI de X utilise le protocole X, le protocole nouvelle génération client-serveur du serveur MySQL 8.0.

Pour des informations générales sur MySQL Document Store, se référer au chapitre » MySQL Document Store du manuel MySQL.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Compiler à partir des sources

## Pré-requis

Cette extension nécessite un serveur MySQL 8+ avec le plugin X activé (par défaut).

Les bibliothèques prérequises pour compiler cette extension sont : Boost (1.53.0 ou supérieur), OpenSSL et Protobuf.

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Un exemple de procédure d'installation sur Ubuntu 18.04 avec PHP 7.2 :

    // Dépendances
    $ apt install build-essential libprotobuf-dev libboost-dev openssl protobuf-compiler liblz4-tool zstd

    // PHP avec les extensions désirées; php7.2-dev est requis pour compiler
    $ apt install php7.2-cli php7.2-dev php7.2-mysql php7.2-pdo php7.2-xml

    // Compiler cette extension
    $ pecl install mysql_xdevapi

La commande `pecl install` n'active pas les extensions PHP (par défaut) et activer les extensions PHP peut se faire de plusieurs manières. Un autre exemple avec PHP 7.2 sur Ubuntu 18.04 :

    // Créer son propre fichier ini
    $ echo "extension=mysql_xdevapi.so" > /etc/php/7.2/mods-available/mysql_xdevapi.ini

    // Utiliser la commande 'phpenmod' (note: spécifique à Debian/Ubuntu)
    $ phpenmod -v 7.2 -s ALL mysql_xdevapi

    // Une alternative à 'phpenmod' est de créer un lien symbolique manuellement
    // $ ln -s /etc/php/7.2/mods-available/mysql_xdevapi.ini /etc/php/7.2/cli/conf.d/20-mysql_xdevapi.ini

    // Voyons quelles extensions MySQL sont activées maintenant
    $ php -m |grep mysql

    mysql_xdevapi
    mysqli
    mysqlnd
    pdo_mysql

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/mysql_xdevapi.

## Configuration à l'exécution

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

Options de configuration Mysql_xdevapi
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
xmysqlnd.collect_memory_statistics | 0 | `INI_SYSTEM` |
xmysqlnd.collect_statistics | 1 | `INI_ALL` |
xmysqlnd.debug |  | `INI_SYSTEM` |
xmysqlnd.mempool_default_size | 16000 | `INI_ALL` |
xmysqlnd.net_read_timeout | 31536000 | `INI_SYSTEM` |
xmysqlnd.trace_alloc |  | `INI_SYSTEM` |

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

`xmysqlnd.collect_memory_statistics` int

`xmysqlnd.collect_statistics` int

`xmysqlnd.debug` string

`xmysqlnd.mempool_default_size` int

`xmysqlnd.net_read_timeout` int

`xmysqlnd.trace_alloc` string

## Compiler à partir des sources

Considérations pour compiler cette extension à partir des sources.

- Le nom de l'extension est 'mysql_xdevapi', donc utiliser `--enable-mysql-xdevapi`.

- Boost; requis, utiliser optionnellement l'option de configuration --with-boost=DIR ou définir la variable d'environnement MYSQL_XDEVAPI_BOOST_ROOT. Seuls les fichiers d'en-tête boost sont requis; pas les binaires.

- Google Protocol Buffers (protobuf): requis, utiliser optionnellement l'option de configuration --with-protobuf=DIR ou définir la variable d'environnement MYSQL_XDEVAPI_PROTOBUF_ROOT.

  Optionnellement utiliser `make protobufs` pour générer les fichiers protobuf (*.pb.cc/.h), et `make clean-protobufs` pour supprimer les fichiers protobuf générés.

  Note spécifique à Windows : selon l'environnement, la bibliothèque statique avec un runtime DLL multi-thread peut être nécessaire. Pour préparer, utiliser les options suivantes : -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF

- Google Protocol Buffers / protoc: requis, il faut s'assurer que le bon 'protoc' est disponible dans le PATH lors de la compilation. C'est particulièrement important car les scripts batch du SDK PHP Windows peuvent écraser l'environnement.

- Bison: requis, et disponible dans le PATH.

  Note spécifique à bison Windows: nous recommandons fortement d'utiliser bison fourni avec le SDK PHP choisi, sinon une erreur similaire à "zend_globals_macros.h(39): error C2375: 'zendparse': redefinition; different linkage Zend/zend_language_parser.h(214): note: see declaration of 'zendparse'" peut être le résultat. De plus, les scripts batch du SDK PHP Windows peuvent écraser l'environnement.

- Note spécifique à Windows: pour préparer l'environnement, voir la documentation officielle de construction Windows pour » le SDK actuel.

  Nous recommandons d'utiliser les antislash '\\' au lieu d'un slash '/' pour tous les chemins.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`MYSQLX_CLIENT_SSL` (int)
`MYSQLX_TYPE_DECIMAL` (int)
`MYSQLX_TYPE_TINY` (int)
`MYSQLX_TYPE_SHORT` (int)
`MYSQLX_TYPE_SMALLINT` (int)
`MYSQLX_TYPE_MEDIUMINT` (int)
`MYSQLX_TYPE_INT` (int)
`MYSQLX_TYPE_BIGINT` (int)
`MYSQLX_TYPE_LONG` (int)
`MYSQLX_TYPE_FLOAT` (int)
`MYSQLX_TYPE_DOUBLE` (int)
`MYSQLX_TYPE_NULL` (int)
`MYSQLX_TYPE_TIMESTAMP` (int)
`MYSQLX_TYPE_LONGLONG` (int)
`MYSQLX_TYPE_INT24` (int)
`MYSQLX_TYPE_DATE` (int)
`MYSQLX_TYPE_TIME` (int)
`MYSQLX_TYPE_DATETIME` (int)
`MYSQLX_TYPE_YEAR` (int)
`MYSQLX_TYPE_NEWDATE` (int)
`MYSQLX_TYPE_ENUM` (int)
`MYSQLX_TYPE_SET` (int)
`MYSQLX_TYPE_TINY_BLOB` (int)
`MYSQLX_TYPE_MEDIUM_BLOB` (int)
`MYSQLX_TYPE_LONG_BLOB` (int)
`MYSQLX_TYPE_BLOB` (int)
`MYSQLX_TYPE_VAR_STRING` (int)
`MYSQLX_TYPE_STRING` (int)
`MYSQLX_TYPE_CHAR` (int)
`MYSQLX_TYPE_BYTES` (int)
`MYSQLX_TYPE_INTERVAL` (int)
`MYSQLX_TYPE_GEOMETRY` (int)
`MYSQLX_TYPE_JSON` (int)
`MYSQLX_TYPE_NEWDECIMAL` (int)
`MYSQLX_TYPE_BIT` (int)
`MYSQLX_LOCK_DEFAULT` (int)
`MYSQLX_LOCK_NOWAIT` (int)
`MYSQLX_LOCK_SKIP_LOCKED` (int)

# Historique des modifications

Les modifications suivantes ont été apportées aux classes/fonctions/méthodes de cette extension.

### Historique de changement général de l'extension ext/mysql_xdevapi

Cet historique de changement référence l'extension ext/mysql_xdevapi.

### Changement global de l'extension ext/mysql_xdevapi

Version | Description
--- | ---
8.0.28 | Suppression du support de TLSv1 et TLSv1.1. Les valeurs "TLSv1", "TLSv1.0" et "TLSv1.1" sont désormais considérées comme invalides pour l'attribut de connexion "tls-versions".
8.0.26 | Dépréciation du support de TLSv1 et TLSv1.1.

# Exemples

Le point d'entrée central de l'API X est la fonction mysql_xdevapi\getSession(), qui reçoit une URI vers un serveur MySQL 8.0 et renvoie un objet mysql_xdevapi\Session.

Exemple #1 Connexion à un serveur MySQL

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("Connection could not be established: " . $e->getMessage());
    }

    // ... use $session
    ?>

La session fournit un accès complet à l'API. Pour une nouvelle installation de serveur MySQL, la première étape consiste à créer un schéma de base de données avec une collection pour stocker des données :

Exemple #2 Création d'un schéma et d'une collection sur le serveur MySQL

    <?php
    $schema = $session->createSchema("test");
    $collection = $schema->createCollection("example");
    ?>

Lorsqu'on stocke des données, généralement json_encode() est utilisé pour encoder les données en JSON, qui peuvent ensuite être stockées dans une collection.

Les exemples suivants stockent des données dans la collection que nous avons créée précédemment, puis récupèrent à nouveau des parties de ces données.

Exemple #3 Stocker et Récupérer des Données

    <?php
    $marco = [
      "name" => "Marco",
      "age"  => 19,
      "job"  => "Programmer"
    ];
    $mike = [
      "name" => "Mike",
      "age"  => 39,
      "job"  => "Manager"
    ];

    $schema = $session->getSchema("test");
    $collection = $schema->getCollection("example");

    $collection->add($marco, $mike)->execute();

    var_dump($collection->find("name = 'Mike'")->execute()->fetchOne());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(4) {
      ["_id"]=>
      string(28) "00005ad66aaf0000000000000003"
      ["age"]=>
      int(39)
      ["job"]=>
      string(7) "Manager"
      ["name"]=>
      string(4) "Mike"
    }

Cet exemple démontre que le serveur MySQL ajoute un champ supplémentaire nommé `_id`, qui sert de clé primaire au document.

Cet exemple démontre également que les données récupérées sont triées par ordre alphabétique. Cet ordre spécifique provient du stockage binaire efficace à l'intérieur du serveur MySQL, mais il ne faut pas s'y fier. Se référer à la documentation du type de données JSON de MySQL pour plus de détails.

Optionnellement, utiliser les itérateurs de PHP pour récupérer plusieurs documents :

Exemple #4 Récupérer et Itérer sur Plusieurs Documents

    <?php
    $result = $collection->find()->execute();
    foreach ($result as $doc) {
      echo "{$doc["name"]} is a {$doc["job"]}.\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Marco is a Programmer.
    Mike is a Manager.

# Fonctions Mysql_xdevapi

# expression

(No version information available, might only be in Git)

expression — Lie une expression à une variable de requête préparée

### Description

function mysql_xdevapi\expression(string `$expression`): object

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`expression`

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Expression()

    <?php
    $expression = mysql_xdevapi\Expression("[age,job]");

    $res  = $coll->find("age > 30")->fields($expression)->limit(3)->execute();
    $data = $res->fetchAll();

    print_r($data);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    <?php

# getSession

(No version information available, might only be in Git)

getSession — Connecte à un serveur MySQL

### Description

function mysql_xdevapi\getSession(string `$uri`): mysql_xdevapi\Session

Connecte au serveur MySQL.

### Liste de paramètres

`uri`

  L'uri du serveur MySQL, tel que `mysqlx://user:password@host`.

  Format d'URI:

  `scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...`

  - `scheme`: requis, le protocole de connexion

    Dans mysql_xdevapi c'est toujours 'mysqlx' (pour le protocole X)

  - `user`: optionnel, le compte utilisateur MySQL pour l'authentification

  - `password`: optionnel, le mot de passe de l'utilisateur MySQL pour l'authentification

  - `target`: requis, l'instance serveur à laquelle la connexion se réfère:

    * Connexion TCP (nom d'hôte, adresse IPv4 ou adresse IPv6)

    * Chemin de socket Unix (chemin de fichier local)

    * Pipe nommé Windows (chemin de fichier local)

  - `port`: optionnel, le port réseau du serveur MySQL.

    par défaut le port pour le protocole X est 33060

  - `?attribute=value`: cet élément est optionnel et spécifie un dictionnaire de données qui contient différentes options, y compris:

    - L'`auth` (mécanisme d'authentification) attribut tel qu'il se rapporte aux connexions chiffrées. Pour plus d'informations, voir » Options de commande pour les connexions chiffrées. Les valeurs 'auth' suivantes sont supportées: `plain`, `mysql41`, `external`, et `sha256_mem`.

    - L'attribut `connect-timeout` affecte la connexion et non les opérations suivantes. Il est défini par connexion, que ce soit sur un seul hôte ou plusieurs.

      Passer un entier positif pour définir le délai de connexion en secondes, ou passer 0 (zéro) pour désactiver le délai (infini). Ne pas définir connect-timeout utilise la valeur par défaut de 10.

      En relation, les variables d'environnement MYSQLX_CONNECTION_TIMEOUT (délai en secondes) et MYSQLX_TEST_CONNECTION_TIMEOUT (utilisé lors de l'exécution des tests) peuvent être définies et utilisées à la place de connect-timeout dans l'URI. L'option connect-timeout de l'URI a la priorité sur ces variables d'environnement.

    - L'attribut optionnel `compression` accepte ces valeurs: `preferred` (le client négocie avec le serveur pour trouver un algorithme supporté; la connexion est non compressée si un algorithme supporté mutuellement n'est pas trouvé), `required` (comme "preferred", mais la connexion est terminée si un algorithme supporté mutuellement n'est pas trouvé), ou `disabled` (la connexion est non compressée). Par défaut à `preferred`.

      Cette option a été ajoutée dans la version 8.0.20.

    - L'attribut optionnel `compression-algorithms` définit les algorithmes de compression désirés (et leur ordre d'utilisation préféré): `zstd_stream` (alias: zstd), `lz4_message` (alias: lz4), ou `deflate_stream` (alias: deflate ou zlib). Par défaut, l'ordre utilisé (selon la disponibilité du système) est lz4_message, zstd_stream, puis deflate_stream. Par exemple, passer compression-algorithms=[lz4,zstd_stream] utilise lz4 s'il est disponible, sinon zstd_stream est utilisé. Si les deux ne sont pas disponibles alors le comportement dépend de la valeur de compression par exemple, si compression=required alors il échouera avec une erreur.

      Cette option a été ajoutée dans la version 8.0.22.

  Exemple #1 Exemple d'URI

      mysqlx://foobar
      mysqlx://root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F
      mysqlx://foo:bar@localhost:33060
      mysqlx://foo:bar@localhost:33160?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33260?ssl-mode=required
      mysqlx://foo:bar@localhost:33360?ssl-mode=required&auth=mysql41
      mysqlx://foo:bar@(/path/to/socket)
      mysqlx://foo:bar@(/path/to/socket)?auth=sha256_mem
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]
      mysqlx://foobar?ssl-ca=(/path/to/ca.pem)&ssl-crl=(/path/to/crl.pem)
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33160/?connect-timeout=0
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required&compression-algorithms=[lz4,zstd_stream]

  Pour plus d'informations, voir connexion à MySQL Shell » en utilisant une chaîne d'URI.

### Valeurs de retour

Un objet Session.

### Erreurs / Exceptions

Une erreur de connexion lance une exception Exception.

### Exemples

Exemple #2 Exemple de mysql_xdevapi\getSession()

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("Connection could not be established: " . $e->getMessage());
    }

    $schemas = $session->getSchemas();
    print_r($schemas);

    $mysql_version = $session->getServerVersion();
    print_r($mysql_version);

    var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => helloworld
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        [2] => mysql_xdevapi\Schema Object
            (
                [name] => mysql
            )
        [3] => mysql_xdevapi\Schema Object
            (
                [name] => performance_schema
            )
        [4] => mysql_xdevapi\Schema Object
            (
                [name] => sys
            )
    )

    80012

    array(4) {
      ["_id"]=>
      string(28) "00005ad66abf0001000400000003"
      ["age"]=>
      int(42)
      ["job"]=>
      string(7) "Butler"
      ["name"]=>
      string(4) "Alfred"
    }

## Sommaire

- expression — Lie une expression à une variable de requête préparée
- getSession — Connecte à un serveur MySQL

# Interface BaseResult

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\BaseResult {
/* Méthodes */
abstract public function getWarnings(): array
abstract public function getWarningsCount(): int
}

# BaseResult::getWarnings

(No version information available, might only be in Git)

BaseResult::getWarnings — Récupère les avertissements de la dernière opération

### Description

abstract public function mysql_xdevapi\BaseResult::getWarnings(): array

Récupère les avertissements générés par la dernière opération du serveur MySQL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau d'objets Warning de la dernière opération. Chaque objet définit un 'message' d'erreur, un 'niveau' d'erreur et un 'code' d'erreur. Un tableau vide est retourné s'il n'y a pas d'erreurs.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# BaseResult::getWarningsCount

(No version information available, might only be in Git)

BaseResult::getWarningsCount — Récupère le nombre d'avertissements de la dernière opération

### Description

abstract public function mysql_xdevapi\BaseResult::getWarningsCount(): int

Renvoie le nombre d'avertissements générés par la dernière opération. Plus précisément, ces avertissements sont générés par le serveur MySQL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre d'avertissements de la dernière opération.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    2

## Sommaire

- BaseResult::getWarnings — Récupère les avertissements de la dernière opération
- BaseResult::getWarningsCount — Récupère le nombre d'avertissements de la dernière opération

# La classe Client

(No version information available, might only be in Git)

## Introduction

Apporte un accès au pool de connexions.

## Synopsis de la classe

class mysql_xdevapi\Client {
/* Méthodes */
public function close(): bool
public function getSession(): mysql_xdevapi\Session
}

# mysql_xdevapi\Client::close

(No version information available, might only be in Git)

mysql_xdevapi\Client::close — Ferme le client

### Description

public function mysql_xdevapi\Client::close(): bool

Ferme toutes les connexions client avec le serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si les connexions sont fermées.

# Client::__construct

(No version information available, might only be in Git)

Client::__construct — Constructeur du client

### Description

private function mysql_xdevapi\Client::__construct()

Construit un objet client.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Client::__construct()

    <?php
    $pooling_options = '{
      "enabled": true,
        "maxSize": 10,
        "maxIdleTime": 3600,
        "queueTimeOut": 1000
    }';
    $client = mysql_xdevapi\getClient($connection_uri, $pooling_options);
    $session = $client->getSession();

# Client::getClient

(No version information available, might only be in Git)

Client::getClient — Renvoie la session client

### Description

public function mysql_xdevapi\Client::getSession(): mysql_xdevapi\Session

Renvoie la session associée au client.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet Session.

## Sommaire

- mysql_xdevapi\Client::close — Ferme le client
- Client::__construct — Constructeur du client
- Client::getClient — Renvoie la session client

# Classe Collection

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\Collection implements mysql_xdevapi\SchemaObject {
/* Propriétés */
public $name;
/* Méthodes */
public function add(mixed `$document`): mysql_xdevapi\CollectionAdd
public function addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
public function count(): int
public function createIndex(string `$index_name`, string `$index_desc_json`): void
public function dropIndex(string `$index_name`): bool
public function existsInDatabase(): bool
public function find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind
public function getName(): string
public function getOne(string `$id`): Document
public function getSchema(): Schema Object
public function getSession(): Session
public function modify(string `$search_condition`): mysql_xdevapi\CollectionModify
public function remove(string `$search_condition`): mysql_xdevapi\CollectionRemove
public function removeOne(string `$id`): mysql_xdevapi\Result
public function replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
}

## Propriétés

name

# Collection::add

(No version information available, might only be in Git)

Collection::add — Ajoute un document à la collection

### Description

public function mysql_xdevapi\Collection::add(mixed `$document`): mysql_xdevapi\CollectionAdd

Déclenche l'insertion du ou des documents donnés dans la collection, et plusieurs variantes de cette méthode sont prises en charge. Les options incluent :

1. Ajouter un seul document sous forme de chaîne JSON.

2. Ajouter un seul document sous forme de tableau comme : `[ 'field' => 'value', 'field2' => 'value2' ... ]`

3. Un mélange des deux, et plusieurs documents peuvent être ajoutés dans la même opération.

### Liste de paramètres

`document`

  Un ou plusieurs documents, et cela peut être soit du JSON ou un tableau de champs avec leurs valeurs associées. Cela ne peut pas être un tableau vide.

  Le serveur MySQL génère automatiquement des valeurs `_id` uniques pour chaque document (recommandé), bien que cela puisse également être ajouté manuellement. Cette valeur doit être unique, sinon l'opération d'ajout échouera.

### Valeurs de retour

Un objet CollectionAdd. Utiliser execute() pour retourner un résultat qui peut être utilisé pour interroger le nombre d'éléments affectés, le nombre d'avertissements générés par l'opération, ou pour récupérer une liste d'identifiants générés pour les documents insérés.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::add()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Ajoute deux documents
    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Ajoute deux documents en utilisant un seul objet JSON
    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    // Récupère une liste d'identifiants générés à partir du dernier add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Notes

> Note:

> Un identifiant unique _id est généré par MySQL Server 8.0 ou supérieur, comme démontré dans l'exemple. Le champ _id doit être défini manuellement si on utilise MySQL Server 5.7.

# Collection::addOrReplaceOne

(No version information available, might only be in Git)

Collection::addOrReplaceOne — Ajoute ou remplace un document de la collection

### Description

public function mysql_xdevapi\Collection::addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Ajoute un nouveau document, ou remplace un document s'il existe déjà.

Il existe plusieurs scénarios pour cette méthode :

- Ni l'id ni aucune valeur de clé unique ne sont en conflit avec un document de la collection, alors le document est ajouté.

- Si l'id ne correspond à aucun document, mais qu'une ou plusieurs valeurs de clé unique entrent en conflit avec un document de la collection, alors une erreur est lancée.

- Si l'id correspond à un document existant et qu'aucune clé unique n'est définie pour la collection, alors le document est remplacé.

- Si l'id correspond à un document existant, et que toutes les clés uniques du document de remplacement correspondent à ce même document ou ne sont en conflit avec aucun autre document de la collection, alors le document est remplacé.

- Si l'id correspond à un document existant, et qu'une ou plusieurs clés uniques correspondent à un autre document de la collection, alors une erreur est lancée.

### Liste de paramètres

`id`

  Ceci est l'identifiant du filtre. Si cet identifiant ou tout autre champ qui a un index unique existe déjà dans la collection, alors il mettra à jour le document correspondant.

  Par défaut, cet identifiant est généré automatiquement par le serveur MySQL lorsque le document a été ajouté, et est référencé en tant que champ nommé '_id'.

`doc`

  Ceci est le document à ajouter ou remplacer, qui est une chaîne JSON.

### Valeurs de retour

Un objet Result.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::addOrReplaceOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Utiliser add()
    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Utiliser addOrReplaceOne()
    // Note: nous passons ici une valeur _id connue
    $result = $collection->addOrReplaceOne('00005b6b53610000000000000056', '{"name": "Fred",  "age": 21, "job": "Construction"}');

    ?>

# Collection::__construct

(No version information available, might only be in Git)

Collection::__construct — Constructeur de Collection

### Description

private function mysql_xdevapi\Collection::__construct()

Construit un objet Collection.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::getOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Un identifiant unique _id est généré par MySQL Server
    // Ceci récupère les _id générés; un seul dans cet exemple, donc $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::count

(No version information available, might only be in Git)

Collection::count — Renvoie le nombre de documents

### Description

public function mysql_xdevapi\Collection::count(): int

Cette fonctionnalité est similaire à une opération SQL `SELECT COUNT(*)` sur le serveur MySQL pour le schéma et la collection actuels. En d'autres termes, elle compte le nombre de documents dans la collection.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre de documents dans la collection.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection
      ->add(
      '{"name": "Bernie",
        "jobs": [
          {"title":"Cat Herder","Salary":42000},
          {"title":"Father","Salary":0}
        ],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [
          {"title":"Scientist","Salary":18000},
          {"title":"Mother","Salary":0}
        ],
        "hobbies": ["Walking","Making pies"]}')
      ->execute();

    var_dump($collection->count());
    ?>

L'exemple ci-dessus va afficher :

    int(2)

# Collection::createIndex

(No version information available, might only be in Git)

Collection::createIndex — Créer un index de collection

### Description

public function mysql_xdevapi\Collection::createIndex(string `$index_name`, string `$index_desc_json`): void

Créer un index sur la collection.

Une exception est lancée si un index portant le même nom existe déjà, ou si la définition de l'index n'est pas correctement formée.

### Liste de paramètres

`index_name`

  Le nom de l'index à créer. Ce nom doit être un nom d'index valide tel que accepté par la requête SQL `CREATE INDEX`.

`index_desc_json`

  La définition de l'index à créer. Elle contient un tableau d'objets IndexField, et chaque objet décrit un seul membre de document à inclure dans l'index, et une chaîne facultative pour le type d'index qui pourrait être INDEX (par défaut) ou SPATIAL.

  Une description IndexField unique se compose des champs suivants :

  - `field`: chaîne, le chemin complet du document vers le membre du document ou le champ à indexer.

  - `type`: chaîne, l'un des types de colonnes SQL pris en charge pour mapper le champ. Pour les types numériques, le mot-clé facultatif UNSIGNED peut suivre. Pour le type TEXT, la longueur à considérer pour l'indexation peut être ajoutée.

  - `required`: booléen, (facultatif) true si le champ doit exister dans le document. Par défaut à `false`, sauf pour `GEOJSON` où il est par défaut à `true`.

  - `options`: entier, (facultatif) drapeaux d'options spéciaux à utiliser lors du décodage de données `GEOJSON`.

  - `srid`: entier, (facultatif) valeur srid à utiliser lors du décodage de données `GEOJSON`.

  C'est une erreur d'inclure d'autres champs non décrits ci-dessus dans les documents IndexDefinition ou IndexField.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::createIndex()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // Créer un index de texte
    $collection->createIndex(
      'myindex1',
      '{"fields": [{
        "field": "$.name",
        "type": "TEXT(25)",
        "required": true}],
        "unique": false}'
    );

    // Un index spatial
    $collection->createIndex(
      'myindex2',
      '{"fields": [{
        "field": "$.home",
        "type": "GEOJSON",
        "required": true}],
        "type": "SPATIAL"}'
    );

    // Index avec plusieurs champs
    $collection->createIndex(
      'myindex3',
      '{"fields": [
        {
          "field": "$.name",
          "type": "TEXT(20)",
          "required": true
        },
        {
          "field": "$.age",
          "type": "INTEGER"
        },
        {
          "field": "$.job",
          "type": "TEXT(30)",
          "required": false
        }
      ],
      "unique": true
      }'
    );

# Collection::dropIndex

(No version information available, might only be in Git)

Collection::dropIndex — Supprime un index de collection

### Description

public function mysql_xdevapi\Collection::dropIndex(string `$index_name`): bool

Supprime un index de collection.

Cette opération ne lance pas d'erreur si l'index n'existe pas, mais `false` est retourné dans ce cas.

### Liste de paramètres

`index_name`

  Le nom de l'index de collection à supprimer.

### Valeurs de retour

`true` si l'opération DROP INDEX a réussi, sinon `false`.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::dropIndex()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    $collection->createIndex(
      'myindex',
      '{"fields": [{"field": "$.name", "type": "TEXT(25)", "required": true}], "unique": false}'
    );

    // ...

    if ($collection->dropIndex('myindex')) {
        echo "An index named 'myindex' was found, and dropped.";
    }
    ?>

L'exemple ci-dessus va afficher :

    An index named 'myindex' was found, and dropped.

# Collection::existsInDatabase

(No version information available, might only be in Git)

Collection::existsInDatabase — Vérifie si la collection existe dans la base de données

### Description

public function mysql_xdevapi\Collection::existsInDatabase(): bool

Vérifie si l'objet Collection fait référence à une collection dans la base de données (schéma).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si la collection existe dans la base de données, sinon `false` si elle n'existe pas.

Une table définie avec deux colonnes (doc et _id) est considérée comme une collection, et une troisième colonne _json_schema à partir de MySQL 8.0.21. Ajouter une colonne supplémentaire signifie que existsInDatabase() ne la verra plus comme une collection.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    // ...

    if (!$collection->existsInDatabase()) {
        echo "The collection no longer exists in the database named addressbook. What happened?";
    }
    ?>

# Collection::find

(No version information available, might only be in Git)

Collection::find — Recherche de document

### Description

public function mysql_xdevapi\Collection::find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind

Recherche une collection de base de données pour un document ou un ensemble de documents. Les documents trouvés sont retournés sous forme d'un objet CollectionFind pour les modifier ou récupérer des résultats supplémentaires.

### Liste de paramètres

`search_condition`

  Bien que facultative, normalement une condition est définie pour limiter les résultats à un sous-ensemble de documents.

  Plusieurs éléments peuvent construire la condition et la syntaxe supporte la liaison de paramètres. L'expression utilisée comme condition de recherche doit être une expression SQL valide. Si aucune condition de recherche n'est fournie (champ vide) alors find('true') est supposé.

### Valeurs de retour

Un objet CollectionFind pour vérifier l'opération, ou récupérer les documents trouvés.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::find()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred",     "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",        "age": 19, "job": "Swimmer"}')->execute();
    $collection->add('{"name": "Fred",       "age": 20, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma",      "age": 21, "job": "Teacher"}')->execute();
    $collection->add('{"name": "Suki",       "age": 22, "job": "Teacher"}')->execute();

    $find   = $collection->find('job LIKE :job AND age > :age');
    $result = $find
      ->bind(['job' => 'Teacher', 'age' => 20])
      ->sort('age DESC')
      ->limit(2)
      ->execute();

    print_r($result->fetchAll());
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b536100000000000000a8
                [age] => 22
                [job] => Teacher
                [name] => Suki
            )
        [1] => Array
            (
                [_id] => 00005b6b536100000000000000a7
                [age] => 21
                [job] => Teacher
                [name] => Wilma
            )
    )

# Collection::getName

(No version information available, might only be in Git)

Collection::getName — Renvoie le nom de la collection

### Description

public function mysql_xdevapi\Collection::getName(): string

Renvoie le nom de la collection.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nom de la collection, sous forme de chaîne de caractères.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    var_dump($collection->getName());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(6) "people"

# Collection::getOne

(No version information available, might only be in Git)

Collection::getOne — Renvoie un document

### Description

public function mysql_xdevapi\Collection::getOne(string `$id`): Document

Récupère un document de la collection.

Ceci est un raccourci pour : `Collection.find("_id = :id").bind("id", id).execute().fetchOne();`

### Liste de paramètres

`id`

  Le _id du document dans la collection.

### Valeurs de retour

L'objet collection, ou `null` si l'_id ne correspond pas à un document.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::getOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Un identifiant unique _id (par défaut, et recommandé) est généré par MySQL Server
    // Ceci récupère les _id générés; un seul dans cet exemple, donc $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::getSchema

(No version information available, might only be in Git)

Collection::getSchema — Renvoie l'objet schéma

### Description

public function mysql_xdevapi\Collection::getSchema(): Schema Object

Renvoie l'objet schéma qui contient la collection.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet schéma en cas de succès, ou `null` si l'objet ne peut pas être récupéré pour la collection donnée.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    var_dump($collection->getSchema());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Collection::getSession

(No version information available, might only be in Git)

Collection::getSession — Renvoie l'objet session

### Description

public function mysql_xdevapi\Collection::getSession(): Session

Renvoie un nouvel objet Session à partir de l'objet Collection.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet Session.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    $newsession = $collection->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(mysql_xdevapi\Session)#1 (0) {
    }
    object(mysql_xdevapi\Session)#4 (0) {
    }

# Collection::modify

(No version information available, might only be in Git)

Collection::modify — Modifie les documents de la collection

### Description

public function mysql_xdevapi\Collection::modify(string `$search_condition`): mysql_xdevapi\CollectionModify

Modifie les documents d'une collection qui répondent à des conditions de recherche spécifiques. Plusieurs opérations sont autorisées, et la liaison de paramètres est supportée.

### Liste de paramètres

`search_condition`

  Doit être une expression SQL valide utilisée pour faire correspondre les documents à modifier. Cette expression peut être aussi simple que `true`, qui correspond à tous les documents, ou elle peut utiliser des fonctions et des opérateurs tels que `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'`, ou `'_id IN ["2","5","7","10"]'`.

### Valeurs de retour

Si l'opération n'est pas exécutée, alors la fonction retournera un objet Modify qui peut être utilisé pour ajouter des opérations de modification supplémentaires.

Si l'opération de modification est exécutée, alors l'objet retourné contiendra le résultat de l'opération.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::modify()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Ajoute deux nouveaux jobs pour tous les Painters: Artist et Crafter
    $collection
      ->modify("job in ('Butler', 'Painter')")
      ->arrayAppend('job', 'Artist')
      ->arrayAppend('job', 'Crafter')
      ->execute();

    // Enlève le champ 'beer' de tous les documents avec l'âge 21
    $collection
      ->modify('age < 21')
      ->unset(['beer'])
      ->execute();
    ?>

# Collection::remove

(No version information available, might only be in Git)

Collection::remove — Enlève des documents de la collection

### Description

public function mysql_xdevapi\Collection::remove(string `$search_condition`): mysql_xdevapi\CollectionRemove

Enlève des documents d'une collection qui répondent à des conditions de recherche spécifiques. Plusieurs opérations sont autorisées, et la liaison de paramètres est supportée.

### Liste de paramètres

`search_condition`

  Doit être une expression SQL valide utilisée pour faire correspondre les documents à modifier. Cette expression peut être aussi simple que `true`, qui correspond à tous les documents, ou elle peut utiliser des fonctions et des opérateurs tels que `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'`, ou `'_id IN ["2","5","7","10"]'`.

### Valeurs de retour

Si l'opération n'est pas exécutée, alors la fonction retournera un objet Remove qui peut être utilisé pour ajouter des opérations de suppression supplémentaires.

Si l'opération de suppression est exécutée, alors l'objet retourné contiendra le résultat de l'opération.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::remove()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Enlève tous les painters
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Enlève le plus vieux butler
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Enlève le record avec l'âge le plus élevé
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# Collection::removeOne

(No version information available, might only be in Git)

Collection::removeOne — Enlève un document de la collection

### Description

public function mysql_xdevapi\Collection::removeOne(string `$id`): mysql_xdevapi\Result

Enlève un document de la collection avec l'ID correspondant. Ceci est un raccourci pour `Collection.remove("_id = :id").bind("id", id).execute()`.

### Liste de paramètres

`id`

  L'identifiant du document de la collection à enlever. Typiquement c'est le _id généré par le serveur MySQL lors de l'ajout de l'enregistrement.

### Valeurs de retour

Un objet Result qui peut être utilisé pour interroger le nombre d'éléments affectés ou le nombre d'avertissements générés par l'opération.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::removeOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Normalement l'_id est connu par d'autres moyens,
    // mais pour cet exemple, récupérons l'identifiant généré et utilisons-le
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    $result = $collection->removeOne($alfred_id);

    if(!$result->getAffectedItemsCount()) {
        echo "Alfred with id $alfred_id was not removed.";
    } else {
        echo "Goodbye, Alfred, you can take _id $alfred_id with you.";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Goodbye, Alfred, you can take _id 00005b6b536100000000000000cb with you.

# Collection::replaceOne

(No version information available, might only be in Git)

Collection::replaceOne — Remplace un document de la collection

### Description

public function mysql_xdevapi\Collection::replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Modifie (ou remplace) le document identifié par ID, s'il existe.

### Liste de paramètres

`id`

  L'identifiant du document à remplacer ou mettre à jour. Typiquement c'est le _id généré par le serveur MySQL lors de l'ajout de l'enregistrement.

`doc`

  Le document de la collection à mettre à jour ou remplacer correspondant au paramètre id.

  Ce document peut être soit un objet document, soit une chaîne JSON valide décrivant le nouveau document.

### Valeurs de retour

Un objet Result qui peut être utilisé pour interroger le nombre d'éléments affectés et le nombre d'avertissements générés par l'opération.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::replaceOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Normalement l'_id est connu par d'autres moyens,
    // mais pour cet exemple, récupérons l'identifiant généré et utilisons-le
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    // ...

    $alfred = $collection->getOne($alfred_id);
    $alfred['age'] = 81;
    $alfred['job'] = 'Guru';

    $collection->replaceOne($alfred_id, $alfred);

    ?>

## Sommaire

- Collection::add — Ajoute un document à la collection
- Collection::addOrReplaceOne — Ajoute ou remplace un document de la collection
- Collection::__construct — Constructeur de Collection
- Collection::count — Renvoie le nombre de documents
- Collection::createIndex — Créer un index de collection
- Collection::dropIndex — Supprime un index de collection
- Collection::existsInDatabase — Vérifie si la collection existe dans la base de données
- Collection::find — Recherche de document
- Collection::getName — Renvoie le nom de la collection
- Collection::getOne — Renvoie un document
- Collection::getSchema — Renvoie l'objet schéma
- Collection::getSession — Renvoie l'objet session
- Collection::modify — Modifie les documents de la collection
- Collection::remove — Enlève des documents de la collection
- Collection::removeOne — Enlève un document de la collection
- Collection::replaceOne — Remplace un document de la collection

# Classe CollectionAdd

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\CollectionAdd implements mysql_xdevapi\Executable {
/* Méthodes */
public function execute(): mysql_xdevapi\Result
}

# CollectionAdd::__construct

(No version information available, might only be in Git)

CollectionAdd::__construct — Constructeur de CollectionAdd

### Description

private function mysql_xdevapi\CollectionAdd::__construct()

Utiliser pour ajouter un document à une collection; appelé depuis un objet Collection.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionAdd::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Ajoute deux documents
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Ajoute deux documents en utilisant un seul objet JSON
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Récupère une liste d'ID générés par le dernier add()
    $ids = $result->getGeneratedIds();
    print_r($ids);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Notes

> Note:

> Un identifiant unique _id est généré par MySQL Server 8.0 ou supérieur, comme démontré dans l'exemple. Le champ _id doit être défini manuellement si on utilise MySQL Server 5.7.

# CollectionAdd::execute

(No version information available, might only be in Git)

CollectionAdd::execute — Exécute la déclaration

### Description

public function mysql_xdevapi\CollectionAdd::execute(): mysql_xdevapi\Result

La méthode execute est requise pour envoyer la demande d'opération CRUD au serveur MySQL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet Result qui peut être utilisé pour vérifier l'état de l'opération, tel que le nombre de lignes affectées.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionAdd::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Ajoute deux documents
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Ajoute deux documents en utilisant un seul objet JSON
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Récupère une liste d'ID générés par le dernier add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

## Sommaire

- CollectionAdd::__construct — Constructeur de CollectionAdd
- CollectionAdd::execute — Exécute la déclaration

# Classe CollectionFind

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\CollectionFind implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Méthodes */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind
public function execute(): mysql_xdevapi\DocResult
public function fields(string `$projection`): mysql_xdevapi\CollectionFind
public function groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function having(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function limit(int `$rows`): mysql_xdevapi\CollectionFind
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function offset(int `$position`): mysql_xdevapi\CollectionFind
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionFind
}

# CollectionFind::bind

(No version information available, might only be in Git)

CollectionFind::bind — Lie une valeur à un paramètre de requête

### Description

public function mysql_xdevapi\CollectionFind::bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind

Cela permet à l'utilisateur de lier un paramètre à l'espace réservé dans la condition de recherche de l'opération find. L'espace réservé a la forme de :NOM où ':' est un préfixe commun qui doit toujours exister avant tout NOM, Nom est le nom réel de l'espace réservé. La fonction bind accepte une liste d'espaces reservés si plusieurs entités doivent être substituées dans la condition de recherche.

### Liste de paramètres

`placeholder_values`

  Les valeurs à substituer dans la condition de recherche; plusieurs valeurs sont autorisées et sont passées sous forme de tableau où "NOM_ESPACE_RESERVE => VALEUR_ESPACE_RESERVE".

### Valeurs de retour

Un objet CollectionFind, ou chaîné avec execute() pour retourner un objet Result.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionFind::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::__construct

(No version information available, might only be in Git)

CollectionFind::__construct — Constructeur de CollectionFind

### Description

private function mysql_xdevapi\CollectionFind::__construct()

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de CollectionFind

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::execute

(No version information available, might only be in Git)

CollectionFind::execute — Exécute la déclaration

### Description

public function mysql_xdevapi\CollectionFind::execute(): mysql_xdevapi\DocResult

Exécute l'opération de recherche; cette fonctionnalité permet le chaînage des méthodes.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet mysql_xdevapi\DocResult, qui peut être utilisé pour récupérer les résultats, ou pour interroger l'état de l'opération.

### Exemples

Exemple #1 Exemple de CollectionFind

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::fields

(No version information available, might only be in Git)

CollectionFind::fields — Définit le filtre de champ de document

### Description

public function mysql_xdevapi\CollectionFind::fields(string `$projection`): mysql_xdevapi\CollectionFind

Définit les colonnes pour la requête à retourner. Si non défini, toutes les colonnes sont utilisées.

### Liste de paramètres

`projection`

  Peut être une chaîne unique ou un tableau de chaînes identifiant les colonnes à retourner pour chaque document correspondant à la condition de recherche.

### Valeurs de retour

Un objet CollectionFind qui peut être utilisé pour un traitement ultérieur.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionFind::fields()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->fields('name')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(1) {
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::groupBy

(No version information available, might only be in Git)

CollectionFind::groupBy — Définit les critères de regroupement

### Description

public function mysql_xdevapi\CollectionFind::groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind

Cette fonction peut être utilisée pour regrouper le jeu de résultats par une ou plusieurs colonnes. Elle est souvent utilisée avec des fonctions d'agrégation telles que `COUNT`, `MAX`, `MIN`, `SUM` etc.

### Liste de paramètres

`sort_expr`

  La ou les colonnes qui doivent être utilisées pour l'opération de regroupement, cela peut être soit une chaîne unique soit un tableau d'arguments de chaîne, un pour chaque colonne.

### Valeurs de retour

Un objet CollectionFind qui peut être utilisé pour un traitement ultérieur.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionFind::groupBy()

    <?php

    // Assumant que $coll est un objet Collection valide

    // Extrait tous les documents de la Collection et regroupe les résultats par le champ 'name'
    $res = $coll->find()->groupBy('name')->execute();

    ?>

# CollectionFind::having

(No version information available, might only be in Git)

CollectionFind::having — Définit la condition pour les fonctions d'agrégation

### Description

public function mysql_xdevapi\CollectionFind::having(string `$sort_expr`): mysql_xdevapi\CollectionFind

Cette fonction peut être utilisée après l'opération 'field' afin de faire une sélection sur les documents à extraire.

### Liste de paramètres

`sort_expr`

  Cela doit être une expression SQL valide, l'utilisation de fonctions d'agrégation est autorisée

### Valeurs de retour

Un objet CollectionFind qui peut être utilisé pour un traitement ultérieur.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionFind::having()

    <?php

    //Assumant que $coll est un objet Collection valide

    //Trouve tous les documents pour lesquels l'âge est supérieur à 40,
    //Seules les colonnes 'name' et 'age' sont retournées dans l'objet Result
    $res = $coll->find()->fields(['name','age'])->having('age > 40')->execute();

    ?>

# CollectionFind::limit

(No version information available, might only be in Git)

CollectionFind::limit — Limite le nombre de documents retournés

### Description

public function mysql_xdevapi\CollectionFind::limit(int `$rows`): mysql_xdevapi\CollectionFind

Définit le nombre maximum de documents à retourner.

### Liste de paramètres

`rows`

  Le nombre maximum de documents.

### Valeurs de retour

Un objet mysql_xdevapi\CollectionFind qui peut être utilisé pour un traitement ultérieur; chaînez avec la méthode execute() pour retourner un objet DocResult.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionFind::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::lockExclusive

(No version information available, might only be in Git)

CollectionFind::lockExclusive — Exécute l'opération avec un VERROU EXCLUSIF

### Description

public function mysql_xdevapi\CollectionFind::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Verrouille le document de manière exclusive. Tant que le document est verrouillé, d'autres transactions ne peuvent pas mettre à jour le document, utiliser `SELECT ... LOCK IN SHARE MODE`, ou lire les données dans certains niveaux d'isolation de transaction. Les lectures cohérentes ignorent les verrous définis sur les enregistrements qui existent dans la vue de lecture.

Pour éviter les problèmes de concurrence, il est logique d'utiliser cette fonction avec la méthode mysql_xdevapi\Collection::modify(). Essentiellement, cette fonction utilise des verrous de ligne pour sérialiser l'accès aux lignes.

### Liste de paramètres

`lock_waiting_option`

  Une option d'attente facultative. Par défaut, c'est `MYSQLX_LOCK_DEFAULT`. Les valeurs valides sont ces constantes :

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valeurs de retour

Renvoie un objet CollectionFind qui peut être utilisé pour un traitement ultérieur.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionFind::lockExclusive()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockExclusive()
      ->execute();

    // ... faire une opération sur l'objet

    // Valider la transaction et déverrouiller le document
    $session->commit();
    ?>

# CollectionFind::lockShared

(No version information available, might only be in Git)

CollectionFind::lockShared — Exécute l'opération avec un VERROU PARTAGE

### Description

public function mysql_xdevapi\CollectionFind::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Autorise le partage des documents entre plusieurs transactions qui sont verrouillées en mode partagé.

D'autres sessions peuvent lire les lignes, mais ne peuvent pas les modifier tant que la transaction n'a pas validé.

Si l'une de ces lignes a été modifiée par une autre transaction qui n'a pas été validée, la requête attendra que cette transaction soit terminée pour pouvoir utiliser les dernières valeurs.

### Liste de paramètres

`lock_waiting_option`

  Une option d'attente facultative. Par défaut, c'est `MYSQLX_LOCK_DEFAULT`. Les valeurs valides sont ces constantes :

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valeurs de retour

Un objet CollectionFind qui peut être utilisé pour un traitement ultérieur.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionFind::lockShared()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockShared()
      ->execute();

    // ... lire l'objet en mode partagé

    // Valider la transaction et déverrouiller le document
    $session->commit();
    ?>

# CollectionFind::offset

(No version information available, might only be in Git)

CollectionFind::offset — Ignore un nombre donné d'éléments à retourner

### Description

public function mysql_xdevapi\CollectionFind::offset(int `$position`): mysql_xdevapi\CollectionFind

Ignore (décale) un nombre donné d'éléments qui autrement seraient retournés par l'opération find. Utiliser avec la méthode limit().

Définir un décalage plus grand que la taille de l'ensemble de résultats donne un ensemble vide.

### Liste de paramètres

`position`

  Le nombre d'éléments à ignorer pour l'opération limit().

### Valeurs de retour

Un objet CollectionFind qui peut être utilisé pour un traitement ultérieur.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionFind::offset()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('age asc')
      ->offset(1)
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::sort

(No version information available, might only be in Git)

CollectionFind::sort — Définit les critères de tri

### Description

public function mysql_xdevapi\CollectionFind::sort(string `$sort_expr`): mysql_xdevapi\CollectionFind

Trie le jeu de résultats par le champ sélectionné dans l'argument sort_expr. Les ordres autorisés sont ASC (Ascendant) ou DESC (Descendant). Cette opération est équivalente à l'opération 'ORDER BY' SQL et suit le même ensemble de règles.

### Liste de paramètres

`sort_expr`

  Une ou plusieurs expressions de tri peuvent être fournies. L'évaluation se fait de gauche à droite, et chaque expression est séparée par une virgule.

### Valeurs de retour

Un objet CollectionFind qui peut être utilisé pour exécuter la commande, ou pour ajouter des opérations supplémentaires.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionFind::sort()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('job desc', 'age asc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(2) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000106"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000107"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

## Sommaire

- CollectionFind::bind — Lie une valeur à un paramètre de requête
- CollectionFind::__construct — Constructeur de CollectionFind
- CollectionFind::execute — Exécute la déclaration
- CollectionFind::fields — Définit le filtre de champ de document
- CollectionFind::groupBy — Définit les critères de regroupement
- CollectionFind::having — Définit la condition pour les fonctions d'agrégation
- CollectionFind::limit — Limite le nombre de documents retournés
- CollectionFind::lockExclusive — Exécute l'opération avec un VERROU EXCLUSIF
- CollectionFind::lockShared — Exécute l'opération avec un VERROU PARTAGE
- CollectionFind::offset — Ignore un nombre donné d'éléments à retourner
- CollectionFind::sort — Définit les critères de tri

# Classe CollectionModify

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\CollectionModify implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSkippable, mysql_xdevapi\CrudOperationSortable {
/* Méthodes */
public function arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionModify
public function patch(string `$document`): mysql_xdevapi\CollectionModify
public function replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function skip(int `$position`): mysql_xdevapi\CollectionModify
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionModify
public function unset(array `$fields`): mysql_xdevapi\CollectionModify
}

# CollectionModify::arrayAppend

(No version information available, might only be in Git)

CollectionModify::arrayAppend — Ajoute un élément à un champ de tableau

### Description

public function mysql_xdevapi\CollectionModify::arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Ajoute un élément à un champ d'un document, car plusieurs éléments d'un champ sont représentés sous forme de tableau. Contrairement à arrayInsert(), arrayAppend() ajoute toujours le nouvel élément à la fin du tableau, alors que arrayInsert() peut définir l'emplacement.

### Liste de paramètres

`collection_field`

  L'identifiant du champ où le nouvel élément est inséré.

`expression_or_literal`

  Le nouvel élément à insérer à la fin du tableau du champ du document.

### Valeurs de retour

Un objet CollectionModify qui peut être utilisé pour exécuter la commande, ou pour ajouter des opérations supplémentaires.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::arrayAppend()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::arrayInsert

(No version information available, might only be in Git)

CollectionModify::arrayInsert — Insère un élément dans un champ de tableau

### Description

public function mysql_xdevapi\CollectionModify::arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Ajoute un élément à un champ d'un document, car plusieurs éléments d'un champ sont représentés sous forme de tableau. Contrairement à mysql_xdevapi\CollectionModify::arrayAppend() cette méthode permet de spécifier où le nouvel élément est inséré en définissant après quel élément, alors que mysql_xdevapi\CollectionModify::arrayAppend() ajoute toujours le nouvel élément à la fin du tableau.

### Liste de paramètres

`collection_field`

  Identifie l'élément du tableau après lequel le nouvel élément sera inséré. Le format de ce paramètre est `FIELD_NAME[ INDEX ]` où FIELD_NAME est le nom du champ du document où ajouter l'élément, et INDEX est l'INDEX de l'élément dans le champ.

  L'INDEX est basé sur zéro, donc le premier élément du tableau a un index de 0.

`expression_or_literal`

  Le nouvel élément à insérer après FIELD_NAME[ INDEX ]

### Valeurs de retour

Un objet CollectionModify qui peut être utilisé pour exécuter la commande, ou pour ajouter des opérations supplémentaires.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::arrayInsert()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayInsert('traits[1]', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010d
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Happy
                        [2] => Brother
                        [3] => Human
                    )
            )
    )

# CollectionModify::bind

(No version information available, might only be in Git)

CollectionModify::bind — Lie une valeur à un paramètre de requête

### Description

public function mysql_xdevapi\CollectionModify::bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify

Lie un paramètre à un espace réservé dans la condition de recherche de l'opération de modification.

L'espace réservé a la forme de :NOM où ':' est un préfixe commun qui doit toujours exister avant tout NOM où NOM est le nom de l'espace réservé. La méthode bind accepte une liste d'espaces réservés si plusieurs entités doivent être substituées dans la condition de recherche de l'opération de modification.

### Liste de paramètres

`placeholder_values`

  Les valeurs d'espace réservé à substituer dans la condition de recherche. Plusieurs valeurs sont autorisées et doivent être passées sous forme de tableau de mappages NOM_ESPACE_RESERVE->VALEUR_ESPACE_RESERVE.

### Valeurs de retour

Un objet CollectionModify qui peut être utilisé pour exécuter la commande, ou pour ajouter des opérations supplémentaires.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000110
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::__construct

(No version information available, might only be in Git)

CollectionModify::__construct — Constructeur de CollectionModify

### Description

private function mysql_xdevapi\CollectionModify::__construct()

Modifie (met à jour) une collection et est instancié par la méthode mysql_xdevapi\Collection::modify().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::execute

(No version information available, might only be in Git)

CollectionModify::execute — Exécute l'opération de modification

### Description

public function mysql_xdevapi\CollectionModify::execute(): mysql_xdevapi\Result

La méthode execute est requise pour envoyer la requête d'opération CRUD au serveur MySQL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet Result qui peut être utilisé pour vérifier le statut de l'opération, tel que le nombre de lignes affectées.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::execute()

    <?php

    /* ... */

    ?>

# CollectionModify::limit

(No version information available, might only be in Git)

CollectionModify::limit — Limite le nombre de documents modifiés

### Description

public function mysql_xdevapi\CollectionModify::limit(int `$rows`): mysql_xdevapi\CollectionModify

Limite le nombre de documents modifiés par cette opération. Combine éventuellement avec skip() pour définir une valeur de décalage.

### Liste de paramètres

`rows`

  Le nombre maximum de documents à modifier.

### Valeurs de retour

Un objet CollectionModify.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();
    $collection->add('{"name": "Betty", "age": 24, "job": "Teacher"}')->execute();

    $collection
      ->modify("job = :job")
      ->bind(['job' => 'Teacher'])
      ->set('job', 'Principal')
      ->limit(1)
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000118
                [age] => 21
                [job] => Construction
                [name] => Fred
            )
        [1] => Array
            (
                [_id] => 00005b6b53610000000000000119
                [age] => 23
                [job] => Principal
                [name] => Wilma
            )
        [2] => Array
            (
                [_id] => 00005b6b5361000000000000011a
                [age] => 24
                [job] => Teacher
                [name] => Betty
            )
    )

# CollectionModify::patch

(No version information available, might only be in Git)

CollectionModify::patch — Corrige un document

### Description

public function mysql_xdevapi\CollectionModify::patch(string `$document`): mysql_xdevapi\CollectionModify

Prend un objet patch et l'applique sur un ou plusieurs documents, et peut mettre à jour plusieurs propriétés de document.

### Liste de paramètres

`document`

  Un document avec les propriétés à appliquer aux documents correspondants.

### Valeurs de retour

Un objet CollectionModify.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::patch()

    <?php

    $res = $coll->modify('"Programmatore" IN job')->patch('{"Hobby" : "Programmare"}')->execute();

    ?>

# CollectionModify::replace

(No version information available, might only be in Git)

CollectionModify::replace — Remplace un champ de document

### Description

public function mysql_xdevapi\CollectionModify::replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Remplace (met à jour) une valeur de champ donnée par une nouvelle.

### Liste de paramètres

`collection_field`

  Le chemin du document de l'élément à définir.

`expression_or_literal`

  La valeur à définir sur l'attribut spécifié.

### Valeurs de retour

Un objet CollectionModify.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::replace()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->replace("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000011b
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::set

(No version information available, might only be in Git)

CollectionModify::set — Définit un attribut de document

### Description

public function mysql_xdevapi\CollectionModify::set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Définit ou met à jour des attributs sur des documents dans une collection.

### Liste de paramètres

`collection_field`

  Le chemin (nom) du document de l'élément à définir.

`expression_or_literal`

  La valeur à définir sur l'attribut spécifié.

### Valeurs de retour

Un objet CollectionModify.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::set()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->set("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000111
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::skip

(No version information available, might only be in Git)

CollectionModify::skip — Ignore les éléments

### Description

public function mysql_xdevapi\CollectionModify::skip(int `$position`): mysql_xdevapi\CollectionModify

Ignore les N premiers éléments qui seraient autrement retournés par une opération de recherche. Si le nombre d'éléments ignorés est supérieur à la taille de l'ensemble de résultats, alors l'opération de recherche renvoie un ensemble vide.

### Liste de paramètres

`position`

  Le nombre d'éléments à ignorer.

### Valeurs de retour

Un objet CollectionModify à utiliser pour un traitement ultérieur.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::skip()

    <?php

    $coll->modify('age > :age')->sort('age desc')->unset(['age'])->bind(['age' => 20])->limit(4)->skip(1)->execute();

    ?>

# CollectionModify::sort

(No version information available, might only be in Git)

CollectionModify::sort — Définit les critères de tri

### Description

public function mysql_xdevapi\CollectionModify::sort(string `$sort_expr`): mysql_xdevapi\CollectionModify

Trie le jeu de résultats par le champ sélectionné dans l'argument sort_expr. Les ordres autorisés sont ASC (Ascendant) ou DESC (Descendant). Cette opération est équivalente à l'opération SQL 'ORDER BY' et suit le même ensemble de règles.

### Liste de paramètres

`sort_expr`

  Une ou plusieurs expressions de tri peuvent être fournies. L'évaluation se fait de gauche à droite et chaque expression doit être séparée par une virgule.

### Valeurs de retour

Un objet CollectionModify qui peut être utilisé pour un traitement ultérieur.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::sort()

    <?php

    $res = $coll->modify('true')->sort('name desc', 'age asc')->limit(4)->set('Married', 'NO')->execute();

    ?>

# CollectionModify::unset

(No version information available, might only be in Git)

CollectionModify::unset — Supprime la valeur des champs de document

### Description

public function mysql_xdevapi\CollectionModify::unset(array `$fields`): mysql_xdevapi\CollectionModify

Supprime les attributs des documents dans une collection.

### Liste de paramètres

`fields`

  Les attributs à supprimer des documents dans une collection.

### Valeurs de retour

Un objet CollectionModify qui peut être utilisé pour un traitement ultérieur.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionModify::unset()

    <?php

    $res = $coll->modify('job like :job_name')->unset(["age", "name"])->bind(['job_name' => 'Plumber'])->execute();

    ?>

## Sommaire

- CollectionModify::arrayAppend — Ajoute un élément à un champ de tableau
- CollectionModify::arrayInsert — Insère un élément dans un champ de tableau
- CollectionModify::bind — Lie une valeur à un paramètre de requête
- CollectionModify::__construct — Constructeur de CollectionModify
- CollectionModify::execute — Exécute l'opération de modification
- CollectionModify::limit — Limite le nombre de documents modifiés
- CollectionModify::patch — Corrige un document
- CollectionModify::replace — Remplace un champ de document
- CollectionModify::set — Définit un attribut de document
- CollectionModify::skip — Ignore les éléments
- CollectionModify::sort — Définit les critères de tri
- CollectionModify::unset — Supprime la valeur des champs de document

# Classe CollectionRemove

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\CollectionRemove implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Méthodes */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionRemove
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove
}

# CollectionRemove::bind

(No version information available, might only be in Git)

CollectionRemove::bind — Lie une valeur à un paramètre

### Description

public function mysql_xdevapi\CollectionRemove::bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove

Lie un paramètre à l'espace réservé dans la condition de recherche de l'opération de suppression.

L'espace réservé a la forme de :NAME où ':' est un préfixe commun qui doit toujours exister avant tout NAME où NAME est le nom de l'espace réservé. La méthode bind accepte une liste d'espaces réservés si plusieurs entités doivent être substituées dans la condition de recherche de l'opération de suppression.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`placeholder_values`

  La valeur de l'espace réservé à substituer dans la condition de recherche. Plusieurs valeurs sont autorisées et doivent être passées sous la forme d'un tableau de mappages NOM_ESPACE_RESERVE->VALEUR_ESPACE_RESERVE.

### Valeurs de retour

Un objet CollectionRemove qui peut être utilisé pour exécuter la commande, ou pour ajouter des opérations supplémentaires.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionRemove::bind()

    <?php

    $res = $coll->remove('age > :age_from and age < :age_to')->bind(['age_from' => 20, 'age_to' => 50])->limit(7)->execute();

    ?>

# CollectionRemove::__construct

(No version information available, might only be in Git)

CollectionRemove::__construct — Constructeur de CollectionRemove

### Description

private function mysql_xdevapi\CollectionRemove::__construct()

Supprime les documents de la collection et est instancié par la méthode mysql_xdevapi\Collection::remove().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Collection::remove()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Supprime tous les peintres
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Supprime le butler le plus âgé
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Supprime l'enregistrement avec l'âge le plus bas
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# CollectionRemove::execute

(No version information available, might only be in Git)

CollectionRemove::execute — Exécute l'opération de suppression

### Description

public function mysql_xdevapi\CollectionRemove::execute(): mysql_xdevapi\Result

La fonction execute doit être invoquée pour déclencher le client à envoyer la requête d'opération CRUD au serveur.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Result object.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionRemove::execute()

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

# CollectionRemove::limit

(No version information available, might only be in Git)

CollectionRemove::limit — Limite le nombre de documents à supprimer

### Description

public function mysql_xdevapi\CollectionRemove::limit(int `$rows`): mysql_xdevapi\CollectionRemove

Définit le nombre maximum de documents à supprimer.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`rows`

  Le nombre maximum de documents à supprimer.

### Valeurs de retour

Renvoie un objet CollectionRemove qui peut être utilisé pour exécuter la commande, ou pour ajouter des opérations supplémentaires.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionRemove::limit()

    <?php

    $res = $coll->remove('job in (\'Barista\', \'Programmatore\', \'Ballerino\', \'Programmatrice\')')->limit(5)->sort(['age desc', 'name asc'])->execute();

    ?>

# CollectionRemove::sort

(No version information available, might only be in Git)

CollectionRemove::sort — Définit le critère de tri

### Description

public function mysql_xdevapi\CollectionRemove::sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove

Trie le jeu de résultats par le champ sélectionné dans l'argument sort_expr. Les ordres autorisés sont ASC (Ascending) ou DESC (Descending). Cette opération est équivalente à l'opération SQL 'ORDER BY' et suit le même ensemble de règles.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`sort_expr`

  Une ou plusieurs expressions de tri peuvent être fournies. L'évaluation se fait de gauche à droite, et chaque expression est séparée par une virgule.

### Valeurs de retour

Un objet CollectionRemove qui peut être utilisé pour exécuter la commande, ou pour ajouter des opérations supplémentaires.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CollectionRemove::sort()

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

## Sommaire

- CollectionRemove::bind — Lie une valeur à un paramètre
- CollectionRemove::__construct — Constructeur de CollectionRemove
- CollectionRemove::execute — Exécute l'opération de suppression
- CollectionRemove::limit — Limite le nombre de documents à supprimer
- CollectionRemove::sort — Définit le critère de tri

# Classe ColumnResult

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\ColumnResult {
/* Méthodes */
public function getCharacterSetName(): string
public function getCollationName(): string
public function getColumnLabel(): string
public function getColumnName(): string
public function getFractionalDigits(): int
public function getLength(): int
public function getSchemaName(): string
public function getTableLabel(): string
public function getTableName(): string
public function getType(): int
public function isNumberSigned(): int
public function isPadded(): int
}

# ColumnResult::__construct

(No version information available, might only be in Git)

ColumnResult::__construct — Constructeur de ColumnResult

### Description

private function mysql_xdevapi\ColumnResult::__construct()

Renvoie les métadonnées de colonne, telles que son jeu de caractères ; cela est instancié par la méthode mysql_xdevapi\RowResult::getColumns().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS nonsense")->execute();
    $session->sql("CREATE DATABASE nonsense")->execute();
    $session->sql("CREATE TABLE nonsense.numbers (hello int, world float unsigned)")->execute();
    $session->sql("INSERT INTO  nonsense.numbers values (42, 42)")->execute();

    $schema = $session->getSchema("nonsense");
    $table  = $schema->getTable("numbers");

    $result1 = $table->select('hello','world')->execute();

    // Renvoie un tableau d'objets ColumnResult
    $columns = $result1->getColumns();

    foreach ($columns as $column) {
        echo "\nColumn label " , $column->getColumnLabel();
        echo " is type "       , $column->getType();
        echo " and is ", ($column->isNumberSigned() === 0) ? "unsigned." : "signed.";
    }

    // Ou bien
    $result2 = $session->sql("SELECT * FROM nonsense.numbers")->execute();

    // Renvoie un tableau d'objets FieldMetadata
    print_r($result2->getColumns());

Résultat de l'exemple ci-dessus est similaire à :

    Column label hello is type 19 and is signed.
    Column label world is type 4  and is unsigned.

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => hello
                [original_name] => hello
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 6
                [type_name] => FLOAT
                [name] => world
                [original_name] => world
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 31
                [length] => 12
                [flags] => 1
                [content_type] => 0
            )
    )

# ColumnResult::getCharacterSetName

(No version information available, might only be in Git)

ColumnResult::getCharacterSetName — Renvoie le jeu de caractères

### Description

public function mysql_xdevapi\ColumnResult::getCharacterSetName(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getCharacterSetName()

    <?php

    /* ... */

    ?>

# ColumnResult::getCollationName

(No version information available, might only be in Git)

ColumnResult::getCollationName — Renvoie le nom de la collation

### Description

public function mysql_xdevapi\ColumnResult::getCollationName(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getCollationName()

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnLabel

(No version information available, might only be in Git)

ColumnResult::getColumnLabel — Renvoie l'étiquette de colonne

### Description

public function mysql_xdevapi\ColumnResult::getColumnLabel(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getColumnLabel()

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnName

(No version information available, might only be in Git)

ColumnResult::getColumnName — Renvoie le nom de la colonne

### Description

public function mysql_xdevapi\ColumnResult::getColumnName(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getColumnName()

    <?php

    /* ... */

    ?>

# ColumnResult::getFractionalDigits

(No version information available, might only be in Git)

ColumnResult::getFractionalDigits — Renvoie la longueur des chiffres fractionnels

### Description

public function mysql_xdevapi\ColumnResult::getFractionalDigits(): int

Récupère le nombre de chiffres fractionnels pour la colonne.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getFractionalDigits()

    <?php

    /* ... */

    ?>

# ColumnResult::getLength

(No version information available, might only be in Git)

ColumnResult::getLength — Renvoie la longueur du champ

### Description

public function mysql_xdevapi\ColumnResult::getLength(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getLength()

    <?php

    /* ... */

    ?>

# ColumnResult::getSchemaName

(No version information available, might only be in Git)

ColumnResult::getSchemaName — Renvoie le nom du schéma

### Description

public function mysql_xdevapi\ColumnResult::getSchemaName(): string

Récupère le nom du schéma où la colonne est stockée.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getSchemaName()

    <?php

    /* ... */

    ?>

# ColumnResult::getTableLabel

(No version information available, might only be in Git)

ColumnResult::getTableLabel — Renvoie l'étiquette de table

### Description

public function mysql_xdevapi\ColumnResult::getTableLabel(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getTableLabel()

    <?php

    /* ... */

    ?>

# ColumnResult::getTableName

(No version information available, might only be in Git)

ColumnResult::getTableName — Renvoie le nom de la table

### Description

public function mysql_xdevapi\ColumnResult::getTableName(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nom de la table pour la colonne.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getTableName()

    <?php

    /* ... */

    ?>

# ColumnResult::getType

(No version information available, might only be in Git)

ColumnResult::getType — Renvoie le type de colonne

### Description

public function mysql_xdevapi\ColumnResult::getType(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::getType()

    <?php

    /* ... */

    ?>

# ColumnResult::isNumberSigned

(No version information available, might only be in Git)

ColumnResult::isNumberSigned — Renvoie si le type est signé

### Description

public function mysql_xdevapi\ColumnResult::isNumberSigned(): int

Récupère les informations de colonne d'une table et est instancié par la méthode mysql_xdevapi\RowResult::getColumns().

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si une colonne donnée est de type signé.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::isNumberSigned()

    <?php

    /* ... */

    ?>

# ColumnResult::isPadded

(No version information available, might only be in Git)

ColumnResult::isPadded — Vérifie si le champ a un remplissage

### Description

public function mysql_xdevapi\ColumnResult::isPadded(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si une colonne donnée a un remplissage.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ColumnResult::isPadded()

    <?php

    /* ... */

    ?>

## Sommaire

- ColumnResult::__construct — Constructeur de ColumnResult
- ColumnResult::getCharacterSetName — Renvoie le jeu de caractères
- ColumnResult::getCollationName — Renvoie le nom de la collation
- ColumnResult::getColumnLabel — Renvoie l'étiquette de colonne
- ColumnResult::getColumnName — Renvoie le nom de la colonne
- ColumnResult::getFractionalDigits — Renvoie la longueur des chiffres fractionnels
- ColumnResult::getLength — Renvoie la longueur du champ
- ColumnResult::getSchemaName — Renvoie le nom du schéma
- ColumnResult::getTableLabel — Renvoie l'étiquette de table
- ColumnResult::getTableName — Renvoie le nom de la table
- ColumnResult::getType — Renvoie le type de colonne
- ColumnResult::isNumberSigned — Renvoie si le type est signé
- ColumnResult::isPadded — Vérifie si le champ a un remplissage

# Interface CrudOperationBindable

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\CrudOperationBindable {
/* Méthodes */
abstract public function bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable
}

# CrudOperationBindable::bind

(No version information available, might only be in Git)

CrudOperationBindable::bind — Lie une valeur à un espace réservé

### Description

abstract public function mysql_xdevapi\CrudOperationBindable::bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable

Lie une valeur à un espace réservé spécifique.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`placeholder_values`

  Le nom des espaces réservés et les valeurs à lier.

### Valeurs de retour

Un objet CrudOperationBindable

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CrudOperationBindable::bind()

    <?php

    $res = $coll->modify('name like :name')->arrayInsert('job[0]', 'Calciatore')->bind(['name' => 'ENTITY'])->execute();
    $res = $table->delete()->orderby('age desc')->where('age < 20 and age > 12 and name != :name')->bind(['name' => 'Tierney'])->limit(2)->execute();

    ?>

## Sommaire

- CrudOperationBindable::bind — Lie une valeur à un espace réservé

# Interface CrudOperationLimitable

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\CrudOperationLimitable {
/* Méthodes */
abstract public function limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable
}

# CrudOperationLimitable::limit

(No version information available, might only be in Git)

CrudOperationLimitable::limit — Définit la limite de résultats

### Description

abstract public function mysql_xdevapi\CrudOperationLimitable::limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable

Définit le nombre maximum de résultats ou de documents à retourner.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`rows`

  Le nombre maximum de résultats ou de documents.

### Valeurs de retour

Un objet CrudOperationLimitable.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CrudOperationLimitable::limit()

    <?php

    $res = $coll->find()->fields(['name as n','age as a','job as j'])->groupBy('j')->limit(11)->execute();
    $res = $table->update()->set('age',69)->where('age > 15 and age < 22')->limit(4)->orderby(['age asc','name desc'])->execute();

    ?>

## Sommaire

- CrudOperationLimitable::limit — Définit la limite de résultats

# Interface CrudOperationSkippable

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\CrudOperationSkippable {
/* Méthodes */
abstract public function skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable
}

# CrudOperationSkippable::skip

(No version information available, might only be in Git)

CrudOperationSkippable::skip — Le nombre d'opérations à ignorer

### Description

abstract public function mysql_xdevapi\CrudOperationSkippable::skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable

Ignore ce nombre d'enregistrements dans l'opération retournée.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`skip`

  Le nombre d'éléments à ignorer.

### Valeurs de retour

Un objet CrudOperationSkippable.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CrudOperationSkippable::skip()

    <?php

    $res = $coll->find('job like \'Programmatore\'')->limit(1)->skip(3)->sort('age asc')->execute();

    ?>

## Sommaire

- CrudOperationSkippable::skip — Le nombre d'opérations à ignorer

# Interface CrudOperationSortable

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\CrudOperationSortable {
/* Méthodes */
abstract public function sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable
}

# CrudOperationSortable::sort

(No version information available, might only be in Git)

CrudOperationSortable::sort — Trie les résultats

### Description

abstract public function mysql_xdevapi\CrudOperationSortable::sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable

Trie le jeu de résultats par le champ sélectionné dans l'argument sort_expr. Les ordres autorisés sont ASC (Ascendant) ou DESC (Descendant). Cette opération est équivalente à l'opération SQL 'ORDER BY' et suit le même ensemble de règles.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`sort_expr`

  Une ou plusieurs expressions de tri peuvent être fournies. L'évaluation se fait de gauche à droite, et chaque expression est séparée par une virgule.

### Valeurs de retour

Un objet CrudOperationSortable.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\CrudOperationSortable::sort()

    <?php

    $res = $coll->find('job like \'Cavia\'')->sort('age desc', '_id desc')->execute();

    ?>

## Sommaire

- CrudOperationSortable::sort — Trie les résultats

# Interface DatabaseObject

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\DatabaseObject {
/* Méthodes */
abstract public function existsInDatabase(): bool
abstract public function getName(): string
abstract public function getSession(): mysql_xdevapi\Session
}

# DatabaseObject::existsInDatabase

(No version information available, might only be in Git)

DatabaseObject::existsInDatabase — Vérifie si l'objet existe dans la base de données

### Description

abstract public function mysql_xdevapi\DatabaseObject::existsInDatabase(): bool

Vérifie si l'objet de base de données fait référence à un objet qui existe dans la base de données.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si l'objet existe dans la base de données, sinon `false` s'il n'existe pas.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\DatabaseObject::existsInDatabase()

    <?php

    $existInDb = $dbObj->existsInDatabase();

    ?>

# DatabaseObject::getName

(No version information available, might only be in Git)

DatabaseObject::getName — Renvoie le nom de l'objet

### Description

abstract public function mysql_xdevapi\DatabaseObject::getName(): string

Récupère le nom de cet objet de base de données.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nom de cet objet de base de données.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\DatabaseObject::getName()

    <?php

    $dbObjName = $dbObj->getName();

    ?>

# DatabaseObject::getSession

(No version information available, might only be in Git)

DatabaseObject::getSession — Renvoie le nom de la session

### Description

abstract public function mysql_xdevapi\DatabaseObject::getSession(): mysql_xdevapi\Session

Récupère la session associée à l'objet de base de données.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Session.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\DatabaseObject::getSession()

    <?php

    $session = $dbObj->getSession();

    ?>

## Sommaire

- DatabaseObject::existsInDatabase — Vérifie si l'objet existe dans la base de données
- DatabaseObject::getName — Renvoie le nom de l'objet
- DatabaseObject::getSession — Renvoie le nom de la session

# Classe DocResult

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\DocResult implements mysql_xdevapi\BaseResult, Traversable {
/* Méthodes */
public function fetchAll(): array
public function fetchOne(): array
public function getWarnings(): Array
public function getWarningsCount(): int
}

# DocResult::__construct

(No version information available, might only be in Git)

DocResult::__construct — Constructeur de DocResult

### Description

private function mysql_xdevapi\DocResult::__construct()

Récupère les résultats et les avertissements du document, et est instancié par CollectionFind.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de DocResult

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Rend un objet DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# DocResult::fetchAll

(No version information available, might only be in Git)

DocResult::fetchAll — Renvoie toutes les lignes

### Description

public function mysql_xdevapi\DocResult::fetchAll(): array

Renvoie toutes les lignes d'un jeu de résultats.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau numérique avec tous les résultats de la requête ; chaque résultat est un tableau associatif. Un tableau vide est renvoyé si aucune ligne n'est présente.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\DocResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Rend un objet DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(2) {

      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000123"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }

      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000122"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }

    }

# DocResult::fetchOne

(No version information available, might only be in Git)

DocResult::fetchOne — Renvoie une ligne

### Description

public function mysql_xdevapi\DocResult::fetchOne(): array

Récupère un résultat d'un jeu de résultats.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le résultat, sous forme de tableau associatif ou `null` si aucun résultat n'est présent.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\DocResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Rend un objet DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchOne());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000125"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

# DocResult::getWarnings

(No version information available, might only be in Git)

DocResult::getWarnings — Renvoie les avertissements de la dernière opération

### Description

public function mysql_xdevapi\DocResult::getWarnings(): Array

Récupère les avertissements générés par la dernière opération du serveur MySQL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau d'objets Warning de la dernière opération. Chaque objet définit un 'message' d'erreur, un 'niveau' d'erreur et un 'code' d'erreur. Un tableau vide est renvoyé si aucune erreur n'est présente.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\DocResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Rend un objet DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "There was an error:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    There was an error:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Something bad and so on
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Something bad and so on
                [level] => 2
                [code] => 1365
            )
    )

# DocResult::getWarningsCount

(No version information available, might only be in Git)

DocResult::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération

### Description

public function mysql_xdevapi\DocResult::getWarningsCount(): int

Renvoie le nombre d'avertissements générés par la dernière opération. Plus précisément, ces avertissements sont générés par le serveur MySQL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre d'avertissements de la dernière opération.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\DocResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Rend un objet DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "There was an error:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000135"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

## Sommaire

- DocResult::__construct — Constructeur de DocResult
- DocResult::fetchAll — Renvoie toutes les lignes
- DocResult::fetchOne — Renvoie une ligne
- DocResult::getWarnings — Renvoie les avertissements de la dernière opération
- DocResult::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération

# Classe Exception

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\Exception extends RuntimeException implements Throwable {
}

# Interface Executable

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\Executable {
/* Méthodes */
abstract public function execute(): mysql_xdevapi\Result
}

# Executable::execute

(No version information available, might only be in Git)

Executable::execute — Exécute une déclaration

### Description

abstract public function mysql_xdevapi\Executable::execute(): mysql_xdevapi\Result

Exécute la déclaration à partir d'une opération de collection ou d'une requête de table; cette fonctionnalité permet le chaînage de méthodes.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un des objets Result, tels que Result ou SqlStatementResult.

### Exemples

Exemple #1 execute() examples

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $result_sql = $session->sql("CREATE DATABASE addressbook")->execute();

    var_dump($result_sql);

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("humans");

    $result_collection = $collection->add(
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}');

    $result_collection_executed = $result_collection->execute();

    var_dump($result_collection);
    var_dump($result_collection_executed);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(mysql_xdevapi\SqlStatementResult)#3 (0) {
    }

    object(mysql_xdevapi\CollectionAdd)#5 (0) {
    }

    object(mysql_xdevapi\Result)#7 (0) {
    }

## Sommaire

- Executable::execute — Exécute une déclaration

# Classe ExecutionStatus

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\ExecutionStatus {
/* Propriétés */
public $affectedItems;
public $matchedItems;
public $foundItems;
public $lastInsertId;
public $lastDocumentId;
/* Constructor */
private function __construct()
}

## Propriétés

affectedItems

matchedItems

foundItems

lastInsertId

lastDocumentId

# ExecutionStatus::__construct

(No version information available, might only be in Git)

ExecutionStatus::__construct — Constructeur d'ExecutionStatus

### Description

private function mysql_xdevapi\ExecutionStatus::__construct()

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\ExecutionStatus::__construct()

    <?php

    /* ... */

    ?>

## Sommaire

- ExecutionStatus::__construct — Constructeur d'ExecutionStatus

# Classe Expression

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\Expression {
/* Propriétés */
public $name;
/* Constructor */
public function __construct(string `$expression`)
}

## Propriétés

name

# Expression::__construct

(No version information available, might only be in Git)

Expression::__construct — Constructeur d'Expression

### Description

public function mysql_xdevapi\Expression::__construct(string `$expression`)

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`expression`

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Expression::__construct()

    <?php

    /* ... */

    ?>

## Sommaire

- Expression::__construct — Constructeur d'Expression

# Classe Result

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\Result implements mysql_xdevapi\BaseResult, Traversable {
/* Méthodes */
public function getAffectedItemsCount(): int
public function getAutoIncrementValue(): int
public function getGeneratedIds(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# Result::__construct

(No version information available, might only be in Git)

Result::__construct — Constructeur de Result

### Description

private function mysql_xdevapi\Result::__construct()

Un objet qui récupère les ID générés, les valeurs AUTO_INCREMENT et les avertissements, pour un jeu de résultats.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Result::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

L'exemple ci-dessus va afficher :

    int(3)

# Result::getAffectedItemsCount

(No version information available, might only be in Git)

Result::getAffectedItemsCount — Renvoie le nombre de lignes affectées

### Description

public function mysql_xdevapi\Result::getAffectedItemsCount(): int

Renvoie le nombre de lignes affectées par l'opération précédente.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre (en tant qu'entier) de lignes affectées.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Result::getAffectedItemsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    var_dump( $res->getAffectedItemsCount() );
    ?>

L'exemple ci-dessus va afficher :

    int(1)

# Result::getAutoIncrementValue

(No version information available, might only be in Git)

Result::getAutoIncrementValue — Renvoie la valeur auto-incrémentée

### Description

public function mysql_xdevapi\Result::getAutoIncrementValue(): int

Renvoie la dernière valeur AUTO_INCREMENT (dernier identifiant inséré).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La dernière valeur AUTO_INCREMENT.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Result::getAutoIncrementValue()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

L'exemple ci-dessus va afficher :

    int(3)

# Result::getGeneratedIds

(No version information available, might only be in Git)

Result::getGeneratedIds — Renvoie les ID générés

### Description

public function mysql_xdevapi\Result::getGeneratedIds(): array

Récupère les valeurs _id générées par la dernière opération. Le champ _id unique est généré par le serveur MySQL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau d'_id générés par la dernière opération, ou un tableau vide s'il n'y en a pas.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Result::getGeneratedIds()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    $ids = $result->getGeneratedIds();
    var_dump($ids);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(2) {
      [0]=>
      string(28) "00005b6b53610000000000000064"
      [1]=>
      string(28) "00005b6b53610000000000000065"
    }

# Result::getWarnings

(No version information available, might only be in Git)

Result::getWarnings — Renvoie les avertissements de la dernière opération

### Description

public function mysql_xdevapi\Result::getWarnings(): array

Renvoie les avertissements de la dernière opération Result.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau d'objets Warning de la dernière opération. Chaque objet définit un message d'erreur, un niveau d'erreur et un code d'erreur. Un tableau vide est renvoyé s'il n'y a pas d'erreurs.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# Result::getWarningsCount

(No version information available, might only be in Git)

Result::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération

### Description

public function mysql_xdevapi\Result::getWarningsCount(): int

Renvoie le nombre d'avertissements générés par la dernière opération.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre d'avertissements générés par la dernière opération.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    2

## Sommaire

- Result::__construct — Constructeur de Result
- Result::getAffectedItemsCount — Renvoie le nombre de lignes affectées
- Result::getAutoIncrementValue — Renvoie la valeur auto-incrémentée
- Result::getGeneratedIds — Renvoie les ID générés
- Result::getWarnings — Renvoie les avertissements de la dernière opération
- Result::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération

# Classe RowResult

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\RowResult implements mysql_xdevapi\BaseResult, Traversable {
/* Méthodes */
public function fetchAll(): array
public function fetchOne(): array
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# RowResult::__construct

(No version information available, might only be in Git)

RowResult::__construct — Constructeur de RowResult

### Description

private function mysql_xdevapi\RowResult::__construct()

Représente l'ensemble de résultats obtenus à partir de la requête de la base de données.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age > 18')->execute()->fetchAll();

    print_r($row);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchAll

(No version information available, might only be in Git)

RowResult::fetchAll — Renvoie toutes les lignes du résultat

### Description

public function mysql_xdevapi\RowResult::fetchAll(): array

Récupère toutes les lignes du jeu de résultats.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau numérique avec tous les résultats de la requête; chaque résultat est un tableau associatif. Un tableau vide est renvoyé si aucune ligne n'est présente.

### Exemples

Exemple #1 mysql_xdevapi\RowResult::fetchAll() example

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchOne

(No version information available, might only be in Git)

RowResult::fetchOne — Renvoie une ligne du résultat

### Description

public function mysql_xdevapi\RowResult::fetchOne(): array

Récupère une ligne du jeu de résultats.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le résultat, sous forme de tableau associatif ou `null` si aucun résultat n'est présent.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age < 40')->execute()->fetchOne();

    print_r($row);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [name] => Sam
        [age] => 33
    )

# RowResult::getColumnsCount

(No version information available, might only be in Git)

RowResult::getColumnsCount — Renvoie le nombre de colonnes

### Description

public function mysql_xdevapi\RowResult::getColumnsCount(): int

Renvoie le nombre de colonnes présentes dans le jeu de résultats.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre de colonnes; 0 s'il n'y en a pas.

### Historique

Version | Description
--- | ---
8.0.14 | La méthode a été renommée de getColumnCount() à getColumnsCount().

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::getColumnsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    echo $sql->getColumnsCount();

Résultat de l'exemple ci-dessus est similaire à :

    2

# RowResult::getColumnNames

(No version information available, might only be in Git)

RowResult::getColumnNames — Renvoie le nom de toutes les colonnes

### Description

public function mysql_xdevapi\RowResult::getColumnNames(): array

Renvoie le nom des colonnes présentes dans le jeu de résultats.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau numérique de noms de colonnes de table, ou un tableau vide si le jeu de résultats est vide.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::getColumnNames()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $colnames = $sql->getColumnNames();

    print_r($colnames);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => name
        [1] => age
    )

# RowResult::getColumns

(No version information available, might only be in Git)

RowResult::getColumns — Renvoie les métadonnées des colonnes

### Description

public function mysql_xdevapi\RowResult::getColumns(): array

Renvoie les métadonnées des colonnes présentes dans le jeu de résultats.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de FieldMetadata représentant les colonnes du résultat, ou un tableau vide si le jeu de résultats est vide.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::getColumns()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $cols = $sql->getColumns();

    print_r($cols);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 7
                [type_name] => BYTES
                [name] => name
                [original_name] => name
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 255
                [fractional_digits] => 0
                [length] => 65535
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => age
                [original_name] => age
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
    )

# RowResult::getWarnings

(No version information available, might only be in Git)

RowResult::getWarnings — Renvoie les avertissements de la dernière opération

### Description

public function mysql_xdevapi\RowResult::getWarnings(): array

Renvoie les avertissements de la dernière opération RowResult.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau d'objets Warning de la dernière opération. Chaque objet définit un message d'erreur 'message', un niveau d'erreur 'level', et un code d'erreur 'code'. Un tableau vide est renvoyé si aucune erreur n'est présente.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# RowResult::getWarningsCount

(No version information available, might only be in Git)

RowResult::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération

### Description

public function mysql_xdevapi\RowResult::getWarningsCount(): int

Renvoie le nombre d'avertissements générés par la dernière opération.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre d'avertissements générés par la dernière opération.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    2

## Sommaire

- RowResult::__construct — Constructeur de RowResult
- RowResult::fetchAll — Renvoie toutes les lignes du résultat
- RowResult::fetchOne — Renvoie une ligne du résultat
- RowResult::getColumnsCount — Renvoie le nombre de colonnes
- RowResult::getColumnNames — Renvoie le nom de toutes les colonnes
- RowResult::getColumns — Renvoie les métadonnées des colonnes
- RowResult::getWarnings — Renvoie les avertissements de la dernière opération
- RowResult::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération

# Classe Schema

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\Schema implements mysql_xdevapi\DatabaseObject {
/* Propriétés */
public $name;
/* Méthodes */
public function createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection
public function dropCollection(string `$collection_name`): bool
public function existsInDatabase(): bool
public function getCollection(string `$name`): mysql_xdevapi\Collection
public function getCollectionAsTable(string `$name`): mysql_xdevapi\Table
public function getCollections(): array
public function getName(): string
public function getSession(): mysql_xdevapi\Session
public function getTable(string `$name`): mysql_xdevapi\Table
public function getTables(): array
}

## Propriétés

name

# Schema::__construct

(No version information available, might only be in Git)

Schema::__construct — Constructeur de schema

### Description

private function mysql_xdevapi\Schema::__construct()

L'objet Schema fournit un accès complet au schéma (base de données).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

# Schema::createCollection

(No version information available, might only be in Git)

Schema::createCollection — Ajoute une collection au schéma

### Description

public function mysql_xdevapi\Schema::createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection

Créer une collection dans le schéma.

### Liste de paramètres

`name`

  Le nom de la collection.

`validate`

  La définition de validation, en tant qu'objet JSON.

### Valeurs de retour

L'objet Collection.

### Historique

Version | Description
--- | ---
8.0.20 | Ajout du paramètre facultatif validate.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::createCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

Exemple #2 Exemple de mysql_xdevapi\Schema::createCollection()

    <?php
     $collection = $schema->createCollection("mycollection", '{
        "validation": {
            "level": "strict",
            "schema": {
                "id": "http://json-schema.org/geo",
                "description": "A geographical coordinate",
                "type": "object",
                "properties": {
                    "latitude": {
                        "type": "number"
                    },
                    "longitude": {
                        "type": "number"
                    }
                },
                "required": ["latitude", "longitude"]
            }
        }
    }');
    // Succès
    $collection->add('{"latitude": 10, "longitude": 20}')->execute();

    // Échec, types invalides (pas des nombres)
    $collection->add('{"latitude": "lat", "longitude": "long"}')->execute();

# Schema::dropCollection

(No version information available, might only be in Git)

Schema::dropCollection — Supprime une collection du schéma

### Description

public function mysql_xdevapi\Schema::dropCollection(string `$collection_name`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`collection_name`

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::dropCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");

    $schema->createCollection("trees");
    $schema->dropCollection("trees");
    $schema->createCollection("buildings");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [buildings] => mysql_xdevapi\Collection Object
            (
                [name] => buildings
            )
    )

# Schema::existsInDatabase

(No version information available, might only be in Git)

Schema::existsInDatabase — Vérifie si l'objet existe dans la base de données

### Description

public function mysql_xdevapi\Schema::existsInDatabase(): bool

Vérifie si l'objet actuel (schéma, table, collection ou vue) existe dans l'objet schéma.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si le schéma, la table, la collection ou la vue existe toujours dans le schéma, sinon `false`.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    // ...

    // Cette collection est-elle toujours dans la base de données (schéma) ?
    if ($trees->existsInDatabase()) {
        echo "Yes, the 'trees' collection is still present.";
    }

Résultat de l'exemple ci-dessus est similaire à :

    Yes, the 'trees' collection is still present.

# Schema::getCollection

(No version information available, might only be in Git)

Schema::getCollection — Renvoie une collection du schéma

### Description

public function mysql_xdevapi\Schema::getCollection(string `$name`): mysql_xdevapi\Collection

Renvoie une collection du schéma.

### Liste de paramètres

`name`

  Le nom de la collection à récupérer.

### Valeurs de retour

L'objet Collection pour la collection sélectionnée.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::getCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    var_dump($trees);

Résultat de l'exemple ci-dessus est similaire à :

    object(mysql_xdevapi\Collection)#3 (1) {
      ["name"]=>
      string(5) "trees"
    }

# Schema::getCollectionAsTable

(No version information available, might only be in Git)

Schema::getCollectionAsTable — Renvoie une collection en tant qu'objet Table

### Description

public function mysql_xdevapi\Schema::getCollectionAsTable(string `$name`): mysql_xdevapi\Table

Renvoie une collection, mais en tant qu'objet Table au lieu d'un objet Collection.

### Liste de paramètres

`name`

  Le nom de la collection à partir de laquelle instancier un objet Table.

### Valeurs de retour

Un objet mysql_xdevapi\Table pour la collection.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::getCollectionAsTable()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $table      = $schema->getCollectionAsTable("people");
    $collection = $schema->getCollection("people");

    var_dump($table);
    var_dump($collection);

Résultat de l'exemple ci-dessus est similaire à :

    object(mysql_xdevapi\Table)#4 (1) {
      ["name"]=>
      string(6) "people"
    }

    object(mysql_xdevapi\Collection)#5 (1) {
      ["name"]=>
      string(6) "people"
    }

# Schema::getCollections

(No version information available, might only be in Git)

Schema::getCollections — Renvoie toutes les collections du schéma

### Description

public function mysql_xdevapi\Schema::getCollections(): array

Récupère une liste de collections pour ce schéma.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de toutes les collections de ce schéma, où chaque élément de tableau est une Collection avec le nom de la collection comme clé.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::getCollections()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $collections = $schema->getCollections();
    var_dump($collections);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      ["people"]=>
      object(mysql_xdevapi\Collection)#4 (1) {
        ["name"]=>
        string(6) "people"
      }
    }

# Schema::getName

(No version information available, might only be in Git)

Schema::getName — Renvoie le nom du schéma

### Description

public function mysql_xdevapi\Schema::getName(): string

Renvoie le nom du schéma.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nom du schéma connecté à l'objet schéma, sous forme de chaîne de caractères.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    var_dump($schema->getName());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(11) "addressbook"

# Schema::getSession

(No version information available, might only be in Git)

Schema::getSession — Renvoie la session du schéma

### Description

public function mysql_xdevapi\Schema::getSession(): mysql_xdevapi\Session

Renvoie un nouvel objet Session à partir de l'objet Schema.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet Session.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    $newsession = $schema->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(mysql_xdevapi\Session)#1 (0) {
    }

    object(mysql_xdevapi\Session)#3 (0) {
    }

# Schema::getTable

(No version information available, might only be in Git)

Schema::getTable — Renvoie la table du schéma

### Description

public function mysql_xdevapi\Schema::getTable(string `$name`): mysql_xdevapi\Table

Récupère un objet Table pour la table fournie dans le schéma.

### Liste de paramètres

`name`

  Le nom de la table.

### Valeurs de retour

Un objet table.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::getTable()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Schema::getTables

(No version information available, might only be in Git)

Schema::getTables — Renvoie les tables du schéma

### Description

public function mysql_xdevapi\Schema::getTables(): array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau de toutes les tables de ce schéma, où chaque élément de tableau est un objet Table avec le nom de la table comme clé.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Schema::getTables()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $session->sql("CREATE TABLE addressbook.cities(name text, population int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Portland', 639863), ('Seattle', 704352)")->execute();

    $schema = $session->getSchema("addressbook");
    $tables = $schema->getTables();

    var_dump($tables);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(2) {
      ["cities"]=>
      object(mysql_xdevapi\Table)#3 (1) {
        ["name"]=>
        string(6) "cities"
      }

      ["names"]=>
      object(mysql_xdevapi\Table)#4 (1) {
        ["name"]=>
        string(5) "names"
      }
    }

## Sommaire

- Schema::__construct — Constructeur de schema
- Schema::createCollection — Ajoute une collection au schéma
- Schema::dropCollection — Supprime une collection du schéma
- Schema::existsInDatabase — Vérifie si l'objet existe dans la base de données
- Schema::getCollection — Renvoie une collection du schéma
- Schema::getCollectionAsTable — Renvoie une collection en tant qu'objet Table
- Schema::getCollections — Renvoie toutes les collections du schéma
- Schema::getName — Renvoie le nom du schéma
- Schema::getSession — Renvoie la session du schéma
- Schema::getTable — Renvoie la table du schéma
- Schema::getTables — Renvoie les tables du schéma

# Interface SchemaObject

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\SchemaObject implements mysql_xdevapi\DatabaseObject {
/* Méthodes */
abstract function getSchema(): mysql_xdevapi\Schema
}

# SchemaObject::getSchema

(No version information available, might only be in Git)

SchemaObject::getSchema — Renvoie l'objet schéma

### Description

abstract function mysql_xdevapi\SchemaObject::getSchema(): mysql_xdevapi\Schema

Utiliser par d'autres objets pour récupérer un objet schéma.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet schéma actuel.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

Résultat de l'exemple ci-dessus est similaire à :

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

## Sommaire

- SchemaObject::getSchema — Renvoie l'objet schéma

# Classe Session

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\Session {
/* Méthodes */
public function close(): bool
public function commit(): Object
public function createSchema(string `$schema_name`): mysql_xdevapi\Schema
public function dropSchema(string `$schema_name`): bool
public function generateUUID(): string
public function getDefaultSchema(): ?mysql_xdevapi\Schema
public function getSchema(string `$schema_name`): mysql_xdevapi\Schema
public function getSchemas(): array
public function getServerVersion(): int
public function listClients(): array
public function quoteName(string `$name`): string
public function releaseSavepoint(string `$name`): void
public function rollback(): void
public function rollbackTo(string `$name`): void
public function setSavepoint(string `$name` = ?): string
public function sql(string `$query`): mysql_xdevapi\SqlStatement
public function startTransaction(): void
}

# Session::close

(No version information available, might only be in Git)

Session::close — Ferme la session

### Description

public function mysql_xdevapi\Session::close(): bool

Ferme la session avec le serveur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si la session a été fermée.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::close()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->close();

# Session::commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

Session::commit — Valide la transaction

### Description

public function mysql_xdevapi\Session::commit(): Object

Valide la transaction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet SqlStatementResult.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::commit()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();

    $collection->add('{"John":42, "Sam":33}')->execute();
    $savepoint = $session->setSavepoint();

    $session->commit();
    $session->close();

# Session::__construct

(No version information available, might only be in Git)

Session::__construct — Description du constructeur

### Description

private function mysql_xdevapi\Session::__construct()

Un objet Session, tel qu'initié par getSession().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->close();
    ?>

# Session::createSchema

(No version information available, might only be in Git)

Session::createSchema — Créer un nouveau schéma

### Description

public function mysql_xdevapi\Session::createSchema(string `$schema_name`): mysql_xdevapi\Schema

Créer un nouveau schéma.

### Liste de paramètres

`schema_name`

  Le nom du schéma à créer.

### Valeurs de retour

Un objet Schema en cas de succès, et émet une exception en cas d'échec.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::createSchema()

    <?php
    $uri  = 'mysqlx://happyuser:password@127.0.0.1:33060/';
    $sess = mysql_xdevapi\getSession($uri);

    try {

        if ($schema = $sess->createSchema('fruit')) {
            echo "Info: I created a schema named 'fruit'\n";
        }

    } catch (Exception $e) {

       echo $e->getMessage();

    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Info: I created a schema named 'fruit'

# Session::dropSchema

(No version information available, might only be in Git)

Session::dropSchema — Supprime un schéma

### Description

public function mysql_xdevapi\Session::dropSchema(string `$schema_name`): bool

Supprime un schéma (base de données).

### Liste de paramètres

`schema_name`

  Le nom du schéma à supprimer.

### Valeurs de retour

`true` si le schéma est supprimé, ou `false` s'il n'existe pas ou ne peut pas être supprimé.

Un niveau d'erreur `E_WARNING` est généré si le schéma n'existe pas.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::dropSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->dropSchema("addressbook");

    $session->close();
    ?>

# Session::generateUUID

(No version information available, might only be in Git)

Session::generateUUID — Renvoie un nouvel UUID

### Description

public function mysql_xdevapi\Session::generateUUID(): string

Génère un identifiant unique universel (Universal Unique IDentifier - UUID) généré selon la » RFC 4122.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'UUID; une chaîne de 32 caractères.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::generateUuid()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $uuid = $session->generateUuid();

    var_dump($uuid);

Résultat de l'exemple ci-dessus est similaire à :

    string(32) "484B18AC7980F8D4FE84613CDA5EE84B"

# Session::getDefaultSchema

(No version information available, might only be in Git)

Session::getDefaultSchema — Renvoie le nom du schéma par défaut

### Description

public function mysql_xdevapi\Session::getDefaultSchema(): ?mysql_xdevapi\Schema

Renvoie le nom du schéma par défaut tel qu'il est généralement défini dans l'URI de connexion.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nom du schéma par défaut défini par la connexion, ou `null` si aucun n'a été défini.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::getSchema()

    <?php
    $uri = "mysqlx://testuser:testpasswd@localhost:33160/testx?ssl-mode=disabled";
    $session = mysql_xdevapi\getSession($uri);

    $schema = $session->getDefaultSchema();
    echo $schema->getName();
    ?>

L'exemple ci-dessus va afficher :

    testx

# Session::getSchema

(No version information available, might only be in Git)

Session::getSchema — Renvoie un nouvel objet schéma

### Description

public function mysql_xdevapi\Session::getSchema(string `$schema_name`): mysql_xdevapi\Schema

Un nouvel objet Schema pour le nom de schéma fourni.

### Liste de paramètres

`schema_name`

  Le nom du schéma (base de données) pour lequel obtenir un objet Schema.

### Valeurs de retour

Un objet Schema.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

Résultat de l'exemple ci-dessus est similaire à :

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

# Session::getSchemas

(No version information available, might only be in Git)

Session::getSchemas — Renvoie les schémas

### Description

public function mysql_xdevapi\Session::getSchemas(): array

Obtient les objets schémas pour tous les schémas disponibles pour la session.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau contenant des objets qui représentent tous les schémas disponibles pour la session.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::getSchemas()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schemas  = $session->getSchemas();

    print_r($schemas);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => addressbook
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        ...

# Session::getServerVersion

(No version information available, might only be in Git)

Session::getServerVersion — Renvoie la version du serveur

### Description

public function mysql_xdevapi\Session::getServerVersion(): int

Renvoie la version du serveur MySQL pour la session.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La version du serveur MySQL pour la session, sous forme d'entier tel que "80012".

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::getServerVersion()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $version = $session->getServerVersion();

    var_dump($version);

Résultat de l'exemple ci-dessus est similaire à :

    int(80012)

# Session::listClients

(No version information available, might only be in Git)

Session::listClients — Renvoie la liste des clients

### Description

public function mysql_xdevapi\Session::listClients(): array

Renvoie la liste des connexions client au serveur MySQL de la session.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau contenant les clients actuellement connectés. Les éléments du tableau sont "client_id", "user", "host" et "sql_session".

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::listClients()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $ids = $session->listClients();

    var_dump($ids);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(1) {
      [0]=>
      array(4) {
        ["client_id"]=>
        int(61)
        ["user"]=>
        string(4) "root"
        ["host"]=>
        string(9) "localhost"
        ["sql_session"]=>
        int(72)
      }
    }

# Session::quoteName

(No version information available, might only be in Git)

Session::quoteName — Ajoute des guillemets

### Description

public function mysql_xdevapi\Session::quoteName(string `$name`): string

Une fonction qui met entre guillemets pour échapper les noms et identifiants SQL. Elle échappe l'identifiant donné conformément aux paramètres de la connexion actuelle. Cette fonction d'échappement ne doit pas être utilisée pour échapper des valeurs.

### Liste de paramètres

`name`

  La chaîne à mettre entre guillemets.

### Valeurs de retour

La chaîne mise entre guillemets.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::quoteName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $first = "MySQL's test";
    var_dump($first);
    var_dump($session->quoteName($first));

    $second = 'Another `test` "like" `this`';
    var_dump($second);
    var_dump($session->quoteName($second));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(12) "MySQL's test"
    string(14) "`MySQL's test`"

    string(28) "Another `test` "like" `this`"
    string(34) "`Another ``test`` "like" ``this```"

# Session::releaseSavepoint

(No version information available, might only be in Git)

Session::releaseSavepoint — Libère le point de sauvegarde

### Description

public function mysql_xdevapi\Session::releaseSavepoint(string `$name`): void

Libère un point de sauvegarde précédemment défini.

### Liste de paramètres

`name`

  Le nom du point de sauvegarde à libérer.

### Valeurs de retour

Un objet SqlStatementResult.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::releaseSavepoint()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollback

(No version information available, might only be in Git)

Session::rollback — Annule la transaction

### Description

public function mysql_xdevapi\Session::rollback(): void

Annule la transaction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet SqlStatementResult.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::rollback()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollbackTo

(No version information available, might only be in Git)

Session::rollbackTo — Annule la transaction jusqu'au point de sauvegarde

### Description

public function mysql_xdevapi\Session::rollbackTo(string `$name`): void

Annule la transaction jusqu'au point de sauvegarde.

### Liste de paramètres

`name`

  Le nom du point de sauvegarde jusqu'auquel annuler; insensible à la casse.

### Valeurs de retour

Un objet SqlStatementResult.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::rollbackTo()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint1 = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $savepoint2 = $session->setSavepoint();

    $session->rollbackTo($savepoint1);
    ?>

# Session::setSavepoint

(No version information available, might only be in Git)

Session::setSavepoint — Créer un point de sauvegarde

### Description

public function mysql_xdevapi\Session::setSavepoint(string `$name` = ?): string

Créer un nouveau point de sauvegarde pour la transaction.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`name`

  Le nom du point de sauvegarde. Le nom est généré automatiquement si le paramètre optionnel `name` n'est pas défini comme 'SAVEPOINT1', 'SAVEPOINT2', etc.

### Valeurs de retour

Le nom du point de sauvegarde.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::setSavepoint()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::sql

(No version information available, might only be in Git)

Session::sql — Créer une requête SQL

### Description

public function mysql_xdevapi\Session::sql(string `$query`): mysql_xdevapi\SqlStatement

Créer une déclaration SQL native. Les espaces réservés sont pris en charge en utilisant la syntaxe native "?". Utiliser la méthode `execute` pour exécuter la déclaration SQL.

### Liste de paramètres

`query`

  La déclaration SQL à exécuter.

### Valeurs de retour

Un objet SqlStatement.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::sql()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE addressbook")->execute();
    ?>

# Session::startTransaction

(No version information available, might only be in Git)

Session::startTransaction — Démarre une transaction

### Description

public function mysql_xdevapi\Session::startTransaction(): void

Démarre une nouvelle transaction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet SqlStatementResult.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Session::startTransaction()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

## Sommaire

- Session::close — Ferme la session
- Session::commit — Valide la transaction
- Session::__construct — Description du constructeur
- Session::createSchema — Créer un nouveau schéma
- Session::dropSchema — Supprime un schéma
- Session::generateUUID — Renvoie un nouvel UUID
- Session::getDefaultSchema — Renvoie le nom du schéma par défaut
- Session::getSchema — Renvoie un nouvel objet schéma
- Session::getSchemas — Renvoie les schémas
- Session::getServerVersion — Renvoie la version du serveur
- Session::listClients — Renvoie la liste des clients
- Session::quoteName — Ajoute des guillemets
- Session::releaseSavepoint — Libère le point de sauvegarde
- Session::rollback — Annule la transaction
- Session::rollbackTo — Annule la transaction jusqu'au point de sauvegarde
- Session::setSavepoint — Créer un point de sauvegarde
- Session::sql — Créer une requête SQL
- Session::startTransaction — Démarre une transaction

# Classe SqlStatement

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\SqlStatement {
/* Constantes */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Propriétés */
public $statement;
/* Méthodes */
public function bind(string `$param`): mysql_xdevapi\SqlStatement
public function execute(): mysql_xdevapi\Result
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Propriétés

statement

## Constantes pré-définies

`mysql_xdevapi\SqlStatement::EXECUTE_ASYNC`

`mysql_xdevapi\SqlStatement::BUFFERED`

# SqlStatement::bind

(No version information available, might only be in Git)

SqlStatement::bind — Lie les paramètres de l'instruction

### Description

public function mysql_xdevapi\SqlStatement::bind(string `$param`): mysql_xdevapi\SqlStatement

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`param`

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatement::bind()

    <?php

    /* ... */

    ?>

# SqlStatement::__construct

(No version information available, might only be in Git)

SqlStatement::__construct — Description de constructeur

### Description

private function mysql_xdevapi\SqlStatement::__construct()

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatement::__construct()

    <?php

    /* ... */

    ?>

# SqlStatement::execute

(No version information available, might only be in Git)

SqlStatement::execute — Exécute l'opération

### Description

public function mysql_xdevapi\SqlStatement::execute(): mysql_xdevapi\Result

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatement::execute()

    <?php

    /* ... */

    ?>

# SqlStatement::getNextResult

(No version information available, might only be in Git)

SqlStatement::getNextResult — Renvoie le résultat suivant

### Description

public function mysql_xdevapi\SqlStatement::getNextResult(): mysql_xdevapi\Result

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatement::getNextResult()

    <?php

    /* ... */

    ?>

# SqlStatement::getResult

(No version information available, might only be in Git)

SqlStatement::getResult — Renvoie le résultat

### Description

public function mysql_xdevapi\SqlStatement::getResult(): mysql_xdevapi\Result

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatement::getResult()

    <?php

    /* ... */

    ?>

# SqlStatement::hasMoreResults

(No version information available, might only be in Git)

SqlStatement::hasMoreResults — Vérifie s'il y a plus de résultats

### Description

public function mysql_xdevapi\SqlStatement::hasMoreResults(): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` s'il reste des objets à récupérer dans le jeu de résultats.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatement::hasMoreResults()

    <?php

    /* ... */

    ?>

## Sommaire

- SqlStatement::bind — Lie les paramètres de l'instruction
- SqlStatement::__construct — Description de constructeur
- SqlStatement::execute — Exécute l'opération
- SqlStatement::getNextResult — Renvoie le résultat suivant
- SqlStatement::getResult — Renvoie le résultat
- SqlStatement::hasMoreResults — Vérifie s'il y a plus de résultats

# Classe SqlStatementResult

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\SqlStatementResult implements mysql_xdevapi\BaseResult, Traversable {
/* Méthodes */
public function fetchAll(): array
public function fetchOne(): array
public function getAffectedItemsCount(): int
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): Array
public function getGeneratedIds(): array
public function getLastInsertId(): String
public function getWarnings(): array
public function getWarningCounts(): int
public function hasData(): bool
public function nextResult(): mysql_xdevapi\Result
}

# SqlStatementResult::__construct

(No version information available, might only be in Git)

SqlStatementResult::__construct — Description de constructeur

### Description

private function mysql_xdevapi\SqlStatementResult::__construct()

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::__construct()

    <?php

    /* ... */

    ?>

# SqlStatementResult::fetchAll

(No version information available, might only be in Git)

SqlStatementResult::fetchAll — Renvoie toutes les lignes du résultat

### Description

public function mysql_xdevapi\SqlStatementResult::fetchAll(): array

Récupère toutes les lignes du jeu de résultats.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau numérique avec tous les résultats de la requête; chaque résultat est un tableau associatif. Un tableau vide est renvoyé si aucune ligne n'est présente.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchAll();

    print_r($rows);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# SqlStatementResult::fetchOne

(No version information available, might only be in Git)

SqlStatementResult::fetchOne — Renvoie une seule ligne

### Description

public function mysql_xdevapi\SqlStatementResult::fetchOne(): array

Récupère une seule ligne du jeu de résultats.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le résultat, sous forme de tableau associatif. En cas d'absence de résultat, null sera renvoyé.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchOne();

    print_r($rows);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [name] => John
        [age] => 42
        [job] => bricklayer
    )

# SqlStatementResult::getAffectedItemsCount

(No version information available, might only be in Git)

SqlStatementResult::getAffectedItemsCount — Renvoie le nombre de lignes affectées

### Description

public function mysql_xdevapi\SqlStatementResult::getAffectedItemsCount(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::getAffectedItemsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnsCount

(No version information available, might only be in Git)

SqlStatementResult::getColumnsCount — Renvoie le nombre de colonnes

### Description

public function mysql_xdevapi\SqlStatementResult::getColumnsCount(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre de colonnes; 0 s'il n'y en a pas.

### Historique

Version | Description
--- | ---
8.0.14 | La méthode a été renommée de getColumnCount() en getColumnsCount().

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::getColumnsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnNames

(No version information available, might only be in Git)

SqlStatementResult::getColumnNames — Renvoie le nom des colonnes

### Description

public function mysql_xdevapi\SqlStatementResult::getColumnNames(): array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::getColumnNames()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumns

(No version information available, might only be in Git)

SqlStatementResult::getColumns — Renvoie les colonnes

### Description

public function mysql_xdevapi\SqlStatementResult::getColumns(): Array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::getColumns()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getGeneratedIds

(No version information available, might only be in Git)

SqlStatementResult::getGeneratedIds — Renvoie les identifiants générés

### Description

public function mysql_xdevapi\SqlStatementResult::getGeneratedIds(): array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau d'identifiants générés à partir de la dernière opération, ou un tableau vide s'il n'y en a pas.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::getGeneratedIds()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getLastInsertId

(No version information available, might only be in Git)

SqlStatementResult::getLastInsertId — Renvoie l'ID de la dernière insertion

### Description

public function mysql_xdevapi\SqlStatementResult::getLastInsertId(): String

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'ID de la dernière opération d'insertion.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::getLastInsertId()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarnings

(No version information available, might only be in Git)

SqlStatementResult::getWarnings — Renvoie les avertissements de la dernière opération

### Description

public function mysql_xdevapi\SqlStatementResult::getWarnings(): array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau d'objets Warning de la dernière opération. Chaque objet définit un 'message' d'erreur, un 'niveau' d'erreur et un 'code' d'erreur. Un tableau vide est renvoyé s'il n'y a pas d'erreurs.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::getWarnings()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarningsCount

(No version information available, might only be in Git)

SqlStatementResult::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération

### Description

public function mysql_xdevapi\SqlStatementResult::getWarningCounts(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre d'avertissements générés lors de la dernière opération CRUD.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::getWarningsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::hasData

(No version information available, might only be in Git)

SqlStatementResult::hasData — Vérifie si le résultat contient des données

### Description

public function mysql_xdevapi\SqlStatementResult::hasData(): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si le résultat contient des données.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::hasData()

    <?php

    /* ... */

    ?>

# SqlStatementResult::nextResult

(No version information available, might only be in Git)

SqlStatementResult::nextResult — Renvoie le résultat suivant

### Description

public function mysql_xdevapi\SqlStatementResult::nextResult(): mysql_xdevapi\Result

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Result suivant du jeu de résultats.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\SqlStatementResult::nextResult()

    <?php

    /* ... */

    ?>

## Sommaire

- SqlStatementResult::__construct — Description de constructeur
- SqlStatementResult::fetchAll — Renvoie toutes les lignes du résultat
- SqlStatementResult::fetchOne — Renvoie une seule ligne
- SqlStatementResult::getAffectedItemsCount — Renvoie le nombre de lignes affectées
- SqlStatementResult::getColumnsCount — Renvoie le nombre de colonnes
- SqlStatementResult::getColumnNames — Renvoie le nom des colonnes
- SqlStatementResult::getColumns — Renvoie les colonnes
- SqlStatementResult::getGeneratedIds — Renvoie les identifiants générés
- SqlStatementResult::getLastInsertId — Renvoie l'ID de la dernière insertion
- SqlStatementResult::getWarnings — Renvoie les avertissements de la dernière opération
- SqlStatementResult::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération
- SqlStatementResult::hasData — Vérifie si le résultat contient des données
- SqlStatementResult::nextResult — Renvoie le résultat suivant

# Classe Statement

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\Statement {
/* Constantes */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Méthodes */
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Constantes pré-définies

`mysql_xdevapi\Statement::EXECUTE_ASYNC`

`mysql_xdevapi\Statement::BUFFERED`

# Statement::__construct

(No version information available, might only be in Git)

Statement::__construct — Description de constructeur

### Description

private function mysql_xdevapi\Statement::__construct()

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Statement::__construct()

    <?php

    /* ... */

    ?>

# Statement::getNextResult

(No version information available, might only be in Git)

Statement::getNextResult — Renvoie le résultat suivant

### Description

public function mysql_xdevapi\Statement::getNextResult(): mysql_xdevapi\Result

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Statement::getNextResult()

    <?php

    /* ... */

    ?>

# Statement::getResult

(No version information available, might only be in Git)

Statement::getResult — Renvoie le résultat

### Description

public function mysql_xdevapi\Statement::getResult(): mysql_xdevapi\Result

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Statement::getResult()

    <?php

    /* ... */

    ?>

# Statement::hasMoreResults

(No version information available, might only be in Git)

Statement::hasMoreResults — Vérifie s'il y a d'autres résultats

### Description

public function mysql_xdevapi\Statement::hasMoreResults(): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Statement::hasMoreResults()

    <?php

    /* ... */

    ?>

## Sommaire

- Statement::__construct — Description de constructeur
- Statement::getNextResult — Renvoie le résultat suivant
- Statement::getResult — Renvoie le résultat
- Statement::hasMoreResults — Vérifie s'il y a d'autres résultats

# Classe Table

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

Fournit un accès à la table à travers des déclarations INSERT/SELECT/UPDATE/DELETE.

## Synopsis de la classe

class mysql_xdevapi\Table implements mysql_xdevapi\SchemaObject {
/* Propriétés */
public $name;
/* Méthodes */
public function count(): int
public function delete(): mysql_xdevapi\TableDelete
public function existsInDatabase(): bool
public function getName(): string
public function getSchema(): mysql_xdevapi\Schema
public function getSession(): mysql_xdevapi\Session
public function insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert
public function isView(): bool
public function select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect
public function update(): mysql_xdevapi\TableUpdate
}

## Propriétés

name

# Table::__construct

(No version information available, might only be in Git)

Table::__construct — Constructeur de Table

### Description

private function mysql_xdevapi\Table::__construct()

Construit un objet table.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");
    ?>

# Table::count

(No version information available, might only be in Git)

Table::count — Renvoie le nombre de lignes

### Description

public function mysql_xdevapi\Table::count(): int

Récupère le nombre de lignes dans la table.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre total de lignes dans la table.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->count());
    ?>

L'exemple ci-dessus va afficher :

    int(2)

# Table::delete

(No version information available, might only be in Git)

Table::delete — Supprime des lignes de la table

### Description

public function mysql_xdevapi\Table::delete(): mysql_xdevapi\TableDelete

Supprime des lignes d'une table.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet TableDelete; utiliser la méthode execute() pour exécuter la requête de suppression.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::delete()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()->where("name = :name")->orderby("age DESC")->limit(1)->bind(['name' => 'John'])->execute();
    ?>

# Table::existsInDatabase

(No version information available, might only be in Git)

Table::existsInDatabase — Vérifie si la table existe dans la base de données

### Description

public function mysql_xdevapi\Table::existsInDatabase(): bool

Vérifie si cette table existe dans la base de données.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie `true` si la table existe dans la base de données, sinon `false` si elle n'existe pas.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->existsInDatabase()) {
      echo "Yes, this table still exists in the session's schema.";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Yes, this table still exists in the session's schema.

# Table::getName

(No version information available, might only be in Git)

Table::getName — Renvoie le nom de la table

### Description

public function mysql_xdevapi\Table::getName(): string

Renvoie le nom de cet objet base de données.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nom de cet objet base de données.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getName());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(5) "names"

# Table::getSchema

(No version information available, might only be in Git)

Table::getSchema — Renvoie le schéma de la table

### Description

public function mysql_xdevapi\Table::getSchema(): mysql_xdevapi\Schema

Récupère le schéma associé à la table.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet Schema.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSchema());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Table::getSession

(No version information available, might only be in Git)

Table::getSession — Renvoie la session de la table

### Description

public function mysql_xdevapi\Table::getSession(): mysql_xdevapi\Session

Obtient la session associée à la table.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet Session.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSession());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(mysql_xdevapi\Session)#9 (0) {
    }

# Table::insert

(No version information available, might only be in Git)

Table::insert — Insère des lignes dans une table

### Description

public function mysql_xdevapi\Table::insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert

Insère des lignes dans une table.

### Liste de paramètres

`columns`

  Les colonnes dans lesquelles insérer les données. Peut être un tableau avec une ou plusieurs valeurs, ou une chaîne de caractères.

`more_columns`

  Des définitions de colonnes supplémentaires.

### Valeurs de retour

Un objet TableInsert; utiliser la méthode execute() pour exécuter l'instruction d'insertion.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::insert()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# Table::isView

(No version information available, might only be in Git)

Table::isView — Renvoie si la table est une vue

### Description

public function mysql_xdevapi\Table::isView(): bool

Détermine si l'objet sous-jacent est une vue ou non.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

`true` si l'objet sous-jacent est une vue, sinon `false`.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::isView()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->isView()) {
        echo "This is a view.";
    } else {
        echo "This is not a view.";
    }
    ?>

L'exemple ci-dessus va afficher :

    This is not a view.

# Table::select

(No version information available, might only be in Git)

Table::select — Sélectionne des lignes dans une table

### Description

public function mysql_xdevapi\Table::select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect

Récupère des données dans une table.

### Liste de paramètres

`columns`

  Les colonnes à partir desquelles récupérer les données. Peut être un tableau avec une ou plusieurs valeurs, ou une chaîne de caractères.

`more_columns`

  Des définitions de colonnes supplémentaires.

### Valeurs de retour

Un objet TableSelect; utiliser la méthode execute() pour exécuter la sélection et retourner un objet RowResult.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Table::update

(No version information available, might only be in Git)

Table::update — Met à jour les lignes de la table

### Description

public function mysql_xdevapi\Table::update(): mysql_xdevapi\TableUpdate

Met à jour les colonnes d'une table.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet TableUpdate; utiliser la méthode execute() pour exécuter l'instruction de mise à jour.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Table::update()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()->set('age',34)->where('name = "Sam"')->limit(1)->execute();
    ?>

## Sommaire

- Table::__construct — Constructeur de Table
- Table::count — Renvoie le nombre de lignes
- Table::delete — Supprime des lignes de la table
- Table::existsInDatabase — Vérifie si la table existe dans la base de données
- Table::getName — Renvoie le nom de la table
- Table::getSchema — Renvoie le schéma de la table
- Table::getSession — Renvoie la session de la table
- Table::insert — Insère des lignes dans une table
- Table::isView — Renvoie si la table est une vue
- Table::select — Sélectionne des lignes dans une table
- Table::update — Met à jour les lignes de la table

# Classe TableDelete

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

Une déclaration pour des opérations de suppression sur une Table.

## Synopsis de la classe

class mysql_xdevapi\TableDelete implements mysql_xdevapi\Executable {
/* Méthodes */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableDelete
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\TableDelete
public function orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete
public function where(string `$where_expr`): mysql_xdevapi\TableDelete
}

# TableDelete::bind

(No version information available, might only be in Git)

TableDelete::bind — Lie les paramètres de la requête de suppression

### Description

public function mysql_xdevapi\TableDelete::bind(array `$placeholder_values`): mysql_xdevapi\TableDelete

Lie une valeur à un espace réservé.

### Liste de paramètres

`placeholder_values`

  Le nom de l'espace réservé et la valeur à lier.

### Valeurs de retour

Un objet TableDelete

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableDelete::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::__construct

(No version information available, might only be in Git)

TableDelete::__construct — Constructeur de TableDelete

### Description

private function mysql_xdevapi\TableDelete::__construct()

Initialisé en utilisant la méthode delete().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableDelete::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::execute

(No version information available, might only be in Git)

TableDelete::execute — Exécute la requête de suppression

### Description

public function mysql_xdevapi\TableDelete::execute(): mysql_xdevapi\Result

Exécute la requête de suppression.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet Result.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableDelete::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::limit

(No version information available, might only be in Git)

TableDelete::limit — Limite les lignes supprimées

### Description

public function mysql_xdevapi\TableDelete::limit(int `$rows`): mysql_xdevapi\TableDelete

Définit le nombre maximum d'enregistrements ou de documents à supprimer.

### Liste de paramètres

`rows`

  Le maximum d'enregistrements ou de documents à supprimer.

### Valeurs de retour

Un objet TableDelete.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableDelete::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::orderby

(No version information available, might only be in Git)

TableDelete::orderby — Définit les critères de tri de la suppression

### Description

public function mysql_xdevapi\TableDelete::orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete

Définit les options de tri pour un ensemble de résultats.

### Liste de paramètres

`orderby_expr`

  La définition du tri.

### Valeurs de retour

Un objet TableDelete.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableDelete::orderBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("age = :age")
      ->bind(['age' => 42])
      ->orderby("name DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::where

(No version information available, might only be in Git)

TableDelete::where — Définit la condition de recherche de suppression

### Description

public function mysql_xdevapi\TableDelete::where(string `$where_expr`): mysql_xdevapi\TableDelete

Définit la condition de recherche pour filtrer.

### Liste de paramètres

`where_expr`

  Définit la condition de recherche pour filtrer les documents ou les enregistrements.

### Valeurs de retour

Un objet TableDelete.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableDelete::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("id = :id")
      ->bind(['id' => 42])
      ->limit(1)
      ->execute();

    ?>

## Sommaire

- TableDelete::bind — Lie les paramètres de la requête de suppression
- TableDelete::__construct — Constructeur de TableDelete
- TableDelete::execute — Exécute la requête de suppression
- TableDelete::limit — Limite les lignes supprimées
- TableDelete::orderby — Définit les critères de tri de la suppression
- TableDelete::where — Définit la condition de recherche de suppression

# Classe TableInsert

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

Une déclaration pour des opérations d'insertion sur une Table.

## Synopsis de la classe

class mysql_xdevapi\TableInsert implements mysql_xdevapi\Executable {
/* Méthodes */
public function execute(): mysql_xdevapi\Result
public function values(array `$row_values`): mysql_xdevapi\TableInsert
}

# TableInsert::__construct

(No version information available, might only be in Git)

TableInsert::__construct — Constructeur de TableInsert

### Description

private function mysql_xdevapi\TableInsert::__construct()

Initialisé par la méthode insert().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableInsert::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::execute

(No version information available, might only be in Git)

TableInsert::execute — Exécute une requête d'insertion

### Description

public function mysql_xdevapi\TableInsert::execute(): mysql_xdevapi\Result

Exécute la déclaration.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet Result.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableInsert::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::values

(No version information available, might only be in Git)

TableInsert::values — Ajoute des valeurs de ligne

### Description

public function mysql_xdevapi\TableInsert::values(array `$row_values`): mysql_xdevapi\TableInsert

Définit les valeurs à insérer.

### Liste de paramètres

`row_values`

  Les valeurs (un tableau) des colonnes à insérer.

### Valeurs de retour

Un objet TableInsert.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableInsert::values()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

## Sommaire

- TableInsert::__construct — Constructeur de TableInsert
- TableInsert::execute — Exécute une requête d'insertion
- TableInsert::values — Ajoute des valeurs de ligne

# Classe TableSelect

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

Une déclaration pour des opérations de récupération d'entrées sur une Table.

## Synopsis de la classe

class mysql_xdevapi\TableSelect implements mysql_xdevapi\Executable {
/* Méthodes */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableSelect
public function execute(): mysql_xdevapi\RowResult
public function groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect
public function having(string `$sort_expr`): mysql_xdevapi\TableSelect
public function limit(int `$rows`): mysql_xdevapi\TableSelect
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function offset(int `$position`): mysql_xdevapi\TableSelect
public function orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect
public function where(string `$where_expr`): mysql_xdevapi\TableSelect
}

# TableSelect::bind

(No version information available, might only be in Git)

TableSelect::bind — Lie les paramètres de la requête select

### Description

public function mysql_xdevapi\TableSelect::bind(array `$placeholder_values`): mysql_xdevapi\TableSelect

Lie une valeur à un espace réservé spécifique.

### Liste de paramètres

`placeholder_values`

  Le nom de l'espace réservé, et la valeur à lier.

### Valeurs de retour

Un objet TableSelect.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::__construct

(No version information available, might only be in Git)

TableSelect::__construct — Constructeur de TableSelect

### Description

private function mysql_xdevapi\TableSelect::__construct()

Un objet retourné par la méthode select(); utiliser execute() pour exécuter la requête.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::execute

(No version information available, might only be in Git)

TableSelect::execute — Exécute une déclaration select

### Description

public function mysql_xdevapi\TableSelect::execute(): mysql_xdevapi\RowResult

Exécute la déclaration select en la chaînant avec la méthode execute().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet RowResult.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::groupBy

(No version information available, might only be in Git)

TableSelect::groupBy — Définit les critères de regroupement de la sélection

### Description

public function mysql_xdevapi\TableSelect::groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect

Définit un critère de regroupement pour le jeu de résultats.

### Liste de paramètres

`sort_expr`

  Le critère de regroupement.

### Valeurs de retour

Un objet TableSelect.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::groupBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [count] => 1
                [age] => 31
            )
        [1] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::having

(No version information available, might only be in Git)

TableSelect::having — Définit la condition de regroupement

### Description

public function mysql_xdevapi\TableSelect::having(string `$sort_expr`): mysql_xdevapi\TableSelect

Définit une condition pour les enregistrements à considérer dans les opérations de fonction d'agrégation.

### Liste de paramètres

`sort_expr`

  Une condition sur les fonctions d'agrégation utilisées sur les critères de regroupement.

### Valeurs de retour

Un objet TableSelect.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::having()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->having('count > 1')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::limit

(No version information available, might only be in Git)

TableSelect::limit — Limite les lignes sélectionnées

### Description

public function mysql_xdevapi\TableSelect::limit(int `$rows`): mysql_xdevapi\TableSelect

Définit le nombre maximum d'enregistrements ou de documents à retourner.

### Liste de paramètres

`rows`

  Le nombre maximum d'enregistrements ou de documents.

### Valeurs de retour

Un objet TableSelect.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::lockExclusive

(No version information available, might only be in Git)

TableSelect::lockExclusive — Exécute EXCLUSIVE LOCK

### Description

public function mysql_xdevapi\TableSelect::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Exécute une opération de lecture avec EXCLUSIVE LOCK. Un seul verrou peut être actif à la fois.

### Liste de paramètres

`lock_waiting_option`

  Une option d'attente facultative qui est définie par défaut sur `MYSQLX_LOCK_DEFAULT`. Les valeurs valides sont :

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valeurs de retour

Un objet TableSelect.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::lockExclusive()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockExclusive(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::lockShared

(No version information available, might only be in Git)

TableSelect::lockShared — Exécute SHARED LOCK

### Description

public function mysql_xdevapi\TableSelect::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Exécute une opération de lecture avec SHARED LOCK. Un seul verrou peut être actif à la fois.

### Liste de paramètres

`lock_waiting_option`

  Une option d'attente facultative qui est définie par défaut sur `MYSQLX_LOCK_DEFAULT`. Les valeurs valides sont :

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Valeurs de retour

Un objet TableSelect.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::lockShared()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockShared(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::offset

(No version information available, might only be in Git)

TableSelect::offset — Définit le décalage de la limite

### Description

public function mysql_xdevapi\TableSelect::offset(int `$position`): mysql_xdevapi\TableSelect

Ignore un nombre donné de lignes dans le résultat.

### Liste de paramètres

`position`

  Le décalage de la limite.

### Valeurs de retour

Un objet TableSelect.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::offset()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->offset(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::orderby

(No version information available, might only be in Git)

TableSelect::orderby — Définit les critères de tri de la sélection

### Description

public function mysql_xdevapi\TableSelect::orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect

Définit les critères de tri.

### Liste de paramètres

`sort_expr`

  L'expression qui définit les critères de tri. Peut être un tableau avec une ou plusieurs expressions, ou une chaîne de caractères.

`sort_exprs`

  Des paramètres supplémentaires pour sort_expr.

### Valeurs de retour

Un objet TableSelect.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::orderBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->orderBy('name desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
        [1] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::where

(No version information available, might only be in Git)

TableSelect::where — Définit les critères de recherche de la sélection

### Description

public function mysql_xdevapi\TableSelect::where(string `$where_expr`): mysql_xdevapi\TableSelect

Définit les conditions de recherche pour filtrer.

### Liste de paramètres

`where_expr`

  Définit la condition de recherche pour filtrer les documents ou les enregistrements.

### Valeurs de retour

Un objet TableSelect.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableSelect::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

## Sommaire

- TableSelect::bind — Lie les paramètres de la requête select
- TableSelect::__construct — Constructeur de TableSelect
- TableSelect::execute — Exécute une déclaration select
- TableSelect::groupBy — Définit les critères de regroupement de la sélection
- TableSelect::having — Définit la condition de regroupement
- TableSelect::limit — Limite les lignes sélectionnées
- TableSelect::lockExclusive — Exécute EXCLUSIVE LOCK
- TableSelect::lockShared — Exécute SHARED LOCK
- TableSelect::offset — Définit le décalage de la limite
- TableSelect::orderby — Définit les critères de tri de la sélection
- TableSelect::where — Définit les critères de recherche de la sélection

# Classe TableUpdate

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

Une déclaration pour des opérations de mises à jour sur une Table.

## Synopsis de la classe

class mysql_xdevapi\TableUpdate implements mysql_xdevapi\Executable {
/* Méthodes */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate
public function execute(): mysql_xdevapi\TableUpdate
public function limit(int `$rows`): mysql_xdevapi\TableUpdate
public function orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate
public function set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate
public function where(string `$where_expr`): mysql_xdevapi\TableUpdate
}

# TableUpdate::bind

(No version information available, might only be in Git)

TableUpdate::bind — Lie les paramètres de la requête de mise à jour

### Description

public function mysql_xdevapi\TableUpdate::bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate

Lie une valeur à un emplacement spécifique.

### Liste de paramètres

`placeholder_values`

  Le nom de l'emplacement réservé, et la valeur à lier, définis comme un tableau JSON.

### Valeurs de retour

Un objet TableUpdate.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableUpdate::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()
      ->set('status', 'admin')
      ->where('name = :name and age > :age')
      ->bind(['name' => 'Bernie', 'age' => 2000])
      ->execute();

    ?>

# TableUpdate::__construct

(No version information available, might only be in Git)

TableUpdate::__construct — Constructeur de TableUpdate

### Description

private function mysql_xdevapi\TableUpdate::__construct()

Initialisé par la méthode update().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableUpdate::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::execute

(No version information available, might only be in Git)

TableUpdate::execute — Exécute la requête de mise à jour

### Description

public function mysql_xdevapi\TableUpdate::execute(): mysql_xdevapi\TableUpdate

Exécute la déclaration de mise à jour.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un objet TableUpdate.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableUpdate::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::limit

(No version information available, might only be in Git)

TableUpdate::limit — Limite le nombre de lignes mises à jour

### Description

public function mysql_xdevapi\TableUpdate::limit(int `$rows`): mysql_xdevapi\TableUpdate

Définit le nombre maximum de lignes ou de documents à mettre à jour.

### Liste de paramètres

`rows`

  Le nombre maximum de lignes ou de documents à mettre à jour.

### Valeurs de retour

Un objet TableUpdate.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableUpdate::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::orderby

(No version information available, might only be in Git)

TableUpdate::orderby — Définit les critères de tri

### Description

public function mysql_xdevapi\TableUpdate::orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate

Définit les critères de tri.

### Liste de paramètres

`orderby_expr`

  L'expression qui définit les critères de tri. Peut être un tableau avec une ou plusieurs expressions, ou une chaîne de caractères.

`orderby_exprs`

  Des paramètres supplémentaires pour les expressions de tri.

### Valeurs de retour

Un objet TableUpdate.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableUpdate::orderby()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();
    ?>

# TableUpdate::set

(No version information available, might only be in Git)

TableUpdate::set — Ajoute un champ à mettre à jour

### Description

public function mysql_xdevapi\TableUpdate::set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate

Met à jour la valeur de la colonne sur les enregistrements d'une table.

### Liste de paramètres

`table_field`

  Le nom de la colonne à mettre à jour.

`expression_or_literal`

  La valeur à définir sur la colonne spécifiée.

### Valeurs de retour

Un objet TableUpdate.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableUpdate::set()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::where

(No version information available, might only be in Git)

TableUpdate::where — Définit le filtre de recherche

### Description

public function mysql_xdevapi\TableUpdate::where(string `$where_expr`): mysql_xdevapi\TableUpdate

Définit la condition de recherche pour filtrer.

### Liste de paramètres

`where_expr`

  La condition de recherche pour filtrer les documents ou les enregistrements.

### Valeurs de retour

Un objet TableUpdate.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\TableUpdate::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

## Sommaire

- TableUpdate::bind — Lie les paramètres de la requête de mise à jour
- TableUpdate::__construct — Constructeur de TableUpdate
- TableUpdate::execute — Exécute la requête de mise à jour
- TableUpdate::limit — Limite le nombre de lignes mises à jour
- TableUpdate::orderby — Définit les critères de tri
- TableUpdate::set — Ajoute un champ à mettre à jour
- TableUpdate::where — Définit le filtre de recherche

# Classe Warning

(PECL mysql-xdevapi >= 8.0.11)

## Introduction

## Synopsis de la classe

class mysql_xdevapi\Warning {
/* Propriétés */
public $message;
public $level;
public $code;
/* Constructeur */
private function __construct()
}

## Propriétés

message

level

code

# Warning::__construct

(No version information available, might only be in Git)

Warning::__construct — Constructeur de Warning

### Description

private function mysql_xdevapi\Warning::__construct()

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Exemples

Exemple #1 Exemple de mysql_xdevapi\Warning::__construct()

    <?php

    /* ... */

    ?>

## Sommaire

- Warning::__construct — Constructeur de Warning

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Compiler à partir des sources
- Constantes pré-définies
- Historique des modifications
- Exemples
- Fonctions Mysql_xdevapi
  - expression — Lie une expression à une variable de requête préparée
  - getSession — Connecte à un serveur MySQL
- mysql_xdevapi\BaseResult — Interface BaseResult
  - BaseResult::getWarnings — Récupère les avertissements de la dernière opération
  - BaseResult::getWarningsCount — Récupère le nombre d'avertissements de la dernière opération
- mysql_xdevapi\Client — La classe Client
  - mysql_xdevapi\Client::close — Ferme le client
  - Client::__construct — Constructeur du client
  - Client::getClient — Renvoie la session client
- mysql_xdevapi\Collection — Classe Collection
  - Collection::add — Ajoute un document à la collection
  - Collection::addOrReplaceOne — Ajoute ou remplace un document de la collection
  - Collection::__construct — Constructeur de Collection
  - Collection::count — Renvoie le nombre de documents
  - Collection::createIndex — Créer un index de collection
  - Collection::dropIndex — Supprime un index de collection
  - Collection::existsInDatabase — Vérifie si la collection existe dans la base de données
  - Collection::find — Recherche de document
  - Collection::getName — Renvoie le nom de la collection
  - Collection::getOne — Renvoie un document
  - Collection::getSchema — Renvoie l'objet schéma
  - Collection::getSession — Renvoie l'objet session
  - Collection::modify — Modifie les documents de la collection
  - Collection::remove — Enlève des documents de la collection
  - Collection::removeOne — Enlève un document de la collection
  - Collection::replaceOne — Remplace un document de la collection
- mysql_xdevapi\CollectionAdd — Classe CollectionAdd
  - CollectionAdd::__construct — Constructeur de CollectionAdd
  - CollectionAdd::execute — Exécute la déclaration
- mysql_xdevapi\CollectionFind — Classe CollectionFind
  - CollectionFind::bind — Lie une valeur à un paramètre de requête
  - CollectionFind::__construct — Constructeur de CollectionFind
  - CollectionFind::execute — Exécute la déclaration
  - CollectionFind::fields — Définit le filtre de champ de document
  - CollectionFind::groupBy — Définit les critères de regroupement
  - CollectionFind::having — Définit la condition pour les fonctions d'agrégation
  - CollectionFind::limit — Limite le nombre de documents retournés
  - CollectionFind::lockExclusive — Exécute l'opération avec un VERROU EXCLUSIF
  - CollectionFind::lockShared — Exécute l'opération avec un VERROU PARTAGE
  - CollectionFind::offset — Ignore un nombre donné d'éléments à retourner
  - CollectionFind::sort — Définit les critères de tri
- mysql_xdevapi\CollectionModify — Classe CollectionModify
  - CollectionModify::arrayAppend — Ajoute un élément à un champ de tableau
  - CollectionModify::arrayInsert — Insère un élément dans un champ de tableau
  - CollectionModify::bind — Lie une valeur à un paramètre de requête
  - CollectionModify::__construct — Constructeur de CollectionModify
  - CollectionModify::execute — Exécute l'opération de modification
  - CollectionModify::limit — Limite le nombre de documents modifiés
  - CollectionModify::patch — Corrige un document
  - CollectionModify::replace — Remplace un champ de document
  - CollectionModify::set — Définit un attribut de document
  - CollectionModify::skip — Ignore les éléments
  - CollectionModify::sort — Définit les critères de tri
  - CollectionModify::unset — Supprime la valeur des champs de document
- mysql_xdevapi\CollectionRemove — Classe CollectionRemove
  - CollectionRemove::bind — Lie une valeur à un paramètre
  - CollectionRemove::__construct — Constructeur de CollectionRemove
  - CollectionRemove::execute — Exécute l'opération de suppression
  - CollectionRemove::limit — Limite le nombre de documents à supprimer
  - CollectionRemove::sort — Définit le critère de tri
- mysql_xdevapi\ColumnResult — Classe ColumnResult
  - ColumnResult::__construct — Constructeur de ColumnResult
  - ColumnResult::getCharacterSetName — Renvoie le jeu de caractères
  - ColumnResult::getCollationName — Renvoie le nom de la collation
  - ColumnResult::getColumnLabel — Renvoie l'étiquette de colonne
  - ColumnResult::getColumnName — Renvoie le nom de la colonne
  - ColumnResult::getFractionalDigits — Renvoie la longueur des chiffres fractionnels
  - ColumnResult::getLength — Renvoie la longueur du champ
  - ColumnResult::getSchemaName — Renvoie le nom du schéma
  - ColumnResult::getTableLabel — Renvoie l'étiquette de table
  - ColumnResult::getTableName — Renvoie le nom de la table
  - ColumnResult::getType — Renvoie le type de colonne
  - ColumnResult::isNumberSigned — Renvoie si le type est signé
  - ColumnResult::isPadded — Vérifie si le champ a un remplissage
- mysql_xdevapi\CrudOperationBindable — Interface CrudOperationBindable
  - CrudOperationBindable::bind — Lie une valeur à un espace réservé
- mysql_xdevapi\CrudOperationLimitable — Interface CrudOperationLimitable
  - CrudOperationLimitable::limit — Définit la limite de résultats
- mysql_xdevapi\CrudOperationSkippable — Interface CrudOperationSkippable
  - CrudOperationSkippable::skip — Le nombre d'opérations à ignorer
- mysql_xdevapi\CrudOperationSortable — Interface CrudOperationSortable
  - CrudOperationSortable::sort — Trie les résultats
- mysql_xdevapi\DatabaseObject — Interface DatabaseObject
  - DatabaseObject::existsInDatabase — Vérifie si l'objet existe dans la base de données
  - DatabaseObject::getName — Renvoie le nom de l'objet
  - DatabaseObject::getSession — Renvoie le nom de la session
- mysql_xdevapi\DocResult — Classe DocResult
  - DocResult::__construct — Constructeur de DocResult
  - DocResult::fetchAll — Renvoie toutes les lignes
  - DocResult::fetchOne — Renvoie une ligne
  - DocResult::getWarnings — Renvoie les avertissements de la dernière opération
  - DocResult::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération
- mysql_xdevapi\Exception — Classe Exception
- mysql_xdevapi\Executable — Interface Executable
  - Executable::execute — Exécute une déclaration
- mysql_xdevapi\ExecutionStatus — Classe ExecutionStatus
  - ExecutionStatus::__construct — Constructeur d'ExecutionStatus
- mysql_xdevapi\Expression — Classe Expression
  - Expression::__construct — Constructeur d'Expression
- mysql_xdevapi\Result — Classe Result
  - Result::__construct — Constructeur de Result
  - Result::getAffectedItemsCount — Renvoie le nombre de lignes affectées
  - Result::getAutoIncrementValue — Renvoie la valeur auto-incrémentée
  - Result::getGeneratedIds — Renvoie les ID générés
  - Result::getWarnings — Renvoie les avertissements de la dernière opération
  - Result::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération
- mysql_xdevapi\RowResult — Classe RowResult
  - RowResult::__construct — Constructeur de RowResult
  - RowResult::fetchAll — Renvoie toutes les lignes du résultat
  - RowResult::fetchOne — Renvoie une ligne du résultat
  - RowResult::getColumnsCount — Renvoie le nombre de colonnes
  - RowResult::getColumnNames — Renvoie le nom de toutes les colonnes
  - RowResult::getColumns — Renvoie les métadonnées des colonnes
  - RowResult::getWarnings — Renvoie les avertissements de la dernière opération
  - RowResult::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération
- mysql_xdevapi\Schema — Classe Schema
  - Schema::__construct — Constructeur de schema
  - Schema::createCollection — Ajoute une collection au schéma
  - Schema::dropCollection — Supprime une collection du schéma
  - Schema::existsInDatabase — Vérifie si l'objet existe dans la base de données
  - Schema::getCollection — Renvoie une collection du schéma
  - Schema::getCollectionAsTable — Renvoie une collection en tant qu'objet Table
  - Schema::getCollections — Renvoie toutes les collections du schéma
  - Schema::getName — Renvoie le nom du schéma
  - Schema::getSession — Renvoie la session du schéma
  - Schema::getTable — Renvoie la table du schéma
  - Schema::getTables — Renvoie les tables du schéma
- mysql_xdevapi\SchemaObject — Interface SchemaObject
  - SchemaObject::getSchema — Renvoie l'objet schéma
- mysql_xdevapi\Session — Classe Session
  - Session::close — Ferme la session
  - Session::commit — Valide la transaction
  - Session::__construct — Description du constructeur
  - Session::createSchema — Créer un nouveau schéma
  - Session::dropSchema — Supprime un schéma
  - Session::generateUUID — Renvoie un nouvel UUID
  - Session::getDefaultSchema — Renvoie le nom du schéma par défaut
  - Session::getSchema — Renvoie un nouvel objet schéma
  - Session::getSchemas — Renvoie les schémas
  - Session::getServerVersion — Renvoie la version du serveur
  - Session::listClients — Renvoie la liste des clients
  - Session::quoteName — Ajoute des guillemets
  - Session::releaseSavepoint — Libère le point de sauvegarde
  - Session::rollback — Annule la transaction
  - Session::rollbackTo — Annule la transaction jusqu'au point de sauvegarde
  - Session::setSavepoint — Créer un point de sauvegarde
  - Session::sql — Créer une requête SQL
  - Session::startTransaction — Démarre une transaction
- mysql_xdevapi\SqlStatement — Classe SqlStatement
  - SqlStatement::bind — Lie les paramètres de l'instruction
  - SqlStatement::__construct — Description de constructeur
  - SqlStatement::execute — Exécute l'opération
  - SqlStatement::getNextResult — Renvoie le résultat suivant
  - SqlStatement::getResult — Renvoie le résultat
  - SqlStatement::hasMoreResults — Vérifie s'il y a plus de résultats
- mysql_xdevapi\SqlStatementResult — Classe SqlStatementResult
  - SqlStatementResult::__construct — Description de constructeur
  - SqlStatementResult::fetchAll — Renvoie toutes les lignes du résultat
  - SqlStatementResult::fetchOne — Renvoie une seule ligne
  - SqlStatementResult::getAffectedItemsCount — Renvoie le nombre de lignes affectées
  - SqlStatementResult::getColumnsCount — Renvoie le nombre de colonnes
  - SqlStatementResult::getColumnNames — Renvoie le nom des colonnes
  - SqlStatementResult::getColumns — Renvoie les colonnes
  - SqlStatementResult::getGeneratedIds — Renvoie les identifiants générés
  - SqlStatementResult::getLastInsertId — Renvoie l'ID de la dernière insertion
  - SqlStatementResult::getWarnings — Renvoie les avertissements de la dernière opération
  - SqlStatementResult::getWarningsCount — Renvoie le nombre d'avertissements de la dernière opération
  - SqlStatementResult::hasData — Vérifie si le résultat contient des données
  - SqlStatementResult::nextResult — Renvoie le résultat suivant
- mysql_xdevapi\Statement — Classe Statement
  - Statement::__construct — Description de constructeur
  - Statement::getNextResult — Renvoie le résultat suivant
  - Statement::getResult — Renvoie le résultat
  - Statement::hasMoreResults — Vérifie s'il y a d'autres résultats
- mysql_xdevapi\Table — Classe Table
  - Table::__construct — Constructeur de Table
  - Table::count — Renvoie le nombre de lignes
  - Table::delete — Supprime des lignes de la table
  - Table::existsInDatabase — Vérifie si la table existe dans la base de données
  - Table::getName — Renvoie le nom de la table
  - Table::getSchema — Renvoie le schéma de la table
  - Table::getSession — Renvoie la session de la table
  - Table::insert — Insère des lignes dans une table
  - Table::isView — Renvoie si la table est une vue
  - Table::select — Sélectionne des lignes dans une table
  - Table::update — Met à jour les lignes de la table
- mysql_xdevapi\TableDelete — Classe TableDelete
  - TableDelete::bind — Lie les paramètres de la requête de suppression
  - TableDelete::__construct — Constructeur de TableDelete
  - TableDelete::execute — Exécute la requête de suppression
  - TableDelete::limit — Limite les lignes supprimées
  - TableDelete::orderby — Définit les critères de tri de la suppression
  - TableDelete::where — Définit la condition de recherche de suppression
- mysql_xdevapi\TableInsert — Classe TableInsert
  - TableInsert::__construct — Constructeur de TableInsert
  - TableInsert::execute — Exécute une requête d'insertion
  - TableInsert::values — Ajoute des valeurs de ligne
- mysql_xdevapi\TableSelect — Classe TableSelect
  - TableSelect::bind — Lie les paramètres de la requête select
  - TableSelect::__construct — Constructeur de TableSelect
  - TableSelect::execute — Exécute une déclaration select
  - TableSelect::groupBy — Définit les critères de regroupement de la sélection
  - TableSelect::having — Définit la condition de regroupement
  - TableSelect::limit — Limite les lignes sélectionnées
  - TableSelect::lockExclusive — Exécute EXCLUSIVE LOCK
  - TableSelect::lockShared — Exécute SHARED LOCK
  - TableSelect::offset — Définit le décalage de la limite
  - TableSelect::orderby — Définit les critères de tri de la sélection
  - TableSelect::where — Définit les critères de recherche de la sélection
- mysql_xdevapi\TableUpdate — Classe TableUpdate
  - TableUpdate::bind — Lie les paramètres de la requête de mise à jour
  - TableUpdate::__construct — Constructeur de TableUpdate
  - TableUpdate::execute — Exécute la requête de mise à jour
  - TableUpdate::limit — Limite le nombre de lignes mises à jour
  - TableUpdate::orderby — Définit les critères de tri
  - TableUpdate::set — Ajoute un champ à mettre à jour
  - TableUpdate::where — Définit le filtre de recherche
- mysql_xdevapi\Warning — Classe Warning
  - Warning::__construct — Constructeur de Warning

# API MySQL originale

# Introduction

Cette extension est obsolète à partir de PHP 5.5.0 et a été supprimée à partir de PHP 7.0.0. À la place, soit l'extension mysqli ou PDO_MySQL devrait être utilisée. Voir aussi la vue d'ensemble de l'API MySQL pour plus d'aide dans le choix d'une API MySQL.

Ces fonctions permettent d'accéder aux bases de données MySQL. Le site officiel de cette base est » http://www.mysql.com/.

La documentation de MySQL est disponible à » http://dev.mysql.com/doc/.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Afin de pouvoir les utiliser, il faut compiler PHP avec le support MySQL.

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

## Installation

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

Pour compiler, utiliser tout simplement l'option de configuration --with-mysql[=DIR] où le paramètre optionnel `[DIR]` pointe vers le dossier d'installation de MySQL.

Bien que cette extension MySQL soit compatible avec MySQL 4.1.0 et supérieur, elle ne supporte pas les fonctionnalités supplémentaires que cette version fournit. Pour cela, utiliser plutôt l'extension MySQLi.

Pour installer l'extension mysqli en même temps que l'extension mysql, il faut utiliser la même bibliothèque client afin d'éviter les conflits.

## Installation sur les systèmes Linux

Note : `[DIR]` est le chemin vers la bibliothèque cliente MySQL (en-têtes et bibliothèques), qui peut être téléchargée depuis le site de » MySQL.

Matrice du support d'ext/mysql
PHP Version | Défaut | Options de configuration : mysqlnd | Options de configuration : `libmysqlclient` | Historique
--- | --- | --- | --- | ---
4.x.x | libmysqlclient | Indisponible | --without-mysql pour désactiver | MySQL est actif par défaut, les bibliothèques clientes MySQL sont incluses en interne
5.0.x, 5.1.x, 5.2.x | libmysqlclient | Indisponible | --with-mysql=[DIR] | MySQL n'est pas actif par défaut, et les bibliothèques clientes MySQL ne sont plus incluses en interne
5.3.x | libmysqlclient | --with-mysql=mysqlnd | --with-mysql=[DIR] | mysqlnd est maintenant disponible
5.4.x | mysqlnd | --with-mysql | --with-mysql=[DIR] | mysqlnd est maintenant incluse par défaut

## Installation sur les systèmes Windows

## PHP 5.0.x, 5.1.x, 5.2.x

MySQL n'est plus activé par défaut, ainsi, la bibliothèque php_mysql.dll doit être activée dans le php.ini. De plus, PHP doit avoir accès à la bibliothèque cliente MySQL. Un fichier nommé libmysql.dll est inclus dans la distribution de PHP pour Windows et pour que PHP puisse discuter avec MySQL, ce fichier doit être disponible dans le PATH du système Windows. Consulter la FAQ intitulée "Où dois-je ajouter mon répertoire PHP à la variable PATH sous Windows ?" pour plus d'informations sur la réalisation de cela. Néanmoins, le fait de copier le fichier libmysql.dll dans le répertoire système de Windows fonctionne (car le dossier système est par défaut dans le PATH système), mais cela n'est pas du tout recommandé.

Pour activer n'importe quelle extension PHP (comme php_mysql.dll), la directive PHP extension_dir doit être définie et doit pointer vers le dossier où sont stockées les extensions PHP. Consulter également le manuel d'installation sous Windows. Par exemple, voici une valeur possible pour la directive extension_dir en PHP 5 : `c:\php\ext`

> Note: Si lorsqu'on démarre le serveur web une erreur similaire à ceci apparaît : `"Unable to load dynamic library './php_mysql.dll'"`, c'est parce que php_mysql.dll et/ou libmysql.dll n'ont pu être trouvés par le système.

## PHP 5.3.0+

Le driver MySQL natif est activé par défaut. Incluez php_mysql.dll, mais libmysql.dll n'est plus nécessaire, ni utilisé.

## Notes sur l'installation de MySQL

Avertissement

Des crashes et des problèmes de démarrage de PHP peuvent être rencontrés lorsqu'on charge cette fonction en même temps que l'extension recode. Voir l'extension recode pour plus de détails.

> Note: Si on a besoin d'autres jeux de caractères que celui par défaut (latin), il faut installer la bibliothèque externe libmysqlclient (non fournie), compilée avec ce jeu de caractères.

## Configuration à l'exécution

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

Options de configuration MySQL
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
mysql.allow_local_infile | "1" | `INI_SYSTEM` |
mysql.allow_persistent | "1" | `INI_SYSTEM` |
mysql.max_persistent | "-1" | `INI_SYSTEM` |
mysql.max_links | "-1" | `INI_SYSTEM` |
mysql.trace_mode | "Off" | `INI_ALL` |
mysql.default_port | NULL | `INI_ALL` |
mysql.default_socket | NULL | `INI_ALL` |
mysql.default_host | NULL | `INI_ALL` |
mysql.default_user | NULL | `INI_ALL` |
mysql.default_password | NULL | `INI_ALL` |
mysql.connect_timeout | "60" | `INI_ALL` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`mysql.allow_local_infile` int
  Autorise l'accès, d'un point de vue de PHP, des fichiers locaux, avec les requêtes LOAD DATA.
`mysql.allow_persistent` bool
  Active ou désactive les connexions persistantes à la base de données MySQL.
`mysql.max_persistent` int
  Le nombre maximum de connexions persistantes aux bases de données MySQL, par processus.
`mysql.max_links` int
  Le nombre maximum de connexions aux bases de données MySQL, y compris les connexions persistantes, par processus.
`mysql.trace_mode` bool
  Mode trace. Lorsque `mysql.trace_mode` est activée, des alertes pour scans de table ou d'index, pour oubli de libération des ressources ou erreurs SQL seront affichées. Cette option a été introduite en PHP 4.3.0.
`mysql.default_port` string
  Le numéro de port TCP par défaut, utilisé pour se connecter à la base de données, lorsque aucun port n'est spécifié. Si aucun port par défaut n'est spécifié, le port sera alors obtenu en lisant la variable d'environnement MYSQL_TCP_PORT, l'entrée `mysql-tcp` dans le fichier /etc/services ou encore la constante de compilation `MYSQL_PORT`, dans cet ordre. Windows n'utilisera aussi que la constante `MYSQL_PORT`.
`mysql.default_socket` string
  Le nom par défaut du socket lorsque l'on se connecte au serveur local, si aucun autre socket n'est spécifié.
`mysql.default_host` string
  Adresse par défaut du serveur, à utiliser lors de la connexion à un serveur MySQL, si aucun hôte n'est spécifié. Ne s'applique pas lorsque le safe mode SQL est activé.
`mysql.default_user` string
  Utilisateur par défaut, à utiliser lors de la connexion à un serveur MySQL, si aucun utilisateur n'est spécifié. Ne s'applique pas lorsque le safe mode SQL est activé.
`mysql.default_password` string
  Mot de passe par défaut, à utiliser lors de la connexion à un serveur MySQL, si aucun mot de passe n'est spécifié. Ne s'applique pas lorsque le safe mode SQL est activé.
`mysql.connect_timeout` int
  Durée maximale d'attente de la réponse d'un serveur, en secondes. Sous Linux, cette durée sert aussi lors du premier échange avec le serveur.

## Types de ressources

Il y a deux types de ressources utilisées par le module MySQL. Le premier est un identifiant de connexion au serveur, appelé `mysql link`, et le second est un identifiant de résultat de requête, appelé `mysql result`.

# Historique des modifications

Les modifications suivantes ont été apportées aux classes/fonctions/méthodes de cette extension.

### Historique des modifications général pour l'extension ext/mysql

Cet historique des modifications fait référence à l'extension ext/mysql.

### Modifications globales sur ext/mysql

La liste suivante présente les modifications sur l'extension entière ext/mysql.

Version | Description
--- | ---
7.0.0 | Cette extension a été supprimée de PHP. Pour plus de détails, voir Choisir une API.

### Modification sur les fonctions existantes

La liste suivante est une compilation des modifications effectuées sur les fonctions de l'extension ext/mysql.

Version | Function | Description
--- | --- | ---

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Il est possible de spécifier des options de client supplémentaires pour les fonctions mysql_connect() et mysql_pconnect(). Ces constantes sont les suivantes :

Constantes client MySQL
Constante | Description
--- | ---
`MYSQL_CLIENT_COMPRESS` | Utilise le protocole avec compression
`MYSQL_CLIENT_IGNORE_SPACE` | Autorise les espaces après les noms de fonction
`MYSQL_CLIENT_INTERACTIVE` | Autorise interactive_timeout secondes d'inactivité sur la connexion (au lieu de wait_timeout).
`MYSQL_CLIENT_SSL` | Utilisation du chiffrement SSL. Cette constante n'est disponible qu'à partir de la version 4.x et plus récente de la bibliothèque cliente MySQL. La version 3.23.x est fournie avec PHP 4 ainsi qu'avec les binaires pour windows de PHP 5.

La fonction mysql_fetch_array() utilise une constante pour spécifier les différents types de formats de réponse. Les constantes suivantes sont utilisées :

Constantes de mysql_fetch_array()
Constante | Description
--- | ---
`MYSQL_ASSOC` | Les colonnes sont retournées dans un tableau, dont les index sont les noms de colonnes.
`MYSQL_BOTH` | Les colonnes sont retournées dans un tableau ayant une indexation numérique et un système d'index correspondant au nom des colonnes.
`MYSQL_NUM` | Les colonnes sont retournées dans un tableau avec un index numérique. Les colonnes sont numérotées dans leur ordre d'apparition. L'index commence à zéro.

# Exemples

## Sommaire

- Exemple avec l'extension MySQL

## Exemple avec l'extension MySQL

Cet exemple simple montre comment se connecter, exécuter une requête, lire les informations obtenues et se déconnecter d'une base de données MySQL.

Exemple #1 Exemple de présentation de l'extension MySQL

    <?php
    // Connexion et sélection de la base
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
        or die('Impossible de se connecter : ' . mysql_error());
    echo 'Connexion réussie';
    mysql_select_db('my_database') or die('Impossible de sélectionner la base de données');

    // Exécution des requêtes SQL
    $query = 'SELECT * FROM my_table';
    $result = mysql_query($query) or die('Échec de la requête : ' . mysql_error());

    // Affichage des résultats en HTML
    echo "<table>\n";
    while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Libération des résultats
    mysql_free_result($result);

    // Fermeture de la connexion
    mysql_close($link);
    ?>

# Fonctions MySQL

## Notes

> Note: La plupart des fonctions MySQL acceptent `link_identifier` comme le dernier paramètre optionnel. S'il n'est pas fourni, la dernière connexion ouverte est utilisée. Si elle n'existe pas, une connexion est essayée d'être établie avec les paramètres par défaut définis dans php.ini. Si les fonctions ne réussissent pas, elles retournent `false`.

# mysql_affected_rows

(PHP 4, PHP 5)

mysql_affected_rows — Retourne le nombre de lignes affectées lors de la dernière opération MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_affected_rows()
- PDOStatement::rowCount()

### Description

function mysql_affected_rows(resource `$link_identifier` = NULL): int

Retourne le nombre de lignes affectées lors de la dernière requête INSERT, UPDATE, REPLACE ou DELETE avec `link_identifier`.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne le nombre de lignes affectées en cas de succès et -1 si la dernière requête a échoué.

Si la dernière requête était un DELETE sans clause WHERE, tous les enregistrements ont été effacés, mais cette fonction va retourner 0 avec les versions de MySQL antérieures à 4.1.2.

Lorsqu'on utilise UPDATE, MySQL ne mettra pas à jour les colonnes si la nouvelle valeur est identique à l'ancienne. Il est donc possible que mysql_affected_rows() ne représente pas forcément le nombre de lignes correspondantes mais plutôt le nombre de lignes qui ont été réellement affectées par la requête.

La requête REPLACE commence par effacer les enregistrements possédant la même clé primaire et ensuite, insère les nouveaux enregistrements. Cette fonction retourne le nombre d'enregistrements effacés ainsi que le nombre d'enregistrements insérés.

Dans le cas d'une requête "INSERT ... ON DUPLICATE KEY UPDATE", la valeur retournée sera `1` si une insertion a été effectuée, ou `2` si une mise à jour d'une ligne existante a été réalisée.

### Exemples

Exemple #1 Exemple avec mysql_affected_rows()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
         die('Impossible de se connecter : ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* Ceci devrait retourner le nombre correct de lignes effacées */
    mysql_query('DELETE FROM mytable WHERE id < 10');
    printf("Lignes effacées : %d\n", mysql_affected_rows());

    /* avec la clause where qui n'est jamais vraie, on devrait obtenir 0 */
    mysql_query('DELETE FROM mytable WHERE 0');
    printf("Lignes effacées : %d\n", mysql_affected_rows());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Lignes effacées : 10
    Lignes effacées : 0

Exemple #2 Exemple avec mysql_affected_rows() en utilisant les transactions

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
         die('Impossible de se connecter : ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* Mise à jour des lignes */
    mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
    printf ("Lignes modifiées : %d\n", mysql_affected_rows());
    mysql_query("COMMIT");
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Lignes modifiées : 10

### Notes

> Note: Transactions
> Lors de l'utilisation des transactions, il faut appeler mysql_affected_rows() après la requête INSERT, UPDATE ou DELETE et non après le COMMIT.

> Note: Requêtes SELECT
> Pour obtenir le nombre de lignes retournées par un SELECT, il est possible d'utiliser mysql_num_rows().

> Note: Clés étrangères en cascade
> mysql_affected_rows() ne compte pas les enregistrements affectés implicitement par un ON DELETE CASCADE et/ou un ON UPDATE CASCADE, concernant les clés étrangères.

### Voir aussi

- mysql_num_rows() - Retourne le nombre de lignes d'un résultat MySQL
- mysql_info() - Lit des informations à propos de la dernière requête MySQL

# mysql_client_encoding

(PHP 4 >= 4.3.0, PHP 5)

mysql_client_encoding — Retourne le nom du jeu de caractères utilisé par le client MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_character_set_name()

### Description

function mysql_client_encoding(resource `$link_identifier` = NULL): string

Retourne la variable `character_set` de MySQL.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne le nom du jeu de caractères par défaut pour la connexion courante.

### Exemples

Exemple #1 Exemple avec mysql_client_encoding()

    <?php
    $link    = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $charset = mysql_client_encoding($link);

    echo "Le jeu de caractères actuel est : $charset\n";
    ?>

L'exemple ci-dessus va afficher :

    Le jeu de caractères actuel est : latin1.

### Voir aussi

- mysql_set_charset() - Définit le jeu de caractères du client MySQL
- mysql_real_escape_string() - Protège une commande SQL de la présence de caractères spéciaux

# mysql_close

(PHP 4, PHP 5)

mysql_close — Ferme la connexion MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_close()
- PDO : Assigne la valeur `null` à l'objet PDO

### Description

function mysql_close(resource `$link_identifier` = NULL): bool

mysql_close() ferme la connexion non persistante au serveur MySQL associée à l'identifiant spécifié. Si `link_identifier` n'est pas spécifié, cette commande s'applique à la dernière connexion ouverte.

Les connexions et les jeux de résultats ouverts de façon non persistantes sont automatiquement détruits lorsqu'un script PHP termine son exécution. Aussi, le fait de fermer une connexion et libérer les résultats étant optionnel, le fait de le faire explicitement est néanmoins vivement recommandé. Ceci va retourner les ressources immédiatement à PHP et à MySQL, ce qui va améliorer les performance. Pour plus d'informations, référez-vous à la libération des ressources

### Liste de paramètres

`link_identifier`
  La connexion MySQL. Si l'identifiant du lien n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_close()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Connexion impossible : ' . mysql_error());
    }
    echo 'Connexion réussie';
    mysql_close($link);
    ?>

L'exemple ci-dessus va afficher :

    Connexion réussie

### Notes

> Note: mysql_close() ne fermera pas les connexions persistantes créées par mysql_pconnect(). Pour plus de détails, voir la page du manuel sur les connexions persistantes.

### Voir aussi

- mysql_connect() - Ouvre une connexion à un serveur MySQL
- mysql_free_result() - Libère le résultat de la mémoire

# mysql_connect

(PHP 4, PHP 5)

mysql_connect — Ouvre une connexion à un serveur MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_connect()
- PDO::__construct()

### Description

function mysql_connect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
bool `$new_link` = `false`,
int `$client_flags` = 0
): resource|false

Ouvre ou réutilise une connexion à un serveur MySQL.

### Liste de paramètres

`server`
  Le serveur MySQL. Il peut aussi inclure le numéro de port. C'est-à-dire `"hostname:port"` ou le chemin vers le socket local, c'est-à-dire `":/path/to/socket"` pour localhost. Si la directive PHP mysql.default_host n'est pas définie (défaut), alors la valeur par défaut est `"localhost:3306"`. En safe mode SQL, ce paramètre est ignoré et la valeur `"localhost:3306"` est toujours utilisée.
`username`
  Le nom d'utilisateur. La valeur par défaut est définie par l'option mysql.default_user. En safe mode SQL, ce paramètre est ignoré et le nom de l'utilisateur propriétaire du processus serveur est utilisé.
`password`
  Le mot de passe. La valeur par défaut est définie par l'option mysql.default_password. En safe mode SQL, ce paramètre est ignoré et un mot de passe vide est utilisé.
`new_link`
  Si un deuxième appel est fait à mysql_connect() avec les mêmes arguments, aucune nouvelle connexion ne sera établie, mais plutôt, l'identifiant de la connexion déjà ouverte sera retourné. Le paramètre `new_link` modifie ce comportement et permet à mysql_connect() de toujours ouvrir une nouvelle connexion, même si mysql_connect() a été appelée avant avec les mêmes paramètres. En safe mode SQL, ce paramètre est ignoré.
`client_flags`
  Le paramètre `client_flags` peut être une combinaison des constantes suivantes : 128 (active le gestionnaire `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` ou `MYSQL_CLIENT_INTERACTIVE`. Consulter la section à propos de Constantes client MySQL pour plus d'informations. En safe mode SQL, ce paramètre est ignoré.

### Valeurs de retour

Retourne l'identifiant de connexion MySQL en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_connect()

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password")
        or die("Impossible de se connecter : " . mysql_error());
    echo 'Connexion réussie';
    mysql_close($link);
    ?>

Exemple #2 Exemple avec mysql_connect() en utilisant la syntaxe `hostname:port`

    <?php
    // on se connecte à example.com et au port 3307
    $link = mysql_connect('example.com:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Connexion impossible : ' . mysql_error());
    }
    echo 'Connecté correctement';
    mysql_close($link);

    // on se connecte à localhost au port 3307
    $link = mysql_connect('127.0.0.1:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Connexion impossible : ' . mysql_error());
    }
    echo 'Connecté correctement';
    mysql_close($link);
    ?>

Exemple #3 Exemple avec mysql_connect() en utilisant la syntaxe ":/path/to/socket"

    <?php
    // on se connecte à localhost et à l'interface de connexion, par exemple /tmp/mysql.sock

    //variante 1 : oublie de localhost
    $link = mysql_connect(':/tmp/mysql', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Connexion impossible : ' . mysql_error());
    }
    echo 'Connecté correctement';
    mysql_close($link);

    // variante 2 : avec localhost
    $link = mysql_connect('localhost:/tmp/mysql.sock', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Connexion impossible : ' . mysql_error());
    }
    echo 'Connecté correctement';
    mysql_close($link);
    ?>

### Notes

> Note: Toutes les fois qu'on spécifie "localhost" ou "localhost:port" en tant que serveur, la bibliothèque client MySQL surchargera cela et essaiera de se connecter à un socket local (nommé pipe sous Windows). Pour utiliser TCP/IP, utiliser "127.0.0.1" au lieu de "localhost". Si la bibliothèque client MySQL essaie de se connecter au mauvais socket local, le chemin correct doit être défini comme mysql.default_host dans php.ini et le champ serveur laissé vide.

> Note: La connexion au serveur sera fermée aussitôt que l'exécution du script se termine, à moins qu'elle soit fermée avant en appelant explicitement mysql_close().

> Note: L'erreur `"Can't create TCP/IP socket (10106)"` signifie habituellement que la directive de configuration variables_order ne contient pas le caractère `E`. Sous Windows, si la variable d'environnement n'est pas copiée, la variable d'environnement `SYSTEMROOT` ne sera pas disponible et PHP aura des problèmes pour charger Winsock.

### Voir aussi

- mysql_pconnect() - Ouvre une connexion persistante à un serveur MySQL
- mysql_close() - Ferme la connexion MySQL

# mysql_create_db

(PHP 4, PHP 5)

mysql_create_db — Crée une base de données MySQL

Avertissement

Cette fonction était obsolète en PHP 4.3.0, et la totalité de l'extension original MySQL a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser soit l'extension MySQLi, soit l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_query()
- PDO::query()

### Description

function mysql_create_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_create_db() tente de créer une nouvelle base de données sur le serveur associé avec l'identifiant de connexion spécifié.

### Liste de paramètres

`database_name`
  Le nom de la base de données à être créée.
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple alternatif avec mysql_create_db()

La fonction mysql_create_db() est obsolète. Il est préférable d'utiliser la fonction mysql_query(), avec une commande SQL "CREATE DATABASE".

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Connexion impossible : ' . mysql_error());
    }

    $sql = 'CREATE DATABASE my_db';
    if (mysql_query($sql, $link)) {
        echo "Base de données créée correctement\n";
    } else {
        echo 'Erreur lors de la création de la base de données : ' . mysql_error() . "\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Base de données créée correctement

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_createdb()

> Note: Cette fonction n'est pas disponible si l'extension MySQL a été compilée avec une bibliothèque client MySQL 4.x.

### Voir aussi

- mysql_query() - Envoie une requête à un serveur MySQL
- mysql_select_db() - Sélectionne une base de données MySQL

# mysql_data_seek

(PHP 4, PHP 5)

mysql_data_seek — Déplace le pointeur interne de résultat MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_data_seek()
- `PDO::FETCH_ORI_ABS`

### Description

function mysql_data_seek(resource `$result`, int `$row_number`): bool

mysql_data_seek() déplace le pointeur interne de résultat, dans le résultat associé à l'identifiant de résultat `result_identifier`. Il le fait pointer à la ligne `row_number`. Le prochain appel à une fonction MySQL de récupération de données, comme la fonction mysql_fetch_assoc() retournera cette ligne.

`row_number` commence à 0. `row_number` doit être une valeur qui va de 0 à mysql_num_rows() - 1. Cependant, si le résultat est vide, un `row_number` de 0 échouera avec une erreur `E_WARNING` et mysql_data_seek() retournera `false`.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`row_number`
  La position de la ligne désirée pour le nouveau pointeur de résultats.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_data_seek()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Connexion impossible : ' . mysql_error());
    }
    $db_selected = mysql_select_db('sample_db');
    if (!$db_selected) {
        die('Sélection de base de données impossible : ' . mysql_error());
    }
    $query = 'SELECT nom_famille, prenom FROM amis';
    $result = mysql_query($query);
    if (!$result) {
        die('Requête échec : ' . mysql_error());
    }
    /* Récupération des lignes en ordre inverse */
    for ($i = mysql_num_rows($result) - 1; $i >= 0; $i--) {
        if (!mysql_data_seek($result, $i)) {
            echo "Ne peut pointer vers la ligne $i : " . mysql_error() . "\n";
            continue;
        }

        if (!($row = mysql_fetch_assoc($result))) {
            continue;
        }

        echo $row['nom_famille'] . ' ' . $row['prenom'] . "<br />\n";
    }

    mysql_free_result($result);
    ?>

### Notes

> Note: La fonction mysql_data_seek() peut être utilisée en conjonction avec mysql_query(), mais pas avec la fonction mysql_unbuffered_query().

### Voir aussi

- mysql_query() - Envoie une requête à un serveur MySQL
- mysql_num_rows() - Retourne le nombre de lignes d'un résultat MySQL
- mysql_fetch_row() - Retourne une ligne de résultat MySQL sous la forme d'un tableau
- mysql_fetch_assoc() - Lit une ligne de résultat MySQL dans un tableau associatif
- mysql_fetch_array() - Retourne une ligne de résultat MySQL sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux
- mysql_fetch_object() - Retourne une ligne de résultat MySQL sous la forme d'un objet

# mysql_db_name

(PHP 4, PHP 5)

mysql_db_name — Récupère le nom de base de données à l'appel de mysql_list_dbs()

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- Requête : `SELECT DATABASE()`

### Description

function mysql_db_name(resource `$result`, int `$row`, mixed `$field` = NULL): string

Récupère le nom de base de données à l'appel de mysql_list_dbs().

### Liste de paramètres

`result`
  Le pointeur de résultat d'un appel de mysql_list_dbs().
`row`
  L'index à l'intérieur du jeu de résultats.
`field`
  Le nom du champ.

### Valeurs de retour

Retourne le nom de base de données en cas de succès et `false` en cas d'échec. Si `false` est retourné, utiliser mysql_error() pour déterminer la nature de l'erreur.

### Exemples

Exemple #1 Exemple mysql_db_name()

    <?php
    error_reporting(E_ALL);

    $link = mysql_connect('dbhost', 'username', 'password');
    $db_list = mysql_list_dbs($link);

    $i = 0;
    $cnt = mysql_num_rows($db_list);
    while ($i < $cnt) {
        echo mysql_db_name($db_list, $i) . "\n";
        $i++;
    }
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_dbname()

### Voir aussi

- mysql_list_dbs() - Liste les bases de données disponibles sur le serveur MySQL
- mysql_tablename() - Lit le nom de la table qui contient un champ

# mysql_db_query

(PHP 4, PHP 5)

mysql_db_query — Sélectionne une base de données et y exécute une requête

Avertissement

Cette fonction était obsolète en PHP 5.3.0, et la totalité de l'extension original MySQL a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser soit l'extension MySQLi, soit l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_select_db() puis la requête
- PDO::__construct()

### Description

function mysql_db_query(string `$database`, string `$query`, resource `$link_identifier` = NULL): resource|bool

mysql_db_query() sélectionne une base de données et exécute une requête sur celle-ci.

### Liste de paramètres

`database`
  Le nom de la base de données qui sera sélectionnée.
`query`
  La requête MySQL. Les données contenues dans la requête doivent être proprement échappées.
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne une ressource de résultat positive MySQL à partir de la requête ou `false` en cas d'erreur. Cette fonction retourne aussi `true`/`false` pour les requêtes `INSERT`/`UPDATE`/`DELETE` pour indiquer une réussite ou un échec.

### Exemples

Exemple #1 Exemple alternatif avec mysql_db_query()

    <?php

    if (!$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
        echo 'Connexion impossible à mysql';
        exit;
    }

    if (!mysql_select_db('mysql_dbname', $link)) {
        echo 'Sélection de base de données impossible';
        exit;
    }

    $sql    = 'SELECT foo FROM bar WHERE id = 42';
    $result = mysql_query($sql, $link);

    if (!$result) {
        echo "Erreur DB, impossible d'effectuer une requête\n";
        echo 'Erreur MySQL : ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_assoc($result)) {
        echo $row['foo'];
    }

    mysql_free_result($result);

    ?>

### Notes

> Note: Soyez avertis que cette fonction ne restaure pas la base de données qui était utilisée initialement. En d'autres termes, on ne peut utiliser cette fonction pour exécuter temporairement une requête SQL dans une autre base de données, il faudra sélectionner manuellement la bonne base à nouveau. Il est fortement recommandé d'utiliser la syntaxe SQL `database.table` ou mysql_select_db() au lieu de cette fonction.

### Voir aussi

- mysql_query() - Envoie une requête à un serveur MySQL
- mysql_select_db() - Sélectionne une base de données MySQL

# mysql_drop_db

(PHP 4, PHP 5)

mysql_drop_db — Efface une base de données MySQL

Avertissement

Cette fonction était obsolète en PHP 4.3.0, et la totalité de l'extension original MySQL a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser soit l'extension MySQLi, soit l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- Exécute une requête `DROP DATABASE`

### Description

function mysql_drop_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_drop_db() essaie d'effacer la base de données `database_name` complète sur le serveur associé à la ressource de connexion `link_identifier`. La fonction mysql_drop_db() est obsolète. Il est préférable d'utiliser mysql_query() avec la requête `DROP DATABASE` à la place.

### Liste de paramètres

`database_name`
  Le nom de la base de données à effacer.
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_drop_db()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
    die('Impossible de se connecter : ' . mysql_error());
    }

    $sql = 'DROP DATABASE my_db';
    if (mysql_query($sql, $link)) {
    echo "La base de données my_db a été effacée avec succès.\n";
    } else {
    echo 'Erreur lors de l\'effacement de la base : ' . mysql_error() . "\n";
    }
    ?>

### Notes

Avertissement

Cette fonction ne sera pas disponible si on a compilé MySQL avec la bibliothèque cliente MySQL 4.x.

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_dropdb()

### Voir aussi

- mysql_query() - Envoie une requête à un serveur MySQL

# mysql_errno

(PHP 4, PHP 5)

mysql_errno — Retourne le numéro d'erreur de la dernière commande MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_errno()
- PDO::errorCode()

### Description

function mysql_errno(resource `$link_identifier` = NULL): int

Retourne le numéro d'erreur de la dernière commande MySQL.

Les erreurs qui sont remontées depuis le serveur MySQL ne sont plus des alertes. À la place, il faut utiliser mysql_errno() pour obtenir le numéro d'erreur. À noter que cette fonction retourne uniquement le code erreur depuis la dernière fonction MySQL exécutée (n'incluant pas les fonctions mysql_error() et mysql_errno()), donc, pour l'utiliser, il faut s'assurer de récupérer la valeur avant d'appeler une autre fonction MySQL.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne le numéro de l'erreur depuis la dernière fonction MySQL, ou `0` (zéro) si aucune erreur ne survient.

### Exemples

Exemple #1 Exemple avec mysql_errno()

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!mysql_select_db("nonexistentdb", $link)) {
       echo mysql_errno($link) . ": " . mysql_error($link). "\n";
    }

    mysql_select_db("kossu", $link);
    if (!mysql_query("SELECT * FROM nonexistenttable", $link)) {
       echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    1049: Unknown database 'nonexistentdb'
    1146: Table 'kossu.nonexistenttable' doesn't exist

### Voir aussi

- mysql_error() - Retourne le texte associé avec l'erreur générée lors de la dernière requête
- » les codes erreurs MySQL

# mysql_error

(PHP 4, PHP 5)

mysql_error — Retourne le texte associé avec l'erreur générée lors de la dernière requête

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_error()
- PDO::errorInfo()

### Description

function mysql_error(resource `$link_identifier` = NULL): string

mysql_error() retourne le message d'erreur généré par la dernière commande MySQL. Les erreurs retournées par le serveur MySQL ne génèrent plus de message d'alerte. À la place, il faut utiliser la fonction mysql_error() pour lire le contenu du message. À noter que cette fonction ne retourne que le texte de l'erreur la plus récente (n'incluant pas mysql_error() et mysql_errno()), ce qui fait que si on souhaite l'utiliser, il faut s'assurer de sa valeur avant de lancer une autre requête.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne le texte de l'erreur de la dernière fonction MySQL, ou `''` (chaîne vide) si aucune erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_error()

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    mysql_select_db("nonexistentdb", $link);
    echo mysql_errno($link) . ": " . mysql_error($link). "\n";

    mysql_select_db("kossu", $link);
    mysql_query("SELECT * FROM nonexistenttable", $link);
    echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    1049: Unknown database 'nonexistentdb'
    1146: Table 'kossu.nonexistenttable' doesn't exist

### Voir aussi

- mysql_errno() - Retourne le numéro d'erreur de la dernière commande MySQL
- » les codes erreurs MySQL

# mysql_escape_string

(PHP 4 >= 4.0.3, PHP 5)

mysql_escape_string — Protège les caractères spéciaux SQL

Avertissement

Cette fonction était obsolète en PHP 4.3.0, et la totalité de l'extension original MySQL a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser soit l'extension MySQLi, soit l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_escape_string()
- PDO::quote()

### Description

function mysql_escape_string(string `$unescaped_string`): string

mysql_escape_string() va protéger tous les caractères de la chaîne `unescaped_string`, pour pouvoir l'utiliser directement dans une requête mysql_query(). Cette fonction est obsolète.

mysql_escape_string() est identique à la fonction mysql_real_escape_string() hormis le fait que mysql_real_escape_string() requiert une ressource de connexion et protège la chaîne en fonction du jeu de caractères courant. mysql_escape_string() ne demande pas de connexion comme argument, et ne respecte pas le jeu de caractères courant.

### Liste de paramètres

`unescaped_string`
  La chaîne qui doit être protégée.

### Valeurs de retour

Retourne la chaîne protégée.

### Exemples

Exemple #1 Exemple avec mysql_escape_string()

    <?php
    $item = "C'est un exemple de Zak";
    $escaped_item = mysql_escape_string($item);
    printf("Chaîne protégée : %s\n", $escaped_item);
    ?>

L'exemple ci-dessus va afficher :

    Chaîne protégée : C\'est un exemple de Zak

### Notes

> Note: mysql_escape_string() ne protège pas les caractères `%` et `_`.

### Voir aussi

- mysql_real_escape_string() - Protège une commande SQL de la présence de caractères spéciaux

# mysql_fetch_array

(PHP 4, PHP 5)

mysql_fetch_array — Retourne une ligne de résultat MySQL sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_array()
- PDOStatement::fetch()

### Description

function mysql_fetch_array(resource `$result`, int `$result_type` = MYSQL_BOTH): array

mysql_fetch_array() retourne un tableau qui contient la ligne demandée dans le résultat `result` et déplace le pointeur de données interne d'un cran.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`result_type`
  Le type de tableau à récupérer. C'est une constante qui peut prendre les valeurs suivantes : `MYSQL_ASSOC`, `MYSQL_NUM`, et `MYSQL_BOTH`.

### Valeurs de retour

Retourne un tableau de chaînes qui correspond à la ligne récupérée ou `false` s'il n'y a plus de lignes. Le type de tableau retourné dépend de la définition du paramètre `result_type`. En utilisant `MYSQL_BOTH` (défaut), l'on récupérera un tableau contenant des indices associatifs et numériques. En utilisant `MYSQL_ASSOC`, on ne récupérera que les indices associatifs (comme le fonctionnement de la fonction mysql_fetch_assoc()), en utilisant `MYSQL_NUM`, on ne récupérera que les indices numériques (comme le fonctionnement de la fonction mysql_fetch_row()).

Si plusieurs colonnes portent le même nom, la dernière colonne aura la priorité. Pour accéder aux autres colonnes du même nom, il faut utiliser l'index numérique, ou faire un alias pour chaque colonne. Pour les alias de colonnes, il ne sera pas possible d'accéder aux contenus avec les noms originaux des colonnes.

### Exemples

Exemple #1 Requête avec duplication de nom de colonnes

    SELECT table1.field AS foo, table2.field AS bar FROM table1, table2

Exemple #2 mysql_fetch_array() avec `MYSQL_NUM`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Impossible de se connecter : " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_NUM)) {
       printf("ID : %s  Nom : %s", $row[0], $row[1]);
    }

    mysql_free_result($result);
    ?>

Exemple #3 mysql_fetch_array() avec `MYSQL_ASSOC`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Impossible de se connecter : " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) {
       printf("ID : %s  Nom : %s", $row["id"], $row["name"]);
    }

    mysql_free_result($result);
    ?>

Exemple #4 mysql_fetch_array() avec `MYSQL_BOTH`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Impossible de se connecter : " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_BOTH)) {
       printf ("ID : %s  Nom : %s", $row[0], $row["name"]);
    }

    mysql_free_result($result);
    ?>

### Notes

> Note: Performance
> Une chose importante à noter est que l'utilisation de mysql_fetch_array() n'est pas significativement plus lente que l'utilisation de mysql_fetch_row(), alors qu'elle fournit une valeur ajoutée significative.

> Note: Les noms des champs retournés par cette fonction sont sensibles à la casse.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Voir aussi

- mysql_fetch_row() - Retourne une ligne de résultat MySQL sous la forme d'un tableau
- mysql_fetch_assoc() - Lit une ligne de résultat MySQL dans un tableau associatif
- mysql_data_seek() - Déplace le pointeur interne de résultat MySQL
- mysql_query() - Envoie une requête à un serveur MySQL

# mysql_fetch_assoc

(PHP 4 >= 4.0.3, PHP 5)

mysql_fetch_assoc — Lit une ligne de résultat MySQL dans un tableau associatif

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_assoc()
- PDOStatement::fetch() avec `mode` en tant que `PDO::FETCH_ASSOC`

### Description

function mysql_fetch_assoc(resource `$result`): array

mysql_fetch_assoc() retourne un tableau associatif qui contient la ligne lue dans le résultat `result` et déplace le pointeur interne de données. mysql_fetch_assoc() revient à appeler la fonction mysql_fetch_array() avec MYSQL_ASSOC en tant que second paramètre. Cette fonction retourne uniquement un tableau associatif.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().

### Valeurs de retour

Retourne un tableau associatif de chaînes qui contient la ligne lue dans le résultat `result`, ou bien `false` s'il ne reste plus de lignes à lire.

Si plusieurs colonnes portent le même nom, la dernière aura la priorité. Pour accéder aux autres colonnes du même nom, il faut utiliser la fonction mysql_fetch_row() avec les indices numériques ou utiliser les alias sur les noms. Regardez la documentation sur la fonction mysql_fetch_array() pour plus d'informations sur les alias.

### Exemples

Exemple #1 Exemple avec mysql_fetch_assoc()

    <?php

    $conn = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!$conn) {
    echo "Impossible de se connecter à la base de données : " . mysql_error();
       exit;
    }

    if (!mysql_select_db("mydbname")) {
       echo "Impossible de sélectionner la base mydbname : " . mysql_error();
       exit;
    }

    $sql = "SELECT id as userid, fullname, userstatus
    FROM   sometable
    WHERE  userstatus = 1";

    $result = mysql_query($sql);

    if (!$result) {
       echo "Impossible d'exécuter la requête ($sql) dans la base : " . mysql_error();
       exit;
    }

    if (mysql_num_rows($result) == 0) {
       echo "Aucune ligne trouvée, rien à afficher.";
       exit;
    }

    // Tant qu'une ligne existe, place cette ligne dans la variable $row
    // sous la forme d'un tableau associatif.
    // Note : Si vous n'attendez qu'une seule ligne, oubliez la boucle
    // Note : Si vous utilisez extract($row); dans la boucle suivante
    //       vous créerez $userid, $fullname et $userstatus
    while ($row = mysql_fetch_assoc($result)) {
       echo $row["userid"];
       echo $row["fullname"];
       echo $row["userstatus"];
    }

    mysql_free_result($result);

    ?>

### Notes

> Note: Performance
> Une chose importante à noter est que l'utilisation de mysql_fetch_assoc() n'est pas significativement plus lente que l'utilisation de mysql_fetch_row(), alors qu'il fournit des valeurs significatives ajoutées.

> Note: Les noms des champs retournés par cette fonction sont sensibles à la casse.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Voir aussi

- mysql_fetch_row() - Retourne une ligne de résultat MySQL sous la forme d'un tableau
- mysql_fetch_array() - Retourne une ligne de résultat MySQL sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux
- mysql_data_seek() - Déplace le pointeur interne de résultat MySQL
- mysql_query() - Envoie une requête à un serveur MySQL
- mysql_error() - Retourne le texte associé avec l'erreur générée lors de la dernière requête

# mysql_fetch_field

(PHP 4, PHP 5)

mysql_fetch_field — Retourne les données enregistrées dans une colonne MySQL sous forme d'objet

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_field()
- PDOStatement::getColumnMeta()

### Description

function mysql_fetch_field(resource `$result`, int `$field_offset` = 0): object

Retourne un objet contenant les informations sur les champs. Cette fonction peut être utilisée pour obtenir des informations sur les champs de la requête fournie `result`.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`field_offset`
  La position numérique du champ. Si la position du champ n'est pas spécifiée, le champ suivant qui n'a pas encore été récupéré par cette fonction est alors récupéré. `field_offset` commence à `0`.

### Valeurs de retour

Retourne un objet contenant les informations sur les champs. Les propriétés de l'objet sont les suivantes :

- `"name"` : nom de la colonne
- `"table"` : nom de la table pour la colonne, qui pourra être l'alias si un alias a été défini.
- `"max_length"` : taille maximale de la colonne
- `"not_null"` : 1 si la colonne ne peut pas être `null`
- `"primary_key"` : 1 si la colonne est une clé primaire
- `"unique_key"` : 1 si la colonne est une clé unique
- `"multiple_key"` : 1 si la colonne est une clé non unique
- `"numeric"` : 1 si la colonne est numérique
- `"blob"` : 1 si la colonne est BLOB
- `"type"` : le type de la colonne
- `"unsigned"` : 1 si la colonne est non signée
- `"zerofill"` : 1 si la colonne est complétée par des zéros

### Exemples

Exemple #1 Exemple avec mysql_fetch_field()

    <?php
    $conn = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$conn) {
       die('Impossible de se connecter : ' . mysql_error());
    }
    mysql_select_db('database');
    $result = mysql_query('select * from table');
    if (!$result) {
       die('Échec de la requête : ' . mysql_error());
    }
    /* Lecture des méta données de la colonne */
    $i = 0;
    while ($i < mysql_num_fields($result)) {
       echo "Détails sur la colonne $i:<br />\n";
       $meta = mysql_fetch_field($result, $i);
       if (!$meta) {
          echo "Aucun détail disponible<br />\n";
       }
       echo "<pre>
        blob:         $meta->blob
        max_length:   $meta->max_length
        multiple_key: $meta->multiple_key
        name:         $meta->name
        not_null:     $meta->not_null
        numeric:      $meta->numeric
        primary_key:  $meta->primary_key
        table:        $meta->table
        type:         $meta->type
        unique_key:   $meta->unique_key
        unsigned:     $meta->unsigned
        zerofill:     $meta->zerofill
       </pre>";
       $i++;
    }
    mysql_free_result($result);
    ?>

### Notes

> Note: Les noms des champs retournés par cette fonction sont sensibles à la casse.

> Note: Si les champs ou les noms de table utilisent un alias dans la requête SQL, le nom utilisé dans l'alias sera retourné. Le nom original peut être récupéré en utilisant la méthode mysqli_result::fetch_field().

### Voir aussi

- mysql_field_seek() - Déplace le pointeur de résultat vers une position donnée

# mysql_fetch_lengths

(PHP 4, PHP 5)

mysql_fetch_lengths — Retourne la taille de chaque colonne d'une ligne de résultat MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_lengths()
- PDOStatement::getColumnMeta()

### Description

function mysql_fetch_lengths(resource `$result`): array|false

mysql_fetch_lengths() retourne un tableau avec la taille de chaque colonne de la dernière ligne retournée par mysql_fetch_row().

mysql_fetch_lengths() stocke les tailles de chaque colonne de la dernière ligne retournée par mysql_fetch_row(), mysql_fetch_assoc(), mysql_fetch_array() et mysql_fetch_object() dans un tableau, en commençant à la position 0.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().

### Valeurs de retour

Un array de taille, en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_fetch_lengths()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
       echo 'Impossible d\'exécuter la requête : ' . mysql_error();
       exit;
    }
    $row     = mysql_fetch_assoc($result);
    $lengths = mysql_fetch_lengths($result);

    print_r($row);
    print_r($lengths);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
       [id] => 42
       [email] => user@example.com
    )
    Array
    (
       [0] => 2
       [1] => 16
    )

### Voir aussi

- mysql_field_len() - Retourne la taille d'un champ de résultat MySQL
- mysql_fetch_row() - Retourne une ligne de résultat MySQL sous la forme d'un tableau
- strlen() - Calcule la taille d'une chaîne

# mysql_fetch_object

(PHP 4, PHP 5)

mysql_fetch_object — Retourne une ligne de résultat MySQL sous la forme d'un objet

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_object()
- PDOStatement::fetch() avec `mode` en tant que `PDO::FETCH_OBJ`

### Description

function mysql_fetch_object(resource `$result`, string `$class_name` = ?, array `$params` = ?): object

mysql_fetch_object() retourne un objet dont les propriétés correspondent à la ligne demandée dans le résultat `result` et déplace le pointeur de données interne d'un cran.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`class_name`
  Le nom de la classe à instancier, dont les propriétés sont définies, et qui sera retourné. Si ce paramètre n'est pas spécifié, un objet stdClass sera retourné.
`params`
  Un tableau de paramètres à passer au constructeur pour les objets `class_name`.

### Valeurs de retour

Retourne un objet avec les propriétés qui correspondent à la ligne récupérée, ou `false` s'il n'y a plus de lignes.

### Exemples

Exemple #1 Exemple avec mysql_fetch_object()

    <?php
    mysql_connect("hostname", "user", "password");
    mysql_select_db("mydb");
    $result = mysql_query("select * from mytable");
    while ($row = mysql_fetch_object($result)) {
       echo $row->user_id;
       echo $row->fullname;
    }
    mysql_free_result($result);
    ?>

Exemple #2 Exemple avec mysql_fetch_object()

    <?php
    class foo {
        public $name;
    }

    mysql_connect("hostname", "user", "password");
    mysql_select_db("mydb");

    $result = mysql_query("select name from mytable limit 1");
    $obj = mysql_fetch_object($result, 'foo');
    var_dump($obj);
    ?>

### Notes

> Note: Performance
> Concernant la vitesse, mysql_fetch_object() est aussi rapide que mysql_fetch_array() et presque aussi rapide que mysql_fetch_row() (la différence est insignifiante).

> Note: mysql_fetch_object() est identique à mysql_fetch_array(), à la différence qu'elle retourne un objet à la place d'un tableau. On pourra ainsi accéder aux valeurs des champs par leur nom, mais plus par leur offset (les nombres ne sont pas des noms MySQL).

> Note: Les noms des champs retournés par cette fonction sont sensibles à la casse.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Voir aussi

- mysql_fetch_array() - Retourne une ligne de résultat MySQL sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux
- mysql_fetch_assoc() - Lit une ligne de résultat MySQL dans un tableau associatif
- mysql_fetch_row() - Retourne une ligne de résultat MySQL sous la forme d'un tableau
- mysql_data_seek() - Déplace le pointeur interne de résultat MySQL
- mysql_query() - Envoie une requête à un serveur MySQL

# mysql_fetch_row

(PHP 4, PHP 5)

mysql_fetch_row — Retourne une ligne de résultat MySQL sous la forme d'un tableau

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_row()
- PDOStatement::fetch() avec `mode` en tant que `PDO::FETCH_NUM`

### Description

function mysql_fetch_row(resource `$result`): array

mysql_fetch_row() retourne un tableau indexé numériquement, qui correspond à la prochaine ligne du résultat MySQL `result` et déplace le pointeur interne de données d'un cran.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().

### Valeurs de retour

Retourne un tableau numérique de chaînes qui correspond à la ligne récupérée, ou `false` s'il n'y a plus de lignes.

mysql_fetch_row() va rechercher une ligne dans le résultat associé à l'identifiant de résultat spécifié. La ligne est retournée sous la forme d'un tableau. Chaque colonne est stockée à une position du tableau, commençant à la position `0`.

### Exemples

Exemple #1 Exemple avec mysql_fetch_row()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
       echo 'Impossible d\'exécuter la requête : ' . mysql_error();
       exit;
    }
    $row = mysql_fetch_row($result);

    echo $row[0]; // 42
    echo $row[1]; // la valeur du champ email
    ?>

### Notes

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Voir aussi

- mysql_fetch_array() - Retourne une ligne de résultat MySQL sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux
- mysql_fetch_assoc() - Lit une ligne de résultat MySQL dans un tableau associatif
- mysql_fetch_object() - Retourne une ligne de résultat MySQL sous la forme d'un objet
- mysql_data_seek() - Déplace le pointeur interne de résultat MySQL
- mysql_fetch_lengths() - Retourne la taille de chaque colonne d'une ligne de résultat MySQL
- mysql_result() - Retourne un champ d'un résultat MySQL

# mysql_field_flags

(PHP 4, PHP 5)

mysql_field_flags — Retourne des détails sur une colonne MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_field_direct() [flags]
- PDOStatement::getColumnMeta() [flags]

### Description

function mysql_field_flags(resource `$result`, int `$field_offset`): string|false

mysql_field_flags() retourne les drapeaux associés au champ spécifié par `field_offset`, dans le résultat `result`. Les drapeaux sont retournés comme des mots, séparés par des espaces, ce qui les rend faciles à séparer, avec la commande explode().

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`field_offset`
  La position numérique du champ. `field_offset` commence à `0`. Si `field_offset` n'existe pas, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne les drapeaux sous la forme d'une chaîne associés avec le résultat ou `false` si une erreur survient.

Les valeurs suivantes (pour une version suffisamment récente de MySQL) sont disponibles : `"not_null"`, `"primary_key"`, `"unique_key"`, `"multiple_key"`, `"blob"`, `"unsigned"`, `"zerofill"`, `"binary"`, `"enum"`, `"auto_increment"` et `"timestamp"`.

### Exemples

Exemple #1 Exemple avec mysql_field_flags()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
       echo 'Impossible d\'exécuter la requête : ' . mysql_error();
       exit;
    }
    $flags = mysql_field_flags($result, 0);

    echo $flags;
    print_r(explode(' ', $flags));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    not_null primary_key auto_increment
    Array
    (
       [0] => not_null
       [1] => primary_key
       [2] => auto_increment
    )

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_fieldflags()

### Voir aussi

- mysql_field_type() - Retourne le type d'une colonne MySQL spécifique
- mysql_field_len() - Retourne la taille d'un champ de résultat MySQL

# mysql_field_len

(PHP 4, PHP 5)

mysql_field_len — Retourne la taille d'un champ de résultat MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_field_direct() [length]
- PDOStatement::getColumnMeta() [len]

### Description

function mysql_field_len(resource `$result`, int `$field_offset`): int|false

mysql_field_len() retourne la taille du champ spécifié.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`field_offset`
  La position numérique du champ. `field_offset` commence à `0`. Si `field_offset` n'existe pas, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

La taille de l'index du champ spécifié en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_field_len()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
       echo 'Impossible d\'exécuter la requête : ' . mysql_error();
       exit;
    }

    // Récupère la longueur du champ id dans la base de données.
    $length = mysql_field_len($result, 0);
    echo $length;
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_fieldlen()

### Voir aussi

- mysql_fetch_lengths() - Retourne la taille de chaque colonne d'une ligne de résultat MySQL
- strlen() - Calcule la taille d'une chaîne

# mysql_field_name

(PHP 4, PHP 5)

mysql_field_name — Retourne le nom d'une colonne dans un résultat MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_field_direct() [name] ou [orgname]
- PDOStatement::getColumnMeta() [name]

### Description

function mysql_field_name(resource `$result`, int `$field_offset`): string|false

mysql_field_name() retourne le nom du champ de l'index spécifié.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`field_offset`
  La position numérique du champ. `field_offset` commence à `0`. Si `field_offset` n'existe pas, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Le nom du champ de l'index spécifié en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_field_name()

    <?php
    /* Supposons que la table utilisée contienne trois champs :
     *   user_id
     *   username
     *   password.
     */
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
       die('Impossible de se connecter au serveur MySQL : ' . mysql_error());
    }
    $dbname = 'mydb';
    $db_selected = mysql_select_db($dbname, $link);
    if (!$db_selected) {
       die("Impossible de se connecter à la base $dbname: " . mysql_error());
    }
    $res = mysql_query('select * from users', $link);

    echo mysql_field_name($res, 0) . "\n";
    echo mysql_field_name($res, 2);
    ?>

L'exemple ci-dessus va afficher :

    user_id
    password

### Notes

> Note: Les noms des champs retournés par cette fonction sont sensibles à la casse.

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_fieldname()

### Voir aussi

- mysql_field_type() - Retourne le type d'une colonne MySQL spécifique
- mysql_field_len() - Retourne la taille d'un champ de résultat MySQL

# mysql_field_seek

(PHP 4, PHP 5)

mysql_field_seek — Déplace le pointeur de résultat vers une position donnée

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_field_seek()
- PDOStatement::fetch() utilisant le paramètre `cursor_orientation` et le paramètre `offset`

### Description

function mysql_field_seek(resource `$result`, int `$field_offset`): bool

mysql_field_seek() place le pointeur de résultat `result` sur le champ spécifié par sa position `field_offset`. Lors du prochain appel à mysql_fetch_field() qui n'aura pas d'argument d'index de champ, le champ désormais pointé sera retourné.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`field_offset`
  La position numérique du champ. `field_offset` commence à `0`. Si `field_offset` n'existe pas, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- mysql_fetch_field() - Retourne les données enregistrées dans une colonne MySQL sous forme d'objet

# mysql_field_table

(PHP 4, PHP 5)

mysql_field_table — Retourne le nom de la table MySQL où se trouve une colonne

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_field_direct() [table] ou [orgtable]
- PDOStatement::getColumnMeta() [table]

### Description

function mysql_field_table(resource `$result`, int `$field_offset`): string

mysql_field_table() retourne le nom de la table où se trouve la colonne d'offset `field_offset`, dans le résultat MySQL `result`.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`field_offset`
  La position numérique du champ. `field_offset` commence à `0`. Si `field_offset` n'existe pas, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Le nom de la table en cas de succès.

### Exemples

Exemple #1 Exemple avec mysql_field_table()

    <?php

    $query = "SELECT account.*, country.* FROM account, country WHERE country.name = 'Portugal' AND account.country_id = country.id";

    // Récupère le résultat depuis la base de données
    $result = mysql_query($query);

    // Liste le nom de la table et ensuite, le nom du champ
    for ($i = 0; $i < mysql_num_fields($result); ++$i) {
        $table = mysql_field_table($result, $i);
        $field = mysql_field_name($result, $i);

        echo  "$table: $field\n";
    }

    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_fieldtable()

### Voir aussi

- mysql_list_tables() - Liste les tables d'une base de données MySQL

# mysql_field_type

(PHP 4, PHP 5)

mysql_field_type — Retourne le type d'une colonne MySQL spécifique

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_fetch_field_direct() [type]
- PDOStatement::getColumnMeta() [driver:decl_type] ou [pdo_type]

### Description

function mysql_field_type(resource `$result`, int `$field_offset`): string

mysql_field_type() est similaire à la fonction mysql_field_name(). Les arguments sont identiques mais c'est le type de la colonne qui est retourné.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`field_offset`
  La position numérique du champ. `field_offset` commence à `0`. Si `field_offset` n'existe pas, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Le type du champ retourné peut être : `"int"`, `"real"`, `"string"`, `"blob"` ou d'autres, comme détaillé » dans la documentation MySQL.

### Exemples

Exemple #1 Exemple avec mysql_field_type()

    <?php
    mysql_connect("localhost", "mysql_username", "mysql_password");
    mysql_select_db("mysql");
    $result = mysql_query("SELECT * FROM func");
    $fields = mysql_num_fields($result);
    $rows   = mysql_num_rows($result);
    $table  = mysql_field_table($result, 0);
    echo "Votre table '" . $table . "' dispose de " . $fields . " colonnes et " . $rows . " ligne(s)\n";
    echo "Les colonnes sont les suivantes :\n";
    for ($i=0; $i < $fields; $i++) {
        $type  = mysql_field_type($result, $i);
        $name  = mysql_field_name($result, $i);
        $len   = mysql_field_len($result, $i);
        $flags = mysql_field_flags($result, $i);
        echo $type . " " . $name . " " . $len . " " . $flags . "\n";
    }
    mysql_free_result($result);
    mysql_close();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Votre table 'func' dispose de 4 colonnes et 1 ligne(s)
    Les colonnes sont les suivantes :
    string name 64 not_null primary_key binary
    int ret 1 not_null
    string dl 128 not_null
    string type 9 not_null enum

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_fieldtype()

### Voir aussi

- mysql_field_name() - Retourne le nom d'une colonne dans un résultat MySQL
- mysql_field_len() - Retourne la taille d'un champ de résultat MySQL

# mysql_free_result

(PHP 4, PHP 5)

mysql_free_result — Libère le résultat de la mémoire

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_free_result()
- Assignez la valeur `null` à l'objet PDO, ou PDOStatement::closeCursor()

### Description

function mysql_free_result(resource `$result`): bool

mysql_free_result() libère toute la mémoire et les ressources utilisées par la ressource de résultat `result`.

mysql_free_result() n'est à appeler que si on a peur d'utiliser trop de mémoire durant l'exécution du script. Toute la mémoire associée à l'identifiant de résultat sera automatiquement libérée.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Si la valeur passée à l'argument `result` n'est pas une ressource, une erreur de niveau `E_WARNING` sera émise. Il est important de noter que la fonction mysql_query() retourne uniquement une resource pour les requêtes `SELECT`, `SHOW`, `EXPLAIN` et `DESCRIBE`.

### Exemples

Exemple #1 Exemple avec mysql_free_result()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
       echo 'Impossible d\'exécuter la requête : ' . mysql_error();
       exit;
    }
    /* Utilisation du résultat */
    $row = mysql_fetch_assoc($result);

    /* Maintenant, nous libérons le résultat et continuons notre script */
    mysql_free_result($result);

    echo $row['id'];
    echo $row['email'];
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_freeresult()

### Voir aussi

- mysql_query() - Envoie une requête à un serveur MySQL
- is_resource() - Détermine si une variable est une ressource

# mysql_get_client_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_client_info — Lit les informations sur le client MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_get_client_info()
- PDO::getAttribute() avec `attribute` en tant que `PDO::ATTR_CLIENT_VERSION`

### Description

function mysql_get_client_info(): string

mysql_get_client_info() retourne une chaîne qui représente le numéro de version du client utilisé par PHP.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La version du client MySQL.

### Exemples

Exemple #1 Exemple avec mysql_get_client_info()

    <?php
    printf("Détails sur le client MySQL : %s\n", mysql_get_client_info());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Détails sur le client MySQL : 3.23.39

### Voir aussi

- mysql_get_host_info() - Lit les informations sur l'hôte MySQL
- mysql_get_proto_info() - Lit les informations sur le protocole MySQL
- mysql_get_server_info() - Lit les informations sur le serveur MySQL

# mysql_get_host_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_host_info — Lit les informations sur l'hôte MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_get_host_info()
- PDO::getAttribute() avec `attribute` en tant que `PDO::ATTR_CONNECTION_STATUS`

### Description

function mysql_get_host_info(resource `$link_identifier` = NULL): string|false

mysql_get_host_info() retourne une chaîne qui représente le type de connexion utilisé avec la connexion `link_identifier`, y compris le nom du serveur hôte.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne une chaîne décrivant le type de connexion MySQL utilisé pour la connexion ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_get_host_info()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
       die('Impossible de se connecter : ' . mysql_error());
    }
    printf("Informations sur l'hôte MySQL : %s\n", mysql_get_host_info());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Informations sur l'hôte MySQL : Localhost via UNIX socket

### Voir aussi

- mysql_get_client_info() - Lit les informations sur le client MySQL
- mysql_get_proto_info() - Lit les informations sur le protocole MySQL
- mysql_get_server_info() - Lit les informations sur le serveur MySQL

# mysql_get_proto_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_proto_info — Lit les informations sur le protocole MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_get_proto_info()

### Description

function mysql_get_proto_info(resource `$link_identifier` = NULL): int|false

Lit les informations sur le protocole MySQL.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne le protocole MySQL en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_get_proto_info()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
       die('Impossible de se connecter : ' . mysql_error());
    }
    printf("Version du protocole MySQL : %s\n", mysql_get_proto_info());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Version du protocole MySQL : 10

### Voir aussi

- mysql_get_client_info() - Lit les informations sur le client MySQL
- mysql_get_host_info() - Lit les informations sur l'hôte MySQL
- mysql_get_server_info() - Lit les informations sur le serveur MySQL

# mysql_get_server_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_server_info — Lit les informations sur le serveur MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_get_server_info()
- PDO::getAttribute() avec `attribute` en tant que `PDO::ATTR_SERVER_VERSION`

### Description

function mysql_get_server_info(resource `$link_identifier` = NULL): string|false

Lit les informations sur le serveur MySQL.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne la version du serveur MySQL en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_get_server_info()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
    die('Impossible de se connecter à la base : ' . mysql_error());
    }
    printf("Version du serveur MySQL : %s\n", mysql_get_server_info());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Version du serveur MySQL : 4.0.1-alpha

### Voir aussi

- mysql_get_client_info() - Lit les informations sur le client MySQL
- mysql_get_host_info() - Lit les informations sur l'hôte MySQL
- mysql_get_proto_info() - Lit les informations sur le protocole MySQL
- phpversion() - Retourne le numéro de la version courante de PHP

# mysql_info

(PHP 4 >= 4.3.0, PHP 5)

mysql_info — Lit des informations à propos de la dernière requête MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_info()

### Description

function mysql_info(resource `$link_identifier` = NULL): string

Lit des informations à propos de la dernière requête MySQL.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne des informations sur une requête en cas de succès, ou `false` si une erreur survient. Regardez l'exemple ci-dessous pour savoir quelles sortes de requêtes fournissent des informations et avoir un aperçu des informations retournées. Les sortes de requêtes qui ne sont pas listées retournent `false`.

### Exemples

Exemple #1 Requêtes MySQL

Requêtes qui retournent des valeurs. Les nombres ne sont là que pour illustrer l'exemple ; ces valeurs correspondent à la requête.

    INSERT INTO ... SELECT ...
    String format: Records: 23 Duplicates: 0 Warnings: 0
    INSERT INTO ... VALUES (...),(...),(...)...
    String format: Records: 37 Duplicates: 0 Warnings: 0
    LOAD DATA INFILE ...
    String format: Records: 42 Deleted: 0 Skipped: 0 Warnings: 0
    ALTER TABLE
    String format: Records: 60 Duplicates: 0 Warnings: 0
    UPDATE
    String format: Rows matched: 65 Changed: 65 Warnings: 0

### Notes

> Note: mysql_info() retourne une valeur différente de `false` pour les commandes INSERT ... VALUES uniquement si plusieurs jeux de valeurs à insérer ont été spécifiés dans la commande.

### Voir aussi

- mysql_affected_rows() - Retourne le nombre de lignes affectées lors de la dernière opération MySQL
- mysql_insert_id() - Retourne l'identifiant généré par la dernière requête
- mysql_stat() - Retourne le statut courant du serveur MySQL

# mysql_insert_id

(PHP 4, PHP 5)

mysql_insert_id — Retourne l'identifiant généré par la dernière requête

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_insert_id()
- PDO::lastInsertId()

### Description

function mysql_insert_id(resource `$link_identifier` = NULL): int

Retourne le dernier identifiant généré par un champ de type AUTO_INCREMENT, sur la connexion MySQL courante ou sur la connexion spécifiée par `link_identifier` (habituellement, une requête de type INSERT).

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

L'ID généré pour une colonne AUTO_INCREMENT par la dernière requête en cas de succès, `0` si la dernière requête n'a pas généré de valeur AUTO_INCREMENT, ou `false` si aucune connexion MySQL n'a été établie.

### Exemples

Exemple #1 Exemple avec mysql_insert_id()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
    die('Impossible de se connecter : ' . mysql_error());
    }
    mysql_select_db('mydb');

    mysql_query("INSERT INTO mytable (product) values ('kossu')");
    printf("Le dernier enregistrement inséré a l'id %d\n", mysql_insert_id());
    ?>

### Notes

Attention

mysql_insert_id() convertira le type retourné de la fonction native MySQL C API `mysql_insert_id()` en un type `long` (nommé int en PHP). Si la colonne AUTO_INCREMENT a une colonne de type BIGINT (64 bits), la conversion peut résulter en une valeur incorrecte. À la place, utiliser la fonction SQL interne à MySQL LAST_INSERT_ID() dans une requête SQL. Pour plus d'informations sur les valeurs entières maximales en PHP, se reporter à la documentation sur les entiers.

> Note: Parce que mysql_insert_id() agit sur la dernière requête exécutée, il faut s'assurer d'appeler la fonction mysql_insert_id() immédiatement après l'exécution de la requête qui a généré la valeur.

> Note: La fonction MySQL `LAST_INSERT_ID()` contient toujours la valeur AUTO_INCREMENT la plus récente, et n'est pas remise à zéro entre deux requêtes.

### Voir aussi

- mysql_query() - Envoie une requête à un serveur MySQL
- mysql_info() - Lit des informations à propos de la dernière requête MySQL

# mysql_list_dbs

(PHP 4, PHP 5)

mysql_list_dbs — Liste les bases de données disponibles sur le serveur MySQL

Avertissement

Cette fonction était obsolète en PHP 5.4.0, et la totalité de l'extension original MySQL a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser soit l'extension MySQLi, soit l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- Requête SQL : `SHOW DATABASES`

### Description

function mysql_list_dbs(resource `$link_identifier` = NULL): resource

mysql_list_dbs() retournera un identifiant de résultat, qui contiendra les noms des bases de données disponibles sur la connexion MySQL courante ou sur la connexion spécifiée par `link_identifier`.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne une ressource de pointeurs de résultats en cas de succès, ou `false` si une erreur survient. Utiliser la fonction mysql_tablename() pour parcourir ce résultat ou tout autre fonction pour les résultats de table, comme la fonction mysql_fetch_array().

### Exemples

Exemple #1 Exemple avec mysql_list_dbs()

    <?php
    // Utilisation sans mysql_list_dbs()
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $res = mysql_query("SHOW DATABASES");

    while ($row = mysql_fetch_assoc($res)) {
         echo $row['Database'] . "\n";
    }

    // Obsolète depuis PHP 5.4.0
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $db_list = mysql_list_dbs($link);

    while ($row = mysql_fetch_object($db_list)) {
         echo $row->Database . "\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    database1
    database2
    database3

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_listdbs()

### Voir aussi

- mysql_db_name() - Récupère le nom de base de données à l'appel de mysql_list_dbs
- mysql_select_db() - Sélectionne une base de données MySQL

# mysql_list_fields

(PHP 4, PHP 5)

mysql_list_fields — Liste les champs d'une table MySQL

Avertissement

Cette fonction était obsolète en PHP 5.4.0, et la totalité de l'extension original MySQL a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser soit l'extension MySQLi, soit l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- Requête SQL : `SHOW COLUMNS FROM sometable`

### Description

function mysql_list_fields(string `$database_name`, string `$table_name`, resource `$link_identifier` = NULL): resource

Liste les champs de la table MySQL spécifiée.

La fonction mysql_list_fields() est obsolète. Il est préférable d'utiliser la fonction mysql_query() avec comme requête `SHOW COLUMNS FROM table [LIKE 'name']` à la place.

### Liste de paramètres

`database_name`
  Le nom de la base de données qui va être interrogée.
`table_name`
  Le nom de la table qui va être interrogée.
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Une ressource de pointeurs de résultats en cas de succès, ou `false` si une erreur survient.

Le résultat retourné peut être utilisé avec les fonctions mysql_field_flags(), mysql_field_len(), mysql_field_name() et mysql_field_type().

### Exemples

Exemple #1 Exemple d'alternative à mysql_list_fields()

    <?php
    $result = mysql_query("SHOW COLUMNS FROM sometable");
    if (!$result) {
       echo 'Impossible d\'exécuter la requête : ' . mysql_error();
       exit;
    }
    if (mysql_num_rows($result) > 0) {
       while ($row = mysql_fetch_assoc($result)) {
          print_r($row);
       }
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
       [Field] => id
       [Type] => int(7)
       [Null] =>
       [Key] => PRI
       [Default] =>
       [Extra] => auto_increment
    )
    Array
    (
       [Field] => email
       [Type] => varchar(100)
       [Null] =>
       [Key] =>
       [Default] =>
       [Extra] =>
    )

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_listfields()

### Voir aussi

- mysql_field_flags() - Retourne des détails sur une colonne MySQL
- mysql_info() - Lit des informations à propos de la dernière requête MySQL

# mysql_list_processes

(PHP 4 >= 4.3.0, PHP 5)

mysql_list_processes — Liste les processus MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_thread_id()

### Description

function mysql_list_processes(resource `$link_identifier` = NULL): resource|false

Récupère les threads actuels du serveur MySQL.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Une ressource de pointeurs de résultats en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_list_processes()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');

    $result = mysql_list_processes($link);
    while ($row = mysql_fetch_assoc($result)){
       printf("%s %s %s %s %s\n", $row["Id"], $row["Host"], $row["db"],
       $row["Command"], $row["Time"]);
    }
    mysql_free_result($result);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    1 localhost test Processlist 0
    4 localhost mysql sleep 5

### Voir aussi

- mysql_thread_id() - Retourne l'identifiant du thread MySQL courant
- mysql_stat() - Retourne le statut courant du serveur MySQL

# mysql_list_tables

(PHP 4, PHP 5)

mysql_list_tables — Liste les tables d'une base de données MySQL

Avertissement

Cette fonction était obsolète en PHP 4.3.0, et la totalité de l'extension original MySQL a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser soit l'extension MySQLi, soit l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- Requête SQL : `SHOW TABLES FROM dbname`

### Description

function mysql_list_tables(string `$database`, resource `$link_identifier` = NULL): resource|false

Liste les tables d'une base de données MySQL spécifiée.

Cette fonction est obsolète. Il est préférable d'utiliser la fonction mysql_query() pour effectuer la requête SQL `SHOW TABLES [FROM db_name] [LIKE 'pattern']` à la place.

### Liste de paramètres

`database`
  Le nom de la base de données
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Une ressource de pointeurs de résultats en cas de succès ou `false` si une erreur survient.

Utiliser la fonction mysql_tablename() pour parcourir ce pointeur de résultats ou tout autre fonction pour les résultats de tables, comme la fonction mysql_fetch_array().

### Exemples

Exemple #1 Exemple d'alternative à mysql_list_tables()

    <?php
    $dbname = 'mysql_dbname';

    if (!mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
       echo 'Impossible de se connecter à MySQL';
       exit;
    }

    $sql = "SHOW TABLES FROM $dbname";
    $result = mysql_query($sql);

    if (!$result) {
       echo "Erreur DB, impossible de lister les tables\n";
       echo 'Erreur MySQL : ' . mysql_error();
       exit;
    }

    while ($row = mysql_fetch_row($result)) {
       echo "Table : {$row[0]}\n";
    }

    mysql_free_result($result);
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_listtables()

### Voir aussi

- mysql_list_dbs() - Liste les bases de données disponibles sur le serveur MySQL
- mysql_tablename() - Lit le nom de la table qui contient un champ

# mysql_num_fields

(PHP 4, PHP 5)

mysql_num_fields — Retourne le nombre de champs d'un résultat MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_num_fields()
- PDOStatement::columnCount()

### Description

function mysql_num_fields(resource `$result`): int|false

Retourne le nombre de champs d'une requête.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().

### Valeurs de retour

Retourne le nombre de champs d'un jeu de résultat en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_num_fields()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
       echo 'Impossible d\'exécuter la requête : ' . mysql_error();
       exit;
    }

    /* Retourne 2 car id,email === 2 champs */
    echo mysql_num_fields($result);
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_numfields()

### Voir aussi

- mysql_select_db() - Sélectionne une base de données MySQL
- mysql_query() - Envoie une requête à un serveur MySQL
- mysql_fetch_field() - Retourne les données enregistrées dans une colonne MySQL sous forme d'objet
- mysql_num_rows() - Retourne le nombre de lignes d'un résultat MySQL

# mysql_num_rows

(PHP 4, PHP 5)

mysql_num_rows — Retourne le nombre de lignes d'un résultat MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_num_rows()
- mysqli_stmt_num_rows()
- PDOStatement::rowCount()

### Description

function mysql_num_rows(resource `$result`): int|false

Récupère le nombre de lignes d'un jeu de résultat. Cette commande n'est disponible que pour les requêtes comme SELECT ou SHOW qui retournent un jeu de résultats. Pour récupérer le nombre de lignes affectées par une requête INSERT, UPDATE, REPLACE ou DELETE, utiliser la fonction mysql_affected_rows().

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().

### Valeurs de retour

Le nombre de lignes dans un jeu de résultats en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_num_rows()

    <?php

    $link = mysql_connect("localhost", "mysql_user", "mysql_password");
    mysql_select_db("database", $link);

    $result = mysql_query("SELECT * FROM table1", $link);
    $num_rows = mysql_num_rows($result);

    echo "$num_rows Rows\n";

    ?>

### Notes

> Note: Lors de l'utilisation de mysql_unbuffered_query(), mysql_num_rows() ne retournera pas une valeur correcte tant que toutes les lignes du jeu de résultats n'auront pas été récupérées.

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_numrows()

### Voir aussi

- mysql_affected_rows() - Retourne le nombre de lignes affectées lors de la dernière opération MySQL
- mysql_connect() - Ouvre une connexion à un serveur MySQL
- mysql_data_seek() - Déplace le pointeur interne de résultat MySQL
- mysql_select_db() - Sélectionne une base de données MySQL
- mysql_query() - Envoie une requête à un serveur MySQL

# mysql_pconnect

(PHP 4, PHP 5)

mysql_pconnect — Ouvre une connexion persistante à un serveur MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_connect() avec le préfixe d'hôte `p:`
- PDO::__construct() avec `PDO::ATTR_PERSISTENT` comme option du driver

### Description

function mysql_pconnect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
int `$client_flags` = 0
): resource

Ouvre une connexion persistante à un serveur MySQL.

mysql_pconnect() se comporte exactement comme mysql_connect(), mais avec deux différences majeures :

Premièrement, lors de la connexion, la fonction essaie de trouver une connexion persistante déjà ouverte sur cet hôte, avec le même nom d'utilisateur et de mot de passe. Si une telle connexion est trouvée, son identifiant est retourné, sans ouvrir de nouvelle connexion.

Deuxièmement, la connexion au serveur MySQL ne sera pas terminée avec la fin du script. Au lieu de cela, le lien sera conservé pour un prochain accès (mysql_close() ne terminera pas une connexion persistante établie par mysql_pconnect()).

C'est pourquoi ce type de connexion est dite persistante.

### Liste de paramètres

`server`
  Le serveur MySQL. Il peut également comprendre un numéro de port, e.g. `"hostname:port"` ou un chemin vers un socket local e.g. `":/path/to/socket"`. Si la directive PHP mysql.default_host n'est pas définie (défaut), alors, la valeur par défaut est `"localhost:3306"`.
`username`
  Le nom de l'utilisateur. La valeur par défaut est l'utilisateur faisant fonctionner le processus serveur courant.
`password`
  Le mot de passe. La valeur par défaut est un mot de passe vide.
`client_flags`
  Le paramètre `client_flags` peut être une combinaison des constantes suivantes : 128 (active le gestionnaire `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` ou `MYSQL_CLIENT_INTERACTIVE`.

### Valeurs de retour

Retourne un identifiant de lien persistant MySQL en cas de succès, ou `false` si une erreur survient.

### Notes

> Note: À noter que les connexions persistantes ne fonctionnent que si on utilise PHP en version module. Consulter la section sur les connexions persistantes aux bases de données pour plus d'informations.

Avertissement

L'utilisation des connexions persistantes requiert des paramétrages d'Apache et de MySQL pour s'assurer que l'on n'atteindra pas la limite maximale de nombre de connexions simultanées autorisée par MySQL.

### Voir aussi

- mysql_connect() - Ouvre une connexion à un serveur MySQL
- Les connexions persistantes aux bases de données

# mysql_ping

(PHP 4 >= 4.3.0, PHP 5)

mysql_ping — Vérifie la connexion au serveur MySQL, et s'y reconnecte au besoin

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_ping()

### Description

function mysql_ping(resource `$link_identifier` = NULL): bool

mysql_ping() vérifie si la connexion au serveur `link_identifier` fonctionne. Si elle est tombée, une reconnexion automatique est effectuée. Cette fonction est utile pour les scripts qui restent inactifs durant un long moment. Ils peuvent ainsi vérifier si le serveur a fermé la connexion, pour cause d'inactivité.

> Note: La reconnexion automatique est désactivée par défaut depuis la version 5.0.3 et suivants de MySQL.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne `true` si la connexion au serveur MySQL fonctionne, `false` sinon.

### Exemples

Exemple #1 Exemple avec mysql_ping()

    <?php
    set_time_limit(0);

    $conn = mysql_connect('localhost', 'mysqluser', 'mypass');
    $db   = mysql_select_db('mydb');

    /* En supposant que l'exécution de la requête prend beaucoup de temps */
    $result = mysql_query($sql);
    if (!$result) {
       echo 'Requête #1 a échoué, sortie.';
       exit;
    }

    /* S'assure que la connexion est toujours active, sinon, tentative de reconnexion */
    if (!mysql_ping($conn)) {
       echo 'Perte de la connexion, sortie après la requête #1';
       exit;
    }
    mysql_free_result($result);

    /* Donc, la connexion est toujours active, exécutons une autre requête */
    $result2 = mysql_query($sql2);
    ?>

### Voir aussi

- mysql_thread_id() - Retourne l'identifiant du thread MySQL courant
- mysql_list_processes() - Liste les processus MySQL

# mysql_query

(PHP 4, PHP 5)

mysql_query — Envoie une requête à un serveur MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_query()
- PDO::query()

### Description

function mysql_query(string `$query`, resource `$link_identifier` = NULL): mixed

mysql_query() envoie une seule requête (les requêtes multiples ne sont pas prises en charge) à la base de données courante sur le serveur associé avec le `link_identifier` spécifié.

### Liste de paramètres

`query`
  Une requête SQL La chaîne de requête ne doit pas se terminer par un point-virgule. Les données contenues dans la requête doivent être échappées proprement.
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Pour les requêtes du type `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN` et les autres requêtes retournant un jeu de résultats, mysql_query() retourne une resource en cas de succès, ou `false` en cas d'erreur.

Pour les autres types de requêtes, `INSERT`, `UPDATE`, `DELETE`, `DROP`, etc., mysql_query() retourne `true` en cas de succès ou `false` en cas d'erreur.

La ressource de résultat retournée doit être passée à la fonction mysql_fetch_array(), et les autres fonctions permettant d'explorer le résultat des tables, pour accéder aux données retournées.

Utiliser mysql_num_rows() pour trouver le nombre de lignes retournées pour une requête du type `SELECT` ou mysql_affected_rows() pour trouver le nombre de lignes affectées par les requêtes du type `DELETE`, `INSERT`, `REPLACE`, ou `UPDATE`.

mysql_query() échoue et retourne `false` si l'utilisateur n'a pas les autorisations nécessaires pour accéder à la (aux) table(s) référencée(s) par la requête.

### Exemples

Exemple #1 Requête invalide

La requête suivante est syntaxiquement invalide, donc mysql_query() va échouer et retourner `false`.

    <?php
    $result = mysql_query('SELECT * WHERE 1=1');
    if (!$result) {
        die('Requête invalide : ' . mysql_error());
    }

    ?>

Exemple #2 Requête valide

La requête suivante est valide, donc mysql_query() va retourner une resource.

    <?php
    // Ceci peut être demandé par un utilisateur, par exemple :
    $firstname = 'fred';
    $lastname  = 'fox';

    // Formulation de la requête
    // C'est la meilleure façon d'exécuter une requête SQL
    // Pour plus d'exemples, voir mysql_real_escape_string()
    $query = sprintf("SELECT firstname, lastname, address, age FROM friends
        WHERE firstname='%s' AND lastname='%s'",
        mysql_real_escape_string($firstname),
        mysql_real_escape_string($lastname));

    // Exécution de la requête
    $result = mysql_query($query);

    // Vérification du résultat
    // Ceci montre la requête envoyée à MySQL ainsi que l'erreur. Utile pour déboguer.
    if (!$result) {
        $message  = 'Requête invalide : ' . mysql_error() . "\n";
        $message .= 'Requête complète : ' . $query;
        die($message);
    }

    // Utilisation du résultat
    // Tenter d'afficher $result ne vous donnera pas d'informations contenues dans la ressource
    // Une des fonctions MySQL de résultat doit être utilisée
    // Voir aussi mysql_result(), mysql_fetch_array(), mysql_fetch_row(), etc.
    while ($row = mysql_fetch_assoc($result)) {
        echo $row['firstname'];
        echo $row['lastname'];
        echo $row['address'];
        echo $row['age'];
    }

    // Libération des ressources associées au jeu de résultats
    // Ceci est effectué automatiquement à la fin du script
    mysql_free_result($result);
    ?>

### Voir aussi

- mysql_connect() - Ouvre une connexion à un serveur MySQL
- mysql_error() - Retourne le texte associé avec l'erreur générée lors de la dernière requête
- mysql_real_escape_string() - Protège une commande SQL de la présence de caractères spéciaux
- mysql_result() - Retourne un champ d'un résultat MySQL
- mysql_fetch_assoc() - Lit une ligne de résultat MySQL dans un tableau associatif
- mysql_unbuffered_query() - Exécute une requête SQL sans mobiliser les résultats MySQL

# mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — Protège une commande SQL de la présence de caractères spéciaux

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_real_escape_string()
- PDO::quote()

### Description

function mysql_real_escape_string(string `$unescaped_string`, resource `$link_identifier` = NULL): string

mysql_real_escape_string() protège une commande SQL de la chaîne `unescaped_string`, en "échappant" les caractères spéciaux tout en prenant en compte le jeu de caractères courant de la connexion `link_identifier`. Le résultat peut être utilisé sans problème avec la fonction mysql_query(). Si des données binaires doivent être insérées, cette fonction doit être utilisée.

mysql_real_escape_string() appelle la fonction mysql_real_escape_string() de la bibliothèque MySQL qui ajoute un antislash aux caractères suivants : `NULL`, `\x00`, `\n`, `\r`, `\`, `'`, `"` et `\x1a`.

Cette fonction doit toujours (avec quelques exceptions) être utilisée avant d'envoyer la requête à MySQL afin de protéger les données d'injection de caractères pouvant dévoyer cette requête.

Attention

# Sécurité : le jeu de caractères par défaut

Le jeu de caractères doit être défini soit au niveau serveur, soit avec la fonction API mysql_set_charset() pour qu'il ait un effet sur la fonction mysql_real_escape_string(). Voir la section sur les concepts des jeux de caractères pour plus d'informations.

### Liste de paramètres

`unescaped_string`
  La chaîne à échapper.
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne la chaîne échappée, ou `false` si une erreur survient.

### Erreurs / Exceptions

Exécuter cette fonction sans qu'une connexion MySQL ne soit présente va également émettre une erreur PHP de niveau `E_WARNING`. N'exécuter cette fonction qu'avec une connexion MySQL valide.

### Exemples

Exemple #1 Exemple simple avec mysql_real_escape_string()

    <?php
    // Connexion
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
    OR die(mysql_error());

    // Requête
    $query = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
    mysql_real_escape_string($user),
    mysql_real_escape_string($password));
    ?>

Exemple #2 Exemple avec mysql_real_escape_string() et la nécessité de la présence d'une connexion

Cet exemple démontre ce qui survient si une connexion MySQL n'est pas présente lors de l'appel à la fonction.

    <?php
    // Nous n'avons pas de connexion MySQL

    $lastname  = "O'Reilly";
    $_lastname = mysql_real_escape_string($lastname);

    $query = "SELECT * FROM actors WHERE last_name = '$_lastname'";

    var_dump($_lastname);
    var_dump($query);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Warning: mysql_real_escape_string(): No such file or directory in /this/test/script.php on line 5
    Warning: mysql_real_escape_string(): A link to the server could not be established in /this/test/script.php on line 5

    bool(false)
    string(41) "SELECT * FROM actors WHERE last_name = ''"

Exemple #3 Un exemple d'attaque par injection SQL

    <?php
    // Nous ne vérifions pas $_POST['password'], il peut contenir ce que l'utilisateur veut ! Par exemple :
    $_POST['username'] = 'aidan';
    $_POST['password'] = "' OR ''='";

    // Demande à la base de vérifier si un utilisateur correspond
    $query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
    mysql_query($query);

    // Cela signifie que la requête envoyée à MySQL sera :
    echo $query;
    ?>

La requête envoyée à MySQL :

    SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''

Cela permet à n'importe qui de s'identifier sans mot de passe valide.

### Notes

> Note: Une connexion MySQL est nécessaire avant d'utiliser la fonction mysql_real_escape_string(), sinon, une erreur de niveau `E_WARNING` sera générée, et `false` sera retourné. Si `link_identifier` n'est pas défini, la dernière connexion MySQL est utilisée.

> Note: Si cette fonction n'est pas utilisée pour protéger les données, la requête sera vulnérable aux attaques par injection SQL.

> Note: mysql_real_escape_string() n'échappe ni `%`, ni `_`. Ce sont des jokers en MySQL si combinés avec `LIKE`, `GRANT`, ou `REVOKE`.

### Voir aussi

- mysql_set_charset() - Définit le jeu de caractères du client MySQL
- mysql_client_encoding() - Retourne le nom du jeu de caractères utilisé par le client MySQL

# mysql_result

(PHP 4, PHP 5)

mysql_result — Retourne un champ d'un résultat MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_data_seek() en conjonction de mysqli_field_seek() et mysqli_fetch_field()
- PDOStatement::fetchColumn()

### Description

function mysql_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Retourne le contenu d'une cellule d'un jeu de résultats MySQL.

Lorsqu'on travaille sur des résultats de grande taille, il est conseillé d'utiliser une des fonctions qui vont rechercher une ligne entière dans un tableau. Ces fonctions sont NETTEMENT plus rapides. De plus, utiliser un offset numérique est aussi beaucoup plus rapide que spécifier un nom littéral.

### Liste de paramètres

`result`
  La resource de résultat qui vient d'être évaluée. Ce résultat vient de l'appel à la fonction mysql_query().
`row`
  Le numéro de la ligne à récupérer. Les numéros de lignes commencent à `0`.
`field`
  Le nom ou la position du champ à récupérer. Il peut être la position du champ, le nom du champ ou le nom de la table suivi d'un point, suivi du nom du champ (`tablename.fieldname`). Si un alias a été utilisé pour le nom de la colonne (`"selected foo as bar from..."`), utiliser plutôt l'alias. Si ce paramètre n'est pas défini, le premier champ sera récupéré.

### Valeurs de retour

Le contenu d'un champ depuis un jeu de résultats MySQL en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_result()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
       die('Impossible de se connecter : ' . mysql_error());
    }
    if (!mysql_select_db('database_name')) {
        die('Impossible de sélectionner la base de données : ' . mysql_error());
    }
    $result = mysql_query('SELECT name FROM work.employee');
    if (!$result) {
       die('Impossible d\'exécuter la requête :' . mysql_error());
    }
    echo mysql_result($result, 2); // Affiche le nom du troisième employé

    mysql_close($link);
    ?>

### Notes

> Note: Les appels mysql_result() ne devraient pas être mélangés avec d'autres fonctions qui travaillent aussi sur le résultat.

### Voir aussi

- mysql_fetch_row() - Retourne une ligne de résultat MySQL sous la forme d'un tableau
- mysql_fetch_array() - Retourne une ligne de résultat MySQL sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux
- mysql_fetch_assoc() - Lit une ligne de résultat MySQL dans un tableau associatif
- mysql_fetch_object() - Retourne une ligne de résultat MySQL sous la forme d'un objet

# mysql_select_db

(PHP 4, PHP 5)

mysql_select_db — Sélectionne une base de données MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_select_db()
- PDO::__construct() (fait partie du dsn)

### Description

function mysql_select_db(string `$database_name`, resource `$link_identifier` = NULL): bool

Sélectionne une base de données MySQL sur le serveur associé avec le paramètre `link_identifier`. Chaque appel à la fonction mysql_query() sera exécuté sur la base de données active.

### Liste de paramètres

`database_name`
  Le nom de la base de données à sélectionner.
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_select_db()

    <?php

    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
       die('Impossible de se connecter : ' . mysql_error());
    }

    // Rendre la base de données foo, la base courante
    $db_selected = mysql_select_db('foo', $link);
    if (!$db_selected) {
       die ('Impossible de sélectionner la base de données : ' . mysql_error());
    }
    ?>

### Notes

> Note: Pour des raisons de compatibilité ascendante, l'alias obsolète suivant peut être utilisé : mysql_selectdb()

### Voir aussi

- mysql_connect() - Ouvre une connexion à un serveur MySQL
- mysql_pconnect() - Ouvre une connexion persistante à un serveur MySQL
- mysql_query() - Envoie une requête à un serveur MySQL

# mysql_set_charset

(PHP 5 >= 5.2.3)

mysql_set_charset — Définit le jeu de caractères du client MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_set_charset()
- PDO: Ajoute le `charset` à la chaîne de connexion, par exemple `charset=utf8`

### Description

function mysql_set_charset(string `$charset`, resource `$link_identifier` = NULL): bool

Définit le jeu de caractères par défaut pour la connexion courante.

### Liste de paramètres

`charset`
  Un nom de jeu de caractères valide.
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Notes

> Note: Cette fonction requiert MySQL version 5.0.7 ou supérieure.

> Note: C'est la meilleure façon de changer le jeu de caractères. L'utilisation de la fonction mysql_query() pour le définir (avec par exemple `SET NAMES utf8`) n'est pas recommandée. Voir la section Concept sur les jeux de caractères en MySQL pour plus d'informations.

### Voir aussi

- Définir un jeu de caractères dans MySQL
- La liste des » jeux de caractères supportés par MySQL
- mysql_client_encoding() - Retourne le nom du jeu de caractères utilisé par le client MySQL

# mysql_stat

(PHP 4 >= 4.3.0, PHP 5)

mysql_stat — Retourne le statut courant du serveur MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_stat()
- PDO::getAttribute() avec `attribute` en tant que `PDO::ATTR_SERVER_INFO`

### Description

function mysql_stat(resource `$link_identifier` = NULL): string

mysql_stat() retourne le statut courant du serveur MySQL.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Retourne une chaîne contenant le statut de durée de fonctionnement, les threads, les requêtes, les tables ouvertes et sur disque, et le nombre de requêtes par seconde. Pour une liste complète des autres variables de statuts, il faut utiliser la commande SQL `SHOW STATUS`. Si `link_identifier` est invalide, `null` est retourné.

### Exemples

Exemple #1 Exemple avec mysql_stat()

    <?php
    $link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $status = explode('  ', mysql_stat($link));
    print_r($status);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
    [0] => Uptime: 5380
    [1] => Threads: 2
    [2] => Questions: 1321299
    [3] => Slow queries: 0
    [4] => Opens: 26
    [5] => Flush tables: 1
    [6] => Open tables: 17
    [7] => Queries per second avg: 245.595
    )

Exemple #2 Exemple alternatif pour mysql_stat()

    <?php
    $link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $result = mysql_query('SHOW STATUS', $link);
    while ($row = mysql_fetch_assoc($result)) {
      echo $row['Variable_name'] . ' = ' . $row['Value'] . "\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    back_log = 50
    basedir = /usr/local/
    bdb_cache_size = 8388600
    bdb_log_buffer_size = 32768
    bdb_home = /var/db/mysql/
    bdb_max_lock = 10000
    bdb_logdir =
    bdb_shared_data = OFF
    bdb_tmpdir = /var/tmp/
    ...

### Voir aussi

- mysql_get_server_info() - Lit les informations sur le serveur MySQL
- mysql_list_processes() - Liste les processus MySQL

# mysql_tablename

(PHP 4, PHP 5)

mysql_tablename — Lit le nom de la table qui contient un champ

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- Requête SQL : `SHOW TABLES`

### Description

function mysql_tablename(resource `$result`, int `$i`): string|false

Lit le nom de la table depuis le jeu de résultats `result`.

Cette fonction est obsolète. Il est préférable d'utiliser la fonction mysql_query() avec une requête SQL `SHOW TABLES [FROM db_name] [LIKE 'pattern']` à la place.

### Liste de paramètres

`result`
  Un pointeur de résultats retourné par la fonction mysql_list_tables().
`i`
  L'index (numéro ligne/table)

### Valeurs de retour

Le nom de la table en cas de succès ou `false` si une erreur survient.

Utiliser la fonction mysql_tablename() pour parcourir ce pointeur de résultats, ou n'importe quelle fonction pour les résultats de tables comme la fonction mysql_fetch_array().

### Exemples

Exemple #1 Exemple avec mysql_tablename()

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password");
    $result = mysql_list_tables("mydb");
    $num_rows = mysql_num_rows($result);
    for ($i = 0; $i < $num_rows; $i++) {
       echo "Table : ", mysql_tablename($result, $i), "\n";
    }

    mysql_free_result($result);
    ?>

### Notes

> Note: La fonction mysql_num_rows() peut être utilisée pour déterminer le nombre de tables dans le pointeur de résultats.

### Voir aussi

- mysql_list_tables() - Liste les tables d'une base de données MySQL
- mysql_field_table() - Retourne le nom de la table MySQL où se trouve une colonne
- mysql_db_name() - Récupère le nom de base de données à l'appel de mysql_list_dbs

# mysql_thread_id

(PHP 4 >= 4.3.0, PHP 5)

mysql_thread_id — Retourne l'identifiant du thread MySQL courant

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- mysqli_thread_id()

### Description

function mysql_thread_id(resource `$link_identifier` = NULL): int|false

mysql_thread_id() retourne l'identifiant du thread courant. Si la connexion `link_identifier` est perdue et que l'on se reconnecte (avec mysql_ping(), par exemple), alors l'identifiant de thread va changer. Cela signifie qu'il faut le récupérer lorsqu'on en a besoin.

### Liste de paramètres

`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

L'identifiant du thread en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mysql_thread_id()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $thread_id = mysql_thread_id($link);
    if ($thread_id){
       printf("L'identifiant du thread courant est : %d\n", $thread_id);
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    L'identifiant du thread courant est : 73

### Voir aussi

- mysql_ping() - Vérifie la connexion au serveur MySQL, et s'y reconnecte au besoin
- mysql_list_processes() - Liste les processus MySQL

# mysql_unbuffered_query

(PHP 4 >= 4.0.6, PHP 5)

mysql_unbuffered_query — Exécute une requête SQL sans mobiliser les résultats MySQL

Avertissement

Cette extension était obsolète en PHP 5.5.0, et a été supprimée en PHP 7.0.0. À la place, vous pouvez utiliser l'extension MySQLi ou l'extension PDO_MySQL. Voir aussi MySQL : choisir une API du guide. Alternatives à cette fonction :

- Voir : les requêtes mises ou non en mémoire tampon

### Description

function mysql_unbuffered_query(string `$query`, resource `$link_identifier` = NULL): resource

mysql_unbuffered_query() envoie la requête SQL `query` à MySQL sans automatiquement récupérer et mettre en mémoire les lignes du résultat, comme pourrait le faire la fonction mysql_query(). Ce comportement permet d'épargner une grande quantité de mémoire lorsque les requêtes SQL produisent un gros jeu de résultats, et il est possible de commencer à travailler sur le jeu de résultats immédiatement après que la première ligne ait été récupérée : l'on n'a pas à attendre la fin du traitement de la requête SQL. Pour utiliser la fonction mysql_unbuffered_query() lorsque plusieurs connexions à des bases de données sont ouvertes, il faut spécifier le paramètre optionnel `link_identifier` pour identifier la connexion à utiliser.

### Liste de paramètres

`query`
  La requête SQL à exécuter Les données de la requête doivent être proprement échappées.
`link_identifier`
  La connexion MySQL. S'il n'est pas spécifié, la dernière connexion ouverte avec la fonction mysql_connect() sera utilisée. Si une telle connexion n'est pas trouvée, la fonction tentera d'ouvrir une connexion, comme si la fonction mysql_connect() avait été appelée sans argument. Si aucune connexion n'est trouvée ou établie, une alerte de niveau `E_WARNING` sera générée.

### Valeurs de retour

Pour les requêtes SELECT, SHOW, DESCRIBE ou EXPLAIN, mysql_unbuffered_query() retourne une resource en cas de succès, ou `false` si une erreur survient.

Pour les autres types de requêtes, UPDATE, DELETE, DROP, etc, mysql_unbuffered_query() retourne `true` en cas de succès ou `false` si une erreur survient.

### Notes

> Note: L'intérêt de mysql_unbuffered_query() est tempéré par une limitation : mysql_num_rows() et mysql_data_seek() ne fonctionnent pas sur une ressource retournée par mysql_unbuffered_query(), jusqu'à ce que toutes les lignes soient récupérées. Il faut aussi lire tous les résultats d'une première requête exécutée avec mysql_unbuffered_query(), avant de pouvoir en exécuter une autre en utilisant le même `link_identifier`.

### Voir aussi

- mysql_query() - Envoie une requête à un serveur MySQL

## Sommaire

- mysql_affected_rows — Retourne le nombre de lignes affectées lors de la dernière opération MySQL
- mysql_client_encoding — Retourne le nom du jeu de caractères utilisé par le client MySQL
- mysql_close — Ferme la connexion MySQL
- mysql_connect — Ouvre une connexion à un serveur MySQL
- mysql_create_db — Crée une base de données MySQL
- mysql_data_seek — Déplace le pointeur interne de résultat MySQL
- mysql_db_name — Récupère le nom de base de données à l'appel de mysql_list_dbs
- mysql_db_query — Sélectionne une base de données et y exécute une requête
- mysql_drop_db — Efface une base de données MySQL
- mysql_errno — Retourne le numéro d'erreur de la dernière commande MySQL
- mysql_error — Retourne le texte associé avec l'erreur générée lors de la dernière requête
- mysql_escape_string — Protège les caractères spéciaux SQL
- mysql_fetch_array — Retourne une ligne de résultat MySQL sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux
- mysql_fetch_assoc — Lit une ligne de résultat MySQL dans un tableau associatif
- mysql_fetch_field — Retourne les données enregistrées dans une colonne MySQL sous forme d'objet
- mysql_fetch_lengths — Retourne la taille de chaque colonne d'une ligne de résultat MySQL
- mysql_fetch_object — Retourne une ligne de résultat MySQL sous la forme d'un objet
- mysql_fetch_row — Retourne une ligne de résultat MySQL sous la forme d'un tableau
- mysql_field_flags — Retourne des détails sur une colonne MySQL
- mysql_field_len — Retourne la taille d'un champ de résultat MySQL
- mysql_field_name — Retourne le nom d'une colonne dans un résultat MySQL
- mysql_field_seek — Déplace le pointeur de résultat vers une position donnée
- mysql_field_table — Retourne le nom de la table MySQL où se trouve une colonne
- mysql_field_type — Retourne le type d'une colonne MySQL spécifique
- mysql_free_result — Libère le résultat de la mémoire
- mysql_get_client_info — Lit les informations sur le client MySQL
- mysql_get_host_info — Lit les informations sur l'hôte MySQL
- mysql_get_proto_info — Lit les informations sur le protocole MySQL
- mysql_get_server_info — Lit les informations sur le serveur MySQL
- mysql_info — Lit des informations à propos de la dernière requête MySQL
- mysql_insert_id — Retourne l'identifiant généré par la dernière requête
- mysql_list_dbs — Liste les bases de données disponibles sur le serveur MySQL
- mysql_list_fields — Liste les champs d'une table MySQL
- mysql_list_processes — Liste les processus MySQL
- mysql_list_tables — Liste les tables d'une base de données MySQL
- mysql_num_fields — Retourne le nombre de champs d'un résultat MySQL
- mysql_num_rows — Retourne le nombre de lignes d'un résultat MySQL
- mysql_pconnect — Ouvre une connexion persistante à un serveur MySQL
- mysql_ping — Vérifie la connexion au serveur MySQL, et s'y reconnecte au besoin
- mysql_query — Envoie une requête à un serveur MySQL
- mysql_real_escape_string — Protège une commande SQL de la présence de caractères spéciaux
- mysql_result — Retourne un champ d'un résultat MySQL
- mysql_select_db — Sélectionne une base de données MySQL
- mysql_set_charset — Définit le jeu de caractères du client MySQL
- mysql_stat — Retourne le statut courant du serveur MySQL
- mysql_tablename — Lit le nom de la table qui contient un champ
- mysql_thread_id — Retourne l'identifiant du thread MySQL courant
- mysql_unbuffered_query — Exécute une requête SQL sans mobiliser les résultats MySQL

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Historique des modifications
- Constantes pré-définies
- Exemples
  - Exemple avec l'extension MySQL
- Fonctions MySQL
  - mysql_affected_rows — Retourne le nombre de lignes affectées lors de la dernière opération MySQL
  - mysql_client_encoding — Retourne le nom du jeu de caractères utilisé par le client MySQL
  - mysql_close — Ferme la connexion MySQL
  - mysql_connect — Ouvre une connexion à un serveur MySQL
  - mysql_create_db — Crée une base de données MySQL
  - mysql_data_seek — Déplace le pointeur interne de résultat MySQL
  - mysql_db_name — Récupère le nom de base de données à l'appel de mysql_list_dbs
  - mysql_db_query — Sélectionne une base de données et y exécute une requête
  - mysql_drop_db — Efface une base de données MySQL
  - mysql_errno — Retourne le numéro d'erreur de la dernière commande MySQL
  - mysql_error — Retourne le texte associé avec l'erreur générée lors de la dernière requête
  - mysql_escape_string — Protège les caractères spéciaux SQL
  - mysql_fetch_array — Retourne une ligne de résultat MySQL sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux
  - mysql_fetch_assoc — Lit une ligne de résultat MySQL dans un tableau associatif
  - mysql_fetch_field — Retourne les données enregistrées dans une colonne MySQL sous forme d'objet
  - mysql_fetch_lengths — Retourne la taille de chaque colonne d'une ligne de résultat MySQL
  - mysql_fetch_object — Retourne une ligne de résultat MySQL sous la forme d'un objet
  - mysql_fetch_row — Retourne une ligne de résultat MySQL sous la forme d'un tableau
  - mysql_field_flags — Retourne des détails sur une colonne MySQL
  - mysql_field_len — Retourne la taille d'un champ de résultat MySQL
  - mysql_field_name — Retourne le nom d'une colonne dans un résultat MySQL
  - mysql_field_seek — Déplace le pointeur de résultat vers une position donnée
  - mysql_field_table — Retourne le nom de la table MySQL où se trouve une colonne
  - mysql_field_type — Retourne le type d'une colonne MySQL spécifique
  - mysql_free_result — Libère le résultat de la mémoire
  - mysql_get_client_info — Lit les informations sur le client MySQL
  - mysql_get_host_info — Lit les informations sur l'hôte MySQL
  - mysql_get_proto_info — Lit les informations sur le protocole MySQL
  - mysql_get_server_info — Lit les informations sur le serveur MySQL
  - mysql_info — Lit des informations à propos de la dernière requête MySQL
  - mysql_insert_id — Retourne l'identifiant généré par la dernière requête
  - mysql_list_dbs — Liste les bases de données disponibles sur le serveur MySQL
  - mysql_list_fields — Liste les champs d'une table MySQL
  - mysql_list_processes — Liste les processus MySQL
  - mysql_list_tables — Liste les tables d'une base de données MySQL
  - mysql_num_fields — Retourne le nombre de champs d'un résultat MySQL
  - mysql_num_rows — Retourne le nombre de lignes d'un résultat MySQL
  - mysql_pconnect — Ouvre une connexion persistante à un serveur MySQL
  - mysql_ping — Vérifie la connexion au serveur MySQL, et s'y reconnecte au besoin
  - mysql_query — Envoie une requête à un serveur MySQL
  - mysql_real_escape_string — Protège une commande SQL de la présence de caractères spéciaux
  - mysql_result — Retourne un champ d'un résultat MySQL
  - mysql_select_db — Sélectionne une base de données MySQL
  - mysql_set_charset — Définit le jeu de caractères du client MySQL
  - mysql_stat — Retourne le statut courant du serveur MySQL
  - mysql_tablename — Lit le nom de la table qui contient un champ
  - mysql_thread_id — Retourne l'identifiant du thread MySQL courant
  - mysql_unbuffered_query — Exécute une requête SQL sans mobiliser les résultats MySQL

# Le pilote natif MySQL

# Introduction

Le driver natif MySQL est un remplacement pour la bibliothèque cliente MySQL (libmysqlclient). Le driver natif MySQL fait partie des sources officielles PHP depuis la version 5.3.0.

Les extensions de bases de données MySQL, `mysqli` et PDO MYSQL, communiquent avec le serveur MySQL. Dans le passé, ces actions étaient réalisées par l'extension, en utilisant les services fournis par la bibliothèque cliente MySQL. Les extensions étaient ainsi compilées avec la bibliothèque cliente MySQL afin de pouvoir utiliser son protocole client-serveur.

Avec le driver natif MySQL, il existe maintenant une alternative, et les extensions de bases de données MySQL peuvent désormais être compilées avec le driver natif MySQL plutôt qu'avec la bibliothèque cliente MySQL.

Le driver natif MySQL est écrit en C sous la forme d'une extension PHP.

# Introduction

Ce que ce n'est pas

Bien que le pilote natif MySQL soit écrit comme une extension PHP, il est important de noter qu'il ne fournit pas une nouvelle API au programmeur PHP. Les API programmeur sont fournies par l'extension MySQL, `mysqli` et PDO MySQL. Ces extensions peuvent maintenant utiliser les services du pilote natif MySQL pour communiquer avec le serveur MySQL. Ainsi, il ne faut pas considérer le pilote natif MySQL comme une API.

Pourquoi l'utiliser?

Utiliser le pilote natif MySQL offre bon nombre d'avantages par rapport à la bibliothèque MySQL cliente.

L'ancienne bibliothèque MySQL cliente a été écrite par MySQL AB (maintenant partie d'Oracle Corporation) et a donc été publiée sous licence MySQL, ce qui a eu pour conséquence de désactiver le support de MySQL par défaut dans PHP. Vu que le pilote natif MySQL a été développé comme partie intégrante du projet PHP, il est publié sous licence PHP, ce qui résout les soucis de licence problématique dans le passé.

De plus, auparavant, on devait compiler les extensions de base de données MySQL par rapport à une copie de la bibliothèque MySQL cliente, ce qui signifie qu'on devait avoir MySQL d'installé sur la machine sur laquelle l'on compile PHP à partir des sources. Ainsi, quand l'application PHP était exécutée, les extensions MySQL appelaient les fichiers de la bibliothèque MySQL cliente au démarrage, ceux-ci devant être obligatoirement installés sur le système. Avec le pilote natif MySQL, ce n'est plus le cas car il est inclus dans la distribution standard. Ainsi, l'on n'aura plus besoin d'avoir MySQL installé pour compiler PHP ou exécuter des applications PHP faisant appel à une base de données.

Du fait que le pilote natif MySQL soit écrit comme une extension PHP, il est intimement lié au cœur de PHP. Ceci implique une meilleure efficacité, notamment en ce qui concerne l'utilisation de la mémoire, car le pilote utilise l'allocation mémoire de PHP et par conséquent supporte les limites de mémoire. Utiliser le pilote natif MySQL aboutit à des performances égales sinon meilleures qu'avec la bibliothèque cliente MySQL, car l'utilisation de la mémoire est beaucoup plus efficace. Le fait que lors de l'utilisation de la bibliothèque cliente MySQL, chaque enregistrement est stocké deux fois en mémoire alors que le client natif MySQL ne les stocke qu'une fois constitue un bon exemple de bonne gestion de la mémoire.

> Note: Surveillance de l'utilisation mémoire
> En raison du fait que le driver natif MySQL utilise le système de gestion mémoire de PHP, son utilisation mémoire peut être surveillée avec la fonction memory_get_usage(). Ceci n'est pas possible avec la bibliothèque libmysqlclient car elle utilise la fonction C malloc() à la place.

Fonctionnalités spéciales

Le pilote natif MySQL fournit aussi quelques fonctionnalités spéciales non disponibles avec la bibliothèque cliente MySQL, listées ci-dessous :

- Des connexions persistantes améliorées
- La fonction spéciale mysqli_fetch_all()
- Des appels aux statistiques de performance : mysqli_get_client_stats(), mysqli_get_connection_stats()

Les statistiques de performances peuvent s'avérer très utiles pour identifier des goulets d'étranglement de performances.

Le pilote natif MySQL fournit aussi des connexions persistantes lors de son utilisation avec l'extension `mysqli`.

Le support de SSL

Le pilote natif MySQL (MySQL Native Driver) supporte SSL.

Le support du protocole compressé

Le pilote natif MySQL supporte le protocole client/serveur MySQL compressé. L'extension `ext/mysqli` si configurée pour utiliser le pilote natif MySQL peut aussi tirer avantage de cette fonctionnalité. Il est à noter que `PDO_MYSQL` ne supporte PAS la compression lorsqu'utilisé avec mysqlnd.

Support des pipes nommés

Les pipes nommés peuvent être utilisés pour se connecter sous Windows.

# Installation

Installation sous Unix

Pour utiliser le pilote natif MySQL, PHP doit être compilé en spécifiant explicitement que les extensions de base de données MySQL doivent être compilées par rapport à lui. C'est fait grâce aux options de configuration précédant la compilation de PHP en elle-même.

Par exemple, pour compiler l'extension MySQL, `mysqli` et PDO MySQL en utilisant le pilote natif MYSQL, la commande suivante doit être passée :

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    [autres options]

Installation sous Windows

Dans les distributions officielles de PHP pour Windows, le pilote natif MySQL est activé par défaut et aucune configuration supplémentaire n'est nécessaire pour l'utiliser. Toutes les extensions de base de données MySQL l'utiliseront alors.

Support du plugin d'authentification SHA-256

Le driver natif MySQL requiert le chargement de la fonctionnalité OpenSSL de PHP, et l'activation de la connexion à MySQL via des comptes qui utilisent le plugin d'authentification MySQL SHA-256. Par exemple, PHP pourrait être configuré en utilisant la commande suivante :

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    --with-openssl
    [autres options]

Dans Autotools, le support SSL étendu dans `mysqlnd` est activé implicitement lors de la compilation avec l'extension `openssl` en utilisant l'option de configuration --with-openssl. Lors de la compilation sans l'extension `openssl`, l'option de configuration --with-mysqlnd-ssl peut être utilisée pour activer explicitement le support SSL étendu.

### Historique

Version | Description
--- | ---
8.4.0 | L'option de configuration Autotools --with-mysqlnd-ssl a été ajoutée pour activer explicitement le support SSL étendu lors de la compilation sans l'extension `openssl`.

# Configuration à l'exécution

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

Options de configuration de MySQL Native Driver
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
mysqlnd.collect_statistics | "1" | `INI_SYSTEM` |
mysqlnd.collect_memory_statistics | "0" | `INI_SYSTEM` |
mysqlnd.debug | "" | `INI_SYSTEM` |
mysqlnd.log_mask | 0 | `INI_ALL` |
mysqlnd.mempool_default_size | 16000 | `INI_ALL` |
mysqlnd.net_read_timeout | "86400" | `INI_ALL` | Avant PHP 7.2.0 la valeur par défaut était "31536000" et la variabilité était `INI_SYSTEM`
mysqlnd.net_cmd_buffer_size | "4096" | `INI_SYSTEM` |
mysqlnd.net_read_buffer_size | "32768" | `INI_SYSTEM` |
mysqlnd.sha256_server_public_key | "" | `INI_PERDIR` |
mysqlnd.trace_alloc | "" | `INI_SYSTEM` |
mysqlnd.fetch_data_copy | 0 | `INI_ALL` | Supprimé à partir de PHP 8.1.0

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`mysqlnd.collect_statistics` bool
  Active la collecte de différentes statistiques du client auxquelles l'on peut accéder via mysqli_get_client_stats(), mysqli_get_connection_stats(), et qui sont aussi décrites dans la section `mysqlnd` de la sortie de la fonction phpinfo(). Ce paramètre active toutes les statistiques de MySQL Native Driver sauf celles relatives à la gestion de la mémoire.
`mysqlnd.collect_memory_statistics` bool
  Active la collecte de différentes statistiques concernant la mémoire qui peuvent être consultées via mysqli_get_client_stats(), mysqli_get_connection_stats(), et qui sont aussi montrées dans la section `mysqlnd` de la sortie de la fonction phpinfo(). Ce paramètre active les statistiques de gestion de la mémoire parmi les statistiques fournies par MySQL Native Driver.
`mysqlnd.debug` string
  Journalise les communications en provenance de toute extension utilisant `mysqlnd`. Le format de cette directive est `mysqlnd.debug = "option1[,parameter_option1][:option2[,parameter_option2]]"`. Les options de formatage des chaînes sont les suivantes:
  - A[,file] - Ajoute la trace à un fichier. S'assure que les données sont écrites après chaque écriture en fermant puis rouvrant le fichier de trace (lent). Ceci aide à s'assurer que le fichier de traces sera complet même si l'application crash.
  - a[,file] - Ajoute la trace à un fichier.
  - d - Active la sortie depuis les macros DBUG_<N> pour l'état actuel. Peut être suivi d'une liste de mots-clés qui sélectionnent la sortie seulement pour les macros DBUG avec ce mot-clé (filtre). Une liste vide de mot-clé sélectionnera tout.
  - f[,functions] - Limite les actions du débogueur à une liste spécifique de fonctions. Une liste vide fera en sorte que toutes les fonctions seront utilisées.
  - F - Marque chaque ligne de débogage du nom du fichier source contenant la macro causant cette sortie.
  - i - Marque chaque ligne de débogage du PID.
  - L - Marque chaque ligne de débogage du nom du fichier source ainsi que de la ligne de la macro qui cause cette sortie.
  - n - Marque chaque ligne de débogage de la profondeur actuelle de la fonction.
  - o[,file] - Similaire à a[,file] mais écrase les fichiers plutôt que de les compléter.
  - O[,file] - Similaire à A[,file] mais écrase les fichiers plutôt que de les compléter.
  - t[,N] - Active le traçage du flux de contrôle des fonctions. La profondeur maximale est précisée par N, par défaut 200.
  - x - Active le profilage.
  - m - Trace les allocations et désallocations de mémoire.
  Exemple:

      d:t:x:O,/tmp/mysqlnd.trace

  > Note: Cette caractéristique n'est disponible que pour les versions debug de PHP.

`mysqlnd.log_mask` int
  Définit quelle requête sera historisée. Par défaut, vaut 0, ce qui signifie que les logs sont désactivés. Il convient de définir cette option en utilisant un entier, et non une constante PHP. Par exemple, une valeur de 48 (16 + 32) va historiser les requêtes lentes qui utilisent soit 'no good index' (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) soit aucun index du tout (SERVER_QUERY_NO_INDEX_USED = 32). Une valeur de 2043 (1 + 2 + 8 + ... + 1024) historisera tout type de requêtes lentes. Les types sont les suivants : SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2, SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32, SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256, SERVER_STATUS_NO_BACKSLASH_ESCAPES=512, et SERVER_QUERY_WAS_SLOW=1024.
`mysqlnd.mempool_default_size` int
  Taille par défaut de la file d'attente mémoire mysqlnd, utilisée par les jeux de résultats.
`mysqlnd.net_read_timeout` int
  `mysqlnd` et la MySQL Client Library, `libmysqlclient` utilisent des API réseau différentes. `mysqlnd` utilise les flux PHP, alors que `libmysqlclient` utilise sa propre implémentation basée sur le système. PHP, par défaut, utilise un timeout en lecture de 60s. Ceci en utilisant le paramètre de php.ini, `default_socket_timeout`. Ceci s'applique à tous les flux qui ne précisent pas de timeout par défaut. `mysqlnd` n'affecte aucune autre valeur et donc des requêtes longues peuvent se voir déconnectées après `default_socket_timeout` secondes avec comme résultat un message d'erreur 2006 - MySQL Server has gone away. La MySQL Client Library affecte un timeout par défaut de 24 * 3600 secondes (1 jour) et attend les autres timeout, comme ceux de TCP/IP. `mysqlnd` utilise maintenant le même timeout très long. La valeur est configurable via le paramètre php.ini `mysqlnd.net_read_timeout`. `mysqlnd.net_read_timeout` est donc utilisé par toute extension (`ext/mysql`, `ext/mysqli`, `PDO_MySQL`) qui se repose sur `mysqlnd`. `mysqlnd` indique aux flux PHP d'utiliser `mysqlnd.net_read_timeout`. À noter : qu'il peut y avoir des différences subtiles entre `MYSQL_OPT_READ_TIMEOUT` de la MySQL Client Library et les flux PHP, par exemple `MYSQL_OPT_READ_TIMEOUT` est dite fonctionnelle uniquement avec des connexions TCP/IP et, avant MySQL 5.1.2, seulement sous Windows. Les flux PHP, eux, n'ont pas cette limite. Voir la documentation des flux en cas de doute.
`mysqlnd.net_cmd_buffer_size` int
  `mysqlnd` alloue un buffer interne pour le réseau d'une taille de `mysqlnd.net_cmd_buffer_size` (dans php.ini) octets pour chaque connexion. Si une commande du protocole MySQL Client Server, par exemple, `COM_QUERY` (requête normale), ne rentre pas dans le buffer, `mysqlnd` va agrandir celui-ci à la taille requise. A chaque fois que le buffer est agrandi pour une connexion, `command_buffer_too_small` va être incrémenté d'un. Si `mysqlnd` doit agrandir le buffer au-delà de sa taille initiale de `mysqlnd.net_cmd_buffer_size` octets pour presque toutes les connexions, il est recommandé d'alors augmenter cette taille par défaut afin d'éviter les ré-allocations. La taille par défaut du buffer est de 4096 octets. La valeur peut aussi être changée au moyen de `mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)`.
`mysqlnd.net_read_buffer_size` int
  Taille maximale du segment en lecture lors de la lecture du corps d'un paquet de commande MySQL. Le protocole serveur de MySQL encapsule toutes ses commandes dans des paquets. Les paquets consistent en un en-tête court suivi d'un corps contenant les infos. La taille du corps est encodée dans l'en-tête. `mysqlnd` lit le corps sous forme de segments de `MIN(header.size, mysqlnd.net_read_buffer_size)` octets. Si le corps d'un paquet est plus grand que `mysqlnd.net_read_buffer_size` octets, `mysqlnd` doit alors appeler `read()` plusieurs fois. La valeur peut aussi être changée au moyen de `mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)`.
`mysqlnd.sha256_server_public_key` string
  En rapport avec le plugin d'authentification SHA-256. Fichier contenant la clé publique RSA sur serveur MySQL. Les clients peuvent soit omettre de définir une clé publique RSA et spécifier la clé via la directive de configuration PHP, ou bien, définir la clé au moment de l'exécution en utilisant la fonction mysqli_options(). Si aucun fichier de clé publique RSA n'est fourni par le client, alors la clé sera échangée conformément à la procédure du plugin d'authentification standard SHA-256.
`mysqlnd.trace_alloc` string
`mysqlnd.fetch_data_copy` int
  Impose la copie des jeux de résultats depuis les tampons internes vers des variables PHP au lieu d'utiliser le mécanisme par défaut de référence et de copie sur écriture. Se référer aux, notes d'implémentation sur la gestion de mémoire pour plus de détails. Copier les jeux de résultats au lieu d'avoir des variables PHP les référençant permet de libérer au plus tôt la mémoire occupée par les variables PHP. En fonction du code de l'API cliente, les requêtes actuelles et de la taille de leurs jeux de résultats, ceci peut réduire l'empreinte mémoire de mysqlnd. Ne pas activer avec PDO_MySQL. PDO_MySQL ne supporte pas encore ce mode.

  > Note: Supprimé à partir de PHP 8.1.0

# Incompatibilités

MySQL Native Driver est dans la plupart des cas compatible avec MySQL Client Library (`libmysql`). Cette section détaille les incompatibilités.

- Les valeurs de type `bit` sont retournées comme des chaînes binaires (p. ex. "\0" ou "\x1F") avec `libmysql` mais comme des chaînes décimales (p. ex. "0" ou "31") avec `mysqlnd`. Pour être compatible avec les deux bibliothèques, il faut toujours retourner les champs bit comme des nombres, avec des requêtes MySQL comme: `SELECT bit + 0 FROM table`.

# Les connexions persistantes

Utilisation des connexions persistantes

Si `mysqli` est utilisé avec `mysqlnd`, lorsqu'une connexion persistante est créée, il génère un appel `COM_CHANGE_USER` (`mysql_change_user()`) sur le serveur. Ceci permet la re-authentification de la connexion.

Comme l'appel `COM_CHANGE_USER` est assez lourd, il est possible de le désactiver à la compilation. Réutiliser une connexion persistante génèrera alors un appel `COM_PING` (`mysql_ping`) pour tester simplement si la connexion est réutilisable.

L'utilisation de `COM_CHANGE_USER` peut être désactivée avec le drapeau de compilation `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`. Par exemple:

    shell# CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" ./configure --with-mysql=/usr/local/mysql/ --with-mysqli=/usr/local/mysql/bin/mysql_config --with-pdo-mysql=/usr/local/mysql/bin/mysql_config --enable-debug && make clean && make -j6

Ou encore:

    shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT"
    shell# configure --whatever-option
    shell# make clean
    shell# make

Il est à noter que seul `mysqli` avec `mysqlnd` utilise `COM_CHANGE_USER`. Les autres extensions/pilotes utilisent `COM_PING` lors de l'utilisation de la connexion persistante.

# Statistiques

Le pilote natif MySQL contient un support pour la collecte de statistiques sur la communication entre le client et le serveur. Les statistiques collectées sont de deux types principaux :

- Statistiques du client
- Statistiques de la connexion

Lorsque l'extension mysqli est utilisée, ces statistiques peuvent être obtenues via deux appels API :

- mysqli_get_client_stats()
- mysqli_get_connection_stats()

> Note: Les statistiques sont agrégées parmi toutes les extensions qui utilisent le pilote natif MySQL. Par exemple, si l'extension mysqli et le pilote PDO MySQL sont tous deux configurés pour utiliser MySQLnd, alors les appels de fonctions de mysqli et les appels de méthodes de PDO affecteront les statistiques. Il n'y a aucun moyen de savoir combien un certain appel d'API d'une extension qui a été compilée sans le pilote natif MySQL a impacté une certaine statistique.

## Récupération des statistiques

Les statistiques du client peuvent être récupérées en appelant la fonction mysqli_get_client_stats().

Les statistiques de connexion peuvent être récupérées en appelant la fonction mysqli_get_connection_stats().

Les deux fonctions retournent un tableau associatif, où le nom d'une statistique est la clé pour les données statistiques correspondantes.

## Statistiques du pilote natif MySQL

La plupart des statistiques sont associées à une connexion, mais certaines sont associées au processus, auquel cas cela sera mentionné.

Les statistiques suivantes sont produites par le pilote natif MySQL :

Statistiques liées au réseau
`bytes_sent`
  Le nombre d'octets envoyés de PHP au serveur MySQL.
`bytes_received`
  Le nombre d'octets reçus du serveur MySQL.
`packets_sent`
  Le nombre de paquets envoyés par le protocole client-serveur MySQL.
`packets_received`
  Le nombre de paquets reçus du protocole client-serveur MySQL.
`protocol_overhead_in`
  Le surdébit du protocole client-serveur MySQL en octets pour le trafic entrant. Actuellement, seul l'en-tête de paquet (4 octets) est considéré comme un surdébit. `protocol_overhead_in = packets_received * 4`
`protocol_overhead_out`
  Le surdébit du protocole client-serveur MySQL en octets pour le trafic sortant. Actuellement, seul l'en-tête de paquet (4 octets) est considéré comme un surdébit. `protocol_overhead_out = packets_received * 4`
`bytes_received_ok_packet`
  La taille totale en octets des paquets OK du protocole client-serveur MySQL reçus. Les paquets OK peuvent contenir un message d'état. La longueur du message d'état peut varier et donc la taille d'un paquet OK n'est pas fixe.

  > Note: La taille totale en octets inclut la taille de l'en-tête du paquet (4 octets, voir le surdébit du protocole).

`packets_received_ok`
  Le nombre de paquets OK du protocole client-serveur MySQL reçus.
`bytes_received_eof_packet`
  La taille totale en octets des paquets EOF du protocole client-serveur MySQL reçus. La taille d'un paquet EOF peut varier en fonction de la version du serveur. De plus, un paquet EOF peut transporter un message d'erreur.

  > Note: La taille totale en octets inclut la taille de l'en-tête du paquet (4 octets, voir le surdébit du protocole).

`packets_received_eof`
  Le nombre de paquets EOF du protocole client-serveur MySQL reçus. Comme pour d'autres statistiques de paquets, le nombre de paquets sera augmenté même si PHP ne reçoit pas le paquet attendu mais, par exemple, un message d'erreur.
`bytes_received_rset_header_packet`
  La taille totale en octets des en-têtes de paquets de résultats du protocole client-serveur MySQL reçus. La taille de l'en-tête de paquet peut varier en fonction de la charge utile (`LOAD LOCAL INFILE`, `INSERT`, `UPDATE`, `SELECT`, message d'erreur).

  > Note: La taille totale en octets inclut la taille de l'en-tête du paquet (4 octets, voir le surdébit du protocole).

`packets_received_rset_header`
  Le nombre de paquets d'en-têtes de résultats du protocole client-serveur MySQL reçus.
`bytes_received_rset_field_meta_packet`
  La taille totale en octets des paquets de métadonnées de résultats du protocole client-serveur (informations de champ). Bien sûr, la taille varie avec les champs du résultat. Le paquet peut également transporter une erreur ou un paquet EOF en cas de COM_LIST_FIELDS.

  > Note: La taille totale en octets inclut la taille de l'en-tête du paquet (4 octets, voir le surdébit du protocole).

`packets_received_rset_field_meta`
  Le nombre de paquets de métadonnées de résultats du protocole client-serveur reçus (informations de champ).
`bytes_received_rset_row_packet`
  La taille totale en octets des données de ligne de résultats du protocole client-serveur MySQL reçues. Le paquet peut également transporter une erreur ou un paquet EOF. On peut calculer le nombre d'erreurs et de paquets EOF en soustrayant `rows_fetched_from_server_normal` et `rows_fetched_from_server_ps` de `bytes_received_rset_row_packet`.

  > Note: La taille totale en octets inclut la taille de l'en-tête du paquet (4 octets, voir le surdébit du protocole).

`packets_received_rset_row`
  Le nombre de paquets de données de ligne de résultats du protocole client-serveur MySQL reçus.
`bytes_received_prepare_response_packet`
  La taille totale en octets des paquets OK du protocole client-serveur MySQL reçus pour l'initialisation des déclarations préparées (paquets d'initialisation de déclaration préparée). Le paquet peut également transporter une erreur. La taille du paquet dépend de la version de MySQL.

  > Note: La taille totale en octets inclut la taille de l'en-tête du paquet (4 octets, voir le surdébit du protocole).

`packets_received_prepare_response`
  Le nombre de paquets OK du protocole client-serveur MySQL reçus pour l'initialisation des déclarations préparées (paquets d'initialisation de déclaration préparée).
`bytes_received_change_user_packet`
  La taille totale en octets des paquets COM_CHANGE_USER du protocole client-serveur MySQL reçus. Le paquet peut également transporter une erreur ou un paquet EOF.

  > Note: La taille totale en octets inclut la taille de l'en-tête du paquet (4 octets, voir le surdébit du protocole).

`packets_received_change_user`
  Le nombre de paquets COM_CHANGE_USER du protocole client-serveur MySQL reçus.
`packets_sent_command`
  Le nombre de commandes MySQL envoyées par PHP au serveur MySQL. Il n'y a aucun moyen de savoir quelles commandes spécifiques et combien d'entre elles ont été envoyées.
`bytes_received_real_data_normal`
  Le nombre d'octets de charge utile récupérés par le client PHP depuis `mysqlnd` en utilisant le protocole texte. Ceci est la taille des données réelles contenues dans les ensembles de résultats qui ne proviennent pas de déclarations préparées et qui ont été récupérées par le client PHP. Il est à noter que bien qu'un ensemble de résultats complet ait pu être extrait de MySQL par `mysqlnd`, cette statistique ne compte que les données réelles extraites de `mysqlnd` par le client PHP.

  Un exemple de séquence de code qui augmentera la valeur est le suivant :

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->fetch_assoc();
      $res->close();

  Chaque opération de récupération augmentera la valeur.

  Cependant, la statistique ne sera pas augmentée si l'ensemble de résultats est uniquement mis en mémoire tampon sur le client, mais non extrait, comme dans l'exemple suivant :

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->close();

`bytes_received_real_data_ps`
  Le nombre d'octets de charge utile récupérés par le client PHP depuis `mysqlnd` en utilisant le protocole de déclaration préparée. Ceci est la taille des données réelles contenues dans les ensembles de résultats qui proviennent de déclarations préparées et qui ont été récupérées par le client PHP. La valeur ne sera pas augmentée si l'ensemble de résultats n'est pas lu par le client PHP. Il est à noter que bien qu'un ensemble de résultats complet ait pu être extrait de MySQL par `mysqlnd`, cette statistique ne compte que les données réelles extraites de `mysqlnd` par le client PHP. Voir également `bytes_received_real_data_normal`.

Statistiques liées aux ensembles de résultats
`result_set_queries`
  Le nombre de requêtes qui ont généré un ensemble de résultats. Exemple de requêtes qui génèrent un ensemble de résultats : `SELECT`, `SHOW`. La statistique ne sera pas augmentée s'il y a une erreur lors de la lecture de l'en-tête du paquet de l'ensemble de résultats.

  > Note: Cette statistique peut être utilisée comme mesure indirecte du nombre de requêtes que PHP a envoyées à MySQL. Cela peut aider à identifier un client qui provoque une charge élevée sur la base de données.

`non_result_set_queries`
  Le nombre de requêtes qui n'ont pas généré d'ensemble de résultats. Exemples de requêtes qui ne génèrent pas d'ensemble de résultats : `INSERT`, `UPDATE`, `LOAD DATA`. Cette statistique ne sera pas augmentée s'il y a une erreur lors de la lecture de l'en-tête du paquet de l'ensemble de résultats.

  > Note: Cette statistique peut être utilisée comme mesure indirecte du nombre de requêtes que PHP a envoyées à MySQL. Cela peut aider à identifier un client qui provoque une charge élevée sur la base de données.

`no_index_used`
  Le nombre de requêtes qui ont généré un ensemble de résultats mais n'ont pas utilisé d'index. (Voir également l'option de démarrage de mysqld `--log-queries-not-using-indexes`).

  > Note: Ces requêtes peuvent être signalées via une exception en appelant `mysqli_report(MYSQLI_REPORT_INDEX);`. Il est possible de les signaler via un avertissement en appelant `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`bad_index_used`
  Le nombre de requêtes qui ont généré un ensemble de résultats et n'ont pas utilisé un bon index. (Voir également l'option de démarrage de mysqld `--log-slow-queries`).

  > Note: Ces requêtes peuvent être signalées via une exception en appelant `mysqli_report(MYSQLI_REPORT_INDEX);`. Il est possible de les signaler via un avertissement en appelant `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`slow_queries`
  Les déclarations SQL qui ont pris plus de `long_query_time` secondes à s'exécuter et ont nécessité au moins `min_examined_row_limit` lignes à examiner.
  Attention

  Pas signalé via mysqli_report().

`buffered_sets`
  Le nombre d'ensembles de résultats mis en mémoire tampon retournés par des requêtes normales (c'est-à-dire pas via une déclaration préparée).

  Exemple d'appels API qui mettront en mémoire tampon les ensembles de résultats sur le client : mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result()

`unbuffered_sets`
  Le nombre d'ensembles de résultats non mis en mémoire tampon retournés par des requêtes normales (c'est-à-dire pas via une déclaration préparée).

  Exemple d'appels API qui ne mettront pas en mémoire tampon les ensembles de résultats sur le client : mysqli_use_result()

`ps_buffered_sets`
  Le nombre d'ensembles de résultats mis en mémoire tampon retournés par des déclarations préparées.

  Exemple d'appels API qui mettront en mémoire tampon les ensembles de résultats sur le client : mysqli_stmt_store_result()

`ps_unbuffered_sets`
  Le nombre d'ensembles de résultats non mis en mémoire tampon retournés par des déclarations préparées. Par défaut les déclarations préparées ne sont pas mises en mémoire tampon, ainsi la plupart des déclarations préparées seront comptabilisées dans cette statistique.
`flushed_normal_sets`
  Le nombre de jeux de résultats retournés par des requêtes normales (c'est-à-dire pas via une déclaration préparée) avec des données non lues qui ont été silencieusement vidées.

  > Note: Le vidage se produit uniquement avec des ensembles de résultats non mis en mémoire tampon. Les ensembles de résultats non mis en mémoire tampon doivent être récupérés complètement avant qu'une nouvelle requête puisse être exécutée sur la connexion, sinon MySQL lancera une erreur. Si l'application ne récupère pas toutes les lignes d'un ensemble de résultats non mis en mémoire tampon, mysqlnd récupère implicitement l'ensemble de résultats pour effacer la ligne. Voir également `rows_skipped_normal`, `rows_skipped_ps`.

  > Quelques causes possibles pour un vidage implicite :

  > - Application cliente défectueuse
  > - Client s'est arrêté de lire après avoir trouvé ce qu'il cherchait mais a fait calculer à MySQL plus de lignes que nécessaire
  > - L'application client s'est arrêtée de manière inattendue

`flushed_ps_sets`
  Le nombre de jeux de résultats retournés par des déclarations préparées avec des données non lues qui ont été silencieusement vidées.

  > Note: Le vidage se produit uniquement avec des ensembles de résultats non mis en mémoire tampon. Les ensembles de résultats non mis en mémoire tampon doivent être récupérés complètement avant qu'une nouvelle requête puisse être exécutée sur la connexion, sinon MySQL lancera une erreur. Si l'application ne récupère pas toutes les lignes d'un ensemble de résultats non mis en mémoire tampon, mysqlnd récupère implicitement l'ensemble de résultats pour effacer la ligne. Voir également `rows_skipped_normal`, `rows_skipped_ps`.

  > Quelques causes possibles pour un vidage implicite :

  > - Application cliente défectueuse
  > - Client s'est arrêté de lire après avoir trouvé ce qu'il cherchait mais a fait calculer à MySQL plus de lignes que nécessaire
  > - L'application client s'est arrêtée de manière inattendue

`ps_prepared_never_executed`
  Le nombre de déclarations préparées préparées mais jamais exécutées.
`ps_prepared_once_executed`
  Le nombre de déclarations préparées exécutées une seule fois.
`rows_fetched_from_server_normal`
`rows_fetched_from_server_ps`
  Le nombre total de lignes d'ensemble de résultats récupérées du serveur. Cela inclut les lignes qui n'ont pas été lues par le client mais ont été implicitement récupérées en raison d'ensembles de résultats non mis en mémoire tampon vidés. Voir également `packets_received_rset_row`.
`rows_buffered_from_client_normal`
  Le nombre total de lignes mises en mémoire tampon provenant d'une requête normale. Ceci est le nombre de lignes qui ont été récupérées de MySQL et mises en mémoire tampon sur le client.

  Exemple de requêtes qui mettront en mémoire tampon les ensembles de résultats :

  - mysqli_query()
  - mysqli_store_result()
`rows_buffered_from_client_ps`
  Equivalent à `rows_buffered_from_client_normal` mais pour les déclarations préparées.
`rows_fetched_from_client_normal_buffered`
  Le nombre total de lignes récupérées par le client à partir d'un ensemble de résultats mis en mémoire tampon créé par une requête normale.
`rows_fetched_from_client_ps_buffered`
  Le nombre total de lignes récupérées par le client à partir d'un ensemble de résultats mis en mémoire tampon créé par une déclaration préparée.
`rows_fetched_from_client_normal_unbuffered`
  Le nombre total de lignes récupérées par le client à partir d'un ensemble de résultats non mis en mémoire tampon créé par une requête normale.
`rows_fetched_from_client_ps_unbuffered`
  Le nombre total de lignes récupérées par le client à partir d'un ensemble de résultats non mis en mémoire tampon créé par une déclaration préparée.
`rows_fetched_from_client_ps_cursor`
  Le nombre total de lignes récupérées par le client à partir d'un curseur créé par une déclaration préparée.
`rows_skipped_normal`
`rows_skipped_ps`
  Réservé pour une utilisation future (actuellement non pris en charge).
`copy_on_write_saved`
`copy_on_write_performed`
  Ceci est une statistique de portée de processus. Avec mysqlnd, les variables retournées par les extensions pointent vers mysqlnd tampons de résultats internes. Si les données ne sont pas modifiées, les données extraites ne sont conservées qu'une seule fois en mémoire. Cependant, toute modification des données nécessitera à mysqlnd de réaliser une opération de copie-sur-écriture.
`explicit_free_result`
`implicit_free_result`
  Ceci est une statistique de portée de connexion et de processus. Le nombre total de résultats libérés.
`proto_text_fetched_null`
  Le nombre total de colonnes de type `MYSQL_TYPE_NULL` récupérées à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_null`
  Le nombre total de colonnes de type `MYSQL_TYPE_NULL` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_bit`
  Le nombre total de colonnes de type `MYSQL_TYPE_BIT` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_bit`
  Le nombre total de colonnes de type `MYSQL_TYPE_BIT` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_tinyint`
  Le nombre total de colonnes de type `MYSQL_TYPE_TINY` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_tinyint`
  Le nombre total de colonnes de type `MYSQL_TYPE_TINY` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_short`
  Le nombre total de colonnes de type `MYSQL_TYPE_SHORT` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_short`
  Le nombre total de colonnes de type `MYSQL_TYPE_SHORT` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_int24`
  Le nombre total de colonnes de type `MYSQL_TYPE_INT24` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_int24`
  Le nombre total de colonnes de type `MYSQL_TYPE_INT24` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_int`
  Le nombre total de colonnes de type `MYSQL_TYPE_LONG` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_int`
  Le nombre total de colonnes de type `MYSQL_TYPE_LONG` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_bigint`
  Le nombre total de colonnes de type `MYSQL_TYPE_LONGLONG` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_bigint`
  Le nombre total de colonnes de type `MYSQL_TYPE_LONGLONG` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_decimal`
  Le nombre total de colonnes de type `MYSQL_TYPE_DECIMAL`, ou `MYSQL_TYPE_NEWDECIMAL` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_decimal`
  Le nombre total de colonnes de type `MYSQL_TYPE_DECIMAL`, ou `MYSQL_TYPE_NEWDECIMAL` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_float`
  Le nombre total de colonnes de type `MYSQL_TYPE_FLOAT` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_float`
  Le nombre total de colonnes de type `MYSQL_TYPE_FLOAT` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_double`
  Le nombre total de colonnes de type `MYSQL_TYPE_DOUBLE` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_double`
  Le nombre total de colonnes de type `MYSQL_TYPE_DOUBLE` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_date`
  Le nombre total de colonnes de type `MYSQL_TYPE_DATE`, ou `MYSQL_TYPE_NEWDATE` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_date`
  Le nombre total de colonnes de type `MYSQL_TYPE_DATE`, ou `MYSQL_TYPE_NEWDATE` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_year`
  Le nombre total de colonnes de type `MYSQL_TYPE_YEAR` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_year`
  Le nombre total de colonnes de type `MYSQL_TYPE_YEAR` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_time`
  Le nombre total de colonnes de type `MYSQL_TYPE_TIME` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_time`
  Le nombre total de colonnes de type `MYSQL_TYPE_TIME` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_datetime`
  Le nombre total de colonnes de type `MYSQL_TYPE_DATETIME` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_datetime`
  Le nombre total de colonnes de type `MYSQL_TYPE_DATETIME` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_timestamp`
  Le nombre total de colonnes de type `MYSQL_TYPE_TIMESTAMP` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_timestamp`
  Le nombre total de colonnes de type `MYSQL_TYPE_TIMESTAMP` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_string`
  Le nombre total de colonnes de type `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING`, ou `MYSQL_TYPE_VARCHAR` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_string`
  Le nombre total de colonnes de type `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING`, ou `MYSQL_TYPE_VARCHAR` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_blob`
  Le nombre total de colonnes de type `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, ou `MYSQL_TYPE_BLOB` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_blob`
  Le nombre total de colonnes de type `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB`, ou `MYSQL_TYPE_BLOB` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_enum`
  Le nombre total de colonnes de type `MYSQL_TYPE_ENUM` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_enum`
  Le nombre total de colonnes de type `MYSQL_TYPE_ENUM` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_set`
  Le nombre total de colonnes de type `MYSQL_TYPE_SET` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_set`
  Le nombre total de colonnes de type `MYSQL_TYPE_SET` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_geometry`
  Le nombre total de colonnes de type `MYSQL_TYPE_GEOMETRY` récupéré à partir d'une requête normale (protocole texte MySQL).
`proto_binary_fetched_geometry`
  Le nombre total de colonnes de type `MYSQL_TYPE_GEOMETRY` récupéré à partir d'une déclaration préparée (protocole binaire MySQL).
`proto_text_fetched_other`
  Le nombre total de colonnes de types `MYSQL_TYPE_*` non listés précédemment récupéré à partir d'une requête normale (protocole texte MySQL).

  > Note: Dans la théorie, cela devrait toujours être `0`.

`proto_binary_fetched_other`
  Le nombre total de colonnes de type `MYSQL_TYPE_*` non listés précédemment récupéré à partir d'une déclaration préparée (protocole binaire MySQL).

  > Note: Dans la théorie, cela devrait toujours être `0`.

Statistiques liées aux connexions
`connect_success`
  Le nombre total de tentatives de connexion réussies.

  > Note: `connect_success` contient la somme des tentatives de connexion réussies persistantes et non persistantes. Par conséquent, le nombre de tentatives de connexion non persistantes réussies est `connect_success - pconnect_success`.

`pconnect_success`
  Le nombre total de tentatives de connexion persistantes réussies.
`connect_failure`
  Le nombre total de tentatives de connexion échouées.
`reconnect`
  Ceci est une statistique de portée de processus.
`active_connections`
  Ceci est une statistique de portée de processus. Le nombre total de connexions persistantes et non persistantes actives.

  > Note: Le nombre total de connexions non persistantes actives est `active_connections - active_persistent_connections`.

`active_persistent_connections`
  Ceci est une statistique de portée de processus. Le nombre total de connexions persistantes actives.
`explicit_close`
  Le nombre total de connexions explicitement fermées.

  Exemple #1 Exemples de fragments de code qui provoquent une fermeture explicite

  -     $link = new mysqli(/* ... */);
        $link->close(/* ... */);

  -     $link = new mysqli(/* ... */);
        $link->connect(/* ... */);

`implicit_close`
  Le nombre total de connexions implicitement fermées.

  Exemple #2 Exemples de fragments de code qui provoquent une fermeture implicite

  -     $link = new mysqli(/* ... */);
        $link->real_connect(/* ... */);

  - `unset($link)`
  - Connexion persistante: une connexion groupée a été créée avec real_connect et il peut y avoir des options inconnues définies - fermer implicitement pour éviter de retourner une connexion avec des options inconnues
  - Connexion persistante: ping/change_user échoue et ext/mysqli ferme la connexion
  - Fin de l'exécution du script : fermeture des connexions qui n'ont pas été fermées par l'utilisateur
`disconnect_close`
  Échecs de connexion indiqués par l'appel à l'API C `mysql_real_connect` lors d'une tentative d'établissement de connexion.
`in_middle_of_command_close`
  Ceci est une statistique de portée de processus. Une connexion a été fermée au milieu de l'exécution d'une commande (ensembles de résultats non récupérés, après l'envoi d'une requête et avant de récupérer une réponse, pendant la récupération de données, pendant le transfert de données avec LOAD DATA).
  Avertissement

  Sauf si des requêtes asynchrones sont utilisées, cela ne devrait se produire que si l'application PHP s'est terminée de manière inattendue et que PHP ferme automatiquement la connexion.

`init_command_executed_count`
  Le nombre total d'exécutions de commandes d'initialisation. Par exemple: `mysqli_options(MYSQLI_INIT_COMMAND , $value)`. Le nombre d'exécutions réussies est `init_command_executed_count - init_command_failed_count`.
`init_command_failed_count`
  Le nombre total d'échecs d'exécution de commandes d'initialisation.

`COM_*` Statistiques liées aux commandes
`com_quit`
`com_init_db`
`com_query`
`com_field_list`
`com_create_db`
`com_drop_db`
`com_refresh`
`com_shutdown`
`com_statistics`
`com_process_info`
`com_connect`
`com_process_kill`
`com_debug`
`com_ping`
`com_time`
`com_delayed_insert`
`com_change_user`
`com_binlog_dump`
`com_table_dump`
`com_connect_out`
`com_register_slave`
`com_stmt_prepare`
`com_stmt_execute`
`com_stmt_send_long_data`
`com_stmt_close`
`com_stmt_reset`
`com_stmt_set_option`
`com_stmt_fetch`
`com_daemon`
  Le nombre total de tentatives d'envoi d'une certaine commande `COM_*` de PHP à MySQL. La statistique est incrémentée après avoir vérifié la ligne et immédiatement avant d'envoyer le paquet de protocole client serveur MySQL correspondant.
  Attention

  Si MySQLnd échoue à envoyer le paquet sur le réseau, les statistiques ne seront pas décrémentées. En cas d'échec, MySQLnd émet un avertissement PHP Error while sending %s packet. PID=%d.

  Exemple #3 Exemples d'utilisation

  - Vérifier si PHP envoie certaines commandes à MySQL, par exemple, vérifier si un client envoie `COM_PROCESS_KILL`
  - Calculer le nombre moyen d'exécutions de commandes préparées en comparant `COM_EXECUTE` avec `COM_PREPARE`
  - Vérifier si PHP a exécuté des déclarations SQL non préparées en vérifiant si `COM_QUERY` est zéro
  - Identifier les scripts PHP qui exécutent un nombre excessif de déclarations SQL en vérifiant `COM_QUERY` et `COM_EXECUTE`

Statistiques diverses
`explicit_stmt_close`
`implicit_stmt_close`
  Ceci est une statistique de portée de processus. Le nombre total de déclarations préparées explicitement fermées.

  > Note: Une déclaration préparée est toujours explicitement fermée. La seule fois où elle est fermée implicitement est lorsque sa préparation échoue.

`mem_emalloc_count`
`mem_emalloc_ammount`
`mem_ecalloc_count`
`mem_ecalloc_ammount`
`mem_realloc_count`
`mem_realloc_ammount`
`mem_efree_count`
`mem_malloc_count`
`mem_malloc_ammount`
`mem_calloc_count`
`mem_calloc_ammount`
`mem_ealloc_count`
`mem_ealloc_ammount`
`mem_free_count`
  Ceci est une statistique de portée de processus. Appelle la gestion de la mémoire.
`command_buffer_too_small`
  Le nombre d'extensions de tampon de commande réseau lors de l'envoi de commandes de PHP à MySQL. MySQLnd alloue un tampon de commande/réseau interne de mysqlnd.net_cmd_buffer_size octets pour chaque connexion. Si un protocole de commande de serveur MySQL, par exemple `COM_QUERY` (requête normale), ne rentre pas dans le tampon, mysqlnd étendra le tampon à ce qui est nécessaire pour envoyer la commande. Chaque fois que le tampon est étendu pour une connexion `command_buffer_too_small` sera incrémenté d'un. Si mysql est obligé de faire croître le tampon au-delà de sa taille initiale de mysqlnd.net_cmd_buffer_size octets pour presque chaque connexion, des considérations pour augmenter la taille par défaut devraient être prises en compte pour éviter les réallocations.
`connection_reused`
  Le nombre total de fois qu'une connexion persistante a été réutilisée.

# Notes

Cette section fournit une compilation de notes diverses sur l'utilisation du pilote natif MySQL.

- Utiliser `mysqlnd` signifie utiliser les flux PHP pour la connexion sous-jacente. Avec `mysqlnd`, la documentation des flux PHP (Flux) devrait être consultée en ce qui concerne les notions comme les timeouts et non pas la documentation de la bibliothèque cliente MySQL.

# Gestion de la mémoire

Introduction

Le driver natif MySQL gère la mémoire d'une façon différente que la bibliothèque client MySQL. Les bibliothèques diffèrent dans la façon dont la mémoire est allouée et libérée, dans la façon dont la mémoire est allouée par morceau pendant la lecture des résultats depuis MySQL, quelles options de débogage et de développement existent, et comment les résultats lus depuis MySQL sont liés aux variables utilisateurs PHP.

Les notes suivantes sont une introduction et un résumé destinés aux utilisateurs intéressés par la compréhension du driver natif MySQL d'un point de vue du code C.

Fonctions utilisées dans la gestion mémoire

Toutes les allocations et les dé-allocations sont réalisées en utilisant les fonctions de gestion de la mémoire de PHP. Toutefois, la consommation mémoire de mysqlnd peut être surveillée en utilisant des appels APIs PHP, comme memory_get_usage(). En raison du fait que la mémoire est allouée et libérée en utilisant la gestion mémoire de PHP, les modifications peuvent ne pas être immédiatement visibles au niveau du système d'exploitation. Le gestionnaire de mémoire PHP fonctionne comme un proxy qui peut avoir un peu de délai dans la libération mémoire du système. Aussi, la comparaison de l'utilisation mémoire du driver natif MySQL et de la bibliothèque cliente MySQL devient difficile. La bibliothèque cliente MySQL appelle directement le gestionnaire mémoire du système d'exploitation, et donc, les effets peuvent être vus immédiatement au niveau du système d'exploitation.

Toutes les limitations mémoire réalisées par PHP affectent également le driver natif MySQL. Ceci peut causer des erreurs de dépassement mémoire lors de la récupération de jeux de résultats trop importants, excédant la taille de la mémoire restante disponible pour PHP. En raison du fait que la bibliothèque cliente MySQL n'utilise pas les fonctions de gestion mémoire de PHP, elle ne prend en compte aucune limitation mémoire définie par PHP. Lors de l'utilisation de la bibliothèque cliente MySQL, suivant le modèle de déploiement, l'empreinte mémoire du processus PHP peut s'accroitre et dépasser la limite mémoire imposée par PHP. De plus, les scripts PHP peuvent analyser des jeux de résultats plus importants, allouant ainsi plus de mémoire pour le jeu de résultats que le contrôle du moteur PHP ne l'autorise.

Les fonctions de gestion mémoire de PHP sont appelées par le driver natif MySQL via un gestionnaire léger. Entre autres, ce gestionnaire rend le débogage facile.

Gestion des jeux de résultats

Les différents serveurs MySQL et les différents clients APIs se différencient suivant la mise en mémoire tampon ou non des jeux de résultats. Les jeux de résultats qui ne sont pas mis en mémoire tampon sont transférés ligne par ligne depuis MySQL vers le client, et le client va parcourir les résultats. Les résultats qui sont mis en mémoire tampon sont récupérés en entier par la bibliothèque cliente avant de les passer au client.

Le driver natif MySQL utilise des flux PHP pour la communication réseau avec le serveur MySQL. Les résultats envoyés par MySQL sont récupérés depuis la mémoire tampon des flux réseau PHP dans la mémoire tampon de résultats de mysqlnd. La mémoire tampon de résultats est composée de zvals. Dans une étape suivante, les résultats sont rendus disponibles au script PHP. Le transfert final depuis la mémoire tampon des résultats dans les variables PHP impacte la consommation mémoire et cela devient très visible lors de l'utilisation de jeux de résultats mis en mémoire tampon.

Par défaut, le driver natif MySQL tente de ne pas conserver en mémoire deux fois les résultats mis en mémoire tampon. Les résultats sont conservés qu'une seule fois dans la mémoire tampon interne de résultats, ainsi que dans leur zvals. Lorsque les résultats sont récupérés dans les variables PHP par le script PHP, les variables vont référencer la mémoire tampon interne de résultats. Les résultats de requêtes de base de données ne sont pas copiés et sont conservés en mémoire seulement une fois. Lorsqu'un utilisateur modifie le contenu d'une variable contenant un résultat de base de données, une opération de copie sur écriture doit être effectuée pour éviter de changer la mémoire tampon interne de résultat référencée. Le contenu de la mémoire tampon ne doit pas être modifié parce que l'utilisateur peut décider de lire le jeu de résultat une seconde fois. L'opération de copie sur écriture est implémentée en utilisant un gestionnaire de liste de référence additionnel, ainsi que l'utilisation des compteurs de référence zvals standard. L'opération de copie sur écriture doit également être effectuée si l'utilisateur lit un jeu de résultats dans les variables PHP et libère un jeu de résultat avant que les variables ne soient supprimées.

D'une manière générale, ce mécanisme fonctionne bien pour les scripts qui lisent un jeu de résultats une seule fois, et ne modifient pas les variables contenant les résultats. Son inconvénient majeur est la surcharge mémoire causée par le gestionnaire de référence additionnel, qui vient principalement du fait que les variables utilisateurs contenant les résultats ne peuvent être entièrement libérées tant que le gestionnaire de référence mysqlnd n'arrête pas de les référencer. Le driver natif MySQL supprime la référence aux variables utilisateurs lorsque le jeu de résultat est libéré ou qu'une opération de copie sur écriture est effectuée. Un observateur peut voir la consommation mémoire totale croître tant que le jeu de résultat n'est pas libéré. Utiliser les statistiques pour vérifier si un script libère le jeu de résultats explicitement, ou si le driver le libère implicitement, faisant ainsi que la mémoire soit utilisée plus longtemps que nécessaire. Les statistiques peuvent aussi aider à voir les opérations de copie sur écriture.

Un script PHP lisant beaucoup de petites lignes d'un jeu de résultat mis en mémoire tampon en utilisant des lignes de code comme `while ($row = $res->fetch_assoc()) { ... }` peut optimiser la consommation mémoire en demandant une copie plutôt que des références. Malgré le fait que demander des copies signifie conserver deux fois le résultat en mémoire, cela autorise PHP à libérer la copie contenue dans `$row` sachant que le jeu de résultats est en train d'être parcouru et avant de libérer le jeu de résultats lui-même. Sur un serveur chargé, l'optimisation de l'utilisation mémoire peut améliorer la performance système globale bien que pour un script individuel, l'approche de la copie peut être plus lente en raison des opérations supplémentaires d'allocation et de copie mémoire.

Surveillance et débogage

Il existe plusieurs façons de surveiller l'utilisation mémoire du driver natif MySQL. Si le but est d'obtenir une vue rapide haut niveau, ou de vérifier la mémoire efficiente des scripts PHP, alors vérifiez les statistiques collectées par la bibliothèque. Elles permettent, par exemple, de voir les requêtes SQL qui génèrent plus de résultats que d'analyses par un script PHP.

La trace de débogage dans l'historisation peut être configurée pour enregistrer les appels au gestionnaire mémoire. Ceci peut aider à voir quand la mémoire est allouée ou libérée. Cependant, la taille des morceaux mémoire demandés peut ne pas y être listée.

Les versions récentes du driver natif MySQL tentent d'émuler des situations de dépassement mémoire aléatoire. Ceci est seulement utile aux développeurs C de la bibliothèque, ou aux développeurs du plugin mysqlnd. Veuillez chercher dans le code source pour les options de configuration de PHP correspondant, ainsi que pour obtenir plus de détails sur ce mécanisme. Cette fonctionnalité est considérée comme privée, et peut être modifiée à tout moment sans aucun avertissement.

# API du plugin du driver natif MySQL

## Sommaire

- Comparaison des plugins mysqlnd avec proxy MySQL
- Obtenir l'API du plugin mysqlnd
- Architecture du plugin du driver natif
- L'API du plugin mysqlnd
- Bien commencer la compilation d'un plugin mysqlnd

L'API du plugin du driver natif MySQL est une fonctionnalité du driver natif MySQL, ou `mysqlnd`. Le plugin `Mysqlnd` opère sur la couche entre les applications PHP et le serveur MySQL. Il est comparable à un proxy MySQL. Un proxy MySQL opère sur une couche entre toutes les applications clientes MySQL, par exemple, une application PHP et un serveur MySQL. Le plugin `Mysqlnd` peut entreprendre des tâches typiques de proxy MySQL comme l'équilibrage de charge, ainsi que le suivi et l'optimisation des performances. En raison d'une architecture et d'une localisation différente, le plugin `mysqlnd` n'a pas tous les inconvénients d'un proxy MySQL. Par exemple, avec le plugin, il n'y a pas qu'un seul point d'échec, pas de serveur de proxy dédié à déployer, et pas de nouveau langage à apprendre (Lua).

Un plugin `mysqlnd` peut être exécuté comme une extension à `mysqlnd`. Un plugin peut intercepter la majorité des fonctions `mysqlnd`. Les fonctions `mysqlnd` sont appelées par l'extension PHP MySQL comme `ext/mysql`, `ext/mysqli`, et `PDO_MYSQL`. Comme résultat, il est possible pour un plugin `mysqlnd` d'intercepter tous les appels effectués par ces extensions depuis une application cliente.

Les appels aux fonctions internes `mysqlnd` peuvent également être interceptés ou remplacés. Il n'y a aucune restriction sur la manipulation des tables de fonctions internes `mysqlnd`. Il est possible de définir des actions pour faire que lorsque certaines fonctions `mysqlnd` sont appelées par l'extension qui utilise `mysqlnd`, l'appel est redirigé vers la fonction appropriée du plugin `mysqlnd`. La possibilité de manipuler les tables de fonctions internes `mysqlnd` dans ce sens permet un maximum de flexibilité.

Le plugin `Mysqlnd` est en fait, une extension PHP, écrite en C, qui utilise l'API du plugin `mysqlnd` (qui est compilé dans le driver natif MySQL, `mysqlnd`). Le plugin peut être à 100% transparent pour les applications PHP. Aucune modification aux applications n'est nécessaire car le plugin opère sur une couche différente. Le plugin `mysqlnd` peut être utilisé dans une couche en dessous de `mysqlnd`.

La liste suivante représente quelques applications possibles du plugin `mysqlnd`.

- L'équilibrage de charge.
  - Séparation des lectures et des écritures. Un exemple de cette fonctionnalité est l'extension PECL/mysqlnd_ms (Maître/esclave). Cette extension sépare les requêtes de lecture et d'écriture pour une configuration de réplication.
  - Basculement
  - Round-Robin, le moins chargé
- Surveillance
  - Journalisation des requêtes
  - Analyse de requêtes
  - Audit de requêtes. Un exemple de ceci est l'extension PECL/mysqlnd_sip (SQL Injection Protection). Cette extension inspecte les requêtes et exécute uniquement celles qui sont autorisées suivant des ensembles de règles.
- Performance
  - La mise en cache. Un exemple de ceci est l'extension PECL/mysqlnd_qc (Query Cache).
  - Étranglement
  - Fragmentation. Un exemple de ceci est l'extension PECL/mysqlnd_mc (Multi Connect). Cette extension tente de séparer une requête SELECT en n parties, en utilisant des requêtes du type SELECT ... LIMIT part_1, SELECT LIMIT part_n. L'extension envoie les requêtes à des serveurs MySQL distincts et fusionne ensuite le résultat à destination du client.

Plugins du driver natif MySQL disponibles

Il y a déjà plusieurs plugins mysqlnd de disponibles.

- PECL/mysqlnd_mc -Plugin Multi Connexion.
- PECL/mysqlnd_ms - Plugin Maître Esclave.
- PECL/mysqlnd_qc - Plugin de mise en cache de requêtes.
- PECL/mysqlnd_pscache - Plugin de mise en cache de gestionnaire de requêtes préparées.
- PECL/mysqlnd_sip - Plugin permettant la protection contre les injections SQL.
- PECL/mysqlnd_uh - Plugin de gestionnaire d'utilisateurs.

## Comparaison des plugins mysqlnd avec proxy MySQL

Les plugins `Mysqlnd` et le proxy MySQL sont des technologies différentes utilisant différentes approches. Les deux sont des outils valides pour résoudre bon nombre de tâches classiques, comme l'équilibrage de charge, la surveillance, et l'amélioration des performances. Une importante différence est que le proxy MySQL fonctionne avec tous les clients MySQL alors que les plugins `mysqlnd` sont spécifiques aux applications PHP.

Comme une extension PHP, un plugin `mysqlnd` doit être installé sur le serveur d'applications PHP, en plus du reste de PHP. Un proxy MySQL peut soit fonctionner sur le serveur d'applications PHP, soit être installé sur une machine dédiée pour gérer plusieurs serveurs d'applications PHP.

Le déploiement d'un proxy MySQL sur un serveur d'applications a 2 avantages :

1. Pas un seul point d'échec
2. Facile à redimensionner (redimensionnement horizontal, redimensionnement par le client)

Un proxy MySQL (et les plugins `mysqlnd`) peut résoudre des problèmes facilement, qui sinon, auraient dû nécessiter des modifications aux applications existantes.

Cependant, un proxy MySQL a quelques désavantages :

- Un proxy MySQL est un nouveau composant, une nouvelle technologie à appliquer au maître et à déployer.
- Un proxy MySQL nécessite la connaissance du langage de script Lua.

Un proxy MySQL peut être personnalisé en utilisant les langages de programmation C et Lua. Lua est le langage préféré pour un proxy MySQL. Pour la plupart des experts PHP, Lua est un nouveau langage à apprendre. Un plugin `mysqlnd` peut être écrit en C. Il est également possible d'écrire un plugin en PHP en utilisant » PECL/mysqlnd_uh.

Un proxy MySQL fonctionne comme un démon - un processus en arrière-plan. Un proxy MySQL peut rappeler des décisions prises antérieurement, vu que tous les états peuvent être conservés. Cependant, un plugin `mysqlnd` est lié au cycle de vie d'une requête PHP. Un proxy MySQL peut également partager des résultats calculés une seule fois sur plusieurs serveurs d'applications. Un plugin `mysqlnd` peut donc avoir besoin de stocker des données dans un médium persistant. Un autre démon peut être utilisé dans ce but, par exemple Memcache. Ce mécanisme donne un avantage au proxy MySQL.

Un proxy MySQL fonctionne au-dessus de la couche physique. Avec un proxy MySQL, il faut analyser et effectuer du "reverse engineering" du protocole client serveur MySQL. Les actions sont limitées à celles qui peuvent être effectuées par la manipulation du protocole de communication. Si la couche physique change (ce qui arrive très rarement), les scripts du proxy MySQL peuvent devoir être adaptés.

Les plugins `Mysqlnd` fonctionnent au-dessus de l'API C, reflétant ainsi les APIs client `libmysqlclient`. Cette API C est essentiellement une enveloppe du protocole Serveur Client MySQL, ou de la couche physique, vu qu'elle est appelée quelques fois. L'on peut intercepter tous les appels à l'API C. PHP utilise l'API C, toutefois, il est possible de connecter tous les appels PHP, sans avoir besoin de programmer au niveau de la couche physique.

`Mysqlnd` implémente la couche physique. Les plugins peuvent toutefois analyser, effectuer un "reverse engineering", manipuler et toujours remplacer le protocole de communication. Cependant, ce n'est généralement pas nécessaire.

Vu que les plugins permettent de créer des implémentations qui utilisent les 2 niveaux (API C et couche physique), ils ont plus de flexibilité que le proxy MySQL. Si un plugin `mysqlnd` est implémenté en utilisant l'API C, toutes les modifications ultérieures à la couche physique ne nécessiteront pas de modification au plugin en tant que tel.

## Obtenir l'API du plugin mysqlnd

L'API du plugin `mysqlnd` est simplement une partie de l'extension du driver PHP Natif MySQL, `ext/mysqlnd`. Le développement de l'API du plugin `mysqlnd` commença en décembre 2009. Il est développé comme une partie du dépôt source de PHP, et ainsi, est disponible depuis soit le dépôt public Git, soit depuis le téléchargement des sources.

Les développeurs de plugin peuvent déterminer la version de `mysqlnd` via la variable `MYSQLND_VERSION`, au format mysqlnd 8.3.17, ou via `MYSQLND_VERSION_ID`, qui est un entier par exemple 50007. Les développeurs peuvent calculer le numéro de version comme ceci :

Table de calcul des MYSQLND_VERSION_ID
Version (partie) | Exemple
--- | ---
Majeur*10000 | 5*10000 = 50000
Mineur*100 | 0*100 = 0
Patch | 7 = 7
MYSQLND_VERSION_ID | 50007

Lors du développement, les développeurs doivent se référer au numéro de version `mysqlnd` pour des tests de compatibilité et de version, sachant que plusieurs versions de `mysqlnd` peuvent survenir durant un cycle de vie de la branche de développement de PHP.

## Architecture du plugin du driver natif

Cette section fournit un aperçu de l'architecture du plugin `mysqlnd`.

Aperçu du driver natif MySQL

Avant de développer des plugins `mysqlnd`, il est utile d'avoir une connaissance minimale sur l'organisation de `mysqlnd`. `Mysqlnd` est composé des modules suivants :

Schéma de l'organisation mysqlnd, par module
Modules de statistiques | mysqlnd_statistics.c
--- | ---
Connexion | mysqlnd.c
Jeu de résultats | mysqlnd_result.c
Données méta du jeu de résultats | mysqlnd_result_meta.c
Requête | mysqlnd_ps.c
Réseau | mysqlnd_net.c
Couche physique | mysqlnd_wireprotocol.c

Objet C orienté paradigme

Au niveau du code, `mysqlnd` utilise un masque C pour implémenter l'orientation de l'objet.

En C, on utilise une structure (`struct`) pour représenter un objet. Les membres de cette structure représentent les propriétés de l'objet. Les membres de la structure pointant vers des fonctions représentent les méthodes.

Contrairement aux autres langages comme C++ ou Java, il n'y a pas de règles fixes sur l'héritage dans les objets C orientés paradigme. Cependant, il y a quelques conventions qui doivent être suivies qui seront abordées ultérieurement.

Le cycle de vie PHP

Le cycle de vie de PHP comporte 2 cycles basiques :

- Le cycle de démarrage et d'arrêt du moteur PHP
- Le cycle d'une demande

Lorsque le moteur PHP démarre, il appelle la fonction d'initialisation du module (MINIT) de chaque extension enregistrée. Ceci permet à chaque module de définir les variables et d'allouer les ressources qui doivent exister pour la durée de vie du processus correspondant au moteur PHP. Lorsque le moteur PHP s'arrête, il appelle la fonction d'arrêt du module (MSHUTDOWN) pour chaque extension.

Pendant la durée de vie du moteur PHP, il recevra des demandes. Chaque demande constitue un autre cycle de vie. Pour chaque requête, le moteur PHP appellera la fonction d'initialisation de chaque extension. L'extension peut effectuer toutes les définitions de variables ainsi que les allocations de ressources nécessaires pour traiter la demande. Lorsque le cycle de la demande se termine, le moteur appelle la fonction d'arrêt (RSHUTDOWN) pour chaque extension, ainsi, l'extension peut lancer tout le nettoyage nécessaire.

Comment fonctionne un plugin

Un plugin `mysqlnd` fonctionne en interceptant les appels effectués à `mysqlnd` par les extensions qui utilisent `mysqlnd`. Ceci est possible en obtenant la table de fonction `mysqlnd`, en la sauvegardant, et en la remplaçant par une table de fonction personnalisée, qui appelle les fonctions du plugin.

Le code suivant montre la façon dont la table de fonction `mysqlnd` est remplacée :

    /* un endroit pour stocker la table de fonction originale */
    struct st_mysqlnd_conn_methods org_methods;

    void minit_register_hooks(TSRMLS_D) {
      /* table de fonction active */
      struct st_mysqlnd_conn_methods * current_methods
        = mysqlnd_conn_get_methods();

      /* sauvegarde de la table de fonction originale */
      memcpy(&org_methods, current_methods,
        sizeof(struct st_mysqlnd_conn_methods);

      /* installation des nouvelles méthodes */
      current_methods->query = MYSQLND_METHOD(my_conn_class, query);
    }

Les manipulations de la table de fonction de connexion doivent être effectuées lors de l'initialisation du module (MINIT). La table de fonction est une ressource globale partagée. Dans un environnement multithread, avec une compilation TSRM, la manipulation d'une ressource globale partagée lors d'un processus de demande entraînera la plupart du temps des conflits.

> Note: N'utiliser aucune logique de taille fixe lors de la manipulation de la table de fonction `mysqlnd` : les nouvelles méthodes peuvent être ajoutées à la fin de la table de fonction. La table de fonction peut être modifiée à tout moment par la suite.

Appel des méthodes parents

Si la table de fonction originale est sauvegardée, il est toujours possible d'appeler les entrées de la table de fonction originale - les méthodes parents.

Dans ce cas, tout comme pour `Connection::stmt_init()`, il est vital d'appeler la méthode parent avant toute autre activité dans la méthode dérivée.

    MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn,
      const char *query, unsigned int query_len TSRMLS_DC) {

      php_printf("my_conn_class::query(query = %s)\n", query);

      query = "SELECT 'query rewritten' FROM DUAL";
      query_len = strlen(query);

      return org_methods.query(conn, query, query_len); /* retour avec appel du parent */
    }

Étendre des propriétés

Un objet `mysqlnd` est représenté par une structure C. Il n'est pas possible d'ajouter un membre à une structure C au moment de l'exécution. Les utilisateurs d'objets `mysqlnd` ne peuvent pas ajouter simplement des propriétés aux objets.

Les données arbitraires (propriétés) peuvent être ajoutées aux objets `mysqlnd` en utilisant une fonction appropriée de la famille `mysqlnd_plugin_get_plugin_<object>_data()`. Lors de l'allocation d'un objet, `mysqlnd` réserve un espace à la fin de l'objet pour accueillir un pointeur `void *` vers des données arbitraires. `mysqlnd` réserve un espace pour un pointeur `void *` par plugin.

La table suivante montre comment calculer la position d'un pointeur pour un plugin spécifique :

Calcul des pointeurs pour mysqlnd
Adresse mémoire | Contenus
--- | ---
0 | Début de la structure C de l'objet mysqlnd
n | Fin de la structure C de l'objet mysqlnd
n + (m x sizeof(void*)) | void* vers les données de l'objet du m-ème plugin

Si l'on prévoit de faire des sous-classes des constructeurs des objets `mysqlnd`, ce qui est autorisé, il faut conserver ceci en mémoire !

Le code suivant montre la façon dont on étend des propriétés :

    /* toutes les données que nous voulons associer */
    typedef struct my_conn_properties {
      unsigned long query_counter;
    } MY_CONN_PROPERTIES;

    /* id du plugin */
    unsigned int my_plugin_id;

    void minit_register_hooks(TSRMLS_D) {
      /* on obtient un ID unique pour le plugin */
      my_plugin_id = mysqlnd_plugin_register();
      /* snip - voir l'extension de la connexion : méthodes */
    }

    static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) {
      MY_CONN_PROPERTIES** props;
      props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data(
        conn, my_plugin_id);
      if (!props || !(*props)) {
        *props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent);
        (*props)->query_counter = 0;
      }
      return props;
    }

Le développeur du plugin est responsable de la gestion de la mémoire associée aux données du plugin.

L'utilisation de l'allocateur de mémoire `mysqlnd` est recommandée pour les données du plugin. Ces fonctions sont nommées en utilisant la convention suivante : `mnd_*loc()`. L'allocateur `mysqlnd` a quelques fonctionnalités bien utiles, comme la possibilité d'utiliser un allocateur de débogage dans une compilation non-débogue.

Quand et comment faire une sous-classe
| Quand faire une sous-classe ? | Est-ce que chaque instance a sa table de fonction privée ? | Comment faire une sous-classe ?
--- | --- | --- | ---
Connexion (MYSQLND) | MINIT | Non | mysqlnd_conn_get_methods()
Jeu de résultats (MYSQLND_RES) | MINIT ou après | Oui | mysqlnd_result_get_methods() ou méthode de l'objet de manipulation de la table de fonction
Méta du jeu de résultats (MYSQLND_RES_METADATA) | MINIT | Non | mysqlnd_result_metadata_get_methods()
Requête (MYSQLND_STMT) | MINIT | Non | mysqlnd_stmt_get_methods()
Réseau (MYSQLND_NET) | MINIT ou après | Oui | mysqlnd_net_get_methods() ou méthode de l'objet de manipulation de la table de fonction
Couche physique (MYSQLND_PROTOCOL) | MINIT ou après | Oui | mysqlnd_protocol_get_methods() ou méthode de l'objet de manipulation de la table de fonction

Il ne faut pas manipuler les tables de fonction après MINIT si ce n'est pas autorisé suivant la table ci-dessus.

Quelques classes contiennent un pointeur vers une méthode de la table de fonction. Toutes les instances d'une telle classe partageront la même table de fonction. Pour éviter le chaos, en particulier dans les environnements threadés, ce genre de tables de fonction ne doit être manipulé que lors du MINIT.

Les autres classes utilisent une copie de la table de fonction globale partagée. Cette copie est créée en même temps que l'objet. Chaque objet utilise sa propre table de fonction. Ceci donne 2 options : il est possible de manipuler la table de fonction par défaut d'un objet au moment du MINIT, et il est également possible d'affiner des méthodes d'un objet sans impacter les autres instances de la même classe.

L'avantage de l'approche avec une table de fonction partagée est la performance. Il n'est pas nécessaire de copier une table de fonction pour chaque objet.

Statut du constructeur
Type | Allocation, construction, réinitialisation | Peut-être modifié ? | Appelant
--- | --- | --- | ---
Connexion (MYSQLND) | mysqlnd_init() | Non | mysqlnd_connect()
Jeu de résultats(MYSQLND_RES) | Allocation : Connection::result_init() Reset et réinitialisation lors de : Result::use_result() Result::store_result | Oui, mais appel du parent ! | Connection::list_fields() Statement::get_result() Statement::prepare() (Méta-données uniquement) Statement::resultMetaData()
Méta du jeu de résultats (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Oui, mais appel du parent ! | Result::read_result_metadata()
Statement (MYSQLND_STMT) | Connection::stmt_init() | Oui, mais appel du parent ! | Connection::stmt_init()
Réseau (MYSQLND_NET) | mysqlnd_net_init() | Non | Connection::init()
Couche physique (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | Non | Connection::init()

Il est vivement recommandé de ne pas remplacer entièrement un constructeur. Les constructeurs effectuent les allocations mémoires. Les allocations mémoires sont vitales pour l'API du plugin `mysqlnd` ainsi que pour la logique de l'objet `mysqlnd`. Si l'on ne se soucie pas des alertes et que l'on insiste pour remplacer les constructeurs, il est recommandé d'au moins appeler le constructeur parent avant de faire quoi que ce soit dans le constructeur.

Au niveau de toutes les alertes, il peut être utile de faire des sous-classes des constructeurs. Les constructeurs sont les endroits parfaits pour modifier les tables de fonction des objets avec les tables d'objets non partagés, comme les jeux de résultats, le réseau ou encore la couche physique.

Statut du destructeur
Type | La méthode dérivée doit appeler le parent ? | Destructeur
--- | --- | ---
Connexion | oui, après l'exécution de la méthode | free_contents(), end_psession()
Jeu de résultats | oui, après l'exécution de la méthode | free_result()
Méta du jeu de résultats | oui, après l'exécution de la méthode | free()
Requête | oui, après l'exécution de la méthode | dtor(), free_stmt_content()
Réseau | oui, après l'exécution de la méthode | free()
Couche physique | oui, après l'exécution de la méthode | free()

Les destructeurs sont les endroits parfaits pour libérer les propriétés, `mysqlnd_plugin_get_plugin_<object>_data()`.

Les destructeurs listés peuvent ne pas être les équivalents aux méthodes actuelles `mysqlnd` libérant l'objet lui-même. Cependant, ils sont les meilleurs endroits pour libérer les données du plugin. Tout comme les constructeurs, il est possible de remplacer les méthodes entières mais ce n'est pas recommandé. Si plusieurs méthodes sont listées dans la table ci-dessus, il faut modifier toutes les méthodes listées et libérer les données du plugin dans la méthode appelée en premier par `mysqlnd`.

La méthode recommandée pour les plugins est de modifier simplement les méthodes, libérer la mémoire et appeler l'implémentation du parent immédiatement après.

## L'API du plugin mysqlnd

Voici la liste des fonctions fournies dans l'API plugin `mysqlnd` :

- mysqlnd_plugin_register()
- mysqlnd_plugin_count()
- mysqlnd_plugin_get_plugin_connection_data()
- mysqlnd_plugin_get_plugin_result_data()
- mysqlnd_plugin_get_plugin_stmt_data()
- mysqlnd_plugin_get_plugin_net_data()
- mysqlnd_plugin_get_plugin_protocol_data()
- mysqlnd_conn_get_methods()
- mysqlnd_result_get_methods()
- mysqlnd_result_meta_get_methods()
- mysqlnd_stmt_get_methods()
- mysqlnd_net_get_methods()
- mysqlnd_protocol_get_methods()

Il n'y a pas de définition formelle de ce qu'est un plugin ainsi de la façon dont fonctionne un plugin.

Les composants les plus souvent trouvés dans les mécanismes de plugin sont :

- Un gestionnaire de plugin
- Une API du plugin
- Les services applicatifs (ou modules)
- Les APIs des services applicatifs (ou APIs du module)

Le concept d'un plugin `mysqlnd` utilise ces fonctionnalités, ainsi que d'autres joyeusetés d'architecture ouverte.

Aucune restriction

Un plugin a un accès total aux travaux internes de `mysqlnd`. Il n'y a aucune limite de sécurité ou de restrictions. Tout peut être écrasé pour implémenter des algorithmes utiles ou hostiles. Il est recommandé de ne déployer que des plugins depuis des sources de confiance.

Tel que discuté précédemment, les plugins peuvent utiliser librement des pointeurs. Ces pointeurs ne sont restreints en aucune manière, aussi, il est possible de pointer vers les données d'un autre plugin. Une simple position arithmétique peut être utilisée pour lire les données d'un autre plugin.

Il est recommandé d'écrire des plugins coopératifs, et ainsi, appeler toujours la méthode parent. Les plugins devraient toujours coopérer avec `mysqlnd`.

Enjeux : un exemple de chaînage et de coopération
Extension | Pointeur mysqlnd.query() | Pile d'appel si on appelle le parent
--- | --- | ---
ext/mysqlnd | mysqlnd.query() | mysqlnd.query
ext/mysqlnd_cache | mysqlnd_cache.query() | mysqlnd_cache.query() mysqlnd.query
ext/mysqlnd_monitor | mysqlnd_monitor.query() | mysqlnd_monitor.query() mysqlnd_cache.query() mysqlnd.query

Dans ce scénario, un plugin cache (`ext/mysqlnd_cache`) et un plugin de surveillance (`ext/mysqlnd_monitor`) sont chargés. Les 2 ont une sous-classe de `Connection::query()`. L'enregistrement du plugin survient lors du `MINIT` en utilisant la logique évoquée précédemment. PHP appelle les extensions dans un ordre alphabétique par défaut. Les plugins ne sont pas au courant les uns les autres et ne peuvent fixer de dépendances.

Par défaut, les plugins appellent l'implémentation du parent de la méthode de requête dans leur version de la méthode dérivée.

Récapitulatif de l'extension PHP

Voici un récapitulatif de ce qui survient lors de l'utilisation d'un plugin d'exemple, `ext/mysqlnd_plugin`, qui expose l'API C du plugin `mysqlnd` à PHP :

- Toutes les applications PHP MySQL tentent d'établir une connexion à l'adresse 192.168.2.29
- L'application PHP utilisera `ext/mysql`, `ext/mysqli` ou `PDO_MYSQL`. Ces 3 extensions PHP MySQL utilisent `mysqlnd` pour établir la connexion à l'adresse 192.168.2.29.
- `Mysqlnd` appelle sa méthode de connexion, qui a été sous-classée par `ext/mysqlnd_plugin`.
- `ext/mysqlnd_plugin` appelle la méthode de l'espace utilisateur `proxy::connect()` enregistrée par l'utilisateur.
- L'espace utilisateur modifie l'hôte de connexion de 192.168.2.29 à 127.0.0.1 et retourne la connexion établie par `parent::connect()`.
- `ext/mysqlnd_plugin` exécute l'équivalent de `parent::connect(127.0.0.1)` en appelant la méthode originale de `mysqlnd` pour établir une connexion.
- `ext/mysqlnd` établit une connexion et redonne la main à `ext/mysqlnd_plugin`. `ext/mysqlnd_plugin` retourne également.
- Quelle que soit l'extension PHP MySQL utilisée par l'application, elle reçoit une connexion à 127.0.0.1. L'extension PHP MySQL redonne la main à l'application PHP. Le cycle est clos.

## Bien commencer la compilation d'un plugin mysqlnd

Il est important de se souvenir qu'un plugin `mysqlnd` est lui-même une extension PHP.

Le code suivant montre la structure basique d'une fonction MINIT utilisée dans un plugin typique `mysqlnd` :

    /* my_php_mysqlnd_plugin.c */

     static PHP_MINIT_FUNCTION(mysqlnd_plugin) {
      /* globales, entrées ini, ressources, classes */

      /* enregistrement du plugin mysqlnd */
      mysqlnd_plugin_id = mysqlnd_plugin_register();

      conn_m = mysqlnd_get_conn_methods();
      memcpy(org_conn_m, conn_m,
        sizeof(struct st_mysqlnd_conn_methods));

      conn_m->query = MYSQLND_METHOD(mysqlnd_plugin_conn, query);
      conn_m->connect = MYSQLND_METHOD(mysqlnd_plugin_conn, connect);
    }

    /* my_mysqlnd_plugin.c */

     enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, query)(/* ... */) {
      /* ... */
    }
    enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, connect)(/* ... */) {
      /* ... */
    }

Tâche d'analyse : depuis C vers l'espace utilisateur

     class proxy extends mysqlnd_plugin_connection {
      public function connect($host, ...) { .. }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

Processus :

1. PHP : l'utilisateur enregistre une fonction de rappel pour le plugin
2. PHP : l'utilisateur appelle une méthode de l'API PHP MySQL pour se connecter à MySQL
3. C : ext/*mysql* appelle la méthode mysqlnd
4. C : mysqlnd se termine dans ext/mysqlnd_plugin

5. C : ext/mysqlnd_plugin

   1. Appel de la fonction de rappel de l'espace utilisateur
   2. Ou la méthode originale `mysqlnd`, si l'espace utilisateur n'a pas défini de fonction de rappel

Il faut effectuer les opérations suivantes :

1. Écrire une classe "mysqlnd_plugin_connection" en C
2. Accepter et enregistrer l'objet proxy via "mysqlnd_plugin_set_conn_proxy()"
3. Appeler les méthodes de proxy de l'espace utilisateur depuis C (optimisation - zend_interfaces.h)

Les méthodes de l'objet de l'espace utilisateur peuvent soit être appelées en utilisant `call_user_function()`, soit il est possible d'opérer à un niveau en dessous du moteur Zend et utiliser `zend_call_method()`.

Optimisation : appel des méthodes depuis C en utilisant zend_call_method

Le code suivant montre un prototype pour la fonction `zend_call_method`, issue de zend_interfaces.h.

     ZEND_API zval* zend_call_method(
      zval **object_pp, zend_class_entry *obj_ce,
      zend_function **fn_proxy, char *function_name,
      int function_name_len, zval **retval_ptr_ptr,
      int param_count, zval* arg1, zval* arg2 TSRMLS_DC
    );

L'API Zend supporte 2 arguments. Il est possible d'en avoir besoin de plus, par exemple :

     enum_func_status (*func_mysqlnd_conn__connect)(
      MYSQLND *conn, const char *host,
      const char * user, const char * passwd,
      unsigned int passwd_len, const char * db,
      unsigned int db_len, unsigned int port,
      const char * socket, unsigned int mysql_flags TSRMLS_DC
    );

Pour contourner ce problème, il faudra faire une copie de `zend_call_method()` et ajouter une fonctionnalité pour ajouter des paramètres. L'on peut réaliser ceci en créant un jeu de macros `MY_ZEND_CALL_METHOD_WRAPPER`.

Appel de l'espace utilisateur PHP

Le code ci-dessous montre la méthode optimisée pour effectuer un appel à une fonction de l'espace utilisateur depuis C :

    /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class,connect)(
      MYSQLND *conn, const char *host /* ... */ TSRMLS_DC) {
      enum_func_status ret = FAIL;
      zval * global_user_conn_proxy = fetch_userspace_proxy();
      if (global_user_conn_proxy) {
        /* appel du proxy de l'espace utilisateur */
        ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/);
      } else {
        /* ou la méthode originale mysqlnd = ne rien faire, être transparent */
        ret = org_methods.connect(conn, host, user, passwd,
              passwd_len, db, db_len, port,
              socket, mysql_flags TSRMLS_CC);
      }
      return ret;
    }

Appel de l'espace utilisateur: arguments simples

    /* my_mysqlnd_plugin.c */

     MYSQLND_METHOD(my_conn_class,connect)(
      /* ... */, const char *host, /* ...*/) {
      /* ... */
      if (global_user_conn_proxy) {
        /* ... */
        zval* zv_host;
        MAKE_STD_ZVAL(zv_host);
        ZVAL_STRING(zv_host, host, 1);
        MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_host /*, ...*/);
        zval_ptr_dtor(&zv_host);
        /* ... */
      }
      /* ... */
    }

Appel de l'espace utilisateur : structures comme arguments

    /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class, connect)(
      MYSQLND *conn, /* ...*/) {
      /* ... */
      if (global_user_conn_proxy) {
        /* ... */
        zval* zv_conn;
        ZEND_REGISTER_RESOURCE(zv_conn, (void *)conn, le_mysqlnd_plugin_conn);
        MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_conn, zv_host /*, ...*/);
        zval_ptr_dtor(&zv_conn);
        /* ... */
      }
      /* ... */
    }

Le premier argument de toutes les méthodes `mysqlnd` est un objet C. Par exemple, le premier argument de la méthode connect() est un pointeur vers `MYSQLND`. La structure MYSQLND représente un objet de connexion `mysqlnd`.

Le pointeur de l'objet de connexion `mysqlnd` peut être comparé à un pointeur de fichier standard I/O. Tout comme un pointeur de fichier standard I/O, un objet de connexion `mysqlnd` doit être lié à l'espace utilisateur en utilisant une variable PHP de type ressource.

Depuis C vers l'espace utilisateur, puis, retour

     class proxy extends mysqlnd_plugin_connection {
      public function connect($conn, $host, ...) {
        /* "pre" hook */
        printf("Connexion à l'hôte = '%s'\n", $host);
        debug_print_backtrace();
        return parent::connect($conn);
      }

      public function query($conn, $query) {
        /* "post" hook */
        $ret = parent::query($conn, $query);
        printf("Requête = '%s'\n", $query);
        return $ret;
      }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

Les utilisateurs PHP doivent pouvoir appeler l'implémentation du parent d'une méthode écrasée.

Comme résultat d'un sous-classement, il est possible de redéfinir uniquement les méthodes sélectionnées, et l'on peut choisir d'avoir des actions "pre" ou "post".

Construction d'une classe : mysqlnd_plugin_connection::connect()

    /*  my_mysqlnd_plugin_classes.c */

     PHP_METHOD("mysqlnd_plugin_connection", connect) {
      /* ... simplifié ! ... */
      zval* mysqlnd_rsrc;
      MYSQLND* conn;
      char* host; int host_len;
      if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "rs",
        &mysqlnd_rsrc, &host, &host_len) == FAILURE) {
        RETURN_NULL();
      }
      ZEND_FETCH_RESOURCE(conn, MYSQLND* conn, &mysqlnd_rsrc, -1,
        "Mysqlnd Connection", le_mysqlnd_plugin_conn);
      if (PASS == org_methods.connect(conn, host, /* simplifié! */ TSRMLS_CC))
        RETVAL_TRUE;
      else
        RETVAL_FALSE;
    }

- Introduction
- Installation
- Configuration à l'exécution
- Incompatibilités
- Les connexions persistantes
- Statistiques
- Notes
- Gestion de la mémoire
- API du plugin du driver natif MySQL
  - Comparaison des plugins mysqlnd avec proxy MySQL
  - Obtenir l'API du plugin mysqlnd
  - Architecture du plugin du driver natif
  - L'API du plugin mysqlnd
  - Bien commencer la compilation d'un plugin mysqlnd

- Aperçu des drivers PHP MySQL
  - Aperçu de la terminologie
  - Choisir une API
  - Choisir une bibliothèque
  - Concepts
- MySQLi — Extension mysqli
  - Introduction
  - Guide de démarrage rapide
  - Installation/Configuration
  - L'extension mysqli et les connexions persistantes
  - Constantes pré-définies
  - Notes
  - Le sommaire des fonctions de l'extension MySQLi
  - mysqli — La classe mysqli
  - mysqli_stmt — La classe mysqli_stmt
  - mysqli_result — La classe mysqli_result
  - mysqli_driver — La classe mysqli_driver
  - mysqli_warning — La classe mysqli_warning
  - mysqli_sql_exception — La classe mysqli_sql_exception
  - Fonctions mysqli obsolètes et alias
  - Historique des modifications
- Mysql_xdevapi
  - Installation/Configuration
  - Constantes pré-définies
  - Historique des modifications
  - Exemples
  - Fonctions Mysql_xdevapi
  - mysql_xdevapi\BaseResult — Interface BaseResult
  - mysql_xdevapi\Client — La classe Client
  - mysql_xdevapi\Collection — Classe Collection
  - mysql_xdevapi\CollectionAdd — Classe CollectionAdd
  - mysql_xdevapi\CollectionFind — Classe CollectionFind
  - mysql_xdevapi\CollectionModify — Classe CollectionModify
  - mysql_xdevapi\CollectionRemove — Classe CollectionRemove
  - mysql_xdevapi\ColumnResult — Classe ColumnResult
  - mysql_xdevapi\CrudOperationBindable — Interface CrudOperationBindable
  - mysql_xdevapi\CrudOperationLimitable — Interface CrudOperationLimitable
  - mysql_xdevapi\CrudOperationSkippable — Interface CrudOperationSkippable
  - mysql_xdevapi\CrudOperationSortable — Interface CrudOperationSortable
  - mysql_xdevapi\DatabaseObject — Interface DatabaseObject
  - mysql_xdevapi\DocResult — Classe DocResult
  - mysql_xdevapi\Exception — Classe Exception
  - mysql_xdevapi\Executable — Interface Executable
  - mysql_xdevapi\ExecutionStatus — Classe ExecutionStatus
  - mysql_xdevapi\Expression — Classe Expression
  - mysql_xdevapi\Result — Classe Result
  - mysql_xdevapi\RowResult — Classe RowResult
  - mysql_xdevapi\Schema — Classe Schema
  - mysql_xdevapi\SchemaObject — Interface SchemaObject
  - mysql_xdevapi\Session — Classe Session
  - mysql_xdevapi\SqlStatement — Classe SqlStatement
  - mysql_xdevapi\SqlStatementResult — Classe SqlStatementResult
  - mysql_xdevapi\Statement — Classe Statement
  - mysql_xdevapi\Table — Classe Table
  - mysql_xdevapi\TableDelete — Classe TableDelete
  - mysql_xdevapi\TableInsert — Classe TableInsert
  - mysql_xdevapi\TableSelect — Classe TableSelect
  - mysql_xdevapi\TableUpdate — Classe TableUpdate
  - mysql_xdevapi\Warning — Classe Warning
- MySQL (Original) — API MySQL originale
  - Installation/Configuration
  - Historique des modifications
  - Constantes pré-définies
  - Exemples
  - Fonctions MySQL
- Mysqlnd — Le pilote natif MySQL
  - Introduction
  - Installation
  - Configuration à l'exécution
  - Incompatibilités
  - Les connexions persistantes
  - Statistiques
  - Notes
  - Gestion de la mémoire
  - API du plugin du driver natif MySQL

# Oracle OCI8

# Introduction

Avertissement

Cette extension est DÉGROUPÉE à partir de PHP 8.4.0.

Ces fonctions permettent d'accéder aux bases de données Oracle. Elles supportent les commandes SQL et PL/SQL. Les fonctions de base incluent le contrôle de transaction, la liaison de variables PHP avec des conteneurs Oracle, le support des types de grands objets (LOB) et des collections. Les fonctions d'extensibilité d'Oracle, telles que le Database Resident Connection Pooling (DRCP) et le cache de résultats sont aussi supportées.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Test
- Configuration à l'exécution

## Pré-requis

OCI8 3.0 est incluse avec PHP 8. Elle est également disponible depuis » PECL. Pour PHP 7, utiliser OCI8 2.2 depuis » PECL. OCI8 requiert Oracle 10g ou bibliothèques cliente ultérieures.

Si la base de données Oracle est sur la même machine que PHP, le logiciel de base de données contient déjà les bibliothèques et en-têtes nécessaires. Lorsque PHP est sur une machine différente, utiliser les bibliothèques gratuites » Oracle Instant Client.

Pour utiliser Oracle Instant Client, installer le fichier compressé ZIP `Basic` ou `Basic Light` de Oracle Instant Client, le paquet RPM, ou le paquet DMG. Lors de la compilation d'OCI8 depuis le code source, installer aussi le `SDK` d'Instant Client.

Il faut exécuter PHP avec la même version ou une version plus récente des bibliothèques clients Oracle utilisées pour construire OCI8.

> Note:

> L'interopérabilité standard du réseau client-serveur d'Oracle permet des connexions entre différentes versions d'Oracle Client et Oracle Database. Pour des configurations certifiées voir la documentation Oracle Support ID ID 207303.1. En résumé, Oracle Client 19, 18 et 12.2 peuvent se connecter à Oracle Database 11.2 ou supérieur. Oracle Client 12.1 peut se connecter à Oracle Database 10.2 ou supérieur. Oracle Client 11.2 peut se connecter à Oracle Database 9.2 ou supérieur.

> Note:

> Le support de toutes les fonctionnalités OCI8 n'est disponible que lors de l'utilisation des versions les plus récentes des bibliothèques clientes Oracle mais aussi de la base de données la plus récente.

## Installation

## Configuration de PHP avec OCI8

Consulter la section précédente sur les Pré-requis avant de configurer OCI8.

Avant de démarrer le serveur web, OCI8, typiquement, nécessite plusieurs variables d'environnement (voir ci-dessous) pour localiser les bibliothèques, pour pointer vers des fichiers de configuration, et pour définir quelques propriétés basiques comme le jeu de caractères utilisé par les bibliothèques OCI8. Les variables doivent être définies avant le démarrage d'un quelconque processus PHP.

Le binaire PHP doit être lié avec les mêmes (ou plus récentes) versions majeures des bibliothèques Oracle pour lesquelles il a été configuré. Par exemple, si on compile OCI8 avec les bibliothèques Oracle 19, alors PHP doit aussi être déployé et exécuté avec les bibliothèques Oracle 19. Les applications PHP peuvent se connecter à d'autres versions de base de données Oracle, sachant qu'Oracle contient des compatibilités de versions des différents clients - serveurs.

## Installation d'OCI8 depuis PECL en utilisant la commande pecl

L'extension OCI8 peut être ajoutée à une installation PHP existante en utilisant le référentiel » PECL.

- Si on est derrière un pare-feu, définissez le proxy de PEAR, par exemple :

      pear config-set http_proxy http://my-proxy.example.com:80/

- Exécuter :

      pecl install oci8

  Pour PHP 7, utiliser `pecl install oci8-2.2.0`.

- Lorsqu'on le demande, saisissez la valeur de `$ORACLE_HOME` ou `instantclient,/chemin/vers/le/répertoire/instant/client/lib`.

  Remarque : Ne saisissez pas de noms de variables tels que `$ORACLE_HOME` ou `$HOME` car `pecl` ne les développera pas. Au lieu de cela, saisissez un chemin développé, par exemple `/opt/oracle/product/19c/dbhome_1` ou `instantclient,/Users/monnom/Téléchargements/instantclient_19_8`.

- Si on obtient une erreur `oci8_dtrace_gen.h: Aucun fichier ou répertoire de ce type`, cela signifie que PHP a été compilé avec DTrace Dynamic Tracing activé. Installer en utilisant la commande :

      $ export PHP_DTRACE=yes
      $ pecl install oci8

- Modifier le fichier php.ini et ajouter la ligne :

      extension=oci8.so

  Il faut s'assurer que la directive php.ini extension_dir est définie sur le répertoire dans lequel oci8.so a été installé.

## Installation d'OCI8 depuis PECL en utilisant phpize

Pour installer OCI8 sur une installation PHP existante lorsque la commande `pecl` n'est pas disponible, téléchargez manuellement le package OCI8 » PECL, par exemple oci8-3.0.0.tgz.

- Extraire le package :

      tar -zxf oci8-3.0.0.tgz
      cd oci8-3.0.0

- Préparer le package :

      phpize

- Configurer le package en utilisant soit `$ORACLE_HOME`, soit Instant Client.

      ./configure -with-oci8=shared,$ORACLE_HOME

  ou

      ./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib

- Installer le package :

      make install

- Si on obtient une erreur `oci8_dtrace_gen.h: Aucun fichier ou répertoire de ce type`, cela signifie que PHP a été compilé avec DTrace Dynamic Tracing activé. Exécuter à nouveau les commandes `configure` et `make` après avoir défini cette variable d'environnement :

      $ export PHP_DTRACE=yes

- Modifier le fichier php.ini et ajouter la ligne :

      extension=oci8.so

  Il faut s'assurer que la directive php.ini extension_dir est configurée sur le répertoire dans lequel oci8.so a été installé.

## Installation d'OCI8 en tant qu'extension partagée lors de la compilation de PHP

Si on compile PHP à partir du code source, l'option de configuration `shared` peut être utilisée pour construire OCI8 en tant que bibliothèque partagée qui peut être chargée dynamiquement dans PHP. La construction d'une extension partagée permet à OCI8 d'être facilement mis à jour sans avoir d'impact sur le reste de PHP.

Configurer OCI8 en utilisant l'une des options de configuration suivantes.

- Lors de l'utilisation des bibliothèques gratuites » Oracle Instant Client, faites ce qui suit :

      ./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib

  Si Instant Client 12.2 (ou une version antérieure) est installé à partir de fichiers ZIP, il faut s'assurer de créer d'abord le lien symbolique vers la bibliothèque, par exemple `ln -s libclntsh.so.12.1 libclntsh.so`.

  Lors de l'utilisation d'une installation basée sur RPM d'Oracle Instant Client, la ligne de configuration ressemblera à ceci :

      ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib

  Par exemple, --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib

- Lors de l'utilisation d'une base de données Oracle ou une installation complète d'Oracle Client, procédez comme suit :

      ./configure --with-oci8=shared,$ORACLE_HOME

  Il faut s'assurer que l'utilisateur du serveur web (`nobody`, `www`) a accès aux bibliothèques, aux fichiers d'initialisation et au fichier tnsnames.ora (si utilisé) sous le répertoire `$ORACLE_HOME`. Avec Oracle 10gR2, il faudra peut-être exécuter l'utilitaire $ORACLE_HOME/install/changePerm.sh pour donner accès au répertoire.

Après la configuration, suivez la procédure habituelle de compilation de PHP, par exemple make install. L'extension partagée OCI8 oci8.so sera créée. Il peut être nécessaire de la déplacer manuellement dans le répertoire des extensions PHP, spécifié par l'option extension_dir dans le fichier php.ini.

Pour terminer l'installation d'OCI8, modifiez le fichier php.ini et ajoutez la ligne :

    extension=oci8.so

## Installation d'OCI8 en tant qu'extension statiquement compilée lors de la compilation de PHP

Si on compile PHP à partir du code source, il est possible de configurer PHP pour inclure OCI8 en tant qu'extension statique en utilisant l'une des options de configuration suivantes.

- Lors de l'utilisation d'Oracle Instant Client, faites ce qui suit :

      ./configure --with-oci8=instantclient,/path/to/instant/client/lib

- Lors de l'utilisation d'une base de données Oracle ou une installation complète du client Oracle, faites ce qui suit :

      ./configure --with-oci8=$ORACLE_HOME

Après la configuration, suivez la procédure habituelle de construction de PHP, par exemple make install. Après une compilation réussie, il n'est pas nécessaire d'ajouter oci8.so au php.ini. Aucune étape supplémentaire de construction n'est requise.

## Installation d'OCI8 sous Windows

La bibliothèque OCI8 peut être ajoutée à une installation existante de PHP en utilisant les DLL du référentiel » PECL ou les bibliothèques situées dans le répertoire `ext` de l'installation PHP.

Avec les bibliothèques Oracle 12c (ou ultérieures), décommentez l'une des lignes suivantes dans le fichier php.ini `extension=php_oci8_12c.dll` ou `extension=php_oci8_11g.dll`, ou bien `extension=php_oci8.dll`. Seule une de ces DLL doit être active au même moment. Les DLLs avec des versions supérieures peuvent contenir plus de fonctionnalités. Toutes les DLLs peuvent ne pas être disponibles pour toutes les versions de PHP. Il faut s'assurer que l'option extension_dir est définie sur le dossier contenant les extensions DLLs de PHP.

Lors de l'utilisation du client Oracle Instant, définissez la variable d'environnement PATH du système au dossier contenant les bibliothèques Oracle.

## Définition de l'environnement Oracle

Avant d'utiliser cette extension, il faut s'assurer que les variables d'environnement Oracle sont correctement définies pour l'utilisateur exécutant le serveur Web. Si le serveur Web est automatiquement démarré au démarrage du serveur, alors il faut s'assurer également de la bonne configuration de la variable d'environnement utilisée à ce moment-ci.

> Note:

> Ne définissez pas les variables d'environnement Oracle en utilisant la fonction putenv() dans les scripts PHP, car les bibliothèques Oracle sont chargées et initialisées avant l'exécution du script. Les variables définies avec putenv() pourraient ainsi entrer en conflit et provoquer aussi bien des crashs que des comportements totalement inattendus. Des fonctions peuvent réagir normalement, d'autres peuvent provoquer des erreurs. Les variables doivent être définies avant le démarrage du serveur.

Sous les systèmes Red Hat Linux et ces variantes, il faut exporter les variables à la fin du fichier /etc/sysconfig/httpd. Sous les autres systèmes utilisant Apache 2, il faut utiliser le script envvars qu'on trouvera dans le dossier bin d'Apache. Une autre option consiste à utiliser la directive `SetEnv` du fichier httpd.conf, mais ceci peut ne pas être suffisant sur quelques systèmes.

Pour vérifier si les variables d'environnement ont été définies correctement, utiliser la fonction phpinfo() et s'attarder sur la section Environment (et non la section Apache Environment) ; elle doit contenir toutes les variables définies.

Les variables qui pourraient être nécessaires sont incluses dans le tableau suivant. Se reporter à la documentation Oracle pour plus d'informations sur toutes les variables.

Variables d'environnement Oracle communes
Nom | But
--- | ---
ORACLE_HOME | Chemin vers le dossier contenant le logiciel de base de données Oracle. Ne définissez pas cette variable lors de l'utilisation du client Oracle Instant. En effet, elle n'est pas nécessaire mais peut causer des problèmes lors de l'installation.
ORACLE_SID | Le nom de la base de données sur la machine locale. Il n'est pas nécessaire de la définir lors de l'utilisation du client Oracle Instant, ou alors, passez la toujours comme paramètre de connexion à la fonction oci_connect().
LD_LIBRARY_PATH | Définir cette variable (ou son équivalent sur la plateforme courante, comme `LIBPATH`, ou `SHLIB_PATH`) comme le chemin vers les bibliothèques Oracle, par exemple $ORACLE_HOME/lib ou /usr/lib/oracle/19/client/lib. Cette variable n'est pas nécessaire si les bibliothèques sont localisées par un mécanisme de recherche différent, comme avec ldconfig ou avec `LD_PRELOAD` au lieu de `LD_LIBRARY_PATH`.
NLS_LANG | C'est la variable principale pour définir le jeu de caractères et les informations de globalisation utilisés par les bibliothèques Oracle.
ORA_SDTZ | Définit le décalage horaire à utiliser par les sessions Oracle.
TNS_ADMIN | Chemin vers le dossier contenant les fichiers de configuration Oracle Net Services (tnsnames.ora et sqlnet.ora). Inutile si la chaîne de connexion utilisée par la fonction oci_connect() est au format de connexion facile comme `localhost/XE`. Inutile également si les fichiers de configuration du réseau sont à des endroits par défaut comme /usr/lib/oracle/VERSION/client/lib/network/admin, $ORACLE_HOME/network/admin ou /etc.

Il existe d'autres variables d'environnement Oracle moins souvent utilisées, comme `TWO_TASK`, `ORA_TZFILE`, ainsi que les diverses variables de globalisation comme `NLS*` et `ORA_NLS_*`.

## En cas de problème

Le problème le plus courant lors de l'installation d'OCI8 est de ne pas avoir configuré correctement les variables d'environnement. C'est un problème typique lorsqu'on reçoit un message d'erreur lors de l'utilisation des fonctions oci_connect() ou oci_pconnect(). L'erreur peut être une erreur purement PHP comme Call to undefined function oci_connect(), une erreur Oracle comme ORA-12705 ou encore un arrêt brutal d'Apache. Vérifier le contenu des fichiers de log d'Apache lors de son démarrage et se reporter aux sections ci-dessus pour résoudre le problème.

Alors que les erreurs réseaux comme ORA-12154 ou ORA-12514 indiquent un problème quant au nommage du réseau ou un problème de configuration, bien souvent, la cause première est que l'environnement PHP n'est pas correctement défini et que les bibliothèques Oracle sont incapables de trouver le fichier de configuration tnsnames.ora.

Sous Windows, le fait d'avoir plusieurs versions d'Oracle sur la même machine peut facilement faire crasher l'installation tant que l'on ne s'est pas assuré que PHP n'utilise pas uniquement la bonne version d'Oracle.

Un utilitaire permettant d'examiner les bibliothèques recherchées et chargées peut aider quant à la résolution de ce genre de problème, tout particulièrement sous Windows.

> Note: Si le serveur Web ne démarre pas ou échoue au démarrage

> Vérifier qu'Apache est lié avec la bibliothèque pthread :

>     # ldd /www/apache/bin/httpd
>       libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
>       libm.so.6 => /lib/libm.so.6 (0x4002f000)
>       libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
>       libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
>       libc.so.6 => /lib/libc.so.6 (0x4007e000)
>       /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

> Si la bibliothèque libpthread n'est pas listée, réinstallez Apache :

>     # cd /usr/src/apache_1.3.xx
>     # make clean
>     # LIBS=-lpthread ./config.status
>     # make
>     # make install

> À noter que sous des systèmes comme UnixWare, la bibliothèque s'appelle libthread au lieu de libpthread. PHP et Apache doivent être configurés avec EXTRA_LIBS=-lthread.

## Test

La suite permettant de tester OCI8 se trouve dans le dossier ext/oci8/tests. Après avoir effectué les tests OCI8, ce dossier contiendra, en plus, les fichiers de journalisation permettant de tracer l'ensemble des erreurs produites.

Avant d'effectuer les tests PHP, éditez le fichier details.inc et définissez les variables de connexion $user, $password et $dbase. La suite de test OCI8 a été développée en utilisant le compte `SYSTEM`. Quelques tests échoueront si l'utilisateur choisi pour effectuer le test n'a pas des permissions équivalentes à ce compte.

Si la file d'attente de connexion de la base de données Oracle est testée, définissez la variable $test_drcp à `true` et il faut s'assurer que la chaîne de connexion utilise un serveur de file d'attente DRCP approprié.

Une alternative à l'édition du fichier details.inc est de définir les variables d'environnement, par exemple :

        $ export PHP_OCI8_TEST_USER=system
        $ export PHP_OCI8_TEST_PASS=oracle
        $ export PHP_OCI8_TEST_DB=localhost/XE
        $ export PHP_OCI8_TEST_DRCP=FALSE

À noter que suivant les shells utilisés, ces variables ne seront pas forcément propagées jusqu'au processus PHP et le test échouera au niveau de la connexion si cette méthode est utilisée.

Puis, définissez tous les environnements nécessaires à la base de données Oracle. Si on exécute PHP sur la même machine que la base de données Oracle, il est possible de faire :

        $ . /usr/local/bin/oraenv

Avec Oracle 11gR2 XE, faites :

        $ . /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh

Quelques shells nécessitent que le fichier php.ini ait un `E` dans le paramètre variables_order, par exemple :

        variables_order = "EGPCS"

Exécuter tous les tests PHP avec la commande :

        $ cd your_php_src_directory
        $ make test

ou exécutez uniquement les tests OCI8 avec la commande :

        $ cd your_php_src_directory
        $ make test TESTS=ext/oci8

Lorsque les tests sont terminés, il est possible d'alors investiguer sur les erreurs rencontrées. Sur les systèmes lents, quelques tests peuvent prendre plus de temps que le délai maximal d'exécution défini dans le fichier run-tests.php. Pour corriger ceci, définissez la variable d'environnement `TEST_TIMEOUT` à une valeur plus grande.

Sur les machines rapides dont la base de données locale est configurée pour une charge minimale (c.-à-d. Oracle 10gR2 XE), quelques tests peuvent échouer avec des erreurs ORA-12516 ou ORA-12520. Pour prévenir ce comportement, augmentez le paramètre `PROCESSES` de la base de données en utilisant les étapes suivantes :

Connexion avec l'utilisateur oracle :

      $ su - oracle

Définir l'environnement nécessaire à Oracle grâce au fichier oracle_env.sh ou oraenv, tel que défini ci-dessus.

Démarrer l'utilitaire en ligne de commande SQL*Plus et augmenter la valeur du paramètre `PROCESSES`

        $ sqlplus / as sysdba
        SQL> alter system set processes=100 scope=spfile

Redémarrer la base de données :

        SQL> startup force

## Configuration à l'exécution

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

Options de configuration OCI8
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
oci8.connection_class | "" | `INI_ALL` |
oci8.default_prefetch | "100" | `INI_SYSTEM` |
oci8.events | Off | `INI_SYSTEM` |
oci8.max_persistent | "-1" | `INI_SYSTEM` |
oci8.old_oci_close_semantics | Off | `INI_SYSTEM` | Obsolète à partir de PHP 8.1.0.
oci8.persistent_timeout | "-1" | `INI_SYSTEM` |
oci8.ping_interval | "60" | `INI_SYSTEM` |
oci8.prefetch_lob_size | "0" | `INI_SYSTEM` | Disponible à partir de PECL OCI8 3.2.
oci8.privileged_connect | Off | `INI_SYSTEM` |
oci8.statement_cache_size | "20" | `INI_SYSTEM` |

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

`oci8.connection_class` string

  Le texte défini par l'utilisateur est utilisé par les connexions du pool de connexions résidantes de la base de données Oracle 11g pour partitionner le pool. Cela permet aux connexions persistantes OCI8 d'une application de réutiliser les sessions à la base de données depuis un script précédent, permettant ainsi une meilleure efficacité. Lorsqu'une application utilise un processus de base de données précédemment utilisé avec une classe de connexion différente, les configurations de la session, comme le format de la date par défaut d'Oracle, seront réinitialisées. Ce comportement permet d'éviter de partager accidentellement des informations entre les différentes applications.

  La valeur peut être définie au moment de l'exécution grâce à la fonction ini_set(), appelée avant la connexion.

  Pour utiliser DRCP, OCI8 doit être lié avec les bibliothèques Oracle 11g et la base de données doit être Oracle 11g. Le pool de connexion doit être activé dans la base de données, l'option de configuration `oci8.connection_class` doit valoir la même chaîne pour tous les serveurs web utilisant la même application, et la chaîne de connexion OCI8 doit spécifier d'utiliser un serveur utilisant un pool.

`oci8.default_prefetch` int

  Cette option définit le nombre par défaut de lignes supplémentaires qui seront récupérées et mises en cache automatiquement chaque fois qu'une requête de bas niveau récupérant des données depuis la base de données sera effectuée. Le fait de définir une valeur de `0` permet de désactiver cette fonctionnalité.

  La valeur de pré-chargement n'altère pas le nombre de lignes que des fonctions comme oci_fetch_array() retournent à l'utilisateur ; le pré-chargement et la mise en cache de lignes est géré en interne par OCI8.

  La valeur peut être définie pour chaque requête, en exécutant la fonction oci_set_prefetch() avant l'exécution de la requête.

  Lors de l'utilisation d'Oracle 12c ou ultérieur, la valeur de pré-chargement définie par PHP peut être surchargée par le fichier de configuration du client oracle : `oraaccess.xml`. Consulter la documentation d'Oracle pour plus d'informations.

  > Note: Si l'on entre une valeur trop importante, cela peut conduire à une amélioration des performances, au détriment de l'utilisation mémoire. Pour des requêtes qui retournent un grand nombre de données, le gain de performance peut être vraiment significatif.

`oci8.events` bool

  Définir à `On` cette option permet à PHP d'être notifié des événements de base de données FAN (`Fast Application Notification`).

  Sans FAN, lorsqu'une instance de la base de données ou bien un nœud de machines échoue brutalement, les applications PHP peuvent se bloquer en attendant une réponse de la base de données, jusqu'au bout du délai d'expiration TCP. Avec les événements FAN, les applications PHP sont notifiées rapidement des erreurs qui affectent les connexions à la base de données. L'extension OCI8 nettoiera les connexions inutilisables dans le cache des connexions persistantes.

  Lorsqu'on utilise `On` comme valeur, la base de données doit également être configurée pour émettre les événements FAN.

  Le support de FAN est disponible lorsque OCI8 est lié à des bibliothèques Oracle 10gR2 (et suivants) et connecté à une base de données Oracle 10gR2 (et suivants).

`oci8.max_persistent` int

  Le nombre maximal de connexions persistantes OCI8 par processus PHP. Le fait de définir cette option à -1 signifie qu'il n'y a aucune limite.

`oci8.old_oci_close_semantics` bool

  Cette option contrôle le comportement de la fonction oci_close(). Activer cette option signifie que oci_close() ne fera rien du tout ; la connexion ne sera pas fermée tant que la fin du script ne sera pas atteinte. Ceci est uniquement pour assurer une compatibilité ascendante. Si on pense qu'il faut activer cette option, on est vivement encouragé à effacer les appels à la fonction oci_close() de l'application au lieu d'activer cette option.

`oci8.persistent_timeout` int

  Le délai maximal (en secondes) qu'un processus PHP donné est autorisé à maintenir une connexion persistante. Le fait de définir cette option à -1 signifie que les connexions persistantes seront toujours maintenues tant que le processus PHP ne se termine ou bien que la connexion est explicitement fermée à l'aide de la fonction oci_close().

  > Note: En PHP, l'expiration des ressources persistantes ne produit aucune alerte. Elle survient lorsque PHP termine un script et vérifie le timestamp de la dernière utilisation de la ressource. Aussi, le paradoxe veut que les connexions persistantes ne peuvent être closes que lors d'une quelconque activité (non nécessaire en OCI8) dans le processus PHP. S'il y a plus d'un processus PHP, alors chacun d'eux doit être activé manuellement afin de lancer l'expiration de leurs propres ressources. L'introduction du pool de connexions persistantes (DRCP) en Oracle 11g résout les problèmes de mémoire et de ressources, que les options `oci8.max_persistent` et `oci8.persistent_timeout` ont tenté précédemment de résoudre.

`oci8.ping_interval` int

  Le délai maximal (en secondes) à attendre avant d'envoyer un ping durant oci_pconnect(). Lorsque définie à 0, les connexions persistantes seront vérifiées à chaque réutilisation. Pour désactiver complètement les ping, définissez cette option à -1.

  > Note: Le fait de désactiver les pings rend les appels à oci_pconnect() hautement rentables, mais cela empêche PHP de détecter les problèmes de connexion, comme les problèmes de réseau, ou si le serveur Oracle a été éteint depuis la connexion de PHP, tant que la connexion n'est pas utilisée plus tard dans le script. Consulter la documentation de la fonction oci_pconnect() pour plus d'informations.

`oci8.prefetch_lob_size` int

  Il s'agit d'un paramètre de réglage affectant la mise en mémoire tampon interne des données LOB. L'augmentation de cette valeur peut améliorer les performances de récupération des petits LOB en réduisant les allers-retours entre PHP et la base de données. L'utilisation de la mémoire changera.

  La valeur affecte les LOB renvoyés en tant qu'instances OCILob ainsi que ceux renvoyés à l'aide de `OCI_RETURN_LOBS`.

  La valeur peut être définie par instruction avec oci_set_prefetch_lob() avant l'exécution de l'instruction.

  > Note: À utiliser avec Oracle Database 12.2 ou ultérieur.

`oci8.privileged_connect` bool

  Cette option active les connexions privilégiées en utilisant les droits externes (`OCI_SYSOPER`, `OCI_SYSDBA`).

  > Note: Le fait de définir cette valeur à `On` permet aux scripts du serveur web exécutant les privilèges utilisateurs systèmes appropriés de se connecter à la base de données en utilisant ces privilèges, sans avoir besoin de fournir un mot de passe à la base de données. Ceci peut avoir des conséquences au niveau de la sécurité.

`oci8.statement_cache_size` int

  Cette option active la mise en cache des requêtes, et spécifie le nombre de requêtes à mettre en cache. Pour désactiver la mise en cache des requêtes, définissez cette option à 0.

  La mise en cache des requêtes permet de ne plus avoir besoin de transmettre le texte de la requête à la base de données, mais aussi, de ne plus avoir besoin de transmettre de méta-données sur la requête à PHP. Ceci permet d'accroître significativement les performances systèmes dans les applications, en ré-utilisant les requêtes durant toute la vie de la connexion. Des "curseurs" de base de données peuvent également aider si l'on part du principe que des requêtes seront ré-utilisées.

  Définir cette valeur à la taille du jeu de requêtes courantes utilisées par l'application. Le fait de définir une valeur trop petite peut faire que les requêtes seront supprimées du cache avant qu'elles ne soient utilisées.

  Cette option est la plus utilisée avec les connexions persistantes.

  Avec la base de données Oracle 12c, cette valeur peut être surchargée et automatiquement ajustée par le fichier `oraaccess.xml` du client Oracle. Voir la documentation d'Oracle pour plus d'explications.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Méthodes et fonctions OCI8
Constante | Description
--- | ---
`OCI_ASSOC` | Utilisé avec oci_fetch_all() et oci_fetch_array() pour récupérer les résultats dans un tableau associatif.
`OCI_BOTH` | Utilisé avec oci_fetch_all() et oci_fetch_array() pour récupérer les résultats dans un tableau associatif et indexé numériquement.
`OCI_COMMIT_ON_SUCCESS` | Mode d'exécution des commandes pour oci_execute(). La commande est automatiquement validée après réussite de la requête.
`OCI_CRED_EXT` | Utilisé avec oci_connect() pour identification sur un serveur Oracle externe ou sur le système d'exploitation.
`OCI_DEFAULT` | Voir la constante `OCI_NO_AUTO_COMMIT`.
`OCI_DESCRIBE_ONLY` | Mode d'exécution des commandes pour oci_execute(). Ce mode est à utiliser si l'on ne souhaite pas exécuter la commande, mais obtenir des descriptions.
`OCI_EXACT_FETCH` | Obsolète. Mode de lecture de résultats. Utilisé lorsque les applications savent à l'avance le nombre de lignes qu'il faudra lire. Ce mode désactive la lecture anticipée d'Oracle version 8 et plus récente. Le curseur est annulé une fois que le nombre de lignes à lire a été atteint, et cela réduit les ressources consommées côté serveur.
`OCI_FETCHSTATEMENT_BY_COLUMN` | Mode par défaut de oci_fetch_all().
`OCI_FETCHSTATEMENT_BY_ROW` | Mode alternatif pour oci_fetch_all().
`OCI_LOB_BUFFER_FREE` | Utilisé avec OCILob::flush pour libérer les buffers utilisés.
`OCI_NO_AUTO_COMMIT` | Mode d'exécution de la requête pour oci_execute(). La transaction n'est pas automatiquement validée lors de l'utilisation de ce mode. Pour plus de lisibilité dans le code, utiliser cette valeur plutôt que l'ancienne valeur `OCI_DEFAULT`.
`OCI_NUM` | Utilisé avec oci_fetch_all() et oci_fetch_array() pour lire un tableau énuméré.
`OCI_RETURN_LOBS` | Utilisé avec oci_fetch_array() pour obtenir la valeur du LOB au lieu du pointeur.
`OCI_RETURN_NULLS` | Utilisé avec oci_fetch_array() pour obtenir des éléments vides, si la valeur du champ est `null`.
`OCI_SEEK_CUR` | Utilisé avec OCILob::seek pour définir la position.
`OCI_SEEK_END` | Utilisé avec OCILob::seek pour définir la position.
`OCI_SEEK_SET` | Utilisé avec OCILob::seek pour définir la position.
`OCI_SYSDATE` | Obsolète.
`OCI_SYSDBA` | Utilisé avec oci_connect() pour se connecter comme SYSDBA utilisant des identifiants externes (oci8.privileged_connect doit être activé pour utiliser cette constante).
`OCI_SYSOPER` | Utilisé avec oci_connect() pour se connecter comme SYSOPER utilisant des identifiants externes (oci8.privileged_connect doit être activé pour utiliser cette constante).
`OCI_TEMP_BLOB` | Utilisé avec OCILob::writeTemporary pour indiquer explicitement qu'un BLOB temporaire doit être créé.
`OCI_TEMP_CLOB` | Utilisé avec OCILob::writeTemporary pour indiquer explicitement qu'un CLOB temporaire doit être créé.

Types définis et liés OCI8
Constante | Description
--- | ---
`OCI_B_BFILE` | Utilisé avec oci_bind_by_name() pour relier des BFILEs.
`OCI_B_BIN` | Utilisé avec oci_bind_by_name() pour relier les valeurs brutes (RAW).
`OCI_B_BLOB` | Utilisé avec oci_bind_by_name() pour relier des BLOB.
`OCI_B_BOL` | Utilisé avec oci_bind_by_name() pour lier une variable booléenne PL/SQL.
`OCI_B_CFILEE` | Utilisé avec oci_bind_by_name() pour relier des CFILEs.
`OCI_B_CLOB` | Utilisé avec oci_bind_by_name() pour relier des CLOB.
`OCI_B_CURSOR` | Utilisé avec oci_bind_by_name() pour relier des curseurs, précédemment alloués avec oci_new_descriptor().
`OCI_B_INT` | Utilisé avec oci_bind_array_by_name() pour relier des tableaux d'entiers.
`OCI_B_NTY` | Utilisé avec oci_bind_by_name() pour relier des noms de types de données.
`OCI_B_NUM` | Utilisé avec oci_bind_array_by_name() pour relier des tableaux de nombres.
`OCI_B_ROWID` | Utilisé avec oci_bind_by_name() pour relier des ROWID.
`SQLT_AFC` | Utilisé avec oci_bind_array_by_name() pour lier les tableaux de CHAR.
`SQLT_AVC` | Utilisé avec oci_bind_array_by_name() pour lier les tableaux de VARCHAR2.
`SQLT_BDOUBLE` | Non supporté.
`SQLT_BFILEE` | Identique à `OCI_B_BFILE`.
`SQLT_BFLOAT` | Non supporté.
`SQLT_BIN` | Identique à `OCI_B_BIN`.
`SQLT_BLOB` | Identique à `OCI_B_BLOB`.
`SQLT_BOL` | Identique à `OCI_B_BOL`.
`SQLT_CFILEE` | Identique à `OCI_B_CFILEE`.
`SQLT_CHR` | Utilisé avec oci_bind_array_by_name() pour lier les tableaux de VARCHAR2. Utilisé également avec oci_bind_by_name().
`SQLT_CLOB` | Identique à `OCI_B_CLOB`.
`SQLT_FLT` | Utilisé avec oci_bind_array_by_name() pour lier les tableaux de FLOAT.
`SQLT_INT` | Identique à `OCI_B_INT`.
`SQLT_LBI` | Utilisé avec oci_bind_by_name() pour lier les valeurs LONG RAW.
`SQLT_LNG` | Utilisé avec oci_bind_by_name() pour lier les valeurs LONG.
`SQLT_LVC` | Utilisé avec oci_bind_array_by_name() pour lier les tableaux de LONG VARCHAR.
`SQLT_NTY` | Identique à `OCI_B_NTY`.
`SQLT_NUM` | Identique à `OCI_B_NUM`.
`SQLT_ODT` | Utilisé avec oci_bind_array_by_name() pour lier les tableaux de LONG.
`SQLT_RDD` | Identique à `OCI_B_ROWID`.
`SQLT_RSET` | Identique à `OCI_B_CURSOR`.
`SQLT_STR` | Utilisé avec oci_bind_array_by_name() pour lier les tableaux de STRING.
`SQLT_UIN` | Non supporté.
`SQLT_VCS` | Utilisé avec oci_bind_array_by_name() pour lier les tableaux de VARCHAR.

Types des descripteurs OCI8
Constante | Description
--- | ---
`OCI_DTYPE_FILE` | Cette option indique à oci_new_descriptor() d'initialiser un nouveau pointeur FILE.
`OCI_DTYPE_LOB` | Cette option indique à oci_new_descriptor() d'initialiser un nouveau descripteur LOB.
`OCI_DTYPE_ROWID` | Cette option indique à oci_new_descriptor() d'initialiser un nouveau descripteur ROWID.
`OCI_D_FILE` | Identique à `OCI_DTYPE_FILE`.
`OCI_D_LOB` | Identique à `OCI_DTYPE_LOB`.
`OCI_D_ROWID` | Identique à `OCI_DTYPE_ROWID`.

Constantes | Description
--- | ---
Constantes OCI8 pour le basculement transparent d'application (TAF)
`OCI_FO_ABORT` (int) | Le basculement a échoué et il n'y a aucune possibilité de réessayer.
`OCI_FO_BEGIN` (int) | Le basculement a détecté une connexion perdue et le basculement commence.
`OCI_FO_END` (int) | Le basculement s'est terminé avec succès.
`OCI_FO_ERROR` (int) | Le basculement a échoué mais il donne à l'application la possibilité de gérer l'erreur et de renvoyer `OCI_FO_RETRY` pour réessayer le basculement.
`OCI_FO_NONE` (int) | L'utilisateur n'a pas demandé de type de basculement.
`OCI_FO_REAUTH` (int) | Un utilisateur Oracle a été réauthentifié.
`OCI_FO_RETRY` (int) | Le basculement doit être réessayé par Oracle. En cas d'erreur lors du basculement vers une nouvelle connexion, TAF peut réessayer le basculement. Typiquement, le code de l'application doit dormir pendant un certain temps avant de renvoyer `OCI_FO_RETRY`.
`OCI_FO_SELECT` (int) | L'utilisateur a également demandé le basculement SELECT. Il permet aux utilisateurs avec des curseurs ouverts de continuer à les utiliser après une panne.
`OCI_FO_SESSION` (int) | L'utilisateur a demandé uniquement le basculement de session. Par exemple, si la connexion d'un utilisateur est perdue, alors une nouvelle session est automatiquement créée pour l'utilisateur sur la sauvegarde. Ce type de basculement ne tente pas de récupérer les SELECT.
`OCI_FO_TXNAL` (int) | L'utilisateur a demandé un basculement de transaction.

# Exemples

Ces exemples utilisent, pour se connecter à la base de données, l'utilisateur `HR` qui est le schéma `"Human Resources"` fourni par la base de données Oracle. Ce compte doit avoir été déverrouillé et le mot de passe réinitialisé avant de pouvoir l'utiliser.

Ces exemples se connectent à la base de données `XE` de la machine. Modifier la chaîne de connexion afin de correspondre à la base de données avant d'exécuter les exemples de cette documentation.

Exemple #1 Requête simple

Cet exemple montre l'exécution d'une requête et l'affichage des résultats. Les requêtes OCI8 utilisent les étapes préparation/exécution/récupération des données.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Préparation de la requête
    $stid = oci_parse($conn, 'SELECT * FROM departments');
    if (!$stid) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Exécution de la logique de la requête
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Récupération des résultats de la requête
    print "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        print "<tr>\n";
        foreach ($row as $item) {
            print "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        print "</tr>\n";
    }
    print "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #2 Insertion de données en utilisant des variables liées

Les variables liées augmentent les performances en permettant la réutilisation du cache et du contexte d'exécution. Les variables liées augmentent également la sécurité en prévenant bon nombre d'injections SQL.

    <?php

    // Avant l'exécution, créez la table suivante :
    //   CREATE TABLE MYTABLE (mid NUMBER, myd VARCHAR2(20));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO MYTABLE (mid, myd) VALUES(:myid, :mydata)');

    $id = 60;
    $data = 'Some data';

    oci_bind_by_name($stid, ':myid', $id);
    oci_bind_by_name($stid, ':mydata', $data);

    $r = oci_execute($stid);  // exécution et validation

    if ($r) {
        print "Une ligne insérée";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #3 Liage d'une clause WHERE d'une requête

Ceci montre le liage simple.

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // Affiche :
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #4 Insertion de données dans une colonne CLOB

Pour de lourdes données, utiliser un objet binaire long (BLOB) ou un objet de caractères long (CLOB). Cet exemple utilise les CLOB.

    <?php

    // Avant l'exécution, créez la table suivante :
    //     CREATE TABLE MYTABLE (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $mykey = 12343;  // clé arbitraire pour l'exemple

    $sql = "INSERT INTO mytable (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_NO_AUTO_COMMIT);
    $clob->save("Une chaîne vraiment très longue");

    oci_commit($conn);

    // Récupération de données CLOB

    $query = 'SELECT myclob FROM mytable WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // Dans une boucle, le fait de libérer la variable avant de récupérer la
        // seconde ligne permet de réduire l'utilisation mémoire de PHP
        unset($row);
    }
    print '</table>';

    ?>

Exemple #5 Utilisation d'une procédure stockée PL/SQL

Il faut lier une variable pour la valeur retournée et, optionnellement, pour tous les arguments de la fonction PL/SQL.

    <?php

    /*
      Avant d'exécuter le programme PHP, créez une fonction stockée
      en langage SQL*Plus ou SQL Developer :

      CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
      BEGIN
          RETURN p * 3;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // Affiche 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #6 Utilisation d'une procédure stockée PL/SQL

Avec les procédures stockées, il faut lier les variables pour tous les arguments.

    <?php

    /*
      Avant d'exécuter le programme PHP, créez une procédure stockée en
      langage SQL*Plus ou SQL Developer :

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // affiche 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #7 Appel d'une fonction PL/SQL qui retourne un `REF CURSOR`

Chaque valeur retournée par la requête est un `REF CURSOR` à utiliser pour récupérer les données.

    <?php
    /*
      Créez une fonction stockée PL/SQL comme ceci :

      CREATE OR REPLACE FUNCTION myfunc(p1 IN NUMBER) RETURN SYS_REFCURSOR AS
          rc SYS_REFCURSOR;
      BEGIN
          OPEN rc FOR SELECT city FROM locations WHERE ROWNUM < p1;
          RETURN rc;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myfunc(5) AS mfrc FROM dual');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
        echo "<tr>\n";
        $rc = $row['MFRC'];
        oci_execute($rc);  // La valeur de la colonne retournée depuis la requête est une référence de curseur
        while (($rc_row = oci_fetch_array($rc, OCI_ASSOC))) {
            echo "    <td>" . $rc_row['CITY'] . "</td>\n";
        }
        oci_free_statement($rc);
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Affiche :
    //   Beijing
    //   Bern
    //   Bombay
    //   Geneva

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# Gestion de la connexion OCI8 et de la mise en file d'attente

## Fonctions de connexion

L'extension oci8 fournit trois fonctions différentes pour se connecter à Oracle. La fonction de connexion standard est la fonction oci_connect(). Cette fonction crée une connexion à la base de données Oracle et retourne une ressource utilisée par les futurs appels à la base de données.

La connexion à un serveur Oracle est une opération raisonnablement coûteuse en termes de temps que cela nécessite. La fonction oci_pconnect() utilise un cache persistant de connexions qui peut être réutilisé à travers différents scripts. Cela signifie qu'une seule connexion sera utilisée par processus PHP (ou un fils Apache).

Si l'application se connecte à Oracle en utilisant un jeu différent de droits de base de données pour chaque utilisateur web, le cache persistant utilisé par la fonction oci_pconnect() devient moins approprié car l'augmentation du nombre d'utilisateurs concurrents va affecter les performances du serveur Oracle, car il devra maintenir trop de connexions en cache. Si l'application est de ce type, il est recommandé d'optimiser l'application en utilisant les options de configuration oci8.max_persistent et oci8.persistent_timeout (elles donnent le contrôle sur la taille et la durée de vie du cache de connexions persistantes) ou utiliser le pool de connexions résidentes d'Oracle (pour les bases de données Oracle 11g et suivants), ou encore, utiliser plutôt la fonction oci_connect().

Les fonctions oci_connect() et oci_pconnect() emploient un cache de connexions ; si on fait des appels multiples à oci_connect(), en utilisant les mêmes paramètres dans un script donné, le second appel ainsi que les suivants retournent le gestionnaire de connexion existant. Le cache utilisé par la fonction oci_connect() est nettoyé à la fin de l'exécution du script ou lorsqu'on ferme explicitement le gestionnaire de connexion. oci_pconnect() a un comportement sensiblement identique, à la différence que le cache est maintenu séparément et est conservé entre les requêtes HTTP.

Il est important de se souvenir de cette fonctionnalité de cache, car elle donne l'apparence que les deux gestionnaires ne sont pas isolés au niveau des transactions, (ils représentent en fait le même gestionnaire de connexion, ils ne sont donc absolument pas isolés). Si l'application a besoin de deux connexions séparées, isolées au niveau des transactions, il faut utiliser la fonction oci_new_connect().

Le cache de la fonction oci_pconnect() est effacé et toutes les connexions à la base de données sont closes lorsque le processus PHP se termine, aussi, les connexions persistantes n'ont d'intérêt que lors de l'utilisation de PHP comme module Apache ou utilisé avec FPM ou similaire. Les connexions persistantes n'ont aucun intérêt via oci_connect() lorsque PHP est utilisé comme CGI ou en ligne de commande.

oci_new_connect() crée toujours une nouvelle connexion au serveur Oracle, indépendamment de l'existence d'autres connexions. Les applications web à fort trafic doivent éviter d'utiliser oci_new_connect(), particulièrement dans les sections les plus chargées de l'application.

Les connexions persistantes peuvent désormais être fermées par l'utilisateur, permettant ainsi un meilleur contrôle des ressources de connexion. Les connexions persistantes peuvent maintenant être fermées automatiquement lorsqu'aucune variable PHP ne les référence, comme ce pourrait être le cas à la fin d'un contexte d'une fonction utilisateur PHP. Ceci annulera toutes les transactions non validées. Ces changements dans les connexions persistantes font qu'elles fonctionnent comme les fonctions non-persistantes, simplifiant l'interface, permettant une plus grande cohérence de l'application et de prévisibilité. Définir la directive oci8.old_oci_close_semantics à On pour retrouver le comportement historique.

Le ré-établissement automatique des connexions persistantes PHP après le redémarrage d'un processus Apache ou FPM fait que les triggers `LOGON` sont uniquement recommandés pour définir les attributs de session et non les requêtes de connexions utilisateurs par application.

## Pool de connexion DRCP

PHP supporte le pool de connexions résidentes Oracle (DRCP). DRCP permet d'utiliser plus efficacement la mémoire de la base de données et permet une meilleure évolution. Peu ou pas de modifications sont nécessaires afin de profiter de DRCP.

DRCP est prévu pour les applications qui se connectent en utilisant peu de schéma de base de données, et qui conservent les connexions ouvertes sur une courte période de temps. Les autres applications doivent utiliser le processus dédié à la base de données Oracle, ou utiliser les serveurs partagés.

DRCP bénéficie des 3 fonctions de connexion, mais seule la fonction oci_pconnect() offre le plus de performance.

Pour rendre DRCP disponible avec OCI8, la version des bibliothèques clientes Oracle utilisées par PHP ainsi que la version de la base de données Oracle doivent être 11g ou supérieure.

La documentation sur DRCP peut être trouvée dans les différents manuels Oracle. Par exemple, se reporter à la » configuration du pool de connexions résidentes à la base de données de la documentation Oracle pour un exemple d'utilisation. Un » livre blanc sur DRCP contient plusieurs informations internes sur DRCP.

Pour utiliser DRCP, installer l'extension OCI8 et les bibliothèques Oracle 11g (ou ultérieur), puis, suivre ces étapes :

- En utilisant les privilèges d'administrateur de la base de données, utiliser un programme comme SQL*Plus pour commencer un pool de connexion à la base de données :

          SQL> execute dbms_connection_pool.start_pool;

- Optionnellement, utiliser `dbms_connection_pool.alter_param()` pour configurer les options DRCP. Les options courantes du pool peuvent être trouvées en utilisant la vue `DBA_CPOOL_INFO`.

- Mettre à jour les chaînes de connexion utilisées. Pour les applications PHP qui se connectent actuellement via un nom de connexion réseau comme `MYDB`:

          $c = oci_pconnect("myuser", "mypassword", "MYDB");

  modifier le fichier tnsnames.ora et ajouter une clause `(SERVER=POOLED)`, par exemple :

          MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com)
                 (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales)
                 (SERVER=POOLED)))

  Sinon, il est possible de modifier la syntaxe de connexion facile en PHP et ajouter `:POOLED` après le nom du service :

          $c = oci_pconnect("myuser", "mypassword", "myhost.dom.com:1521/sales:POOLED");

- Éditer php.ini et choisir le nom de la classe de connexion. Ce nom indique une division logique du pool de connexion et peut être utilisé pour isoler le pool des différentes applications. Toutes applications PHP utilisant le même utilisateur ainsi que la même valeur de classe de connexion pourront se partager le pool de connexions, permettant ainsi d'obtenir une plus grande disponibilité.

          oci8.connection_class = "MY_APPLICATION_NAME"

- Exécuter l'application, se connecter à la base de données 11g (ou supérieur).

> Note:

> Les applications utilisant Oracle Client libraries 10g qui ont besoin de la performance des connexions persistantes, peuvent réduire la quantité de mémoire allouée au serveur de la base de données en utilisant les serveurs partagés Oracle (connu auparavant comme serveurs multithreadés). Se reporter à la documentation Oracle pour plus d'informations.

> Note:

> La modification d'un mot de passe lors de connexions DRCP échouera avec l'erreur "ORA-56609: Usage not supported with DRCP". Ceci est une restriction documentée de la base de données Oracle 11g.

# Support de FAN (Fast Application Notification : Application de notification Rapide) OCI8

Le support de FAN fournit un basculement de connexion rapide, une fonctionnalité de haute disponibilité pour la base de données Oracle. Il permet aux scripts PHP OCI8 d'être notifiés lorsqu'une machine de base de données ou une instance de base de données devient non disponible. Sans FAN, OCI8 peut se figer en cas d'atteinte du délai maximal TCP, et une erreur est retournée, ce qui peut prendre plusieurs minutes. L'activation de FAN en OCI8 permet aux applications de détecter les erreurs et de se re-connecter à une instance de connexion disponible sans que le serveur Web n'ait besoin d'en connaître.

Le support de FAN est disponible lorsque les bibliothèques clientes Oracle liées à PHP et la base de données Oracle sont en version 10gR2 ou supérieures.

FAN fait bénéficier aux utilisateurs de la technologie de cluster Oracle (RAC) car les connexions survivantes aux instances de base de données peuvent être effectuées immédiatement. Les utilisateurs de Data Guard Oracle avec un broker, vont voir les événements FAN générés lorsqu'une base de données passe en ligne. Les bases de données qui ne font pas partie d'un cluster vont envoyer des événements FAN lorsque la base de données redémarre.

Pour les connexions actives, lorsqu'une machine ou une instance de base de données devient indisponible, une erreur de connexion sera retournée par la fonction de l'extension OCI8 appelée. Lors d'une reconnexion d'un script sous-jacent PHP, une connexion à une instance de base de données survivante sera établie. L'extension OCI8 va également, de façon transparente, nettoyer toutes les connexions inactives affectées par une machine de base de données ou une instance en échec, aussi, les appels de connexion PHP vont établir une nouvelle connexion sans que le script n'en connaisse, faisant ainsi aucune interruption de service.

Lorsque oci8.events vaut `On`, il est suggéré de définir oci8.ping_interval à -1 pour désactiver le ping, sachant que l'activation des événements FAN fournit un gestionnaire de connexions pro-actif des connexions inactives devenues invalides par une interruption de service.

Pour activer le support FAN en PHP OCI8, compiler PHP OCI8 avec les bibliothèques Oracle 10gR2 ou supérieures, puis suivre ces étapes :

- Avec les privilèges d'administrateur de la base de données, utiliser un programme comme SQL*Plus pour activer le service de base de données pour poster les événements FAN ; par exemple :

          SQL> execute dbms_service.modify_service(
                         SERVICE_NAME        => 'sales',
                         AQ_HA_NOTIFICATIONS => TRUE);

- Éditer le fichier php.ini et ajouter :

          oci8.events = On

- Si l'application ne gère toujours pas les conditions d'erreur OCI8, la modifier pour détecter les échecs. Ceci peut nécessiter la re-connexion et la ré-exécution des requêtes.
- Exécuter l'application, se connecter à la base de données Oracle 10gR2 ou supérieures.

# Le support de la reprise transparente d'application (TAF) d'OCI8

TAF est une fonctionnalité de la base de données Oracle qui fournit une haute disponibilité. Elle permet aux applications PHP OCI8 de se reconnecter automatiquement à une base de données préconfigurée lorsque la connectivité à la base de données échoue en raison d'une panne d'instance ou de réseau.

Dans un système de base de données Oracle configuré, TAF se produit lorsque l'application PHP détecte que l'instance de base de données est hors service ou injoignable. Elle établit une connexion à un autre nœud dans une configuration Oracle » RAC, une base de données de secours à chaud, ou la même instance de base de données elle-même. Consulter le » Guide du programmeur de l'interface d'appel Oracle pour plus d'informations sur OCI TAF.

Une fonction de rappel d'application peut être enregistrée avec oci_register_taf_callback(). Pendant la reprise, le traitement normal de l'application s'arrête et le rappel enregistré est invoqué. La fonction de rappel notifie l'application des événements de reprise. Si la reprise réussit, le traitement normal reprendra. Si la reprise est abandonnée, toutes les opérations de base de données suivantes dans l'application échoueront en raison de l'absence de connexion disponible.

Lorsque la connexion échoue sur une autre base de données, la fonction de rappel peut réinitialiser tout état de connexion nécessaire, par exemple en rejouant les commandes ALTER SESSION nécessaires si le service de base de données n'avait pas -failover_restore activé.

Une fonction de rappel d'application peut être supprimée en appelant oci_unregister_taf_callback().

## Configuration de la reprise transparente d'application

TAF peut être configuré du côté PHP OCI8 ou dans la configuration de la base de données. Si les deux sont configurés, les paramètres côté base de données ont la priorité.

Configurer TAF dans PHP OCI8 (le côté client) en incluant le paramètre FAILOVER_MODE dans la partie CONNECT_DATA d'un descripteur de connexion. Consulter la section Configuration de la reprise transparente d'application du » Guide de l'administrateur Oracle Database Net Services pour plus d'informations sur la configuration côté client de TAF.

Un exemple de tnsnames.ora pour configurer TAF reconnectant à la même instance de base de données :

        ORCL =
          (DESCRIPTION =
            (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
            (CONNECT_DATA =
              (SERVICE_NAME = orclpdb1)
              (FAILOVER_MODE =
                (TYPE = SELECT)
                (METHOD = BASIC)
                (RETRIES = 20)
                (DELAY = 15))))

Il est également possible de configurer TAF du côté de la base de données en modifiant le service cible avec » srvctl (pour RAC) ou la procédure empaquetée » DBMS_SERVICE.MODIFY_SERVICE (pour les bases de données à instance unique).

## Utilisation des fonctions de rappels TAF dans OCI8

Une fonction de rappel TAF est une fonction d'application qui peut être enregistrée pour être appelée pendant la reprise. Elle est appelée plusieurs fois pendant la reprise de la connexion de l'application.

La fonction de rappel est appelée pour la première fois lorsqu'une perte de connexion est détectée. Cela permet à l'application d'agir en conséquence pour les retards à venir de la reprise. Si la reprise est réussie, la fonction de rappel est invoquée après que la connexion soit rétablie et utilisable. À ce moment, l'application peut resynchroniser les paramètres de session et prendre des actions telles que informer l'utilisateur qu'une reprise a eu lieu. Si la reprise est infructueuse, un rappel se produit pour informer l'application qu'une reprise n'a pas eu lieu et que la connexion n'est pas utilisable.

L'interface d'une fonction de rappel TAF définie par l'utilisateur est la suivante :

function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

`connection`

  La connexion Oracle sur laquelle le rappel TAF a été enregistré via oci_register_taf_callback(). La connexion n'est pas valide tant que la reprise n'est pas terminée avec succès.

`event`

  L'événement de reprise indique l'état actuel de la reprise.

  - `OCI_FO_BEGIN` indique que la reprise a détecté une perte de connexion et que la reprise commence.

  - `OCI_FO_END` indique que la reprise a réussi.

  - `OCI_FO_ABORT` indique que la reprise a échoué et qu'il n'y a pas d'option de réessayer.

  - `OCI_FO_ERROR` indique également que la reprise a échoué, mais il donne à l'application l'opportunité de gérer l'erreur et de retourner OCI_FO_RETRY pour réessayer la reprise.

  - `OCI_FO_REAUTH` indique que un utilisateur Oracle a été réauthentifié.

`type`

  Le type de reprise. Cela permet au rappel de savoir quel type de reprise l'application a demandé. Les valeurs habituelles sont les suivantes :

  - `OCI_FO_SESSION` indique que l'utilisateur a demandé uniquement la reprise de session. Par exemple, si la connexion d'un utilisateur est perdue, une nouvelle session est automatiquement créée pour l'utilisateur sur la base de secours. Ce type de reprise ne tente pas de récupérer les SELECT.

  - `OCI_FO_SELECT` indique que l'utilisateur a demandé la reprise SELECT également. Il permet aux utilisateurs avec des curseurs ouverts de continuer à les récupérer après une défaillance.

`return value`

  - `0` indique que les étapes de reprise doivent continuer normalement.

  - `OCI_FO_RETRY` indique que la reprise doit être tentée à nouveau par Oracle. En cas d'erreur lors de la reprise vers une nouvelle connexion, TAF est capable de réessayer la reprise. En général, le code de l'application doit dormir pendant un certain temps avant de retourner OCI_FO_RETRY.

Exemple #1 Enregistrement d'une fonction de rappel TAF

    <?php

    // Définition de la fonction de rappel de l'espace utilisateur
    class MyClass {
        public static $retry_count;
        public static function TAFCallback($conn, $event, $type)
        {
            switch ($event) {
                case OCI_FO_BEGIN:
                    printf(" Failing Over ... Please stand by\n");
                    printf(" Failover type was found to be %s \n",
                           (($type==OCI_FO_SESSION) ? "SESSION"
                            :(($type==OCI_FO_SELECT) ? "SELECT" : "UNKNOWN!")));
                    self::$retry_count = 0;
                    break;
                case OCI_FO_ABORT:
                    // L'application ne peut pas continuer à utiliser la base de données
                    printf(" Failover aborted. Failover will not take place.\n");
                    break;
                case OCI_FO_END:
                    // Reprise réussie. Informer les utilisateurs qu'une reprise a eu lieu.
                    printf(" Failover ended ... resuming services\n");
                    break;
                case OCI_FO_REAUTH:
                    printf(" Failed over user ... resuming services\n");
                    // Rejouer toutes les commandes ALTER SESSION associées à cette connexion
                    // par exemple oci_parse($conn, 'ALTER SESSION ...');
                    break;
                case OCI_FO_ERROR:
                    // Stopper les tentatives si nous avons déjà essayé 20 fois.
                    if (self::$retry_count >= 20)
                        return 0;
                    printf(" Failover error received. Sleeping...\n");
                    sleep(10);
                    self::$retry_count++;
                    return OCI_FO_RETRY; // retry failover
                    break;
                default:
                    printf("Bad Failover Event: %d.\n", $event);
                    break;
            }
            return 0;
        }
    }

    $fn_name = 'MyClass::TAFCallback';

    $conn = oci_connect('hr', 'welcome', 'orcl');
    $sysconn = oci_connect('system', 'oracle', 'orcl');

    // Utiliser une connexion privilégiée pour construire une instruction SQL qui initiera la reprise
    $sql = <<< 'END'
    select unique 'alter system disconnect session '''||sid||','||serial#||''''
    from v$session_connect_info
    where sid = sys_context('USERENV', 'SID')
    END;

    $s = oci_parse($conn, $sql);
    oci_execute($s);
    $r = oci_fetch_array($s);
    $disconnectssql = $r[0];

    oci_register_taf_callback($conn, $fn_name); // Register TAFCallback to Oracle TAF

    print "Parsing user query\n";
    $sql = "select systimestamp from dual";
    $stmt = oci_parse($conn, $sql);

    // Par exemple, si une perte de connexion se produit à ce moment, oci_execute() détectera
    // la perte et la reprise commencera. Pendant la reprise, oci_execute() invoquera
    // la fonction de rappel TAF plusieurs fois. Si la reprise réussit,
    // une nouvelle connexion est créée de manière transparente et oci_execute() continuera comme
    // d'habitude. Les paramètres de session de la connexion peuvent être réinitialisés dans la fonction de rappel TAF.
    // Si la reprise est abandonnée, oci_execute() renverra une erreur
    // car une connexion valide n'est pas disponible.

    // Déconnecter l'utilisateur, ce qui initie la reprise
    print "Disconnecting the user\n";
    $discsql = oci_parse($sysconn, $disconnectssql);
    oci_execute($discsql);

    print "Executing user query\n";
    $e = oci_execute($stmt);
    if (!$e) {
        $m = oci_error($stmt);
        trigger_error("Could not execute statement: ". $m['message'], E_USER_ERROR);
    }
    $row = oci_fetch_array($stmt);
    print $row[0] . "\n";

    // faire d'autres instructions SQL avec la nouvelle connexion, si elle est valide
    // $stmt = oci_parse($conn,  . . .);

    ?>

## Voir aussi

- oci_register_taf_callback()
- oci_unregister_taf_callback()

# OCI8 et le suivi dynamique DTrace

OCI8 2.0 introduit DTrace qui peut être utilisé sur les systèmes qui supportent DTrace. Voir le suivi dynamique DTrace pour un aperçu de PHP et DTrace.

## Installation d'OCI8 avec le support de DTrace

Pour activer le support de DTrace en PHP OCI8, il faut compiler OCI8 comme extension partagée, après avoir configuré `PHP_DTRACE`.

    $ export PHP_DTRACE=yes
    $ pecl install oci8

Éditer php.ini, définir l'option extension_dir pour correspondre au dossier contenant le fichier oci8.so créé, et activer l'extension en ajoutant :

    extension=oci8.so

Si on installe PHP OCI8 depuis PECL en utilisant phpize et configure (au lieu de pecl), il faut définir `PHP_DTRACE=yes`. Ceci en raison du fait que l'option `--enable-dtrace` sera ignorée par une limitation du script configure du paquet PECL.

Voir l'installation d'une extension PECL pour les instructions générales d'installation PECL.

## Découverte statique DTrace en PHP OCI8

Les découvertes statiques suivantes sont disponibles en PHP OCI8
Nom de la découverte | Description de la découverte | Arguments de la découverte
--- | --- | ---
`oci8-connect-entry` | Initialisé par oci_connect(), oci_pconnect() et oci_new_connect(). Lancé avant que la connexion à la base de données ne soit établie. | char *username, char *dbname, char *charset, long session_mode, int persistent, int exclusive
`oci8-connect-return` | Lancé à la fin de la connexion. | void *connection
`oci8-check-connection` | Lancé si une erreur Oracle a fait que la connexion est devenue invalide. | void *connection, char *client_id, int is_open, long errcode, unsigned long server_status
`oci8-sqltext` | Lancé lorsque oci_parse() est exécuté. | void *connection, char *client_id, void *statement, char *sql
`oci8-connection-close` | Lancé lorsque la connexion à la base de données est totalement détruite. | void *connection
`oci8-error` | Lancé si une erreur Oracle survient. | int status, long errcode
`oci8-execute-mode` | Lancé lors d'un appel à oci_execute() pour afficher le mode d'exécution. | void *connection, char *client_id, void *statement, unsigned int mode

Ces découvertes sont utiles pour suivre les scripts OCI8.

Les variables connection et statement sont des pointeurs vers les structures internes utilisées pour suivre les connexions PHP et les requêtes exécutées.

La variable client_id est la valeur définie par oci_set_client_identifier().

Le cœur de PHP a aussi des découvertes statiques. Voir les découvertes statiques DTrace dans le cœur PHP.

Découvertes DTrace pour le débogage interne en OCI8
Nom de la découverte
`oci8-connect-expiry`
`oci8-connect-lookup`
`oci8-connect-p-dtor-close`
`oci8-connect-p-dtor-release`
`oci8-connect-type`
`oci8-sesspool-create`
`oci8-sesspool-stats`
`oci8-sesspool-type`

Ces découvertes sont utiles pour les mainteneurs OCI8. Se référer au code source d'OCI8 pour les arguments et pour voir quand elles sont lancées.

## Liste des découvertes statiques DTrace en PHP OCI8

Pour lister toutes les découvertes disponibles, démarrer un processus PHP et exécuter :

    # dtrace -l

L'affichage sera similaire à :

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
       17 phpoci22116           oci8.so   php_oci_dtrace_check_connection oci8-check-connection
       18 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-entry
       19 phpoci22116           oci8.so         php_oci_persistent_helper oci8-connect-expiry
       20 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-lookup
       21 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-close
       22 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-release
       23 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-return
       24 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-type
       25 phpoci22116           oci8.so          php_oci_connection_close oci8-connection-close
       26 phpoci22116           oci8.so                     php_oci_error oci8-error
       27 phpoci22116           oci8.so         php_oci_statement_execute oci8-execute-mode
       28 phpoci22116           oci8.so              php_oci_create_spool oci8-sesspool-create
       29 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-stats
       30 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-type
       31 phpoci22116           oci8.so          php_oci_statement_create oci8-sqltext

Les valeurs de la colonne "Provider" affichent `phpoci` suivi de l'identifiant du processus actuellement exécuté par PHP.

La colonne "Function" affiche les noms des fonctions C interne à PHP où chaque fournisseur est situé.

Si un processus PHP n'est pas en cours d'exécution, alors aucune découverte PHP ne sera affichée.

## Exemple de DTrace avec PHP OCI8

Cet exemple montre les bases du langage de script DTrace D.

Exemple #1 user_oci8_probes.d pour suivre toutes les découvertes statiques au niveau utilisation PHP OCI8 avec DTrace

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::oci8-connect-entry
    {
        printf("%lld: PHP connect-entry\n", walltimestamp);
        printf("  credentials=\"%s@%s\"\n", arg0 ? copyinstr(arg0) : "", arg1 ? copyinstr(arg1) : "");
        printf("  charset=\"%s\"\n", arg2 ? copyinstr(arg2) : "");
        printf("  session_mode=%ld\n", (long)arg3);
        printf("  persistent=%d\n", (int)arg4);
        printf("  exclusive=%d\n", (int)arg5);
    }

    php*:::oci8-connect-return
    {
        printf("%lld: PHP oci8-connect-return\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-connection-close
    {
        printf("%lld: PHP oci8-connect-close\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-error
    {
        printf("%lld: PHP oci8-error\n", walltimestamp);
        printf("  status=%d\n", (int)arg0);
        printf("  errcode=%ld\n", (long)arg1);
    }

    php*:::oci8-check-connection
    {
        printf("%lld: PHP oci8-check-connection\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  is_open=%d\n", arg2);
        printf("  errcode=%ld\n", (long)arg3);
        printf("  server_status=%lu\n", (unsigned long)arg4);
    }

    php*:::oci8-sqltext
    {
        printf("%lld: PHP oci8-sqltext\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  sql=\"%s\"\n", arg3 ? copyinstr(arg3) : "");
    }

    php*:::oci8-execute-mode
    {
        printf("%lld: PHP oci8-execute-mode\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  mode=0x%x\n", arg3);
    }

Ce script utilise l'option `-Z` de dtrace, lui permettant d'être exécuté lorsqu'il n'y a aucun processus PHP en cours d'exécution. Si cette option est omise, le script va vouloir se terminer immédiatement lorsqu'aucun exécutable PHP n'est en cours de fonctionnement.

Sur les machines avec plusieurs CPU, l'ordre des découvertes semble ne pas être séquentiel. Ceci dépend du CPU qui exécute les découvertes, et le nombre de threads qui migrent des CPUs. L'affichage des timestamps des découvertes peut aider à éviter toute confusion.

Le script suit tous les points de découvertes statiques niveau utilisateur PHP OCI8 pendant la durée de l'exécution du script PHP. Exécution du script D :

    # ./user_oci8_probes.d

Exécuter un script PHP ou une application. Le script de surveillance D affiche chaque argument de découvertes lancé. Par exemple, un simple script PHP qui requête une table va produire les traces suivantes :

    1381794982092854582: PHP connect-entry
      credentials="hr@localhost/pdborcl"
      charset=""
      session_mode=0
      persistent=0
      exclusive=0
    1381794982183158766: PHP oci8-connect-return
      connection=0x7f4a7907bfb8
    1381794982183594576: PHP oci8-sqltext
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      sql="select * from employees"
    1381794982183783706: PHP oci8-execute-mode
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      mode=0x20
    1381794982444344390: PHP oci8-connect-close
      connection=0x7f4a7907bfb8

Lorsque la surveillance se termine, le script D peut s'arrêter avec ``CTRL`+`C``.

## Voir aussi

- Le suivi dynamique DTrace

# Types de données supportés par le pilote

Le pilote supporte les types suivants lors du liage de paramètres en utilisant la fonction oci_bind_by_name() :
Type | Liage
--- | ---
`SQLT_NTY` | Lie une collection de types natifs depuis un objet de collection PHP comme ceux créés par oci_new_collection().
`SQLT_BFILEE` | Lie une ressource native, telle que celles créées par la fonction oci_new_descriptor().
`SQLT_CFILEE` | Lie une ressource native, telle que celles créées par la fonction oci_new_descriptor().
`SQLT_CLOB` | Lie une ressource native, telle que celles créées par la fonction oci_new_descriptor().
`SQLT_BLOB` | Lie une ressource native, comme celles créées par la fonction oci_new_descriptor().
`SQLT_RDD` | Lie une ressource native, comme celles créées par la fonction oci_new_descriptor().
`SQLT_NUM` | Convertit un paramètre PHP en un type long 'C', et le lie à cette valeur.
`SQLT_RSET` | Lie un gestionnaire de requête natif, comme ceux créés par la fonction oci_parse() ou ceux récupérés depuis d'autres requêtes OCI.
`SQLT_BOL` | Lie le paramètre PHP au booléen PL/SQL
`SQLT_CHR` et les autres types | Convertit le paramètre PHP en un type chaîne de caractères et le lie en tant que chaîne de caractères.

Les types suivants sont supportés lors de la récupération de colonnes depuis un jeu de résultats :
Type | Liage
--- | ---
`SQLT_RSET` | Crée une ressource de requêtes OCI pour représenter le curseur.
`SQLT_RDD` | Crée un objet ROWID.
`SQLT_BLOB` | Crée un objet LOB.
`SQLT_CLOB` | Crée un objet LOB.
`SQLT_BFILE` | Crée un objet LOB.
`SQLT_LNG` | Lié comme SQLT_CHR, retourné sous la forme d'une chaîne de caractères
`SQLT_LBI` | Lié comme `SQLT_BIN`, retourné sous la forme d'une chaîne de caractères
Tous les autres types | Lié comme `SQLT_CHR`, retourné sous la forme d'une chaîne de caractères

# Fonctions OCI8

# oci_bind_array_by_name

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL OCI8 >= 1.2.0)

oci_bind_array_by_name — Lie un tableau PHP à un paramètre de tableau Oracle PL/SQL

### Description

function oci_bind_array_by_name(
resource `$statement`,
string `$param`,
array `&$var`,
int `$max_array_length`,
int `$max_item_length` = -1,
int `$type` = `SQLT_AFC`
): bool

Lie un tableau PHP `var` à un marqueur Oracle `param`, qui pointe vers un tableau PL/SQL. Il peut être utilisé pour l'entrée ou la sortie, suivant la configuration à l'exécution.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

`param`

  Le marqueur Oracle.

`var`

  Un tableau.

`max_array_length`

  Spécifie la longueur maximale des tableaux d'entrées et de résultats.

`max_item_length`

  Définit la longueur maximale pour les éléments du tableau. Si `max_item_length` n'est pas fourni ou s'il vaut -1, oci_bind_array_by_name() cherchera l'élément le plus long dans le tableau d'entrée et l'utilisera en tant que longueur maximale.

`type`

  Devrait être utilisé pour définir le type des éléments PL/SQL. Voir la liste des types disponibles ci-dessous :

  - `SQLT_NUM` - pour les tableaux de NUMBER.

  - `SQLT_INT` - pour les tableaux INTEGER (Note : INTEGER c'est actuellement un synonyme pour NUMBER(38), mais le type `SQLT_NUM` ne fonctionnera pas dans ce cas même s'ils sont synonymes).

  - `SQLT_FLT` - pour les tableaux de FLOAT.

  - `SQLT_AFC` - pour les tableaux de CHAR.

  - `SQLT_CHR` - pour les tableaux de VARCHAR2.

  - `SQLT_VCS` - pour les tableaux de VARCHAR.

  - `SQLT_AVC` - pour les tableaux de CHARZ.

  - `SQLT_STR` - pour les tableaux de STRING.

  - `SQLT_LVC` - pour les tableaux de LONG VARCHAR.

  - `SQLT_ODT` - pour les tableaux de DATE.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_bind_array_by_name()

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $create = "CREATE TABLE bind_example(name VARCHAR(20))";
    $stid = oci_parse($conn, $create);
    oci_execute($stid);

    $create_pkg = "
    CREATE OR REPLACE PACKAGE ARRAYBINDPKG1 AS
      TYPE ARRTYPE IS TABLE OF VARCHAR(20) INDEX BY BINARY_INTEGER;
      PROCEDURE iobind(c1 IN OUT ARRTYPE);
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg);
    oci_execute($stid);

    $create_pkg_body = "
    CREATE OR REPLACE PACKAGE BODY ARRAYBINDPKG1 AS
      CURSOR CUR IS SELECT name FROM bind_example;
      PROCEDURE iobind(c1 IN OUT ARRTYPE) IS
        BEGIN
        -- Bulk Insert
        FORALL i IN INDICES OF c1
          INSERT INTO bind_example VALUES (c1(i));

        -- Fetch and reverse;
        IF NOT CUR%ISOPEN THEN
          OPEN CUR;
        END IF;
        FOR i IN REVERSE 1..5 LOOP
          FETCH CUR INTO c1(i);
          IF CUR%NOTFOUND THEN
            CLOSE CUR;
            EXIT;
          END IF;
        END LOOP;
      END iobind;
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg_body);
    oci_execute($stid);

    $stid = oci_parse($conn, "BEGIN arraybindpkg1.iobind(:c1); END;");
    $array = array("one", "two", "three", "four", "five");
    oci_bind_array_by_name($stid, ":c1", $array, 5, -1, SQLT_CHR);
    oci_execute($stid);

    var_dump($array);

    ?>

# oci_bind_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_bind_by_name — Associe une variable PHP à un marqueur Oracle

### Description

function oci_bind_by_name(
resource `$statement`,
string `$param`,
mixed `&$var`,
int `$max_length` = -1,
int `$type` = 0
): bool

Lie une variable PHP `var` au marqueur Oracle `param`. Le fait de lier une variable est important en termes de performance de la base de données Oracle, mais aussi en termes de sécurité relative aux injections SQL.

Le liage permet aux bases de données de réutiliser le contexte d'exécution de la requête ainsi que le cache associé, y compris lorsqu'un autre utilisateur ou processus l'exécute. Le liage réduit le risque d'injection SQL car les données associées à une variable liée ne sont jamais traitées comme faisant partie de la requête SQL. Inutile donc d'ajouter des quotes ou d'échapper ces données.

Les variables PHP liées peuvent changer et la requête ré-exécutée sans avoir besoin d'analyser de nouveau la requête ou de lier de nouveau les variables.

Avec Oracle, les variables liées sont habituellement divisées en lien `IN` pour les valeurs passées à la base de données, et en lien `OUT` pour les valeurs à retourner à PHP. Une variable liée peut être à la fois en lien `IN` et `OUT`. Dans ce cas, le fait de savoir si la variable liée doit être utilisée pour l'entrée ou la sortie sera déterminé au moment de l'exécution.

Il faut spécifier le paramètre `max_length` lors de l'utilisation du lien `OUT` afin que PHP alloue assez de mémoire pour contenir la valeur de retour.

Pour les liens `IN`, il est recommandé de définir le paramètre `max_length` si la requête est exécutée plusieurs fois avec des valeurs différentes pour les variables PHP. Sinon, Oracle peut tronquer les données à la longueur de la valeur initiale de la variable PHP. Si l'on ne connaît pas la valeur maximale dont on a besoin, alors appelez de nouveau la fonction oci_bind_by_name() avec les données courantes, avant chaque appel à la fonction oci_execute(). Le fait d'associer une taille supérieure à ce dont on a besoin a un impact sur la mémoire associée au processus pour la base de données.

Un appel à la fonctionnalité d'association de variables donne à Oracle l'adresse mémoire à utiliser pour lire les données. Pour les liens `IN`, cette adresse doit contenir des données valides lors de l'appel à la fonction oci_execute(). Ceci signifie que la variable liée doit rester dans le contexte jusqu'à l'exécution. Si ce n'est pas le cas, des résultats non attendus peuvent survenir, ainsi que des erreurs de type "ORA-01460: unimplemented or unreasonable conversion requested". Pour les liens `OUT`, un symptôme peut être qu'aucune valeur n'a été définie dans la variable PHP.

Pour une requête qui est exécutée à plusieurs reprises, les valeurs liées qui ne changent jamais peuvent réduire la capacité de l'optimisateur d'Oracle à choisir le meilleur plan d'exécution. Pour les requêtes prenant du temps, qui sont rarement appelées plusieurs fois, l'association de variables n'apporte aucun bénéfice. Cependant, dans les 2 cas, l'association est plus sécurisée que de placer directement les chaînes de caractères dans la requête SQL, sachant qu'il y a un risque de mauvais filtrage de l'entrée utilisateur.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI8 valide.

`param`

  Le marqueur, préfixé par deux-points, utilisé dans la requête. Les deux-points sont optionnels dans le paramètre `param`.

`var`

  La variable PHP à associer avec le marqueur du paramètre `param`.

`max_length`

  Spécifie la taille maximale pour les données. Si la valeur est -1, la fonction utilisera la longueur courante des données du paramètre `var` pour définir la longueur maximale. Dans ce cas, le paramètre `var` doit exister et contenir des données lors de l'appel à la fonction oci_bind_by_name().

`type`

  Le type de données à utiliser par Oracle pour traiter les données. Par défaut, vaut `SQLT_CHR`. Oracle convertira les données entre ce type et la colonne de la base de données (ou des variables de type PL/SQL), lorsque c'est possible.

  S'il faut lier des types abstraits de données (LOB/ROWID/BFILE), il faudra l'allouer dans un premier temps, avec oci_new_descriptor(). La longueur `length` ne sert pas pour ces types et devrait être fixée à -1.

  Les valeurs possibles pour le paramètre `type` sont :

  - `SQLT_BFILEE` ou `OCI_B_BFILE` - pour les BFILEs ;

  - `SQLT_CFILEE` ou `OCI_B_CFILEE` - pour les CFILEs ;

  - `SQLT_CLOB` ou `OCI_B_CLOB` - pour les CLOBs ;

  - `SQLT_BLOB` ou `OCI_B_BLOB` - pour les BLOBs ;

  - `SQLT_RDD` ou `OCI_B_ROWID` - pour les ROWIDs ;

  - `SQLT_NTY` ou `OCI_B_NTY` - pour les types de données nommés ;

  - `SQLT_INT` ou `OCI_B_INT` - pour les entiers ;

  - `SQLT_CHR` - pour les VARCHAR ;

  - `SQLT_BIN` ou `OCI_B_BIN` - pour les colonnes RAW ;

  - `SQLT_LNG` - pour les colonnes LONG ;

  - `SQLT_LBI` - pour les colonnes LONG RAW ;

  - `SQLT_RSET` - pour les curseurs créés avec la fonction oci_new_cursor();

  - `SQLT_BOL` ou `OCI_B_BOL` - pour les booléens (requiert Oracle Database 12c)

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Insertion de données avec la fonction oci_bind_by_name()

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (id NUMBER, text VARCHAR2(40));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn,"INSERT INTO mytab (id, text) VALUES(:id_bv, :text_bv)");

    $id = 1;
    $text = "Données à insérer     ";
    oci_bind_by_name($stid, ":id_bv", $id);
    oci_bind_by_name($stid, ":text_bv", $text);
    oci_execute($stid);

    // La table contient maintenant : 1, 'Données à insérer

    ?>

Exemple #2 Une association avec de multiples appels

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (id NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $a = array(1,3,5,7,11);  // Données à insérer

    $stid = oci_parse($conn, 'INSERT INTO mytab (id) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $v, 20);
    foreach ($a as $v) {
        $r = oci_execute($stid, OCI_DEFAULT);  // Ne pas valider automatiquement
    }
    oci_commit($conn); // Une seule validation

    // La table contient maintenant 5 lignes : 1, 3, 5, 7, 11

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #3 Association avec une boucle `foreach`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT * FROM departments WHERE department_name = :dname AND location_id = :loc';
    $stid = oci_parse($conn, $sql);

    $ba = array(':dname' => 'IT Support', ':loc' => 1700);

    foreach ($ba as $key => $val) {

        // oci_bind_by_name($stid, $key, $val) ne fonctionne pas car
        // elle associe chaque marqueur au même endroit : $val
        // au lieu d'utiliser l'endroit actuel de la donnée $ba[$key]
        oci_bind_by_name($stid, $key, $ba[$key]);
    }

    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    foreach ($row as $item) {
        print $item."<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #4 Association dans une clause WHERE

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // Affiche :
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #5 Association avec une clause LIKE

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Trouve tous les critères qui commencent par 'South'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE city LIKE :bv");
    $city = 'South%';  // '%' is a wildcard in SQL
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // Affiche :
    //   South Brunswick
    //   South San Francisco
    //   Southlake

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #6 Association avec REGEXP_LIKE

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Trouve tous les critères qui contiennent 'ing'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE REGEXP_LIKE(city, :bv)");
    $city = '.*ing.*';
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // Affiche :
    //   Beijing
    //   Singapore

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Pour quelques conditions utilisées dans les clauses IN, utiliser des variables liées individuelles. Les valeurs inconnues au moment de l'exécution pourront être définies à NULL. Ceci permet d'utiliser une seule requête pour l'ensemble des utilisateurs de l'application, maximisant ainsi l'efficacité du cache Oracle DB.

Exemple #7 Association de plusieurs valeurs dans une clause IN

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE employee_id in (:e1, :e2, :e3)';
    $stid = oci_parse($conn, $sql);
    $mye1 = 103;
    $mye2 = 104;
    $mye3 = NULL; // pretend we were not given this value
    oci_bind_by_name($stid, ':e1', $mye1);
    oci_bind_by_name($stid, ':e2', $mye2);
    oci_bind_by_name($stid, ':e3', $mye3);
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    foreach ($res['LAST_NAME'] as $name) {
        print $name ."<br>\n";
    }

    // Affiche :
    //   Ernst
    //   Hunold

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #8 Association d'un ROWID retourné par une requête

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //   INSERT INTO mytab (id, salary, name) VALUES (1, 100, 'Chris');
    //   COMMIT;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT ROWID, name FROM mytab WHERE id = :id_bv FOR UPDATE');
    $id = 1;
    oci_bind_by_name($stid, ':id_bv', $id);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    $rid = $row['ROWID'];
    $name = $row['NAME'];

    // Modification du nom en lettre majuscule & sauvegarde de cette modification
    $name = strtoupper($name);
    $stid = oci_parse($conn, 'UPDATE mytab SET name = :n_bv WHERE ROWID = :r_bv');
    oci_bind_by_name($stid, ':n_bv', $name);
    oci_bind_by_name($stid, ':r_bv', $rid, -1, OCI_B_ROWID);
    oci_execute($stid);

    // La table contient maintenant 1, 100, CHRIS

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #9 Association d'un ROWID dans un INSERT

    <?php

    // Cet exemple insère un id & un nom, puis, met à jour le salaire
    // Création de la table avec :
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //
    // Basé sur l'exemple original de ROWID, fourni par thies at thieso dot net (980221)

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = "INSERT INTO mytab (id, name) VALUES(:id_bv, :name_bv)
            RETURNING ROWID INTO :rid";

    $ins_stid = oci_parse($conn, $sql);

    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_bind_by_name($ins_stid, ":id_bv",   $id,    10);
    oci_bind_by_name($ins_stid, ":name_bv", $name,  32);
    oci_bind_by_name($ins_stid, ":rid",     $rowid, -1, OCI_B_ROWID);

    $sql = "UPDATE mytab SET salary = :salary WHERE ROWID = :rid";
    $upd_stid = oci_parse($conn, $sql);
    oci_bind_by_name($upd_stid, ":rid", $rowid, -1, OCI_B_ROWID);
    oci_bind_by_name($upd_stid, ":salary", $salary,   32);

    // ids et noms à insérer
    $data = array(1111 => "Larry",
                  2222 => "Bill",
                  3333 => "Jim");

    // Salaire de chaque personne
    $salary = 10000;

    // Insertion et mise à jour immédiate de chaque ligne
    foreach ($data as $id => $name) {
        oci_execute($ins_stid);
        oci_execute($upd_stid);
    }

    $rowid->free();
    oci_free_statement($upd_stid);
    oci_free_statement($ins_stid);

    // Affichage des nouvelles lignes
    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        var_dump($row);
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #10 Association pour une fonction stockée PL/SQL

    <?php

    // Avant d'exécuter le programme PHP, une fonction stockée doit être créée
    // au format SQL*Plus ou SQL Developer :
    //
    //  CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
    //  BEGIN
    //      RETURN p * 3;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);

    // La valeur retournée est un lien OUT. Le type par défaut devra être
    // de type string, aussi, l'association sur une longueur de 40 signifie
    // que la chaîne retournée fera au maximum 40 caractères.
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // Affiche 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #11 Association de paramètres à une procédure stockée PL/SQL

    <?php

    // Avant d'exécuter le programme PHP, une procédure stockée doit être créée
    // au format SQL*Plus ou SQL Developer :
    //
    //  CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
    //  BEGIN
    //      p2 := p1 * 2;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);

    // Le second paramètre de la procédure stockée est un lien OUT.
    // Le type par défaut devra être de type string, aussi,
    // l'association sur une longueur de 40 signifie
    // que la chaîne retournée fera au maximum 40 caractères.

    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // Affiche 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #12 Association sur une colonne CLOB

    <?php

    // Avant l'exécution, il est nécessaire de créer la table :
    //     CREATE TABLE mytab (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $mykey = 12343;  // Clé arbitraire pour l'exemple ;

    $sql = "INSERT INTO mytab (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_DEFAULT);
    $clob->save("A very long string");

    oci_commit($conn);

    // Récupération des données CLOB

    $query = 'SELECT myclob FROM mytab WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // Dans une boucle, le fait de libérer la variable avant la récupération de
        // la ligne suivante réduit l'utilisation mémoire de PHP
        unset($row);
    }
    print '</table>';

    ?>

Exemple #13 Association sur un booléen dans un script PL/SQL

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $plsql =
      "begin
        :output1 := true;
        :output2 := false;
       end;";

    $s = oci_parse($c, $plsql);
    oci_bind_by_name($s, ':output1', $output1, -1, OCI_B_BOL);
    oci_bind_by_name($s, ':output2', $output2, -1, OCI_B_BOL);
    oci_execute($s);
    var_dump($output1);  // true
    var_dump($output2);  // false

    ?>

### Notes

Avertissement

Ne pas utiliser la fonction addslashes() et oci_bind_by_name() simultanément, car aucun ajout de guillemets n'est nécessaire. Si c'est le cas, alors les guillemets ajoutés seront écrits dans la base de données ; en effet, la fonction oci_bind_by_name() insère les données brutes et ne supprime ni les guillemets ajoutés, ni les caractères d'échappement.

> Note:

> Si l'on associe une chaîne de caractères à une colonne de type `CHAR` dans une clause `WHERE`, il faut se souvenir qu'Oracle utilise une comparaison en ajoutant des caractères vides pour les colonnes de type `CHAR`. Aussi, la variable PHP doit être complétée par des caractères vides afin d'atteindre la même taille que la colonne pour que la clause `WHERE` fonctionne.

> Note:

> L'argument PHP `var` est une référence. Aussi, quelques formats de boucle peuvent ne pas fonctionner comme prévu :

>     <?php
>     foreach ($myarray as $key => $value)  {
>         oci_bind_by_name($stid, $key, $value);
>     }
>     ?>

> Ceci associe chaque clé à la valeur pointée par $value, aussi, toutes les variables associées pointent vers la valeur de la dernière itération de la boucle. A la place, utiliser ceci :

>     <?php
>     foreach ($myarray as $key => $value) {
>         oci_bind_by_name($stid, $key, $myarray[$key]);
>     }
>     ?>

### Voir aussi

- oci_bind_array_by_name() - Lie un tableau PHP à un paramètre de tableau Oracle PL/SQL
- oci_parse() - Prépare une requête SQL avec Oracle

# oci_cancel

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_cancel — Termine la lecture de curseurs Oracle

### Description

function oci_cancel(resource `$statement`): bool

Invalide un curseur, libère toutes les ressources associées et annule la possibilité de lecture depuis la ressource.

### Liste de paramètres

`statement`

  Une requête OCI.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# oci_client_version

(PHP 5 >= 5.3.7, PHP 7, PHP 8, PECL OCI8 >= 1.4.6)

oci_client_version — Retourne la version de la bibliothèque cliente Oracle

### Description

function oci_client_version(): string

Retourne une chaîne de caractères contenant le numéro de la version de la bibliothèque cliente Oracle C, à laquelle PHP est liée.

### Liste de paramètres

Aucun.

### Valeurs de retour

Retourne le numéro de version, sous la forme d'une chaîne de caractères.

### Exemples

Exemple #1 Exemple avec oci_client_version()

    <?php
        echo "Client Version: " . oci_client_version(); // Version du client : 19.9.0.0.0
    ?>

### Notes

> Note:

> Les bibliothèques Oracle avant la 10gR2 ne possédaient pas de fonctionnalité interne permettant de récupérer le numéro de version de la bibliothèque. La chaîne "Unknown" sera retournée dans ce cas.

### Voir aussi

- oci_server_version() - Retourne la version du serveur Oracle

# oci_close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_close — Ferme une connexion Oracle

### Description

function oci_close(resource `$connection`): ?bool

Ferme une connexion `connection` Oracle. La connexion sera fermée si aucune ressource ne l'utilise et si elle a été créée avec la fonction oci_connect() ou la fonction oci_new_connect().

Il est recommandé de fermer les connexions qui ne sont plus nécessaires, rendant ainsi plus de ressources disponibles pour les autres utilisateurs.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect(), ou oci_new_connect().

### Valeurs de retour

Retourne `null` quand oci8.old_oci_close_semantics est activé, `true` sinon.

### Exemples

Exemple #1 Fermeture d'une connexion

Les ressources associées avec une connexion doivent être fermées afin d'assurer à la base de données sous-jacente la fin des opérations et ainsi, y libérer les ressources.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');
    $r = oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    // Libération de l'identifiant de requête lors de la fermeture de la connexion
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #2 Les connexions à la base de données sont fermées à partir du moment où les références le sont

L'identifiant interne comptant les connexions doit valoir zéro pour pouvoir fermer la connexion.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');  // ceci incrémente le compteur interne $conn
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    oci_close($conn);

    // $conn n'est plus utilisable dans le script mais la connexion sous-jacente à
    // la base de données est toujours ouverte tant que $stid n'est pas libéré.
    var_dump($conn);  // affiche NULL

    // Pendant que PHP attend, le fait d'interroger la vue V$SESSION d'Oracle
    // dans un terminal montrera qu'un utilisateur est toujours connecté.
    sleep(10);

    // Lorsque $stid est libéré, la connexion à la base de données sera physiquement fermée
    oci_free_statement($stid);

    // Pendant que PHP attend, le fait d'interroger la vue V$SESSION d'Oracle
    // dans un terminal montrera que l'utilisateur s'est déconnecté.
    sleep(10);

    ?>

Exemple #3 Fermeture d'une connexion ouverte plus d'une fois

Lorsque des identifiants de base de données sont réutilisés, toutes les connexions doivent être fermées avant que la connexion à la base de données sous-jacente le soit réellement.

    <?php

    $conn1 = oci_connect('hr', 'welcome', 'localhost/XE');

    // L'utilisation des mêmes identifiants réutilise la même connexion à la base de données sous-jacente.
    // Toutes les modifications non validées effectuées sur $conn1 seront visibles sur $conn2.
    $conn2 = oci_connect('hr', 'welcome', 'localhost/XE');

    // Pendant que PHP attend, le fait d'interroger la vue V$SESSION d'Oracle
    // dans un terminal montrera qu'un seul utilisateur est connecté.
    sleep(10);

    oci_close($conn1); // ne ferme pas la connexion à la base de données sous-jacente
    var_dump($conn1);  // affiche NULL car la variable $conn1 n'est plus utilisable
    var_dump($conn2);  // affiche que $conn2 est toujours une ressource de connexion valide

    ?>

Exemple #4 Les connexions sont fermées lorsque les variables sortent du contexte

Lorsque toutes les variables référençant une connexion sortent du contexte et sont libérées par PHP, une annulation survient (si nécessaire) et la connexion sous-jacente à la base de données est fermée.

    <?php

    function myfunc() {
        $conn = oci_connect('hr', 'hrpwd', 'localhost/XE');
        if (!$conn) {
            $e = oci_error();
            trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
        }

        $stid = oci_parse($conn, 'UPDATE mytab SET id = 100');
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
        return "Finished";
    }

    $r = myfunc();
    // À ce moment, une annulation survient et la connexion sous-jacente à la base de données est fermée.

    print $r;  // affiche la valeur de retour de la fonction "Finished"

    ?>

### Notes

> Note:

> Les variables ayant une dépendance à l'identifiant de connexion, comme les identifiants de requêtes retournés par la fonction oci_parse(), doivent être libérées avant de tenter de fermer la connexion sous-jacente à la base de données.

> Note:

> La fonction oci_close() ne ferme pas les connexions sous-jacentes à la base de données créées par la fonction oci_pconnect().

### Voir aussi

- oci_connect() - Établit une connexion avec un serveur Oracle
- oci_free_statement() - Libère toutes les ressources réservées par un résultat Oracle

# oci_commit

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_commit — Valide les transactions Oracle en cours

### Description

function oci_commit(resource `$connection`): bool

Valide toutes les transactions en cours sur la connexion Oracle `connection`. Une validation rend permanentes toutes les modifications, en libérant tous les verrous.

Une transaction commence lorsque la première requête SQL qui modifie des données est exécutée avec la fonction oci_execute() en utilisant le drapeau `OCI_NO_AUTO_COMMIT`. Les modifications suivantes faites par d'autres requêtes deviennent parties intégrantes de la même transaction. Les données modifiées par une transaction sont temporaires tant que la transaction n'est pas validée ou annulée. Les autres utilisateurs de la base de données ne verront ces modifications qu'une fois la transaction validée.

Lors de l'insertion ou de la mise à jour de données, l'utilisation des transactions est recommandée afin de garantir la consistance relationnelle des données, mais aussi afin d'augmenter les performances.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect(), ou oci_new_connect().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_commit()

    <?php

    // Insertion dans plusieurs tables, avec une annulation des modifications si des erreurs surviennent

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // Le drapeau OCI_NO_AUTO_COMMIT indique à Oracle de ne pas valider les insertions automatiquement.
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // Annulation des modifications sur les 2 tables
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Valide les modifications sur les 2 tables
    $r = oci_commit($conn);
    if (!$r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

### Notes

> Note:

> Les transactions sont automatiquement annulées lorsque l'on ferme la connexion, ou lorsque le script se termine, un des deux arrivant le premier. Il faut explicitement appeler la fonction oci_commit() pour valider la transaction.

> Chaque appel à la fonction oci_execute() qui utilise le mode `OCI_COMMIT_ON_SUCCESS` explicitement ou par défaut, validera toutes les transactions précédentes non validées à ce stade.

> Toutes les requêtes Oracle comme `CREATE` ou `DROP` valideront également toutes les transactions non validées.

### Voir aussi

- oci_execute() - Exécute une commande SQL Oracle
- oci_rollback() - Annule les transactions Oracle en cours

# oci_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_connect — Établit une connexion avec un serveur Oracle

### Description

function oci_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Retourne un identifiant de connexion, nécessaire à la plupart des appels OCI8.

Pour les performances, la plupart des applications devraient utiliser les connexions persistantes avec oci_pconnect() au lieu de oci_connect(). Voir la section sur la gestion des connexions pour des informations générales sur la gestion des connexions et le regroupement des connexions.

Les appels suivants (suivant un premier) à la fonction oci_connect() avec les mêmes paramètres retournent le gestionnaire de connexion retourné lors du premier appel. Cela signifie que les transactions effectuées sur un gestionnaire seront actives sur les autres, sachant qu'elles utilisent la même connexion sous-jacente. Si 2 gestionnaires doivent avoir des transactions isolées, utiliser à la place la fonction oci_new_connect().

### Liste de paramètres

`username`

  Le nom d'utilisateur Oracle.

`password`

  Le mot de passe de l'utilisateur.

`connection_string`
  Contient l'instance `Oracle` sur laquelle nous devons nous connecter. Ce peut être une » chaîne de connexion rapide, un nom de connexion issue du fichier tnsnames.ora, ou le nom d'une instance locale Oracle. Si non spécifié ou `null`, PHP utilise des variables d'environnement comme `TWO_TASK` (sous Linux) ou `LOCAL` (sous Windows) et `ORACLE_SID` pour déterminer l'instance `Oracle` sur laquelle nous devons nous connecter. Pour utiliser la méthode de connexion rapide, PHP doit être lié avec la bibliothèque cliente Oracle 10g ou supérieur. La chaîne de connexion rapide pour Oracle 10g ou supérieur est de la forme : [//]host_name[:port][/service_name]. Depuis Oracle 11g, la syntaxe est : [//]host_name[:port][/service_name][:server_type][/instance_name]. Des options supplémentaires ont été introduit avec Oracle 19c Les noms des services peuvent être trouvés en exécutant l'utilitaire Oracle `lsnrctl status` sur la machine exécutant la base de données. Le fichier tnsnames.ora peut être dans le chemin de recherche d'Oracle Net, qui inclut /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin et /etc. Une solution alternative serait de définit `TNS_ADMIN` afin que le fichier $TNS_ADMIN/tnsnames.ora soit lu. Assurez-vous que le daemon exécutant le serveur web a accès en lecture à ce fichier.
`encoding`
  Détermine le jeu de caractères utilisé par la bibliothèque cliente Oracle. Le jeu de caractères n'a pas besoin d'être identique à celui utilisé par la base de données. S'il ne correspond pas, Oracle ferait de son mieux pour convertir les données depuis le jeu de caractères de la base de données. Suivant les jeux de caractères, il se peut que le résultat ne soit pas parfait. De plus, cette conversion nécessite un peu de temps système. Si non spécifié, la bibliothèque cliente Oracle déterminera un jeu de caractères depuis la variable d'environnement `NLS_LANG`. Le fait de passer ce paramètre peut réduire la durée de connexion.
`session_mode`
  Ce paramètre est disponible à partir de PHP 5 (PECL OCI8 1.1) et accepte les valeurs suivantes : `OCI_DEFAULT`, `OCI_SYSOPER` et `OCI_SYSDBA`. Si soit la constante `OCI_SYSOPER`, soit la constante `OCI_SYSDBA` est spécifiée, cette fonction tentera d'établir une connexion privilégiée en utilisant des identifiants externes. Les connexions privilégiées sont désactivées par défault. Pour les activer, vous devez définir l'option oci8.privileged_connect à `On`. PHP 5.3 (PECL OCI8 1.3.4) introduisent la valeur de mode `OCI_CRED_EXT`. Ce mode demande à Oracle d'utiliser une identification externe ou bien issue du système d'exploitation, qui doit être configurée dans la base de données. Le drapeau `OCI_CRED_EXT` ne peut être utilisé qu'avec le nom d'utilisateur "/" associé à un mot de passe vide. L'option oci8.privileged_connect peut être définie à `On` ou `Off`. `OCI_CRED_EXT` peut être combiné avec le mode `OCI_SYSOPER` ou le mode `OCI_SYSDBA`. `OCI_CRED_EXT` n'est pas supporté sous Windows pour des raisons de sécurité.

### Valeurs de retour

Retourne un identifiant de connexion ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` est désormais nullable.

### Exemples

Exemple #1 Exemple avec oci_connect() en utilisant la syntaxe simplifiée

    <?php

    // Connexion au service XE (i.e. la base de données) sur la machine "localhost"
    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemple #2 Exemple avec oci_connect() en utilisant un nom de connexion réseau

    <?php

    // Connexion à la base de données MYDB décrite dans le fichier tnsnames.ora,
    // Un exemple d'entrée tnsnames.ora pour MYDB pourrait être :
    //   MYDB =
    //     (DESCRIPTION =
    //       (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.oracle.com)(PORT = 1521))
    //       (CONNECT_DATA =
    //         (SERVER = DEDICATED)
    //         (SERVICE_NAME = XE)
    //       )
    //     )

    $conn = oci_connect('hr', 'welcome', 'MYDB');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemple #3 Exemple avec oci_connect() en utilisant un jeu de caractères spécifique

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE', 'AL32UTF8');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemple #4 Exemple avec plusieurs appels à la fonction oci_connect()

    <?php

    $c1 = oci_connect("hr", "welcome", 'localhost/XE');
    $c2 = oci_connect("hr", "welcome", 'localhost/XE');

    // À la fois $c1 et $c2 affichent le même identifiant de ressources PHP, ce qui signifie
    // qu'il s'agit de la même connexion à la base de données
    echo "c1 is $c1<br>\n";
    echo "c2 is $c2<br>\n";

    function create_table($conn)
    {
        $stmt = oci_parse($conn, "create table hallo (test varchar2(64))");
        oci_execute($stmt);
        echo "Created table<br>\n";
    }

    function drop_table($conn)
    {
        $stmt = oci_parse($conn, "drop table hallo");
        oci_execute($stmt);
        echo "Dropped table<br>\n";
    }

    function insert_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "insert into hallo
                  values(to_char(sysdate,'DD-MON-YY HH24:MI:SS'))");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname inserted row without committing<br>\n";
    }

    function rollback($connname, $conn)
    {
        oci_rollback($conn);
        echo "$connname rollback<br>\n";
    }

    function select_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "select * from hallo");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname ----selecting<br>\n";
        while (oci_fetch($stmt)) {
            echo "    " . oci_result($stmt, "TEST") . "<br>\n";
        }
        echo "$connname ----done<br>\n";
    }

    create_table($c1);

    insert_data('c1', $c1);   // Insère une ligne en utilisant c1
    sleep(2);                 // On attend afin de voir un timestamp différent pour la seconde ligne
    insert_data('c2', $c2);   // Insère une ligne en utilisant c2

    select_data('c1', $c1);   // Les résultats des 2 insertions sont retournés
    select_data('c2', $c2);   // Les résultats des 2 insertions sont retournés

    rollback('c1', $c1);      // Annulation de la transaction en utilisant c1

    select_data('c1', $c1);   // Les 2 insertions ont été annulées
    select_data('c2', $c2);

    drop_table($c1);

    // La fermeture d'une connexion rend les variables PHP indisponibles, mais les autres
    // peuvent être toujours utilisées
    oci_close($c1);
    echo "c1 is $c1<br>\n";
    echo "c2 is $c2<br>\n";

    // Affichage :
    //    c1 is Resource id #5
    //    c2 is Resource id #5
    //    Created table
    //    c1 inserted row without committing
    //    c2 inserted row without committing
    //    c1 ----selecting
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c1 ----done
    //    c2 ----selecting
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c2 ----done
    //    c1 rollback
    //    c1 ----selecting
    //    c1 ----done
    //    c2 ----selecting
    //    c2 ----done
    //    Dropped table
    //    c1 is
    //    c2 is Resource id #5

    ?>

### Notes

> Note:

> Si un problème est survenu lors de l'installation de l'extension OCI8, une des manifestations sera un problème lors de la connexion. Se reporter à la section Installation/Configuration pour plus d'informations en cas d'erreurs.

### Voir aussi

- oci_pconnect() - Ouvre une connexion persistante à un serveur Oracle
- oci_new_connect() - Connexion au serveur Oracle en utilisant une seule connexion
- oci_close() - Ferme une connexion Oracle

# oci_define_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_define_by_name — Associe une variable PHP avec une colonne pour une requête de récupération de données

### Description

function oci_define_by_name(
resource `$statement`,
string `$column`,
mixed `&$var`,
int `$type` = 0
): bool

Associe une variable PHP avec une colonne pour une requête de récupération de données utilisant la fonction oci_fetch().

L'appel à la fonction oci_define_by_name() doit s'effectuer avant l'exécution de la fonction oci_execute().

### Liste de paramètres

`statement`
  Un identifiant de requête OCI8 créé par la fonction oci_parse() et exécuté par la fonction oci_execute(), ou un identifiant de requête `REF CURSOR`.
`column`

  Le nom de la colonne utilisé dans la requête.

  Utiliser un nom en majuscule, pour les noms de colonne non sensibles à la casse (par défaut sous Oracle). Utiliser la casse exacte du nom de la colonne pour les noms de colonne sensibles à la casse.

`var`

  La variable PHP qui contiendra la valeur retournée par la colonne.

`type`

  Le type de données à retourner. En général, ce paramètre n'est pas nécessaire. À noter que le style Oracle de conversion de données n'est pas appliqué ici. Par exemple, `SQLT_INT` sera ignoré et le type de données retourné sera `SQLT_CHR`.

  Il est possible d'utiliser, optionnellement, la fonction oci_new_descriptor() pour allouer des descripteurs LOB/ROWID/BFILE.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_define_by_name()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // Les définitions DOIVENT être faites avant l'exécution de la requête
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // Chaque récupération peuple les variables précédemment définies avec les données de la prochaine ligne
    while (oci_fetch($stid)) {
        echo "Location id $locid is $city<br>\n";
    }

    // Affiche :
    //   Location id 1000 is Roma
    //   Location id 1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #2 Exemple avec oci_define_by_name() et des noms de colonne sensibles à la casse

    <?php

    /*
      Avant exécution, créez la table suivante avec un nom de colonne sensible à la casse :
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Utiliser des majuscules pour les noms de colonne insensibles à la casse
    oci_define_by_name($stid, 'ID', $id);

    // Utiliser la casse exacte pour les noms de colonnes sensibles à la casse
    oci_define_by_name($stid, 'MyDescription', $mydesc);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo "id $id is $mydesc<br>\n";
    }

    // Affiche :
    //   id 1 is Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #3 Exemple avec oci_define_by_name() et des colonnes de type LOB

    <?php

    /*
      Avant exécution, créez la table suivante :
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Les définitions DOIVENT être effectuées avant l'exécution
    oci_define_by_name($stid, 'ID', $id);
    oci_define_by_name($stid, 'FRUIT', $fruit);  // $fruit will become a LOB descriptor

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " is " . $fruit->load(100) . "<br>\n";
    }

    // Affiche :
    //   1 is apple
    //   2 is orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #4 Exemple avec oci_define_by_name() et un type explicite

    <?php

    /*
      Avant exécution, créez la table suivante :
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Les définitions DOIVENT être faites avant exécution
    oci_define_by_name($stid, 'ID', $id);

    $fruit = oci_new_descriptor($conn, OCI_D_LOB);
    oci_define_by_name($stid, 'FRUIT', $fruit, OCI_D_CLOB);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " is " . $fruit->load(100) . "<br>\n";
    }

    // Affiche :
    //   1 is apple
    //   2 is orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Voir aussi

- oci_fetch() - Lit la prochaine ligne d'un résultat Oracle dans un buffer interne
- oci_new_descriptor() - Initialise un nouveau pointeur vide de LOB/FILE Oracle

# oci_error

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_error — Retourne la dernière erreur Oracle

### Description

function oci_error(?resource `$connection_or_statement` = `null`): array|false

Retourne la dernière erreur Oracle.

La fonction doit être appelée immédiatement après qu'une erreur survient. Les erreurs sont réinitialisées après une requête réussie.

### Liste de paramètres

`connection_or_statement`

  Pour la plupart des erreurs, le paramètre `connection_or_statement` représente une ressource de connexion. Pour les erreurs de connexion avec les fonctions oci_connect(), oci_new_connect() ou oci_pconnect(), `null` doit être passé.

### Valeurs de retour

Si aucune erreur n'est trouvée, oci_error() retourne `false`. Sinon, oci_error() retourne l'information concernant l'erreur sous la forme d'un tableau associatif.

Description du tableau retourné par oci_error()
Clé du tableau | Type | Description
--- | --- | ---
`code` | int | Le numéro d'erreur Oracle.
`message` | string | Le texte de l'erreur Oracle.
`offset` | int | L'octet de position de l'erreur dans la requête SQL. S'il n'y a pas de requête, `0` sera placé comme valeur.
`sqltext` | string | Le texte de la requête SQL. S'il n'y a pas de requête, ce sera une chaîne vide.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_or_statement` est désormais nullable.

### Exemples

Exemple #1 Exemple d'affichage d'un message d'erreur Oracle après une erreur de connexion

    <?php
    $conn = oci_connect("hr", "welcome", "localhost/XE");
    if (!$conn) {
        $e = oci_error();   // Pour les erreurs oci_connect, ne passez pas de gestionnaire de connexion
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Exemple #2 Exemple d'affichage d'un message d'erreur Oracle après une erreur d'analyse

    <?php
    $stid = oci_parse($conn, "select ' from dual");  // Notez l'erreur avec les guillemets
    if (!$stid) {
        $e = oci_error($conn);  // Pour les erreurs oci_parse, passez le gestionnaire de connexion
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Exemple #3 Exemple d'affichage d'un message d'erreur Oracle après une erreur d'exécution rencontrée dans une requête SQL

    <?php
    $stid = oci_parse($conn, "select does_not_exist from dual");
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);  // Pour les erreurs oci_execute, passez le gestionnaire de connexion
        print htmlentities($e['message']);
        print "\n<pre>\n";
        print htmlentities($e['sqltext']);
        printf("\n%".($e['offset']+1)."s", "^");
        print  "\n</pre>\n";
    }
    ?>

# oci_execute

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_execute — Exécute une commande SQL Oracle

### Description

function oci_execute(resource `$statement`, int `$mode` = `OCI_COMMIT_ON_SUCCESS`): bool

Exécute une requête `statement` précédemment retournée par la fonction oci_parse().

Après exécution, les requêtes comme `INSERT` auront par défaut les données validées (commitées) sur la base de données. Pour les requêtes comme `SELECT`, l'exécution effectue la logique de la requête. Les résultats de la requête peuvent être récupérés par PHP avec des fonctions comme oci_fetch_array().

Chaque requête analysée peut être exécutée plusieurs fois, inutile donc de les analyser de nouveau. Ceci est pratique pour des requêtes de type `INSERT` lorsque des données y sont liées grâce à la fonction oci_bind_by_name().

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

`mode`

  Un second paramètre optionnel peut prendre une des constantes suivantes :

  Modes d'exécution
  Constante | Description
  --- | ---
  `OCI_COMMIT_ON_SUCCESS` | Validation automatique sur la connexion lorsque la requête a été exécutée avec succès. C'est le comportement par défaut.
  `OCI_DESCRIBE_ONLY` | Rend les métadonnées de la requête disponibles aux fonctions comme oci_field_name() mais ne crée pas de jeu de résultats. Tout appel à des fonctions de récupération comme oci_fetch_array() échouera.
  `OCI_NO_AUTO_COMMIT` | Ne valide pas automatiquement les modifications.

  L'utilisation du mode `OCI_NO_AUTO_COMMIT` démarre ou continue une transaction. Les transactions sont automatiquement annulées lorsque la connexion est fermée ou lorsque le script se termine. Appelez explicitement la fonction oci_commit() pour valider la transaction ou la fonction oci_rollback() pour l'annuler.

  Lors de l'insertion ou de la mise à jour de données, l'utilisation de transactions est fortement recommandée pour garantir la consistance relationnelle des données, mais aussi en raison d'un gain non négligeable de performance.

  Si le mode `OCI_NO_AUTO_COMMIT` est utilisé pour toutes opérations y compris les requêtes, et que les fonctions oci_commit() et oci_rollback() ne sont jamais appelées, OCI8 effectuera une annulation à la fin du script même si les données ont changé. Pour éviter ce comportement, la plupart des scripts n'utilisent pas le mode `OCI_NO_AUTO_COMMIT` pour les requêtes ou les procédures stockées PL/SQL. Il faut s'assurer de la consistance transactionnelle appropriée des applications lors de l'utilisation de la fonction oci_execute() avec différents modes dans le même script.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_execute() pour des requêtes

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemple #2 Exemple avec oci_execute() sans spécifier de mode

    <?php

    // Avant exécution, créez la table :
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');

    oci_execute($stid); // La ligne est validée et est immédiatement visible par les autres utilisateurs

    ?>

Exemple #3 Exemple avec oci_execute() et `OCI_NO_AUTO_COMMIT`

    <?php

    // Avant exécution, créez la table :
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $i, 10);
    for ($i = 1; $i <= 5; ++$i) {
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
    }
    oci_commit($conn);  // valide toutes les nouvelles valeurs : 1, 2, 3, 4, 5

    ?>

Exemple #4 Exemple avec oci_execute() et différents modes dans le même script

    <?php

    // Avant exécution, créez la table :
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);  // données non validées

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (456)');
    oci_execute($stid);  // valide à la fois les valeurs 123 et 456

    ?>

Exemple #5 Exemple avec oci_execute() et `OCI_DESCRIBE_ONLY`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM locations');
    oci_execute($s, OCI_DESCRIBE_ONLY);
    for ($i = 1; $i <= oci_num_fields($stid); ++$i) {
        echo oci_field_name($stid, $i) . "<br>\n";
    }

    ?>

### Notes

> Note:

> Les transactions sont automatiquement annulées lorsque les connexions sont fermées, ou lorsque le script se termine, suivant ce qui arrive en premier. Appelez explicitement la fonction oci_commit() pour valider une transaction.

> Tout appel à la fonction oci_execute() qui utilise le mode `OCI_COMMIT_ON_SUCCESS` explicitement ou par défaut validera toutes les transactions en cours.

> Toutes les requêtes Oracle DDL comme `CREATE` ou `DROP` valideront toutes les transactions en cours.

> Note:

> À cause du fait que la fonction oci_execute() envoie généralement la requête à la base de données, la fonction oci_execute() peut identifier les erreurs de syntaxe de la requête que la fonction oci_parse() aurait pu ne pas détecter.

### Voir aussi

- oci_parse() - Prépare une requête SQL avec Oracle

# oci_fetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch — Lit la prochaine ligne d'un résultat Oracle dans un buffer interne

### Description

function oci_fetch(resource `$statement`): bool

Lit la prochaine ligne d'une requête dans un buffer interne accessible soit via la fonction oci_result(), soit en utilisant les variables précédemment définies avec la fonction oci_define_by_name().

Voir la fonction oci_fetch_array() pour des informations génériques sur la récupération de données.

### Liste de paramètres

`statement`
  Un identifiant de requête OCI8 créé par la fonction oci_parse() et exécuté par la fonction oci_execute(), ou un identifiant de requête `REF CURSOR`.

### Valeurs de retour

Retourne `true` en cas de succès, ou `false` s'il n'y a plus de lignes disponibles pour la requête `statement`.

### Exemples

Exemple #1 Exemple avec oci_fetch() avec des variables définies

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // La définition doit s'effectuer AVANT l'exécution
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // Chaque récupération utilise les variables précédemment définies avec les données de la prochaine ligne
    while (oci_fetch($stid)) {
        echo "Location id $locid is $city<br>\n";
    }

    // Affiche :
    //   Location id 1000 is Roma
    //   Location id 1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #2 Exemple avec oci_fetch() et oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " is ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Affiche :
    //   1000 is Roma
    //   1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notes

> Note:

> Cette fonction ne retournera pas de lignes depuis le jeu de résultats implicite depuis une base de données Oracle. Utiliser plutôt la fonction oci_fetch_array().

### Voir aussi

- oci_define_by_name() - Associe une variable PHP avec une colonne pour une requête de récupération de données
- oci_fetch_all() - Lit plusieurs lignes d'un résultat dans un tableau multidimensionnel
- oci_fetch_array() - Lit une ligne d'un résultat sous forme de tableau associatif ou numérique
- oci_fetch_assoc() - Lit une ligne d'un résultat sous forme de tableau associatif
- oci_fetch_object() - Lit une ligne d'un résultat sous forme d'objet
- oci_fetch_row() - Lit la prochaine ligne d'une requête sous forme de tableau numérique
- oci_result() - Retourne la valeur d'une colonne dans un résultat Oracle

# oci_fetch_all

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_all — Lit plusieurs lignes d'un résultat dans un tableau multidimensionnel

### Description

function oci_fetch_all(
resource `$statement`,
array `&$output`,
int `$offset` = 0,
int `$limit` = -1,
int `$flags` = OCI_FETCHSTATEMENT_BY_COLUMN | OCI_ASSOC
): int

Lit toutes les lignes d'un résultat Oracle dans un tableau à 2 dimensions. Par défaut, toutes les lignes sont retournées.

Cette fonction peut être appelée une seule fois pour chaque requête exécutée via la fonction oci_execute().

### Liste de paramètres

`statement`
  Un identifiant de requête OCI8 créé par la fonction oci_parse() et exécuté par la fonction oci_execute(), ou un identifiant de requête `REF CURSOR`.
`output`

  La variable qui va contenir les lignes retournées.

  Les colonnes LOB sont retournées sous la forme d'une chaîne lorsqu'Oracle supporte la conversion.

  Voir la fonction oci_fetch_array() pour plus d'informations sur la façon dont les données et leurs types sont récupérés.

`offset`

  Nombre de lignes initiales à ignorer lors de la lecture du résultat. Par défaut, ce paramètre vaut 0, pour commencer la lecture à la première ligne.

`limit`

  Nombre de lignes maximal à retourner. Par défaut, vaut -1, ce qui signifie que toutes les lignes disponibles seront retournées depuis le paramètre `offset` + 1.

`flags`

  Le paramètre `flags` indique la structure du tableau mais aussi si des tableaux associatifs doivent être utilisés.

  Modes de structure des tableaux pour la fonction oci_fetch_all()
  Constante | Description
  --- | ---
  `OCI_FETCHSTATEMENT_BY_ROW` | Le tableau retourné contiendra un seul sous tableau par lignes.
  `OCI_FETCHSTATEMENT_BY_COLUMN` | Le tableau retourné contiendra un seul sous tableau par colonnes. C'est le comportement par défaut.

  Les tableaux peuvent être indexés soit par l'en-tête de colonne, soit numériquement.

  Modes d'index des tableaux pour la fonction oci_fetch_all()
  Constante | Description
  --- | ---
  `OCI_NUM` | Des index numériques sont utilisés pour chaque tableau de colonnes.
  `OCI_ASSOC` | Des index associatifs sont utilisés pour chaque tableau de colonnes. C'est le comportement par défaut.

  Utiliser l'opérateur d'addition "+" pour choisir une combinaison de structures de tableaux et de modes d'index.

  Les noms de colonnes qui ne sont pas sensibles à la casse (par défaut sous Oracle), auront des noms d'attributs en majuscule. Les noms de colonnes qui sont sensibles à la casse, auront des noms d'attributs utilisant exactement la même casse de la colonne. Utiliser la fonction var_dump() sur l'objet de résultat pour vérifier la casse appropriée à utiliser pour chaque requête.

  Les requêtes qui possèdent plus d'une colonne dont le nom est identique doivent utiliser des alias. Sinon, seulement une des colonnes apparaîtra dans le tableau associatif.

### Valeurs de retour

Retourne le nombre de lignes récupérées dans le paramètre `output` qui peut être de 0 ou plus.

### Exemples

Exemple #1 Exemple avec oci_fetch_all()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res);

    echo "$nrows lignes récupérées<br>\n";
    var_dump($res);

    // var_dump affichera :
    //    2 lignes récupérées
    //    array(2) {
    //      ["POSTAL_CODE"]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(6) "10934x"
    //      }
    //      ["CITY"]=>
    //      array(2) {
    //        [0]=>
    //        string(4) "Roma"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    // Affichage des résultats
    echo "<table border='1'>\n";
    foreach ($res as $col) {
        echo "<tr>\n";
        foreach ($col as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #2 Exemple avec oci_fetch_all() et `OCI_FETCHSTATEMENT_BY_ROW`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW);

    echo "$nrows lignes récupérées<br>\n";
    var_dump($res);

    // Affiche :
    //    2 lignes récupérées
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "00989x"
    //        ["CITY"]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "10934x"
    //        ["CITY"]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #3 Exemple avec oci_fetch_all() et `OCI_NUM`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW + OCI_NUM);

    echo "$nrows lignes récupérées<br>\n";
    var_dump($res);

    // Affiche :
    //    2 lignes récupérées
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "10934x"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notes

> Note:

> L'utilisation du paramètre `offset` est vraiment inefficace. Toutes les lignes à éviter sont comprises dans le jeu de résultats retourné par la base de données à PHP. Puis, elles sont écartées. Il est plus efficace d'utiliser une requête SQL pour restreindre le champ des lignes désirées. Voir la fonction oci_fetch_array() pour un exemple concret.

> Note:

> Les requêtes qui retournent un très grand nombre de lignes peuvent gagner en économie de mémoire lors de l'utilisation de fonctions récupérant une seule ligne, comme le fait la fonction oci_fetch_array().

> Note: Pour les requêtes retournant un très grand nombre de lignes, les performances peuvent être très grandement accrues en augmentant la valeur de l'option oci8.default_prefetch ou en utilisant la fonction oci_set_prefetch().

> Note:

> Cette fonction ne retournera pas de lignes depuis un jeu de résultats implicite d'une base de données Oracle 12c. Il faut plutôt utiliser la fonction oci_fetch_array().

### Voir aussi

- oci_fetch() - Lit la prochaine ligne d'un résultat Oracle dans un buffer interne
- oci_fetch_array() - Lit une ligne d'un résultat sous forme de tableau associatif ou numérique
- oci_fetch_assoc() - Lit une ligne d'un résultat sous forme de tableau associatif
- oci_fetch_object() - Lit une ligne d'un résultat sous forme d'objet
- oci_fetch_row() - Lit la prochaine ligne d'une requête sous forme de tableau numérique
- oci_set_prefetch() - Indique le nombre de lignes qui doivent être lues à l'avance par Oracle

# oci_fetch_array

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_array — Lit une ligne d'un résultat sous forme de tableau associatif ou numérique

### Description

function oci_fetch_array(resource `$statement`, int `$mode` = OCI_BOTH | OCI_RETURN_NULLS): array|false

Retourne un tableau contenant la prochaine ligne d'une requête. Chaque entrée de ce tableau correspond à une colonne de la ligne. Cette fonction est appelée typiquement dans une boucle qui retourne `false` lorsqu'il n'y a plus de ligne disponible.

Si le paramètre `statement` correspond à un bloc PL/SQL retourné par des jeux de résultats implicites Oracle Database, alors les lignes depuis tous les jeux de résultats seront récupérées consécutivement. Si `statement` est retourné par la fonction oci_get_implicit_resultset(), alors seul le sous-jeu de lignes d'une seule requête enfant sera retourné.

Pour plus de détails sur le mapping des types de données effectué par l'extension OCI8, lisez les types de données supportés par le driver.

### Liste de paramètres

`statement`
  Un identifiant de requête OCI8 créé par la fonction oci_parse() et exécuté par la fonction oci_execute(), ou un identifiant de requête `REF CURSOR`.

  Peut également être un identifiant de requête retourné par la fonction oci_get_implicit_resultset().

`mode`

  Le paramètre optionnel `mode` peut être la combinaison des constantes suivantes :

  Modes pour oci_fetch_array()
  Constante | Description
  --- | ---
  `OCI_BOTH` | Retourne un tableau, indexé numériquement et avec les noms de colonnes. Identique à `OCI_ASSOC` + `OCI_NUM`). C'est le comportement par défaut.
  `OCI_ASSOC` | Retourne un tableau associatif.
  `OCI_NUM` | Retourne un tableau indexé numériquement.
  `OCI_RETURN_NULLS` | Crée des éléments vides pour les valeurs `null`. La valeur des éléments sera la valeur `null` PHP.
  `OCI_RETURN_LOBS` | Retourne le contenu du LOB au lieu de leur descripteur.

  Le `mode` par défaut est `OCI_BOTH`.

  Utiliser l'opérateur d'addition "+" pour spécifier plus d'un mode à la fois.

### Valeurs de retour

Retourne un tableau avec des indices numériques ou associatifs. S'il n'y a plus de ligne disponible pour la requête `statement` alors `false` sera retourné.

Par défaut, les colonnes `LOB` sont retournées sous la forme de descripteurs LOB.

Les colonnes `DATE` sont retournées sous la forme d'une chaîne formatée avec le format de date courante. Le format par défaut peut être modifié grâce aux variables d'environnement Oracle, comme `NLS_LANG` ou par l'exécution de la commande `ALTER SESSION SET NLS_DATE_FORMAT`.

Les noms de colonnes qui ne sont pas sensibles à la casse (par défaut sous Oracle), auront des noms d'attributs en majuscule. Les noms de colonnes qui sont sensibles à la casse, auront des noms d'attributs utilisant exactement la même casse de la colonne. Utiliser la fonction var_dump() sur l'objet de résultat pour vérifier la casse appropriée à utiliser pour chaque requête.

Le nom de la table n'est pas inclus dans l'index du tableau. Si la requête contient deux colonnes différentes avec le même nom, utiliser la constante `OCI_NUM` ou ajoutez un alias à la colonne à la requête pour s'assurer l'unicité du nom ; voir l'exemple #7. Sinon, seulement une colonne sera retournée via PHP.

### Exemples

Exemple #1 Exemple avec oci_fetch_array() avec `OCI_BOTH`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_BOTH)) != false) {
        // Utiliser des noms de colonne en majuscule pour les indices des tableau associatif
        echo $row[0] . " and " . $row['DEPARTMENT_ID']   . " are the same<br>\n";
        echo $row[1] . " and " . $row['DEPARTMENT_NAME'] . " are the same<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #2 Exemple avec oci_fetch_array() avec `OCI_NUM`

    <?php

    /*
      Avant l'exécution, créez la table :
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_NUM)) != false) {
        echo $row[0] . "<br>\n";
        echo $row[1]->read(11) . "<br>\n"; // ceci affichera les 11 premiers octets depuis DESCRIPTION
    }

    // Affiche :
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #3 Exemple avec oci_fetch_array() avec `OCI_ASSOC`

    <?php

    /*
      Avant l'exécution, créez la table :
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION']->read(11) . "<br>\n"; // ceci affichera les 11 premiers octets depuis DESCRIPTION
    }

    // Affiche :
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #4 Exemple avec oci_fetch_array() avec `OCI_RETURN_NULLS`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC)) != false) { // Ignore NULLs
        var_dump($row);
    }

    /*
    Le code ci-dessus affiche :
      array(1) {
        [1]=>
        string(1) "1"
      }
    */

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) { // Récupère NULLs
        var_dump($row);
    }

    /*
    Le code ci-dessus affiche :
      array(2) {
        [1]=>
        string(1) "1"
        ["NULL"]=>
        NULL
      }
    */

    ?>

Exemple #5 oci_fetch_array() with `OCI_RETURN_LOBS`

    <?php

    /*
      Avant l'exécution, créez la table :
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) != false) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION'] . "<br>\n"; // contient la totalité de DESCRIPTION

        // Dans une boucle, le fait de libérer la variable avant de récupérer une seconde
        // ligne permet de réduire l'utilisation mémoire de PHP
        unset($row);
    }

    // Affiche :
    //    1
    //    A very long string

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #6 Exemple avec oci_fetch_array() avec des noms de colonnes sensibles à la casse

    <?php

    /*
       Avant l'exécution, créez la table :
          CREATE TABLE mytab ("Name" VARCHAR2(20), city VARCHAR2(20));
          INSERT INTO mytab ("Name", city) values ('Chris', 'Melbourne');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);

    // Vu que 'Name' a été créé comme une colonne sensible à la casse, la même casse
    // est utilisé pour les index du tableau. Cependant, 'CITY' doit être utilisé
    // pour les index de colonne non sensible à la casse
    print $row['Name'] . "<br>\n";   //  affiche Chris
    print $row['CITY'] . "<br>\n";   //  affiche Melbourne

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #7 Exemple avec oci_fetch_array() avec des colonnes possédant des noms dupliqués

    <?php

    /*
      Avant l'exécution, créez la table :
          CREATE TABLE mycity (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycity (id, name) values (1, 'Melbourne');
          CREATE TABLE mycountry (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycountry (id, name) values (1, 'Australia');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT mycity.name, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // L'affiche ne contient que UNE entrée "NAME" :
    //    array(1) {
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    // Pour interroger un nom de colonne dupliqué, utiliser un alias de colonne SQL
    // comme "AS ctnm":
    $sql = 'SELECT mycity.name AS ctnm, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // L'affichage contient maintenant 2 colonnes :
    //    array(2) {
    //      ["CTNM"]=>
    //      string(9) "Melbourne"
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #8 Exemple avec oci_fetch_array() et des colonnes `DATE`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Définit le format utilisé pour les dates sur cette connexion.
    // Pour des raisons de performance, vous devriez modifier le format via un trigger ou
    // en utilisant les variables d'environnement
    $stid = oci_parse($conn, "ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD'");
    oci_execute($stid);

    $stid = oci_parse($conn, 'SELECT hire_date FROM employees WHERE employee_id = 188');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    echo $row['HIRE_DATE'] . "<br>\n";  // Affiche 1997-06-14

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #9 Exemple avec oci_fetch_array() et `REF CURSOR`

    <?php
    /*
      Créez la procédure stockée PL/SQL suivante avant l'exécution :

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Exécute le REF CURSOR retourné et y récupère un identifiant de requête
    oci_execute($refcur);
    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #10 Pagination avec oci_fetch_array() en utilisant une requête utilisant le paramètre `LIMIT`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Retrouve la version de la base de données
    preg_match('/Release ([0-9]+)\./', oci_server_version($conn), $matches);
    $oracleversion = $matches[1];

    // Requête pour la pagination
    $sql = 'SELECT city, postal_code FROM locations ORDER BY city';

    if ($oracleversion >= 12) {
        // Utilisation de la syntaxe Oracle 12c OFFSET / FETCH NEXT
        $sql = $sql . ' OFFSET :offset ROWS FETCH NEXT :numrows ROWS ONLY';
    } else {
        // Les versions anciennes d'Oracle ont besoin d'une requête imbriquée
        // pour sélectionner un sous-jeu depuis $sql. Ou, si la requête SQL
        // est connue au moment du développement, utiliser plutôt une fonction
        // row_number() au lieu de cette solution d'imbrication. Dans les
        // environnements de production, assurez-vous d'éviter les injections
        // SQL avec la concaténation.
        $sql = "SELECT * FROM (SELECT a.*, ROWNUM AS my_rnum
                               FROM ($sql) a
                               WHERE ROWNUM <= :offset + :numrows)
                WHERE my_rnum > :offset";
    }

    $offset  = 0;  // Ne pas traiter les premières lignes
    $numrows = 5;  // Retourne 5 lignes
    $stid = oci_parse($conn, $sql);
    oci_bind_by_name($stid, ':numrows', $numrows);
    oci_bind_by_name($stid, ':offset', $offset);
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_NULLS)) != false) {
        echo $row['CITY'] . " " . $row['POSTAL_CODE'] . "<br>\n";
    }

    // Affiche :
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    Geneva 1730
    //    Hiroshima 6823

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #11 Exemple avec oci_fetch_array() avec Oracle Database

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Requiert OCI8 2.0 (ou ultérieur) et Oracle Database 12c (ou ultérieur)
    // Voir aussi oci_get_implicit_resultset()
    $sql = 'DECLARE
               c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Note : oci_fetch_all et oci_fetch() ne peuvent être utilisées de cette façon
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Affiche :
    //    Beijing 190518
    //    Bern    3095
    //    Bombay  490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notes

> Note:

> Les indices des tableaux associatifs doivent être en majuscule pour les colonnes standards Oracle qui ont été créées avec des noms sensibles à la casse.

> Note: Pour les requêtes retournant un très grand nombre de lignes, les performances peuvent être très grandement accrues en augmentant la valeur de l'option oci8.default_prefetch ou en utilisant la fonction oci_set_prefetch().

> Note:

> La fonction oci_fetch_array() est à peine plus lente que la fonction oci_fetch_assoc() ou oci_fetch_row(), mais est plus flexible.

### Voir aussi

- oci_fetch() - Lit la prochaine ligne d'un résultat Oracle dans un buffer interne
- oci_fetch_all() - Lit plusieurs lignes d'un résultat dans un tableau multidimensionnel
- oci_fetch_assoc() - Lit une ligne d'un résultat sous forme de tableau associatif
- oci_fetch_object() - Lit une ligne d'un résultat sous forme d'objet
- oci_fetch_row() - Lit la prochaine ligne d'une requête sous forme de tableau numérique
- oci_set_prefetch() - Indique le nombre de lignes qui doivent être lues à l'avance par Oracle

# oci_fetch_assoc

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_assoc — Lit une ligne d'un résultat sous forme de tableau associatif

### Description

function oci_fetch_assoc(resource `$statement`): array|false

Retourne un tableau associatif contenant la prochaine ligne de résultat d'une requête. Chaque élément du tableau correspond à une colonne de la ligne. Cette fonction est appelée typiquement dans une boucle tant qu'elle ne retourne pas `false`, indiquant qu'il n'y a plus de ligne disponible.

oci_fetch_assoc() est identique à la fonction oci_fetch_array() et le mode `OCI_ASSOC` + `OCI_RETURN_NULLS`.

### Liste de paramètres

`statement`
  Un identifiant de requête OCI8 créé par la fonction oci_parse() et exécuté par la fonction oci_execute(), ou un identifiant de requête `REF CURSOR`.

### Valeurs de retour

Retourne un tableau associatif ou `false` s'il n'y a plus de ligne disponible pour la requête `statement`.

### Exemples

Exemple #1 Exemple avec oci_fetch_assoc()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_assoc($stid)) != false) {
        echo $row['DEPARTMENT_ID'] . " " . $row['DEPARTMENT_NAME'] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notes

> Note:

> Voir oci_fetch_array() pour plus d'exemples sur la récupération de lignes.

### Voir aussi

- oci_fetch() - Lit la prochaine ligne d'un résultat Oracle dans un buffer interne
- oci_fetch_all() - Lit plusieurs lignes d'un résultat dans un tableau multidimensionnel
- oci_fetch_array() - Lit une ligne d'un résultat sous forme de tableau associatif ou numérique
- oci_fetch_object() - Lit une ligne d'un résultat sous forme d'objet
- oci_fetch_row() - Lit la prochaine ligne d'une requête sous forme de tableau numérique

# oci_fetch_object

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_object — Lit une ligne d'un résultat sous forme d'objet

### Description

function oci_fetch_object(resource `$statement`, int `$mode` = OCI_ASSOC | OCI_RETURN_NULLS): stdClass|false

Retourne un objet contenant la prochaine ligne de résultat d'une requête. Chaque attribut de cet objet correspond à une colonne de la ligne. Cette fonction est appelée typiquement dans une boucle tant qu'elle ne retourne pas `false`, indiquant qu'il n'y a plus de lignes disponibles.

Pour plus de détails sur le mapping des types de données effectué par l'extension OCI8, lisez les types de données supportés par le driver.

### Liste de paramètres

`statement`
  Un identifiant de requête OCI8 créé par la fonction oci_parse() et exécuté par la fonction oci_execute(), ou un identifiant de requête `REF CURSOR`.

### Valeurs de retour

Retourne un objet. Chaque attribut de cet objet correspond à une colonne de la ligne. S'il n'y a plus de lignes disponibles dans la requête `statement` alors `false` est retourné.

Toutes les colonnes `LOB` sont retournées sous la forme de descripteurs LOB.

Les colonnes `DATE` sont retournées sous forme de chaînes formatées avec le format de date courante. Le format par défaut peut être changé à l'aide des variables d'environnement Oracle, comme `NLS_LANG` ou en exécutant la commande `ALTER SESSION SET NLS_DATE_FORMAT`.

Les noms de colonnes qui ne sont pas sensibles à la casse (par défaut sous Oracle), auront des noms d'attributs en majuscule. Les noms de colonnes qui sont sensibles à la casse, auront des noms d'attributs utilisant exactement la même casse de la colonne. Utiliser la fonction var_dump() sur l'objet de résultat pour vérifier la casse appropriée pour l'accès aux attributs.

Les valeurs d'attribut seront `null` pour chaque champ de données `NULL`.

### Exemples

Exemple #1 Exemple avec oci_fetch_object()

    <?php

    /*
      Avant l'exécution, créez la table :
        CREATE TABLE mytab (id NUMBER, description VARCHAR2(30));
        INSERT INTO mytab (id, description) values (1, 'Fish and Chips');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // Utiliser des noms d'attributs en majuscule pour chaque colonne standard Oracle
        echo $row->ID . "<br>\n";
        echo $row->DESCRIPTION . "<br>\n";
    }

    // Affiche :
    //    1
    //    Fish and Chips

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #2 Exemple avec oci_fetch_object() avec des noms de colonne sensibles à la casse

    <?php

    /*
      Avant l'exécution, créez le tableau avec une colonne dont le nom est sensible à la casse :
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, "MyDescription" FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // Utiliser des noms d'attributs en majuscule pour chaque colonne Oracle standard
        echo $row->ID . "<br>\n";
        // Utiliser la casse exacte pour les noms de colonnes sensibles à la casse
        echo $row->MyDescription . "<br>\n";
    }

    // Affiche :
    //    1
    //    Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #3 Exemple avec oci_fetch_object() avec des LOBs

    <?php

    /*
      Avant l'exécution, créez la table :
        CREATE TABLE mytab (id NUMBER, description CLOB);
        INSERT INTO mytab (id, description) values (1, 'A very long string');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        echo $row->ID . "<br>\n";
        // Ce qui suit affichera les 11 premiers octets depuis DESCRIPTION
        echo $row->DESCRIPTION->read(11) . "<br>\n";
    }

    // Affiche :
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Voir aussi

- oci_fetch() - Lit la prochaine ligne d'un résultat Oracle dans un buffer interne
- oci_fetch_all() - Lit plusieurs lignes d'un résultat dans un tableau multidimensionnel
- oci_fetch_assoc() - Lit une ligne d'un résultat sous forme de tableau associatif
- oci_fetch_array() - Lit une ligne d'un résultat sous forme de tableau associatif ou numérique
- oci_fetch_row() - Lit la prochaine ligne d'une requête sous forme de tableau numérique

# oci_fetch_row

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_row — Lit la prochaine ligne d'une requête sous forme de tableau numérique

### Description

function oci_fetch_row(resource `$statement`): array|false

Retourne un tableau indexé numériquement contenant la prochaine ligne d'une requête. Chaque élément de ce tableau correspond à une colonne de la ligne. Cette fonction est appelée typiquement dans une boucle tant qu'elle ne retourne pas `false`, indiquant qu'il n'y a plus de lignes disponibles.

oci_fetch_row() est identique à la fonction oci_fetch_array() et le mode `OCI_NUM` + `OCI_RETURN_NULLS`.

### Liste de paramètres

`statement`
  Un identifiant de requête OCI8 créé par la fonction oci_parse() et exécuté par la fonction oci_execute(), ou un identifiant de requête `REF CURSOR`.

### Valeurs de retour

Retourne un tableau indexé numériquement. S'il n'y a plus de lignes disponibles pour la requête `statement` alors `false` sera retourné.

### Exemples

Exemple #1 Exemple avec oci_fetch_row()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_row($stid)) != false) {
        echo $row[0] . " " . $row[1] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notes

> Note:

> Voir oci_fetch_array() pour plus d'exemples sur la récupération de lignes.

### Voir aussi

- oci_fetch() - Lit la prochaine ligne d'un résultat Oracle dans un buffer interne
- oci_fetch_all() - Lit plusieurs lignes d'un résultat dans un tableau multidimensionnel
- oci_fetch_array() - Lit une ligne d'un résultat sous forme de tableau associatif ou numérique
- oci_fetch_assoc() - Lit une ligne d'un résultat sous forme de tableau associatif
- oci_fetch_object() - Lit une ligne d'un résultat sous forme d'objet

# oci_field_is_null

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_is_null — Test si un champ de la ligne récupérée vaut `null`

### Description

function oci_field_is_null(resource `$statement`, string|int `$column`): bool

Vérifie si le champ `column` donné de la ligne courante de la requête `statement` vaut `null`.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

`column`

  Peut être l'index du champ (à partir de 1) ou son nom.

### Valeurs de retour

Retourne `true` si `column` vaut `null`, `false` sinon.

### Exemples

Exemple #1 Exemple avec oci_field_name()

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (c1 NUMBER);
    //   INSERT INTO mytab VALUES (1);
    //   INSERT INTO mytab VALUES (NULL);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) != false) {
        $ncols = oci_num_fields($stid);
        for ($col = 1; $col <= $ncols; $col++) {
            var_dump(oci_field_is_null($stid, $col));
        }
    }

    // Affiche :
    //    bool(false)
    //    bool(true)

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_field_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_name — Retourne le nom d'un champ Oracle

### Description

function oci_field_name(resource `$statement`, string|int `$column`): string|false

Retourne le nom du champ `column`.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

`column`

  Peut être un index de champ (en commençant à 1) ou un nom de champ.

### Valeurs de retour

Retourne le nom, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec oci_field_name()

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Utilisation de OCI_DESCRIBE_ONLY si aucune ligne n'est récupérée

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Affiche :
    //    Name           Type
    //    NUMBER_COL    NUMBER
    //    VARCHAR2_COL  VARCHAR2
    //    CLOB_COL      CLOB
    //    DATE_COL      DATE

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Voir aussi

- oci_num_fields() - Retourne le nombre de colonnes dans un résultat Oracle
- oci_field_type() - Retourne le type de données d'un champ Oracle
- oci_field_size() - Retourne la taille d'un champ Oracle

# oci_field_precision

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_precision — Lit la précision d'un champ Oracle

### Description

function oci_field_precision(resource `$statement`, string|int `$column`): int|false

Retourne la précision du champ `column`.

Pour les colonnes de type FLOAT, la précision est non nulle, et l'échelle est de -127. Si la précision est 0, alors la colonne est de type NUMBER. Sinon, elle est de type `NUMBER(precision, scale)`.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

`column`

  Peut être un index de champ (en commençant à 1) ou un nom de champ.

### Valeurs de retour

Retourne la précision, sous la forme d'un entier, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec oci_field_precision()

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Utilisation de  OCI_DESCRIBE_ONLY si aucune ligne n'est récupérée

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Affiche :
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Voir aussi

- oci_field_scale() - Lit l'échelle d'une colonne Oracle
- oci_field_type() - Retourne le type de données d'un champ Oracle

# oci_field_scale

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_scale — Lit l'échelle d'une colonne Oracle

### Description

function oci_field_scale(resource `$statement`, string|int `$column`): int|false

Lit l'échelle d'une colonne Oracle.

Pour les colonnes de type FLOAT, la précision est non nulle, et l'échelle est de -127. Si la précision est 0, alors la colonne est de type NUMBER. Sinon, elle est de type `NUMBER(precision, scale)`.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

`column`

  Peut être un index de champ (en commençant à 1) ou le nom d'un champ.

### Valeurs de retour

Retourne l'échelle, sous la forme d'un entier, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec oci_field_scale()

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Utilisation de OCI_DESCRIBE_ONLY si aucune ligne n'est récupérée

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Affiche :
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Voir aussi

- oci_field_precision() - Lit la précision d'un champ Oracle
- oci_field_type() - Retourne le type de données d'un champ Oracle

# oci_field_size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_size — Retourne la taille d'un champ Oracle

### Description

function oci_field_size(resource `$statement`, string|int `$column`): int|false

Retourne la taille du champ `column` Oracle .

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

`column`

  Peut être l'index du champ (l'indexation commence à 1) ou le nom du champ.

### Valeurs de retour

Retourne la taille du champ `column` en octets, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec oci_field_size()

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Utilisation de OCI_DESCRIBE_ONLY si aucune ligne n'est récupérée

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Affiche :
    //    Name           Type       Length
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Voir aussi

- oci_num_fields() - Retourne le nombre de colonnes dans un résultat Oracle
- oci_field_name() - Retourne le nom d'un champ Oracle

# oci_field_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type — Retourne le type de données d'un champ Oracle

### Description

function oci_field_type(resource `$statement`, string|int `$column`): string|int|false

Retourne le nom du type de données d'un champ.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

`column`

  Peut être l'index du champ (l'indexation commence à 1) ou le nom.

### Valeurs de retour

Retourne le type de données d'un champ, sous la forme d'une chaîne de caractères ou d'un entier, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec oci_field_type()

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Utilisation de OCI_DESCRIBE_ONLY si aucune ligne n'est récupérée

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Affiche :
    //    Name           Type       Length
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Voir aussi

- oci_num_fields() - Retourne le nombre de colonnes dans un résultat Oracle
- oci_field_name() - Retourne le nom d'un champ Oracle
- oci_field_size() - Retourne la taille d'un champ Oracle

# oci_field_type_raw

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type_raw — Lit les données brutes du type d'un champ

### Description

function oci_field_type_raw(resource `$statement`, string|int `$column`): int|false

Lit les données brutes "SQLT" du type du champ `column`.

Pour avoir le nom du type du champ, utiliser la fonction oci_field_type().

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

`column`

  Peut être l'index d'un champ (en commençant à 1) ou le nom d'un champ.

### Valeurs de retour

Retourne le type brut de données Oracle, pour le champ, sous la forme d'un nombre, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec oci_field_type_raw()

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1), clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid, OCI_DESCRIBE_ONLY);  // Utilisation de OCI_DESCRIBE_ONLY si aucune ligne n'est récupérée

    $n = oci_num_fields($stid);
    for ($i = 1; $i <= $n; ++$i) {
        echo oci_field_name($stid, $i) . " is raw type: " . oci_field_type_raw($stid, $i) . "<br>\n";
    }

    // Affiche :
    //    NUMBER_COL is raw type: 2
    //    VARCHAR2_COL is raw type: 1
    //    CLOB_COL is raw type: 112
    //    DATE_COL is raw type: 12

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_free_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_descriptor — Libère un descripteur

### Description

function oci_free_descriptor(OCILob `$lob`): bool

Libère un descripteur alloué par la fonction oci_new_descriptor().

### Liste de paramètres

`lob`

  Descripteur alloué par oci_new_descriptor().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Notes

> Note:

> Cette fonction est habituellement utilisée comme méthode OCILOB::free.

### Voir aussi

- OCILOB::free

# oci_free_statement

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_statement — Libère toutes les ressources réservées par un résultat Oracle

### Description

function oci_free_statement(resource `$statement`): bool

Libère toutes les ressources réservées par le résultat ou curseur Oracle `statement`. Ce dernier a été obtenu de la fonction oci_parse(), ou directement d'Oracle.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# oci_get_implicit_resultset

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL OCI8 >= 2.0.0)

oci_get_implicit_resultset — Retourne le fils suivant d'une ressource de requête depuis une ressource de requête parent qui a un jeu de résultat implicite Oracle Database

### Description

function oci_get_implicit_resultset(resource `$statement`): resource|false

Utilisé pour récupérer des jeux consécutifs de résultats de requêtes après l'exécution d'un bloc stocké ou anonyme Oracle PL/SQL où ce bloc retourne des résultats de requêtes avec la fonction DBMS_SQL.RETURN_RESULT Oracle PL/SQL de la base de données Oracle 12 (ou ultérieur). Ceci permet aux blocs PL/SQL de retourner facilement des résultats de requêtes.

La requête fils peut être utilisée avec n'importe laquelle des fonctions de récupération OCI8 : oci_fetch(), oci_fetch_all(), oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() ou oci_fetch_row()

Les requêtes fils héritent des valeurs pré-récupérées de leurs parents, ou elles peuvent être explicitement définies avec la fonction oci_set_prefetch().

### Liste de paramètres

`statement`

  Un identifiant de requête OCI8 valide créé par la fonction oci_parse() et exécutée par la fonction oci_execute(). L'identifiant de requête peut ou non être associé avec une requête OCI8 qui retourne des jeux de résultats implicites.

### Valeurs de retour

Retourne un gestionnaire de requête pour la prochaine requête fils disponible sur `statement`. Retourne `false` lorsque la requête fils n'existe pas, ou que toutes les requêtes fils ont été retournées par de précédents appels à la fonction oci_get_implicit_resultset().

### Exemples

Exemple #1 Récupération des jeux de résultats implicites via une boucle

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (($stid_c = oci_get_implicit_resultset($stid))) {
        echo "<h2>Nouveau jeu de résultats implicite :</h2>\n";
        echo "<table>\n";
        while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
            echo "<tr>\n";
            foreach ($row as $item) {
                echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
            }
            echo "</tr>\n";
        }
        echo "</table>\n";
    }

    // Affiche :
    //    Nouveau jeu de résultats implicite :
    //     Beijing 190518
    //     Bern    3095
    //     Bombay  490231
    //    Nouveau jeu de résultats implicite :
    //     CN
    //     CH
    //     IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #2 Récupère individuellement les gestionnaires de requêtes fils

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_1 = oci_get_implicit_resultset($stid);
    $stid_2 = oci_get_implicit_resultset($stid);

    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);

    // Affichage :
    //    array(2) {
    //      ["CITY"]=>
    //      string(7) "Beijing"
    //      ["POSTAL_CODE"]=>
    //      string(6) "190518"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CN"
    //    }
    //    array(2) {
    //      ["CITY"]=>
    //      string(4) "Bern"
    //      ["POSTAL_CODE"]=>
    //      string(4) "3095"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CH"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #3 Définition explicite du compteur de pré-récupération

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_c = oci_get_implicit_resultset($stid);
    oci_set_prefetch($stid_c, 200);   // Définit la pré-récupération avant de récupérer depuis la requête fils
    echo "<table>\n";
    while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #4 Exemple de jeu de résultats implicite sans utiliser la fonction oci_get_implicit_resultset()

Tous les résultats de toutes les requêtes sont retournés consécutivement.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Note : oci_fetch_all et oci_fetch() ne peuvent être utilisées de cette façon
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Affichage :
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notes

> Note: Pour les requêtes retournant un très grand nombre de lignes, les performances peuvent être très grandement accrues en augmentant la valeur de l'option oci8.default_prefetch ou en utilisant la fonction oci_set_prefetch().

# oci_lob_copy

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_copy — Copie un LOB Oracle

### Description

function oci_lob_copy(OCILob `$to`, OCILob `$from`, ?int `$length` = `null`): bool

Copie un LOB ou une partie d'un LOB vers un autre LOB. Les anciennes données du LOB de destination seront écrasées par les nouvelles.

S'il faut copier une partie spécifique d'un LOB vers une position particulière d'un LOB, utiliser la fonction OCILob::seek() pour déplacer le pointeur interne de LOB.

### Liste de paramètres

`to`

  Le LOB de destination.

`from`

  Le LOB copié.

`length`

  Indique la taille des données à copier.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` est désormais nullable.

### Notes

> Note:

> La classe OCILob était appelée OCI-Lob antérieur à PHP 8 et OCI8 3.0.0.

# oci_lob_is_equal

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_is_equal — Compare deux LOB/FILE Oracle

### Description

function oci_lob_is_equal(OCILob `$lob1`, OCILob `$lob2`): bool

Compare deux LOB/FILE Oracle.

### Liste de paramètres

`lob1`

  Un identifiant LOB.

`lob2`

  Un identifiant LOB.

### Valeurs de retour

Retourne `true` si ces objets sont égaux, `false` sinon.

### Notes

> Note:

> La classe OCILob était appelée OCI-Lob antérieur à PHP 8 et OCI8 3.0.0.

# oci_new_collection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_collection — Initialise une nouvelle collection Oracle

### Description

function oci_new_collection(resource `$connection`, string `$type_name`, ?string `$schema` = `null`): OCICollection|false

Initialise une nouvelle collection Oracle.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle, retourné par la fonction oci_connect() ou la fonction oci_pconnect().

`type_name`

  Doit être un type nommé valide (en majuscule).

`schema`

  Doit pointer sur le schéma de base de données, où le type a été créé. Le nom de l'utilisateur courant est utilisé quand `null` est fourni.

### Valeurs de retour

Retourne un nouvel objet OCICollection, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | `schema` est désormais nullable.

### Notes

> Note:

> La classe OCICollection était appelée OCI-Collection antérieurement à PHP 8 et OCI8 3.0.0.

# oci_new_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_connect — Connexion au serveur Oracle en utilisant une seule connexion

### Description

function oci_new_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Établit une nouvelle connexion au serveur Oracle et s'identifie.

Contrairement aux fonctions oci_connect() et oci_pconnect(), oci_new_connect() ne met pas en cache les connexions et retourne toujours un gestionnaire de connexion nouvellement ouvert. Ceci est très utile si l'application a besoin d'une isolation transactionnelle entre deux jeux de requêtes.

### Liste de paramètres

`username`

  Le nom d'utilisateur Oracle.

`password`

  Le mot de passe pour l'utilisateur.

`connection_string`
  Contient l'instance `Oracle` sur laquelle nous devons nous connecter. Ce peut être une » chaîne de connexion rapide, un nom de connexion issue du fichier tnsnames.ora, ou le nom d'une instance locale Oracle. Si non spécifié ou `null`, PHP utilise des variables d'environnement comme `TWO_TASK` (sous Linux) ou `LOCAL` (sous Windows) et `ORACLE_SID` pour déterminer l'instance `Oracle` sur laquelle nous devons nous connecter. Pour utiliser la méthode de connexion rapide, PHP doit être lié avec la bibliothèque cliente Oracle 10g ou supérieur. La chaîne de connexion rapide pour Oracle 10g ou supérieur est de la forme : [//]host_name[:port][/service_name]. Depuis Oracle 11g, la syntaxe est : [//]host_name[:port][/service_name][:server_type][/instance_name]. Des options supplémentaires ont été introduit avec Oracle 19c Les noms des services peuvent être trouvés en exécutant l'utilitaire Oracle `lsnrctl status` sur la machine exécutant la base de données. Le fichier tnsnames.ora peut être dans le chemin de recherche d'Oracle Net, qui inclut /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin et /etc. Une solution alternative serait de définit `TNS_ADMIN` afin que le fichier $TNS_ADMIN/tnsnames.ora soit lu. Assurez-vous que le daemon exécutant le serveur web a accès en lecture à ce fichier.
`encoding`
  Détermine le jeu de caractères utilisé par la bibliothèque cliente Oracle. Le jeu de caractères n'a pas besoin d'être identique à celui utilisé par la base de données. S'il ne correspond pas, Oracle ferait de son mieux pour convertir les données depuis le jeu de caractères de la base de données. Suivant les jeux de caractères, il se peut que le résultat ne soit pas parfait. De plus, cette conversion nécessite un peu de temps système. Si non spécifié, la bibliothèque cliente Oracle déterminera un jeu de caractères depuis la variable d'environnement `NLS_LANG`. Le fait de passer ce paramètre peut réduire la durée de connexion.
`session_mode`
  Ce paramètre est disponible à partir de PHP 5 (PECL OCI8 1.1) et accepte les valeurs suivantes : `OCI_DEFAULT`, `OCI_SYSOPER` et `OCI_SYSDBA`. Si soit la constante `OCI_SYSOPER`, soit la constante `OCI_SYSDBA` est spécifiée, cette fonction tentera d'établir une connexion privilégiée en utilisant des identifiants externes. Les connexions privilégiées sont désactivées par défault. Pour les activer, vous devez définir l'option oci8.privileged_connect à `On`. PHP 5.3 (PECL OCI8 1.3.4) introduisent la valeur de mode `OCI_CRED_EXT`. Ce mode demande à Oracle d'utiliser une identification externe ou bien issue du système d'exploitation, qui doit être configurée dans la base de données. Le drapeau `OCI_CRED_EXT` ne peut être utilisé qu'avec le nom d'utilisateur "/" associé à un mot de passe vide. L'option oci8.privileged_connect peut être définie à `On` ou `Off`. `OCI_CRED_EXT` peut être combiné avec le mode `OCI_SYSOPER` ou le mode `OCI_SYSDBA`. `OCI_CRED_EXT` n'est pas supporté sous Windows pour des raisons de sécurité.

### Valeurs de retour

Retourne un identifiant de connexion, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` est désormais nullable.

### Exemples

Voici comment séparer des transactions.

Exemple #1 Exemple avec oci_new_connect()

    <?php

    // Création de la table mytab (mycol number);

    function query($name, $c)
    {
        echo "Querying $name\n";
        $s = oci_parse($c, "select * from mytab");
        oci_execute($s, OCI_NO_AUTO_COMMIT);
        $row = oci_fetch_array($s, OCI_ASSOC);
        if (!$row) {
            echo "No rows\n";
        } else {
            do {
                foreach ($row as $item)
                    echo $item . " ";
                echo "\n";
            } while (($row = oci_fetch_array($s, OCI_ASSOC)) != false);
        }
    }

    $c1 = oci_connect("hr", "welcome", "localhost/orcl");
    $c2 = oci_new_connect("hr", "welcome", "localhost/orcl");

    $s = oci_parse($c1, "insert into mytab values(1234)");
    oci_execute($s, OCI_NO_AUTO_COMMIT);

    query("basic connection", $c1);
    query("new connection", $c2);
    oci_commit($c1);
    query("new connection after commit", $c2);

    // Affiche :
    //   Querying basic connection
    //   1234
    //   Querying new connection
    //   No rows
    //   Querying new connection after commit
    //   1234

    ?>

Voir la fonction oci_connect() pour plus d'exemples sur l'utilisation de ce paramètre.

### Voir aussi

- oci_connect() - Établit une connexion avec un serveur Oracle
- oci_pconnect() - Ouvre une connexion persistante à un serveur Oracle

# oci_new_cursor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_cursor — Alloue et retourne un nouveau curseur Oracle

### Description

function oci_new_cursor(resource `$connection`): resource|false

Alloue un nouveau curseur Oracle sur la connexion spécifiée.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle, retourné par la fonction oci_connect() ou la fonction oci_pconnect().

### Valeurs de retour

Retourne un nouveau gestionnaire de connexion, ou `false` si une erreur survient.

### Exemples

Exemple #1 Utiliser un REF CURSOR issu d'une procédure enregistrée

    <?php
    // Prérequis :
    //   crée ou remplace la procédure myproc(myrc out sys_refcursor) comme ceci
    //   begin
    //     open myrc for select first_name from employees;
    //   end;

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $curs = oci_new_cursor($conn);
    $stid = oci_parse($conn, "begin myproc(:cursbv); end;");
    oci_bind_by_name($stid, ":cursbv", $curs, -1, OCI_B_CURSOR);
    oci_execute($stid);

    oci_execute($curs);  // Exécute le REF CURSOR comme un identifiant de requête normal
    while (($row = oci_fetch_array($curs, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo $row['FIRST_NAME'] . "<br />\n";
    }

    oci_free_statement($stid);
    oci_free_statement($curs);
    oci_close($conn);
    ?>

# oci_new_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_descriptor — Initialise un nouveau pointeur vide de LOB/FILE Oracle

### Description

function oci_new_descriptor(resource `$connection`, int `$type` = `OCI_DTYPE_LOB`): ?OCILob

Initialise un nouveau pointeur vide de LOB/FILE Oracle.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle, retourné par la fonction oci_connect() ou la fonction oci_pconnect().

`type`

  Les valeurs acceptées pour `type` sont : `OCI_D_FILE`, `OCI_D_LOB` et `OCI_D_ROWID`.

### Valeurs de retour

Retourne une nouvelle ressource LOB ou FILE en cas de succès, ou `null` en cas d'échec.

### Exemples

Exemple #1 Exemple avec oci_new_descriptor()

    <?php
    /* Ce script est fait pour être appelé dans un formulaire HTML
     * Il attend les variables $user, $password, $table, $where, et $commitsize
     * Le script efface alors les lignes sélectionnées avec ROWID et valide
     * l'effacement après chaque groupe de $commitsize lignes.
     * (Utiliser avec prudence, car il n'y a pas d'annulation possible).
     */
    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "select rowid from $table $where");
    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_define_by_name($stmt, "ROWID", $rowid);
    oci_execute($stmt);
    while (oci_fetch($stmt)) {
        $nrows = oci_num_rows($stmt);
        $delete = oci_parse($conn, "delete from $table where ROWID = :rid");
        oci_bind_by_name($delete, ":rid", $rowid, -1, OCI_B_ROWID);
        oci_execute($delete);
        echo "$nrows\n";
        if (($nrows % $commitsize) == 0) {
            oci_commit($conn);
        }
    }
    $nrows = oci_num_rows($stmt);
    echo "$nrows deleted...\n";
    oci_free_statement($stmt);
    oci_close($conn);
    ?>

    <?php
    /* Ce script illustre le chargement de colonnes de type LOB
     * Le formulaire utilisé dans cet exemple ressemble à ceci :
     * <form action="upload.php" method="post" enctype="multipart/form-data">
     * <input type="file" name="lob_upload" />
     * ...
     */
      if (!isset($lob_upload) || $lob_upload == 'none'){
    ?>
    <form action="upload.php" method="post" enctype="multipart/form-data">
    Upload file: <input type="file" name="lob_upload" /><br />
    <input type="submit" value="Upload" /> - <input type="reset" value="Reset" />
    </form>
    <?php
      } else {

         // $lob_upload contient le fichier temporaire

         // Reportez-vous à la section sur le téléchargement de fichiers
         // pour sécuriser vos téléchargements

         $conn = oci_connect($user, $password);
         $lob = oci_new_descriptor($conn, OCI_D_LOB);
         $stmt = oci_parse($conn, "insert into $table (id, the_blob)
                   values(my_seq.NEXTVAL, EMPTY_BLOB()) returning the_blob into :the_blob");
         oci_bind_by_name($stmt, ':the_blob', $lob, -1, OCI_B_BLOB);
         oci_execute($stmt, OCI_DEFAULT);
         if ($lob->savefile($lob_upload)){
            oci_commit($conn);
            echo "BLOB chargé !\n";
         }else{
            echo "Impossible de charger le BLOB\n";
         }
         $lob->free();
         oci_free_statement($stmt);
         oci_close($conn);
      }
    ?>

Exemple #2 Exemple avec oci_new_descriptor()

    <?php
    /* Appel d'une procédure PL/SQL stockée qui prend un clob
     * en entrée.
     * Exemple de signature de procédure stockée PL/SQL :
     *
     * PROCEDURE save_data
     *   Argument Name                  Type                    In/Out Default?
     *   ------------------------------ ----------------------- ------ --------
     *   KEY                            NUMBER(38)              IN
     *   DATA                           CLOB                    IN
     *
     */

    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "begin save_data(:key, :data); end;");
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stmt, ':key', $key);
    oci_bind_by_name($stmt, ':data', $clob, -1, OCI_B_CLOB);
    $clob->write($data);
    oci_execute($stmt, OCI_DEFAULT);
    oci_commit($conn);
    $clob->free();
    oci_free_statement($stmt);
    ?>

### Voir aussi

- oci_bind_by_name() - Associe une variable PHP à un marqueur Oracle

# oci_num_fields

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_fields — Retourne le nombre de colonnes dans un résultat Oracle

### Description

function oci_num_fields(resource `$statement`): int

Retourne le nombre de colonnes dans le résultat Oracle `statement`.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

### Valeurs de retour

Retourne le nombre de colonnes, sous la forme d'un entier.

### Exemples

Exemple #1 Exemple avec oci_num_fields()

    <?php

    // Création de la table avec :
    //   CREATE TABLE mytab (id NUMBER, quantity NUMBER);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Utilisation de OCI_DESCRIBE_ONLY si aucune ligne n'est récupérée

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " " . oci_field_type($stid, $i) . "<br>\n";
    }

    // Affiche :
    //    ID NUMBER
    //    QUANTITY NUMBER

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_num_rows

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_rows — Retourne le nombre de lignes affectées durant la dernière commande Oracle

### Description

function oci_num_rows(resource `$statement`): int|false

Retourne le nombre de lignes affectées durant la dernière commande Oracle.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide.

### Valeurs de retour

Retourne le nombre de lignes affectées, sous la forme d'un entier, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec oci_num_rows()

    <?php
    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "create table emp2 as select * from employees");
    oci_execute($stid);
    echo oci_num_rows($stid) . " lignes insérées.<br />\n";
    oci_free_statement($stid);

    $stid = oci_parse($conn, "delete from emp2");
    oci_execute($stid, OCI_DEFAULT);
    echo oci_num_rows($stid) . " lignes effacées.<br />\n";
    oci_commit($conn);
    oci_free_statement($stid);

    $stid = oci_parse($conn, "drop table emp2");
    oci_execute($stid);
    oci_free_statement($stid);

    oci_close($conn);
    ?>

### Notes

> Note:

> Cette fonction ne retourne pas le nombre de lignes sélectionnées. Pour les commandes de type SELECT, cette fonction va retourner le nombre de lignes qui ont été lues dans le buffer avec oci_fetch*().

# oci_parse

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_parse — Prépare une requête SQL avec Oracle

### Description

function oci_parse(resource `$connection`, string `$sql`): resource|false

Prépare la requête `sql` en utilisant la connexion `connection` et retourne l'identifiant de requête qui pourra être utilisé avec les fonctions oci_bind_by_name(), oci_execute(), etc.

Les identifiants de requête peuvent être libérés en utilisant la fonction oci_free_statement() ou en définissant la variable correspondante à la valeur `null`.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect() ou oci_new_connect().

`sql`

  La requête SQL ou PL/SQL.

  Les requêtes SQL ne doivent pas se terminer par un point-virgule (";"). Les requêtes PL/SQL doivent se terminer par un point-virgule (";").

### Valeurs de retour

Retourne un gestionnaire de requête en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_parse()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    // Analyse de la requête. Notez qu'il n'y a pas de point-virgule à la fin de la requête SQL
    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Exemple #2 Exemple avec oci_parse() et une requête PL/SQL

    <?php

    /*
      Avant d'exécuter ce code PHP, vous devez créer une procédure stockée en
      SQL*Plus ou SQL Developer:

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    // Lors de l'analyse PL/SQL, il doit y avoir un point-virgule à la fin de la chaîne
    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // affiche 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Notes

> Note:

> Cette fonction ne valide pas la requête `sql`. La seule façon de savoir si la requête `sql` est valide est de l'exécuter.

### Voir aussi

- oci_execute() - Exécute une commande SQL Oracle
- oci_free_statement() - Libère toutes les ressources réservées par un résultat Oracle

# oci_password_change

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_password_change — Modifie le mot de passe d'un utilisateur Oracle

### Description

function oci_password_change(
resource `$connection`,
string `$username`,
string `$old_password`,
string `$new_password`
): bool
function oci_password_change(
string `$database_name`,
string `$username`,
string `$old_password`,
string `$new_password`
): resource

Modifie le mot de passe de l'utilisateur `username`.

La fonction oci_password_change() est plus utile avec des scripts PHP en ligne de commandes, ou lorsque des connexions non persistantes sont utilisées dans l'application PHP.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle, retourné par la fonction oci_connect() ou la fonction oci_pconnect().

`username`

  Le nom d'utilisateur Oracle.

`old_password`

  L'ancien mot de passe.

`new_password`

  Le nouveau mot de passe à définir.

`database_name`

  Le nom de la base de données.

### Valeurs de retour

Quand `database_name` est fourni, oci_password_change() retourne `true` en cas de succès, ou `false` si une erreur survient. Quand `connection` est fourni, oci_password_change() retourne la ressource de connexion en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_password_change() pour changer le mot de passe d'un utilisateur déjà connecté

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    oci_password_change($c, $user, $current_pw, $new_pw);
    echo "Le nouveau mot de passe est : " . $new_pw . "\n";

    ?>

Exemple #2 Exemple avec oci_password_change() pour se connecter et changer le mot de passe en une seule étape

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    if (!$c) {
        $m = oci_error();
        if ($m['code'] == 28001) { // "ORA-28001: Le mot de passe a expiré"
            // Connexion et changement du mot de passe en une étape
            $c = oci_password_change($dbase, $user, $current_pw, $new_pw);
            if ($c) {
                echo "Le nouveau mot de passe est : " . $new_pw . "\n";
            }
        }
    }

    if (!$c) {  // L'erreur originale n'était pas 28001, ou la modification du mot de passe a échoué
        $m = oci_error();
        trigger_error('Impossible de se connecter à la base de données : '. $m['message'], E_USER_ERROR);
    }

    // Utilisation de la connexion $c
    // ...

    ?>

### Notes

> Note:

> Changer le mot de passe, avec cette fonction, ou directement dans Oracle devrait être fait avec précaution. Ceci car les applications PHP pourraient continuer d'utiliser des connexions persistantes avec l'ancien mot de passe. La meilleure pratique est de redémarrer tous les serveurs webs dès lors que le mot de passe a été changé.

> Note:

> Si l'on met à jour les bibliothèques clients ou la base de données Oracle depuis une version antérieure à 11.2.0.3 vers une version 11.2.0.3 ou supérieure, la fonction oci_password_change() peut retourner l'erreur "ORA-1017: invalid username/password" tant que les versions du client et du serveur ne seront pas identiques.

> Note:

> La seconde syntaxe de oci_password_change() est disponible depuis la version d'OCI8 1.1.

# oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — Ouvre une connexion persistante à un serveur Oracle

### Description

function oci_pconnect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Ouvre une connexion persistante à un serveur Oracle et s'identifie.

Les connexions persistantes sont mises en cache et sont réutilisées entre les requêtes, réduisant ainsi la charge à chaque chargement de la page ; une application PHP typique a une seule connexion persistante à un serveur Oracle par processus enfant Apache (ou processus PHP FastCGI/CGI). Voir la section sur la Gestion des Connexions et le Regroupement des Connexions pour plus d'informations.

### Liste de paramètres

`username`

  Le nom d'utilisateur Oracle.

`password`

  Le mot de passe de l'utilisateur.

`connection_string`
  Contient l'instance `Oracle` sur laquelle nous devons nous connecter. Ce peut être une » chaîne de connexion rapide, un nom de connexion issue du fichier tnsnames.ora, ou le nom d'une instance locale Oracle. Si non spécifié ou `null`, PHP utilise des variables d'environnement comme `TWO_TASK` (sous Linux) ou `LOCAL` (sous Windows) et `ORACLE_SID` pour déterminer l'instance `Oracle` sur laquelle nous devons nous connecter. Pour utiliser la méthode de connexion rapide, PHP doit être lié avec la bibliothèque cliente Oracle 10g ou supérieur. La chaîne de connexion rapide pour Oracle 10g ou supérieur est de la forme : [//]host_name[:port][/service_name]. Depuis Oracle 11g, la syntaxe est : [//]host_name[:port][/service_name][:server_type][/instance_name]. Des options supplémentaires ont été introduit avec Oracle 19c Les noms des services peuvent être trouvés en exécutant l'utilitaire Oracle `lsnrctl status` sur la machine exécutant la base de données. Le fichier tnsnames.ora peut être dans le chemin de recherche d'Oracle Net, qui inclut /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin et /etc. Une solution alternative serait de définit `TNS_ADMIN` afin que le fichier $TNS_ADMIN/tnsnames.ora soit lu. Assurez-vous que le daemon exécutant le serveur web a accès en lecture à ce fichier.
`encoding`
  Détermine le jeu de caractères utilisé par la bibliothèque cliente Oracle. Le jeu de caractères n'a pas besoin d'être identique à celui utilisé par la base de données. S'il ne correspond pas, Oracle ferait de son mieux pour convertir les données depuis le jeu de caractères de la base de données. Suivant les jeux de caractères, il se peut que le résultat ne soit pas parfait. De plus, cette conversion nécessite un peu de temps système. Si non spécifié, la bibliothèque cliente Oracle déterminera un jeu de caractères depuis la variable d'environnement `NLS_LANG`. Le fait de passer ce paramètre peut réduire la durée de connexion.
`session_mode`
  Ce paramètre est disponible à partir de PHP 5 (PECL OCI8 1.1) et accepte les valeurs suivantes : `OCI_DEFAULT`, `OCI_SYSOPER` et `OCI_SYSDBA`. Si soit la constante `OCI_SYSOPER`, soit la constante `OCI_SYSDBA` est spécifiée, cette fonction tentera d'établir une connexion privilégiée en utilisant des identifiants externes. Les connexions privilégiées sont désactivées par défault. Pour les activer, vous devez définir l'option oci8.privileged_connect à `On`. PHP 5.3 (PECL OCI8 1.3.4) introduisent la valeur de mode `OCI_CRED_EXT`. Ce mode demande à Oracle d'utiliser une identification externe ou bien issue du système d'exploitation, qui doit être configurée dans la base de données. Le drapeau `OCI_CRED_EXT` ne peut être utilisé qu'avec le nom d'utilisateur "/" associé à un mot de passe vide. L'option oci8.privileged_connect peut être définie à `On` ou `Off`. `OCI_CRED_EXT` peut être combiné avec le mode `OCI_SYSOPER` ou le mode `OCI_SYSDBA`. `OCI_CRED_EXT` n'est pas supporté sous Windows pour des raisons de sécurité.

### Valeurs de retour

Retourne un identifiant de connexion, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_pconnect()

    <?php

    // Connexion au service XE (i.e. base de données) sur la machine "localhost"
    $conn = oci_pconnect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Voir la fonction oci_connect() pour plus d'exemples sur l'utilisation de ce paramètre.

### Notes

> Note: La durée de vie ainsi que le nombre maximal de connexions persistantes Oracle par processus PHP peuvent être affinés en définissant les valeurs de configuration suivantes : oci8.persistent_timeout, oci8.ping_interval et oci8.max_persistent.

### Voir aussi

- oci_connect() - Établit une connexion avec un serveur Oracle
- oci_new_connect() - Connexion au serveur Oracle en utilisant une seule connexion

# oci_register_taf_callback

(PHP 7.0 >= 7.0.21, PHP 8, PHP 7 >= 7.1.7, PHP 8, PECL OCI8 >= 2.1.7)

oci_register_taf_callback — Enregistre une fonction de rappel définie par l'utilisateur pour Oracle Database TAF

### Description

function oci_register_taf_callback(resource `$connection`, ?callable `$callback`): bool

Enregistre une fonction de rappel définie par l'utilisateur pour `connection`. Si `connection` échoue en raison d'une défaillance de l'instance ou du réseau, la fonction de rappel enregistrée sera invoquée plusieurs fois pendant le basculement. Voir Support de basculement d'application transparente OCI8 (TAF) pour plus d'informations.

Lorsque oci_register_taf_callback() est appelée plusieurs fois, chaque enregistrement écrase le précédent.

Utiliser oci_unregister_taf_callback() pour annuler explicitement un rappel défini par l'utilisateur.

Les enregistrements de rappel TAF ne seront PAS sauvegardés entre les connexions persistantes, par conséquent, le rappel doit être réenregistré pour une nouvelle connexion persistante.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle.

`callback`

  Une fonction de rappel définie par l'utilisateur pour enregistrer TAF Oracle. Il peut s'agir d'une chaîne de nom de fonction ou d'une fermeture (fonction anonyme).

  L'interface pour une fonction de rappel définie par l'utilisateur TAF est la suivante :

  function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

  Voir la description du paramètre et un exemple sur la page Support de basculement d'application transparente OCI8 (TAF).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- oci_unregister_taf_callback() - Efface une fonction de rappel définie par l'utilisateur pour Oracle Database TAF

# oci_result

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_result — Retourne la valeur d'une colonne dans un résultat Oracle

### Description

function oci_result(resource `$statement`, string|int `$column`): mixed

Retourne les données de la colonne `column` dans la ligne courante du résultat `statement`.

Pour plus de détails sur le mapping des types de données effectué par l'extension OCI8, lisez les types de données supportés par le driver.

### Liste de paramètres

`statement`

`column`

  Peut être soit le numéro de la colonne (en commençant à 1), soit le nom de la colonne. Si c'est le nom de la colonne, c'est parce que les métadonnées Oracle le présentent comme tel, et sera en majuscule pour les colonnes créées en ne tenant pas compte de la casse.

### Valeurs de retour

Retourne tous les types, sauf les types abstraits (ROWIDs, LOBs et FILEs). Retourne `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec oci_fetch() et oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " is ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Affiche :
    //   1000 is Roma
    //   1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Voir aussi

- oci_fetch_array() - Lit une ligne d'un résultat sous forme de tableau associatif ou numérique
- oci_fetch_assoc() - Lit une ligne d'un résultat sous forme de tableau associatif
- oci_fetch_object() - Lit une ligne d'un résultat sous forme d'objet
- oci_fetch_row() - Lit la prochaine ligne d'une requête sous forme de tableau numérique
- oci_fetch_all() - Lit plusieurs lignes d'un résultat dans un tableau multidimensionnel

# oci_rollback

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_rollback — Annule les transactions Oracle en cours

### Description

function oci_rollback(resource `$connection`): bool

Annule toutes les modifications non validées pour une connexion `connection` Oracle et met fin à la transaction courante. Tous les verrous seront également libérés. Tous les points de sauvegarde Oracle (`SAVEPOINTS`) seront supprimés.

Une transaction commence lorsque la première requête SQL qui modifie des données est exécutée avec la fonction oci_execute() en utilisant le drapeau `OCI_NO_AUTO_COMMIT`. Les modifications suivantes effectuées par d'autres requêtes deviennent partie intégrante de la même transaction. Les modifications effectuées lors d'une transaction sont temporaires tant que la transaction n'a pas été validée ou annulée. Les autres utilisateurs de la base de données ne verront ces modifications que lors de la validation de la transaction.

Lors de l'insertion ou de la mise à jour de données, l'utilisation des transactions est fortement recommandée afin de garantir la consistance relationnelle des données, mais aussi pour des raisons de performance.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect() ou oci_new_connect().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_rollback()

    <?php

    // Insertion dans plusieurs tables, puis, annulation des modifications si des erreurs surviennent

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // Le drapeau OCI_NO_AUTO_COMMIT indique à Oracle de ne pas valider l'insertion immédiatement.
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // Annulation des modifications sur les 2 tables
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Validation des modifications sur les 2 tables
    $r = oci_commit($conn);
    if (!r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

Exemple #2 Exemple de retour à un point de sauvegarde (`SAVEPOINT`)

    <?php
    $stid = oci_parse($conn, 'UPDATE mytab SET id = 1111');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // création du point de sauvegarde
    $stid = oci_parse($conn, 'SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    $stid = oci_parse($conn, 'UPDATE mytab SET id = 2222');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // utilise une requête SQL explicite pour effectuer le retour au point de sauvegarde
    $stid = oci_parse($conn, 'ROLLBACK TO SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    oci_commit($conn);  // mytab a maintenant un id de 1111
    ?>

### Notes

> Note:

> Les transactions sont automatiquement annulées lorsqu'on ferme la connexion, ou lorsque le script se termine, un des deux arrivant le premier. Il faut explicitement appeler la fonction oci_commit() pour valider la transaction.

> Tous les appels à la fonction oci_execute() qui utilisent le mode `OCI_COMMIT_ON_SUCCESS`, que ce soit par défaut ou de façon explicite, valideront toutes les transactions en attente.

> Toutes les requêtes Oracle comme `CREATE` ou `DROP` valideront également, automatiquement, toutes les transactions en attente.

### Voir aussi

- oci_commit() - Valide les transactions Oracle en cours
- oci_execute() - Exécute une commande SQL Oracle

# oci_server_version

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_server_version — Retourne la version du serveur Oracle

### Description

function oci_server_version(resource `$connection`): string|false

Retourne une chaîne contenant la version du serveur Oracle ainsi que les options disponibles.

### Liste de paramètres

`connection`

### Valeurs de retour

Retourne les informations sur la version, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_server_version()

    <?php
    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    echo "Version du serveur : " . oci_server_version($conn);

    // Affiche :
    // Version du serveur : Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit Production
    // With the Partitioning, OLAP, Data Mining and Real Application Testing option

    oci_close($conn);
    ?>

### Voir aussi

- oci_client_version() - Retourne la version de la bibliothèque cliente Oracle

# oci_set_action

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_action — Définit le nom de l'action

### Description

function oci_set_action(resource `$connection`, string `$action`): bool

Définit le nom de l'action pour un traçage Oracle.

Le nom de l'action est enregistré avec la base de données lors du prochain aller-retour 'round-trip' entre PHP et la base de données ; typiquement, lorsqu'une requête SQL est exécutée.

Le nom de l'action peut être interrogé par la suite depuis la vue d'administration de la base de données `V$SESSION`. Il peut être utilisé pour tracer et surveiller d'autres vues comme `V$SQLAREA` et `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

La valeur peut être conservée au travers des connexions persistantes.

### Liste de paramètres

`connection`
  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect() ou la fonction oci_new_connect().
`action`

  Chaîne choisie par l'utilisateur jusqu'à 32 octets de long.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Définition d'une action

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Enregistre l'action
    oci_set_action($c, 'Friend Lookup');

    // Code générant un aller-retour (round-trip), par exemple, une requête :
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Pendant l'exécution du script, l'administrateur peut voir les actions
    // en cours d'exécution :

    sqlplus system/welcome
    SQL> select action from v$session;

### Notes

> Note: Requis par la version Oracle
> Cette fonction est disponible si PHP est lié à partir de la version 10g de la bibliothèque de la base de données Oracle .

Astuce

# Performance

Avec les anciennes version OCI8 ou les anciennes bases de données Oracle, l'information quant au client peut être défini en utilisant le paquet Oracle `DBMS_APPLICATION_INFO`. Ceci est moins efficace que d'utiliser la fonction oci_set_client_info().

Attention

# Allers-retours

Quelques fonctions OCI8 nécessitent des allers-retours avec la base de données. Ces allers-retours peuvent être évités lors de l'utilisation de requêtes dont le résultat est mis en cache.

### Voir aussi

- oci_set_module_name() - Définit le nom du module
- oci_set_client_info() - Définit l'information concernant le client
- oci_set_client_identifier() - Définit l'identifiant du client
- oci_set_db_operation() - Définit l'opération de base de données

# oci_set_call_timeout

(PHP 7.2 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_call_timeout — Définit un délai d'attente en millisecondes pour les appels de base de données

### Description

function oci_set_call_timeout(resource `$connection`, int `$timeout`): bool

Définit un délai d'attente limitant le temps maximum qu'un aller-retour de base de données utilisant cette connexion peut prendre.

Chaque opération OCI8 peut effectuer zéro ou plusieurs appels à la bibliothèque cliente d'Oracle. Ces appels internes peuvent ensuite effectuer zéro ou plusieurs aller-retours vers la base de données Oracle. Si l'un de ces aller-retours prend plus de `time_out` millisecondes, alors l'opération est annulée et une erreur est renvoyée à l'application.

La valeur `time_out` s'applique à chaque aller-retour individuellement, et non à la somme de tous les aller-retours. Le temps passé à traiter en PHP OCI8 avant ou après l'achèvement de chaque aller-retour n'est pas compté.

Lorsqu'un appel est interrompu, Oracle tentera de nettoyer la connexion pour la réutiliser. Cette opération est autorisée à s'exécuter pendant une autre période de `time_out`. En fonction du résultat du nettoyage, la connexion peut ou non être réutilisable.

Lorsque des connexions persistantes sont utilisées, la valeur de délai d'attente sera conservée entre les requêtes PHP.

La fonction oci_set_call_timeout() est disponible lorsque OCI8 utilise les bibliothèques clientes Oracle 18 (ou ultérieures).

### Liste de paramètres

`connection`
  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect() ou la fonction oci_new_connect().
`timeout`

  Le temps maximum en millisecondes qu'un aller-retour entre PHP et la base de données Oracle peut prendre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Mise en place du délai d'attente

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    oci_set_call_timeout($conn, 5000);

    ?>

# oci_set_client_identifier

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_identifier — Définit l'identifiant du client

### Description

function oci_set_client_identifier(resource `$connection`, string `$client_id`): bool

Définit l'identifiant du client, utilisé par de nombreux composants de la base de données pour identifier les utilisateurs de l'application qui s'authentifie avec le même nom d'utilisateur de base de données.

L'identifiant du client est enregistré avec la base de données lors du prochain aller-retour 'round-trip' entre PHP et la base de données est effectué ; typiquement, l'exécution d'une requête SQL.

L'identifiant peut par la suite être interrogé, par exemple, avec la requête `SELECT SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER') FROM DUAL`. Une vue de l'administration de la base de données, comme la vue `V$SESSION` contient également la valeur. Il peut être utilisé avec `DBMS_MONITOR.CLIENT_ID_TRACE_ENABLE` dans le cadre d'un traçage. Il peut également être utilisé dans le cadre d'un audit.

La valeur peut être conservée suivant les différentes requêtes des pages qui utilisent la même connexion persistante.

### Liste de paramètres

`connection`
  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect() ou la fonction oci_new_connect().
`client_id`

  Chaîne choisie par l'utilisateur jusqu'à 64 octets de long.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Définit l'identifiant du client comme l'utilisateur de l'application

    <?php

    // Retrouve le nom utilisé pour l'identification de l'utilisateur de l'application
    session_start();
    $un = my_validate_session($_SESSION['username']);
    $c = oci_connect('myschema', 'welcome', 'localhost/XE');

    // Informe Oracle sur cet utilisateur
    oci_set_client_identifier($c, $un);

    // Le prochain aller-retour (round-trip) vers la base de données validera cet identifiant
    $s = oci_parse($c, 'select mydata from mytable');
    oci_execute($s);

    // ...

    ?>

### Notes

Attention

# Allers-retours

Quelques fonctions OCI8 nécessitent des allers-retours avec la base de données. Ces allers-retours peuvent être évités lors de l'utilisation de requêtes dont le résultat est mis en cache.

### Voir aussi

- oci_set_module_name() - Définit le nom du module
- oci_set_action() - Définit le nom de l'action
- oci_set_client_info() - Définit l'information concernant le client
- oci_set_db_operation() - Définit l'opération de base de données

# oci_set_client_info

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_info — Définit l'information concernant le client

### Description

function oci_set_client_info(resource `$connection`, string `$client_info`): bool

Définit l'information concernant le client pour un traçage Oracle.

L'information du client est enregistrée avec la base de données lors du prochain aller-retour 'round-trip' entre PHP et la base de données survient ; typiquement, lorsqu'une requête SQL est exécutée.

L'information du client peut par la suite être interrogée depuis la vue d'administration de la base de données `V$SESSION`.

La valeur sera conservée via le mécanisme des connexions persistantes.

### Liste de paramètres

`connection`
  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect() ou la fonction oci_new_connect().
`client_info`

  Chaîne utilisateur jusqu'à 64 octets de long.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Définit l'information sur le client

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Enregistre l'information sur le client
    oci_set_client_info($c, 'My Application Version 2');

    // Code générant un aller-retour (round-trip), par exemple, une requête :
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Pendant l'exécution de ce script, l'administrateur peut voir les informations
    // du client :

    sqlplus system/welcome
    SQL> select client_info from v$session;

### Notes

> Note: Requis par la version Oracle
> Cette fonction est disponible si PHP est lié à partir de la version 10g de la bibliothèque de la base de données Oracle .

Astuce

# Performance

Avec les anciennes version OCI8 ou les anciennes bases de données Oracle, l'information quant au client peut être défini en utilisant le paquet Oracle `DBMS_APPLICATION_INFO`. Ceci est moins efficace que d'utiliser la fonction oci_set_client_info().

Attention

# Allers-retours

Quelques fonctions OCI8 nécessitent des allers-retours avec la base de données. Ces allers-retours peuvent être évités lors de l'utilisation de requêtes dont le résultat est mis en cache.

### Voir aussi

- oci_set_module_name() - Définit le nom du module
- oci_set_action() - Définit le nom de l'action
- oci_set_client_identifier() - Définit l'identifiant du client
- oci_set_db_operation() - Définit l'opération de base de données

# oci_set_db_operation

(PHP 7 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_db_operation — Définit l'opération de base de données

### Description

function oci_set_db_operation(resource `$connection`, string `$action`): bool

Définit l'opération de base de données (DBOP) pour le traçage Oracle.

L'opération de base de données est enregistrée avec la base de données lors du prochain 'aller-retour' de PHP vers la base de données, généralement lorsqu'une déclaration SQL est exécutée.

L'opération de base de données peut ensuite être interrogée à partir de l'administration de la base de données vues telles que `V$SQL_MONITOR`.

La fonction oci_set_db_operation() est disponible lorsque OCI8 utilise les bibliothèques clientes Oracle 12 (ou ultérieures) et Oracle Database 12 (ou ultérieures).

### Liste de paramètres

`connection`
  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect() ou la fonction oci_new_connect().
`action`

  La chaîne choisie par l'utilisateur.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Mise en place de la DBOP

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Enregistre l'opération
    oci_set_db_operation($c, 'main query');

    // Code qui provoque un aller-retour, par exemple une requête:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Lorsque le script est en cours d'exécution, l'administrateur peut voir les opérations de base de données
    // en cours d'exécution:

    sqlplus system/welcome
    SQL> select dbop_name from v$sql_monitor;

### Notes

Attention

# Allers-retours

Quelques fonctions OCI8 nécessitent des allers-retours avec la base de données. Ces allers-retours peuvent être évités lors de l'utilisation de requêtes dont le résultat est mis en cache.

### Voir aussi

- oci_set_action() - Définit le nom de l'action
- oci_set_module_name() - Définit le nom du module
- oci_set_client_info() - Définit l'information concernant le client
- oci_set_client_identifier() - Définit l'identifiant du client

# oci_set_edition

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_edition — Définit l'édition de la base de données

### Description

function oci_set_edition(string `$edition`): bool

Définit l'édition des objets de la base de données à utiliser par les connexions.

L'édition Oracle permet à des versions concurrentes des applications d'être exécutées en utilisant le même nom de schéma et d'objets. Ceci est pratique pour mettre à jour en direct les systèmes.

Appelez la fonction oci_set_edition() avant d'appeler une fonction comme oci_connect(), oci_pconnect() ou oci_new_connect().

Si une édition est définie mais n'est pas valide sur la base de données, toute tentative de connexion échouera même si la fonction oci_set_edition() retourne un statut de réussite.

Lors de l'utilisation des connexions persistantes, si une connexion avec l'édition demandée existe déjà, elle sera ré-utilisée. Sinon, une connexion persistante différente sera créée.

### Liste de paramètres

`edition`

  Nom de l'édition Oracle, précédemment créé avec la commande SQL "`CREATE EDITION`".

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 2 scripts peuvent utiliser différentes versions de myfunc() au même moment

    <?php

    // Fichier 1

    echo "Version 1 de l'application\n";

    oci_set_edition('ORA$BASE');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "Le résultat est $r\n";

    ?>

    <?php

    // Fichier 2

    echo "Version 2 de l'application\n";

    oci_set_edition('E1');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "Le résultat est $r\n";

    ?>

### Notes

> Note: Exigence de la version Oracle

> Cette fonction est disponible pour Oracle 11gR2 et suivants.

Attention

# Connexions persistantes

Pour éviter les inconsistances de données ou des erreurs inattendues, ne pas utiliser la requête ALTER SESSION SET EDITION pour changer une édition sur les connexions persistantes.

Attention

# File d'attente de connexions DRCP

Pour éviter les inconsistances de données ou des erreurs inattendues lors de l'utilisation des éditions et de DRCP avec Oracle 11.2.0.1, conservez une correspondance un-à-un entre oci8.connection_class et le nom de l'édition utilisé par les applications. Chaque serveur pour une classe de connexion donnée doit être utilisé avec une seule édition. Cette restriction a été supprimée dans Oracle 11.2.0.2.

# oci_set_module_name

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_module_name — Définit le nom du module

### Description

function oci_set_module_name(resource `$connection`, string `$name`): bool

Définit le nom du module pour le traçage Oracle.

Le nom du module est enregistré avec la base de données lors du prochain aller-retour 'round-trip' entre PHP et la base de données survient ; typiquement, lorsqu'une requête SQL est exécutée.

Le nom pourra être ensuite interrogé depuis la vue d'administration de la base de données comme `V$SESSION`. Il pourra être également utilisé pour du traçage et de la surveillance, comme avec `V$SQLAREA` et `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

La valeur sera retenue via le mécanisme des connexions persistantes.

### Liste de paramètres

`connection`
  Un identifiant de connexion Oracle, retourné par la fonction oci_connect(), oci_pconnect() ou la fonction oci_new_connect().
`name`

  Chaîne choisie par l'utilisateur jusqu'à 48 octets de long.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Définition du nom du module

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Enregistrement du module
    oci_set_module_name($c, 'Home Page');

    // Code générant un aller-retour (round-trip), par exemple, une requête :
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);
    ?>

    // Pendant l'exécution du script, l'administrateur peut voir les
    // modules en utilisation :

    sqlplus system/welcome
    SQL> select module from v$session;

### Notes

> Note: Requis par la version Oracle
> Cette fonction est disponible si PHP est lié à partir de la version 10g de la bibliothèque de la base de données Oracle .

Astuce

# Performance

Avec les anciennes version OCI8 ou les anciennes bases de données Oracle, l'information quant au client peut être défini en utilisant le paquet Oracle `DBMS_APPLICATION_INFO`. Ceci est moins efficace que d'utiliser la fonction oci_set_client_info().

Attention

# Allers-retours

Quelques fonctions OCI8 nécessitent des allers-retours avec la base de données. Ces allers-retours peuvent être évités lors de l'utilisation de requêtes dont le résultat est mis en cache.

### Voir aussi

- oci_set_action() - Définit le nom de l'action
- oci_set_client_info() - Définit l'information concernant le client
- oci_set_client_identifier() - Définit l'identifiant du client
- oci_set_db_operation() - Définit l'opération de base de données

# oci_set_prefetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_set_prefetch — Indique le nombre de lignes qui doivent être lues à l'avance par Oracle

### Description

function oci_set_prefetch(resource `$statement`, int `$rows`): bool

Définit le nombre de lignes à précharger par les bibliothèques clientes Oracle après un appel réussi à la fonction oci_execute() mais aussi pour chaque appel aux fonctions internes de récupération de lignes à la base de données. Pour les requêtes retournant un grand nombre de lignes, les performances peuvent être significativement améliorées en augmentant le nombre de lignes à précharger par rapport à la valeur par défaut définie par l'option de configuration oci8.default_prefetch.

Le préchargement est une façon efficace de retourner plus d'une ligne de données depuis la base de données pour chaque envoi réseau. Il en retourne une meilleure utilisation du réseau mais aussi une meilleure utilisation du CPU. Le préchargement de lignes est interne à OCI8 et le comportement des fonctions de récupération de données reste inchangé suivant la valeur du compteur de préchargement. Par exemple, la fonction oci_fetch_row() retournera toujours une ligne. Le buffer de préchargement est propre à chaque requête et ne sera pas utilisé pour ré-exécuter des requêtes ou par les autres connexions.

Il convient d'appeler la fonction oci_set_prefetch() avant la fonction oci_execute().

Un des moyens de gagner en efficacité est de définir la valeur de préchargement à une valeur raisonnable en fonction du réseau et de la base de données à gérer. Pour les requêtes retournant un très grand nombre de lignes, il convient de récupérer l'ensemble des lignes par morceaux (c.-à-d. définir la valeur de préchargement à une valeur en dessous du nombre total de lignes). Ceci permet à la base de données de gérer les requêtes des autres utilisateurs pendant que le script PHP gère le jeu de lignes courant.

Le préchargement a été introduit en Oracle 8i. Le préchargement `REF CURSOR` a été introduit en Oracle 11gR2 et est disponible lorsque PHP est lié avec les bibliothèques clientes Oracle 11gR2 (ou supérieur). Les curseurs imbriqués de préchargement ont été introduits en Oracle 11gR2 et nécessitent à la fois les bibliothèques clientes Oracle, et une base de données en version 11gR2 (ou supérieur).

Le préchargement n'est pas supporté lorsque les requêtes contiennent des colonnes de type LONG ou LOB. La valeur de préchargement sera utilisée dans toutes les situations où le préchargement est supporté.

Lors de l'utilisation de la base de données Oracle 12c, le jeu de valeurs préchargées par PHP peut être écrasé par le fichier de configuration client d'Oracle `oraaccess.xml`. Se référer à la documentation d'Oracle pour plus de détails.

### Liste de paramètres

`statement`
  Un identifiant de requête OCI8 créé par la fonction oci_parse() et exécuté par la fonction oci_execute(), ou un identifiant de requête `REF CURSOR`.
`rows`

  Le nombre de lignes à précharger, >=0

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Modification de la valeur de préchargement pour une requête

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
    oci_set_prefetch($stid, 300);  // A définir avant l'appel à la fonction oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Exemple #2 Modification de la valeur de préchargement pour une récupération REF CURSOR

    <?php
    /*
      Création de la procédure stockée PL/SQL suivante :

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Modification de la valeur de préchargement avant l'exécution du curseur.
    // Le préchargement REF CURSOR fonctionne lorsque PHP est lié avec les bibliothèques clientes
    // Oracle 11gR2 (ou supérieur)
    oci_set_prefetch($refcur, 200);
    oci_execute($refcur);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Si PHP OCI8 récupère des données depuis un curseur `REF CURSOR` puis, retourne le curseur `REF CURSOR` à une seconde procédure stockée pour traitement, alors il convient de définir le préchargement de `REF CURSOR` à `0` afin d'éviter de perdre des lignes du jeu de résultats. La valeur de préchargement est le nombre de lignes supplémentaire à récupérer pour chaque requête interne OCI8 à la base de données, aussi, le fait de la définir à `0` signifie uniquement que nous souhaitons récupérer une seule ligne à la fois.

Exemple #3 Définition de la valeur de préchargement lorsque l'on retourne un curseur `REF CURSOR` à Oracle

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/orcl');

    // Récupération du curseur REF CURSOR
    $stid = oci_parse($conn, 'BEGIN myproc(:rc_out); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc_out', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Affiche 2 lignes, mais ne précharge pas de lignes supplémentaires
    // sinon, ces lignes supplémentaires ne seront pas passées à myproc_use_rc().
    oci_set_prefetch($refcur, 0);
    oci_execute($refcur);
    $row = oci_fetch_array($refcur);
    var_dump($row);
    $row = oci_fetch_array($refcur);
    var_dump($row);

    // passe le curseur REF CURSOR à myproc_use_rc() afin d'effectuer d'autres
    // traitement sur le jeu de résultats
    $stid = oci_parse($conn, 'begin myproc_use_rc(:rc_in); end;');
    oci_bind_by_name($stid, ':rc_in', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    ?>

### Voir aussi

- l'option de configuration oci8.default_prefetch

# oci_set_prefetch_lob

(PHP 8.2, PECL OCI8 >= 3.2)

oci_set_prefetch_lob — Définit la quantité de données préchargées pour chaque CLOB ou BLOB.

### Description

function oci_set_prefetch_lob(resource `$statement`, int `$prefetch_lob_size`): bool

Définit la taille du tampon interne utilisé pour récupérer chaque valeur CLOB ou BLOB lorsque l'implémentation récupère le localisateur LOB Oracle interne de la base de données après un appel de requête réussi à oci_execute() et pour chaque demande de récupération interne ultérieure à la base de données. Augmenter cette valeur peut améliorer les performances de récupération des LOB plus petits en réduisant les allers-retours entre PHP et la base de données. L'utilisation de la mémoire changera.

Cette valeur affecte les LOB retournés sous forme d'instances OCILob et également ceux retournés en utilisant `OCI_RETURN_LOBS`.

Appeler oci_set_prefetch_lob() avant d'appeler oci_execute(). Si ce n'est pas fait, la valeur de oci8.prefetch_lob_size est utilisée.

La valeur de préchargement LOB doit être définie uniquement avec Oracle Database 12.2 ou ultérieur.

### Liste de paramètres

`statement`
  Un identifiant de requête OCI8 créé par la fonction oci_parse() et exécuté par la fonction oci_execute(), ou un identifiant de requête `REF CURSOR`.
`prefetch_lob_size`

  Le nombre d'octets de chaque LOB à précharger, >= 0

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Changement de la valeur de préchargement LOB pour une requête

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myclob FROM mytable');
    oci_set_prefetch_lob($stid, 100000);  // Set before calling oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS+OCI_RETURN_LOBS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Voir aussi

- L'option ini oci8.prefetch_lob_size

# oci_statement_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_statement_type — Retourne le type de la requête Oracle

### Description

function oci_statement_type(resource `$statement`): string|false

Retourne un mot clé identifiant le type de la requête `statement` OCI8.

### Liste de paramètres

`statement`

  Un identifiant de requête OCI valide, retourné par la fonction oci_parse().

### Valeurs de retour

Retourne le type de requête `statement` sous la forme d'une des chaînes suivantes.

Type de requête
Chaîne retournée | Notes
--- | ---
`ALTER` |
`BEGIN` |
`CALL` |
`CREATE` |
`DECLARE` |
`DELETE` |
`DROP` |
`INSERT` |
`SELECT` |
`UPDATE` |
`UNKNOWN` |

Retourne `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec oci_statement_type()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'DELETE FROM departments WHERE department_id = 130;');
    if (oci_statement_type($stid) == "DELETE") {
        trigger_error('Vous n\'êtes pas autorisé à effacer des lignes dans cette table', E_USER_ERROR);
    }
    else {
        oci_execute($stid);  // efface la ligne
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_unregister_taf_callback

(PHP 7.0 >= 7.0.23, PHP 8, PHP 7 >= 7.1.9, PHP 8, PECL OCI8 >= 2.1.7)

oci_unregister_taf_callback — Efface une fonction de rappel définie par l'utilisateur pour Oracle Database TAF

### Description

function oci_unregister_taf_callback(resource `$connection`): bool

Efface la fonction de rappel définie par l'utilisateur enregistrée pour `connection` par oci_register_taf_callback(). Voir Support de basculement d'application transparente OCI8 (TAF) pour plus d'informations.

### Liste de paramètres

`connection`

  Un identifiant de connexion Oracle.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- oci_register_taf_callback() - Enregistre une fonction de rappel définie par l'utilisateur pour Oracle Database TAF

## Sommaire

- oci_bind_array_by_name — Lie un tableau PHP à un paramètre de tableau Oracle PL/SQL
- oci_bind_by_name — Associe une variable PHP à un marqueur Oracle
- oci_cancel — Termine la lecture de curseurs Oracle
- oci_client_version — Retourne la version de la bibliothèque cliente Oracle
- oci_close — Ferme une connexion Oracle
- oci_commit — Valide les transactions Oracle en cours
- oci_connect — Établit une connexion avec un serveur Oracle
- oci_define_by_name — Associe une variable PHP avec une colonne pour une requête de récupération de données
- oci_error — Retourne la dernière erreur Oracle
- oci_execute — Exécute une commande SQL Oracle
- oci_fetch — Lit la prochaine ligne d'un résultat Oracle dans un buffer interne
- oci_fetch_all — Lit plusieurs lignes d'un résultat dans un tableau multidimensionnel
- oci_fetch_array — Lit une ligne d'un résultat sous forme de tableau associatif ou numérique
- oci_fetch_assoc — Lit une ligne d'un résultat sous forme de tableau associatif
- oci_fetch_object — Lit une ligne d'un résultat sous forme d'objet
- oci_fetch_row — Lit la prochaine ligne d'une requête sous forme de tableau numérique
- oci_field_is_null — Test si un champ de la ligne récupérée vaut null
- oci_field_name — Retourne le nom d'un champ Oracle
- oci_field_precision — Lit la précision d'un champ Oracle
- oci_field_scale — Lit l'échelle d'une colonne Oracle
- oci_field_size — Retourne la taille d'un champ Oracle
- oci_field_type — Retourne le type de données d'un champ Oracle
- oci_field_type_raw — Lit les données brutes du type d'un champ
- oci_free_descriptor — Libère un descripteur
- oci_free_statement — Libère toutes les ressources réservées par un résultat Oracle
- oci_get_implicit_resultset — Retourne le fils suivant d'une ressource de requête depuis une ressource de requête parent qui a un jeu de résultat implicite Oracle Database
- oci_lob_copy — Copie un LOB Oracle
- oci_lob_is_equal — Compare deux LOB/FILE Oracle
- oci_new_collection — Initialise une nouvelle collection Oracle
- oci_new_connect — Connexion au serveur Oracle en utilisant une seule connexion
- oci_new_cursor — Alloue et retourne un nouveau curseur Oracle
- oci_new_descriptor — Initialise un nouveau pointeur vide de LOB/FILE Oracle
- oci_num_fields — Retourne le nombre de colonnes dans un résultat Oracle
- oci_num_rows — Retourne le nombre de lignes affectées durant la dernière commande Oracle
- oci_parse — Prépare une requête SQL avec Oracle
- oci_password_change — Modifie le mot de passe d'un utilisateur Oracle
- oci_pconnect — Ouvre une connexion persistante à un serveur Oracle
- oci_register_taf_callback — Enregistre une fonction de rappel définie par l'utilisateur pour Oracle Database TAF
- oci_result — Retourne la valeur d'une colonne dans un résultat Oracle
- oci_rollback — Annule les transactions Oracle en cours
- oci_server_version — Retourne la version du serveur Oracle
- oci_set_action — Définit le nom de l'action
- oci_set_call_timeout — Définit un délai d'attente en millisecondes pour les appels de base de données
- oci_set_client_identifier — Définit l'identifiant du client
- oci_set_client_info — Définit l'information concernant le client
- oci_set_db_operation — Définit l'opération de base de données
- oci_set_edition — Définit l'édition de la base de données
- oci_set_module_name — Définit le nom du module
- oci_set_prefetch — Indique le nombre de lignes qui doivent être lues à l'avance par Oracle
- oci_set_prefetch_lob — Définit la quantité de données préchargées pour chaque CLOB ou BLOB.
- oci_statement_type — Retourne le type de la requête Oracle
- oci_unregister_taf_callback — Efface une fonction de rappel définie par l'utilisateur pour Oracle Database TAF

# La classe OCICollection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Introduction

Fonctionnalités des collections OCI8 Collection.

> Note:

> La classe OCI-Collection a été renommée en OCICollection dans PHP 8 OCI8 3.0.0 pour s'aligner sur les normes de nommage PHP.

## Synopsis de la classe

class OCICollection {
/* Méthodes */
public function append(string `$value`): bool
public function assign(OCICollection `$from`): bool
public function assignElem(int `$index`, string `$value`): bool
public function free(): bool
public function getElem(int `$index`): string|float|null|false
public function max(): int|false
public function size(): int|false
public function trim(int `$num`): bool
}

# OCICollection::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::append — Ajoute un élément à une collection Oracle

### Description

public function OCICollection::append(string `$value`): bool

Ajoute un élément à la fin d'une collection Oracle.

### Liste de paramètres

`value`

  La valeur à ajouter à la collection.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Collection a été renommée en OCICollection pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCICollection::assign

# OCICollection::assign

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assign — Assigne une valeur à une collection depuis une autre collection Oracle

### Description

public function OCICollection::assign(OCICollection `$from`): bool

Assigne une valeur à une collection, à partir de la collection `from`. Les deux collections doivent avoir été créées avec oci_new_collection() avant d'utiliser cette fonction.

### Liste de paramètres

`from`

  Une instance OCICollection.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Collection a été renommée en OCICollection pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCICollection::append

# OCICollection::assignElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assignElem — Assigne une valeur à un élément d'une collection Oracle

### Description

public function OCICollection::assignElem(int `$index`, string `$value`): bool

Assigne une valeur à l'élément dont l'index est `index`.

### Liste de paramètres

`index`

  L'index de l'élément. Le premier vaut 0.

`value`

  Peut être soit une chaîne de caractères, soit un nombre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Collection a été renommée en OCICollection pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCICollection::getElem

# OCICollection::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::free — Libère les ressources associées avec un objet de collection

### Description

public function OCICollection::free(): bool

Libère les ressources associées avec un objet de collection.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Collection a été renommée en OCICollection pour aligner avec les standards de nommage PHP.

### Voir aussi

- oci_new_collection

# OCICollection::getElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::getElem — Retourne la valeur d'un élément d'une collection Oracle

### Description

public function OCICollection::getElem(int `$index`): string|float|null|false

Retourne la valeur de l'élément à l'index `index` (en commençant à 0).

### Liste de paramètres

`index`

  L'index de l'élément. Le premier vaut 0.

### Valeurs de retour

Retournera `false` si cet élément n'existe pas; `null`, si l'élément est `null` chaîne si la colonne est de type chaîne, et nombre si c'est un champ numérique.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Collection a été renommée en OCICollection pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCICollection::assignElem

# OCICollection::max

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::max — Retourne le nombre maximal de valeurs d'une collection Oracle

### Description

public function OCICollection::max(): int|false

Retourne le nombre maximal de valeurs d'une collection Oracle.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre maximal, sous la forme d'un entier, ou `false` si une erreur survient.

Si la valeur retournée vaut 0, alors le nombre d'éléments n'est pas limité.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Collection a été renommée en OCICollection pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCICollection::size

# OCICollection::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::size — Retourne la taille d'une collection Oracle

### Description

public function OCICollection::size(): int|false

Retourne la taille d'une collection Oracle.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre d'éléments de la collection, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Collection a été renommée en OCICollection pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCICollection::max

# OCICollection::trim

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::trim — Supprime les derniers éléments d'une collection Oracle

### Description

public function OCICollection::trim(int `$num`): bool

Supprime les `num` derniers éléments d'une collection.

### Liste de paramètres

`num`

  Le nombre d'éléments à supprimer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Collection a été renommée en OCICollection pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCICollection::size

## Sommaire

- OCICollection::append — Ajoute un élément à une collection Oracle
- OCICollection::assign — Assigne une valeur à une collection depuis une autre collection Oracle
- OCICollection::assignElem — Assigne une valeur à un élément d'une collection Oracle
- OCICollection::free — Libère les ressources associées avec un objet de collection
- OCICollection::getElem — Retourne la valeur d'un élément d'une collection Oracle
- OCICollection::max — Retourne le nombre maximal de valeurs d'une collection Oracle
- OCICollection::size — Retourne la taille d'une collection Oracle
- OCICollection::trim — Supprime les derniers éléments d'une collection Oracle

# La classe OCILob

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Introduction

Fonctionnalité OCI8 LOB pour les objets de données binaire large (BLOB) et de caractères (CLOB).

> Note:

> La classe OCI-Lob a été renommée en OCILob dans PHP 8 et PECL OCI8 3.0.0 pour s'aligner sur les normes de nommage PHP.

## Synopsis de la classe

class OCILob {
/* Méthodes */
public function append(OCILob `$from`): bool
public function close(): bool
public function eof(): bool
public function erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false
public function export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool
public function flush(int `$flag` = 0): bool
public function free(): bool
public function getBuffering(): bool
public function import(string `$filename`): bool
public function load(): string|false
public function read(int `$length`): string|false
public function rewind(): bool
public function save(string `$data`, int `$offset` = 0): bool
public function seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool
public function setBuffering(bool `$mode`): bool
public function size(): int|false
public function tell(): int|false
public function truncate(int `$length` = 0): bool
public function write(string `$data`, ?int `$length` = `null`): int|false
public function writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool
}

# OCILob::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::append — Ajoute des données à un LOB Oracle

### Description

public function OCILob::append(OCILob `$from`): bool

Ajoute des données à un LOB Oracle.

L'écriture dans un LOB avec OCI-Lob->append() échouera si la bufferisation a été préalablement activée. Il faut désactiver la bufferisation avant d'ajouter des données. On aura peut-être à vider les buffers avec la fonction OCILob::flush avant de la désactiver.

### Liste de paramètres

`from`

  Le LOB copié.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::flush
- OCILob::setBuffering
- OCILob::getBuffering

# OCILob::close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::close — Ferme un LOB Oracle

### Description

public function OCILob::close(): bool

Ferme un LOB Oracle. Cette fonction doit être utilisée uniquement avec OCILob::writeTemporary.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::writeTemporary

# OCILob::eof

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::eof — Teste la fin du LOB Oracle

### Description

public function OCILob::eof(): bool

Vérifie si le pointeur interne d'un LOB est à la fin.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si le pointeur interne de LOB a atteint la fin du LOB, et `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Notes

> Note:

> Cette fonction retournera une erreur Oracle si OCILob::setBuffering est actif sur le LOB.

### Voir aussi

- OCILob::size

# OCILob::erase

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::erase — Écrase une partie d'un LOB Oracle

### Description

public function OCILob::erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false

Écrase la partie du LOB Oracle commençant à l'offset `offset`, sur la longueur de `length` octets.

Pour les BLOB, l'effacement signifie que la valeur existante du LOB est remplacée par le caractère 0. Pour les CLOB, ce sont des espaces.

### Liste de paramètres

`offset`

`length`

### Valeurs de retour

Retourne le nombre de caractères/octets effacés ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` et `length` sont désormais nullable.
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::truncate

# OCILob::export

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::export — Exporte un LOB Oracle dans un fichier

### Description

public function OCILob::export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool

Exporte un LOB Oracle dans un fichier.

### Liste de paramètres

`filename`

  Le chemin vers le fichier.

`offset`

  Indique la position à partir de laquelle l'on doit commencer à exporter.

`length`

  Indique la taille des données à exporter.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` et `length` sont désormais nullable.
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::import

# OCILob::flush

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::flush — Écrit les LOB Oracle sur le disque

### Description

public function OCILob::flush(int `$flag` = 0): bool

Écrit les LOB Oracle sur le disque.

### Liste de paramètres

`flag`

  Par défaut, les ressources ne sont pas libérées, mais en utilisant l'option `flag` avec la valeur `OCI_LOB_BUFFER_FREE`, il est possible de le faire explicitement. Il faut s'assurer de bien savoir ce qu'on fait : la prochaine lecture ou écriture dans le même LOB demandera alors une requête au serveur, et la réinitialisation des ressources. Il est recommandé d'utiliser l'option `OCI_LOB_BUFFER_FREE` uniquement si l'on n'a plus besoin du LOB.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Retourne `false` si la bufferisation n'a pas été activée, ou si une erreur est survenue.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::getBuffering
- OCILob::setBuffering

# OCILob::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::free — Détruit un pointeur de LOB Oracle

### Description

public function OCILob::free(): bool

Libère les ressources associées avec la ressource, précédemment allouée avec oci_new_descriptor().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

# OCILob::getBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::getBuffering — Retourne l'état de bufferisation LOB d'Oracle

### Description

public function OCILob::getBuffering(): bool

Retourne l'état de bufferisation LOB d'Oracle.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `false` si la bufferisation des LOB est désactivée, et `true` si elle l'est.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::setBuffering

# OCILob::import

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::import — Importe un fichier dans LOB Oracle

### Description

public function OCILob::import(string `$filename`): bool

Écrit les données du fichier `filename` dans le LOB, à partir de la position courante.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::export
- OCILob::write

# OCILob::load

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::load — Retourne le contenu d'un LOB

### Description

public function OCILob::load(): string|false

Lit le contenu d'un LOB Oracle. Le script peut être interrompu à cause de memory_limit, si ce dernier dépasse la limite. Dans la plupart des cas, il est recommandé d'utiliser la fonction OCILob::read à la place. En cas d'erreur, OCI-Lob->load() retourne `false`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le contenu de l'objet, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::read

# OCILob::read

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::read — Lit une partie d'un LOB Oracle

### Description

public function OCILob::read(int `$length`): string|false

Lit `length` octets (BLOB) ou caractères (CLOB) à partir de la position courante du LOB.

La lecture stoppe lorsque `length` octets ont été lus pour un BLOB, lorsque `length` caractères ont été lus pour un CLOB, ou que la fin du LOB a été atteinte. Le pointeur de LOB sera déplacé par cette lecture du nombre d'octets/caractères lus.

### Liste de paramètres

`length`

  La taille des données à lire, en octets pour un BLOB, en caractères pour un CLOB. Les grosses valeurs seront ramenées à 1 Mo.

### Valeurs de retour

Retourne le contenu, sous la forme d'une chaîne de caractères ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::load
- OCILob::write

# OCILob::rewind

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::rewind — Ramène le pointeur interne d'un LOB Oracle au début

### Description

public function OCILob::rewind(): bool

Ramène le pointeur interne d'un LOB Oracle au début.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::seek
- OCILob::tell

# OCILob::save

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::save — Sauvegarde des données dans un LOB Oracle

### Description

public function OCILob::save(string `$data`, int `$offset` = 0): bool

Sauvegarde des données dans un LOB Oracle.

### Liste de paramètres

`data`

  Les données à sauvegarder.

`offset`

  Peut être utilisé pour indiquer la position depuis le début du LOB.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::write
- OCILob::import

# OCILob::saveFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::saveFile — Alias de OCILob::import()

### Description

Cette fonction est un alias de : OCILob::import().

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

# OCILob::seek

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::seek — Déplace le pointeur interne d'un LOB Oracle

### Description

public function OCILob::seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool

Déplace le pointeur interne d'un LOB Oracle.

### Liste de paramètres

`offset`

  Indique la distance de déplacement. Le type de déplacement est spécifié avec `whence`.

`whence`

  Peut être une constante parmi :

  - `OCI_SEEK_SET` - déplace le pointeur à la position `offset`.
  - `OCI_SEEK_CUR` - ajoute `offset` octets à la position courante.
  - `OCI_SEEK_END` - ajoute `offset` octets à la fin du LOB (utiliser une valeur négative pour obtenir une position avant la fin du LOB).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::rewind
- OCILob::tell
- OCILob::eof

# OCILob::setBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::setBuffering — Active/désactive la bufferisation des LOB Oracle

### Description

public function OCILob::setBuffering(bool `$mode`): bool

Active ou désactive la bufferisation des LOB Oracle, en fonction du paramètre `mode`.

Utiliser cette fonction apporte des améliorations de performances par bufferisation des petites lectures et écritures de LOB : le buffer limite les allers/retours avec le serveur. OCILob::flush() doit être utilisé pour vider les buffers une fois qu'on a fini de travailler avec le LOB.

### Liste de paramètres

`mode`

  `true` pour l'activer, et `false` pour la désactiver.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient. Des appels répétés à lob->setbuffering() avec la même valeur de paramètre renverra toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::getBuffering

# OCILob::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::size — Retourne la taille d'un LOB Oracle

### Description

public function OCILob::size(): int|false

Retourne la taille d'un LOB Oracle.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la taille du LOB ou `false` si une erreur survient. Les objets vides ont une taille de 0.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

# OCILob::tell

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::tell — Retourne la position courante du pointeur de LOB

### Description

public function OCILob::tell(): int|false

Retourne la position courante du pointeur de LOB.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la position courante du pointeur interne du LOB, ou bien `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::rewind
- OCILob::size
- OCILob::eof

# OCILob::truncate

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::truncate — Tronque un LOB Oracle

### Description

public function OCILob::truncate(int `$length` = 0): bool

Tronque un LOB Oracle.

### Liste de paramètres

`length`

  Si `length` est fourni, OCI-Lob->truncate() tronque le LOB à `length` octets. Sinon, OCI-Lob->truncate() va purger complètement le LOB.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::erase

# OCILob::write

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::write — Écrit des données dans un LOB Oracle

### Description

public function OCILob::write(string `$data`, ?int `$length` = `null`): int|false

Écrit les données de la variable `data` à la position courante du LOB.

### Liste de paramètres

`data`

  Les données à écrire dans le LOB.

`length`

  Si ce paramètre est un entier, l'écriture s'arrêtera après `length` octets, ou à la fin de la variable `data`.

### Valeurs de retour

Retourne le nombre d'octets écrits ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` est désormais nullable.
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::read

# OCILob::writeTemporary

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeTemporary — Écrit un LOB Oracle temporaire

### Description

public function OCILob::writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool

Crée un LOB temporaire et y écrit les données `data`.

Il faut utiliser la fonction OCILob::close lorsqu'on a fini de travailler avec le LOB.

### Liste de paramètres

`data`

  Les données à écrire.

`type`

  Peut prendre l'une des valeurs suivantes :

  - `OCI_TEMP_BLOB` sert à créer un BLOB temporaire.
  - `OCI_TEMP_CLOB` sert à créer un CLOB temporaire.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

### Voir aussi

- OCILob::close

# OCILob::writeToFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeToFile — Alias de OCILob::export()

### Description

Cette fonction est un alias de : OCILob::export().

### Historique

Version | Description
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` et `length` sont désormais nullable.
8.0.0, PECL OCI8 3.0.0 | La classe OCI-Lob a été renommée en OCILob pour aligner avec les standards de nommage PHP.

## Sommaire

- OCILob::append — Ajoute des données à un LOB Oracle
- OCILob::close — Ferme un LOB Oracle
- OCILob::eof — Teste la fin du LOB Oracle
- OCILob::erase — Écrase une partie d'un LOB Oracle
- OCILob::export — Exporte un LOB Oracle dans un fichier
- OCILob::flush — Écrit les LOB Oracle sur le disque
- OCILob::free — Détruit un pointeur de LOB Oracle
- OCILob::getBuffering — Retourne l'état de bufferisation LOB d'Oracle
- OCILob::import — Importe un fichier dans LOB Oracle
- OCILob::load — Retourne le contenu d'un LOB
- OCILob::read — Lit une partie d'un LOB Oracle
- OCILob::rewind — Ramène le pointeur interne d'un LOB Oracle au début
- OCILob::save — Sauvegarde des données dans un LOB Oracle
- OCILob::saveFile — Alias de OCILob::import
- OCILob::seek — Déplace le pointeur interne d'un LOB Oracle
- OCILob::setBuffering — Active/désactive la bufferisation des LOB Oracle
- OCILob::size — Retourne la taille d'un LOB Oracle
- OCILob::tell — Retourne la position courante du pointeur de LOB
- OCILob::truncate — Tronque un LOB Oracle
- OCILob::write — Écrit des données dans un LOB Oracle
- OCILob::writeTemporary — Écrit un LOB Oracle temporaire
- OCILob::writeToFile — Alias de OCILob::export

# Fonctions et alias OCI8 obsolètes

# oci_internal_debug

(PHP 5, PHP 7, PECL OCI8 >= 1.1.0, PECL OCI8 <= 2.2.0)

oci_internal_debug — Active ou désactive la sortie de débogage interne

### Description

function oci_internal_debug(bool `$onoff`): void

Active ou désactive la sortie de débogage interne.

### Liste de paramètres

`onoff`

  Définit cette valeur à `false` pour désactiver la sortie de débogage ou à `true` pour l'activer.

### Valeurs de retour

Aucune valeur n'est retournée.

### Notes

> Note:

> Cette fonction a été supprimée en PHP 8 et PECL OCI8 3.0.

# ocibindbyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocibindbyname — Alias de oci_bind_by_name()

### Description

Alias de oci_bind_by_name()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicancel

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicancel — Alias de oci_cancel()

### Description

Alias de oci_cancel()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicloselob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ocicloselob — Alias de OCILob::close()

### Description

Alias de OCILob::close()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicollappend

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollappend — Alias de OCICollection::append()

### Description

Alias de OCICollection::append()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicollassign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 >= 1.0.0)

ocicollassign — Alias de OCICollection::assign()

### Description

Alias de OCICollection::assign()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicollassignelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollassignelem — Alias de OCICollection::assignElem()

### Description

Alias de OCICollection::assignElem()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicollgetelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollgetelem — Alias de OCICollection::getElem()

### Description

Alias de OCICollection::getElem()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicollmax

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollmax — Alias de OCICollection::max()

### Description

Alias de OCICollection::max()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicollsize

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollsize — Alias de OCICollection::size()

### Description

Alias de OCICollection::size()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicolltrim

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolltrim — Alias de OCICollection::trim()

### Description

Alias de OCICollection::trim()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicolumnisnull

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnisnull — Alias de oci_field_is_null()

### Description

Alias de oci_field_is_null()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicolumnname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnname — Alias de oci_field_name()

### Description

Alias de oci_field_name()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicolumnprecision

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnprecision — Alias de oci_field_precision()

### Description

Alias de oci_field_precision()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicolumnscale

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnscale — Alias de oci_field_scale()

### Description

Alias de oci_field_scale()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicolumnsize

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnsize — Alias de oci_field_size()

### Description

Alias de oci_field_size()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicolumntype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntype — Alias de oci_field_type()

### Description

Alias de oci_field_type()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicolumntyperaw

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntyperaw — Alias de oci_field_type_raw()

### Description

Alias de oci_field_type_raw()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocicommit

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicommit — Alias de oci_commit()

### Description

Alias de oci_commit()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocidefinebyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocidefinebyname — Alias de oci_define_by_name()

### Description

Alias de oci_define_by_name()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocierror

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocierror — Alias de oci_error()

### Description

Alias de oci_error()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ociexecute

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociexecute — Alias de oci_execute()

### Description

Alias de oci_execute()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocifetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetch — Alias de oci_fetch()

### Description

Alias de oci_fetch()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocifetchinto

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchinto — Variante obsolète de la fonction oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() et oci_fetch_row()

### Description

Variante obsolète de oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() et oci_fetch_row()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocifetchstatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchstatement — Alias de oci_fetch_all()

### Description

Alias de oci_fetch_all()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocifreecollection

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecollection — Alias de OCICollection::free()

### Description

Alias de OCICollection::free()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocifreecursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecursor — Alias de oci_free_statement()

### Description

Alias de oci_free_statement()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocifreedesc

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreedesc — Alias de OCILob::free()

### Description

Alias de OCILob::free()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocifreestatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreestatement — Alias de oci_free_statement()

### Description

Alias de oci_free_statement()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ociinternaldebug

(PHP 4, PHP 5, PHP 7, PECL OCI8 >= 1.0.0, PECL OCI8 <= 2.2.0)

ociinternaldebug — Alias de oci_internal_debug()

### Description

Alias de oci_internal_debug()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ociloadlob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociloadlob — Alias de OCILob::load()

### Description

Alias de OCILob::load()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocilogoff

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogoff — Alias de oci_close()

### Description

Alias de oci_close()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocilogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogon — Alias de oci_connect()

### Description

Alias de oci_connect()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocinewcollection

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcollection — Alias de oci_new_collection()

### Description

Alias de oci_new_collection()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocinewcursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcursor — Alias de oci_new_cursor()

### Description

Alias de oci_new_cursor()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocinewdescriptor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewdescriptor — Alias de oci_new_descriptor()

### Description

Alias de oci_new_descriptor()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocinlogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinlogon — Alias de oci_new_connect()

### Description

Alias de oci_new_connect()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocinumcols

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinumcols — Alias de oci_num_fields()

### Description

Alias de oci_num_fields()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ociparse

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociparse — Alias de oci_parse()

### Description

Alias de oci_parse()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ociplogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociplogon — Alias de oci_pconnect()

### Description

Alias de oci_pconnect()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ociresult

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociresult — Alias de oci_result()

### Description

Alias de oci_result()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocirollback

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirollback — Alias de oci_rollback()

### Description

Alias de oci_rollback()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocirowcount

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirowcount — Alias de oci_num_rows()

### Description

Alias de oci_num_rows()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocisavelob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelob — Alias de OCILob::save()

### Description

Alias de OCILob::save()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocisavelobfile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelobfile — Alias de OCILob::import()

### Description

Alias de OCILob::import()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ociserverversion

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociserverversion — Alias de oci_server_version()

### Description

Alias de oci_server_version()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocisetprefetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisetprefetch — Alias de oci_set_prefetch()

### Description

Alias de oci_set_prefetch()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ocistatementtype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocistatementtype — Alias de oci_statement_type()

### Description

Alias de oci_statement_type()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ociwritelobtofile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociwritelobtofile — Alias de OCILob::export()

### Description

Alias de OCILob::export()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

# ociwritetemporarylob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ociwritetemporarylob — Alias de OCILob::writeTemporary()

### Description

Alias de OCILob::writeTemporary()

Avertissement

Cet alias est OBSOLÈTE à partir de PHP 5.4.0. Dépendre de cet alias est fortement déconseillé.

## Sommaire

- oci_internal_debug — Active ou désactive la sortie de débogage interne
- ocibindbyname — Alias de oci_bind_by_name
- ocicancel — Alias de oci_cancel
- ocicloselob — Alias de OCILob::close
- ocicollappend — Alias de OCICollection::append
- ocicollassign — Alias de OCICollection::assign
- ocicollassignelem — Alias de OCICollection::assignElem
- ocicollgetelem — Alias de OCICollection::getElem
- ocicollmax — Alias de OCICollection::max
- ocicollsize — Alias de OCICollection::size
- ocicolltrim — Alias de OCICollection::trim
- ocicolumnisnull — Alias de oci_field_is_null
- ocicolumnname — Alias de oci_field_name
- ocicolumnprecision — Alias de oci_field_precision
- ocicolumnscale — Alias de oci_field_scale
- ocicolumnsize — Alias de oci_field_size
- ocicolumntype — Alias de oci_field_type
- ocicolumntyperaw — Alias de oci_field_type_raw
- ocicommit — Alias de oci_commit
- ocidefinebyname — Alias de oci_define_by_name
- ocierror — Alias de oci_error
- ociexecute — Alias de oci_execute
- ocifetch — Alias de oci_fetch
- ocifetchinto — Variante obsolète de la fonction oci_fetch_array, oci_fetch_object, oci_fetch_assoc et oci_fetch_row
- ocifetchstatement — Alias de oci_fetch_all
- ocifreecollection — Alias de OCICollection::free
- ocifreecursor — Alias de oci_free_statement
- ocifreedesc — Alias de OCILob::free
- ocifreestatement — Alias de oci_free_statement
- ociinternaldebug — Alias de oci_internal_debug
- ociloadlob — Alias de OCILob::load
- ocilogoff — Alias de oci_close
- ocilogon — Alias de oci_connect
- ocinewcollection — Alias de oci_new_collection
- ocinewcursor — Alias de oci_new_cursor
- ocinewdescriptor — Alias de oci_new_descriptor
- ocinlogon — Alias de oci_new_connect
- ocinumcols — Alias de oci_num_fields
- ociparse — Alias de oci_parse
- ociplogon — Alias de oci_pconnect
- ociresult — Alias de oci_result
- ocirollback — Alias de oci_rollback
- ocirowcount — Alias de oci_num_rows
- ocisavelob — Alias de OCILob::save
- ocisavelobfile — Alias de OCILob::import
- ociserverversion — Alias de oci_server_version
- ocisetprefetch — Alias de oci_set_prefetch
- ocistatementtype — Alias de oci_statement_type
- ociwritelobtofile — Alias de OCILob::export
- ociwritetemporarylob — Alias de OCILob::writeTemporary

- Installation/Configuration
  - Pré-requis
  - Installation
  - Test
  - Configuration à l'exécution
- Constantes pré-définies
- Exemples
- Gestion de la connexion OCI8 et de la mise en file d'attente
- Support de FAN (Fast Application Notification : Application de notification Rapide) OCI8
- Le support de la reprise transparente d'application (TAF) d'OCI8
- OCI8 et le suivi dynamique DTrace
- Types de données supportés par le pilote
- Fonctions OCI8
  - oci_bind_array_by_name — Lie un tableau PHP à un paramètre de tableau Oracle PL/SQL
  - oci_bind_by_name — Associe une variable PHP à un marqueur Oracle
  - oci_cancel — Termine la lecture de curseurs Oracle
  - oci_client_version — Retourne la version de la bibliothèque cliente Oracle
  - oci_close — Ferme une connexion Oracle
  - oci_commit — Valide les transactions Oracle en cours
  - oci_connect — Établit une connexion avec un serveur Oracle
  - oci_define_by_name — Associe une variable PHP avec une colonne pour une requête de récupération de données
  - oci_error — Retourne la dernière erreur Oracle
  - oci_execute — Exécute une commande SQL Oracle
  - oci_fetch — Lit la prochaine ligne d'un résultat Oracle dans un buffer interne
  - oci_fetch_all — Lit plusieurs lignes d'un résultat dans un tableau multidimensionnel
  - oci_fetch_array — Lit une ligne d'un résultat sous forme de tableau associatif ou numérique
  - oci_fetch_assoc — Lit une ligne d'un résultat sous forme de tableau associatif
  - oci_fetch_object — Lit une ligne d'un résultat sous forme d'objet
  - oci_fetch_row — Lit la prochaine ligne d'une requête sous forme de tableau numérique
  - oci_field_is_null — Test si un champ de la ligne récupérée vaut null
  - oci_field_name — Retourne le nom d'un champ Oracle
  - oci_field_precision — Lit la précision d'un champ Oracle
  - oci_field_scale — Lit l'échelle d'une colonne Oracle
  - oci_field_size — Retourne la taille d'un champ Oracle
  - oci_field_type — Retourne le type de données d'un champ Oracle
  - oci_field_type_raw — Lit les données brutes du type d'un champ
  - oci_free_descriptor — Libère un descripteur
  - oci_free_statement — Libère toutes les ressources réservées par un résultat Oracle
  - oci_get_implicit_resultset — Retourne le fils suivant d'une ressource de requête depuis une ressource de requête parent qui a un jeu de résultat implicite Oracle Database
  - oci_lob_copy — Copie un LOB Oracle
  - oci_lob_is_equal — Compare deux LOB/FILE Oracle
  - oci_new_collection — Initialise une nouvelle collection Oracle
  - oci_new_connect — Connexion au serveur Oracle en utilisant une seule connexion
  - oci_new_cursor — Alloue et retourne un nouveau curseur Oracle
  - oci_new_descriptor — Initialise un nouveau pointeur vide de LOB/FILE Oracle
  - oci_num_fields — Retourne le nombre de colonnes dans un résultat Oracle
  - oci_num_rows — Retourne le nombre de lignes affectées durant la dernière commande Oracle
  - oci_parse — Prépare une requête SQL avec Oracle
  - oci_password_change — Modifie le mot de passe d'un utilisateur Oracle
  - oci_pconnect — Ouvre une connexion persistante à un serveur Oracle
  - oci_register_taf_callback — Enregistre une fonction de rappel définie par l'utilisateur pour Oracle Database TAF
  - oci_result — Retourne la valeur d'une colonne dans un résultat Oracle
  - oci_rollback — Annule les transactions Oracle en cours
  - oci_server_version — Retourne la version du serveur Oracle
  - oci_set_action — Définit le nom de l'action
  - oci_set_call_timeout — Définit un délai d'attente en millisecondes pour les appels de base de données
  - oci_set_client_identifier — Définit l'identifiant du client
  - oci_set_client_info — Définit l'information concernant le client
  - oci_set_db_operation — Définit l'opération de base de données
  - oci_set_edition — Définit l'édition de la base de données
  - oci_set_module_name — Définit le nom du module
  - oci_set_prefetch — Indique le nombre de lignes qui doivent être lues à l'avance par Oracle
  - oci_set_prefetch_lob — Définit la quantité de données préchargées pour chaque CLOB ou BLOB.
  - oci_statement_type — Retourne le type de la requête Oracle
  - oci_unregister_taf_callback — Efface une fonction de rappel définie par l'utilisateur pour Oracle Database TAF
- OCICollection — La classe OCICollection
  - OCICollection::append — Ajoute un élément à une collection Oracle
  - OCICollection::assign — Assigne une valeur à une collection depuis une autre collection Oracle
  - OCICollection::assignElem — Assigne une valeur à un élément d'une collection Oracle
  - OCICollection::free — Libère les ressources associées avec un objet de collection
  - OCICollection::getElem — Retourne la valeur d'un élément d'une collection Oracle
  - OCICollection::max — Retourne le nombre maximal de valeurs d'une collection Oracle
  - OCICollection::size — Retourne la taille d'une collection Oracle
  - OCICollection::trim — Supprime les derniers éléments d'une collection Oracle
- OCILob — La classe OCILob
  - OCILob::append — Ajoute des données à un LOB Oracle
  - OCILob::close — Ferme un LOB Oracle
  - OCILob::eof — Teste la fin du LOB Oracle
  - OCILob::erase — Écrase une partie d'un LOB Oracle
  - OCILob::export — Exporte un LOB Oracle dans un fichier
  - OCILob::flush — Écrit les LOB Oracle sur le disque
  - OCILob::free — Détruit un pointeur de LOB Oracle
  - OCILob::getBuffering — Retourne l'état de bufferisation LOB d'Oracle
  - OCILob::import — Importe un fichier dans LOB Oracle
  - OCILob::load — Retourne le contenu d'un LOB
  - OCILob::read — Lit une partie d'un LOB Oracle
  - OCILob::rewind — Ramène le pointeur interne d'un LOB Oracle au début
  - OCILob::save — Sauvegarde des données dans un LOB Oracle
  - OCILob::saveFile — Alias de OCILob::import
  - OCILob::seek — Déplace le pointeur interne d'un LOB Oracle
  - OCILob::setBuffering — Active/désactive la bufferisation des LOB Oracle
  - OCILob::size — Retourne la taille d'un LOB Oracle
  - OCILob::tell — Retourne la position courante du pointeur de LOB
  - OCILob::truncate — Tronque un LOB Oracle
  - OCILob::write — Écrit des données dans un LOB Oracle
  - OCILob::writeTemporary — Écrit un LOB Oracle temporaire
  - OCILob::writeToFile — Alias de OCILob::export
- Fonctions et alias OCI8 obsolètes
  - oci_internal_debug — Active ou désactive la sortie de débogage interne
  - ocibindbyname — Alias de oci_bind_by_name
  - ocicancel — Alias de oci_cancel
  - ocicloselob — Alias de OCILob::close
  - ocicollappend — Alias de OCICollection::append
  - ocicollassign — Alias de OCICollection::assign
  - ocicollassignelem — Alias de OCICollection::assignElem
  - ocicollgetelem — Alias de OCICollection::getElem
  - ocicollmax — Alias de OCICollection::max
  - ocicollsize — Alias de OCICollection::size
  - ocicolltrim — Alias de OCICollection::trim
  - ocicolumnisnull — Alias de oci_field_is_null
  - ocicolumnname — Alias de oci_field_name
  - ocicolumnprecision — Alias de oci_field_precision
  - ocicolumnscale — Alias de oci_field_scale
  - ocicolumnsize — Alias de oci_field_size
  - ocicolumntype — Alias de oci_field_type
  - ocicolumntyperaw — Alias de oci_field_type_raw
  - ocicommit — Alias de oci_commit
  - ocidefinebyname — Alias de oci_define_by_name
  - ocierror — Alias de oci_error
  - ociexecute — Alias de oci_execute
  - ocifetch — Alias de oci_fetch
  - ocifetchinto — Variante obsolète de la fonction oci_fetch_array, oci_fetch_object, oci_fetch_assoc et oci_fetch_row
  - ocifetchstatement — Alias de oci_fetch_all
  - ocifreecollection — Alias de OCICollection::free
  - ocifreecursor — Alias de oci_free_statement
  - ocifreedesc — Alias de OCILob::free
  - ocifreestatement — Alias de oci_free_statement
  - ociinternaldebug — Alias de oci_internal_debug
  - ociloadlob — Alias de OCILob::load
  - ocilogoff — Alias de oci_close
  - ocilogon — Alias de oci_connect
  - ocinewcollection — Alias de oci_new_collection
  - ocinewcursor — Alias de oci_new_cursor
  - ocinewdescriptor — Alias de oci_new_descriptor
  - ocinlogon — Alias de oci_new_connect
  - ocinumcols — Alias de oci_num_fields
  - ociparse — Alias de oci_parse
  - ociplogon — Alias de oci_pconnect
  - ociresult — Alias de oci_result
  - ocirollback — Alias de oci_rollback
  - ocirowcount — Alias de oci_num_rows
  - ocisavelob — Alias de OCILob::save
  - ocisavelobfile — Alias de OCILob::import
  - ociserverversion — Alias de oci_server_version
  - ocisetprefetch — Alias de oci_set_prefetch
  - ocistatementtype — Alias de oci_statement_type
  - ociwritelobtofile — Alias de OCILob::export
  - ociwritetemporarylob — Alias de OCILob::writeTemporary

# PostgreSQL

# Introduction

La base de données PostgreSQL est un produit Open Source, disponible sans frais. PostgreSQL, développé au département de Science informatique, à UC Berkeley, a été le pionnier de nombreux concepts objet-relationnels actuellement disponibles sur le marché. PostgreSQL accepte le langage SQL92/SQL99, assure l'intégrité transactionnelle, l'intégrité référentielle, les procédures stockées et l'extension de type. PostgreSQL est une évolution du code original de Berkeley.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Pour accéder au support PostgreSQL, la bibliothèque libpq (la bibliothèque cliente PostgreSQL C) est nécessaire. À partir de PHP 8.0.0, libpq 9.1 ou ultérieure est requise. À partir de PHP 8.4.0, libpq 10.0 ou ultérieure est requise. PostgreSQL supporte de nombreux jeux de caractères, y compris les jeux multioctets asiatiques. La version courante et plus de détails sur PostgreSQL sont accessibles sur le site » http://www.postgresql.org/ et la » Documentation PostgreSQL.

## Installation

Afin d'activer le support PostgreSQL, l'option --with-pgsql[=DIR] est nécessaire lors de la compilation de PHP. `DIR` est le chemin du dossier d'installation de PostgreSQL, et par défaut il vaut /usr/local/pgsql. Si le module de chargement dynamique est disponible, le module PostgreSQL peut être chargé avec la directive extension du fichier php.ini ou via la fonction dl().

## Configuration à l'exécution

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

Options de configuration PostgreSQL
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
pgsql.allow_persistent | "1" | `INI_SYSTEM` |
pgsql.max_persistent | "-1" | `INI_SYSTEM` |
pgsql.max_links | "-1" | `INI_SYSTEM` |
pgsql.auto_reset_persistent | "0" | `INI_SYSTEM` |
pgsql.ignore_notice | "0" | `INI_ALL` |
pgsql.log_notice | "0" | `INI_ALL` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`pgsql.allow_persistent` bool

  Autorise ou non les connexions persistantes PostgreSQL.

`pgsql.max_persistent` int

  Le nombre maximum de connexions persistantes Postgres par processus.

`pgsql.max_links` int

  Le nombre maximum de connexions Postgres par processus, y compris les connexions persistantes.

`pgsql.auto_reset_persistent` int

  Détecte les connexions persistantes (ouvertes avec pg_pconnect()) rompues.

`pgsql.ignore_notice` int

  Active ou non l'affichage des notices PostgreSQL.

`pgsql.log_notice` int

  Active ou non l'enregistrement en fichier log des messages notices PostgreSQL. La directive PHP pgsql.ignore_notice doit être désactivée pour pouvoir enregistrer les messages de notices en fichier log.

## Types de ressources

Antérieur à PHP 8.1.0, il y avait deux types de ressources utilisés dans le module PostgreSQL. Le premier est l'identifiant pour la connexion à la base de données et le second est une ressource qui contient le résultat d'une requête.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`PGSQL_LIBPQ_VERSION` (string)
  Version courte de libpq qui ne contient que des nombres et des points.
`PGSQL_LIBPQ_VERSION_STR` (string)
  Antérieur à PHP 8.0.0, la version longue de libpq qui inclut les informations du compilateur. À partir de PHP 8.0.0, la valeur est identique à `PGSQL_LIBPQ_VERSION`, et l'utilisation de `PGSQL_LIBPQ_VERSION_STR` est obsolète.
`PGSQL_ASSOC` (int)
  Passée à pg_fetch_array(). Retourne un tableau associatif des noms et valeurs des champs.
`PGSQL_NUM` (int)
  Passée à pg_fetch_array(). Retourne un tableau à index numérique des numéros et valeurs des champs.
`PGSQL_BOTH` (int)
  Passée à pg_fetch_array(). Retourne un tableau des valeurs des champs qui est indexé numériquement (par le numéro des champs) et indexé littéralement (par le nom des champs).
`PGSQL_CONNECT_FORCE_NEW` (int)
  Passée à pg_connect() pour forcer la création d'une nouvelle connexion, plutôt que de réutiliser une connexion identique existante.
`PGSQL_CONNECT_ASYNC` (int)
  Passé à la fonction pg_connect() pour créer une connexion asynchrone.
`PGSQL_CONNECTION_AUTH_OK` (int)
`PGSQL_CONNECTION_AWAITING_RESPONSE` (int)
`PGSQL_CONNECTION_BAD` (int)
  Retournée par pg_connection_status() indiquant que la connexion à la base de données est invalide.
`PGSQL_CONNECTION_MADE` (int)
`PGSQL_CONNECTION_OK` (int)
  Retournée par pg_connection_status() indiquant que la connexion à la base de données est valide.
`PGSQL_CONNECTION_SETENV` (int)
`PGSQL_CONNECTION_SSL_STARTUP` (int)
`PGSQL_CONNECTION_STARTED` (int)
`PGSQL_SEEK_SET` (int)
  Passée à pg_lo_seek(). Le positionnement commencera au début de l'objet.
`PGSQL_SEEK_CUR` (int)
  Passée à pg_lo_seek(). Le positionnement commencera à la position courante.
`PGSQL_SEEK_END` (int)
  Passée à pg_lo_seek(). Le positionnement commencera à la fin de l'objet.
`PGSQL_EMPTY_QUERY` (int)
  Retournée par pg_result_status(). La chaîne de caractères envoyée au serveur était vide.
`PGSQL_COMMAND_OK` (int)
  Retournée par pg_result_status(). Commande correctement complétée ne retournant aucune donnée.
`PGSQL_TUPLES_OK` (int)
  Retournée par pg_result_status(). Commande correctement complétée retournant des données (comme `SELECT` ou `SHOW`).
`PGSQL_TUPLES_CHUNK` (int)
  Retourné par pg_result_status(). Indique la réussite de l'exécution d'une commande retournant des données en mode par blocs. Retourné pour les commandes `SELECT` lorsque pg_set_chunked_rows_size() est défini. L'ensemble des résultats est divisé en plusieurs blocs, chacun contenant un nombre prédéfini de lignes. Disponible à partir de PHP 8.4.0 et libpq 17.
`PGSQL_COPY_OUT` (int)
  Retournée par pg_result_status(). Copie (à partir du serveur) de transfert de données commencée.
`PGSQL_COPY_IN` (int)
  Retournée par pg_result_status(). Copie (vers le serveur) de transfert de données commencée.
`PGSQL_BAD_RESPONSE` (int)
  Retournée par pg_result_status(). La réponse du serveur n'a pas été comprise.
`PGSQL_NONFATAL_ERROR` (int)
  Retournée par pg_result_status(). Une erreur non fatale (de niveau notice ou warning) s'est produite.
`PGSQL_FATAL_ERROR` (int)
  Retournée par pg_result_status(). Une erreur fatale s'est produite.
`PGSQL_TRANSACTION_IDLE` (int)
  Retournée par pg_transaction_status(). La connexion est actuellement libre, aucune transaction en cours.
`PGSQL_TRANSACTION_ACTIVE` (int)
  Retournée par pg_transaction_status(). Une commande est en cours sur la connexion. Une requête a été envoyée sur la connexion et n'a toujours pas été complétée.
`PGSQL_TRANSACTION_INTRANS` (int)
  Retournée par pg_transaction_status(). La connexion est libre, dans un bloc de transaction.
`PGSQL_TRANSACTION_INERROR` (int)
  Retournée par pg_transaction_status(). La connexion est libre, dans un bloc de transaction échoué.
`PGSQL_TRANSACTION_UNKNOWN` (int)
  Retournée par pg_transaction_status(). La connexion est mauvaise.
`PGSQL_DIAG_SEVERITY` (int)
  Passée à pg_result_error_field(). La sévérité; le contenu du champ est `ERROR`, `FATAL` ou `PANIC` (dans un message d'erreur) ou `WARNING`, `NOTICE`, `DEBUG`, `INFO` ou `LOG` (dans un message d'avertissement) ou une traduction localisée parmi celles-ci. Toujours présent.
`PGSQL_DIAG_SQLSTATE` (int)
  Passée à pg_result_error_field(). Le code SQLSTATE pour cette erreur. Le code SQLSTATE identifie le type d'erreur qui s'est produite; cela peut être utilisé par des applications d'entrée pour effectuer des opérations spécifiques (comme la gestion d'erreur) en réponse à une erreur de base de données particulière. Ce champ ne peut être localisé et est toujours présent.
`PGSQL_DIAG_MESSAGE_PRIMARY` (int)
  Passée à pg_result_error_field(). Le champ d'erreur primaire interprétable pour l'utilisateur (normalement une ligne). Toujours présent.
`PGSQL_DIAG_MESSAGE_DETAIL` (int)
  Passée à pg_result_error_field(). Détail : un second message d'erreur optionnel apportant plus de détails à propos du problème. Peut être sur plusieurs lignes.
`PGSQL_DIAG_MESSAGE_HINT` (int)
  Passée à pg_result_error_field(). Conseil : une suggestion optionnelle qui indique que faire à propos du problème. Ceci est prévu d'être différent de l'erreur puisqu'elle offre un conseil (potentiellement inadéquat) plutôt que les faits véridiques. Peut être sur plusieurs lignes.
`PGSQL_DIAG_STATEMENT_POSITION` (int)
  Passée à pg_result_error_field(). Une chaîne de caractères contenant une valeur entière décimale indiquant une erreur de position du curseur en tant qu'index dans la requête originale. Le premier caractère a l'index 1 et les positions sont mesurées en caractères, non en octets.
`PGSQL_DIAG_INTERNAL_POSITION` (int)
  Passée à pg_result_error_field(). Ceci est défini étant la même chose que le champ `PG_DIAG_STATEMENT_POSITION`, mais cela est utilisé lorsque la position du curseur réfère à une commande générée internement plutôt que d'une envoyée par le client. Le champ `PG_DIAG_INTERNAL_QUERY` apparaîtra toujours lorsque ce champ apparaît.
`PGSQL_DIAG_INTERNAL_QUERY` (int)
  Passée à pg_result_error_field(). Le texte d'une commande générée internement échouée. Cela peut être, par exemple, une requête SQL envoyée par une fonction PL/pgSQL.
`PGSQL_DIAG_CONTEXT` (int)
  Passée à pg_result_error_field(). Une indication du contexte dans lequel l'erreur s'est produite. Présentement, ceci inclut une pile d'appel des traceback des fonctions procédurales actives ainsi que des requêtes générées à l'interne. Le traçage est une entrée par ligne, les plus récentes en premier.
`PGSQL_DIAG_SOURCE_FILE` (int)
  Passée à pg_result_error_field(). Le nom du fichier de l'emplacement du code source PostgreSQL où l'erreur a été reportée.
`PGSQL_DIAG_SOURCE_LINE` (int)
  Passée à pg_result_error_field(). Le nombre de ligne de l'emplacement du code source PostgreSQL où l'erreur a été reportée.
`PGSQL_DIAG_SOURCE_FUNCTION` (int)
  Passée à pg_result_error_field(). Le nom de la fonction de source code PostgreSQL reportant l'erreur.
`PGSQL_DIAG_SCHEMA_NAME` (int)
  Disponible à partir de PHP 7.3.0.
`PGSQL_DIAG_TABLE_NAME` (int)
  Disponible à partir de PHP 7.3.0.
`PGSQL_DIAG_COLUMN_NAME` (int)
  Disponible à partir de PHP 7.3.0.
`PGSQL_DIAG_DATATYPE_NAME` (int)
  Disponible à partir de PHP 7.3.0.
`PGSQL_DIAG_CONSTRAINT_NAME` (int)
  Disponible à partir de PHP 7.3.0.
`PGSQL_ERRORS_TERSE` (int)
  Passée à pg_set_error_verbosity(). Spécifie que les messages retournés incluent la sévérité, le texte primaire ainsi que la position seulement; ceci devrait entrer sur une seule ligne.
`PGSQL_ERRORS_DEFAULT` (int)
  Passée à pg_set_error_verbosity(). Le mode par défaut produit des messages qui incluent ce qui est plus haut et des détails en plus, conseil ou des champs contextes (ceci peut être sur plusieurs lignes).
`PGSQL_ERRORS_VERBOSE` (int)
  Passée à pg_set_error_verbosity(). Le mode verbeux inclut tous les champs disponibles.
`PGSQL_ERRORS_SQLSTATE` (int)
  Passé à pg_set_error_verbosity(). Inclut uniquement la gravité de l'erreur et le code d'erreur `SQLSTATE`. Si aucun code d'erreur n'est disponible, la sortie est similaire au mode `PGSQL_ERRORS_TERSE`. Avant PostgreSQL 11.1, la sortie est toujours la même que dans le mode `PGSQL_ERRORS_TERSE`.
`PGSQL_NOTICE_LAST` (int)
  Utilisé par pg_last_notice(). Disponible à partir de PHP 7.1.0.
`PGSQL_NOTICE_ALL` (int)
  Utilisé par pg_last_notice(). Disponible à partir de PHP 7.1.0.
`PGSQL_NOTICE_CLEAR` (int)
  Utilisé par pg_last_notice(). Disponible à partir de PHP 7.1.0.
`PGSQL_STATUS_LONG` (int)
  Passée à pg_result_status(). Indique que le code résultat est désiré numérique.
`PGSQL_STATUS_STRING` (int)
  Passée à pg_result_status(). Indique que le tag de résultat de commande est désiré textuel.
`PGSQL_CONV_IGNORE_DEFAULT` (int)
  Passée à pg_convert(). Ignore les valeurs par défaut dans la table pendant la conversion.
`PGSQL_CONV_FORCE_NULL` (int)
  Passée à pg_convert(). Utilise `null` à la place d'une chaîne de caractères vide.
`PGSQL_CONV_IGNORE_NOT_NULL` (int)
  Passée à pg_convert(). Ignore la conversion de `null` à l'intérieur des colonnes `NOT NULL`.
`PGSQL_DML_NO_CONV` (int)
  Passée aux fonctions pg_insert(), pg_select(), pg_update() et pg_delete(). Tous les paramètres passés tels quels. Un échappement manuel est nécessaire si les paramètres contiennent des données fournies par l'utilisateur. Utiliser la fonction pg_escape_string() pour cela.
`PGSQL_DML_EXEC` (int)
  Passée aux fonctions pg_insert(), pg_select(), pg_update() et pg_delete(). Exécution de la requête par ces fonctions.
`PGSQL_DML_ASYNC` (int)
  Passée aux fonctions pg_insert(), pg_select(), pg_update() et pg_delete(). Exécution asynchrone de la requête par ces fonctions.
`PGSQL_DML_STRING` (int)
  Passée aux fonctions pg_insert(), pg_select(), pg_update() et pg_delete(). Retourne la chaîne de requête exécutée.
`PGSQL_DML_ESCAPE` (int)
  Passée aux fonctions pg_insert(), pg_select(), pg_update() et pg_delete(). Applique un échappement interne à tous les paramètres plutôt que d'appeler la fonction pg_convert(). Cette option ne gère pas les méta-données. La requête doit être aussi rapide qu'avec les fonctions pg_query() et pg_send_query().
`PGSQL_POLLING_FAILED` (int)
  Retournée par la fonction pg_connect_poll() pour indiquer que la tentative de connexion a échoué.
`PGSQL_POLLING_READING` (int)
  Retournée par la fonction pg_connect_poll() pour indiquer que la connexion attend que le socket PostgreSQL ne soit accessible en lecture.
`PGSQL_POLLING_WRITING` (int)
  Retournée par la fonction pg_connect_poll() pour indiquer que la connexion attend que le socket PostgreSQL ne soit accessible en écriture.
`PGSQL_POLLING_OK` (int)
  Retournée par la fonction pg_connect_poll() pour indiquer que la connexion est prête à être utilisée.
`PGSQL_POLLING_ACTIVE` (int)
  Retournée par la fonction pg_connect_poll() pour indiquer que la connexion est actuellement active.
`PGSQL_DIAG_SEVERITY_NONLOCALIZED` (int)
  La sévérité ; les contenus du champ sont ERROR, FATAL, ou PANIC (dans un message d'erreur), ou WARNING, NOTICE, DEBUG, INFO, ou LOG (dans un message de remarque). Ceci est identique au champ PG_DIAG_SEVERITY à l'exception que les contenus ne sont jamais localisés. Ceci est présent seulement dans les versions 9.6 et ultérieures / PHP 7.3.0 ou supérieure.
`PGSQL_SHOW_CONTEXT_NEVER` (int)
  À utiliser avec pg_set_error_context_visibility(), le contexte n'est jamais affiché. Disponible à partir de PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ERRORS` (int)
  À utiliser avec pg_set_error_context_visibility(), les champs du contexte sont inclus uniquement dans les messages d'erreur. C'est le comportement par défaut. Disponible à partir de PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ALWAYS` (int)
  À utiliser avec pg_set_error_context_visibility(), les champs du contexte sont inclus dans les messages d'erreur, d'avis et d'avertissement. Disponible à partir de PHP 8.3.0.
`PGSQL_TRACE_SUPPRESS_TIMESTAMPS` (int)
  À utiliser avec pg_trace(), l'horodatage n'est pas inclus dans les messages de trace. Disponible à partir de PHP 8.4.20.
`PGSQL_TRACE_REGRESS_MODE` (int)
  À utiliser avec pg_trace(), des champs tels que les OIDs sont inclus dans les messages de trace. Disponible à partir de PHP 8.3.0.

# Exemples

## Sommaire

- Utilisation simple
- Utilisation simple

## Utilisation simple

Ce simple exemple montre comment se connecter, exécuter une requête et afficher les lignes résultantes et se déconnecter d'une base de données PostgreSQL.

Exemple #1 Exemple général de l'extension PostgreSQL

    <?php

    // Connexion, sélection de la base de données
    $dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
        or die('Connexion impossible : ' . pg_last_error());

    // Exécution de la requête SQL
    $query = 'SELECT * FROM authors';
    $result = pg_query($dbconn, $query) or die('Échec de la requête : ' . pg_last_error());

    // Affichage des résultats en HTML
    echo "<table>\n";
    while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Libère le résultat
    pg_free_result($result);

    // Ferme la connexion
    pg_close($dbconn);

    ?>

## Utilisation simple

Ces exemples contiennent des fonctions définies par l'utilisateur semblables aux fonctions antérieures MySQL.

Exemple #1 Exemple de fonctions PostgreSQL définies par l'utilisateur

    <?php
    // Cette fonction devrait être nécessaire, car une connexion PostgreSQL se
    // lie à une base de données.
    function pg_list_dbs($db)
    {
        assert(is_resource($db));
        $query = '
    SELECT
     d.datname as "Name",
     u.usename as "Owner",
     pg_encoding_to_char(d.encoding) as "Encoding"
    FROM
     pg_database d LEFT JOIN pg_user u ON d.datdba = u.usesysid
    ORDER BY 1;
    ';
        return pg_query($db, $query);
    }

    // Lister les tables.
    function pg_list_tables($db)
    {
        assert(is_resource($db));
        $query = "
    SELECT
     c.relname as \"Name\",
     CASE c.relkind WHEN 'r' THEN 'table' WHEN 'v' THEN 'view' WHEN 'i' THEN 'index' WHEN 'S' THEN 'sequence' WHEN 's' THEN 'special' END as \"Type\",
      u.usename as \"Owner\"
    FROM
     pg_class c LEFT JOIN pg_user u ON c.relowner = u.usesysid
    WHERE
     c.relkind IN ('r','v','S','')
     AND c.relname !~ '^pg_'
    ORDER BY 1;
    ";
        return pg_query($db, $query);
    }

    // Voir aussi pg_meta_data(). Ceci retourne la définition des champs en tant que tableau.
    function pg_list_fields($db, $table)
    {
        assert(is_resource($db));
        $query = "
    SELECT
     a.attname,
     format_type(a.atttypid, a.atttypmod),
     a.attnotnull,
     a.atthasdef,
     a.attnum
    FROM
     pg_class c,
     pg_attribute a
    WHERE
     c.relname = '".$table."'
     AND a.attnum > 0 AND a.attrelid = c.oid
    ORDER BY a.attnum;
    ";
        return pg_query($db, $query);
    }
    ?>

# Fonctions PostgreSQL

## Notes

> Note:

> Les fonctions ne sont pas toutes supportées par toutes les versions. Cela dépend de la version de libpq (la bibliothèque cliente de PostgreSQL C) et comment libpq est compilée. Si les extensions PHP PostgreSQL sont manquantes, alors c'est parce que la version de libpq ne les supporte pas.

> Note:

> La plupart des fonctions PostgreSQL acceptent le paramètre `connection` comme premier paramètre optionnel. S'il n'est pas fourni, la dernière connexion ouverte est utilisée. Si elle n'existe pas, les fonctions retournent `false`.

> Note:

> PostgreSQL transforme automatiquement tous les identifiants (par exemple, les noms de tables/colonnes) en minuscule à la création d'objet et lors de la requête. Pour forcer l'utilisation des caractères majuscules ou minuscules et majuscules des identifiants, il faut échapper l'identifiant en utilisant des guillemets ("").

> Note:

> PostgreSQL n'a pas de commande spéciale pour récupérer les schémas des bases de données (par exemple, toutes les tables dans la base de données). À la place, il y a un schéma standard nommé `information_schema` contenant les vues du système avec toutes les informations nécessaires, dans un format de requête facile. Voir la » Documentation PostgreSQL pour tous les détails.

# pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_affected_rows — Retourne le nombre de lignes affectées

### Description

function pg_affected_rows(PgSql\Result `$result`): int

pg_affected_rows() retourne le nombre de lignes affectées par les requêtes de type `INSERT`, `UPDATE` et `DELETE`.

Le serveur retourne également le nombre de lignes sélectionnées.

> Note:

> Auparavant, cette fonction s'appelait pg_cmdtuples().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).

### Valeurs de retour

Le nombre de lignes affectées par la requête. S'il n'y a pas de tuple affecté, la fonction retournera `0`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_affected_rows()

    <?php
    $result = pg_query($conn, "INSERT INTO editeur VALUES ('Auteur')");

    $cmdtuples = pg_affected_rows($result);

    echo $cmdtuples . " lignes ont été affectées.\n";
    ?>

L'exemple ci-dessus va afficher :

    1 lignes ont été affectées.

### Voir aussi

- pg_query() - Exécute une requête PostgreSQL
- pg_query_params() - Envoie une commande au serveur et attend le résultat, avec les capacités de passer des paramètres séparément de la commande texte SQL
- pg_execute() - Exécute une requête préparée PostgreSQL
- pg_num_rows() - Retourne le nombre de lignes PostgreSQL

# pg_cancel_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_cancel_query — Annule une requête asynchrone

### Description

function pg_cancel_query(PgSql\Connection `$connection`): bool

pg_cancel_query() annule la requête asynchrone, démarrée avec pg_send_query(), pg_send_query_params() ou pg_send_execute(). Il n'est pas possible d'annuler une requête démarrée avec pg_query().

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_cancel_query()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from auteurs; select count(*) from auteurs;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Premier appel de pg_get_result() : $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 a $rows1 enregistrements\n\n";

      // Annule la requête en cours de fonctionnement. Ce sera la deuxième requête
      // si elle fonctionne encore.
      pg_cancel_query($dbconn);
    ?>

L'exemple ci-dessus va afficher :

    Premier appel de pg_get_result() : Resource id #3
    Resource id #3 a 3 enregistrements

### Voir aussi

- pg_send_query() - Exécute une requête PostgreSQL asynchrone
- pg_connection_busy() - Vérifie si la connexion PostgreSQL est occupée

# pg_change_password

(PHP 8 >= 8.4.0)

pg_change_password — Change le mot de passe d'un utilisateur PostgreSQL

### Description

function pg_change_password(PgSql\Connection `$connection`, string `$user`, string `$password`): bool

pg_change_password() change le mot de passe d'un utilisateur PostgreSQL. Cette fonction utilise la fonction libpq `PQchangePassword`, qui gère automatiquement le chiffrement du mot de passe en fonction de la configuration du serveur.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`user`
  Le nom de l'utilisateur PostgreSQL dont le mot de passe doit être changé.
`password`
  Le nouveau mot de passe.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- pg_connect() - Établit une connexion PostgreSQL

# pg_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_client_encoding — Lit l'encodage du client

### Description

function pg_client_encoding(?PgSql\Connection `$connection` = `null`): string

PostgreSQL supporte la conversion automatique entre le serveur et le client pour certains jeux de caractères. pg_client_encoding() retourne l'encodage du client. La chaîne de retour sera un des encodages standards de PostgreSQL.

> Note:

> Si la bibliothèque libpq est compilée sans le support de l'encodage multioctets, pg_client_encoding() retournera toujours `SQL_ASCII`. Le support de l'encodage dépend de la version de PostgreSQL. Se référer à la documentation de PostgreSQL sur les encodages supportés.

> Auparavant, cette fonction s'appelait pg_clientencoding().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

L'encodage du client.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_client_encoding()

    <?php
    // On suppose que $conn est une connexion à une base de données ISO-8859-1
    $encoding = pg_client_encoding($conn);

    echo "L'encodage du client est : ", $encoding, "\n";
    ?>

L'exemple ci-dessus va afficher :

    L'encodage du client est : ISO-8859-1

### Voir aussi

- pg_set_client_encoding() - Choisit l'encodage du client PostgreSQL

# pg_close

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_close — Termine une connexion PostgreSQL

### Description

function pg_close(?PgSql\Connection `$connection` = `null`): true

pg_close() ferme la connexion au serveur PostgreSQL associé à `connection`.

> Note:

> Il n'est généralement pas nécessaire de fermer une connexion non persistante, car elles sont automatiquement fermées à la fin d'un script.

S'il y a des instances de PgSql\Lob ouvertes avec cette connexion, ne fermez pas la connexion avant d'avoir fermé toutes les instances de PgSql\Lob.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.2.0 | Le type de retour est maintenant `true`, auparavant il était bool.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_close()

    <?php
    $dbconn = pg_connect("host=localhost port=5432 dbname=marie")
          or die("Connexion impossible");
    echo 'Connexion réussie';
    pg_close($dbconn);
    ?>

L'exemple ci-dessus va afficher :

    Connexion réussie

### Voir aussi

- pg_connect() - Établit une connexion PostgreSQL

# pg_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_connect — Établit une connexion PostgreSQL

### Description

function pg_connect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_connect() ouvre une connexion à une base de données PostgreSQL grâce à la chaîne de connexion `connection_string`.

Si un deuxième appel à pg_connect() est fait avec les mêmes arguments, aucune nouvelle connexion ne sera établie à moins qu'on ne passe `PGSQL_CONNECT_FORCE_NEW` à `flags`, mais la connexion précédente sera retournée.

L'ancienne syntaxe $conn = pg_connect("host", "port", "options", "tty", "dbname") est obsolète.

### Liste de paramètres

`connection_string`

  La chaîne `connection_string` peut être vide pour utiliser tous les paramètres par défaut ou elle peut contenir un ou plusieurs paramètres de configuration séparés par des espaces. Chaque paramètre de configuration est sous la forme `code = valeur`. Les espaces autour du signe égal sont optionnels. Pour écrire une valeur vide ou une valeur contenant des espaces, entourez cette valeur avec des apostrophes, par exemple : `code = 'une valeur'`. Les apostrophes et les antislashs à l'intérieur de la valeur doivent être échappés par un antislash, c'est-à-dire \' et \\.

  Les mots-clé actuellement reconnus sont : `host`, `hostaddr`, `port`, `dbname` (valeur par défaut: `user`), `user`, `password`, `connect_timeout`, `options`, `tty` (ignoré), `sslmode`, `requiressl` (obsolète, utiliser `sslmode`) et `service`. La liste de ces arguments dépend de la version du serveur PostgreSQL.

  Le paramètre `options` peut être utilisé pour passer des paramètres pour la ligne de commande invoquant le serveur.

`flags`

  Si `PGSQL_CONNECT_FORCE_NEW` est passé en argument, alors une nouvelle connexion sera créée, même si la chaîne `connection_string` est identique à celle de la connexion existante.

  Si `PGSQL_CONNECT_ASYNC` est fourni, la connexion sera établie de façon asynchrone. Le statut de la connexion peut être vérifié via la fonction pg_connect_poll() ou via la fonction pg_connection_status().

### Valeurs de retour

Retourne une instance de PgSql\Connection en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PgSql\Connection ; auparavant, une resource était retournée.

### Exemples

Exemple #1 Exemple avec pg_connect()

    <?php
    $dbconn = pg_connect("dbname=marie");
    // connexion à une base de données nommée "marie"

    $dbconn2 = pg_connect("host=localhost port=5432 dbname=marie");
    // connexion à une base de données nommée "marie" sur l'hôte "localhost" sur le port "5432"

    $dbconn3 = pg_connect("host=mouton port=5432 dbname=marie user=agneau password=foo");
    // connexion à une base de données nommée "marie" sur l'hôte "mouton" avec un
    // nom d'utilisateur et un mot de passe

    $conn_string = "host=mouton port=5432 dbname=test user=agneau password=bar";
    $dbconn4 = pg_connect($conn_string);
    // connexion à une base de données nommée "test" sur l'hôte "mouton" avec un
    // nom d'utilisateur et un mot de passe

    $dbconn5 = pg_connect("host=localhost options='--client_encoding=UTF8'");
    //connexion à la base sur "localhost" et passage d'un paramètre de la ligne de
    // commande concernant l'encodage UTF-8
    ?>

### Voir aussi

- pg_pconnect() - Établit une connexion PostgreSQL persistante
- pg_close() - Termine une connexion PostgreSQL
- pg_host() - Retourne le nom d'hôte
- pg_port() - Retourne le numéro de port
- pg_tty() - Retourne le nom de TTY associé à la connexion
- pg_options() - Retourne les options PostgreSQL
- pg_dbname() - Retourne le nom de la base de données PostgreSQL

# pg_connect_poll

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_connect_poll — Teste le statut d'une tentative de connexion asynchrone PostgreSQL en cours

### Description

function pg_connect_poll(PgSql\Connection `$connection`): int

La fonction pg_connect_poll() teste le statut d'une connexion PostgreSQL créée en appelant la fonction pg_connect() avec l'option `PGSQL_CONNECT_ASYNC`.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

Retourne la constante `PGSQL_POLLING_FAILED`, `PGSQL_POLLING_READING`, `PGSQL_POLLING_WRITING`, `PGSQL_POLLING_OK`, ou la constante `PGSQL_POLLING_ACTIVE`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

# pg_connection_busy

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_busy — Vérifie si la connexion PostgreSQL est occupée

### Description

function pg_connection_busy(PgSql\Connection `$connection`): bool

pg_connection_busy() détermine si la connexion est occupée. Si elle est occupée, une requête a déjà été lancée, et est en cours. Si pg_get_result() est utilisée, elle sera alors bloquée.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

Retourne `true` si la connexion est occupée, sinon `false`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_connection_busy()

    <?php
     $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");
     $bs = pg_connection_busy($dbconn);
     if ($bs) {
         echo 'La connexion est occupée';
     } else {
         echo 'La connexion est libre';
     }
    ?>

### Voir aussi

- pg_connection_status() - Lit le statut de la connexion PostgreSQL
- pg_get_result() - Lit un résultat PostgreSQL asynchrone

# pg_connection_reset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_reset — Relance la connexion au serveur PostgreSQL

### Description

function pg_connection_reset(PgSql\Connection `$connection`): bool

pg_connection_reset() effectue une reconnexion au serveur, avec les mêmes paramètres que lors de la connexion précédente avec `connection`. Cette fonction est pratique pour le traitement des erreurs.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_connection_reset()

    <?php
     $dbconn = pg_connect("dbname=publisher") or die ("Connexion impossible");
     $dbconn2 = pg_connection_reset($dbconn);
     if ($dbconn2) {
         echo 'Redémarrage réussi';
     } else {
         echo 'Redémarrage échoué';
     }
    ?>

### Voir aussi

- pg_connect() - Établit une connexion PostgreSQL
- pg_pconnect() - Établit une connexion PostgreSQL persistante
- pg_connection_status() - Lit le statut de la connexion PostgreSQL

# pg_connection_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_status — Lit le statut de la connexion PostgreSQL

### Description

function pg_connection_status(PgSql\Connection `$connection`): int

pg_connection_status() retourne le statut de la connexion `connection`.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

`PGSQL_CONNECTION_OK` ou `PGSQL_CONNECTION_BAD`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_connection_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");
      $stat = pg_connection_status($dbconn);
      if ($stat === PGSQL_CONNECTION_OK) {
          echo 'Connexion ok';
      } else {
          echo 'Connexion erronée';
      }
    ?>

### Voir aussi

- pg_connection_busy() - Vérifie si la connexion PostgreSQL est occupée

# pg_consume_input

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_consume_input — Lit l'entrée de la connexion

### Description

function pg_consume_input(PgSql\Connection `$connection`): bool

La fonction pg_consume_input() lit toutes les entrées en attente d'être lues depuis le serveur de base de données.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

`true` en cas de succès, ou `false` si une erreur survient. Il est à noter que `true` n'indique pas forcément que l'entrée est en attente d'être lue.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

# pg_convert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_convert — Convertit des valeurs d'un tableau associatif en une forme convenable pour des requêtes SQL

### Description

function pg_convert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = 0
): array|false

pg_convert() vérifie et convertit le tableau associatif `values` en une requête SQL valide. Pour que pg_convert() fonctionne, il faut que la table `table_name` existe, et contienne au moins autant de colonnes que le tableau `values` a d'éléments. Les noms des champs de `table_name` doivent correspondre aux index du tableau dans `values`. Retourne un tableau avec les valeurs converties en cas de succès, et sinon, `false`.

> Note:

> Les valeurs booléennes sont acceptées et converties en booléen PostgreSQL. Les représentations de valeurs booléennes sous forme de chaînes de caractères sont également supportées. `null` est converti en NULL PostgreSQL.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`table_name`

  Nom de la table pour laquelle les types seront convertis.

`values`

  Données à convertir.

`flags`

  Un nombre de `PGSQL_CONV_IGNORE_DEFAULT`, `PGSQL_CONV_FORCE_NULL` ou `PGSQL_CONV_IGNORE_NOT_NULL`, combiné.

### Valeurs de retour

Un tableau des valeurs converties, ou `false` si une erreur survient.

### Erreurs / Exceptions

Une ValueError ou TypeError est déclenchée lorsque la valeur ou le type du champ ne correspond pas correctement à un type PostgreSQL.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une erreur ValueError ou TypeError lorsque la valeur ou le type du champ ne correspond pas correctement à un type PostgreSQL ; précédemment, un `E_WARNING` était émis.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_convert()

    <?php
      $dbconn = pg_connect('dbname=foo');

      $tmp = array(
          'auteur' => 'Joe Thackery',
          'annee' => 2005,
          'titre' => 'Ma Vie, par Joe Thackery'
      );

      $vals = pg_convert($dbconn, 'auteurs', $tmp);
    ?>

### Voir aussi

- pg_meta_data() - Lit les métadonnées de la table PostgreSQL
- pg_insert() - Insère un tableau dans une table
- pg_select() - Effectue une sélection PostgreSQL
- pg_update() - Modifie les lignes d'une table
- pg_delete() - Efface des lignes PostgreSQL

# pg_copy_from

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_from — Insère des lignes dans une table à partir d'un tableau

### Description

function pg_copy_from(
PgSql\Connection `$connection`,
string `$table_name`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): bool

pg_copy_from() insère les éléments du tableau `rows` dans une table. Cette fonction utilise la commande SQL interne `COPY FROM`.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`table_name`

  Nom de la table dans laquelle `rows` sera copié.

`rows`

  Un iterable de données à copier dans `table_name`. Chaque valeur dans `rows` devient une ligne dans `table_name`. Chaque valeur dans `rows` devrait être une chaîne délimitée par des valeurs à insérer à l'intérieur de chaque champ. Les valeurs doivent être terminées par un saut à la ligne.

`separator`

  Le marqueur qui sépare les valeurs pour chaque champ dans chaque élément de `rows`. Par défaut `\t`.

`null_as`

  Comment les valeurs `NULL` de SQL sont représentées dans `rows`. Par défaut `\\N` (`"\\\\N"`).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre `rows` accepte désormais un iterable.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_copy_from()

    <?php
       $db = pg_connect("dbname=publisher") or die("Connexion impossible");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Voir aussi

- pg_copy_to() - Copie une table dans un tableau

# pg_copy_to

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_to — Copie une table dans un tableau

### Description

function pg_copy_to(
PgSql\Connection `$connection`,
string `$table_name`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): array|false

pg_copy_to() copie la table `table_name` dans un tableau. Cette fonction utilise la commande interne SQL `COPY TO` pour récupérer les enregistrements.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`table_name`

  Nom de la table depuis laquelle les données seront copiées dans `rows`.

`separator`

  Le marqueur qui sépare les valeurs pour chaque champ dans chaque élément de `rows`. Par défaut `\t`.

`null_as`

  Comment les valeurs `NULL` de SQL sont représentées dans `rows`. Par défaut `\\N` (`"\\\\N"`).

### Valeurs de retour

Un tableau avec un élément pour chaque ligne de données `COPY`, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_copy_to()

    <?php
       $db = pg_connect("dbname=publisher") or die("Connexion impossible");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Voir aussi

- pg_copy_from() - Insère des lignes dans une table à partir d'un tableau

# pg_dbname

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_dbname — Retourne le nom de la base de données PostgreSQL

### Description

function pg_dbname(?PgSql\Connection `$connection` = `null`): string

pg_dbname() retourne le nom de la base de données PostgreSQL associée à la connexion `connection`.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Une chaîne de type string contenant le nom de la base de données associée à la connexion `connection`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_dbname()

    <?php
     error_reporting(E_ALL);

     pg_connect ("host=localhost port=5432 dbname=marie");
     echo pg_dbname(); // affiche marie
    ?>

# pg_delete

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_delete — Efface des lignes PostgreSQL

### Description

function pg_delete(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_delete() efface les lignes d'une table spécifiées par les clés et valeur du tableau associatif `conditions`.

Si `flags` est fourni, pg_convert() est appliqué à `conditions` avec les drapeaux fournis.

Par défaut pg_delete() passe des valeurs brutes. Les valeurs doivent être échappées ou le drapeau `PGSQL_DML_ESCAPE` doit être spécifié dans `flags`. `PGSQL_DML_ESCAPE` met des guillemets et échappe les paramètres/identifiants. Par conséquent, les noms de table/colonnes deviennent sensibles à la casse.

Il est à noter que ni l'échappement ni les requêtes préparées peuvent protéger des requêtes LIKE, JSON, Tableaux, Regex, etc. Ces paramètres devraient être traités en fonction de leur contexte. C'est-à-dire échapper/valider les valeurs.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`table_name`

  Nom de la table depuis laquelle les lignes seront effacées.

`conditions`

  Un tableau où les clés sont les noms des champs de la table `table_name` et où les valeurs sont les valeurs de ces champs qui sont à effacer.

`flags`

  Toute combinaison des valeurs suivantes : `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` ou `PGSQL_DML_STRING`. Si `PGSQL_DML_STRING` fait partie du paramètre `flags` alors, la requête sera retournée. Lorsque la constante `PGSQL_DML_NO_CONV` ou la constante `PGSQL_DML_ESCAPE` est définie, aucun appel à la fonction pg_convert() ne sera fait en interne.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient. Retourne une chaîne de caractères si `PGSQL_DML_STRING` est passé dans le paramètre `flags`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_delete()

    <?php
     $db = pg_connect ('dbname=foo');
     // Ceci est sûr quelque peu, car toutes les valeurs sont échappées
     // Cependant PostgreSQL supporte les JSON/Tableaux. Ceux-ci ne sont pas
     // sûrs ni par échappement ni par les requêtes préparées.
     $res = pg_delete($db, 'post_log', $_POST, PG_DML_ESCAPE);
     if ($res) {
         echo "Les données POSTées ont été effacées : $res\n";
     } else {
         echo "Les données d'entrées sont erronées.\n";
     }
    ?>

### Voir aussi

- pg_convert() - Convertit des valeurs d'un tableau associatif en une forme convenable pour des requêtes SQL

# pg_end_copy

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_end_copy — Synchronise avec le serveur PostgreSQL

### Description

function pg_end_copy(?PgSql\Connection `$connection` = `null`): bool

pg_end_copy() synchronise le client PostgreSQL (normalement un processus serveur web) avec le serveur PostgreSQL, après une opération de copie faite par pg_put_line(). pg_end_copy() doit être utilisé, autrement le serveur PostgreSQL ne sera plus synchronisé avec le client et émettra une erreur.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_end_copy()

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\tBonjour le monde\t4.5\n");
      pg_put_line($conn, "4\tAurevoir le monde\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Voir aussi

- pg_put_line() - Envoie une chaîne au serveur PostgreSQL

# pg_escape_bytea

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_bytea — Protège une chaîne pour insertion dans un champ bytea

### Description

function pg_escape_bytea(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_bytea() protège les caractères de la chaîne `string` avec le mode bytea. La chaîne protégée est retournée.

> Note:

> Lors de l'utilisation d'une commande `SELECT` avec des données de type bytea, PostgreSQL retourne des valeurs octales, préfixées avec des antislashs '\' (par exemple \032). Les utilisateurs doivent effectuer la conversion en format binaire manuellement.

> pg_escape_bytea() requiert PostgreSQL 7.2 ou plus récent. Avec PostgreSQL 7.2.0 et 7.2.1, les données bytea doivent être transtypées lorsque l'on active le support des chaînes de caractères multioctets. C'est-à-dire `INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea);`. PostgreSQL 7.2.2 ou plus récent ne requiert pas cette manipulation. Toutefois, si le client et le serveur n'utilisent pas le même jeu de caractères, il peut arriver des erreurs. Il faut alors forcer le transtypage manuellement.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`string`

  Une chaîne de caractères contenant du texte ou des données binaires qui seront insérées dans la colonne bytea.

### Valeurs de retour

Une chaîne de caractères contenant les données échappées.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_escape_bytea()

    <?php
    // Connexion à la base de données
    $dbconn = pg_connect('dbname=foo');

    // Lecture d'un fichier binaire
    $data = file_get_contents('image1.jpg');

    // Échappement des données binaires
    $escaped = pg_escape_bytea($data);

    // Insertion dans la base de données
    pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', '{$escaped}')");
    ?>

### Voir aussi

- pg_unescape_bytea() - Supprime la protection d'une chaîne de type bytea
- pg_escape_string() - Protège une chaîne de caractères pour une requête SQL

# pg_escape_identifier

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_identifier — Protège un identifiant pour l'insertion dans un champ texte.

### Description

function pg_escape_identifier(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_identifier() protège un identifiant (exemple: table, nom de champ) pour une requête en base de données. Le résultat est une chaîne de caractères protégée pour PostgreSQL. pg_escape_identifier() ajoute des guillemets avant et après les données. Les utilisateurs ne doivent donc pas ajouter de guillemets. L'utilisation de cette fonction est recommandée pour les identifiants des requêtes. Pour les données brutes SQL (c'est-à-dire les paramètres, excepté de type bytea), pg_escape_literal() ou pg_escape_string() doit être utilisé. Pour les champs de type bytea il est nécessaire d'utiliser pg_escape_bytea().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`string`

  Une chaîne de caractères contenant du texte à protéger.

### Valeurs de retour

Une chaîne de caractères contenant les données protégées, ou `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_escape_identifier()

    <?php
      // Connexion à la base de données
      $dbconn = pg_connect('dbname=foo');

      // Protection du nom de la table
      $escaped = pg_escape_identifier($table_name);

      // Sélection des lignes de la table $table_name
      pg_query("SELECT * FROM {$escaped};");
    ?>

### Voir aussi

- pg_escape_literal() - Protège une requête SQL littérale à insérer dans un champ texte
- pg_escape_bytea() - Protège une chaîne pour insertion dans un champ bytea
- pg_escape_string() - Protège une chaîne de caractères pour une requête SQL

# pg_escape_literal

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_literal — Protège une requête SQL littérale à insérer dans un champ texte

### Description

function pg_escape_literal(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_literal() protège une requête SQL littérale pour le requêtage à la base de données PostgreSQL. Le résultat retourné est une chaîne de caractères protégée au format PostgreSQL. pg_escape_literal() ajoute des simples quotes avant et après les données. Les utilisateurs ne doivent donc pas ajouter des simples quotes. L'utilisation de cette fonction est recommandée à la place de pg_escape_string(). Si la colonne est de type bytea, il convient d'utiliser à la place la fonction pg_escape_bytea(). Pour protéger les identifiants (par exemple les noms de table, nom de champs), il convient d'utiliser la fonction pg_escape_identifier().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`string`

  Une chaîne de caractères contenant du texte à protéger.

### Valeurs de retour

Une chaîne de caractères contenant les données protégées, ou `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_escape_literal()

    <?php
      // Connexion à la base de données
      $dbconn = pg_connect('dbname=foo');

      // Lecture d'un fichier (contenant apostrophes et antislashes)
      $data = file_get_contents('letter.txt');

      // Protection des données
      $escaped = pg_escape_literal($data);

      // Insertion en base de données. Notez qu'il n'y a pas de simple quotes autour de {$escaped}
      pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', {$escaped})");
    ?>

### Voir aussi

- pg_escape_identifier() - Protège un identifiant pour l'insertion dans un champ texte.
- pg_escape_bytea() - Protège une chaîne pour insertion dans un champ bytea
- pg_escape_string() - Protège une chaîne de caractères pour une requête SQL

# pg_escape_string

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_string — Protège une chaîne de caractères pour une requête SQL

### Description

function pg_escape_string(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_string() protège une chaîne de caractères pour l'insérer dans la base de données. Elle retourne la chaîne ainsi protégée au format PostgreSQL. L'utilisation de cette fonction est recommandée, à la place de addslashes(). Si le type de la colonne est bytea, pg_escape_bytea() doit plutôt être utilisée. La fonction pg_escape_identifier() doit être utilisée pour échapper les identifiants (c.-à-d. noms de tables, noms de champs).

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`string`

  Une chaîne de caractères contenant le texte à échapper.

### Valeurs de retour

Une chaîne de caractères contenant les données échappées.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_escape_string()

    <?php
    // Connexion à la base de données
    $dbconn = pg_connect('dbname=foo');

    // Lecture d'un fichier texte (contenant des apostrophes et des antislashs)
    $data = file_get_contents('letter.txt');

    // Protection des données
    $escaped = pg_escape_string($data);

    // Insertion dans la base de données
    pg_query("INSERT INTO correspondence (name, data) VALUES ('Ma lettre', '{$escaped}')");
    ?>

### Voir aussi

- pg_escape_bytea() - Protège une chaîne pour insertion dans un champ bytea

# pg_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_execute — Exécute une requête préparée PostgreSQL

### Description

function pg_execute(PgSql\Connection `$connection` = ?, string `$statement_name`, array `$params`): PgSql\Result|false

Envoie une requête pour exécuter une requête préparée avec les paramètres donnés et attend le résultat.

pg_execute() est comme pg_query_params(), mais la commande qui sera exécutée est spécifiée en nommant une requête préalablement préparée, au lieu de donner une chaîne en tant que requête. Cette caractéristique permet aux commandes qui seront utilisées à plusieurs reprises d'être analysées et planifiées qu'une seule fois, plutôt que d'être exécutées chaque fois. La requête doit avoir été préalablement préparée dans la session courante.

Les paramètres sont identiques à la fonction pg_query_params() à l'exception du nom de la requête préparée qui est donnée à la place de la requête sous forme de chaîne.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`statement_name`

  Le nom de la requête préparée à exécuter. Si une chaîne vide est spécifiée (""), alors la requête qui n'est pas nommée est exécutée. Le nom doit avoir été précédemment préparé en utilisant pg_prepare(), pg_send_prepare() ou une commande SQL `PREPARE`.

`params`

  Un tableau de valeurs de paramètres pour substituer les variables $1, $2, etc. dans la requête préparée originale. Le nombre d'éléments présents dans le tableau doit concorder avec le nombre de variables à remplacer.

  Avertissement

  Les éléments sont convertis en chaînes de caractères en appelant cette fonction.

### Valeurs de retour

Une instance de PgSql\Result en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PgSql\Result instance ; auparavant, une resource était retourné.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_execute()

    <?php
    // Connexion à une base de données nommée "marie"
    $dbconn = pg_connect("dbname=marie");

    // Prépare une requête pour l'exécution
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM magasins WHERE nom = $1');

    // Exécute la requête préparée. À noter qu'il n'est pas nécessaire d'échapper
    // la chaîne "Joe's Widgets"
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Exécute la même requête préparée, cette fois avec un paramètre différent
    $result = pg_execute($dbconn, "my_query", array("Vêtements Vêtements Vêtements"));

    ?>

### Voir aussi

- pg_prepare() - Envoie une requête au serveur pour créer une instruction préparée avec les paramètres donnés et attend l'exécution
- pg_send_prepare() - Envoie une requête pour créer une requête préparée avec les paramètres donnés, sans attendre la fin de son exécution
- pg_query_params() - Envoie une commande au serveur et attend le résultat, avec les capacités de passer des paramètres séparément de la commande texte SQL

# pg_fetch_all

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_all — Lit toutes les lignes d'un résultat

### Description

function pg_fetch_all(PgSql\Result `$result`, int `$mode` = `PGSQL_ASSOC`): array

pg_fetch_all() retourne un tableau qui contient toutes les lignes de `result`.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`mode`
  Un paramètre optionnel qui contrôle la façon dont le array retourné est indexé. `mode` est une constante qui peut prendre les valeurs suivantes : `PGSQL_ASSOC`, `PGSQL_NUM` et `PGSQL_BOTH`. En utilisant `PGSQL_NUM`, la fonction retournera un tableau avec des indices numériques, en utilisant `PGSQL_ASSOC`, elle retournera seulement des indices associatifs tandis que `PGSQL_BOTH` retournera à la fois des indices numériques et associatifs.

### Valeurs de retour

Un tableau array de toutes les lignes dans le jeu de résultats. Chaque ligne est un tableau de valeurs des champs indexée par le nom des champs.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.
8.0.0 | pg_fetch_all() retournera désormais un tableau vide au lieu de `false` pour les ensembles de résultats avec zéro ligne.
7.1.0 | Le paramètre `mode` a été ajouté.

### Exemples

Exemple #1 Exemple avec pg_fetch_all()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT * FROM auteurs");
    if (!$result) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    $arr = pg_fetch_all($result);

    print_r($arr);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [id] => 1
                [name] => Fred
            )

        [1] => Array
            (
                [id] => 2
                [name] => Bob
            )

    )

### Voir aussi

- pg_fetch_row() - Lit une ligne dans un tableau
- pg_fetch_array() - Lit une ligne de résultat PostgreSQL dans un tableau
- pg_fetch_object() - Lit une ligne de résultat PostgreSQL dans un objet
- pg_fetch_result() - Retourne les valeurs d'un résultat

# pg_fetch_all_columns

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_fetch_all_columns — Récupère toutes les lignes d'une colonne de résultats particulière en tant que tableau

### Description

function pg_fetch_all_columns(PgSql\Result `$result`, int `$field` = 0): array

pg_fetch_all_columns() retourne un tableau qui contient toutes les lignes (enregistrements) d'une colonne particulière d'une ressource de résultats.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`field`

  Numéro de la colonne. Par défaut la première colonne si non-spécifié.

### Valeurs de retour

Un tableau contenant toutes les valeurs d'une colonne du résultat.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_fetch_all_columns()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT title, name, address FROM authors");
    if (!$result) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    // Récupère un tableau contenant tous les noms d'auteurs
    $arr = pg_fetch_all_columns($result, 1);

    var_dump($arr);

    ?>

### Voir aussi

- pg_fetch_all() - Lit toutes les lignes d'un résultat

# pg_fetch_array

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_array — Lit une ligne de résultat PostgreSQL dans un tableau

### Description

function pg_fetch_array(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_BOTH`): array|false

pg_fetch_array() retourne un tableau qui contient la ligne demandée.

pg_fetch_array() est une version évoluée de pg_fetch_row(). En plus de proposer un tableau à indice numérique, elle peut aussi enregistrer les données dans un tableau associatif, en utilisant les noms des champs comme clés. Ces deux fonctions utilisent le tableau associatif par défaut.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

pg_fetch_array() n'est pas significativement plus lente que pg_fetch_row() et elle apporte un confort d'utilisation appréciable.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`row`

  Numéro de la ligne à récupérer. Les lignes sont numérotées en commençant à 0. Si l'argument est omis ou s'il vaut `null`, la ligne suivante est récupérée.

`mode`
  Un paramètre optionnel qui contrôle la façon dont le array retourné est indexé. `mode` est une constante qui peut prendre les valeurs suivantes : `PGSQL_ASSOC`, `PGSQL_NUM` et `PGSQL_BOTH`. En utilisant `PGSQL_NUM`, la fonction retournera un tableau avec des indices numériques, en utilisant `PGSQL_ASSOC`, elle retournera seulement des indices associatifs tandis que `PGSQL_BOTH` retournera à la fois des indices numériques et associatifs.

### Valeurs de retour

Un tableau à indice numérique (commençant à 0), associatif (indexé avec le nom des champs) ou les deux. Chaque valeur dans le tableau est représentée comme une chaîne (chaîne de caractères). Les valeurs `null` de la base de données sont retournées `null`.

`false` est retournée si `row` excède le nombre de lignes dans le jeu de résultats, n'a plus de ligne disponible ou tout autre erreur. Tenter de récupérer le résultat d'une requête autre que SELECT retournera aussi `false`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_fetch_array()

    <?php

    $conn = pg_pconnect ("dbname=publisher");
    if (!$conn) {
      echo "Erreur de connexion.\n";
      exit;
    }

    $result = pg_query ($conn, "SELECT auteur, email FROM auteurs");
    if (!$result) {
      echo "Erreur durant la requête.\n";
      exit;
    }

    $arr = pg_fetch_array ($result, 0, PGSQL_NUM);
    echo $arr[0] . " <- Ligne 1 Auteurs\n";
    echo $arr[1] . " <- Ligne 1 E-mail\n";

    // Le paramètre row est optionnel ; NULL peut être passé à la place,
    // pour passer un mode. Les appels successifs à pg_fetch_array
    // retourneront la ligne suivante.
    $arr = pg_fetch_array($result, NULL, PGSQL_ASSOC);
    echo $arr["auteur"] . " <- Ligne 2 Auteur\n";
    echo $arr["email"] . " <- Ligne 2 E-mail\n";

    $arr = pg_fetch_array($result);
    echo $arr["auteur"] . " <- Ligne 3 Auteur\n";
    echo $arr[1] . " <- Ligne 3 E-mail\n";

    ?>

### Voir aussi

- pg_fetch_row() - Lit une ligne dans un tableau
- pg_fetch_object() - Lit une ligne de résultat PostgreSQL dans un objet
- pg_fetch_result() - Retourne les valeurs d'un résultat

# pg_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_assoc — Lit une ligne de résultat PostgreSQL sous forme de tableau associatif

### Description

function pg_fetch_assoc(PgSql\Result `$result`, ?int `$row` = `null`): array|false

pg_fetch_assoc() retourne un tableau associatif qui contient la ligne en cours dans le résultat `result`.

pg_fetch_assoc() est équivalent d'appeler pg_fetch_array() avec `PGSQL_ASSOC` comme troisième paramètre (qui est optionnel). Cela retournera seulement un tableau associatif. En cas de besoin d'indices numériques, utiliser pg_fetch_row().

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

pg_fetch_assoc() n'est pas significativement plus lente que pg_fetch_row() et elle apporte un confort d'utilisation appréciable.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`row`

  Numéro de la ligne à récupérer. Les lignes sont numérotées en commençant à 0. Si l'argument est omis ou s'il vaut `null`, la ligne suivante est récupérée.

### Valeurs de retour

Un tableau à indice associatif (par nom de champ). Chaque valeur dans le tableau est représentée comme une chaîne de caractères. Les valeurs `null` de la base de données sont retournées `null`.

`false` est retournée si `row` excède le nombre de lignes dans le jeu de résultats, n'a plus de ligne disponible ou tout autre erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_fetch_assoc()

    <?php
    $conn = pg_pconnect ("dbname=publisher");
    if (!$conn) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    $result = pg_query ($conn, "SELECT id, auteur, email FROM auteurs");
    if (!$result) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    while ($row = pg_fetch_assoc($result)) {
      echo $row['id'];
      echo $row['auteur'];
      echo $row['email'];
    }
    ?>

### Voir aussi

- pg_fetch_row() - Lit une ligne dans un tableau
- pg_fetch_array() - Lit une ligne de résultat PostgreSQL dans un tableau
- pg_fetch_object() - Lit une ligne de résultat PostgreSQL dans un objet
- pg_fetch_result() - Retourne les valeurs d'un résultat

# pg_fetch_object

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_object — Lit une ligne de résultat PostgreSQL dans un objet

### Description

function pg_fetch_object(
PgSql\Result `$result`,
?int `$row` = `null`,
string `$class` = "stdClass",
array `$constructor_args` = []
): object|false

pg_fetch_object() retourne un objet ainsi que ses propriétés qui correspond aux noms des champs de la ligne. La fonction peut optionnellement instancier un objet d'une classe spécifique et passer les paramètres au constructeur de cette classe.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

Du point de vue vitesse, la fonction est identique à pg_fetch_array() et est presque aussi rapide que pg_fetch_row() (la différence est insignifiante).

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`row`

  Numéro de la ligne à récupérer. Les lignes sont numérotées en commençant à 0. Si l'argument est omis ou s'il vaut `null`, la ligne suivante est récupérée.

`class`

  Le nom de la classe à instancier, fixe les propriétés de celles-ci et ses valeurs de retour. Si rien n'est spécifié, un objet de style stdClass est retourné.

`constructor_args`

  Paramètre optionnel de type array pour passer des arguments au constructeur de la classe `class`.

### Valeurs de retour

Un objet de type object avec les attributs pour chaque champ dans le jeu de résultats. Les valeurs `null` de la base de données sont retournées `null`.

`false` est retournée si `row` excède le nombre de lignes dans le jeu de résultats, n'a plus de ligne disponible ou tout autre erreur.

### Erreurs / Exceptions

Une ValueError est déclenchée lorsque l'argument `constructor_args` n'est pas vide et que la classe n'a pas de constructeur.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une exception ValueError lorsque l'argument `constructor_args` n'est pas vide et que la classe n'a pas de constructeur ; précédemment, une exception Exception était déclenchée.
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_fetch_object()

    <?php

    $database = 'store';

    $db_conn = pg_connect("host=localhost port=5432 dbname=$database");
    if (!$db_conn) {
      echo "La connexion à la base $database a échoué\n";
      exit;
    }

    $qu = pg_query($db_conn, "SELECT * FROM livres ORDER BY auteur");

    while ($data = pg_fetch_object($qu)) {
      echo $data->auteur . " (";
      echo $data->annee . "): ";
      echo $data->titre . "<br />";
    }

    pg_free_result($qu);
    pg_close($db_conn);

    ?>

### Voir aussi

- pg_query() - Exécute une requête PostgreSQL
- pg_fetch_array() - Lit une ligne de résultat PostgreSQL dans un tableau
- pg_fetch_assoc() - Lit une ligne de résultat PostgreSQL sous forme de tableau associatif
- pg_fetch_row() - Lit une ligne dans un tableau
- pg_fetch_result() - Retourne les valeurs d'un résultat

# pg_fetch_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_fetch_result — Retourne les valeurs d'un résultat

### Description

function pg_fetch_result(PgSql\Result `$result`, string|false|null `$row` , mixed `$field`): string|false|null
function pg_fetch_result(PgSql\Result `$result`, mixed `$field`): string|false|null

pg_fetch_result() retourne la valeur d'une ligne et d'un champ (colonne) en particulier à partir d'une instance PgSql\Result.

> Note:

> Cette fonction s'appelait auparavant pg_result().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`row`

  Numéro de la ligne à récupérer. Les lignes sont numérotées de 0 en montant. Si l'argument est omis, la ligne suivante est récupérée.

`field`

  Une chaîne de type string représentant le nom du champ (colonne) à récupérer, sinon un entier de type int représentant le numéro du champ à récupérer. Les champs sont numérotés de 0 en montant.

### Valeurs de retour

Les booléens sont retournés comme des "t" ou "f". Tous les autres types, y compris les tableaux, sont retournés sous forme de chaînes formatées, de la même manière que PostgreSQL les afficherait dans le client psql. Les valeurs NULL de la base de données sont retournées NULL.

`false` est retournée si `row` excède le nombre de lignes dans le jeu de résultats, n'a plus de ligne disponible ou tout autre erreur.

### Historique

Version | Description
--- | ---
8.3.0 | `row` est désormais nullable.
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_fetch_result()

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "Premier champ dans la deuxième ligne est : ", $val, "\n";
    ?>

L'exemple ci-dessus va afficher :

    Premier champ dans la deuxième ligne est : 2

### Voir aussi

- pg_query() - Exécute une requête PostgreSQL
- pg_fetch_array() - Lit une ligne de résultat PostgreSQL dans un tableau

# pg_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_row — Lit une ligne dans un tableau

### Description

function pg_fetch_row(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_NUM`): array|false

pg_fetch_row() lit une ligne dans le résultat associé à l'instance `result`.

> Note: Cette fonction définit les champs NULL à la valeur PHP `null`.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`row`

  Numéro de la ligne à récupérer. Les lignes sont numérotées en commençant à 0. Si l'argument est omis ou s'il vaut `null`, la ligne suivante est récupérée.

`mode`
  Un paramètre optionnel qui contrôle la façon dont le array retourné est indexé. `mode` est une constante qui peut prendre les valeurs suivantes : `PGSQL_ASSOC`, `PGSQL_NUM` et `PGSQL_BOTH`. En utilisant `PGSQL_NUM`, la fonction retournera un tableau avec des indices numériques, en utilisant `PGSQL_ASSOC`, elle retournera seulement des indices associatifs tandis que `PGSQL_BOTH` retournera à la fois des indices numériques et associatifs.

### Valeurs de retour

Un tableau de type array, indexé de 0 en montant, avec chaque valeur représentée comme une chaîne (chaîne de caractères). Les valeurs `null` de la base de données sont retournées `null`.

`false` est retournée si `row` excède le nombre de lignes dans le jeu de résultats, n'a plus de ligne disponible ou tout autre erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_fetch_row()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT auteur, email FROM auteurs");
    if (!$result) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Auteur : $row[0]  E-mail : $row[1]";
      echo "<br />\n";
    }

    ?>

### Voir aussi

- pg_query() - Exécute une requête PostgreSQL
- pg_fetch_array() - Lit une ligne de résultat PostgreSQL dans un tableau
- pg_fetch_object() - Lit une ligne de résultat PostgreSQL dans un objet
- pg_fetch_result() - Retourne les valeurs d'un résultat

# pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_is_null — Teste si un champ PostgreSQL est à `null`

### Description

function pg_field_is_null(PgSql\Result `$result`, string|false|null `$row` , mixed `$field`): int
function pg_field_is_null(PgSql\Result `$result`, mixed `$field`): int

pg_field_is_null() teste si un champ dans une instance PgSql\Result est un `NULL` SQL ou pas.

> Note:

> Auparavant, cette fonction s'appelait pg_fieldisnull().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`row`

  Numéro de la ligne à récupérer. Les lignes sont numérotées de 0 en montant. Si l'argument est omis, la ligne courante est récupérée.

`field`

  Numéro du champ (commençant à 0) de type int ou le nom du champ de type string.

### Valeurs de retour

Retourne `1` si le champ de la ligne donnée est `null`, `0` s'il n'est pas `null`. `false` est retournée si la ligne n'est pas dans le tableau ou tout autre erreur.

### Historique

Version | Description
--- | ---
8.3.0 | `row` est désormais nullable.
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_field_is_null()

    <?php
        $dbconn = pg_connect("dbname=publisher") or die ("Connexion impossible");
        $res = pg_query($dbconn, "select * from auteurs where auteur = 'Orwell'");
        if ($res) {
            if (pg_field_is_null($res, 0, "annee") == 1) {
                echo "La valeur du champ \"annee\" est null.\n";
            }
            if (pg_field_is_null($res, 0, "annee") == 0) {
                echo "La valeur du champ \"annee\" n'est pas null.\n";
            }
        }
    ?>

# pg_field_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_name — Retourne le nom d'un champ PostgreSQL

### Description

function pg_field_name(PgSql\Result `$result`, int `$field`): string

pg_field_name() retourne le nom du champ qui occupe la colonne numéro `field` dans le résultat `result`. La numérotation des champs commence à 0.

> Note:

> Auparavant, cette fonction s'appelait pg_fieldname().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`field`

  Numéro du champ, commençant à 0.

### Valeurs de retour

Le nom du champ.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Récupération d'informations des champs

    <?php
     $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

     $res = pg_query($dbconn, "select * from auteurs where auteur = 'Orwell'");
     $i = pg_num_fields($res);
     for ($j = 0; $j < $i; $j++) {
         echo "colonne $j\n";
         $fieldname = pg_field_name($res, $j);
         echo "Champ : $fieldname\n";
         echo "Taille affichée : ".pg_field_prtlen($res, $fieldname)." caractères\n";
         echo "Taille de stockage : ".pg_field_size($res, $j)." octets\n";
         echo "Type de champ : ".pg_field_type($res, $j)." \n\n";
     }
    ?>

L'exemple ci-dessus va afficher :

    colonne 0
    Champ : auteur
    Taille affichée : 6 caractères
    Taille de stockage : -1 octets
    Type de champ : varchar

    colonne 1
    Champ : annee
    Taille affichée : 4 caractères
    Taille de stockage : 2 octets
    Type de champ : int2

    colonne 2
    Champ : titre
    Taille affichée : 24 caractères
    Taille de stockage : -1 octets
    Type de champ : varchar

### Voir aussi

- pg_field_num() - Retourne le numéro d'une colonne

# pg_field_num

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_num — Retourne le numéro d'une colonne

### Description

function pg_field_num(PgSql\Result `$result`, string `$field`): int

pg_field_num() retourne le numéro de la colonne, dont le nom est `field`, dans le résultat `result`.

> Note:

> Auparavant, cette fonction s'appelait pg_fieldnum().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`field`

  Le nom du champ. Le nom donné est traité comme un identifiant dans une commande SQL, c'est-à-dire qu'il est mis en minuscule sauf s'il est entre guillemets doubles.

### Valeurs de retour

Le numéro du champ (commençant à 0) ou -1 en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Récupération d'informations des champs

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      $res = pg_query($dbconn, "select auteur, annee, titre from auteurs where auteur = 'Orwell'");

      echo "Le numéro de la colonne 'titre' est : ", pg_field_num($res, 'titre');
    ?>

L'exemple ci-dessus va afficher :

    Le numéro de la colonne 'titre' est : 2

### Voir aussi

- pg_field_name() - Retourne le nom d'un champ PostgreSQL

# pg_field_prtlen

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_prtlen — Retourne la taille imprimée

### Description

function pg_field_prtlen(PgSql\Result `$result`, string|false|null `$row` , mixed `$field_name_or_number`): int
function pg_field_prtlen(PgSql\Result `$result`, mixed `$field_name_or_number`): int

pg_field_prtlen() retourne la taille imprimée (nombre de caractères) d'une valeur donnée dans un résultat PostgreSQL. La numérotation des lignes commence à 0. pg_field_prtlen() retourne `false` en cas d'erreur.

Le paramètre `field_name_or_number` peut être passé soit en tant qu'entier, soit en tant que chaîne de caractères. S'il est passé en tant qu'entier, PHP l'identifie comme le numéro d'un champ, sinon, comme le nom d'un champ.

Voir l'exemple donné à la page de la documentation de la fonction pg_field_name().

> Note:

> Auparavant, cette fonction s'appelait pg_fieldprtlen().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`row`

  Numéro de la ligne dans le résultat. Les lignes sont numérotées à partir de 0 en montant. Si ce paramètre n'est pas fourni, la ligne en cours est récupérée.

### Valeurs de retour

Le nombre de caractères imprimés.

### Historique

Version | Description
--- | ---
8.3.0 | `row` est désormais nullable.
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Récupération d'informations à propos des champs

    <?php
      $dbconn = pg_connect("dbname=editeur") or die("Connexion impossible");

      $res = pg_query($dbconn, "select * from auteurs where auteur = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "colonne $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "nom champ : $fieldname\n";
          echo "taille affichage : " . pg_field_prtlen($res, $fieldname) . " caractères\n";
          echo "taille enregistrement : " . pg_field_size($res, $j) . " octets\n";
          echo "type champ : " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

L'exemple ci-dessus va afficher :

    colonne 0
    nom champ : auteur
    taille affichage : 6 caractères
    taille enregistrement : -1 octets
    type champ : varchar

    colonne 1
    nom champ : annee
    taille affichage : 4 caractères
    taille enregistrement : 2 octets
    type champ : int2

    colonne 2
    nom champ : titre
    taille affichage : 24 caractères
    taille enregistrement : -1 octets
    type champ : varchar

### Voir aussi

- pg_field_size() - Retourne la taille interne de stockage d'un champ donné

# pg_field_size

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_size — Retourne la taille interne de stockage d'un champ donné

### Description

function pg_field_size(PgSql\Result `$result`, int `$field`): int

pg_field_size() retourne la taille interne de stockage d'un champ donné, en octets.

> Note:

> Auparavant, cette fonction s'appelait pg_fieldsize().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`field`

  Numéro du champ, commençant à 0.

### Valeurs de retour

La taille du stockage interne d'un champ (en octets). -1 signifie un champ à grandeur variable.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Récupération d'informations des champs

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      $res = pg_query($dbconn, "select * from auteurs where auteur = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "colonne $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "Nom du champ : $fieldname\n";
          echo "Taille pour l'affichage : " . pg_field_prtlen($res, $fieldname) . " caractères\n";
          echo "Taille pour le stockage : " . pg_field_size($res, $j) . " octets\n";
          echo "Type du champ : " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

L'exemple ci-dessus va afficher :

    colonne 0
    Nom du champ : auteur
    Taille pour l'affichage : 6 caractères
    Taille pour le stockage : -1 octets
    Type du champ : varchar

    colonne 1
    Nom du champ : annee
    Taille pour l'affichage : 4 caractères
    Taille pour le stockage : 2 octets
    Type du champ : int2

    colonne 2
    Nom du champ : titre
    Taille pour l'affichage : 24 caractères
    Taille pour le stockage : -1 octets
    Type du champ : varchar

### Voir aussi

- pg_field_prtlen() - Retourne la taille imprimée
- pg_field_type() - Retourne le type d'un champ PostgreSQL donné par index

# pg_field_table

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

pg_field_table — Retourne le nom ou l'oid d'une table

### Description

function pg_field_table(PgSql\Result `$result`, int `$field`, bool `$oid_only` = `false`): string|int|false

pg_field_table() retourne le nom de la table à laquelle le champ appartient ou l'oid de la table si le paramètre `oid_only` vaut `true`.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`field`

  Numéro du champ, commençant à 0.

`oid_only`

  Par défaut, le nom de la table à laquelle le champ appartient est retourné mais si le paramètre `oid_only` est défini à `true`, alors, ce sera l'oid qui sera retourné.

### Valeurs de retour

En cas de succès, le nom de la table ou l'oid, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Récupération des informations d'une table à partir d'un champ

    <?php
    $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

    $res = pg_query($dbconn, "SELECT bar FROM foo");

    echo pg_field_table($res, 0);
    echo pg_field_table($res, 0, true);

    $res = pg_query($dbconn, "SELECT version()");
    var_dump(pg_field_table($res, 0));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    foo
    14379580

    bool(false)

### Notes

> Note:

> Retourner l'oid est plus rapide que de retourner le nom de la table, car la récupération du nom de la table nécessite une requête sur la table système de la base de données.

### Voir aussi

- pg_field_name() - Retourne le nom d'un champ PostgreSQL
- pg_field_type() - Retourne le type d'un champ PostgreSQL donné par index

# pg_field_type

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_type — Retourne le type d'un champ PostgreSQL donné par index

### Description

function pg_field_type(PgSql\Result `$result`, int `$field`): string

pg_field_type() retourne une chaîne contenant le type de base du champ donné par son index `field`.

> Note:

> Si le champ utilise un domaine PostgreSQL (plutôt que d'un type basique), c'est le nom du domaine sous-jacent qui est retourné, plutôt que le nom du domaine en tant que tel.

> Note:

> Auparavant, cette fonction s'appelait pg_fieldtype().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`field`

  Numéro du champ, commençant à 0.

### Valeurs de retour

Une string contenant le nom de base du type de champ.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Récupération d'informations des champs

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      // On assume que 'titre' est un type varchar
      $res = pg_query($dbconn, "select titre from auteurs where auteur = 'Orwell'");

      echo "Type du champ titre : ", pg_field_type($res, 0);
    ?>

L'exemple ci-dessus va afficher :

    Type du champ titre : varchar

### Voir aussi

- pg_field_prtlen() - Retourne la taille imprimée
- pg_field_name() - Retourne le nom d'un champ PostgreSQL
- pg_field_type_oid() - Retourne le type ID (OID) pour le numéro du champ correspondant

# pg_field_type_oid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_field_type_oid — Retourne le type ID (OID) pour le numéro du champ correspondant

### Description

function pg_field_type_oid(PgSql\Result `$result`, int `$field`): string|int

pg_field_type_oid() retourne un entier contenant l'OID du type de base du champ `field` donné dans l'instance `result`.

Il est possible d'obtenir plus d'informations à propos du type de champ en interrogeant la table système de PostgreSQL pg_type() avec le OID obtenu par cette fonction.

> Note:

> Si le champ utilise un domaine PostgreSQL (plutôt que d'un type basique), c'est le OID du domaine sous-jacent qui est retourné, plutôt que le OID du domaine en tant que tel.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`field`

  Numéro du champ, commençant à 0.

### Valeurs de retour

Le OID du type de base du champ.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Récupération d'informations des champs

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      // On assume que 'titre' est un type varchar
      $res = pg_query($dbconn, "select titre from auteurs where auteur = 'Orwell'");

      echo "Type du champ titre OID : ", pg_field_type_oid($res, 0);
    ?>

L'exemple ci-dessus va afficher :

    Type du champ titre OID : 1043

### Voir aussi

- pg_field_type() - Retourne le type d'un champ PostgreSQL donné par index
- pg_field_prtlen() - Retourne la taille imprimée
- pg_field_name() - Retourne le nom d'un champ PostgreSQL

# pg_flush

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_flush — Envoie les données de requête sortante sur la connexion

### Description

function pg_flush(PgSql\Connection `$connection`): int|bool

La fonction pg_flush() envoie toutes les données sortantes de requête en attente d'être envoyées sur la connexion.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

Retourne `true` si l'envoi a réussi, ou si aucune donnée n'est en attente d'envoi, `0` si une partie des données en attente ont été envoyées mais qu'il en reste encore ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

# pg_free_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_free_result — Libère la mémoire

### Description

function pg_free_result(PgSql\Result `$result`): bool

pg_free_result() libère la mémoire et les données associées avec l'instance PgSql\Result.

pg_free_result() n'est vraiment utile que si l'on risque d'utiliser trop de mémoire durant le script. La mémoire occupée par les résultats est automatiquement libérée à la fin du script.

> Note:

> Auparavant, cette fonction s'appelait pg_freeresult().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_free_result()

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "Le premier champ de la seconde ligne est : ", $val, "\n";

    pg_free_result($res);
    ?>

L'exemple ci-dessus va afficher :

    Le premier champ de la seconde ligne est : 2

### Voir aussi

- pg_query() - Exécute une requête PostgreSQL
- pg_query_params() - Envoie une commande au serveur et attend le résultat, avec les capacités de passer des paramètres séparément de la commande texte SQL
- pg_execute() - Exécute une requête préparée PostgreSQL
- pg_result_memory_size() - Retourne la quantité de mémoire allouée pour un résultat de requête

# pg_get_notify

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_notify — Lit le message SQL NOTIFY

### Description

function pg_get_notify(PgSql\Connection `$connection`, int `$mode` = `PGSQL_ASSOC`): array|false

pg_get_notify() reçoit le message de NOTIFY envoyé par une commande SQL `NOTIFY`. Pour lire le message associé, utiliser la commande `LISTEN`.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`mode`
  Un paramètre optionnel qui contrôle la façon dont le array retourné est indexé. `mode` est une constante qui peut prendre les valeurs suivantes : `PGSQL_ASSOC`, `PGSQL_NUM` et `PGSQL_BOTH`. En utilisant `PGSQL_NUM`, la fonction retournera un tableau avec des indices numériques, en utilisant `PGSQL_ASSOC`, elle retournera seulement des indices associatifs tandis que `PGSQL_BOTH` retournera à la fois des indices numériques et associatifs.

### Valeurs de retour

Un tableau contenant le nom du message `NOTIFY`. Si le serveur le supporte, le tableau contient aussi la version du serveur et la charge utile (payload). Sinon, si aucun `NOTIFY` n'est en attente, alors `false` est retourné.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_get_notify()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    // écoute le message 'author_updated' des autres processus
    pg_query($conn, 'LISTEN author_updated;');
    $notify = pg_get_notify($conn);
    if (!$notify) {
      echo "Aucun message\n";
    } else {
      print_r($notify);
    }
    ?>

### Voir aussi

- pg_get_pid() - Lit l'identifiant de processus du serveur PostgreSQL

# pg_get_pid

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_pid — Lit l'identifiant de processus du serveur PostgreSQL

### Description

function pg_get_pid(PgSql\Connection `$connection`): int

pg_get_pid() lit l'identifiant de processus du serveur PostgreSQL. L'identifiant de processus est pratique pour vérifier si un message de `NOTIFY` a été envoyé via pg_get_notify() par un autre processus ou pas.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

L'identifiant du processus du serveur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_get_pid()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    // PID du serveur. Utiliser alors le PID avec pg_get_notify()
    $pid = pg_get_pid($conn);
    ?>

### Voir aussi

- pg_get_notify() - Lit le message SQL NOTIFY

# pg_get_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_get_result — Lit un résultat PostgreSQL asynchrone

### Description

function pg_get_result(PgSql\Connection `$connection`): PgSql\Result|false

pg_get_result() récupère l'instance PgSql\Result d'une requête asynchrone exécutée par pg_send_query(), pg_send_query_params(), ou pg_send_execute().

pg_send_query() et les autres fonctions de requête asynchrone peuvent envoyer plusieurs requêtes à un serveur PostgreSQL et pg_get_result() est utilisé pour obtenir chaque résultat de requête, un par un.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

Une instance de PgSql\Result, ou `false` s'il n'y a plus de résultat disponible.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PgSql\Result instance ; auparavant, une resource était retourné.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_get_result()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from auteurs; select count(*) from auteurs;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Premier appel à pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 a $rows1 enregistrements\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Second appel à pg_get_result(): $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 a $rows2 enregistrements\n";
    ?>

L'exemple ci-dessus va afficher :

    Premier appel à pg_get_result(): Resource id #3
    Resource id #3 a 3 enregistrements

    Second appel à pg_get_result(): Resource id #4
    Resource id #4 a 1 enregistrements

### Voir aussi

- pg_send_query() - Exécute une requête PostgreSQL asynchrone

# pg_host

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_host — Retourne le nom d'hôte

### Description

function pg_host(?PgSql\Connection `$connection` = `null`): string

pg_host() retourne le nom d'hôte associé à l'instance de connexion PostgreSQL.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Une chaîne contenant le nom de l'ordinateur hôte de `connection` ou une chaîne vide en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_host()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Correctement connecté à : " . pg_host($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Voir aussi

- pg_connect() - Établit une connexion PostgreSQL
- pg_pconnect() - Établit une connexion PostgreSQL persistante

# pg_insert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_insert — Insère un tableau dans une table

### Description

function pg_insert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = `PGSQL_DML_EXEC`
): PgSql\Result|string|bool

pg_insert() insère les `values` dans la table `table_name`.

Si `flags` est spécifié, pg_convert() est appliqué à `values` avec les drapeaux fournis.

Par défaut pg_insert() passe des valeurs brutes. Les valeurs doivent être échappées ou le drapeau `PGSQL_DML_ESCAPE` doit être spécifié dans `flags`. `PGSQL_DML_ESCAPE` met des guillemets et échappe les paramètres/identifiants. Par conséquent, les noms de table/colonnes deviennent sensibles à la casse.

Il est à noter que ni l'échappement ni les requêtes préparées peuvent protéger des requêtes LIKE, JSON, Tableaux, Regex, etc. Ces paramètres devraient être traités en fonction de leur contexte. C'est-à-dire échapper/valider les valeurs.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`table_name`

  Nom de la table dans laquelle les lignes seront insérées. La table `table_name` doit avoir au moins autant de colonnes que `values` a d'éléments.

`values`

  Un tableau dont les clés sont les noms des champs dans la table `table_name`, et où les valeurs sont les valeurs de ces champs qui seront insérées.

`flags`

  Toutes combinaisons de constantes parmi `PGSQL_CONV_OPTS`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` ou `PGSQL_DML_STRING`. Si `PGSQL_DML_STRING` fait partie du paramètre `flags`, alors la requête sera retournée. Lorsque la constante `PGSQL_DML_NO_CONV` ou la constante `PGSQL_DML_ESCAPE` est définie, aucun appel à la fonction pg_convert() ne sera effectué en interne.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.. Ou retourne une chaîne de caractères si `PGSQL_DML_STRING` est fourni via `flags`.

### Erreurs / Exceptions

Une ValueError est déclenchée lorsque la table spécifiée est invalide.

Une ValueError ou TypeError est déclenchée lorsque la valeur ou le type du champ ne correspond pas correctement à un type PostgreSQL.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une erreur ValueError lorsque la table spécifiée est invalide ; précédemment, un `E_WARNING` était émis.
8.3.0 | Lance désormais une erreur ValueError ou TypeError lorsque la valeur ou le type du champ ne correspond pas correctement à un type PostgreSQL ; précédemment, un `E_WARNING` était émis.
8.1.0 | Retourne désormais une instance de PgSql\Result instance ; auparavant, une resource était retourné.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_insert()

    <?php
      $dbconn = pg_connect ('dbname=foo');
      // Ceci est sûr quelque peu, car toutes les valeurs sont échappées
      // Cependant PostgreSQL supporte les JSON/Tableaux. Ceux-ci ne sont pas
      // sûrs ni par échappement ni par les requêtes préparées.
      $res = pg_insert($dbconn, 'post_log', $_POST, PGSQL_DML_ESCAPE);
      if ($res) {
          echo "Les données POSTées ont pu être enregistrées avec succès.\n";
      } else {
          echo "Il y a un problème avec les données.\n";
      }
    ?>

### Voir aussi

- pg_convert() - Convertit des valeurs d'un tableau associatif en une forme convenable pour des requêtes SQL

# pg_jit

(PHP 8 >= 8.4.0)

pg_jit — Retourne les informations JIT du serveur

### Description

function pg_jit(?PgSql\Connection `$connection` = `null`): array

pg_jit() retourne un tableau contenant les informations JIT (compilation Just-In-Time) du serveur PostgreSQL.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Retourne un tableau contenant les informations JIT du serveur.

### Voir aussi

- pg_version() - Retourne un tableau avec les versions du client, du protocole et du serveur (si disponible)

# pg_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_error — Lit le dernier message d'erreur sur la connexion

### Description

function pg_last_error(?PgSql\Connection `$connection` = `null`): string

pg_last_error() retourne le dernier message d'erreur pour une connexion `connection`.

Les messages d'erreur peuvent être écrasés par des appels internes à l'extension PostgreSQL (libpq) : il se peut que le message retourné ne soit pas approprié, notamment si plusieurs erreurs ont eu lieu dans le module.

Utiliser pg_result_error(), pg_result_error_field(), pg_result_status() et pg_connection_status() pour améliorer la gestion des erreurs.

> Note:

> Auparavant, cette fonction s'appelait pg_errormessage().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Une chaîne de caractères contenant le dernier message d'erreur sur la connexion `connection`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_last_error()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      // Requête qui échoue
      $res = pg_query($dbconn, "select * from doesnotexist");

      echo pg_last_error($dbconn);
    ?>

### Voir aussi

- pg_result_error() - Lit le message d'erreur associé à un résultat
- pg_result_error_field() - Retourne un champ individuel d'un rapport d'erreur

# pg_last_notice

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

pg_last_notice — Retourne la dernière note du serveur PostgreSQL

### Description

function pg_last_notice(PgSql\Connection `$connection`, int `$mode` = `PGSQL_NOTICE_LAST`): array|string|bool

pg_last_notice() retourne la dernière note du serveur PostgreSQL sur la connexion `connection` spécifiée. Le serveur PostgreSQL envoie des notes dans plusieurs cas, par exemple lors de création d'une colonne `SERIAL` dans une table.

Avec pg_last_notice(), il est possible d'éviter des requêtes inutiles en vérifiant si des notes sont liées ou pas à la transaction.

Le suivi des notes peut être rendu optionnel en mettant à 1 la directive de configuration `pgsql.ignore_notice` du fichier php.ini.

L'enregistrement des notes peut être rendu optionnel en mettant la directive de configuration `pgsql.log_notice` du php.ini à 0. À moins que `pgsql.ignore_notice` ne soit à 0, les notes ne seront pas enregistrées.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`mode`

  L'un de `PGSQL_NOTICE_LAST` (pour retourner la dernière note), `PGSQL_NOTICE_ALL` (pour retourner toutes les notes), ou `PGSQL_NOTICE_CLEAR` (pour effacer les notes).

### Valeurs de retour

Une chaîne de caractères contenant la dernière note sur la connexion `connection` avec `PGSQL_NOTICE_LAST`, un tableau avec `PGSQL_NOTICE_ALL`, un booléen avec `PGSQL_NOTICE_CLEAR`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
7.1.0 | Le paramètre `mode` a été ajouté.

### Exemples

Exemple #1 Exemple avec pg_last_notice()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    $res = pg_query("CREATE TABLE test (id SERIAL)");

    $notice = pg_last_notice($pgsql_conn);

    echo $notice;
    ?>

L'exemple ci-dessus va afficher :

    CREATE TABLE will create implicit sequence "test_id_seq" for "serial" column "test.id"

### Voir aussi

- pg_query() - Exécute une requête PostgreSQL
- pg_last_error() - Lit le dernier message d'erreur sur la connexion

# pg_last_oid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_oid — Retourne l'identifiant de la dernière ligne

### Description

function pg_last_oid(PgSql\Result `$result`): string|int|false

pg_last_oid() sert à récupérer le OID assigné à une ligne insérée.

Le champ OID est devenu optionnel depuis PostgreSQL 7.2 et ne sera plus présent par défaut dans PostgreSQL 8.1. Lorsque le champ OID n'est pas présent dans la table, le programmeur doit utiliser pg_result_status() pour vérifier si la ligne a été correctement insérée.

Pour obtenir la valeur d'un champ `SERIAL` dans une ligne insérée, il est nécessaire d'utiliser la fonction `CURRVAL` de PostgreSQL en nommant la séquence à qui la dernière valeur est requise. Si le nom de la séquence est inconnu, la fonction PostgreSQL 8.0 `pg_get_serial_sequence` est nécessaire.

PostgreSQL 8.1 a une fonction `LASTVAL` qui retourne la valeur de la séquence la plus récemment utilisée de la session. Ceci permet d'éviter de nommer la séquence, la table ou la colonne.

> Note:

> Auparavant, cette fonction s'appelait pg_getlastoid().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).

### Valeurs de retour

Un entier ou chaîne de caractères contenant le OID assigné à la plus récente ligne insérée dans la connexion `connection` spécifiée ou `false` en cas d'erreur ou de OID indisponible.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_last_oid()

    <?php
      // Connexion à la base de données
      pg_connect("dbname=mark host=localhost");

      // Création d'une table exemple
      pg_query("CREATE TABLE test (a INTEGER) WITH OIDS");

      // Insertion de quelques données
      $res = pg_query("INSERT INTO test VALUES (1)");

      $oid = pg_last_oid($res);
    ?>

### Voir aussi

- pg_query() - Exécute une requête PostgreSQL
- pg_result_status() - Lit le statut du résultat

# pg_lo_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_close — Ferme un objet de grande taille PostgreSQL

### Description

function pg_lo_close(PgSql\Lob `$lob`): bool

pg_lo_close() ferme un objet large.

Pour utiliser un objet de grande taille (`lo`), il est nécessaire de le faire dans une transaction.

> Note:

> Auparavant, cette fonction s'appelait pg_loclose().

### Liste de paramètres

`lob`
  Une instance PgSql\Lob, retourné par pg_lo_open().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `lob` attend désormais une instance de PgSql\Lob ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_close()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "données objet de grande taille");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Voir aussi

- pg_lo_open() - Ouvre un objet de grande taille PostgreSQL
- pg_lo_create() - Crée un objet de grande taille PostgreSQL
- pg_lo_import() - Importe un objet de grande taille depuis un fichier

# pg_lo_create

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_create — Crée un objet de grande taille PostgreSQL

### Description

function pg_lo_create(PgSql\Connection `$connection` = ?, mixed `$object_id` = ?): int
function pg_lo_create(mixed `$object_id`): int

pg_lo_create() crée un objet de grande taille et retourne son OID. Les modes d'accès PostgreSQL `INV_READ` et `INV_WRITE` ne sont pas supportés, l'objet est toujours créé avec des droits d'accès en lecture et écriture.

Pour utiliser un objet de grande taille, il est nécessaire de le faire dans une transaction.

Au lieu d'utiliser l'interface d'objet de grande taille (qui n'a aucun contrôle d'accès et qui est encombrant à utiliser), essayez la colonne de type bytea de PostgreSQL et pg_escape_bytea().

> Note:

> Auparavant, cette fonction s'appelait pg_locreate().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`object_id`

  Si le paramètre `object_id` est fourni, la fonction essayera de créer un objet large avec cet identifiant, sinon, un identifiant d'objet disponible sera assigné par le serveur.

### Valeurs de retour

Un objet large OID, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_create()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "données objet de grande taille");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

# pg_lo_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_export — Exporte un objet de grande taille vers un fichier

### Description

function pg_lo_export(PgSql\Connection `$connection` = ?, int `$oid`, string `$filename`): bool

pg_lo_export() prend un objet de grande taille de la base de données PostgreSQL et sauvegarde son contenu dans un fichier local au système.

Pour utiliser un objet de grande taille (`lo`), il est nécessaire de le faire dans une transaction.

> Note:

> Auparavant, cette fonction s'appelait pg_loexport().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`oid`

  Le OID de l'objet de grande taille dans la base de données.

`filename`

  Le chemin d'accès complet ainsi que le fichier dans lequel il sera écrit l'objet de grande taille sur le système du client.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_export()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       $handle = pg_lo_open($database, $oid, "w");
       pg_lo_write($handle, "données objet de grande taille");
       pg_lo_close($handle);
       pg_lo_export($database, $oid, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### Voir aussi

- pg_lo_import() - Importe un objet de grande taille depuis un fichier

# pg_lo_import

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_import — Importe un objet de grande taille depuis un fichier

### Description

function pg_lo_import(PgSql\Connection `$connection` = ?, string `$filename`, int|string `$oid` = ?): int|string|false

pg_lo_import() crée un nouvel objet de grande taille dans la base de données en utilisant un fichier dans le système de fichiers en tant que données sources.

Pour utiliser un objet de grande taille (`lo`), il est nécessaire de le faire dans une transaction.

> Note:

> Auparavant, cette fonction s'appelait pg_loimport().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`filename`

  Le chemin d'accès complet ainsi que le fichier dans lequel il sera lu l'objet de grande taille sur le système du client.

`oid`

  Si le paramètre `oid` est fourni, la fonction essayera de créer un objet large avec cet identifiant, sinon, un identifiant d'objet disponible sera assigné par le serveur. Ce paramètre dépend d'une fonctionnalité qui est apparue avec PostgreSQL 8.1.

### Valeurs de retour

Le OID du nouvel objet de grande taille créé, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_import()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_import($database, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### Voir aussi

- pg_lo_export() - Exporte un objet de grande taille vers un fichier
- pg_lo_open() - Ouvre un objet de grande taille PostgreSQL

# pg_lo_open

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_open — Ouvre un objet de grande taille PostgreSQL

### Description

function pg_lo_open(PgSql\Connection `$connection`, int `$oid`, string `$mode`): PgSql\Lob|false

pg_lo_open() ouvre un objet large dans la base de données et retourne une instance de PgSql\Lob pour qu'il puisse être manipulé.

Avertissement

Ne pas fermer la connexion à la base de données avant de fermer l'instance PgSql\Lob.

Pour utiliser un objet de grande taille (`lo`), il est nécessaire de le faire dans une transaction.

> Note:

> Auparavant, cette fonction s'appelait pg_loopen().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`oid`

  Le OID de l'objet de grande taille dans la base de données.

`mode`

  Peut être "r" pour lecture seule, "w" pour écriture seule ou "rw" pour lecture et écriture.

### Valeurs de retour

Une instance PgSql\Lob, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PgSql\Lob ; auparavant, une resource était retournée.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_open()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "données objet de grande taille");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Voir aussi

- pg_lo_close() - Ferme un objet de grande taille PostgreSQL
- pg_lo_create() - Crée un objet de grande taille PostgreSQL

# pg_lo_read

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read — Lit un objet de grande taille

### Description

function pg_lo_read(PgSql\Lob `$lob`, int `$length` = 8192): string|false

pg_lo_read() lit au plus `length` octets d'un objet de grande taille, et retourne les données sous la forme d'une chaîne.

Pour utiliser un objet de grande taille (`lo`), il est nécessaire de le faire dans une transaction.

> Note:

> Auparavant, cette fonction s'appelait pg_loread().

### Liste de paramètres

`lob`
  Une instance PgSql\Lob, retourné par pg_lo_open().
`length`

  Un nombre maximal d'octets à retourner. Cet argument est optionnel.

### Valeurs de retour

Une chaîne contenant `length` octets de l'objet de grande taille ou `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `lob` attend désormais une instance de PgSql\Lob ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_read()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       $data = pg_lo_read($handle, 50000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Voir aussi

- pg_lo_read_all() - Lit un objet de grande taille en totalité

# pg_lo_read_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read_all — Lit un objet de grande taille en totalité

### Description

function pg_lo_read_all(PgSql\Lob `$lob`): int

pg_lo_read_all() lit un objet de grande taille en totalité et le passe directement au client, après les en-têtes adéquats. Cette fonction est prévue pour transmettre des sons ou des images.

Pour utiliser un objet de grande taille (`lo`), il est nécessaire de le faire dans une transaction.

> Note:

> Auparavant, cette fonction s'appelait pg_loreadall().

### Liste de paramètres

`lob`
  Une instance PgSql\Lob, retourné par pg_lo_open().

### Valeurs de retour

Nombre d'octets lus.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `lob` attend désormais une instance de PgSql\Lob ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_read_all()

    <?php
       header('Content-type: image/jpeg');
       $image_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $image_oid, "r");
       pg_lo_read_all($handle);
       pg_query($database, "commit");
    ?>

### Voir aussi

- pg_lo_read() - Lit un objet de grande taille

# pg_lo_seek

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_seek — Modifie la position dans un objet de grande taille

### Description

function pg_lo_seek(PgSql\Lob `$lob`, int `$offset`, int `$whence` = `SEEK_CUR`): bool

pg_lo_seek() modifie la position du pointeur dans l'instance PgSql\Lob.

Pour utiliser un objet de grande taille (`lo`), il est nécessaire de le faire dans une transaction.

### Liste de paramètres

`lob`
  Une instance PgSql\Lob, retourné par pg_lo_open().
`offset`

  Le nombre d'octets de déplacement.

`whence`

  Une de ces constantes `PGSQL_SEEK_SET` (positionne à partir du début de l'objet), `PGSQL_SEEK_CUR` (positionne à partir de la position courante) ou `PGSQL_SEEK_END` (positionne à partir de la fin de l'objet).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `lob` attend désormais une instance de PgSql\Lob ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_seek()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Saute les 50000 premiers octets
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // Lit les prochains 10000 octets
       $data = pg_lo_read($handle, 10000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Voir aussi

- pg_lo_tell() - Retourne la position courante dans un objet de grande taille PostgreSQL

# pg_lo_tell

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_tell — Retourne la position courante dans un objet de grande taille PostgreSQL

### Description

function pg_lo_tell(PgSql\Lob `$lob`): int

pg_lo_tell() retourne la position courante (à partir du début) du pointeur de lecture sur l'objet de grande taille `lob`.

Pour utiliser une interface avec un objet de grande taille, il est nécessaire de l'inclure dans un bloc de transaction.

### Liste de paramètres

`lob`
  Une instance PgSql\Lob, retourné par pg_lo_open().

### Valeurs de retour

La position courante du pointeur (en nombre d'octets) à partir du début de l'objet de grande taille. S'il y a une erreur, la valeur retournée sera négative.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `lob` attend désormais une instance de PgSql\Lob ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_tell()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Saute les 50000 premiers octets
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // On vérifie combien d'octets nous avons sauté
       $offset = pg_lo_tell($handle);
       echo "Position du pointeur est : $offset";
       pg_query($database, "commit");
    ?>

L'exemple ci-dessus va afficher :

    Position du pointeur est : 50000

### Voir aussi

- pg_lo_seek() - Modifie la position dans un objet de grande taille

# pg_lo_truncate

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_lo_truncate — Tronque un objet large

### Description

function pg_lo_truncate(PgSql\Lob `$lob`, int `$size`): bool

pg_lo_truncate() tronque une instance PgSql\Lob.

Pour utiliser l'interface des objets larges, il est nécessaire de l'enfermer dans un bloc de transaction.

### Liste de paramètres

`lob`
  Une instance PgSql\Lob, retourné par pg_lo_open().
`size`

  Le nombre d'octets à tronquer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `lob` attend désormais une instance de PgSql\Lob ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_truncate()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Tronque à 0
       pg_lo_truncate($handle, 0);
       pg_query($database, "commit");
       echo $data;
    ?>

### Voir aussi

- pg_lo_tell() - Retourne la position courante dans un objet de grande taille PostgreSQL

# pg_lo_unlink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_unlink — Efface un objet de grande taille PostgreSQL

### Description

function pg_lo_unlink(PgSql\Connection `$connection`, int `$oid`): bool

pg_lo_unlink() efface l'objet de grande taille dont l'identifiant est `oid`, pour la connexion `connection`. Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Pour utiliser un objet de grande taille (`lo`), il est nécessaire de le faire dans une transaction.

> Note:

> Auparavant, cette fonction s'appelait pg_lounlink().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`oid`

  Le OID de l'objet de grande taille dans la base de données.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_lo_unlink()

    <?php
       // OID de l'objet de grande taille à supprimer
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       pg_lo_unlink($database, $doc_oid);
       pg_query($database, "commit");
    ?>

### Voir aussi

- pg_lo_create() - Crée un objet de grande taille PostgreSQL
- pg_lo_import() - Importe un objet de grande taille depuis un fichier

# pg_lo_write

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_write — Écrit un objet de grande taille PostgreSQL

### Description

function pg_lo_write(PgSql\Lob `$lob`, string `$data`, ?int `$length` = `null`): int|false

pg_lo_write() écrit des données à l'intérieur d'un objet de grande taille à la position courante.

Pour manipuler un objet de grande taille (`lo`), il est nécessaire de placer les opérations dans un bloc de transaction.

> Note:

> Auparavant, cette fonction s'appelait pg_lowrite().

### Liste de paramètres

`lob`
  Une instance PgSql\Lob, retourné par pg_lo_open().
`data`

  Les données à être écrites dans l'objet de grande taille. Si `length` est un int et est inférieur à la grandeur de `data`, seuls les `length` premiers octets y seront écrits.

`length`

  Un nombre maximal d'octets à écrire. Il doit être supérieur à zéro et inférieur à la grandeur de `data`. Cet argument est optionnel, s'il est omis, il prendra par défaut la grandeur de `data`.

### Valeurs de retour

Le nombre d'octets écrits dans l'objet de grande taille ou `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `lob` attend désormais une instance de PgSql\Lob ; auparavant, une resource était attendu.
8.0.0 | `length` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_lo_write()

    <?php
       $doc_oid = 189762345;
       $data = "Ceci écrasera le début de l'objet de grande taille.";
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "w");
       $data = pg_lo_write($handle, $data);
       pg_query($database, "commit");
    ?>

### Voir aussi

- pg_lo_create() - Crée un objet de grande taille PostgreSQL
- pg_lo_open() - Ouvre un objet de grande taille PostgreSQL

# pg_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_meta_data — Lit les métadonnées de la table PostgreSQL

### Description

function pg_meta_data(PgSql\Connection `$connection`, string `$table_name`, bool `$extended` = `false`): array|false

pg_meta_data() retourne la définition de la table `table_name` sous forme de tableau.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`table_name`

  Le nom de la table.

`extended`

  Drapeau pour retourner les méta-données étendues. Par défaut, vaut `false`.

### Valeurs de retour

Un tableau de la table de définition, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Récupération des métadonnées d'une table

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      $meta = pg_meta_data($dbconn,'auteurs');
      if (is_array ($meta)) {
           echo '<pre>';
           var_dump ($meta);
           echo '</pre>';
      }
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
    ["auteur"]=>
    array(5) {
      ["num"]=>
      int(1)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["annee"]=>
    array(5) {
      ["num"]=>
      int(2)
      ["type"]=>
      string(4) "int2"
      ["len"]=>
      int(2)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["titre"]=>
    array(5) {
      ["num"]=>
      int(3)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    }

### Voir aussi

- pg_convert() - Convertit des valeurs d'un tableau associatif en une forme convenable pour des requêtes SQL

# pg_num_fields

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_fields — Retourne le nombre de champs

### Description

function pg_num_fields(PgSql\Result `$result`): int

pg_num_fields() retourne le nombre de champs (ou colonnes) d'une instance PgSql\Result.

> Note:

> Auparavant, cette fonction s'appelait pg_numfields().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).

### Valeurs de retour

Le nombre de champs (ou colonnes) dans le jeu de résultats. En cas d'erreur, -1 est retourné.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_num_fields()

    <?php
    $result = pg_query($conn, "SELECT 1, 2");

    $num = pg_num_fields($result);

    echo $num . " champ(s) retourné(s).\n";
    ?>

L'exemple ci-dessus va afficher :

    2 champ(s) retourné(s).

### Voir aussi

- pg_num_rows() - Retourne le nombre de lignes PostgreSQL
- pg_affected_rows() - Retourne le nombre de lignes affectées

# pg_num_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_rows — Retourne le nombre de lignes PostgreSQL

### Description

function pg_num_rows(PgSql\Result `$result`): int

pg_num_rows() retourne le nombre de lignes d'une instance PgSql\Result.

> Note:

> Auparavant, cette fonction s'appelait pg_numrows().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).

### Valeurs de retour

Le nombre de lignes dans le jeu de résultats. En cas d'erreur, `-1` est retourné.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_num_rows()

    <?php
    $result = pg_query($conn, "SELECT 1");

    $rows = pg_num_rows($result);

    echo $rows . " ligne(s) retournée(s).\n";
    ?>

L'exemple ci-dessus va afficher :

    1 ligne(s) retournée(s).

### Voir aussi

- pg_num_fields() - Retourne le nombre de champs
- pg_affected_rows() - Retourne le nombre de lignes affectées

# pg_options

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_options — Retourne les options PostgreSQL

### Description

function pg_options(?PgSql\Connection `$connection` = `null`): string

pg_options() retourne une chaîne contenant les options de la connexion PostgreSQL `connection`.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Une chaîne contenant les options de `connection`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_options()

    <?php
       $pgsql_conn = pg_connect("dbname=mark host=localhost");
       echo pg_options($pgsql_conn);
    ?>

### Voir aussi

- pg_connect() - Établit une connexion PostgreSQL

# pg_parameter_status

(PHP 5, PHP 7, PHP 8)

pg_parameter_status — Consulte un paramètre de configuration courant du serveur

### Description

function pg_parameter_status(PgSql\Connection `$connection` = ?, string `$name`): string|false

Consulte un paramètre de configuration courant du serveur.

Certaines valeurs de paramètres sont retournées par le serveur automatiquement lors du démarrage de la connexion ou lorsqu'une valeur change. pg_parameter_status() peut être utilisée pour interroger ces configurations. La fonction retourne la valeur courante du paramètre s'il est connu ou `false` si le paramètre est inconnu.

Les paramètres retournés par le serveur sont `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone` et `integer_datetimes`. Il est à noter que `server_version`, `server_encoding` et `integer_datetimes` ne peuvent changer après le démarrage de PostgreSQL.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`name`

  Les valeurs possibles de `name` sont `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone` et `integer_datetimes`. Il est à noter que cette valeur est sensible à la casse.

### Valeurs de retour

Une chaîne contenant la valeur du paramètre, `false` en cas d'échec ou du paramètre `name` invalide.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_parameter_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      echo "Encodage du serveur : ", pg_parameter_status($dbconn, "server_encoding");
    ?>

L'exemple ci-dessus va afficher :

    Encodage du serveur : SQL_ASCII

# pg_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_pconnect — Établit une connexion PostgreSQL persistante

### Description

function pg_pconnect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_pconnect() retourne une instance PgSql\Connection de connexion persistante.

Si un second appel est fait à pg_pconnect() avec le même `connection_string` comme étant une connexion existante, la connexion existante sera retournée à moins qu'on ne passe `PGSQL_CONNECT_FORCE_NEW` à `flags`.

Pour activer les connexions persistantes, la directive de configuration pgsql.allow_persistent du php.ini doit être mise à `On` (ce qui est sa valeur par défaut). Le nombre maximal de connexions peut être limité grâce à la directive de configuration pgsql.max_persistent dans le fichier php.ini (par défaut, elle vaut `-1`, c'est-à-dire pas de limite). Le nombre total de connexions peut être configuré avec la directive pgsql.max_links du fichier php.ini.

pg_close() ne refermera pas les connexions persistantes générées par pg_pconnect().

### Liste de paramètres

`connection_string`

  La chaîne `connection_string` peut être vide pour utiliser tous les paramètres par défaut ou elle peut contenir un ou plusieurs paramètres de configuration séparés par des espaces. Chaque paramètre de configuration est sous la forme `code = valeur`. Les espaces autour du signe égal sont optionnels. Pour écrire une valeur vide ou une valeur contenant des espaces, entourez cette valeur avec des apostrophes, par exemple : `code = 'une valeur'`. Les apostrophes et les antislashs à l'intérieur de la valeur doivent être échappés par un antislash, c'est-à-dire `\'` et `\\`.

  Les mots-clé actuellement reconnus sont : `host`, `hostaddr`, `port`, `dbname`, `user`, `password`, `connect_timeout`, `options`, `tty` (ignoré), `sslmode`, `requiressl` (obsolète, utiliser `sslmode`) et `service`. La liste de ces arguments dépend de la version du serveur PostgreSQL.

`flags`

  Si `PGSQL_CONNECT_FORCE_NEW` est passé en argument, alors une nouvelle connexion sera créée, même si la chaîne `connection_string` est identique à celle de la connexion existante.

### Valeurs de retour

Retourne une instance de PgSql\Connection en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PgSql\Connection ; auparavant, une resource était retournée.

### Exemples

Exemple #1 Exemple avec pg_pconnect()

    <?php
    // connexion à une base de données nommée "marie"
    $dbconn = pg_pconnect("dbname=marie");

    // connexion à une base de données nommée "marie" sur l'hôte "localhost" sur le port "5432"
    $dbconn2 = pg_pconnect("host=localhost port=5432 dbname=marie");

    // connexion à une base de données nommée "marie" sur l'hôte "mouton" avec un
    // nom d'utilisateur et un mot de passe
    $dbconn3 = pg_pconnect("host=mouton port=5432 dbname=marie user=agneau password=foo");

    // connexion à une base de données nommée "test" sur l'hôte "mouton" avec un
    // nom d'utilisateur et un mot de passe
    $conn_string = "host=mouton port=5432 dbname=test user=agneau password=bar";
    $dbconn4 = pg_pconnect($conn_string);
    ?>

### Voir aussi

- pg_connect() - Établit une connexion PostgreSQL
- Connexions Persistantes

# pg_ping

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_ping — Ping la connexion à la base

### Description

function pg_ping(?PgSql\Connection `$connection` = `null`): bool

pg_ping() ping la connexion à la base de données et essaie de se reconnecter si la connexion est perdue.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_ping()

    <?php
    $conn = pg_pconnect ("dbname=publisher");
    if (!$conn) {
      echo "Une erreur est survenue.\n";
      exit;
    }

    if (!pg_ping($conn))
      die("La connexion est perdue\n");
    ?>

### Voir aussi

- pg_connection_status() - Lit le statut de la connexion PostgreSQL
- pg_connection_reset() - Relance la connexion au serveur PostgreSQL

# pg_port

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_port — Retourne le numéro de port

### Description

function pg_port(?PgSql\Connection `$connection` = `null`): string

pg_port() retourne le numéro de port de la connexion donnée par `connection`.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Une chaîne de caractères contenant le numéro du port du serveur de base de données identifié par `connection` ou une chaîne vide en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_port()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Connecté correctement au port : " . pg_port($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — Envoie une requête au serveur pour créer une instruction préparée avec les paramètres donnés et attend l'exécution

### Description

function pg_prepare(PgSql\Connection `$connection` = ?, string `$statement_name`, string `$query`): PgSql\Result|false

pg_prepare() crée une requête préparée pour une exécution ultérieure avec pg_execute() ou pg_send_execute(). Cette caractéristique permet aux commandes qui seront utilisées à plusieurs reprises d'être analysées et planifiées qu'une seule fois, plutôt que d'être exécutées chaque fois.

La fonction crée une requête préparée nommée `statement_name` à partir de la chaîne `query`, celle-ci ne doit contenir qu'une seule commande SQL. `statement_name` peut être `""` pour créer une requête qui n'est pas nommée. Dans ce cas, les requêtes qui existaient et qui se trouvaient sans noms sont automatiquement remplacées; autrement, il y aura une erreur si le nom de la requête est déjà défini dans la session courante. Si des paramètres sont utilisés, ils sont référés à `$1`, `$2`, etc. dans `query`.

Des requêtes préparées à utiliser avec pg_prepare() peuvent être aussi créées en exécutant la requête SQL `PREPARE`. (Par contre, pg_prepare() est plus flexible puisqu'elle ne nécessite pas que les types des paramètres soient préspécifiés.) De plus, bien qu'il n'y ait pas de fonction PHP pour supprimer une requête préparée, la requête SQL `DEALLOCATE` peut être utilisée pour ce motif.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`statement_name`

  Le nom à donner à la requête préparée. Il doit être unique à chaque session. Si une chaîne vide est spécifiée `""` alors une requête sans nom est créée, écrasant les requêtes sans noms précédemment définies.

`query`

  La requête SQL avec ses paramètres. Elle doit contenir seulement une seule requête. Plusieurs requêtes séparées par des points-virgules ne sont pas autorisées. Si des paramètres sont utilisés, ils sont référés à `$1`, `$2`, etc.

### Valeurs de retour

Une instance PgSql\Result en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PgSql\Result instance ; auparavant, une resource était retourné.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_prepare()

    <?php
    // Connexion à une base de données nommée "marie"
    $dbconn = pg_connect("dbname=marie");

    // Prépare une requête pour l'exécution
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM magasins WHERE nom = $1');

    // Exécute la requête préparée. À noter qu'il n'est pas nécessaire d'échapper
    // la chaîne "Joe's Widgets"
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Exécute la même requête préparée, cette fois avec un paramètre différent
    $result = pg_execute($dbconn, "my_query", array("Vêtements Vêtements Vêtements"));

    ?>

### Voir aussi

- pg_execute() - Exécute une requête préparée PostgreSQL
- pg_send_execute() - Envoie une requête pour exécuter une requête préparée avec des paramètres donnés, sans attendre le(s) résultat(s)

# pg_put_copy_data

(PHP 8 >= 8.4.0)

pg_put_copy_data — Envoie des données au serveur durant une opération COPY

### Description

function pg_put_copy_data(PgSql\Connection `$connection`, string `$cmd`): int

Envoie des données au serveur durant une opération `COPY FROM STDIN`. Une commande `COPY` doit avoir été émise via pg_query() avant l'appel à cette fonction.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`cmd`
  Les données à envoyer au serveur. Un saut de ligne final est automatiquement ajouté s'il est absent. Les données doivent être formatées selon le format de la commande `COPY`.

### Valeurs de retour

Retourne `1` en cas de succès, `0` si les données n'ont pas pu être mises en file d'attente (uniquement en mode non bloquant), ou `-1` en cas d'erreur.

### Voir aussi

- pg_put_copy_end() - Signale la fin d'une opération COPY au serveur
- pg_query() - Exécute une requête PostgreSQL

# pg_put_copy_end

(PHP 8 >= 8.4.0)

pg_put_copy_end — Signale la fin d'une opération COPY au serveur

### Description

function pg_put_copy_end(PgSql\Connection `$connection`, ?string `$error` = `null`): int

Envoie une indication de fin de données au serveur durant une opération `COPY FROM STDIN`.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`error`
  Si non `null`, l'opération `COPY` est forcée à échouer avec le message d'erreur fourni.

### Valeurs de retour

Retourne `1` en cas de succès, `0` si les données n'ont pas pu être mises en file d'attente (uniquement en mode non bloquant), ou `-1` en cas d'erreur.

### Voir aussi

- pg_put_copy_data() - Envoie des données au serveur durant une opération COPY
- pg_query() - Exécute une requête PostgreSQL

# pg_put_line

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_put_line — Envoie une chaîne au serveur PostgreSQL

### Description

function pg_put_line(PgSql\Connection `$connection` = ?, string `$query`): bool

pg_put_line() envoie une chaîne (terminée par `null`) au serveur PostgreSQL. Ceci est nécessaire en conjonction avec une commande `COPY FROM` PostgreSQL.

`COPY` est un chargement très rapide des données supporté par PostgreSQL. Les données sont passées sans être analysées et dans une simple transaction.

Une alternative plutôt que d'utiliser la commande brute pg_put_line() est d'utiliser pg_copy_from(). C'est une interface bien plus simple.

> Note:

> À noter que l'application doit explicitement ajouter les deux caractères "\." à la fin de la chaîne pour indiquer au serveur qu'elle a fini d'envoyer des données, avant d'appeler pg_end_copy().

Avertissement

L'utilisation de pg_put_line() cause sur la plupart des objets de grande taille à échouer, incluant pg_lo_read() et pg_lo_tell(). Il est possible d'utiliser pg_copy_from() et pg_copy_to() à la place.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`query`

  Une ligne de texte à envoyer directement au serveur PostgreSQL. Un caractère d'arrêt `null` est automatiquement ajouté.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_put_line()

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\tBonjour le monde\t4.5\n");
      pg_put_line($conn, "4\tAurevoir le monde\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Voir aussi

- pg_end_copy() - Synchronise avec le serveur PostgreSQL

# pg_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_query — Exécute une requête PostgreSQL

### Description

function pg_query(PgSql\Connection `$connection` = ?, string `$query`): PgSql\Result|false

pg_query() exécute la requête `query` sur la base de données spécifiée `connection`. pg_query_params() doit être préféré dans la plupart des cas.

Si une erreur se produit et `false` est retourné, les détails de l'erreur peuvent être récupérés en utilisant la fonction pg_last_error() si la connexion est valide.

> Note: Bien que `connection` puisse être omis, il n'est pas recommandé de le faire, car il peut se révéler difficile de retrouver les bogues dans les scripts.

> Note:

> Auparavant, cette fonction s'appelait pg_exec(). pg_exec() est toujours disponible pour des raisons de compatibilité, mais les utilisateurs sont encouragés à utiliser le nouveau nom.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`query`

  La requête ou les requêtes SQL à être exécutées. Lorsque plusieurs requêtes sont passées à la fonction, elles sont automatiquement exécutées comme étant une transaction, à moins qu'il y ait les commandes BEGIN/COMMIT incluses dans la requête. Cependant, l'utilisation de transactions multiples dans un seul appel de fonction n'est pas recommandée.

  Avertissement

  L'interpolation des chaînes de caractères fournies par l'utilisateur est extrêmement dangereuse et il faut garder en tête l'ensemble des vulnérabilités concernant les injections SQL. Dans la plupart des cas, la fonction pg_query_params() doit être préférée ; il est préférable de passer les valeurs fournies par l'utilisateur comme paramètres, plutôt que de les substituer dans la requête.

  Toutes données utilisateur substituées directement dans la chaîne de la requête doivent être proprement échappées.

### Valeurs de retour

Une instance PgSql\Result en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PgSql\Result instance ; auparavant, une resource était retourné.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_query()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Une erreur s'est produite.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT auteur, email FROM auteurs");
    if (!$result) {
      echo "Une erreur s'est produite.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Auteur: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

Exemple #2 Utilisation de pg_query() avec plusieurs requêtes

    <?php

    $conn = pg_pconnect("dbname=publisher");

    // ces requêtes seront exécutées en tant qu'une seule transaction

    $query = "UPDATE authors SET author=UPPER(author) WHERE id=1;";
    $query .= "UPDATE authors SET author=LOWER(author) WHERE id=2;";
    $query .= "UPDATE authors SET author=NULL WHERE id=3;";

    pg_query($conn, $query);

    ?>

### Voir aussi

- pg_connect() - Établit une connexion PostgreSQL
- pg_pconnect() - Établit une connexion PostgreSQL persistante
- pg_fetch_array() - Lit une ligne de résultat PostgreSQL dans un tableau
- pg_fetch_object() - Lit une ligne de résultat PostgreSQL dans un objet
- pg_num_rows() - Retourne le nombre de lignes PostgreSQL
- pg_affected_rows() - Retourne le nombre de lignes affectées

# pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — Envoie une commande au serveur et attend le résultat, avec les capacités de passer des paramètres séparément de la commande texte SQL

### Description

function pg_query_params(PgSql\Connection `$connection` = ?, string `$query`, array `$params`): PgSql\Result|false

Envoie une commande au serveur et attend le résultat, avec les capacités de passer des paramètres séparément de la commande texte SQL.

pg_query_params() est comme pg_query(), mais offre des fonctionnalités additionnelles : les valeurs des paramètres peuvent être spécifiées séparément de la ligne de commande propre.

Si des paramètres sont utilisés, ils sont référés à $1, $2, etc. dans `query`. Le même paramètre peut survenir plus d'une fois dans la requête `query` ; la même valeur sera utilisée dans ce cas. `params` spécifie les valeurs actuelles des paramètres. Une valeur `null` dans ce tableau signifie que le paramètre correspondant est SQL `null`.

Le principal avantage de pg_query_params() sur pg_query() est que les valeurs des paramètres peuvent être séparées de la requête `query`, par conséquent, on évite les échappements de caractères ennuyeux et source d'erreurs. Contrairement à pg_query(), pg_query_params() permet seulement une seule commande SQL dans la chaîne donnée. (Il peut y avoir des points-virgules à l'intérieur mais pas plus d'une seule commande.)

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`query`

  La requête SQL avec ses paramètres. Elle doit contenir seulement une seule requête. Plusieurs requêtes séparées par des points-virgules ne sont pas autorisées. Si des paramètres sont utilisés, ils sont référés à $1, $2, etc.

  Les valeurs fournies par l'utilisateur doivent toujours être passées comme paramètres, et non interpolées dans la chaîne de requête, où elles peuvent potentiellement former des injections SQL et introduire des bogues lorsque ces données contiennent des guillemets. Si pour une raison quelconque il n'est pas possible d'utiliser de paramètres, il faut s'assurer que les valeurs interpolées sont proprement échappées.

`params`

  Un tableau de valeurs de paramètres pour substituer les variables $1, $2, etc. dans la requête préparée originale. Le nombre d'éléments présents dans le tableau doit concorder avec le nombre de variables à remplacer.

  Les valeurs attendues pour les champs `bytea` ne sont pas supportées comme paramètres. Utiliser plutôt la fonction pg_escape_bytea() ou utiliser les fonctions sur les objets larges.

### Valeurs de retour

Une instance PgSql\Result en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PgSql\Result instance ; auparavant, une resource était retourné.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_query_params()

    <?php
    // Connexion à une base de données nommée "marie"
    $dbconn = pg_connect("dbname=marie");

    // Cherche tous les magasins nommés Joe's Widgets. À noter qu'il n'est pas
    // nécessaire d'échapper la chaîne "Joe's Widgets"
    $result = pg_query_params($dbconn, 'SELECT * FROM magasins WHERE nom = $1', array("Joe's Widgets"));

    // Compare en utilisant pg_query
    $str = pg_escape_string("Joe's Widgets");
    $result = pg_query($dbconn, "SELECT * FROM magasins WHERE nom = '{$str}'");

    ?>

### Voir aussi

- pg_query() - Exécute une requête PostgreSQL

# pg_result_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_error — Lit le message d'erreur associé à un résultat

### Description

function pg_result_error(PgSql\Result `$result`): string|false

pg_result_error() retourne le message d'erreur associé au résultat `result`. Par conséquent, l'utilisateur a des chances d'obtenir un message d'erreur plus approprié que via pg_last_error().

La fonction pg_result_error_field() peut donner bien plus de détails sur les erreurs que pg_result_error().

Comme pg_query() retourne `false` si la requête échoue, il faut utiliser pg_send_query() et pg_get_result() pour récupérer la ressource de résultat.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).

### Valeurs de retour

Retourne une chaîne de caractères. Retourne une chaîne vide s'il n'y a aucune erreur. S'il y a une erreur associée avec le paramètre `result`, `false` sera retourné.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_result_error()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from nexistepas;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Voir aussi

- pg_result_error_field() - Retourne un champ individuel d'un rapport d'erreur
- pg_query() - Exécute une requête PostgreSQL
- pg_send_query() - Exécute une requête PostgreSQL asynchrone
- pg_get_result() - Lit un résultat PostgreSQL asynchrone
- pg_last_error() - Lit le dernier message d'erreur sur la connexion
- pg_last_notice() - Retourne la dernière note du serveur PostgreSQL

# pg_result_error_field

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_result_error_field — Retourne un champ individuel d'un rapport d'erreur

### Description

function pg_result_error_field(PgSql\Result `$result`, int `$field_code`): string|false|null

pg_result_error_field() retourne un des champs détaillés de message d'erreur qui sont associés à l'instance `result`. Le champ d'erreur est spécifié par `field_code`.

Puisque pg_query() et pg_query_params() retournent `false` si la requête échoue, il faut utiliser pg_send_query() et pg_get_result() pour obtenir le jeu de résultats.

En cas de besoin d'obtenir plus d'informations sur l'erreur lors de l'échec des requêtes avec pg_query(), utiliser pg_set_error_verbosity() et pg_last_error() et analyser ensuite le résultat.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`field_code`

  Les valeurs possibles de `field_code` sont : `PGSQL_DIAG_SEVERITY`, `PGSQL_DIAG_SQLSTATE`, `PGSQL_DIAG_MESSAGE_PRIMARY`, `PGSQL_DIAG_MESSAGE_DETAIL`, `PGSQL_DIAG_MESSAGE_HINT`, `PGSQL_DIAG_STATEMENT_POSITION`, `PGSQL_DIAG_INTERNAL_POSITION`, `PGSQL_DIAG_INTERNAL_QUERY`, `PGSQL_DIAG_CONTEXT`, `PGSQL_DIAG_SOURCE_FILE`, `PGSQL_DIAG_SOURCE_LINE` ou `PGSQL_DIAG_SOURCE_FUNCTION`.

### Valeurs de retour

Retourne une chaîne contenant le contenu du champ d'erreur, `null` si le champ n'existe pas ou `false` en cas d'échec.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_result_error_field()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from nexistepas;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error_field($res1, PGSQL_DIAG_SQLSTATE);
    ?>

### Voir aussi

- pg_result_error() - Lit le message d'erreur associé à un résultat

# pg_result_memory_size

(PHP 8 >= 8.4.0)

pg_result_memory_size — Retourne la quantité de mémoire allouée pour un résultat de requête

### Description

function pg_result_memory_size(PgSql\Result `$result`): int

Renvoie la quantité de mémoire, en octets, allouée pour l'instance de PgSql\Result spécifiée. Cette valeur est la même que celle qui serait libérée par pg_free_result().

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).

### Valeurs de retour

Renvoie la quantité de mémoire en octets.

### Exemples

Exemple #1 Exemple de pg_result_memory_size()

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, 'SELECT 1');

    $size = pg_result_memory_size($res);

    var_dump($size);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(3288)

### Voir aussi

- pg_free_result() - Libère la mémoire

# pg_result_seek

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_result_seek — Définit la position de la ligne dans un résultat

### Description

function pg_result_seek(PgSql\Result `$result`, int `$row`): bool

pg_result_seek() définit la position interne de la ligne dans le résultat `result`.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`row`

  Ligne à déplacer la position interne dans le jeu de résultats `result`. Les lignes sont numérotées à partir de zéro.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_result_seek()

    <?php

    // Connexion à la base de données
    $conn = pg_pconnect("dbname=publisher");

    // Exécution de la requête
    $result = pg_query($conn, "SELECT auteur, email FROM auteurs");

    // Déplacement à la troisième ligne (on assume qu'il y a 3 lignes)
    pg_result_seek($result, 2);

    // Récupération de la troisième ligne
    $row = pg_fetch_row($result);

    ?>

### Voir aussi

- pg_fetch_row() - Lit une ligne dans un tableau
- pg_fetch_assoc() - Lit une ligne de résultat PostgreSQL sous forme de tableau associatif
- pg_fetch_array() - Lit une ligne de résultat PostgreSQL dans un tableau
- pg_fetch_object() - Lit une ligne de résultat PostgreSQL dans un objet
- pg_fetch_result() - Retourne les valeurs d'un résultat

# pg_result_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_status — Lit le statut du résultat

### Description

function pg_result_status(PgSql\Result `$result`, int `$mode` = `PGSQL_STATUS_LONG`): string|int

pg_result_status() retourne le statut du résultat `result` ou la commande d'exécution de PostgreSQL associée au résultat.

### Liste de paramètres

`result`
  Une instance PgSql\Result, retourné par pg_query(), pg_query_params(), ou pg_execute() (entre autres).
`mode`

  Soit `PGSQL_STATUS_LONG` pour retourner un statut numérique de `result` ou `PGSQL_STATUS_STRING` pour retourner le tag de la commande de `result`. Si l'argument n'est pas spécifié, `PGSQL_STATUS_LONG` est la valeur par défaut.

### Valeurs de retour

Les valeurs de retour possibles sont `PGSQL_EMPTY_QUERY`, `PGSQL_COMMAND_OK`, `PGSQL_TUPLES_OK`, `PGSQL_TUPLES_CHUNK`, `PGSQL_COPY_OUT`, `PGSQL_COPY_IN`, `PGSQL_BAD_RESPONSE`, `PGSQL_NONFATAL_ERROR` et `PGSQL_FATAL_ERROR` si `PGSQL_STATUS_LONG` est spécifié. Autrement, une chaîne contenant le tag de la commande PostgreSQL est retournée.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `result` attend désormais une instance de PgSql\Result ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_result_status()

    <?php

    // Connexion à la base de données
    $conn = pg_pconnect("dbname=publisher");

    // Exécution de COPY
    $result = pg_query($conn, "COPY auteurs FROM STDIN;");

    // Récupération du statut
    $status = pg_result_status($result);

    // Détermination du statut
    if ($status == PGSQL_COPY_IN)
       echo "Le copiage a eu lieu.";
    else
       echo "Le copiage a échoué.";

    ?>

L'exemple ci-dessus va afficher :

    Le copiage a eu lieu.

### Voir aussi

- pg_connection_status() - Lit le statut de la connexion PostgreSQL

# pg_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_select — Effectue une sélection PostgreSQL

### Description

function pg_select(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions` = [],
int `$flags` = `PGSQL_DML_EXEC`,
int `$mode` = `PGSQL_ASSOC`
): array|string|false

pg_select() sélectionne les enregistrements par `conditions` qui est au format `field=>value`. Lorsque la requête réussit, elle retourne un tableau contenant tous les enregistrements et champs qui vérifient la condition spécifiée par `conditions`.

Si `flags` est spécifié, pg_convert() est appliqué à `conditions` avec les drapeaux fournis.

Si le paramètre `mode` est défini, la valeur de retour sera sous la forme d'un tableau indexé avec `PGSQL_NUM`, un tableau associatif avec `PGSQL_ASSOC` (par défaut), ou les deux avec `PGSQL_BOTH`.

Par défaut pg_select() passe des valeurs brutes. Les valeurs doivent être échappées ou l'option PGSQL_DML_ESCAPE doit être fournie. PGSQL_DML_ESCAPE met des guillemets et échappe les paramètres/identifiants. Par conséquent, les noms de table/colonnes deviennent sensibles à la casse.

Il est à noter que ni l'échappement ni les requêtes préparées peuvent protéger des requêtes LIKE, JSON, Tableaux, Regex, etc. Ces paramètres devraient être traités en fonction de leur contexte. C'est-à-dire échapper/valider les valeurs.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`table_name`

  Nom de la table à partir de laquelle sélectionner les lignes.

`conditions`

  Un array dont les clés sont les noms des champs dans la table `table_name`, et dont les valeurs sont les conditions qu'une ligne doit remplir pour être récupérée. À partir de PHP 8.4.0, lorsqu'un tableau vide est fourni, aucune condition ne sera appliquée. Auparavant, la fonction échouait avec un argument `conditions` vide.

`flags`

  Un nombre quelconque de `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` ou `PGSQL_DML_STRING` combinés. Si `PGSQL_DML_STRING` fait partie des `flags`, alors la chaîne de requête est renvoyée. Lorsque `PGSQL_DML_NO_CONV` ou `PGSQL_DML_ESCAPE` est activé, pg_convert() n'est pas appelée en interne.

`mode`

  Un nombre quelconque de `PGSQL_ASSOC`, `PGSQL_NUM` ou `PGSQL_BOTH`. Si `PGSQL_ASSOC` est défini, la valeur de retour sera un array associatif, avec `PGSQL_NUM`, la valeur de retour sera un array indexé numériquement, et avec `PGSQL_BOTH`, la valeur de retour sera à la fois un array associatif et numériquement indexé.

### Valeurs de retour

Retourne une string si `PGSQL_DML_STRING` est fourni via `flags`, sinon ceci retourne un array en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `conditions` est désormais optionnel.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
7.1.0 | Le paramètre `mode` a été ajouté.

### Exemples

Exemple #1 Exemple avec pg_select()

    <?php
      $db = pg_connect ('dbname=foo');
      // Ceci est sûr quelque peu, car toutes les valeurs sont échappées
      // Cependant PostgreSQL supporte les JSON/Tableaux. Ceux-ci ne sont pas
      // sûrs ni par échappement ni par les requêtes préparées.
      $rec = pg_select($db, 'post_log', $_POST, PG_DML_ESCAPE);
      if ($rec) {
        echo "Lignes lues\n";
        var_dump($rec);
      } else {
        echo "Problème dans les données utilisateur\n";
      }
    ?>

### Voir aussi

- pg_convert() - Convertit des valeurs d'un tableau associatif en une forme convenable pour des requêtes SQL

# pg_send_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_execute — Envoie une requête pour exécuter une requête préparée avec des paramètres donnés, sans attendre le(s) résultat(s)

### Description

function pg_send_execute(PgSql\Connection `$connection`, string `$statement_name`, array `$params`): int|bool

Envoie une requête pour exécuter une requête préparée avec des paramètres donnés, sans attendre le(s) résultat(s).

Cette fonction est similaire à pg_send_query_params(), mais la commande qui sera exécutée est spécifiée en nommant une requête préalablement préparée, au lieu de donner une chaîne en tant que requête. Les paramètres de la fonction sont gérés de la même manière que pg_execute(). Comme pg_execute(), la fonction ne fonctionnera pas sur les versions antérieures à PostgreSQL 7.4.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`statement_name`

  Le nom de la requête préparée à exécuter. Si une chaîne vide est spécifiée (""), alors la requête qui n'est pas nommée est exécutée. Le nom doit avoir été précédemment préparé en utilisant pg_prepare(), pg_send_prepare() ou une commande SQL `PREPARE`.

`params`

  Un tableau de valeurs de paramètres pour substituer les variables $1, $2, etc. dans la requête préparée originale. Le nombre d'éléments présents dans le tableau doit concorder avec le nombre de variables à remplacer.

### Valeurs de retour

Retourne `true` en cas de succès, `false` ou `0` en cas d'échec. Utiliser pg_get_result() pour déterminer le résultat de la requête.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_send_execute()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      // Prépare une requête pour l'exécution
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM magasins WHERE nom = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Exécute la requête préparée. Notez qu'il n'est pas nécessaire d'échapper
      // la chaîne "Joe's Widgets"
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Exécute la même requête préparée, cette fois avec un paramètre différent
      if (!pg_connection_busy($dbconn)) {
        pg_execute($dbconn, "my_query", array("Vêtements Vêtements Vêtements"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### Voir aussi

- pg_prepare() - Envoie une requête au serveur pour créer une instruction préparée avec les paramètres donnés et attend l'exécution
- pg_send_prepare() - Envoie une requête pour créer une requête préparée avec les paramètres donnés, sans attendre la fin de son exécution
- pg_execute() - Exécute une requête préparée PostgreSQL

# pg_send_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_prepare — Envoie une requête pour créer une requête préparée avec les paramètres donnés, sans attendre la fin de son exécution

### Description

function pg_send_prepare(PgSql\Connection `$connection`, string `$statement_name`, string `$query`): int|bool

Envoie une requête pour créer une requête préparée avec les paramètres donnés, sans attendre la fin de son exécution.

Cette fonction est la version asynchrone de pg_prepare() : elle retourne `true` si elle a été capable de répartir la requête et `false` si elle n'a pas été capable. Après un appel réussi, appelez pg_get_result() pour déterminer si le serveur a créé correctement la requête préparée. Les paramètres de la fonction sont gérés de la même manière que pg_execute(). Comme pg_execute(), la fonction ne fonctionnera pas sur les versions antérieures à PostgreSQL 7.4.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`statement_name`

  Le nom à donner à la requête préparée. Il doit être unique à chaque session. Si une chaîne vide est spécifiée ("") alors une requête sans nom est créée, écrasant les requêtes sans nom précédemment définies.

`query`

  La requête SQL avec ses paramètres. Elle doit contenir seulement une seule requête. Plusieurs requêtes séparées par des points-virgules ne sont pas autorisées. Si des paramètres sont utilisés, ils sont référés à $1, $2, etc.

### Valeurs de retour

Retourne `true` en cas de succès, `false` ou `0` en cas d'échec. Utiliser pg_get_result() pour déterminer le résultat de la requête.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple pg_send_prepare()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      // Prépare une requête pour l'exécution
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM magasins WHERE nom = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Exécute la requête préparée. Notez qu'il n'est pas nécessaire d'échapper
      // la chaîne "Joe's Widgets"
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Exécute la même requête préparée, cette fois avec un paramètre différent
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Vêtements Vêtements Vêtements"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### Voir aussi

- pg_connect() - Établit une connexion PostgreSQL
- pg_pconnect() - Établit une connexion PostgreSQL persistante
- pg_execute() - Exécute une requête préparée PostgreSQL
- pg_send_execute() - Envoie une requête pour exécuter une requête préparée avec des paramètres donnés, sans attendre le(s) résultat(s)
- pg_send_query_params() - Envoie une commande et sépare les paramètres au serveur sans attendre le(s) résultat(s)

# pg_send_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_send_query — Exécute une requête PostgreSQL asynchrone

### Description

function pg_send_query(PgSql\Connection `$connection`, string `$query`): int|bool

pg_send_query() envoie une requête ou des requêtes de manière asynchrone à la connexion `connection`. Contrairement à pg_query(), elle peut envoyer plusieurs requêtes à la fois au serveur PostgreSQL et obtenir les résultats un par un en utilisant pg_get_result().

L'exécution du script n'est pas bloquée durant l'exécution des requêtes. Utiliser pg_connection_busy() pour vérifier si la connexion est occupée (c'est-à-dire la requête est en train d'être exécutée). Les requêtes peuvent être annulées avec pg_cancel_query().

Bien que l'on puisse envoyer plusieurs requêtes en même temps, il n'est pas possible d'envoyer plusieurs requêtes sur une connexion occupée. Si une requête est envoyée alors que la connexion est occupée, elle attendra que la requête précédente soit terminée et perdra tous ses résultats.

### Liste de paramètres

`connection`

  La ressource de connexion de la base de données PostgreSQL.

`query`

  La requête ou les requêtes SQL à être exécutées.

  Les données contenues dans la requête doivent être échappées proprement.

### Valeurs de retour

Retourne `true` en cas de succès, `false` ou `0` en cas d'échec. Utiliser pg_get_result() pour déterminer le résultat de la requête.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_send_query()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn,"select * from auteurs; select count(*) from auteurs;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Premier appel de pg_get_result() : $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 a $rows1 enregistrements\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Second appel de pg_get_result() : $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 a $rows2 enregistrements\n";
    ?>

L'exemple ci-dessus va afficher :

    Premier appel de pg_get_result() : Resource id #3
    Resource id #3 a 3 enregistrements

    Second appel de pg_get_result() : Resource id #4
    Resource id #4 a 1 enregistrements

### Voir aussi

- pg_query() - Exécute une requête PostgreSQL
- pg_cancel_query() - Annule une requête asynchrone
- pg_get_result() - Lit un résultat PostgreSQL asynchrone
- pg_connection_busy() - Vérifie si la connexion PostgreSQL est occupée

# pg_send_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_query_params — Envoie une commande et sépare les paramètres au serveur sans attendre le(s) résultat(s)

### Description

function pg_send_query_params(PgSql\Connection `$connection`, string `$query`, array `$params`): int|bool

Envoie une commande et sépare les paramètres au serveur sans attendre le(s) résultat(s).

Cette fonction est équivalente à pg_send_query() à l'exception que les paramètres de la requête peuvent être spécifiés séparément de la chaîne de requête `query`. Les paramètres de la fonction sont gérés de la même manière que pg_execute(). Comme pg_execute(), la fonction ne fonctionnera pas sur les versions antérieures à PostgreSQL 7.4 et elle n'autorise qu'une seule commande par requête.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`query`

  La requête SQL avec ses paramètres. Elle doit contenir seulement une seule requête. Plusieurs requêtes séparées par des points-virgules ne sont pas autorisées. Si des paramètres sont utilisés, ils sont référés à $1, $2, etc.

`params`

  Un tableau de valeurs de paramètres pour substituer les variables $1, $2, etc. dans la requête préparée originale. Le nombre d'éléments présents dans le tableau doit concorder avec le nombre de variables à remplacer.

### Valeurs de retour

Retourne `true` en cas de succès, `false` ou `0` en cas d'échec. Utiliser pg_get_result() pour déterminer le résultat de la requête.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_send_query_params()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      // Avec les paramètres. Notez qu'il n'est pas nécessaire d'échapper la
      // chaîne du paramètre.
      pg_send_query_params($dbconn, 'select count(*) from auteurs where ville = $1', array('Perth'));

      // Compare avec l'utilisation basique de pg_send_query
      $str = pg_escape_string('Perth');
      pg_send_query($dbconn, "select count(*) from auteurs where ville = '{$str}'");
    ?>

### Voir aussi

- pg_send_query() - Exécute une requête PostgreSQL asynchrone

# pg_set_chunked_rows_size

(PHP 8 >= 8.4.0)

pg_set_chunked_rows_size — Définit les résultats de la requête à récupérer en mode chunk

### Description

function pg_set_chunked_rows_size(PgSql\Connection `$connection`, int `$size`): bool

Définit les résultats de la requête à récupérer en mode chunk. La requête retournée par la suite sera divisée en plusieurs morceaux, chacun contenant jusqu'à `size` lignes. Cette fonction doit être appelée avant de récupérer les résultats avec pg_get_result(). Cette fonction n'est disponible que lorsque libpq est en version 17 ou supérieure.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`size`
  Le nombre de lignes à récupérer dans chaque morceau.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Si `size` est inférieur à `1`, une ValueError sera lancée.

### Exemples

Exemple #1 Exemple de pg_result_memory_size()

    <?php

    $conn = pg_connect($conn_str);

    for ($i = 0; $i < 10; $i ++) {
      pg_query($conn, "INSERT INTO users DEFAULT VALUES");
    }

    pg_send_query($conn, "SELECT * FROM users");
    pg_set_chunked_rows_size($conn, 1);

    $result = pg_get_result($conn);
    var_dump(pg_num_rows($result));

    // Pas d'effet après que le résultat soit récupéré
    var_dump(pg_set_chunked_rows_size($conn, 10));

L'exemple ci-dessus va afficher :

    int(1)
    bool(false)

### Voir aussi

- pg_get_result() - Lit un résultat PostgreSQL asynchrone
- pg_result_status() - Lit le statut du résultat

# pg_set_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_set_client_encoding — Choisit l'encodage du client PostgreSQL

### Description

function pg_set_client_encoding(PgSql\Connection `$connection` = ?, string `$encoding`): int

pg_set_client_encoding() fixe l'encodage du client. Elle retourne 0 en cas de succès et -1 en cas d'erreur.

PostgreSQL convertira automatiquement les données dans l'encodage de la base de données vers l'encodage du client.

> Note:

> Auparavant, cette fonction s'appelait pg_setclientencoding().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`encoding`

  L'encodage client demandé. Une de ces constantes : `SQL_ASCII`, `EUC_JP`, `EUC_CN`, `EUC_KR`, `EUC_TW`, `UNICODE`, `MULE_INTERNAL`, `LATINX` (X=1...9), `KOI8`, `WIN`, `ALT`, `SJIS`, `BIG5` ou `WIN1250`.

  La liste exacte des encodages disponibles dépend de la version PostgreSQL, alors vérifiez le manuel PostgreSQL pour une liste plus spécifique.

### Valeurs de retour

Retourne `0` en cas de succès ou `-1` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_set_client_encoding()

    <?php

    $conn = pg_pconnect("dbname=editeur");
    if (!$conn) {
      echo "Une erreur s'est produite.\n";
      exit;
    }

    // Fixe l'encodage du client à UNICODE. Les données seront automatiquement
    // converties de l'encodage serveur à l'encodage client.
    pg_set_client_encoding($conn, "UNICODE");

    $result = pg_query($conn, "SELECT auteur, email FROM auteurs");
    if (!$result) {
      echo "Une erreur s'est produite.\n";
      exit;
    }

    // Écriture de données UTF-8
    while ($row = pg_fetch_row($result)) {
      echo "Auteur: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### Voir aussi

- pg_client_encoding() - Lit l'encodage du client

# pg_set_error_context_visibility

(PHP 8 >= 8.3.0)

pg_set_error_context_visibility — Détermine la visibilité des messages d'erreur du contexte retournés par pg_last_error() et pg_result_error()

### Description

function pg_set_error_context_visibility(PgSql\Connection `$connection`, int `$visibility`): int

Détermine la visibilité des messages d'erreur du contexte retournés par pg_last_error() et pg_result_error()

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`visibility`

  La visibilité requise : `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` ou `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Valeurs de retour

Le niveau de visibilité précédent : `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` ou `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Exemples

Exemple #1 pg_set_error_context_visibility() exemple

    <?php
          $dbconn = pg_connect("dbname=publisher") or die("Impossible de se connecter");
          if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
          }
          pg_set_error_context_visibility($dbconn, PGSQL_SHOW_CONTEXT_ALWAYS);
          $res1 = pg_get_result($dbconn);
          echo pg_result_error($res1);
          ?>

### Voir aussi

- pg_last_error() - Lit le dernier message d'erreur sur la connexion
- pg_result_error() - Lit le message d'erreur associé à un résultat

# pg_set_error_verbosity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_set_error_verbosity — Détermine le degré des messages retournés par pg_last_error() et pg_result_error()

### Description

function pg_set_error_verbosity(PgSql\Connection `$connection` = ?, int `$verbosity`): int|false

Détermine le degré des messages retournés par pg_last_error() et pg_result_error().

pg_set_error_verbosity() fixe le degré d'erreur et retourne le paramètre précédent de la connexion. Avec le mode `PGSQL_ERRORS_TERSE`, les messages retournés incluent la sévérité, le texte primaire et la position seulement ; normalement, cela va entrer sur une seule ligne. Le mode par défaut (`PGSQL_ERRORS_DEFAULT`) produit des messages qui incluent les messages ci-dessus et des détails, des astuces ou les champs en contexte (ces messages peuvent être étendus sur plusieurs lignes). Le mode `PGSQL_ERRORS_VERBOSE` inclut tous les champs disponibles. Le changement du degré des messages n'affecte pas les messages disponibles qui proviennent des résultats déjà existants, mais seulement les messages des résultats créés par la suite.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` n'est pas spécifiée, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`verbosity`

  Le degré de message d'erreur : `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` ou `PGSQL_ERRORS_VERBOSE`.

### Valeurs de retour

Le degré de message d'erreur précédent : `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` ou `PGSQL_ERRORS_VERBOSE`, ou `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_set_error_verbosity()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from nexistepas;");
      }

      pg_set_error_verbosity($dbconn, PGSQL_ERRORS_VERBOSE);
      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Voir aussi

- pg_last_error() - Lit le dernier message d'erreur sur la connexion
- pg_result_error() - Lit le message d'erreur associé à un résultat

# pg_socket

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_socket — Récupère un gestionnaire de lecture seul sur le socket sous-jacent d'une connexion PostgreSQL

### Description

function pg_socket(PgSql\Connection `$connection`): resource|false

La fonction pg_socket() retourne une ressource en lecture seule correspondant au socket sous-jacent de la connexion PostgreSQL fournie.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

Une ressource de socket en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

# pg_socket_poll

(PHP 8 >= 8.4.0)

pg_socket_poll — Scrute la disponibilité en lecture/écriture du socket d'une connexion PostgreSQL

### Description

function pg_socket_poll(
resource `$socket`,
int `$read`,
int `$write`,
int `$timeout` = -1
): int

Scrute le socket d'une connexion PostgreSQL pour déterminer sa disponibilité en lecture et/ou en écriture. Le socket peut être obtenu via pg_socket(). Cette fonction est utile pour mettre en œuvre des flux de requêtes asynchrones non bloquants.

### Liste de paramètres

`socket`
  Une ressource socket obtenue depuis pg_socket().
`read`
  Indique s'il faut vérifier la disponibilité en lecture : `1` pour vérifier, `0` pour ignorer.
`write`
  Indique s'il faut vérifier la disponibilité en écriture : `1` pour vérifier, `0` pour ignorer.
`timeout`
  Le nombre maximum de millisecondes d'attente. La valeur `-1` attend indéfiniment, et `0` n'attend pas du tout.

### Valeurs de retour

Retourne une valeur positive si le socket est prêt, `0` si le délai d'attente a été atteint, ou `-1` en cas d'erreur.

### Voir aussi

- pg_socket() - Récupère un gestionnaire de lecture seul sur le socket sous-jacent d'une connexion PostgreSQL
- pg_consume_input() - Lit l'entrée de la connexion
- pg_send_query() - Exécute une requête PostgreSQL asynchrone

# pg_trace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_trace — Active le suivi d'une connexion PostgreSQL

### Description

function pg_trace(
string `$filename`,
string `$mode` = "w",
?PgSql\Connection `$connection` = `null`,
int `$trace_mode` = 0
): bool

pg_trace() active le suivi des communications entre PHP et le serveur PostgreSQL. Cet historique sera enregistré dans un fichier. Pour comprendre ces lignes, il faut être familier avec le protocole de communication interne à PostgreSQL.

Pour ceux qui ne le sont pas, elles peuvent être utiles pour suivre les requêtes et les erreurs : avec la commande grep '^To backend' trace.log, il sera possible de voir les requêtes réellement envoyées au serveur PostgreSQL. Pour plus d'informations, se référer à la » Documentation PostgreSQL.

### Liste de paramètres

`filename`

  Le chemin complet et le nom du fichier dans lequel le suivi sera enregistré. Comme fopen().

`mode`

  Le mode d'accès optionnel, comme fopen().

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`trace_mode`

  Un mode de trace facultatif avec les constantes suivantes : `PGSQL_TRACE_SUPPRESS_TIMESTAMPS` et `PGSQL_TRACE_REGRESS_MODE`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.3.0 | `trace_mode` a été ajouté.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_trace()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Maintenant /tmp/trace.log contiendra le suivi des communications
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Voir aussi

- fopen() - Ouvre un fichier ou une URL
- pg_untrace() - Termine le suivi d'une connexion PostgreSQL

# pg_transaction_status

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_transaction_status — Retourne le statut de la transaction en cours du serveur

### Description

function pg_transaction_status(PgSql\Connection `$connection`): int

Retourne le statut de la transaction en cours du serveur.

Attention

pg_transaction_status() donnera de mauvais résultats lorsqu'on l'utilise avec un serveur PostgreSQL 7.3 qui a le paramètre `autocommit` désactivé. La fonctionnalité de autocommit est obsolète et n'existe plus dans les versions de serveur plus récentes.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.

### Valeurs de retour

Le statut peut être `PGSQL_TRANSACTION_IDLE` (actuellement inactif), `PGSQL_TRANSACTION_ACTIVE` (une commande est en cours), `PGSQL_TRANSACTION_INTRANS` (inactif, dans un bloc de transaction valide), ou `PGSQL_TRANSACTION_INERROR` (inactif, dans un bloc de transaction en échec). `PGSQL_TRANSACTION_UNKNOWN` est retourné si la connexion est mauvaise. `PGSQL_TRANSACTION_ACTIVE` est retourné seulement si la requête a été envoyée au serveur et que celle-ci n'a pas été encore complétée.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_transaction_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Connexion impossible");
      $stat = pg_transaction_status($dbconn);
      if ($stat === PGSQL_TRANSACTION_UNKNOWN) {
          echo 'Connexion mauvaise';
      } else if ($stat === PGSQL_TRANSACTION_IDLE) {
          echo 'Connexion actuellement inactive';
      } else {
          echo 'Connexion est en cours de transaction';
      }
    ?>

# pg_tty

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_tty — Retourne le nom de TTY associé à la connexion

### Description

function pg_tty(?PgSql\Connection `$connection` = `null`): string

pg_tty() retourne le nom de TTY de la connexion associée à `connection`.

> Note:

> pg_tty() est obsolète, puisque le serveur ne fait plus attention à la configuration TTY, mais demeure pour des raisons de compatibilité.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Une chaîne contenant le débogue TTY de la connexion `connection`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_tty()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Débogue TTY serveur est : " . pg_tty($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_unescape_bytea

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_unescape_bytea — Supprime la protection d'une chaîne de type bytea

### Description

function pg_unescape_bytea(string `$string`): string

pg_unescape_bytea() supprime la protection des caractères de type bytea. Elle retourne la chaîne de caractères déprotégée, pouvant contenir des données binaires.

> Note:

> Lors de l'utilisation d'une commande `SELECT` avec des données de type bytea, PostgreSQL retourne des valeurs octales, préfixées avec des antislashs \ (e.g. \032). Les utilisateurs doivent effectuer la conversion en format binaire eux-mêmes.

### Liste de paramètres

`string`

  Une chaîne de caractères contenant les données bytea PostgreSQL à être converties en chaîne de caractères binaire PHP.

### Valeurs de retour

Une chaîne de caractères contenant les données déprotégées.

### Exemples

Exemple #1 Exemple avec pg_unescape_bytea()

    <?php
      // Connexion à la base de données
      $dbconn = pg_connect('dbname=foo');

      // Récupération des données bytea
      $res = pg_query("SELECT data FROM galerie WHERE nom='Arbres Pin'");
      $raw = pg_fetch_result($res, 'data');

      // Convertit en binaire et envoie au navigateur
      header('Content-type: image/jpeg');
      echo pg_unescape_bytea($raw);
    ?>

### Voir aussi

- pg_escape_bytea() - Protège une chaîne pour insertion dans un champ bytea
- pg_escape_string() - Protège une chaîne de caractères pour une requête SQL

# pg_untrace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_untrace — Termine le suivi d'une connexion PostgreSQL

### Description

function pg_untrace(?PgSql\Connection `$connection` = `null`): true

pg_untrace() termine le suivi d'une connexion PostgreSQL, initiée avec pg_trace().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.2.0 | Le type de retour est maintenant `true`, auparavant il était bool.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_untrace()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Maintenant le suivi des communications est désactivé
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Voir aussi

- pg_trace() - Active le suivi d'une connexion PostgreSQL

# pg_update

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_update — Modifie les lignes d'une table

### Description

function pg_update(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_update() modifie les lignes de la table `table_name`, qui vérifient la condition `conditions` avec `values`.

Si `flags` est spécifié, pg_convert() est appliqué à `values` avec les drapeaux fournis.

Par défaut pg_update() passe des valeurs brutes. Les valeurs doivent être échappées ou le drapeau `PGSQL_DML_ESCAPE` doit être spécifié dans `flags`. `PGSQL_DML_ESCAPE` met des guillemets et échappe les paramètres/identifiants. Par conséquent, les noms de table/colonnes deviennent sensibles à la casse.

Il est à noter que ni l'échappement ni les requêtes préparées peuvent protéger des requêtes LIKE, JSON, Tableaux, Regex, etc. Ces paramètres devraient être traités en fonction de leur contexte. C'est-à-dire échapper/valider les valeurs.

### Liste de paramètres

`connection`
  Une instance PgSql\Connection.
`table_name`

  Le nom de la table dans laquelle les lignes seront mises à jour.

`values`

  Un tableau dont les clés sont les noms des champs dans la table `table_name`, et où les valeurs sont les lignes correspondantes qui seront mises à jour.

`conditions`

  Un tableau dont les clés sont les noms des champs dans la table `table_name`, et où les valeurs sont les conditions à remplir par les lignes pour être mises à jour.

`flags`

  Toutes combinaisons de constantes parmi `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` ou `PGSQL_DML_STRING`. Si `PGSQL_DML_STRING` fait partie du paramètre `flags`, alors la requête sera retournée. Lorsque la constante `PGSQL_DML_NO_CONV` ou la constante `PGSQL_DML_ESCAPE` est définie, aucun appel à la fonction pg_convert() ne sera réalisé en interne.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient. Retourne une chaîne de caractères si `PGSQL_DML_STRING` est passé via le paramètre `flags`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_update()

    <?php
      $db = pg_connect ('dbname=foo');
      $data = array('field1'=>'AA', 'field2'=>'BB');

      // Ceci est sûr quelque peu, car toutes les valeurs sont échappées
      // Cependant PostgreSQL supporte les JSON/Tableaux. Ceux-ci ne sont pas
      // sûrs ni par échappement ni par les requêtes préparées.
      $res = pg_update($db, 'post_log', $_POST, $data);
      if ($res) {
          echo "Les données ont été modifiées : $res\n";
      } else {
          echo "Problème dans les données utilisateur\n";
      }
    ?>

### Voir aussi

- pg_convert() - Convertit des valeurs d'un tableau associatif en une forme convenable pour des requêtes SQL

# pg_version

(PHP 5, PHP 7, PHP 8)

pg_version — Retourne un tableau avec les versions du client, du protocole et du serveur (si disponible)

### Description

function pg_version(?PgSql\Connection `$connection` = `null`): array

pg_version() retourne un tableau avec les versions du client, du protocole et du serveur.

Pour plus d'informations sur le serveur, utiliser pg_parameter_status().

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est `null`, la connexion par défaut est utilisée. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

### Valeurs de retour

Retourne un tableau avec les clés `client`, `protocol` et `server` et valeurs (si disponibles).

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.
8.0.0 | `connection` est désormais nullable.

### Exemples

Exemple #1 Exemple avec pg_version()

    <?php
    $dbconn = pg_connect("host=localhost port=5432 dbname=marie")
       or die("Connexion impossible");

    $v = pg_version($dbconn);

    echo $v['client'];
    ?>

L'exemple ci-dessus va afficher :

    7.4

### Voir aussi

- pg_parameter_status() - Consulte un paramètre de configuration courant du serveur

## Sommaire

- pg_affected_rows — Retourne le nombre de lignes affectées
- pg_cancel_query — Annule une requête asynchrone
- pg_change_password — Change le mot de passe d'un utilisateur PostgreSQL
- pg_client_encoding — Lit l'encodage du client
- pg_close — Termine une connexion PostgreSQL
- pg_connect — Établit une connexion PostgreSQL
- pg_connect_poll — Teste le statut d'une tentative de connexion asynchrone PostgreSQL en cours
- pg_connection_busy — Vérifie si la connexion PostgreSQL est occupée
- pg_connection_reset — Relance la connexion au serveur PostgreSQL
- pg_connection_status — Lit le statut de la connexion PostgreSQL
- pg_consume_input — Lit l'entrée de la connexion
- pg_convert — Convertit des valeurs d'un tableau associatif en une forme convenable pour des requêtes SQL
- pg_copy_from — Insère des lignes dans une table à partir d'un tableau
- pg_copy_to — Copie une table dans un tableau
- pg_dbname — Retourne le nom de la base de données PostgreSQL
- pg_delete — Efface des lignes PostgreSQL
- pg_end_copy — Synchronise avec le serveur PostgreSQL
- pg_escape_bytea — Protège une chaîne pour insertion dans un champ bytea
- pg_escape_identifier — Protège un identifiant pour l'insertion dans un champ texte.
- pg_escape_literal — Protège une requête SQL littérale à insérer dans un champ texte
- pg_escape_string — Protège une chaîne de caractères pour une requête SQL
- pg_execute — Exécute une requête préparée PostgreSQL
- pg_fetch_all — Lit toutes les lignes d'un résultat
- pg_fetch_all_columns — Récupère toutes les lignes d'une colonne de résultats particulière en tant que tableau
- pg_fetch_array — Lit une ligne de résultat PostgreSQL dans un tableau
- pg_fetch_assoc — Lit une ligne de résultat PostgreSQL sous forme de tableau associatif
- pg_fetch_object — Lit une ligne de résultat PostgreSQL dans un objet
- pg_fetch_result — Retourne les valeurs d'un résultat
- pg_fetch_row — Lit une ligne dans un tableau
- pg_field_is_null — Teste si un champ PostgreSQL est à null
- pg_field_name — Retourne le nom d'un champ PostgreSQL
- pg_field_num — Retourne le numéro d'une colonne
- pg_field_prtlen — Retourne la taille imprimée
- pg_field_size — Retourne la taille interne de stockage d'un champ donné
- pg_field_table — Retourne le nom ou l'oid d'une table
- pg_field_type — Retourne le type d'un champ PostgreSQL donné par index
- pg_field_type_oid — Retourne le type ID (OID) pour le numéro du champ correspondant
- pg_flush — Envoie les données de requête sortante sur la connexion
- pg_free_result — Libère la mémoire
- pg_get_notify — Lit le message SQL NOTIFY
- pg_get_pid — Lit l'identifiant de processus du serveur PostgreSQL
- pg_get_result — Lit un résultat PostgreSQL asynchrone
- pg_host — Retourne le nom d'hôte
- pg_insert — Insère un tableau dans une table
- pg_jit — Retourne les informations JIT du serveur
- pg_last_error — Lit le dernier message d'erreur sur la connexion
- pg_last_notice — Retourne la dernière note du serveur PostgreSQL
- pg_last_oid — Retourne l'identifiant de la dernière ligne
- pg_lo_close — Ferme un objet de grande taille PostgreSQL
- pg_lo_create — Crée un objet de grande taille PostgreSQL
- pg_lo_export — Exporte un objet de grande taille vers un fichier
- pg_lo_import — Importe un objet de grande taille depuis un fichier
- pg_lo_open — Ouvre un objet de grande taille PostgreSQL
- pg_lo_read — Lit un objet de grande taille
- pg_lo_read_all — Lit un objet de grande taille en totalité
- pg_lo_seek — Modifie la position dans un objet de grande taille
- pg_lo_tell — Retourne la position courante dans un objet de grande taille PostgreSQL
- pg_lo_truncate — Tronque un objet large
- pg_lo_unlink — Efface un objet de grande taille PostgreSQL
- pg_lo_write — Écrit un objet de grande taille PostgreSQL
- pg_meta_data — Lit les métadonnées de la table PostgreSQL
- pg_num_fields — Retourne le nombre de champs
- pg_num_rows — Retourne le nombre de lignes PostgreSQL
- pg_options — Retourne les options PostgreSQL
- pg_parameter_status — Consulte un paramètre de configuration courant du serveur
- pg_pconnect — Établit une connexion PostgreSQL persistante
- pg_ping — Ping la connexion à la base
- pg_port — Retourne le numéro de port
- pg_prepare — Envoie une requête au serveur pour créer une instruction préparée avec les paramètres donnés et attend l'exécution
- pg_put_copy_data — Envoie des données au serveur durant une opération COPY
- pg_put_copy_end — Signale la fin d'une opération COPY au serveur
- pg_put_line — Envoie une chaîne au serveur PostgreSQL
- pg_query — Exécute une requête PostgreSQL
- pg_query_params — Envoie une commande au serveur et attend le résultat, avec les capacités de passer des paramètres séparément de la commande texte SQL
- pg_result_error — Lit le message d'erreur associé à un résultat
- pg_result_error_field — Retourne un champ individuel d'un rapport d'erreur
- pg_result_memory_size — Retourne la quantité de mémoire allouée pour un résultat de requête
- pg_result_seek — Définit la position de la ligne dans un résultat
- pg_result_status — Lit le statut du résultat
- pg_select — Effectue une sélection PostgreSQL
- pg_send_execute — Envoie une requête pour exécuter une requête préparée avec des paramètres donnés, sans attendre le(s) résultat(s)
- pg_send_prepare — Envoie une requête pour créer une requête préparée avec les paramètres donnés, sans attendre la fin de son exécution
- pg_send_query — Exécute une requête PostgreSQL asynchrone
- pg_send_query_params — Envoie une commande et sépare les paramètres au serveur sans attendre le(s) résultat(s)
- pg_set_chunked_rows_size — Définit les résultats de la requête à récupérer en mode chunk
- pg_set_client_encoding — Choisit l'encodage du client PostgreSQL
- pg_set_error_context_visibility — Détermine la visibilité des messages d'erreur du contexte retournés par pg_last_error et pg_result_error
- pg_set_error_verbosity — Détermine le degré des messages retournés par pg_last_error et pg_result_error
- pg_socket — Récupère un gestionnaire de lecture seul sur le socket sous-jacent d'une connexion PostgreSQL
- pg_socket_poll — Scrute la disponibilité en lecture/écriture du socket d'une connexion PostgreSQL
- pg_trace — Active le suivi d'une connexion PostgreSQL
- pg_transaction_status — Retourne le statut de la transaction en cours du serveur
- pg_tty — Retourne le nom de TTY associé à la connexion
- pg_unescape_bytea — Supprime la protection d'une chaîne de type bytea
- pg_untrace — Termine le suivi d'une connexion PostgreSQL
- pg_update — Modifie les lignes d'une table
- pg_version — Retourne un tableau avec les versions du client, du protocole et du serveur (si disponible)

# La classe PgSql\Connection

(PHP 8 >= 8.1.0)

## Introduction

Une classe complètement opaque qui remplace la resource `pgsql link` à partir de PHP 8.1.0.

## Synopsis de la classe

namespace PgSql;
final class Connection {
}

# La classe PgSql\Result

(PHP 8 >= 8.1.0)

## Introduction

Une classe complètement opaque qui remplace la resource `pgsql result` à partir de PHP 8.1.0.

## Synopsis de la classe

namespace PgSql;
final class Result {
}

# La classe PgSql\Lob

(PHP 8 >= 8.1.0)

## Introduction

Une classe complètement opaque qui remplace la resource `pgsql large object` à partir de PHP 8.1.0.

## Synopsis de la classe

namespace PgSql;
final class Lob {
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Exemples
  - Utilisation simple
  - Utilisation simple
- Fonctions PostgreSQL
  - pg_affected_rows — Retourne le nombre de lignes affectées
  - pg_cancel_query — Annule une requête asynchrone
  - pg_change_password — Change le mot de passe d'un utilisateur PostgreSQL
  - pg_client_encoding — Lit l'encodage du client
  - pg_close — Termine une connexion PostgreSQL
  - pg_connect — Établit une connexion PostgreSQL
  - pg_connect_poll — Teste le statut d'une tentative de connexion asynchrone PostgreSQL en cours
  - pg_connection_busy — Vérifie si la connexion PostgreSQL est occupée
  - pg_connection_reset — Relance la connexion au serveur PostgreSQL
  - pg_connection_status — Lit le statut de la connexion PostgreSQL
  - pg_consume_input — Lit l'entrée de la connexion
  - pg_convert — Convertit des valeurs d'un tableau associatif en une forme convenable pour des requêtes SQL
  - pg_copy_from — Insère des lignes dans une table à partir d'un tableau
  - pg_copy_to — Copie une table dans un tableau
  - pg_dbname — Retourne le nom de la base de données PostgreSQL
  - pg_delete — Efface des lignes PostgreSQL
  - pg_end_copy — Synchronise avec le serveur PostgreSQL
  - pg_escape_bytea — Protège une chaîne pour insertion dans un champ bytea
  - pg_escape_identifier — Protège un identifiant pour l'insertion dans un champ texte.
  - pg_escape_literal — Protège une requête SQL littérale à insérer dans un champ texte
  - pg_escape_string — Protège une chaîne de caractères pour une requête SQL
  - pg_execute — Exécute une requête préparée PostgreSQL
  - pg_fetch_all — Lit toutes les lignes d'un résultat
  - pg_fetch_all_columns — Récupère toutes les lignes d'une colonne de résultats particulière en tant que tableau
  - pg_fetch_array — Lit une ligne de résultat PostgreSQL dans un tableau
  - pg_fetch_assoc — Lit une ligne de résultat PostgreSQL sous forme de tableau associatif
  - pg_fetch_object — Lit une ligne de résultat PostgreSQL dans un objet
  - pg_fetch_result — Retourne les valeurs d'un résultat
  - pg_fetch_row — Lit une ligne dans un tableau
  - pg_field_is_null — Teste si un champ PostgreSQL est à null
  - pg_field_name — Retourne le nom d'un champ PostgreSQL
  - pg_field_num — Retourne le numéro d'une colonne
  - pg_field_prtlen — Retourne la taille imprimée
  - pg_field_size — Retourne la taille interne de stockage d'un champ donné
  - pg_field_table — Retourne le nom ou l'oid d'une table
  - pg_field_type — Retourne le type d'un champ PostgreSQL donné par index
  - pg_field_type_oid — Retourne le type ID (OID) pour le numéro du champ correspondant
  - pg_flush — Envoie les données de requête sortante sur la connexion
  - pg_free_result — Libère la mémoire
  - pg_get_notify — Lit le message SQL NOTIFY
  - pg_get_pid — Lit l'identifiant de processus du serveur PostgreSQL
  - pg_get_result — Lit un résultat PostgreSQL asynchrone
  - pg_host — Retourne le nom d'hôte
  - pg_insert — Insère un tableau dans une table
  - pg_jit — Retourne les informations JIT du serveur
  - pg_last_error — Lit le dernier message d'erreur sur la connexion
  - pg_last_notice — Retourne la dernière note du serveur PostgreSQL
  - pg_last_oid — Retourne l'identifiant de la dernière ligne
  - pg_lo_close — Ferme un objet de grande taille PostgreSQL
  - pg_lo_create — Crée un objet de grande taille PostgreSQL
  - pg_lo_export — Exporte un objet de grande taille vers un fichier
  - pg_lo_import — Importe un objet de grande taille depuis un fichier
  - pg_lo_open — Ouvre un objet de grande taille PostgreSQL
  - pg_lo_read — Lit un objet de grande taille
  - pg_lo_read_all — Lit un objet de grande taille en totalité
  - pg_lo_seek — Modifie la position dans un objet de grande taille
  - pg_lo_tell — Retourne la position courante dans un objet de grande taille PostgreSQL
  - pg_lo_truncate — Tronque un objet large
  - pg_lo_unlink — Efface un objet de grande taille PostgreSQL
  - pg_lo_write — Écrit un objet de grande taille PostgreSQL
  - pg_meta_data — Lit les métadonnées de la table PostgreSQL
  - pg_num_fields — Retourne le nombre de champs
  - pg_num_rows — Retourne le nombre de lignes PostgreSQL
  - pg_options — Retourne les options PostgreSQL
  - pg_parameter_status — Consulte un paramètre de configuration courant du serveur
  - pg_pconnect — Établit une connexion PostgreSQL persistante
  - pg_ping — Ping la connexion à la base
  - pg_port — Retourne le numéro de port
  - pg_prepare — Envoie une requête au serveur pour créer une instruction préparée avec les paramètres donnés et attend l'exécution
  - pg_put_copy_data — Envoie des données au serveur durant une opération COPY
  - pg_put_copy_end — Signale la fin d'une opération COPY au serveur
  - pg_put_line — Envoie une chaîne au serveur PostgreSQL
  - pg_query — Exécute une requête PostgreSQL
  - pg_query_params — Envoie une commande au serveur et attend le résultat, avec les capacités de passer des paramètres séparément de la commande texte SQL
  - pg_result_error — Lit le message d'erreur associé à un résultat
  - pg_result_error_field — Retourne un champ individuel d'un rapport d'erreur
  - pg_result_memory_size — Retourne la quantité de mémoire allouée pour un résultat de requête
  - pg_result_seek — Définit la position de la ligne dans un résultat
  - pg_result_status — Lit le statut du résultat
  - pg_select — Effectue une sélection PostgreSQL
  - pg_send_execute — Envoie une requête pour exécuter une requête préparée avec des paramètres donnés, sans attendre le(s) résultat(s)
  - pg_send_prepare — Envoie une requête pour créer une requête préparée avec les paramètres donnés, sans attendre la fin de son exécution
  - pg_send_query — Exécute une requête PostgreSQL asynchrone
  - pg_send_query_params — Envoie une commande et sépare les paramètres au serveur sans attendre le(s) résultat(s)
  - pg_set_chunked_rows_size — Définit les résultats de la requête à récupérer en mode chunk
  - pg_set_client_encoding — Choisit l'encodage du client PostgreSQL
  - pg_set_error_context_visibility — Détermine la visibilité des messages d'erreur du contexte retournés par pg_last_error et pg_result_error
  - pg_set_error_verbosity — Détermine le degré des messages retournés par pg_last_error et pg_result_error
  - pg_socket — Récupère un gestionnaire de lecture seul sur le socket sous-jacent d'une connexion PostgreSQL
  - pg_socket_poll — Scrute la disponibilité en lecture/écriture du socket d'une connexion PostgreSQL
  - pg_trace — Active le suivi d'une connexion PostgreSQL
  - pg_transaction_status — Retourne le statut de la transaction en cours du serveur
  - pg_tty — Retourne le nom de TTY associé à la connexion
  - pg_unescape_bytea — Supprime la protection d'une chaîne de type bytea
  - pg_untrace — Termine le suivi d'une connexion PostgreSQL
  - pg_update — Modifie les lignes d'une table
  - pg_version — Retourne un tableau avec les versions du client, du protocole et du serveur (si disponible)
- PgSql\Connection — La classe PgSql\Connection
- PgSql\Result — La classe PgSql\Result
- PgSql\Lob — La classe PgSql\Lob

# SQLite3

# Introduction

Support des bases de données SQLite version 3.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

À partir de PHP 7.4.0, » libsqlite ≥ 3.7.4 est requise. Auparavant, la bibliothèque libsqlite intégrée aurait pu être utilisée à la place.

## Installation

Le support de SQLite3 est activé par défaut. Il est possible de le désactiver en utilisant l'option `--without-sqlite3` au moment de la compilation.

Les utilisateurs Windows doivent activer la bibliothèque php_sqlite3.dll pour utiliser cette extension. Cette DLL est incluse avec les distributions de PHP pour Windows.

> Note: Installation supplémentaire sur Windows à partir de PHP 7.4.0

> Afin de faire fonctionner cette extension, quelques bibliothèques DLL doivent être disponibles via le PATH du système Windows. Lisez la F.A.Q intitulée "Comment ajouter mon dossier PHP à mon PATH Windows" pour plus d'informations. Le fait de copier les bibliothèques DLL depuis le dossier PHP dans le dossier système Windows fonctionne également (car le dossier système est par défaut dans le PATH système), mais cette méthode n'est pas recommandée. Cette extension nécessite que les fichiers suivants se trouvent dans le PATH : libsqlite3.dll.

## Configuration à l'exécution

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

Options de configuration Sqlite3
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
sqlite3.extension_dir | "" | `INI_SYSTEM` |
sqlite3.defensive | 1 | `INI_USER` | Disponible à partir de PHP 7.2.17 et 7.3.4 pour libsqlite ≥ 3.26.0. Antérieur à PHP 8.2.0 ce paramètre pouvait seulement être modifié en tant que `INI_SYSTEM`.

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

`sqlite3.extension_dir` string

  Chemin vers le dossier où se trouvent les extensions chargeables pour SQLite.

`sqlite3.defensive` bool

  Lorsque le drapeau défensif est activé, les fonctionnalités du langage qui permettent à du SQL ordinaire de corrompre délibérément les fichiers de la base de données sont désactivées. Ceci interdit d'écrire directement dans le schéma, les tables d’ombre (telles que les tables de données FTS) ou la table virtuelle sqlite_dbpage. Ce paramètre php.ini n'est effectif que pour libsqlite ≥ 3.26.0.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`SQLITE3_ASSOC` (int)
  Spécifie que la méthode Sqlite3Result::fetchArray() doit retourner un tableau indexé par le nom de la colonne dans le jeu de résultats correspondant.
`SQLITE3_NUM` (int)
  Spécifie que la méthode Sqlite3Result::fetchArray() doit retourner un tableau indexé par le numéro de la colonne dans le jeu de résultats correspondant, en commençant à la colonne 0.
`SQLITE3_BOTH` (int)
  Spécifie que la méthode Sqlite3Result::fetchArray() doit retourner un tableau indexé par le nom et le numéro de la colonne dans le jeu de résultats correspondant, en commençant à la colonne 0.
`SQLITE3_INTEGER` (int)
  Représente la classe de stockage INTEGER de SQLite3.
`SQLITE3_FLOAT` (int)
  Représente la classe de stockage REAL (FLOAT) de SQLite3.
`SQLITE3_TEXT` (int)
  Représente la classe de stockage TEXT de SQLite3.
`SQLITE3_BLOB` (int)
  Représente la classe de stockage BLOB de SQLite3.
`SQLITE3_NULL` (int)
  Représente la classe de stockage NULL de SQLite3.
`SQLITE3_OPEN_READONLY` (int)
  Spécifie que la base de données SQLite3 doit être ouverte en lecture seule.
`SQLITE3_OPEN_READWRITE` (int)
  Spécifie que la base de données SQLite3 doit être ouverte en lecture et en écriture.
`SQLITE3_OPEN_CREATE` (int)
  Spécifie que la base de données SQLite3 doit être créée si elle n'existe pas déjà.
`SQLITE3_DETERMINISTIC` (int)
  Spécifie qu'une fonction créée avec SQLite3::createFunction() est déterministe, c'est-à-dire qu'elle retourne toujours le même résultat étant donné les mêmes entrées dans une seule instruction SQL. (disponible à partir de PHP 7.1.4)

# La classe SQLite3

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introduction

Une classe d'interface avec les bases de données SQLite3.

## Synopsis de la classe

class SQLite3 {
/* Constantes */
public const int OK;
public const int DENY;
public const int IGNORE;
public const int CREATE_INDEX;
public const int CREATE_TABLE;
public const int CREATE_TEMP_INDEX;
public const int CREATE_TEMP_TABLE;
public const int CREATE_TEMP_TRIGGER;
public const int CREATE_TEMP_VIEW;
public const int CREATE_TRIGGER;
public const int CREATE_VIEW;
public const int DELETE;
public const int DROP_INDEX;
public const int DROP_TABLE;
public const int DROP_TEMP_INDEX;
public const int DROP_TEMP_TABLE;
public const int DROP_TEMP_TRIGGER;
public const int DROP_TEMP_VIEW;
public const int DROP_TRIGGER;
public const int DROP_VIEW;
public const int INSERT;
public const int PRAGMA;
public const int READ;
public const int SELECT;
public const int TRANSACTION;
public const int UPDATE;
public const int ATTACH;
public const int DETACH;
public const int ALTER_TABLE;
public const int REINDEX;
public const int ANALYZE;
public const int CREATE_VTABLE;
public const int DROP_VTABLE;
public const int FUNCTION;
public const int SAVEPOINT;
public const int COPY;
public const int RECURSIVE;
/* Méthodes */
public function __construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")
public function backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool
public function busyTimeout(int `$milliseconds`): bool
public function changes(): int
public function close(): bool
public function createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool
public function enableExceptions(bool `$enable` = `false`): bool
public static function escapeString(string `$string`): string
public function exec(string `$query`): bool
public function lastErrorCode(): int
public function lastErrorMsg(): string
public function lastInsertRowID(): int
public function loadExtension(string `$name`): bool
public function open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false
public function prepare(string `$query`): SQLite3Stmt|false
public function query(string `$query`): SQLite3Result|false
public function querySingle(string `$query`, bool `$entireRow` = `false`): mixed
public function setAuthorizer(?callable `$callback`): bool
public static function version(): array
}

## Constantes pré-définies

`SQLite3::OK`

`SQLite3::DENY`

`SQLite3::IGNORE`

`SQLite3::CREATE_INDEX`

`SQLite3::CREATE_TABLE`

`SQLite3::CREATE_TEMP_INDEX`

`SQLite3::CREATE_TEMP_TABLE`

`SQLite3::CREATE_TEMP_TRIGGER`

`SQLite3::CREATE_TEMP_VIEW`

`SQLite3::CREATE_TRIGGER`

`SQLite3::CREATE_VIEW`

`SQLite3::DELETE`

`SQLite3::DROP_INDEX`

`SQLite3::DROP_TABLE`

`SQLite3::DROP_TEMP_INDEX`

`SQLite3::DROP_TEMP_TABLE`

`SQLite3::DROP_TEMP_TRIGGER`

`SQLite3::DROP_TEMP_VIEW`

`SQLite3::DROP_TRIGGER`

`SQLite3::DROP_VIEW`

`SQLite3::INSERT`

`SQLite3::PRAGMA`

`SQLite3::READ`

`SQLite3::SELECT`

`SQLite3::TRANSACTION`

`SQLite3::UPDATE`

`SQLite3::ATTACH`

`SQLite3::DETACH`

`SQLite3::ALTER_TABLE`

`SQLite3::REINDEX`

`SQLite3::ANALYZE`

`SQLite3::CREATE_VTABLE`

`SQLite3::DROP_VTABLE`

`SQLite3::FUNCTION`

`SQLite3::SAVEPOINT`

`SQLite3::COPY`

`SQLite3::RECURSIVE`

# SQLite3::backup

(PHP 7 >= 7.4.0, PHP 8)

SQLite3::backup — Sauvegarde une base de données dans une autre base de données

### Description

public function SQLite3::backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool

SQLite3::backup() copie le contenu d'une base de données dans une autre, écrasant le contenu de la base de données de destination. Cela est utile pour créer des sauvegardes de bases de données ou pour copier des bases de données en mémoire vers ou depuis des fichiers persistants.

Astuce

Depuis SQLite 3.27.0 (2019-02-07), il est également possible d'utiliser l'instruction `VACUUM INTO 'file.db';` pour sauvegarder la base de données dans un nouveau fichier.

### Liste de paramètres

`destination`

  Une connexion à une base de données SQLite3 ouverte avec SQLite3::open().

`sourceDatabase`

  Le nom de la base de données est `"main"` pour la base de données principale, `"temp"` pour la base de données temporaire, ou le nom spécifié après le mot-clé `AS` dans une instruction `ATTACH` pour une base de données attachée.

`destinationDatabase`

  Analogue à `sourceDatabase` mais pour la `destination`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Sauvegarder une base de données existante

    <?php
    // $conn est une connexion à une base de données sqlite3 déjà ouverte

    $backup = new SQLite3('backup.sqlite');
    $conn->backup($backup);
    ?>

# SQLite3::busyTimeout

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

SQLite3::busyTimeout — Définit le gestionnaire d'attente de la connexion

### Description

public function SQLite3::busyTimeout(int `$milliseconds`): bool

Définit le gestionnaire d'attente qui patientera tant que la base de données n'est pas verrouillée ou que le délai d'attente ne soit atteint.

### Liste de paramètres

`milliseconds`

  Les millisecondes à attendre. Le fait de définir cette valeur à une valeur inférieure ou égale à zéro désactivera un gestionnaire d'attente précédemment défini.

### Valeurs de retour

Retourne `true` en cas de succès, ou `false` si une erreur survient.

# SQLite3::changes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::changes — Retourne le nombre de lignes modifiées (ou insérées, effacées) par la dernière requête SQL

### Description

public function SQLite3::changes(): int

Retourne le nombre de lignes modifiées (ou insérées, effacées) par la dernière requête SQL.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier correspondant au nombre de lignes modifiées (ou insérées, effacées) par la dernière requête SQL.

### Exemples

Exemple #1 Exemple avec SQLite3::changes()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $query = $db->exec('UPDATE counter SET views=0 WHERE page="test"');
    if ($query) {
        echo 'Nombre de lignes modifiées : ', $db->changes();
    }
    ?>

# SQLite3::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::close — Ferme la connexion avec la base de données

### Description

public function SQLite3::close(): bool

Ferme la connexion avec la base de données.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec SQLite3::close()

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->close();
    ?>

# SQLite3::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::__construct — Instancie un objet SQLite3 et ouvre la base de données SQLite 3

### Description

public function SQLite3::__construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")

Initialise un objet SQLite3 et ouvre une connexion à la base de données SQLite 3. Si le chiffrement a été inclus durant la compilation, alors cette fonction tentera d'utiliser la clé correspondante.

### Liste de paramètres

`filename`

  Chemin vers la base de données SQLite, ou `:memory:` pour utiliser la base de données se trouvant en mémoire vive. Si `filename` est une chaîne vide, une base de données temporaire privée sera créée sur le disque. Cette base de données privée sera automatiquement supprimée dès que la connexion de la base de données est fermée.

`flags`

  Drapeaux optionnels utilisés pour déterminer la manière d'ouverture de la base de données SQLite. Par défaut, l'ouverture s'effectue en utilisant `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE`.

  - `SQLITE3_OPEN_READONLY` : Ouvre la base de données en lecture seule.

  - `SQLITE3_OPEN_READWRITE` : Ouvre la base de données en lecture et en écriture.

  - `SQLITE3_OPEN_CREATE` : Crée la base de données si elle n'existe pas.

`encryptionKey`

  Une clé de chiffrement optionnelle, à utiliser lors du chiffrement/déchiffrement de la base de données SQLite. Si le module de chiffrement SQLite n'est pas installé, ce paramètre n'aura aucun effet.

### Erreurs / Exceptions

Lance une Exception en cas d'échec.

### Historique

Version | Description
--- | ---
7.0.10 | Le `filename` peut maintenant être vide pour utiliser une base de données privée, temporaire sur disque.

### Exemples

Exemple #1 Exemple avec SQLite3::__construct()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (bar TEXT)');
    $db->exec("INSERT INTO foo (bar) VALUES ('This is a test')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());
    ?>

# SQLite3::createAggregate

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createAggregate — Enregistre une fonction PHP à utiliser comme fonction d'agrégation SQLite

### Description

public function SQLite3::createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool

Enregistre une fonction PHP ou une fonction définie par l'utilisateur à utiliser comme fonction d'agrégation SQL, qui sera utilisée dans les requêtes SQL.

### Liste de paramètres

`name`

  Nom de la fonction d'agrégation SQL à créer ou à redéfinir.

`stepCallback`

  Fonction de rappel appelée pour chaque ligne dans le jeu de résultats. La fonction PHP devrait accumuler le résultat et stocker son contexte d'agrégation.

  Cette fonction doit être définie comme :

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`

    `null` pour la première ligne ; sur les lignes suivantes ceci aura la valeur qui a été précédemment retournée par la fonction step ; il est recommandé d'utiliser ceci pour maintenir l'état d'agrégation.

  `rownumber`

    Le numéro de ligne courante.

  `value`

    Le premier argument à passer à l'agrégateur.

  `values`

    Arguments supplémentaires à passer à l'agrégateur.

  La valeur retournée de cette fonction sera utilisée comme argument `context` lors du prochain appel d'une fonction d'étape ou finale.
`finalCallback`

  Fonction de rappel pour agréger les "étapes" de données de chaque ligne. Une fois que toutes les lignes ont été traitées, la fonction sera appelée, prendra les données du contexte d'agrégation et retournera le résultat. La fonction de rappel doit retourner un type compris par SQLite (c.-à-d. un type scalaire).

  Cette fonction doit être définie comme :

  function fini(mixed `$context`, int `$rownumber`): mixed
  `context`

    Contient la valeur de retour du tout dernier appel à la fonction step.

  `rownumber`

    Toujours `0`.

  La valeur de retour de cette fonction sera utilisée comme valeur de retour pour l'agrégation.
`argCount`

  Le nombre d'arguments pris par la fonction d'agrégation SQL. Si ce nombre est négatif, alors la fonction d'agrégation SQL pourra prendre un nombre non défini d'arguments.

### Valeurs de retour

Retourne `true` si la création de l'agrégat a réussi, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple d'une fonction d'agrégation avec max_length

    <?php
    $data = array(
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
       );
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->bindValue(1, $str);
        $insert->execute();
    }
    $insert = null;

    function max_len_step($context, $rownumber, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $rownumber)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->querySingle('SELECT max_len(a) from strings'));
    ?>

L'exemple ci-dessus va afficher :

    int(5)

Dans cet exemple, on crée une fonction agrégative qui va calculer la longueur de la plus grande chaîne de caractères dans une des colonnes de la table. Pour chaque ligne, la fonction `max_len_step` est appelée et le paramètre `$context` est passé. Le paramètre de contexte est comme n'importe quelle autre variable PHP et doit être fixé pour contenir un tableau ou même, un objet. Dans cet exemple, nous l'utilisons pour contenir la taille maximale que nous avons vu jusqu'à présent ; si le paramètre `$string` a une grandeur plus importante que celle courante, on met à jour le contexte pour contenir cette nouvelle taille maximale.

Une fois que toutes les lignes ont été traitées, SQLite appelle la fonction `max_len_finalize` pour déterminer le résultat agrégatif. Ici, nous pourrions effectuer des calculs basés sur les données trouvées dans `$context`. Dans notre exemple simple, nous avons calculé le résultat comme si la requête progressait, alors que nous avons simplement besoin de retourner la valeur de contexte.

Astuce

Il n'est PAS recommandé d'enregistrer une copie des valeurs dans le contexte pour finalement les traiter. Dans ce cas, SQLite utiliserait beaucoup trop de mémoire pour traiter la requête - imaginez la quantité de mémoire nécessaire si un million de lignes étaient enregistrées en mémoire, sachant que chaque ligne contient une chaîne de caractères (32 octets par chaîne).

Astuce

Il est possible d'utiliser SQLite3::createAggregate() pour surcharger les fonctions natives de SQLite.

# SQLite3::createCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

SQLite3::createCollation — Enregistre une fonction PHP pour l'utiliser comme fonction de classement SQL

### Description

public function SQLite3::createCollation(string `$name`, callable `$callback`): bool

Enregistre une fonction PHP ou une fonction définie par l'utilisateur pour l'utiliser comme fonction de classement dans une requête SQL.

### Liste de paramètres

`name`

  Nom de la fonction de classement SQL à créer ou à re-définir.

`callback`

  Le nom d'une fonction PHP ou d'une fonction définie par l'utilisateur à appliquer comme fonction de rappel, définissant le comportement du classement. Elle doit accepter deux arguments et retournera la même chose que la fonction strcmp(), c'est-à-dire qu'elle doit retourner -1, 1, ou 0 si la première chaîne trie avant, après, ou est équivalente à la seconde.

  Cette fonction doit être définie comme :

  function collation(mixed `$value1`, mixed `$value2`): int

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec SQLite3::createCollation()

Enregistre la fonction PHP strnatcmp() comme séquence de classement dans la base de données SQLite3.

    <?php

    $db = new SQLite3(":memory:");
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->createCollation('NATURAL_CMP', 'strnatcmp');

    $defaultSort = $db->query("SELECT col1 FROM test ORDER BY col1");
    $naturalSort = $db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP");

    echo "Par défaut :\n";
    while ($row = $defaultSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    echo "\nNaturel :\n";
    while ($row = $naturalSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    $db->close();

    ?>

L'exemple ci-dessus va afficher :

    Par défaut :
    a1
    a10
    a2

    Naturel :
    a1
    a2
    a10

### Voir aussi

- La documentation sur le classement SQLite : » http://sqlite.org/datatype3.html#collation

# SQLite3::createFunction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createFunction — Enregistre une fonction PHP à utiliser comme fonction scalaire SQL

### Description

public function SQLite3::createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool

Enregistre une fonction PHP ou une fonction utilisateur à utiliser comme fonction scalaire SQL, pour utilisation dans les requêtes SQL.

### Liste de paramètres

`name`

  Nom de la fonction SQL à créer ou à redéfinir.

`callback`

  Le nom de la fonction PHP ou la fonction utilisateur à appliquer comme callback, définissant le comportement de la fonction SQL.

  Cette fonction doit être définie comme :

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    Le premier argument à passer à la fonction SQL.

  `values`

    Arguments supplémentaires à passer à la fonction SQL.

`argCount`

  Nombre d'arguments que la fonction SQL prend. Si ce paramètre est `-1`, la fonction SQL peut prendre n'importe quel nombre d'arguments.

`flags`

  Une conjonction d'opérations de bits d'indicateurs. Actuellement, seul `SQLITE3_DETERMINISTIC` est pris en charge, ce qui spécifie que la fonction retourne toujours le même résultat étant donné les mêmes entrées dans une seule instruction SQL.

### Valeurs de retour

Retourne `true` si la fonction a été créée avec succès, `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.1.4 | Le paramètre `flags` a été ajouté.

### Exemples

Exemple #1 Exemple avec SQLite3::createFunction()

    <?php
    function my_udf_md5($string) {
        return hash('md5', $string);
    }

    $db = new SQLite3('mysqlitedb.db');
    $db->createFunction('my_udf_md5', 'my_udf_md5');

    var_dump($db->querySingle('SELECT my_udf_md5("test")'));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(32) "098f6bcd4621d373cade4e832627b4f6"

# SQLite3::enableExceptions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::enableExceptions — Active le lancement d'exceptions

### Description

public function SQLite3::enableExceptions(bool `$enable` = `false`): bool

Contrôle si l'instance SQLite3 lancera des exceptions ou des avertissements lors d'une erreur.

### Liste de paramètres

`enable`

  Si `true`, l'instance SQLite3, et les instances dérivées de SQLite3Stmt et SQLite3Result, lanceront des exceptions en cas d'erreurs.

  Si `false`, l'instance SQLite3, et les instances dérivées de SQLite3Stmt et SQLite3Result, lanceront des avertissements en cas d'erreurs.

  Pour chacun des modes, le code et message d'erreur, s'il y a, seront disponibles grâce à SQLite3::lastErrorCode() et SQLite3::lastErrorMsg() respectivement.

### Valeurs de retour

Retourne l'ancienne valeur ; `true` si les exceptions étaient activées, `false` sinon.

### Historique

Version | Description
--- | ---
8.3.0 | Appeler SQLite3::enableExceptions() avec `enable` à `false` déclenchera un avertissement `E_DEPRECATED`.

### Exemples

Exemple #1 Exemple avec SQLite3::enableExceptions()

    <?php
    $sqlite = new SQLite3(':memory:');
    try {
        $sqlite->exec('create table foo');
        $sqlite->enableExceptions(true);
        $sqlite->exec('create table bar');
    } catch (Exception $e) {
        echo 'Caught exception: ' . $e->getMessage();
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Warning: SQLite3::exec(): near "foo": syntax error in example.php on line 4
    Caught exception: near "bar": syntax error

# SQLite3::escapeString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::escapeString — Retourne une chaîne nettoyée

### Description

public static function SQLite3::escapeString(string `$string`): string

Retourne une chaîne qui a été nettoyée afin de l'inclure sans risque dans les requêtes SQL.

Avertissement

Cette fonction n'est pas capable de gérer les chaînes binaires !

Pour correctement gérer les champs BLOB qui contiennent des caractères NUL, utiliser plutôt la fonction SQLite3Stmt::bindParam().

### Liste de paramètres

`string`

  La chaîne à nettoyer.

### Valeurs de retour

Retourne une chaîne nettoyée, qui pourra être utilisée sans risque dans une requête SQL.

### Notes

Avertissement

La fonction addslashes() ne doit PAS être utilisée pour protéger la chaîne dans les requêtes SQL ; il serait possible d'observer d'étranges résultats lorsque l'on récupérera les données.

# SQLite3::exec

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::exec — Exécute une requête sur une base de données

### Description

public function SQLite3::exec(string `$query`): bool

Exécute une requête sur une base de données.

> Note: SQLite3 doit parfois créer des » fichiers temporaires lors de l'exécution des requêtes, donc les dossiers respectifs doivent être accessibles en écriture.

### Liste de paramètres

`query`

  La requête SQL à exécuter (typiquement, une requête de type INSERT, UPDATE ou DELETE).

### Valeurs de retour

Retourne `true` si la requête a été exécutée avec succès, `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec SQLite3::exec()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE bar (bar TEXT)');
    ?>

# SQLite3::lastErrorCode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorCode — Retourne le code erreur de la dernière requête SQL ayant échoué

### Description

public function SQLite3::lastErrorCode(): int

Retourne le code erreur de la dernière requête SQL ayant échoué.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier représentant le code erreur de la dernière requête ayant échoué.

# SQLite3::lastErrorMsg

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorMsg — Retourne le message d'erreur, en anglais, de la dernière requête ayant échoué

### Description

public function SQLite3::lastErrorMsg(): string

Retourne le message d'erreur, en anglais, de la dernière requête ayant échoué.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le message d'erreur, en anglais, de la dernière requête ayant échoué.

# SQLite3::lastInsertRowID

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastInsertRowID — Retourne l'identifiant de la ligne correspondant à la dernière requête de type INSERT

### Description

public function SQLite3::lastInsertRowID(): int

Retourne l'identifiant de la ligne correspondant à la dernière requête de type INSERT effectuée sur la base de données.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'identifiant de la ligne correspondant à la dernière requête de type INSERT effectuée sur la base de données. Si aucune requête de type INSERT dans les tables rowid n'a réussi sur cette connexion de base de données, alors SQLite3::lastInsertRowID() retourne `0`.

# SQLite3::loadExtension

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::loadExtension — Tente de charger une bibliothèque d'extension SQLite

### Description

public function SQLite3::loadExtension(string `$name`): bool

Tente de charger une bibliothèque d'extension SQLite.

### Liste de paramètres

`name`

  Le nom de la bibliothèque à charger. L'extension doit se trouver dans le dossier spécifié par l'option de configuration sqlite3.extension_dir.

### Valeurs de retour

Retourne `true` si l'extension a été chargée avec succès, `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec SQLite3::loadExtension()

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->loadExtension('libagg.so');
    ?>

# SQLite3::open

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::open — Ouvre une base de données SQLite

### Description

public function SQLite3::open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void

Ouvre une base de données SQLite 3. Si la compilation inclut le chiffrement, la clé correspondante sera utilisée.

### Liste de paramètres

`filename`

  Chemin vers la base de données SQLite, ou `:memory:` pour utiliser la base de données se trouvant en mémoire vive.

`flags`

  Drapeaux optionnels à utiliser pour déterminer la manière d'ouverture de la base de données SQLite. Par défaut, ce sera `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE`.

  - `SQLITE3_OPEN_READONLY` : Ouvre la base de données en lecture seule.

  - `SQLITE3_OPEN_READWRITE` : Ouvre la base de données en lecture et écriture.

  - `SQLITE3_OPEN_CREATE` : Crée la base de données si elle n'existe pas.

`encryptionKey`

  La clé optionnelle de chiffrement utilisée lors du chiffrement/déchiffrement de la base de données SQLite. Si le module SQLite de chiffrement n'est pas installé, ce paramètre n'aura aucun effet.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec SQLite3::open()

    <?php
    /**
     * Exemple simple qui étend la classe SQLite3 et change les paramètres
     * __construct, puis, utilise la méthode de connexion pour initialiser la
     * base de données.
     */
    class MyDB extends SQLite3
    {
        function __construct()
        {
            $this->open('mysqlitedb.db');
        }
    }

    $db = new MyDB();

    $db->exec('CREATE TABLE foo (bar STRING)');
    $db->exec("INSERT INTO foo (bar) VALUES ('Ceci est un test')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());
    ?>

# SQLite3::openBlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::openBlob — Ouvre un flux de ressource pour lire un BLOB

### Description

public function SQLite3::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false

Ouvre un flux de ressource pour lire ou écrire un BLOB, qui serait sélectionné par :

SELECT `column` FROM `database`.`table` WHERE rowid = `rowid`

> Note: Il n'est pas possible de changer la taille d'un BLOB en écrivant vers le flux. À la place, une déclaration UPDATE doit être exécutée, en utilisant, éventuellement la fonction zeroblob() de SQLite pour définir la taille du BLOB désiré.

### Liste de paramètres

`table`

  Le nom de la table.

`column`

  Le nom de la colonne.

`rowid`

  La ligne ID.

`database`

  Le nom symbolique de la base de données.

`flags`

  Soit `SQLITE3_OPEN_READONLY` ou `SQLITE3_OPEN_READWRITE` pour ouvrir le flux en lecture seule, ou en lecture et écriture, respectivement.

### Valeurs de retour

Retourne une ressource de flux, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.2.0 | Le paramètre `flags` a été ajouté, permettant d'écrire des BLOBs ; précédemment seule la lecture était supportée.

### Exemples

Exemple #1 Exemple avec SQLite3::openBlob()

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES ('Lorem ipsum')");
    $stream = $conn->openBlob('test', 'text', 1);
    echo stream_get_contents($stream);
    fclose($stream); // obligatoire, sinon la ligne suivante échouerait
    $conn->close();
    ?>

L'exemple ci-dessus va afficher :

    Lorem ipsum

Exemple #2 Écrire progressivement un BLOB

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES (zeroblob(36))");
    $stream = $conn->openBlob('test', 'text', 1, 'main', SQLITE3_OPEN_READWRITE);
    for ($i = 0; $i < 3; $i++) {
        fwrite($stream,  "Lorem ipsum\n");
    }
    fclose($stream);
    echo $conn->querySingle("SELECT text FROM test");
    $conn->close();
    ?>

L'exemple ci-dessus va afficher :

    Lorem ipsum
    Lorem ipsum
    Lorem ipsum

# SQLite3::prepare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::prepare — Prépare une requête SQL pour exécution

### Description

public function SQLite3::prepare(string `$query`): SQLite3Stmt|false

Prépare une requête SQL pour exécution et retourne un objet SQLite3Stmt.

### Liste de paramètres

`query`

  La requête SQL à préparer.

### Valeurs de retour

Retourne un objet SQLite3Stmt en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec SQLite3::prepare()

    <?php
    unlink('mysqlitedb.db');
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'Ceci est un test')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray());
    ?>

### Voir aussi

- SQLite3Stmt::paramCount() - Retourne le nombre de paramètres d'une requête préparée
- SQLite3Stmt::bindValue() - Lie la valeur d'un paramètre à une variable de déclaration
- SQLite3Stmt::bindParam() - Lie un paramètre à une variable de déclaration

# SQLite3::query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::query — Exécute une requête SQL

### Description

public function SQLite3::query(string `$query`): SQLite3Result|false

Exécute une requête SQL, et retourne un objet SQLite3Result. Si la requête ne génère pas de résultat (comme les instructions DML), l'objet SQLite3Result retourné n'est pas vraiment utilisable. Utiliser SQLite3::exec() pour ces requêtes à la place.

### Liste de paramètres

`query`

  La requête SQL à exécuter.

### Valeurs de retour

Retourne un objet SQLite3Result, ou `false` si une erreur survient

### Exemples

Exemple #1 Exemple avec SQLite3::query()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $results = $db->query('SELECT bar FROM foo');
    while ($row = $results->fetchArray()) {
        var_dump($row);
    }
    ?>

# SQLite3::querySingle

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::querySingle — Exécute une requête et retourne un seul résultat

### Description

public function SQLite3::querySingle(string `$query`, bool `$entireRow` = `false`): mixed

Exécute une requête et retourne un seul résultat.

### Liste de paramètres

`query`

  La requête SQL à exécuter.

`entireRow`

  Par défaut, cette fonction retourne la valeur de la première colonne retournée par la requête. Si `entireRow` vaut `true`, alors la fonction retournera un tableau contenant toute la première ligne.

### Valeurs de retour

Retourne la valeur de la première colonne du résultat, ou un tableau contenant toute la première ligne (si le paramètre `entireRow` vaut `true`).

Si la requête est valide mais ne retourne aucun résultat, `null` sera retourné si `entireRow` est `false`, sinon un tableau vide est retourné.

Les requêtes invalides retournent `false`.

### Exemples

Exemple #1 Exemple avec SQLite3::querySingle()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    var_dump($db->querySingle('SELECT username FROM user WHERE userid=1'));
    print_r($db->querySingle('SELECT username, email FROM user WHERE userid=1', true));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(5) "Scott"
    Array
    (
        [username] => Scott
        [email] => scott@example.com
    )

# SQLite3::setAuthorizer

(PHP 8)

SQLite3::setAuthorizer — Configure une fonction de rappel à utiliser comme autorisateur pour limiter ce qu'une instruction peut faire

### Description

public function SQLite3::setAuthorizer(?callable `$callback`): bool

Définit une fonction de rappel qui sera appelée par SQLite chaque fois qu'une action est effectuée (lecture, suppression, mise à jour, etc.). Cela est utilisé lors de la préparation d'une instruction SQL à partir d'une source non fiable pour s'assurer que les instructions SQL ne tentent pas d'accéder à des données auxquelles elles ne sont pas autorisées à accéder, ou qu'elles ne tentent pas d'exécuter des instructions malveillantes qui endommagent la base de données. Par exemple, une application peut autoriser un utilisateur à saisir des requêtes SQL arbitraires pour évaluation par une base de données. Mais l'application ne veut pas que l'utilisateur puisse apporter des modifications arbitraires à la base de données. Un autorisateur pourrait alors être mis en place pendant que le SQL saisi par l'utilisateur est préparé pour interdire tout sauf les déclarations SELECT.

La fonction de rappel de l'autorisateur peut être appelée plusieurs fois pour chaque instruction préparée par SQLite. Une requête `SELECT` ou `UPDATE` appellera l'autorisateur pour chaque colonne qui serait lue ou mise à jour.

La fonction de rappel de l'autorisateur est appelée avec jusqu'à cinq paramètres. Le premier paramètre est toujours donné, et est un int (code d'action) correspondant à une constante de `SQLite3`. Les autres paramètres ne sont passés que pour certaines actions. Le tableau suivant décrit les deuxième et troisième paramètres en fonction de l'action :

Liste des codes d'action et des paramètres
Action | Second paramètre | Troisième paramètre
--- | --- | ---
`SQLite3::CREATE_INDEX` | Nom de l'index | Nom de la table
`SQLite3::CREATE_TABLE` | Nom de la table | `null`
`SQLite3::CREATE_TEMP_INDEX` | Nom de l'index | Nom de la table
`SQLite3::CREATE_TEMP_TABLE` | Nom de la table | `null`
`SQLite3::CREATE_TEMP_TRIGGER` | Nom du déclencheur | Nom de la table
`SQLite3::CREATE_TEMP_VIEW` | Nom de la vue | `null`
`SQLite3::CREATE_TRIGGER` | Nom du déclencheur | Nom de la table
`SQLite3::CREATE_VIEW` | Nom de la vue | `null`
`SQLite3::DELETE` | Nom de la table | `null`
`SQLite3::DROP_INDEX` | Nom de l'index | Nom de la table
`SQLite3::DROP_TABLE` | Nom de la table | `null`
`SQLite3::DROP_TEMP_INDEX` | Nom de l'index | Nom de la table
`SQLite3::DROP_TEMP_TABLE` | Nom de la table | `null`
`SQLite3::DROP_TEMP_TRIGGER` | Nom du déclencheur | Nom de la table
`SQLite3::DROP_TEMP_VIEW` | Nom de la vue | `null`
`SQLite3::DROP_TRIGGER` | Nom du déclencheur | Nom de la table
`SQLite3::DROP_VIEW` | Nom de la vue | `null`
`SQLite3::INSERT` | Nom de la table | `null`
`SQLite3::PRAGMA` | Nom Pragma | Le premier argument passé au pragma, ou `null`
`SQLite3::READ` | Nom de la table | Nom de la colonne
`SQLite3::SELECT` | `null` | `null`
`SQLite3::TRANSACTION` | Opération | `null`
`SQLite3::UPDATE` | Nom de la table | Nom de la colonne
`SQLite3::ATTACH` | Filename | `null`
`SQLite3::DETACH` | Nom de la base de données | `null`
`SQLite3::ALTER_TABLE` | Nom Database | Nom de la table
`SQLite3::REINDEX` | Nom de l'index | `null`
`SQLite3::ANALYZE` | Nom de la table | `null`
`SQLite3::CREATE_VTABLE` | Nom de la table | Nom du module
`SQLite3::DROP_VTABLE` | Nom de la table | Nom du module
`SQLite3::FUNCTION` | `null` | Nom de la fonction
`SQLite3::SAVEPOINT` | Opération | Nom du point de sauvegarde
`SQLite3::RECURSIVE` | `null` | `null`

Le quatrième paramètre sera le nom de la base de données (`"main"`, `"temp"`, etc.) si applicable.

Le cinquième paramètre de la fonction de rappel de l'autorisateur est le nom du déclencheur ou de la vue le plus interne qui est responsable de la tentative d'accès ou `null` si cette tentative d'accès est directement issue du code SQL de niveau supérieur.

Lorsque la fonction de rappel retourne `SQLite3::OK`, cela signifie que l'opération demandée est acceptée. Lorsque la fonction de rappel retourne `SQLite3::DENY`, l'appel qui a déclenché l'autorisateur échouera avec un message d'erreur expliquant que l'accès est refusé.

Si le code d'action est `SQLite3::READ` et que la fonction de rappel retourne `SQLite3::IGNORE`, alors l'instruction préparée est construite pour substituer une valeur `null` à la place de la colonne de la table qui aurait été lue si `SQLite3::OK` avait été retourné. Le retour de `SQLite3::IGNORE` peut être utilisé pour refuser à un utilisateur non fiable l'accès à des colonnes individuelles d'une table.

Lorsqu'une table est référencée par un `SELECT` mais aucune valeur de colonne n'est extraite de cette table (par exemple dans une requête comme `"SELECT count(*) FROM table"`), alors la fonction de rappel de l'autorisateur est invoquée une fois pour cette table avec un nom de colonne qui est une chaîne vide.

Si le code d'action est `SQLite3::DELETE` et que la fonction de rappel retourne `SQLite3::IGNORE`, alors l'opération DELETE se poursuit mais l'optimisation de troncature est désactivée et toutes les lignes sont supprimées individuellement.

Seul un seul autorisateur peut être en place sur une connexion de base de données à la fois. Chaque appel à SQLite3::setAuthorizer() remplace l'appel précédent. Désactivez l'autorisateur en installant un rappel `null`. L'autorisateur est désactivé par défaut.

La fonction de rappel de l'autorisateur ne doit pas faire quoi que ce soit qui modifiera la connexion de base de données qui a invoqué la fonction de rappel de l'autorisateur.

Il est à noter que l'autorisateur n'est appelé que lorsqu'une instruction est préparée, pas lorsqu'elle est exécutée.

Plus de détails peuvent être trouvés dans la » documentation de SQLite3.

### Liste de paramètres

`callback`

  Le callable à appeler.

  Si `null` est passé, cela désactivera le rappel de l'autorisateur actuel.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Cette méthode ne lance aucune erreur, mais si un autorisateur est activé et retourne une valeur invalide, la préparation de l'instruction lancera une erreur (ou une exception, selon l'utilisation de la méthode SQLite3::enableExceptions()).

### Exemples

Exemple #1 Exemple de SQLite3::setAuthorizer()

Ceci n'autorise que l'accès en lecture, et seules certaines colonnes de la table `users` seront retournées. Les autres colonnes seront remplacées par `null`.

    <?php
    $db = new SQLite3('data.sqlite');
    $db->exec('CREATE TABLE users (id, name, password);');
    $db->exec('INSERT INTO users VALUES (1, \'Pauline\', \'Snails4eva\');');

    $allowed_columns = ['id', 'name'];

    $db->setAuthorizer(function (int $action, ...$args) use ($allowed_columns) {
        if ($action === SQLite3::READ) {
            list($table, $column) = $args;

            if ($table === 'users' && in_array($column, $allowed_columns)) {
                return SQLite3::OK;
            }

            return SQLite3::IGNORE;
        }

        return SQLite3::DENY;
    });

    print_r($db->querySingle('SELECT * FROM users WHERE id = 1;'));

L'exemple ci-dessus va afficher :

    Array
    (
        [id] => 1
        [name] => Pauline
        [password] =>
    )

# SQLite3::version

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::version — Retourne la version de la bibliothèque SQLite3

### Description

public static function SQLite3::version(): array

Retourne la version de la bibliothèque SQLite3.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif contenant les clés "versionString" et "versionNumber".

### Exemples

Exemple #1 Exemple avec SQLite3::version()

    <?php
    print_r(SQLite3::version());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [versionString] => 3.5.9
        [versionNumber] => 3005009
    )

## Sommaire

- SQLite3::backup — Sauvegarde une base de données dans une autre base de données
- SQLite3::busyTimeout — Définit le gestionnaire d'attente de la connexion
- SQLite3::changes — Retourne le nombre de lignes modifiées (ou insérées, effacées) par la dernière requête SQL
- SQLite3::close — Ferme la connexion avec la base de données
- SQLite3::__construct — Instancie un objet SQLite3 et ouvre la base de données SQLite 3
- SQLite3::createAggregate — Enregistre une fonction PHP à utiliser comme fonction d'agrégation SQLite
- SQLite3::createCollation — Enregistre une fonction PHP pour l'utiliser comme fonction de classement SQL
- SQLite3::createFunction — Enregistre une fonction PHP à utiliser comme fonction scalaire SQL
- SQLite3::enableExceptions — Active le lancement d'exceptions
- SQLite3::escapeString — Retourne une chaîne nettoyée
- SQLite3::exec — Exécute une requête sur une base de données
- SQLite3::lastErrorCode — Retourne le code erreur de la dernière requête SQL ayant échoué
- SQLite3::lastErrorMsg — Retourne le message d'erreur, en anglais, de la dernière requête ayant échoué
- SQLite3::lastInsertRowID — Retourne l'identifiant de la ligne correspondant à la dernière requête de type INSERT
- SQLite3::loadExtension — Tente de charger une bibliothèque d'extension SQLite
- SQLite3::open — Ouvre une base de données SQLite
- SQLite3::openBlob — Ouvre un flux de ressource pour lire un BLOB
- SQLite3::prepare — Prépare une requête SQL pour exécution
- SQLite3::query — Exécute une requête SQL
- SQLite3::querySingle — Exécute une requête et retourne un seul résultat
- SQLite3::setAuthorizer — Configure une fonction de rappel à utiliser comme autorisateur pour limiter ce qu'une instruction peut faire
- SQLite3::version — Retourne la version de la bibliothèque SQLite3

# La classe SQLite3Exception

(PHP 8 >= 8.3.0)

## Introduction

Représente une exception spécifique à SQLite3.

## Synopsis de la classe

class SQLite3Exception extends Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe SQLite3Stmt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introduction

La classe qui représente les commandes préparées pour une base de données SQLite3.

## Synopsis de la classe

class SQLite3Stmt {
/* Méthodes */
private function __construct(SQLite3 `$sqlite3`, string `$query`)
public function bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool
public function clear(): bool
public function close(): true
public function execute(): SQLite3Result|false
public function getSQL(bool `$expand` = `false`): string|false
public function paramCount(): int
public function readOnly(): bool
public function reset(): bool
}

# SQLite3Stmt::bindParam

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindParam — Lie un paramètre à une variable de déclaration

### Description

public function SQLite3Stmt::bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool

Lie un paramètre à une variable de déclaration.

Attention

Avant PHP 7.2.14 et 7.3.0, respectivement, SQLite3Stmt::reset() doit être appelé après le premier appel à SQLite3Stmt::execute() si la valeur liée devrait être correctement mise à jour lors des appels suivants à SQLite3Stmt::execute(). Si SQLite3Stmt::reset() n'est pas appelé, les valeurs liées ne seront pas modifiées, même si la valeur assignée à la variable passée à SQLite3Stmt::bindParam() a été modifiée, ou SQLite3Stmt::bindParam() a été appelé une nouvelle fois.

### Liste de paramètres

`param`
  Soit une chaîne de caractères (pour les paramètres nommés) ou un entier (pour les paramètres positionnels) identifiant la variable de déclaration à laquelle la valeur doit être liée. Si un paramètre nommé ne débute pas avec un caractère "deux points" (`:`) ou un arobase (`@`), "deux points" (`:`) seront automatiquement préfixés. Les paramètres positionnels commencent avec `1`.
`var`

  Le paramètre à lier à la variable de déclaration.

`type`

  Le type de données du paramètre à lier.

  - `SQLITE3_INTEGER` : La valeur est un entier signé, stocké sur 1, 2, 3, 4, 6, ou 8 octets, suivant la grandeur de la valeur.

  - `SQLITE3_FLOAT` : La valeur est un nombre à virgule flottante, stocké sur 8 octets.

  - `SQLITE3_TEXT` : La valeur est un texte, stocké en utilisant l'encodage de la base de données (UTF-8, UTF-16BE ou UTF-16-LE).

  - `SQLITE3_BLOB` : La valeur est un BLOB, stocké exactement de la façon dont il a été fourni.

  - `SQLITE3_NULL` : La valeur est la valeur NULL.

  À partir de PHP 7.0.7, si `type` est omis, il est automatiquement détecté depuis le type de `var` : booléen et entier sont traités comme `SQLITE3_INTEGER`, nombre décimal comme `SQLITE3_FLOAT`, `null` comme `SQLITE3_NULL` et tous les autres comme `SQLITE3_TEXT`. Auparavant, si `type` était omis, il était par défaut `SQLITE3_TEXT`.

  > Note:

  > Si `var` est `null`, c'était toujours traité comme `SQLITE3_NULL`, peu importe le `type` fourni.

### Valeurs de retour

Retourne `true` si le paramètre est lié à la variable de déclaration, `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.4.0 | `param` supporte désormais la notation `@param`.

### Exemples

Exemple #1 Utilisation de SQLite3Stmt::bindParam()

Cet exemple montre comment une déclaration préparée unique avec un seul paramètre lié peut être utilisée pour insérer plusieurs lignes avec des valeurs différentes.

    <?php
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE foo (bar TEXT)");

    $stmt = $db->prepare("INSERT INTO foo VALUES (:bar)");
    $stmt->bindParam(':bar', $bar, SQLITE3_TEXT);

    $bar = 'baz';
    $stmt->execute();

    $bar = 42;
    $stmt->execute();

    $res = $db->query("SELECT * FROM foo");
    while (($row = $res->fetchArray(SQLITE3_ASSOC))) {
        var_dump($row);
    }
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }
    array(1) {
      ["bar"]=>
      string(2) "42"
    }

### Voir aussi

- SQLite3Stmt::bindValue() - Lie la valeur d'un paramètre à une variable de déclaration
- SQLite3::prepare() - Prépare une requête SQL pour exécution

# SQLite3Stmt::bindValue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindValue — Lie la valeur d'un paramètre à une variable de déclaration

### Description

public function SQLite3Stmt::bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool

Lie la valeur d'un paramètre à une variable de déclaration.

Attention

Avant PHP 7.2.14 et 7.3.0, respectivement, une fois que la déclaration a été exécutée SQLite3Stmt::reset() doit être appelé pour pouvoir changer la valeur des paramètres liés.

### Liste de paramètres

`param`
  Soit une chaîne de caractères (pour les paramètres nommés) ou un entier (pour les paramètres positionnels) identifiant la variable de déclaration à laquelle la valeur doit être liée. Si un paramètre nommé ne débute pas avec un caractère "deux points" (`:`) ou un arobase (`@`), "deux points" (`:`) seront automatiquement préfixés. Les paramètres positionnels commencent avec `1`.
`value`

  La valeur à lier à la variable de déclaration.

`type`

  Le type de données de la valeur à lier.

  - `SQLITE3_INTEGER` : La valeur est un entier signé, stocké sur 1, 2, 3, 4, 6, ou 8 octets, suivant la grandeur de la valeur.

  - `SQLITE3_FLOAT` : La valeur est un nombre à virgule flottante, stocké sur 8 octets.

  - `SQLITE3_TEXT` : La valeur est un texte, stocké en utilisant l'encodage de la base de données (UTF-8, UTF-16BE ou UTF-16-LE).

  - `SQLITE3_BLOB` : La valeur est un BLOB, stocké exactement de la façon dont il a été fourni.

  - `SQLITE3_NULL` : La valeur est la valeur NULL.

  À partir de PHP 7.0.7, si `type` est omis, il est automatiquement détecté depuis le type de `value` : booléen et entier sont traités comme `SQLITE3_INTEGER`, nombre décimal comme `SQLITE3_FLOAT`, `null` comme `SQLITE3_NULL` et tous les autres comme `SQLITE3_TEXT`. Auparavant, si `type` était omis, il était par défaut `SQLITE3_TEXT`.

  > Note:

  > Si `value` est `null`, c'était toujours traité comme `SQLITE3_NULL`, peu importe le `type` fourni.

### Valeurs de retour

Retourne `true` si la valeur a été liée à la variable de déclaration, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.4.0 | `param` supporte désormais la notation `@param`.

### Exemples

Exemple #1 Exemple avec SQLite3Stmt::bindValue()

    <?php
    $db = new SQLite3(':memory:');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'Ceci est un test')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray(SQLITE3_ASSOC));
    ?>

L'exemple ci-dessus va afficher :

    array(1) {
      ["bar"]=>
      string(16) "Ceci est un test"
    }

### Voir aussi

- SQLite3Stmt::bindParam() - Lie un paramètre à une variable de déclaration
- SQLite3::prepare() - Prépare une requête SQL pour exécution

# SQLite3Stmt::clear

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::clear — Supprime tous les paramètres actuellement liés

### Description

public function SQLite3Stmt::clear(): bool

Supprime tous les paramètres actuellement liés (les définit en tant que `null`).

Attention

Cette méthode doit être utilisée avec SQLite3Stmt::reset(). Si utilisée seule, tout appel à SQLite3Stmt::bindValue() ou SQLite3Stmt::bindParam() n'aura aucun effet et tous les paramètres liés auront comme valeur `null`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si tous les paramètres actuellement liés ont été supprimés, `false` si une erreur survient.

# SQLite3Stmt::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::close — Ferme une requête préparée

### Description

public function SQLite3Stmt::close(): true

Ferme une requête préparée.

> Note: Il est à noter que tous les SQLite3Result qui ont été récupérés en exécutant cette instruction seront invalidés lorsque l'instruction sera fermée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Une Error est levée si la méthode est appelée sur un objet non initialisé.

### Historique

Version | Description
--- | ---
8.1.0 | Cette méthode lève désormais une exception Error si l'objet n'est pas correctement initialisé. Auparavant, elle retournait `false`.

# SQLite3Stmt::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::__construct — Construit un objet SQLite3Stmt

### Description

private function SQLite3Stmt::__construct(SQLite3 `$sqlite3`, string `$query`)

Les instances de SQLite3Stmt sont créées par SQLite3::prepare().

### Liste de paramètres

`sqlite3`

`query`

# SQLite3Stmt::execute

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::execute — Exécute une requête préparée

### Description

public function SQLite3Stmt::execute(): SQLite3Result|false

Exécute une requête préparée et retourne un objet représentant le jeu de résultats.

Attention

Les objets de jeu de résultats récupérés par l'appel de cette méthode sur le même objet d'instruction ne sont pas indépendants, mais partagent plutôt la même structure sous-jacente. Par conséquent, il est recommandé d'appeler SQLite3Result::finalize(), avant d'appeler de nouveau SQLite3Stmt::execute() sur le même objet d'instruction.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet SQLite3Result si la requête préparée a été exécutée avec succès, ou `false` si une erreur survient.

### Voir aussi

- SQLite3::prepare() - Prépare une requête SQL pour exécution
- SQLite3Stmt::bindValue() - Lie la valeur d'un paramètre à une variable de déclaration
- SQLite3Stmt::bindParam() - Lie un paramètre à une variable de déclaration

# SQLite3Stmt::getSQL

(PHP 7 >= 7.4.0, PHP 8)

SQLite3Stmt::getSQL — Récupère le SQL d'une instruction préparée

### Description

public function SQLite3Stmt::getSQL(bool `$expand` = `false`): string|false

Récupère le SQL d'une instruction préparée. Si `expand` est `false`, le SQL non modifié est récupéré. Si `expand` est `true`, tous les paramètres de requête sont remplacés par leurs valeurs liées, ou par un `NULL` SQL, s'ils ne sont pas encore liés.

### Liste de paramètres

`expand`

  S'il faut récupérer le code SQL étendu. Passer `true` n'est supporté qu'à partir de libsqlite 3.14.

### Valeurs de retour

Retourne le SQL de la déclaration préparée, ou `false` si une erreur survient.

### Erreurs / Exceptions

Si `expand` est `true`, mais que la version de libsqlite est inférieure à 3.14, une erreur de niveau `E_WARNING` ou une Exception est émise, en accord avec SQLite3::enableExceptions().

### Exemples

Exemple #1 Inspecter le SQL étendu

    <?php
    $db = new SQLite3(':memory:');
    $stmt = $db->prepare("SELECT :a, ?, :c");
    $stmt->bindValue(':a', 'foo');
    $answer = 42;
    $stmt->bindParam(2, $answer);
    var_dump($stmt->getSQL(true));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(24) "SELECT 'foo', '42', NULL"

# SQLite3Stmt::paramCount

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::paramCount — Retourne le nombre de paramètres d'une requête préparée

### Description

public function SQLite3Stmt::paramCount(): int

Retourne le nombre de paramètres d'une requête préparée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de paramètres d'une requête préparée.

### Voir aussi

- SQLite3::prepare() - Prépare une requête SQL pour exécution

# SQLite3Stmt::readOnly

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SQLite3Stmt::readOnly — Détermine si une instruction est définitivement en lecture seule

### Description

public function SQLite3Stmt::readOnly(): bool

Détermine si une instruction est définitivement en lecture seule. Une instruction est considérée comme en lecture seule, si elle ne fait aucun changement direct au contenu du fichier de base de données. Il est à noter que les fonctions SQL définies par l'utilisateur peuvent indirectement changer la base de données en tant qu'effet secondaire.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'instruction est définitivement en lecture seule, `false` sinon.

# SQLite3Stmt::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::reset — Réinitialise une requête préparée

### Description

public function SQLite3Stmt::reset(): bool

Réinitialise une requête préparée, de manière à retrouver son état initial, avant exécution. Toutes les liaisons resteront intactes après cette opération.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si la requête préparée a été correctement réinitialisée, ou `false` si une erreur survient.

## Sommaire

- SQLite3Stmt::bindParam — Lie un paramètre à une variable de déclaration
- SQLite3Stmt::bindValue — Lie la valeur d'un paramètre à une variable de déclaration
- SQLite3Stmt::clear — Supprime tous les paramètres actuellement liés
- SQLite3Stmt::close — Ferme une requête préparée
- SQLite3Stmt::__construct — Construit un objet SQLite3Stmt
- SQLite3Stmt::execute — Exécute une requête préparée
- SQLite3Stmt::getSQL — Récupère le SQL d'une instruction préparée
- SQLite3Stmt::paramCount — Retourne le nombre de paramètres d'une requête préparée
- SQLite3Stmt::readOnly — Détermine si une instruction est définitivement en lecture seule
- SQLite3Stmt::reset — Réinitialise une requête préparée

# La classe SQLite3Result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introduction

Une classe qui représente les résultats d'une base de données SQLite 3.

## Synopsis de la classe

class SQLite3Result {
/* Méthodes */
private function __construct()
public function columnName(int `$column`): string|false
public function columnType(int `$column`): int|false
public function fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false
public function finalize(): true
public function numColumns(): int
public function reset(): bool
}

# SQLite3Result::columnName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnName — Retourne le nom d'une colonne

### Description

public function SQLite3Result::columnName(int `$column`): string|false

Retourne le nom de la colonne identifiée par le paramètre `column`. Il est à noter que le nom de la colonne de résultat est la valeur de la clause `AS` pour cette colonne, s'il y a une clause `AS`. S'il n'y a pas de clause alors le nom de la colonne est non spécifié et peut changer d'une version de libsqlite3 à une autre.

### Liste de paramètres

`column`

  Le numéro de la colonne, en commençant par 0.

### Valeurs de retour

Retourne le nom de la colonne identifiée par le paramètre `column`, ou `false` si la colonne n'existe pas.

# SQLite3Result::columnType

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnType — Retourne le type d'une colonne

### Description

public function SQLite3Result::columnType(int `$column`): int|false

Retourne le type de la colonne identifiée par le paramètre `column`.

### Liste de paramètres

`column`

  Le numéro de la colonne, en commençant par 0.

### Valeurs de retour

Retourne le type de données de la colonne identifiée par `column` (l'un de `SQLITE3_INTEGER`, `SQLITE3_FLOAT`, `SQLITE3_TEXT`, `SQLITE3_BLOB`, ou `SQLITE3_NULL`), ou `false` si la colonne n'existe pas.

# SQLite3Result::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::__construct — Construit un SQLite3Result

### Description

private function SQLite3Result::__construct()

Les instances de SQLite3Result sont créées par SQLite3::query() et SQLite3Stmt::execute().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# SQLite3Result::fetchArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::fetchArray — Récupère un jeu de résultats sous la forme d'un tableau associatif

### Description

public function SQLite3Result::fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false

Récupère un jeu de résultats sous la forme d'un tableau associatif ou indexé numériquement, ou les deux. Par défaut, ce sera les deux.

### Liste de paramètres

`mode`

  Contrôle la façon dont la prochaine ligne doit être retournée à la fonction appelante. Cette valeur peut être `SQLITE3_ASSOC`, `SQLITE3_NUM`, ou `SQLITE3_BOTH`.

  - `SQLITE3_ASSOC` : Retourne un tableau indexé par le nom de la colonne, tel que retourné dans le jeu de résultats correspondant.

  - `SQLITE3_NUM` : Retourne un tableau indexé par le numéro de la colonne, tel que retourné dans le jeu de résultats, en commençant par la colonne 0.

  - `SQLITE3_BOTH` : Retourne un tableau indexé par le nom et le numéro de la colonne, tel que retourné par le jeu de résultats, en commençant par la colonne 0.

### Valeurs de retour

Retourne une ligne du jeu de résultats, sous la forme d'un tableau associatif, ou sous la forme d'un tableau indexé, ou les deux. Retourne `false` s'il n'y a plus de lignes.

Les types des valeurs du tableau retourné sont mappés à partir de types SQLite3 comme suit : les entiers sont mappés à int s'ils s'insèrent dans la plage `PHP_INT_MIN`.. `PHP_INT_MAX`, et à string sinon. Les nombres à virgule sont mappés à float, les valeurs `null` sont mappées à null, et les chaînes et les objets BLOB sont mappés à string.

# SQLite3Result::finalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::finalize — Ferme un jeu de résultats

### Description

public function SQLite3Result::finalize(): true

Ferme un jeu de résultats.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Une Error est levée si la méthode est appelée sur un objet non initialisé.

### Historique

Version | Description
--- | ---
8.1.0 | Cette méthode lève désormais une exception Error si l'objet n'est pas correctement initialisé. Auparavant, elle retournait `false`.

# SQLite3Result::numColumns

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::numColumns — Retourne le nombre de colonnes du jeu de résultats

### Description

public function SQLite3Result::numColumns(): int

Retourne le nombre de colonnes du jeu de résultats.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de colonnes du jeu de résultats.

# SQLite3Result::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::reset — Repositionne le pointeur sur la première ligne du jeu de résultats

### Description

public function SQLite3Result::reset(): bool

Repositionne le pointeur sur la première ligne du jeu de résultats.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si le jeu de résultats a été réinitialisé avec succès, `false` si une erreur survient.

## Sommaire

- SQLite3Result::columnName — Retourne le nom d'une colonne
- SQLite3Result::columnType — Retourne le type d'une colonne
- SQLite3Result::__construct — Construit un SQLite3Result
- SQLite3Result::fetchArray — Récupère un jeu de résultats sous la forme d'un tableau associatif
- SQLite3Result::finalize — Ferme un jeu de résultats
- SQLite3Result::numColumns — Retourne le nombre de colonnes du jeu de résultats
- SQLite3Result::reset — Repositionne le pointeur sur la première ligne du jeu de résultats

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- SQLite3 — La classe SQLite3
  - SQLite3::backup — Sauvegarde une base de données dans une autre base de données
  - SQLite3::busyTimeout — Définit le gestionnaire d'attente de la connexion
  - SQLite3::changes — Retourne le nombre de lignes modifiées (ou insérées, effacées) par la dernière requête SQL
  - SQLite3::close — Ferme la connexion avec la base de données
  - SQLite3::__construct — Instancie un objet SQLite3 et ouvre la base de données SQLite 3
  - SQLite3::createAggregate — Enregistre une fonction PHP à utiliser comme fonction d'agrégation SQLite
  - SQLite3::createCollation — Enregistre une fonction PHP pour l'utiliser comme fonction de classement SQL
  - SQLite3::createFunction — Enregistre une fonction PHP à utiliser comme fonction scalaire SQL
  - SQLite3::enableExceptions — Active le lancement d'exceptions
  - SQLite3::escapeString — Retourne une chaîne nettoyée
  - SQLite3::exec — Exécute une requête sur une base de données
  - SQLite3::lastErrorCode — Retourne le code erreur de la dernière requête SQL ayant échoué
  - SQLite3::lastErrorMsg — Retourne le message d'erreur, en anglais, de la dernière requête ayant échoué
  - SQLite3::lastInsertRowID — Retourne l'identifiant de la ligne correspondant à la dernière requête de type INSERT
  - SQLite3::loadExtension — Tente de charger une bibliothèque d'extension SQLite
  - SQLite3::open — Ouvre une base de données SQLite
  - SQLite3::openBlob — Ouvre un flux de ressource pour lire un BLOB
  - SQLite3::prepare — Prépare une requête SQL pour exécution
  - SQLite3::query — Exécute une requête SQL
  - SQLite3::querySingle — Exécute une requête et retourne un seul résultat
  - SQLite3::setAuthorizer — Configure une fonction de rappel à utiliser comme autorisateur pour limiter ce qu'une instruction peut faire
  - SQLite3::version — Retourne la version de la bibliothèque SQLite3
- SQLite3Exception — La classe SQLite3Exception
- SQLite3Stmt — La classe SQLite3Stmt
  - SQLite3Stmt::bindParam — Lie un paramètre à une variable de déclaration
  - SQLite3Stmt::bindValue — Lie la valeur d'un paramètre à une variable de déclaration
  - SQLite3Stmt::clear — Supprime tous les paramètres actuellement liés
  - SQLite3Stmt::close — Ferme une requête préparée
  - SQLite3Stmt::__construct — Construit un objet SQLite3Stmt
  - SQLite3Stmt::execute — Exécute une requête préparée
  - SQLite3Stmt::getSQL — Récupère le SQL d'une instruction préparée
  - SQLite3Stmt::paramCount — Retourne le nombre de paramètres d'une requête préparée
  - SQLite3Stmt::readOnly — Détermine si une instruction est définitivement en lecture seule
  - SQLite3Stmt::reset — Réinitialise une requête préparée
- SQLite3Result — La classe SQLite3Result
  - SQLite3Result::columnName — Retourne le nom d'une colonne
  - SQLite3Result::columnType — Retourne le type d'une colonne
  - SQLite3Result::__construct — Construit un SQLite3Result
  - SQLite3Result::fetchArray — Récupère un jeu de résultats sous la forme d'un tableau associatif
  - SQLite3Result::finalize — Ferme un jeu de résultats
  - SQLite3Result::numColumns — Retourne le nombre de colonnes du jeu de résultats
  - SQLite3Result::reset — Repositionne le pointeur sur la première ligne du jeu de résultats

# Driver Microsoft SQL Server pour PHP

# Introduction

L'extension SQLSRV permet d'accéder à un serveur de base de données Microsoft SQL et SQL Azure. La version 3.0 du pilote supporte SQL Server, en commençant par SQL Server 2005, et incluant SQL Server 2012 et SQL Server 2012 LocalDB (pour plus d'informations à propos de LocalDB, voir » le pilote PHP pour le support de SQL Server pour LocalDB et » SQL Server 2012 Express LocalDB.)

L'extension SQLSRV est supportée par Microsoft et est disponible au téléchargement ici : » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx. SQL Server 2012 LocalDB peut être téléchargé ici : » http://go.microsoft.com/fwlink/?LinkID=237665.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

L'extension SQLSRV peut être utilisée sur les systèmes d'exploitation suivants :

- Windows Vista Service Pack 2 ou supérieur
- Windows Server 2008 Service Pack 2 ou supérieur
- Windows Server 2008 R2
- Windows 7

L'extension SQLSRV requiert que le client natif Microsoft SQL Server 2012 soit installé sur la même machine que celle qui exécute PHP. Si le client natif Microsoft SQL Server 2012 n'est pas installé, cliquez sur le lien approprié ci-dessous pour le télécharger :

- » Téléchargement du paquet x86
- » Téléchargement du paquet x64

Le téléchargement SQLSRV est livré avec 8 pilotes, dont 4 dédiés au support de PDO.

La version la plus récente du pilote est disponible au téléchargement ici : » téléchargement de SQLSRV.

Pour plus d'informations sur les pré-requis SQLSRV, se reporter au chapitre sur les » pré-requis du système SQLSRV.

## Installation

L'extension SQLSRV est activée en ajoutant la bibliothèque DLL appropriée dans le dossier d'extensions PHP et en ajoutant l'entrée correspondante dans le fichier php.ini. Le téléchargement de SQLSRV est fourni avec 8 pilotes, dont 4 dédiés au support de PDO.

La version la plus récente du pilote est disponible au téléchargement ici : » téléchargement de SQLSRV.

Pour plus d'informations sur les pré-requis SQLSRV, se reporter au chapitre sur les » pré-requis du système SQLSRV.

Depuis la version 4.0, l'extension SQLSRV n'est compatible que lorsque PHP 7.0 fonctionne sur Linux ou Windows.

## Configuration à l'exécution

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

La table suivante liste les options de configuration disponibles pour l'extension. Pour plus d'informations sur ces options, se reporter au chapitre sur la » gestion des erreurs et alertes SQLSRV.

Options de configuration SQLSRV
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
sqlsrv.WarningsReturnAsErrors | 1 (`true`) | `INI_ALL` | Disponible depuis SQLSRV 1.0
sqlsrv.LogSubsystems | 0 | `INI_ALL` | Disponible depuis SQLSRV 1.0
sqlsrv.LogSeverity | 1 | `INI_ALL` | Disponible depuis SQLSRV 1.0

## Types de ressources

## Ressource de connexion

Une ressource de connexion retournée par la fonction sqlsrv_connect().

## Ressource de requête

Une ressource de requête retournée par la fonction sqlsrv_query() ou la fonction sqlsrv_prepare().

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`SQLSRV_FETCH_ASSOC` (int)
  Force sqlsrv_fetch_array() à retourner un tableau associatif quand il est passé en paramètre.
`SQLSRV_FETCH_NUMERIC` (int)
  Force sqlsrv_fetch_array() à retourner un tableau indexé numériquement quand il est passé en paramètre.
`SQLSRV_FETCH_BOTH` (int)
  Force sqlsrv_fetch_array() à retourner un tableau associatif et un tableau indexé numériquement quand il est passé en paramètre (comportement par défaut).
`SQLSRV_ERR_ALL` (int)
  Force sqlsrv_errors() à retourner les erreurs et avertissements quand il est passé en paramètre (comportement par défaut).
`SQLSRV_ERR_ERRORS` (int)
  Force sqlsrv_errors() à retourner seulement les erreurs (pas les avertissements) quand il est passé en paramètre.
`SQLSRV_ERR_WARNINGS` (int)
  Force sqlsrv_errors() à retourner seulement les avertissements (pas les erreurs) quand il est passé en paramètre.
`SQLSRV_LOG_SYSTEM_ALL` (int)
  Active les logs de tous les sous-systèmes quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_LOG_SYSTEM_CONN` (int)
  Active les logs de toute l'activité des connexions quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_LOG_SYSTEM_INIT` (int)
  Active les logs de toute l'activité des initialisations quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_LOG_SYSTEM_OFF` (int)
  Désactive les logs de tous les sous-systèmes quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_LOG_SYSTEM_STMT` (int)
  Active les logs des requêtes quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_LOG_SYSTEM_UTIL` (int)
  Active les logs des erreurs de fonction quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_LOG_SEVERITY_ALL` (int)
  Active les logs des erreurs, avertissements et notes quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_LOG_SEVERITY_ERROR` (int)
  Spécifie que les erreurs seront enregistrées quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_LOG_SEVERITY_NOTICE` (int)
  Spécifie que les notes seront enregistrées quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_LOG_SEVERITY_WARNING` (int)
  Spécifie que les avertissements seront enregistrées quand il est passé à la fonction sqlsrv_configure() comme paramère.
`SQLSRV_NULLABLE_YES` (int)
  Indique qu'une colonne peut être nulle.
`SQLSRV_NULLABLE_NO` (int)
  Indique qu'une colonne ne peut pas être nulle.
`SQLSRV_NULLABLE_UNKNOWN` (int)
  Indique s'il est connu qu'une colonne est nulle.
`SQLSRV_PARAM_IN` (int)
  Indique un paramètre d'entrée quand il est passé à la fonction sqlsrv_query() ou à la fonction sqlsrv_prepare().
`SQLSRV_PARAM_INOUT` (int)
  Indique un paramètre d'entrée ou de sortie quand il est passé à la fonction sqlsrv_query() ou à la fonction sqlsrv_prepare().
`SQLSRV_PARAM_OUT` (int)
  Indique un paramètre de sortie quand il est passé à la fonction sqlsrv_query() ou à la fonction sqlsrv_prepare().
`SQLSRV_PHPTYPE_INT` (int)
  Spécifie une donnée de type entier PHP. Pour plus d'informations, voir » Comment spécifier les types PHP.
`SQLSRV_PHPTYPE_DATETIME` (int)
  Spécifie une donnée de type datetime (date et heure) PHP. Pour plus d'informations, voir » Comment spécifier les types PHP.
`SQLSRV_PHPTYPE_FLOAT` (int)
  Spécifie une donnée de type nombre à virgule flottante PHP. Pour plus d'informations, voir » Comment spécifier les types PHP.
`SQLSRV_PHPTYPE_STREAM` (int)
  Spécifie une donnée de type flux de PHP. Cette constante fonctionne comme une fonction et accepte une constante encodée. Voir les constantes SQLSRV_ENC_*. Pour plus d'informations, se reporter à » Comment spécifier les types PHP.
`SQLSRV_PHPTYPE_STRING` (int)
  Spécifie une donnée de type chaîne de caractères PHP. Cette constante fonctionne comme une fonction et accepte une constante encodée. Voir les constantes SQLSRV_ENC_*. Pour plus d'informations, se reporter à » Comment spécifier les types PHP.
`SQLSRV_ENC_BINARY` (int)
  Spécifie que la donnée est retournée sous la forme d'un flux brute d'octets depuis le serveur sans y effectuer un encodage ou une transformation. Pour plus d'informations, se reporter à » Comment spécifier les types PHP.
`SQLSRV_ENC_CHAR` (int)
  Les données sont retournées sous la forme de caractères sur 8 octets, tels que spécifiés dans la page de code des paramètres régionaux Windows définis sur le système. Tout caractère multioctet ou caractères qui ne correspondent pas à cette page de code seront substitués par un point d'interrogation sur un octet (?). C'est l'encodage par défaut. Pour plus d'informations, se reporter à » Comment spécifier les types PHP.
`SQLSRV_SQLTYPE_BIGINT` (int)
  Décrit le type de données bigint SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_BINARY` (int)
  Décrit le type de données binaire SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_BIT` (int)
  Décrit le type de données bit SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_CHAR` (int)
  Décrit le type de données caractère SQL Server. Cette constante fonctionne comme une fonction et accepte un paramètre indiquant le nombre de caractères. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_DATE` (int)
  Décrit le type de données date SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_DATETIME` (int)
  Décrit le type de données datetime SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_DATETIME2` (int)
  Décrit le type de données datetime2 SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_DATETIMEOFFSET` (int)
  Décrit le type de données datetimeoffset SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_DECIMAL` (int)
  Décrit le type de données décimal. Cette constante fonctionne comme une fonction et accepte 2 paramètres indiquant (dans l'ordre) la précision et l'échelle. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_FLOAT` (int)
  Décrit le type de données nombre à virgule flottante SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_IMAGE` (int)
  Décrit le type de données image SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_INT` (int)
  Décrit le type de données entier SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_MONEY` (int)
  Décrit le type de données monnaie SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_NCHAR` (int)
  Décrit le type de données nchar SQL Server. Cette constante fonctionne comme une fonction et accepte un seul paramètre indiquant le nombre de caractères. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_NUMERIC` (int)
  Décrit le type de données numérique SQL Server. Cette constante fonctionne comme une fonction et accepte 2 paramètres (dans l'ordre), la précision et l'échelle. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_NVARCHAR` (int)
  Décrit le type de données nvarchar SQL Server. Cette constante fonctionne comme une fonction et accepte un seul paramètre indiquant le nombre de caractères. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_NVARCHAR`('max') (int)
  Décrit le type de données nvarchar(MAX) SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_NTEXT` (int)
  Décrit le type de données ntext SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_REAL` (int)
  Décrit le type de données réelle SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_SMALLDATETIME` (int)
  Décrit le type de données smalldatetime SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_SMALLINT` (int)
  Décrit le type de données smallint SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_SMALLMONEY` (int)
  Décrit le type de données smallmoney SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_TEXT` (int)
  Décrit le type de données texte SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_TIME` (int)
  Décrit le type de données time SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_TIMESTAMP` (int)
  Décrit le type de données timestamp SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_TINYINT` (int)
  Décrit le type de données tinyint SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_UNIQUEIDENTIFIER` (int)
  Décrit le type de données uniqueidentifier SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_UDT` (int)
  Décrit le type de données UDT SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_VARBINARY` (int)
  Décrit le type de données varbinary SQL Server. Cette constante fonctionne comme une fonction et accepte un seul paramètre indiquant le nombre d'octets. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_VARBINARY`('max') (int)
  Décrit le type de données varbinary(MAX) SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_VARCHAR` (int)
  Décrit le type de données varchar SQL Server. Cette constante fonctionne comme une fonction et accepte un seul paramètre indiquant le nombre de caractères. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_VARCHAR`('max') (int)
  Décrit le type de données varchar(MAX) SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_SQLTYPE_XML` (int)
  Décrit le type de données XML SQL Server. Pour plus d'informations, se reporter à » Comment spécifier les types SQL.
`SQLSRV_TXN_READ_UNCOMMITTED` (int)
  Indique un niveau d'isolation de la transaction à READ UNCOMMITTED. Cette valeur est utilisée pour définir le niveau de l'isolation de la transaction dans le tableau $connectionOptions passé à la fonction sqlsrv_connect().
`SQLSRV_TXN_READ_COMMITTED` (int)
  Indique un niveau d'isolation de la transaction à READ COMMITTED. Cette valeur est utilisée pour définir le niveau de l'isolation de la transaction dans le tableau $connectionOptions passé à la fonction sqlsrv_connect().
`SQLSRV_TXN_REPEATABLE_READ` (int)
  Indique un niveau d'isolation de la transaction à REPEATABLE READ. Cette valeur est utilisée pour définir le niveau de l'isolation de la transaction dans le tableau $connectionOptions passé à la fonction sqlsrv_connect().
`SQLSRV_TXN_SNAPSHOT` (int)
  Indique un niveau d'isolation de la transaction à SNAPSHOT. Cette valeur est utilisée pour définir le niveau de l'isolation de la transaction dans le tableau $connectionOptions passé à la fonction sqlsrv_connect().
`SQLSRV_TXN_READ_SERIALIZABLE` (int)
  Indique un niveau d'isolation de la transaction à SERIALIZABLE. Cette valeur est utilisée pour définir le niveau de l'isolation de la transaction dans le tableau $connectionOptions passé à la fonction sqlsrv_connect().
`SQLSRV_CURSOR_FORWARD` (int)
  Indique un curseur de type "suivant uniquement". Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_CURSOR_STATIC` (int)
  Indique un curseur de type "statique". Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_CURSOR_DYNAMIC` (int)
  Indique un curseur de type "dynamique". Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_CURSOR_KEYSET` (int)
  Indique un curseur de type "keyset". Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_CURSOR_BUFFERED` (int)
  Crée une requête de curseur côté client. Cela permet d'accéder aux lignes dans n'importe quel ordre. Pour des informations quant à son utilisation, se reporter à la section sur la » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_SCROLL_NEXT` (int)
  Spécifie la ligne à sélectionner dans un jeu de résultats. Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_SCROLL_PRIOR` (int)
  Spécifie la ligne à sélectionner dans un jeu de résultats. Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_SCROLL_FIRST` (int)
  Spécifie la ligne à sélectionner dans un jeu de résultats. Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_SCROLL_LAST` (int)
  Spécifie la ligne à sélectionner dans un jeu de résultats. Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_SCROLL_ABSOLUTE` (int)
  Spécifie la ligne à sélectionner dans un jeu de résultats. Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.
`SQLSRV_SCROLL_RELATIVE` (int)
  Spécifie la ligne à sélectionner dans un jeu de résultats. Pour plus d'informations, se reporter à la section sur » la spécification d'un type de curseur et la sélection de lignes.

# Fonctions SQLSRV

# sqlsrv_begin_transaction

(No version information available, might only be in Git)

sqlsrv_begin_transaction — Commence une transaction

### Description

function sqlsrv_begin_transaction(resource `$conn`): bool

La transaction commençant avec la fonction sqlsrv_begin_transaction() inclut toutes les requêtes qui sont exécutées après l'appel à la fonction sqlsrv_begin_transaction() et avant l'appel à la fonction sqlsrv_rollback() ou la fonction sqlsrv_commit(). Une transaction explicite peut être commencée et validée (ou annulée) en utilisant ces fonctions au lieu d'exécuter les requêtes SQL qui commencent et valident/annulent les transactions. Pour plus d'informations, se reporter aux » transactions SQLSRV.

### Liste de paramètres

`conn`
  La ressource de connexion retournée par un appel à la fonction sqlsrv_connect().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec sqlsrv_begin_transaction()

L'exemple suivant montre la façon d'utiliser la fonction sqlsrv_begin_transaction() avec les fonctions sqlsrv_commit() et sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Commence la transaction. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Initialise les valeurs des paramètres. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Exécute la première requête. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
              VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Exécute la seconde requête. */
    $sql2 = "UPDATE InventoryTable
              SET Quantity = (Quantity - ?)
              WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Si les deux requêtes sont exécutées avec succès, on valide la transaction. */
    /* Sinon, on annule la transaction. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaction validée.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaction annulée.<br />";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- sqlsrv_commit() - Valide une transaction commencée avec la fonction sqlsrv_begin_transaction
- sqlsrv_rollback() - Annule une transaction qui a été commencée grâce à la fonction sqlsrv_begin_transaction

# sqlsrv_cancel

(No version information available, might only be in Git)

sqlsrv_cancel — Annule une requête

### Description

function sqlsrv_cancel(resource `$stmt`): bool

Annule une requête. Tous les résultats associés avec la requête qui n'ont pas été utilisés seront supprimés. Après l'appel à la fonction sqlsrv_cancel(), la requête spécifiée peut être ré-exécutée si elle a été créée avec la fonction sqlsrv_prepare(). L'appel à la fonction sqlsrv_cancel() n'est pas nécessaire si tous les résultats associés avec la requête ont été utilisés.

### Liste de paramètres

`stmt`
  La ressource de la requête à annuler.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec sqlsrv_cancel()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Sales FROM Table_1";

    $stmt = sqlsrv_prepare( $conn, $sql);

    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    if( sqlsrv_execute( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    $salesTotal = 0;
    $count = 0;

    while( ($row = sqlsrv_fetch_array( $stmt)) && $salesTotal <=100000)
    {
         $qty = $row[0];
         $price = $row[1];
         $salesTotal += ( $price * $qty);
         $count++;
    }

    echo "$count ventes ont représenté les premiers $$salesTotal de revenus.<br />";

    // Annule les résultats restants. La requête peut être ré-utilisée.
    sqlsrv_cancel( $stmt);
    ?>

### Notes

La principale différence entre la fonction sqlsrv_cancel() et la fonction sqlsrv_free_stmt() est qu'une ressource de requête annulée avec la fonction sqlsrv_cancel() peut être ré-utilisée si elle a été créée avec la fonction sqlsrv_prepare(). Une ressource de requête annulée avec la fonction sqlsrv_free_statement() ne peut plus être ré-exécutée.

### Voir aussi

- sqlsrv_free_stmt() - Libère toutes les ressources de la requête spécifiée
- sqlsrv_prepare() - Prépare une requête pour exécution

# sqlsrv_client_info

(No version information available, might only be in Git)

sqlsrv_client_info — Retourne les informations sur le client ainsi que sur la connexion spécifiée

### Description

function sqlsrv_client_info(resource `$conn`): array

Retourne des informations sur le client ainsi que sur la connexion spécifiée.

### Liste de paramètres

`conn`
  La connexion sur laquelle on souhaite des informations.

### Valeurs de retour

Retourne un tableau associatif dont les clés sont décrites dans la table ci-dessous. Retourne `false` sinon.

Tableau retourné par sqlsrv_client_info
Clé | Description
--- | ---
DriverDllName | SQLNCLI10.DLL
DriverODBCVer | version ODBC (xx.yy)
DriverVer | version de la bibliothèque DLL native client du serveur (10.5.xxx)
ExtensionVer | version de la bibliothèque php_sqlsrv.dll (2.0.xxx.x)

### Exemples

Exemple #1 Exemple avec sqlsrv_client_info()

    <?php
    $serverName = "serverName\sqlexpress";
    $connOptions = array("UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connOptions );

    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    if( $client_info = sqlsrv_client_info( $conn)) {
        foreach( $client_info as $key => $value) {
            echo $key.": ".$value."<br />";
        }
    } else {
        echo "Erreur lors de la récupération des informations clientes.<br />";
    }
    ?>

### Voir aussi

- sqlsrv_server_info() - Retourne des informations sur le serveur

# sqlsrv_close

(No version information available, might only be in Git)

sqlsrv_close — Clôture une connexion établie et libère les ressources associées

### Description

function sqlsrv_close(resource `$conn`): bool

Clôture une connexion établie et libère les ressources associées.

### Liste de paramètres

`conn`
  La connexion à fermer.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec sqlsrv_close()

    <?php
    $nomServeur = "serverName\sqlexpres";
    $connOptions = array("UID"=>"nomutilisateur", "PWD"=>"motdepasse", "Database"=>"nomschema");
    $conn = sqlsrv_connect( $nomServeur, $connOptions );
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    //-------------------------------------
    // Effectuer les operations sur la base de données
    //-------------------------------------

    // Et on ferme la connexion.
    sqlsrv_close( $conn );
    ?>

### Voir aussi

- sqlsrv_connect() - Ouvre une connexion sur une base de données Microsoft SQL Server

# sqlsrv_commit

(No version information available, might only be in Git)

sqlsrv_commit — Valide une transaction commencée avec la fonction sqlsrv_begin_transaction()

### Description

function sqlsrv_commit(resource `$conn`): bool

Valide une transaction commencée par la fonction sqlsrv_begin_transaction(). La connexion est retournée en mode auto-commit après l'appel à la fonction sqlsrv_commit(). La transaction validée inclut toutes les requêtes exécutées après un appel à la fonction sqlsrv_begin_transaction(). Les transactions doivent commencer, être validées ou être annulées en utilisant ces fonctions au lieu d'utiliser des requêtes déclarant le début ou l'annulation d'une transaction. Pour plus d'informations, se reporter aux » transactions SQLSRV.

### Liste de paramètres

`conn`
  La connexion sur laquelle la transaction va être validée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec sqlsrv_commit()

L'exemple suivant montre la façon d'utiliser la fonction sqlsrv_commit() avec sqlsrv_begin_transaction() et sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Début de la transaction. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Initialisation des paramètres. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Définition et exécution de la première requête. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Définition et exécution de la seconde requête. */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Si les deux requêtes ont réussi, on commit la transaction. */
    /* Sinon, on l'annule. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaction validée.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaction annulée.<br />";
    }
    ?>

### Voir aussi

- sqlsrv_begin_transaction() - Commence une transaction
- sqlsrv_rollback() - Annule une transaction qui a été commencée grâce à la fonction sqlsrv_begin_transaction

# sqlsrv_configure

(No version information available, might only be in Git)

sqlsrv_configure — Modifie la configuration du gestionnaire d'erreurs et d'historisations du driver

### Description

function sqlsrv_configure(string `$setting`, mixed `$value`): bool

Modifie la configuration du gestionnaire d'erreurs et d'historisations du driver.

### Liste de paramètres

`setting`
  Le nom de la configuration à définir. Les valeurs possibles sont "WarningsReturnAsErrors", "LogSubsystems", et "LogSeverity".
`value`

  La valeur de la configuration à définir. La table suivante montre les valeurs possibles :

  Options de configuration du gestionnaire d'erreurs et d'historisations
  Configurations | Options
  --- | ---
  WarningsReturnAsErrors | 1 (`true`) ou 0 (`false`)
  LogSubsystems | SQLSRV_LOG_SYSTEM_ALL (-1) SQLSRV_LOG_SYSTEM_CONN (2) SQLSRV_LOG_SYSTEM_INIT (1) SQLSRV_LOG_SYSTEM_OFF (0) SQLSRV_LOG_SYSTEM_STMT (4) SQLSRV_LOG_SYSTEM_UTIL (8)
  LogSeverity | SQLSRV_LOG_SEVERITY_ALL (-1) SQLSRV_LOG_SEVERITY_ERROR (1) SQLSRV_LOG_SEVERITY_NOTICE (4) SQLSRV_LOG_SEVERITY_WARNING (2)

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- » Le gestionnaire d'erreur SQLSRV.
- » Le gestionnaire d'historisation SQLSRV.

# sqlsrv_connect

(No version information available, might only be in Git)

sqlsrv_connect — Ouvre une connexion sur une base de données Microsoft SQL Server

### Description

function sqlsrv_connect(string `$serverName`, array `$connectionInfo` = ?): resource

Ouvre une connexion sur une base de données Microsoft SQL Server. Par défaut, la connexion tente d'utiliser l'authentification Windows. Pour se connecter en utilisant l'authentification SQL Server, ajouter l'"UID" et le "PWD" dans le tableau d'options de connexion.

### Liste de paramètres

`serverName`
  Le nom du serveur sur lequel nous souhaitons réaliser une connexion. Pour se connecter sur une instance particulière, faites suivre le nom du serveur, puis un antislash, puis le nom de l'instance (c.-à-d. serverName\sqlexpress).
`connectionInfo`
  Un tableau associatif spécifiant les options pour la connexion sur le serveur. Si les valeurs des clés UID et PWD ne sont pas spécifiées, la connexion tentera d'utiliser l'authentification Windows. Pour une liste complète des clés supportées, se reporter aux » options de connexion SQLSRV.

### Valeurs de retour

Une ressource de connexion. Si la connexion n'a pu être ouverte, `false` sera retourné.

### Exemples

Exemple #1 Connexion en utilisant l'authentification Windows.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName

    // Vu que UID et PWD ne sont pas spécifiés dans le tableau $connectionInfo,
    // la connexion va tenter d'utiliser l'authentification Windows.
    $connectionInfo = array( "Database"=>"dbName");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Connexion établie.<br />";
    }else{
         echo "La connexion n'a pu être établie.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Exemple #2 Connexion en spécifiant un nom d'utilisateur et un mot de passe.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Connexion établie.<br />";
    }else{
         echo "La connexion n'a pu être établie.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Exemple #3 Connexion sur un port spécifique.

    <?php
    $serverName = "serverName\\sqlexpress, 1542"; //serverName\instanceName, portNumber (default is 1433)
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Connexion établie.<br />";
    }else{
         echo "La connexion n'a pu être établie.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Notes

Par défaut, la fonction sqlsrv_connect() utilise la file d'attente de connexion afin d'augmenter les performances. Pour désactiver cette file d'attente (c.-à-d. et ainsi, forcer une nouvelle connexion à chaque appel à la fonction), définissez l'option "ConnectionPooling" dans le tableau $connectionOptions à 0 (ou `false`). Pour plus d'informations se reporter au chapitre sur la » file d'attente de connexions SQLSRV.

L'extension SQLSRV n'a pas de fonction dédiée pour modifier la base de données sur laquelle l'extension est connectée. La base de données cible est spécifiée dans le tableau $connectionOptions passé à la fonction sqlsrv_connect. Pour changer la base de données sur une connexion ouverte, exécutez la requête suivante : "USE dbName" (c.-à-d. sqlsrv_query($conn, "USE dbName")).

### Voir aussi

- sqlsrv_close() - Clôture une connexion établie et libère les ressources associées
- sqlsrv_errors() - Retourne une erreur ainsi que certaines informations sur la dernière opération SQLSRV effectuée
- sqlsrv_query() - Prépare et exécute une requête

# sqlsrv_errors

(No version information available, might only be in Git)

sqlsrv_errors — Retourne une erreur ainsi que certaines informations sur la dernière opération SQLSRV effectuée

### Description

function sqlsrv_errors(int `$errorsOrWarnings` = ?): mixed

Retourne une erreur ainsi que certaines informations sur la dernière opération SQLSRV effectuée.

### Liste de paramètres

`errorsOrWarnings`
  Détermine si l'on doit retourner des informations sur l'erreur, des informations sur l'alerte, ou les deux. Si ce paramètre n'est pas fourni, les deux informations seront retournées. Voici la liste des valeurs supportées par ce paramètre : SQLSRV_ERR_ALL, SQLSRV_ERR_ERRORS, SQLSRV_ERR_WARNINGS.

### Valeurs de retour

Si une erreur et/ou une alerte survient lors de la dernière opération SQLSRV, un tableau de tableaux contenant les informations de l'erreur sera retourné. Si aucune erreur ni alerte ne survient, `null` sera retourné. Le tableau suivant décrit la structure du tableau retourné :

Tableau retourné par sqlsrv_errors
Clé | Description
--- | ---
SQLSTATE | Pour les erreurs originaires du driver ODBC, ce sera le SQLSTATE retourné par ODBC. Pour les erreurs originaires du Microsoft Drivers pour PHP pour le serveur SQL, un SQLSTATE de IMSSP. Pour les alertes originaires du Microsoft Drivers pour PHP pour le serveur SQL, un SQLSTATE de 01SSP.
code | Pour les erreurs originaires du serveur SQL, le code erreur natif du serveur SQL. Pour les erreurs originaires du ODBC driver, le code erreur retourné par ODBC. Pour les erreurs originaires du Microsoft Drivers pour PHP pour le serveur SQL, le code erreur Microsoft Drivers pour PHP pour le serveur SQL.
message | Une description de l'erreur.

### Exemples

Exemple #1 Exemple avec functionname()

    <?php
    $serverName = "serverName/sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /* Requête pour sélectionner un nom de colonne invalide. */
    $sql = "SELECT BadColumnName FROM Table_1";

    /* L'exécution de la requête va échouer car le nom de la colonne n'existe pas. */
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false ) {
        if( ($errors = sqlsrv_errors() ) != null) {
            foreach( $errors as $error ) {
                echo "SQLSTATE: ".$error[ 'SQLSTATE']."<br />";
                echo "code: ".$error[ 'code']."<br />";
                echo "message: ".$error[ 'message']."<br />";
            }
        }
    }
    ?>

### Notes

Par défaut, les alertes générées lors d'un appel à une fonction SQLSRV sont traitées comme des erreurs. Cela signifie que si une alerte survient lors d'un appel à une fonction SQLSRV, la fonction retournera `false`. Cependant, les alertes qui correspondent aux SQLSTATE de valeurs 01000, 01001, 01003, et 01S02 ne seront jamais traitées comme des erreurs. Pour plus d'informations sur la façon de modifier ce comportement, se reporter à la documentation sur la fonction sqlsrv_configure() ainsi que sur la configuration de WarningsReturnAsErrors.

### Voir aussi

- sqlsrv_configure() - Modifie la configuration du gestionnaire d'erreurs et d'historisations du driver

# sqlsrv_execute

(No version information available, might only be in Git)

sqlsrv_execute — Exécute une requête préparée avec la fonction sqlsrv_prepare()

### Description

function sqlsrv_execute(resource `$stmt`): bool

Exécute une requête préparée avec la fonction sqlsrv_prepare(). Cette fonction est idéale pour exécuter une requête préparée à plusieurs reprises avec des valeurs différentes pour les paramètres.

### Liste de paramètres

`stmt`
  Une ressource de requête retournée par la fonction sqlsrv_prepare().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec sqlsrv_execute()

Cet exemple montre la façon pour préparer une requête avec la fonction sqlsrv_prepare() ainsi que l'exécution à plusieurs reprises (avec des valeurs différentes pour les paramètres) en utilisant la fonction sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Initialise les paramètres et prépare la requête.
    // Les variables $qty et $id sont liées à la requête, $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Définition des informations SalesOrderDetailID et OrderQty.
    // Ce tableau lie l'ID order à la quantitié order dans une paire key=>value.
    $orders = array( 1=>10, 2=>20, 3=>30);

    // Exécute la requête pour chaque ordre.
    foreach( $orders as $id => $qty) {
        // En raison du fait que $id et $qty sont liés à $stmt1, leurs valeurs
        // mises à jour sont utilisées lors de chaque exécution de la requête.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Notes

Lorsque l'on prépare une requête qui utilise des variables comme paramètres, les variables sont liées à la requête. Cela signifie que si l'on met à jour les valeurs des variables, la prochaine exécution de la requête utilisera les valeurs mises à jour. Pour les requêtes que l'on ne prévoit d'utiliser qu'une seule fois, il est recommandé d'utiliser plutôt la fonction sqlsrv_query().

### Voir aussi

- sqlsrv_prepare() - Prépare une requête pour exécution
- sqlsrv_query() - Prépare et exécute une requête

# sqlsrv_fetch

(No version information available, might only be in Git)

sqlsrv_fetch — Rend la prochaine ligne d'un jeu de résultats disponible pour lecture

### Description

function sqlsrv_fetch(resource `$stmt`, int `$row` = ?, int `$offset` = ?): mixed

Rend la prochaine ligne d'un jeu de résultats disponible pour lecture. Utiliser la fonction sqlsrv_get_field() pour lire les champs de la ligne.

### Liste de paramètres

`stmt`
  Une ressource de requête créée par l'exécution de la fonction sqlsrv_query() ou de la fonction sqlsrv_execute().
`row`

  La ligne à traiter. Ce paramètre ne peut être utilisé que si la requête spécifiée a été préparée avec un curseur scrollable. Dans ce cas, ce paramètre peut prendre une des valeurs suivantes :

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Spécifie la ligne à traiter si le paramètre row est défini à `SQLSRV_SCROLL_ABSOLUTE` ou `SQLSRV_SCROLL_RELATIVE`. Il est à noter que la première ligne d'un jeu de résultats a l'index 0.

### Valeurs de retour

Retourne `true` si la prochaine ligne du jeu de résultats a été récupérée avec succès, `false` si une erreur survient et `null` s'il n'y a plus de ligne à récupérer dans le jeu de résultats.

### Exemples

Exemple #1 Exemple avec sqlsrv_fetch()

L'exemple suivant montre la façon pour récupérer une ligne avec la fonction sqlsrv_fetch() et pour récupérer les champs de la ligne avec la fonction sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Récupère la première ligne (et dans ce cas, seulement celle-ci) du jeu de résultats
    // pour lecture.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Récupère les champs de la ligne. Les indices des champs commencent à 0 et
    // doivent être récupérés dans l'ordre.
    // Le fait de récupérer les champs de la ligne par leurs noms n'est pas supporté
    // par la fonction sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Voir aussi

- sqlsrv_get_field() - Récupère les données du champ depuis la ligne actuellement sélectionnée
- sqlsrv_fetch_array() - Retourne une ligne sous la forme d'un tableau
- sqlsrv_fetch_object() - Récupère la prochaine ligne de données du jeu de résultats sous la forme d'un objet

# sqlsrv_fetch_array

(No version information available, might only be in Git)

sqlsrv_fetch_array — Retourne une ligne sous la forme d'un tableau

### Description

function sqlsrv_fetch_array(
resource `$stmt`,
int `$fetchType` = ?,
int `$row` = ?,
int `$offset` = ?
): array

Retourne la prochaine ligne de données disponible sous la forme d'un tableau associatif, d'un tableau numérique ou les deux (par défaut).

### Liste de paramètres

`stmt`
  Une ressource de requête retournée par sqlsrv_query ou sqlsrv_prepare.
`fetchType`
  Une constante prédéfinie spécifiant le type de tableau à retourner. Les valeurs possibles sont `SQLSRV_FETCH_ASSOC`, `SQLSRV_FETCH_NUMERIC`, et `SQLSRV_FETCH_BOTH` (la valeur par défaut). Le type de récupération SQLSRV_FETCH_ASSOC ne doit pas être utilisé lors du traitement d'un jeu de résultats possédant des colonnes dont le nom est identique.
`row`
  Spécifie la ligne à traiter dans le jeu de résultats utilisant un curseur scrollable. Les valeurs possibles sont `SQLSRV_SCROLL_NEXT`, `SQLSRV_SCROLL_PRIOR`, `SQLSRV_SCROLL_FIRST`, `SQLSRV_SCROLL_LAST`, `SQLSRV_SCROLL_ABSOLUTE` et, `SQLSRV_SCROLL_RELATIVE` (la valeur par défaut). Lorsque ce paramètre est spécifié, le paramètre `fetchType` doit également être explicitement défini.
`offset`
  Spécifie la ligne à accéder si le paramètre row est défini à `SQLSRV_SCROLL_ABSOLUTE` ou `SQLSRV_SCROLL_RELATIVE`. Il est à noter que la première ligne du jeu de résultats a comme index 0.

### Valeurs de retour

Retourne un tableau en cas de succès, `null` s'il n'y a plus de ligne à retourner, et `false` si une erreur survient.

### Exemples

Exemple #1 Récupération d'un tableau associatif

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC) ) {
          echo $row['LastName'].", ".$row['FirstName']."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

Exemple #2 Récupération d'un tableau numérique

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_NUMERIC) ) {
          echo $row[0].", ".$row[1]."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

### Notes

Le fait de ne pas spécifier le paramètre `fetchType` ou le fait de le définir explicitement à la valeur `SQLSRV_FETCH_TYPE` dans l'exemple ci-dessus retournera un tableau contenant à la fois des clés associatives et des clés numériques.

Si plus d'une colonne est retournée avec le même nom, la dernière colonne prendra le dessus. Pour éviter d'avoir des problèmes avec les noms des colonnes, utiliser des alias.

Si une colonne ne possédant aucun nom est retournée, la clé associative de l'élément du tableau sera une chaîne vide ("").

### Voir aussi

- sqlsrv_connect() - Ouvre une connexion sur une base de données Microsoft SQL Server
- sqlsrv_query() - Prépare et exécute une requête
- sqlsrv_errors() - Retourne une erreur ainsi que certaines informations sur la dernière opération SQLSRV effectuée
- sqlsrv_fetch() - Rend la prochaine ligne d'un jeu de résultats disponible pour lecture

# sqlsrv_fetch_object

(No version information available, might only be in Git)

sqlsrv_fetch_object — Récupère la prochaine ligne de données du jeu de résultats sous la forme d'un objet

### Description

function sqlsrv_fetch_object(
resource `$stmt`,
string `$className` = ?,
array `$ctorParams` = ?,
int `$row` = ?,
int `$offset` = ?
): mixed

Récupère la prochaine ligne de données du jeu de résultats sous la forme d'une instance de la classe spécifiée dont les propriétés correspondent aux noms des champs de la ligne récupérée et les valeurs correspondant aux valeurs des champs de la ligne récupérée.

### Liste de paramètres

`stmt`
  Une ressource de requête créée par la fonction sqlsrv_query() ou la fonction sqlsrv_execute().
`className`
  Le nom de la classe à instancier. Si aucun nom de classe n'est spécifié, stdClass sera instanciée.
`ctorParams`
  Valeurs à passer au constructeur de la classe spécifiée. Si le constructeur de la classe spécifiée prend des paramètres, le tableau ctorParams doit être fourni.
`row`

  La ligne à traiter. Ce paramètre ne peut être utilisé que si la requête spécifiée a été préparée avec un curseur scrollable. Dans ce cas, ce paramètre peut prendre une des valeurs suivantes :

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Spécifie la ligne à traiter si le paramètre row est défini à la valeur `SQLSRV_SCROLL_ABSOLUTE` ou `SQLSRV_SCROLL_RELATIVE`. Il est à noter que la première ligne du jeu de résultats a un index de 0.

### Valeurs de retour

Retourne un objet en cas de succès, `null` s'il n'y a plus de ligne à retourner, et `false` si une erreur survient ou si la classe spécifiée n'existe pas.

### Exemples

Exemple #1 Exemple avec sqlsrv_fetch_object()

L'exemple suivant montre la façon pour récupérer une ligne sous la forme d'un objet stdClass.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT fName, lName FROM Table_1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Récupère chaque ligne sous la forme d'un objet
    // Vu qu'aucune classe n'est spécifiée, chaque ligne sera récupérée sous la forme d'un objet stdClass.
    // Les noms des propriétés correspondent aux noms des champs.
    while( $obj = sqlsrv_fetch_object( $stmt)) {
          echo $obj->fName.", ".$obj->lName."<br />";
    }
    ?>

### Notes

Si un nom de classe est spécifié avec le paramètre optionnel $className et la classe a des propriétés dont les noms correspondent à des noms de champs du jeu de résultats, les valeurs correspondantes du jeu de résultats seront appliquées à ces propriétés. Si un nom de champs du jeu de résultats ne correspond pas à une propriété de la classe, une propriété dont le nom correspond au nom du champ sera ajoutée à l'objet et la valeur correspondante dans le jeu de résultats sera appliquée à cette propriété. La règle suivante s'applique lors de l'utilisation du paramètre $className :

- Le nom du champ et de la propriété sont sensibles à la casse.
- La correspondance champ/propriété survient en tenant compte des modificateurs d'accès.
- Les types de données des propriétés de la classe sont ignorés lors de l'application de la valeur d'un champ sur une propriété.
- Si la classe n'existe pas, la fonction retourne `false` et ajoute une erreur dans la collection des erreurs.

Suivant si le paramètre $className est fourni ou non, si un champ avec aucun nom est retourné, la valeur du champ sera ignorée et une alerte sera ajoutée à la collection des erreurs.

Lors du traitement d'un jeu de résultats qui possède plusieurs colonnes portant le même nom, il peut être plus judicieux d'utiliser la fonction sqlsrv_fetch_array() ou une combinaison des fonctions sqlsrv_fetch() et sqlsrv_get_field().

### Voir aussi

- sqlsrv_fetch() - Rend la prochaine ligne d'un jeu de résultats disponible pour lecture
- sqlsrv_fetch_array() - Retourne une ligne sous la forme d'un tableau

# sqlsrv_field_metadata

(No version information available, might only be in Git)

sqlsrv_field_metadata — Récupère les données méta pour les champs d'une requête préparée par la fonction sqlsrv_prepare() ou la fonction sqlsrv_query()

### Description

function sqlsrv_field_metadata(resource `$stmt`): mixed

Récupère les données méta pour les champs d'une requête préparée par la fonction sqlsrv_prepare() ou la fonction sqlsrv_query(). La fonction sqlsrv_field_metadata() peut être appelée sur une requête avant ou après son exécution.

### Liste de paramètres

`stmt`
  Une ressource de requête depuis laquelle les données méta seront récupérées.

### Valeurs de retour

Retourne un tableau de tableaux en cas de succès. Sinon `false` est retourné. Chaque tableau retourné est décrit dans la table suivante :

Tableau retourné par la fonction sqlsrv_field_metadata
Clé | Description
--- | ---
Name | Le nom du champ.
Type | La valeur numérique pour le type SQL.
Size | Le nombre de caractères pour les champs de type caractères, le nombre d'octets pour les champs de type binaire, ou `null` pour les autres types.
Precision | La précision pour les variables de type précision, `null` pour les autres types.
Scale | L'échelle pour les variables de type scale, `null` pour les autres types.
Nullable | Une énumération indiquant si la colonne peut être nulle, ne peut pas l'être, ou si cette information n'est pas connue.

Pour plus d'informations, se reporter à la documentation sur la fonction » sqlsrv_field_metadata de la documentation Microsoft SQLSRV.

### Exemples

Exemple #1 Exemple avec sqlsrv_field_metadata()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"AdventureWorks", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_prepare( $conn, $sql );

    foreach( sqlsrv_field_metadata( $stmt ) as $fieldMetadata ) {
        foreach( $fieldMetadata as $name => $value) {
           echo "$name: $value<br />";
        }
          echo "<br />";
    }
    ?>

### Voir aussi

- sqlsrv_client_info() - Retourne les informations sur le client ainsi que sur la connexion spécifiée

# sqlsrv_free_stmt

(No version information available, might only be in Git)

sqlsrv_free_stmt — Libère toutes les ressources de la requête spécifiée

### Description

function sqlsrv_free_stmt(resource `$stmt`): bool

Libère toutes les ressources pour la requête spécifiée. La requête ne pourra plus être utilisée après le passage à la fonction sqlsrv_free_stmt(). Si la requête sqlsrv_free_stmt() est appelée alors que la requête est en cours d'exécution, l'exécution de la requête est interrompue, et la requête est annulée.

### Liste de paramètres

`stmt`
  La requête dont les ressources seront libérées. Il est à noter que `null` est une valeur de paramètre valide. Cette valeur permet à la fonction d'être appelée à plusieurs reprises dans un script.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec sqlsrv_free_stmt()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /*-------------------------------
         Exploitation de la requête ici.
    -------------------------------*/

    /* Libération des ressources associées à la requête. */
    sqlsrv_free_stmt( $stmt);

    ?>

### Notes

La principale différence entre la fonction sqlsrv_free_stmt() et la fonction sqlsrv_cancel() est qu'une ressource de requête annulée avec la fonction sqlsrv_cancel() peut être ré-exécutée si elle a été créée avec la fonction sqlsrv_prepare(). Une ressource de requête annulée avec la fonction sqlsrv_free_statement() ne peut plus être ré-exécutée.

### Voir aussi

- sqlsrv_cancel() - Annule une requête

# sqlsrv_get_config

(No version information available, might only be in Git)

sqlsrv_get_config — Retourne la valeur de la configuration spécifiée

### Description

function sqlsrv_get_config(string `$setting`): mixed

Retourne la valeur de la configuration spécifiée.

### Liste de paramètres

`setting`
  Le nom de la configuration pour laquelle la valeur sera retournée. Pour une liste des configurations, voir la fonction sqlsrv_configure().

### Valeurs de retour

Retourne la valeur de la configuration demandée. Si une configuration invalide est fournie, `false` sera retourné.

### Voir aussi

- sqlsrv_configure() - Modifie la configuration du gestionnaire d'erreurs et d'historisations du driver

# sqlsrv_get_field

(No version information available, might only be in Git)

sqlsrv_get_field — Récupère les données du champ depuis la ligne actuellement sélectionnée

### Description

function sqlsrv_get_field(resource `$stmt`, int `$fieldIndex`, int `$getAsType` = ?): mixed

Récupère les données du champ depuis la ligne actuellement sélectionnée. Les champs doivent être lus dans l'ordre. Leurs indices commencent à 0.

### Liste de paramètres

`stmt`
  Une ressource de requête retournée par la fonction sqlsrv_query() ou la fonction sqlsrv_execute().
`fieldIndex`
  L'index du champ à récupérer. Les indices des champs commencent à 0. Les champs doivent être lus dans l'ordre, c.-à-d. si l'on accède au champ d'indice 1, alors le champ d'indice 0 ne sera plus disponible.
`getAsType`
  Le type de données PHP pour les données du champ retourné. Si ce paramètre n'est pas défini, les données du champ seront retournées sous la forme d'un type de données PHP par défaut. Pour plus d'informations sur les types de données PHP par défaut, se reporter à la section sur » les types de données PHP par défaut de la documentation Microsoft SQLSRV.

### Valeurs de retour

Retourne les données depuis le champ spécifié en cas de succès. Retourne `false` si une erreur survient.

### Exemples

Exemple #1 sqlsrv_get_field() example

L'exemple suivant montre la façon de récupérer une ligne avec la fonction sqlsrv_fetch() et récupère les champs de la ligne avec la fonction sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Rend disponible la première (et dans ce cas, la seule) ligne du jeu de résultats pour lecture.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Récupère les champs de la ligne. Les indices commencent à 0 et doivent être récupérés dans l'ordre.
    // La récupération des champs de la ligne par leurs noms n'est pas supportée par la fonction sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Voir aussi

- sqlsrv_fetch() - Rend la prochaine ligne d'un jeu de résultats disponible pour lecture
- sqlsrv_fetch_array() - Retourne une ligne sous la forme d'un tableau
- sqlsrv_fetch_object() - Récupère la prochaine ligne de données du jeu de résultats sous la forme d'un objet

# sqlsrv_has_rows

(No version information available, might only be in Git)

sqlsrv_has_rows — Indique si la requête spécifiée contient des lignes

### Description

function sqlsrv_has_rows(resource `$stmt`): bool

Indique si la requête spécifiée contient des lignes.

### Liste de paramètres

`stmt`
  Une ressource de requête retournée par la fonction sqlsrv_query() ou la fonction sqlsrv_execute().

### Valeurs de retour

Retourne `true` si la requête spécifiée contient des lignes, `false` si elle n'en contient pas ou bien si une erreur survient.

### Exemples

Exemple #1 Exemple avec sqlsrv_has_rows()

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");

    if ($stmt) {
       $rows = sqlsrv_has_rows( $stmt );
       if ($rows === true)
          echo "Il y a des lignes. <br />";
       else
          echo "Il n'y a aucune ligne. <br />";
    }
    ?>

### Voir aussi

- sqlsrv_num_rows() - Récupère le nombre de lignes d'un jeu de résultats
- sqlsrv_query() - Prépare et exécute une requête

# sqlsrv_next_result

(No version information available, might only be in Git)

sqlsrv_next_result — Rend actif le prochain résultat de la requête spécifiée

### Description

function sqlsrv_next_result(resource `$stmt`): mixed

Rend actif le prochain résultat de la requête spécifiée. Les résultats incluent les jeux de résultats, le nombre de lignes, et les paramètres de sortie.

### Liste de paramètres

`stmt`
  La requête sur laquelle le prochain résultat sera appelé.

### Valeurs de retour

Retourne `true` si le prochain résultat a été récupéré avec succès, `false` si une erreur survient, et `null` s'il n'y a plus de résultat à récupérer.

### Exemples

Exemple #1 Exemple avec sqlsrv_next_result()

L'exemple suivant exécute une requête batch qui fait des insertions dans une table, puis, fait une sélection de la table. Ceci produit 2 résultats sur la requête : un pour les lignes affectées par le INSERT, et un pour les lignes retournées par le SELECT. Pour récupérer les lignes retournées par le SELECT, la fonction sqlsrv_next_result() doit être appelée pour passer le premier résultat.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array("Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    $query = "INSERT INTO Table_1 (id, data) VALUES (?,?); SELECT * FROM TABLE_1;";
    $params = array(1, "some data");
    $stmt = sqlsrv_query($conn, $query, $params);

    // Consomme le premier résultat (lignes affectées par le INSERT) sans appeler la fonction sqlsrv_next_result.
    echo "Lignes affectées : ".sqlsrv_rows_affected($stmt)."<br />";

    // Se déplace au résultat suivant et affiche les résultats.
    $next_result = sqlsrv_next_result($stmt);
    if( $next_result ) {
       while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC)){
          echo $row['id']." : ".$row['data']."<br />";
       }
    } elseif( is_null($next_result)) {
         echo "Il n'y a plus de résultat.<br />";
    } else {
         die(print_r(sqlsrv_errors(), true));
    }
    ?>

### Voir aussi

- sqlsrv_query() - Prépare et exécute une requête
- sqlsrv_fetch_array() - Retourne une ligne sous la forme d'un tableau
- sqlsrv_rows_affected() - Retourne le nombre de lignes modifiées par la dernière requête de type INSERT, UPDATE, ou DELETE

# sqlsrv_num_fields

(No version information available, might only be in Git)

sqlsrv_num_fields — Récupère le nombre de champs (colonnes) dans une requête

### Description

function sqlsrv_num_fields(resource `$stmt`): mixed

Récupère le nombre de champs (colonnes) dans une requête.

### Liste de paramètres

`stmt`
  La requête depuis laquelle le nombre de champs est retournée. La fonction sqlsrv_num_fields() peut être appelée sur une requête avant ou après l'exécution de la requête.

### Valeurs de retour

Retourne le nombre de champs en cas de succès. Retourne `false` sinon.

### Exemples

Exemple #1 Exemple avec sqlsrv_num_fields()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_query($conn, $sql);
    if( $stmt === false) {
       die( print_r( sqlsrv_errors(), true));
    }

    $numFields = sqlsrv_num_fields( $stmt );

    while( sqlsrv_fetch( $stmt )) {
       // Itération sur les champs de chaque ligne.
       for($i = 0; $i < $numFields; $i++) {
          echo sqlsrv_get_field($stmt, $i)." ";
       }
       echo "<br />";
    }
    ?>

### Voir aussi

- sqlsrv_field_metadata() - Récupère les données méta pour les champs d'une requête préparée par la fonction sqlsrv_prepare ou la fonction sqlsrv_query
- sqlsrv_fetch() - Rend la prochaine ligne d'un jeu de résultats disponible pour lecture
- sqlsrv_get_field() - Récupère les données du champ depuis la ligne actuellement sélectionnée

# sqlsrv_num_rows

(No version information available, might only be in Git)

sqlsrv_num_rows — Récupère le nombre de lignes d'un jeu de résultats

### Description

function sqlsrv_num_rows(resource `$stmt`): mixed

Récupère le nombre de lignes d'un jeu de résultats. Cette fonction nécessite que la ressource de requête ait été créée avec un curseur statique ou keyset. Pour plus d'informations, se reporter aux fonctions sqlsrv_query(), sqlsrv_prepare(), ou au chapitre » Spécifier un type de curseur et sélectionner des lignes dans la documentation de Microsoft SQLSRV.

### Liste de paramètres

`stmt`
  La requête depuis laquelle le nombre total de lignes est retourné. La ressource de requête doit avoir été créée avec un curseur statique ou keyset. Pour plus d'informations, se reporter aux fonctions sqlsrv_query(), sqlsrv_prepare(), ou au chapitre » Spécifier un type de curseur et sélectionner des lignes dans la documentation de Microsoft SQLSRV.

### Valeurs de retour

Retourne le nombre total de lignes récupérées en cas de succès, et `false` si une erreur survient. Si un curseur avant (par défaut), ou un curseur dynamique est utilisé, `false` sera retourné.

### Exemples

Exemple #1 Exemple avec sqlsrv_num_rows()

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $sql = "SELECT * FROM Table_1";
    $params = array();
    $options =  array( "Scrollable" => SQLSRV_CURSOR_KEYSET );
    $stmt = sqlsrv_query( $conn, $sql , $params, $options );

    $row_count = sqlsrv_num_rows( $stmt );

    if ($row_count === false)
       echo "Erreur lors de la récupération du nombre de lignes.";
    else
       echo $row_count;
    ?>

### Voir aussi

- sqlsrv_has_rows() - Indique si la requête spécifiée contient des lignes
- sqlsrv_rows_affected() - Retourne le nombre de lignes modifiées par la dernière requête de type INSERT, UPDATE, ou DELETE

# sqlsrv_prepare

(No version information available, might only be in Git)

sqlsrv_prepare — Prépare une requête pour exécution

### Description

function sqlsrv_prepare(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Prépare une requête pour exécution. Cette fonction est idéale pour préparer une requête qui sera exécutée plusieurs fois avec des valeurs de paramètres différents.

### Liste de paramètres

`conn`
  Une ressource de connexion retournée par la fonction sqlsrv_connect().
`sql`
  La chaîne qui définit la requête à préparer et à exécuter.
`params`

  Un tableau spécifiant les informations de paramètres lors de l'exécution d'une requête contenant des paramètres. Les éléments du tableau peuvent être n'importe lequel de ceux qui suivent :

  - Une valeur littérale
  - Une variable PHP
  - Un tableau avec la structure suivante : array($value [, $direction [, $phpType [, $sqlType]]])
  La table suivante décrit les éléments de la structure du tableau ci-dessus :

  Structure du tableau
  Élément | Description
  --- | ---
  $value | Une valeur littérale, une variable PHP ou une variable PHP passée par référence.
  $direction (optional) | Une des constantes SQLSRV suivantes, utilisées pour indiquer la direction du paramètre : SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. La valeur par défaut est SQLSRV_PARAM_IN.
  $phpType (optional) | Une constante SQLSRV_PHPTYPE_* qui spécifie le type de données PHP de la valeur retournée.
  $sqlType (optional) | Une constante SQLSRV_SQLTYPE_* qui spécifie le type de données du serveur SQL de la valeur d'entrée.

`options`
  Un tableau spécifiant les options de propriétés de la requête. Les clés supportées sont décrites dans le tableau suivant :

  Options de la requête
  Clé | Valeurs | Description
  --- | --- | ---
  QueryTimeout | Une valeur entière positive. | Définit le délai maximal d'exécution de la requête, en seconde. Par défaut, le driver attendra indéfiniment les résultats.
  SendStreamParamsAtExec | `true` ou `false` (par défaut, `true`) | Configure le driver pour envoyer les données du flux à l'exécution (`true`), ou envoyer les données du flux par morceaux (`false`). Par défaut, la valeur est définie à `true`. Pour plus d'informations, se reporter à la fonction sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, ou SQLSRV_CURSOR_KEYSET | Voir la section sur » la spécification d'un type de curseur et la sélection de lignes de la documentation Microsoft SQLSRV.

### Valeurs de retour

Retourne une ressource de requête en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec sqlsrv_prepare()

Cet exemple montre la façon de préparer une requête avec la fonction sqlsrv_prepare() et sa ré-exécution à plusieurs reprises (avec des valeurs de paramètres différents) en utilisant la fonction sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Initialise les paramètres et prépare la requête.
    // Les variables $qty et $id sont liées à la requête $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Définit les informations SalesOrderDetailID et OrderQty.
    // Ce tableau lie l'ordre des IDs avec l'ordre des quantités avec des paires clé=>valeur.
    $orders = array( 1=>10, 2=>20, 3=>30);

    // Exécute la requête pour chaque ordre.
    foreach( $orders as $id => $qty) {
        // En raison du fait que $id et $qty sont liés à $stmt1,
        // leurs valeurs mises à jour sont utilisées lors de chaque exécution
        // de la requête.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Notes

Lorsque l'on prépare une requête qui utilise des variables comme paramètres, les variables sont liées à la requête. Cela signifie que si l'on met à jour les valeurs de ces variables, la prochaine exécution de la requête prendra en compte ces nouvelles valeurs. Pour les requêtes que l'on ne prévoit exécuter qu'une seule fois, utiliser la fonction sqlsrv_query().

### Voir aussi

- sqlsrv_execute() - Exécute une requête préparée avec la fonction sqlsrv_prepare
- sqlsrv_query() - Prépare et exécute une requête

# sqlsrv_query

(No version information available, might only be in Git)

sqlsrv_query — Prépare et exécute une requête

### Description

function sqlsrv_query(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Prépare et exécute une requête.

### Liste de paramètres

`conn`
  Une ressource de connexion retournée par la fonction sqlsrv_connect().
`sql`
  La chaîne qui définit la requête à préparer et à exécuter.
`params`

  Un tableau spécifiant les paramètres lors de l'exécution d'une requête les autorisant. Les éléments du tableau peuvent être n'importe lequel parmi la liste ci-dessous :

  - Une valeur littérale
  - Une variable PHP
  - Un tableau avec cette structure : array($value [, $direction [, $phpType [, $sqlType]]])
  La table suivante décrit les éléments dans la structure du tableau ci-dessus :

  Structure du tableau
  Élément | Description
  --- | ---
  $value | Une valeur littérale, une variable PHP ou une variable PHP par référence.
  $direction (optional) | Une des constantes SQLSRV suivantes utilisées pour indiquer la direction du paramètre : SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. La valeur par défaut est SQLSRV_PARAM_IN.
  $phpType (optional) | Une constante SQLSRV_PHPTYPE_* qui spécifie le type de données PHP de la valeur retournée.
  $sqlType (optional) | Une constante SQLSRV_SQLTYPE_* qui spécifie le type de données du serveur SQL pour la valeur en entrée.

`options`
  Un tableau spécifiant les options de la requête. Les clés supportées sont décrites dans le tableau suivant :

  Options de requête
  Clé | Valeur | Description
  --- | --- | ---
  QueryTimeout | Une valeur entière positive. | Définit le délai d'exécution maximal de la requête en seconde. Par défaut, le driver attendra indéfiniment les résultats.
  SendStreamParamsAtExec | `true` ou `false` (par défaut, vaut `true`) | Configure le driver pour envoyer tous les flux de données à l'exécution (`true`) ou envoyer les flux de données en morceaux (`false`). Pour plus d'informations, voir la fonction sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, ou SQLSRV_CURSOR_KEYSET | Voir le chapitre sur » la spécification d'un type de curseur et la sélection de lignes dans la documentation Microsoft SQLSRV.

### Valeurs de retour

Retourne une ressource de requête en cas de succès, et `false` si une erreur survient.

### Exemples

Exemple #1 sqlsrv_query() example

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "INSERT INTO Table_1 (id, data) VALUES (?, ?)";
    $params = array(1, "some data");

    $stmt = sqlsrv_query( $conn, $sql, $params);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Notes

Pour les requêtes que l'on ne prévoit d'exécuter qu'une seule fois, il est recommandé d'utiliser la fonction sqlsrv_query(). Pour ré-exécuter une requête avec des valeurs différentes pour ses paramètres, utiliser la combinaison de la fonction sqlsrv_prepare() et de la fonction sqlsrv_execute().

### Voir aussi

- sqlsrv_prepare() - Prépare une requête pour exécution
- sqlsrv_execute() - Exécute une requête préparée avec la fonction sqlsrv_prepare

# sqlsrv_rollback

(No version information available, might only be in Git)

sqlsrv_rollback — Annule une transaction qui a été commencée grâce à la fonction sqlsrv_begin_transaction()

### Description

function sqlsrv_rollback(resource `$conn`): bool

Annule une transaction qui a été commencée grâce à la fonction sqlsrv_begin_transaction() et retourne la connexion en mode auto-validation.

### Liste de paramètres

`conn`
  La ressource de connexion retournée par un appel à la fonction sqlsrv_connect().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec sqlsrv_rollback()

L'exemple suivant montre la façon d'utiliser la fonction sqlsrv_begin_transaction() avec les fonctions sqlsrv_commit() et sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Commence la transaction. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Initialise les valeurs des paramètres. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Exécution de la première requête. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Exécute la seconde requête. */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Si les deux requêtes ont été exécutées avec succès,
    on valide la transaction */
    /* Sinon, on annule la transaction. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaction validée.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaction annulée.<br />";
    }
    ?>

### Voir aussi

- sqlsrv_begin_transaction() - Commence une transaction
- sqlsrv_commit() - Valide une transaction commencée avec la fonction sqlsrv_begin_transaction

# sqlsrv_rows_affected

(No version information available, might only be in Git)

sqlsrv_rows_affected — Retourne le nombre de lignes modifiées par la dernière requête de type INSERT, UPDATE, ou DELETE

### Description

function sqlsrv_rows_affected(resource `$stmt`): int|false

Retourne le nombre de lignes modifiées par la dernière requête de type INSERT, UPDATE, ou DELETE. Pour plus d'informations sur le nombre de lignes retournées par une requête SELECT, se reporter à la fonction sqlsrv_num_rows().

### Liste de paramètres

`stmt`
  La ressource de requête exécutée.

### Valeurs de retour

Retourne le nombre de lignes affectées par la dernière requête INSERT, UPDATE, ou DELETE. Si aucune ligne n'est affectée, 0 sera retourné. Si le nombre de lignes affectées ne peut être déterminé, -1 sera retourné. Si une erreur survient, `false` sera retourné.

### Exemples

Exemple #1 Exemple avec sqlsrv_rows_affected()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ? WHERE id = ?";

    $params = array("updated data", 1);

    $stmt = sqlsrv_query( $conn, $sql, $params);

    $rows_affected = sqlsrv_rows_affected( $stmt);
    if( $rows_affected === false) {
         die( print_r( sqlsrv_errors(), true));
    } elseif( $rows_affected == -1) {
          echo "Aucune information de disponible.<br />";
    } else {
          echo $rows_affected." lignes ont été mises à jour.<br />";
    }
    ?>

### Voir aussi

- sqlsrv_num_rows() - Récupère le nombre de lignes d'un jeu de résultats

# sqlsrv_send_stream_data

(No version information available, might only be in Git)

sqlsrv_send_stream_data — Envoie des données depuis le flux vers le serveur

### Description

function sqlsrv_send_stream_data(resource `$stmt`): bool

Envoie des données depuis le flux vers le serveur. Jusqu'à 8 Ko de données sont envoyées à chaque appel.

### Liste de paramètres

`stmt`
  Une ressource de requête retournée par la fonction sqlsrv_query() ou par la fonction sqlsrv_execute().

### Valeurs de retour

Retourne `true` s'il y a encore des données à envoyer, et `false` s'il n'y en a plus.

### Exemples

Exemple #1 Exemple avec sqlsrv_send_stream_data()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ( ?) WHERE id = 100";

    // Ouvre les données sous forme de flux et on les place dans le tableau $params.
    $data = fopen( "data://text/plain,[ Lengthy content here. ]", "r");
    $params = array( &$data);

    // Prépare la requête. Utilisation du tableau $options pour désactiver
    // le comportement par défaut, qui est d'envoyer toutes les données du flux
    // au moment de l'exécution de la requête.
    $options = array("SendStreamParamsAtExec"=>0);
    $stmt = sqlsrv_prepare( $conn, $sql, $params, $options);

    sqlsrv_execute( $stmt);

    // Envoie jusqu'à 8 Ko de données au serveur
    // à chaque appel à la fonction sqlsrv_send_stream_data.
    $i = 1;
    while( sqlsrv_send_stream_data( $stmt)) {
          $i++;
    }
    echo "$i appels ont été effectués.";
    ?>

### Voir aussi

- sqlsrv_prepare() - Prépare une requête pour exécution
- sqlsrv_query() - Prépare et exécute une requête

# sqlsrv_server_info

(No version information available, might only be in Git)

sqlsrv_server_info — Retourne des informations sur le serveur

### Description

function sqlsrv_server_info(resource `$conn`): array

Retourne des informations sur le serveur.

### Liste de paramètres

`conn`
  La ressource de connexion qui connecte le client et le serveur.

### Valeurs de retour

Retourne un tableau tel que décrit dans la table suivante :

Tableau retourné
CurrentDatabase | La base de données connectée
--- | ---
SQLServerVersion | La version du serveur SQL
SQLServerName | Le nom du serveur

### Exemples

Exemple #1 Exemple avec sqlsrv_server_info()

    <?php
    $serverName = "serverName\sqlexpress";
    $conn = sqlsrv_connect( $serverName);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $server_info = sqlsrv_server_info( $conn);
    if( $server_info )
    {
        foreach( $server_info as $key => $value) {
           echo $key.": ".$value."<br />";
        }
    } else {
          die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Voir aussi

- sqlsrv_client_info() - Retourne les informations sur le client ainsi que sur la connexion spécifiée

## Sommaire

- sqlsrv_begin_transaction — Commence une transaction
- sqlsrv_cancel — Annule une requête
- sqlsrv_client_info — Retourne les informations sur le client ainsi que sur la connexion spécifiée
- sqlsrv_close — Clôture une connexion établie et libère les ressources associées
- sqlsrv_commit — Valide une transaction commencée avec la fonction sqlsrv_begin_transaction
- sqlsrv_configure — Modifie la configuration du gestionnaire d'erreurs et d'historisations du driver
- sqlsrv_connect — Ouvre une connexion sur une base de données Microsoft SQL Server
- sqlsrv_errors — Retourne une erreur ainsi que certaines informations sur la dernière opération SQLSRV effectuée
- sqlsrv_execute — Exécute une requête préparée avec la fonction sqlsrv_prepare
- sqlsrv_fetch — Rend la prochaine ligne d'un jeu de résultats disponible pour lecture
- sqlsrv_fetch_array — Retourne une ligne sous la forme d'un tableau
- sqlsrv_fetch_object — Récupère la prochaine ligne de données du jeu de résultats sous la forme d'un objet
- sqlsrv_field_metadata — Récupère les données méta pour les champs d'une requête préparée par la fonction sqlsrv_prepare ou la fonction sqlsrv_query
- sqlsrv_free_stmt — Libère toutes les ressources de la requête spécifiée
- sqlsrv_get_config — Retourne la valeur de la configuration spécifiée
- sqlsrv_get_field — Récupère les données du champ depuis la ligne actuellement sélectionnée
- sqlsrv_has_rows — Indique si la requête spécifiée contient des lignes
- sqlsrv_next_result — Rend actif le prochain résultat de la requête spécifiée
- sqlsrv_num_fields — Récupère le nombre de champs (colonnes) dans une requête
- sqlsrv_num_rows — Récupère le nombre de lignes d'un jeu de résultats
- sqlsrv_prepare — Prépare une requête pour exécution
- sqlsrv_query — Prépare et exécute une requête
- sqlsrv_rollback — Annule une transaction qui a été commencée grâce à la fonction sqlsrv_begin_transaction
- sqlsrv_rows_affected — Retourne le nombre de lignes modifiées par la dernière requête de type INSERT, UPDATE, ou DELETE
- sqlsrv_send_stream_data — Envoie des données depuis le flux vers le serveur
- sqlsrv_server_info — Retourne des informations sur le serveur

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Fonctions SQLSRV
  - sqlsrv_begin_transaction — Commence une transaction
  - sqlsrv_cancel — Annule une requête
  - sqlsrv_client_info — Retourne les informations sur le client ainsi que sur la connexion spécifiée
  - sqlsrv_close — Clôture une connexion établie et libère les ressources associées
  - sqlsrv_commit — Valide une transaction commencée avec la fonction sqlsrv_begin_transaction
  - sqlsrv_configure — Modifie la configuration du gestionnaire d'erreurs et d'historisations du driver
  - sqlsrv_connect — Ouvre une connexion sur une base de données Microsoft SQL Server
  - sqlsrv_errors — Retourne une erreur ainsi que certaines informations sur la dernière opération SQLSRV effectuée
  - sqlsrv_execute — Exécute une requête préparée avec la fonction sqlsrv_prepare
  - sqlsrv_fetch — Rend la prochaine ligne d'un jeu de résultats disponible pour lecture
  - sqlsrv_fetch_array — Retourne une ligne sous la forme d'un tableau
  - sqlsrv_fetch_object — Récupère la prochaine ligne de données du jeu de résultats sous la forme d'un objet
  - sqlsrv_field_metadata — Récupère les données méta pour les champs d'une requête préparée par la fonction sqlsrv_prepare ou la fonction sqlsrv_query
  - sqlsrv_free_stmt — Libère toutes les ressources de la requête spécifiée
  - sqlsrv_get_config — Retourne la valeur de la configuration spécifiée
  - sqlsrv_get_field — Récupère les données du champ depuis la ligne actuellement sélectionnée
  - sqlsrv_has_rows — Indique si la requête spécifiée contient des lignes
  - sqlsrv_next_result — Rend actif le prochain résultat de la requête spécifiée
  - sqlsrv_num_fields — Récupère le nombre de champs (colonnes) dans une requête
  - sqlsrv_num_rows — Récupère le nombre de lignes d'un jeu de résultats
  - sqlsrv_prepare — Prépare une requête pour exécution
  - sqlsrv_query — Prépare et exécute une requête
  - sqlsrv_rollback — Annule une transaction qui a été commencée grâce à la fonction sqlsrv_begin_transaction
  - sqlsrv_rows_affected — Retourne le nombre de lignes modifiées par la dernière requête de type INSERT, UPDATE, ou DELETE
  - sqlsrv_send_stream_data — Envoie des données depuis le flux vers le serveur
  - sqlsrv_server_info — Retourne des informations sur le serveur

- CUBRID
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions CUBRID
  - Fonctions CUBRID compatibles MySQL
  - Fonctions et alias CUBRID obsolètes
- dBase
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions dBase
- Firebird/InterBase
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Firebird/InterBase
- IBM DB2 — Fonctions IBM DB2, Cloudscape et Apache Derby
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions IBM DB2
- MongoDB — L'extension MongoDB
  - Installation/Configuration
  - Constantes pré-définies
  - Tutoriels
  - Architecture et fonctionnalités spéciales — Explications de l'architecture du pilote et des fonctionnalités spéciales
  - Sécurité
  - MongoDB\Driver — Classes de l'extension MongoDB
  - MongoDB\BSON — Classes et fonctions BSON de MongoDB
  - MongoDB\Driver\Monitoring — Classes de surveillance et fonctions abonnées
  - MongoDB\Driver\Exception — Les classes d'exception
- MySQL — Plugins et drivers MySQL
  - Aperçu des drivers PHP MySQL
  - MySQLi — Extension mysqli
  - Mysql_xdevapi
  - MySQL (Original) — API MySQL originale
  - Mysqlnd — Le pilote natif MySQL
- OCI8 — Oracle OCI8
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Gestion de la connexion OCI8 et de la mise en file d'attente
  - Support de FAN (Fast Application Notification : Application de notification Rapide) OCI8
  - Le support de la reprise transparente d'application (TAF) d'OCI8
  - OCI8 et le suivi dynamique DTrace
  - Types de données supportés par le pilote
  - Fonctions OCI8
  - OCICollection — La classe OCICollection
  - OCILob — La classe OCILob
  - Fonctions et alias OCI8 obsolètes
- PostgreSQL
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions PostgreSQL
  - PgSql\Connection — La classe PgSql\Connection
  - PgSql\Result — La classe PgSql\Result
  - PgSql\Lob — La classe PgSql\Lob
- SQLite3
  - Installation/Configuration
  - Constantes pré-définies
  - SQLite3 — La classe SQLite3
  - SQLite3Exception — La classe SQLite3Exception
  - SQLite3Stmt — La classe SQLite3Stmt
  - SQLite3Result — La classe SQLite3Result
- SQLSRV — Driver Microsoft SQL Server pour PHP
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions SQLSRV

- Interface d'abstraction
  - DBA — Couche d'abstraction de base de données (style dbm)
  - ODBC — ODBC (Unifié)
  - PDO — PHP Data Objects
- Extensions spécifiques des fabricants de bases de données
  - CUBRID
  - dBase
  - Firebird/InterBase
  - IBM DB2 — Fonctions IBM DB2, Cloudscape et Apache Derby
  - MongoDB — L'extension MongoDB
  - MySQL — Plugins et drivers MySQL
  - OCI8 — Oracle OCI8
  - PostgreSQL
  - SQLite3
  - SQLSRV — Driver Microsoft SQL Server pour PHP

# Extensions relatives aux dates et aux heures

# Calendar

# Introduction

L'extension Calendar contient une série de fonctions afin de convertir simplement les différents formats de calendrier. Elles sont basées sur un comptage de jour Julien. Le comptage Julien est un comptage commençant le 1er janvier 4713 av. J.-C. Pour convertir les différents calendriers, il faut tout d'abord convertir en nombre de jours Julien, puis, dans le type de calendrier du choix. Le comptage de jours Julien est très différent du calendrier Julien ! Pour plus d'informations sur le comptage en jours Julien, visitez cette page : » http://www.hermetic.ch/cal_stud/jdn.htm. Pour plus d'informations sur les différents calendriers, visitez cette page : » http://www.fourmilab.ch/documents/calendar/. Des extraits de cette page sont inclus dans ces instructions et sont entre guillemets.

# Installation/Configuration

## Sommaire

- Installation

## Installation

Pour faire fonctionner ces fonctions avec PHP, il faut le compiler avec l'option --enable-calendar.

La version Windows de PHP dispose du support automatique de cette extension. Vous n'avez pas à ajouter de bibliothèque supplémentaire pour disposer de ces fonctions.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`CAL_EASTER_DEFAULT` (int)
  Pour easter_days() : calcule Pâques pour les années avant 1753 selon le calendrier julien, et pour les années ultérieures selon le calendrier grégorien.
`CAL_EASTER_ROMAN` (int)
  Pour easter_days() : calcule Pâques pour les années avant 1583 selon le calendrier julien, et pour les années ultérieures selon le calendrier grégorien.
`CAL_EASTER_ALWAYS_GREGORIAN` (int)
  Pour easter_days() : calcule Pâques selon le calendrier grégorien proleptique.
`CAL_EASTER_ALWAYS_JULIAN` (int)
  Pour easter_days() : calcule Pâques selon le calendrier julien.
`CAL_GREGORIAN` (int)
  Pour cal_days_in_month(), cal_from_jd(), cal_info() et cal_to_jd() : utilise le calendrier grégorien proleptique.
`CAL_JULIAN` (int)
  Pour cal_days_in_month(), cal_from_jd(), cal_info() et cal_to_jd() : utilise le calendrier julien.
`CAL_JEWISH` (int)
  Pour cal_days_in_month(), cal_from_jd(), cal_info() et cal_to_jd() : utilise le calendrier hébraïque.
`CAL_FRENCH` (int)
  Pour cal_days_in_month(), cal_from_jd(), cal_info() et cal_to_jd() : utilise le calendrier républicain.
`CAL_NUM_CALS` (int)
  Le nombre de calendriers disponibles.
`CAL_JEWISH_ADD_ALAFIM_GERESH` (int)
  Pour jdtojewish() : ajoute un symbole geresh (qui ressemble à une apostrophe) en tant que séparateur de milliers au numéro de l'année.
`CAL_JEWISH_ADD_ALAFIM` (int)
  Pour jdtojewish() : ajoute le mot alafim en tant que séparateur de milliers au numéro de l'année.
`CAL_JEWISH_ADD_GERESHAYIM` (int)
  Pour jdtojewish() : ajoute un symbole gershayim (qui ressemble à un guillemet) avant la lettre finale des nombres de jour et d'année.
`CAL_DOW_DAYNO` (int)
  Pour jddayofweek() : le jour de la semaine en tant que int, où `0` signifie dimanche et `6` signifie samedi.
`CAL_DOW_SHORT` (int)
  Pour jddayofweek() : le nom anglais abrégé du jour de la semaine.
`CAL_DOW_LONG` (int)
  Pour jddayofweek() : le nom anglais du jour de la semaine.
`CAL_MONTH_GREGORIAN_SHORT` (int)
  Pour jdmonthname() : le nom de mois grégorien abrégé.
`CAL_MONTH_GREGORIAN_LONG` (int)
  Pour jdmonthname() : le nom de mois grégorien.
`CAL_MONTH_JULIAN_SHORT` (int)
  Pour jdmonthname() : le nom de mois julien abrégé.
`CAL_MONTH_JULIAN_LONG` (int)
  Pour jdmonthname() : le nom de mois julien.
`CAL_MONTH_JEWISH` (int)
  Pour jdmonthname() : le nom de mois hébraïque.
`CAL_MONTH_FRENCH` (int)
  Pour jdmonthname() : le nom de mois républicain.

# Calendar Fonctions

# cal_days_in_month

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_days_in_month — Retourne le nombre de jours dans un mois, pour une année et un calendrier donnés

### Description

function cal_days_in_month(int `$calendar`, int `$month`, int `$year`): int

Retourne le nombre de jours dans le mois `month` de l'année `year`, pour le calendrier `calendar`.

### Liste de paramètres

`calendar`

  Calendrier à utiliser pour le calcul

`month`

  Mois dans le calendrier sélectionné

`year`

  Année dans le calendrier sélectionné

### Valeurs de retour

Le nombre de jours dans le mois sélectionné, dans le calendrier fourni.

### Exemples

Exemple #1 Exemple avec cal_days_in_month()

    <?php
    $number = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
    echo "Il y avait {$number} jours en août 2003";
    ?>

# cal_from_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_from_jd — Convertit le nombre de jours Julien en un calendrier spécifique

### Description

function cal_from_jd(int `$julian_day`, int `$calendar`): array

cal_from_jd() convertit le nombre de jours Julien `julian_day` en une date du calendrier `calendar`. Les valeurs possibles pour `calendar` sont `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` et `CAL_FRENCH`.

### Liste de paramètres

`julian_day`

  Jour Julien, sous la forme d'un entier

`calendar`

  Calendrier à utiliser

### Valeurs de retour

Retourne un tableau contenant des informations sur le calendrier, comme le mois, le jour, l'année, le jour de la semaine (`dow`), les noms abrégés et complets des jours de la semaine et du mois, et la date, sous la forme d'une chaîne de caractères "mois/jour/année". L'intervalle du jour de la semaine va de `0` (dimanche) à `6` (samedi).

### Exemples

Exemple #1 Exemple avec cal_from_jd()

    <?php
    $today = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
    print_r(cal_from_jd($today, CAL_GREGORIAN));
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
       [date] => 8/16/2003
       [month] => 8
       [day] => 16
       [year] => 2003
       [dow] => 6
       [abbrevdayname] => Sat
       [dayname] => Saturday
       [abbrevmonth] => Aug
       [monthname] => August
    )

### Voir aussi

- cal_to_jd() - Convertit un calendrier en nombre de jours Julien
- jdtofrench() - Convertit le nombre de jours du calendrier Julien en date du calendrier français républicain
- jdtogregorian() - Convertit le nombre de jours du calendrier Julien en date grégorienne
- jdtojewish() - Convertit le nombre de jours du calendrier Julien en date du calendrier juif
- jdtojulian() - Convertit le nombre de jours du calendrier Julien en date du calendrier Julien
- jdtounix() - Convertit un jour Julien en timestamp UNIX

# cal_info

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_info — Retourne des détails sur un calendrier

### Description

function cal_info(int `$calendar` = -1): array

cal_info() retourne des informations sur le calendrier `calendar` spécifié.

Les informations de calendriers sont retournées dans un tableau qui contient les éléments `calname`, `calsymbol`, `month`, `abbrevmonth` et `maxdaysinmonth`. Les noms des différents calendriers qui peuvent être utilisés dans le paramètre `calendar` sont les suivants :

- 0 ou `CAL_GREGORIAN` - Calendrier Grégorien
- 1 ou `CAL_JULIAN` - Calendrier Julien
- 2 ou `CAL_JEWISH` - Calendrier juif
- 3 ou `CAL_FRENCH` - Calendrier révolutionnaire français

Si le paramètre `calendar` n'est pas spécifié, un tableau représentant tous les calendriers est retourné.

### Liste de paramètres

`calendar`

  Calendrier dont on souhaite des informations. Si aucun calendrier n'est spécifié, des informations sur tous les calendriers seront retournées.

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec cal_info()

    <?php
    $info = cal_info(0);
    print_r($info);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [months] => Array
            (
                [1] => January
                [2] => February
                [3] => March
                [4] => April
                [5] => May
                [6] => June
                [7] => July
                [8] => August
                [9] => September
                [10] => October
                [11] => November
                [12] => December
            )

        [abbrevmonths] => Array
            (
                [1] => Jan
                [2] => Feb
                [3] => Mar
                [4] => Apr
                [5] => May
                [6] => Jun
                [7] => Jul
                [8] => Aug
                [9] => Sep
                [10] => Oct
                [11] => Nov
                [12] => Dec
            )

        [maxdaysinmonth] => 31
        [calname] => Gregorian
        [calsymbol] => CAL_GREGORIAN
    )

# cal_to_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_to_jd — Convertit un calendrier en nombre de jours Julien

### Description

function cal_to_jd(
int `$calendar`,
int `$month`,
int `$day`,
int `$year`
): int

cal_to_jd() calcule le nombre de jours Julien pour une date, dans le calendrier `calendar`. Les valeurs possibles pour `calendar` sont `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` et `CAL_FRENCH`.

### Liste de paramètres

`calendar`

  Calendrier à convertir. Un parmi `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` ou `CAL_FRENCH`.

`month`

  Le mois, sous la forme d'un nombre. L'intervalle valide dépend du calendrier `calendar`

`day`

  Le jour, sous la forme d'un nombre. L'intervalle valide dépend du calendrier `calendar`

`year`

  L'année, sous la forme d'un nombre. L'intervalle valide dépend du calendrier `calendar`

### Valeurs de retour

Le nombre de jours Julien.

### Voir aussi

- cal_from_jd() - Convertit le nombre de jours Julien en un calendrier spécifique
- frenchtojd() - Convertit une date du calendrier français républicain en nombre de jours du calendrier Julien
- gregoriantojd() - Convertit une date grégorienne en nombre de jours du calendrier julien
- jewishtojd() - Convertit une date du calendrier juif en nombre de jours du calendrier julien
- juliantojd() - Convertit un jour du calendrier Julien en un nombre de jours du calendrier Julien
- unixtojd() - Convertit un timestamp UNIX en un jour Julien

# easter_date

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_date — Retourne le timestamp Unix pour minuit local le jour de Pâques d'une année donnée

### Description

function easter_date(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

Retourne un timestamp UNIX pour Pâques, à minuit, pour une année donnée.

La date de Pâques a été fixée par le concile de Nicée, en 325 de notre ère, comme étant le dimanche après la première pleine lune qui suit l'équinoxe de printemps. L'équinoxe de printemps est considéré comme étant toujours le 21 mars, ce qui réduit le problème au calcul de la date de la lune pleine qui suit, et le dimanche suivant. L'algorithme fut introduit vers 532, par Dionysius Exiguus. Avec le calendrier julien (pour les années avant 1753), un cycle de 19 ans suffit pour connaître les dates des phases de la lune. Avec le calendrier grégorien (à partir des années 1753, conçu par Clavius et Lilius, puis introduit par le pape Grégoire XIII en octobre 1582, et en Grande-Bretagne et ses colonies en septembre 1752), deux facteurs de correction ont été ajoutés pour rendre le cycle plus précis.

### Liste de paramètres

`year`

  L'année, doit être un nombre compris entre 1970 et 2037 pour les systèmes 32 bits, ou entre 1970 et 2 000 000 000 pour les systèmes 64 bits. Si omis ou `null`, la valeur par défaut sera l'année courante suivant l'heure locale.

`mode`

  Permet de calculer la date de Pâques en fonction du calendrier julien quand défini à `CAL_EASTER_ALWAYS_JULIAN`. Voir aussi les constantes de calendrier.

### Valeurs de retour

La date pour Pâques, sous la forme d'un timestamp unix.

### Erreurs / Exceptions

Une ValueError est déclenchée si l'année est antérieure à 1970 ou postérieure à 2037 lors de l'exécution sur un système 32 bits, ou postérieure à 2 000 000 000 sur un système 64 bits.

### Historique

Version | Description
--- | ---
8.3.0 | Sur les systèmes 64 bits, le paramètre `year` accepte désormais des valeurs dans la plage de 1970 à 2 000 000 000.
8.0.0 | `year` est désormais nullable.
8.0.0 | Une ValueError est désormais déclenchée lorsque `year` est en dehors de la plage autorisée. Auparavant, une alerte `E_WARNING` était générée et la fonction retournait `false`.

### Exemples

Exemple #1 Exemple avec easter_date()

    <?php

    echo date("M-d-Y", easter_date(1999));        // Apr-04-1999
    echo date("M-d-Y", easter_date(2000));        // Apr-23-2000
    echo date("M-d-Y", easter_date(2001));        // Apr-15-2001

    ?>

Exemple #2 Utilisation de easter_date() avec DateTime

    <?php

    $timestamp = easter_date(2023);

    $datetime = new \DateTime();
    $datetime->setTimestamp($timestamp);

    echo $datetime->format('M-d-Y'); // Apr-09-2023

    ?>

### Notes

> Note:

> La fonction easter_date() repose sur les fonctions de la bibliothèque C time du système, plutôt que sur les fonctions date et time internes de PHP. Aussi, la fonction easter_date() utilise la variable d'environnement `TZ` pour déterminer le fuseau horaire à utiliser, plutôt que le fuseau horaire par défaut de PHP, ce qui peut conduire à un comportement non désiré lors de l'utilisation de cette fonction avec d'autres fonctions date de PHP.

> Comme contournement, il est possible d'utiliser la fonction easter_days() avec les classes DateTime et DateInterval pour calculer le jour de Pâques dans le fuseau horaire PHP, comme ceci :

>     <?php
>     function get_easter_datetime($year) {
>         $base = new DateTime("$year-03-21");
>         $days = easter_days($year);

>         return $base->add(new DateInterval("P{$days}D"));
>     }

>     foreach (range(2012, 2015) as $year) {
>         printf("Pâques, en %d, tombe le %s\n",
>                $year,
>                get_easter_datetime($year)->format('d F'));
>     }
>     ?>

> L'exemple ci-dessus va afficher :

>     Pâques, en 2012, tombe le 08 Avril
>     Pâques, en 2013, tombe le 31 Mars
>     Pâques, en 2014, tombe le 20 Avril
>     Pâques, en 2015, tombe le 05 Avril

### Voir aussi

- easter_days() - Retourne le nombre de jours entre le 21 mars et Pâques, pour une année donnée pour le calcul de Pâques avant 1970 et après 2037

# easter_days

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_days — Retourne le nombre de jours entre le 21 mars et Pâques, pour une année donnée

### Description

function easter_days(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

Retourne le nombre de jours entre le 21 mars et Pâques, pour une année donnée. Si l'année n'est pas précisée, l'année courante sera utilisée.

Cette fonction peut être utilisée à la place de easter_date() pour calculer la date de Pâques, pour les années qui tombent hors de l'intervalle de validité des timestamps UNIX (c.-à-d. avant 1970 ou après 2037).

La date de Pâques a été fixée par le concile de Nicée, en 325 de notre ère, comme étant le dimanche après la première pleine lune qui suit l'équinoxe de printemps. L'équinoxe de printemps est considéré comme étant toujours le 21 mars, ce qui réduit le problème au calcul de la date de la lune pleine qui suit, et le dimanche suivant. L'algorithme fut introduit vers 532, par Dionysius Exiguus. Avec le calendrier julien (pour les années avant 1753), un cycle de 19 ans suffit pour connaître les dates des phases de la lune. Avec le calendrier grégorien (à partir des années 1753, conçu par Clavius et Lilius, puis introduit par le pape Grégoire XIII en octobre 1582, et en Grande-Bretagne et ses colonies en septembre 1752), deux facteurs de correction ont été ajoutés pour rendre le cycle plus précis.

### Liste de paramètres

`year`

  L'année, sous la forme d'un nombre positif. Si omis ou `null`, la valeur par défaut sera l'année courante suivant l'heure locale.

`mode`

  Permet le calcul des dates de Pâques en se basant sur le calendrier grégorien pour les années entre 1582 et 1752 lorsque défini à `CAL_EASTER_ROMAN`. Voir les constantes des calendriers pour les autres constantes valides.

### Valeurs de retour

Le nombre de jours entre le 21 mars et Pâques, pour l'année `year` fournie.

### Historique

Version | Description
--- | ---
8.0.0 | `year` est désormais nullable.

### Exemples

Exemple #1 Exemple avec easter_days()

    <?php

    echo easter_days(1999);        // 14, c.-à-d. le 4 avril
    echo easter_days(1492);        // 32, c.-à-d. le 22 avril
    echo easter_days(1913);        //  2, c.-à-d. le 23 mars

    ?>

### Voir aussi

- easter_date() - Retourne le timestamp Unix pour minuit local le jour de Pâques d'une année donnée

# frenchtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

frenchtojd — Convertit une date du calendrier français républicain en nombre de jours du calendrier Julien

### Description

function frenchtojd(int `$month`, int `$day`, int `$year`): int

frenchtojd() convertit une date du calendrier français républicain en nombre de jours du calendrier Julien.

Cette fonction convertit les dates comprises entre l'an 1 et l'an 14 (du 22 septembre 1792 au 22 septembre 1806 en calendrier grégorien). Cela couvre plus que la durée d'existence de ce calendrier.

### Liste de paramètres

`month`

  Le mois, sous la forme d'un nombre de 1 (pour Vendémiaire) à 13 (pour la période de 5-6 jours à la fin de chaque année)

`day`

  Le jour, sous la forme d'un nombre compris entre 1 et 30

`year`

  L'année, sous la forme d'un nombre compris entre 1 et 14

### Valeurs de retour

Le jour Julien pour la date fournie du calendrier français républicain, sous la forme d'un entier.

### Voir aussi

- jdtofrench() - Convertit le nombre de jours du calendrier Julien en date du calendrier français républicain
- cal_to_jd() - Convertit un calendrier en nombre de jours Julien

# gregoriantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

gregoriantojd — Convertit une date grégorienne en nombre de jours du calendrier julien

### Description

function gregoriantojd(int `$month`, int `$day`, int `$year`): int

L'intervalle de validité pour le calendrier grégorien est du 25 novembre, 4714 avant J.-C. au moins jusqu'au 31 décembre 9999 après J.-C.

Bien qu'il soit possible de manipuler des dates jusqu'en 4714 avant J.-C., une telle utilisation n'est pas significative. En effet, ce calendrier fut créé le 15 octobre 1582 après J.-C. (ou 5 octobre 1582 en calendrier julien). Certains pays ne l'acceptèrent que bien plus tard. Par exemple, la Grande-Bretagne n'y passa qu'en 1752, l'URSS en 1918 et la Grèce en 1923. La plupart des pays européens utilisaient le calendrier julien avant le grégorien.

### Liste de paramètres

`month`

  Le mois, sous la forme d'un nombre compris entre 1 (pour janvier) et 12 (pour décembre)

`day`

  Le jour, sous la forme d'un nombre compris entre 1 et 31. Si le mois a moins de jours que fourni, un débordement se produit ; voir exemple ci-dessous.

`year`

  L'année, sous la forme d'un nombre compris entre -4714 et 9999. Les nombres négatifs signifient les années avant J.-C., les nombres positifs signifient après J.-C. Il est à noter qu'il n'y a pas d'année `0` ; 31 décembre, 1 avant J.-C. est immédiatement suivi par 1 janvier, 1 après J.-C.

### Valeurs de retour

Le jour julien pour la date grégorienne fournie, sous la forme d'un entier. Les dates en dehors de l'intervalle valide retournent `0`.

### Exemples

Exemple #1 Fonctions calendrier

    <?php
    $jd = gregoriantojd(10, 11, 1970);
    echo "$jd\n";
    $gregorian = jdtogregorian($jd);
    echo "$gregorian\n";
    ?>

L'exemple ci-dessus va afficher :

    2440871
    10/11/1970

Exemple #2 Comportement de débordement

    <?php
    echo gregoriantojd(2, 31, 2018), PHP_EOL,
         gregoriantojd(3,  3, 2018), PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    2458181
    2458181

### Voir aussi

- jdtogregorian() - Convertit le nombre de jours du calendrier Julien en date grégorienne
- cal_to_jd() - Convertit un calendrier en nombre de jours Julien

# jddayofweek

(PHP 4, PHP 5, PHP 7, PHP 8)

jddayofweek — Retourne le numéro du jour de la semaine

### Description

function jddayofweek(int `$julian_day`, int `$mode` = `CAL_DOW_DAYNO`): int|string

Retourne le numéro du jour de la semaine. Peut retourner une chaîne ou un entier, en fonction du mode.

### Liste de paramètres

`julian_day`

  Le numéro du jour Julien, sous la forme d'un entier

`mode`

  Modes pour la semaine du calendrier
  Mode | Signification
  --- | ---
  0 (défaut) | Retourne le numéro du jour comme un entier (0=dimanche, 1=lundi, etc.)
  1 | Retourne une chaîne contenant le nom du jour (anglais grégorien)
  2 | Retourne une chaîne contenant le nom abrégé du jour de la semaine (anglais grégorien)

### Valeurs de retour

Le jour de la semaine grégorien, sous la forme d'un entier ou d'une chaîne de caractères.

# jdmonthname

(PHP 4, PHP 5, PHP 7, PHP 8)

jdmonthname — Retourne le nom du mois

### Description

function jdmonthname(int `$julian_day`, int `$mode`): string

Retourne une chaîne contenant le nom du mois. `mode` indique de quel calendrier dépend ce mois, et quel type de nom doit être retourné.

Modes de calendrier
Mode | Signification | Valeurs
--- | --- | ---
`CAL_MONTH_GREGORIAN_SHORT` | Grégorien - abrégé | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_GREGORIAN_LONG` | Grégorien | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JULIAN_SHORT` | Julien - abrégé | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_JULIAN_LONG` | Julien | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JEWISH` | Juif | Tishri, Heshvan, Kislev, Tevet, Shevat, Adar, Adar I, Adar II, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
`CAL_MONTH_FRENCH` | Républicain français | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

### Liste de paramètres

`julian_day`

  Le jour Julien à analyser

`mode`

  Le mode de calendrier (voir tableau ci-dessus).

### Valeurs de retour

Le nom du mois pour le jour Julien et le `mode`.

# jdtofrench

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtofrench — Convertit le nombre de jours du calendrier Julien en date du calendrier français républicain

### Description

function jdtofrench(int `$julian_day`): string

Convertit le nombre de jours du calendrier julien en date du calendrier français républicain.

### Liste de paramètres

`julian_day`

  Le numéro du jour Julien, sous la forme d'un entier

### Valeurs de retour

La date française républicaine, sous la forme d'une chaîne de caractères "mois/jour/année".

### Voir aussi

- frenchtojd() - Convertit une date du calendrier français républicain en nombre de jours du calendrier Julien
- cal_from_jd() - Convertit le nombre de jours Julien en un calendrier spécifique

# jdtogregorian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtogregorian — Convertit le nombre de jours du calendrier Julien en date grégorienne

### Description

function jdtogregorian(int `$julian_day`): string

Convertit le nombre de jours du calendrier Julien en une chaîne contenant une date du calendrier grégorien, au format "mois/jour/année".

### Liste de paramètres

`julian_day`

  Le numéro du jour Julien, sous la forme d'un entier

### Valeurs de retour

La date grégorienne, sous la forme d'une chaîne de caractères "mois/jour/année".

### Voir aussi

- gregoriantojd() - Convertit une date grégorienne en nombre de jours du calendrier julien
- cal_from_jd() - Convertit le nombre de jours Julien en un calendrier spécifique

# jdtojewish

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojewish — Convertit le nombre de jours du calendrier Julien en date du calendrier juif

### Description

function jdtojewish(int `$julian_day`, bool `$hebrew` = `false`, int `$flags` = 0): string

Convertit un nombre de jours du calendrier Julien en calendrier juif.

### Liste de paramètres

`julian_day`

  Un nombre de jour Julien sous forme d'entier.

`hebrew`

  Si le paramètre `hebrew` est défini à `true`, le paramètre `flags` est utilisé pour l'hébreu, format de sortie basé sur une chaîne de caractères encodée en ISO-8859-8.

`flags`

  Un masque de bits pouvant être composé de `CAL_JEWISH_ADD_ALAFIM_GERESH`, `CAL_JEWISH_ADD_ALAFIM` et `CAL_JEWISH_ADD_GERESHAYIM`.

### Valeurs de retour

La date juive, sous la forme d'une chaîne de caractères "mois/jour/année", ou une chaîne de caractères de date hébraïque codée ISO-8859-8, en fonction du paramètre `hebrew`.

### Exemples

Exemple #1 Exemple avec jdtojewish()

    <?php
    $jd = gregoriantojd(10, 8, 2002);
    echo jdtojewish($jd, true), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_GERESHAYIM), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_ALAFIM), PHP_EOL,
         jdtojewish($jd, true,CAL_JEWISH_ADD_ALAFIM_GERESH), PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    ב חשון התשסג
    ב' חשון התשס"ג
    ב חשון ה אלפים תשסג
    ב חשון ה'תשסג

### Voir aussi

- jewishtojd() - Convertit une date du calendrier juif en nombre de jours du calendrier julien
- cal_from_jd() - Convertit le nombre de jours Julien en un calendrier spécifique

# jdtojulian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojulian — Convertit le nombre de jours du calendrier Julien en date du calendrier Julien

### Description

function jdtojulian(int `$julian_day`): string

Convertit le nombre de jours du calendrier Julien en une chaîne contenant la date du calendrier Julien, au format "mois/jour/année".

### Liste de paramètres

`julian_day`

  Le nombre de jours Julien, sous la forme d'un entier

### Valeurs de retour

La date julienne, sous la forme d'une chaîne de caractères "mois/jour/année".

### Voir aussi

- juliantojd() - Convertit un jour du calendrier Julien en un nombre de jours du calendrier Julien
- cal_from_jd() - Convertit le nombre de jours Julien en un calendrier spécifique

# jdtounix

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtounix — Convertit un jour Julien en timestamp UNIX

### Description

function jdtounix(int `$julian_day`): int

Retourne un timestamp UNIX correspondant au jour Julien `julian_day`. Le temps retourné est UTC.

### Liste de paramètres

`julian_day`

  Le nombre de jours Julien, compris entre `2440588` et `106751993607888` sur les systèmes 64bit, ou compris entre `2440588` et `2465443` sur les systèmes 32bit.

### Valeurs de retour

Le timestamp unix pour le début (minuit, pas midi) du jour Julien donné.

### Erreurs / Exceptions

Si `julian_day` est hors de l'intervalle autorisé, une ValueError est lancée.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction ne retourne désormais plus `false` en cas d'échec, mais lève une ValueError à la place.
7.3.24, 7.4.12 | La limite supérieure du paramètre `julian_day` a été étendue. Avant, elle était de `2465342` suivant l'architecture.

### Voir aussi

- unixtojd() - Convertit un timestamp UNIX en un jour Julien

# jewishtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

jewishtojd — Convertit une date du calendrier juif en nombre de jours du calendrier julien

### Description

function jewishtojd(int `$month`, int `$day`, int `$year`): int

Bien qu'il soit possible de manipuler des dates à partir de l'an 1 (3761 avant J.C.), une telle utilisation a peu de sens. Le calendrier juif a été utilisé depuis plusieurs dizaines de siècles, mais dans les premiers temps, il n'y avait pas de formule pour déterminer le début du mois. Un nouveau mois commençait quand une nouvelle lune était observée.

### Liste de paramètres

`month`

  Le mois, sous la forme d'un nombre entre `1` et `13`, où `1` signifie `Tishri`, `13` signifie `Elul`, et `6` et `7` signifient `Adar` dans les années régulières, mais `Adar I` et `Adar II`, respectivement, dans les années bissextiles.

`day`

  Le jour, sous la forme d'un nombre entre `1` et `30`. Si le mois n'a que 29 jours, le premier jour du mois suivant est supposé.

`year`

  L'année, sous la forme d'un nombre entre 1 et 9999

### Valeurs de retour

Le jour julien pour la date juive donnée, sous la forme d'un entier.

### Voir aussi

- jdtojewish() - Convertit le nombre de jours du calendrier Julien en date du calendrier juif
- cal_to_jd() - Convertit un calendrier en nombre de jours Julien

# juliantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

juliantojd — Convertit un jour du calendrier Julien en un nombre de jours du calendrier Julien

### Description

function juliantojd(int `$month`, int `$day`, int `$year`): int

Intervalle de validité du calendrier Julien : 4713 avant J.-C. à 9999 après J.-C.

Bien qu'il soit possible de manipuler des dates jusqu'en 4713 avant J.-C., une telle utilisation n'est pas significative. En effet, ce calendrier fut créé en 46 avant J.-C., et ses détails ne furent finalisés qu'au plus tôt en 8 après J.-C., et probablement pas avant le quatrième siècle après J.-C. De plus, le début de l'année variait suivant les peuples, certains n'acceptant pas janvier comme premier mois de l'année.

Attention

Il faut se rappeler que le calendrier actuellement utilisé dans le monde est un calendrier grégorien. gregoriantojd() peut être utilisé pour convertir ce genre de dates en un nombre de jours du calendrier Julien.

### Liste de paramètres

`month`

  Le mois, sous la forme d'un nombre entre 1 (pour janvier) et 12 (pour décembre)

`day`

  Le jour, sous la forme d'un nombre entre 1 et 31

`year`

  L'année, sous la forme d'un nombre entre -4713 et 9999

### Valeurs de retour

Le jour julien pour la date julienne donnée, sous la forme d'un entier.

### Voir aussi

- jdtojulian() - Convertit le nombre de jours du calendrier Julien en date du calendrier Julien
- cal_to_jd() - Convertit un calendrier en nombre de jours Julien

# unixtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

unixtojd — Convertit un timestamp UNIX en un jour Julien

### Description

function unixtojd(?int `$timestamp` = `null`): int|false

Retourne le jour Julien du timestamp UNIX `timestamp` (nombre de secondes depuis le 1/1/1970), ou pour le jour courant si `timestamp` est omis. De toute façon, l'heure est considérée comme l'heure locale (pas UTC).

### Liste de paramètres

`timestamp`

  Un timestamp unix à convertir.

### Valeurs de retour

Un nombre de jours Julien, sous la forme d'un entier, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `timestamp` est désormais nullable.

### Voir aussi

- jdtounix() - Convertit un jour Julien en timestamp UNIX

## Sommaire

- cal_days_in_month — Retourne le nombre de jours dans un mois, pour une année et un calendrier donnés
- cal_from_jd — Convertit le nombre de jours Julien en un calendrier spécifique
- cal_info — Retourne des détails sur un calendrier
- cal_to_jd — Convertit un calendrier en nombre de jours Julien
- easter_date — Retourne le timestamp Unix pour minuit local le jour de Pâques d'une année donnée
- easter_days — Retourne le nombre de jours entre le 21 mars et Pâques, pour une année donnée
- frenchtojd — Convertit une date du calendrier français républicain en nombre de jours du calendrier Julien
- gregoriantojd — Convertit une date grégorienne en nombre de jours du calendrier julien
- jddayofweek — Retourne le numéro du jour de la semaine
- jdmonthname — Retourne le nom du mois
- jdtofrench — Convertit le nombre de jours du calendrier Julien en date du calendrier français républicain
- jdtogregorian — Convertit le nombre de jours du calendrier Julien en date grégorienne
- jdtojewish — Convertit le nombre de jours du calendrier Julien en date du calendrier juif
- jdtojulian — Convertit le nombre de jours du calendrier Julien en date du calendrier Julien
- jdtounix — Convertit un jour Julien en timestamp UNIX
- jewishtojd — Convertit une date du calendrier juif en nombre de jours du calendrier julien
- juliantojd — Convertit un jour du calendrier Julien en un nombre de jours du calendrier Julien
- unixtojd — Convertit un timestamp UNIX en un jour Julien

- Installation/Configuration
  - Installation
- Constantes pré-définies
- Calendar Fonctions
  - cal_days_in_month — Retourne le nombre de jours dans un mois, pour une année et un calendrier donnés
  - cal_from_jd — Convertit le nombre de jours Julien en un calendrier spécifique
  - cal_info — Retourne des détails sur un calendrier
  - cal_to_jd — Convertit un calendrier en nombre de jours Julien
  - easter_date — Retourne le timestamp Unix pour minuit local le jour de Pâques d'une année donnée
  - easter_days — Retourne le nombre de jours entre le 21 mars et Pâques, pour une année donnée
  - frenchtojd — Convertit une date du calendrier français républicain en nombre de jours du calendrier Julien
  - gregoriantojd — Convertit une date grégorienne en nombre de jours du calendrier julien
  - jddayofweek — Retourne le numéro du jour de la semaine
  - jdmonthname — Retourne le nom du mois
  - jdtofrench — Convertit le nombre de jours du calendrier Julien en date du calendrier français républicain
  - jdtogregorian — Convertit le nombre de jours du calendrier Julien en date grégorienne
  - jdtojewish — Convertit le nombre de jours du calendrier Julien en date du calendrier juif
  - jdtojulian — Convertit le nombre de jours du calendrier Julien en date du calendrier Julien
  - jdtounix — Convertit un jour Julien en timestamp UNIX
  - jewishtojd — Convertit une date du calendrier juif en nombre de jours du calendrier julien
  - juliantojd — Convertit un jour du calendrier Julien en un nombre de jours du calendrier Julien
  - unixtojd — Convertit un timestamp UNIX en un jour Julien

# Date et Heure

# Introduction

DateTimeImmutable et les classes associées permettent de représenter les informations de date et d'heure. Les objets peuvent être créés en passant les informations de date et d'heure via une chaîne de caractères, ou à partir de l'heure du système utilisé.

Un riche ensemble de méthodes est fourni pour modifier et formater ces informations ainsi que la gestion des fuseaux horaires et des transitions DST.

Les fonctionnalités de date/heure de PHP implémentent le calendrier ISO 8601, qui est un » calendrier grégorien proleptique implémentant les règles actuelles des jours bissextiles d'avant la mise en place du calendrier grégorien, et inclut également l'année `0` comme numéro d'année comprise entre `-1 avant l'ère commune` et `1 de l'ère commune`. Les secondes intercalaires ne sont pas prises en charge.

Les informations quant à la date et l'heure sont stockées en interne comme nombre sur 64 bits, aussi, toutes les dates imaginables (y compris les dates négatives) sont supportées. L'intervalle va de 292 milliards d'années dans le passé, et la même valeur dans le futur.

> Note: Les fuseaux horaires référencés dans cette section peuvent être trouvés dans la section Liste des Fuseaux Horaires Supportés.

# Installation/Configuration

## Sommaire

- Installation
- Configuration à l'exécution

## Installation

Il n'y pas d'installation nécessaire pour utiliser ces fonctions, elles font parties du cœur de PHP.

> Note: Récupération de la dernière base de données des fuseaux horaires

> La dernière version de la base de données des fuseaux horaires peut être installée via le paquet PECL » timezonedb.

## Configuration à l'exécution

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

Options de configurations pour les dates et heures
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
date.default_latitude | "31.7667" | `INI_ALL` |
date.default_longitude | "35.2333" | `INI_ALL` |
date.sunrise_zenith | "90.833333" | `INI_ALL` | Avant PHP 8.0.0, la valeur par défaut était "90.583333"
date.sunset_zenith | "90.833333" | `INI_ALL` | Avant PHP 8.0.0, la valeur par défaut était "90.583333"
date.timezone | "UTC" | `INI_ALL` | À partir de PHP 8.2, un avertissement est émis si l'option est définie avec une valeur invalide ou une chaîne vide.

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`date.default_latitude` float

  La latitude par défaut allant de `0` à l'équateur, jusqu'à `+90` en direction du nord, et `-90` en direction du sud.

`date.default_longitude` float

  La longitude par défaut allant de `0` au méridien d'origine, jusqu'à `+180` en direction de l'est, et `-180` en direction de l'ouest.

`date.sunrise_zenith` float

  L'angle de zénith du lever du soleil par défaut.

  La valeur par défaut est 90°50'. Les 50' supplémentaires sont dus à deux composantes : le rayon du Soleil, qui est de 16', et la réfraction atmosphérique, qui est de 34'.

`date.sunset_zenith` float

  L'angle de zénith du coucher du soleil par défaut.

`date.timezone` string

  Le fuseau horaire par défaut utilisé par toutes les fonctions date/heure. L'ordre des fuseaux horaires utilisés si aucun n'est spécifié est explicitement décrit dans la page de documentation sur la fonction date_default_timezone_get(). Voir Liste des Fuseaux Horaires Supportés pour une liste complète des fuseaux horaires supportés.

> Note: Les quatre premières options de configuration sont actuellement utilisées uniquement par les fonctions date_sunrise() et date_sunset().

# Constantes pré-définies

Les constantes `DATE_*` sont définies et offrent des standards des dates, qui peuvent être utilisés avec toutes les fonctions de formatage de date (comme date()).

Formats de retour `returnFormat` disponibles pour date_sunrise() et date_sunset()
Avertissement

Ces constantes sont dépréciées à partir de PHP 8.4.0. Les fonctions correspondantes date_sunrise() et date_sunset() sont dépréciées à partir de PHP 8.1.0.

`SUNFUNCS_RET_TIMESTAMP` (int)
  Timestamp
`SUNFUNCS_RET_STRING` (int)
  Heures:minutes (exemple: `08:02`)
`SUNFUNCS_RET_DOUBLE` (int)
  Heures en tant que nombre à virgule flottante (exemple `8.75`)

`DATE_*` constantes
`DATE_ATOM` (string)
  Atom (exemple : `2005-08-15T15:52:01+00:00`) ; compatible avec ISO-8601, RFC 3339 et XML Schema
`DATE_COOKIE` (string)
  Cookies HTTP (exemple : `Monday, 15-Aug-2005 15:52:01 UTC`)
`DATE_ISO8601` (string)
  Semblable à ISO-8601 (exemple : `2005-08-15T15:52:01+0000`)

  > Note: Ce format n'est pas compatible avec ISO-8601, mais il est resté ainsi pour des raisons de compatibilité ascendante. Utiliser `DATE_ISO8601_EXPANDED`, `DATE_ATOM` pour une compatibilité avec ISO-8601 à la place (ref ISO8601:2004 section 4.3.3 clause d).

`DATE_ISO8601_EXPANDED` (string)
  ISO-8601 Expanded (exemple : `+10191-07-26T08:59:52+01:00`)

  > Note: Ce format permet des plages d'années en dehors de la plage normale d'ISO-8601 de `0000` à `9999` en incluant toujours un caractère de signe. Il s'assure également de la compatibilité de la partie du fuseau horaire (`+01:00`) avec ISO-8601.

`DATE_RFC822` (string)
  RFC 822 (exemple : `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC850` (string)
  RFC 850 (exemple : `Monday, 15-Aug-05 15:52:01 UTC`)
`DATE_RFC1036` (string)
  RFC 1036 (exemple : `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC1123` (string)
  RFC 1123 (exemple : `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC7231` (string)
  RFC 7231 (à partir de PHP 7.0.19 et 7.1.5) (exemple : `Sat, 30 Apr 2016 17:52:13 GMT`)
`DATE_RFC2822` (string)
  RFC 2822 (exemple : `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC3339` (string)
  Identique à `DATE_ATOM`.
`DATE_RFC3339_EXTENDED` (string)
  Format étendu RFC 3339 (exemple : `2005-08-15T15:52:01.000+00:00`)
`DATE_RSS` (string)
  RSS (exemple : `Mon, 15 Aug 2005 15:52:01 +0000`). Alias de `DATE_RFC1123`.
`DATE_W3C` (string)
  World Wide Web Consortium (exemple : `2005-08-15T15:52:01+00:00`). Alias de `DATE_RFC3339`.

# Exemples

## Sommaire

- Arithmétique avec DateTime

## Arithmétique avec DateTime

Les exemples suivants montrent quelques pièges de l'arithmétique de DateTime en ce qui concerne les transitions DST et les mois ayant un nombre différent de jours.

Exemple #1 DateTimeImmutable::add/sub ajout d'un intervalle de temps écoulé

Ajouter PT24H au-delà d'une transition DST semblera ajouter 23/25 heures (pour la plupart des fuseaux horaires).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->add(new DateInterval("PT3H"));
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

L'exemple ci-dessus va afficher :

    Start: 2015-11-01 00:00:00 -04:00
    End:   2015-11-01 02:00:00 -05:00

Exemple #2 DateTimeImmutable::modify et strtotime incrémentation ou décrémentation de valeurs individuelles

Ajouter +24 heures au-delà d'une transition DST peut ajouter exactement 24 heures comme vu avec la chaîne date/time (sauf si l'heure de début ou de fin est sur un point de transition).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+24 hours");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

L'exemple ci-dessus va afficher :

    Start: 2015-11-01 00:00:00 -04:00
    End:   2015-11-02 00:00:00 -05:00

Exemple #3 L'ajout ou la soustraction de dates/heures peut dépasser (en plus ou en moins) des dates

Comme pour 31 janvier + 1 mois donnera comme résultat 2 mars (année bissextile) ou 3 mars (année normale).

    <?php
    echo "Normal year:\n"; // February has 28 days
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Leap year:\n"; // February has 29 days
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

L'exemple ci-dessus va afficher :

    Normal year:
    Start: 2015-01-31 00:00:00 -05:00
    End:   2015-03-03 00:00:00 -05:00
    Leap year:
    Start: 2016-01-31 00:00:00 -05:00
    End:   2016-03-02 00:00:00 -05:00

Pour obtenir le dernier jour du mois prochain (autrement dit pour prévenir le dépassement), le format `last day of` est disponible.

    <?php
    echo "Normal year:\n"; // February has 28 days
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Leap year:\n"; // February has 29 days
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

L'exemple ci-dessus va afficher :

    Normal year:
    Start: 2015-01-31 00:00:00 -05:00
    End:   2015-02-28 00:00:00 -05:00
    Leap year:
    Start: 2016-01-31 00:00:00 -05:00
    End:   2016-02-29 00:00:00 -05:00

# La classe DateTime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Introduction

Représentation de la date et du temps.

Cette classe se comporte comme DateTimeImmutable, à l'exception que les objets se modifient eux-mêmes quand une méthode de modification telle que DateTime::modify() est appelée.

Avertissement

L'appel de méthodes sur des objets de la classe DateTime modifiera les informations encapsulées dans ces objets, si l'on veut éviter cela, on devra utiliser l'opérateur `clone` pour créer un nouvel objet. L'utilisation de DateTimeImmutable au lieu de DateTime est recommandée pour obtenir ce comportement par défaut.

## Synopsis de la classe

class DateTime implements DateTimeInterface {
/* Constantes héritées */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Méthodes */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
public function add(DateInterval `$interval`): DateTime
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false
public static function createFromImmutable(DateTimeImmutable `$object`): static
public static function createFromInterface(DateTimeInterface `$object`): DateTime
public static function createFromTimestamp(int|float `$timestamp`): static
public function modify(string `$modifier`): DateTime
public static function __set_state(array `$array`): DateTime
public function setDate(int `$year`, int `$month`, int `$day`): DateTime
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime
public function setMicrosecond(int `$microsecond`): static
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime
public function setTimestamp(int `$timestamp`): DateTime
public function setTimezone(DateTimeZone `$timezone`): DateTime
public function sub(DateInterval `$interval`): DateTime
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.
7.2.0 | Les constantes de classe de DateTime sont maintenant définies sur DateTimeInterface.
7.1.0 | Le constructeur de DateTime inclut désormais les microsecondes actuelles dans la valeur construite. Avant cela, il initialisait toujours les microsecondes à `0`.

# DateTime::add

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::add -- date_add — Modifie un objet DateTime, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté

### Description

Style orienté objet

public function DateTime::add(DateInterval `$interval`): DateTime

Style procédural

function date_add(DateTime `$object`, DateInterval `$interval`): DateTime

Ajoute la durée de l'objet DateInterval à l'objet DateTime.

Comme DateTimeImmutable::add() mais fonctionne avec DateTime.

La version procédurale prend un objet DateTime comme premier argument.

### Liste de paramètres

`object`
  Style procédural uniquement : Un objet DateTime retourné par la fonction date_create(). Cette fonction modifie cet objet.
`interval`

  Un objet DateInterval

### Valeurs de retour

Retourne l'objet modifié DateTime pour chainer les méthodes.

### Voir aussi

- DateTimeImmutable::add() - Retourne un nouvel objet, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté

# DateTime::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::__construct — Retourne un nouvel objet DateTime

### Description

public function DateTime::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Comme DateTimeImmutable::__construct() mais fonctionne avec DateTime. Considérer l'utilisation de DateTimeImmutable et ses fonctionnalités à la place.

Retourne un nouvel objet DateTime.

### Liste de paramètres

`datetime`

  Une chaîne date/heure. Les formats valides sont expliqués dans la documentation sur les formats Date et Heure.

  Passer `"now"` pour obtenir le temps courant lors de l'utilisation du paramètre `$timezone`.

`timezone`

  Un objet DateTimeZone représentant le fuseau horaire de `$datetime`.

  Si `$timezone` est omis ou `null`, le fuseau horaire actuel sera utilisé.

  > Note:

  > Le paramètre `$timezone` et le fuseau horaire actuel sont ignorés quand le paramètre `$datetime` est un horodatage UNIX (p. ex. `@946684800`) ou spécifie un fuseau horaire (p. ex. `2010-01-28T15:00:00+02:00`).

### Valeurs de retour

Retourne une nouvelle instance DateTime.

### Erreurs / Exceptions

Si une chaîne de date ou de temps invalide est fournie, une DateMalformedStringException est lancée. Antérieur à PHP 8.3, ceci était une Exception.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une DateMalformedStringException si une chaîne invalide est fournie, au lieu de Exception.

### Voir aussi

- DateTimeImmutable::__construct() - Retourne un nouvel objet DateTimeImmutable

# DateTime::createFromFormat

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — Analyse une heure au format texte selon le format spécifié.

### Description

Style orienté objet

public static function DateTime::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Style procédural

function date_create_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Retourne un nouvel objet DateTime représentant la date et l'heure spécifiées par le texte `datetime`, qui a été formaté dans le `format` donné.

Identique à DateTimeImmutable::createFromFormat() et date_create_immutable_from_format(), respectivement, mais crée un objet DateTime.

Cette méthode, y compris les paramètres, les exemples et les considérations, est documentée sur la page DateTimeImmutable::createFromFormat.

### Liste de paramètres

Voir DateTimeImmutable::createFromFormat.

### Valeurs de retour

Retourne un nouvel objet DateTime ou `false` si une erreur survient.

### Erreurs / Exceptions

Cette méthode lance une ValueError lorsque le `datetime` contient des octets NULL.

### Historique

Version | Description
--- | ---
8.0.21, 8.1.8, 8.2.0 | Lance désormais une ValueError lorsque des octets NULL sont passés dans `datetime`, ce qui était auparavant ignoré silencieusement.

### Exemples

Pour une série complète d'exemples, voir DateTimeImmutable::createFromFormat.

### Voir aussi

- DateTimeImmutable::createFromFormat() - Analyse une heure au format texte selon le format spécifié.

# DateTime::createFromImmutable

(PHP 7 >= 7.3.0, PHP 8)

DateTime::createFromImmutable — Retourne une nouvelle instance d'objet DateTime encapsulant l'objet DateTimeImmutable fourni

### Description

public static function DateTime::createFromImmutable(DateTimeImmutable `$object`): static

### Liste de paramètres

`object`

  L'objet immuable DateTimeImmutable qui doit être converti en une version mutable. Cet objet n'est pas modifié, mais une nouvelle instance d'objet DateTime est créée contenant les mêmes informations de date, temps, et fuseau horaire.

### Valeurs de retour

Retourne une nouvelle instance de DateTime.

### Historique

Version | Description
--- | ---
8.0.0 | La méthode renvoie une instance de la classe invoquée. Auparavant, elle créait une nouvelle instance de DateTime.

### Exemples

Exemple #1 Créer un objet de date et temps mutable

    <?php
    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $mutable = DateTime::createFromImmutable( $date );

# DateTime::createFromInterface

(PHP 8)

DateTime::createFromInterface — Retourne un nouvel objet DateTime encapsulant l'objet DateTimeInterface fourni

### Description

public static function DateTime::createFromInterface(DateTimeInterface `$object`): DateTime

### Liste de paramètres

`object`

  L'objet DateTimeInterface qui doit être converti en une version mutable. Cet objet n'est pas modifié, mais une nouvelle instance d'objet DateTime est créée contenant les mêmes informations de date, temps, et fuseau horaire.

### Valeurs de retour

Retourne une nouvelle instance de DateTime.

### Exemples

Exemple #1 Création d'un objet de date et temps mutable

    <?php
    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $mutable = DateTime::createFromInterface($date);

    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $also_mutable = DateTime::createFromInterface($date);

# DateTime::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTime::createFromTimestamp — Crée une instance à partir d'un horodatage Unix

### Description

public static function DateTime::createFromTimestamp(int|float `$timestamp`): static

Crée une instance à partir d'un horodatage Unix.

### Liste de paramètres

`timestamp`
  Horodatage Unix représentant la date. Une valeur de type nombre décimal est également acceptée, ce qui permet une précision à la microseconde.

### Valeurs de retour

Retourne une nouvelle instance de DateTime.

### Erreurs / Exceptions

Si `timestamp` est en dehors de l'intervalle [`PHP_INT_MIN`, `PHP_INT_MAX`], une DateRangeError est lancée.

### Exemples

Exemple #1 Exemple avec DateTime::createFromTimestamp()

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

L'exemple ci-dessus va afficher :

    1970-01-01 00:02:03.456789

# DateTime::getLastErrors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getLastErrors — Alias de DateTimeImmutable::getLastErrors()

### Description

Cette fonction est un alias de : DateTimeImmutable::getLastErrors()

# DateTime::modify

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::modify -- date_modify — Modifie le timestamp

### Description

Style orienté objet

public function DateTime::modify(string `$modifier`): DateTime

Style procédural

function date_modify(DateTime `$object`, string `$modifier`): DateTime|false

Modifie le timestamp d'un objet DateTime en l'incrémentant ou le décrémentant dans un format acceptable par DateTimeImmutable::__construct().

### Liste de paramètres

`object`
  Style procédural uniquement : Un objet DateTime retourné par la fonction date_create(). Cette fonction modifie cet objet.
`modifier`

  Une chaîne date/heure. Les formats valides sont expliqués dans la documentation sur les formats Date et Heure.

### Valeurs de retour

Retourne DateTime en cas de succès. Style procédural retourne `false` en cas d'erreur.

### Erreurs / Exceptions

API orientée objet uniquement : Si une chaîne de date ou de temps invalide est fournie, une DateMalformedStringException est lancée.

### Historique

Version | Description
--- | ---
8.4.0 | A désormais un type de retour provisoire de DateTime. Auparavant, il était DateTime|false.
8.3.0 | DateTime::modify() lance désormais DateMalformedStringException si une chaîne invalide est passée. Auparavant, il retournait `false`, et un avertissement était émis. date_modify() n'a pas été modifiée.

### Exemples

Exemple #1 Exemple avec DateTime::modify()

Style orienté objet

    <?php
    $date = new DateTime('2006-12-12');
    $date->modify('+1 day');
    echo $date->format('Y-m-d');

L'exemple ci-dessus va afficher :

    2006-12-13

Style procédural

    <?php
    $date = date_create('2006-12-12');
    date_modify($date, '+1 day');
    echo date_format($date, 'Y-m-d');

L'exemple ci-dessus va afficher :

    2006-12-13

Exemple #2 Il faut se méfier lors de l'ajout ou la soustraction de mois

    <?php
    $date = new DateTime('2000-12-31');

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

L'exemple ci-dessus va afficher :

    2001-01-31
    2001-03-03

Exemple #3 Tous les formats de date et d'heure sont pris en charge

    <?php
    $date = new DateTime('2020-12-31');

    $date->modify('July 1st, 2023');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('Monday next week');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('17:30');
    echo $date->format('Y-m-d H:i') . "\n";

L'exemple ci-dessus va afficher :

    2023-07-01 00:00
    2023-07-03 00:00
    2023-07-03 17:30

### Voir aussi

- strtotime() - Transforme un texte anglais en timestamp
- DateTimeImmutable::modify() - Crée un nouvel objet avec l'horodatage modifié
- DateTime::add() - Modifie un objet DateTime, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté
- DateTime::sub() - Soustrait une durée à un objet DateTime
- DateTime::setDate() - Assigne la date
- DateTime::setISODate() - Configure une date ISO
- DateTime::setTime() - Assigne l'heure
- DateTime::setTimestamp() - Assigne la date et l'heure à l'aide d'un horodatage Unix

# DateTime::__set_state

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__set_state — Le gestionnaire __set_state

### Description

public static function DateTime::__set_state(array `$array`): DateTime

Le gestionnaire __set_state().

Comme DateTimeImmutable::__set_state() mais fonctionne avec DateTime.

### Liste de paramètres

`array`

  Le tableau d'initialisation.

### Valeurs de retour

Retourne une nouvelle instance de l'objet DateTime.

# DateTime::setDate

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setDate -- date_date_set — Assigne la date

### Description

Style orienté objet

public function DateTime::setDate(int `$year`, int `$month`, int `$day`): DateTime

Style procédural

function date_date_set(
DateTime `$object`,
int `$year`,
int `$month`,
int `$day`
): DateTime

Assigne la date courante de l'objet DateTime à une nouvelle date.

Comme DateTimeImmutable::setDate() mais fonctionne avec DateTime et modifie l'objet existant.

La version procédurale prend un objet DateTime comme premier argument.

### Liste de paramètres

`object`
  Style procédural uniquement : Un objet DateTime retourné par la fonction date_create(). Cette fonction modifie cet objet.
`year`

  Année de la date.

`month`

  Mois de la date.

`day`

  Jour de la date.

### Valeurs de retour

Retourne l'objet modifié DateTime pour chainer les méthodes.

### Voir aussi

- DateTimeImmutable::setDate() - Définit la date

# DateTime::setISODate

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setISODate -- date_isodate_set — Configure une date ISO

### Description

Style orienté objet

public function DateTime::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime

Style procédural

function date_isodate_set(
DateTime `$object`,
int `$year`,
int `$week`,
int `$dayOfWeek` = 1
): DateTime

Configure une date au format ISO 8601 : en utilisant des décalages de semaines et de jours, au lieu de dates spécifiques.

Comme DateTimeImmutable::setISODate() mais fonctionne avec DateTime.

La version procédurale prend un objet DateTime comme premier argument.

### Liste de paramètres

`object`
  Style procédural uniquement : Un objet DateTime retourné par la fonction date_create(). Cette fonction modifie cet objet.
`year`

  L'année de la date.

`week`

  Le numéro de la semaine.

`dayOfWeek`

  Décalage par rapport au premier jour de la semaine.

### Valeurs de retour

Retourne l'objet modifié DateTime pour chainer les méthodes.

### Voir aussi

- DateTimeImmutable::setISODate() - Définit la date ISO

# DateTime::setMicrosecond

(PHP 8 >= 8.4.0)

DateTime::setMicrosecond — Définit la partie microseconde de l'heure

### Description

public function DateTime::setMicrosecond(int `$microsecond`): static

Définit la partie microseconde de l'heure.

Comme DateTimeImmutable::setMicrosecond() mais fonctionne avec DateTime.

### Liste de paramètres

`microsecond`
  La valeur de microseconde à définir (`0` à `999999`).

### Valeurs de retour

Retourne l'objet modifié DateTime pour chainer les méthodes.

### Erreurs / Exceptions

Si `microsecond` est en dehors de l'intervalle [`0`, `999999`], une DateRangeError est lancée.

### Exemples

Exemple #1 Exemple avec DateTime::setMicrosecond()

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Voir aussi

- DateTimeInterface::getMicrosecond() - Récupère la partie microseconde de l'horodatage Unix

# DateTime::setTime

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTime -- date_time_set — Assigne l'heure

### Description

Style orienté objet

public function DateTime::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Style procédural

function date_time_set(
DateTime `$object`,
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Change le temps dans l'objet DateTime.

Comme DateTimeImmutable::setTime() mais fonctionne avec DateTime.

La version procédurale prend un objet DateTime comme premier argument.

### Liste de paramètres

`object`
  Style procédural uniquement : Un objet DateTime retourné par la fonction date_create(). Cette fonction modifie cet objet.
`hour`

  Heure du moment.

`minute`

  Minute du moment.

`second`

  Seconde du moment.

`microsecond`

  Microsecondes du moment.

### Valeurs de retour

Retourne l'objet modifié DateTime pour chainer les méthodes.

### Historique

Version | Description
--- | ---
8.1.0 | Le comportement avec les heures doubles existantes (pendant la transition DST) a changé. Auparavant, PHP choisissait la deuxième occurrence (après la transition DST), au lieu de la première occurrence (avant la transition DST).
7.1.0 | Le paramètre `microsecond` a été ajouté.

### Voir aussi

- DateTimeImmutable::setTime() - Définit l'horaire

# DateTime::setTimestamp

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::setTimestamp -- date_timestamp_set — Assigne la date et l'heure à l'aide d'un horodatage Unix

### Description

Style orienté objet

public function DateTime::setTimestamp(int `$timestamp`): DateTime

Style procédural

function date_timestamp_set(DateTime `$object`, int `$timestamp`): DateTime

Assigne la date et l'heure à l'aide d'un horodatage Unix.

Comme DateTimeImmutable::setTimestamp() mais fonctionne avec DateTime.

La version procédurale prend un objet DateTime comme premier argument.

### Liste de paramètres

`object`
  Style procédural uniquement : Un objet DateTime retourné par la fonction date_create(). Cette fonction modifie cet objet.
`timestamp`

  Horodatage Unix représentant la date et l'heure. Définir un horodatage en dehors de l'intervalle d'un entier est possible en utilisant DateTimeImmutable::modify() avec le format `@`.

### Valeurs de retour

Retourne l'objet modifié DateTime pour chainer les méthodes.

### Voir aussi

- DateTimeImmutable::setTimestamp() - Définit la date et l'heure basées sur un horodatage Unix
- DateTime::setMicrosecond() - Définit la partie microseconde de l'heure

# DateTime::setTimezone

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTimezone -- date_timezone_set — Configure le fuseau horaire de l'objet DateTime

### Description

Style orienté objet

public function DateTime::setTimezone(DateTimeZone `$timezone`): DateTime

Style procédural

function date_timezone_set(DateTime `$object`, DateTimeZone `$timezone`): DateTime

Définit un nouveau fuseau horaire pour un objet DateTime.

Comme DateTimeImmutable::setTimezone() mais fonctionne avec DateTime.

La version procédurale prend un objet DateTime comme premier argument.

### Liste de paramètres

`object`
  Style procédural uniquement : Un objet DateTime retourné par la fonction date_create(). Cette fonction modifie cet objet.
`timezone`

  Un objet DateTimeZone représentant le fuseau horaire désiré.

### Valeurs de retour

Retourne l'objet DateTime pour chaîner les méthodes. Le point dans le temps sous-jacent n'est pas modifié lors de l'appel de cette méthode.

### Exemples

Exemple #1 Exemple avec DateTime::setTimeZone()

Style orienté objet

    <?php
    $date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

L'exemple ci-dessus va afficher :

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

Style procédural

    <?php
    $date = date_create('2000-01-01', timezone_open('Pacific/Nauru'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

    date_timezone_set($date, timezone_open('Pacific/Chatham'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

L'exemple ci-dessus va afficher :

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Voir aussi

- DateTimeImmutable::setTimezone() - Définit le fuseau horaire
- DateTime::getTimezone() - Retourne le fuseau horaire relatif au DateTime fourni
- DateTimeZone::__construct() - Crée un nouvel objet DateTimeZone

# DateTime::sub

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::sub -- date_sub — Soustrait une durée à un objet DateTime

### Description

Style orienté objet

public function DateTime::sub(DateInterval `$interval`): DateTime

Style procédural

function date_sub(DateTime `$object`, DateInterval `$interval`): DateTime

Modifie l'objet DateTime spécifié, en soustrayant l'objet DateInterval spécifié.

Comme DateTimeImmutable::sub() mais fonctionne avec DateTime.

La version procédurale prend un objet DateTime comme premier argument.

### Liste de paramètres

`object`
  Style procédural uniquement : Un objet DateTime retourné par la fonction date_create(). Cette fonction modifie cet objet.
`interval`

  Un objet DateInterval

### Valeurs de retour

Retourne l'objet modifié DateTime pour chainer les méthodes.

### Erreurs / Exceptions

API orientée objet uniquement : Si une opération non supportée est tentée, telle que l'utilisation d'un objet DateInterval représentant une spécification de temps relatif telle que `next weekday`, une DateInvalidOperationException est lancée.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une DateInvalidOperationException avec DateTime::sub() au lieu d'un avertissement quand une opération non supportée est tentée. date_sub() n'a pas été modifié.

### Voir aussi

- DateTimeImmutable::sub() - Soustrait un nombre de jours, mois, années, heures et secondes

## Sommaire

- DateTime::add — Modifie un objet DateTime, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté
- DateTime::__construct — Retourne un nouvel objet DateTime
- DateTime::createFromFormat — Analyse une heure au format texte selon le format spécifié.
- DateTime::createFromImmutable — Retourne une nouvelle instance d'objet DateTime encapsulant l'objet DateTimeImmutable fourni
- DateTime::createFromInterface — Retourne un nouvel objet DateTime encapsulant l'objet DateTimeInterface fourni
- DateTime::createFromTimestamp — Crée une instance à partir d'un horodatage Unix
- DateTime::getLastErrors — Alias de DateTimeImmutable::getLastErrors
- DateTime::modify — Modifie le timestamp
- DateTime::__set_state — Le gestionnaire __set_state
- DateTime::setDate — Assigne la date
- DateTime::setISODate — Configure une date ISO
- DateTime::setMicrosecond — Définit la partie microseconde de l'heure
- DateTime::setTime — Assigne l'heure
- DateTime::setTimestamp — Assigne la date et l'heure à l'aide d'un horodatage Unix
- DateTime::setTimezone — Configure le fuseau horaire de l'objet DateTime
- DateTime::sub — Soustrait une durée à un objet DateTime

# La classe DateTimeImmutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

Représentation d'une date et heure.

Cette classe se comporte de manière identique à DateTime à l'exception que de nouveaux objets sont retournés quand des méthodes de modification telle que DateTime::modify() sont appelées.

## Synopsis de la classe

class DateTimeImmutable implements DateTimeInterface {
/* Constantes héritées */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Méthodes */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function add(DateInterval `$interval`): DateTimeImmutable
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = null): DateTimeImmutable|false
public static function createFromInterface(DateTimeInterface `$object`): DateTimeImmutable
public static function createFromMutable(DateTime `$object`): static
public static function createFromTimestamp(int|float `$timestamp`): static
public static function getLastErrors(): array|false
#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function modify(string `$modifier`): DateTimeImmutable
public static function __set_state(array `$array`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function setMicrosecond(int `$microsecond`): static
#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function setTimestamp(int `$timestamp`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function setTimezone(DateTimeZone `$timezone`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function sub(DateInterval `$interval`): DateTimeImmutable
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = false): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.
7.1.0 | Le constructeur DateTimeImmutable inclut désormais les microsecondes actuelles dans la valeur construite. Avant cela, il initialisait toujours les microsecondes à `0`.

# DateTimeImmutable::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::add — Retourne un nouvel objet, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté

### Description

#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function DateTimeImmutable::add(DateInterval `$interval`): DateTimeImmutable

Construit un nouvel objet DateTimeImmutable, et y ajoute l'objet DateInterval spécifié, pour représenter la nouvelle valeur.

### Liste de paramètres

`interval`

  Un objet DateInterval

### Valeurs de retour

Retourne un nouvel objet DateTimeImmutable avec les données modifiées.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::add()

Style orienté objet

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

Exemple #2 Exemples supplémentaires de DateTimeImmutable::add()

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2000-01-01 10:00:30
    2007-06-05 04:03:02

Exemple #3 Faire attention lors de l'ajout de mois

    <?php
    $date = new DateTimeImmutable('2000-12-31');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->add($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->add($interval);
    echo $newDate2->format('Y-m-d') . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2001-01-31
    2001-03-03

### Voir aussi

- DateTimeImmutable::sub() - Soustrait un nombre de jours, mois, années, heures et secondes
- DateTimeImmutable::diff() - Retourne la différence entre deux objets DateTime
- DateTimeImmutable::modify() - Crée un nouvel objet avec l'horodatage modifié

# DateTimeImmutable::__construct

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__construct -- date_create_immutable — Retourne un nouvel objet DateTimeImmutable

### Description

Style orienté objet

public function DateTimeImmutable::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Style procédural

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Retourne un nouvel objet DateTimeImmutable.

### Liste de paramètres

`datetime`

  Une chaîne date/heure. Les formats valides sont expliqués dans la documentation sur les formats Date et Heure.

  Passer `"now"` pour obtenir le temps courant lors de l'utilisation du paramètre `$timezone`.

`timezone`

  Un objet DateTimeZone représentant le fuseau horaire de `$datetime`.

  Si `$timezone` est omis ou `null`, le fuseau horaire actuel sera utilisé.

  > Note:

  > Le paramètre `$timezone` et le fuseau horaire actuel sont ignorés quand le paramètre `$datetime` est un horodatage UNIX (p. ex. `@946684800`) ou spécifie un fuseau horaire (p. ex. `2010-01-28T15:00:00+02:00` ou `2010-07-05T06:00:00Z`).

### Valeurs de retour

Retourne une nouvelle instance DateTimeImmutable.

### Erreurs / Exceptions

Si une chaîne de date ou de temps invalide est fournie, une DateMalformedStringException est lancée. Antérieur à PHP 8.3, ceci était une Exception.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une DateMalformedStringException si une chaîne invalide est fournie, au lieu de Exception.
7.1.0 | Désormais les microsecondes sont remplies avec leur valeur actuelle. Et non '00000'.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::__construct()

Style orienté objet

    <?php
    try {
        $date = new DateTimeImmutable('2000-01-01');
    } catch (Exception $e) {
        echo $e->getMessage();
        exit(1);
    }

    echo $date->format('Y-m-d');

L'exemple ci-dessus va afficher :

    2000-01-01

Style procédural

    <?php
    $date = date_create('2000-01-01');
    if (!$date) {
        $e = date_get_last_errors();
        foreach ($e['errors'] as $error) {
            echo "$error\n";
        }
        exit(1);
    }

    echo date_format($date, 'Y-m-d');

L'exemple ci-dessus va afficher :

    2000-01-01

Exemple #2 Subtilités de DateTimeImmutable::__construct()

    <?php
    date_default_timezone_set('America/Jamaica');

    // date/time spécifié dans le fuseau horaire PHP.
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // date/time spécifié dans le fuseau horaire spécifié.
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // date/time courant dans le fuseau horaire par défaut de PHP.
    $date = new DateTimeImmutable();
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // date/time courante dans le fuseau horaire spécifié.
    $date = new DateTimeImmutable('now', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Utilisant un horodatage UNIX. Il est à noter que le résultat est dans le fuseau horaire UTC.
    $date = new DateTimeImmutable('@946684800');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Les valeurs inexistantes sont reportées.
    $date = new DateTimeImmutable('2000-02-30');
    echo $date->format('Y-m-d H:i:sP') . "\n";

Résultat de l'exemple ci-dessus est similaire à :

    2000-01-01 00:00:00-05:00
    2000-01-01 00:00:00+12:00
    2010-04-24 10:24:16-04:00
    2010-04-25 02:24:16+12:00
    2000-01-01 00:00:00+00:00
    2000-03-01 00:00:00-05:00

> Note:

> Les dates reportées peuvent être détectées en vérifiant les avertissements à l'aide de DateTimeImmutable::getLastErrors().

Exemple #3 Changement du fuseau horaire associé

    <?php
    $timeZone = new \DateTimeZone('Asia/Tokyo');

    $time = new \DateTimeImmutable();
    $time = $time->setTimezone($timeZone);

    echo $time->format('Y/m/d H:i:s e'), "\n";

Résultat de l'exemple ci-dessus est similaire à :

    2022/08/12 23:49:23 Asia/Tokyo

Exemple #4 Utilisation d'une chaîne de date/heure relative

    <?php
    $time = new \DateTimeImmutable("-1 year");

    echo $time->format('Y/m/d H:i:s'), "\n";

Résultat de l'exemple ci-dessus est similaire à :

    2021/08/12 15:43:51

# DateTimeImmutable::createFromFormat

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — Analyse une heure au format texte selon le format spécifié.

### Description

Style orienté objet

public static function DateTimeImmutable::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Style procédural

function date_create_immutable_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Retourne un nouvel objet DateTimeImmutable représentant la date et l'heure spécifiées par la chaîne `datetime`, qui a été formatée au `format` donné.

### Liste de paramètres

`format`

  Le format dans lequel string doit être transmise. Voir les options de formatage ci-dessous. Dans la plupart des cas, les mêmes lettres que pour la date() peuvent être utilisées.

  Tous les champs sont initialisés avec la date/heure actuelle. Dans la plupart des cas, l'on voudra les remettre à "zéro" (l'époque Unix, `1970-01-01 00:00:00 UTC`). Il est possible de faire cela en incluant le caractère `!` comme premier caractère dans `format`, ou `|` comme dernier. Consulter la documentation de chaque caractère ci-dessous pour plus d'informations.

  Le format est analysé de gauche à droite, ce qui signifie que dans certaines situations, l'ordre dans lequel les caractères de format sont présents affecte le résultat. Dans le cas de `z` (le jour de l'année), il est nécessaire qu'une année ait déjà été analysée, par exemple via les caractères `Y` ou `y`.

  Les lettres utilisées pour l'analyse des nombres autorisent une large plage de valeurs, en dehors de ce que serait la plage logique. Par exemple, le `d` (jour du mois) accepte des valeurs comprises entre `00` et `99`. La seule contrainte est sur le nombre de chiffres. Le mécanisme de débordement de l'analyseur date/heure est utilisé lorsque des valeurs hors plage sont données. Les exemples ci-dessous illustrent certains de ces comportements.

  Cela signifie également que les données analysées pour une lettre de format sont gourmandes et liront jusqu'au nombre de chiffres que son format autorise. Cela peut également signifier qu'il n'y a plus assez de caractères dans la chaîne `datetime` pour les caractères de format suivants. Un exemple plus bas sur cette page illustre également ce problème.

  Les caractères suivants sont reconnus pour le paramètre `format`
  Caractère de `format` | Description | Exemple de valeurs analysées
  --- | --- | ---
  Jour | --- | ---
  `d` et `j` | Jour du mois, sur 2 chiffres, avec ou sans le zéro initial | `01` à `31` ou `1` à `31` (les nombres à 2 chiffres supérieurs au nombre de jours du mois sont acceptés, auquel cas ils feront déborder le mois. Par exemple utiliser 33 avec janvier, signifiera le 2 février)
  `D` et `l` | Une représentation textuelle du jour | De `Mon` jusqu'à `Sun` ou de `Sunday` jusqu'à `Saturday` Si le nom de jour donné est différent alors le nom de jour appartenant à une date analysée (ou par défaut) est différent, alors un débordement se produit vers la date suivante avec le nom de jour donné. Voir les exemples ci-dessous pour une explication.
  `S` | Préfixe anglais du jour du mois, sur 2 caractères. Il sera ignoré lors de l'analyse. | `st`, `nd`, `rd` ou `th`.
  `z` | Le jour de l'année (en commençant à 0); doit être précédé par `Y` ou `y`. | `0` à `365` (les nombres à 3 chiffres supérieurs aux nombres d'une année sont acceptés, auquel cas ils feront déborder l'année. Par exemple, utiliser 366 avec 2022, signifie le 2 janvier 2023)
  Mois | --- | ---
  `F` et `M` | Une représentation textuelle du mois, comme January ou Sept | De `January` à `December` ou de `Jan` à `Dec`
  `m` et `n` | Une représentation numérique du mois, avec ou sans zéro initial | De `01` à `12` ou de `1` à `12` (les nombres à 2 chiffres supérieurs à 12 sont acceptés, auquel cas ils feront déborder l'année. Par exemple, utiliser 13 signifie janvier de l'année suivante)
  Année | --- | ---
  `X` et `x` | Une représentation numérique complète d'une année, jusqu'à 19 chiffres, éventuellement préfixée par `+` ou `-` | Exemples : `0055`, `787`, `1999`, `-2003`, `+10191`
  `Y` | Une représentation complète de l'année, jusqu'à 4 chiffres | Exemples : `25` (comme `0025`), `787`, `1999`, `2003`
  `y` | Une représentation partielle de l'année, sur 2 chiffres (qui doit être dans l'intervalle 1970-2069, inclus) | Exemples : `99` ou `03` (seront interprétés comme l'année `1999` et l'année `2003`, respectivement)
  Heure | --- | ---
  `a` et `A` | Ante meridiem et Post meridiem | `am` ou `pm`
  `g` et `h` | L'heure au format 12-heures, avec ou sans zéro initial | De `1` à `12` ou de `01` à `12` (les nombres à 2 chiffres supérieurs à 12 sont acceptés, auquel cas ils feront déborder le jour. Par exemple utiliser 14 signifie 02 dans la prochaine période AM/PM)
  `G` et `H` | L'heure au format 24-heures, avec ou sans zéro initial | De `0` à `23` ou de `00` à `23` (les nombres à 2 chiffres supérieurs à 24 sont acceptés, auquel cas ils feront déborder la journée. Par exemple utiliser 26 signifie 02:00 le lendemain)
  `i` | Les minutes, avec un zéro initial | De `00` à `59` (les nombres à 2 chiffres supérieurs à 59 sont acceptés, auquel cas ils feront déborder l'heure. Par exemple utiliser 66 signifie :06 l'heure suivante)
  `s` | Les secondes, avec un zéro initial | De `00` à `59` (les nombres à 2 chiffres supérieurs à 59 sont acceptés, auquel cas ils feront déborder la minute. Par exemple utiliser 90 signifie :30 la minute suivante)
  `v` | Les millisecondes (jusqu'à 3 chiffres) | Exemple : `12` (`0.12` secondes), `345` (`0.345` secondes)
  `u` | Les microsecondes (jusqu'à 6 chiffres) | Exemple : `45` (`0.45` secondes), `654321` (`0.654321` secondes)
  Fuseau horaire | --- | ---
  `e`, `O`, `p`, `P` et `T` | L'identifiant du fuseau horaire, ou la différence en heures avec UTC, ou la différence avec UTC avec deux points (:) entre les heures et les minutes, ou l'abréviation du fuseau horaire | Exemples : `UTC`, `GMT`, `Atlantic/Azores` ou `+0200` ou `+02:00` ou `EST`, `MDT`
  Date/heure complète | --- | ---
  `U` | Le nombre de secondes depuis l'époque Unix (1er janvier 1970 00:00:00 GMT) | Exemple : `1292177455`
  Espace et séparateurs | --- | ---
  `` (espace) | Zéro ou plusieurs espaces, tabulations, caractères NBSP (U+A0), ou NNBSP (U+202F) | Exemple : `"\t"`, `" "`
  `#` | Un des symboles de séparation suivants : `;`, `:`, `/`, `.`, `,`, `-`, `(` ou `)` | Exemple : `/`
  `;`, `:`, `/`, `.`, `,`, `-`, `(` ou `)` | Le caractère spécifié. | Exemple : `-`
  `?` | Un octet aléatoire | Exemple : `^` (Il est à noter que pour les caractères UTF-8, l'on pourrait avoir besoin de plus d'un `?`. Dans ce cas, utiliser `*` est probablement ce que l'on veut à la place)
  `*` | Octets aléatoires jusqu'au prochain séparateur ou chiffre | Exemple : `*` dans `Y-*-d` avec la chaîne `2009-aWord-08` trouvera la chaîne `aWord`
  `!` | Réinitialise tous les champs (année, mois, jour, heure, minute, seconde ainsi que les informations quant au fuseau horaire) à des valeurs similaires à zéro (`0` pour heure, minute, seconde et fraction, `1` pour mois et jour, `1970` pour l'année et `UTC` pour les informations de fuseau horaire) | Sans le caractère `!,` tous les champs seront définis à la date et heure courante.
  `|` | Réinitialise tous les champs (année, mois, jour, heure, minute, seconde ainsi que les informations quant au fuseau horaire) à valeurs similaires à zéro s'ils n'ont pas encore été analysés | `Y-m-d|` définira l'année, le mois et le jour avec les informations trouvées dans la chaîne analysée, mais aussi l'heure, les minutes et les secondes à 0.
  `+` | Si le spécifieur de format est présent, les données restantes de la chaîne ne causeront pas une erreur, mais une alerte | Utiliser la méthode DateTime::getLastErrors() pour identifier la présence de données restantes.

  Les caractères non reconnus dans la chaîne de format entraîneront l'échec de l'analyse et un message d'erreur est ajouté à la structure renvoyée. Il est possible d'interroger les messages d'erreur avec DateTimeImmutable::getLastErrors().

  Pour inclure un caractère littéral dans `format`, il faut l'échapper avec un antislash (`\`).

  Si `format` n'est pas composé du caractère `!` alors les valeurs de temps générées qui sont absentes de `format` prendront comme valeur le temps système.

  Si `format` contient le caractère `!`, alors les valeurs de temps générées qui sont absentes de `format` ainsi que les valeurs situées à gauche de `!` prendront des valeurs mesurées depuis l'époque Unix.

  Si un caractère de temps est analysé, alors tous les autres champs liés au temps sont mis à "0", sauf s'ils sont également analysés.

  Le début de l'époque Unix est le 01/01/1970 à 00:00:00 UTC.

`datetime`

  Chaîne représentant le moment.

`timezone`

  Un objet DateTimeZone représentant le fuseau horaire désiré.

  Si `timezone` est omis ou `null` et `datetime` ne contient pas de fuseau, le fuseau courant sera utilisé.

  > Note:

  > Le paramètre `timezone` et le fuseau courant sont ignorés lorsque le paramètre `datetime` contient un timestamp (p. ex. `946684800`) ou précise un fuseau (p. ex. `2010-01-28T15:00:00+02:00`).

### Valeurs de retour

Retourne un nouvel objet DateTimeImmutable ou `false` si une erreur survient.

### Erreurs / Exceptions

Cette méthode lance une ValueError lorsque le `datetime` contient des octets NULL.

### Historique

Version | Description
--- | ---
8.2.9 | Le spécificateur `` (espace) prend désormais également en charge les caractères NBSP (U+A0) et NNBSP (U+202F).
8.2.0 | Les spécificateurs de `format` `X` et `x` ont été ajoutés.
8.0.21, 8.1.8, 8.2.0 | Lance désormais une ValueError lorsque des octets NULL sont passés dans `datetime`, ce qui était auparavant ignoré silencieusement.
7.3.0 | Le spécificateur de `format` `v` a été ajouté.

### Exemples

Exemple #1 Exemple avec DateTimeImmutable::createFromFormat()

Style orienté objet

    <?php
    $date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
    echo $date->format('Y-m-d');

Exemple #2 Utilisation des constantes de format prédéfinies avec DateTimeImmutable::createFromFormat()

Style orienté objet

    <?php
    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::ISO8601,
        '2004-02-12T15:19:21+00:00'
    );
    echo $date->format('c e') . "\n";

    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::RFC3339_EXTENDED,
        '2013-10-14T09:00:00.000+02:00'
    );
    echo $date->format('c e') . "\n";

Les constantes de formatage telles qu'elles sont utilisées dans cet exemple consistent en une chaîne de caractères pour formater un objet DateTimeImmutable. Dans la plupart des cas, ces lettres correspondent aux mêmes éléments d'information sur la date et l'heure que ceux définis dans la section paramètres ci-dessus, mais elles ont tendance à être plus indulgentes.

Exemple #3 Les subtilités de DateTimeImmutable::createFromFormat()

    <?php
    echo 'Date courante: ' . date('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-!d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = '!d';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'i';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

Résultat de l'exemple ci-dessus est similaire à :

    Date courante: 2022-06-02 15:50:46
    Format: Y-m-d; 2009-02-15 15:50:46
    Format: Y-m-d H:i:s; 2009-02-15 15:16:17
    Format: Y-m-!d H:i:s; 1970-01-15 15:16:17
    Format: !d; 1970-01-15 00:00:00
    Format: i; 2022-06-02 00:15:00

Exemple #4 Chaîne de format avec des caractères littéraux

    <?php
    echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');

Résultat de l'exemple ci-dessus est similaire à :

    23:15:03

Exemple #5 Comportement de débordement

    <?php
    echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);

Résultat de l'exemple ci-dessus est similaire à :

    Sat, 04 Jun 2022 17:01:37 +0000

Bien que le résultat semble étrange, il est correct, car les débordements suivants se produisent :

1. `97` secondes débordent sur `1` minute, ce qui laisse `37` secondes.
2. `61` minutes débordent sur `1` heure, ce qui laisse `1` minute.
3. `35` jours débordent sur `1` mois, ce qui laisse `4` jours. Le nombre de jours restants dépend du mois, car tous les mois n'ont pas le même nombre de jours.
4. `18` mois débordent sur `1` an, ce qui laisse `6` mois.

Exemple #6 Comportement pour le nom de jour débordant

    <?php
    $d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
    echo $d->format(DateTime::RFC1123), "\n";

Résultat de l'exemple ci-dessus est similaire à :

    Mon, 10 Aug 2020 01:00:00 +0000

Bien que le résultat semble étrange, il est correct, car les débordements suivants se produisent :

1. `3 Aug 2020 25:00:00` débordent sur `(Tue) 4 Aug 2020 01:00`.
2. `Mon` est appliqué, ce qui avance la date au `Mon, 10 Aug 2020 01:00:00`. L'explication des mots-clés relatifs tels que `Mon` est expliquée dans la section sur les formats relatifs.

Afin de détecter les dépassements de dates, il est possible d'utiliser DateTimeImmutable::getLastErrors(), qui inclura un avertissement en cas de dépassement.

Exemple #7 Détecter les dates dépassées

    <?php
    $d = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97');
    echo $d->format(DateTimeImmutable::RFC2822), "\n\n";

    var_dump(DateTimeImmutable::getLastErrors());

Résultat de l'exemple ci-dessus est similaire à :

    Sat, 04 Jun 2022 17:01:37 +0000

    array(4) {
      'warning_count' =>
      int(2)
      'warnings' =>
      array(1) {
        [19] =>
        string(27) "The parsed date was invalid"
      }
      'error_count' =>
      int(0)
      'errors' =>
      array(0) {
      }
    }

Exemple #8 Comportement d'analyse gourmand

    <?php
    print_r(date_parse_from_format('Gis', '60101'));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [year] =>
        [month] =>
        [day] =>
        [hour] => 60
        [minute] => 10
        [second] => 0
        [fraction] => 0
        [warning_count] => 1
        [warnings] => Array
            (
                [5] => The parsed time was invalid
            )

        [error_count] => 1
        [errors] => Array
            (
                [4] => A two digit second could not be found
            )

        [is_localtime] =>
    )

Le format `G` consiste à analyser les heures d'horloge sur 24 heures, avec ou sans zéro de tête. Cela nécessite d'analyser 1 ou 2 chiffres. Parce qu'il y a deux chiffres suivants, il lit avidement cela comme `60`.

Les caractères de format `i` et `s` suivants nécessitent tous deux deux chiffres. Cela signifie que `10` est passé comme minute (`i`), et qu'il n'y a alors plus assez de chiffres à analyser comme seconde (`s`).

Le tableau `errors` indique ce problème.

De plus, une heure de `60` est en dehors de la plage `0`-`24`, ce qui fait que le tableau `warnings` inclut un avertissement indiquant que l'heure n'est pas valide.

### Voir aussi

- DateTimeImmutable::__construct() - Retourne un nouvel objet DateTimeImmutable
- DateTimeImmutable::getLastErrors() - Retourne les alertes et erreurs
- checkdate() - Valide une date grégorienne
- strptime() - Analyse une date générée par strftime

# DateTimeImmutable::createFromInterface

(PHP 8)

DateTimeImmutable::createFromInterface — Retourne un nouvel objet DateTimeImmutable encapsulant l'objet DateTimeInterface fourni

### Description

public static function DateTimeImmutable::createFromInterface(DateTimeInterface `$object`): DateTimeImmutable

### Liste de paramètres

`object`

  L'objet DateTimeInterface qui doit être converti en une version immutable. Cet objet n'est pas modifié, mais une nouvelle instance d'objet DateTimeImmutable est créée contenant les mêmes informations de date, temps, et fuseau horaire.

### Valeurs de retour

Retourne une nouvelle instance de DateTimeImmutable.

### Exemples

Exemple #1 Création d'un objet de date et temps immutable

    <?php
    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromInterface($date);

    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $also_immutable = DateTimeImmutable::createFromInterface($date);

# DateTimeImmutable::createFromMutable

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

DateTimeImmutable::createFromMutable — Retourne une nouvelle instance de DateTimeImmutable encapsulant l'objet DateTime fourni

### Description

public static function DateTimeImmutable::createFromMutable(DateTime `$object`): static

### Liste de paramètres

`object`

  L'objet DateTime mutable que l'on veut convertir en version immutable. Cet objet n'est pas modifié, mais une nouvelle instance de DateTimeImmutable est créée, contenant les mêmes informations de date, heure et de fuseau horaire.

### Valeurs de retour

Retourne une nouvelle instance de DateTimeImmutable.

### Historique

Version | Description
--- | ---
8.0.0 | La méthode retourne une instance de la classe appelée. Auparavant, elle créait une nouvelle instance de DateTimeImmutable.

### Exemples

Exemple #1 Création d'un objet date temps immutable

    <?php
    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromMutable( $date );

# DateTimeImmutable::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTimeImmutable::createFromTimestamp — Crée une instance à partir d'un horodatage Unix

### Description

public static function DateTimeImmutable::createFromTimestamp(int|float `$timestamp`): static

Crée une instance à partir d'un horodatage Unix.

### Liste de paramètres

`timestamp`
  Horodatage Unix représentant la date. Une valeur de type nombre décimal est également acceptée, ce qui permet une précision à la microseconde.

### Valeurs de retour

Retourne une nouvelle instance de DateTimeImmutable.

### Erreurs / Exceptions

Si `timestamp` est en dehors de l'intervalle [`PHP_INT_MIN`, `PHP_INT_MAX`], une DateRangeError est lancée.

### Exemples

Exemple #1 Exemple avec DateTimeImmutable::createFromTimestamp()

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

L'exemple ci-dessus va afficher :

    1970-01-01 00:02:03.456789

# DateTimeImmutable::getLastErrors

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::getLastErrors — Retourne les alertes et erreurs

### Description

public static function DateTimeImmutable::getLastErrors(): array|false

Retourne un tableau des alertes et erreurs trouvées lors de l'analyse d'une chaîne date/heure.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau contenant les informations à propos des alertes et erreurs, ou `false` s'il n'y a ni alertes ni erreurs.

### Historique

Version | Description
--- | ---
8.2.0 | Antérieur à PHP 8.2.0, cette fonction ne retournait pas `false` en l'absence d'avertissement ou d'erreur. Au lieu de cela, elle renvoyait toujours la structure de tableau documentée.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::getLastErrors()

    <?php
    try {
        $date = new DateTimeImmutable('asdfasdf');
    } catch (Exception $e) {
        // À des fins de démonstration uniquement...
        print_r(DateTimeImmutable::getLastErrors());

        // La vraie manière orientée objet de faire cela est
        echo $e->getMessage();
    }
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [6] => Double timezone specification
            )

        [error_count] => 1
        [errors] => Array
            (
                [0] => The timezone could not be found in the database
            )
    )
    Failed to parse time string (asdfasdf) at position 0 (a): The timezone could not be found in the database

Les index 6, et 0 dans la sortie de l'exemple font référence à l'index du caractère dans la chaîne où l'erreur s'est produite.

Exemple #2 Détecter les dates invalides

    <?php
    $date = DateTimeImmutable::createFromFormat('!Y-m-d', '2020-02-30');
    print_r(DateTimeImmutable::getLastErrors());

L'exemple ci-dessus va afficher :

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [10] => The parsed date was invalid
            )

        [error_count] => 0
        [errors] => Array
            (
            )
    )

# DateTimeImmutable::modify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::modify — Crée un nouvel objet avec l'horodatage modifié

### Description

#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function DateTimeImmutable::modify(string `$modifier`): DateTimeImmutable

Crée un nouvel objet DateTimeImmutable avec l'horodatage modifié. L'objet original ne sera pas modifié.

### Liste de paramètres

`modifier`

  Une chaîne date/heure. Les formats valides sont expliqués dans la documentation sur les formats Date et Heure.

### Valeurs de retour

Retourne DateTimeImmutable en cas de succès. Style procédural retourne `false` en cas d'erreur.

### Erreurs / Exceptions

Si une chaîne de date ou de temps invalide est fournie, une DateMalformedStringException est lancée. Antérieur à PHP 8.3, ceci était un avertissement.

### Historique

Version | Description
--- | ---
8.4.0 | A désormais un type de retour provisoire de DateTimeImmutable. Auparavant, il était DateTimeImmutable|false.
8.3.0 | DateTimeImmutable::modify() lance désormais DateMalformedStringException si une chaîne invalide est fournie. Auparavant, il retournait `false`, et un avertissement était émis.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::modify()

Style orienté objet

    <?php
    $date = new DateTimeImmutable('2006-12-12');
    $newDate = $date->modify('+1 day');
    echo $newDate->format('Y-m-d');

L'exemple ci-dessus va afficher :

    2006-12-13

Exemple #2 Faire attention lors de l'ajout ou soustraction de mois

    <?php
    $date = new DateTimeImmutable('2000-12-31');

    $newDate1 = $date->modify('+1 month');
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->modify('+1 month');
    echo $newDate2->format('Y-m-d') . "\n";

L'exemple ci-dessus va afficher :

    2001-01-31
    2001-03-03

### Voir aussi

- DateTimeImmutable::add() - Retourne un nouvel objet, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté
- DateTimeImmutable::sub() - Soustrait un nombre de jours, mois, années, heures et secondes
- DateTimeImmutable::setDate() - Définit la date
- DateTimeImmutable::setISODate() - Définit la date ISO
- DateTimeImmutable::setTime() - Définit l'horaire
- DateTimeImmutable::setTimestamp() - Définit la date et l'heure basées sur un horodatage Unix

# DateTimeImmutable::__set_state

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__set_state — Le gestionnaire __set_state

### Description

public static function DateTimeImmutable::__set_state(array `$array`): DateTimeImmutable

Le gestionnaire __set_state().

### Liste de paramètres

`array`

  Le tableau d'initialisation.

### Valeurs de retour

Retourne une nouvelle instance d'un objet DateTimeImmutable.

# DateTimeImmutable::setDate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setDate — Définit la date

### Description

#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function DateTimeImmutable::setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable

Retourne un nouvel objet DateTimeImmutable avec la date actuelle de l'objet DateTimeImmutable définie à la date donnée.

### Liste de paramètres

`object`
  Style procédural uniquement : Un objet DateTime retourné par la fonction date_create(). Cette fonction modifie cet objet.
`year`

  Année de la date.

`month`

  Mois de la date.

`day`

  Jour de la date.

### Valeurs de retour

Retourne un nouvel objet DateTimeImmutable avec les données modifiées.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::setDate()

Style orienté objet

    <?php
    $date = new DateTimeImmutable();
    $newDate = $date->setDate(2001, 2, 3);
    echo $newDate->format('Y-m-d');

L'exemple ci-dessus va afficher :

    2001-02-03

Exemple #2 Les valeurs excédant la plage sont ajoutées à leur valeur parente

    <?php
    $date = new DateTimeImmutable();

    $newDate = $date->setDate(2001, 2, 28);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 2, 29);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 14, 3);
    echo $newDate->format('Y-m-d') . "\n";

L'exemple ci-dessus va afficher :

    2001-02-28
    2001-03-01
    2002-02-03

### Voir aussi

- DateTimeImmutable::setISODate() - Définit la date ISO
- DateTimeImmutable::setTime() - Définit l'horaire

# DateTimeImmutable::setISODate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setISODate — Définit la date ISO

### Description

#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function DateTimeImmutable::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable

Retourne un nouvel objet DateTimeImmutable avec la date définie en respectant le standard ISO 8601, utilisant les semaines et écarts de jour plutôt que des dates spécifiques.

### Liste de paramètres

`year`

  Année de la date.

`week`

  Semaine de la date.

`dayOfWeek`

  Décalage par rapport au premier jour de la semaine.

### Valeurs de retour

Retourne un nouvel objet DateTimeImmutable avec les données modifiées.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::setISODate()

Style orienté objet

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

L'exemple ci-dessus va afficher :

    2008-01-07
    2008-01-13

Style procédural

    <?php

    $date = date_create();

    date_isodate_set($date, 2008, 2);
    echo date_format($date, 'Y-m-d') . "\n";

    date_isodate_set($date, 2008, 2, 7);
    echo date_format($date, 'Y-m-d') . "\n";

L'exemple ci-dessus va afficher :

    2008-01-07
    2008-01-13

Exemple #2 Les valeurs excédant la plage sont ajoutées à leur valeur parente

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 8);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 53, 7);
    echo $newDate->format('Y-m-d') . "\n";

L'exemple ci-dessus va afficher :

    2008-01-13
    2008-01-14
    2009-01-04

Exemple #3 Trouver le mois dont une semaine se trouve

    <?php

    $date = new DateTimeImmutable();
    $newDate = $date->setISODate(2008, 14);
    echo $newDate->format('n');

L'exemple ci-dessus va afficher :

    3

### Voir aussi

- DateTimeImmutable::setDate() - Définit la date
- DateTimeImmutable::setTime() - Définit l'horaire

# DateTimeImmutable::setMicrosecond

(PHP 8 >= 8.4.0)

DateTimeImmutable::setMicrosecond — Définit la partie microseconde de l'heure

### Description

#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function DateTimeImmutable::setMicrosecond(int `$microsecond`): static

Retourne un nouvel objet DateTimeImmutable construit à partir de l'ancien, avec la partie microseconde modifiée.

### Liste de paramètres

`microsecond`
  La valeur de microseconde à définir (`0` à `999999`).

### Valeurs de retour

Retourne un nouvel objet DateTimeImmutable avec les données modifiées.

### Erreurs / Exceptions

Si `microsecond` est en dehors de l'intervalle [`0`, `999999`], une DateRangeError est lancée.

### Exemples

Exemple #1 Exemple avec DateTimeImmutable::setMicrosecond()

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date = $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Voir aussi

- DateTimeInterface::getMicrosecond() - Récupère la partie microseconde de l'horodatage Unix

# DateTimeImmutable::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTime — Définit l'horaire

### Description

#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function DateTimeImmutable::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable

Retourne un nouvel objet DateTimeImmutable avec l'heure définie à l'heure fournie.

### Liste de paramètres

`hour`

  Heure de l'horaire.

`minute`

  Minutes de l'horaire.

`second`

  Secondes de l'horaire.

`microsecond`

  Microsecondes de l'horaire.

### Valeurs de retour

Retourne un nouvel objet DateTimeImmutable avec les données modifiées.

### Historique

Version | Description
--- | ---
8.1.0 | Le comportement avec les heures doubles existantes (pendant la transition DST) a changé. Auparavant, PHP choisissait la deuxième occurrence (après la transition DST), au lieu de la première occurrence (avant la transition DST).
7.1.0 | Le paramètre `microsecond` a été ajouté.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::setTime()

Style orienté objet

    <?php
    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    2001-01-01 14:55:00
    2001-01-01 14:55:24

Exemple #2 Les valeurs dépassant les intervalles sont ajoutées à leurs valeurs parentes

    <?php
    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 65);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 65, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(25, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2001-01-01 14:55:24
    2001-01-01 14:56:05
    2001-01-01 15:05:24
    2001-01-02 01:55:24

### Voir aussi

- DateTimeImmutable::setDate() - Définit la date
- DateTimeImmutable::setISODate() - Définit la date ISO

# DateTimeImmutable::setTimestamp

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimestamp — Définit la date et l'heure basées sur un horodatage Unix

### Description

#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function DateTimeImmutable::setTimestamp(int `$timestamp`): DateTimeImmutable

Retourne un nouvel objet DateTimeImmutable construit à partir de l'ancien, avec la date et l'heure basées sur un horodatage Unix.

### Liste de paramètres

`timestamp`

  L'horodatage Unix représentant la date. Définir l'horodatage en dehors de l'intervalle d'un entier est possible en utilisant DateTimeImmutable::modify() avec le format `@`.

### Valeurs de retour

Retourne un nouvel objet DateTimeImmutable avec les données modifiées.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::setTimestamp()

Style orienté objet

    <?php
    $date = new DateTimeImmutable();
    echo $date->format('U = Y-m-d H:i:s') . "\n";

    $newDate = $date->setTimestamp(1171502725);
    echo $newDate->format('U = Y-m-d H:i:s') . "\n";

Résultat de l'exemple ci-dessus est similaire à :

    1272508903 = 2010-04-28 22:41:43
    1171502725 = 2007-02-14 20:25:25

### Voir aussi

- DateTimeImmutable::getTimestamp() - Récupère le timestamp Unix
- DateTimeImmutable::setMicrosecond() - Définit la partie microseconde de l'heure

# DateTimeImmutable::setTimezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimezone — Définit le fuseau horaire

### Description

#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function DateTimeImmutable::setTimezone(DateTimeZone `$timezone`): DateTimeImmutable

Retourne un nouvel objet DateTimeImmutable avec un nouveau fuseau horaire défini.

### Liste de paramètres

`timezone`

  Un objet DateTimeZone représentant le fuseau horaire désiré.

### Valeurs de retour

Retourne un nouvel objet modifié DateTimeImmutable pour chaîner les méthodes. Le point dans le temps sous-jacent n'est pas modifié lors de l'appel de cette méthode.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::setTimeZone()

Style orienté objet

    <?php
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $newDate = $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $newDate->format('Y-m-d H:i:sP') . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Voir aussi

- DateTimeImmutable::getTimezone() - Retourne le fuseau horaire relatif au DateTime fourni
- DateTimeZone::__construct() - Crée un nouvel objet DateTimeZone

# DateTimeImmutable::sub

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::sub — Soustrait un nombre de jours, mois, années, heures et secondes

### Description

#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function DateTimeImmutable::sub(DateInterval `$interval`): DateTimeImmutable

Retourne un nouvel objet DateTimeImmutable, avec l'objet DateInterval spécifié soustrait de l'objet DateTimeImmutable spécifié.

### Liste de paramètres

`interval`

  Un objet DateInterval.

### Valeurs de retour

Retourne un nouvel objet DateTimeImmutable avec les données modifiées.

### Erreurs / Exceptions

Si une opération non supportée est tentée, telle que l'utilisation d'un objet DateInterval représentant une spécification de temps relatif telle que `next weekday`, une DateInvalidOperationException est lancée.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une DateInvalidOperationException au lieu d'un avertissement quand une opération non supportée est tentée.

### Exemples

Exemple #1 Exemple de DateTimeImmutable::sub()

Style orienté objet

    <?php
    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2000-01-10

Exemple #2 Exemples supplémentaires de DateTimeImmutable::sub()

    <?php
    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2000-01-19 13:59:30
    1992-08-15 19:56:58

Exemple #3 Faire attention lors de la soustraction de mois

    <?php
    $date = new DateTimeImmutable('2001-04-30');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->sub($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->sub($interval);
    echo $newDate2->format('Y-m-d') . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2001-03-30
    2001-03-02

### Voir aussi

- DateTimeImmutable::add() - Retourne un nouvel objet, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté
- DateTimeImmutable::diff() - Retourne la différence entre deux objets DateTime
- DateTimeImmutable::modify() - Crée un nouvel objet avec l'horodatage modifié

## Sommaire

- DateTimeImmutable::add — Retourne un nouvel objet, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté
- DateTimeImmutable::__construct — Retourne un nouvel objet DateTimeImmutable
- DateTimeImmutable::createFromFormat — Analyse une heure au format texte selon le format spécifié.
- DateTimeImmutable::createFromInterface — Retourne un nouvel objet DateTimeImmutable encapsulant l'objet DateTimeInterface fourni
- DateTimeImmutable::createFromMutable — Retourne une nouvelle instance de DateTimeImmutable encapsulant l'objet DateTime fourni
- DateTimeImmutable::createFromTimestamp — Crée une instance à partir d'un horodatage Unix
- DateTimeImmutable::getLastErrors — Retourne les alertes et erreurs
- DateTimeImmutable::modify — Crée un nouvel objet avec l'horodatage modifié
- DateTimeImmutable::__set_state — Le gestionnaire __set_state
- DateTimeImmutable::setDate — Définit la date
- DateTimeImmutable::setISODate — Définit la date ISO
- DateTimeImmutable::setMicrosecond — Définit la partie microseconde de l'heure
- DateTimeImmutable::setTime — Définit l'horaire
- DateTimeImmutable::setTimestamp — Définit la date et l'heure basées sur un horodatage Unix
- DateTimeImmutable::setTimezone — Définit le fuseau horaire
- DateTimeImmutable::sub — Soustrait un nombre de jours, mois, années, heures et secondes

# L'interface DateTimeInterface

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

DateTimeInterface a été créé pour que les déclarations de type de paramètre, retour, ou propriété puissent accepter soit DateTime soit DateTimeImmutable comme valeur. Il n'est pas possible d'implémenter cette interface dans les classes utilisateurs.

Les constantes communes qui permettent de formater les objets DateTimeImmutable ou DateTime via DateTimeImmutable::format() et DateTime::format() sont également définies sur cette interface.

## Sommaire de l'Interface

interface DateTimeInterface {
/* Constantes */
public const string ATOM = "Y-m-d\\TH:i:sP";
public const string COOKIE = "l, d-M-Y H:i:s T";
public const string ISO8601 = "Y-m-d\\TH:i:sO";
public const string ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string RFC822 = "D, d M y H:i:s O";
public const string RFC850 = "l, d-M-y H:i:s T";
public const string RFC1036 = "D, d M y H:i:s O";
public const string RFC1123 = "D, d M Y H:i:s O";
public const string RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string RFC2822 = "D, d M Y H:i:s O";
public const string RFC3339 = "Y-m-d\\TH:i:sP";
public const string RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string RSS = "D, d M Y H:i:s O";
public const string W3C = "Y-m-d\\TH:i:sP";
/* Méthodes */
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Constantes pré-définies

DateTimeInterface::ATOM string
DATE_ATOM
  Atom (exemple: 2005-08-15T15:52:01+00:00) ; compatible avec ISO-8601, RFC 3339 et XML Schema
DateTimeInterface::COOKIE string
DATE_COOKIE
  HTTP Cookies (exemple: Monday, 15-Aug-2005 15:52:01 UTC)
DateTimeInterface::ISO8601 string
DATE_ISO8601
  Semblable à ISO-8601 (exemple: 2005-08-15T15:52:01+0000)

  > Note: Ce format n'est pas compatible avec ISO-8601, mais reste ainsi pour des raisons de compatibilité ascendante. Utiliser DateTimeInterface::ISO8601_EXPANDED, DateTimeInterface::ATOM pour assurer la compatibilité avec ISO-8601. (ref ISO8601:2004 section 4.3.3 clause d)

DateTimeInterface::ISO8601_EXPANDED string
DATE_ISO8601_EXPANDED
  ISO-8601 Expanded (exemple: +10191-07-26T08:59:52+01:00)

  > Note: Ce format permet des plages d'années en dehors de la plage normale de ISO-8601 allant de `0000` à `9999` en incluant toujours un caractère de signe. Il s'assure également que cette partie de fuseau horaire (`+01:00`) est compatible avec ISO-8601.

DateTimeInterface::RFC822 string
DATE_RFC822
  RFC 822 (exemple: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC850 string
DATE_RFC850
  RFC 850 (exemple: Monday, 15-Aug-05 15:52:01 UTC)
DateTimeInterface::RFC1036 string
DATE_RFC1036
  RFC 1036 (exemple: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC1123 string
DATE_RFC1123
  RFC 1123 (exemple: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC7231 string
DATE_RFC7231
  RFC 7231 (à partir de PHP 7.0.19 et 7.1.5) (exemple: Sat, 30 Apr 2016 17:52:13 GMT)
DateTimeInterface::RFC2822 string
DATE_RFC2822
  RFC 2822 (exemple: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC3339 string
DATE_RFC3339
  Comme DATE_ATOM
DateTimeInterface::RFC3339_EXTENDED string
DATE_RFC3339_EXTENDED
  RFC 3339 EXTENDED format (exemple : 2005-08-15T15:52:01.000+00:00)
DateTimeInterface::RSS string
DATE_RSS
  RSS (exemple: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::W3C string
DATE_W3C
  World Wide Web Consortium (exemple : 2005-08-15T15:52:01+00:00)

## Historique

Version | Description
--- | ---
8.5.0 | Les constantes `DATE_RFC7231` et `DateTimeInterface::RFC7231` ont été rendues obsolètes.
8.4.0 | Les constantes de classe sont maintenant typées.
8.2.0 | La constante `DateTimeInterface::ISO8601_EXPANDED` a été ajoutée.
7.2.0 | Les constantes de classe de DateTime sont maintenant définies sur DateTimeInterface.

# DateTimeInterface::diff

# DateTimeImmutable::diff

# DateTime::diff

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::diff -- DateTimeImmutable::diff -- DateTime::diff -- date_diff — Retourne la différence entre deux objets DateTime

### Description

Style orienté objet

public function DateTimeInterface::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTimeImmutable::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTime::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Style procédural

function date_diff(DateTimeInterface `$baseObject`, DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Retourne la différence entre deux objets DateTimeInterface.

### Liste de paramètres

`datetime`

  La date à comparer.

`absolute`

  Doit-on forcer l'intervalle à être positif ?

### Valeurs de retour

L'objet DateInterval représente la différence entre les deux dates.

Le paramètre `absolute` affecte uniquement la propriété `invert` d'un objet DateInterval.

La valeur de retour représente de façon plus détaillée l'intervalle de temps à appliquer sur l'objet original (`$this` ou `$originObject`) pour arriver à `$targetObject`. Cette procédure n'est pas toujours réversible.

La méthode est consciente des changements d'heure d'été et peut donc renvoyer un intervalle de `24 heures et 30 minutes`, comme dans l'un des exemples. Si l'on souhaite calculer avec le temps absolu, il faut d'abord convertir à la fois `$this`/ `$baseObject` et `$targetObject` en UTC.

### Exemples

Exemple #1 Exemple avec DateTimeImmutable::diff()

Style orienté objet

    <?php
    $origin = new DateTimeImmutable('2009-10-11');
    $target = new DateTimeImmutable('2009-10-13');
    $interval = $origin->diff($target);
    echo $interval->format('%R%a days');

L'exemple ci-dessus va afficher :

    +2 days

Style procédural

    <?php
    $origin = date_create('2009-10-11');
    $target = date_create('2009-10-13');
    $interval = date_diff($origin, $target);
    echo $interval->format('%R%a days');

L'exemple ci-dessus va afficher :

    +2 days

Exemple #2 DateTimeInterface::diff() lors du passage à l'heure d'été

    <?php
    $originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");
    $targetTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
    $interval = $originalTime->diff($targetTime);
    echo $interval->format("%H:%I:%S (Full days: %a)"), "\n";

L'exemple ci-dessus va afficher :

    24:30:00 (Full days: 0)

Exemple #3 Calcul d'intervalle avec DateTimeInterface::diff()

La valeur renvoyée par la méthode est le temps exact qu'il faut pour aller de `$this` à `$targetObject`. La comparaison entre le 1er janvier et le 31 décembre renvoie donc 364 jours et non 365 (pour les années non bissextiles).

    <?php
    $originalTime = new DateTimeImmutable("2023-01-01 UTC");
    $targetTime = new DateTimeImmutable("2023-12-31 UTC");
    $interval = $originalTime->diff($targetTime);
    echo "Jours totaux: ", $interval->format("%a"), "\n";

L'exemple ci-dessus va afficher :

    Jours totaux: 364

Exemple #4 Comparaison de deux objets DateTime

> Note:

> Les objets DateTimeImmutable ou DateTime peuvent être comparés en utilisant les opérateurs de comparaison.

    <?php
    $date1 = new DateTime("now");
    $date2 = new DateTime("tomorrow");

    var_dump($date1 == $date2);
    var_dump($date1 < $date2);
    var_dump($date1 > $date2);

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(false)

### Voir aussi

- DateInterval::format() - Formate l'intervalle
- DateTime::add() - Modifie un objet DateTime, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté
- DateTime::sub() - Soustrait une durée à un objet DateTime

# DateTimeInterface::format

# DateTimeImmutable::format

# DateTime::format

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::format -- DateTimeImmutable::format -- DateTime::format -- date_format — Retourne une date formatée suivant le format fourni

### Description

Style orienté objet

public function DateTimeInterface::format(string `$format`): string
public function DateTimeImmutable::format(string `$format`): string
public function DateTime::format(string `$format`): string

Style procédural

function date_format(DateTimeInterface `$object`, string `$format`): string

Retourne une date formatée suivant le format fourni.

### Liste de paramètres

`object`
  Seulement en style procédural : un objet DateTime retourné par date_create()
`format`

  Le format de la date désirée. Voir les options de formatage ci-dessous. Il existe aussi de nombreuses constantes de dates qui peuvent être utilisées, ce qui fait que `DATE_RSS` va remplacer le format `"D, d M Y H:i:s"`.

  Les caractères suivants sont reconnus dans le paramètre `format`
  Caractères pour le paramètre `format` | Description | Exemple de valeurs retournées
  --- | --- | ---
  Jour | --- | ---
  `d` | Jour du mois, sur deux chiffres (avec un zéro initial) | `01` à `31`
  `D` | Jour de la semaine, en trois lettres (et en anglais - par défaut : en anglais, ou sinon, dans la langue locale du serveur) | `Mon` à `Sun`
  `j` | Jour du mois sans les zéros initiaux | `1` à `31`
  `l` ('L' minuscule) | Jour de la semaine, textuel, version longue, en anglais | `Sunday` à `Saturday`
  `N` | Représentation numérique ISO 8601 du jour de la semaine | `1` (pour lundi) à `7` (pour dimanche)
  `S` | Suffixe ordinal d'un nombre pour le jour du mois, en anglais, sur deux lettres | `st`, `nd`, `rd` ou `th`. Fonctionne bien avec `j`
  `w` | Jour de la semaine au format numérique | `0` (pour dimanche) à `6` (pour samedi)
  `z` | Jour de l'année | `0` à `365`
  Semaine | --- | ---
  `W` | Numéro de semaine dans l'année ISO 8601, les semaines commencent le lundi | Exemple : `42` (la 42ème semaine de l'année)
  Mois | --- | ---
  `F` | Mois, textuel, version longue; en anglais, comme `January` ou `December` | `January` à `December`
  `m` | Mois au format numérique, avec zéros initiaux | `01` à `12`
  `M` | Mois, en trois lettres, en anglais | `Jan` à `Dec`
  `n` | Mois sans les zéros initiaux | `1` à `12`
  `t` | Nombre de jours dans le mois | `28` à `31`
  Année | --- | ---
  `L` | Est-ce que l'année est bissextile | `1` si bissextile, `0` sinon.
  `o` | Année de numérotation des semaines ISO 8601. C'est la même valeur que `Y`, excepté si le numéro de la semaine ISO (`W`) appartient à l'année précédente ou suivante, cette année sera utilisée à la place. | Exemples : `1999` ou `2003`
  `X` | Une représentation numérique complète étendue d'une année, d'au moins 4 chiffres, avec un `-` pour les années avant l'ère commune et un `+` pour les années de l'ère commune. | Exemples : `-0055`, `+0787`, `+1999`, `+10191`
  `x` | Une représentation numérique complète étendue si nécessaire, ou une représentation numérique complète standard si possible (comme `Y`). Au moins quatre chiffres. Les années antérieures à l'ère commune sont préfixées par un `-`. Les années au-delà (et y compris) du `10000` sont préfixées par un `+`. | Exemples : `-0055`, `0787`, `1999`, `+10191`
  `Y` | Une représentation numérique complète d'une année, au moins 4 chiffres, avec `-` pour les années av. J.-C. | Exemples : `-0055`, `0787`, `1999`, `2003`, `10191`
  `y` | Année sur 2 chiffres | Exemples : `99` ou `03`
  Heure | --- | ---
  `a` | Ante meridiem et Post meridiem en minuscules | `am` ou `pm`
  `A` | Ante meridiem et Post meridiem en majuscules | `AM` ou `PM`
  `B` | Heure Internet Swatch | `000` à `999`
  `g` | Heure, au format 12h, sans les zéros initiaux | `1` à `12`
  `G` | Heure, au format 24h, sans les zéros initiaux | `0` à `23`
  `h` | Heure, au format 12h, avec les zéros initiaux | `01` à `12`
  `H` | Heure, au format 24h, avec les zéros initiaux | `00` à `23`
  `i` | Minutes avec les zéros initiaux | `00` à `59`
  `s` | Secondes avec zéros initiaux | `00` à `59`
  `u` | Microsecondes. Il est à noter que la fonction date() générera toujours `000000` vu qu'elle prend un paramètre de type entier, alors que la méthode DateTimeInterface::format() supporte les microsecondes si un objet de type DateTimeInterface a été créé avec des microsecondes. | Exemple : `654321`
  `v` | Millisecondes. Même note que pour `u`. | Exemple : `654`
  Fuseau horaire | --- | ---
  `e` | L'identifiant du fuseau horaire | Exemples : `UTC`, `GMT`, `Atlantic/Azores`
  `I` (i majuscule) | L'heure d'été est activée ou pas | `1` si oui, `0` sinon.
  `O` | Différence d'heures avec l'heure de Greenwich (GMT), sans deux-points entre les heures et les minutes | Exemple : `+0200`
  `P` | Différence avec l'heure Greenwich (GMT) avec un deux-points entre les heures et les minutes | Exemple : `+02:00`
  `p` | Identique à `P`, mais retourne `Z` au lieu de `+00:00` (disponible à partir de PHP 8.0.0) | Exemples : `Z` ou `+02:00`
  `T` | Abréviation du fuseau horaire, si connu ; sinon décalage depuis GMT | Exemples : `EST`, `MDT`, `+05`
  `Z` | Décalage horaire en secondes. Le décalage des zones à l'ouest de la zone UTC est négatif, et à l'est, il est positif. | `-43200` à `50400`
  Date et Heure complète | --- | ---
  `c` | Date au format ISO 8601. Seulement compatible avec le format non étendu (jusqu'à l'année 9999). Les dates plus tardives donneront une chaîne invalide. Pour les dates plus tardives et le format étendu, voir `x` et `X`. | 2004-02-12T15:19:21+00:00
  `r` | Format de date » RFC 2822/» RFC 5322 | Exemple : `Thu, 21 Dec 2000 16:01:07 +0200`
  `U` | Secondes depuis l'époque Unix (1er Janvier 1970, 0h00 00s GMT) | Voir aussi time()

  Les caractères non reconnus seront imprimés tels quels. "`Z`" retournera toujours `0` lorsqu'il est utilisé avec gmdate().

  > Note:

  > Sachant que cette fonction n'accepte que des entiers sous la forme de timestamp, le caractère `u` n'est utile que lors de l'utilisation de la fonction date_format() avec un timestamp utilisateur créé avec la fonction date_create().

### Valeurs de retour

Retourne la date formatée, sous forme de chaîne de caractères, en cas de succès.

### Historique

Version | Description
--- | ---
8.2.0 | Les caractères de format `X` ou `x` ont été ajoutés.
8.0.0 | Le caractère de format `p` a été ajouté.

### Exemples

Exemple #1 Exemple avec DateTime::format()

Style orienté objet

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:s');
    ?>

L'exemple ci-dessus va afficher :

    2000-01-01 00:00:00

Style procédural

    <?php
    $date = date_create('2000-01-01');
    echo date_format($date, 'Y-m-d H:i:s');
    ?>

L'exemple ci-dessus va afficher :

    2000-01-01 00:00:00

Exemple #2 Plus d'exemples

    <?php
    // Définit le fuseau horaire par défaut.
    date_default_timezone_set('UTC');

    // Maintenant
    $date = new DateTimeImmutable();

    // Affiche quelque chose comme : Wednesday
    echo $date->format('l'), "\n";

    // Affiche quelque chose comme : Wednesday 19th of October 2022 08:40:48 AM
    echo $date->format('l jS \o\f F Y h:i:s A'), "\n";

    /* Utilisation des constantes dans le paramètre format */
    // Affiche quelque chose comme : Wed, 19 Oct 2022 08:40:48 +0000
    echo $date->format(DateTimeInterface::RFC2822), "\n";
    ?>

Il est possible d'empêcher le développement d'un caractère reconnu dans la chaîne de format en le précédant d'un antislash. Si le caractère avec un antislash est déjà une séquence spéciale, il faudra peut-être également échapper l'antislash.

Exemple #3 Échappement de caractères lors du formatage

    <?php
    $date = new DateTimeImmutable();

    // Affiche quelque chose comme : Wednesday the 19th
    echo $date->format('l \t\h\e jS');
    ?>

Pour formater des dates dans d'autres langues, IntlDateFormatter::format() peut être utilisée à la place de DateTimeInterface::format().

### Notes

Cette méthode n'utilise pas les locales. Tous les affichages seront en anglais.

### Voir aussi

- IntlDateFormatter::format() - Formate la date et l'heure sous forme de chaîne

# DateTimeInterface::getMicrosecond

# DateTimeImmutable::getMicrosecond

# DateTime::getMicrosecond

(PHP 8 >= 8.4.0)

DateTimeInterface::getMicrosecond -- DateTimeImmutable::getMicrosecond -- DateTime::getMicrosecond — Récupère la partie microseconde de l'horodatage Unix

### Description

public function DateTimeInterface::getMicrosecond(): int
public function DateTimeImmutable::getMicrosecond(): int
public function DateTime::getMicrosecond(): int

Récupère la partie microseconde de l'horodatage Unix.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la partie microseconde de l'horodatage Unix représentant la date.

### Exemples

Exemple #1 Exemple avec DateTimeInterface::getMicrosecond()

    <?php
    $date = new DateTimeImmutable('2024-01-01 12:34:56.789123');
    var_dump($date->format('u'));
    var_dump($date->getMicrosecond());
    ?>

L'exemple ci-dessus va afficher :

    string(6) "789123"
    int(789123)

### Voir aussi

- DateTimeInterface::getTimestamp() - Récupère le timestamp Unix
- DateTimeInterface::format() - Retourne une date formatée suivant le format fourni

# DateTimeInterface::getOffset

# DateTimeImmutable::getOffset

# DateTime::getOffset

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getOffset -- DateTimeImmutable::getOffset -- DateTime::getOffset -- date_offset_get — Retourne le décalage horaire

### Description

Style orienté objet

public function DateTimeInterface::getOffset(): int
public function DateTimeImmutable::getOffset(): int
public function DateTime::getOffset(): int

Style procédural

function date_offset_get(DateTimeInterface `$object`): int

Retourne le décalage horaire.

### Liste de paramètres

`object`
  Seulement en style procédural : un objet DateTime retourné par date_create()

### Valeurs de retour

Retourne le décalage horaire en secondes, depuis UTC en cas de succès.

### Exemples

Exemple #1 Exemple avec DateTime::getOffset()

Style orienté objet

    <?php
    $winter = new DateTimeImmutable('2010-12-21', new DateTimeZone('America/New_York'));
    $summer = new DateTimeImmutable('2008-06-21', new DateTimeZone('America/New_York'));

    echo $winter->getOffset() . "\n";
    echo $summer->getOffset() . "\n";

L'exemple ci-dessus va afficher :

    -18000
    -14400

Style procédural

    <?php
    $winter = date_create('2010-12-21', timezone_open('America/New_York'));
    $summer = date_create('2008-06-21', timezone_open('America/New_York'));

    echo date_offset_get($winter) . "\n";
    echo date_offset_get($summer) . "\n";

L'exemple ci-dessus va afficher :

    -18000
    -14400

Note : -18000 = -5 heures, -14400 = -4 heures.

# DateTimeInterface::getTimestamp

# DateTimeImmutable::getTimestamp

# DateTime::getTimestamp

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::getTimestamp -- DateTimeImmutable::getTimestamp -- DateTime::getTimestamp -- date_timestamp_get — Récupère le timestamp Unix

### Description

Style orienté objet

public function DateTimeInterface::getTimestamp(): int
public function DateTimeImmutable::getTimestamp(): int
public function DateTime::getTimestamp(): int

Style procédural

function date_timestamp_get(DateTimeInterface `$object`): int

Récupère le timestamp Unix.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le timestamp Unix représentant la date.

### Erreurs / Exceptions

Si l'horodatage ne peut pas être représenté sous la forme d'un entier, une DateRangeError est lancée. Antérieur à PHP 8.3.0, une ValueError était lancée. Et avant PHP 8.0.0, `false` était retourné dans ce cas. Cependant, l'horodatage peut être récupéré en tant que chaîne de caractères en utilisant DateTimeInterface::format() avec le format `U`.

### Historique

Version | Description
--- | ---
8.3.0 | L'exception de hors limites est désormais une DateRangeError.
8.0.0 | Ces fonctions ne retournent plus `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec DateTime::getTimestamp()

Style orienté objet

    <?php
    $date = new DateTimeImmutable();
    echo $date->getTimestamp();

Résultat de l'exemple ci-dessus est similaire à :

    1272509157

Style procédural

    <?php
    $date = date_create();
    echo date_timestamp_get($date);

Résultat de l'exemple ci-dessus est similaire à :

    1272509157

Pour récupérer l'horodatage avec une précision en millisecondes ou microsecondes, il est possible d'utiliser la fonction DateTimeInterface::format().

Exemple #2 Récupération de l'horodatage avec une précision en millisecondes et microsecondes

Style orienté objet

    <?php
    $date = new DateTimeImmutable();
    $milli = (int) $date->format('Uv'); // Horodatage en millisecondes
    $micro = (int) $date->format('Uu'); // Horodatage en microsecondes

    echo $milli, "\n", $micro, "\n";

Résultat de l'exemple ci-dessus est similaire à :

    1674057635586
    1674057635586918

### Voir aussi

- DateTime::setTimestamp() - Assigne la date et l'heure à l'aide d'un horodatage Unix
- DateTimeImmutable::setTimestamp() - Définit la date et l'heure basées sur un horodatage Unix
- DateTimeInterface::format() - Retourne une date formatée suivant le format fourni
- DateTimeInterface::getMicrosecond() - Récupère la partie microseconde de l'horodatage Unix

# DateTimeInterface::getTimezone

# DateTimeImmutable::getTimezone

# DateTime::getTimezone

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getTimezone -- DateTimeImmutable::getTimezone -- DateTime::getTimezone -- date_timezone_get — Retourne le fuseau horaire relatif au DateTime fourni

### Description

Style orienté objet

public function DateTimeInterface::getTimezone(): DateTimeZone|false
public function DateTimeImmutable::getTimezone(): DateTimeZone|false
public function DateTime::getTimezone(): DateTimeZone|false

Style procédural

function date_timezone_get(DateTimeInterface `$object`): DateTimeZone|false

Retourne le fuseau horaire relatif au DateTime fourni.

### Liste de paramètres

`object`
  Seulement en style procédural : un objet DateTime retourné par date_create()

### Valeurs de retour

Retourne un objet DateTimeZone en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec DateTime::getTimezone()

Style orienté objet

    <?php
    $date = new DateTimeImmutable("now", new DateTimeZone('Europe/London'));
    $tz = $date->getTimezone();
    echo $tz->getName();

L'exemple ci-dessus va afficher :

    Europe/London

Style procédural

    <?php
    $date = date_create("now", timezone_open('Europe/London'));
    $tz = date_timezone_get($date);
    echo timezone_name_get($tz);

L'exemple ci-dessus va afficher :

    Europe/London

### Voir aussi

- DateTime::setTimezone() - Configure le fuseau horaire de l'objet DateTime

# DateTime::__serialize

# DateTimeImmutable::__serialize

# DateTimeInterface::__serialize

(PHP 8 >= 8.2.0)

DateTime::__serialize -- DateTimeImmutable::__serialize -- DateTimeInterface::__serialize — Sérialise un DateTime

### Description

public function DateTime::__serialize(): array
public function DateTimeImmutable::__serialize(): array
public function DateTimeInterface::__serialize(): array

Le gestionnaire __serialize().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La représentation sérialisée de l'objet DateTime.

### Exemples

Exemple #1 Exemple de DateTime::serialize()

    <?php
    $date = new DateTime('2025-03-27');
    var_dump(serialize($date));

L'exemple ci-dessus va afficher :

    string(114) "O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}"

### Voir aussi

- DateTime::__unserialize() - Désérialise un DateTime

# DateTime::__unserialize

# DateTimeImmutable::__unserialize

# DateTimeInterface::__unserialize

(PHP 8 >= 8.2.0)

DateTime::__unserialize -- DateTimeImmutable::__unserialize -- DateTimeInterface::__unserialize — Désérialise un DateTime

### Description

public function DateTime::__unserialize(array `$data`): void
public function DateTimeImmutable::__unserialize(array `$data`): void
public function DateTimeInterface::__unserialize(array `$data`): void

Le gestionnaire __unserialize().

### Liste de paramètres

`data`

  L'objet DateTime sérialisé.

### Valeurs de retour

L'objet DateTime.

### Exemples

Exemple #1 Exemple de DateTime::unserialize()

    <?php
    $serializedDate = 'O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}';
    var_dump(unserialize($serializedDate));

L'exemple ci-dessus va afficher :

    object(DateTime)#1 (3) {
      ["date"]=>
      string(26) "2025-03-27 00:00:00.000000"
      ["timezone_type"]=>
      int(3)
      ["timezone"]=>
      string(3) "UTC"
    }

### Voir aussi

- DateTime::__serialize() - Sérialise un DateTime

# DateTime::__wakeup

# DateTimeImmutable::__wakeup

# DateTimeInterface::__wakeup

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__wakeup -- DateTimeImmutable::__wakeup -- DateTimeInterface::__wakeup — Le gestionnaire __wakeup

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
public function DateTime::__wakeup(): void
#[\Deprecated]
public function DateTimeImmutable::__wakeup(): void
#[\Deprecated]
public function DateTimeInterface::__wakeup(): void

Le gestionnaire __wakeup().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Initialise un objet DateTime.

## Sommaire

- DateTimeInterface::diff — Retourne la différence entre deux objets DateTime
- DateTimeInterface::format — Retourne une date formatée suivant le format fourni
- DateTimeInterface::getMicrosecond — Récupère la partie microseconde de l'horodatage Unix
- DateTimeInterface::getOffset — Retourne le décalage horaire
- DateTimeInterface::getTimestamp — Récupère le timestamp Unix
- DateTimeInterface::getTimezone — Retourne le fuseau horaire relatif au DateTime fourni
- DateTime::__serialize — Sérialise un DateTime
- DateTime::__unserialize — Désérialise un DateTime
- DateTime::__wakeup — Le gestionnaire __wakeup

# La classe DateTimeZone

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Introduction

Représentation d'un fuseau horaire.

## Synopsis de la classe

class DateTimeZone {
/* Constantes */
public const int AFRICA;
public const int AMERICA;
public const int ANTARCTICA;
public const int ARCTIC;
public const int ASIA;
public const int ATLANTIC;
public const int AUSTRALIA;
public const int EUROPE;
public const int INDIAN;
public const int PACIFIC;
public const int UTC;
public const int ALL;
public const int ALL_WITH_BC;
public const int PER_COUNTRY;
/* Méthodes */
public function __construct(string `$timezone`)
public function getLocation(): array|false
public function getName(): string
public function getOffset(DateTimeInterface `$datetime`): int
public function getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false
public static function listAbbreviations(): array
public static function listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array
}

## Constantes pré-définies

`DateTimeZone::AFRICA` int

  Fuseau africain.

`DateTimeZone::AMERICA` int

  Fuseau américain.

`DateTimeZone::ANTARCTICA` int

  Fuseau antarctique.

`DateTimeZone::ARCTIC` int

  Fuseau arctique.

`DateTimeZone::ASIA` int

  Fuseau asiatique.

`DateTimeZone::ATLANTIC` int

  Fuseau atlantique.

`DateTimeZone::AUSTRALIA` int

  Fuseau australien.

`DateTimeZone::EUROPE` int

  Fuseau européen.

`DateTimeZone::INDIAN` int

  Fuseau indien.

`DateTimeZone::PACIFIC` int

  Fuseau pacifique.

`DateTimeZone::UTC` int

  Fuseau UTC.

`DateTimeZone::ALL` int

  Tous les fuseaux.

`DateTimeZone::ALL_WITH_BC` int

  Tous les fuseaux, y compris les anciens.

`DateTimeZone::PER_COUNTRY` int

  Fuseaux horaires par pays.

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.

# DateTimeZone::__construct

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::__construct -- timezone_open — Crée un nouvel objet DateTimeZone

### Description

Style orienté objet

public function DateTimeZone::__construct(string `$timezone`)

Style procédural

function timezone_open(string `$timezone`): DateTimeZone|false

Crée un nouvel objet DateTimeZone.

Un objet DateTimeZone fournit l'accès à trois types différents de règles de fuseaux horaires : un décalage UTC (type `1`), une abréviation de fuseau horaire (type `2`), et un identifiant de fuseau horaire tel que publié dans la base de données de fuseau horaire IANA (type `3`).

L'objet DateTimeZone peut être attaché aux objets DateTime et DateTimeImmutable afin d'être en mesure de rendre le fuseau horaire encapsulé par ces objets dans un fuseau horaire local.

### Liste de paramètres

`timezone`

  Un des fuseaux horaires supportés, une valeur de décalage (+0200), ou une abréviation de fuseau (BST).

### Valeurs de retour

Retourne un objet DateTimeZone, en cas de succès. Style procédural retourne `false` en cas d'erreur..

### Erreurs / Exceptions

Cette méthode lance une DateInvalidTimeZoneException si le fuseau horaire fourni n'est pas reconnu comme un fuseau horaire valide. Antérieur à PHP 8.3, ceci était une Exception.

### Historique

Version | Description
--- | ---
8.3.0 | Les valeurs invalides lancent désormais une DateInvalidTimeZoneException au lieu d'une Exception générique.

### Exemples

Exemple #1 Création et attachement d'un DateTimeZone à un DateTimeImmutable

    <?php
    $d = new DateTimeImmutable("2022-06-02 15:44:48 UTC");

    $timezones = [ 'Europe/London', 'GMT+04:45', '-06:00', 'CEST' ];

    foreach ($timezones as $tz) {
        $tzo = new DateTimeZone($tz);

        $local = $d->setTimezone($tzo);
        echo $local->format(DateTimeInterface::RFC2822 . ' — e') . "\n";
    }

L'exemple ci-dessus va afficher :

    Thu, 02 Jun 2022 16:44:48 +0100 — Europe/London
    Thu, 02 Jun 2022 20:29:48 +0445 — +04:45
    Thu, 02 Jun 2022 09:44:48 -0600 — -06:00
    Thu, 02 Jun 2022 17:44:48 +0200 — CEST

Exemple #2 Interception des erreurs avec DateTimeZone

    <?php
    // Gestion des erreurs par interception des exceptions
    $timezones = array('Europe/London', 'Mars/Phobos', 'Jupiter/Europa');

    foreach ($timezones as $tz) {
        try {
            $mars = new DateTimeZone($tz);
            echo $mars->getName() . "\n";
        } catch(Exception $e) {
            echo $e->getMessage() . "\n";
        }
    }

L'exemple ci-dessus va afficher :

    Europe/London
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Mars/Phobos)
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Jupiter/Europa)

# DateTimeZone::getLocation

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeZone::getLocation -- timezone_location_get — Retourne les informations géographiques d'un fuseau horaire

### Description

Style orienté objet

public function DateTimeZone::getLocation(): array|false

Style procédural

function timezone_location_get(DateTimeZone `$object`): array|false

Retourne les informations géographiques d'un fuseau horaire, comprenant le code du pays, la latitude et la longitude, et commentaires.

### Liste de paramètres

`object`
  Seulement en style procédural : un DateTimeZone objet retourné par timezone_open()

### Valeurs de retour

Tableau contenant les informations de localisation du fuseau horaire ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec DateTimeZone::getLocation()

    <?php
    $tz = new DateTimeZone("Asia/Jakarta");
    print_r($tz->getLocation());
    print_r(timezone_location_get($tz));

L'exemple ci-dessus va afficher :

    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )
    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )

L'élément `country_code` contient le code pays ISO 3166-1 alpha-2 de chaque entrée. Les éléments `latitude` et `longitude` contiennent les coordonnées de la ville nommée à partir de l'identifiant de fuseau horaire, et `comments` contient (lorsque non `false`) un indice de l'endroit où dans le pays donné ce fuseau horaire est appliqué. Cette information est appropriée pour les utilisateurs finaux.

### Voir aussi

- DateTimeZone::listIdentifiers() - Retourne un tableau numérique contenant tous les identifiants de fuseaux horaires définis pour obtenir une liste complète ou partielle de tous les identifiants de fuseaux horaires pris en charge

# DateTimeZone::getName

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getName -- timezone_name_get — Retourne le nom du fuseau horaire

### Description

Style orienté objet

public function DateTimeZone::getName(): string

Style procédural

function timezone_name_get(DateTimeZone `$object`): string

Retourne le nom du fuseau horaire.

### Liste de paramètres

`object`

  L'objet DateTimeZone utilisé pour récupérer le nom du fuseau horaire.

### Valeurs de retour

Selon le type de zone, le décalage UTC (type 1), l'abréviation de fuseau horaire (type 2) et les identifiants de fuseau horaire tels que publiés dans la base de données de fuseaux horaires IANA (type 3), la chaîne de description pour créer un nouvel objet DateTimeZone avec le même décalage et/ou les mêmes règles. Par exemple `02:00`, `CEST` ou l'un des noms de fuseaux horaires dans la liste des fuseaux horaires.

# DateTimeZone::getOffset

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getOffset -- timezone_offset_get — Retourne le décalage GMT d'un fuseau horaire

### Description

Style orienté objet

public function DateTimeZone::getOffset(DateTimeInterface `$datetime`): int

Style procédural

function timezone_offset_get(DateTimeZone `$object`, DateTimeInterface `$datetime`): int

timezone_offset_get() retourne le décalage horaire par rapport au GMT pour le paramètre `datetime`. Le décalage GMT est calculé à partir des informations de fuseau horaire contenues dans l'objet DateTimeZone utilisé.

### Liste de paramètres

`object`
  Seulement en style procédural : un DateTimeZone objet retourné par timezone_open()
`datetime`

  Objet DateTime qui contient la date dont il faut calculer le décalage.

### Valeurs de retour

Retourne le décalage horaire, exprimé en secondes, en cas de succès.

### Exemples

Exemple #1 Exemple avec DateTimeZone::getOffset()

    <?php
    // Crée deux objets fuseau horaire, un pour Taipei (Taiwan) et un pour
    // Tokyo (Japon)
    $dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
    $dateTimeZoneJapan = new DateTimeZone("Asia/Tokyo");

    // Crée deux objets DateTime qui contiennent le même timestamp Unix,
    // mais sont situés dans deux fuseaux horaires différents.
    $dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
    $dateTimeJapan = new DateTime("now", $dateTimeZoneJapan);

    // Calcule le décalage horaire GMT pour l'objet $dateTimeTaipei
    // mais en utilisant le fuseau horaire de Tokyo
    // ($dateTimeZoneJapan).
    $timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);

    // Devrait afficher int(32400) (pour les dates après le Sat Sep 8 01:00:00 1951 JST).
    var_dump($timeOffset);

L'exemple ci-dessus va afficher :

    int(32400)

# DateTimeZone::getTransitions

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getTransitions -- timezone_transitions_get — Retourne toutes les transitions d'un fuseau horaire

### Description

Style orienté objet

public function DateTimeZone::getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

Style procédural

function timezone_transitions_get(DateTimeZone `$object`, int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

### Liste de paramètres

`object`
  Seulement en style procédural : un DateTimeZone objet retourné par timezone_open()
`timestampBegin`

  Début du timestamp.

`timestampEnd`

  Fin du timestamp.

### Valeurs de retour

Retourne un tableau indexé numériquement des tableaux de transition en cas de succès, ou `false` si une erreur survient. Les objets DateTimeZone enveloppant des fuseaux de type 1 (décalage UTC) et type 2 (abréviations) ne contiennent pas de transitions et appeler cette méthode sur eux retournera `false`.

Si `timestampBegin` est fourni, la première entrée dans le tableau retourné contiendra un élément de transition au temps de `timestampBegin`.

Structure des tableaux de transition
Clé | Type | Description
--- | --- | ---
`ts` | int | timestamp Unix
`time` | string | Chaîne de temps `DateTimeInterface::ISO8601_EXPANDED` (PHP 8.2 et ultérieur), ou `DateTimeInterface::ISO8601` (PHP 8.1 et inférieur)
`offset` | int | Décalage horaire vers UTC en secondes
`isdst` | bool | Indique si l'heure d'été est active
`abbr` | string | Abréviation du fuseau horaire

### Historique

Version | Description
--- | ---
8.1.0 | La valeur par défaut de `timestampEnd` a été changée en 2147483647. Auparavant, c'était `PHP_INT_MAX`.

### Exemples

Exemple #1 Exemple avec timezone_transitions_get()

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions();
    print_r(array_slice($transitions, 0, 3));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [ts] => -2147483648
                [time] => 1901-12-13T20:45:52+00:00
                [offset] => -75
                [isdst] =>
                [abbr] => LMT
            )

        [1] => Array
            (
                [ts] => 442304971
                [time] => 1847-12-01T00:01:15+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => -1691964000
                [time] => 1916-05-21T02:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

Exemple #2 Un exemple de timezone_transitions_get() avec `timestampBegin` défini

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions(time());
    print_r(array_slice($transitions, 0, 3));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [ts] => 1759058251
                [time] => 2025-09-28T11:17:31+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

        [1] => Array
            (
                [ts] => 1761440400
                [time] => 2025-10-26T01:00:00+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => 1774746000
                [time] => 2026-03-29T01:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

# DateTimeZone::listAbbreviations

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listAbbreviations -- timezone_abbreviations_list — Retourne un tableau associatif, décrivant un fuseau horaire

### Description

Style orienté objet

public static function DateTimeZone::listAbbreviations(): array

Style procédural

function timezone_abbreviations_list(): array

La liste des abréviations retournée contient tous les usages historiques des abréviations, ce qui peut amener à des entrées correctes, mais confuses. Il y a aussi des conflits, car `PST` est utilisé à la fois aux États-Unis et aux Philippines.

La liste que cette fonction retourne n'est par conséquent pas adaptée pour construire un tableau d'options présentant un choix de fuseau horaire aux utilisateurs.

> Note:

> Les données pour cette fonction sont pré-compilées pour des raisons de performance, et ne sont pas mises à jour lors de l'utilisation d'une » timezonedb plus récente.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le tableau des abréviations des fuseaux horaires.

### Exemples

Exemple #1 Exemple avec timezone_abbreviations_list()

    <?php
    $timezone_abbreviations = DateTimeZone::listAbbreviations();
    print_r($timezone_abbreviations["acst"]);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Adelaide
            )

        [1] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Broken_Hill
            )

        [2] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Darwin
            )

        [3] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/North
            )

        [4] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/South
            )

        [5] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Yancowinna
            )

    )

### Voir aussi

- timezone_identifiers_list() - Alias de DateTimeZone::listIdentifiers

# DateTimeZone::listIdentifiers

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — Retourne un tableau numérique contenant tous les identifiants de fuseaux horaires définis

### Description

Style orienté objet

public static function DateTimeZone::listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

Style procédural

function timezone_identifiers_list(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

Retourne la liste des » identifiants de fuseaux horaires IANA.

> Note: Il est possible de détecter le fuseau horaire du client (navigateur) en JavaScript en utilisant » Intl.DateTimeFormat ou » Temporal.ZonedDateTime.

### Liste de paramètres

`timezoneGroup`

  Une (ou une combinaison) des constantes de classe DateTimeZone.

`countryCode`

  Un code de pays en deux lettres (en majuscule), compatible ISO 3166-1.

  > Note: Cette option n'est disponible que lorsque le paramètre `timezoneGroup` prend la valeur de `DateTimeZone::PER_COUNTRY`.

### Valeurs de retour

Retourne le tableau des identifiants des fuseaux horaires. Seuls les éléments non obsolètes sont retournés. Pour tout obtenir, y compris les identifiants de fuseau horaire obsolètes, utiliser `DateTimeZone::ALL_WITH_BC` comme valeur pour `timezoneGroup`.

### Historique

Version | Description
--- | ---
8.0.0 | Antérieur à cette version, `false` était retourné en cas d'échec.
7.1.0 | `countryCode` est désormais nullable.

### Exemples

Exemple #1 Lister les identifiants avec des commentaires de localisation

    <?php
    $identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ALL);

    foreach ($identifiers as $tzid) {
      $tz = new DateTimeZone($tzid);
      $comments = $tz->getLocation()['comments'];
      echo $tzid . " (" . ($comments ?: 'Région entière') . ")\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    America/Antigua (Région entière)
    America/Araguaina (Tocantins)
    America/Argentina/Buenos_Aires (Buenos Aires (BA, CF))
    America/Argentina/Catamarca (Catamarca (CT), Chubut (CH))
    America/Argentina/Cordoba (Argentine (la plupart des régions : CB, CC, CN, ER, FM, MN, SE, SF))
    // (Sortie tronquée en raison de la longueur)

Exemple #2 Lister les identifiants d'une région spécifique

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA );
    for ($i=0; $i < 5; $i++) {
        echo "$timezone_identifiers[$i]\n";
    }

Résultat de l'exemple ci-dessus est similaire à :

    Asia/Aden
    Asia/Almaty
    Asia/Amman
    Asia/Anadyr
    Asia/Aqtau

Exemple #3 Lister les identifiants de plusieurs régions

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA | DateTimeZone::PACIFIC );
    echo join( ', ', $timezone_identifiers );

Résultat de l'exemple ci-dessus est similaire à :

    Asia/Aden, Asia/Almaty, Asia/Amman, Asia/Anadyr, Asia/Aqtau, Asia/Aqtobe,
    Asia/Ashgabat, Asia/Atyrau, Asia/Baghdad, Asia/Bahrain, Asia/Baku,
    Asia/Bangkok, Asia/Barnaul, Asia/Beirut, Asia/Bishkek, Asia/Brunei,
    Asia/Chita, Asia/Choibalsan, Asia/Colombo, Asia/Damascus, Asia/Dhaka,
    Asia/Dili, Asia/Dubai, Asia/Dushanbe, Asia/Famagusta, Asia/Gaza, Asia/Hebron,
    Asia/Ho_Chi_Minh, Asia/Hong_Kong, Asia/Hovd, Asia/Irkutsk, Asia/Jakarta,
    Asia/Jayapura, Asia/Jerusalem, Asia/Kabul, Asia/Kamchatka, Asia/Karachi,
    Asia/Kathmandu, Asia/Khandyga, Asia/Kolkata, Asia/Krasnoyarsk,
    Asia/Kuala_Lumpur, Asia/Kuching, Asia/Kuwait, Asia/Macau, Asia/Magadan,
    Asia/Makassar, Asia/Manila, Asia/Muscat, Asia/Nicosia, Asia/Novokuznetsk,
    Asia/Novosibirsk, Asia/Omsk, Asia/Oral, Asia/Phnom_Penh, Asia/Pontianak,
    Asia/Pyongyang, Asia/Qatar, Asia/Qostanay, Asia/Qyzylorda, Asia/Riyadh,
    Asia/Sakhalin, Asia/Samarkand, Asia/Seoul, Asia/Shanghai, Asia/Singapore,
    Asia/Srednekolymsk, Asia/Taipei, Asia/Tashkent, Asia/Tbilisi, Asia/Tehran,
    Asia/Thimphu, Asia/Tokyo, Asia/Tomsk, Asia/Ulaanbaatar, Asia/Urumqi,
    Asia/Ust-Nera, Asia/Vientiane, Asia/Vladivostok, Asia/Yakutsk, Asia/Yangon,
    Asia/Yekaterinburg, Asia/Yerevan, Pacific/Apia, Pacific/Auckland,
    Pacific/Bougainville, Pacific/Chatham, Pacific/Chuuk, Pacific/Easter,
    Pacific/Efate, Pacific/Fakaofo, Pacific/Fiji, Pacific/Funafuti,
    Pacific/Galapagos, Pacific/Gambier, Pacific/Guadalcanal, Pacific/Guam,
    Pacific/Honolulu, Pacific/Kanton, Pacific/Kiritimati, Pacific/Kosrae,
    Pacific/Kwajalein, Pacific/Majuro, Pacific/Marquesas, Pacific/Midway,
    Pacific/Nauru, Pacific/Niue, Pacific/Norfolk, Pacific/Noumea,
    Pacific/Pago_Pago, Pacific/Palau, Pacific/Pitcairn, Pacific/Pohnpei,
    Pacific/Port_Moresby, Pacific/Rarotonga, Pacific/Saipan, Pacific/Tahiti,
    Pacific/Tarawa, Pacific/Tongatapu, Pacific/Wake, Pacific/Wallis

Exemple #4 Lister les identifiants d'un seul pays

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::PER_COUNTRY, "UA" );
    foreach( $timezone_identifiers as $identifier ) {
        echo "$identifier\n";
    }

Résultat de l'exemple ci-dessus est similaire à :

    Europe/Kyiv
    Europe/Simferopol
    Europe/Uzhgorod
    Europe/Zaporozhye

### Voir aussi

- timezone_abbreviations_list() - Alias de DateTimeZone::listAbbreviations

## Sommaire

- DateTimeZone::__construct — Crée un nouvel objet DateTimeZone
- DateTimeZone::getLocation — Retourne les informations géographiques d'un fuseau horaire
- DateTimeZone::getName — Retourne le nom du fuseau horaire
- DateTimeZone::getOffset — Retourne le décalage GMT d'un fuseau horaire
- DateTimeZone::getTransitions — Retourne toutes les transitions d'un fuseau horaire
- DateTimeZone::listAbbreviations — Retourne un tableau associatif, décrivant un fuseau horaire
- DateTimeZone::listIdentifiers — Retourne un tableau numérique contenant tous les identifiants de fuseaux horaires définis

# La classe DateInterval

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introduction

Représente un intervalle de dates.

Un intervalle stocke un nombre fixe de durées (en années, mois, jours, heures, etc.) ou une chaîne relative à une durée dans un format compréhensible par le constructeur de la classe DateTime et DateTimeImmutable.

Plus précisément, l'information d'un objet de la classe DateInterval est une instruction pour aller d'une date/moment à une autre date/moment. Ce processus n'est pas toujours réversible.

Une façon typique de créer un objet DateInterval est en calculant la différence entre deux objets dates/moments à travers DateTimeInterface::diff().

Comme il n'y a pas une manière bien définie pour comparer les intervalles, les instances de DateInterval sont incomparables.

## Synopsis de la classe

class DateInterval {
/* Propriétés */
public int $y;
public int $m;
public int $d;
public int $h;
public int $i;
public int $s;
public float $f;
public int $invert;
public mixed $days;
public bool $from_string;
public string $date_string;
/* Méthodes */
public function __construct(string `$duration`)
public static function createFromDateString(string `$datetime`): DateInterval
public function format(string `$format`): string
}

## Propriétés

Avertissement

Les propriétés disponibles répertoriées ci-dessous dépendent de la version de PHP et doivent être considérées en lecture seule.

y

  Nombre d'années.

m

  Nombre de mois.

d

  Nombre de jours.

h

  Nombre d'heures.

i

  Nombre de minutes.

s

  Nombre de secondes.

f

  Nombre de microsecondes, en une fraction de seconde.

invert

  Vaut `1` si l'intervalle représente une période de temps négative, `0` sinon. Voir la méthode DateInterval::format().

days

  Si l'objet DateInterval a été créé avec la méthode DateTimeImmutable::diff() ou DateTime::diff(), alors ce sera le nombre total de jours entre la date de début et la date de fin. Sinon, days vaudra `false`.

from_string

  Si l'objet DateInterval a été créé avec la méthode DateInterval::createFromDateString(), alors cette propriété vaudra `true`, et la propriété date_string sera renseignée. Sinon, cette propriété vaudra `false`, et les propriétés de y à f, invert, et days seront renseignées.

date_string

  La chaîne de caractères utilisée comme argument pour DateInterval::createFromDateString().

## Historique

Version | Description
--- | ---
8.2.0 | Les propriétés from_string et date_string ont été ajoutées aux instances de DateInterval qui ont été créées à l'aide de la méthode DateInterval::createFromDateString().
8.2.0 | Seules les propriétés de `y` jusqu'à `f`, `invert`, et `days` seront visibles.
7.4.0 | Les instances de DateInterval sont désormais incomparables ; auparavant, toutes les instances DateInterval étaient considérées comme égales.
7.1.0 | La propriété f a été ajoutée.

# DateInterval::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::__construct — Crée un nouvel objet DateInterval

### Description

public function DateInterval::__construct(string `$duration`)

Crée un nouvel objet DateInterval.

### Liste de paramètres

`duration`

  Une spécification d'intervalle.

  Le format commence avec la lettre `P`, pour period. Chaque durée de la période est représentée par une valeur entière suivie par une désignation de période. Si la durée contient des éléments de temps, cette portion de la spécification est précédée par la lettre `T`.

  Désignation de période `duration`
  Désignation de période | Description
  --- | ---
  `Y` | Années
  `M` | Mois
  `D` | Jours
  `W` | Semaine. Convertie en jours. Antérieur à PHP 8.0.0, ne peut pas être combiné avec `D`.
  `H` | Heures
  `M` | Minutes
  `S` | Secondes

  Voici quelques exemples simples : 2 jours sera `P2D` ; 2 secondes sera `PT2S` ; 6 années et 5 minutes sera `P6YT5M`.

  > Note:

  > Les types d'unité doivent être entrés des plus grands aux plus petits. Ainsi, les années doivent être présentes avant les mois, les mois avant les jours, les jours avant les minutes, etc. Aussi, une année et 4 jours doivent être représentés comme `P1Y4D`, et non `P4D1Y`.

  Cette spécification peut également être représentée sous la forme d'une date avec heure. Aussi, une année et 4 jours peuvent être `P0001-00-04T00:00:00`. Mais les valeurs de ce format ne peuvent pas excéder une période donnée (c.-à-d. `25` heures est invalide).

  Ces formats sont basés sur la » spécification de durée ISO 8601.

### Erreurs / Exceptions

Lance une exception DateMalformedIntervalStringException lorsque le paramètre `duration` ne peut être analysé comme un intervalle. Antérieur à PHP 8.3, ceci était une Exception.

### Historique

Version | Description
--- | ---
8.3.0 | Lance désormais une DateMalformedIntervalStringException au lieu de Exception.
8.2.0 | Seules les propriétés `y` à `f`, `invert`, et `days` seront visibles, y compris une nouvelle propriété booléenne `from_string`.
8.0.0 | `W` peut être combiné avec `D`.

### Exemples

Exemple #1 Construction et utilisation des objets DateInterval

    <?php
    // Créer une date spécifique
    $someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");

    // Créer un intervalle
    $interval = new \DateInterval("P7D");

    // Ajouter un intervalle
    $someDate->add($interval);

    // Convertir l'intervalle en chaîne de caractères
    echo $interval->format("%d");

L'exemple ci-dessus va afficher :

    7

Exemple #2 Exemple avec DateInterval

    <?php
    $interval = new DateInterval('P1W2D');
    var_dump($interval);

Résultat de l'exemple ci-dessus en PHP 8.2 :

    object(DateInterval)#1 (10) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["from_string"]=>
      bool(false)
    }

Résultat de l'exemple ci-dessus en PHP 8 :

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

Résultat de l'exemple ci-dessus en PHP 7 :

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(2)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

### Voir aussi

- DateInterval::format() - Formate l'intervalle
- DateTime::add() - Modifie un objet DateTime, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté
- DateTime::sub() - Soustrait une durée à un objet DateTime
- DateTime::diff() - Retourne la différence entre deux objets DateTime

# DateInterval::createFromDateString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::createFromDateString — Configure un objet DateInterval à partir des parties d'une chaîne

### Description

Style orienté objet

public static function DateInterval::createFromDateString(string `$datetime`): DateInterval

Style procédural

function date_interval_create_from_date_string(string `$datetime`): DateInterval|false

Utilise les analyseurs de dates comme celui de DateTimeImmutable et configure un objet DateInterval à partir d'une chaîne de caractères.

### Liste de paramètres

`datetime`

  Une date avec des parties relatives. Spécifiquement, le format relatif supporté par l'analyseur utilisé pour les classes DateTimeImmutable, DateTime, et strtotime() sera utilisé pour construire le DateInterval.

  Pour utiliser une chaîne au format ISO-8601 comme `P7D`, il faut utiliser DateInterval::__construct().

### Valeurs de retour

Retourne DateInterval en cas de succès. Style procédural retourne `false` en cas d'erreur.

### Erreurs / Exceptions

API orientée objet uniquement : Si une chaîne Date/Time invalide est passée, DateMalformedIntervalStringException est levée.

### Historique

Version | Description
--- | ---
8.4.0 | A désormais un type de retour provisoire de DateInterval. Auparavant, il était DateInterval|false. | 8.3.0 | DateInterval::createFromDateString() lance désormais DateMalformedIntervalStringException si une chaîne invalide est passée. Auparavant, il retournait `false`, et un avertissement était émis. date_interval_create_from_date_string() n'a pas été modifié.
8.2.0 | Seules les propriétés `from_string` et `date_string` seront visibles lorsqu'un objet DateInterval est créé avec cette méthode.

### Exemples

Exemple #1 Analyse d'intervalles de dates valides

    <?php
    // Chacun de ces intervalles est égal.
    $i = new DateInterval('P1D');
    $i = DateInterval::createFromDateString('1 day');

    $i = new DateInterval('P2W');
    $i = DateInterval::createFromDateString('2 weeks');

    $i = new DateInterval('P3M');
    $i = DateInterval::createFromDateString('3 months');

    $i = new DateInterval('P4Y');
    $i = DateInterval::createFromDateString('4 years');

    $i = new DateInterval('P1Y1D');
    $i = DateInterval::createFromDateString('1 year + 1 day');

    $i = new DateInterval('P1DT12H');
    $i = DateInterval::createFromDateString('1 day + 12 hours');

    $i = new DateInterval('PT3600S');
    $i = DateInterval::createFromDateString('3600 seconds');

Exemple #2 Analyse des combinaisons et des intervalles négatifs

    <?php
    $i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
    echo $i->format('%d %h %i'), "\n";

    $i = DateInterval::createFromDateString('1 year - 10 days');
    echo $i->format('%y %d'), "\n";

L'exemple ci-dessus va afficher :

    449 2 70
    1 -10

Exemple #3 Analyse des intervalles de dates relatifs spéciaux

    <?php
    $i = DateInterval::createFromDateString('last day of next month');
    var_dump($i);

    $i = DateInterval::createFromDateString('last weekday');
    var_dump($i);

Résultat de l'exemple ci-dessus en PHP 8.2 :

    object(DateInterval)#1 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(22) "last day of next month"
    }
    object(DateInterval)#2 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(12) "last weekday"
    }

Résultat de l'exemple ci-dessus en PHP 8 est similaire à :

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(1)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(2)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }
    object(DateInterval)#2 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(1)
      ["special_amount"]=>
      int(-1)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(1)
    }

# DateInterval::format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::format — Formate l'intervalle

### Description

public function DateInterval::format(string `$format`): string

Formate l'intervalle.

### Liste de paramètres

`format`

  Les caractères suivants sont reconnus dans la chaîne `format`. Chaque caractère utilisé pour le format doit être préfixé par un signe de pourcentage (`%`).
  Caractère de `format` | Description | Valeur d'exemple
  --- | --- | ---
  `%` | Caractère `%` littéral | `%`
  `Y` | Année, numérique, au moins 2 chiffres avec zéros initiaux | `01`, `03`
  `y` | Année, numérique | `1`, `3`
  `M` | Mois, numérique, au moins 2 chiffres avec zéros initiaux | `01`, `03`, `12`
  `m` | Mois, numérique | `1`, `3`, `12`
  `D` | Jour, numérique, au moins 2 chiffres avec zéros initiaux | `01`, `03`, `31`
  `d` | Jour, numérique | `1`, `3`, `31`
  `a` | Nombre total de jours, provenant de la méthode DateTime::diff() ou `(unknown)` sinon | `4`, `18`, `8123`
  `H` | Heure, numérique, au moins 2 chiffres avec zéros initiaux | `01`, `03`, `23`
  `h` | Heure, numérique | `1`, `3`, `23`
  `I` | Minute, numérique, au moins 2 chiffres avec zéros initiaux | `01`, `03`, `59`
  `i` | Minute, numérique | `1`, `3`, `59`
  `S` | Seconde, numérique, au moins 2 chiffres avec zéros initiaux | `01`, `03`, `57`
  `s` | Seconde, numérique | `1`, `3`, `57`
  `F` | Microsecondes, numérique, au moins 6 chiffres, avec zéros initiaux | `007701`, `052738`, `428291`
  `f` | Microsecondes, numérique | `7701`, `52738`, `428291`
  `R` | Signe "`-`" lorsque négatif, "`+`" si positif | `-`, `+`
  `r` | Signe "`-`" lorsque négatif, vide si positif | `-`, ``

### Valeurs de retour

Retourne l'intervalle formaté.

### Historique

Version | Description
--- | ---
7.2.12 | Le format `F` et `f` sera désormais toujours positif.
7.1.0 | Les caractères de format `F` et `f` ont été ajoutés.

### Exemples

Exemple #1 Exemple avec DateInterval

    <?php
    $interval = new DateInterval('P2Y4DT6H8M');
    echo $interval->format('%d jours');

L'exemple ci-dessus va afficher :

    4 jours

Exemple #2 DateInterval et retenue

    <?php
    $interval = new DateInterval('P32D');
    echo $interval->format('%d jours');

L'exemple ci-dessus va afficher :

    32 jours

Exemple #3 DateInterval et DateTime::diff() avec les modificateurs %a et %d

    <?php
    $january = new DateTime('2010-01-01');
    $february = new DateTime('2010-02-01');
    $interval = $february->diff($january);

    // %a affichera le nombre total de jours...
    echo $interval->format('%a jours au total')."\n";

    // ...alors que %d n'affichera que le nombre de jours non encore couverts
    // dans le mois.
    echo $interval->format('%m mois, %d jour');

L'exemple ci-dessus va afficher :

    31 jours au total
    1 mois, 0 jour

### Notes

> Note:

> La méthode DateInterval::format() ne recalcule pas la retenue dans les chaînes de temps ni dans les segments de date. Ce comportement est attendu car il n'est pas possible de dépasser des valeurs comme `"32 days"` qui pourraient être interprétées comme `"1 mois et 4 jours"` ou `"1 mois et 1 jour"`.

### Voir aussi

- DateTime::diff() - Retourne la différence entre deux objets DateTime

## Sommaire

- DateInterval::__construct — Crée un nouvel objet DateInterval
- DateInterval::createFromDateString — Configure un objet DateInterval à partir des parties d'une chaîne
- DateInterval::format — Formate l'intervalle

# La classe DatePeriod

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introduction

Représente une période de dates.

Une période de dates permet des itérations à travers un jeu de dates et d'heures, survenant à intervalle régulier, sur une période donnée.

## Synopsis de la classe

class DatePeriod implements IteratorAggregate {
/* Constantes */
public const int EXCLUDE_START_DATE;
public const int INCLUDE_END_DATE;
/* Propriétés */
public readonly ?DateTimeInterface $start;
public readonly ?DateTimeInterface $current;
public readonly ?DateTimeInterface $end;
public readonly ?DateInterval $interval;
public readonly int $recurrences;
public readonly bool $include_start_date;
public readonly bool $include_end_date;
/* Méthodes */
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
public function __construct(string `$isostr`, int `$options` = 0)
public static function createFromISO8601String(string `$specification`, int `$options` = 0): static
public function getDateInterval(): DateInterval
public function getEndDate(): ?DateTimeInterface
public function getRecurrences(): ?int
public function getStartDate(): DateTimeInterface
}

## Constantes pré-définies

`DatePeriod::EXCLUDE_START_DATE` int

  Exclut la date de début, utilisée par DatePeriod::__construct().

`DatePeriod::INCLUDE_END_DATE` int

  Inclut la date de fin, utilisée par DatePeriod::__construct().

## Propriétés

recurrences

  La quantité minimale d'instances retournée par l'itérateur.

  Si le nombre de récurrences a été explicitement passé par l'intermédiaire du paramètre `$recurrences` dans le constructeur de l'instance DatePeriod, alors cette propriété contient cette valeur, plus un si la date de début n'a pas été désactivée par `DatePeriod::EXCLUDE_START_DATE`, plus un si la date de fin a été activée par `DatePeriod::INCLUDE_END_DATE`.

  Si le nombre de récurrences n'a pas été explicitement passé, alors cette propriété contient le nombre minimum d'instances retournées. Cela serait `0`, plus un si la date de début n'a pas été désactivée par `DatePeriod::EXCLUDE_START_DATE`, plus un si la date de fin a été activée par `DatePeriod::INCLUDE_END_DATE`.

      <?php
      $start = new DateTime('2018-12-31 00:00:00');
      $end   = new DateTime('2021-12-31 00:00:00');
      $interval = new DateInterval('P1M');
      $recurrences = 5;

      // récurrences explicitement définies par le constructeur
      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
      echo $period->recurrences, "\n";

      // récurrences non définies dans le constructeur
      $period = new DatePeriod($start, $interval, $end);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

  L'exemple ci-dessus va afficher :

      5
      6
      7
      1
      0

  Voir aussi DatePeriod::getRecurrences().

include_end_date

  Inclut ou non la date de fin dans le jeu de dates récurrentes.

include_start_date

  S'il faut inclure la date de début dans l'ensemble des dates récurrentes ou non.

start

  La date de début de la période.

current

  Pendant l'itération, cela contiendra la date courante dans la période.

end

  La date de fin de la période.

interval

  Une spécification d'intervalle répétitif ISO 8601.

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.
8.2.0 | La constante `DatePeriod::INCLUDE_END_DATE` et la propriété include_end_date ont été ajoutées.
8.0.0 | La classe DatePeriod implémente désormais IteratorAggregate. Auparavant, seule Traversable était implémentée.

# DatePeriod::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DatePeriod::__construct — Crée un nouvel objet DatePeriod

### Description

public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
Avertissement

Les constructeurs suivants ont été rendus obsolètes :

public function DatePeriod::__construct(string `$isostr`, int `$options` = 0)

Cette variante du constructeur est obsolète à partir de PHP 8.4.0, utiliser DatePeriod::createFromISO8601String() à la place.

Crée un nouvel objet DatePeriod.

Les objets DatePeriod peuvent être utilisés comme itérateur pour générer un certain nombre d'objets DateTimeImmutable ou DateTime à partir d'une `start` date (date de début), un `interval`, et une `end` date (date de fin) ou du nombre de `recurrences`.

La classe des objets renvoyés est équivalente à la classe ancêtre DateTimeImmutable ou DateTime fournie par l'objet `start`.

### Liste de paramètres

`start`

  La date de début de la période. Incluse par défaut dans le jeu de résultats.

`interval`

  L'intervalle entre les récurrences de la période.

`recurrences`

  Le nombre de récurrences. Doit être plus grand que `0`. Le nombre de résultats renvoyés est supérieur d'une unité, car la date de début est incluse dans le jeu de résultats par défaut.

`end`

  La date de fin de la période. Non incluse par défaut dans le jeu de résultats.

`isostr`

  Un sous-ensemble de la » spécification ISO 8601 de la répétition de l'intervalle.

  Exemples de certaines fonctionnalités de spécification d'intervalle ISO 8601 que PHP ne prend pas en charge :

  1. Les occurrences zéro (`R0/`)
  2. Décalages horaires autres que UTC (`Z`), tels que `+02:00`.
`options`

  Un champ de bits qui peut être utilisé pour contrôler certains comportements avec les dates de début et de fin.

  Peut être configuré à `DatePeriod::EXCLUDE_START_DATE` pour exclure la date de début du jeu de dates de récurrence dans la période.

  Peut être configuré à `DatePeriod::INCLUDE_END_DATE` pour inclure la date de fin du jeu de dates de récurrence dans la période.

### Erreurs / Exceptions

Lance une exception DateMalformedPeriodStringException lorsque le paramètre `isostr` ne peut être analysé comme une période ISO 8601 valide. Antérieur à PHP 8.3, ceci était une Exception.

### Historique

Version | Description
--- | ---
8.4.0 | La signature utilisant `isostr` a été dépréciée, utiliser DatePeriod::createFromISO8601String() à la place.
8.3.0 | Lance désormais une DateMalformedPeriodStringException au lieu de Exception.
8.2.0 | La constante `DatePeriod::INCLUDE_END_DATE` a été ajoutée.
7.2.19, 7.3.6, 7.4.0 | `recurrences` doit désormais être plus grand que `0`.

### Exemples

Exemple #1 Exemple avec DatePeriod

    <?php
    $start = new DateTime('2012-07-01');
    $interval = new DateInterval('P7D');
    $end = new DateTime('2012-07-31');
    $recurrences = 4;
    $iso = 'R4/2012-07-01T00:00:00Z/P7D';

    // Toutes ces périodes sont équivalentes.
    $period = new DatePeriod($start, $interval, $recurrences);
    $period = new DatePeriod($start, $interval, $end);
    $period = new DatePeriod($iso);

    // En parcourant l'objet DatePeriod, toutes les
    // dates de la récursion pour la période seront affichées.
    foreach ($period as $date) {
        echo $date->format('Y-m-d')."\n";
    }

L'exemple ci-dessus va afficher :

    Deprecated: Calling DatePeriod::__construct(string $isostr, int $options = 0) is deprecated, use DatePeriod::createFromISO8601String() instead in script on line 11
    2012-07-01
    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Exemple #2 Exemple avec DatePeriod et `DatePeriod::EXCLUDE_START_DATE`

    <?php
    $start = new DateTime('2012-07-01');
    $interval = new DateInterval('P7D');
    $end = new DateTime('2012-07-31');

    $period = new DatePeriod($start, $interval, $end,
                             DatePeriod::EXCLUDE_START_DATE);

    // En parcourant l'objet DatePeriod,
    // toutes les dates de récurrence pour la période sont affichées.
    // Notez que, dans ce cas, 2012-07-01 ne sera pas affiché.
    foreach ($period as $date) {
        echo $date->format('Y-m-d')."\n";
    }

L'exemple ci-dessus va afficher :

    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Exemple #3 DatePeriod montrant tous les derniers jeudis du mois sur une année

    <?php
    $begin = new DateTime('2021-12-31');
    $end = new DateTime('2022-12-31 23:59:59');

    $interval = DateInterval::createFromDateString('last thursday of next month');
    $period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);

    foreach ($period as $dt) {
        echo $dt->format('l Y-m-d'), "\n";
    }

L'exemple ci-dessus va afficher :

    Thursday 2022-01-27
    Thursday 2022-02-24
    Thursday 2022-03-31
    Thursday 2022-04-28
    Thursday 2022-05-26
    Thursday 2022-06-30
    Thursday 2022-07-28
    Thursday 2022-08-25
    Thursday 2022-09-29
    Thursday 2022-10-27
    Thursday 2022-11-24
    Thursday 2022-12-29

### Notes

Les nombres de répétitions non bornés spécifiés dans la section 4.5 "Intervalle de temps récurrent" de la norme ISO 8601 ne sont pas supportés, c'est-à-dire ni `"R/..."` comme `isostr` ni `null` comme `end` ne fonctionneraient.

# DatePeriod::createFromISO8601String

(PHP 8 >= 8.3.0)

DatePeriod::createFromISO8601String — Crée un nouvel objet DatePeriod à partir d'une chaîne de caractères ISO8601

### Description

public static function DatePeriod::createFromISO8601String(string `$specification`, int `$options` = 0): static

Crée un nouvel objet DatePeriod à partir d'une chaîne de caractères ISO8601, tel que spécifié avec `specification`.

### Liste de paramètres

`specification`

  Un sous-ensemble de la spécification » ISO 8601 des intervalles récurrents.

  Un exemple de spécification d'intervalle ISO 8601 acceptée est `R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M`, qui spécifie :

  - 5 itérations (`R5/`)
  - Commence à `2008-03-01T13:00:00Z`.
  - Chaque itération est un intervalle de 1 an, 2 mois, 10 jours, 2 heures et 30 minutes (`/P1Y2M10DT2H30M`).

  Les exemples de certaines fonctionnalités de spécification d'intervalle ISO 8601 que PHP ne prend pas en charge sont :

  1. zéro occurrences (`R0/`)
  2. décalages horaires autres que UTC (`Z`), tels que `+02:00`.
`options`

  Un champ de bits qui peut être utilisé pour contrôler certains comportements avec les dates de début et de fin.

  Avec `DatePeriod::EXCLUDE_START_DATE` on exclut la date de début de l'ensemble des dates récurrentes dans la période.

  Avec `DatePeriod::INCLUDE_END_DATE` on inclut la date de fin dans l'ensemble des dates récurrentes dans la période.

### Valeurs de retour

Crée un nouvel objet DatePeriod.

Les objets DatePeriod créés avec cette méthode peuvent être utilisés comme un itérateur pour générer un certain nombre d'objets DateTimeImmutable.

### Erreurs / Exceptions

Lance une DateMalformedPeriodStringException quand la `specification` ne peut pas être analysée comme un intervalle ISO 8601 valide.

### Exemples

Exemple #1 Exemple de DatePeriod::createFromISO8601String

    <?php
    $iso = 'R4/2023-07-01T00:00:00Z/P7D';
    $period = DatePeriod::createFromISO8601String($iso);

    // En itérant sur l'objet DatePeriod, toutes les
    // dates récurrentes dans cette période sont affichées.
    foreach ($period as $date) {
        echo $date->format('Y-m-d'), "\n";
    }

L'exemple ci-dessus va afficher :

    2023-07-01
    2023-07-08
    2023-07-15
    2023-07-22
    2023-07-29

# DatePeriod::getDateInterval

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getDateInterval — Retourne l'intervalle

### Description

Style orienté objet

public function DatePeriod::getDateInterval(): DateInterval

Retourne un objet DateInterval représentant l'intervalle utilisé pour la période.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet DateInterval

### Exemples

Exemple #1 Exemple avec DatePeriod::getDateInterval()

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $interval = $period->getDateInterval();
    echo $interval->format('%d day');

L'exemple ci-dessus va afficher :

    1 day

### Voir aussi

- DatePeriod::getStartDate() - Obtient la date de début
- DatePeriod::getEndDate() - Retourne la date de fin

# DatePeriod::getEndDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getEndDate — Retourne la date de fin

### Description

Style orienté objet

public function DatePeriod::getEndDate(): ?DateTimeInterface

Retourne la date de fin de la période.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `null` si la DatePeriod n'a pas de date de fin. Par exemple, lorsqu'elle est initialisée avec le paramètre `recurrences`, ou avec le paramètre `isostr` sans date de fin.

Renvoie un objet DateTimeImmutable lorsque la DatePeriod est initialisée avec un objet DateTimeImmutable comme paramètre `end`.

Retourne un objet DateTime cloné représentant la date de fin sinon.

### Exemples

Exemple #1 Exemples avec DatePeriod::getEndDate()

    <?php
    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        new DateTime('2016-05-20T00:00:00Z')
    );
    $start = $period->getEndDate();
    echo $start->format(DateTime::ISO8601);

Les exemples ci-dessus vont afficher :

    2016-05-20T00:00:00+0000

Exemple #2 DatePeriod::getEndDate() sans date de fin

    <?php
    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        7
    );
    var_dump($period->getEndDate());

L'exemple ci-dessus va afficher :

    NULL

### Voir aussi

- DatePeriod::getStartDate() - Obtient la date de début
- DatePeriod::getDateInterval() - Retourne l'intervalle

# DatePeriod::getRecurrences

(PHP 7 >= 7.2.17/7.3.4, PHP 8)

DatePeriod::getRecurrences — Récupère le nombre de récurrences

### Description

Style orienté objet

public function DatePeriod::getRecurrences(): ?int

Récupère le nombre de récurrences.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre de récurrences est défini en passant explicitement la valeur de `$recurrences` au constructeur de la classe DatePeriod, sinon il est défini comme `null`.

### Exemples

Exemple #1 Valeurs différentes pour DatePeriod::getRecurrences()

    <?php
    $start = new DateTime('2018-12-31 00:00:00');
    $end   = new DateTime('2021-12-31 00:00:00');
    $interval = new DateInterval('P1M');
    $recurrences = 5;
    // récurrences définies explicitement via le constructeur
    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
    echo $period->getRecurrences(), "\n\n";

    // récurrences non définies dans le constructeur
    $period = new DatePeriod($start, $interval, $end);
    var_dump($period->getRecurrences());

    $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
    var_dump($period->getRecurrences());

L'exemple ci-dessus va afficher :

    5
    5
    5

    NULL
    NULL

### Voir aussi

- DatePeriod::$recurrences

# DatePeriod::getStartDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getStartDate — Obtient la date de début

### Description

Style orienté objet

public function DatePeriod::getStartDate(): DateTimeInterface

Obtient la date de début d'une période.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un objet DateTimeImmutable quand la DatePeriod est initialisée avec un objet DateTimeImmutable comme paramètre `start`.

Renvoie un objet DateTime dans les autres cas.

### Exemples

Exemple #1 Exemple DatePeriod::getStartDate()

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $start = $period->getStartDate();
    echo $start->format(DateTime::ISO8601);

L'exemple ci-dessus va afficher :

    2016-05-16T00:00:00+0000

### Voir aussi

- DatePeriod::getEndDate() - Retourne la date de fin
- DatePeriod::getDateInterval() - Retourne l'intervalle

## Sommaire

- DatePeriod::__construct — Crée un nouvel objet DatePeriod
- DatePeriod::createFromISO8601String — Crée un nouvel objet DatePeriod à partir d'une chaîne de caractères ISO8601
- DatePeriod::getDateInterval — Retourne l'intervalle
- DatePeriod::getEndDate — Retourne la date de fin
- DatePeriod::getRecurrences — Récupère le nombre de récurrences
- DatePeriod::getStartDate — Obtient la date de début

# Fonctions Date/Heure

# checkdate

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdate — Valide une date grégorienne

### Description

function checkdate(int `$month`, int `$day`, int `$year`): bool

Vérifie la validité d'une date formée par les arguments. Une date est considérée comme valide si chaque paramètre est défini correctement.

### Liste de paramètres

`month`

  Le mois doit être compris entre 1 et 12.

`day`

  Le jour doit être un jour autorisé par le mois donné. Les années bissextiles sont prises en compte.

`year`

  L'année est comprise entre 1 et 32767 inclus.

### Valeurs de retour

Retourne `true` si la date fournie est valide, `false` sinon.

### Exemples

Exemple #1 Exemple avec checkdate()

    <?php
    var_dump(checkdate(12, 31, 2000));
    var_dump(checkdate(2, 29, 2001));

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)

### Voir aussi

- mktime() - Retourne l'horodatage UNIX d'une date
- strtotime() - Transforme un texte anglais en timestamp

# date

(PHP 4, PHP 5, PHP 7, PHP 8)

date — Formate un horodatage Unix

### Description

function date(string `$format`, ?int `$timestamp` = `null`): string

Retourne une date sous forme d'une chaîne, au format donné par le paramètre `format`, fournie par le paramètre `timestamp` (horodatage Unix) ou la date et l'heure courantes si aucun timestamp n'est fourni. En d'autres termes, le paramètre `timestamp` est optionnel et vaut par défaut la valeur de la fonction time().

Avertissement

Les horodatages Unix ne gèrent pas les fuseaux horaires. Utiliser la classe DateTimeImmutable, et sa méthode de formatage DateTimeInterface::format() pour formater les informations de date/heure avec un fuseau horaire attaché.

### Liste de paramètres

`format`

  Format accepté par DateTimeInterface::format().

  > Note: date() générera toujours `000000` pour les microsecondes puisqu'il prend un paramètre int, alors que DateTimeInterface::format() supporte les microsecondes si un objet de type DateTimeInterface a été créé avec des microsecondes.

`timestamp`
  Le paramètre optionnel `timestamp` est un timestamp Unix de type entier qui vaut par défaut l'heure courante locale si `timestamp` est omis ou `null`. En d'autres termes, il vaut par défaut la valeur de la fonction time().

### Valeurs de retour

Retourne une date formatée en chaîne de caractères.

### Erreurs / Exceptions

Chaque appel à une fonction date/heure générera un diagnostic de type `E_WARNING` si le fuseau horaire n'est pas valide. Voir aussi date_default_timezone_set()

### Historique

Version | Description
--- | ---
8.0.0 | `timestamp` est désormais nullable.

### Exemples

Exemple #1 Exemple avec date()

    <?php
    // Définit le fuseau horaire par défaut à utiliser.
    date_default_timezone_set('UTC');

    // Affichage de quelque chose comme : Monday
    echo date("l"). "\n";

    // Affichage de quelque chose comme : Monday 8th of August 2005 03:12:46 PM
    echo date('l jS \of F Y h:i:s A'). "\n";

    // Affiche : July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)). "\n";

    /* utilise les constantes dans le paramètre format */
    // Affichage de quelque chose comme : Wed, 25 Sep 2013 15:28:57 -0700
    echo date(DATE_RFC2822). "\n";

    // Affichage de quelque chose comme : 2000-07-01T00:00:00+00:00
    echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));

Il est possible de faire afficher un caractère spécial dans la chaîne de format en le protégeant par un antislash. Si le caractère est lui-même une séquence incluant un antislash, on devra protéger aussi l'antislash.

Exemple #2 Protection des caractères dans la fonction date()

    <?php
    // Affichage de quelque chose comme : Wednesday the 15th
    echo date('l \t\h\e jS');

Voici maintenant quelques exemples de formatage avec date(). Il est à noter qu'il est recommandé d'échapper tous les autres caractères, car s'ils ont une signification spéciale, ils risquent de produire des effets secondaires indésirables. Il est à noter que les versions futures de PHP peuvent attribuer une signification à des lettres qui sont actuellement inertes. Lorsque l'on échappe les caractères, pensez à utiliser des guillemets simples, pour que les séquences `\n` ne deviennent pas des nouvelles lignes.

Exemple #3 Exemple avec date()

    <?php
    // Aujourd'hui, le 10 mars 2001, 5:16:18 pm, Fuseau horaire
    // Mountain Standard Time (MST)

    date_default_timezone_set("America/Phoenix");

    echo date("F j, Y, g:i a") . "\n";                 // March 10, 2001, 5:16 pm
    echo date("m.d.y") . "\n";                         // 03.10.01
    echo date("j, n, Y") . "\n";                       // 10, 3, 2001
    echo date("Ymd") . "\n";                           // 20010310
    echo date('h-i-s, j-m-y, it is w Day') . "\n";     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
    echo date('\i\t \i\s \t\h\e jS \d\a\y.') . "\n";   // it is the 10th day.
    echo date("D M j G:i:s T Y") . "\n";               // Sat Mar 10 17:16:18 MST 2001
    echo date('H:m:s \m \i\s\ \m\o\n\t\h') . "\n";     // 17:03:18 m is month
    echo date("H:i:s") . "\n";                         // 17:16:18
    echo date("Y-m-d H:i:s") . "\n";                   // 2001-03-10 17:16:18 (the MySQL DATETIME format)
    ?>

Pour formater des dates dans d'autres langues, IntlDateFormatter::format() peut être utilisé à la place de date().

### Notes

> Note:

> Pour générer un timestamp à partir d'une représentation de date, il est possible d'utiliser la fonction strtotime(). De plus, certaines bases de données disposent de fonctions pour convertir leurs propres formats de date en timestamp (par exemple, MySQL et sa fonction » UNIX_TIMESTAMP()).

Astuce

Un timestamp représentant le début de la requête est disponible dans la variable $_SERVER['REQUEST_TIME'].

### Voir aussi

- DateTimeImmutable::__construct() - Retourne un nouvel objet DateTimeImmutable
- DateTimeInterface::format() - Retourne une date formatée suivant le format fourni
- gmdate() - Formate une date/heure GMT/TUC
- idate() - Formate une partie de l'heure/date locale en tant qu'entier
- getdate() - Retourne la date/heure
- getlastmod() - Retourne la date de dernière modification de la page
- mktime() - Retourne l'horodatage UNIX d'une date
- IntlDateFormatter::format() - Formate la date et l'heure sous forme de chaîne
- time() - Retourne l'horodatage UNIX actuel
- Constantes DateTime prédéfinies

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_add — Alias de DateTime::add()

### Description

Cette fonction est un alias de : DateTime::add()

# date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_create — Création d'un objet DateTime

### Description

function date_create(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTime|false

Version procédurale de DateTime::__construct()

Contrairement au constructeur de DateTime, il renverra `false` au lieu d'une exception si la chaîne `datetime` n'est pas valide.

### Liste de paramètres

Voir DateTimeImmutable::__construct.

### Valeurs de retour

Renvoie une nouvelle instance DateTime ou `false` si une erreur survient

### Voir aussi

- DateTimeImmutable::__construct() - Retourne un nouvel objet DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Analyse une heure au format texte selon le format spécifié.
- DateTime::__construct() - Retourne un nouvel objet DateTime

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_create_from_format — Alias de DateTime::createFromFormat()

### Description

Cette fonction est un alias de : DateTime::createFromFormat()

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable — Crée un nouvel objet DateTimeImmutable

### Description

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Version procédurale de DateTimeImmutable::__construct().

Contrairement au constructeur de DateTimeImmutable, cette fonction retournera `false` à la place d'une exception si la chaîne `datetime` transmise n'est pas valide.

### Liste de paramètres

Voir DateTimeImmutable::__construct.

### Valeurs de retour

Retourne une nouvelle instance DateTimeImmutable ou `false` si une erreur survient

### Voir aussi

- DateTimeImmutable::createFromFormat() - Analyse une heure au format texte selon le format spécifié.

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable_from_format — Alias de DateTimeImmutable::createFromFormat()

### Description

Cette fonction est un alias de : DateTimeImmutable::createFromFormat()

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_date_set — Alias de DateTime::setDate()

### Description

Cette fonction est un alias de : DateTime::setDate()

# date_default_timezone_get

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_get — Récupère le décalage horaire par défaut utilisé par toutes les fonctions date/heure d'un script

### Description

function date_default_timezone_get(): string

Cette fonction retourne le décalage horaire en suivant l'ordre de préférences suivant :

- Lecture du décalage horaire défini en utilisant la fonction date_default_timezone_set() (si elle existe)

- Lecture de la valeur de l'option de configuration date.timezone (si elle est définie)

Si tout ce qui précède échoue, date_default_timezone_get() retournera le décalage horaire par défaut de `UTC`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères.

### Exemples

Exemple #1 Récupération du décalage horaire par défaut

    <?php
    date_default_timezone_set('Europe/London');

    if (date_default_timezone_get()) {
        echo 'date_default_timezone_set : ' . date_default_timezone_get() . "\n";
    }

    if (ini_get('date.timezone')) {
        echo 'date.timezone : ' . ini_get('date.timezone');
    }

Résultat de l'exemple ci-dessus est similaire à :

    date_default_timezone_set : Europe/London
    date.timezone : Europe/London

Exemple #2 Récupération de l'abréviation d'un décalage horaire

    <?php
    date_default_timezone_set('America/Los_Angeles');
    echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');

L'exemple ci-dessus va afficher :

    America/Los_Angeles => America/Los_Angeles => PST

### Voir aussi

- date_default_timezone_set() - Définit le décalage horaire par défaut de toutes les fonctions date/heure
- Liste des Fuseaux Horaires Supportés

# date_default_timezone_set

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_set — Définit le décalage horaire par défaut de toutes les fonctions date/heure

### Description

function date_default_timezone_set(string `$timezoneId`): bool

La fonction date_default_timezone_set() définit le décalage horaire par défaut utilisé par toutes les fonctions date/heure.

Au lieu d'utiliser cette fonction pour définir le décalage horaire par défaut dans le script, il est également possible d'utiliser la configuration INI date.timezone.

### Liste de paramètres

`timezoneId`

  L'identifiant de décalage horaire, comme `UTC`, `Africa/Lagos`, `Asia/Hong_Kong`, ou `Europe/Lisbon`. La liste des identifiants valides est disponible dans le Liste des Fuseaux Horaires Supportés.

### Valeurs de retour

Cette fonction retourne `false` si `timezoneId` n'est pas valide, `true` sinon.

### Exemples

Exemple #1 Récupération du décalage horaire par défaut

    <?php
    date_default_timezone_set('America/Los_Angeles');

    $script_tz = date_default_timezone_get();
    $ini_tz = ini_get('date.timezone');

    if (strcmp($script_tz, $ini_tz)){
        echo 'Le décalage horaire du script diffère du décalage horaire défini dans le fichier ini.';
    } else {
        echo 'Le décalage horaire du script est équivalent à celui défini dans le fichier ini.';
    }

### Voir aussi

- date_default_timezone_get() - Récupère le décalage horaire par défaut utilisé par toutes les fonctions date/heure d'un script
- Liste des Fuseaux Horaires Supportés

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_diff — Alias de DateTime::diff()

### Description

Cette fonction est un alias de : DateTime::diff()

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_format — Alias de DateTime::format()

### Description

Cette fonction est un alias de : DateTime::format()

# date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_get_last_errors — Alias de DateTimeImmutable::getLastErrors()

### Description

Cette fonction est un alias de : DateTimeImmutable::getLastErrors()

# date_interval_create_from_date_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_create_from_date_string — Alias de DateInterval::createFromDateString()

### Description

Cette fonction est un alias de : DateInterval::createFromDateString()

# date_interval_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_format — Alias de DateInterval::format()

### Description

Cette fonction est un alias de : DateInterval::format()

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_isodate_set — Alias de DateTime::setISODate()

### Description

Cette fonction est un alias de : DateTime::setISODate()

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_modify — Alias de DateTime::modify()

### Description

Cette fonction est un alias de : DateTime::modify()

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_offset_get — Alias de DateTime::getOffset()

### Description

Cette fonction est un alias de : DateTime::getOffset()

# date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — Retourne un tableau associatif avec des informations détaillées sur une date/moment donnée

### Description

function date_parse(string `$datetime`): array

date_parse() analyse la chaîne `datetime` donnée selon les mêmes règles que strtotime() et DateTimeImmutable::__construct(). Au lieu de renvoyer un horodatage Unix (avec strtotime()) ou un objet DateTimeImmutable (avec DateTimeImmutable::__construct()), il renvoie un tableau associatif avec les informations qu'il pourrait détecter dans la chaîne `datetime` donnée.

Si aucune information sur un certain groupe d'éléments ne peut être trouvée, ces éléments du tableau seront définis sur `false` ou seront manquants. Si nécessaire pour construire un horodatage ou un objet DateTimeImmutable à partir de la même chaîne `datetime`, plusieurs champs peuvent être définis sur une valeur non-`false`. Voir les exemples ci-dessous pour les cas où cela se produit.

### Liste de paramètres

`datetime`

  Date/moment dans un format accepté par DateTimeImmutable::__construct().

### Valeurs de retour

Retourne un tableau contenant des informations sur la date/moment analysée.

Le tableau retourné a des clés pour `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction`, et `is_localtime`.

Si `is_localtime` est présent, alors `zone_type` indique le type de fuseau horaire. Pour le type `1` (décalage UTC) les champs `zone` et `is_dst` sont ajoutés. Pour le type `2` (abréviation) les champs `tz_abbr` et `is_dst` sont ajoutés. Pour le type `3` (identifiant de fuseau horaire) les champs `tz_abbr` et `tz_id` sont ajoutés.

Si des éléments de temps relatifs sont présents dans la chaîne `datetime`, tels que `+3 days`, le tableau retourné inclut un tableau imbriqué avec la clé `relative`. Ce tableau contient alors les clés `year`, `month`, `day`, `hour`, `minute`, `second`, et si nécessaire `weekday`, et `weekdays`, selon la chaîne qui a été passée.

Le tableau inclut les champs `warning_count` et `warnings`. Le premier indique le nombre d'avertissements. Les clés du tableau `warnings` indiquent la position dans le paramètre `datetime` où l'avertissement s'est produit, avec la valeur de chaîne décrivant l'avertissement lui-même. Un exemple ci-dessous montre un tel avertissement.

Le tableau inclut aussi les champs `error_count` et `errors`. Le premier indique le nombre d'erreurs. Les clés du tableau `errors` indiquent la position dans le paramètre `datetime` où l'erreur s'est produite, avec la valeur de chaîne décrivant l'avertissement lui-même. Un exemple ci-dessous montre un tel avertissement.

Avertissement

Le nombre d'éléments de tableau dans les tableaux `warnings` et `errors` peut être inférieur à `warning_count` ou `error_count` s'ils se sont produits à la même position.

### Erreurs / Exceptions

Dans le cas où la fonction retourne une erreur, l'élément `"errors"` contiendra les messages d'erreur.

### Historique

Version | Description
--- | ---
7.2.0 | L'élément `zone` du tableau retourné représente maintenant des secondes au lieu des minutes, et son signe est inversé. Par exemple, `-120` est maintenant `7200`.

### Exemples

Exemple #1 date_parse() avec une chaîne `datetime` complète

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5"));

L'exemple ci-dessus va afficher :

    array(12) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Les éléments de fuseau horaire n'apparaissent que s'ils sont inclus dans la chaîne `datetime` donnée. Dans ce cas, il y aura toujours un élément `zone_type` et quelques autres en fonction de sa valeur.

Exemple #2 date_parse() avec des informations abrégées sur le fuseau horaire

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));

L'exemple ci-dessus va afficher :

    array(16) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(2)
      ["zone"]=>
      int(0)
      ["is_dst"]=>
      bool(true)
      ["tz_abbr"]=>
      string(3) "BST"
    }

Exemple #3 date_parse() avec des informations d'identifiant de fuseau horaire

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));

L'exemple ci-dessus va afficher :

    array(14) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(3)
      ["tz_id"]=>
      string(13) "Europe/London"
    }

Si une chaîne `datetime` plus minimale est analysée, moins d'informations sont disponibles. Dans cet exemple, toutes les parties temporelles sont renvoyées comme `false`.

Exemple #4 date_parse() avec une chaîne minimale

    <?php
    var_dump(date_parse("June 2nd, 2022"));

L'exemple ci-dessus va afficher :

    array(12) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      bool(false)
      ["minute"]=>
      bool(false)
      ["second"]=>
      bool(false)
      ["fraction"]=>
      bool(false)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Les formats relatifs n'influencent pas les valeurs analysées depuis des formats absolus, mais sont analysés dans l'élément "relative".

Exemple #5 Exemple avec date_parse() et des formats relatifs

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));

L'exemple ci-dessus va afficher :

    array(13) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(6) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(7)
        ["hour"]=>
        int(1)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
      }
    }

Certaines strophes, telles que `Thursday` (jeudi) définiront la partie heure de la chaîne sur `0`. Si `Thursday` (jeudi) est passé à DateTimeImmutable::__construct() l'heure, la minute, la seconde et la fraction seront également définies sur `0`. Dans l'exemple ci-dessous, l'élément année est cependant laissé à `false`.

Exemple #6 date_parse() avec des effets secondaires

    <?php
    var_dump(date_parse("Thursday, June 2nd"));

L'exemple ci-dessus va afficher :

    array(13) {
      ["year"]=>
      bool(false)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(0)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(7) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["weekday"]=>
        int(4)
      }
    }

### Voir aussi

- date_parse_from_format() - Récupère les informations d'une date donnée suivant un format spécifique pour analyser le paramètre `datetime` avec un format spécifique
- checkdate() - Valide une date grégorienne pour une validation de date Grégorienne
- getdate() - Retourne la date/heure

# date_parse_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_parse_from_format — Récupère les informations d'une date donnée suivant un format spécifique

### Description

function date_parse_from_format(string `$format`, string `$datetime`): array

Retourne un tableau associatif contenant des informations détaillées sur une date/moment donnée.

### Liste de paramètres

`format`

  Documentation sur l'utilisation du `format`, se référer à la documentation de DateTimeImmutable::createFromFormat(). Les mêmes règles s'appliquent.

`datetime`

  Chaîne représentant la date/moment.

### Valeurs de retour

Retourne un tableau associatif avec des informations détaillées sur la date/moment donnée.

Le tableau retourné a des clés pour `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction`, et `is_localtime`.

Si `is_localtime` est présent, alors `zone_type` indique le type de fuseau horaire. Pour le type `1` (décalage UTC) les champs `zone` et `is_dst` sont ajoutés. Pour le type `2` (abréviation) les champs `tz_abbr` et `is_dst` sont ajoutés. Pour le type `3` (identifiant de fuseau horaire) les champs `tz_abbr` et `tz_id` sont ajoutés.

Le tableau inclut les champs `warning_count` et `warnings`. Le premier indique le nombre d'avertissements. Les clés du tableau `warnings` indiquent la position dans le paramètre `datetime` où l'avertissement s'est produit, avec la valeur de chaîne décrivant l'avertissement lui-même. Un exemple ci-dessous montre un tel avertissement.

Le tableau inclut aussi les champs `error_count` et `errors`. Le premier indique le nombre d'erreurs. Les clés du tableau `errors` indiquent la position dans le paramètre `datetime` où l'erreur s'est produite, avec la valeur de chaîne décrivant l'erreur elle-même. Un exemple ci-dessous montre une telle erreur.

Avertissement

Le nombre d'éléments de tableau dans les tableaux `warnings` et `errors` peut être inférieur à `warning_count` ou `error_count` s'ils se sont produits à la même position.

### Erreurs / Exceptions

Cette fonction lance une ValueError lorsque le `datetime` contient des octets NULL.

### Historique

Version | Description
--- | ---
8.0.21, 8.1.8, 8.2.0 | Lance désormais une ValueError lorsque des octets NULL sont passés dans `datetime`, ce qui était auparavant ignoré silencieusement.
7.2.0 | L'élément `zone` du tableau retourné représente des secondes au lieu de minutes maintenant, et son signe est inversé. Par exemple `-120` est maintenant égal à `7200`.

### Exemples

Exemple #1 Exemple avec date_parse_from_format()

    <?php
    $date = "6.1.2009 13:00+01:00";
    print_r(date_parse_from_format("j.n.Y H:iP", $date));

L'exemple ci-dessus va afficher :

    Array
    (
        [year] => 2009
        [month] => 1
        [day] => 6
        [hour] => 13
        [minute] => 0
        [second] => 0
        [fraction] => 0
        [warning_count] => 0
        [warnings] => Array
            (
            )

        [error_count] => 0
        [errors] => Array
            (
            )

        [is_localtime] => 1
        [zone_type] => 1
        [zone] => 3600
        [is_dst] =>
    )

Exemple #2 Exemple de date_parse_from_format() avec des warnings (avertissements)

    <?php
    $date = "26 August 2022 22:30 pm";
    $parsed = date_parse_from_format("j F Y G:i a", $date);

    echo "Warnings count: ", $parsed['warning_count'], "\n";
    foreach ($parsed['warnings'] as $position => $message) {
        echo "\tOn position {$position}: {$message}\n";
    }

L'exemple ci-dessus va afficher :

    Warnings count: 1
    	On position 23: The parsed time was invalid

Exemple #3 Exemple de date_parse_from_format() avec des errors (erreurs)

    <?php
    $date = "26 August 2022 CEST";
    $parsed = date_parse_from_format("j F Y H:i", $date);

    echo "Errors count: ", $parsed['error_count'], "\n";
    foreach ($parsed['errors'] as $position => $message) {
        echo "\tOn position {$position}: {$message}\n";
    }

L'exemple ci-dessus va afficher :

    Errors count: 3
    	On position 15: A two digit hour could not be found
    	On position 19: Not enough data available to satisfy format

### Voir aussi

- DateTimeImmutable::createFromFormat() - Analyse une heure au format texte selon le format spécifié.
- checkdate() - Valide une date grégorienne

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_sub — Alias de DateTime::sub()

### Description

Cette fonction est un alias de : DateTime::sub()

### Voir aussi

- DateTimeImmutable::sub() - Soustrait un nombre de jours, mois, années, heures et secondes
- DateTime::sub() - Soustrait une durée à un objet DateTime

# date_sun_info

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

date_sun_info — Retourne un tableau avec les informations sur le lever/coucher du soleil ainsi que le début et la fin de l'aube

### Description

function date_sun_info(int `$timestamp`, float `$latitude`, float `$longitude`): array

### Liste de paramètres

`timestamp`

  Horodatage Unix.

`latitude`

  Latitude, en degrés.

`longitude`

  Longitude, en degrés.

### Valeurs de retour

Retourne un tableau dont la structure du tableau est détaillée dans la liste suivante :

`sunrise`
  L'horodatage du lever du soleil (angle de zénith = 90°35').
`sunset`
  L'horodatage du coucher du soleil (angle de zénith = 90°35').
`transit`
  L'horodatage où le soleil est à son zénith, c'est-à-dire a atteint son point le plus haut.
`civil_twilight_begin`
  Le début de l'aube civile (angle de zénith = 96°). Elle se termine au `sunrise`.
`civil_twilight_end`
  La fin du crépuscule civil (angle de zénith = 96°). Elle commence au `sunset`.
`nautical_twilight_begin`
  Le début de l'aube nautique (angle de zénith = 102°). Elle se termine au `civil_twilight_begin`.
`nautical_twilight_end`
  La fin du crépuscule nautique (angle de zénith = 102°). Elle commence au `civil_twilight_end`.
`astronomical_twilight_begin`
  Le début de l'aube astronomique (angle de zénith = 108°). Elle se termine au `nautical_twilight_begin`.
`astronomical_twilight_end`
  La fin du crépuscule astronomique (angle de zénith = 108°). Elle commence au `nautical_twilight_end`.

Les valeurs des éléments du tableau sont soit des horodatages UNIX, `false`, si le soleil est sous le zénith respectif pour la journée entière, ou `true`, si le soleil est au-dessus du zénith respectif pour toute la journée.

### Historique

Version | Description
--- | ---
7.2.0 | Le calcul a été corrigé en tenant compte du minuit local au lieu du midi local, ce qui modifie légèrement les résultats.

### Exemples

Exemple #1 Exemple avec date_sun_info()

    <?php
    $sun_info = date_sun_info(strtotime("2006-12-12"), 31.7667, 35.2333);
    foreach ($sun_info as $key => $val) {
      echo "$key: " . date("H:i:s", $val) . "\n";
    }

L'exemple ci-dessus va afficher :

    sunrise: 05:52:11
    sunset: 15:41:21
    transit: 10:46:46
    civil_twilight_begin: 05:24:08
    civil_twilight_end: 16:09:24
    nautical_twilight_begin: 04:52:25
    nautical_twilight_end: 16:41:06
    astronomical_twilight_begin: 04:21:32
    astronomical_twilight_end: 17:12:00

Exemple #2 Nuit polaire avec un peu de traitement

    <?php
    $tz = new \DateTimeZone('America/Anchorage');

    $si = date_sun_info(strtotime("2022-12-21"), 70.21, -148.51);
    foreach ($si as $key => $value) {
        echo
            match ($value) {
                true => 'always',
                false => 'never',
                default => date_create("@{$value}")->setTimeZone($tz)->format( 'H:i:s T' ),
            },
            ": {$key}",
            "\n";
    }

L'exemple ci-dessus va afficher :

    never: sunrise
    never: sunset
    12:52:18 AKST: transit
    10:53:19 AKST: civil_twilight_begin
    14:51:17 AKST: civil_twilight_end
    09:01:47 AKST: nautical_twilight_begin
    16:42:48 AKST: nautical_twilight_end
    07:40:47 AKST: astronomical_twilight_begin
    18:03:49 AKST: astronomical_twilight_end

Exemple #3 Soleil de minuit (Tromsø, Norvège)

    <?php
    $si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
    print_r($si);

L'exemple ci-dessus va afficher :

    Array
    (
        [sunrise] => 1
        [sunset] => 1
        [transit] => 1656240426
        [civil_twilight_begin] => 1
        [civil_twilight_end] => 1
        [nautical_twilight_begin] => 1
        [nautical_twilight_end] => 1
        [astronomical_twilight_begin] => 1
        [astronomical_twilight_end] => 1
    )

Exemple #4 Calcul de la durée du jour (Kyiv)

    <?php
    $si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
    $diff = $si['sunset'] - $si['sunrise'];
    echo "Durée du jour: ",
        floor($diff / 3600), "h ",
        floor(($diff % 3600) / 60), "s\n";

L'exemple ci-dessus va afficher :

    Durée du jour: 13h 56s

# date_sunrise

(PHP 5, PHP 7, PHP 8)

date_sunrise — Retourne l'heure de lever du soleil pour un jour et un endroit donnés

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Dépendre de cette fonction est fortement déconseillé. L'utilisation de date_sun_info() est encouragée à la place.

### Description

#[\Deprecated]
function date_sunrise(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

date_sunrise() retourne l'heure de lever du soleil pour un jour (spécifié par le paramètre `timestamp`) et un endroit donnés.

### Liste de paramètres

`timestamp`

  Le timestamp Unix du jour pour lequel l'heure de lever du soleil est donnée.

`returnFormat`

  Constantes pour le paramètre `returnFormat`
  Constante | Description | Exemple
  --- | --- | ---
  SUNFUNCS_RET_STRING | Retourne le résultat en tant que chaîne de caractères | 16:46
  SUNFUNCS_RET_DOUBLE | Retourne le résultat en tant que nombre décimal | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Retourne le résultat en tant qu'entier (timestamp) | 1095034606

`latitude`

  Par défaut, c'est le Nord. Passez une valeur négative pour le Sud. Voir aussi date.default_latitude.

`longitude`

  Par défaut, c'est l'Est. Passez une valeur négative pour l'Ouest. Voir aussi date.default_longitude.

`zenith`

  `zenith` est l'angle entre le centre du soleil et la ligne perpendiculaire à la surface de la terre. Par défaut date.sunrise_zenith

  Valeurs courantes de l'angle `zenith`
  Angle | Description
  --- | ---
  90°50' | Lever du soleil : le point où le soleil devient visible.
  96° | Crépuscule civil : conventionnellement utilisé pour signifier le début de l'aube.
  102° | Crépuscule nautique : le point où l'horizon commence à être visible en mer.
  108° | Crépuscule astronomique : le point où le soleil commence à être la source de toute illumination.

`utcOffset`

  Spécifié en heures. Le `utcOffset` est ignoré si `returnFormat` est `SUNFUNCS_RET_TIMESTAMP`.

### Valeurs de retour

Retourne l'heure de lever du soleil dans le `returnFormat` spécifié en cas de succès ou `false` si une erreur survient. Une raison possible de l'échec est que le soleil ne se lève pas du tout, ce qui arrive à l'intérieur des cercles polaires pendant une partie de l'année.

### Erreurs / Exceptions

Chaque appel à une fonction date/heure générera un diagnostic de type `E_WARNING` si le fuseau horaire n'est pas valide. Voir aussi date_default_timezone_set()

### Historique

Version | Description
--- | ---
8.1.0 | Cette fonction a été rendue obsolète en faveur de date_sun_info().
8.0.0 | `latitude`, `longitude`, `zenith` et `utcOffset` sont désormais nullable.

### Exemples

Exemple #1 Exemple avec date_sunrise()

    <?php

    /* Calcule l'heure du lever du soleil pour Lisbonne, Portugal
    Latitude: 38.4 North
    Longitude: 9 West
    Zenith ~= 90
    offset: +1 GMT
    */

    echo date("D M d Y"). ', sunrise time : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

Résultat de l'exemple ci-dessus est similaire à :

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, sunrise time : 08:54

Exemple #2 Pas de lever de soleil

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunrise($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

L'exemple ci-dessus va afficher :

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Voir aussi

- date_sun_info() - Retourne un tableau avec les informations sur le lever/coucher du soleil ainsi que le début et la fin de l'aube

# date_sunset

(PHP 5, PHP 7, PHP 8)

date_sunset — Retourne l'heure de coucher du soleil pour un jour et un endroit donnés

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Dépendre de cette fonction est fortement déconseillé. L'utilisation de date_sun_info() est encouragée à la place.

### Description

#[\Deprecated]
function date_sunset(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

La fonction date_sunset() retourne l'heure de coucher du soleil pour un jour (spécifié en tant que `timestamp` Unix) et un endroit donnés.

### Liste de paramètres

`timestamp`

  Le `timestamp` Unix du jour pour lequel l'heure du coucher du soleil est donnée.

`returnFormat`

  Constantes pour le paramètre `returnFormat`
  Constante | Description | Exemple
  --- | --- | ---
  SUNFUNCS_RET_STRING | Retourne le résultat sous la forme d'une chaîne de caractères | 16:46
  SUNFUNCS_RET_DOUBLE | Retourne le résultat sous la forme d'un nombre décimal | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Retourne le résultat sous la forme d'un entier (timestamp) | 1095034606

`latitude`

  Par défaut, c'est le Nord. Une valeur négative doit être passée pour le Sud. Voir aussi date.default_latitude.

`longitude`

  Par défaut, c'est l'Est. Une valeur négative doit être passée pour l'Ouest. Voir aussi date.default_longitude.

`zenith`

  `zenith` est l'angle entre le centre du soleil et la ligne perpendiculaire à la surface de la terre. Par défaut date.sunset_zenith

  Valeurs communes d'angle `zenith`
  Angle | Description
  --- | ---
  90°50' | Coucher du soleil : le point où le soleil devient invisible.
  96° | Crépuscule civil : conventionnellement utilisé pour signifier la fin du crépuscule.
  102° | Crépuscule nautique : le point où l'horizon cesse d'être visible en mer.
  108° | Crépuscule astronomique : le point où le soleil cesse d'être la source de toute illumination.

`utcOffset`

  Spécifié en heures. Le `utcOffset` est ignoré, si `returnFormat` est `SUNFUNCS_RET_TIMESTAMP`.

### Valeurs de retour

Retourne l'heure de coucher du soleil dans le `returnFormat` spécifié ou `false` si une erreur survient. Une raison possible de l'échec est que le soleil ne se couche pas, ce qui se passe à l'intérieur des cercles polaires pour une partie de l'année.

### Erreurs / Exceptions

Chaque appel à une fonction date/heure générera un diagnostic de type `E_WARNING` si le fuseau horaire n'est pas valide. Voir aussi date_default_timezone_set()

### Historique

Version | Description
--- | ---
8.1.0 | Cette fonction a été rendue obsolète en faveur de date_sun_info().
8.0.0 | `latitude`, `longitude`, `zenith` et `utcOffset` sont désormais nullable.

### Exemples

Exemple #1 Exemple avec date_sunset()

    <?php

         /* Calcule l'heure du coucher du soleil pour Lisbonne, Portugal
    Latitude: 38.4 North
    Longitude: 9 West
    Zenith ~= 90
    offset:1 GMT
    */

    echo date("D M d Y"). ', sunset time : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

Résultat de l'exemple ci-dessus est similaire à :

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, sunset time : 18:13

Exemple #2 Pas de coucher du soleil

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

L'exemple ci-dessus va afficher :

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Voir aussi

- date_sun_info() - Retourne un tableau avec les informations sur le lever/coucher du soleil ainsi que le début et la fin de l'aube

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_time_set — Alias de DateTime::setTime()

### Description

Cette fonction est un alias de : DateTime::setTime()

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_get — Alias de DateTime::getTimestamp()

### Description

Cette fonction est un alias de : DateTime::getTimestamp()

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_set — Alias de DateTime::setTimestamp()

### Description

Cette fonction est un alias de : DateTime::setTimestamp()

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_get — Alias de DateTime::getTimezone()

### Description

Cette fonction est un alias de : DateTime::getTimezone()

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_set — Alias de DateTime::setTimezone()

### Description

Cette fonction est un alias de : DateTime::setTimezone()

# getdate

(PHP 4, PHP 5, PHP 7, PHP 8)

getdate — Retourne la date/heure

### Description

function getdate(?int `$timestamp` = `null`): array

Retourne un array associatif contenant les informations de date et d'heure du `timestamp`, ou la date/heure courante locale si `timestamp` est omis ou `null`.

### Liste de paramètres

`timestamp`
  Le paramètre optionnel `timestamp` est un timestamp Unix de type entier qui vaut par défaut l'heure courante locale si `timestamp` est omis ou `null`. En d'autres termes, il vaut par défaut la valeur de la fonction time().

### Valeurs de retour

Retourne un tableau associatif contenant les informations de date et d'heure du timestamp `timestamp`. Les éléments du tableau associatif retourné sont les suivants :

Nom des clés du tableau associatif retourné
Clé | Description | Exemple de valeur retournée
--- | --- | ---
`"seconds"` | Représentation numérique des secondes | `0` à `59`
`"minutes"` | Représentation numérique des minutes | `0` à `59`
`"hours"` | Représentation numérique des heures | `0` à `23`
`"mday"` | Représentation numérique du jour du mois courant | `1` à `31`
`"wday"` | Représentation numérique du jour de la semaine courante | `0` (pour dimanche) à `6` (pour samedi)
`"mon"` | Représentation numérique du mois | `1` à `12`
`"year"` | Année, sur 4 chiffres | Exemples : `1999` ou `2003`
`"yday"` | Représentation numérique du jour de l'année | `0` à `365`
`"weekday"` | Version texte du jour de la semaine | `Sunday` à `Saturday`
`"month"` | Version texte du mois, comme `January` ou `March` | `January` à `December`
`0` | Nombre de secondes depuis l'époque Unix, similaire à la valeur retournée par la fonction time() et utilisée par date(). | Dépend du système, typiquement de `-2147483648` à `2147483647`.

### Historique

Version | Description
--- | ---
8.0.0 | `timestamp` est désormais nullable.

### Exemples

Exemple #1 Exemple avec getdate()

    <?php
    $today = getdate();
    print_r($today);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [seconds] => 40
        [minutes] => 58
        [hours] => 21
        [mday] => 17
        [wday] => 2
        [mon] => 6
        [year] => 2003
        [yday] => 167
        [weekday] => Tuesday
        [month] => June
        [0] => 1055901520
    )

### Voir aussi

- date() - Formate un horodatage Unix
- idate() - Formate une partie de l'heure/date locale en tant qu'entier
- localtime() - Récupère l'heure locale
- time() - Retourne l'horodatage UNIX actuel
- setlocale() - Modifie les informations de localisation

# gettimeofday

(PHP 4, PHP 5, PHP 7, PHP 8)

gettimeofday — Retourne l'heure actuelle

### Description

function gettimeofday(bool `$as_float` = `false`): array|float

C'est une interface avec gettimeofday(2). Elle retourne un tableau associatif qui contient les informations retournées par le système.

### Liste de paramètres

`as_float`

  Lorsque défini à `true`, un nombre décimal est retourné à la place d'un tableau.

### Valeurs de retour

Par défaut, un tableau est retourné. Si le paramètre `as_float` est défini, alors un nombre décimal sera retourné.

Clés du tableau :

- "sec" : secondes depuis l'époque Unix
- "usec" : microsecondes
- "minuteswest" : minutes de décalage par rapport à Greenwich, vers l'Ouest.
- "dsttime" : type de correction dst

### Exemples

Exemple #1 Exemple avec gettimeofday()

    <?php
    print_r(gettimeofday());

    echo gettimeofday(true);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
       [sec] => 1073504408
       [usec] => 238215
       [minuteswest] => 0
       [dsttime] => 1
    )
    1073504408.23910

# gmdate

(PHP 4, PHP 5, PHP 7, PHP 8)

gmdate — Formate une date/heure GMT/TUC

### Description

function gmdate(string `$format`, ?int `$timestamp` = `null`): string

gmdate() est identique à la fonction date(), hormis le fait que le temps retourné est GMT (`Greenwich Mean Time`).

### Liste de paramètres

`format`

  Le format de la date en sortie. Voir les options de formatage pour la fonction date().

`timestamp`
  Le paramètre optionnel `timestamp` est un timestamp Unix de type entier qui vaut par défaut l'heure courante locale si `timestamp` est omis ou `null`. En d'autres termes, il vaut par défaut la valeur de la fonction time().

### Valeurs de retour

Retourne une date formatée.

### Historique

Version | Description
--- | ---
8.0.0 | `timestamp` est désormais nullable.

### Exemples

Exemple #1 Exemple avec gmdate()

    <?php
    date_default_timezone_set("Europe/Helsinki");

    echo date("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo gmdate("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998));

L'exemple ci-dessus va afficher :

    Jan 01 1998 00:00:00 Europe/Helsinki
    Dec 31 1997 22:00:00 UTC

### Voir aussi

- DateTimeImmutable::__construct() - Retourne un nouvel objet DateTimeImmutable
- DateTimeInterface::format() - Retourne une date formatée suivant le format fourni
- date() - Formate un horodatage Unix
- mktime() - Retourne l'horodatage UNIX d'une date
- gmmktime() - Retourne le timestamp UNIX d'une date GMT
- IntlDateFormatter::format() - Formate la date et l'heure sous forme de chaîne

# gmmktime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmmktime — Retourne le timestamp UNIX d'une date GMT

### Description

function gmmktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

Identique à la fonction mktime() excepté le fait que les paramètres optionnels passés sont GMT. gmmktime() utilise en interne la fonction mktime(), donc, seuls les temps valides dans la zone locale dérivée peuvent être utilisés.

Comme mktime(), les arguments restants peuvent être ignorés. Ils prendront alors leurs valeurs GMT actuelles.

Appeler gmmktime() sans arguments n'est pas supporté. Cela aura pour résultat de lancer une ArgumentCountError. time() peut être utilisé pour récupérer l'horodatage courant.

### Liste de paramètres

`hour`

  Le nombre d'heures depuis le début de la journée fixée par les paramètres `month`, `day` et `year`. Les valeurs négatives font référence aux heures avant minuit du jour en question. Les valeurs supérieures à 23 font référence aux heures associées pour le(s) jour(s) suivant(s).

`minute`

  Le nombre de minutes depuis le début de l'heure `hour`. Les valeurs négatives font référence aux minutes de l'heure précédente. Les valeurs supérieures à 59 font référence aux minutes associées pour l'(les) heure(s) suivante(s).

`second`

  Le nombre de secondes depuis le début de la minute `minute`. Les valeurs négatives font référence aux secondes de la minute précédente. Les valeurs supérieures à 59 font référence aux secondes associées à la(les) minute(s) suivante(s).

`month`

  Le nombre de mois depuis la fin de l'année précédente. Les valeurs comprises entre 1 et 12 font référence aux mois du calendrier normal de l'année en question. Les valeurs inférieures à 1 (y compris les valeurs négatives) font référence aux mois de l'année précédente dans l'ordre inverse, aussi, 0 correspond à décembre, -1 à novembre, etc. Les valeurs supérieures à 12 font référence au mois correspondant dans l'(les) année(s) suivante(s).

`day`

  Le nombre de jours depuis la fin du mois précédent. Les valeurs comprises entre 1 et 28, 29, 30, 31 (suivant le mois) font référence aux jours normaux dans le mois courant. Les valeurs inférieures à 1 (y compris les valeurs négatives) font référence aux jours du mois précédent, aussi, 0 correspond au dernier jour du mois précédent, -1, le jour d'avant, etc. Les valeurs supérieures au nombre de jours du mois courant font référence aux jours correspondants du(des) mois suivant(s).

`year`

  L'année

### Valeurs de retour

Retourne un horodatage Unix, sous la forme d'un entier, ou `false` si l'horodatage ne rentre pas dans un entier PHP.

### Historique

Version | Description
--- | ---
8.0.0 | `hour` n'est plus optionnel. Pour obtenir un horodatage unix, il faudra utiliser la fonction time().
8.0.0 | `minute`, `second`, `month`, `day` et `year` sont désormais nullable.

### Exemples

Exemple #1 Exemple avec gmmktime()

    <?php
    date_default_timezone_set("Indian/Maldives");

    echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));

L'exemple ci-dessus va afficher :

    July 1, 2000 is on a Saturday

### Voir aussi

- La classe DateTimeImmutable
- mktime() - Retourne l'horodatage UNIX d'une date
- date() - Formate un horodatage Unix
- time() - Retourne l'horodatage UNIX actuel

# gmstrftime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmstrftime — Formate une date/heure GMT/TUC en fonction de la configuration locale

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Il est fortement recommandé de les éviter.

Les alternatives à cette fonction incluent :

- gmdate()
- IntlDateFormatter::format()

### Description

#[\Deprecated]
function gmstrftime(string `$format`, ?int `$timestamp` = null): string|false

gmstrftime() se comporte exactement comme strftime() hormis le fait que l'heure utilisée est celle de Greenwich (`Greenwich Mean Time`, GMT). Par exemple, lorsque la zone `Eastern Standard Time` (est des USA) est GMT -0500, la première ligne de l'exemple ci-dessous affiche `"Dec 31 1998 20:00:00"`, tandis que la seconde affiche `"Jan 01 1999 01:00:00"`.

Avertissement

Cette fonction dépend des informations locales du système d'exploitation, qui peuvent être incohérentes ou ne pas être disponibles du tout. Utiliser plutôt la méthode IntlDateFormatter::format().

### Liste de paramètres

`format`

  Voir la description de la fonction strftime().

`timestamp`
  Le paramètre optionnel `timestamp` est un timestamp Unix de type entier qui vaut par défaut l'heure courante locale si `timestamp` est omis ou `null`. En d'autres termes, il vaut par défaut la valeur de la fonction time().

### Valeurs de retour

Retourne une chaîne de caractères formatée suivant la chaîne de format donnée, en utilisant le paramètre `timestamp` donné ou l'heure locale courante si aucun horodatage n'est fourni. Les noms des mois, des jours de la semaine et des autres chaînes dépendant d'une localisation donnée, respectent la localisation courante définie par la fonction setlocale(). En cas d'échec, `false` est retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `timestamp` est désormais nullable.

### Exemples

Exemple #1 Exemple avec gmstrftime()

    <?php

    setlocale(LC_TIME, 'es_ES.UTF-8');
    date_default_timezone_set('EST');

    echo strftime("%B %d %Y %H:%M:%S",   mktime(20, 0, 0, 12, 31, 98)) . "\n";
    echo gmstrftime("%B %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98));

L'exemple ci-dessus va afficher :

    Deprecated: Function strftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 6
    diciembre 31 1998 20:00:00

    Deprecated: Function gmstrftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 7
    enero 01 1999 01:00:00

### Voir aussi

- IntlDateFormatter::format() - Formate la date et l'heure sous forme de chaîne
- DateTimeInterface::format() - Retourne une date formatée suivant le format fourni
- strftime() - Formate une date/heure locale avec la configuration locale

# idate

(PHP 5, PHP 7, PHP 8)

idate — Formate une partie de l'heure/date locale en tant qu'entier

### Description

function idate(string `$format`, ?int `$timestamp` = `null`): int|false

idate() retourne un nombre formaté avec le format `format` et représentant le timestamp `timestamp` ou l'heure courante si `timestamp` est omis. En d'autres termes, le paramètre `timestamp` est optionnel et la valeur par défaut est la valeur retournée par la fonction time().

À l'inverse de la fonction date(), idate() accepte juste un caractère comme paramètre `format`.

### Liste de paramètres

`format`

  Les caractères suivants sont reconnus dans la chaîne de caractères du paramètre `format`
  Caractères de `format` | Description
  --- | ---
  `B` | Temps Internet Swatch Beat
  `d` | Le jour du mois
  `h` | Heure (format 12 heures)
  `H` | Heure (format 24 heures)
  `i` | Minutes
  `I` (i, en majuscule) | Retourne `1` si l'heure d'été est activée, `0` sinon
  `L` (l, en majuscule) | Retourne `1` pour une année bissextile, `0` sinon
  `m` | Numéro du mois
  `N` | Jour de la semaine ISO-8601 (`1` pour le lundi à `7` pour le dimanche)
  `o` | Année ISO-8601 (4 chiffres)
  `s` | Secondes
  `t` | Nombre de jours dans le mois courant
  `U` | Secondes depuis l'époque Unix - 1 janvier 1970 00:00:00 UTC - c'est la même chose que la fonction time()
  `w` | Jour de la semaine (`0` pour dimanche)
  `W` | Le numéro de semaine de l'année ; selon l'ISO-8601, les semaines débutent le lundi
  `y` | Année sur 1 ou 2 chiffres, voir la note plus bas
  `Y` | Année sur 4 chiffres
  `z` | Jour de l'année
  `Z` | Décalage horaire, en secondes

`timestamp`
  Le paramètre optionnel `timestamp` est un timestamp Unix de type entier qui vaut par défaut l'heure courante locale si `timestamp` est omis ou `null`. En d'autres termes, il vaut par défaut la valeur de la fonction time().

### Valeurs de retour

Retourne un int en cas de succès, ou `false` si une erreur survient.

Sachant que idate() retourne toujours un entier et qu'il ne peut commencer par `0`, idate() peut retourner moins de chiffres que ce dont on pourrait espérer. Voir l'exemple ci-dessous.

### Erreurs / Exceptions

Chaque appel à une fonction date/heure générera un diagnostic de type `E_WARNING` si le fuseau horaire n'est pas valide. Voir aussi date_default_timezone_set()

### Historique

Version | Description
--- | ---
8.2.0 | Ajoute les caractères de format `N` (jour de la semaine ISO-8601) et `o` (année ISO-8601).
8.0.0 | `timestamp` est désormais nullable.

### Exemples

Exemple #1 Exemple avec idate()

    <?php
    $timestamp = strtotime('1st January 2004'); // 1072915200

    // ceci affiche l'année sur deux chiffres
    // néanmoins, vu que ce chiffre va commencer par "0",
    // seul "4" sera affiché
    echo idate('y', $timestamp) . "\n";

    $timestamp = strtotime('1st January 2024'); // 1704067200
    echo idate('y', $timestamp);

L'exemple ci-dessus va afficher :

    4
    24

### Voir aussi

- DateTimeInterface::format() - Retourne une date formatée suivant le format fourni
- date() - Formate un horodatage Unix
- getdate() - Retourne la date/heure
- time() - Retourne l'horodatage UNIX actuel

# localtime

(PHP 4, PHP 5, PHP 7, PHP 8)

localtime — Récupère l'heure locale

### Description

function localtime(?int `$timestamp` = `null`, bool `$associative` = `false`): array

localtime() retourne un tableau identique à la structure retournée par la fonction C localtime.

### Liste de paramètres

`timestamp`
  Le paramètre optionnel `timestamp` est un timestamp Unix de type entier qui vaut par défaut l'heure courante locale si `timestamp` est omis ou `null`. En d'autres termes, il vaut par défaut la valeur de la fonction time().
`associative`

  Détermine si la fonction doit retourner un tableau régulier, indexé numériquement, ou un tableau associatif.

### Valeurs de retour

Si `associative` est défini à `false` ou pas fourni, alors le tableau est retourné comme un tableau indexé numériquement standard. Si `associative` est défini à `true` alors localtime() retourne un tableau associatif contenant les éléments de la structure retournée par l'appel de la fonction localtime de C. Les clés du tableau associatif sont les suivantes :

- "tm_sec" : secondes, de `0` à `59`
- "tm_min" : minutes, de `0` à `59`
- "tm_hour" : heure, de `0` à `23`
- "tm_mday" : jour du mois, de `1` à `31`
- "tm_mon" : mois de l'année, de `0` (Jan) à `11` (Déc)
- "tm_year" : Année depuis 1900
- "tm_wday" : Jour de la semaine, de `0` (Dim) à `6` (Sam)
- "tm_yday" : Jour de l'année, de `0` à `365`
- "tm_isdst" : Est-ce que l'heure d'été a pris effet ? Valeur positive si oui, `0` sinon, valeur négative si le résultat n'a pu être déterminé.

### Erreurs / Exceptions

Chaque appel à une fonction date/heure générera un diagnostic de type `E_WARNING` si le fuseau horaire n'est pas valide. Voir aussi date_default_timezone_set()

### Historique

Version | Description
--- | ---
8.0.0 | `timestamp` est désormais nullable.

### Exemples

Exemple #1 Exemple avec localtime()

    <?php
    $localtime = localtime();
    $localtime_assoc = localtime(time(), true);
    print_r($localtime);
    print_r($localtime_assoc);

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 24
        [1] => 3
        [2] => 19
        [3] => 3
        [4] => 3
        [5] => 105
        [6] => 0
        [7] => 92
        [8] => 1
    )

    Array
    (
        [tm_sec] => 24
        [tm_min] => 3
        [tm_hour] => 19
        [tm_mday] => 3
        [tm_mon] => 3
        [tm_year] => 105
        [tm_wday] => 0
        [tm_yday] => 92
        [tm_isdst] => 1
    )

### Voir aussi

- getdate() - Retourne la date/heure

# microtime

(PHP 4, PHP 5, PHP 7, PHP 8)

microtime — Retourne le timestamp UNIX actuel avec les microsecondes

### Description

function microtime(bool `$as_float` = `false`): string|float

microtime() retourne le timestamp Unix, avec les microsecondes. Cette fonction est uniquement disponible sur les systèmes qui supportent la fonction gettimeofday().

Pour mesurer les performances, l'utilisation de hrtime() est recommandée.

### Liste de paramètres

`as_float`

  Si utilisé et défini à `true`, microtime() retournera un nombre à virgule flottante au lieu d'une chaîne de caractères, tel que décrit dans la section des valeurs retournées ci-dessous.

### Valeurs de retour

Par défaut, microtime() retourne une chaîne de caractères au format "msec sec", où `sec` est le nombre de secondes depuis l'époque Unix (1 janvier 1970, 00:00:00 GMT), et `msec` est le nombre de microsecondes qui se sont écoulées depuis `sec`, exprimé en secondes sous forme de fraction décimale.

Si `as_float` est défini à `true`, alors microtime() retourne un nombre à virgule flottante, qui représente le temps courant, en secondes, depuis l'époque Unix, précis à la microseconde près.

### Exemples

Exemple #1 Durée d'exécution d'un script en PHP

    <?php
    $time_start = microtime(true);

    // Attend pendant un moment
    usleep(10_000);

    $time_end = microtime(true);
    $time = $time_end - $time_start;

    print "Ne rien faire pendant $time secondes\n";

Exemple #2 Exemple avec microtime() et `REQUEST_TIME_FLOAT`

    <?php
    // Durée d'attente aléatoire
    usleep(random_int(10_000, 1_000_000));

    // REQUEST_TIME_FLOAT est disponible dans le tableau superglobal $_SERVER.
    // Il contient le timestamp du début de la requête, avec une précision à la microseconde.
    $time = microtime(true) - $_SERVER["REQUEST_TIME_FLOAT"];

    echo "Ne rien faire pendant $time secondes\n";

### Voir aussi

- time() - Retourne l'horodatage UNIX actuel
- hrtime() - Renvoie le temps de haute résolution du système

# mktime

(PHP 4, PHP 5, PHP 7, PHP 8)

mktime — Retourne l'horodatage UNIX d'une date

### Description

function mktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

mktime() retourne un horodatage UNIX correspondant aux arguments fournis. Cet horodatage est un entier long, contenant le nombre de secondes entre le début de l'époque UNIX (1er janvier 1970 00:00:00 GMT) et le temps spécifié.

Les arguments optionnels ou `null` peuvent être omis, de droite à gauche, et tous les arguments manquants sont utilisés avec la valeur courante de l'heure et du jour.

Avertissement

Il est à noter que l'ordre des arguments est inhabituel : `month`, `day`, `year`, et non dans l'ordre plus raisonnable que serait `year`, `month`, `day`.

Appeler mktime() sans arguments n'est pas supporté. Cela aura pour résultat de lancer une ArgumentCountError. time() peut être utilisé pour récupérer l'horodatage courant.

### Liste de paramètres

`hour`

  Le nombre d'heures depuis le début de la journée fixée par les paramètres `month`, `day` et `year`. Les valeurs négatives font référence aux heures avant minuit du jour en question. Les valeurs supérieures à 23 font référence aux heures associées pour le(s) jour(s) suivant(s).

`minute`

  Le nombre de minutes depuis le début de l'heure `hour`. Les valeurs négatives font référence aux minutes de l'heure précédente. Les valeurs supérieures à 59 font référence aux minutes associées pour l'(les) heure(s) suivante(s).

`second`

  Le nombre de secondes depuis le début de la minute `minute`. Les valeurs négatives font référence aux secondes de la minute précédente. Les valeurs supérieures à 59 font référence aux secondes associées à la(les) minute(s) suivante(s).

`month`

  Le nombre de mois depuis la fin de l'année précédente. Les valeurs comprises entre 1 et 12 font référence aux mois du calendrier normal de l'année en question. Les valeurs inférieures à 1 (y compris les valeurs négatives) font référence aux mois de l'année précédente dans l'ordre inverse, aussi, 0 correspond à décembre, -1 à novembre, etc. Les valeurs supérieures à 12 font référence au mois correspondant dans l'(les) année(s) suivante(s).

`day`

  Le nombre de jours depuis la fin du mois précédent. Les valeurs comprises entre 1 et 28, 29, 30, 31 (suivant le mois) font référence aux jours normaux dans le mois courant. Les valeurs inférieures à 1 (y compris les valeurs négatives) font référence aux jours du mois précédent, aussi, 0 correspond au dernier jour du mois précédent, -1, le jour d'avant, etc. Les valeurs supérieures au nombre de jours du mois courant font référence aux jours correspondants du(des) mois suivant(s).

`year`

  L'année, peut être sur deux ou quatre chiffres, avec des valeurs allant de 0 à 69, correspondant aux valeurs 2000 à 2069 et 70 à 100, correspondant aux valeurs 1970 à 2000. Sur les systèmes où time_t est un entier signé sur 32bits, ce qui est le plus courant de nos jours, la période valide pour `year` est quelque part près de 1901 et 2038.

### Valeurs de retour

mktime() retourne un horodatage Unix des arguments donnés, ou `false` si l'horodatage ne rentre pas dans un entier PHP.

### Historique

Version | Description
--- | ---
8.0.0 | `hour` n'est plus optionnel. Pour obtenir un horodatage unix, il faudra utiliser la fonction time().
8.0.0 | `minute`, `second`, `month`, `day` et `year` sont désormais nullable.

### Exemples

Exemple #1 Exemple simple avec mktime()

    <?php
    // Configuration du fuseau horaire.
    date_default_timezone_set('UTC');

    // Affiche : July 1, 2000 est un Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    // Affiche quelque chose comme : 2006-04-05T01:02:03+00:00
    echo date('c', mktime(1, 2, 3, 4, 5, 2006)) . "\n";

Résultat de l'exemple ci-dessus est similaire à :

    July 1, 2000 is on a Saturday
    2006-04-05T01:02:03+00:00

Exemple #2 Exemple avec mktime()

mktime() est pratique pour faire des calculs de dates et des validations, car elle va automatiquement corriger les valeurs invalides. Par exemple, toutes les lignes suivantes vont retourner la même date : "Jan-01-1998".

    <?php
    date_default_timezone_set('America/New_York');

    echo date("c", mktime(0, 0, 0, 12, 32, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 13, 1, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 98)) . "\n";

Résultat de l'exemple ci-dessus est similaire à :

    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00

Exemple #3 Utiliser mktime pour trouver des dates relatives

    <?php
    date_default_timezone_set('Asia/Tokyo');

    $tomorrow  = mktime(0, 0, 0, date("m")  , date("d")+1, date("Y"));
    print date('c', $tomorrow) . "\n";

    $lastmonth = mktime(0, 0, 0, date("m")-1, date("d"),   date("Y"));
    print date('c', $lastmonth) . "\n";

    $nextyear  = mktime(0, 0, 0, date("m"),   date("d"),   date("Y")+1) . "\n";
    print date('c', $nextyear) . "\n";

Résultat de l'exemple ci-dessus est similaire à :

    2025-09-30T00:00:00+09:00
    2025-08-29T00:00:00+09:00
    2026-09-29T00:00:00+09:00

> Note:

> Ceci peut être plus fiable que d'ajouter ou de soustraire le nombre de secondes dans un jour ou un mois à un horodatage à cause du changement d'heure.

Exemple #4 Dernier jour d'un mois

Le dernier jour d'un mois peut être décrit comme le jour "0" du mois suivant, et non pas le jour -1. Les deux exemples suivants vont donner la chaîne "Last day in Feb 2000 is: 29".

    <?php

    $lastday = mktime(0, 0, 0, 3, 0, 2000);
    echo 'Last day in Feb 2000 is: ', date('d', $lastday) . "\n";
    $lastday = mktime(0, 0, 0, 4, -31, 2000);
    echo 'Last day in Feb 2000 is: ', date('d', $lastday) . "\n";

L'exemple ci-dessus va afficher :

    Last day in Feb 2000 is: 29
    Last day in Feb 2000 is: 29

### Voir aussi

- DateTimeImmutable
- checkdate() - Valide une date grégorienne
- gmmktime() - Retourne le timestamp UNIX d'une date GMT
- date() - Formate un horodatage Unix
- time() - Retourne l'horodatage UNIX actuel

# strftime

(PHP 4, PHP 5, PHP 7, PHP 8)

strftime — Formate une date/heure locale avec la configuration locale

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Il est fortement recommandé de les éviter.

Les alternatives à cette fonction incluent :

- date()
- IntlDateFormatter::format()

### Description

#[\Deprecated]
function strftime(string `$format`, ?int `$timestamp` = null): string|false

Formate une date et/ou une heure suivant la localisation locale. Les noms des mois, des jours de la semaine mais aussi d'autres chaînes dépendantes de la langue, respecteront la localisation courante définie par la fonction setlocale().

Avertissement

Tous les caractères modificateurs ne sont pas toujours supportés par toutes les bibliothèques C. Dans ce cas, ils ne seront pas supportés par PHP non plus. De plus, toutes les plates-formes ne supportent pas les timestamps négatifs, et les dates pourraient être limitées par le début de l'époque Unix. Cela signifie que `%e`, `%T`, `%R` et `%D` (et peut-être d'autres) et les dates antérieures au `1er janvier 1970` ne fonctionneront pas sous Windows, sur certaines distributions de Linux, et sur certains systèmes d'exploitation. Pour Windows, une liste complète des options de conversion est disponible sur le » site de MSDN. Utiliser plutôt la méthode IntlDateFormatter::format().

### Liste de paramètres

`format`

  Les caractères suivants sont reconnus dans le paramètre `format`
  `format` | Description | Exemple de valeurs retournées
  --- | --- | ---
  Jour | --- | ---
  `%a` | Nom abrégé du jour de la semaine | De `Sun` à `Sat`
  `%A` | Nom complet du jour de la semaine | De `Sunday` à `Saturday`
  `%d` | Jour du mois en numérique, sur 2 chiffres (avec le zéro initial) | De `01` à `31`
  `%e` | Jour du mois, avec un espace précédant le premier chiffre. L'implémentation Windows est différente, voir après pour plus d'informations. | De `1` à `31`
  `%j` | Jour de l'année, sur 3 chiffres avec un zéro initial | `001` à `366`
  `%u` | Représentation ISO-8601 du jour de la semaine | De `1` (pour lundi) à `7` (pour dimanche)
  `%w` | Représentation numérique du jour de la semaine | De `0` (pour dimanche) à `6` (pour samedi)
  Semaine | --- | ---
  `%U` | Numéro de la semaine de l'année donnée, en commençant par le premier lundi comme première semaine | `13` (pour la 13ème semaine pleine de l'année)
  `%V` | Numéro de la semaine de l'année, suivant la norme ISO-8601:1988, en commençant comme première semaine, la semaine de l'année contenant au moins 4 jours, et où lundi est le début de la semaine | De `01` à `53` (où 53 compte comme semaine de chevauchement)
  `%W` | Une représentation numérique de la semaine de l'année, en commençant par le premier lundi de la première semaine | `46` (pour la 46ème semaine de la semaine commençant par un lundi)
  Mois | --- | ---
  `%b` | Nom du mois, abrégé, suivant la locale | De `Jan` à `Dec`
  `%B` | Nom complet du mois, suivant la locale | De `January` à `December`
  `%h` | Nom du mois abrégé, suivant la locale (alias de %b) | De `Jan` à `Dec`
  `%m` | Mois, sur 2 chiffres | De `01` (pour janvier) à `12` (pour décembre)
  Année | --- | ---
  `%C` | Représentation, sur 2 chiffres, du siècle (année divisée par 100, réduit à un entier) | `19` pour le 20ème siècle
  `%g` | Représentation, sur 2 chiffres, de l'année, compatible avec les standards ISO-8601:1988 (voir %V) | Exemple : `09` pour la semaine du 6 janvier 2009
  `%G` | La version complète à quatre chiffres de %g | Exemple : `2008` pour la semaine du 3 janvier 2009
  `%y` | L'année, sur 2 chiffres | Exemple : `09` pour 2009, `79` pour 1979
  `%Y` | L'année, sur 4 chiffres | Exemple : `2038`
  Heure | --- | ---
  `%H` | L'heure, sur 2 chiffres, au format 24 heures | De `00` à `23`
  `%k` | L'heure au format 24 heures, avec un espace précédant un seul chiffre | De `0` à `23`
  `%I` | Heure, sur 2 chiffres, au format 12 heures | De `01` à `12`
  `%l` ('L' minuscule) | Heure, au format 12 heures, avec un espace précédant un seul chiffre | De `1` à `12`
  `%M` | Minute, sur 2 chiffres | De `00` à `59`
  `%p` | 'AM' ou 'PM', en majuscule, basé sur l'heure fournie | Exemple : `AM` pour 00:31, `PM` pour 22:23. Le résultat exact dépend du système d'exploitation, et ils peuvent également renvoyer des variantes en minuscules, ou des variantes avec des points (comme `a.m.`).
  `%P` | 'am' ou 'pm', en minuscule, basé sur l'heure fournie | Exemple : `am` pour 00:31, `pm` pour 22:23. Non pris en charge par tous les systèmes d'exploitation.
  `%r` | Identique à "%I:%M:%S %p" | Exemple : `09:34:17 PM` pour 21:34:17
  `%R` | Identique à "`%H:%M`" | Exemple : `00:35` pour 12:35 AM, `16:44` pour 4:44 PM
  `%S` | Seconde, sur 2 chiffres | De `00` à `59`
  `%T` | Identique à "`%H:%M:%S`" | Exemple : `21:34:17` pour 09:34:17 PM
  `%X` | Représentation de l'heure, basée sur la locale, sans la date | Exemple : `03:59:16` ou `15:59:16`
  `%z` | Le décalage horaire. Non implémenté tel que décrit sous Windows. Voir plus bas pour plus d'informations. | Exemple : `-0500` pour l'heure US de l'est
  `%Z` | L'abréviation du décalage horaire. Non implémenté tel que décrit sous Windows. Voir plus bas pour plus d'informations. | Exemple : `EST` pour l'heure de l'Est
  L'heure et la date | --- | ---
  `%c` | Date et heure préférées, basées sur la locale | Exemple : `Tue Feb 5 00:45:10 2009` pour le 5 février 2009 à 12:45:10 AM
  `%D` | Identique à "`%m/%d/%y`" | Exemple : `02/05/09` pour le 5 février 2009
  `%F` | Identique à "`%Y-%m-%d`" (utilisé habituellement par les bases de données) | Exemple : `2009-02-05` pour le 5 février 2009
  `%s` | Timestamp de l'époque Unix (identique à la fonction time()) | Exemple : `305815200` pour le 10 septembre 1979 08:40:00 AM
  `%x` | Représentation préférée de la date, basée sur la locale, sans l'heure | Exemple : `02/05/09` pour le 5 février 2009
  Divers | --- | ---
  `%n` | Une nouvelle ligne ("\n") | ---
  `%t` | Une tabulation ("\t") | ---
  `%%` | Le caractère de pourcentage ("`%`") | ---

  Avertissement

  Contrairement à la norme `ISO-9899:1999`, Sun Solaris commence avec le dimanche à 1. Aussi, le format `%u` ne fonctionnera pas tel que décrit dans ce manuel.

  Avertissement

  Windows seulement :

  Le modificateur `%e` n'est pas supporté sous Windows. Pour calculer la valeur, le modificateur `%#d` peut être utilisé à la place. L'exemple d'après illustre la manière d'écrire un code cross-plateforme.

  Les modificateurs `%z` et `%Z` retournent tous les deux le nom du fuseau horaire au lieu du décalage ou de l'abréviation.

  Avertissement

  macOS et musl uniquement : Le modificateur `%P` n'est pas supporté par l'implémentation de cette fonction sous macOS.

`timestamp`
  Le paramètre optionnel `timestamp` est un timestamp Unix de type entier qui vaut par défaut l'heure courante locale si `timestamp` est omis ou `null`. En d'autres termes, il vaut par défaut la valeur de la fonction time().

### Valeurs de retour

Retourne une chaîne de caractères formatée suivant le paramètre `format` donné, en utilisant le paramètre `timestamp` ou la date locale courante si aucun timestamp n'est fourni. Les noms des mois, des jours de la semaine mais aussi d'autres chaînes dépendantes de la langue, respecteront la localisation courante définie par la fonction setlocale(). La fonction retourne `false` si `format` est vide, contient des spécificateurs de conversion non supportés, ou si la longueur de la chaîne retournée serait supérieure à `4095`.

### Erreurs / Exceptions

Chaque appel à une fonction date/heure générera un diagnostic de type `E_WARNING` si le fuseau horaire n'est pas valide. Voir aussi date_default_timezone_set()

Vu que la sortie dépend de la bibliothèque C sous-jacente, quelques spécificateurs de conversion ne sont pas supportés. Sous Windows, le fait de fournir un spécificateur de conversion inconnu retourne 5 messages de niveau `E_WARNING` et retournera `false` au final. Sous d'autres systèmes d'exploitation, on ne recevra aucun message de niveau `E_WARNING` et la sortie contiendra les spécificateurs non convertis.

### Historique

Version | Description
--- | ---
8.0.0 | `timestamp` est désormais nullable.

### Exemples

Cet exemple ne fonctionnera que si l'on a les locales respectives installées sur le système.

Exemple #1 Exemple avec strftime()

    <?php
    setlocale(LC_TIME, "C");
    echo strftime("%A");
    setlocale(LC_TIME, "fi_FI");
    echo strftime(" in Finnish is %A,");
    setlocale(LC_TIME, "fr_FR");
    echo strftime(" in French %A and");
    setlocale(LC_TIME, "de_DE");
    echo strftime(" in German %A.\n");

Exemple #2 Exemple au format de date ISO 8601:1988

    <?php
    /*     December 2002 / January 2003
    ISOWk  M   Tu  W   Thu F   Sa  Su
    ----- ----------------------------
    51     16  17  18  19  20  21  22
    52     23  24  25  26  27  28  29
    1      30  31   1   2   3   4   5
    2       6   7   8   9  10  11  12
    3      13  14  15  16  17  18  19   */

    // Affiche : 12/28/2002 - %V,%G,%Y = 52,2002,2002
    echo "12/28/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n";

    // Affiche : 12/30/2002 - %V,%G,%Y = 1,2003,2002
    echo "12/30/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n";

    // Affiche : 1/3/2003 - %V,%G,%Y = 1,2003,2003
    echo "1/3/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n";

    // Affiche : 1/10/2003 - %V,%G,%Y = 2,2003,2003
    echo "1/10/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n";

    /*     December 2004 / January 2005
    ISOWk  M   Tu  W   Thu F   Sa  Su
    ----- ----------------------------
    51     13  14  15  16  17  18  19
    52     20  21  22  23  24  25  26
    53     27  28  29  30  31   1   2
    1       3   4   5   6   7   8   9
    2      10  11  12  13  14  15  16   */

    // Affiche : 12/23/2004 - %V,%G,%Y = 52,2004,2004
    echo "12/23/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n";

    // Affiche : 12/31/2004 - %V,%G,%Y = 53,2004,2004
    echo "12/31/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n";

    // Affiche : 1/2/2005 - %V,%G,%Y = 53,2004,2005
    echo "1/2/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n";

    // Affiche : 1/3/2005 - %V,%G,%Y = 1,2005,2005
    echo "1/3/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n";

Exemple #3 `%e` fonctionnant sous toute plateforme

    <?php

    // Jan 1 : résultats dans : '%e%1%' (%%, e, %%, %e, %%)
    $format = '%%e%%%e%%';

    // Vérifie sous Windows, pour trouver et remplacer le modificateur %e
    // correctement
    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') {
        $format = preg_replace('#(?<!%)((?:%%)*)%e#', '\1%#d', $format);
    }

    echo strftime($format);

Exemple #4 Affiche tous les formats connus ou non

    <?php

    // Décrit les formats
    $strftimeFormats = array(
        'A' => 'Une représentation textuelle complète du jour',
        'B' => 'Nom du mois complet, basé sur la locale',
        'C' => 'Représentation sur 2 chiffres de l\'année (année, divisée par 100, tronquée en entier)',
        'D' => 'Identique à "%m/%d/%y"',
        'E' => '',
        'F' => 'Identique à "%Y-%m-%d"',
        'G' => 'La version complète, sur 4 chiffres de %g',
        'H' => 'Une représentation sur 2 chiffres de l\'heure au format 24-heures',
        'I' => 'Une représentation sur 2 chiffres de l\'heure au format 12-heures',
        'J' => '',
        'K' => '',
        'L' => '',
        'M' => 'Une représentation sur 2 chiffres des minutes',
        'N' => '',
        'O' => '',
        'P' => '"am" ou "pm" (en minuscule) basé sur l\'heure courante',
        'Q' => '',
        'R' => 'Identique à "%H:%M"',
        'S' => 'Une représentation sur 2 chiffres des secondes',
        'T' => 'Identique à "%H:%M:%S"',
        'U' => 'Numéro de la semaine pour l\'année courante, en commençant par le premier dimanche comme première semaine',
        'V'  => 'ISO-8601:1988 numéro de la semaine de l\'année courante, commençant par la première semaine de l\'année avec au moins 4 jours de semaine, avec le lundi comme début de semaine',
        'W' => 'Une représentation numérique de la semaine de l\'année, en commençant par le premier lundi comme première semaine',
        'X' => 'Représentation préférée pour l\'heure, basée sur la locale, sans la date',
        'Y' => 'Une représentation sur 4 chiffres de l\'année',
        'Z' => 'L\'abréviation du décalage horaire, non fournie par %z (dépend du système d\'exploitation)',
        'a' => 'L\'abréviation de la représentation textuelle du jour',
        'b' => 'L\'abréviation du nom du mois, basée sur la locale',
        'c' => 'Timestamp préféré basé sur la locale',
        'd' => 'Jour du mois sur 2 chiffres (avec le zéro initial)',
        'e' => 'Jour du mois, avec un espace précédant un seul chiffre',
        'f' => '',
        'g' => 'Une représentation sur 2 chiffres de l\'année au format ISO-8601:1988 (voir %V)',
        'h' => 'Abréviation du nom du mois, basée sur la locale (alias de %b)',
        'i' => '',
        'j' => 'Jour de l\'année, sur 3 chiffres avec zéro initial',
        'k' => 'Heure, au format 24-heures, avec un espace précédant un seul chiffre',
        'l' => 'Heure, au format 12-heures, avec un espace précédant un seul chiffre',
        'm' => 'Une représentation du mois sur 2 chiffres',
        'n' => 'Un caractère de nouvelle ligne ("\n")',
        'o' => '',
        'p' => '"AM" ou "PM" (en majuscule) basé sur l\'heure courante',
        'q' => '',
        'r' => 'Identique à "%I:%M:%S %p"',
        's' => 'Timestamp par rapport à l\'époque Unix',
        't' => 'Un caractère de tabulation ("\t")',
        'u' => 'Représentation numérique du jour de la semaine au format ISO-8601',
        'v' => '',
        'w' => 'Représentation numérique du jour de la semaine',
        'x' => 'Représentation préférée de la date, basée sur la locale, sans l\'heure',
        'y' => 'Représentation de l\'année sur 2 chiffres',
        'z' => 'Soit le décalage horaire depuis UTC ou son abréviation (suivant le système d\'exploitation)',
        '%' => 'Un caractère pourcentage ("%")',
    );

    // Résultats
    $strftimeValues = array();

    // Évalue les formats tout en supprimant les erreurs
    foreach ($strftimeFormats as $format => $description) {
        if (false !== ($value = @strftime("%{$format}"))) {
            $strftimeValues[$format] = $value;
        }
    }

    // Trouve la valeur la plus longue
    $maxValueLength = 2 + max(array_map('strlen', $strftimeValues));

    // Affiche tous les formats connus
    foreach ($strftimeValues as $format => $value) {
        echo "Format connu : '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n";
    }

    // Affiche tous les formats non connus
    foreach (array_diff_key($strftimeFormats, $strftimeValues) as $format => $description) {
        echo "Format inconnu : '{$format}'   ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n";
    }

Résultat de l'exemple ci-dessus est similaire à :

    Format connu : 'A' = 'Friday'            ( Une représentation textuelle complète du jour )
    Format connu : 'B' = 'December'          ( Nom du mois complet, basé sur la locale )
    Format connu : 'H' = '11'                ( Une représentation sur 2 chiffres de l'heure au format 24-heures )
    Format connu : 'I' = '11'                ( Une représentation sur 2 chiffres de l'heure au format 12-heures )
    Format connu : 'M' = '24'                ( Une représentation sur 2 chiffres des minutes )
    Format connu : 'S' = '44'                ( Une représentation sur 2 chiffres des secondes )
    Format connu : 'U' = '48'                ( Numéro de la semaine pour l'année courante, en commençant par le premier dimanche comme première semaine )
    Format connu : 'W' = '48'                ( Une représentation numérique de la semaine de l'année, en commençant par le premier lundi comme première semaine )
    Format connu : 'X' = '11:24:44'          ( Représentation préférée pour l'heure, basée sur la locale, sans la date )
    Format connu : 'Y' = '2010'              ( Une représentation sur 4 chiffres de l'année )
    Format connu : 'Z' = 'GMT Standard Time' ( L'abréviation du décalage horaire, non fournie par %z (dépend du système d'exploitation) )
    Format connu : 'a' = 'Fri'               ( L'abréviation de la représentation textuelle du jour )
    Format connu : 'b' = 'Dec'               ( L'abréviation du nom du mois, basée sur la locale )
    Format connu : 'c' = '12/03/10 11:24:44' ( Timestamp préféré basé sur la locale )
    Format connu : 'd' = '03'                ( Jour du mois sur 2 chiffres (avec le zéro initial) )
    Format connu : 'j' = '337'               ( Jour de l'année, sur 3 chiffres avec zéro initial )
    Format connu : 'm' = '12'                ( Une représentation du mois sur 2 chiffres )
    Format connu : 'p' = 'AM'                ( "AM" ou "PM" (en majuscule) basé sur l'heure courante )
    Format connu : 'w' = '5'                 ( Représentation numérique du jour de la semaine )
    Format connu : 'x' = '12/03/10'          ( Représentation préférée de la date, basée sur la locale, sans l'heure )
    Format connu : 'y' = '10'                ( Représentation de l'année sur 2 chiffres )
    Format connu : 'z' = 'GMT Standard Time' ( Soit le décalage horaire depuis UTC ou son abréviation (suivant le système d'exploitation) )
    Format connu : '%' = '%'                 ( Un caractère pourcentage ("%") )
    Format inconnu : 'C'                       ( Représentation sur 2 chiffres de l'année (année, divisée par 100, tronquée en entier) )
    Format inconnu : 'D'                       ( Identique à "%m/%d/%y" )
    Format inconnu : 'E'
    Format inconnu : 'F'                       ( Identique à "%Y-%m-%d" )
    Format inconnu : 'G'                       ( La version complète, sur 4 chiffres de %g )
    Format inconnu : 'J'
    Format inconnu : 'K'
    Format inconnu : 'L'
    Format inconnu : 'N'
    Format inconnu : 'O'
    Format inconnu : 'P'                       ( "am" ou "pm" (en minuscule) basé sur l'heure courante )
    Format inconnu : 'Q'
    Format inconnu : 'R'                       ( Identique à "%H:%M" )
    Format inconnu : 'T'                       ( Identique à "%H:%M:%S" )
    Format inconnu : 'V'                       ( ISO-8601:1988 numéro de la semaine de l'année courante, commençant par la première semaine de l'année avec au moins 4 jours de semaine, avec le lundi comme début de semaine )
    Format inconnu : 'e'                       ( Jour du mois, avec un espace précédant un seul chiffre )
    Format inconnu : 'f'
    Format inconnu : 'g'                       ( Une représentation sur 2 chiffres de l'année au format ISO-8601:1988 (voir %V) )
    Format inconnu : 'h'                       ( Abréviation du nom du mois, basée sur la locale (alias de %b) )
    Format inconnu : 'i'
    Format inconnu : 'k'                       ( Heure, au format 24-heures, avec un espace précédant un seul chiffre )
    Format inconnu : 'l'                       ( Heure, au format 12-heures, avec un espace précédant un seul chiffre )
    Format inconnu : 'n'                       ( Un caractère de nouvelle ligne ("\n") )
    Format inconnu : 'o'
    Format inconnu : 'q'
    Format inconnu : 'r'                       ( Identique à "%I:%M:%S %p" )
    Format inconnu : 's'                       ( Timestamp par rapport à l'époque Unix )
    Format inconnu : 't'                       ( Un caractère de tabulation ("\t") )
    Format inconnu : 'u'                       ( Représentation numérique du jour de la semaine au format ISO-8601 )
    Format inconnu : 'v'

### Notes

> Note: `%G` et `%V`, qui sont basées sur la semaine `ISO 8601:1988`, peuvent conduire à des résultats inattendus (bien que corrects) si le système de numérotation n'est pas connu. Voir l'exemple `%V` de cette page.

### Voir aussi

- IntlDateFormatter::format() - Formate la date et l'heure sous forme de chaîne
- DateTimeInterface::format() - Retourne une date formatée suivant le format fourni
- » Outil de formatage strftime() en ligne
- setlocale() - Modifie les informations de localisation
- mktime() - Retourne l'horodatage UNIX d'une date
- strptime() - Analyse une date générée par strftime
- gmstrftime() - Formate une date/heure GMT/TUC en fonction de la configuration locale
- » groupe de spécifications de strftime()

# strptime

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

strptime — Analyse une date générée par strftime()

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.1.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function strptime(string `$timestamp`, string `$format`): array|false

strptime() retourne un tableau après avoir analysé `timestamp`, ou false en cas d'erreur.

Les noms des mois et jours de la semaine dépendent de la configuration locale, choisie avec setlocale() (LC_TIME).

### Liste de paramètres

`timestamp` (chaîne de caractères)

  La chaîne à analyser (p. ex. retournée par strftime())

`format` (chaîne de caractères)

  Le format utilisé par `timestamp` (p. ex. le même que celui qui a été utilisé par strftime()).

  Pour plus d'informations sur les spécificateurs de formats, voir la fonction strftime().

### Valeurs de retour

Retourne un tableau ou `false` si une erreur survient.

Les paramètres suivants sont retournés dans le tableau
Paramètres | Description
--- | ---
`"tm_sec"` | Secondes après la minute (0-61)
`"tm_min"` | Minutes après l'heure (0-59)
`"tm_hour"` | Heure depuis minuit (0-23)
`"tm_mday"` | Jour du mois (1-31)
`"tm_mon"` | Mois depuis janvier (0-11)
`"tm_year"` | Années depuis 1900
`"tm_wday"` | Jours depuis dimanche (0-6)
`"tm_yday"` | Jours depuis le 1er janvier (0-365)
`"unparsed"` | La partie de `timestamp` qui n'a pas été reconnue par l'analyseur avec le `format` spécifié.

### Historique

Version | Description
--- | ---
8.1.0 | Cette fonction a été rendue obsolète. Utiliser date_parse_from_format() à la place (pour de l'analyse indépendante de la locale), ou IntlDateFormatter::parse() (pour de l'analyse dépendante de la locale)

### Exemples

Exemple #1 Exemple avec strptime()

    <?php
    $format = '%d/%m/%Y %H:%M:%S';
    $strf = strftime($format);

    echo "$strf\n";

    print_r(strptime($strf, $format));

Résultat de l'exemple ci-dessus est similaire à :

    03/10/2004 15:54:19

    Array
    (
        [tm_sec] => 19
        [tm_min] => 54
        [tm_hour] => 15
        [tm_mday] => 3
        [tm_mon] => 9
        [tm_year] => 104
        [tm_wday] => 0
        [tm_yday] => 276
        [unparsed] =>
    )

### Notes

> Note: Cette fonction n'est pas implémentée sur les plates-formes Windows.

> Note:

> En interne, cette fonction appelle la fonction `strptime()` fournie par la bibliothèque système C. Cette fonction a des comportements bien différents suivant les systèmes d'exploitation. L'utilisation de la fonction date_parse_from_format(), qui elle, ne souffre pas de ces défauts, est recommandée.

> Note:

> `"tm_sec"` inclut toutes les secondes intercalaires (actuellement 2 par an). Pour plus d'informations sur les secondes intercalaires, se reporter à l'» article sur Wikipedia les concernant.

### Voir aussi

- IntlDateFormatter::parse() - Analyse une chaîne vers un timestamp
- DateTime::createFromFormat() - Analyse une heure au format texte selon le format spécifié.
- checkdate() - Valide une date grégorienne
- strftime() - Formate une date/heure locale avec la configuration locale
- date_parse_from_format() - Récupère les informations d'une date donnée suivant un format spécifique

# strtotime

(PHP 4, PHP 5, PHP 7, PHP 8)

strtotime — Transforme un texte anglais en timestamp

### Description

function strtotime(string `$datetime`, ?int `$baseTimestamp` = `null`): int|false

La fonction strtotime() essaye de lire une date au format anglais fournie par le paramètre `datetime`, et de la transformer en timestamp Unix (le nombre de secondes depuis le 1er janvier 1970 à 00:00:00 UTC), relativement au timestamp `baseTimestamp`, ou à la date courante si ce dernier est omis. L'analyse de la chaîne de date est définie dans les formats de date et d'heure et comporte plusieurs considérations subtiles. Il est fortement recommandé d'en examiner tous les détails.

Avertissement

L'horodatage Unix que cette fonction retourne ne contient pas d'information à propos des fuseaux horaires. Pour faire des calculs avec les informations de date/moment, il est recommandé d'utiliser DateTimeImmutable qui est plus capable.

Chaque paramètre de la fonction utilise le décalage horaire par défaut à moins qu'un décalage horaire y soit explicitement paramétré. Il faut veiller à ne pas utiliser un décalage horaire différent pour chaque paramètre à moins que ce soit ce dont il est nécessaire. Se reporter à la fonction date_default_timezone_get() afin de savoir comment définir un décalage horaire par défaut.

### Liste de paramètres

`datetime`

  Une chaîne date/heure. Les formats valides sont expliqués dans la documentation sur les formats Date et Heure.

`baseTimestamp`

  Le timestamp, représentant la date courante, utilisé pour le calcul relatif des dates.

### Valeurs de retour

Retourne un timestamp en cas de succès, `false` sinon.

### Erreurs / Exceptions

Chaque appel à une fonction date/heure générera un diagnostic de type `E_WARNING` si le fuseau horaire n'est pas valide. Voir aussi date_default_timezone_set()

### Historique

Version | Description
--- | ---
8.0.0 | `baseTimestamp` est désormais nullable.

### Exemples

Exemple #1 Exemple avec strtotime()

    <?php
    echo strtotime("now"), "\n";
    echo strtotime("10 September 2000"), "\n";
    echo strtotime("+1 day"), "\n";
    echo strtotime("+1 week"), "\n";
    echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n";
    echo strtotime("next Thursday"), "\n";
    echo strtotime("last Monday"), "\n";

Exemple #2 Vérification d'erreur

    <?php
    $str = 'Pas bon';

    if (($timestamp = strtotime($str)) === false) {
       echo "La chaîne ($str) est boguée";
    } else {
       echo "$str == " . date('l dS \o\f F Y h:i:s A', $timestamp);
    }

### Notes

> Note:

> Dans ce cas, la date "relative" signifie également que si un composant particulier de l'horodatage n'est pas fourni, il sera extrait textuellement de `baseTimestamp`. Autrement dit, `strtotime('February')`, s'il est exécuté le 31 mai 2022, sera interprété comme le `31 février 2022`, qui débordera sur un horodatage le `3 mars`. (Dans une année bissextile, ce serait le `2 mars`.) L'utilisation de `strtotime('1 February')` ou `strtotime('first day of February')` éviterait ce problème.

> Note:

> Si le chiffre des années est précisé sur deux chiffres, les valeurs entre 00-69 correspondent à 2000-2069 et 70-99 à 1970-1999. Voir les notes ci-après concernant les différences possibles entre systèmes 32-bit (des dates peuvent échouer après le 19/01/2038 à 03:14:07).

> Note:

> L'intervalle de validité d'un timestamp va du vendredi 13 décembre 1901 20:45:54 UTC au mardi 19 janvier 2038 03:14:07 UTC. (Cela correspond aux dates maximales et minimales pour un entier de 32 bits signé).

> Pour les versions 64-bit de PHP, l'intervalle valide d'un timestamp est réellement infini, sachant que 64 bits peut représenter approximativement 293 milliards d'années dans n'importe quelle direction.

> Note:

> L'utilisation de cette fonction sur des opérations mathématiques n'est pas conseillée. Il vaut mieux utiliser dans ce cas DateTime::add() et DateTime::sub().

### Voir aussi

- DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Analyse une heure au format texte selon le format spécifié.
- Les formats sur les dates
- checkdate() - Valide une date grégorienne
- strptime() - Analyse une date générée par strftime

# time

(PHP 4, PHP 5, PHP 7, PHP 8)

time — Retourne l'horodatage UNIX actuel

### Description

function time(): int

time() retourne l'heure courante, mesurée en secondes depuis le début de l'époque UNIX, (1er janvier 1970 00:00:00 GMT).

> Note:

> Les horodatages Unix ne contiennent aucune information concernant le fuseau horaire local. Il est recommandé d'utiliser la classe DateTimeImmutable pour manipuler les informations relatives à la date et à l'heure afin d'éviter les écueils liés aux seuls horodatages Unix.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'horodatage actuel.

### Exemples

Exemple #1 Exemple avec time()

    <?php
    echo 'Aujourd\'hui : '. time();

Résultat de l'exemple ci-dessus est similaire à :

    Aujourd'hui : 1660338149

### Notes

Astuce

Un horodatage représentant le début de la requête est disponible dans la variable $_SERVER['REQUEST_TIME'].

### Voir aussi

- DateTimeImmutable
- date() - Formate un horodatage Unix
- microtime() - Retourne le timestamp UNIX actuel avec les microsecondes

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_abbreviations_list — Alias de DateTimeZone::listAbbreviations()

### Description

Cette fonction est un alias de : DateTimeZone::listAbbreviations()

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_identifiers_list — Alias de DateTimeZone::listIdentifiers()

### Description

Cette fonction est un alias de : DateTimeZone::listIdentifiers()

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_location_get — Alias de DateTimeZone::getLocation()

### Description

Cette fonction est un alias de : DateTimeZone::getLocation()

# timezone_name_from_abbr

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

timezone_name_from_abbr — Retourne le nom d'un fuseau horaire à partir de son abréviation et de son décalage UTC

### Description

function timezone_name_from_abbr(string `$abbr`, int `$utcOffset` = -1, int `$isDST` = -1): string|false

### Liste de paramètres

`abbr`

  Abréviation du fuseau horaire.

`utcOffset`

  Décalage à partir du GMT en secondes. La valeur par défaut est -1 ce qui signifie que le premier fuseau horaire trouvé correspondant à `abbr` est retourné. Autrement, le décalage exact est recherché et seulement s'il n'est pas trouvé alors le premier fuseau horaire avec n'importe quel décalage est retourné.

`isDST`

  Indicateur d'heure d'été/heure d'hiver. Par défaut -1 qui signifie que le décalage heure d'été/heure d'hiver n'est pas pris en compte dans la recherche même si le fuseau le gère. Si mis à 1, alors le `utcOffset` est supposé comprendre le décalage heure d'été /heure d'hiver; si 0 alors `utcOffset` est supposé représenter un décalage ne prenant pas en compte l'heure d'été/hiver. Si `abbr` n'existe pas alors le fuseau horaire est cherché uniquement au moyen de `utcOffset` et `isDST`.

### Valeurs de retour

Retourne un nom de fuseau horaire en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec timezone_name_from_abbr()

    <?php
    echo timezone_name_from_abbr("CET") . "\n";
    echo timezone_name_from_abbr("", 3600, 0) . "\n";

Résultat de l'exemple ci-dessus est similaire à :

    Europe/Berlin
    Europe/Paris

### Voir aussi

- timezone_abbreviations_list() - Alias de DateTimeZone::listAbbreviations

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_name_get — Alias de DateTimeZone::getName()

### Description

Cette fonction est un alias de : DateTimeZone::getName()

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_offset_get — Alias de DateTimeZone::getOffset()

### Description

Cette fonction est un alias de : DateTimeZone::getOffset()

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_open — Alias de DateTimeZone::__construct()

### Description

Cette fonction est un alias de : DateTimeZone::__construct()

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_transitions_get — Alias de DateTimeZone::getTransitions()

### Description

Cette fonction est un alias de : DateTimeZone::getTransitions()

# timezone_version_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_version_get — Lit la version de la timezonedb

### Description

function timezone_version_get(): string

timezone_version_get() lit la version de la timezonedb.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères au format `YYYY.increment`, tel que `2022.2`.

Si l'on a une ancienne version de la base de données de fuseaux horaires (par exemple, elle n'affiche pas l'année en cours), il est possible de mettre à jour les informations de fuseau horaire en mettant à jour la version de PHP ou en installant le package PECL » timezonedb.

Certaines distributions Linux corrigent le support date/heure de PHP pour utiliser une source alternative pour les informations de fuseau horaire. Dans ce cas, cette fonction renverra `0.system`. On est encouragé également à installer le package PECL » timezonedb dans ce cas.

### Exemples

Exemple #1 Lecture de la version de la timezonedb

    <?php
    echo timezone_version_get();

Résultat de l'exemple ci-dessus est similaire à :

    2022.2

### Voir aussi

- Liste des fuseaux horaires valides

## Sommaire

- checkdate — Valide une date grégorienne
- date — Formate un horodatage Unix
- date_add — Alias de DateTime::add
- date_create — Création d'un objet DateTime
- date_create_from_format — Alias de DateTime::createFromFormat
- date_create_immutable — Crée un nouvel objet DateTimeImmutable
- date_create_immutable_from_format — Alias de DateTimeImmutable::createFromFormat
- date_date_set — Alias de DateTime::setDate
- date_default_timezone_get — Récupère le décalage horaire par défaut utilisé par toutes les fonctions date/heure d'un script
- date_default_timezone_set — Définit le décalage horaire par défaut de toutes les fonctions date/heure
- date_diff — Alias de DateTime::diff
- date_format — Alias de DateTime::format
- date_get_last_errors — Alias de DateTimeImmutable::getLastErrors
- date_interval_create_from_date_string — Alias de DateInterval::createFromDateString
- date_interval_format — Alias de DateInterval::format
- date_isodate_set — Alias de DateTime::setISODate
- date_modify — Alias de DateTime::modify
- date_offset_get — Alias de DateTime::getOffset
- date_parse — Retourne un tableau associatif avec des informations détaillées sur une date/moment donnée
- date_parse_from_format — Récupère les informations d'une date donnée suivant un format spécifique
- date_sub — Alias de DateTime::sub
- date_sun_info — Retourne un tableau avec les informations sur le lever/coucher du soleil ainsi que le début et la fin de l'aube
- date_sunrise — Retourne l'heure de lever du soleil pour un jour et un endroit donnés
- date_sunset — Retourne l'heure de coucher du soleil pour un jour et un endroit donnés
- date_time_set — Alias de DateTime::setTime
- date_timestamp_get — Alias de DateTime::getTimestamp
- date_timestamp_set — Alias de DateTime::setTimestamp
- date_timezone_get — Alias de DateTime::getTimezone
- date_timezone_set — Alias de DateTime::setTimezone
- getdate — Retourne la date/heure
- gettimeofday — Retourne l'heure actuelle
- gmdate — Formate une date/heure GMT/TUC
- gmmktime — Retourne le timestamp UNIX d'une date GMT
- gmstrftime — Formate une date/heure GMT/TUC en fonction de la configuration locale
- idate — Formate une partie de l'heure/date locale en tant qu'entier
- localtime — Récupère l'heure locale
- microtime — Retourne le timestamp UNIX actuel avec les microsecondes
- mktime — Retourne l'horodatage UNIX d'une date
- strftime — Formate une date/heure locale avec la configuration locale
- strptime — Analyse une date générée par strftime
- strtotime — Transforme un texte anglais en timestamp
- time — Retourne l'horodatage UNIX actuel
- timezone_abbreviations_list — Alias de DateTimeZone::listAbbreviations
- timezone_identifiers_list — Alias de DateTimeZone::listIdentifiers
- timezone_location_get — Alias de DateTimeZone::getLocation
- timezone_name_from_abbr — Retourne le nom d'un fuseau horaire à partir de son abréviation et de son décalage UTC
- timezone_name_get — Alias de DateTimeZone::getName
- timezone_offset_get — Alias de DateTimeZone::getOffset
- timezone_open — Alias de DateTimeZone::__construct
- timezone_transitions_get — Alias de DateTimeZone::getTransitions
- timezone_version_get — Lit la version de la timezonedb

# Erreurs et Exceptions Date/Heure

- DateError (étend Error)
  - DateObjectError DateRangeError
- DateException (étend Exception)
  - - DateInvalidOperationException
    - DateInvalidTimezoneException
    - DateMalformedIntervalStringException
    - DateMalformedPeriodStringException
    - DateMalformedStringException

# Formats supportés de temps et de dates

Cette section décrit, dans un format de type BNF, tous les formats différents que l'analyseur de DateTimeImmutable, DateTime, date_create_immutable(), date_create(), date_parse(), et strtotime() est capable de comprendre. Les formats sont groupés par sections. Dans la plupart des cas, les formats de sections différentes, séparés par des caractères d'espacement blanc, des virgules ou des points, peuvent être utilisés dans la même chaîne date/moment. Pour chaque format supporté, un ou plusieurs exemples sont donnés ainsi qu'une description du format correspondant. Les caractères entre guillemets simples pour les formats sont insensibles à la casse (`'t'` pourrait s'écrire `t` ou `T`), les caractères écrits entre guillemets doubles, eux, sont sensibles à la casse (`"T"` et seulement `T`).

Pour formater des objets DateTimeImmutable et DateTime, se référer à la documentation de la méthode DateTimeInterface::format().

Un ensemble de règles générales devrait être pris en compte.

1. L'analyseur permet à chaque unité (année, mois, jour, heure, minute, seconde) la plage entière de valeurs. Pour une année c'est juste 4 chiffres, pour un mois c'est 0-12, pour un jour 0-31, pour une heure c'est 0-24, et pour une minute c'est 0-59.
2. 60 est autorisé pour les secondes, car parfois des chaînes de dates avec cette seconde intercalaire apparaissent. Mais PHP implémente le temps Unix où "60" n'est pas un nombre de secondes valide et déborde.
3. strtotime() retourne `false` si un des nombres est en dehors de la plage, et DateTimeImmutable::__construct() lance une exception.
4. Si une chaîne contient une date, tous les éléments sont remis à 0.
5. Tous les éléments de temps moins significatifs sont remis à 0 si n'importe quel élément d'un temps est présent dans la chaîne donnée.
6. L'analyseur est idiot, et n'effectue pas de vérification pour le rendre plus rapide (et plus générique).
7. Outre les règles applicables aux éléments temporels individuels, l'analyseur comprend également des formats composés plus spécifiques, tels que l'analyse des horodatages Unix (`@1690388256`) et des dates hebdomadaires ISO (`2008-W28-3`).

8. Il y a une vérification additionnelle si une date invalide est fournie :

       <?php
       $res = date_parse("2015-09-31");
       var_dump($res["warnings"]);

   L'exemple ci-dessus va afficher :

       array(1) {
         [11] =>
         string(27) "The parsed date was invalid"
       }

9. Il est déjà possible de gérer ces cas spéciaux, mais l'utilisation de DateTimeImmutable::createFromFormat() est requise en fournissant le format voulu.

       <?php
       $res = DateTimeImmutable::createFromFormat("Y-m-d", "2015-09-34");
       var_dump($res);

   L'exemple ci-dessus va afficher :

       object(DateTimeImmutable)#1 (3) {
         ["date"] =>
         string(26) "2015-10-04 17:24:43.000000"
         ["timezone_type"] =>
         int(3)
         ["timezone"] =>
         string(13) "Europe/London"
       }

## Formats pour les temps (Time)

Cette page décrit les différents formats dans une syntaxe de type BNF que les analyseurs de DateTimeImmutable, DateTime, date_create(), date_create_immutable(), et strtotime() comprennent.

Pour formater des objets DateTimeImmutable et DateTime, se référer à la documentation de la méthode DateTimeInterface::format().

Symboles utilisés
Description | Formats | Exemples
--- | --- | ---
`frac` | . [0-9]+ | ".21342", ".85"
`hh` | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` | [01][0-9] | "2"[0-4] | "04", "07", "19"
`méridien` | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`MM` | [0-5][0-9] | "00", "12", "59"
`II` | [0-5][0-9] | "00", "12", "59"
`espace` | [ \t] |
`tz` | "("? [A-Za-z]{1,6} ")"? | [A-Z][a-z]+([_/][A-Z][a-z]+)+ | "CEST", "Europe/Amsterdam", "America/Indiana/Knox"
`tzcorrection` | "GMT"? [+-] `hh` ":"? `MM`? | "+0400", "GMT-07:00", "-07:00"

Notation 12 heures
Description | Format | Exemples
--- | --- | ---
Heures seules, avec méridien | `hh` `espace`? `méridien` | "4 am", "5PM"
Heures et minutes, avec méridien | `hh` [.:] `MM` `espace`? `méridien` | "4:08 am", "7:19P.M."
Heures, minutes et secondes avec méridien | `hh` [.:] `MM` [.:] `II` `espace`? `méridien` | "4:08:37 am", "7:19:19P.M."
MS SQL (Heures, minutes, secondes et fraction avec méridien) | `hh` ":" `MM` ":" `II` [.:] [0-9]+ `méridien` | "4:08:39:12313am"

Notation 24 heures
Description | Format | Exemples
--- | --- | ---
Heures et minutes | 't'? `HH` [.:] `MM` | "04:08", "19.19", "T23:43"
Heures et minutes, sans double-points | 't'? `HH` `MM` | "0408", "t1919", "T2343"
Heures, minutes et secondes | 't'? `HH` [.:] `MM` [.:] `II` | "04.08.37", "t19:19:19"
Heures, minutes et secondes, sans double-points | 't'? `HH` `MM` `II` | "040837", "T191919"
Heures, minutes, secondes et fuseau horaire | 't'? `HH` [.:] `MM` [.:] `II` `espace`? ( `tzcorrection` | `tz` ) | "040837CEST", "T191919-0700"
Heures, minutes, secondes et fraction | 't'? `HH` [.:] `MM` [.:] `II` `frac` | "04.08.37.81412", "19:19:19.532453"
Information de fuseau horaire | `tz` | `tzcorrection` | "CEST", "Europe/Amsterdam", "+0430", "GMT-06:00"

## Formats de dates

Cette page décrit les différents formats dans une syntaxe de type BNF que les analyseurs de DateTimeImmutable, DateTime, date_create(), date_create_immutable(), et strtotime() comprennent.

Pour formater des objets DateTimeImmutable et DateTime, se référer à la documentation de la méthode DateTimeInterface::format().

Symboles utilisés
Description | Format | Exemples
--- | --- | ---
`suffixe des jours` | "st" | "nd" | "rd" | "th" |
`dd` | ([0-2]?[0-9] | "3"[01]) `daysuf`? | "7th", "22nd", "31"
`DD` | "0" [0-9] | [1-2][0-9] | "3" [01] | "07", "31"
`m` | 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | "I" | "II" | "III" | "IV" | "V" | "VI" | "VII" | "VIII" | "IX" | "X" | "XI" | "XII" |
`M` | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`mm` | "0"? [0-9] | "1"[0-2] | "0", "04", "7", "12"
`MM` | "0" [0-9] | "1"[0-2] | "00", "04", "07", "12"
`y` | [0-9]{1,4} | "00", "78", "08", "8", "2008"
`yy` | [0-9]{2} | "00", "08", "78"
`YY` | [0-9]{4} | "2000", "2008", "1978"
`YYY` | [0-9]{5,19} | "81412", "20192"

Notations localisées
Description | Format | Exemples
--- | --- | ---
Mois américain et jour | `mm` "/" `dd` | "5/12", "10/27"
Mois américain, jour et année | `mm` "/" `dd` "/" `y` | "12/22/78", "1/17/2006", "1/17/6"
Année sur quatre chiffres, mois et jour avec slashs | `YY` "/" `mm` "/" `dd` | "2008/6/30", "1978/12/22"
Année sur quatre chiffres et mois (GNU) | `YY` "-" `mm` | "2008-6", "2008-06", "1978-12"
Année, mois et jour avec tirets | `y` "-" `mm` "-" `dd` | "2008-6-30", "78-12-22", "8-6-21"
Jour, mois et année sur quatre chiffres, avec des points, des tabulations ou des tirets | `dd` [.\t-] `mm` [.-] `YY` | "30-6-2008", "22.12.1978"
Jour, mois et année sur deux chiffres, avec des points ou des tabulations | `dd` [.\t] `mm` "." `yy` | "30.6.08", "22\t12.78"
Jour, mois textuel et année | `dd` ([ \t.-])* `m` ([ \t.-])* `y` | "30-June 2008", "22DEC78", "14 III 1879"
Mois textuel et année sur quatre chiffres (le jour sera le 1) | `m` ([ \t.-])* `YY` | "June 2008", "DEC1978", "March 1879"
Année sur quatre chiffres et mois textuel (le jour sera le 1) | `YY` ([ \t.-])* `m` | "2008 June", "1978-XII", "1879.MArCH"
Mois textuel, jour et année | `m` ([ .\t-])* `dd` [,.stndrh\t ]+ `y` | "July 1st, 2008", "April 17, 1790", "May.9,78"
Mois textuel et jour | `m` ([ .\t-])* `dd` [,.stndrh\t ]* | "July 1st,", "Apr 17", "May.9"
Jour et mois textuel | `dd` ([ .\t-])* `m` | "1 July", "17 Apr", "9.May"
Mois abrégé, jour et année | `M` "-" `DD` "-" `y` | "May-09-78", "Apr-17-1790"
Année, mois abrégé et jour | `y` "-" `M` "-" `DD` | "78-Dec-22", "1814-MAY-17"
Année (et juste l'année) | `YY` | "1978", "2008"
Année (développé, 5-19 chiffres avec signe) | [+-] `YYY` | "-81120", "+20192"
Mois textuel (et juste le mois) | `m` | "March", "jun", "DEC"

Notations ISO8601
Description | Format | Exemples
--- | --- | ---
Année, mois et jour sur huit chiffres | `YY` `MM` `DD` | "15810726", "19780417", "18140517"
Année sur quatre chiffres, mois et jour avec des slashes | `YY` "/" `MM` "/" `DD` | "2008/06/30", "1978/12/22"
Année sur deux chiffres, mois et jour avec des tirets | `yy` "-" `MM` "-" `DD` | "08-06-30", "78-12-22"
Année sur quatre chiffres avec un signe optionnel, mois et jour | [+-]? `YY` "-" `MM` "-" `DD` | "-0002-07-26", "+1978-04-17", "1814-05-17"
Année à cinq chiffres avec le signe, le mois et le jour requis | [+-] `YYY` "-" `MM` "-" `DD` | "-81120-02-26", "+20192-04-17"

> Note:

> Pour les formats `y` et `yy`, les années avant 100 sont considérées d'une manière spéciale lorsque les symboles `y` ou `yy` sont utilisés. Si l'année est comprise entre 0 (inclusif) et 69 (inclusif), 2000 sera ajouté. Si l'année est comprise entre 70 (inclusif) et 99 (inclusif) alors 1900 sera ajouté. Cela signifie que "00-01-01" est interprété comme "2000-01-01".

> Note:

> Le format "Jour, mois et année sur deux chiffres avec tabulations ou points" (`dd` [.\t] `mm` "." `yy`) ne fonctionne que pour des valeurs d'années de 61 (inclusif) à 99 (inclusif) - en dehors de ces bornes, le format du temps "`HH` [.:] `MM` [.:] `SS`" a une précédence plus forte et primera.

> Note:

> Le format "Année (et seulement l'année)" ne fonctionne de manière fiable que si une chaîne de temps a déjà été trouvée. Sinon, si l'année à quatre chiffres correspond à `HH` `MM`, ces deux éléments de date sont définis à la place.

> Pour analyser de manière cohérente seulement une année, utiliser DateTimeImmutable::createFromFormat() avec le spécificateur `Y`.

Attention

Il est possible d'ajouter ou soustraire une retenue pour les formats `dd` et `DD`. Le jour 0 signifie le dernier jour du mois précédent, les retenues positives compteront le mois suivant. Ainsi, "2008-08-00" est équivalent à "2008-07-31" et "2008-06-31" est équivalent à "2008-07-01" (juin ne possède que 30 jours).

Il est à noter que la plage de jour est limitée à 0-31 comme indiqué par l'expression régulière ci-dessus. Ainsi, "2008-06-32" n'est pas une chaîne de date valide, par exemple.

Il est aussi possible de jouer avec les retenues des formats `mm` et `MM` grâce à la valeur 0. Une valeur de mois de 0 signifie Décembre de l'année précédente. Par exemple "2008-00-22" est équivalent à "2007-12-22".

Si l'on combine les deux notions précédentes et utilise une retenue négative sur le jour et le mois, alors il se passe ceci : "2008-00-00" est converti d'abord vers "2007-12-00" puis vers "2007-11-30". Ceci arrive aussi avec la chaîne "0000-00-00" qui est alors transformée vers "-0001-11-30" (l'année -1 dans le calendrier ISO 8601, qui est 2 BC dans le calendrier Grégorien).

## Formats composés

Cette page décrit les différents formats dans une syntaxe de type BNF que les analyseurs de DateTimeImmutable, DateTime, date_create(), date_create_immutable(), et strtotime() comprennent.

Pour formater des objets DateTimeImmutable et DateTime, se référer à la documentation de la méthode DateTimeInterface::format().

Symboles utilisés
Description | Formats | Exemples
--- | --- | ---
`DD` | "0" [0-9] | [1-2][0-9] | "3" [01] | "02", "12", "31"
`doy` | "00"[1-9] | "0"[1-9][0-9] | [1-2][0-9][0-9] | "3"[0-5][0-9] | "36"[0-6] | "001", "012", "180", "350", "366"
`frac` | . [0-9]+ | ".21342", ".85"
`hh` | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` | [01][0-9] | "2"[0-4] | "04", "07", "19"
`méridien` | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`ii` | [0-5]?[0-9] | "04", "8", "59"
`II` | [0-5][0-9] | "04", "08", "59"
`M` | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`MM` | [0-1][0-9] | "00", "12"
`espace` | [ \t] |
`ss` | ([0-5]?[0-9])|60 | "04", "8", "59", "60" (seconde intercalaire)
`SS` | [0-5][0-9] | "04", "08", "59"
`W` | "0"[1-9] | [1-4][0-9] | "5"[0-3] | "05", "17", "53"
`tzcorrection` | "GMT"? [+-] `hh` ":"? `II`? | "+0400", "GMT-07:00", "-07:00"
`YY` | [0-9]{4} | "2000", "2008", "1978"

Formats standards
Description | Exemples
--- | ---
ATOM | "2022-06-02T16:58:35+00:00"
COOKIE | "Thursday, 02-Jun-2022 16:58:35 UTC"
ISO8601 | "2022-06-02T16:58:35+0000"
» RFC 822 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 850 | "Thursday, 02-Jun-22 16:58:35 UTC"
» RFC 1036 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 1123 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 2822 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 3339 | "2022-06-02T16:58:35+00:00"
» RFC 3339 Extended | "2022-06-02T16:58:35.698+00:00"
» RFC 7231 | "Thu, 02 Jun 2022 16:58:35 GMT"
RSS | "Thu, 02 Jun 2022 16:58:35 +0000"
W3C | "2022-06-02T16:58:35+00:00"

Notations localisées
Description | Format | Exemples
--- | --- | ---
Format de log commun | `dd` "/" `M` "/" `YY` : `HH` ":" `II` ":" `SS` `space` `tzcorrection` | "10/Oct/2000:13:55:36 -0700"
EXIF | `YY` ":" `MM` ":" `DD` " " `HH` ":" `II` ":" `SS` | "2008:08:07 18:11:31"
Année ISO avec semaine ISO | `YY` "-"? "W" `W` | "2008W27", "2008-W28"
Année ISO avec semaine ISO et jour | `YY` "-"? "W" `W` "-"? [0-7] | "2008W273", "2008-W28-3"
MySQL | `YY` "-" `MM` "-" `DD` " " `HH` ":" `II` ":" `SS` | "2008-08-07 18:11:31"
PostgreSQL : Année avec jour de l'année | `YY` "."? `doy` | "2008.197", "2008197"
SOAP | `YY` "-" `MM` "-" `DD` "T" `HH` ":" `II` ":" `SS` `frac` `tzcorrection`? | "2008-07-01T22:35:17.02", "2008-07-01T22:35:17.03+08:00"
Unix Timestamp | "@" "-"? [0-9]+ | "@1215282385"
Unix Timestamp avec les microsecondes | "@" "-"? [0-9]+ "." [0-9]{0,6} | "@1607974647.503686"
XMLRPC | `YY` `MM` `DD` "T" `hh` ":" `II` ":" `SS` | "20080701T22:38:07", "20080701T9:38:07"
XMLRPC (Compact) | `YY` `MM` `DD` 't' `hh` `II` `SS` | "20080701t223807", "20080701T093807"
WDDX | `YY` "-" `mm` "-" `dd` "T" `hh` ":" `ii` ":" `ss` | "2008-7-1T9:3:37"

> Note:

> Le "W" dans les formats "Année ISO avec semaine ISO" et "Année ISO avec semaine ISO et jour" est sensible à la casse ; l'on ne peut utiliser que la majuscule "W".

> Le "T" dans les formats SOAP, XMLRPC et WDDX est sensible à la casse ; utiliser toujours la majuscule "T".

> Le format timestamp Unix définit le fuseau horaire à UTC.

## Formats relatifs

Cette page décrit les différents formats dans une syntaxe de type BNF que les analyseurs de DateTimeImmutable, DateTime, date_create(), date_create_immutable(), et strtotime() comprennent.

Pour formater des objets DateTimeImmutable et DateTime, se référer à la documentation de la méthode DateTimeInterface::format().

Symboles utilisés
Description | Format
--- | ---
`dayname` | 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
`daytext` | 'weekday' | 'weekdays'
`number` | [+-]?[0-9]+
`ordinal` | 'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | 'next' | 'last' | 'previous' | 'this'
`reltext` | 'next' | 'last' | 'previous' | 'this'
`space` | [ \t]+
`unit` | 'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond' | 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | `daytext`

Notations basées sur le jour
Format | Description | Exemples
--- | --- | ---
'yesterday' | Minuit d'hier | "yesterday 14:00"
'midnight' | Le temps est affecté à 00:00:00 |
'today' | Le temps est affecté à 00:00:00 |
'now' | Maintenant |
'noon' | Le temps est affecté à 12:00:00 | "yesterday noon"
'tomorrow' | Minuit de demain |
'back of' `hour` | 15 minutes avant l'heure précisée | "back of 7pm", "back of 15"
'front of' `hour` | 15 minutes après l'heure spécifiée | "front of 5am", "front of 23"
'first day of' | Affecte le jour du premier jour du mois courant. Il est généralement préférable d'utiliser cette expression avec le nom du mois qui suit, car elle ne concerne que le mois en cours. | "first day of January 2008"
'last day of' | Affecte le jour du dernier jour du mois courant. Il est généralement préférable d'utiliser cette expression avec le nom du mois qui suit, car elle ne concerne que le mois en cours. | "last day of next month"
`ordinal` `space` `dayname` `space` 'of' | Calcule le `x`-ème jour de semaine du mois en cours. | "first sat of July 2008"
'last' `space` `dayname` `space` 'of' | Calcule le dernier jour de semaine du mois en cours. | "last sat of July 2008"
`number` `space`? (`unit` | 'week') | Gère des temps relatifs dont la valeur est dénombrée. | "+5 weeks", "12 day", "-7 weekdays"
(`ordinal` | `reltext`) `space` `unit` | Gère les éléments temporels relatifs dont la valeur est un texte. `last` et `previous` sont équivalents à `-1`, `this` à 0, et `next` à `+1`. | "fifth day", "second month", "last day", "previous year"
'ago' | Utilise dans le passé toute description de temps relatif ('il y a'). | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago"
`dayname` | Se déplace vers le prochain jour indiqué.(Voir note) | "Monday"
`reltext` `space` 'week' | Gère le format spécial "weekday + last/this/next week". | "Monday next week"

> Note:

> Les expressions relatives sont toujours traitées après les expressions non relatives. Ceci fait en sorte que "+1 week july 2008" et "july 2008 +1 week" sont équivalents.

> "yesterday", "midnight", "today", "noon" et "tomorrow" sont des exceptions à cette règle. Il est à noter que "tomorrow 11:00" et "11:00 tomorrow" sont différents. Soit la date d'aujourd'hui à "July 23rd, 2008", la première expression donne "2008-07-24 11:00" alors que la seconde donnera "2008-07-24 00:00". La raison est que ces cinq expressions influencent directement la date courante.

> Les mots clés tels que "first day of" dépendent du contexte dans lequel la chaîne de format relative est utilisée. Si utilisé avec une méthode statique ou une fonction, le référent est l'horodatage actuel du système. Cependant, si utilisé dans DateTime::modify() ou DateTimeImmutable::modify(), le référent est l'objet sur lequel la méthode `modify()` est appelée.

> Note:

> Il est à noter les remarques qui suivent lorsque le jour de semaine courant est le même que le jour de semaine utilisé dans la chaîne de date/time. Le jour de semaine courant aurait pu être recalculé par rapport aux parties non relatives de la chaîne date/time.

> 1. "`dayname`" n'avance pas vers un autre jour. (Exemple : "Wed July 23rd, 2008" signifie "2008-07-23").
> 2. "`number` `dayname`" n'avance pas vers un autre jour. (Exemple : "1 wednesday july 23rd, 2008" signifie "2008-07-23").
> 3. "`number` week `dayname`" ajoutera d'abord le nombre de semaines, mais n'avancera pas vers un autre jour. Dans ce cas "`number` week" et "`dayname`" sont deux blocs distincts. (Exemple : "+1 week wednesday july 23rd, 2008" signifie "2008-07-30").
> 4. "`ordinal` `dayname`" avance vers un autre jour. (Exemple : "first wednesday july 23rd, 2008" signifie "2008-07-30").
> 5. "`number` week `ordinal` `dayname`" ajoutera d'abord le nombre de semaines et ensuite avancera vers un autre jour. Dans ce cas, "`number` week" et "`ordinal` `dayname`" sont deux blocs distincts. (Exemple : "+1 week first wednesday july 23rd, 2008" signifie "2008-08-06").
> 6. "`ordinal` `dayname` 'of' " n'avance pas vers un autre jour. (Exemple : "first wednesday of july 23rd, 2008" signifie "2008-07-02" car la phrase avec 'of' remet à zéro le jour du mois vers '1' et le '23' sera ignoré).

> Il est à noter que le "of" dans "`ordinal` `space` `dayname` `space` 'of' " et "'last' `space` `dayname` `espace` 'of' " fait quelque chose de spécial.

> 1. Il affecte le jour du mois à 1.
> 2. "`ordinal` `dayname` 'of' " n'avance pas vers un autre jour. (Exemple : "first tuesday of july 2008" signifie "2008-07-01").
> 3. "`ordinal` `dayname` " avance vers un autre jour. (Exemple : "first tuesday july 2008" signifie "2008-07-08", voir aussi le point numéro 4 de la liste ci-dessus).
> 4. "'last' `dayname` 'of' " prend le dernier `dayname` du mois courant. (Exemple : "last wed of july 2008" signifie "2008-07-30")
> 5. "'last' `dayname`" prend le dernier `dayname` à partir du jour actuel. (Exemple : "last wed july 2008" signifie "2008-06-25"; "july 2008" affecte d'abord la date courante à "2008-07-01" et ensuite "last wed" remonte au dernier mercredi qui est le "2008-06-25").

> Note:

> Les valeurs relatives des mois calculés sont basées sur le nombre de jours des mois que l'on utilise. Par exemple, "+2 month 2011-11-30", donnera comme résultat la date "2012-01-30". Ceci est dû au fait que le mois de novembre comporte 30 jours, et que le mois de décembre en comporte 31, soit un ajout total de 61 jours.

> Note:

> `number` est un nombre entier ; si un nombre décimal est donné, le point (ou la virgule) sera probablement interprété comme un délimiteur. Par exemple, `'+1.5 hours'` sera analysé en tant que `'+1 5 hours'`, et non pas comme `'+1 hour +30 minutes'`.

### Historique

Version | Description
--- | ---
8.4.0 | `number` accepte désormais un signe plus suivi d'un signe moins, par exemple `+-2`, et d'autres combinaisons de plusieurs signes.
8.2.0 | `number` n'accepte plus un signe plus suivi d'un signe moins, exemple `+-2`.
7.0.8 | Les semaines commencent toujours le lundi. Autrefois, le dimanche était également considéré pour commencer une semaine.

# Liste des Fuseaux Horaires Supportés

## Sommaire

- Afrique
- Amérique
- Antarctique
- Arctique
- Asie
- Atlantique
- Australie
- Europe
- Indien
- Pacifique
- Autres

Ici, vous trouverez une liste complète des fuseaux horaires supportés par PHP, qui peuvent être utilisés avec, e.g. date_default_timezone_set().

Attention

Le comportement des fuseaux horaires qui ne sont pas listés ici est indéfini.

> Note: La dernière version de la base de données des fuseaux horaires peut être installée via la commande PECL » timezonedb.

> Note: Cette liste est basée sur la version de la base de données des fuseaux horaires 2026.1.

## Afrique

Afrique
Africa/Abidjan | Africa/Accra | Africa/Addis_Ababa | Africa/Algiers
Africa/Asmara | Africa/Bamako | Africa/Bangui | Africa/Banjul
Africa/Bissau | Africa/Blantyre | Africa/Brazzaville | Africa/Bujumbura
Africa/Cairo | Africa/Casablanca | Africa/Ceuta | Africa/Conakry
Africa/Dakar | Africa/Dar_es_Salaam | Africa/Djibouti | Africa/Douala
Africa/El_Aaiun | Africa/Freetown | Africa/Gaborone | Africa/Harare
Africa/Johannesburg | Africa/Juba | Africa/Kampala | Africa/Khartoum
Africa/Kigali | Africa/Kinshasa | Africa/Lagos | Africa/Libreville
Africa/Lome | Africa/Luanda | Africa/Lubumbashi | Africa/Lusaka
Africa/Malabo | Africa/Maputo | Africa/Maseru | Africa/Mbabane
Africa/Mogadishu | Africa/Monrovia | Africa/Nairobi | Africa/Ndjamena
Africa/Niamey | Africa/Nouakchott | Africa/Ouagadougou | Africa/Porto-Novo
Africa/Sao_Tome | Africa/Tripoli | Africa/Tunis | Africa/Windhoek

## Amérique

Amérique
America/Adak | America/Anchorage | America/Anguilla | America/Antigua
America/Araguaina | America/Argentina/Buenos_Aires | America/Argentina/Catamarca | America/Argentina/Cordoba
America/Argentina/Jujuy | America/Argentina/La_Rioja | America/Argentina/Mendoza | America/Argentina/Rio_Gallegos
America/Argentina/Salta | America/Argentina/San_Juan | America/Argentina/San_Luis | America/Argentina/Tucuman
America/Argentina/Ushuaia | America/Aruba | America/Asuncion | America/Atikokan
America/Bahia | America/Bahia_Banderas | America/Barbados | America/Belem
America/Belize | America/Blanc-Sablon | America/Boa_Vista | America/Bogota
America/Boise | America/Cambridge_Bay | America/Campo_Grande | America/Cancun
America/Caracas | America/Cayenne | America/Cayman | America/Chicago
America/Chihuahua | America/Ciudad_Juarez | America/Costa_Rica | America/Coyhaique
America/Creston | America/Cuiaba | America/Curacao | America/Danmarkshavn
America/Dawson | America/Dawson_Creek | America/Denver | America/Detroit
America/Dominica | America/Edmonton | America/Eirunepe | America/El_Salvador
America/Fort_Nelson | America/Fortaleza | America/Glace_Bay | America/Goose_Bay
America/Grand_Turk | America/Grenada | America/Guadeloupe | America/Guatemala
America/Guayaquil | America/Guyana | America/Halifax | America/Havana
America/Hermosillo | America/Indiana/Indianapolis | America/Indiana/Knox | America/Indiana/Marengo
America/Indiana/Petersburg | America/Indiana/Tell_City | America/Indiana/Vevay | America/Indiana/Vincennes
America/Indiana/Winamac | America/Inuvik | America/Iqaluit | America/Jamaica
America/Juneau | America/Kentucky/Louisville | America/Kentucky/Monticello | America/Kralendijk
America/La_Paz | America/Lima | America/Los_Angeles | America/Lower_Princes
America/Maceio | America/Managua | America/Manaus | America/Marigot
America/Martinique | America/Matamoros | America/Mazatlan | America/Menominee
America/Merida | America/Metlakatla | America/Mexico_City | America/Miquelon
America/Moncton | America/Monterrey | America/Montevideo | America/Montserrat
America/Nassau | America/New_York | America/Nome | America/Noronha
America/North_Dakota/Beulah | America/North_Dakota/Center | America/North_Dakota/New_Salem | America/Nuuk
America/Ojinaga | America/Panama | America/Paramaribo | America/Phoenix
America/Port-au-Prince | America/Port_of_Spain | America/Porto_Velho | America/Puerto_Rico
America/Punta_Arenas | America/Rankin_Inlet | America/Recife | America/Regina
America/Resolute | America/Rio_Branco | America/Santarem | America/Santiago
America/Santo_Domingo | America/Sao_Paulo | America/Scoresbysund | America/Sitka
America/St_Barthelemy | America/St_Johns | America/St_Kitts | America/St_Lucia
America/St_Thomas | America/St_Vincent | America/Swift_Current | America/Tegucigalpa
America/Thule | America/Tijuana | America/Toronto | America/Tortola
America/Vancouver | America/Whitehorse | America/Winnipeg | America/Yakutat

## Antarctique

Antarctique
Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie
Antarctica/Mawson | Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera
Antarctica/Syowa | Antarctica/Troll | Antarctica/Vostok |

## Arctique

Arctique
Arctic/Longyearbyen

## Asie

Asie
Asia/Aden | Asia/Almaty | Asia/Amman | Asia/Anadyr
Asia/Aqtau | Asia/Aqtobe | Asia/Ashgabat | Asia/Atyrau
Asia/Baghdad | Asia/Bahrain | Asia/Baku | Asia/Bangkok
Asia/Barnaul | Asia/Beirut | Asia/Bishkek | Asia/Brunei
Asia/Chita | Asia/Colombo | Asia/Damascus | Asia/Dhaka
Asia/Dili | Asia/Dubai | Asia/Dushanbe | Asia/Famagusta
Asia/Gaza | Asia/Hebron | Asia/Ho_Chi_Minh | Asia/Hong_Kong
Asia/Hovd | Asia/Irkutsk | Asia/Jakarta | Asia/Jayapura
Asia/Jerusalem | Asia/Kabul | Asia/Kamchatka | Asia/Karachi
Asia/Kathmandu | Asia/Khandyga | Asia/Kolkata | Asia/Krasnoyarsk
Asia/Kuala_Lumpur | Asia/Kuching | Asia/Kuwait | Asia/Macau
Asia/Magadan | Asia/Makassar | Asia/Manila | Asia/Muscat
Asia/Nicosia | Asia/Novokuznetsk | Asia/Novosibirsk | Asia/Omsk
Asia/Oral | Asia/Phnom_Penh | Asia/Pontianak | Asia/Pyongyang
Asia/Qatar | Asia/Qostanay | Asia/Qyzylorda | Asia/Riyadh
Asia/Sakhalin | Asia/Samarkand | Asia/Seoul | Asia/Shanghai
Asia/Singapore | Asia/Srednekolymsk | Asia/Taipei | Asia/Tashkent
Asia/Tbilisi | Asia/Tehran | Asia/Thimphu | Asia/Tokyo
Asia/Tomsk | Asia/Ulaanbaatar | Asia/Urumqi | Asia/Ust-Nera
Asia/Vientiane | Asia/Vladivostok | Asia/Yakutsk | Asia/Yangon
Asia/Yekaterinburg | Asia/Yerevan |  |

## Atlantique

Atlantique
Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde
Atlantic/Faroe | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia
Atlantic/St_Helena | Atlantic/Stanley |  |

## Australie

Australie
Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Darwin
Australia/Eucla | Australia/Hobart | Australia/Lindeman | Australia/Lord_Howe
Australia/Melbourne | Australia/Perth | Australia/Sydney |

## Europe

Europe
Europe/Amsterdam | Europe/Andorra | Europe/Astrakhan | Europe/Athens
Europe/Belgrade | Europe/Berlin | Europe/Bratislava | Europe/Brussels
Europe/Bucharest | Europe/Budapest | Europe/Busingen | Europe/Chisinau
Europe/Copenhagen | Europe/Dublin | Europe/Gibraltar | Europe/Guernsey
Europe/Helsinki | Europe/Isle_of_Man | Europe/Istanbul | Europe/Jersey
Europe/Kaliningrad | Europe/Kirov | Europe/Kyiv | Europe/Lisbon
Europe/Ljubljana | Europe/London | Europe/Luxembourg | Europe/Madrid
Europe/Malta | Europe/Mariehamn | Europe/Minsk | Europe/Monaco
Europe/Moscow | Europe/Oslo | Europe/Paris | Europe/Podgorica
Europe/Prague | Europe/Riga | Europe/Rome | Europe/Samara
Europe/San_Marino | Europe/Sarajevo | Europe/Saratov | Europe/Simferopol
Europe/Skopje | Europe/Sofia | Europe/Stockholm | Europe/Tallinn
Europe/Tirane | Europe/Ulyanovsk | Europe/Vaduz | Europe/Vatican
Europe/Vienna | Europe/Vilnius | Europe/Volgograd | Europe/Warsaw
Europe/Zagreb | Europe/Zurich |  |

## Indien

Indien
Indian/Antananarivo | Indian/Chagos | Indian/Christmas | Indian/Cocos
Indian/Comoro | Indian/Kerguelen | Indian/Mahe | Indian/Maldives
Indian/Mauritius | Indian/Mayotte | Indian/Reunion |

## Pacifique

Pacifique
Pacific/Apia | Pacific/Auckland | Pacific/Bougainville | Pacific/Chatham
Pacific/Chuuk | Pacific/Easter | Pacific/Efate | Pacific/Fakaofo
Pacific/Fiji | Pacific/Funafuti | Pacific/Galapagos | Pacific/Gambier
Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Kanton
Pacific/Kiritimati | Pacific/Kosrae | Pacific/Kwajalein | Pacific/Majuro
Pacific/Marquesas | Pacific/Midway | Pacific/Nauru | Pacific/Niue
Pacific/Norfolk | Pacific/Noumea | Pacific/Pago_Pago | Pacific/Palau
Pacific/Pitcairn | Pacific/Pohnpei | Pacific/Port_Moresby | Pacific/Rarotonga
Pacific/Saipan | Pacific/Tahiti | Pacific/Tarawa | Pacific/Tongatapu
Pacific/Wake | Pacific/Wallis |  |

## Autres

Avertissement

N'utilisez aucun des fuseaux horaires listés ici (excepté UTC), ils n'existent que pour des raisons de compatibilité ascendante et leur comportement peut provoquer des erreurs. De plus, ces fuseaux horaires peuvent être supprimée de la base de donnée IANA de fuseaux horaire à tout moment.

Avertissement

Si vous ne tenez pas compte de l'avertissement précédent, veuillez prendre note que la base de données de l'IANA qui fournit le support des fuseaux horaires dans PHP utilise les signes POSIX ce qui signifie que les zones `Etc/GMT+n` et `Etc/GMT-n` sont inversées par rapport à l'usage commun.

Par exemple, le fuseau horaire 8 heures après GMT qui est utilisé en Chine et en Australie occidentale est actuellement `Etc/GMT-8` dans cette base de données, et non `Etc/GMT+8` comme on pourrait s'y attendre.

Une fois encore, il est fortement recommandé que vous utilisiez le bon fuseau horaire pour votre emplacement, tel que `Asia/Shanghai` ou `Australia/Perth` pour les exemples précédents.

Autres
Africa/Asmera | Africa/Timbuktu | America/Argentina/ComodRivadavia | America/Atka
America/Buenos_Aires | America/Catamarca | America/Coral_Harbour | America/Cordoba
America/Ensenada | America/Fort_Wayne | America/Godthab | America/Indianapolis
America/Jujuy | America/Knox_IN | America/Louisville | America/Mendoza
America/Montreal | America/Nipigon | America/Pangnirtung | America/Porto_Acre
America/Rainy_River | America/Rosario | America/Santa_Isabel | America/Shiprock
America/Thunder_Bay | America/Virgin | America/Yellowknife | Antarctica/South_Pole
Asia/Ashkhabad | Asia/Calcutta | Asia/Choibalsan | Asia/Chongqing
Asia/Chungking | Asia/Dacca | Asia/Harbin | Asia/Istanbul
Asia/Kashgar | Asia/Katmandu | Asia/Macao | Asia/Rangoon
Asia/Saigon | Asia/Tel_Aviv | Asia/Thimbu | Asia/Ujung_Pandang
Asia/Ulan_Bator | Atlantic/Faeroe | Atlantic/Jan_Mayen | Australia/ACT
Australia/Canberra | Australia/Currie | Australia/LHI | Australia/North
Australia/NSW | Australia/Queensland | Australia/South | Australia/Tasmania
Australia/Victoria | Australia/West | Australia/Yancowinna | Brazil/Acre
Brazil/DeNoronha | Brazil/East | Brazil/West | Canada/Atlantic
Canada/Central | Canada/Eastern | Canada/Mountain | Canada/Newfoundland
Canada/Pacific | Canada/Saskatchewan | Canada/Yukon | CET
Chile/Continental | Chile/EasterIsland | CST6CDT | Cuba
EET | Egypt | Eire | EST
EST5EDT | Etc/GMT | Etc/GMT+0 | Etc/GMT+1
Etc/GMT+10 | Etc/GMT+11 | Etc/GMT+12 | Etc/GMT+2
Etc/GMT+3 | Etc/GMT+4 | Etc/GMT+5 | Etc/GMT+6
Etc/GMT+7 | Etc/GMT+8 | Etc/GMT+9 | Etc/GMT-0
Etc/GMT-1 | Etc/GMT-10 | Etc/GMT-11 | Etc/GMT-12
Etc/GMT-13 | Etc/GMT-14 | Etc/GMT-2 | Etc/GMT-3
Etc/GMT-4 | Etc/GMT-5 | Etc/GMT-6 | Etc/GMT-7
Etc/GMT-8 | Etc/GMT-9 | Etc/GMT0 | Etc/Greenwich
Etc/UCT | Etc/Universal | Etc/UTC | Etc/Zulu
Europe/Belfast | Europe/Kiev | Europe/Nicosia | Europe/Tiraspol
Europe/Uzhgorod | Europe/Zaporozhye | Factory | GB
GB-Eire | GMT | GMT+0 | GMT-0
GMT0 | Greenwich | Hongkong | HST
Iceland | Iran | Israel | Jamaica
Japan | Kwajalein | Libya | MET
Mexico/BajaNorte | Mexico/BajaSur | Mexico/General | MST
MST7MDT | Navajo | NZ | NZ-CHAT
Pacific/Enderbury | Pacific/Johnston | Pacific/Ponape | Pacific/Samoa
Pacific/Truk | Pacific/Yap | Poland | Portugal
PRC | PST8PDT | ROC | ROK
Singapore | Turkey | UCT | Universal
US/Alaska | US/Aleutian | US/Arizona | US/Central
US/East-Indiana | US/Eastern | US/Hawaii | US/Indiana-Starke
US/Michigan | US/Mountain | US/Pacific | US/Samoa
UTC | W-SU | WET | Zulu

# La classe DateError

(PHP 8 >= 8.3.0)

## Introduction

Lancée quand la base de données des fuseaux horaires n'est pas trouvée, ou contient des données invalides.

Cette erreur ne devrait jamais se produire, et ne dépend pas du code. Il y a deux exceptions enfants (DateObjectError et DateRangeError) qui sont lancées en fonction des erreurs du développeur ou des problèmes de plage.

## Synopsis de la classe

class DateError extends Error {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Voir aussi

- DateObjectError
- DateRangeError

# La classe DateObjectError

(PHP 8 >= 8.3.0)

## Introduction

Lancée lorsqu'une des classes Date/Heure n'a pas été correctement initialisée.

Parce que les classes Date/Heure ne sont pas finales, ces classes peuvent être héritées. Quand le constructeur parent n'est pas appelé, cette erreur est lancée. C'est toujours une erreur de programmation.

## Synopsis de la classe

class DateObjectError extends DateError {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Voir aussi

- DateError
- DateRangeError

# La classe DateRangeError

(PHP 8 >= 8.3.0)

## Introduction

Lancée par DateTime::getTimestamp(), DateTimeImmutable::getTimestamp(), et date_timestamp_get(), sur les plateformes 32 bits si l'objet date représente une date en dehors de la plage signée 32 bits.

## Synopsis de la classe

class DateRangeError extends DateError {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Voir aussi

- DateError
- DateObjectError

# La classe DateException

(PHP 8 >= 8.3.0)

## Introduction

Classe parente de toutes les exceptions Date/Time, pour les problèmes qui sont liés aux entrées utilisateur, ou aux arguments textuels libres qui doivent être analysés.

Les exceptions enfants suivantes sont lancées par l'extension :

- DateInvalidOperationException
- DateInvalidTimezoneException
- DateMalformedIntervalStringException
- DateMalformedPeriodStringException
- DateMalformedStringException

## Synopsis de la classe

class DateException extends Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe DateInvalidOperationException

(PHP 8 >= 8.3.0)

## Introduction

Lancée par DateTimeImmutable::sub() et DateTime::sub() lorsqu'une opération non supportée est tentée.

Un exemple d'opération non supportée est l'utilisation d'un objet DateInterval représentant des spécifications de temps relatives telles que `next weekday`, car aucune déclaration logique inversée ne peut être construite.

## Synopsis de la classe

class DateInvalidOperationException extends DateException {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe DateInvalidTimeZoneException

(PHP 8 >= 8.3.0)

## Introduction

Lancée lorsqu'une valeur incorrecte est passée à DateTimeZone::__construct().

## Synopsis de la classe

class DateInvalidTimeZoneException extends DateException {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe DateMalformedIntervalStringException

(PHP 8 >= 8.3.0)

## Introduction

Lancée lorsqu'un argument `duration` invalide est passé à DateInterval::__construct().

## Synopsis de la classe

class DateMalformedIntervalStringException extends DateException {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe DateMalformedPeriodStringException

(PHP 8 >= 8.3.0)

## Introduction

Lancée lorsqu'un argument `isostr` invalide est passé à DatePeriod::__construct().

## Synopsis de la classe

class DateMalformedPeriodStringException extends DateException {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe DateMalformedStringException

(PHP 8 >= 8.3.0)

## Introduction

Lancée lorsqu'une chaîne de Date/Heure invalide est détectée.

Cela peut être une valeur passée à DateTimeImmutable::__construct(), DateTimeImmutable::modify(), DateTime::__construct(), ou DateTime::modify().

## Synopsis de la classe

class DateMalformedStringException extends DateException {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Installation/Configuration
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Exemples
  - Arithmétique avec DateTime
- DateTime — La classe DateTime
  - DateTime::add — Modifie un objet DateTime, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté
  - DateTime::__construct — Retourne un nouvel objet DateTime
  - DateTime::createFromFormat — Analyse une heure au format texte selon le format spécifié.
  - DateTime::createFromImmutable — Retourne une nouvelle instance d'objet DateTime encapsulant l'objet DateTimeImmutable fourni
  - DateTime::createFromInterface — Retourne un nouvel objet DateTime encapsulant l'objet DateTimeInterface fourni
  - DateTime::createFromTimestamp — Crée une instance à partir d'un horodatage Unix
  - DateTime::getLastErrors — Alias de DateTimeImmutable::getLastErrors
  - DateTime::modify — Modifie le timestamp
  - DateTime::__set_state — Le gestionnaire __set_state
  - DateTime::setDate — Assigne la date
  - DateTime::setISODate — Configure une date ISO
  - DateTime::setMicrosecond — Définit la partie microseconde de l'heure
  - DateTime::setTime — Assigne l'heure
  - DateTime::setTimestamp — Assigne la date et l'heure à l'aide d'un horodatage Unix
  - DateTime::setTimezone — Configure le fuseau horaire de l'objet DateTime
  - DateTime::sub — Soustrait une durée à un objet DateTime
- DateTimeImmutable — La classe DateTimeImmutable
  - DateTimeImmutable::add — Retourne un nouvel objet, avec le nombre de jours, mois, années, heures, minutes et secondes ajouté
  - DateTimeImmutable::__construct — Retourne un nouvel objet DateTimeImmutable
  - DateTimeImmutable::createFromFormat — Analyse une heure au format texte selon le format spécifié.
  - DateTimeImmutable::createFromInterface — Retourne un nouvel objet DateTimeImmutable encapsulant l'objet DateTimeInterface fourni
  - DateTimeImmutable::createFromMutable — Retourne une nouvelle instance de DateTimeImmutable encapsulant l'objet DateTime fourni
  - DateTimeImmutable::createFromTimestamp — Crée une instance à partir d'un horodatage Unix
  - DateTimeImmutable::getLastErrors — Retourne les alertes et erreurs
  - DateTimeImmutable::modify — Crée un nouvel objet avec l'horodatage modifié
  - DateTimeImmutable::__set_state — Le gestionnaire __set_state
  - DateTimeImmutable::setDate — Définit la date
  - DateTimeImmutable::setISODate — Définit la date ISO
  - DateTimeImmutable::setMicrosecond — Définit la partie microseconde de l'heure
  - DateTimeImmutable::setTime — Définit l'horaire
  - DateTimeImmutable::setTimestamp — Définit la date et l'heure basées sur un horodatage Unix
  - DateTimeImmutable::setTimezone — Définit le fuseau horaire
  - DateTimeImmutable::sub — Soustrait un nombre de jours, mois, années, heures et secondes
- DateTimeInterface — L'interface DateTimeInterface
  - DateTimeInterface::diff — Retourne la différence entre deux objets DateTime
  - DateTimeInterface::format — Retourne une date formatée suivant le format fourni
  - DateTimeInterface::getMicrosecond — Récupère la partie microseconde de l'horodatage Unix
  - DateTimeInterface::getOffset — Retourne le décalage horaire
  - DateTimeInterface::getTimestamp — Récupère le timestamp Unix
  - DateTimeInterface::getTimezone — Retourne le fuseau horaire relatif au DateTime fourni
  - DateTime::__serialize — Sérialise un DateTime
  - DateTime::__unserialize — Désérialise un DateTime
  - DateTime::__wakeup — Le gestionnaire __wakeup
- DateTimeZone — La classe DateTimeZone
  - DateTimeZone::__construct — Crée un nouvel objet DateTimeZone
  - DateTimeZone::getLocation — Retourne les informations géographiques d'un fuseau horaire
  - DateTimeZone::getName — Retourne le nom du fuseau horaire
  - DateTimeZone::getOffset — Retourne le décalage GMT d'un fuseau horaire
  - DateTimeZone::getTransitions — Retourne toutes les transitions d'un fuseau horaire
  - DateTimeZone::listAbbreviations — Retourne un tableau associatif, décrivant un fuseau horaire
  - DateTimeZone::listIdentifiers — Retourne un tableau numérique contenant tous les identifiants de fuseaux horaires définis
- DateInterval — La classe DateInterval
  - DateInterval::__construct — Crée un nouvel objet DateInterval
  - DateInterval::createFromDateString — Configure un objet DateInterval à partir des parties d'une chaîne
  - DateInterval::format — Formate l'intervalle
- DatePeriod — La classe DatePeriod
  - DatePeriod::__construct — Crée un nouvel objet DatePeriod
  - DatePeriod::createFromISO8601String — Crée un nouvel objet DatePeriod à partir d'une chaîne de caractères ISO8601
  - DatePeriod::getDateInterval — Retourne l'intervalle
  - DatePeriod::getEndDate — Retourne la date de fin
  - DatePeriod::getRecurrences — Récupère le nombre de récurrences
  - DatePeriod::getStartDate — Obtient la date de début
- Fonctions Date/Heure
  - checkdate — Valide une date grégorienne
  - date — Formate un horodatage Unix
  - date_add — Alias de DateTime::add
  - date_create — Création d'un objet DateTime
  - date_create_from_format — Alias de DateTime::createFromFormat
  - date_create_immutable — Crée un nouvel objet DateTimeImmutable
  - date_create_immutable_from_format — Alias de DateTimeImmutable::createFromFormat
  - date_date_set — Alias de DateTime::setDate
  - date_default_timezone_get — Récupère le décalage horaire par défaut utilisé par toutes les fonctions date/heure d'un script
  - date_default_timezone_set — Définit le décalage horaire par défaut de toutes les fonctions date/heure
  - date_diff — Alias de DateTime::diff
  - date_format — Alias de DateTime::format
  - date_get_last_errors — Alias de DateTimeImmutable::getLastErrors
  - date_interval_create_from_date_string — Alias de DateInterval::createFromDateString
  - date_interval_format — Alias de DateInterval::format
  - date_isodate_set — Alias de DateTime::setISODate
  - date_modify — Alias de DateTime::modify
  - date_offset_get — Alias de DateTime::getOffset
  - date_parse — Retourne un tableau associatif avec des informations détaillées sur une date/moment donnée
  - date_parse_from_format — Récupère les informations d'une date donnée suivant un format spécifique
  - date_sub — Alias de DateTime::sub
  - date_sun_info — Retourne un tableau avec les informations sur le lever/coucher du soleil ainsi que le début et la fin de l'aube
  - date_sunrise — Retourne l'heure de lever du soleil pour un jour et un endroit donnés
  - date_sunset — Retourne l'heure de coucher du soleil pour un jour et un endroit donnés
  - date_time_set — Alias de DateTime::setTime
  - date_timestamp_get — Alias de DateTime::getTimestamp
  - date_timestamp_set — Alias de DateTime::setTimestamp
  - date_timezone_get — Alias de DateTime::getTimezone
  - date_timezone_set — Alias de DateTime::setTimezone
  - getdate — Retourne la date/heure
  - gettimeofday — Retourne l'heure actuelle
  - gmdate — Formate une date/heure GMT/TUC
  - gmmktime — Retourne le timestamp UNIX d'une date GMT
  - gmstrftime — Formate une date/heure GMT/TUC en fonction de la configuration locale
  - idate — Formate une partie de l'heure/date locale en tant qu'entier
  - localtime — Récupère l'heure locale
  - microtime — Retourne le timestamp UNIX actuel avec les microsecondes
  - mktime — Retourne l'horodatage UNIX d'une date
  - strftime — Formate une date/heure locale avec la configuration locale
  - strptime — Analyse une date générée par strftime
  - strtotime — Transforme un texte anglais en timestamp
  - time — Retourne l'horodatage UNIX actuel
  - timezone_abbreviations_list — Alias de DateTimeZone::listAbbreviations
  - timezone_identifiers_list — Alias de DateTimeZone::listIdentifiers
  - timezone_location_get — Alias de DateTimeZone::getLocation
  - timezone_name_from_abbr — Retourne le nom d'un fuseau horaire à partir de son abréviation et de son décalage UTC
  - timezone_name_get — Alias de DateTimeZone::getName
  - timezone_offset_get — Alias de DateTimeZone::getOffset
  - timezone_open — Alias de DateTimeZone::__construct
  - timezone_transitions_get — Alias de DateTimeZone::getTransitions
  - timezone_version_get — Lit la version de la timezonedb
- Erreurs et Exceptions Date/Heure
- Formats supportés de temps et de dates
- Liste des Fuseaux Horaires Supportés
  - Afrique
  - Amérique
  - Antarctique
  - Arctique
  - Asie
  - Atlantique
  - Australie
  - Europe
  - Indien
  - Pacifique
  - Autres
- DateError — La classe DateError
- DateObjectError — La classe DateObjectError
- DateRangeError — La classe DateRangeError
- DateException — La classe DateException
- DateInvalidOperationException — La classe DateInvalidOperationException
- DateInvalidTimeZoneException — La classe DateInvalidTimeZoneException
- DateMalformedIntervalStringException — La classe DateMalformedIntervalStringException
- DateMalformedPeriodStringException — La classe DateMalformedPeriodStringException
- DateMalformedStringException — La classe DateMalformedStringException

# Gestion du temps à haute résolution

# Introduction

L'extension HRTime implémente une classe StopWatch de haute résolution. Elle utilise la meilleure des APIs sur les différentes plateformes, qui fournira une résolution à la nanoseconde. Il est également possible d'implémenter un chronomètre personnalisé en utilisant les ticks de bas niveau, délivrés par les APIs sous-jacentes.

> Note: À partir de PHP 7.3.0 la fonction liée hrtime() fait partie du cœur.

# Installation/Configuration

## Sommaire

- Installation

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/hrtime.

# Exemples

## Sommaire

- Utilisation simple

## Utilisation simple

Cet exemple montre l'utilisation basique de la classe StopWatch.

Exemple #1 Mesure l'exécution de différents blocs et retourne le total

    <?php

    $c = new HRTime\StopWatch;

    $c->start();
    /* mesure l'exécution de ce bloc de code */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $elapsed0 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    /* la mesure n'est pas en cours ici */
    for ($i = 0; $i < 1024*1024; $i++);

    $c->start();
    /* mesure l'exécution de ce bloc de code */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $elapsed1 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    $elapsed_total = $c->getElapsedTime(HRTime\Unit::NANOSECOND);

    ?>

# La classe HRTime\PerformanceCounter

(PECL hrtime >= 0.4.3)

## Introduction

## Synopsis de la classe

class HRTime\PerformanceCounter {
/* Méthodes */
public static function getFrequency(): int
public static function getTicks(): int
public static function getTicksSince(int `$start`): int
}

# HRTime\PerformanceCounter::getFrequency

(PECL hrtime >= 0.4.3)

HRTime\PerformanceCounter::getFrequency — Fréquence du timer en ticks par seconde

### Description

public static function HRTime\PerformanceCounter::getFrequency(): int

Retourne la fréquence du timer en ticks par seconde. Cette valeur est constante après le démarrage du système sur la plupart des systèmes d'exploitations.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier indiquant la fréquence du timer.

# HRTime\PerformanceCounter::getTicks

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicks — Ticks courants depuis le système

### Description

public static function HRTime\PerformanceCounter::getTicks(): int

Retourne le compte de ticks.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier indiquant le compte de ticks.

# HRTime\PerformanceCounter::getTicksSince

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicksSince — Ticks écoulés depuis la valeur fournie

### Description

public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int

Retourne le compte de ticks écoulés depuis la valeur de départ fournie.

### Liste de paramètres

`start`
  Valeur de ticks de départ.

### Valeurs de retour

Retourne un entier indiquant le compte de ticks.

## Sommaire

- HRTime\PerformanceCounter::getFrequency — Fréquence du timer en ticks par seconde
- HRTime\PerformanceCounter::getTicks — Ticks courants depuis le système
- HRTime\PerformanceCounter::getTicksSince — Ticks écoulés depuis la valeur fournie

# La classe HRTime\StopWatch

(PECL hrtime >= 0.4.3)

## Introduction

## Synopsis de la classe

class HRTime\StopWatch extends HRTime\PerformanceCounter {
/* Méthodes */
public function getElapsedTicks(): int
public function getElapsedTime(int `$unit` = ?): float
public function getLastElapsedTicks(): int
public function getLastElapsedTime(int `$unit` = ?): float
public function isRunning(): bool
public function start(): void
public function stop(): void
/* Méthodes héritées */
public static function HRTime\PerformanceCounter::getFrequency(): int
public static function HRTime\PerformanceCounter::getTicks(): int
public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int
}

# HRTime\StopWatch::getElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTicks — Récupère les ticks écoulés pour tous les intervalles

### Description

public function HRTime\StopWatch::getElapsedTicks(): int

Récupère les ticks écoulés pour tous les intervalles fermés précédents.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier indiquant les ticks écoulés.

# HRTime\StopWatch::getElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTime — Récupère le temps écoulé pour tous les intervalles

### Description

public function HRTime\StopWatch::getElapsedTime(int `$unit` = ?): float

Récupère le temps écoulé pour tous les intervalles précédents clos.

### Liste de paramètres

`unit`
  Unité de temps représentée par une constante HRTime\Unit. Par défaut vaut HRTime\Unit::SECOND.

### Valeurs de retour

Retourne un nombre décimal indiquant le temps écoulé.

# HRTime\StopWatch::getLastElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTicks — Récupère les ticks écoulés pour le dernier intervalle

### Description

public function HRTime\StopWatch::getLastElapsedTicks(): int

Récupère les ticks écoulés pour le dernier intervalle fermé.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier indiquant les ticks écoulés.

# HRTime\StopWatch::getLastElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTime — Récupère le temps écoulé pour le dernier intervalle

### Description

public function HRTime\StopWatch::getLastElapsedTime(int `$unit` = ?): float

Récupère le temps écoulé pour le dernier intervalle.

### Liste de paramètres

`unit`
  Unité de temps représentée par une constante HRTime\Unit. Par défaut vaut HRTime\Unit::SECOND.

### Valeurs de retour

Retourne un nombre décimal indiquant le temps écoulé.

# HRTime\StopWatch::isRunning

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::isRunning — Vérifie si la mesure du temps est en cours

### Description

public function HRTime\StopWatch::isRunning(): bool

Vérifie si la mesure du temps a été démarrée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un booléen indiquant si la mesure du temps est en cours.

# HRTime\StopWatch::start

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::start — Démarre la mesure du temps

### Description

public function HRTime\StopWatch::start(): void

Démarre la mesure du temps. Cette méthode n'a aucun effet si la mesure du temps a déjà été démarrée. La mesure va continuer si elle a été arrêtée précédemment.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne void.

# HRTime\StopWatch::stop

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::stop — Arrête la mesure du temps

### Description

public function HRTime\StopWatch::stop(): void

Arrête la mesure du temps pour l'intervalle précédent.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne void.

## Sommaire

- HRTime\StopWatch::getElapsedTicks — Récupère les ticks écoulés pour tous les intervalles
- HRTime\StopWatch::getElapsedTime — Récupère le temps écoulé pour tous les intervalles
- HRTime\StopWatch::getLastElapsedTicks — Récupère les ticks écoulés pour le dernier intervalle
- HRTime\StopWatch::getLastElapsedTime — Récupère le temps écoulé pour le dernier intervalle
- HRTime\StopWatch::isRunning — Vérifie si la mesure du temps est en cours
- HRTime\StopWatch::start — Démarre la mesure du temps
- HRTime\StopWatch::stop — Arrête la mesure du temps

# La classe HRTime\Unit

(PECL hrtime >= 0.4.3)

## Introduction

## Synopsis de la classe

class HRTime\Unit {
/* Constantes */
const int SECOND = 0;
const int MILLISECOND = 1;
const int MICROSECOND = 2;
const int NANOSECOND = 3;
/* Méthodes */
}

## Constantes pré-définies

`HRTime\Unit::SECOND`
`HRTime\Unit::MILLISECOND`
`HRTime\Unit::MICROSECOND`
`HRTime\Unit::NANOSECOND`

- Installation/Configuration
  - Installation
- Exemples
  - Utilisation simple
- HRTime\PerformanceCounter — La classe HRTime\PerformanceCounter
  - HRTime\PerformanceCounter::getFrequency — Fréquence du timer en ticks par seconde
  - HRTime\PerformanceCounter::getTicks — Ticks courants depuis le système
  - HRTime\PerformanceCounter::getTicksSince — Ticks écoulés depuis la valeur fournie
- HRTime\StopWatch — La classe HRTime\StopWatch
  - HRTime\StopWatch::getElapsedTicks — Récupère les ticks écoulés pour tous les intervalles
  - HRTime\StopWatch::getElapsedTime — Récupère le temps écoulé pour tous les intervalles
  - HRTime\StopWatch::getLastElapsedTicks — Récupère les ticks écoulés pour le dernier intervalle
  - HRTime\StopWatch::getLastElapsedTime — Récupère le temps écoulé pour le dernier intervalle
  - HRTime\StopWatch::isRunning — Vérifie si la mesure du temps est en cours
  - HRTime\StopWatch::start — Démarre la mesure du temps
  - HRTime\StopWatch::stop — Arrête la mesure du temps
- HRTime\Unit — La classe HRTime\Unit

- Calendar
  - Installation/Configuration
  - Constantes pré-définies
  - Calendar Fonctions
- Date/Heure — Date et Heure
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - DateTime — La classe DateTime
  - DateTimeImmutable — La classe DateTimeImmutable
  - DateTimeInterface — L'interface DateTimeInterface
  - DateTimeZone — La classe DateTimeZone
  - DateInterval — La classe DateInterval
  - DatePeriod — La classe DatePeriod
  - Fonctions Date/Heure
  - Erreurs et Exceptions Date/Heure
  - Formats supportés de temps et de dates
  - Liste des Fuseaux Horaires Supportés
  - DateError — La classe DateError
  - DateObjectError — La classe DateObjectError
  - DateRangeError — La classe DateRangeError
  - DateException — La classe DateException
  - DateInvalidOperationException — La classe DateInvalidOperationException
  - DateInvalidTimeZoneException — La classe DateInvalidTimeZoneException
  - DateMalformedIntervalStringException — La classe DateMalformedIntervalStringException
  - DateMalformedPeriodStringException — La classe DateMalformedPeriodStringException
  - DateMalformedStringException — La classe DateMalformedStringException
- HRTime — Gestion du temps à haute résolution
  - Installation/Configuration
  - Exemples
  - HRTime\PerformanceCounter — La classe HRTime\PerformanceCounter
  - HRTime\StopWatch — La classe HRTime\StopWatch
  - HRTime\Unit — La classe HRTime\Unit

# Extensions relatives aux systèmes de fichiers

# Direct IO

# Introduction

PHP supporte les fonctions Direct IO, telles que décrites dans le standard Posix (Section 6) pour effectuer des fonctions I/O de bas niveau par rapport aux fonctions C-Language stream I/O (fopen(), fread(),..). L'utilisation des fonctions DIO devrait être considérée uniquement lorsqu'un contrôle direct d'un périphérique est nécessaire. Dans tous les autres cas, les fonctions standard de système de fichiers sont plus adéquates.

# Installation/Configuration

## Sommaire

- Installation
- Types de ressources

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/dio.

## Types de ressources

Un type de ressource est défini par cette extension : un descripteur de fichier, retourné par la fonction dio_open().

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`F_DUPFD` (int)

`F_GETFD` (int)

`F_GETFL` (int)

`F_GETLK` (int)

`F_GETOWN` (int)

`F_RDLCK` (int)

`F_SETFL` (int)

`F_SETLK` (int)

`F_SETLKW` (int)

`F_SETOWN` (int)

`F_UNLCK` (int)

`F_WRLCK` (int)

`O_APPEND` (int)

`O_ASYNC` (int)

`O_CREAT` (int)

`O_EXCL` (int)

`O_NDELAY` (int)

`O_NOCTTY` (int)

`O_NONBLOCK` (int)

`O_RDONLY` (int)

`O_RDWR` (int)

`O_SYNC` (int)

`O_TRUNC` (int)

`O_WRONLY` (int)

`S_IRGRP` (int)

`S_IROTH` (int)

`S_IRUSR` (int)

`S_IRWXG` (int)

`S_IRWXO` (int)

`S_IRWXU` (int)

`S_IWGRP` (int)

`S_IWOTH` (int)

`S_IWUSR` (int)

`S_IXGRP` (int)

`S_IXOTH` (int)

`S_IXUSR` (int)

# Fonctions Direct IO

# dio_close

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_close — Ferme l'accès au fichier

### Description

function dio_close(resource `$fd`): void

dio_close() ferme l'accès au fichier représenté par la ressource `fd`.

### Liste de paramètres

`fd`

  La ressource de fichier retournée par dio_open().

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Fermeture d'une ressource de fichier

    <?php
    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_close($fd);
    ?>

### Voir aussi

- dio_open() - Ouvre un nouveau fichier avec les permissions spécifiées

# dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_fcntl — Exécute une fonction fichier de langage C

### Description

function dio_fcntl(resource `$fd`, int `$cmd`, mixed `$args` = ?): mixed

dio_fcntl() exécute l'opération `cmd` sur le fichier représenté par la ressource `fd`. Certaines commandes demandent des arguments supplémentaires qui sont fournis dans l'argument `args`.

### Liste de paramètres

`fd`

  La ressource de fichier retournée par dio_open().

`cmd`

  Peut être une de ces opérations suivantes :

  - `F_SETLK` : le verrou est posé ou levé. Si le verrou appartient à un autre utilisateur, dio_fcntl() retourne -1.

  - `F_SETLKW` : identique à `F_SETLK`, mais si le verrou appartient à quelqu'un d'autre, dio_fcntl() attend la levée du verrou.

  - `F_GETLK` : dio_fcntl() retourne un tableau associatif (comme décrit ci-dessous) si un autre utilisateur empêche la pose d'un verrou. S'il n'y a aucun empêchement, l'entrée "type" prendra la valeur `F_UNLCK`.

  - `F_DUPFD` : trouve les numéros de ressource de fichier les plus petits, disponibles, inférieurs ou égaux à `args` et les retourne.

  - `F_SETFL` : configure les descripteurs de fichier à la valeur spécifiée par `args`, qui peut être `O_APPEND`, `O_NONBLOCK` ou `O_ASYNC`. Pour utiliser `O_ASYNC` il sera nécessaire d'utiliser l'extension PCNTL.

`args`

  `args` est un tableau associatif lorsque `cmd` vaut `F_SETLK` ou `F_SETLKW`, avec les entrées suivantes :

  - `start` : offset de début de verrou

  - `length` : taille de la surface verrouillée. Zéro indique la fin du fichier

  - `whence` : l_start est relatif à : peut être `SEEK_SET`, `SEEK_END` et `SEEK_CUR`

  - `type` : type de verrou. peut être `F_RDLCK` (verrou en lecture), `F_WRLCK` (verrou en écriture) ou `F_UNLCK` (déverrouillage)

### Valeurs de retour

Retourne le résultat d'un appel en C.

### Exemples

Exemple #1 Positionnement et suppression d'un verrou

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
       // le descripteur de fichier semble verrouillé
       echo "Le verrou n'a pu être effacé. Il a été posé par quelqu'un d'autre.";
    } else {
       echo "Le verrou a été défini/verrouillé avec succès";
    }

    dio_close($fd);
    ?>

### Notes

> Note: Cette fonction n'est pas implémentée sur les plates-formes Windows.

# dio_open

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_open — Ouvre un nouveau fichier avec les permissions spécifiées

### Description

function dio_open(string `$filename`, int `$flags`, int `$mode` = 0): resource

Ouvre un accès à un fichier et retourne une ressource de fichier.

### Liste de paramètres

`filename`

  Le chemin vers le fichier à ouvrir.

`flags`

  Le paramètre `flags` est une valeur comprenant des drapeaux depuis la liste suivante. Cette valeur doit inclure une constante parmi `O_RDONLY`, `O_WRONLY`, ou `O_RDWR`. À cette constante, il est possible d'y ajouter n'importe quels drapeaux depuis cette liste.

  - `O_RDONLY` : ouvre le fichier en lecture seule.

  - `O_WRONLY` : ouvre le fichier en écriture.

  - `O_RDWR` : ouvre le fichier en lecture et écriture.

  - `O_CREAT` : crée le fichier, s'il n'existe pas.

  - `O_EXCL` : si `O_CREAT` et `O_EXCL` sont utilisés et que le fichier existe, dio_open() échouera.

  - `O_TRUNC` : si le fichier existe et qu'il est ouvert en écriture, le fichier sera réduit à la taille nulle.

  - `O_APPEND` : les écritures se font à partir de la fin du fichier.

  - `O_NONBLOCK` : active le mode non-bloquant.

  - `O_NOCTTY` : évite que le système d'exploitation n'assigne au fichier ouvert un processus contrôlant le terminal lorsque ce fichier est un fichier TTY.

`mode`

  Si `flags` contient `O_CREAT`, `mode` définira les permissions du fichier (permissions de création). `mode` est requis pour une opération correcte lorsque `O_CREAT` est spécifié dans le `flags` et est ignoré sinon.

  Les permissions assignées au fichier créé seront affectées par la configuration du processus umask.

### Valeurs de retour

Une ressource de fichier ou `false` en cas d'erreur.

### Exemples

Exemple #1 Ouverture d'un fichier

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_close($fd);
    ?>

### Voir aussi

- dio_close() - Ferme l'accès au fichier

# dio_read

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_read — Lit les octets dans un fichier

### Description

function dio_read(resource `$fd`, int `$len` = 1024): string

dio_read() lit et retourne `len` octets dans le fichier représenté par la ressource `fd`.

### Liste de paramètres

`fd`

  La ressource de fichier retournée par dio_open().

`len`

  Le nombre d'octets à lire. Si le paramètre n'est pas spécifié, dio_read() lit un bloc de 1 ko.

### Valeurs de retour

Les octets lus de `fd`.

### Voir aussi

- dio_write() - Écrit des données dans le fichier avec la possibilité de tronquer sa longueur

# dio_seek

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_seek — Déplace le pointeur interne de fichier

### Description

function dio_seek(resource `$fd`, int `$pos`, int `$whence` = SEEK_SET): int

dio_seek() sert à modifier la position du pointeur de fichier dans le fichier.

### Liste de paramètres

`fd`

  La ressource de fichier retournée par dio_open().

`pos`

  La nouvelle position.

`whence`

  Spécifie comment la position `pos` devrait être interprétée :

  - `SEEK_SET` (défaut) : spécifie que `pos` est spécifié à partir du début du fichier.

  - `SEEK_CUR` : spécifie que `pos` est un nombre de caractères à partir de la position courante dans le fichier. Ce nombre peut être positif ou négatif.

  - `SEEK_END` : spécifie que `pos` est un nombre de caractères à partir de la fin du fichier. Une valeur négative spécifie une position à l'intérieur de l'étendue courante du fichier ; une valeur positive spécifie une position au-delà de la fin courante. Si l'on spécifie une position après la fin et que l'on y écrit des données, cela va agrandir le fichier avec des zéros jusqu'à cette position.

### Valeurs de retour

### Exemples

Exemple #1 Positionnement dans un fichier

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_seek($fd, 10, SEEK_SET);
    // la position est maintenant à 10 caractères depuis le début du fichier

    dio_seek($fd, -2, SEEK_CUR);
    // la position est maintenant à 8 caractères depuis le début du fichier

    dio_seek($fd, -5, SEEK_END);
    // la position est maintenant à 5 caractères depuis la fin du fichier

    dio_seek($fd, 10, SEEK_END);
    // la position est maintenant à 10 caractères après la fin du fichier.
    // Les 10 caractères entre la fin du fichier et la position courante sont
    // complétés par des zéros.

    dio_close($fd);
    ?>

# dio_stat

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_stat — Lit des informations sur le fichier

### Description

function dio_stat(resource `$fd`): array

dio_stat() retourne les informations sur le fichier.

### Liste de paramètres

`fd`

  Le descripteur de fichier retourné par dio_open().

### Valeurs de retour

Retourne un tableau associatif avec les clés suivantes :

- "device" : device

- "inode" : inode

- "mode" : mode

- "nlink" : nombre de liens physiques

- "uid" : user id

- "gid" : group id

- "device_type" : type de device (si inode device)

- "size" : taille totale en octets

- "blocksize" : taille du bloc

- "blocks" : nombre de blocs alloués

- "atime" : date du dernier accès

- "mtime" : date de dernière modification

- "ctime" : date de dernier changement

En cas d'erreur, dio_stat() retourne `null`.

# dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)

dio_tcsetattr — Modifie les attributs du terminal et le taux de baud du port série

### Description

function dio_tcsetattr(resource `$fd`, array `$options`): bool

dio_tcsetattr() modifie les attributs du terminal et le taux de baud du port série de `fd`.

### Liste de paramètres

`fd`

  Le descripteur de fichier retourné par dio_open().

`options`

  Les options actuellement disponibles sont :

  - 'baud' : taux de baud du port : peut être 38400,19200,9600,4800, 2400,1800,1200,600,300,200,150,134,110,75 ou 50. Par défaut, c'est 9600.

  - 'bits' : bits de données : peut être 8,7,6 ou 5. Par défaut, c'est 8.

  - 'stop' : bits de stop : peut être 1 ou 2. Par défaut, c'est 1.

  - 'parity' : peut être 0, 1 ou 2. Par défaut, c'est 0.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Définition du débit des bauds sur un port série

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_fcntl($fd,F_SETFL, O_SYNC );

    dio_tcsetattr($fd, array(
        'baud' => 9600,
        'bits' => 8,
        'stop'  =>1,
        'parity' => 0
    ));

    while (true) {
        $data = dio_read($fd, 256);
        if ($data !== null && $data !== '') {
            echo $data;
        }
    }

    ?>

### Notes

> Note: Cette fonction n'est pas implémentée sur les plates-formes Windows.

# dio_truncate

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_truncate — Tronque un fichier

### Description

function dio_truncate(resource `$fd`, int `$offset`): bool

dio_truncate() tronque un fichier à au plus `offset` octets, en taille.

Si auparavant le fichier était plus grand que cette taille, les données en plus seront perdues. Si par contre le fichier était plus petit, il n'est pas spécifié si le fichier est gardé intact ou agrandi. Dans le dernier cas, la partie étendue devient des octets zéros.

### Liste de paramètres

`fd`

  La ressource de fichier retournée par dio_open().

`offset`

  La position en octets.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Notes

> Note: Cette fonction n'est pas implémentée sur les plates-formes Windows.

# dio_write

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_write — Écrit des données dans le fichier avec la possibilité de tronquer sa longueur

### Description

function dio_write(resource `$fd`, string `$data`, int `$len` = 0): int

dio_write() écrit jusqu'à `len` octets issus de la variable `data`, dans le fichier représenté par la ressource `fd`.

### Liste de paramètres

`fd`

  Le descripteur de fichier retourné par dio_open().

`data`

  Les données à écrire.

`len`

  La longueur des données à écrire en octets. Si elle n'est pas spécifiée, la fonction écrit toutes les données dans le fichier spécifié.

### Valeurs de retour

Retourne le nombre d'octets écrits dans `fd`.

### Voir aussi

- dio_read() - Lit les octets dans un fichier

## Sommaire

- dio_close — Ferme l'accès au fichier
- dio_fcntl — Exécute une fonction fichier de langage C
- dio_open — Ouvre un nouveau fichier avec les permissions spécifiées
- dio_read — Lit les octets dans un fichier
- dio_seek — Déplace le pointeur interne de fichier
- dio_stat — Lit des informations sur le fichier
- dio_tcsetattr — Modifie les attributs du terminal et le taux de baud du port série
- dio_truncate — Tronque un fichier
- dio_write — Écrit des données dans le fichier avec la possibilité de tronquer sa longueur

- Installation/Configuration
  - Installation
  - Types de ressources
- Constantes pré-définies
- Fonctions Direct IO
  - dio_close — Ferme l'accès au fichier
  - dio_fcntl — Exécute une fonction fichier de langage C
  - dio_open — Ouvre un nouveau fichier avec les permissions spécifiées
  - dio_read — Lit les octets dans un fichier
  - dio_seek — Déplace le pointeur interne de fichier
  - dio_stat — Lit des informations sur le fichier
  - dio_tcsetattr — Modifie les attributs du terminal et le taux de baud du port série
  - dio_truncate — Tronque un fichier
  - dio_write — Écrit des données dans le fichier avec la possibilité de tronquer sa longueur

# Les dossiers

# Constantes pré-définies

`DIRECTORY_SEPARATOR` (string)
`PATH_SEPARATOR` (string)
  Un point-virgule sous Windows, deux points (:) sinon.
`SCANDIR_SORT_ASCENDING` (int)
`SCANDIR_SORT_DESCENDING` (int)
`SCANDIR_SORT_NONE` (int)

# La classe Directory

(PHP 4, PHP 5, PHP 7, PHP 8)

## Introduction

Les instances de la classe Directory sont créées en appelant la fonction dir(), sans utiliser l'opérateur new.

## Synopsis de la classe

final class Directory {
/* Propriétés */
public readonly string $path;
public readonly resource $handle;
/* Méthodes */
public function close(): void
public function read(): string|false
public function rewind(): void
}

## Propriétés

path

  Le dossier qui a été ouvert.

handle

  Peut être utilisé avec d'autres fonctions relatives aux dossiers, comme readdir(), rewinddir() et closedir().

## Historique

Version | Description
--- | ---
8.5.0 | La classe est désormais finale.
8.1.0 | Les propriétés path et handle sont désormais en lecture seule.

# Directory::close

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::close — Ferme le gestionnaire de dossier

### Description

public function Directory::close(): void

### Historique

Version | Description
--- | ---
8.0.0 | Aucun paramètre n'est accepté. Auparavant, un gestionnaire de dossier pouvait être passé en argument.

# Directory::read

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::read — Lit une entrée depuis le gestionnaire de dossier

### Description

public function Directory::read(): string|false

### Historique

Version | Description
--- | ---
8.0.0 | Aucun paramètre n'est accepté. Auparavant, un gestionnaire de dossier pouvait être passé en argument.

# Directory::rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::rewind — Réinitialise le gestionnaire de dossier

### Description

public function Directory::rewind(): void

### Historique

Version | Description
--- | ---
8.0.0 | Aucun paramètre n'est accepté. Auparavant, un gestionnaire de dossier pouvait être passé en argument.

## Sommaire

- Directory::close — Ferme le gestionnaire de dossier
- Directory::read — Lit une entrée depuis le gestionnaire de dossier
- Directory::rewind — Réinitialise le gestionnaire de dossier

# Fonctions sur les dossiers

# Voir aussi

Pour des fonctions connexes telles que dirname(), is_dir(), mkdir() et rmdir(), se reporter à la section système de fichiers.

# chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

chdir — Change de dossier

### Description

function chdir(string `$directory`): bool

chdir() change le dossier courant de PHP en `directory`.

### Liste de paramètres

`directory`

  Le nouveau dossier courant

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si une erreur survient.

### Exemples

Exemple #1 Exemple avec chdir()

    <?php

    // dossier courant
    echo getcwd() . "\n";

    chdir('public_html');

    // dossier courant
    echo getcwd() . "\n";

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    /home/vincent
    /home/vincent/public_html

### Notes

Attention

Si l'interpréteur PHP a été compilé avec ZTS d'activé (Zend Thread Safety), tous les changements du dossier courant réalisés via la fonction chdir() seront invisibles du système d'exploitation. Toutes les fonctions internes de PHP continueront à respecter le changement de dossier courant ; mais tous les appels aux fonctions des bibliothèques externes via FFI ne le respecteront pas. Il est possible de vérifier si la copie de PHP a été compilée avec l'activation de ZTS en utilisant php -i ou en utilisant la constante interne `PHP_ZTS`.

### Voir aussi

- getcwd() - Retourne le dossier de travail courant

# chroot

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

chroot — Change le dossier racine

### Description

function chroot(string `$directory`): bool

chroot() change le répertoire racine du processus courant en `directory`, puis change le répertoire de travail courant en "/".

Cette fonction n'est disponible que sur les systèmes GNU et BSD et que si l'on utilise la SAPI CLI, CGI ou Embed. De plus, cette fonction nécessite les privilèges d'administrateur.

Appeler cette fonction ne change pas la valeur des constantes magiques `__DIR__` et `__FILE__`.

### Liste de paramètres

`directory`

  Le répertoire vers lequel changer la racine.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec chroot()

    <?php
    chroot("/path/to/your/chroot/");
    echo getcwd();
    ?>

L'exemple ci-dessus va afficher :

    /

### Notes

> Note: Cette fonction n'est pas implémentée sur les plates-formes Windows.

> Note: Cette fonction n'est pas disponible dans les interpréteurs PHP compilé avec ZTS (Zend Thread Safety) d'activé. Pour vérifier si votre copie de PHP a été compilé avec ZTS d'activé, utiliser php -i ou tester la constante incluse `PHP_ZTS`.

# closedir

(PHP 4, PHP 5, PHP 7, PHP 8)

closedir — Ferme le pointeur sur le dossier

### Description

function closedir(?resource `$dir_handle` = `null`): void

closedir() ferme le pointeur de dossier `dir_handle`.

### Liste de paramètres

`dir_handle`
  Le gestionnaire de dossier resource précédemment ouvert avec opendir(). Si `dir_handle` est `null` le dernier gestionnaire ouvert avec opendir() sera utilisé.

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.5.0 | Utiliser `null` pour `dir_handle` est maintenant obsolète. Au lieu de cela, le dernier gestionnaire de dossier ouvert doit être fourni explicitement.
8.0.0 | `dir_handle` est désormais nullable.

### Exemples

Pour un exemple complet, se reporter à la documentation de opendir().

### Voir aussi

- opendir() - Ouvre un dossier, et récupère un pointeur dessus
- readdir() - Lit une entrée du dossier
- rewinddir() - Retourne à la première entrée du dossier
- dir() - Retourne une instance de la classe Directory
- is_dir() - Indique si le fichier est un dossier
- glob() - Recherche des chemins qui vérifient un masque
- scandir() - Liste les fichiers et dossiers dans un dossier

# dir

(PHP 4, PHP 5, PHP 7, PHP 8)

dir — Retourne une instance de la classe Directory

### Description

function dir(string `$directory`, ?resource `$context` = `null`): Directory|false

Un mécanisme pseudo-objet permet la lecture d'un dossier. L'argument `directory` est ouvert.

### Liste de paramètres

`directory`

  Le dossier à ouvrir

`context`

  > Note: Une resource de contexte de flux.

### Valeurs de retour

Retourne une instance de la classe Directory en cas de succès, ou `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.0.0 | `context` est désormais nullable.

### Exemples

Exemple #1 Exemple avec dir()

Il est à noter la façon dont la valeur de retour de Directory::read() est vérifiée dans l'exemple suivant. Nous testons si la valeur est identique (égale et de même type que - voyez opérateurs de comparaison pour plus de détails) à `false` sinon, toute entrée de dossier dont le nom s'évalue à `false` causera l'arrêt de la boucle.

    <?php
    $d = dir("/etc/php5");
    echo "Pointeur : " . $d->handle . "\n";
    echo "Chemin : " . $d->path . "\n";
    while (false !== ($entry = $d->read())) {
       echo $entry."\n";
    }
    $d->close();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Pointeur : Resource id #2
    Chemin : /etc/php5
    .
    ..
    apache
    cgi
    cli

### Notes

> Note:

> L'ordre dans lequel les entrées du dossier sont retournées avec la méthode read dépend du système.

# getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

getcwd — Retourne le dossier de travail courant

### Description

function getcwd(): string|false

Retourne le dossier de travail courant.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le dossier de travail courant en cas de réussite ou `false` en cas d'échec.

Sur certaines variantes d'Unix, getcwd() peut retourner `false` si l'un des dossiers parents n'a pas les droits de lecture ou de recherche définis, même si le dossier courant les a. Voir la fonction chmod() pour plus d'informations sur les modes de permissions.

### Exemples

Exemple #1 Exemple avec getcwd()

    <?php

    // dossier courant
    echo getcwd() . "\n";

    chdir('cvs');

    // dossier courant
    echo getcwd() . "\n";

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    /home/didou
    /home/didou/cvs

### Notes

Attention

Si l'interpréteur PHP a été compilé avec ZTS d'activé (Zend Thread Safety), le dossier courant de travail, retourné par la fonction getcwd() peut être différent de celui retourné par les interfaces systèmes. Les bibliothèques externes (appelées via FFI), qui dépendent du dossier courant de travail, seront affectées.

### Voir aussi

- chdir() - Change de dossier
- chmod() - Change le mode du fichier

# opendir

(PHP 4, PHP 5, PHP 7, PHP 8)

opendir — Ouvre un dossier, et récupère un pointeur dessus

### Description

function opendir(string `$directory`, ?resource `$context` = `null`): resource|false

opendir() retourne un pointeur sur un dossier qui peut être utilisé avec les fonctions closedir(), readdir() et rewinddir().

### Liste de paramètres

`directory`
  Le chemin du dossier à ouvrir.
`context`
  Pour une description du paramètre `context`, se reporter à la section les flux du manuel.

### Valeurs de retour

Renvoie un gestionnaire de dossier en cas de succès ou `false` si une erreur survient

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

Ceci peut se produire si `directory` n'est pas un dossier valide, le dossier ne peut être ouvert pour des raisons de permissions, ou à cause d'erreurs liées au système de fichiers.

### Historique

Version | Description
--- | ---
8.0.0 | `context` est désormais nullable.

### Exemples

Exemple #1 Liste toutes les entrées d'un dossier, en ignorant les entrées spéciales `.` et `..`

Du fait que les entrées de dossier et de fichier peuvent être des chaînes et s'évaluer comme "faux" (par exemple un dossier nommé `"0"`), et que readdir() retourne `false` lorsqu'il a lu toutes les entrées d'un dossier, il faut utiliser l'opérateur de comparaison `===` pour distinguer correctement une entrée de dossier dont le nom est "faux" d'une entrée de dossier qui a été lue et qui est `false`.

    <?php
    if ($handle = opendir('/path/to/files')) {
        echo "Entrées :\n";

        /* Gestion correcte des entrées de dossier pouvant être évaluées comme fausses */
        while (false !== ($entry = readdir($handle))) {
            if ($entry === '.' || $entry === '..') {
                continue;
            }
            echo "$entry\n";
        }

        closedir($handle);
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Entrées :
    base
    en
    fr
    output.md
    test.php

### Voir aussi

- readdir() - Lit une entrée du dossier
- rewinddir() - Retourne à la première entrée du dossier
- closedir() - Ferme le pointeur sur le dossier
- dir() - Retourne une instance de la classe Directory
- is_dir() - Indique si le fichier est un dossier
- glob() - Recherche des chemins qui vérifient un masque
- scandir() - Liste les fichiers et dossiers dans un dossier

# readdir

(PHP 4, PHP 5, PHP 7, PHP 8)

readdir — Lit une entrée du dossier

### Description

function readdir(?resource `$dir_handle` = `null`): string|false

Renvoie le nom de la prochaine entrée dans le dossier. Les entrées sont renvoyées dans l'ordre dans lequel elles sont stockées dans le système de fichiers.

### Liste de paramètres

`dir_handle`
  Un gestionnaire de dossier resource précédemment ouvert avec opendir(). Si `dir_handle` est `null` le dernier gestionnaire ouvert avec opendir() sera utilisé.

### Valeurs de retour

Retourne le nom de l'entrée en cas de réussite, ou `false` si une erreur survient.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Historique

Version | Description
--- | ---
8.5.0 | Utiliser `null` pour `dir_handle` est maintenant déprécié. Au lieu de cela, le dernier gestionnaire de dossier ouvert doit être fourni explicitement.
8.0.0 | `dir_handle` est désormais nullable.

### Exemples

Pour un exemple complet, se reporter à la documentation de la fonction opendir().

### Voir aussi

- opendir() - Ouvre un dossier, et récupère un pointeur dessus
- rewinddir() - Retourne à la première entrée du dossier
- closedir() - Ferme le pointeur sur le dossier
- dir() - Retourne une instance de la classe Directory
- is_dir() - Indique si le fichier est un dossier
- glob() - Recherche des chemins qui vérifient un masque
- scandir() - Liste les fichiers et dossiers dans un dossier

# rewinddir

(PHP 4, PHP 5, PHP 7, PHP 8)

rewinddir — Retourne à la première entrée du dossier

### Description

function rewinddir(?resource `$dir_handle` = `null`): void

Réinitialise le flux de dossier indiqué par `dir_handle` au début du dossier.

### Liste de paramètres

`dir_handle`
  Un gestionnaire de dossier resource précédemment ouvert avec opendir(). Si `dir_handle` est `null` le dernier gestionnaire ouvert avec opendir() sera utilisé.

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.5.0 | Utiliser `null` pour `dir_handle` est maintenant déprécié. Au lieu de cela, le dernier gestionnaire de dossier ouvert doit être fourni explicitement.
8.0.0 | `dir_handle` est désormais nullable.

### Exemples

Pour un exemple complet, se reporter à la documentation de opendir().

### Voir aussi

- opendir() - Ouvre un dossier, et récupère un pointeur dessus
- readdir() - Lit une entrée du dossier
- closedir() - Ferme le pointeur sur le dossier
- dir() - Retourne une instance de la classe Directory
- is_dir() - Indique si le fichier est un dossier
- glob() - Recherche des chemins qui vérifient un masque
- scandir() - Liste les fichiers et dossiers dans un dossier

# scandir

(PHP 5, PHP 7, PHP 8)

scandir — Liste les fichiers et dossiers dans un dossier

### Description

function scandir(string `$directory`, int `$sorting_order` = `SCANDIR_SORT_ASCENDING`, ?resource `$context` = `null`): array|false

Retourne un tableau de fichiers et de dossiers issus de `directory`.

### Liste de paramètres

`directory`

  Le dossier qui sera analysé.

`sorting_order`

  Par défaut, le tri est en ordre alphabétique, croissant. Si le paramètre optionnel `sorting_order` est défini à `SCANDIR_SORT_DESCENDING`, alors le tri sera en ordre alphabétique inverse. Si ce paramètre est défini à `SCANDIR_SORT_NONE`, alors le résultat ne sera pas trié.

`context`

  Pour une description du paramètre `context`, se reporter à la section flux de données du manuel.

### Valeurs de retour

Retourne un tableau des fichiers en cas de succès ou `false` en cas d'échec. Si `directory` n'est pas un dossier, alors une valeur booléenne `false` est retournée et une erreur de niveau `E_WARNING` est générée.

### Historique

Version | Description
--- | ---
8.0.0 | `context` est désormais nullable.

### Exemples

Exemple #1 Un simple exemple avec scandir()

    <?php
    $dir    = '/tmp';
    $files1 = scandir($dir);
    $files2 = scandir($dir, SCANDIR_SORT_DESCENDING);

    print_r($files1);
    print_r($files2);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => .
        [1] => ..
        [2] => bar.php
        [3] => foo.txt
        [4] => somedir
    )
    Array
    (
        [0] => somedir
        [1] => foo.txt
        [2] => bar.php
        [3] => ..
        [4] => .
    )

### Notes

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Voir aussi

- opendir() - Ouvre un dossier, et récupère un pointeur dessus
- readdir() - Lit une entrée du dossier
- glob() - Recherche des chemins qui vérifient un masque
- is_dir() - Indique si le fichier est un dossier
- sort() - Trie un tableau en ordre croissant

## Sommaire

- chdir — Change de dossier
- chroot — Change le dossier racine
- closedir — Ferme le pointeur sur le dossier
- dir — Retourne une instance de la classe Directory
- getcwd — Retourne le dossier de travail courant
- opendir — Ouvre un dossier, et récupère un pointeur dessus
- readdir — Lit une entrée du dossier
- rewinddir — Retourne à la première entrée du dossier
- scandir — Liste les fichiers et dossiers dans un dossier

- Constantes pré-définies
- Directory — La classe Directory
  - Directory::close — Ferme le gestionnaire de dossier
  - Directory::read — Lit une entrée depuis le gestionnaire de dossier
  - Directory::rewind — Réinitialise le gestionnaire de dossier
- Fonctions sur les dossiers
  - chdir — Change de dossier
  - chroot — Change le dossier racine
  - closedir — Ferme le pointeur sur le dossier
  - dir — Retourne une instance de la classe Directory
  - getcwd — Retourne le dossier de travail courant
  - opendir — Ouvre un dossier, et récupère un pointeur dessus
  - readdir — Lit une entrée du dossier
  - rewinddir — Retourne à la première entrée du dossier
  - scandir — Liste les fichiers et dossiers dans un dossier

# Informations sur les fichiers

# Introduction

Les fonctions dans ce module tentent de déterminer le type de contenu et l'encodage d'un fichier en examinant certaines séquences d'octets magiques à des positions spécifiques à l'intérieur du fichier. Bien qu'il ne s'agisse pas d'une approche infaillible, la méthode heuristique effectue un très bon travail.

# Installation/Configuration

## Sommaire

- Installation
- Types de ressources

## Installation

Cette extension est activée par défaut.

Les utilisateurs Windows doivent inclure la bibliothèque DLL fournie php_fileinfo.dll dans leur php.ini pour activer cette extension.

La bibliothèque libmagic est fournie avec PHP, mais embarque des changements propres pour PHP. Un patch de libmagic nommé libmagic.patch est maintenu et peut être trouvé dans la source de l'extension fileinfo de PHP.

## Types de ressources

Avant PHP 8.1.0, l'extension Fileinfo utilisait une ressource : un descripteur magique de base de données retourné par finfo_open().

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`FILEINFO_NONE` (int)
  Aucun traitement spécial.
`FILEINFO_SYMLINK` (int)
  Suit les symlinks.
`FILEINFO_MIME_TYPE` (int)
  Retourne le type MIME.
`FILEINFO_MIME_ENCODING` (int)
  Retourne l'encodage MIME du fichier.
`FILEINFO_MIME` (int)
  Retourne le type MIME et l'encodage MIME, tels que décrits par la RFC 2045.
`FILEINFO_COMPRESS` (int)
  Décompresse les fichiers compressés. Désactivé en raison des conséquences sur la sécurité des threads.
`FILEINFO_DEVICES` (int)
  Regarde les contenus des blocs ou les dispositifs spéciaux de caractères.
`FILEINFO_CONTINUE` (int)
  Retourne toutes les données trouvées, pas seulement la première.
`FILEINFO_PRESERVE_ATIME` (int)
  Si possible, conserve le temps d'accès au fichier original.
`FILEINFO_RAW` (int)
  Ne traduit pas les caractères non imprimables en représentation octale `\ooo`.
`FILEINFO_EXTENSION` (int)
  Retourne l'extension de fichier appropriée pour un type MIME détecté dans le fichier. Pour les types qui ont généralement plusieurs extensions de fichier, telles que les images `JPEG`, la valeur de retour est plusieurs extensions séparées par une barre oblique, par exemple : `"jpeg/jpg/jpe/jfif"`. Pour les types inconnus non disponibles dans la base de données magic.mime, la valeur de retour est `"???"`. Disponible à partir de PHP 7.2.0.
`FILEINFO_APPLE` (int)
  Retourne le créateur et le type Apple.

# Fonctions Fileinfo

# finfo_buffer

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_buffer -- finfo::buffer — Retourne des informations à propos d'une chaîne de caractères tampon

### Description

Style procédural

function finfo_buffer(
finfo `$finfo`,
string `$string`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Style orienté objet

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Cette fonction est utilisée pour récupérer des informations à propos de données binaires dans une chaîne de caractères.

### Liste de paramètres

`finfo`
  Une instance finfo, retourné par finfo_open().
`string`
  Contenu d'un fichier à vérifier.
`flags`
  Une ou une union de plusieurs constantes Fileinfo.
`context`

### Valeurs de retour

Retourne une description textuelle de l'argument `string` ou `false` si une erreur s'est produite.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre `context` a été rendu obsolète car il est ignoré.
8.1.0 | La paramètre `finfo` attend désormais une instance de finfo ; auparavant, une resource était attendu.
8.0.0 | `context` est désormais nullable.

### Exemples

Exemple #1 Exemple avec finfo_buffer()

    <?php
    $finfo = new finfo(FILEINFO_MIME);
    echo $finfo->buffer($_POST["script"]) . "\n";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    application/x-sh; charset=us-ascii

### Voir aussi

- finfo_file() - Retourne des informations à propos d'un fichier

# finfo_close

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_close — Ferme une instance finfo

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function finfo_close(finfo `$finfo`): true

Cette fonction fermait l'instance ouverte par finfo_open() jusqu'à PHP 7.4, mais c'est un no-op à partir de la conversion de la ressource finfo en objet effectuée dans PHP 8.0, et a été rendue obsolète en PHP 8.5.

### Liste de paramètres

`finfo`
  Une instance finfo, retourné par finfo_open().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.5.0 | Cette fonction a été rendue obsolète.
8.5.0 | Le type de retour est désormais `true` ; auparavant, c'était bool.
8.1.0 | Cette fonction est un NOP désormais.
8.1.0 | La paramètre `finfo` attend désormais une instance de finfo ; auparavant, une resource était attendu.

# finfo_file

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_file -- finfo::file — Retourne des informations à propos d'un fichier

### Description

Style procédural

function finfo_file(
finfo `$finfo`,
string `$filename`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Style orienté objet

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Cette fonction est utilisée pour récupérer des informations à propos d'un fichier.

### Liste de paramètres

`finfo`
  Une instance finfo, retourné par finfo_open().
`filename`
  Nom d'un fichier à vérifier.
`flags`
  Une ou une union de plusieurs constantes Fileinfo.
`context`
  Pour une description de `contexts`, se référer à Fonctions sur les flux.

### Valeurs de retour

Retourne une description textuelle du contenu de l'argument `filename` ou `false` si une erreur s'est produite.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `finfo` attend désormais une instance de finfo ; auparavant, une resource était attendu.
8.0.0 | `context` est désormais nullable.

### Exemples

Exemple #1 Exemple avec finfo_file()

    <?php
    $finfo = finfo_open(FILEINFO_MIME_TYPE); // Retourne le type mime autrement appelé extension mimetype
    foreach (glob("*") as $filename) {
        echo finfo_file($finfo, $filename) . "\n";
    }
    finfo_close($finfo);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    text/html
    image/gif
    application/vnd.ms-excel

### Voir aussi

- finfo_buffer() - Retourne des informations à propos d'une chaîne de caractères tampon

# finfo_open

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_open -- finfo::__construct — Crée une nouvelle instance finfo

### Description

Style procédural

function finfo_open(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`): finfo|false

Style orienté objet (constructor):

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Cette fonction ouvre une base de données magique et retourne son instance.

### Liste de paramètres

`flags`
  Une ou une union de plusieurs constantes Fileinfo.
`magic_database`
  Nom de fichier d'une base de données magique, normalement quelque chose comme /path/to/magic.mime. Si non spécifié, la variable d'environnement `MAGIC` est utilisée. Si la variable d'environnement n'est pas définie, la base de données magique embarquée dans PHP sera utilisée. Le fait de passer `null` ou une chaîne de caractères vide équivaut à utiliser la valeur par défaut.

### Valeurs de retour

(Uniquement en mode procédural) Retourne une instance de finfo en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de finfo ; antérieurement, une resource était retournée.
8.0.3 | `magic_database` est désormais nullable.

### Exemples

Exemple #1 Style orienté objet

    <?php
    $finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic"); // Retourne le type mime

    /* Récupère le mime-type d'un fichier spécifique */
    $filename = "/usr/local/something.txt";
    echo $finfo->file($filename);

    ?>

Exemple #2 Style procédural

    <?php
    $finfo = finfo_open(FILEINFO_MIME, "/usr/share/misc/magic"); // Retourne le type mime

    if (!$finfo) {
        echo "Échec de l'ouverture de la base de données fileinfo";
        exit();
    }

    /* Récupère le mime-type d'un fichier spécifique */
    $filename = "/usr/local/something.txt";
    echo finfo_file($finfo, $filename);

    /* Fermeture de la connexion */
    finfo_close($finfo);
    ?>

L'exemple ci-dessus va afficher :

    text/plain; charset=us-ascii

### Notes

> Note: Généralement, l'utilisation de la base de données magique embarquée (en laissant les variables d'environnement `magic_database` et `MAGIC` non définies) est la meilleure des solutions à moins d'avoir besoin d'une base de données magique spécifique.

### Voir aussi

- finfo_close() - Ferme une instance finfo

# finfo_set_flags

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_set_flags -- finfo::set_flags — Définit des options de configuration libmagic

### Description

Style procédural

function finfo_set_flags(finfo `$finfo`, int `$flags`): true

Style orienté objet

public function finfo::set_flags(int `$flags`): true

Cette fonction définit diverses options de Fileinfo. Les options peuvent être aussi fixées directement dans finfo_open() ou par d'autres fonctions Fileinfo.

### Liste de paramètres

`finfo`
  Une instance finfo, retourné par finfo_open().
`flags`
  Une ou une union de plusieurs constantes Fileinfo.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `finfo` attend désormais une instance de finfo ; auparavant, une resource était attendu.

# mime_content_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mime_content_type — Détecte le type de contenu d'un fichier

### Description

function mime_content_type(resource|string `$filename`): string|false

Retourne le type de contenu MIME d'un fichier en utilisant les informations depuis le fichier magic.mime.

### Liste de paramètres

`filename`
  Chemin vers le fichier à tester.

### Valeurs de retour

Retourne le type de contenu au format MIME, comme `text/plain` ou `application/octet-stream`, ou `false` si une erreur survient.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec mime_content_type()

    <?php
    echo mime_content_type('php.gif') . "\n";
    echo mime_content_type('test.php');
    ?>

L'exemple ci-dessus va afficher :

    image/gif
    text/plain

### Voir aussi

- finfo_file() - Retourne des informations à propos d'un fichier
- finfo_buffer() - Retourne des informations à propos d'une chaîne de caractères tampon

## Sommaire

- finfo_buffer — Retourne des informations à propos d'une chaîne de caractères tampon
- finfo_close — Ferme une instance finfo
- finfo_file — Retourne des informations à propos d'un fichier
- finfo_open — Crée une nouvelle instance finfo
- finfo_set_flags — Définit des options de configuration libmagic
- mime_content_type — Détecte le type de contenu d'un fichier

# La classe finfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

## Introduction

Cette classe fournit une interface orientée objet aux fonctions fileinfo.

## Synopsis de la classe

class finfo {
/* Méthodes */
public function __construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)
public function buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function set_flags(int `$flags`): true
}

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::buffer — Alias de finfo_buffer()

### Description

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Cette fonction est un alias de : finfo_buffer()

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::__construct — Alias de finfo_open()

### Description

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Cette fonction est un alias de : finfo_open()

### Historique

Version | Description
--- | ---
8.0.3 | `magic_database` est désormais nullable.

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::file — Alias de finfo_file()

### Description

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Cette fonction est un alias de : finfo_file()

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::set_flags — Alias de finfo_set_flags()

### Description

public function finfo::set_flags(int `$flags`): true

Cette fonction est un alias de : finfo_set_flags()

## Sommaire

- finfo::buffer — Alias de finfo_buffer()
- finfo::__construct — Alias de finfo_open
- finfo::file — Alias de finfo_file()
- finfo::set_flags — Alias de finfo_set_flags()

- Installation/Configuration
  - Installation
  - Types de ressources
- Constantes pré-définies
- Fonctions Fileinfo
  - finfo_buffer — Retourne des informations à propos d'une chaîne de caractères tampon
  - finfo_close — Ferme une instance finfo
  - finfo_file — Retourne des informations à propos d'un fichier
  - finfo_open — Crée une nouvelle instance finfo
  - finfo_set_flags — Définit des options de configuration libmagic
  - mime_content_type — Détecte le type de contenu d'un fichier
- finfo — La classe finfo
  - finfo::buffer — Alias de finfo_buffer()
  - finfo::__construct — Alias de finfo_open
  - finfo::file — Alias de finfo_file()
  - finfo::set_flags — Alias de finfo_set_flags()

# Système de fichiers

# Introduction

Aucune bibliothèque externe n'est requise pour avoir cette extension, mais pour le support des grands fichiers `LFS` sur Linux, il faut avoir une version récente de glibc et il faudra compiler PHP avec les options suivantes : `-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64`.

# Installation/Configuration

## Sommaire

- Configuration à l'exécution
- Types de ressources

## Configuration à l'exécution

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

Options de configuration le système de fichiers
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
allow_url_fopen | "1" | `INI_SYSTEM` |
allow_url_include | "0" | `INI_SYSTEM` | Obsolète à partir de PHP 7.4.0.
user_agent | NULL | `INI_ALL` |
default_socket_timeout | "60" | `INI_ALL` |
from | "" | `INI_ALL` |
auto_detect_line_endings | "0" | `INI_ALL` | Obsolète à partir de PHP 8.1.0.
sys_temp_dir | "" | `INI_SYSTEM` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`allow_url_fopen` bool

  Cette option active les versions étendues des fonctions d'accès aux fichiers, qui savent exploiter les URL. Les extensions par défaut permettent d'accéder aux fichiers distants avec les protocoles FTP ou HTTP. Certaines extensions comme zlib, peuvent ajouter d'autres fonctionnalités.

`allow_url_include` bool

  Cette option permet l'utilisation des gestionnaires d'URL avec les fonctions suivantes : include, include_once, require, require_once.

  > Note:

  > Ce paramètre nécessite que le paramètre `allow_url_fopen` soit activé avec `"on"`.

`user_agent` string

  Définit le user agent que PHP doit envoyer.

`default_socket_timeout` int

  Durée d'expiration (en secondes) pour les flots basés sur les sockets. Spécifier une valeur négative signifie une durée d'expiration infinie.

`from` string

  L'adresse mail à utiliser pour les connexions FTP non-authentifiées ou encore pour fournir une valeur au champ "From" sur une connexion HTTP.

`auto_detect_line_endings` bool

  Lorsque cette option est activée, PHP va examiner les données lues par fgets() et file() pour voir si le fichier utilise les conventions de ligne de Unix, MS-Dos ou Macintosh.

  Cela permet à PHP de fonctionner avec des systèmes Macintosh, mais par défaut, cette option est désactivée, car cette détection impose une légère pénalité en temps de traitement, mais aussi parce que ceux qui utilisent les retours chariots comme séparateurs auront des soucis de compatibilité.

`sys_temp_dir` string

## Types de ressources

Le système de fichiers utilise des `flux` comme type de ressource. Les flux sont documentés dans leur propre chapitre.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`SEEK_SET` (int)
`SEEK_CUR` (int)
`SEEK_END` (int)
`LOCK_SH` (int)
`LOCK_EX` (int)
`LOCK_UN` (int)
`LOCK_NB` (int)

`flags` disponibles pour file()
`FILE_USE_INCLUDE_PATH` (int)
  Recherche le `filename` dans include_path.
`FILE_NO_DEFAULT_CONTEXT` (int)
`FILE_APPEND` (int)
  Ajoute du contenu au fichier existant.
`FILE_IGNORE_NEW_LINES` (int)
  Supprime les caractères de fin de ligne.
`FILE_SKIP_EMPTY_LINES` (int)
  Ignore les lignes vides.
`FILE_BINARY` (int)

  Mode binaire.

  Avertissement

  Cette constante n'a aucun effet et est dépréciée à partir de PHP 8.1.0.

`FILE_TEXT` (int)

  Mode texte.

  Avertissement

  Cette constante n'a aucun effet et est dépréciée à partir de PHP 8.1.0.

`flags` disponibles pour glob()
`GLOB_AVAILABLE_FLAGS` (int)
  Tous les indicateurs `GLOB_*` combinés. Équivalent à `0` | `GLOB_BRACE` | `GLOB_MARK` | `GLOB_NOSORT` | `GLOB_NOCHECK` | `GLOB_NOESCAPE` | `GLOB_ERR` | `GLOB_ONLYDIR`
`GLOB_BRACE` (int)
  Étend {a,b,c} pour correspondre à 'a', 'b' ou 'c'

  > Note: `GLOB_BRACE` n'est pas disponible sur certains systèmes non-GNU, comme Solaris ou Alpine Linux.

`GLOB_ERR` (int)
  Arrête en cas d'erreurs de lecture (comme les répertoires illisibles), par défaut, les erreurs sont ignorées.
`GLOB_MARK` (int)
  Ajoute une barre oblique (un antislash sur Windows) à chaque répertoire retourné.
`GLOB_NOCHECK` (int)
  Renvoie le motif de recherche si aucun fichier correspondant n'a été trouvé.
`GLOB_NOESCAPE` (int)
  Les barres obliques inverses ne protègent pas les métacaractères.
`GLOB_NOSORT` (int)
  Renvoie les fichiers tels qu'ils apparaissent dans le répertoire (sans tri). Lorsque ce drapeau n'est pas utilisé, les chemins sont triés par ordre alphabétique.
`GLOB_ONLYDIR` (int)
  Renvoie uniquement les entrées de répertoire qui correspondent au modèle.

`flags` disponibles pour pathinfo()
`PATHINFO_ALL` (int)
  Toutes les parties du chemin renvoyées sous forme de tableau associatif.
`PATHINFO_DIRNAME` (int)
  Le chemin du répertoire ou du fichier.
`PATHINFO_BASENAME` (int)
  Le nom du répertoire ou le nom et l'extension du fichier.
`PATHINFO_EXTENSION` (int)
  L'extension du fichier.
`PATHINFO_FILENAME` (int)
  Le nom du fichier (sans l'extension) ou du répertoire.

`scanner_mode` disponibles pour parse_ini_file() et parse_ini_string()
`INI_SCANNER_NORMAL` (int)
  Mode d'analyse normale des directives INI.
`INI_SCANNER_RAW` (int)
  Mode d'analyse brut des directives INI.
`INI_SCANNER_TYPED` (int)
  Mode scanner typé INI.

`flags` disponibles pour fnmatch()
`FNM_NOESCAPE` (int)
  Désactive la protection des antislash.
`FNM_PATHNAME` (int)
  Un slash dans la chaîne ne correspond qu'au slash final du motif.
`FNM_PERIOD` (int)
  Le point initial dans la chaîne doit correspondre exactement au point dans le motif.
`FNM_CASEFOLD` (int)
  Recherche sans casse. Une partie de l'extension GNU.

Constantes de téléversement de fichiers PHP
`UPLOAD_ERR_CANT_WRITE` (int)

  Échec de l'écriture du fichier sur le disque. La valeur de la constante est `7`.

`UPLOAD_ERR_EXTENSION` (int)

  Une extension PHP a interrompu le téléversement du fichier. PHP ne fournit pas de moyen de savoir quelle extension a provoqué l'arrêt du téléversement du fichier ; examiner la liste des extensions chargées avec la fonction phpinfo() peut aider. La valeur de la constante est `8`.

`UPLOAD_ERR_FORM_SIZE` (int)

  Le fichier téléversé dépasse la directive MAX_FILE_SIZE spécifiée dans le formulaire HTML. La valeur de la constante est `2`.

`UPLOAD_ERR_INI_SIZE` (int)

  Le fichier téléversé dépasse la directive upload_max_filesize spécifiée dans le fichier php.ini. La valeur de la constante est `1`.

`UPLOAD_ERR_NO_FILE` (int)

  Aucun fichier n'a été téléversé. La valeur de la constante est `4`.

`UPLOAD_ERR_NO_TMP_DIR` (int)

  Absence de dossier temporaire. La valeur de la constante est `6`.

`UPLOAD_ERR_OK` (int)

  Aucune erreur, le fichier a été téléversé avec succès. La valeur de la constante est `0`.

`UPLOAD_ERR_PARTIAL` (int)

  Le fichier téléversé n'a été que partiellement téléversé. La valeur de la constante est `3`.

# Fonctions sur les systèmes de fichiers

# Voir aussi

Pour les fonctions connexes, se reporter aussi à la section sur les accès aux Dossiers et sur les exécutions de programme.

Pour une liste et une explication sur les différents outils d'accès aux fichiers distants, se reporter aussi à Liste des protocoles et des gestionnaires supportés.

# basename

(PHP 4, PHP 5, PHP 7, PHP 8)

basename — Retourne le nom de la composante finale d'un chemin

### Description

function basename(string `$path`, string `$suffix` = ""): string

Prend en paramètre `path`, le chemin d'un fichier ou d'un répertoire et en fournit le nom de la dernière composante.

> Note:

> basename() agit de manière naïve et n'a pas connaissance du système de fichiers sous-jacent ou des composantes d'un chemin telles que "`..`".

Attention

basename() est sensible à la locale, donc si le chemin possède des caractères multioctets, la locale qui convient doit être enregistrée au moyen de la fonction setlocale(). Si `path` contient des caractères qui sont invalides pour la locale courante, le comportement de basename() est indéfini.

### Liste de paramètres

`path`

  Un chemin.

  Sous Windows, le caractère slash (`/`) et l'antislash (`\`) sont utilisés comme séparateurs de dossier. Sous les autres OS, seul le caractère slash (`/`) est utilisé.

`suffix`

  Si le nom de la composante se termine par `suffix`, celui-ci sera aussi supprimé.

### Valeurs de retour

Retourne le nom de base du chemin `path` donné.

### Exemples

Exemple #1 Exemple avec basename()

    <?php
    echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL;
    echo "2) ".basename("/etc/sudoers.d").PHP_EOL;
    echo "3) ".basename("/etc/passwd").PHP_EOL;
    echo "4) ".basename("/etc/").PHP_EOL;
    echo "5) ".basename(".").PHP_EOL;
    echo "6) ".basename("/");
    ?>

L'exemple ci-dessus va afficher :

    1) sudoers
    2) sudoers.d
    3) passwd
    4) etc
    5) .
    6)

### Voir aussi

- dirname() - Renvoie le chemin du dossier parent
- pathinfo() - Retourne des informations sur un chemin système

# chgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

chgrp — Change le groupe d'un fichier

### Description

function chgrp(string `$filename`, string|int `$group`): bool

Essaie de remplacer le groupe propriétaire courant du fichier `filename` par `group`.

Seul le super-utilisateur (root) peut changer le groupe propriétaire d'un fichier arbitrairement ; les utilisateurs classiques ne peuvent changer le groupe propriétaire d'un fichier que si l'utilisateur propriétaire du fichier est membre du groupe.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

`group`

  Un nom ou un numéro de groupe.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Modification de groupe d'un fichier

    <?php
    $filename = 'shared_file.txt';
    $format = "%s's Group ID @ %s: %d\n";
    printf($format, $filename, date('r'), filegroup($filename));
    chgrp($filename, 8);
    clearstatcache(); // ne pas mettre en cache le résultat de filegroup()
    printf($format, $filename, date('r'), filegroup($filename));
    ?>

### Notes

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

> Note: Sur Windows, cette fonction échoue silencieusement quand appliquée sur un fichier ordinaire.

### Voir aussi

- chown() - Change le propriétaire du fichier
- chmod() - Change le mode du fichier

# chmod

(PHP 4, PHP 5, PHP 7, PHP 8)

chmod — Change le mode du fichier

### Description

function chmod(string `$filename`, int `$permissions`): bool

Remplace le mode du fichier `filename` par le mode `permissions`.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

`permissions`

  Il est à noter que le mode `permissions` est considéré comme un nombre en notation octale, aussi, afin de s'en assurer, il est possible de préfixer le mode `permissions` par un zéro. Les chaînes comme "g+w" ne fonctionneront pas correctement :

      <?php
      chmod("/somedir/somefile", 755);   // notation décimale : probablement faux
      chmod("/somedir/somefile", "u+rwx,go+rx"); // chaîne : incorrect
      chmod("/somedir/somefile", 0755);  // notation octale : valeur du mode correcte
      ?>

  Le paramètre `permissions` est constitué de trois valeurs octales qui spécifient les droits pour le propriétaire, le groupe du propriétaire et les autres, respectivement. Chaque composant peut être calculé en ajoutant les droits désirés. Le chiffre 1 donne les droits d'exécution, le chiffre 2 les droits d'écriture et le chiffre 4 les droits de lecture. Ajouter simplement ces nombres pour spécifier les droits voulus. Il est aussi possible de lire le manuel des systèmes Unix avec man 1 chmod et man 2 chmod.

      <?php
      // Lecture et écriture pour le propriétaire, rien pour les autres
      chmod("/somedir/somefile", 0600);

      // Lecture et écriture pour le propriétaire, lecture pour les autres
      chmod("/somedir/somefile", 0644);

      // Tout pour le propriétaire, lecture et exécution pour les autres
      chmod("/somedir/somefile", 0755);

      // Tout pour le propriétaire, lecture exécution pour le groupe, rien pour les autres
      chmod("/somedir/somefile", 0750);
      ?>

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

En cas d'échec, une erreur `E_WARNING` est émise.

### Notes

> Note:

> L'utilisateur courant est l'utilisateur avec lequel PHP fonctionne. Il est probablement différent de l'utilisateur que l'on utilise en mode Shell ou FTP. Le mode ne peut être modifié que par l'utilisateur à qui appartient le fichier sur la plupart des systèmes.

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

### Voir aussi

- chown() - Change le propriétaire du fichier
- chgrp() - Change le groupe d'un fichier
- fileperms() - Lit les droits d'un fichier
- stat() - Renvoie les informations à propos d'un fichier

# chown

(PHP 4, PHP 5, PHP 7, PHP 8)

chown — Change le propriétaire du fichier

### Description

function chown(string `$filename`, string|int `$user`): bool

Change le propriétaire du fichier `filename` en `user`. Seul le super-utilisateur (root) peut changer arbitrairement le propriétaire d'un fichier.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

`user`

  Un nom ou un numéro d'utilisateur.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec chown()

    <?php

    // Nom du fichier et nom d'utilisateur à utiliser
    $file_name= "foo.php";
    $path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
    $user_name = "root";

    // Définit l'utilisateur
    chown($path, $user_name);

    // Vérification du résultat
    $stat = stat($path);
    print_r(posix_getpwuid($stat['uid']));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [name] => root
        [passwd] => x
        [uid] => 0
        [gid] => 0
        [gecos] => root
        [dir] => /root
        [shell] => /bin/bash
    )

### Notes

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

> Note: Sur Windows, cette fonction échoue silencieusement quand appliquée sur un fichier ordinaire.

### Voir aussi

- chmod() - Change le mode du fichier
- chgrp() - Change le groupe d'un fichier

# clearstatcache

(PHP 4, PHP 5, PHP 7, PHP 8)

clearstatcache — Efface le cache de stat()

### Description

function clearstatcache(bool `$clear_realpath_cache` = `false`, string `$filename` = ""): void

L'appel à la fonction stat() ou lstat() est relativement coûteux en termes de temps d'exécution. Pour cela, le résultat du dernier appel à l'une des fonctions de statut, (voir la liste ci-dessous), est sauvegardé pour réutilisation ultérieure. Pour forcer la vérification du statut d'un fichier, dans le cas où le fichier aurait pu être modifié ou aurait disparu, il faut utiliser la fonction clearstatcache() afin d'effacer de la mémoire les résultats du dernier appel à la fonction.

Il est à noter que PHP ne met pas en cache les informations concernant un fichier inexistant. Si l'on appelle file_exists() sur un fichier qui n'existe pas, la fonction retourne `false` jusqu'à ce que l'on crée le fichier. Si l'on crée le fichier, la fonction retourne `true` même si l'on efface le fichier. Cependant, unlink() efface automatiquement le cache.

> Note:

> Cette fonction met en cache des informations sur les fichiers. Il n'est donc nécessaire d'appeler clearstatcache() que si l'on fait des opérations multiples sur le même fichier, et que l'on souhaite avoir une version récente des informations.

Les fonctions affectées incluent : stat(), lstat(), file_exists(), is_writable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype(), et fileperms().

### Liste de paramètres

`clear_realpath_cache`

  Si l'on doit aussi vider le cache des chemins réels.

`filename`

  Nettoie le cache de chemin réel d'un fichier spécifique. Ne peut être utilisé que si le paramètre `clear_realpath_cache` vaut `true`.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec clearstatcache()

    <?php
    $file = 'output_log.txt';

    function get_owner($file)
    {
        $stat = stat($file);
        $user = posix_getpwuid($stat['uid']);
        return $user['name'];
    }

    $format = "UID @ %s: %s\n";

    printf($format, date('r'), get_owner($file));

    chown($file, 'ross');
    printf($format, date('r'), get_owner($file));

    clearstatcache();
    printf($format, date('r'), get_owner($file));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: ross

# copy

(PHP 4, PHP 5, PHP 7, PHP 8)

copy — Copie un fichier

### Description

function copy(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Fait une copie du fichier `from` vers le fichier `to`.

Pour déplacer un fichier, utiliser la fonction rename().

### Liste de paramètres

`from`

  Chemin vers le fichier source.

`to`

  Le chemin de destination. Si `to` est une URL, la copie peut échouer si ce protocole ne supporte pas l'écrasement de fichiers existants.

  Avertissement

  Si le fichier de destination `to` existe déjà, il sera écrasé.

`context`

  Une ressource de contexte valide, créée par la fonction stream_context_create().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec copy()

    <?php
    $file = 'example.txt';
    $newfile = 'example.txt.bak';

    if (!copy($file, $newfile)) {
        echo "La copie du fichier $file a échoué...\n";
    }
    ?>

### Voir aussi

- move_uploaded_file() - Déplace un fichier téléchargé
- rename() - Renomme un fichier ou un dossier
- La section du manuel concernant la gestion des téléchargements de fichiers

# delete

delete — Voir unlink() ou unset()

### Description

Il n'y a pas de mot clé ou fonction delete dans le langage PHP. Si l'on arrive sur cette page en tentant de supprimer un fichier, il convient d'utiliser unlink(). Pour supprimer une variable de la portée locale, se référer à unset().

### Voir aussi

- unlink() - Supprime un fichier
- unset() - unset(détruit) une variable

# dirname

(PHP 4, PHP 5, PHP 7, PHP 8)

dirname — Renvoie le chemin du dossier parent

### Description

function dirname(string `$path`, int `$levels` = 1): string

Renvoie le chemin parent d'un chemin représentant un fichier ou un dossier, qui correspond à `levels` niveau(x) plus haut que le dossier courant.

> Note:

> dirname() agit naïvement sur la chaîne en entrée et n'est pas au courant du système de fichiers réel ou d'éventuels composants comme "`..`".

Attention

Sur Windows, dirname() suppose la codepage actuellement définie, donc pour qu'il puisse voir le nom de dossier correct avec des caractères multioctets dans le chemin, la codepage correspondante doit être définie. Si `path` contient des caractères qui sont invalides pour la codepage courante, le comportement de dirname() est indéfini.

Sur d'autres systèmes, dirname() suppose que `path` est encodé dans un encodage compatible ASCII. Sinon, le comportement de la fonction est indéfini.

### Liste de paramètres

`path`

  Un chemin.

  Sous Windows, les slash (`/`) et antislash (`\`) sont utilisés comme séparateurs de dossier. Dans les autres environnements, seul le slash (`/`) est utilisé.

`levels`

  Le nombre de dossiers parents plus haut.

  Doit être un entier supérieur à 0.

### Valeurs de retour

Retourne le dossier parent du chemin. S'il n'y a pas de slash dans le chemin `path`, un point ('`.`') sera retourné, indiquant le dossier courant. Sinon, la chaîne retournée sera le chemin `path` dont on aura supprimé tous les `/component`.

Attention

Il faut faire attention lors de l'utilisation de cette fonction dans une boucle qui peut atteindre le dossier racine, car ceci peut produire une boucle infinie.

    <?php
    dirname('.');    // Retournera '.'.
    dirname('/');    // Retournera `\` sur Windows et '/' sur les systèmes *nix.
    dirname('\\');   // Retournera `\` sur Windows et '.' sur les systèmes *nix.
    dirname('C:\\'); // Retournera 'C:\' sur Windows et '.' sur les systèmes *nix.
    ?>

### Exemples

Exemple #1 Exemple avec dirname()

    <?php
    echo dirname("/etc/passwd") . PHP_EOL;
    echo dirname("/etc/") . PHP_EOL;
    echo dirname(".") . PHP_EOL;
    echo dirname("C:\\") . PHP_EOL;
    echo dirname("/usr/local/lib", 2);

Résultat de l'exemple ci-dessus est similaire à :

    /etc
    / (ou \ sous Windows)
    .
    C:\
    /usr

### Voir aussi

- basename() - Retourne le nom de la composante finale d'un chemin
- pathinfo() - Retourne des informations sur un chemin système
- realpath() - Retourne le chemin canonique absolu

# disk_free_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_free_space — Renvoie l'espace disque disponible sur le système de fichiers ou la partition

### Description

function disk_free_space(string `$directory`): float|false

Renvoie l'espace disque disponible dans le répertoire ou la partition.

### Liste de paramètres

`directory`

  Un dossier du système de fichiers ou une partition d'un disque.

  > Note:

  > Si l'on fournit un fichier au lieu d'un dossier, le comportement de cette fonction n'est pas défini, suivant le système d'exploitation et les versions de PHP.

### Valeurs de retour

Retourne le nombre d'octets disponible, sous la forme d'un nombre décimal ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec disk_free_space()

    <?php
    // $df contient le nombre d'octets libres sur "/"
    $df = disk_free_space("/");

    // Sous Windows:
    $df_c = disk_free_space("C:");
    $df_d = disk_free_space("D:");
    ?>

### Notes

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

### Voir aussi

- disk_total_space() - Retourne la taille d'un dossier ou d'une partition

# disk_total_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_total_space — Retourne la taille d'un dossier ou d'une partition

### Description

function disk_total_space(string `$directory`): float|false

Étant donné une chaîne contenant un répertoire, cette fonction retourne le nombre total d'octets sur le système de fichiers ou la partition de disque correspondante.

### Liste de paramètres

`directory`

  Un dossier du système de fichiers ou la partition d'un disque.

### Valeurs de retour

Retourne la taille en octets, sous la forme d'un nombre décimal ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec disk_total_space()

    <?php
    // $ds contient le nombre d'octets du dossier "/"
    $ds = disk_total_space("/");

    // Sous Windows :
    $ds = disk_total_space("C:");
    $ds = disk_total_space("D:");
    ?>

### Notes

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

### Voir aussi

- disk_free_space() - Renvoie l'espace disque disponible sur le système de fichiers ou la partition

# diskfreespace

(PHP 4, PHP 5, PHP 7, PHP 8)

diskfreespace — Alias de disk_free_space()

### Description

Cette fonction est un alias de : disk_free_space().

# fclose

(PHP 4, PHP 5, PHP 7, PHP 8)

fclose — Ferme un fichier

### Description

function fclose(resource `$stream`): bool

Ferme le fichier représenté par le pointeur `stream`.

### Liste de paramètres

`stream`

  Le pointeur de fichier doit être valide et doit avoir été correctement ouvert par la fonction fopen() ou la fonction fsockopen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec fclose()

    <?php

    $handle = fopen('somefile.txt', 'r');

    fclose($handle);

    ?>

### Voir aussi

- fopen() - Ouvre un fichier ou une URL
- fsockopen() - Ouvre un socket de connexion Internet ou Unix

# fdatasync

(PHP 8 >= 8.1.0)

fdatasync — Synchronise les données (mais pas les métadonnées) avec le fichier

### Description

function fdatasync(resource `$stream`): bool

Cette fonction synchronise le contenu du `stream` sur le support de stockage, tout comme fsync() le fait, mais elle ne synchronise pas les métadonnées des fichiers. Il est à noter que cette fonction est différente seulement dans les systèmes POSIX. Sous Windows, cette fonction est un alias de fsync().

### Liste de paramètres

`stream`
  Le pointeur de fichier doit être valide et pointer sur un fichier ouvert avec succès par fopen() ou fsockopen() (et pas encore fermé par fclose()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec fdatasync()

    <?php
    $file = 'test.txt';
    $stream = fopen($file, 'w');
    fwrite($stream, 'test data');
    fwrite($stream, "\r\n");
    fwrite($stream, 'additional data');
    fdatasync($stream);
    fclose($stream);
    ?>

### Voir aussi

- fflush() - Envoie tout le contenu généré dans un fichier
- fsync() - Synchronise les modifications apportées au fichier (y compris les métadonnées)

# feof

(PHP 4, PHP 5, PHP 7, PHP 8)

feof — Teste la fin du fichier

### Description

function feof(resource `$stream`): bool

Teste la fin du fichier.

### Liste de paramètres

`stream`
  Le pointeur de fichier doit être valide et pointer sur un fichier ouvert avec succès par fopen() ou fsockopen() (et pas encore fermé par fclose()).

### Valeurs de retour

Retourne `true` si le pointeur `stream` est à la fin du fichier ou si une erreur survient (y compris les délais d'attente de socket), sinon, retourne `false`.

### Notes

Avertissement

Si une connexion ouverte avec fsockopen() n'est pas fermée par le serveur, feof() se bloquera. Pour contourner ce comportement, se reporter à l'exemple ci-dessous :

Exemple #1 Gestion des délais d'attente dépassés avec feof()

    <?php
    function safe_feof($fp, &$start = NULL) {
     $start = microtime(true);

     return feof($fp);
    }

    /* Assumons que $fp a été précédemment ouvert par fsockopen() */

    $start = NULL;
    $timeout = ini_get('default_socket_timeout');

    while(!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout)
    {
     /* Gestion */
    }
    ?>

Avertissement

Si le pointeur de fichier passé n'est pas valide, le résultat sera une boucle infinie car feof() échouera à retourner `true`.

Exemple #2 Exemple avec feof() et un pointeur de fichier invalide

    <?php
    // Si le fichier ne peut être lu ou n'existe pas, la fonction fopen retourne FALSE
    $file = @fopen("no_such_file", "r");

    // FALSE issu de fopen émettra une alerte et fera que l'on aura une boucle infinie ici
    while (!feof($file)) {
    }

    fclose($file);
    ?>

# fflush

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fflush — Envoie tout le contenu généré dans un fichier

### Description

function fflush(resource `$stream`): bool

Force l'écriture de toutes les données bufferisées dans le fichier désigné par `stream`.

### Liste de paramètres

`stream`
  Le pointeur de fichier doit être valide et pointer sur un fichier ouvert avec succès par fopen() ou fsockopen() (et pas encore fermé par fclose()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Écriture d'un fichier en utilisant fflush()

    <?php
    $filename = 'bar.txt';

    $file = fopen($filename, 'r+');
    rewind($file);
    fwrite($file, 'Foo');
    fflush($file);
    ftruncate($file, ftell($file));
    fclose($file);
    ?>

### Voir aussi

- clearstatcache() - Efface le cache de stat
- fwrite() - Écrit un fichier en mode binaire

# fgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetc — Lit un caractère dans un fichier

### Description

function fgetc(resource `$stream`): string|false

Lit un caractère dans un fichier.

### Liste de paramètres

`stream`
  Le pointeur de fichier doit être valide et pointer sur un fichier ouvert avec succès par fopen() ou fsockopen() (et pas encore fermé par fclose()).

### Valeurs de retour

Retourne une chaîne contenant un seul caractère, lu depuis le fichier pointé par `stream`. Retourne `false` à la fin du fichier.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Exemples

Exemple #1 Exemple avec fgetc()

    <?php
    $fp = fopen('somefile.txt', 'r');
    if (!$fp) {
        echo 'Impossible d\'ouvrir le fichier somefile.txt';
    }
    while (false !== ($char = fgetc($fp))) {
        echo "$char\n";
    }
    ?>

### Notes

> Note: Cette fonction gère les chaînes binaires.

### Voir aussi

- fread() - Lecture du fichier en mode binaire
- fopen() - Ouvre un fichier ou une URL
- popen() - Ouvre un pointeur de fichier de processus
- fsockopen() - Ouvre un socket de connexion Internet ou Unix
- fgets() - Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier

# fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetcsv — Obtient une ligne depuis un pointeur de fichier et l'analyse pour des champs CSV

### Description

function fgetcsv(
resource `$stream`,
?int `$length` = `null`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\"
): array|false

Similaire à fgets() mais fgetcsv() analyse la ligne qu'il lit et recherche les champs CSV, qu'il va retourner dans un tableau les contenant.

> Note: Les paramètres de locale sont pris en compte par cette fonction. Par exemple, les données encodées dans certains encodages à un octet peuvent être analysées incorrectement si `LC_CTYPE` est `en_US.UTF-8`.

### Liste de paramètres

`stream`

  Un pointeur valide sur un fichier ouvert avec fopen(), popen() ou fsockopen().

`length`

  Doit être plus grand que la plus grande ligne (en termes de caractères) à lire dans le fichier (y compris le caractère de fin de ligne). Dans le cas contraire la ligne sera scindée en tranches de `length` caractères, sauf si la scission se produit à l'intérieur d'un encadrement.

  Omettre ce paramètre (ou le définir à 0, ou `null` en PHP 8.0.0 ou ultérieur) fait que la longueur maximale de la ligne n'est pas limitée, ce qui est légèrement plus lent.

`separator`

  Le paramètre `separator` définit le séparateur de champ. Il doit s'agir d'un caractère d'un seul octet.

`enclosure`

  Le paramètre `enclosure` définit le caractère d'encadrement des champs. Il doit s'agir d'un caractère d'un seul octet.

`escape`

  Le paramètre `escape` définit le caractère d'échappement. Il doit s'agir d'un caractère d'un seul octet ou d'une chaîne vide. La chaîne vide (`""`) désactive le mécanisme d'échappement propriétaire.

  Avertissement

  Dans le flux d'entrée, le caractère d'encadrement `enclosure` peut toujours être échappé en le doublant à l'intérieur d'une chaîne entre guillemets, ce qui donne un seul caractère `enclosure` dans le résultat analysé. Le caractère d'échappement `escape` fonctionne différemment : si une séquence de caractères `escape` et `enclosure` apparaît dans l'entrée, les deux caractères seront présents dans le résultat analysé. Donc avec les paramètres par défaut, une ligne CSV comme `"a""b","c\"d"` aura les champs analysés comme `a"b` et `c\"d`, respectivement.

  Avertissement

  À partir de PHP 8.4.0, l'utilisation de la valeur par défaut de `escape` est dépréciée. Elle doit être fournie explicitement soit par position, soit par l'utilisation des arguments nommés.

Avertissement

Lorsque le `escape` est défini sur autre chose qu'une chaîne vide (`""`), cela peut entraîner un CSV qui n'est pas conforme à » RFC 4180 ou incapable de survivre à un aller-retour à travers les fonctions CSV de PHP. La valeur par défaut pour `escape` est `"\\"`, il est donc recommandé de la définir explicitement sur une chaîne vide. La valeur par défaut changera dans une future version de PHP, au plus tôt dans PHP 9.0.

### Valeurs de retour

Retourne un tableau indexé contenant les champs lus en cas de succès, ou `false` si une erreur survient.

> Note:

> Une ligne vide dans un fichier CSV est retournée sous la forme d'un tableau contenant la valeur `null` et ne sera pas traitée comme une erreur.

> Note: Si PHP ne reconnaît pas correctement les fins de lignes lors de la lecture de fichiers qui ont été créés ou lus sur un Macintosh, l'activation de l'option de configuration auto_detect_line_endings peut régler le problème.

### Erreurs / Exceptions

Lève une ValueError si `separator` ou `enclosure` n'a pas une longueur d'un octet.

Lève une ValueError si `escape` n'a pas une longueur d'un octet ou est une chaîne vide.

### Historique

Version | Description
--- | ---
8.4.0 | Se fier à la valeur par défaut de `escape` est désormais déprécié.
8.3.0 | Une chaîne vide est renvoyée au lieu d'une chaîne contenant un seul octet nul pour le dernier champ si celui-ci contient uniquement une délimitation non terminée.
8.0.0 | `length` est désormais nullable.
7.4.0 | Le paramètre `escape` accepte désormais une chaîne de caractères vide afin de désactiver le mécanisme d'échappement propriétaire.

### Exemples

Exemple #1 Lit et affiche le contenu d'un fichier CSV

    <?php
    $row = 1;
    if (($handle = fopen("test.csv", "r")) !== FALSE) {
        while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
            $num = count($data);
            echo "<p> $num champs à la ligne $row: <br /></p>\n";
            $row++;
            for ($c=0; $c < $num; $c++) {
                echo $data[$c] . "<br />\n";
            }
        }
        fclose($handle);
    }
    ?>

### Voir aussi

- fputcsv() - Formate une ligne en CSV et l'écrit dans un fichier
- str_getcsv() - Analyse une chaîne de caractères CSV dans un tableau
- SplFileObject::fgetcsv() - Récupère une ligne depuis le fichier et l'analyse comme étant des données CSV
- SplFileObject::fputcsv() - Écrit un tableau sous la forme d'une ligne CSV
- SplFileObject::setCsvControl() - Définit les options CSV
- SplFileObject::getCsvControl() - Récupère les options pour CSV
- explode() - Scinde une chaîne de caractères en segments
- file() - Lit le fichier et renvoie le résultat dans un tableau
- pack() - Compacte des données dans une chaîne binaire

# fgets

(PHP 4, PHP 5, PHP 7, PHP 8)

fgets — Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier

### Description

function fgets(resource `$stream`, ?int `$length` = `null`): string|false

Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier.

### Liste de paramètres

`stream`
  Le pointeur de fichier doit être valide et pointer sur un fichier ouvert avec succès par fopen() ou fsockopen() (et pas encore fermé par fclose()).
`length`

  Lit jusqu'à la taille `length` - 1 octet depuis le pointeur de fichier `stream`, ou bien la fin du fichier, ou une nouvelle ligne (qui est incluse dans la valeur retournée), ou encore un EOF (celui qui arrive en premier). Si aucune longueur n'est fournie, la fonction lira le flux jusqu'à la fin de la ligne.

### Valeurs de retour

Retourne une chaîne de caractères d'au plus `length` - 1 octets lus depuis le fichier pointé par `stream`. `false` est retourné s'il n'y a plus de données à lire.

Si une erreur survient, la fonction retourne `false`.

### Exemples

Exemple #1 Lecture d'un fichier ligne par ligne

    <?php

    $fp = @fopen("/tmp/inputfile.txt", "r");

    if ($fp) {
        while (($buffer = fgets($fp, 4096)) !== false) {
            echo $buffer, PHP_EOL;
        }
        if (!feof($fp)) {
            echo "Erreur: fgets() a échoué\n";
        }

        fclose($fp);
    }

    ?>

### Notes

> Note: Si PHP ne reconnaît pas correctement les fins de lignes lors de la lecture de fichiers qui ont été créés ou lus sur un Macintosh, l'activation de l'option de configuration auto_detect_line_endings peut régler le problème.

> Note:

> Les programmeurs habitués à la programmation 'C' noteront que fgets() ne se comporte pas comme son équivalent C lors de la rencontre de la fin du fichier.

### Voir aussi

- fgetss() - Renvoie la ligne courante du fichier et élimine les balises HTML
- fread() - Lecture du fichier en mode binaire
- fgetc() - Lit un caractère dans un fichier
- stream_get_line() - Lit une ligne dans un flux
- fopen() - Ouvre un fichier ou une URL
- popen() - Ouvre un pointeur de fichier de processus
- fsockopen() - Ouvre un socket de connexion Internet ou Unix
- stream_set_timeout() - Configure la durée d'expiration d'un flux

# fgetss

(PHP 4, PHP 5, PHP 7)

fgetss — Renvoie la ligne courante du fichier et élimine les balises HTML

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.3.0, et a été SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function fgetss(resource `$handle`, int `$length` = ?, string `$allowable_tags` = ?): string

Identique à fgets(), sauf que la fonction fgetss() tente de supprimer tous les octets nuls, toutes les balises HTML et PHP qu'elle trouve dans le texte lu. La fonction conserve l'état de l'analyse d'appel en appel, et ainsi n'est pas équivalente à l'appel de strip_tags() sur la valeur de retour de fgets().

### Liste de paramètres

`handle`
  Le pointeur de fichier doit être valide et pointer sur un fichier ouvert avec succès par fopen() ou fsockopen() (et pas encore fermé par fclose()).
`length`

  Taille des données à récupérer.

`allowable_tags`

  Il est possible d'utiliser ce paramètre optionnel pour spécifier les balises qui ne doivent pas être supprimées. Voir strip_tags() pour plus de détails concernant `allowable_tags`.

### Valeurs de retour

Retourne une chaîne de taille `length` - 1 octet lu depuis le fichier pointé par `handle`, dont les balises HTML et PHP ont été supprimées.

Si une erreur survient, la fonction retourne `false`.

### Exemples

Exemple #1 Lecture d'un fichier PHP ligne par ligne

    <?php
    $str = <<<EOD
    <html><body>
     <p>Welcome! Today is the <?php echo(date('jS')); ?> of <?= date('F'); ?>.</p>
    </body></html>
    Text outside of the HTML block.
    EOD;
    file_put_contents('sample.php', $str);

    $handle = @fopen("sample.php", "r");
    if ($handle) {
        while (!feof($handle)) {
            $buffer = fgetss($handle, 4096);
            echo $buffer;
        }
        fclose($handle);
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Welcome! Today is the  of .

    Text outside of the HTML block.

### Notes

> Note: Si PHP ne reconnaît pas correctement les fins de lignes lors de la lecture de fichiers qui ont été créés ou lus sur un Macintosh, l'activation de l'option de configuration auto_detect_line_endings peut régler le problème.

### Voir aussi

- fgets() - Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier
- fopen() - Ouvre un fichier ou une URL
- popen() - Ouvre un pointeur de fichier de processus
- fsockopen() - Ouvre un socket de connexion Internet ou Unix
- strip_tags() - Supprime les balises HTML et PHP d'une chaîne
- SplFileObject::fgetss() - Récupère une ligne d'un fichier et supprime les balises HTML
- Le filtre string.strip_tags

# file

(PHP 4, PHP 5, PHP 7, PHP 8)

file — Lit le fichier et renvoie le résultat dans un tableau

### Description

function file(string `$filename`, int `$flags` = 0, ?resource `$context` = `null`): array|false

Lit le fichier et renvoie le résultat dans un tableau.

> Note:

> Il est possible d'utiliser la fonction file_get_contents() pour retourner le contenu d'un fichier dans une chaîne de caractères.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

  Astuce

  Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

`flags`

  Le paramètre optionnel `flags` peut être une ou plusieurs des constantes suivantes :

  `FILE_USE_INCLUDE_PATH`
    Recherche le fichier dans l'include_path.
  `FILE_IGNORE_NEW_LINES`
    N'ajoute pas de nouvelle ligne à la fin de chaque élément du tableau.
  `FILE_SKIP_EMPTY_LINES`
    Ignore les lignes vides.
  `FILE_NO_DEFAULT_CONTEXT`
    N'utilise pas le contexte par défaut.
`context`

  > Note: Une resource de contexte de flux.

### Valeurs de retour

Retourne le fichier dans un tableau. Chaque élément du tableau correspond à une ligne du fichier, et les retours-chariot sont placés en fin de ligne. Si une erreur survient, file() retournera `false`.

> Note:

> Chaque ligne du tableau résultant inclura une fin de ligne, à moins que `FILE_IGNORE_NEW_LINES` soit utilisé.

> Note: Si PHP ne reconnaît pas correctement les fins de lignes lors de la lecture de fichiers qui ont été créés ou lus sur un Macintosh, l'activation de l'option de configuration auto_detect_line_endings peut régler le problème.

### Erreurs / Exceptions

À partir de PHP 8.3.0, une exception ValueError est levée si le `flags` contient des valeurs invalides, comme `FILE_APPEND`.

Émet une erreur de niveau `E_WARNING` si le fichier n'existe pas.

### Historique

Version | Description
--- | ---
8.3.0 | Une exception ValueError est levée pour toute valeur invalide du `flags`.

### Exemples

Exemple #1 Exemple avec file()

    <?php
    // Lit une page web dans un tableau.
    $lines = file('http://www.example.com/');

    // Affiche toutes les lignes du tableau comme code HTML, avec les numéros de ligne
    foreach ($lines as $line_num => $line) {
        echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
    }

    // Utilisation de drapeau
    $trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    ?>

### Notes

Avertissement

Lorsque SSL est utilisé, le serveur IIS de Microsoft violera le protocole en fermant la connexion sans envoyer un indicateur `close_notify`. PHP le reportera en tant que "SSL: Fatal Protocol Error" quand vous arrivez à la fin des données. Pour contourner ce le niveau de la directive error_reporting doit être baissée pour ne pas inclure les avertissements. PHP peut détecter automatiquement les serveur IIS bogué lors de l'ouverture du flux en utilisant `https://` et supprimera l'avertissement. Lors de l'utilisation de fsockopen() pour créer un socket `ssl://`, c'est au développeur de détecter et supprimer l'avertissement.

### Voir aussi

- file_get_contents() - Lit tout un fichier dans une chaîne
- readfile() - Affiche un fichier
- fopen() - Ouvre un fichier ou une URL
- fsockopen() - Ouvre un socket de connexion Internet ou Unix
- popen() - Ouvre un pointeur de fichier de processus
- include - include
- stream_context_create() - Crée un contexte de flux

# file_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

file_exists — Vérifie si un fichier ou un dossier existe

### Description

function file_exists(string `$filename`): bool

Vérifie si un fichier ou un dossier existe.

### Liste de paramètres

`filename`

  Chemin vers le fichier ou le dossier.

  Sous Windows, il convient d'utiliser le format de chemin //computername/share/filename ou \\computername\share\filename pour vérifier qu'un fichier est disponible sur le partage réseau.

### Valeurs de retour

Retourne `true` si le fichier ou le dossier spécifié par le paramètre `filename` existe ; `false` sinon.

> Note:

> Retourne `false` pour les liens symboliques pointant vers un fichier qui n'existe pas.

> Note:

> La vérification est effectuée en utilisant l'UID/GID réel au lieu de l'effectif.

> Note: Comme le type entier de PHP est signé et que de nombreuses plates-formes utilisent des entiers de 32 bits, certaines fonctions relatives au système de fichiers peuvent retourner des résultats étranges pour les fichiers de taille supérieure à 2 Go.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Teste l'existence d'un fichier

    <?php
    $filename = '/path/to/foo.txt';

    if (file_exists($filename)) {
        echo "Le fichier $filename existe.";
    } else {
        echo "Le fichier $filename n'existe pas.";
    }
    ?>

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- is_readable() - Indique si un fichier existe et est accessible en lecture
- is_writable() - Indique si un fichier est accessible en écriture
- is_file() - Indique si le fichier est un véritable fichier
- file() - Lit le fichier et renvoie le résultat dans un tableau
- SplFileInfo

# file_get_contents

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

file_get_contents — Lit tout un fichier dans une chaîne

### Description

function file_get_contents(
string `$filename`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`,
int `$offset` = 0,
?int `$length` = `null`
): string|false

Identique à la fonction file(), hormis le fait que file_get_contents() retourne le fichier `filename` dans une chaîne, à partir de la position `offset`, et jusqu'à `length` octets. En cas d'erreur, file_get_contents() retourne `false`.

file_get_contents() est la façon recommandée pour lire le contenu d'un fichier dans une chaîne de caractères. Elle utilise un buffer en mémoire si ce mécanisme est supporté par le système, afin d'améliorer les performances.

> Note:

> Si l'on ouvre une URI avec des caractères spéciaux, comme des espaces, il faut encoder cette URI avec la fonction urlencode().

### Liste de paramètres

`filename`

  Nom du fichier à lire.

`use_include_path`

  > Note:

  > La constante `FILE_USE_INCLUDE_PATH` peut être utilisée pour déclencher la recherche dans le chemin d'inclusion. Ceci est impossible si strict typing est activé, car `FILE_USE_INCLUDE_PATH` est un int. Il convient d'utiliser `true` à la place.

`context`

  Une ressource de contexte valide, créée avec la fonction stream_context_create(). S'il n'y a pas besoin d'utiliser un contexte particulier, il est possible d'ignorer ce paramètre en affectant la valeur `null`.

`offset`

  La position à partir de laquelle on commence à lire dans le flux original. Une position négative compte à partir de la fin du flux.

  Le déplacement dans le fichier (`offset`) n'est pas supporté sur des fichiers distants. Toute tentative de se déplacer dans un fichier qui n'est pas local peut fonctionner sur les petits déplacements, mais le comportement peut ne pas être attendu car le processus utilise le flux du buffer.

`length`

  La taille maximale des données à lire. Le comportement par défaut est de lire jusqu'à la fin du fichier. Ce paramètre s'applique sur le flux traité par les filtres.

### Valeurs de retour

Retourne les données lues ou `false` si une erreur survient.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Erreurs / Exceptions

Émet une alerte de type `E_WARNING` si, `filename` ne peut être trouvé, si le paramètre `length` est plus petit que zéro, ou si le déplacement à la position `offset` spécifié dans le flux échoue.

Quand file_get_contents() est appelé sur un dossier, une erreur de niveau `E_WARNING` est générée sur Windows, et à partir de PHP 7.4 sur les autres systèmes d'exploitation aussi.

### Historique

Version | Description
--- | ---
8.0.0 | `length` est désormais nullable.
7.1.0 | Ajout du support pour des positions `offset` négatives.

### Exemples

Exemple #1 Lit et affiche le code HTML d'un site Web

    <?php
    $homepage = file_get_contents('http://www.example.com/');
    echo $homepage;
    ?>

Exemple #2 Recherche un fichier dans le include_path

    <?php
    // Si le typage strict est activé c.-à-d. declare(strict_types=1);
    $file = file_get_contents('./people.txt', true);
    // Sinon
    $file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
    ?>

Exemple #3 Lit une section d'un fichier

    <?php
    // Lit 14 caractères à partir du 21ème caractère
    $section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
    var_dump($section);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(14) "lle Bjori Ro"

Exemple #4 Utilisation des contextes de flux

    <?php
    // Création d'un flux
    $opts = [
      'http' => [
        'method' => "GET",
        'header' => "Accept-language: en\r\n" .
                    "Cookie: foo=bar",
      ]
    ];

    $context = stream_context_create($opts);

    // Accès à un fichier HTTP avec les entêtes HTTP indiqués ci-dessus
    $file = file_get_contents('http://www.example.com/', false, $context);
    ?>

### Notes

> Note: Cette fonction gère les chaînes binaires.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

Avertissement

Lorsque SSL est utilisé, le serveur IIS de Microsoft violera le protocole en fermant la connexion sans envoyer un indicateur `close_notify`. PHP le reportera en tant que "SSL: Fatal Protocol Error" quand vous arrivez à la fin des données. Pour contourner ce le niveau de la directive error_reporting doit être baissée pour ne pas inclure les avertissements. PHP peut détecter automatiquement les serveur IIS bogué lors de l'ouverture du flux en utilisant `https://` et supprimera l'avertissement. Lors de l'utilisation de fsockopen() pour créer un socket `ssl://`, c'est au développeur de détecter et supprimer l'avertissement.

### Voir aussi

- file() - Lit le fichier et renvoie le résultat dans un tableau
- fgets() - Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier
- fread() - Lecture du fichier en mode binaire
- readfile() - Affiche un fichier
- file_put_contents() - Écrit des données dans un fichier
- stream_get_contents() - Lit tout un flux dans une chaîne
- stream_context_create() - Crée un contexte de flux
- $http_response_header

# file_put_contents

(PHP 5, PHP 7, PHP 8)

file_put_contents — Écrit des données dans un fichier

### Description

function file_put_contents(
string `$filename`,
mixed `$data`,
int `$flags` = 0,
?resource `$context` = `null`
): int|false

Revient à appeler les fonctions fopen(), fwrite() et fclose() successivement.

Si le fichier `filename` n'existe pas, il sera créé. Sinon, le fichier existant sera écrasé, si l'option `FILE_APPEND` n'est pas définie.

### Liste de paramètres

`filename`

  Chemin vers le fichier dans lequel on doit écrire les données.

`data`

  Les données à écrire. Peut être soit une chaîne de caractères, un tableau ou une ressource de flux (explication plus bas).

  Si `data` est une ressource de type stream, le buffer restant de ce flux sera copié dans le fichier spécifié. Cela revient à utiliser la fonction stream_copy_to_stream().

  Il est également possible de spécifier le paramètre `data` en tant qu'un tableau à une seule dimension. C'est l'équivalent à `file_put_contents($filename, implode('', $array))`.

`flags`

  La valeur du paramètre `flags` peut être n'importe quelle combinaison des drapeaux suivants, liés par l'opérateur binaire OU (`|`).

  Drapeaux disponibles
  Drapeau | Description
  --- | ---
  `FILE_USE_INCLUDE_PATH` | Recherche le fichier `filename` dans le dossier d'inclusion. Voir include_path pour plus d'informations.
  `FILE_APPEND` | Si le fichier `filename` existe déjà, cette option permet d'ajouter les données au fichier au lieu de l'écraser.
  `LOCK_EX` | Acquiert un verrou exclusif sur le fichier lors de l'opération d'écriture. En d'autres termes, un appel à la fonction flock() survient entre l'appel à la fonction fopen() et l'appel à la fonction fwrite(). Ce comportement n'est pas identique à un appel à la fonction fopen() avec le mode "x".

`context`

  Une ressource de contexte valide créée avec la fonction stream_context_create().

### Valeurs de retour

Retourne le nombre d'octets qui ont été écrits au fichier, ou `false` si une erreur survient.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Exemples

Exemple #1 Utilisation simple de file_put_contents

    <?php
    $file = 'people.txt';
    // Ouvre un fichier pour lire un contenu existant
    $current = file_get_contents($file);
    // Ajoute une personne
    $current .= "Jean Dupond\n";
    // Écrit le résultat dans le fichier
    file_put_contents($file, $current);
    ?>

Exemple #2 Utilisation d'options pour file_put_contents

    <?php
    $file = 'people.txt';
    // Une nouvelle personne à ajouter
    $person = "Jean Dupond\n";
    // Écrit le contenu dans le fichier, en utilisant le drapeau
    // FILE_APPEND pour rajouter à la suite du fichier et
    // LOCK_EX pour empêcher quiconque d'autre d'écrire dans le fichier
    // en même temps
    file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
    ?>

### Notes

> Note: Cette fonction gère les chaînes binaires.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Voir aussi

- fopen() - Ouvre un fichier ou une URL
- fwrite() - Écrit un fichier en mode binaire
- file_get_contents() - Lit tout un fichier dans une chaîne
- stream_context_create() - Crée un contexte de flux

# fileatime

(PHP 4, PHP 5, PHP 7, PHP 8)

fileatime — Renvoie la date à laquelle le fichier a été accédé pour la dernière fois

### Description

function fileatime(string `$filename`): int|false

Renvoie la date à laquelle le fichier a été accédé pour la dernière fois.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Renvoie la date à laquelle le fichier a été accédé pour la dernière fois ou `false` si une erreur survient. La date est retournée sous la forme d'un timestamp Unix.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec fileatime()

    <?php

    // Affiche : somefile.txt a été accédé le : December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename a été accédé le : " . date("F d Y H:i:s.", fileatime($filename));
    }

    ?>

### Notes

> Note:

> La date de dernier accès d'un fichier est supposée changer à chaque fois que les blocs de données du fichier ont commencé à être lus. Cela peut être très coûteux en termes de performance lorsqu'une application accède régulièrement à beaucoup de fichiers ou de répertoires.

> La plupart des systèmes de fichiers Unix peuvent être montés en ayant désactivé cette information pour accroître les performances d'une telle application ; les nouvelles `USENET` sont un bon exemple. Sur de tels systèmes de fichiers, cette fonction devient totalement inutile.

> Note: Notez que la précision temporelle peut varier selon le système de fichiers utilisé.

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- filemtime() - Lit la date de dernière modification du fichier
- fileinode() - Lit le numéro d'inode du fichier
- date() - Formate un horodatage Unix

# filectime

(PHP 4, PHP 5, PHP 7, PHP 8)

filectime — Renvoie la date de dernière modification de l'inode d'un fichier

### Description

function filectime(string `$filename`): int|false

Renvoie la date de dernière modification de l'inode d'un fichier.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Renvoie la date à laquelle l'inode a été modifié pour la dernière fois ou `false` si une erreur survient. L'heure est retournée sous la forme d'un timestamp Unix.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec filectime()

    <?php

    // Affiche : somefile.txt a été modifié le : December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename a été modifié le : " . date("F d Y H:i:s.", filectime($filename));
    }

    ?>

### Notes

> Note:

> Sur la plupart des systèmes de fichiers UNIX, un fichier est considéré comme modifié si les données de son inode sont modifiées. C'est-à-dire lorsque les permissions, le propriétaire, le groupe ou d'autres métadonnées de l'inode sont mis à jour. Voir aussi filemtime() (qu'il sera possible d'utiliser lorsqu'on créera des indications telles que "Dernière modification : " sur les pages web) et fileatime().

> Note:

> Il est à noter que dans certains ouvrages Unix, le `ctime` d'un fichier est considéré comme sa date de création. Cela est faux ! Il n'y a pas de date de création de fichier sous la plupart des systèmes UNIX.

> Note: Notez que la précision temporelle peut varier selon le système de fichiers utilisé.

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- filemtime() - Lit la date de dernière modification du fichier

# filegroup

(PHP 4, PHP 5, PHP 7, PHP 8)

filegroup — Lit le groupe d'un fichier

### Description

function filegroup(string `$filename`): int|false

Lit le groupe du fichier. L'identifiant de groupe est retourné au format numérique, il convient d'utiliser posix_getgrgid() pour retrouver le nom du groupe.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Retourne le groupe qui possède le fichier `filename`, ou `false` si une erreur survient. L'identifiant de groupe est retourné au format numérique, il convient d'utiliser posix_getgrgid() pour retrouver le nom du groupe. En cas d'erreur, `false` est retourné.

### Erreurs / Exceptions

Si une erreur survient, une alerte de type `E_WARNING` est émise.

### Exemples

Exemple #1 Recherche le groupe d'un fichier

    <?php
    $filename = 'index.php';
    print_r(posix_getgrgid(filegroup($filename)));
    ?>

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- fileowner() - Lit l'identifiant du propriétaire d'un fichier
- posix_getgrgid() - Retourne des informations sur un groupe

# fileinode

(PHP 4, PHP 5, PHP 7, PHP 8)

fileinode — Lit le numéro d'inode du fichier

### Description

function fileinode(string `$filename`): int|false

Lit le numéro d'inode du fichier.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Retourne le numéro d'inode du fichier, ou `false` si une erreur survient.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Comparaison de l'inode d'un fichier avec le fichier courant

    <?php
    $filename = 'index.php';
    if (getmyinode() == fileinode($filename)) {
        echo 'Vous vérifiez le fichier courant.';
    }
    ?>

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- getmyinode() - Retourne l'inode du script
- stat() - Renvoie les informations à propos d'un fichier

# filemtime

(PHP 4, PHP 5, PHP 7, PHP 8)

filemtime — Lit la date de dernière modification du fichier

### Description

function filemtime(string `$filename`): int|false

Lit la date à laquelle le fichier a été modifié pour la dernière fois.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Renvoie le timestamp Unix de dernière modification du fichier `filename` ou `false` si une erreur survient. Il est possible d'utiliser date() sur ce résultat pour obtenir une date de modification humainement lisible.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec filemtime()

    <?php
    // Affichera : somefile.txt a été modifié le : December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename a été modifié le : " . date ("F d Y H:i:s.", filemtime($filename));
    }
    ?>

### Notes

> Note: Notez que la précision temporelle peut varier selon le système de fichiers utilisé.

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- filectime() - Renvoie la date de dernière modification de l'inode d'un fichier
- stat() - Renvoie les informations à propos d'un fichier
- touch() - Modifie la date de modification et de dernier accès d'un fichier
- getlastmod() - Retourne la date de dernière modification de la page

# fileowner

(PHP 4, PHP 5, PHP 7, PHP 8)

fileowner — Lit l'identifiant du propriétaire d'un fichier

### Description

function fileowner(string `$filename`): int|false

Lit l'identifiant du propriétaire d'un fichier.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Renvoie l'identifiant du propriétaire du fichier `filename`, ou `false` si une erreur survient. L'identifiant du propriétaire est numérique : il faut utiliser posix_getpwuid() pour retrouver le nom d'utilisateur.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Recherche du propriétaire d'un fichier

    <?php
    $filename = 'index.php';
    print_r(posix_getpwuid(fileowner($filename)));
    ?>

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- filegroup() - Lit le groupe d'un fichier
- stat() - Renvoie les informations à propos d'un fichier
- posix_getpwuid() - Retourne des informations sur un utilisateur

# fileperms

(PHP 4, PHP 5, PHP 7, PHP 8)

fileperms — Lit les droits d'un fichier

### Description

function fileperms(string `$filename`): int|false

Lit les droits du fichier donné.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Retourne les permissions du fichier sous forme numérique. Les bits de poids faible sont les mêmes que ceux des permissions dans chmod(), cependant la plupart des plateformes incluent dans le retour des informations sur le type de fichier donné dans `filename`. Les exemples qui suivent montrent comment tester la valeur de retour concernant les permissions et le type de fichier sur des systèmes POSIX comme Linux ou macOS.

Pour les fichiers locaux, la valeur spécifique `st_mode` de la structure C retournée par la fonction stat() est utilisée. Les bits affectés peuvent changer en fonction de la plateforme et il est recommandé de se renseigner à son sujet s'il faut analyser les bits ne concernant pas la permission.

Retourne `false` en cas d'échec.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Affichage des droits en valeur octale

    <?php
    echo substr(sprintf('%o', fileperms('/tmp')), -4);
    echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
    ?>

L'exemple ci-dessus va afficher :

    1777
    0644

Exemple #2 Affichage de tous les droits

    <?php
    $perms = fileperms('/etc/passwd');

    switch ($perms & 0xF000) {
        case 0xC000: // Socket
            $info = 's';
            break;
        case 0xA000: // Lien symbolique
            $info = 'l';
            break;
        case 0x8000: // Régulier
            $info = 'r';
            break;
        case 0x6000: // Bloc spécial
            $info = 'b';
            break;
        case 0x4000: // dossier
            $info = 'd';
            break;
        case 0x2000: // Caractère spécial
            $info = 'c';
            break;
        case 0x1000: // pipe FIFO
            $info = 'p';
            break;
        default: // Inconnu
            $info = 'u';
    }

    // Propriétaire
    $info .= (($perms & 0x0100) ? 'r' : '-');
    $info .= (($perms & 0x0080) ? 'w' : '-');
    $info .= (($perms & 0x0040) ?
                (($perms & 0x0800) ? 's' : 'x' ) :
                (($perms & 0x0800) ? 'S' : '-'));

    // Groupe
    $info .= (($perms & 0x0020) ? 'r' : '-');
    $info .= (($perms & 0x0010) ? 'w' : '-');
    $info .= (($perms & 0x0008) ?
                (($perms & 0x0400) ? 's' : 'x' ) :
                (($perms & 0x0400) ? 'S' : '-'));

    // Tout le monde
    $info .= (($perms & 0x0004) ? 'r' : '-');
    $info .= (($perms & 0x0002) ? 'w' : '-');
    $info .= (($perms & 0x0001) ?
                (($perms & 0x0200) ? 't' : 'x' ) :
                (($perms & 0x0200) ? 'T' : '-'));

    echo $info;
    ?>

L'exemple ci-dessus va afficher :

    -rw-r--r--

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- chmod() - Change le mode du fichier
- is_readable() - Indique si un fichier existe et est accessible en lecture
- stat() - Renvoie les informations à propos d'un fichier

# filesize

(PHP 4, PHP 5, PHP 7, PHP 8)

filesize — Lit la taille d'un fichier

### Description

function filesize(string `$filename`): int|false

Lit la taille du fichier donné.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Renvoie la taille du fichier `filename` en octets, ou `false` (et génère une erreur de niveau `E_WARNING`) en cas d'erreur.

> Note: Comme le type entier de PHP est signé et que de nombreuses plates-formes utilisent des entiers de 32 bits, certaines fonctions relatives au système de fichiers peuvent retourner des résultats étranges pour les fichiers de taille supérieure à 2 Go.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec filesize()

    <?php

    // Affiche p. ex.  somefile.txt: 1024 bytes

    $filename = 'somefile.txt';
    echo $filename . ': ' . filesize($filename) . ' bytes';

    ?>

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- file_exists() - Vérifie si un fichier ou un dossier existe

# filetype

(PHP 4, PHP 5, PHP 7, PHP 8)

filetype — Retourne le type de fichier

### Description

function filetype(string `$filename`): string|false

Retourne le type d'un fichier donné.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Retourne le type du fichier. Les réponses possibles sont : `fifo`, `char`, `dir`, `block`, `link`, `file`, `socket` et `unknown`.

Retourne `false` en cas d'erreur. filetype() va aussi émettre une erreur `E_NOTICE` si l'appel stat échoue, ou si le type de fichier est inconnu.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec filetype()

    <?php

    echo filetype('/etc/passwd');
    echo "\n";
    echo filetype('/etc/');
    ?>

L'exemple ci-dessus va afficher :

    file
    dir

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- is_dir() - Indique si le fichier est un dossier
- is_file() - Indique si le fichier est un véritable fichier
- is_link() - Indique si le fichier est un lien symbolique
- file_exists() - Vérifie si un fichier ou un dossier existe
- mime_content_type() - Détecte le type de contenu d'un fichier
- pathinfo() - Retourne des informations sur un chemin système
- stat() - Renvoie les informations à propos d'un fichier

# flock

(PHP 4, PHP 5, PHP 7, PHP 8)

flock — Verrouille le fichier

### Description

function flock(resource `$stream`, int `$operation`, int `&$would_block` = `null`): bool

flock() permet de réaliser un système simple de verrous écriture/lecture, qui peut être utilisé sur n'importe quelle plate-forme (Unix et Windows compris).

Le verrou est également levé avec fclose(), ou quand `stream` est ramassé par le ramasse-miettes.

PHP dispose d'un système complet de verrouillage de fichiers. Tous les programmes qui accèdent au fichier doivent utiliser la même méthode de verrouillage pour qu'il soit efficace. Par défaut, cette fonction se bloquera tant que le verrou demandé ne sera pas acquis ; ce comportement peut être contrôlé avec l'option `LOCK_NB` dont se trouve la documentation ci-dessous.

### Liste de paramètres

`stream`
  Un pointeur de système de fichiers de type resource qui est habituellement créé en utilisant la fonction fopen().
`operation`

  `operation` peut prendre une des valeurs suivantes :

  - `LOCK_SH` pour acquérir un verrou partagé (lecture).
  - `LOCK_EX` pour acquérir un verrou exclusif (écriture).
  - `LOCK_UN` pour libérer un verrou (partagé ou exclusif).

  Il est également possible d'ajouter `LOCK_NB` comme masque d'une des opérations précédentes si l'on ne veut pas que la fonction flock() bloque durant le verrouillage.

`would_block`

  Ce troisième argument optionnel est défini à 1 si le verrou doit bloquer le script (condition d'erreur `EWOULDBLOCK`).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec flock()

    <?php

    $fp = fopen("/tmp/lock.txt", "r+");

    if (flock($fp, LOCK_EX)) { // acquiert un verrou exclusif
        ftruncate($fp, 0);     // effacement du contenu
        rewind($fp);
        fwrite($fp, "Écrire dans un fichier\n");
        fflush($fp);            // libère le contenu avant d'enlever le verrou
        flock($fp, LOCK_UN);    // Enlève le verrou
    } else {
        echo "Impossible de verrouiller le fichier !";
    }

    fclose($fp);

    ?>

Exemple #2 Exemple avec flock() en utilisant l'option `LOCK_NB`

    <?php
    $fp = fopen('/tmp/lock.txt', 'r+');

    /* Activation de l'option LOCK_NB lors d'une opération LOCK_EX */
    if(!flock($fp, LOCK_EX | LOCK_NB)) {
        echo 'Impossible d\'obtenir le verrou';
        exit(-1);
    }

    /* ... */

    fclose($fp);
    ?>

### Notes

> Note:

> flock() utilise les verrous obligatoires sous Windows, qui sont aussi supportés sur Linux et les systèmes dérivés de System V au moyen de l'appel système fcntl(): si le fichier en question a le bit setgid positionné et le bit de groupe vide. Sur Linux, le système de fichiers devra être monté avec l'option mand pour que cela fonctionne.

> Note:

> Comme flock() requiert un pointeur de fichier, il est possible d'avoir à utiliser un verrou spécial pour protéger l'accès au fichier que l'on veut tronquer en l'ouvrant en mode d'écriture (avec "w" ou "w+" comme argument de fopen()).

> Note:

> Ne devrait être utilisé que sur des ressources issues de fopen() pour des fichiers locaux ou via le gestionnaire de flux personnalisé en définissant streamWrapper::stream_lock().

Avertissement

Assigner une autre valeur à l'argument `stream` dans ce code libérera le verrou.

Avertissement

Sur certains systèmes d'exploitation, flock() est implémenté au niveau processus. Lors de l'utilisation d'une API multithread, il y a un risque de ne pas pouvoir avoir confiance en flock() pour protéger les fichiers contre d'autres scripts PHP qui fonctionnent en parallèle sur d'autres threads du même serveur.

flock() n'est pas supporté sur les vieux systèmes de fichiers comme `FAT` et ses dérivés, et retourne forcément `false` sous ces environnements.

> Note:

> Sur Windows, si la procédure de verrou ouvre un fichier une deuxième fois, il ne peut pas accéder au fichier à travers ce gestionnaire jusqu'à ce que le fichier soit déverrouillé.

# fnmatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

fnmatch — Teste un nom de fichier au moyen d'un masque de recherche

### Description

function fnmatch(string `$pattern`, string `$filename`, int `$flags` = 0): bool

fnmatch() vérifie si la chaîne `filename` va passer le masque Shell `pattern`.

### Liste de paramètres

`pattern`

  Le `pattern` à comparer. Habituellement, le `pattern` contiendra des caractères génériques tels que `'?'` et `'*'`.

  Caractères génériques à utiliser dans le paramètre `pattern`
  Caractère générique | Description
  --- | ---
  `?` | Le point d'interrogation correspondra à n'importe quel caractère unique. Par exemple, le motif `"file?.txt"` correspondra à `"file1.txt"` et `"fileA.txt"`, mais ne correspondra pas à `"file10.txt"`.
  `*` | L'astérisque correspondra à zéro ou plusieurs caractères. Par exemple, le motif `"foo*.xml"` correspondra à `"foo.xml"` et `"foobar.xml"`.
  `[ ]` | Les crochets sont utilisés pour créer des plages de points de code ASCII ou des ensembles de caractères. Par exemple, le motif `"index.php[45]"` correspondra à `"index.php4"` et `"index.php5"`, mais ne correspondra pas à `"index.phpt"`. Des plages bien connues sont `[0-9]`, `[a-z]` et `[A-Z]`. Plusieurs ensembles et plages peuvent être utilisés simultanément, par exemple `[0-9a-zABC]`.
  `!` | Le point d'exclamation est utilisé pour nier les caractères dans les crochets. Par exemple, `"[!A-Z]*.html"` correspondra à `"demo.html"`, mais ne correspondra pas à `"Demo.html"`.
  `\` | Le backslash est utilisé pour échapper les caractères spéciaux. Par exemple, `"Name\?"` correspondra à `"Name?"`, mais ne correspondra pas à `"Names"`.

`filename`

  La chaîne testée. Cette fonction est particulièrement utile pour les noms de fichier, mais peut également être utilisée sur des chaînes régulières.

  L'utilisateur moyen de Shell peut être familier avec les masques Shell, ou tout au moins, leurs expressions les plus simples, comme `'?'` et `'*'`. De cette façon, utiliser fnmatch() au lieu de preg_match() pour des recherches peut être plus pratique pour les non-initiés.

`flags`

  La valeur de `flags` peut être une combinaison des drapeaux suivants, joints avec l' opérateur binaire OR (|).

  Liste des drapeaux possibles pour fnmatch()
  `Flag` | Description
  --- | ---
  `FNM_NOESCAPE` | Désactive l'échappement des antislashes.
  `FNM_PATHNAME` | Un slash dans une chaîne correspond uniquement à un slash dans le masque fourni.
  `FNM_PERIOD` | Un point en début de chaîne doit correspondre exactement à un point dans le masque fourni.
  `FNM_CASEFOLD` | Les correspondances ne tiennent pas compte de la casse. Fait partie de l'extension GNU.

### Valeurs de retour

Retourne `true` s'il y a une correspondance, `false` sinon.

### Exemples

Exemple #1 Vérifier le nom d'une couleur avec un masque Shell

    <?php
    if (fnmatch("*gr[ae]y", $color)) {
      echo "des formes de gris ...";
    }
    ?>

### Notes

Avertissement

Actuellement, cette fonction n'est pas disponible pour les systèmes non-POSIX, à l'exception de Windows.

### Voir aussi

- glob() - Recherche des chemins qui vérifient un masque
- preg_match() - Effectue une recherche de correspondance avec une expression rationnelle standard
- sscanf() - Analyse une chaîne à l'aide d'un format
- printf() - Affiche une chaîne de caractères formatée
- sprintf() - Retourne une chaîne formatée

# fopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fopen — Ouvre un fichier ou une URL

### Description

function fopen(
string `$filename`,
string `$mode`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`
): resource|false

fopen() crée une ressource nommée, spécifiée par le paramètre `filename`, sous la forme d'un flux.

### Liste de paramètres

`filename`

  Si `filename` est de la forme "protocole://", `filename` est supposé être une URL, et PHP va rechercher un gestionnaire de protocole adapté pour lire ce fichier. Si aucun gestionnaire pour ce protocole n'est disponible, PHP va émettre une alerte qui permettra de savoir qu'il y a des problèmes dans le script, et il tentera d'exploiter `filename` comme un fichier classique.

  Si PHP décide que le fichier `filename` est un fichier local, il va essayer d'ouvrir un flux avec ce fichier. Le fichier doit être accessible à PHP. Il faut donc s'assurer d'avoir les droits d'accès à ce fichier. Si l'on active la directive open_basedir, d'autres conditions peuvent aussi s'appliquer.

  Si PHP a décidé que `filename` spécifie un protocole enregistré, et que ce protocole est enregistré comme un protocole réseau, PHP s'assurera que la directive allow_url_fopen est activée. Si elle est inactive, PHP va émettre une alerte et l'appel fopen() va échouer.

  > Note:

  > La liste des protocoles supportés est disponible sur Liste des protocoles et des gestionnaires supportés. Certains protocoles (appelés aussi `wrappers` ou gestionnaires) supportent des `context` et/ou des options dans le fichier php.ini. Se référer aux pages du manuel traitant le protocole, pour connaître la liste des options qui sont disponibles (p. ex. l'option de php.ini `user_agent` est utilisée par le gestionnaire `http`).

  Sous Windows, il faut s'assurer de bien protéger les antislashs utilisés dans le chemin du fichier, ou bien utiliser des slashs.

      <?php
      $handle = fopen("c:\\folder\\resource.txt", "r");
      ?>

`mode`

  Le paramètre `mode` spécifie le type d'accès désiré au flux. Il peut prendre les valeurs suivantes :

  Liste des modes possibles pour la fonction fopen() en utilisant le paramètre `mode`
  `mode` | Description
  --- | ---
  `'r'` | Ouvre en lecture seule et place le pointeur de fichier au début du fichier.
  `'r+'` | Ouvre en lecture et écriture et place le pointeur de fichier au début du fichier.
  `'w'` | Ouvre en écriture seule ; place le pointeur de fichier au début du fichier et réduit la taille du fichier à 0. Si le fichier n'existe pas, on tente de le créer.
  `'w+'` | Ouvre en lecture et écriture ; le comportement est le même que pour `'w'`.
  `'a'` | Ouvre en écriture seule ; place le pointeur de fichier à la fin du fichier. Si le fichier n'existe pas, on tente de le créer. Dans ce mode, la fonction fseek() n'a aucun effet, les écritures surviennent toujours.
  `'a+'` | Ouvre en lecture et écriture ; place le pointeur de fichier à la fin du fichier. Si le fichier n'existe pas, on tente de le créer. Dans ce mode, la fonction fseek() n'affecte que la position de lecture, les écritures sont toujours ajoutées à la fin.
  `'x'` | Crée et ouvre le fichier en écriture seulement ; place le pointeur de fichier au début du fichier. Si le fichier existe déjà, fopen() va échouer, en retournant `false` et en générant une erreur de niveau `E_WARNING`. Si le fichier n'existe pas, fopen() tente de le créer. Ce mode est l'équivalent des options `O_EXCL|O_CREAT` pour l'appel système `open(2)` sous-jacent.
  `'x+'` | Crée et ouvre le fichier pour lecture et écriture ; le comportement est le même que pour `'x'`.
  `'c'` | Ouvre le fichier pour écriture seulement. Si le fichier n'existe pas, il sera créé, s'il existe, il n'est pas tronqué (contrairement à `'w'`) et l'appel à la fonction n'échoue pas (comme dans le cas de `'x'`). Le pointeur du fichier est positionné au début. Ce mode peut être utile pour obtenir un verrou (voir flock()) avant de tenter de modifier le fichier, utiliser `'w'` pourrait tronquer le fichier avant d'obtenir le verrou (il est possible de toujours tronquer grâce à ftruncate()).
  `'c+'` | Ouvre le fichier pour lecture et écriture, le comportement est le même que pour le mode `'c'`.
  `'e'` | Définit l'indicateur close-on-exec sur le descripteur de fichier ouvert. Disponible uniquement en PHP compilé sur les systèmes conformes POSIX.1-2008.
  `'n'` | Définit l'indicateur non-bloquant sur le descripteur de fichier. Seulement disponible en PHP compilé sur les systèmes conformes POSIX.1-2008.

  > Note:

  > Les systèmes d'exploitation utilisent différents caractères pour les nouvelles lignes. Lors de l'écriture dans un fichier texte et que l'on insère une nouvelle ligne, il faut utiliser le bon caractère pour le système d'exploitation. Les systèmes Unix utilisent `\n` comme nouvelle ligne, les systèmes Windows utilisent `\r\n`, et les systèmes Macintosh (Mac OS Classic) utilisent `\r`.

  > Si l'on n'utilise pas le bon caractère de nouvelle ligne lors de l'écriture des fichiers, il y a un risque d'ouvrir les fichiers avec des applications qui donneront un aspect 'bizarre' au texte.

  > Windows propose un mode de traduction (`'t'`), qui va traduire automatiquement les caractères `\n` en `\r\n` lors du travail sur le fichier. À l'inverse, il est possible d'utiliser l'option `'b'` pour forcer le fichier à être écrit en mode binaire, sans traduction des données. Pour utiliser ces options, il faut ajouter `'b'` ou `'t'` comme dernier caractère du paramètre `mode`.

  > Le mode de traduction par défaut est `'b'`. Il est possible d'utiliser `'t'` lors de l'écriture dans des fichiers de texte et le caractère `\n` pour définir les fins de ligne, dans les scripts, mais que l'on s'attend à ce que le fichier soit relu par une application comme les anciennes versions de Notepad. Il est recommandé de toujours utiliser l'option `'b'` dans les autres cas.

  > Si l'on spécifie `'t'` lors du travail avec des fichiers binaires, il serait possible de rencontrer des problèmes avec les données, comme des images corrompues ou des caractères `\r\n` inopinés.

  > Note:

  > Pour des raisons de portabilité, il est fortement recommandé de réécrire les scripts qui utilisent l'option `'t'`, pour qu'ils utilisent le bon caractère de nouvelle ligne et le mode `'b'`.

  > Note: Le `mode` est ignoré pour les enveloppes de flux php://output, php://input, php://stdin, php://stdout, php://stderr et php://fd.

`use_include_path`

  Le troisième paramètre optionnel `use_include_path` peut être défini à `true` pour chercher le fichier dans l'include_path.

`context`

  > Note: Une resource de contexte de flux.

### Valeurs de retour

Retourne une ressource représentant le pointeur de fichier, ou `false` si une erreur survient

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Historique

Version | Description
--- | ---
7.0.16, 7.1.2 | L'option `'e'` a été ajoutée.

### Exemples

Exemple #1 Exemple avec fopen()

    <?php
    $handle = fopen("/home/rasmus/file.txt", "r");
    $handle = fopen("/home/rasmus/file.gif", "wb");
    $handle = fopen("http://www.example.com/", "r");
    $handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
    ?>

### Notes

Avertissement

Lorsque SSL est utilisé, le serveur IIS de Microsoft violera le protocole en fermant la connexion sans envoyer un indicateur `close_notify`. PHP le reportera en tant que "SSL: Fatal Protocol Error" quand vous arrivez à la fin des données. Pour contourner ce le niveau de la directive error_reporting doit être baissée pour ne pas inclure les avertissements. PHP peut détecter automatiquement les serveur IIS bogué lors de l'ouverture du flux en utilisant `https://` et supprimera l'avertissement. Lors de l'utilisation de fsockopen() pour créer un socket `ssl://`, c'est au développeur de détecter et supprimer l'avertissement.

> Note:

> En cas de problèmes en lecture ou écriture de fichier et que l'on utilise PHP en version module de serveur, il est à noter que les fichiers auxquels l'on accède ne sont pas nécessairement accessibles au processus serveur.

> Note:

> Cette fonction peut également réussir lorsque `filename` est un dossier. En cas de doute sur le fait que `filename` soit un fichier ou un dossier, il est possible d'utiliser la fonction is_dir() avant d'utiliser la fonction fopen().

### Voir aussi

- Liste des protocoles et des gestionnaires supportés
- fclose() - Ferme un fichier
- fgets() - Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier
- fread() - Lecture du fichier en mode binaire
- fwrite() - Écrit un fichier en mode binaire
- fsockopen() - Ouvre un socket de connexion Internet ou Unix
- file() - Lit le fichier et renvoie le résultat dans un tableau
- file_exists() - Vérifie si un fichier ou un dossier existe
- is_readable() - Indique si un fichier existe et est accessible en lecture
- stream_set_timeout() - Configure la durée d'expiration d'un flux
- popen() - Ouvre un pointeur de fichier de processus
- stream_context_create() - Crée un contexte de flux
- umask() - Change le "umask" courant
- SplFileObject

# fpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

fpassthru — Affiche le reste du fichier

### Description

function fpassthru(resource `$stream`): int

Lit tout le reste d'un fichier jusqu'à la fin et dirige le résultat vers la sortie standard.

Il faut appeler la fonction rewind() pour réinitialiser le pointeur de fichier au début si l'on a déjà écrit des données dans le fichier.

Pour uniquement copier le contenu d'un fichier dans le buffer de sortie, sans le modifier auparavant ou placer le pointeur à un endroit particulier, il est recommandé d'utiliser la fonction readfile(), ce qui évite d'appeler la fonction fopen().

### Liste de paramètres

`stream`
  Le pointeur de fichier doit être valide et pointer sur un fichier ouvert avec succès par fopen() ou fsockopen() (et pas encore fermé par fclose()).

### Valeurs de retour

Retourne le nombre de caractères lus depuis `stream` et passés à la sortie standard.

### Exemples

Exemple #1 Utilisation de fpassthru() avec un fichier binaire

    <?php

    // ouvre un fichier en mode binaire
    $name = './img/ok.png';
    $fp = fopen($name, 'rb');

    // envoie les bons en-têtes
    header("Content-Type: image/png");
    header("Content-Length: " . filesize($name));

    // envoie le contenu du fichier, puis stoppe le script
    fpassthru($fp);
    exit;

    ?>

### Notes

> Note:

> Lors de l'utilisation de la fonction fpassthru() sur un fichier binaire sous Windows, il faut s'assurer d'avoir ouvert le fichier en mode binaire en ajoutant la lettre `b` au mode d'accès utilisé dans fopen().

> Il est recommandé d'utiliser l'option `b` lorsqu'on traite des fichiers binaires, même si le système ne le requiert pas, de façon à rendre les scripts portables.

### Voir aussi

- readfile() - Affiche un fichier
- fopen() - Ouvre un fichier ou une URL
- popen() - Ouvre un pointeur de fichier de processus
- fsockopen() - Ouvre un socket de connexion Internet ou Unix

# fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsv — Formate une ligne en CSV et l'écrit dans un fichier

### Description

function fputcsv(
resource `$stream`,
array `$fields`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\",
string `$eol` = "\n"
): int|false

fputcsv() formate la ligne (passée sous forme de tableau `fields`) en tant que CSV et l'écrit (terminé par un `eol`) dans le `stream` spécifié.

### Liste de paramètres

`stream`
  Le pointeur de fichier doit être valide et pointer sur un fichier ouvert avec succès par fopen() ou fsockopen() (et pas encore fermé par fclose()).
`fields`

  Un tableau de chaînes de caractères string.

`separator`

  Le paramètre `separator` définit le séparateur de champ. Il doit s'agir d'un caractère d'un seul octet.

`enclosure`

  Le paramètre `enclosure` définit le caractère d'encadrement des champs. Il doit s'agir d'un caractère d'un seul octet.

`escape`

  Le paramètre `escape` définit le caractère d'échappement. Il doit s'agir d'un caractère d'un seul octet ou d'une chaîne vide. La chaîne vide (`""`) désactive le mécanisme d'échappement propriétaire.

  Avertissement

  Dans le flux d'entrée, le caractère d'encadrement `enclosure` peut toujours être échappé en le doublant à l'intérieur d'une chaîne entre guillemets, ce qui donne un seul caractère `enclosure` dans le résultat analysé. Le caractère d'échappement `escape` fonctionne différemment : si une séquence de caractères `escape` et `enclosure` apparaît dans l'entrée, les deux caractères seront présents dans le résultat analysé. Donc avec les paramètres par défaut, une ligne CSV comme `"a""b","c\"d"` aura les champs analysés comme `a"b` et `c\"d`, respectivement.

  Avertissement

  À partir de PHP 8.4.0, l'utilisation de la valeur par défaut de `escape` est dépréciée. Elle doit être fournie explicitement soit par position, soit par l'utilisation des arguments nommés.

`eol`

  Le paramètre optionnel `eol` définit une séquence de fin de ligne (End of Line) personnalisée.

Avertissement

Lorsque le `escape` est défini sur autre chose qu'une chaîne vide (`""`), cela peut entraîner un CSV qui n'est pas conforme à » RFC 4180 ou incapable de survivre à un aller-retour à travers les fonctions CSV de PHP. La valeur par défaut pour `escape` est `"\\"`, il est donc recommandé de la définir explicitement sur une chaîne vide. La valeur par défaut changera dans une future version de PHP, au plus tôt dans PHP 9.0.

> Note:

> Si un caractère `enclosure` est contenu dans un champ, il sera échappé en le doublant, à moins qu'il ne soit immédiatement précédé d'un `escape`.

### Valeurs de retour

Retourne la taille de la chaîne écrite ou `false` si une erreur survient.

### Erreurs / Exceptions

Lève une ValueError si `separator` ou `enclosure` n'a pas une longueur d'un octet.

Lève une ValueError si `escape` n'a pas une longueur d'un octet ou est une chaîne vide.

### Historique

Version | Description
--- | ---
8.4.0 | Se fier à la valeur par défaut de `escape` est désormais déprécié.
8.1.0 | Le paramètre optionnel `eol` a été ajouté.
7.4.0 | Le paramètre `escape` accepte désormais une chaîne de caractères vide afin de désactiver le mécanisme d'échappement propriétaire.

### Exemples

Exemple #1 Exemple avec fputcsv()

    <?php

    $list = [
        ['aaa', 'bbb', 'ccc', 'dddd'],
        ['123', '456', '789'],
        ['"aaa"', '"bbb"']
    ];

    $fp = fopen('file.csv', 'w');

    foreach ($list as $fields) {
         fputcsv($fp, $fields, ',', '"', '');
    }

    fclose($fp);
    ?>

L'exemple ci-dessus va écrire ce qui suit vers `file.csv`:

    aaa,bbb,ccc,dddd
    123,456,789
    """aaa""","""bbb"""

### Voir aussi

- fgetcsv() - Obtient une ligne depuis un pointeur de fichier et l'analyse pour des champs CSV
- str_getcsv() - Analyse une chaîne de caractères CSV dans un tableau
- SplFileObject::fgetcsv() - Récupère une ligne depuis le fichier et l'analyse comme étant des données CSV
- SplFileObject::fputcsv() - Écrit un tableau sous la forme d'une ligne CSV
- SplFileObject::setCsvControl() - Définit les options CSV
- SplFileObject::getCsvControl() - Récupère les options pour CSV

# fputs

(PHP 4, PHP 5, PHP 7, PHP 8)

fputs — Alias de fwrite()

### Description

Cette fonction est un alias de : fwrite().

# fread

(PHP 4, PHP 5, PHP 7, PHP 8)

fread — Lecture du fichier en mode binaire

### Description

function fread(resource `$stream`, int `$length`): string|false

fread() lit jusqu'à `length` octets dans le fichier référencé par `stream`. La lecture s'arrête lorsqu'une des conditions suivantes apparaît :

- `length` octets ont été lus
- la fin du fichier est atteinte
- un paquet devient disponible ou le temps socket timeout est passé (pour les flux réseau)
- si le flux est lu depuis le buffer, et qu'il ne représente pas un fichier plein, alors au moins une lecture d'un nombre d'octets équivalent à la taille du bloc (habituellement 8192) est réalisée ; suivant les données du buffer précédent, la taille des données retournées peut être supérieure à la taille du bloc.

### Liste de paramètres

`stream`
  Un pointeur de système de fichiers de type resource qui est habituellement créé en utilisant la fonction fopen().
`length`

  Taille `length` d'octets à lire.

### Valeurs de retour

Retourne la chaîne lue, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec fread()

    <?php
    // Lit un fichier, et le place dans une chaîne
    $filename = "/usr/local/something.txt";
    $handle = fopen($filename, "r");
    $contents = fread($handle, filesize($filename));
    fclose($handle);
    ?>

Exemple #2 Exemple avec fread() et un fichier binaire

Avertissement

Sur les systèmes qui différencient les fichiers textes et binaires (c.-à-d. Windows) le fichier doit être ouvert avec la lettre 'b' ajoutée au paramètre de mode de la fonction fopen().

    <?php
    $filename = "c:\\files\\somepic.gif";
    $handle = fopen($filename, "rb");
    $contents = fread($handle, filesize($filename));
    fclose($handle);
    ?>

Exemple #3 Exemple avec fread() et un fichier distant

Avertissement

Lors de la lecture depuis n'importe quelle source qui n'est pas un fichier local, comme des flux retournés lors de la lecture de fichiers distants ou depuis popen() et fsockopen(), la lecture s'arrête après la réception d'un paquet. Il faut donc faire des boucles pour collecter les données par paquet, comme présenté ci-dessous.

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    $contents = stream_get_contents($handle);
    fclose($handle);
    ?>

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    if (FALSE === $handle) {
        exit("Échec lors de l'ouverture du flux vers l'URL");
    }

    $contents = '';

    while (!feof($handle)) {
        $contents .= fread($handle, 8192);
    }
    fclose($handle);
    ?>

### Notes

> Note:

> Pour lire le contenu d'un fichier dans une chaîne de caractères, il est recommandé d'utiliser file_get_contents() qui est bien plus rapide que le code ci-dessus.

> Note:

> Noter que la fonction fread() lit la position courante du pointeur de fichier. Il est possible d'utiliser la fonction ftell() pour trouver la position courante du pointeur et la fonction rewind() pour réinitialiser la position du pointeur.

### Voir aussi

- fwrite() - Écrit un fichier en mode binaire
- fopen() - Ouvre un fichier ou une URL
- fsockopen() - Ouvre un socket de connexion Internet ou Unix
- popen() - Ouvre un pointeur de fichier de processus
- fgets() - Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier
- fgetss() - Renvoie la ligne courante du fichier et élimine les balises HTML
- fscanf() - Analyse un fichier en fonction d'un format
- file() - Lit le fichier et renvoie le résultat dans un tableau
- fpassthru() - Affiche le reste du fichier
- fseek() - Modifie la position du pointeur de fichier
- ftell() - Renvoie la position courante du pointeur de fichier
- rewind() - Replace le pointeur de fichier au début
- unpack() - Déconditionne des données depuis une chaîne binaire

# fscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fscanf — Analyse un fichier en fonction d'un format

### Description

function fscanf(resource `$stream`, string `$format`, mixed `&...$vars`): array|int|false|null

La fonction fscanf() est similaire à la fonction sscanf(), sauf qu'elle prend un fichier en entrée, représenté par la ressource `stream` et interprète l'entrée en fonction du format `format` spécifié.

Tous les caractères blancs de la chaîne de formatage correspondent à autant d'espaces dans le flux d'entrée. Cela signifie qu'une tabulation (`\t`) dans la chaîne de format peut remplacer un espace simple dans le flux d'entrée.

Chaque appel à la fonction fscanf() lit une ligne du fichier.

### Liste de paramètres

`stream`
  Un pointeur de système de fichiers de type resource qui est habituellement créé en utilisant la fonction fopen().
`format`

  Le format interprété pour `string` décrit dans la documentation de la sprintf() avec les différences suivantes :

  - La fonction ne tient pas compte du contexte local.
  - `F`, `g`, `G` et `b` ne sont pas supportés.
  - `D` représente un nombre décimal.
  - `i` représente un nombre entier avec détection de base.
  - `n` représente le nombre de caractères traités à ce stade.
  - `s` arrête la lecture à chaque caractère d'espacement.
  - `*` au lieu de `argnum$` supprime l'affectation de cette spécification de conversion.
`vars`
  Les valeurs optionnelles à assigner.

### Valeurs de retour

Si seulement 2 paramètres sont passés à la fonction, la valeur analysée sera retournée sous la forme d'un array. Si des paramètres optionnels sont passés, la fonction retourne le nombre de valeurs assignées. Les paramètres optionnels doivent être passés par référence.

S'il y a plus de sous-chaînes attendues dans le `format` que disponibles dans `string`, `null` sera retourné. Pour les autres erreurs, `false` sera retourné.

Lorsque des paramètres optionnels sont utilisés et que la fin de l'entrée lue depuis `stream` est atteinte avant qu'aucune valeur n'ait été analysée, `-1` est retourné.

### Exemples

Exemple #1 Exemple avec fscanf()

    <?php
    $handle = fopen("users.txt", "r");
    while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
        list ($name, $profession, $countrycode) = $userinfo;
        //... traitement des données
    }
    fclose($handle);
    ?>

Exemple #2 Contenu du fichier users.txt

    javier  argonaut        pe
    hiroshi sculptor        jp
    robert  slacker us
    luigi   florist it

### Voir aussi

- fread() - Lecture du fichier en mode binaire
- fgets() - Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier
- fgetss() - Renvoie la ligne courante du fichier et élimine les balises HTML
- sscanf() - Analyse une chaîne à l'aide d'un format
- printf() - Affiche une chaîne de caractères formatée
- sprintf() - Retourne une chaîne formatée

# fseek

(PHP 4, PHP 5, PHP 7, PHP 8)

fseek — Modifie la position du pointeur de fichier

### Description

function fseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Modifie le curseur de position dans le fichier `stream`. La nouvelle position, mesurée en octets, à partir du début du fichier, est obtenue en additionnant la distance `offset` à la position `whence`.

En général, il est possible de se déplacer au-delà de la fin du flux (eof) ; si des données sont alors écrites, la lecture de toute zone non écrite entre la fin du flux et la position visée renverra des octets de valeur 0. Cependant, certains flux ne supportent pas ce comportement, en particulier lorsque l'espace de stockage sous-jacent est de taille fixe.

### Liste de paramètres

`stream`
  Un pointeur de système de fichiers de type resource qui est habituellement créé en utilisant la fonction fopen().
`offset`

  La position.

  Pour se déplacer à une position avant la fin du fichier, une valeur négative dans le `offset` doit être passée et le paramètre `whence` doit être défini sur `SEEK_END`.

`whence`

  Les valeurs possibles pour `whence` sont :

  - `SEEK_SET` - Définir la position égale à `offset` octets depuis le début du fichier.
  - `SEEK_CUR` - Définir la position à l'emplacement actuel plus `offset` octets.
  - `SEEK_END` - Définir la position à la fin du fichier plus `offset` octets.

### Valeurs de retour

En cas de succès, retourne `0`; sinon, retourne `-1`.

Avertissement

Cette fonction a été créée pour imiter la fonction du même nom en langage C. Il faut faire attention aux valeurs de retour car elles diffèrent de ce que l'on pourrait attendre en PHP.

### Exemples

Exemple #1 Exemple avec fseek()

    <?php

    $fp = fopen('somefile.txt', 'r');

    // lit quelques données
    $data = fgets($fp, 4096);

    // retourne au début du fichier
    // identique à rewind($fp);
    fseek($fp, 0);

    ?>

### Notes

> Note:

> Si l'on ouvre le fichier avec le mode `a` ou `a+`, toutes les données que l'on écrira dans le fichier seront toujours ajoutées, sans se soucier de la position dans le fichier, et le résultat de l'appel à fseek() sera indéterminé.

> Note:

> Tous les flux ne supportent pas le déplacement. Pour ceux qui ne le supportent pas, le déplacement en avant se fera en lisant et libérant les octets; les autres formes de déplacements échoueront.

### Voir aussi

- ftell() - Renvoie la position courante du pointeur de fichier
- rewind() - Replace le pointeur de fichier au début

# fstat

(PHP 4, PHP 5, PHP 7, PHP 8)

fstat — Lit les informations sur un fichier à partir d'un pointeur de fichier

### Description

function fstat(resource `$stream`): array|false

Rassemble les informations sur le fichier dont on connaît le pointeur `stream`. fstat() est similaire à la fonction stat(), hormis le fait qu'elle utilise un pointeur de fichier, au lieu d'un nom de fichier.

### Liste de paramètres

`stream`
  Un pointeur de système de fichiers de type resource qui est habituellement créé en utilisant la fonction fopen().

### Valeurs de retour

Retourne un tableau contenant les statistiques pour le fichier ; le format de ce tableau est décrit en détail sur la page de documentation de la fonction stat(). Retourne `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec fstat()

    <?php

    // ouvre un fichier
    $fp = fopen("/etc/passwd", "r");

    // lit des informations
    $fstat = fstat($fp);

    // ferme le fichier
    fclose($fp);

    // affiche uniquement la partie associative
    print_r(array_slice($fstat, 13));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [dev] => 771
        [ino] => 488704
        [mode] => 33188
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 1114
        [atime] => 1061067181
        [mtime] => 1056136526
        [ctime] => 1056136526
        [blksize] => 4096
        [blocks] => 8
    )

### Notes

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

# fsync

(PHP 8 >= 8.1.0)

fsync — Synchronise les modifications apportées au fichier (y compris les métadonnées)

### Description

function fsync(resource `$stream`): bool

Cette fonction synchronise les modifications apportées au fichier, y compris ses métadonnées. Celle-ci est similaire à fflush(), mais elle demande également au système d'exploitation d'écrire sur le support de stockage.

### Liste de paramètres

`stream`
  Le pointeur de fichier doit être valide et pointer sur un fichier ouvert avec succès par fopen() ou fsockopen() (et pas encore fermé par fclose()).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec fsync()

    <?php
    $file = 'test.txt';
    $stream = fopen($file, 'w');
    fwrite($stream, 'test data');
    fwrite($stream, "\r\n");
    fwrite($stream, 'additional data');
    fsync($stream);
    fclose($stream);
    ?>

### Voir aussi

- fdatasync() - Synchronise les données (mais pas les métadonnées) avec le fichier
- fflush() - Envoie tout le contenu généré dans un fichier

# ftell

(PHP 4, PHP 5, PHP 7, PHP 8)

ftell — Renvoie la position courante du pointeur de fichier

### Description

function ftell(resource `$stream`): int|false

Renvoie la position courante du pointeur de fichier référencé par `stream`.

### Liste de paramètres

`stream`

  Le pointeur de fichier doit être valide, et avoir été correctement ouvert par fopen() ou popen(). ftell() donne des résultats non définis pour les flux "`append-only`" (ouvert avec le flag "a").

### Valeurs de retour

Retourne la position courante du pointeur dans le fichier repéré par le pointeur `stream` sous la forme d'un entier, c.-à-d., sa position dans le flux du fichier.

Si une erreur survient, la fonction retournera `false`.

> Note: Comme le type entier de PHP est signé et que de nombreuses plates-formes utilisent des entiers de 32 bits, certaines fonctions relatives au système de fichiers peuvent retourner des résultats étranges pour les fichiers de taille supérieure à 2 Go.

### Exemples

Exemple #1 Exemple avec ftell()

    <?php

    // Ouvre un fichier et y lit quelques données
    $fp = fopen("/etc/passwd", "r");
    $data = fgets($fp, 12);

    // Où en sommes-nous ?
    echo ftell($fp); // 11

    fclose($fp);

    ?>

### Voir aussi

- fopen() - Ouvre un fichier ou une URL
- popen() - Ouvre un pointeur de fichier de processus
- fseek() - Modifie la position du pointeur de fichier
- rewind() - Replace le pointeur de fichier au début

# ftruncate

(PHP 4, PHP 5, PHP 7, PHP 8)

ftruncate — Tronque un fichier

### Description

function ftruncate(resource `$stream`, int `$size`): bool

Prend le pointeur de fichier `stream` et le tronque à la taille de `size`.

### Liste de paramètres

`stream`

  Le pointeur de fichier.

  > Note:

  > Le pointeur `stream` doit avoir été ouvert en écriture.

`size`

  La taille que l'on doit conserver.

  > Note:

  > Si `size` est plus grand que la taille du fichier, ce dernier sera étendu par des octets nuls.

  > Si `size` est plus petit que la taille du fichier, le reste des données sera perdu.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ftruncate()

    <?php
    $filename = 'lorem_ipsum.txt';

    $handle = fopen($filename, 'r+');
    ftruncate($handle, rand(1, filesize($filename)));
    rewind($handle);
    echo fread($handle, filesize($filename));
    fclose($handle);
    ?>

### Notes

> Note:

> Le pointeur de fichier n'est pas modifié.

### Voir aussi

- fopen() - Ouvre un fichier ou une URL
- fseek() - Modifie la position du pointeur de fichier

# fwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

fwrite — Écrit un fichier en mode binaire

### Description

function fwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

fwrite() écrit le contenu de la chaîne `data` dans le fichier pointé par `stream`.

### Liste de paramètres

`stream`
  Un pointeur de système de fichiers de type resource qui est habituellement créé en utilisant la fonction fopen().
`data`

  La chaîne à écrire.

`length`

  Si la longueur `length` est fournie, l'écriture s'arrêtera après `length` octets, ou à la fin de la chaîne (le premier des deux).

### Valeurs de retour

fwrite() retourne le nombre d'octets écrits ou `false` si une erreur survient.

### Erreurs / Exceptions

La fonction fwrite() émet une `E_WARNING` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `length` est désormais nullable.

### Exemples

Exemple #1 Exemple avec fwrite()

    <?php
    $filename = 'test.txt';
    $somecontent = "Ajout de chaîne dans le fichier\n";

    // Assurons nous que le fichier est accessible en écriture
    if (is_writable($filename)) {

        // Dans notre exemple, nous ouvrons le fichier $filename en mode d'ajout
        // Le pointeur de fichier est placé à la fin du fichier
        // c'est là que $somecontent sera placé
        if (!$fp = fopen($filename, 'a')) {
             echo "Impossible d'ouvrir le fichier ($filename)";
             exit;
        }

        // Écrivons quelque chose dans notre fichier.
        if (fwrite($fp, $somecontent) === FALSE) {
            echo "Impossible d'écrire dans le fichier ($filename)";
            exit;
        }

        echo "L'écriture de ($somecontent) dans le fichier ($filename) a réussi";

        fclose($fp);

    } else {
        echo "Le fichier $filename n'est pas accessible en écriture.";
    }
    ?>

### Notes

> Note:

> Le fait d'écrire dans un flux réseau peut se terminer avant que la chaîne complète ne soit écrite. La valeur retournée par la fonction fwrite() peut être vérifiée comme ceci :

>     <?php
>     function fwrite_stream($fp, $string) {
>         for ($written = 0; $written < strlen($string); $written += $fwrite) {
>             $fwrite = fwrite($fp, substr($string, $written));
>             if ($fwrite === false) {
>                 return $written;
>             }
>         }
>         return $written;
>     }
>     ?>

> Note:

> Sur les systèmes qui font la différence entre les fichiers binaires et les fichiers textes (par exemple, Windows), le fichier doit être ouvert avec l'option 'b' incluse dans le paramètre de mode de fopen().

> Note:

> Si `stream` est ouvert en mode ajout (`append`), fwrite() sera atomique (sauf si la taille de `data` excède la taille du bloc du système de fichiers, sur quelques plates-formes, et tant que le fichier se trouve sur le système de fichiers local). Ainsi, il n'est pas nécessaire d'utiliser la fonction flock() sur une ressource avant d'appeler la fonction fwrite() ; toutes les données seront écrites sans interruption.

> Note:

> Si l'on écrit 2 fois dans le fichier, les données seront ajoutées à la fin du fichier ; cela signifie que l'exemple suivant ne donnera pas le résultat attendu :

>     <?php
>     $fp = fopen('data.txt', 'w');
>     fwrite($fp, '1');
>     fwrite($fp, '23');
>     fclose($fp);

>     // le contenu de 'data.txt' est maintenant 123 et non 23 !
>     ?>

### Voir aussi

- fread() - Lecture du fichier en mode binaire
- fopen() - Ouvre un fichier ou une URL
- fsockopen() - Ouvre un socket de connexion Internet ou Unix
- popen() - Ouvre un pointeur de fichier de processus
- file_get_contents() - Lit tout un fichier dans une chaîne
- pack() - Compacte des données dans une chaîne binaire

# glob

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

glob — Recherche des chemins qui vérifient un masque

### Description

function glob(string `$pattern`, int `$flags` = 0): array|false

glob() recherche tous les chemins qui vérifient le masque `pattern`, en suivant les règles utilisées par la fonction `glob()` de la libc, qui sont les mêmes que celles utilisées par le Shell en général.

Le comportement sur les systèmes Unix et macOS est déterminé par l'implémentation de glob() du système. Sous Windows, une implémentation conforme à la définition POSIX 1003.2 de glob() est utilisée, avec une extension pour gérer la convention `[!...]` permettant de nier une plage.

### Liste de paramètres

`pattern`

  Le masque. Aucun remplacement de tilde (`~`) ou de paramètre n'est fait.

  Caractères spéciaux :

  - `*` - Associe zéro ou plus de caractères.
  - `?` - Associe exactement un caractère (n'importe quel caractère).
  - `[...]` - Associe un caractère d'un ensemble de caractères. Si le premier caractère est `!`, associe n'importe quels caractères pas dans cet ensemble.
  - `{a,b,c}` - Associe une chaîne parmi un groupe de chaînes séparées par des virgules lorsque le drapeau `GLOB_BRACE` est utilisé.
  - `\` - Échappe le caractère suivant, sauf quand le drapeau `GLOB_NOESCAPE` est utilisé.
`flags`

  N'importe laquelle des constantes `GLOB_*`.

### Valeurs de retour

Retourne un tableau contenant les fichiers et dossiers correspondant au masque, un tableau vide s'il n'y a aucune correspondance, ou `false` si une erreur survient. Sauf si `GLOB_NOSORT` a été utilisé, les noms seront triés alphanumériquement.

### Exemples

Exemple #1 Un moyen pratique pour remplacer opendir() par glob()

    <?php
    foreach (glob("*.txt") as $filename) {
        echo "$filename occupe " . filesize($filename) . "\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    funclist.txt occupe 44686
    funcsummary.txt occupe 267625
    quickref.txt occupe 137820

Exemple #2 Exemple avec un motif plus complexe

    <?php
    foreach (glob("path/*/*.{txt,md}", \GLOB_BRACE) as $filename) {
        echo "$filename\n";
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    path/docs/mailinglist-rules.md
    path/docs/README.md
    path/docs/release-process.md
    path/pear/install-pear.txt
    path/Zend/README.md

### Notes

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

> Note: Cette fonction n'est pas disponible sur quelques systèmes (p. ex. vieux Sun OS).

### Voir aussi

- opendir() - Ouvre un dossier, et récupère un pointeur dessus
- readdir() - Lit une entrée du dossier
- closedir() - Ferme le pointeur sur le dossier
- fnmatch() - Teste un nom de fichier au moyen d'un masque de recherche

# is_dir

(PHP 4, PHP 5, PHP 7, PHP 8)

is_dir — Indique si le fichier est un dossier

### Description

function is_dir(string `$filename`): bool

Indique si le fichier est un dossier.

### Liste de paramètres

`filename`

  Chemin vers le fichier. Si `filename` est un fichier relatif, il sera vérifié relativement au dossier de travail courant. Si `filename` est un lien symbolique ou un lien conventionnel, le lien sera résolu et vérifié. Si l'on a activé open_basedir, plus de restrictions peuvent être appliquées.

### Valeurs de retour

Retourne `true` si le nom de fichier existe et que c'est un dossier, `false` sinon.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec is_dir()

    <?php
    var_dump(is_dir('a_file.txt'));
    var_dump(is_dir('bogus_dir/abc'));

    var_dump(is_dir('..')); // un dossier au-dessus
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(false)
    bool(true)

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- chdir() - Change de dossier
- dir() - Retourne une instance de la classe Directory
- opendir() - Ouvre un dossier, et récupère un pointeur dessus
- is_file() - Indique si le fichier est un véritable fichier
- is_link() - Indique si le fichier est un lien symbolique

# is_executable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_executable — Indique si le fichier est exécutable

### Description

function is_executable(string `$filename`): bool

Indique si le fichier est exécutable.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Retourne `true` si le fichier existe et qu'il est exécutable, `false` sinon. Sur les systèmes POSIX, un fichier est exécutable si le bit exécutable des permissions de fichier est défini. Sur Windows, voir la note ci-dessous.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec is_executable()

    <?php

    $file = '/home/vincent/somefile.sh';

    if (is_executable($file)) {
        echo $file.' est exécutable';
    } else {
        echo $file.' n\'est pas exécutable';
    }

    ?>

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

> Note: Sur Windows, un fichier est considéré exécutable, si c'est un fichier proprement exécutable tel que rapporté par l'API Win `GetBinaryType()`; pour des raisons de rétrocompatibilité, les fichiers qui ont comme extension .bat ou .cmd sont aussi considérés comme exécutables. Antérieur à PHP 7.4.0, tout fichier non vide avec une extension .exe ou .com était considéré exécutable. À noter que PATHEXT n'est pas pertinent pour is_executable().

### Voir aussi

- is_file() - Indique si le fichier est un véritable fichier
- is_link() - Indique si le fichier est un lien symbolique

# is_file

(PHP 4, PHP 5, PHP 7, PHP 8)

is_file — Indique si le fichier est un véritable fichier

### Description

function is_file(string `$filename`): bool

Indique si le fichier est un véritable fichier. Si `filename` est un lien symbolique, il résoudra le lien et fournira des informations sur le fichier référencé.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Retourne `true` si le nom de fichier existe et que c'est un fichier régulier, `false` sinon.

> Note: Comme le type entier de PHP est signé et que de nombreuses plates-formes utilisent des entiers de 32 bits, certaines fonctions relatives au système de fichiers peuvent retourner des résultats étranges pour les fichiers de taille supérieure à 2 Go.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec is_file()

    <?php
    var_dump(is_file('a_file.txt')) . "\n";
    var_dump(is_file('/usr/bin/')) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- is_dir() - Indique si le fichier est un dossier
- is_link() - Indique si le fichier est un lien symbolique
- SplFileInfo

# is_link

(PHP 4, PHP 5, PHP 7, PHP 8)

is_link — Indique si le fichier est un lien symbolique

### Description

function is_link(string `$filename`): bool

Indique si le fichier est un lien symbolique.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Retourne `true` si le nom de fichier existe et que c'est un lien symbolique, `false` sinon.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Création et vérification d'un lien symbolique

    <?php
    $link = 'uploads';

    if (is_link($link)) {
        echo readlink($link);
    } else {
        symlink('uploads.php', $link);
    }
    ?>

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- is_dir() - Indique si le fichier est un dossier
- is_file() - Indique si le fichier est un véritable fichier
- readlink() - Renvoie le contenu d'un lien symbolique
- symlink() - Crée un lien symbolique

# is_readable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_readable — Indique si un fichier existe et est accessible en lecture

### Description

function is_readable(string `$filename`): bool

Indique si un fichier existe et est accessible en lecture.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

### Valeurs de retour

Retourne `true` si le fichier ou le dossier spécifié par `filename` existe et est accessible en lecture, `false` sinon.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec is_readable()

    <?php
    $filename = 'test.txt';
    if (is_readable($filename)) {
        echo 'Le fichier est accessible en lecture';
    } else {
        echo 'Le fichier n\'est pas accessible en lecture !';
    }
    ?>

### Notes

Il est à noter que PHP accède aux fichiers avec les mêmes autorisations que l'utilisateur qui fait tourner le serveur web (souvent, c'est 'nobody', personne).

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

> Note:

> La vérification est effectuée en utilisant l'UID/GID réel au lieu de l'effectif.

Cette fonction peut retourner `true` pour les dossiers. Il convient d'utiliser la fonction is_dir() pour distinguer les fichiers et les dossiers.

### Voir aussi

- is_writable() - Indique si un fichier est accessible en écriture
- file_exists() - Vérifie si un fichier ou un dossier existe
- fgets() - Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier

# is_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

is_uploaded_file — Indique si le fichier a été téléchargé par HTTP POST

### Description

function is_uploaded_file(string `$filename`): bool

Retourne `true` si le fichier `filename` a été téléchargé par HTTP POST. Cela est très utile pour s'assurer qu'un utilisateur n'essaie pas d'accéder intentionnellement à un fichier auquel il n'a pas de droits (comme /etc/passwd).

Ce type de vérification est spécialement important s'il est possible que les fichiers téléchargés révèlent leur contenu à l'utilisateur, ou même aux utilisateurs du même système.

Pour un fonctionnement correct, la fonction is_uploaded_file() nécessite un argument comme $_FILES['userfile']['tmp_name'], - le nom du fichier téléchargé sur la machine cliente $_FILES['userfile']['name'] ne fonctionne pas.

### Liste de paramètres

`filename`

  Le nom de fichier à vérifier.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec is_uploaded_file()

    <?php

    if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
       echo "Fichier ". $_FILES['userfile']['name'] ." téléchargé avec succès.\n";
       echo "Affichage du contenu\n";
       readfile($_FILES['userfile']['tmp_name']);
    } else {
       echo "Attaque possible par téléchargement de fichier : ";
       echo "Nom du fichier : '". $_FILES['userfile']['tmp_name'] . "'.";
    }

    ?>

### Voir aussi

- move_uploaded_file() - Déplace un fichier téléchargé
- $_FILES
- Voir la section sur la gestion des téléchargements pour un exemple d'utilisation simple.

# is_writable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writable — Indique si un fichier est accessible en écriture

### Description

function is_writable(string `$filename`): bool

retourne `true` si `filename` existe et est accessible en écriture. L'argument peut être le nom d'un dossier, permettant ainsi de vérifier si le dossier est accessible en écriture.

Il est à noter que PHP accède aux fichiers avec les mêmes autorisations que l'utilisateur qui fait tourner le serveur web (souvent, c'est '`nobody`', personne).

### Liste de paramètres

`filename`

  Le nom du fichier à vérifier.

### Valeurs de retour

Retourne `true` si le fichier `filename` existe et est accessible en écriture.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Exemple avec is_writable()

    <?php
    $filename = 'test.txt';
    if (is_writable($filename)) {
        echo 'Le fichier est accessible en écriture.';
    } else {
        echo 'Le fichier n\'est pas accessible en écriture !';
    }
    ?>

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- is_readable() - Indique si un fichier existe et est accessible en lecture
- file_exists() - Vérifie si un fichier ou un dossier existe
- fwrite() - Écrit un fichier en mode binaire

# is_writeable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writeable — Alias de is_writable()

### Description

Cette fonction est un alias de : is_writable().

# lchgrp

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchgrp — Change l'appartenance du groupe d'un lien symbolique

### Description

function lchgrp(string `$filename`, string|int `$group`): bool

Essaie de remplacer le groupe du lien symbolique `filename` par le groupe `group`.

Seul le super-utilisateur peut changer le groupe d'un lien symbolique arbitrairement ; les autres utilisateurs peuvent changer le groupe d'un lien symbolique vers un groupe auquel cet utilisateur est membre.

### Liste de paramètres

`filename`

  chemin vers le lien symbolique.

`group`

  Le groupe, spécifié par son nom ou son numéro.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Modification du groupe d'un lien symbolique

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchgrp($link, 8);
    ?>

### Notes

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

> Note: Cette fonction n'est pas implémentée sur les plates-formes Windows.

### Voir aussi

- chgrp() - Change le groupe d'un fichier
- lchown() - Change le propriétaire d'un lien symbolique
- chown() - Change le propriétaire du fichier
- chmod() - Change le mode du fichier

# lchown

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchown — Change le propriétaire d'un lien symbolique

### Description

function lchown(string `$filename`, string|int `$user`): bool

Essaie de remplacer le propriétaire du lien symbolique `filename` par l'utilisateur `user`.

Seul le super-utilisateur peut changer le propriétaire d'un lien symbolique.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

`user`

  L'utilisateur, par son nom ou son numéro.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Modification du propriétaire d'un lien symbolique

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchown($link, 8);
    ?>

### Notes

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

> Note: Cette fonction n'est pas implémentée sur les plates-formes Windows.

### Voir aussi

- chown() - Change le propriétaire du fichier
- lchgrp() - Change l'appartenance du groupe d'un lien symbolique
- chgrp() - Change le groupe d'un fichier
- chmod() - Change le mode du fichier

# link

(PHP 4, PHP 5, PHP 7, PHP 8)

link — Crée un lien physique

### Description

function link(string `$target`, string `$link`): bool

link() crée un lien physique.

### Liste de paramètres

`target`

  La cible du lien.

`link`

  Le nom du lien.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

La fonction échoue, et émet une `E_WARNING`, si `link` existe déjà, ou si `target` n'existe pas.

### Exemples

Exemple #1 Création d'un lien physique simple

    <?php

    $target = 'source.ext'; // Ceci est le fichier qui existe actuellement
    $link = 'newfile.ext';  // Ceci sera le nom du fichier à lier

    link($target, $link);
    ?>

### Notes

> Note: Cette fonction ne fonctionne pas avec les fichiers distants, car le fichier examiné doit être accessible sur le système de fichiers du serveur.

> Note: Windows uniquement : cette fonction requiert un niveau de fonctionnement avec des droits élevés, ou bien la désactivation d'UAC.

### Voir aussi

- symlink() - Crée un lien symbolique
- readlink() - Renvoie le contenu d'un lien symbolique
- linkinfo() - Renvoie les informations d'un lien
- unlink() - Supprime un fichier

# linkinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

linkinfo — Renvoie les informations d'un lien

### Description

function linkinfo(string `$path`): int|false

Renvoie les informations d'un lien.

Cette fonction est utilisée pour vérifier si un lien (pointé par le chemin `path`) existe réellement (en utilisant la même méthode que la macro S_ISLNK, définie dans stat.h).

### Liste de paramètres

`path`

  Chemin vers le lien.

### Valeurs de retour

linkinfo() retourne le champ `st_dev` de la structure stat Unix C, retourné par l'appel système `lstat`. Retourne un entier non négatif en cas de succès, -1 dans le cas où le lien n'a pas été trouvé, ou `false` si une violation open.base_dir survient.

### Exemples

Exemple #1 Exemple avec linkinfo()

    <?php

    echo linkinfo('/vmlinuz'); // 835

    ?>

### Voir aussi

- symlink() - Crée un lien symbolique
- link() - Crée un lien physique
- readlink() - Renvoie le contenu d'un lien symbolique

# lstat

(PHP 4, PHP 5, PHP 7, PHP 8)

lstat — Retourne les informations sur un fichier ou un lien symbolique

### Description

function lstat(string `$filename`): array|false

Rassemble les statistiques du fichier ou du lien symbolique désigné par `filename`.

### Liste de paramètres

`filename`

  Chemin vers un fichier ou un lien symbolique.

### Valeurs de retour

Se reporter à la page de manuel de stat() pour plus d'informations sur la structure du tableau retourné par lstat(). Cette fonction est identique à la fonction stat() hormis le fait que si `filename` est un lien symbolique, les informations seront alors basées sur le lien symbolique.

En cas d'échec, `false` est retourné.

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Comparaison entre stat() et lstat()

    <?php
    symlink('uploads.php', 'uploads');

    // On met en évidence la différence d'informations
    array_diff(stat('uploads'), lstat('uploads'));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Informations qui diffèrent entre les 2 fichiers.

    Array
    (
        [ino] => 97236376
        [mode] => 33188
        [size] => 34
        [atime] => 1223580003
        [mtime] => 1223581848
        [ctime] => 1223581848
        [blocks] => 8
    )

### Notes

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- stat() - Renvoie les informations à propos d'un fichier

# mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

mkdir — Crée un dossier

### Description

function mkdir(
string `$directory`,
int `$permissions` = 0777,
bool `$recursive` = `false`,
?resource `$context` = `null`
): bool

Tente de créer le dossier spécifié par `directory`.

### Liste de paramètres

`directory`

  Le chemin du dossier.

  Astuce

  Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

`permissions`

  Les permissions par défaut sont 0777, ce qui correspond au maximum de droits possible. Pour plus d'informations sur les permissions, se référer à la documentation de la fonction chmod().

  > Note:

  > `permissions` est ignoré sous Windows.

  Il est à noter que l'on aura à préciser les `permissions` en base octale, ce qui signifie que l'on aura probablement un 0 comme premier chiffre. Les `permissions` seront aussi modifiées par le umask courant, qu'il est possible de modifier avec la fonction umask().

`recursive`

  Si `true`, alors tous les répertoires parents au `directory` spécifié seront également créés, avec les mêmes permissions.

`context`

  > Note: Une resource de contexte de flux.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

> Note:

> Si le répertoire à créer existe déjà, cela est considéré comme une erreur et `false` sera toujours retourné. Les fonctions is_dir() ou file_exists() peuvent être utilisées pour vérifier si le répertoire existe déjà avant d'essayer de le créer.

### Erreurs / Exceptions

Émet une alerte de niveau `E_WARNING` si le dossier existe déjà.

Émet une alerte de niveau `E_WARNING` si les permissions empêchent la création du dossier.

### Exemples

Exemple #1 Exemple avec mkdir()

    <?php
    mkdir("/path/to/my/dir", 0700);
    ?>

Exemple #2 mkdir() utilisant le paramètre `recursive`

    <?php
    // Structure de dossier désirée
    $structure = './depth1/depth2/depth3/';

    // Pour créer une structure imbriquée, le paramètre $recursive
    // doit être spécifié.

    if (!mkdir($structure, 0777, true)) {
        die('Échec lors de la création des dossiers...');
    }

    // ...
    ?>

### Voir aussi

- is_dir() - Indique si le fichier est un dossier
- rmdir() - Efface un dossier
- umask() - Change le "umask" courant

# move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

move_uploaded_file — Déplace un fichier téléchargé

### Description

function move_uploaded_file(string `$from`, string `$to`): bool

S'assure que le fichier `from` est un fichier téléchargé par HTTP POST. Si le fichier est valide, il est déplacé jusqu'à `to`.

Ce type de vérification est spécialement important s'il est possible que les fichiers téléchargés révèlent leur contenu à l'utilisateur, ou même aux utilisateurs du même système.

### Liste de paramètres

`from`

  Le nom du fichier téléchargé.

`to`

  La destination du fichier déplacé.

### Valeurs de retour

Retourne `true` en cas de succès.

Si `from` n'est pas valide, rien ne se passe, et move_uploaded_file() retournera `false`.

Si `from` est un fichier téléchargé, mais que pour une raison quelconque, il ne peut être déplacé, rien ne se passe, et move_uploaded_file() retourne `false`. De plus, une alerte est affichée.

### Exemples

Exemple #1 Téléchargement de plusieurs fichiers

    <?php
    $uploads_dir = '/uploads';
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() peut empêcher les attaques de système de fichiers;
            // la validation/assainissement supplémentaire du nom de fichier peut être approprié
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "$uploads_dir/$name");
        }
    }
    ?>

### Notes

> Note:

> move_uploaded_file() tient compte de l'open_basedir. Cependant, les restrictions sont placées uniquement sur le paramètre `to` qui permet le déplacement des fichiers chargés dans lesquels `from` peut entrer en conflit avec ces restrictions. move_uploaded_file() permet de s'assurer de la sécurité de cette opération en autorisant le déplacement des seuls fichiers chargés via PHP.

Avertissement

Si le fichier de destination existe déjà, il sera écrasé.

### Voir aussi

- is_uploaded_file() - Indique si le fichier a été téléchargé par HTTP POST
- rename() - Renomme un fichier ou un dossier
- Voir la section sur les téléchargements de fichiers pour un exemple d'utilisation

# parse_ini_file

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_ini_file — Analyse un fichier de configuration

### Description

function parse_ini_file(string `$filename`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_file() charge le fichier `filename` et retourne les configurations qui s'y trouvent sous forme d'un tableau associatif.

La structure des fichiers de configuration lus est similaire à celle de php.ini.

Avertissement

Cette fonction ne doit pas être utilisée avec des entrées non fiables, sauf si `scanner_mode` est `INI_SCANNER_RAW` car la sortie analysée pourrait contenir les valeurs de constantes sensibles, telles que des constantes contenant un mot de passe de base de données.

### Liste de paramètres

`filename`

  Le nom du fichier de configuration à analyser. Si un chemin relatif est utilisé, il est évalué relatif au dossier courant actuel, puis selon le include_path.

`process_sections`

  En passant le paramètre `process_sections` à `true`, le résultat sera un tableau multidimensionnel, incluant les noms des sections et les configurations. La valeur par défaut de ce paramètre est `false`

`scanner_mode`

  Peut être `INI_SCANNER_NORMAL` (défaut) ou `INI_SCANNER_RAW`. Si `INI_SCANNER_RAW` est fourni, alors les valeurs en option ne seront pas analysées.

  À parti de PHP 5.6.1 peut aussi être spécifié comme `INI_SCANNER_TYPED`. Dans ce mode les booléens, null et entiers sont préservés tant que possible. Les chaines de caractères `"true"`, `"on"` et `"yes"` sont converties vers `true`. `"false"`, `"off"`, `"no"` et `"none"` sont considérés comme `false`. `"null"` est converti en `null` dans ce mode. De plus toutes les chaines de caractères numériques sont converties en entier si possible.

### Valeurs de retour

La configuration est retournée sous la forme d'un tableau associatif en cas de succès, et `false` si une erreur survient.

### Exemples

Exemple #1 Contenu du fichier sample.ini

    ; Ceci est un fichier de configuration
    ; Les commentaires commencent par ';', comme dans php.ini

    [first_section]
    one = 1
    five = 5
    animal = BIRD

    [second_section]
    path = "/usr/local/bin"
    URL = "http://www.example.com/~username"

    [third_section]
    phpversion[] = "5.0"
    phpversion[] = "5.1"
    phpversion[] = "5.2"
    phpversion[] = "5.3"

    urls[svn] = "http://svn.php.net"
    urls[git] = "http://git.php.net"

Exemple #2 Exemple avec parse_ini_file()

Les constantes (mais pas les "constantes magiques" telles que `__FILE__`) peuvent aussi être utilisées dans le fichier .ini, ce qui fait que si l'on définit une constante avant d'exécuter parse_ini_file(), elle sera intégrée dans les résultats. Seules les valeurs de configuration sont évaluées, et la valeur doit juste être la constante. Par exemple :

    <?php

    define('BIRD', 'Dodo bird');

    // Analyse sans sections
    $ini_array = parse_ini_file("sample.ini");
    print_r($ini_array);

    // Analyse avec sections
    $ini_array = parse_ini_file("sample.ini", true);
    print_r($ini_array);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [one] => 1
        [five] => 5
        [animal] => Dodo bird
        [path] => /usr/local/bin
        [URL] => http://www.example.com/~username
        [phpversion] => Array
            (
                [0] => 5.0
                [1] => 5.1
                [2] => 5.2
                [3] => 5.3
            )

        [urls] => Array
            (
                [svn] => http://svn.php.net
                [git] => http://git.php.net
            )

    )
    Array
    (
        [first_section] => Array
            (
                [one] => 1
                [five] => 5
                [animal] => Dodo bird
            )

        [second_section] => Array
            (
                [path] => /usr/local/bin
                [URL] => http://www.example.com/~username
            )

        [third_section] => Array
            (
                [phpversion] => Array
                    (
                        [0] => 5.0
                        [1] => 5.1
                        [2] => 5.2
                        [3] => 5.3
                    )

                [urls] => Array
                    (
                        [svn] => http://svn.php.net
                        [git] => http://git.php.net
                    )

            )

    )

Exemple #3 parse_ini_file() pour analyser un fichier php.ini

    <?php
    // Une fonction simple pour comparer les résultats ci-dessous
    function yesno($expression)
    {
        return($expression ? 'Yes' : 'No');
    }

    // Lit le chemin du php.ini en utilisant php_ini_loaded_file()
    $ini_path = php_ini_loaded_file();

    // Analyse de php.ini
    $ini = parse_ini_file($ini_path);

    // Affichage et comparatif des valeurs. Il est à noter que get_cfg_var()
    // va donner les mêmes résultats entre les résultats analysés et chargés
    echo '(analysé) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
    echo '(chargé ) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    (analysé) magic_quotes_gpc = Yes
    (chargé ) magic_quotes_gpc = Yes

Exemple #4 Interpolation de Valeur

En plus d'évaluer les constantes, certains caractères ont une signification particulière dans une valeur ini. Additionnellement, les variables d'environnement et options de configuration définies précédemment (voir get_cfg_var()) peuvent être lues en utilisant la syntaxe `${}`.

    ; | est utilisé pour le OU bit à bit
    three = 2|3

    ; & est utilisé pour le ET bit à bit
    four = 6&5

    ; ^ est utilisé pour le OU exclusif bit à bit
    five = 3^6

    ; ~ est utilisé pour la négation bit à bit
    negative_two = ~1

    ; () est utilisé pour le regroupement
    seven = (8|7)&(6|5)

    ; Interpoler la variable d'environnement PATH
    path = ${PATH}

    ; Interpoler l'option de configuration 'memory_limit'
    configured_memory_limit = ${memory_limit}

Exemple #5 Échapper des Caractères

Certains caractères ont une signification particulière dans les chaînes à guillemets doubles et doivent être échappés en les préfixant d'un antislash. Tout d'abord, ce sont les guillemets double `"` comme le marqueur de frontière, et l'antislash `\` lui-même (si suivi d'un des caractères spéciaux) :

    quoted = "She said \"Exactly my point\"." ; Donne une chaîne contenant des guillemets.
    hint = "Use \\\" to escape double quote" ; Donne : Use \" to escape double quote

Il y a une exception pour les chemins Windows-esque : il est possible de ne pas échapper l'antislash traînant si la chaîne citée est directement suivie d'un retour à la ligne :

    save_path = "C:\Temp\"

Si l'on doit échapper un guillemet double suivi d'un retour à la ligne dans une valeur multiligne, il est possible d'utiliser la concaténation de valeur de la manière suivante (il y a une chaîne à guillemet double directement suivie d'une autre) :

    long_text = "Lorem \"ipsum\"""
     dolor" ; Donne : Lorem "ipsum"\n dolor

Un autre caractère avec une signification particulière est `$` (le signe dollar). Il doit être échappé s'il est suivi d'une accolade ouvrante :

    code = "\${test}"

L'échappement de caractères n'est pas supporté dans le mode `INI_SCANNER_RAW` (dans ce mode tous les caractères sont traités "tels quels").

Il est à noter que l'analyseur INI ne supporte pas les séquences d'échappement standard (`\n`, `\t`, etc.). Si nécessaire, le résultat de parse_ini_file() doit être post-procédé avec la fonction stripcslashes().

### Notes

> Note:

> Cette fonction n'a rien à voir avec le fichier php.ini. Ce dernier a déjà été traité lorsque l'on commence à exécuter le script. Cette fonction peut permettre de lire ses propres fichiers de configuration.

> Note:

> Si une valeur du fichier ini contient des données non-alphanumériques, il faut la protéger en la plaçant entre guillemets doubles (").

> Note: Il existe des mots réservés qui ne doivent pas être utilisés en tant que clés dans les fichiers ini. Cela inclut : `null`, `yes`, `no`, `true`, `false`, `on`, `off` et `none`. Les valeurs `null`, `off`, `no` et `false` donnent `""`, et les valeurs `on`, `yes` et `true` donnent `"1"`, à moins que le mode `INI_SCANNER_TYPED` ne soit utilisé. Les caractères `?{}|&~!()^"` ne doivent pas être utilisés n'importe où dans la clé et ont une signification spéciale dans la valeur.

> Note:

> Les entrées sans un signal égal seront ignorées. Par exemple, "foo" sera ignoré alors que "bar =" sera analysé et ajouté avec une valeur vide. Par exemple, MySQL a une option de configuration "no-auto-rehash" dans le fichier my.cnf qui ne prend pas de valeur, aussi, elle sera ignorée.

> Note:

> Les fichiers ini sont généralement traités comme des fichiers de texte brut par les serveurs web, et donc envoyés au navigateur si demandé. Ceci signifie que pour la sécurité soit les fichiers ini doivent être stockés en dehors de la racine docroot, soit reconfigurer le serveur web pour ne pas les servir. L'échec de faire l'une de ces mesures peut introduire un risque de sécurité.

### Voir aussi

- parse_ini_string() - Analyse une chaîne de configuration

# parse_ini_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

parse_ini_string — Analyse une chaîne de configuration

### Description

function parse_ini_string(string `$ini_string`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_string() retourne la configuration dans la chaîne `ini_string` dans un tableau associatif.

La structure de la chaîne doit être la même que celle du fichier php.ini.

Avertissement

Cette fonction ne doit pas être utilisée avec des entrées non fiables, sauf si `scanner_mode` est `INI_SCANNER_RAW` car la sortie analysée pourrait contenir les valeurs de constantes sensibles, telles que des constantes contenant un mot de passe de base de données.

### Liste de paramètres

`ini_string`

  Le contenu de type ini à analyser.

`process_sections`

  En activant le paramètre `process_sections` avec `true`, le résultat sera un tableau multidimensionnel, avec les noms de sections et de directives. La valeur par défaut du paramètre `process_sections` est `false`

`scanner_mode`

  Peut prendre les valeurs des constantes `INI_SCANNER_NORMAL` (par défaut) ou `INI_SCANNER_RAW`. Si `INI_SCANNER_RAW` est utilisé, les valeurs des options ne seront pas analysées.

  À parti de PHP 5.6.1 peut aussi être spécifié comme `INI_SCANNER_TYPED`. Dans ce mode les booléens, null et entiers sont préservés tant que possible. Les chaines de caractères `"true"`, `"on"` et `"yes"` sont converties vers `true`. `"false"`, `"off"`, `"no"` et `"none"` sont considérés comme `false`. `"null"` est converti en `null` dans ce mode. De plus toutes les chaines de caractères numériques sont converties en entier si possible.

### Valeurs de retour

Les directives sont retournées sous forme de tableau array en cas de succès, et `false` en cas d'erreur.

### Notes

> Note: Il y a plusieurs mots réservés qui ne doivent pas être utilisés comme clé dans les fichiers .ini. Cela inclut : `null`, `yes`, `no`, `true`, `false`, `on`, `off`, `none`. Les valeurs `null`, `off`, `no` et `false` sont retournées comme `""`, et les valeurs `on`, `yes` et `true` sont retournées comme `"1"`, à moins que le mode `INI_SCANNER_TYPED` ne soit utilisé. Les caractères `?{}|&~![()^"` ne doivent être utilisés nulle part dans les clés, et ont une signification spéciale dans les valeurs.

### Voir aussi

- parse_ini_file() - Analyse un fichier de configuration

# pathinfo

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pathinfo — Retourne des informations sur un chemin système

### Description

function pathinfo(string `$path`, int `$flags` = `PATHINFO_ALL`): array|string

pathinfo() retourne des informations sur le chemin `path`, sous forme de chaîne ou de tableau associatif, ceci dépend du paramètre `flags`.

> Note:

> Pour plus d'informations sur la lecture du chemin courant, se référer à la section sur les variables prédéfinies.

> Note:

> pathinfo() opère naïvement sur la chaîne d'entrée, et n'est pas consciente du système de fichiers actuel, ou des composants de chemins tels que "`..`".

> Note:

> Sur les systèmes Windows uniquement, le caractère `\` sera interprété comme un séparateur de répertoire. Sur les autres systèmes, il sera traité comme n'importe quel autre caractère.

Attention

La fonction pathinfo() est sensible à la configuration locale, aussi, pour qu'elle analyse correctement un chemin contenant les caractères sur plusieurs octets, la locale correspondante doit être définie en utilisant la fonction setlocale().

### Liste de paramètres

`path`

  Le chemin à analyser.

`flags`

  Spécifie quel élément sera retourné. Il est possible de passer l'une des constantes `PATHINFO_DIRNAME`, `PATHINFO_BASENAME`, `PATHINFO_EXTENSION` et `PATHINFO_FILENAME`.

  Si `flags` n'est pas renseigné, tous les éléments sont retournés.

### Valeurs de retour

Si `flags` n'est pas utilisé, cette fonction retourne un tableau associatif contenant les éléments suivants : `dirname`, `basename`, `extension` (s'il y en a), et `filename`.

> Note:

> Si `path` contient plus d'une extension, `PATHINFO_EXTENSION` retourne uniquement le dernier et `PATHINFO_FILENAME` va supprimer uniquement le dernier également (voir le premier exemple ci-dessous).

> Note:

> Si `path` n'a pas d'extension, l'élément `extension` ne sera pas retourné (voir le second exemple ci-après).

> Note:

> Si `basename` du paramètre `path` commence par un point, les caractères suivants sont interprétés comme l' `extension`, et le `filename` sera vide (voir le troisième exemple ci-dessous).

Si `flags` est présent, cette fonction retourne une chaîne de caractères contenant l'élément demandé.

### Exemples

Exemple #1 Exemple avec pathinfo()

    <?php
    $path_parts = pathinfo('/www/htdocs/inc/lib.inc.php');

    echo $path_parts['dirname'], "\n";
    echo $path_parts['basename'], "\n";
    echo $path_parts['extension'], "\n";
    echo $path_parts['filename'], "\n";
    ?>

L'exemple ci-dessus va afficher :

    /www/htdocs/inc
    lib.inc.php
    php
    lib.inc

Exemple #2 Exemple pathinfo() montrant la différence entre null et l'absence d'extension

    <?php
    $path_parts = pathinfo('/path/emptyextension.');
    var_dump($path_parts['extension']);

    $path_parts = pathinfo('/path/noextension');
    var_dump($path_parts['extension']);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(0) ""

    Notice: Undefined index: extension in test.php on line 6
    NULL

Exemple #3 Exemple pathinfo() pour un fichier caché (dot-file)

    <?php
    print_r(pathinfo('/some/path/.test'));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [dirname] => /some/path
        [basename] => .test
        [extension] => test
        [filename] =>
    )

Exemple #4 Exemple de pathinfo() avec déréférencement de tableau

Le paramètre `flags` n'est pas un masque de bits. Seule une valeur peut être fournie. Pour sélectionner uniquement un ensemble limité de valeurs analysées, il convient d'utiliser la déstructuration de tableau comme ceci :

    <?php
    ['basename' => $basename, 'dirname' => $dirname] = pathinfo('/www/htdocs/inc/lib.inc.php');

    var_dump($basename, $dirname);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    string(11) "lib.inc.php"
    string(15) "/www/htdocs/inc"

### Voir aussi

- dirname() - Renvoie le chemin du dossier parent
- basename() - Retourne le nom de la composante finale d'un chemin
- parse_url() - Analyse une URL et retourne ses composants
- realpath() - Retourne le chemin canonique absolu

# pclose

(PHP 4, PHP 5, PHP 7, PHP 8)

pclose — Ferme un pointeur de fichier de processus

### Description

function pclose(resource `$handle`): int

Ferme un pointeur de fichier vers un pipe ouvert par la fonction popen().

### Liste de paramètres

`handle`

  Le pointeur de fichier doit être valide, et avoir été ouvert correctement par popen().

### Valeurs de retour

Retourne le statut final du processus exécuté ou `-1` en cas d'échec.

> Note: Si PHP a été compilé avec l'option de configuration --enable-sigchild, la valeur retournée de cette fonction sera indéfinie.

### Exemples

Exemple #1 Exemple avec pclose()

    <?php
    $handle = popen('/bin/ls', 'r');
    pclose($handle);
    ?>

### Notes

> Note: Unix seulement :

> pclose() est implémenté en interne en utilisant l'appel système `waitpid(3)`. Pour obtenir le code de statut réel de sortie, la fonction pcntl_wexitstatus() devrait être utilisée.

### Voir aussi

- popen() - Ouvre un pointeur de fichier de processus

# popen

(PHP 4, PHP 5, PHP 7, PHP 8)

popen — Ouvre un pointeur de fichier de processus

### Description

function popen(string `$command`, string `$mode`): resource|false

Ouvre un pipe vers un processus exécuté en effectuant un fork de la commande fournie par le paramètre `command`.

### Liste de paramètres

`command`

  La commande

`mode`

  Le mode. Soit `'r'` pour lecture, soit `'w'` pour l'écriture.

  Sur Windows, popen() utilise le mode texte par défaut, c.-à-d. tous les caractères `\n` écrits ou lus du pipe seront traduits en `\r\n`. Si ceci n'est pas désiré, le mode binaire peut être forcé en définissant le `mode` à `'rb'` et `'wb'`, respectivement.

### Valeurs de retour

Retourne un pointeur de fichier identique à celui retourné par fopen(), hormis le fait qu'il sera unidirectionnel (lecture seule, ou écriture seule), et doit être terminé par pclose(). Ce pointeur peut être utilisé avec fgets(), fgetss() et fwrite(). Lorsque le mode est 'r', le pointeur de fichier retourné équivaut au STDOUT de la commande, et lorsque le mode est 'w', le pointeur de fichier retourné équivaut au STDIN de la commande.

Si une erreur survient, la fonction retourne `false`.

### Exemples

Exemple #1 Exemple avec popen()

    <?php
    $handle = popen("/bin/ls", "r");
    ?>

Si la commande à exécuter n'a pu être trouvée, une ressource valide sera retournée. Cela semble étrange, mais c'est pratique. Cela permet d'accéder aux messages d'erreur qui ont été retournés par le Shell :

Exemple #2 Exemple avec popen()

    <?php
    error_reporting(E_ALL);

    /* Ajoute une redirection pour pouvoir lire stderr. */
    $handle = popen('/path/to/executable 2>&1', 'r');
    echo "'$handle'; " . gettype($handle) . "\n";
    $read = fread($handle, 2096);
    echo $read;
    pclose($handle);
    ?>

### Notes

> Note:

> Pour un support bidirectionnel (two-way), il convient d'utiliser la fonction proc_open().

### Voir aussi

- pclose() - Ferme un pointeur de fichier de processus
- fopen() - Ouvre un fichier ou une URL
- proc_open() - Exécute une commande et ouvre les pointeurs de fichiers pour les entrées / sorties

# readfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readfile — Affiche un fichier

### Description

function readfile(string `$filename`, bool `$use_include_path` = `false`, ?resource `$context` = `null`): int|false

Lit un fichier et l'envoie dans le buffer de sortie.

### Liste de paramètres

`filename`

  Le fichier à lire.

`use_include_path`

  Il est possible d'utiliser le deuxième paramètre optionnel pour explorer le dossier include_path, en passant la valeur de `true`.

`context`

  > Note: Une resource de contexte de flux.

### Valeurs de retour

Retourne le nombre d'octets lus depuis le fichier en cas de succès, ou `false` si une erreur survient

### Erreurs / Exceptions

En cas d'échec, une alerte de type `E_WARNING` sera émise.

### Exemples

Exemple #1 Forcer le téléchargement en utilisant readfile()

    <?php
    $file = 'monkey.gif';

    if (file_exists($file)) {
        header('Content-Description: File Transfer');
        header('Content-Type: application/octet-stream');
        header('Content-Disposition: attachment; filename="'.basename($file).'"');
        header('Expires: 0');
        header('Cache-Control: must-revalidate');
        header('Pragma: public');
        header('Content-Length: ' . filesize($file));
        readfile($file);
        exit;
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Notes

> Note:

> readfile() ne présentera pas de problème mémoire, même lors de l'envoi de gros fichiers. En cas de ce type de problème, il faut s'assurer que la mise en mémoire tampon de la sortie est désactivée avec la fonction ob_get_level().

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Voir aussi

- fpassthru() - Affiche le reste du fichier
- file() - Lit le fichier et renvoie le résultat dans un tableau
- fopen() - Ouvre un fichier ou une URL
- include - include
- require - require
- virtual() - Effectue une sous-requête Apache
- file_get_contents() - Lit tout un fichier dans une chaîne
- Liste des protocoles et des gestionnaires supportés

# readlink

(PHP 4, PHP 5, PHP 7, PHP 8)

readlink — Renvoie le contenu d'un lien symbolique

### Description

function readlink(string `$path`): string|false

readlink() effectue la même chose que la fonction C `readlink`.

### Liste de paramètres

`path`

  Le chemin vers le lien symbolique.

### Valeurs de retour

Retourne le contenu du lien symbolique ou `false` si une erreur survient.

> Note: La fonction échoue si le paramètre `path` n'est pas un lien symbolique, sauf sous Windows, où le chemin normalisé sera retourné.

### Exemples

Exemple #1 Exemple avec readlink()

    <?php

    // Affiche p. ex. /boot/vmlinux-2.4.20-xfs
    echo readlink('/vmlinuz');

    ?>

### Voir aussi

- is_link() - Indique si le fichier est un lien symbolique
- symlink() - Crée un lien symbolique
- linkinfo() - Renvoie les informations d'un lien

# realpath

(PHP 4, PHP 5, PHP 7, PHP 8)

realpath — Retourne le chemin canonique absolu

### Description

function realpath(string `$path`): string|false

realpath() résout tous les liens symboliques, et remplace toutes les références `/./`, `/../` et `/` de `path` puis retourne le chemin canonique absolu ainsi trouvé.

### Liste de paramètres

`path`

  Le chemin à vérifier.

  > Note:

  > Un chemin d'accès doit être fourni, la valeur peut être une chaîne de caractères vide. Dans ces cas, la valeur est interprétée comme étant le dossier courant.

### Valeurs de retour

Retourne le chemin canonique absolu ainsi trouvé. Le résultat ne contient aucun lien symbolique, `/./` ou `/../`. Les délimiteurs de fin comme `\` et `/` sont également supprimés.

realpath() retourne `false` si une erreur survient, p. ex. si le fichier n'existe pas.

> Note:

> Le script qui s'exécute doit avoir les permissions en exécution sur tous les dossiers de la structure, sinon, la fonction realpath() retourne `false`.

> Note:

> Pour les systèmes de fichiers insensibles à la casse, realpath() peut ou non normaliser la casse des caractères.

> Note:

> La fonction realpath() ne fonctionnera pas pour un fichier qui se trouve à l'intérieur d'un Phar car ce chemin serait un chemin d'accès virtuel, pas un vrai.

> Note:

> Sur Windows, les jonctions et les liens symboliques aux dossiers sont uniquement étendus d'un niveau.

> Note: Comme le type entier de PHP est signé et que de nombreuses plates-formes utilisent des entiers de 32 bits, certaines fonctions relatives au système de fichiers peuvent retourner des résultats étranges pour les fichiers de taille supérieure à 2 Go.

### Exemples

Exemple #1 Exemple avec realpath()

    <?php
    chdir('/var/www/');
    echo realpath('./../../etc/passwd') . PHP_EOL;

    echo realpath('/tmp/') . PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    /etc/passwd
    /tmp

Exemple #2 Exemple avec realpath() sous Windows

Sous Windows, realpath() changera les chemins de style Unix en chemins de style Windows.

    <?php
    echo realpath('/windows/system32'), PHP_EOL;

    echo realpath('C:\Program Files\\'), PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    C:\WINDOWS\System32
    C:\Program Files

### Voir aussi

- basename() - Retourne le nom de la composante finale d'un chemin
- dirname() - Renvoie le chemin du dossier parent
- pathinfo() - Retourne des informations sur un chemin système

# realpath_cache_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_get — Récupère les entrées du cache realpath

### Description

function realpath_cache_get(): array

Récupère les entrées du cache realpath.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau d'entrées du cache realpath. Les clés sont les chemins originaux et les valeurs sont des tableaux de données contenant le chemin résolu, la date d'expiration et d'autres paramètres gardés en cache.

### Exemples

Exemple #1 Exemple avec realpath_cache_get()

    <?php
    var_dump(realpath_cache_get());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(2) {
      ["/test"]=>
      array(4) {
        ["key"]=>
        int(123456789)
        ["is_dir"]=>
        bool(true)
        ["realpath"]=>
        string(5) "/test"
        ["expires"]=>
        int(1260318939)
      }
      ["/test/test.php"]=>
      array(4) {
        ["key"]=>
        int(987654321)
        ["is_dir"]=>
        bool(false)
        ["realpath"]=>
        string(12) "/root/test.php"
        ["expires"]=>
        int(1260318939)
      }
    }

### Voir aussi

- realpath_cache_size() - Récupère la taille du cache realpath

# realpath_cache_size

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_size — Récupère la taille du cache realpath

### Description

function realpath_cache_size(): int

Récupère la quantité de mémoire utilisée par le cache realpath.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la quantité de mémoire utilisée par le cache realpath.

### Exemples

Exemple #1 Exemple avec realpath_cache_size()

    <?php
    var_dump(realpath_cache_size());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(412)

### Voir aussi

- realpath_cache_get() - Récupère les entrées du cache realpath
- L'option de configuration realpath_cache_size

# rename

(PHP 4, PHP 5, PHP 7, PHP 8)

rename — Renomme un fichier ou un dossier

### Description

function rename(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Tente de renommer `from` en `to`, en le déplaçant de répertoire si nécessaire. Si l'on renomme un fichier et que `to` existe, il sera écrasé. Si l'on renomme un répertoire et que `to` existe, cette fonction émet un avertissement.

### Liste de paramètres

`from`

  L'ancien nom.

  > Note:

  > L'enveloppe utilisée dans le paramètre `from` DOIT être la même que celle utilisée dans `to`.

`to`

  Le nouveau nom.

  > Note: Sur Windows, si `to` existe déjà, il doit pouvoir être écrit. Sinon rename() échoue et émet une `E_WARNING`.

`context`

  > Note: Une resource de contexte de flux.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec rename()

    <?php
    rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
    ?>

### Voir aussi

- copy() - Copie un fichier
- unlink() - Supprime un fichier
- move_uploaded_file() - Déplace un fichier téléchargé

# rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

rewind — Replace le pointeur de fichier au début

### Description

function rewind(resource `$stream`): bool

Replace le pointeur de fichier `stream` au début du flux.

> Note:

> Si le fichier a été ouvert en mode d'ajout ("a" ou "a+"), toutes les données que l'on écrira dans ce fichier seront toujours ajoutées, sans se soucier de la position du pointeur de fichier.

### Liste de paramètres

`stream`

  Le pointeur de fichier doit être valide, et avoir été correctement ouvert par fopen().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple d'écrasement avec rewind()

    <?php
    $handle = fopen('output.txt', 'r+');

    fwrite($handle, 'Really long sentence.');
    rewind($handle);
    fwrite($handle, 'Foo');
    rewind($handle);

    echo fread($handle, filesize('output.txt'));

    fclose($handle);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Foolly long sentence.

### Voir aussi

- fread() - Lecture du fichier en mode binaire
- fseek() - Modifie la position du pointeur de fichier
- ftell() - Renvoie la position courante du pointeur de fichier
- fwrite() - Écrit un fichier en mode binaire

# rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

rmdir — Efface un dossier

### Description

function rmdir(string `$directory`, ?resource `$context` = `null`): bool

Tente d'effacer le dossier dont le chemin est `directory`. Le dossier doit être vide, et le script doit avoir les autorisations adéquates. Une alerte de niveau `E_WARNING` est générée en cas d'échec.

### Liste de paramètres

`directory`

  Le chemin vers le dossier.

`context`

  > Note: Une resource de contexte de flux.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec rmdir()

    <?php
    if (!is_dir('examples')) {
        mkdir('examples');
    }

    rmdir('examples');
    ?>

### Voir aussi

- is_dir() - Indique si le fichier est un dossier
- mkdir() - Crée un dossier
- unlink() - Supprime un fichier

# set_file_buffer

(PHP 4, PHP 5, PHP 7, PHP 8)

set_file_buffer — Alias de stream_set_write_buffer()

### Description

Cette fonction est un alias de : stream_set_write_buffer().

# stat

(PHP 4, PHP 5, PHP 7, PHP 8)

stat — Renvoie les informations à propos d'un fichier

### Description

function stat(string `$filename`): array|false

Renvoie les informations à propos du fichier `filename`. Si `filename` est un lien symbolique, les informations proviennent du fichier lui-même, et non du lien symbolique. Avant PHP 7.4.0, sous Windows NTS compile les valeurs statiques `size`, `atime`, `mtime` et `ctime` depuis les liens symboliques, dans ce cas.

lstat() est identique à stat() sauf que les informations seront alors basées sur le lien symbolique.

### Liste de paramètres

`filename`

  Le chemin vers le fichier.

### Valeurs de retour

Format du résultat de stat() et fstat()
Numérique | Associatif | Description
--- | --- | ---
0 | dev | volume (***)
1 | ino | Numéro d'inode (****)
2 | mode | droit d'accès à l'inode *****
3 | nlink | nombre de liens
4 | uid | userid du propriétaire (*)
5 | gid | groupid du propriétaire (*)
6 | rdev | type du volume, si le volume est une inode
7 | size | taille en octets
8 | atime | date de dernier accès (Unix timestamp)
9 | mtime | date de dernière modification (Unix timestamp)
10 | ctime | date de dernier changement d'inode (Unix timestamp)
11 | blksize | taille de bloc (**)
12 | blocks | nombre de blocs de 512 octets alloués (**)

* - Sous Windows, ceci sera toujours `0`.

** - uniquement sur les systèmes qui supportent le type `st_blksize`. Les autres systèmes (p. ex. Windows) retournent `-1`.

*** - Sous Windows, à partir de PHP 7.4.0, ce sera le numéro de série du volume qui contient le fichier, qui sera un entier 64-bit non signé qui peut déborder. Auparavant, c'était la représentation numérique de la lettre du volume (c.-à-d. `2` pour `C:`) pour la fonction stat(), et `0` pour la fonction lstat().

**** - Sous Windows, à partir de PHP 7.4.0, c'est l'identifiant associé avec le fichier, qui sera un entier 64-bit non signé qui peut déborder. Auparavant, c'était toujours `0`.

***** Sous Windows, le bit de la permission d'écriture est défini en fonction de l'attribut lecture seule du fichier, et la même valeur est rapportée pour tous les utilisateurs, groupe, et propriétaire. L'ACL n'est pas prise en compte, contrairement à is_writable().

La valeur de `mode` contient des informations lues par plusieurs fonctions. Écrite en octal, en commençant par la droite, les trois premiers chiffres sont retournés par chmod(). Le chiffre suivant est ignoré par PHP. Les deux chiffres suivants indiquent le type de fichier :

Les types de fichiers `mode`
`mode` en octal | Signification
--- | ---
`0140000` | socket
`0120000` | lien symbolique
`0100000` | fichier régulier
`0060000` | périphérique bloc
`0040000` | dossier
`0020000` | périphérique de caractère
`0010000` | FIFO (un tube nommé)

Ainsi, par exemple, un fichier régulier pourrait être `0100644` et un dossier pourrait être `0040755`.

En cas d'erreur, stat() retourne `false`.

> Note: Comme le type entier de PHP est signé et que de nombreuses plates-formes utilisent des entiers de 32 bits, certaines fonctions relatives au système de fichiers peuvent retourner des résultats étranges pour les fichiers de taille supérieure à 2 Go.

### Erreurs / Exceptions

Si une erreur survient, une alerte de type `E_WARNING` est émise.

### Historique

Version | Description
--- | ---
7.4.0 | Sous Windows, le numéro du volume est maintenant le numéro de série qui contient le fichier, et le numéro de l'inode est l'identifiant associé avec le fichier.
7.4.0 | Les valeurs statiques `size`, `atime`, `mtime` et `ctime` des liens symboliques sont toujours celles de la cible. Ce n'était précédemment pas le cas pour les builds NTS sous Windows.

### Exemples

Exemple #1 Exemple avec stat()

    <?php
    /* Récupération des informations */
    $stat = stat('C:\php\php.exe');

    /*
     * Affichage de la date et heure de l'accès à ce fichier,
     * identique à l'appel à la fonction fileatime()
     */
    echo 'Date et heure d\'accès : ' . $stat['atime'];

    /*
     * Affiche de la date et heure de modification du fichier,
     * identique à l'appel à la fonction filemtime()
     */
    echo 'Date et heure de modification : ' . $stat['mtime'];

    /* Affichage du numéro du device */
    echo 'Numéro du Device : ' . $stat['dev'];
    ?>

Exemple #2 Utilisation des informations issues de stat() conjointement avec la fonction touch()

    <?php
    /* Récupération des informations issues de la fonction stat */
    $stat = stat('C:\php\php.exe');

    /* L'accès aux informations a-t-il échoué ? */
    if (!$stat) {
        echo 'L\'appel à stat() a échoué...';
    } else {
        /*
         * Nous voulons que la date et heure d'accès soit d'une
         * semaine après la date courante.
         */
        $atime = $stat['atime'] + 604800;

        /* Touchons le fichier ! */
        if(!touch('some_file.txt', time(), $atime)) {
            echo 'Échec lors de l\'appel à la fonction touch()...';
        } else {
            echo 'L\'appel à touch() a réussi...';
        }
    }
    ?>

### Notes

> Note: Notez que la précision temporelle peut varier selon le système de fichiers utilisé.

> Note: Les résultats de cette fonction sont mis en cache. Voyez la fonction clearstatcache() pour plus de détails.

Astuce

À partir de PHP 5.0.0, cette fonction peut aussi être utilisée avec quelques protocoles url. Lisez Liste des protocoles et des gestionnaires supportés pour connaître les protocoles supportant la famille de fonctionnalités de stat().

### Voir aussi

- lstat() - Retourne les informations sur un fichier ou un lien symbolique
- fstat() - Lit les informations sur un fichier à partir d'un pointeur de fichier
- filemtime() - Lit la date de dernière modification du fichier
- filegroup() - Lit le groupe d'un fichier
- SplFileInfo

# symlink

(PHP 4, PHP 5, PHP 7, PHP 8)

symlink — Crée un lien symbolique

### Description

function symlink(string `$target`, string `$link`): bool

symlink() crée un lien symbolique pour l'objet `target` avec le nom de `link`.

### Liste de paramètres

`target`

  La cible du lien.

`link`

  Le nom du lien.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

La fonction échoue, et émet une `E_WARNING`, si `link` existe déjà. Sur Windows, cette fonction échoue également, et émet une `E_WARNING`, si `target` n'existe pas.

### Exemples

Exemple #1 Création d'un lien symbolique

    <?php
    $target = 'uploads.php';
    $link = 'uploads';
    symlink($target, $link);

    echo readlink($link);
    ?>

### Voir aussi

- is_link() - Indique si le fichier est un lien symbolique
- link() - Crée un lien physique
- readlink() - Renvoie le contenu d'un lien symbolique
- linkinfo() - Renvoie les informations d'un lien
- unlink() - Supprime un fichier

# tempnam

(PHP 4, PHP 5, PHP 7, PHP 8)

tempnam — Crée un fichier avec un nom unique

### Description

function tempnam(string `$directory`, string `$prefix`): string|false

Crée un fichier dont le nom est unique, ayant comme permissions d'accès 0600, dans le dossier spécifié. Si le dossier n'existe pas ou qu'il n'est pas accessible en écriture, tempnam() tentera de créer un fichier dans le dossier temporaire système, et retournera le chemin complet de ce fichier, y compris son nom.

### Liste de paramètres

`directory`

  Le dossier dans lequel le fichier temporaire sera créé.

`prefix`

  Le préfixe du fichier temporaire généré.

  > Note: Seuls les 63 premiers caractères du préfixe sont utilisés, le reste est ignoré. Windows utilise uniquement les 3 premiers caractères du préfixe.

### Valeurs de retour

Retourne un nouveau fichier temporaire (avec son chemin), ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Le nom des fichiers créés par tempnam() est désormais plus long de 13 octets. La longueur totale dépend toujours de la plateforme.
7.1.0 | tempnam() émet désormais une notice lors du rabat sur le dossier temporaire système.

### Exemples

Exemple #1 Exemple avec tempnam()

    <?php
    $tmpfname = tempnam("/tmp", "FOO");

    $handle = fopen($tmpfname, "w");
    fwrite($handle, "Écriture dans le fichier temporaire");
    fclose($handle);

    // traitement

    unlink($tmpfname);
    ?>

### Notes

> Note: Si PHP ne peut pas créer un fichier dans le dossier spécifié par le paramètre `directory`, il tentera dans le dossier par défaut du système. Sous les systèmes de fichiers NTFS, ceci arrive également si le dossier `directory` contient plus de 65534 fichiers.

### Voir aussi

- tmpfile() - Crée un fichier temporaire
- sys_get_temp_dir() - Retourne le chemin du répertoire utilisé pour les fichiers temporaires
- unlink() - Supprime un fichier

# tmpfile

(PHP 4, PHP 5, PHP 7, PHP 8)

tmpfile — Crée un fichier temporaire

### Description

function tmpfile(): resource|false

Crée un fichier temporaire avec un nom unique, ouvert en écriture, lecture et binaire (`w+b`), et retourne un pointeur de fichier.

Ce fichier sera automatiquement effacé lorsqu'il sera fermé (par exemple, en appelant la fonction fclose(), ou lorsqu'il n'y a plus de référence au gestionnaire de fichier retourné par la fonction tmpfile()), ou lorsque le script sera terminé.

Attention

Si le script se termine de manière inattendue, il se peut que le fichier temporaire ne soit pas supprimé.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un pointeur de fichier, identique à celui retourné par la fonction fopen(), pour le nouveau fichier ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec tmpfile()

    <?php
    $temp = tmpfile();
    fwrite($temp, "Écriture dans le fichier temporaire");
    fseek($temp, 0);
    echo fread($temp, 1024);
    fclose($temp); // ceci va effacer le fichier
    ?>

L'exemple ci-dessus va afficher :

    Écriture dans le fichier temporaire

### Voir aussi

- tempnam() - Crée un fichier avec un nom unique
- sys_get_temp_dir() - Retourne le chemin du répertoire utilisé pour les fichiers temporaires

# touch

(PHP 4, PHP 5, PHP 7, PHP 8)

touch — Modifie la date de modification et de dernier accès d'un fichier

### Description

function touch(string `$filename`, ?int `$mtime` = `null`, ?int `$atime` = `null`): bool

Tente de forcer la date de modification du fichier désigné par le paramètre `filename` à la date spécifiée par le paramètre `mtime`. Il est à noter que la date de dernier accès est modifiée, quel que soit le nombre de paramètres.

Si le fichier n'existe pas, PHP tentera de le créer.

### Liste de paramètres

`filename`

  Le nom du fichier à créer.

`mtime`

  La date de modification. Si `mtime` est omis, c'est l'heure courante time() qui est utilisée.

`atime`

  Si non `null`, l'heure d'accès au fichier fourni sera défini à la valeur du paramètre `atime`. Sinon, elle sera définie à la valeur passée au paramètre `mtime`. Si tous les deux sont `null`, l'heure courante du système sera utilisée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `mtime` et `atime` sont désormais nullable.

### Exemples

Exemple #1 Exemple avec touch()

    <?php
    if (touch($FileName)) {
        echo "La date de modification de $FileName a été modifiée à la date courante";
    } else {
        echo "Désolé, il est impossible de changer la date de modification de $FileName";
    }
    ?>

Exemple #2 Exemple avec touch() en utilisant le paramètre `mtime`

    <?php
    /*
     * Ceci est la date et l'heure du dernier accès, nous y ajoutons 1 heure
     * dans le passé.
     */
    $time = time() - 3600;

    /* Touchons le fichier ! */
    if (!touch('some_file.txt', $time)) {
        echo 'Whoops, une erreur est survenue...';
    } else {
        echo 'L\'appel à la fonction touch() a réussi';
    }
    ?>

### Notes

> Note: Notez que la précision temporelle peut varier selon le système de fichiers utilisé.

# umask

(PHP 4, PHP 5, PHP 7, PHP 8)

umask — Change le "umask" courant

### Description

function umask(?int `$mask` = `null`): int

umask() change le umask de PHP et le remplace par `mask` : `mask & 0777` puis, retourne le vieux umask. Lorsque PHP est utilisé comme module de serveur, le umask reprend sa valeur à la fin de chaque script.

### Liste de paramètres

`mask`

  Le nouvel umask.

### Valeurs de retour

Si `mask` est `null`, umask() retourne simplement l'umask actuel sinon l'ancien umask est retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `mask` est désormais nullable.

### Exemples

Exemple #1 Exemple avec umask()

    <?php
    $old = umask(0);
    chmod("/path/some_dir/some_file.txt", 0755);
    umask($old);

    // Vérification
    if ($old != umask()) {
        die('Une erreur est survenue lors de la modification des droits');
    }
    ?>

### Notes

> Note:

> Évitez d'utiliser cette fonction sur un serveur Web multithreadé. Il vaut mieux changer les droits d'un dossier avec la fonction chmod(), après la création du dossier. En utilisant umask(), il y a un risque de rencontrer des comportements indéfinis au niveau des autres scripts et du serveur, car ils utilisent tous le même umask.

# unlink

(PHP 4, PHP 5, PHP 7, PHP 8)

unlink — Supprime un fichier

### Description

function unlink(string `$filename`, ?resource `$context` = `null`): bool

Supprime `filename`. Similaire à la fonction Unix C `unlink()`. En cas d'échec, une alerte de niveau `E_WARNING` est générée.

### Liste de paramètres

`filename`

  Chemin vers le fichier.

  Si le fichier est un lien symbolique, le lien symbolique sera supprimé. Sur Windows, pour supprimer un lien symbolique vers un dossier, rmdir() doit être utilisé à la place.

`context`

  > Note: Une resource de contexte de flux.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.3.0 | Sur Windows, il est désormais possible de unlink() les fichiers dont les gestionnaires sont utilisés, ce qui auparavant échouait. Cependant, il n'est toujours pas possible de recréer le fichier supprimé, jusqu'à ce que tous ses gestionnaires soient fermés.

### Exemples

Exemple #1 Exemple avec unlink()

    <?php
    $fh = fopen('test.html', 'a');
    fwrite($fh, '<h1>Hello world!</h1>');
    fclose($fh);

    unlink('test.html');
    ?>

### Voir aussi

- rmdir() - Efface un dossier

## Sommaire

- basename — Retourne le nom de la composante finale d'un chemin
- chgrp — Change le groupe d'un fichier
- chmod — Change le mode du fichier
- chown — Change le propriétaire du fichier
- clearstatcache — Efface le cache de stat
- copy — Copie un fichier
- delete — Voir unlink ou unset
- dirname — Renvoie le chemin du dossier parent
- disk_free_space — Renvoie l'espace disque disponible sur le système de fichiers ou la partition
- disk_total_space — Retourne la taille d'un dossier ou d'une partition
- diskfreespace — Alias de disk_free_space
- fclose — Ferme un fichier
- fdatasync — Synchronise les données (mais pas les métadonnées) avec le fichier
- feof — Teste la fin du fichier
- fflush — Envoie tout le contenu généré dans un fichier
- fgetc — Lit un caractère dans un fichier
- fgetcsv — Obtient une ligne depuis un pointeur de fichier et l'analyse pour des champs CSV
- fgets — Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier
- fgetss — Renvoie la ligne courante du fichier et élimine les balises HTML
- file — Lit le fichier et renvoie le résultat dans un tableau
- file_exists — Vérifie si un fichier ou un dossier existe
- file_get_contents — Lit tout un fichier dans une chaîne
- file_put_contents — Écrit des données dans un fichier
- fileatime — Renvoie la date à laquelle le fichier a été accédé pour la dernière fois
- filectime — Renvoie la date de dernière modification de l'inode d'un fichier
- filegroup — Lit le groupe d'un fichier
- fileinode — Lit le numéro d'inode du fichier
- filemtime — Lit la date de dernière modification du fichier
- fileowner — Lit l'identifiant du propriétaire d'un fichier
- fileperms — Lit les droits d'un fichier
- filesize — Lit la taille d'un fichier
- filetype — Retourne le type de fichier
- flock — Verrouille le fichier
- fnmatch — Teste un nom de fichier au moyen d'un masque de recherche
- fopen — Ouvre un fichier ou une URL
- fpassthru — Affiche le reste du fichier
- fputcsv — Formate une ligne en CSV et l'écrit dans un fichier
- fputs — Alias de fwrite
- fread — Lecture du fichier en mode binaire
- fscanf — Analyse un fichier en fonction d'un format
- fseek — Modifie la position du pointeur de fichier
- fstat — Lit les informations sur un fichier à partir d'un pointeur de fichier
- fsync — Synchronise les modifications apportées au fichier (y compris les métadonnées)
- ftell — Renvoie la position courante du pointeur de fichier
- ftruncate — Tronque un fichier
- fwrite — Écrit un fichier en mode binaire
- glob — Recherche des chemins qui vérifient un masque
- is_dir — Indique si le fichier est un dossier
- is_executable — Indique si le fichier est exécutable
- is_file — Indique si le fichier est un véritable fichier
- is_link — Indique si le fichier est un lien symbolique
- is_readable — Indique si un fichier existe et est accessible en lecture
- is_uploaded_file — Indique si le fichier a été téléchargé par HTTP POST
- is_writable — Indique si un fichier est accessible en écriture
- is_writeable — Alias de is_writable
- lchgrp — Change l'appartenance du groupe d'un lien symbolique
- lchown — Change le propriétaire d'un lien symbolique
- link — Crée un lien physique
- linkinfo — Renvoie les informations d'un lien
- lstat — Retourne les informations sur un fichier ou un lien symbolique
- mkdir — Crée un dossier
- move_uploaded_file — Déplace un fichier téléchargé
- parse_ini_file — Analyse un fichier de configuration
- parse_ini_string — Analyse une chaîne de configuration
- pathinfo — Retourne des informations sur un chemin système
- pclose — Ferme un pointeur de fichier de processus
- popen — Ouvre un pointeur de fichier de processus
- readfile — Affiche un fichier
- readlink — Renvoie le contenu d'un lien symbolique
- realpath — Retourne le chemin canonique absolu
- realpath_cache_get — Récupère les entrées du cache realpath
- realpath_cache_size — Récupère la taille du cache realpath
- rename — Renomme un fichier ou un dossier
- rewind — Replace le pointeur de fichier au début
- rmdir — Efface un dossier
- set_file_buffer — Alias de stream_set_write_buffer
- stat — Renvoie les informations à propos d'un fichier
- symlink — Crée un lien symbolique
- tempnam — Crée un fichier avec un nom unique
- tmpfile — Crée un fichier temporaire
- touch — Modifie la date de modification et de dernier accès d'un fichier
- umask — Change le "umask" courant
- unlink — Supprime un fichier

- Installation/Configuration
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Fonctions sur les systèmes de fichiers
  - basename — Retourne le nom de la composante finale d'un chemin
  - chgrp — Change le groupe d'un fichier
  - chmod — Change le mode du fichier
  - chown — Change le propriétaire du fichier
  - clearstatcache — Efface le cache de stat
  - copy — Copie un fichier
  - delete — Voir unlink ou unset
  - dirname — Renvoie le chemin du dossier parent
  - disk_free_space — Renvoie l'espace disque disponible sur le système de fichiers ou la partition
  - disk_total_space — Retourne la taille d'un dossier ou d'une partition
  - diskfreespace — Alias de disk_free_space
  - fclose — Ferme un fichier
  - fdatasync — Synchronise les données (mais pas les métadonnées) avec le fichier
  - feof — Teste la fin du fichier
  - fflush — Envoie tout le contenu généré dans un fichier
  - fgetc — Lit un caractère dans un fichier
  - fgetcsv — Obtient une ligne depuis un pointeur de fichier et l'analyse pour des champs CSV
  - fgets — Récupère la ligne courante à partir de l'emplacement du pointeur sur fichier
  - fgetss — Renvoie la ligne courante du fichier et élimine les balises HTML
  - file — Lit le fichier et renvoie le résultat dans un tableau
  - file_exists — Vérifie si un fichier ou un dossier existe
  - file_get_contents — Lit tout un fichier dans une chaîne
  - file_put_contents — Écrit des données dans un fichier
  - fileatime — Renvoie la date à laquelle le fichier a été accédé pour la dernière fois
  - filectime — Renvoie la date de dernière modification de l'inode d'un fichier
  - filegroup — Lit le groupe d'un fichier
  - fileinode — Lit le numéro d'inode du fichier
  - filemtime — Lit la date de dernière modification du fichier
  - fileowner — Lit l'identifiant du propriétaire d'un fichier
  - fileperms — Lit les droits d'un fichier
  - filesize — Lit la taille d'un fichier
  - filetype — Retourne le type de fichier
  - flock — Verrouille le fichier
  - fnmatch — Teste un nom de fichier au moyen d'un masque de recherche
  - fopen — Ouvre un fichier ou une URL
  - fpassthru — Affiche le reste du fichier
  - fputcsv — Formate une ligne en CSV et l'écrit dans un fichier
  - fputs — Alias de fwrite
  - fread — Lecture du fichier en mode binaire
  - fscanf — Analyse un fichier en fonction d'un format
  - fseek — Modifie la position du pointeur de fichier
  - fstat — Lit les informations sur un fichier à partir d'un pointeur de fichier
  - fsync — Synchronise les modifications apportées au fichier (y compris les métadonnées)
  - ftell — Renvoie la position courante du pointeur de fichier
  - ftruncate — Tronque un fichier
  - fwrite — Écrit un fichier en mode binaire
  - glob — Recherche des chemins qui vérifient un masque
  - is_dir — Indique si le fichier est un dossier
  - is_executable — Indique si le fichier est exécutable
  - is_file — Indique si le fichier est un véritable fichier
  - is_link — Indique si le fichier est un lien symbolique
  - is_readable — Indique si un fichier existe et est accessible en lecture
  - is_uploaded_file — Indique si le fichier a été téléchargé par HTTP POST
  - is_writable — Indique si un fichier est accessible en écriture
  - is_writeable — Alias de is_writable
  - lchgrp — Change l'appartenance du groupe d'un lien symbolique
  - lchown — Change le propriétaire d'un lien symbolique
  - link — Crée un lien physique
  - linkinfo — Renvoie les informations d'un lien
  - lstat — Retourne les informations sur un fichier ou un lien symbolique
  - mkdir — Crée un dossier
  - move_uploaded_file — Déplace un fichier téléchargé
  - parse_ini_file — Analyse un fichier de configuration
  - parse_ini_string — Analyse une chaîne de configuration
  - pathinfo — Retourne des informations sur un chemin système
  - pclose — Ferme un pointeur de fichier de processus
  - popen — Ouvre un pointeur de fichier de processus
  - readfile — Affiche un fichier
  - readlink — Renvoie le contenu d'un lien symbolique
  - realpath — Retourne le chemin canonique absolu
  - realpath_cache_get — Récupère les entrées du cache realpath
  - realpath_cache_size — Récupère la taille du cache realpath
  - rename — Renomme un fichier ou un dossier
  - rewind — Replace le pointeur de fichier au début
  - rmdir — Efface un dossier
  - set_file_buffer — Alias de stream_set_write_buffer
  - stat — Renvoie les informations à propos d'un fichier
  - symlink — Crée un lien symbolique
  - tempnam — Crée un fichier avec un nom unique
  - tmpfile — Crée un fichier temporaire
  - touch — Modifie la date de modification et de dernier accès d'un fichier
  - umask — Change le "umask" courant
  - unlink — Supprime un fichier

# Inotify

# Introduction

L'extension inotify fait l'interface avec les fonctions inotify_init(), inotify_add_watch() et inotify_rm_watch().

Comme la fonction C inotify_init() retourne un pointeur de fichier, la fonction PHP inotify_init() retourne un flux, à utiliser avec les fonctions standard de flux, telle que stream_select(), stream_set_blocking() et fclose(). inotify_read() remplace l'approche en langage C de lecture des événements.

# Installation/Configuration

## Sommaire

- Installation/Configuration
- Types de ressources

## Installation/Configuration

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/inotify.

## Types de ressources

Cette extension définit un flux de données, retourné par inotify_init().

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Les constantes Inotify sont utilisables avec les fonctions inotify_add_watch() et/ou retournées par la fonction inotify_read()
`IN_ACCESS` (int)
  Le fichier a été accédé (lu) (*)
`IN_MODIFY` (int)
  Le fichier a été modifié (*)
`IN_ATTRIB` (int)
  Les métadonnées ont changé (p. ex. les permissions, la date de modification, etc.) (*)
`IN_CLOSE_WRITE` (int)
  Le fichier ouvert en écriture a été refermé (*)
`IN_CLOSE_NOWRITE` (int)
  Le fichier non-ouvert en écriture a été refermé (*)
`IN_OPEN` (int)
  Le fichier a été ouvert (*)
`IN_MOVED_TO` (int)
  Fichier déplacé dans un dossier surveillé (*)
`IN_MOVED_FROM` (int)
  Fichier déplacé depuis un dossier surveillé (*)
`IN_CREATE` (int)
  Fichier ou dossier créé dans un dossier surveillé (*)
`IN_DELETE` (int)
  Fichier ou dossier supprimé dans un dossier surveillé (*)
`IN_DELETE_SELF` (int)
  Les fichiers ou dossiers surveillés ont été supprimés
`IN_MOVE_SELF` (int)
  Les fichiers ou dossiers surveillés ont été déplacés
`IN_CLOSE` (int)
  Égal à IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
`IN_MOVE` (int)
  Égal à IN_MOVED_FROM | IN_MOVED_TO
`IN_ALL_EVENTS` (int)
  Composition de toutes les constantes précédentes
`IN_UNMOUNT` (int)
  Le système de fichiers contenant les objets surveillés a été démonté
`IN_Q_OVERFLOW` (int)
  Queue d'événements en dépassement de capacité (wd vaut -1 pour cet événement)
`IN_IGNORED` (int)
  La surveillance a été retirée (explicitement par inotify_rm_watch() ou parce que le fichier a été supprimé, ou que le système de fichiers a été démonté)
`IN_ISDIR` (int)
  Le sujet de cet événement est un dossier
`IN_ONLYDIR` (int)
  Ne surveille que le chemin, si c'est un dossier (Depuis Linux 2.6.15)
`IN_DONT_FOLLOW` (int)
  Ne déréférence pas le chemin si c'est un lien symbolique (Depuis Linux 2.6.15)
`IN_MASK_ADD` (int)
  Ajoute les événements au masque de surveillance pour ce chemin, s'il existe déjà (au lieu de remplacer).
`IN_ONESHOT` (int)
  Surveille le chemin de cet événement, puis le supprime de la liste de surveillance.

> Note: Les événements marqués par un astérisque (*) ci-dessus peuvent survenir pour des fichiers dans des dossiers sous surveillance.

# Fonctions Inotify

# inotify_add_watch

(PECL inotify >= 0.1.2)

inotify_add_watch — Ajoute un point de surveillance à une instance inotify

### Description

function inotify_add_watch(resource `$inotify_instance`, string `$pathname`, int `$mask`): int|false

inotify_add_watch() ajoute un point de surveillance à une instance inotify ou modifie un point de surveillance en cours vers un nouveau fichier ou dossier spécifié par le chemin `pathname`.

Utiliser inotify_add_watch() sur un objet déjà en surveillance modifie la configuration. Utiliser la constante `IN_MASK_ADD` ajoute les événements (OR logique).

### Liste de paramètres

`inotify_instance`
  Ressource returnée par inotify_init()
`pathname`
  Fichier ou dossier à surveiller.
`mask`
  Événements à surveiller. Voir Constantes pré-définies.

### Valeurs de retour

La valeur retournée est un pointeur inotify unique (inotify instance wide), ou `false` si une erreur survient.

### Voir aussi

- inotify_init() - Initialise une instance inotify

# inotify_init

(PECL inotify >= 0.1.2)

inotify_init — Initialise une instance inotify

### Description

function inotify_init(): resource|false

Initialise une instance inotify pour utiliser avec la fonction inotify_add_watch()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un flux ou `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple d'utilisation d'inotify

    <?php
    // Crée une instance inotify
    $fd = inotify_init();

    // Surveille les modifications des métadonnées du fichier __FILE__ (p. ex. mtime)
    $watch_descriptor = inotify_add_watch($fd, __FILE__, IN_ATTRIB);

    // Génère un événement
    touch(__FILE__);

    // Lit les événements
    $events = inotify_read($fd);
    print_r($events);

    // Les méthodes suivantes permettent d'utiliser les fonctions inotify sans bloquer sur inotify_read():

    // - Utiliser stream_select() sur $fd:
    $read = array($fd);
    $write = null;
    $except = null;
    stream_select($read,$write,$except,0);

    // - Utiliser stream_set_blocking() sur $fd
    stream_set_blocking($fd, 0);
    inotify_read($fd); // Does no block, and return false if no events are pending

    // - Utiliser inotify_queue_len() pour vérifier la taille de la file d'attente
    $queue_len = inotify_queue_len($fd); // If > 0, inotify_read() will not block

    // Arrêt de la surveillance de __FILE__
    inotify_rm_watch($fd, $watch_descriptor);

    // Destruction de l'instance inotify
    // Cela aurait arrêté toutes les surveillances si ce n'était pas déjà fait
    fclose($fd);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(
      array(
        'wd' => 1,     // Égale le $watch_descriptor
        'mask' => 4,   // Le bit IN_ATTRIB est activé
        'cookie' => 0, // identifiant unique pour relier des événements (e.g.
                       // IN_MOVE_FROM et IN_MOVE_TO)
        'name' => '',  // Le nom du fichier (e.g. si un dossier était sous surveillance)
      ),
    );

### Voir aussi

- inotify_add_watch() - Ajoute un point de surveillance à une instance inotify
- inotify_rm_watch() - Supprime un point de surveillance d'une instance inotify
- inotify_queue_len() - Retourne le nombre d'événements qui sont survenus
- inotify_read() - Lit les événements dans une instance inotify
- fclose() - Ferme un fichier

# inotify_queue_len

(PECL inotify >= 0.1.2)

inotify_queue_len — Retourne le nombre d'événements qui sont survenus

### Description

function inotify_queue_len(resource `$inotify_instance`): int

Cette fonction permet de savoir si inotify_read() va bloquer ou non. Si un nombre supérieur à 0 est retourné, il y a des événements en attente, et inotify_read() ne va pas bloquer.

### Liste de paramètres

`inotify_instance`
  Ressource returnée par inotify_init()

### Valeurs de retour

Retourne le nombre d'événements qui sont survenus.

### Voir aussi

- inotify_init() - Initialise une instance inotify
- stream_select() - Surveille la modification d'un ou plusieurs flux
- stream_set_blocking() - Configure le mode bloquant d'un flux

# inotify_read

(PECL inotify >= 0.1.2)

inotify_read — Lit les événements dans une instance inotify

### Description

function inotify_read(resource `$inotify_instance`): array

Lit les événements dans une instance inotify.

### Liste de paramètres

`inotify_instance`
  Ressource returnée par inotify_init()

### Valeurs de retour

Un tableau d'événements inotify ou `false` si aucun événement n'était dans la liste, et que `inotify_instance` était non-bloquant. Chaque événement dans le tableau dispose des index suivants :

- wd, le pointeur retourné par la fonction inotify_add_watch()
- mask est un champ de bits de constantes inotify
- cookie est un identifiant unique pour relier des événements communs (p. ex. `IN_MOVE_FROM` et `IN_MOVE_TO`)
- name est le nom du fichier (p. ex. si un fichier a été modifié dans le dossier de surveillance)

### Voir aussi

- inotify_init() - Initialise une instance inotify
- stream_select() - Surveille la modification d'un ou plusieurs flux
- stream_set_blocking() - Configure le mode bloquant d'un flux
- inotify_queue_len() - Retourne le nombre d'événements qui sont survenus

# inotify_rm_watch

(PECL inotify >= 0.1.2)

inotify_rm_watch — Supprime un point de surveillance d'une instance inotify

### Description

function inotify_rm_watch(resource `$inotify_instance`, int `$watch_descriptor`): bool

inotify_rm_watch() retire le point de surveillance `watch_descriptor` de l'instance inotify `inotify_instance`.

### Liste de paramètres

`inotify_instance`
  Ressource returnée par inotify_init()
`watch_descriptor`
  Point de surveillance à retirer

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- inotify_init() - Initialise une instance inotify

## Sommaire

- inotify_add_watch — Ajoute un point de surveillance à une instance inotify
- inotify_init — Initialise une instance inotify
- inotify_queue_len — Retourne le nombre d'événements qui sont survenus
- inotify_read — Lit les événements dans une instance inotify
- inotify_rm_watch — Supprime un point de surveillance d'une instance inotify

- Installation/Configuration
  - Installation/Configuration
  - Types de ressources
- Constantes pré-définies
- Fonctions Inotify
  - inotify_add_watch — Ajoute un point de surveillance à une instance inotify
  - inotify_init — Initialise une instance inotify
  - inotify_queue_len — Retourne le nombre d'événements qui sont survenus
  - inotify_read — Lit les événements dans une instance inotify
  - inotify_rm_watch — Supprime un point de surveillance d'une instance inotify

# xattr

# Introduction

L'extension xattr permet la manipulation des attributs étendus d'un système de fichiers.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Pour utiliser xattr, il faut installer la bibliothèque libattr. Elle est disponible sur » http://savannah.nongnu.org/projects/attr/.

> Note:

> Ces fonctions ne fonctionnent que sur les systèmes de fichiers qui supportent les attributs étendus, et qu'ils les ont activés lors du montage du périphérique. Parmi les exemples de systèmes de fichiers qui supportent les attributs étendus, on peut noter `ext2`, `ext3`, `reiserfs`, `jfs`, et `xfs`.

## Installation

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/xattr.

Aucune bibliothèque DLL pour cette extension PECL n'est actuellement disponible. Reportez-vous à la section Compilation sous Windows.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`XATTR_ROOT` (int)
  Définit un attribut dans l'espace de noms racine. Nécessite les privilèges d'administrateur.
`XATTR_DONTFOLLOW` (int)
  Ne pas suivre un lien symbolique mais opérer directement sur le lien symbolique.
`XATTR_CREATE` (int)
  La fonction échouera si l'attribut étendu existe déjà.
`XATTR_REPLACE` (int)
  La fonction échouera si l'attribut étendu n'existe pas.

# Fonctions xattr

# xattr_get

(PECL xattr >= 0.9.0)

xattr_get — Récupère un attribut étendu

### Description

function xattr_get(string `$filename`, string `$name`, int `$flags` = 0): string|false

xattr_get() récupère la valeur de l'attribut étendu nommé `name` du fichier `filename`.

Les attributs étendus ont deux espaces de noms différents : `user` et `root`. L'espace de noms `user` est disponible pour tous les utilisateurs tandis que l'espace de noms `root` n'est disponible que pour les utilisateurs ayant les privilèges `root`. xattr opère sur l'espace de noms `user` par défaut, mais vous pouvez changer cela en utilisant l'argument `flags`.

### Liste de paramètres

`filename`

  Le fichier depuis lequel on récupère l'attribut.

`name`

  Le nom de l'attribut.

`flags`

  Flags xattr supportés
  `XATTR_DONTFOLLOW` | Ne pas suivre les liens symboliques mais opère directement sur le lien lui-même.
  `XATTR_ROOT` | Définit l'attribut dans l'espace de noms racine. Nécessite les privilèges d'administrateur.

### Valeurs de retour

Retourne une chaîne contenant la valeur ou `false` si l'attribut n'existe pas.

### Exemples

Exemple #1 Vérifie si l'administrateur système a signé le fichier

    <?php
    $file = '/usr/local/sbin/some_binary';
    $signature = xattr_get($file, 'Root signature', XATTR_ROOT);

    /* ... vérifie si $signature est valide ... */

    ?>

### Voir aussi

- xattr_list() - Récupère une liste d'attributs étendus
- xattr_set() - Définit un attribut étendu
- xattr_remove() - Efface un attribut étendu

# xattr_list

(PECL xattr >= 0.9.0)

xattr_list — Récupère une liste d'attributs étendus

### Description

function xattr_list(string `$filename`, int `$flags` = 0): array

xattr_list() récupère une liste de noms d'attributs étendus d'un fichier désigné par le paramètre `filename`.

Les attributs étendus ont deux espaces de noms différents : `user` et `root`. L'espace de noms `user` est disponible pour tous les utilisateurs tandis que l'espace de noms `root` n'est disponible que pour les utilisateurs ayant les privilèges `root`. xattr opère sur l'espace de noms `user` par défaut, mais vous pouvez changer cela en utilisant l'argument `flags`.

### Liste de paramètres

`filename`

  Le chemin vers le fichier.

`flags`

  Flags xattr supportés
  `XATTR_DONTFOLLOW` | Ne pas suivre les liens symboliques mais opère directement sur le lien lui-même.
  `XATTR_ROOT` | Définit l'attribut dans l'espace de noms racine. Nécessite les privilèges d'administrateur.

### Valeurs de retour

Cette fonction retourne un tableau contenant les noms des attributs étendus.

### Exemples

Exemple #1 Affiche les noms de tous les attributs étendus d'un fichier

    <?php
    $file = 'un_fichier';
    $root_attributes = xattr_list($file, XATTR_ROOT);
    $user_attributes = xattr_list($file);

    echo "Attributs racine :\n";
    foreach ($root_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    echo "\n Attributs utilisateur : \n";
    foreach ($user_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    ?>

### Voir aussi

- xattr_get() - Récupère un attribut étendu

# xattr_remove

(PECL xattr >= 0.9.0)

xattr_remove — Efface un attribut étendu

### Description

function xattr_remove(string `$filename`, string `$name`, int `$flags` = 0): bool

xattr_remove() efface un attribut étendu nommé `name` d'un fichier désigné par le paramètre `filename`.

Les attributs étendus ont deux espaces de noms différents : `user` et `root`. L'espace de noms `user` est disponible pour tous les utilisateurs tandis que l'espace de noms `root` n'est disponible que pour les utilisateurs ayant les privilèges `root`. xattr opère sur l'espace de noms `user` par défaut, mais vous pouvez changer cela en utilisant l'argument `flags`.

### Liste de paramètres

`filename`

  Le fichier depuis lequel nous effaçons l'attribut.

`name`

  Le nom de l'attribut à effacer.

`flags`

  Options xattr disponibles
  `XATTR_DONTFOLLOW` | Ne pas suivre les liens symboliques mais opère directement sur le lien lui-même.
  `XATTR_ROOT` | Définit l'attribut dans l'espace de noms racine. Nécessite les privilèges d'administrateur.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Efface tous les attributs étendus d'un fichier

    <?php
    $file = 'un_fichier';
    $attributes = xattr_list($file);

    foreach ($attributes as $attr_name) {
        xattr_remove($file, $attr_name);
    }
    ?>

### Voir aussi

- xattr_list() - Récupère une liste d'attributs étendus
- xattr_set() - Définit un attribut étendu
- xattr_get() - Récupère un attribut étendu

# xattr_set

(PECL xattr >= 0.9.0)

xattr_set — Définit un attribut étendu

### Description

function xattr_set(
string `$filename`,
string `$name`,
string `$value`,
int `$flags` = 0
): bool

xattr_set() définit la valeur d'un attribut étendu nommé `name` à la valeur `value` d'un fichier désigné par le paramètre `filename`.

Les attributs étendus ont deux espaces de noms différents : `user` et `root`. L'espace de noms `user` est disponible pour tous les utilisateurs tandis que l'espace de noms `root` n'est disponible que pour les utilisateurs ayant les privilèges `root`. xattr opère sur l'espace de noms `user` par défaut, mais vous pouvez changer cela en utilisant l'argument `flags`.

### Liste de paramètres

`filename`

  Le fichier dans lequel nous devons définir l'attribut.

`name`

  Le nom de l'attribut étendu. Cet attribut sera créé s'il n'existe pas encore ou remplacé sinon. Il est possible de modifier ce comportement en utilisant le paramètre `flags`.

`value`

  La valeur de l'attribut.

`flags`

  Flags xattr supportés
  `XATTR_CREATE` | La fonction échouera si l'attribut étendu existe déjà.
  `XATTR_REPLACE` | La fonction échouera si l'attribut étendu n'existe pas.
  `XATTR_DONTFOLLOW` | Ne pas suivre les liens symboliques mais opère directement sur le lien lui-même.
  `XATTR_ROOT` | Définit l'attribut dans l'espace de noms racine. Nécessite les privilèges d'administrateur.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Définition des attributs étendus dans un fichier .wav

    <?php
    $file = 'ma_chanson_favorite.wav';
    xattr_set($file, 'Artist', 'Someone');
    xattr_set($file, 'My ranking', 'Good');
    xattr_set($file, 'Listen count', '34');

    /* ... autres codes ... */

    printf("Vous avez écouté cette chanson %d fois", xattr_get($file, 'Listen count'));
    ?>

### Voir aussi

- xattr_get() - Récupère un attribut étendu
- xattr_remove() - Efface un attribut étendu

# xattr_supported

(PECL xattr >= 1.0.0)

xattr_supported — Vérifie si un système de fichiers supporte les attributs étendus

### Description

function xattr_supported(string `$filename`, int `$flags` = 0): bool

xattr_supported() vérifie si le système de fichiers contenant le fichier `filename` supporte les attributs étendus. Un accès en lecture au fichier `filename` est nécessaire.

### Liste de paramètres

`filename`

  Le chemin du fichier à tester.

`flags`

  Flags xattr supportés
  `XATTR_DONTFOLLOW` | Ne pas suivre les liens symboliques mais opère directement sur le lien lui-même.

### Valeurs de retour

Cette fonction retourne `true` si le système de fichiers supporte les attributs étendus, `false` sinon et `null` si l'on ne peut pas le déterminer (par exemple, mauvais chemin vers le fichier ou lorsqu'il manque des permissions sur le fichier).

### Exemples

Exemple #1 Exemple avec xattr_supported()

Le code suivant vérifie si nous pouvons utiliser les attributs étendus.

    <?php
    $file = 'un_fichier';

    if (xattr_supported($file)) {
        /* ... utiliser les fonctions xattr_* ... */
    }

    ?>

### Voir aussi

- xattr_get() - Récupère un attribut étendu
- xattr_list() - Récupère une liste d'attributs étendus

## Sommaire

- xattr_get — Récupère un attribut étendu
- xattr_list — Récupère une liste d'attributs étendus
- xattr_remove — Efface un attribut étendu
- xattr_set — Définit un attribut étendu
- xattr_supported — Vérifie si un système de fichiers supporte les attributs étendus

- Installation/Configuration
  - Pré-requis
  - Installation
- Constantes pré-définies
- Fonctions xattr
  - xattr_get — Récupère un attribut étendu
  - xattr_list — Récupère une liste d'attributs étendus
  - xattr_remove — Efface un attribut étendu
  - xattr_set — Définit un attribut étendu
  - xattr_supported — Vérifie si un système de fichiers supporte les attributs étendus

# xdiff

# Introduction

L'extension xdiff permet la création et l'application de patchs, contenant les différences entre différentes versions d'un même fichier.

Cette extension supporte deux modes d'opération : sur les chaînes et sur les fichiers, ainsi que deux formats de patch : unifié et binaire. Les patches unifiés sont parfaits pour les fichiers textes, car ils sont lisibles et faciles à passer en revue. Les fichiers binaires comme les archives compressées ou les images sont plus adaptés aux patches binaires, car ils sont compatibles avec les données binaires, et gèrent les caractères qui ne s'impriment pas.

Depuis la version 1.5.0, il y a deux jeux de fonctions pour générer les fichiers binaires. Les nouvelles fonctions, xdiff_string_rabdiff() et xdiff_file_rabdiff() génèrent un résultat compatible avec les anciennes fonctions, mais généralement plus rapidement, et avec des résultats plus compacts. Pour plus de détails sur la génération de patchs binaires, et leur différence, voir le site Web de » libxdiff.

Cette extension utilise la bibliothèque libxdiff pour implémenter ces fonctions. Se reporter à » http://www.xmailserver.org/xdiff-lib.html pour plus d'informations.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Pour utiliser xdiff, il faut avoir installé libxdiff, disponible sur la page d'accueil de » http://www.xmailserver.org/xdiff-lib.html.

> Note:

> La version libxdiff 0.7 au minimum est nécessaire pour ces fonctions.

## Installation

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/xdiff.

Les binaires Windows (les fichiers DLL) pour cette extension PECL sont disponibles sur le site web PECL.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`XDIFF_PATCH_NORMAL` (int)
  Cette option indique que les fonctions xdiff_string_patch() et xdiff_file_patch() doivent créer un résultat en appliquant le patch au contenu original, et créer ainsi une nouvelle version du fichier. C'est le mode d'opération par défaut.
`XDIFF_PATCH_REVERSE` (int)
  Cette option indique que les fonctions xdiff_string_patch() et xdiff_file_patch() doivent créer un résultat en annulant un patch depuis une version de fichier pour retrouver la version originale.

# Fonctions xdiff

# xdiff_file_bdiff

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff — Crée un diff binaire de 2 fichiers

### Description

function xdiff_file_bdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Crée un diff binaire de 2 fichiers et enregistre le résultat dans un fichier patch. Cette fonction fonctionne avec des fichiers textes mais aussi des fichiers binaires. Le fichier patch résultant peut être ensuite appliqué en utilisant les fonctions xdiff_file_bpatch() et xdiff_string_bpatch().

### Liste de paramètres

`old_file`

  Chemin vers le premier fichier. C'est l'ancien fichier.

`new_file`

  Chemin vers le second fichier. C'est le nouveau fichier.

`dest`

  Chemin vers le fichier patch résultant. Ce patch contient les différences entre l'ancien et le nouveau fichier. Il est au format binaire et est humainement illisible.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec xdiff_file_bdiff()

Le code suivant crée un diff binaire de 2 archives.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_bdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Notes

> Note:

> Les 2 fichiers seront chargés en mémoire ; aussi, il faut s'assurer que le paramètre memory_limit est défini à une valeur assez élevée.

### Voir aussi

- xdiff_file_bpatch() - Patche un fichier avec un diff binaire

# xdiff_file_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff_size — Lit la taille d'un fichier créé lors de l'application d'un diff binaire

### Description

function xdiff_file_bdiff_size(string `$file`): int

Retourne la taille d'un fichier résultat créé après l'application d'un patch binaire depuis le fichier `file` sur le fichier original.

### Liste de paramètres

`file`

  Le chemin vers le patch binaire créé par la fonction xdiff_string_bdiff() ou la fonction xdiff_string_rabdiff().

### Valeurs de retour

Retourne la taille du fichier créé.

### Exemples

Exemple #1 Exemple avec xdiff_file_bdiff_size()

Le code suivant lit la taille d'un fichier créé après l'application d'un diff binaire.

    <?php
    $length = xdiff_string_bdiff_size('file.bdiff');
    echo "Le fichier résultat a une taille de $length octets";
    ?>

### Voir aussi

- xdiff_file_bdiff() - Crée un diff binaire de 2 fichiers
- xdiff_file_rabdiff() - Crée un diff binaire de 2 fichiers en utilisant l'algorithme polynomial de Rabin des empreintes digitales
- xdiff_file_bpatch() - Patche un fichier avec un diff binaire

# xdiff_file_bpatch

(PECL xdiff >= 1.5.0)

xdiff_file_bpatch — Patche un fichier avec un diff binaire

### Description

function xdiff_file_bpatch(string `$file`, string `$patch`, string `$dest`): bool

Patche le fichier `file` avec le `patch` binaire et enregistre le résultat dans le fichier `dest`. Cette fonction accepte les patchs créés via les fonctions xdiff_file_bdiff() et xdiff_file_rabdiff() ou leur équivalent sous forme de chaînes.

### Liste de paramètres

`file`

  Le fichier original.

`patch`

  Le fichier patch binaire.

`dest`

  Chemin vers le fichier résultat.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec xdiff_file_bpatch()

Le code suivant applique un diff binaire à un fichier.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_bpatch($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "Fichier patché";
    } else {
       echo "Le fichier ne peut être patché";
    }

    ?>

### Notes

> Note:

> Les 2 fichiers (`file` et `patch`) seront chargés en mémoire ; aussi, il faut s'assurer que le paramétrage de memory_limit est suffisamment élevé.

### Voir aussi

- xdiff_file_bdiff() - Crée un diff binaire de 2 fichiers
- xdiff_file_rabdiff() - Crée un diff binaire de 2 fichiers en utilisant l'algorithme polynomial de Rabin des empreintes digitales

# xdiff_file_diff

(PECL xdiff >= 0.2.0)

xdiff_file_diff — Crée un diff unifié entre deux fichiers

### Description

function xdiff_file_diff(
string `$old_file`,
string `$new_file`,
string `$dest`,
int `$context` = 3,
bool `$minimal` = `false`
): bool

Crée un diff unifié contenant les différences entre le fichier `old_file` et `new_file` et les enregistre dans le fichier `dest`. Le fichier résultant est humainement lisible. Le paramètre optionnel `context` spécifie le nombre de lignes du contexte qui doit être ajouté autour de chaque modification. Si le paramètre `minimal` vaut `true`, alors le fichier de sortie sera le plus petit possible (peut prendre beaucoup de temps).

### Liste de paramètres

`old_file`

  Chemin vers le premier fichier. Ce fichier représente l'ancien fichier.

`new_file`

  Chemin vers le second fichier. Ce fichier représente le nouveau fichier.

`dest`

  Chemin vers le fichier contenant la différence.

`context`

  Indique le nombre de lignes de contexte qu'on souhaite inclure dans le résultat de diff.

`minimal`

  Configurer `minimal` à `true` pour minimaliser la taille du fichier des différences (peut prendre beaucoup de temps).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec xdiff_file_diff()

Le code suivant crée un diff de deux fichiers php avec une longueur de contexte de 2.

    <?php
    $old_version = 'my_script.php';
    $new_version = 'my_new_script.php';

    xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
    ?>

### Notes

> Note:

> Cette fonction ne fonctionne pas correctement avec les fichiers binaires. Pour effectuer un diff sur des fichiers binaires, utiliser la fonction xdiff_file_bdiff()/xdiff_file_rabdiff().

### Voir aussi

- xdiff_file_patch() - Patche un fichier avec un diff unifié

# xdiff_file_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_file_diff_binary — Alias de xdiff_file_bdiff()

### Description

function xdiff_file_diff_binary(string `$old_file`, string `$new_file`, string `$dest`): bool

Crée un diff binaire entre les deux fichiers et stocke le résultat dans `dest`. Cette fonction fonctionne avec les fichiers texte, mais aussi avec les fichiers binaires. Le patch résultant peut être appliqué à l'aide de la fonction xdiff_file_bpatch().

Depuis la version 1.5.0, cette fonction est un alias de xdiff_file_bdiff().

### Liste de paramètres

`old_file`

  Chemin jusqu'au premier fichier. Ce fichier est le "vieux" fichier.

`new_file`

  Chemin jusqu'au deuxième fichier. Ce fichier est le "nouveau" fichier.

`dest`

  Chemin vers le fichier résultat. Ce fichier contient les différences entre l'ancien et le nouveau fichier. C'est un format binaire, et il est illisible par un humain.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec xdiff_file_diff_binary()

Le code suivant crée une différence binaire de deux archives.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
    ?>

### Notes

> Note:

> Les deux fichiers seront chargés en mémoire ; il faut s'assurer d'avoir défini `memory_limit` à une valeur assez grande.

### Voir aussi

- xdiff_file_bdiff() - Crée un diff binaire de 2 fichiers
- xdiff_file_bpatch() - Patche un fichier avec un diff binaire

# xdiff_file_merge3

(PECL xdiff >= 0.2.0)

xdiff_file_merge3 — Fusionne trois fichiers en un seul

### Description

function xdiff_file_merge3(
string `$old_file`,
string `$new_file1`,
string `$new_file2`,
string `$dest`
): mixed

Fusionne trois fichiers en un seul et le stocke dans `dest`. Le fichier `old_file` est la version originale, tandis que les fichiers `new_file1` et `new_file2` sont les versions modifiées de l'original.

### Liste de paramètres

`old_file`

  Chemin vers le premier fichier. C'est l'ancien fichier.

`new_file1`

  Chemin vers le second fichier. C'est la version modifiée de `old_file`.

`new_file2`

  Chemin vers le troisième fichier. C'est la version modifiée de `old_file`.

`dest`

  Chemin vers le fichier résultant, contenant la fusion des modifications des fichiers `new_file1` et `new_file2`.

### Valeurs de retour

Retourne `true` si la fusion a réussi, une chaîne avec les parties rejetées s'il y en a, ou `false` si une erreur interne s'est produite.

### Exemples

Exemple #1 Exemple avec xdiff_file_merge3()

Le code suivant fusionne trois fichiers en un.

    <?php
    $old_version = 'original_script.php';
    $fix1 = 'script_with_fix1.php';
    $fix2 = 'script_with_fix2.php';

    $errors = xdiff_file_merge3($old_version, $fix1, $fix2, 'fixed_script.php');
    if (is_string($errors)) {
        echo "Rejets :\n";
        echo $errors;
    }
    ?>

### Voir aussi

- xdiff_string_merge3() - Fusionne trois chaînes en une seule

# xdiff_file_patch

(PECL xdiff >= 0.2.0)

xdiff_file_patch — Patche un fichier avec un diff unifié

### Description

function xdiff_file_patch(
string `$file`,
string `$patch`,
string `$dest`,
int `$flags` = DIFF_PATCH_NORMAL
): mixed

Patche le fichier `file` avec le patch fourni par le paramètre `patch` et enregistre le résultat dans un fichier. `patch` doit être un diff unifié créé par la fonction xdiff_file_diff()/xdiff_string_diff(). Un paramètre optionnel `flags` spécifie le mode de l'opération.

### Liste de paramètres

`file`

  Le fichier original.

`patch`

  Le fichier contenant le patch unifié. Il doit avoir été créé en utilisant les fonctions xdiff_string_diff(), xdiff_file_diff() ou par des outils compatibles.

`dest`

  Le chemin vers le fichier résultat.

`flags`

  Peut être soit `XDIFF_PATCH_NORMAL` (mode par défaut, patch normal) ou `XDIFF_PATCH_REVERSE` (patch inversé).

  Depuis la version 1.5.0, il est également possible d'utiliser l'opérateur binaire OR pour activer le drapeau `XDIFF_PATCH_IGNORESPACE`.

### Valeurs de retour

Retourne `false` si une erreur interne s'est produite, une chaîne avec les parties rejetées du `patch` si c'est le cas ou `true` si le `patch` a été appliqué avec succès.

### Exemples

Exemple #1 Exemple avec xdiff_file_patch()

Le code suivant applique un diff à un fichier.

    <?php
    $old_version = 'my_script-1.0.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($old_version, $patch, 'my_script-1.1.php');
    if (is_string($errors)) {
       echo "Rejets :\n";
       echo $errors;
    }

    ?>

Exemple #2 Exemple de retour à l'état initial après l'application d'un patch

Le code suivant annule un patch.

    <?php
    $new_version = 'my_script-1.1.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($new_version, $patch, 'my_script-1.0.php', XDIFF_PATCH_REVERSE);
    if (is_string($errors)) {
       echo "Rejets :\n";
       echo $errors;
    }

    ?>

### Voir aussi

- xdiff_file_diff() - Crée un diff unifié entre deux fichiers

# xdiff_file_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_file_patch_binary — Alias de xdiff_file_bpatch()

### Description

function xdiff_file_patch_binary(string `$file`, string `$patch`, string `$dest`): bool

Patche le fichier `file` avec un `patch` binaire et enregistre le résultat dans le fichier `dest`. Cette fonction accepte les patchs créés avec la fonction xdiff_file_bdiff() ou la fonction xdiff_file_rabdiff() ou leur équivalent sous forme de chaînes.

Depuis la version 1.5.0, cette fonction est un alias de la fonction xdiff_file_bpatch().

### Liste de paramètres

`file`

  Le fichier original.

`patch`

  Le Patch binaire.

`dest`

  Le chemin vers le fichier résultat.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec xdiff_file_patch_binary()

Le code suivant applique un diff binaire à un fichier.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_patch_binary($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "File patched";
    } else {
       echo "File couldn't be patched";
    }

    ?>

### Notes

> Note:

> Les deux fichiers (le fichier et le patch) seront chargés en mémoire ; il faut s'assurer d'avoir défini `memory_limit` à une valeur assez élevée.

### Voir aussi

- xdiff_string_patch_binary() - Alias de xdiff_string_bpatch

# xdiff_file_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_file_rabdiff — Crée un diff binaire de 2 fichiers en utilisant l'algorithme polynomial de Rabin des empreintes digitales

### Description

function xdiff_file_rabdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Crée un diff binaire de 2 fichiers et enregistre le résultat dans un fichier patch. La différence entre cette fonction et la fonction xdiff_file_bdiff() se situe au niveau de l'algorithme utilisé. Aussi, cette fonction devrait être plus rapide et devrait produire un diff plus petit. Cette fonction fonctionne avec des fichiers textes, comme avec des fichiers binaires. Le fichier patch résultant pourra ensuite être appliqué avec les fonctions xdiff_file_bpatch() et xdiff_string_bpatch().

Pour plus de détails concernant les différences d'algorithme, se reporter au site web de la bibliothèque » libxdiff.

### Liste de paramètres

`old_file`

  Chemin vers le premier fichier. C'est l'ancien fichier.

`new_file`

  Chemin vers le second fichier. C'est le nouveau fichier.

`dest`

  Chemin vers le fichier résultant. Le fichier résultant contient les différences entre l'ancien et le nouveau fichier. Il est au format binaire, aussi, il ne sera pas humainement lisible.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec xdiff_file_rabdiff()

Le code suivant crée un diff binaire de 2 archives.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_rabdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Notes

> Note:

> Les 2 fichiers seront chargés en mémoire ; aussi, il faut s'assurer que le paramétrage de memory_limit est suffisamment élevé.

### Voir aussi

- xdiff_file_bpatch() - Patche un fichier avec un diff binaire

# xdiff_string_bdiff

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff — Crée un diff binaire de 2 chaînes

### Description

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Crée un diff binaire de 2 chaînes et retourne le résultat. Cette fonction fonctionne aussi bien avec des données textes qu'avec des données binaires. Le patch résultant pourra ensuite être appliqué en utilisant les fonctions xdiff_string_bpatch() et xdiff_file_bpatch().

### Liste de paramètres

`old_data`

  Première chaîne contenant des données binaires. Ce sont les anciennes données.

`new_data`

  Seconde chaîne contenant des données binaires. Ce sont les nouvelles données.

### Valeurs de retour

Retourne un diff binaire contenant les différences entre les anciennes et les nouvelles données, ou `false` si une erreur interne survient.

### Voir aussi

- xdiff_string_bpatch() - Patche une chaîne avec un diff binaire

# xdiff_string_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff_size — Lit la taille d'un fichier créé en appliquant un diff binaire

### Description

function xdiff_string_bdiff_size(string `$patch`): int

Retourne la taille d'un fichier résultat créé après l'application d'un `patch` binaire sur un fichier original.

### Liste de paramètres

`patch`

  Le patch binaire créé par la fonction xdiff_string_bdiff() ou la fonction xdiff_string_rabdiff().

### Valeurs de retour

Retourne la taille du fichier créé.

### Exemples

Exemple #1 Exemple avec xdiff_string_bdiff_size()

Le code suivant lit la taille d'un fichier créé après l'application d'un diff binaire.

    <?php
    $binary_patch = file_get_contents('file.bdiff');
    $length = xdiff_string_bdiff_size($binary_patch);
    echo "La taille du fichier résultant est de $length octets.";
    ?>

### Voir aussi

- xdiff_string_bdiff() - Crée un diff binaire de 2 chaînes
- xdiff_string_rabdiff() - Crée un diff binaire de 2 chaînes en utilisant l'algorithme polynomial de Rabin des empreintes digitales
- xdiff_string_bpatch() - Patche une chaîne avec un diff binaire

# xdiff_string_bpatch

(PECL xdiff >= 1.5.0)

xdiff_string_bpatch — Patche une chaîne avec un diff binaire

### Description

function xdiff_string_bpatch(string `$str`, string `$patch`): string

Patche une chaîne `str` avec un `patch` binaire. Cette fonction accepte les patchs créés via les fonctions xdiff_string_bdiff() et xdiff_string_rabdiff(), ou leur équivalent sous forme de fichier.

### Liste de paramètres

`str`

  La chaîne binaire originale.

`patch`

  Le patch binaire sous forme d'une chaîne de caractères.

### Valeurs de retour

Retourne la chaîne patchée, ou `false` si une erreur survient.

### Voir aussi

- xdiff_string_bdiff() - Crée un diff binaire de 2 chaînes
- xdiff_string_rabdiff() - Crée un diff binaire de 2 chaînes en utilisant l'algorithme polynomial de Rabin des empreintes digitales

# xdiff_string_diff

(PECL xdiff >= 0.2.0)

xdiff_string_diff — Crée un diff unifié entre deux chaînes

### Description

function xdiff_string_diff(
string `$old_data`,
string `$new_data`,
int `$context` = 3,
bool `$minimal` = `false`
): string

Crée un diff unifié contenant les différences entre la chaîne `old_data` et la chaîne `new_data` et retourne le diff ainsi créé. Le diff résultant est humainement lisible. Le paramètre optionnel `context` spécifie le nombre de lignes de contexte à ajouter autour de chaque modification. Le fait de définir le paramètre `minimal` à `true` fera que le diff sera le plus petit possible (peut prendre du temps).

### Liste de paramètres

`old_data`

  Première chaîne de données. Ce sont les anciennes données.

`new_data`

  Seconde chaîne de données. Ce sont les nouvelles données.

`context`

  Indique le nombre de lignes de contexte qu'on souhaite inclure dans le diff résultant.

`minimal`

  Configurer `minimal` à `true` pour minimaliser la taille du diff (peut prendre beaucoup de temps).

### Valeurs de retour

Retourne une chaîne représentant le diff résultant, ou `false` si une erreur interne survient.

### Exemples

Exemple #1 Exemple avec xdiff_string_diff()

Le code suivant effectue un diff de deux articles.

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $new_article = $_REQUEST['article']; /* disons que quelqu'un a posté un nouvel article via un formulaire html */

    $diff = xdiff_string_diff($old_article, $new_article, 1);
    if (is_string($diff)) {
        echo "Différences entre les deux articles :\n";
        echo $diff;
    }

    ?>

### Notes

> Note:

> Cette fonction ne fonctionne pas correctement avec des chaînes binaires. Pour effectuer un diff de chaînes binaires, utiliser la fonction xdiff_string_bdiff()/xdiff_string_rabdiff().

### Voir aussi

- xdiff_string_patch() - Patche une chaîne avec un diff unifié

# xdiff_string_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_string_diff_binary — Alias de xdiff_string_bdiff()

### Description

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Crée un diff binaire de 2 chaînes et retourne le résultat. Cette fonction fonctionne avec du texte mais aussi avec des données binaires. Le patch résultant peut être appliqué ultérieurement en utilisant la fonction xdiff_string_bpatch()/xdiff_file_bpatch().

Depuis la version 1.5.0, cette fonction est un alias de la fonction xdiff_string_bdiff().

### Liste de paramètres

`old_data`

  Première chaîne avec des données binaires. Ce sont les anciennes données.

`new_data`

  Seconde chaîne avec des données binaires. Ce sont les nouvelles données.

### Valeurs de retour

Retourne une chaîne avec le résultat ou `false` si une erreur interne est survenue.

### Voir aussi

- xdiff_string_bdiff() - Crée un diff binaire de 2 chaînes
- xdiff_string_bpatch() - Patche une chaîne avec un diff binaire

# xdiff_string_merge3

(PECL xdiff >= 0.2.0)

xdiff_string_merge3 — Fusionne trois chaînes en une seule

### Description

function xdiff_string_merge3(
string `$old_data`,
string `$new_data1`,
string `$new_data2`,
string `&$error` = ?
): mixed

Fusionne 3 chaînes en une et retourne le résultat. Le paramètre `old_data` est la version originale des données tandis que `new_data1` et `new_data2` sont les versions modifiées de l'original. Le paramètre optionnel `error` est utilisé pour stocker toutes les parties rejetées lors de la fusion.

### Liste de paramètres

`old_data`

  Première chaîne de données. Ce sont les anciennes données.

`new_data1`

  Seconde chaîne de données. Ce sont les versions modifiées de `old_data`.

`new_data2`

  Troisième chaîne de données. Ce sont les versions modifiées de `old_data`.

`error`

  Si `error` est fourni, alors les parties rejetées y seront stockées.

### Valeurs de retour

Retourne la chaîne fusionnée, `false` si une erreur interne survient ou `true` si la chaîne fusionnée est vide.

### Voir aussi

- xdiff_file_merge3() - Fusionne trois fichiers en un seul

# xdiff_string_patch

(PECL xdiff >= 0.2.0)

xdiff_string_patch — Patche une chaîne avec un diff unifié

### Description

function xdiff_string_patch(
string `$str`,
string `$patch`,
int `$flags` = ?,
string `&$error` = ?
): string

Patche la chaîne `str` avec un `patch` unifié et retourne le résultat. `patch` doit être un patch unifié créé par les fonctions xdiff_file_diff() et xdiff_string_diff(). Un paramètre optionnel `flags` spécifie le mode de l'opération. Toutes les parties rejetées seront stockées dans la variable `error` si elle est fournie.

### Liste de paramètres

`str`

  La chaîne originale.

`patch`

  Le patch unifié. Il doit avoir été créé en utilisant les fonctions xdiff_string_diff(), xdiff_file_diff() ou tout autre outil compatible.

`flags`

  `flags` peut être soit `XDIFF_PATCH_NORMAL` (mode par défaut, patch normal), soit `XDIFF_PATCH_REVERSE` (patch inversé).

  Depuis la version 1.5.0, il est également possible d'utiliser l'opérateur binaire OR pour activer le drapeau `XDIFF_PATCH_IGNORESPACE`.

`error`

  Si `error` est fourni, les parties rejetées y seront stockées.

### Valeurs de retour

Retourne la chaîne patchée, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec xdiff_string_patch()

Le code suivant applique les changements à des articles.

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $diff = $_SERVER['patch']; /* disons que quelqu'un a passé un patch via un formulaire html */

    $errors = '';

    $new_article = xdiff_string_patch($old_article, $diff, XDIFF_PATCH_NORMAL, $errors);
    if (is_string($new_article)) {
        echo "Nouvel article :\n";
        echo $new_article;
    }

    if (strlen($errors)) {
        echo "Rejets : \n";
        echo $errors;
    }

    ?>

### Voir aussi

- xdiff_string_diff() - Crée un diff unifié entre deux chaînes

# xdiff_string_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_string_patch_binary — Alias de xdiff_string_bpatch()

### Description

function xdiff_string_patch_binary(string `$str`, string `$patch`): string

Patche une chaîne `str` avec un `patch` binaire. Cette fonction accepte les patchs créés avec les fonctions xdiff_string_bdiff() et xdiff_string_rabdiff() ou leur équivalent en fichiers.

Depuis la version 1.5.0, cette fonction est un alias de la fonction xdiff_string_bpatch().

### Liste de paramètres

`str`

  La chaîne binaire originale.

`patch`

  Le patch binaire.

### Valeurs de retour

Retourne la chaîne patchée, ou `false` si une erreur survient.

### Voir aussi

- xdiff_string_bpatch() - Patche une chaîne avec un diff binaire
- xdiff_string_bdiff() - Crée un diff binaire de 2 chaînes
- xdiff_string_rabdiff() - Crée un diff binaire de 2 chaînes en utilisant l'algorithme polynomial de Rabin des empreintes digitales

# xdiff_string_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_string_rabdiff — Crée un diff binaire de 2 chaînes en utilisant l'algorithme polynomial de Rabin des empreintes digitales

### Description

function xdiff_string_rabdiff(string `$old_data`, string `$new_data`): string|false

Crée un diff binaire entre deux chaînes en utilisant l’algorithme d’empreinte polynomial de Rabin implémenté par » libxdiff. Comparé à xdiff_string_bdiff(), cet algorithme génère généralement des diffs plus compacts et fonctionne plus rapidement, tout en restant pleinement compatible avec xdiff_string_bpatch() et xdiff_file_bpatch() pour l’application des patchs.

Cette fonction peut être utilisée avec des données texte ou binaires. Les données de diff produites peuvent ensuite être appliquées afin de recréer la nouvelle version à partir de l’ancienne.

Pour obtenir davantage d’informations sur l’algorithme, consulter la » documentation de libxdiff.

### Liste de paramètres

`old_data`

  La première chaîne contenant les données binaires « anciennes ».

`new_data`

  La seconde chaîne contenant les données binaires « nouvelles ».

### Valeurs de retour

Retourne une chaîne binaire contenant les différences entre les données anciennes et nouvelles, ou `false` si une erreur survient.

### Exemples

Exemple #1 Création d’un diff binaire entre deux chaînes

    <?php
    $old = file_get_contents('file_v1.txt');
    $new = file_get_contents('file_v2.txt');

    $diff = xdiff_string_rabdiff($old, $new);
    file_put_contents('patch.rdiff', $diff);
    ?>

### Voir aussi

- xdiff_string_bdiff() - Crée un diff binaire de 2 chaînes
- xdiff_string_bpatch() - Patche une chaîne avec un diff binaire
- xdiff_file_bpatch() - Patche un fichier avec un diff binaire

## Sommaire

- xdiff_file_bdiff — Crée un diff binaire de 2 fichiers
- xdiff_file_bdiff_size — Lit la taille d'un fichier créé lors de l'application d'un diff binaire
- xdiff_file_bpatch — Patche un fichier avec un diff binaire
- xdiff_file_diff — Crée un diff unifié entre deux fichiers
- xdiff_file_diff_binary — Alias de xdiff_file_bdiff
- xdiff_file_merge3 — Fusionne trois fichiers en un seul
- xdiff_file_patch — Patche un fichier avec un diff unifié
- xdiff_file_patch_binary — Alias de xdiff_file_bpatch
- xdiff_file_rabdiff — Crée un diff binaire de 2 fichiers en utilisant l'algorithme polynomial de Rabin des empreintes digitales
- xdiff_string_bdiff — Crée un diff binaire de 2 chaînes
- xdiff_string_bdiff_size — Lit la taille d'un fichier créé en appliquant un diff binaire
- xdiff_string_bpatch — Patche une chaîne avec un diff binaire
- xdiff_string_diff — Crée un diff unifié entre deux chaînes
- xdiff_string_diff_binary — Alias de xdiff_string_bdiff
- xdiff_string_merge3 — Fusionne trois chaînes en une seule
- xdiff_string_patch — Patche une chaîne avec un diff unifié
- xdiff_string_patch_binary — Alias de xdiff_string_bpatch
- xdiff_string_rabdiff — Crée un diff binaire de 2 chaînes en utilisant l'algorithme polynomial de Rabin des empreintes digitales

- Installation/Configuration
  - Pré-requis
  - Installation
- Constantes pré-définies
- Fonctions xdiff
  - xdiff_file_bdiff — Crée un diff binaire de 2 fichiers
  - xdiff_file_bdiff_size — Lit la taille d'un fichier créé lors de l'application d'un diff binaire
  - xdiff_file_bpatch — Patche un fichier avec un diff binaire
  - xdiff_file_diff — Crée un diff unifié entre deux fichiers
  - xdiff_file_diff_binary — Alias de xdiff_file_bdiff
  - xdiff_file_merge3 — Fusionne trois fichiers en un seul
  - xdiff_file_patch — Patche un fichier avec un diff unifié
  - xdiff_file_patch_binary — Alias de xdiff_file_bpatch
  - xdiff_file_rabdiff — Crée un diff binaire de 2 fichiers en utilisant l'algorithme polynomial de Rabin des empreintes digitales
  - xdiff_string_bdiff — Crée un diff binaire de 2 chaînes
  - xdiff_string_bdiff_size — Lit la taille d'un fichier créé en appliquant un diff binaire
  - xdiff_string_bpatch — Patche une chaîne avec un diff binaire
  - xdiff_string_diff — Crée un diff unifié entre deux chaînes
  - xdiff_string_diff_binary — Alias de xdiff_string_bdiff
  - xdiff_string_merge3 — Fusionne trois chaînes en une seule
  - xdiff_string_patch — Patche une chaîne avec un diff unifié
  - xdiff_string_patch_binary — Alias de xdiff_string_bpatch
  - xdiff_string_rabdiff — Crée un diff binaire de 2 chaînes en utilisant l'algorithme polynomial de Rabin des empreintes digitales

- Direct IO
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Direct IO
- Les dossiers
  - Constantes pré-définies
  - Directory — La classe Directory
  - Fonctions sur les dossiers
- Fileinfo — Informations sur les fichiers
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Fileinfo
  - finfo — La classe finfo
- Système de fichiers
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions sur les systèmes de fichiers
- Inotify
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Inotify
- xattr
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions xattr
- xdiff
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions xdiff

# Support du langage humain et de l'encodage de caractères

# Bibliothèque d'orthographe Enchant

# Introduction

Enchant est la liaison PHP de la » bibliothèque Enchant. Enchant fournit une uniformité et une conformité pour toutes les bibliothèques d'orthographe, et implémente certaines fonctionnalités qui peuvent faire défaut dans une bibliothèque. Tout devrait "juste fonctionner".

Enchant supporte les bibliothèques suivantes :

- `Aspell/Pspell (prévu pour remplacer Ispell)`
- `Ispell (très ancien, peut être considéré comme un standard)`
- `MySpell/Hunspell (un projet OpenOffice.org, également utilisé par Mozilla)`
- `Uspell (prévu à l'origine pour le yiddish, l'hébreu et les langues d'Europe de l'Est - hébergé dans le CVS d'AbiWord sous le module "uspell")`
- `Hspell (Hébreu)`
- `AppleSpell (Mac OSX)`

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Types de ressources

## Pré-requis

Cette version utilise les fonctions de la » bibliothèque Enchant par Dom Lachowicz. Il faut utiliser Enchant 1.2.4 ou supérieur. Enchant 2.0.0 ou supérieur est uniquement supporté à partir de PHP 8.0.0.

Enchant requiert également » Glib 2.6 ou supérieur. Les bibliothèques Windows pré-compilées sont disponibles depuis » http://ftp.gnome.org/pub/gnome/binaries/win32/glib/.

## Installation

En partant du principe que les bibliothèques requises sont installées, les utilisateurs peuvent activer enchant en ajoutant l'option --with-enchant[=dir] lors de la compilation de PHP.

Les utilisateurs de Windows doivent activer php_enchant.dll pour pouvoir utiliser cette extension.

> Note: Configuration supplémentaire sur Windows
> Afin de faire fonctionner cette extension, quelques bibliothèques DLL doivent être disponibles via le PATH du système Windows. Lisez la F.A.Q intitulée "Comment ajouter mon dossier PHP à mon PATH Windows" pour plus d'informations. Le fait de copier les bibliothèques DLL depuis le dossier PHP dans le dossier système Windows fonctionne également (car le dossier système est par défaut dans le PATH système), mais cette méthode n'est pas recommandée. Cette extension nécessite que les fichiers suivants se trouvent dans le PATH : libenchant.dll, glib-2.dll, gmodule-2.dll. De plus, il est nécessaire de copier au moins un des fournisseurs fournis dans lib\enchant vers \usr\local\lib\enchant-2 (qui est un chemin absolu à partir de la racine du disque actuel). Antérieur à PHP 8.0.0, c'est-à-dire en utilisant Enchant v1, les fournisseurs devaient être copiés dans C:\enchant_plugins à la place, où ce chemin pouvait être personnalisé en créant la valeur de registre `HKEY_CURRENT_USER\SOFTWARE\Enchant\Config\Module_Dir` et en la configurant avec le chemin souhaité.

## Types de ressources

Antérieur à PHP 8.0.0, il y a deux types de ressources dans cette extension. La première est le broker (gestionnaire de backends) et la seconde est pour le dictionnaire.

# Constantes pré-définies

`LIBENCHANT_VERSION` (string)
  La version de libenchant. Disponible à partir de PHP 8.0.0.
`ENCHANT_MYSPELL` (int)
  Type de dictionnaire pour MySpell. Utilisé avec enchant_broker_get_dict_path() et enchant_broker_set_dict_path(). Obsolète à partir de PHP 8.0.0.
`ENCHANT_ISPELL` (int)
  Type de dictionnaire pour Ispell. Utilisé avec enchant_broker_get_dict_path() et enchant_broker_set_dict_path(). Obsolète à partir de PHP 8.0.0.

# Exemples

Exemple #1 Exemple d'utilisation d'Enchant

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "Current broker provides the following backend(s):\n";
    print_r($bprovides);

    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);
        $dprovides = enchant_dict_describe($d);
        echo "dictionary $tag provides:\n";
        $wordcorrect = enchant_dict_check($d, "soong");
        print_r($dprovides);
        if (!$wordcorrect) {
            $suggs = enchant_dict_suggest($d, "soong");
            echo "Suggestions for 'soong':";
            print_r($suggs);
        }
        enchant_broker_free_dict($d);
    } else {
    }
    enchant_broker_free($r);
    ?>

# Fonctions Enchant

# enchant_broker_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0)

enchant_broker_describe — Énumère les fournisseurs Enchant

### Description

function enchant_broker_describe(EnchantBroker `$broker`): array

Énumère les fournisseurs Enchant et affiche quelques informations sur eux. Les mêmes informations sont fournies via la fonction phpinfo().

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().

### Valeurs de retour

Retourne un tableau des fournisseurs Enchant disponibles avec leurs détails.

### Historique

Version | Description
--- | ---
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.
8.0.0 | Antérieur à cette version, cette fonction retournait `false` en cas d'échec.

### Exemples

Exemple #1 Liste les interfaces fournies par un sponsor donné

    <?php
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "Le sponsor courant fournit les interfaces suivantes :\n";
    print_r($bprovides);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Le sponsor courant fournit les interfaces suivantes :
    Array
    (
        [0] => Array
            (
                [name] => aspell
                [desc] => Aspell Provider
                [file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [name] => hspell
                [desc] => Hspell Provider
                [file] => /usr/lib/enchant/libenchant_hspell.so
            )

        [2] => Array
            (
                [name] => ispell
                [desc] => Ispell Provider
                [file] => /usr/lib/enchant/libenchant_ispell.so
            )

        [3] => Array
            (
                [name] => myspell
                [desc] => Myspell Provider
                [file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

# enchant_broker_dict_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_dict_exists — Vérifie si un dictionnaire existe

### Description

function enchant_broker_dict_exists(EnchantBroker `$broker`, string `$tag`): bool

Vérifie si un dictionnaire existe.

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().
`tag`
  langue, dans un format comme us_US, ch_DE, etc.

### Valeurs de retour

Retourne `true` si la langue existe, `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec enchant_broker_dict_exists()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r,$tag)) {
        echo $tag . " dictionary found.\n";
    }
    ?>

### Voir aussi

- enchant_broker_describe() - Énumère les fournisseurs Enchant

# enchant_broker_free

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free — Libère la ressource de sponsor ainsi que ses dictionnaires

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function enchant_broker_free(EnchantBroker `$broker`): bool

Libère un sponsor ainsi que tous ses dictionnaires. À partir de PHP 8.0.0, il est recommandé de détruire l'objet au lieu d'appeler cette fonction.

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est dépréciée au profit de la désinitialisation de l'objet.
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.

### Voir aussi

- enchant_broker_init() - Crée un nouvel objet broker

# enchant_broker_free_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free_dict — Libère une ressource de dictionnaire

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function enchant_broker_free_dict(EnchantDictionary `$dictionary`): bool

Libère un dictionnaire. À partir de PHP 8.0.0, il est recommandé de détruire l'objet au lieu d'appeler cette fonction.

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction est dépréciée au profit de la désinitialisation de l'objet.
8.0.0 | `dictionary` attend désormais une EnchantDictionary; auparavant, une resource était attendue.

### Voir aussi

- enchant_broker_request_dict() - Crée un nouveau dictionnaire
- enchant_broker_request_pwl_dict() - Crée un dictionnaire en utilisant un fichier PWL

# enchant_broker_get_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_get_dict_path — Récupère le chemin du dossier pour un backend fourni

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function enchant_broker_get_dict_path(EnchantBroker `$broker`, int `$type`): string|false

Récupère le chemin du dossier pour un backend fourni.

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().
`type`
  Le type des dictionnaires, c.-à-d. `ENCHANT_MYSPELL` ou `ENCHANT_ISPELL`.

### Valeurs de retour

Retourne le chemin du dossier du dictionnaire en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction a été dépréciée.
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.

### Notes

> Note: Cette fonction est seulement disponible si l'extension a été compilée avec Enchant v1.

### Voir aussi

- enchant_broker_set_dict_path() - Définit le chemin du dossier pour un backend fourni

# enchant_broker_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_get_error — Retourne la dernière erreur d'un sponsor

### Description

function enchant_broker_get_error(EnchantBroker `$broker`): string|false

Retourne la dernière erreur survenue pour ce sponsor.

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().

### Valeurs de retour

Retourne le message si une erreur a été trouvée, ou `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.

# enchant_broker_init

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_init — Crée un nouvel objet broker

### Description

function enchant_broker_init(): EnchantBroker|false

### Liste de paramètres

### Valeurs de retour

Retourne une ressource broker en cas de succès, `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de EnchantBroker ; auparavant une resource était retournée.

### Voir aussi

- enchant_broker_free() - Libère la ressource de sponsor ainsi que ses dictionnaires

# enchant_broker_list_dicts

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_list_dicts — Retourne une liste de tous les dictionnaires disponibles

### Description

function enchant_broker_list_dicts(EnchantBroker `$broker`): array

Retourne une liste de tous les dictionnaires disponibles ainsi que leurs détails.

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().

### Valeurs de retour

Retourne un tableau des dictionnaires disponibles avec leurs détails.

### Historique

Version | Description
--- | ---
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.
8.0.0 | Antérieur à cette version, la fonction retournait `false` en cas d'échec.

### Exemples

Exemple #1 Liste tous les dictionnaires disponibles pour un broker

    <?php
    $r = enchant_broker_init();
    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => Array
            (
                [lang_tag] => de
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [lang_tag] => de_DE
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [3] => Array
            (
                [lang_tag] => en
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [4] => Array
            (
                [lang_tag] => en_GB
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [5] => Array
            (
                [lang_tag] => en_US
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [6] => Array
            (
                [lang_tag] => hi_IN
                [provider_name] => myspell
                [provider_desc] => Myspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

### Voir aussi

- enchant_broker_describe() - Énumère les fournisseurs Enchant

# enchant_broker_request_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_dict — Crée un nouveau dictionnaire

### Description

function enchant_broker_request_dict(EnchantBroker `$broker`, string `$tag`): EnchantDictionary|false

Crée un nouveau dictionnaire en utilisant le paramètre `tag`, représentant la langue dont l'on veut associer le dictionnaire ("en_US", "de_DE", ...).

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().
`tag`
  Une balise décrivant la locale, par exemple, en_US, de_DE

### Valeurs de retour

Retourne une ressource de dictionnaire en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de EnchantDictionary ; auparavant une resource était retournée.

### Exemples

Exemple #1 Exemple avec enchant_broker_request_dict()

Vérifie si un dictionnaire existe en utilisant la fonction enchant_broker_dict_exists() et le demande.

    <?php
    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker,$tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        var_dump($dict);
    }
    ?>

### Voir aussi

- enchant_dict_describe() - Décrit un dictionnaire
- enchant_broker_dict_exists() - Vérifie si un dictionnaire existe
- enchant_broker_free_dict() - Libère une ressource de dictionnaire

# enchant_broker_request_pwl_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_pwl_dict — Crée un dictionnaire en utilisant un fichier PWL

### Description

function enchant_broker_request_pwl_dict(EnchantBroker `$broker`, string `$filename`): EnchantDictionary|false

Crée un dictionnaire en utilisant un fichier PWL. Un fichier PWL est un fichier de mots personnels contenant un mot par ligne.

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().
`filename`
  Chemin vers le fichier PWL. Si le fichier n'existe pas, un nouveau sera créé, si possible.

### Valeurs de retour

Retourne une ressource de dictionnaire en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de EnchantDictionary ; auparavant une resource était retournée.

### Voir aussi

- enchant_dict_describe() - Décrit un dictionnaire
- enchant_broker_dict_exists() - Vérifie si un dictionnaire existe
- enchant_broker_free_dict() - Libère une ressource de dictionnaire

# enchant_broker_set_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_set_dict_path — Définit le chemin du dossier pour un backend fourni

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function enchant_broker_set_dict_path(EnchantBroker `$broker`, int `$type`, string `$path`): bool

Définit le chemin du dossier pour un backend fourni.

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().
`type`
  Le type des dictionnaires, c.-à-d. `ENCHANT_MYSPELL` ou `ENCHANT_ISPELL`.
`path`
  Le chemin du dossier du dictionnaire.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction a été dépréciée.
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.

### Notes

> Note: Cette fonction est seulement disponible si l'extension a été compilée avec Enchant v1.

### Voir aussi

- enchant_broker_get_dict_path() - Récupère le chemin du dossier pour un backend fourni

# enchant_broker_set_ordering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_set_ordering — Déclare une préférence pour un dictionnaire d'une langue

### Description

function enchant_broker_set_ordering(EnchantBroker `$broker`, string `$tag`, string `$ordering`): bool

Déclare une préférence pour un dictionnaire à utiliser pour la langue spécifiée par le paramètre `tag`. L'ordre est une liste de noms de fournisseurs séparée par une virgule. Le caractère spécial "*" peut être utilisé comme langue pour déclarer un ordre par défaut pour toutes les langues qui ne déclarent pas explicitement un ordre.

### Liste de paramètres

`broker`
  Un courtier Enchant retourné par enchant_broker_init().
`tag`
  La langue. Le caractère "*" peut être utilisé en tant que langue pour déclarer un ordre par défaut pour toutes les langues qui ne déclarent pas explicitement un ordre.
`ordering`
  Liste de noms de fournisseurs séparée par une virgule

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `broker` attend désormais une instance de EnchantBroker ; auparavant, une resource était attendu.

# enchant_dict_add

(PHP 8)

enchant_dict_add — Ajoute un mot à une liste de mots personnelle

### Description

function enchant_dict_add(EnchantDictionary `$dictionary`, string `$word`): void

Ajoute un mot à la liste des mots personnelle du dictionnaire fourni.

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  Le mot à ajouter

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `dictionary` attend désormais une instance de EnchantDictionary ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Ajout d'un mot à un PWL

    <?php

    $filename = './my_word_list.pwl';
    $word = 'Supercalifragilisticexpialidocious';

    $broker = enchant_broker_init();
    $dict = enchant_broker_request_pwl_dict($broker, $filename);

    enchant_dict_add($dict, $word);

    ?>

### Voir aussi

- enchant_broker_request_pwl_dict() - Crée un dictionnaire en utilisant un fichier PWL
- enchant_broker_request_dict() - Crée un nouveau dictionnaire

# enchant_dict_add_to_personal

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_personal — Alias de enchant_dict_add()

Avertissement

Cet alias est OBSOLÈTE en PHP 8.0.0.

### Description

Cette fonction est un alias de : enchant_dict_add().

# enchant_dict_add_to_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_session — Ajoute un mot à la session courante

### Description

function enchant_dict_add_to_session(EnchantDictionary `$dictionary`, string `$word`): void

Ajoute le mot `word` au dictionnaire fourni. Il ne sera ajouté que pour la session courante.

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  Le mot à ajouter

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | `dictionary` attend désormais une instance de EnchantDictionary ; auparavant, une resource était attendu.

### Voir aussi

- enchant_broker_request_dict() - Crée un nouveau dictionnaire

# enchant_dict_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_check — Vérifie si un mot est correctement orthographié

### Description

function enchant_dict_check(EnchantDictionary `$dictionary`, string `$word`): bool

Retourne `true` si le mot `word` est correctement orthographié, `false` sinon.

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  Le mot à vérifier

### Valeurs de retour

Retourne `true` si le mot est correctement orthographié, `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0 | `dictionary` attend désormais une instance de EnchantDictionary ; auparavant, une resource était attendu.

# enchant_dict_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_describe — Décrit un dictionnaire

### Description

function enchant_dict_describe(EnchantDictionary `$dictionary`): array

Retourne les détails d'un dictionnaire.

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `dictionary` attend désormais une instance de EnchantDictionary ; auparavant, une resource était attendu.
8.0.0 | Antérieur à cette version, cette fonction retournait `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec enchant_dict_describe()

Vérifie si un dictionnaire existe en utilisant la fonction enchant_broker_dict_exists() et affiche tous les détails concernant ce dictionnaire.

    <?php
    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker, $tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        $dict_details = enchant_dict_describe($dict);
        print_r($dict_details);
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [lang] => en_US
        [name] => aspell
        [desc] => Aspell Provider
        [file] => /usr/lib/enchant/libenchant_aspell.so
    )

# enchant_dict_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_get_error — Retourne la dernière erreur de la session courante

### Description

function enchant_dict_get_error(EnchantDictionary `$dictionary`): string|false

Retourne la dernière erreur de la session courante.

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().

### Valeurs de retour

Retourne le message d'erreur sous la forme d'une chaîne de caractères, ou `false` si aucune erreur n'est survenue.

### Historique

Version | Description
--- | ---
8.0.0 | `dictionary` attend désormais une instance de EnchantDictionary ; auparavant, une resource était attendu.

# enchant_dict_is_added

(PHP 8)

enchant_dict_is_added — Que le 'mot' existe ou non dans cette session d'orthographe

### Description

function enchant_dict_is_added(EnchantDictionary `$dictionary`, string `$word`): bool

Informe si le mot existe déjà ou non dans la session courante.

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  Le mot à rechercher

### Valeurs de retour

Retourne `true` si le mot existe ou `false`

### Historique

Version | Description
--- | ---
8.0.0 | `dictionary` attend désormais une instance de EnchantDictionary ; auparavant, une resource était attendu.

### Voir aussi

- enchant_dict_add_to_session() - Ajoute un mot à la session courante

# enchant_dict_is_in_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_is_in_session — Alias de enchant_dict_is_added()

Avertissement

Cet alias est OBSOLÈTE en PHP 8.0.0.

### Description

Cette fonction est un alias de : enchant_dict_is_added().

# enchant_dict_quick_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant:0.2.0-1.0.1)

enchant_dict_quick_check — Vérifie si le mot est correctement orthographié et fournit des suggestions

### Description

function enchant_dict_quick_check(EnchantDictionary `$dictionary`, string `$word`, array `&$suggestions` = `null`): bool

Retourne `true` si le mot est correctement orthographié, `false` sinon ; si la variable des suggestions est fournie, elle est remplie des suggestions possibles.

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  Le mot à vérifier
`suggestions`
  Si le mot n'est pas correctement orthographié, cette variable contiendra un tableau de suggestions.

### Valeurs de retour

Retourne `true` si le mot est correctement orthographié, `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0 | `dictionary` attend désormais une instance de EnchantDictionary ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec enchant_dict_quick_check()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();

    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);
        enchant_dict_quick_check($d, 'soong', $suggs);
        print_r($suggs);
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => song
        [1] => snog
        [2] => soon
        [3] => Sang
        [4] => Sung
        [5] => sang
        [6] => sung
        [7] => sponge
        [8] => spongy
        [9] => snag
        [10] => snug
        [11] => sonic
        [12] => sing
        [13] => songs
        [14] => Son
        [15] => Sonja
        [16] => Synge
        [17] => son
        [18] => Sejong
        [19] => sarong
        [20] => sooner
        [21] => Sony
        [22] => sown
        [23] => scone
        [24] => song's
    )

### Voir aussi

- enchant_dict_check() - Vérifie si un mot est correctement orthographié
- enchant_dict_suggest() - Suggère des orthographes pour un mot

# enchant_dict_store_replacement

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_store_replacement — Ajoute une orthographe pour un mot

### Description

function enchant_dict_store_replacement(EnchantDictionary `$dictionary`, string `$misspelled`, string `$correct`): void

Ajoute une orthographe pour 'mis' en utilisant 'cor'. Il est à noter que si l'on remplace @mis par @cor, alors il est probable que les futures occurrences de @mis seront remplacées par @cor. Ainsi, @cor sera ajouté à la liste des suggestions.

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`misspelled`
  Le mot à traiter
`correct`
  Le mot correct

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `dictionary` attend désormais une instance de EnchantDictionary ; auparavant, une resource était attendu.

# enchant_dict_suggest

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_suggest — Suggère des orthographes pour un mot

### Description

function enchant_dict_suggest(EnchantDictionary `$dictionary`, string `$word`): array

### Liste de paramètres

`dictionary`
  Un dictionnaire Enchant retourné par enchant_broker_request_dict() ou enchant_broker_request_pwl_dict().
`word`
  Mot à utiliser pour les suggestions

### Valeurs de retour

Retourne un tableau de suggestions si le mot est mal orthographié.

### Historique

Version | Description
--- | ---
8.0.0 | `dictionary` attend désormais une instance de EnchantDictionary ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec enchant_dict_suggest()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);

        $wordcorrect = enchant_dict_check($d, "soong");
        if (!$wordcorrect) {
            $suggs = enchant_dict_suggest($d, "soong");
            echo "Suggestions pour 'soong' : ";
            print_r($suggs);
        }
    }
    ?>

### Voir aussi

- enchant_dict_check() - Vérifie si un mot est correctement orthographié
- enchant_dict_quick_check() - Vérifie si le mot est correctement orthographié et fournit des suggestions

## Sommaire

- enchant_broker_describe — Énumère les fournisseurs Enchant
- enchant_broker_dict_exists — Vérifie si un dictionnaire existe
- enchant_broker_free — Libère la ressource de sponsor ainsi que ses dictionnaires
- enchant_broker_free_dict — Libère une ressource de dictionnaire
- enchant_broker_get_dict_path — Récupère le chemin du dossier pour un backend fourni
- enchant_broker_get_error — Retourne la dernière erreur d'un sponsor
- enchant_broker_init — Crée un nouvel objet broker
- enchant_broker_list_dicts — Retourne une liste de tous les dictionnaires disponibles
- enchant_broker_request_dict — Crée un nouveau dictionnaire
- enchant_broker_request_pwl_dict — Crée un dictionnaire en utilisant un fichier PWL
- enchant_broker_set_dict_path — Définit le chemin du dossier pour un backend fourni
- enchant_broker_set_ordering — Déclare une préférence pour un dictionnaire d'une langue
- enchant_dict_add — Ajoute un mot à une liste de mots personnelle
- enchant_dict_add_to_personal — Alias de enchant_dict_add
- enchant_dict_add_to_session — Ajoute un mot à la session courante
- enchant_dict_check — Vérifie si un mot est correctement orthographié
- enchant_dict_describe — Décrit un dictionnaire
- enchant_dict_get_error — Retourne la dernière erreur de la session courante
- enchant_dict_is_added — Que le 'mot' existe ou non dans cette session d'orthographe
- enchant_dict_is_in_session — Alias de enchant_dict_is_added
- enchant_dict_quick_check — Vérifie si le mot est correctement orthographié et fournit des suggestions
- enchant_dict_store_replacement — Ajoute une orthographe pour un mot
- enchant_dict_suggest — Suggère des orthographes pour un mot

# La classe EnchantBroker

(PHP 8)

## Introduction

Une classe totalement opaque qui remplace les ressources `enchant_broker` à partir de PHP 8.0.0.

## Synopsis de la classe

final class EnchantBroker {
}

# La classe EnchantDictionary

(PHP 8)

## Introduction

Une classe totalement opaque qui remplace les ressources `enchant_dict` à partir de PHP 8.0.0.

## Synopsis de la classe

final class EnchantDictionary {
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Types de ressources
- Constantes pré-définies
- Exemples
- Fonctions Enchant
  - enchant_broker_describe — Énumère les fournisseurs Enchant
  - enchant_broker_dict_exists — Vérifie si un dictionnaire existe
  - enchant_broker_free — Libère la ressource de sponsor ainsi que ses dictionnaires
  - enchant_broker_free_dict — Libère une ressource de dictionnaire
  - enchant_broker_get_dict_path — Récupère le chemin du dossier pour un backend fourni
  - enchant_broker_get_error — Retourne la dernière erreur d'un sponsor
  - enchant_broker_init — Crée un nouvel objet broker
  - enchant_broker_list_dicts — Retourne une liste de tous les dictionnaires disponibles
  - enchant_broker_request_dict — Crée un nouveau dictionnaire
  - enchant_broker_request_pwl_dict — Crée un dictionnaire en utilisant un fichier PWL
  - enchant_broker_set_dict_path — Définit le chemin du dossier pour un backend fourni
  - enchant_broker_set_ordering — Déclare une préférence pour un dictionnaire d'une langue
  - enchant_dict_add — Ajoute un mot à une liste de mots personnelle
  - enchant_dict_add_to_personal — Alias de enchant_dict_add
  - enchant_dict_add_to_session — Ajoute un mot à la session courante
  - enchant_dict_check — Vérifie si un mot est correctement orthographié
  - enchant_dict_describe — Décrit un dictionnaire
  - enchant_dict_get_error — Retourne la dernière erreur de la session courante
  - enchant_dict_is_added — Que le 'mot' existe ou non dans cette session d'orthographe
  - enchant_dict_is_in_session — Alias de enchant_dict_is_added
  - enchant_dict_quick_check — Vérifie si le mot est correctement orthographié et fournit des suggestions
  - enchant_dict_store_replacement — Ajoute une orthographe pour un mot
  - enchant_dict_suggest — Suggère des orthographes pour un mot
- EnchantBroker — La classe EnchantBroker
- EnchantDictionary — La classe EnchantDictionary

# Détermine le sexe d'un prénom

# Introduction

L'extension PHP Gender est un port du programme gender.c originalement écrit par Joerg Michael. Le but premier de ce programme est de trouver le sexe d'un prénom. La base de données courante contient plus de 40000 prénoms de 54 pays.

# Installation/Configuration

## Sommaire

- Installation

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/gender.

# Exemples

## Sommaire

- Exemple d'utilisation

## Exemple d'utilisation

Exemple d'utilisation de la classe Gender.

Exemple #1 Exemple d'utilisation

    <?php

    namespace Gender;

    $gender = new Gender;

    $name = "Milene";
    $country = Gender::FRANCE;

    $result = $gender->get($name, $country);

    $data = $gender->country($country);

    switch($result) {
        case Gender::IS_FEMALE:
            printf("Le prénom %s est de sexe féminin pour le pays %s\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_FEMALE:
            printf("Le prénom %s est le plus souvent de sexe féminin pour le pays %s\n", $name, $data['country']);
        break;

        case Gender::IS_MALE:
            printf("Le prénom %s est de sexe masculin pour le pays %s\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_MALE:
            printf("Le prénom %s est le plus souvent de sexe masculin pour le pays %s\n", $name, $data['country']);
        break;

        case Gender::IS_UNISEX_NAME:
            printf("Le prénom %s est unisexe pour le pays %s\n", $name, $data['country']);
        break;

        case Gender::IS_A_COUPLE:
            printf("Le prénom %s est à la fois masculin et féminin pour le pays %s\n", $name, $data['country']);
        break;

        case Gender::NAME_NOT_FOUND:
            printf("Le prénom %s n'a pas été trouvé pour le pays %s\n", $name, $data['country']);
        break;

        case Gender::ERROR_IN_NAME:
            echo "Il y a une erreur dans le prénom fourni !\n";
        break;

        default:
            echo "Une erreur est survenue !\n";
        break;

    }

# La classe Gender\Gender

(PECL gender >= 0.6.0)

## Introduction

## Synopsis de la classe

class Gender\Gender {
/* Constantes */
const int IS_FEMALE = 70;
const int IS_MOSTLY_FEMALE = 102;
const int IS_MALE = 77;
const int IS_MOSTLY_MALE = 109;
const int IS_UNISEX_NAME = 63;
const int IS_A_COUPLE = 67;
const int NAME_NOT_FOUND = 32;
const int ERROR_IN_NAME = 69;
const int ANY_COUNTRY = 0;
const int BRITAIN = 1;
const int IRELAND = 2;
const int USA = 3;
const int SPAIN = 4;
const int PORTUGAL = 5;
const int ITALY = 6;
const int MALTA = 7;
const int FRANCE = 8;
const int BELGIUM = 9;
const int LUXEMBOURG = 10;
const int NETHERLANDS = 11;
const int GERMANY = 12;
const int EAST_FRISIA = 13;
const int AUSTRIA = 14;
const int SWISS = 15;
const int ICELAND = 16;
const int DENMARK = 17;
const int NORWAY = 18;
const int SWEDEN = 19;
const int FINLAND = 20;
const int ESTONIA = 21;
const int LATVIA = 22;
const int LITHUANIA = 23;
const int POLAND = 24;
const int CZECH_REP = 25;
const int SLOVAKIA = 26;
const int HUNGARY = 27;
const int ROMANIA = 28;
const int BULGARIA = 29;
const int BOSNIA = 30;
const int CROATIA = 31;
const int KOSOVO = 32;
const int MACEDONIA = 33;
const int MONTENEGRO = 34;
const int SERBIA = 35;
const int SLOVENIA = 36;
const int ALBANIA = 37;
const int GREECE = 38;
const int RUSSIA = 39;
const int BELARUS = 40;
const int MOLDOVA = 41;
const int UKRAINE = 42;
const int ARMENIA = 43;
const int AZERBAIJAN = 44;
const int GEORGIA = 45;
const int KAZAKH_UZBEK = 46;
const int TURKEY = 47;
const int ARABIA = 48;
const int ISRAEL = 49;
const int CHINA = 50;
const int INDIA = 51;
const int JAPAN = 52;
const int KOREA = 53;
/* Méthodes */
public function __construct(string `$dsn` = ?)
public function connect(string `$dsn`): bool
public function country(int `$country`): array|false
public function get(string `$name`, int `$country` = ?): int
public function isNick(string `$name0`, string `$name1`, int `$country` = ?): array
public function similarNames(string `$name`, int `$country` = ?): array
}

## Constantes pré-définies

`Gender\Gender::IS_FEMALE`
`Gender\Gender::IS_MOSTLY_FEMALE`
`Gender\Gender::IS_MALE`
`Gender\Gender::IS_MOSTLY_MALE`
`Gender\Gender::IS_UNISEX_NAME`
`Gender\Gender::IS_A_COUPLE`
`Gender\Gender::NAME_NOT_FOUND`
`Gender\Gender::ERROR_IN_NAME`
`Gender\Gender::ANY_COUNTRY`
`Gender\Gender::BRITAIN`
`Gender\Gender::IRELAND`
`Gender\Gender::USA`
`Gender\Gender::SPAIN`
`Gender\Gender::PORTUGAL`
`Gender\Gender::ITALY`
`Gender\Gender::MALTA`
`Gender\Gender::FRANCE`
`Gender\Gender::BELGIUM`
`Gender\Gender::LUXEMBOURG`
`Gender\Gender::NETHERLANDS`
`Gender\Gender::GERMANY`
`Gender\Gender::EAST_FRISIA`
`Gender\Gender::AUSTRIA`
`Gender\Gender::SWISS`
`Gender\Gender::ICELAND`
`Gender\Gender::DENMARK`
`Gender\Gender::NORWAY`
`Gender\Gender::SWEDEN`
`Gender\Gender::FINLAND`
`Gender\Gender::ESTONIA`
`Gender\Gender::LATVIA`
`Gender\Gender::LITHUANIA`
`Gender\Gender::POLAND`
`Gender\Gender::CZECH_REP`
`Gender\Gender::SLOVAKIA`
`Gender\Gender::HUNGARY`
`Gender\Gender::ROMANIA`
`Gender\Gender::BULGARIA`
`Gender\Gender::BOSNIA`
`Gender\Gender::CROATIA`
`Gender\Gender::KOSOVO`
`Gender\Gender::MACEDONIA`
`Gender\Gender::MONTENEGRO`
`Gender\Gender::SERBIA`
`Gender\Gender::SLOVENIA`
`Gender\Gender::ALBANIA`
`Gender\Gender::GREECE`
`Gender\Gender::RUSSIA`
`Gender\Gender::BELARUS`
`Gender\Gender::MOLDOVA`
`Gender\Gender::UKRAINE`
`Gender\Gender::ARMENIA`
`Gender\Gender::AZERBAIJAN`
`Gender\Gender::GEORGIA`
`Gender\Gender::KAZAKH_UZBEK`
`Gender\Gender::TURKEY`
`Gender\Gender::ARABIA`
`Gender\Gender::ISRAEL`
`Gender\Gender::CHINA`
`Gender\Gender::INDIA`
`Gender\Gender::JAPAN`
`Gender\Gender::KOREA`

# Gender\Gender::connect

(PECL gender >= 0.6.0)

Gender\Gender::connect — Connexion à un dictionnaire externe

### Description

public function Gender\Gender::connect(string `$dsn`): bool

Connexion à un dictionnaire externe. Actuellement, seuls les flux sont supportés.

### Liste de paramètres

`dsn`
  DSN à ouvrir.

### Valeurs de retour

Un booléen en cas de succès ou d'échec.

# Gender\Gender::__construct

(PECL gender >= 0.6.0)

Gender\Gender::__construct — Construit un objet Gender

### Description

public function Gender\Gender::__construct(string `$dsn` = ?)

Crée un objet Gender, en se connectant, optionnellement, à un dictionnaire externe. Lorsqu'aucune base de données n'est fournie, les données compilées en interne seront utilisées.

### Liste de paramètres

`dsn`
  DSN à ouvrir.

# Gender\Gender::country

(PECL gender >= 0.8.0)

Gender\Gender::country — Récupère la représentation textuelle d'un pays

### Description

public function Gender\Gender::country(int `$country`): array|false

Récupère la représentation textuelle d'un pays depuis la constante de la classe Gender.

### Liste de paramètres

`country`
  Identifiant du pays (correspond à une constante de la classe Gender\Gender).

### Valeurs de retour

Retourne un tableau contenant les noms courts et longs du pays en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec Gender\Gender::country()

    $gender = new Gender\Gender;
    var_dump($gender->country(Gender\Gender::BRITAIN));

L'exemple ci-dessus va afficher :

    array(2) {
      'country_short' =>
      string(2) "UK"
      'country' =>
      string(13) "Great Britain"
    }

# Gender\Gender::get

(PECL gender >= 0.6.0)

Gender\Gender::get — Récupère le sexe d'un prénom

### Description

public function Gender\Gender::get(string `$name`, int `$country` = ?): int

Récupère le sexe d'un prénom pour un pays spécifique.

### Liste de paramètres

`name`
  Le prénom à vérifier.
`country`
  L'identifiant du pays (une constante de la classe Gender).

### Valeurs de retour

Retourne le sexe du prénom.

# Gender\Gender::isNick

(PECL gender >= 0.9.0)

Gender\Gender::isNick — Vérifie si name0 est un alias de name1

### Description

public function Gender\Gender::isNick(string `$name0`, string `$name1`, int `$country` = ?): array

Vérifie si name0 est un alias de name1.

### Liste de paramètres

`name0`
  Nom à vérifier.
`name1`
  Nom à vérifier.
`country`
  Identifiant du pays, identifié par la constante de la classe Gender. Si omis, ANY_COUNTRY sera utilisé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# Gender\Gender::similarNames

(PECL gender >= 0.9.0)

Gender\Gender::similarNames — Récupère des noms similaires

### Description

public function Gender\Gender::similarNames(string `$name`, int `$country` = ?): array

Récupère des noms similaires pour le nom et le pays fourni.

### Liste de paramètres

`name`
  Nom à vérifier.
`country`
  Identifiant du pays, identifié par la constante de classe Gender. Si omis, ANY_COUNTRY sera utilisé.

### Valeurs de retour

Retourne un tableau contenant les noms similaires trouvés.

## Sommaire

- Gender\Gender::connect — Connexion à un dictionnaire externe
- Gender\Gender::__construct — Construit un objet Gender
- Gender\Gender::country — Récupère la représentation textuelle d'un pays
- Gender\Gender::get — Récupère le sexe d'un prénom
- Gender\Gender::isNick — Vérifie si name0 est un alias de name1
- Gender\Gender::similarNames — Récupère des noms similaires

- Installation/Configuration
  - Installation
- Exemples
  - Exemple d'utilisation
- Gender\Gender — La classe Gender\Gender
  - Gender\Gender::connect — Connexion à un dictionnaire externe
  - Gender\Gender::__construct — Construit un objet Gender
  - Gender\Gender::country — Récupère la représentation textuelle d'un pays
  - Gender\Gender::get — Récupère le sexe d'un prénom
  - Gender\Gender::isNick — Vérifie si name0 est un alias de name1
  - Gender\Gender::similarNames — Récupère des noms similaires

# Gettext

# Introduction

Les fonctions gettext implémentent l'API NLS (`Native Language Support`) qui peut servir à internationaliser les scripts PHP. Se référer à la documentation GNU sur le site » http://www.gnu.org/software/gettext/manual/gettext.html, ou bien sur le système pour plus d'explications sur ces fonctions.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Pour utiliser ces fonctions, il faut télécharger et installer les bibliothèques GNU gettext depuis » http://www.gnu.org/software/gettext/gettext.html.

## Installation

Pour inclure le module GNU gettext dans PHP, il faut le compiler avec l'option --with-gettext[=DIR], où DIR est le dossier d'installation de gettext. Par défaut, c'est /usr/local.

# Fonctions Gettext

# _

(PHP 4, PHP 5, PHP 7, PHP 8)

_ — Alias de gettext()

### Description

Cette fonction est un alias de : gettext().

# bind_textdomain_codeset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

bind_textdomain_codeset — Spécifie ou récupère le jeu de caractères utilisé pour les messages du domaine DOMAIN

### Description

function bind_textdomain_codeset(string `$domain`, ?string `$codeset` = `null`): string|false

bind_textdomain_codeset() permet de récupérer ou définir l'encodage dans lequel les messages de `domain` seront retournés par gettext() et fonctions similaires.

### Liste de paramètres

`domain`

  Le domaine.

`codeset`

  Le jeu de caractères. Si `null`, l'encodage actuellement défini est retourné.

### Valeurs de retour

Une chaîne de caractères en cas de succès.

### Erreurs / Exceptions

Lève une ValueError si `domain` est une string vide.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `domain` est une string vide.
8.4.0 | `codeset` est désormais optionnel. Auparavant, ce paramètre devait toujours être spécifié.
8.0.3 | `codeset` est désormais nullable. Auparavant, il n'était pas possible de récupérer l'encodage actuellement défini.

### Notes

> Note:

> L'information bind_textdomain_codeset() est maintenue par process, et non par thread.

# bindtextdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

bindtextdomain — Spécifie ou récupère le chemin d'un domaine

### Description

function bindtextdomain(string `$domain`, ?string `$directory` = `null`): string|false

La fonction bindtextdomain() définit ou récupère le chemin d'un domaine.

### Liste de paramètres

`domain`

  Le domaine.

`directory`

  Le chemin vers le dossier. Une chaîne vide signifie le dossier courant. Si `null`, le dossier actuellement défini est retourné.

### Valeurs de retour

Le chemin complet pour le `domain` actuellement défini, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | `directory` est désormais facultatif. Auparavant, ce paramètre devait toujours être spécifié.
8.0.3 | `directory` est désormais nullable. Auparavant, il n'était pas possible de récupérer le dossier actuellement défini.

### Exemples

Exemple #1 Exemple avec bindtextdomain()

    <?php

    $domain = 'myapp';
    echo bindtextdomain($domain, '/usr/share/myapp/locale');

    ?>

L'exemple ci-dessus va afficher :

    /usr/share/myapp/locale

### Notes

> Note:

> L'information bindtextdomain() est maintenue par process, et non par thread.

# dcgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dcgettext — Remplace le domaine lors d'une recherche

### Description

function dcgettext(string `$domain`, string `$message`, int `$category`): string

Permet de remplacer le domaine courant lors de la recherche d'un message.

### Liste de paramètres

`domain`

  Le domaine

`message`

  Le message

`category`

  La catégorie

### Valeurs de retour

Une chaîne de caractères en cas de succès.

### Voir aussi

- gettext() - Recherche un message dans le domaine courant

# dcngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dcngettext — Version plurielle de dcgettext

### Description

function dcngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`,
int `$category`
): string

Permet de remplacer le domaine courant pour une recherche simple au pluriel d'un message.

### Liste de paramètres

`domain`

  Le domaine

`singular`

`plural`

`count`

`category`

### Valeurs de retour

Une chaîne de caractères en cas de succès.

### Voir aussi

- ngettext() - Version plurielle de gettext

# dgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dgettext — Remplace le domaine courant

### Description

function dgettext(string `$domain`, string `$message`): string

dgettext() remplace le domaine courant `domain` pour une recherche simple dans `message`.

### Liste de paramètres

`domain`

  Le domaine

`message`

  Le message

### Valeurs de retour

Une chaîne de caractères en cas de succès.

### Erreurs / Exceptions

Lève une ValueError si `domain` est une string vide.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `domain` est une string vide.

### Voir aussi

- gettext() - Recherche un message dans le domaine courant

# dngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dngettext — Version plurielle de dgettext

### Description

function dngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`
): string

dngettext() permet de remplacer le domaine courant `domain` pour une recherche simple au pluriel d'un message.

### Liste de paramètres

`domain`

  Le domaine

`singular`

`plural`

`count`

### Valeurs de retour

Une chaîne de caractères en cas de succès.

### Erreurs / Exceptions

Lève une ValueError si `domain` est une string vide.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `domain` est une string vide.

### Voir aussi

- ngettext() - Version plurielle de gettext

# gettext

(PHP 4, PHP 5, PHP 7, PHP 8)

gettext — Recherche un message dans le domaine courant

### Description

function gettext(string `$message`): string

Recherche un message dans le domaine courant.

### Liste de paramètres

`message`

  Le message à traduire.

### Valeurs de retour

Retourne une chaîne traduite, si elle en a trouvé une dans la table de traduction, ou bien le message `message`, s'il n'a pas été trouvé.

### Exemples

Exemple #1 Exemple avec gettext()

    <?php
    // Choix de l'allemand
    putenv('LC_ALL=de_DE');
    setlocale(LC_ALL, 'de_DE');

    // Spécifie la localisation des tables de traduction
    bindtextdomain("myPHPApp", "./locale");

    // Choisit le domaine
    textdomain("myPHPApp");

    // La traduction est cherchée dans ./locale/de_DE/LC_MESSAGES/myPHPApp.mo

    // Affichage d'un message de test
    echo gettext("Bienvenue dans mon application PHP");

    // Ou utiliser l'alias _() pour remplacer gettext()
    echo _("Passez une bonne journée");
    ?>

### Notes

> Note:

> Il est possible d'utiliser le caractère souligné (_) comme alias de cette fonction.

> Note:

> Le fait de définir une langue n'est pas suffisant pour certains systèmes d'exploitation et l'utilisation de la fonction putenv() est nécessaire afin de définir la locale courante.

### Voir aussi

- _() - Alias de gettext
- setlocale() - Modifie les informations de localisation

# ngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ngettext — Version plurielle de gettext

### Description

function ngettext(string `$singular`, string `$plural`, int `$count`): string

Version plurielle de gettext(). Quelques langues ont plus d'une forme de messages pluriels dépendant du compteur.

### Liste de paramètres

`singular`

  L'ID singulier du message.

`plural`

  L'ID pluriel du message.

`count`

  Le nombre (c.-à-d. nombre d'éléments) pour déterminer la traduction du nombre grammatical respectif.

### Valeurs de retour

Retourne la forme plurielle correcte du message identifié par `singular` et `plural` pour le compteur `count`.

### Exemples

Exemple #1 Exemple avec ngettext()

    <?php

    setlocale(LC_ALL, 'cs_CZ');
    printf(ngettext("%d window", "%d windows", 1), 1); // 1 okno
    printf(ngettext("%d window", "%d windows", 2), 2); // 2 okna
    printf(ngettext("%d window", "%d windows", 5), 5); // 5 oken

    ?>

# textdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

textdomain — Définit le domaine par défaut

### Description

function textdomain(?string `$domain` = `null`): string

Cette fonction définit le domaine de recherche à utiliser lorsque des appels à gettext() sont effectués. Ce domaine dépend généralement de l'application.

### Liste de paramètres

`domain`

  Le nouveau domaine des messages, ou `null` pour récupérer la configuration courante sans la modifier.

### Valeurs de retour

Cette fonction retourne le domaine de messages courant en cas de succès, après une éventuelle modification.

### Erreurs / Exceptions

Lève une ValueError si `domain` est une string vide.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `domain` est une string vide.
8.4.0 | `domain` est désormais facultatif. Auparavant, ce paramètre devait toujours être spécifié.

### Notes

> Note:

> L'information textdomain() est maintenue par process, et non par thread.

## Sommaire

- _ — Alias de gettext
- bind_textdomain_codeset — Spécifie ou récupère le jeu de caractères utilisé pour les messages du domaine DOMAIN
- bindtextdomain — Spécifie ou récupère le chemin d'un domaine
- dcgettext — Remplace le domaine lors d'une recherche
- dcngettext — Version plurielle de dcgettext
- dgettext — Remplace le domaine courant
- dngettext — Version plurielle de dgettext
- gettext — Recherche un message dans le domaine courant
- ngettext — Version plurielle de gettext
- textdomain — Définit le domaine par défaut

- Installation/Configuration
  - Pré-requis
  - Installation
- Fonctions Gettext
  - _ — Alias de gettext
  - bind_textdomain_codeset — Spécifie ou récupère le jeu de caractères utilisé pour les messages du domaine DOMAIN
  - bindtextdomain — Spécifie ou récupère le chemin d'un domaine
  - dcgettext — Remplace le domaine lors d'une recherche
  - dcngettext — Version plurielle de dcgettext
  - dgettext — Remplace le domaine courant
  - dngettext — Version plurielle de dgettext
  - gettext — Recherche un message dans le domaine courant
  - ngettext — Version plurielle de gettext
  - textdomain — Définit le domaine par défaut

# iconv

# Introduction

Ce module contient une interface vers la fonctionnalité de conversion de jeux de caractères iconv. Avec ce module, il est possible de transformer une chaîne représentée dans un jeu de caractères local en une chaîne représentée dans un autre jeu de caractères, qui peut être le jeu de caractères Unicode. Les jeux de caractères supportés dépendent de l'implémentation iconv du système. Il est à noter que la fonction iconv sur certains systèmes peut ne pas fonctionner comme prévu. Dans ce cas, ce serait une bonne idée d'installer la bibliothèque » GNU libiconv. Elle aboutira très probablement à des résultats plus cohérents.

Cette extension est fournie avec diverses fonctions utilitaires qui aident à écrire des scripts multilingues. Les sections suivantes présentent les nouvelles fonctionnalités.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

Il n'est besoin de rien de spécial si le système est conforme au standard POSIX, car la bibliothèque standard C fournit iconv. Dans le cas contraire, il faut installer la bibliothèque » libiconv sur le système.

## Installation

Cette extension est activée par défaut, cependant, elle peut être désactivée en compilant PHP avec l'option --without-iconv.

La directive optionnelle --with-iconv[=DIR] est utilisée pour spécifier l'emplacement de iconv sur le système sur lequel PHP est compilé. Si cette directive n'est pas spécifiée, seuls les emplacements par défaut seront parcourus.

## Configuration à l'exécution

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

Options de configuration iconv
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
iconv.input_encoding | "" | `INI_ALL` | Obsolète en PHP 5.6.0.
iconv.output_encoding | "" | `INI_ALL` | Obsolète en PHP 5.6.0.
iconv.internal_encoding | "" | `INI_ALL` | Obsolète en PHP 5.6.0.

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

Avertissement

Quelques systèmes (comme IBM AIX) utilisent `"ISO8859-1"` au lieu de `"ISO-8859-1"`, cette valeur doit donc être utilisée dans les options de configuration ainsi que dans les paramètres des fonctions.

`iconv.input_encoding` string
  Avertissement

  Cette fonctionnalité est OBSOLÈTE à partir de PHP 5.6.0. Dépendre de cette fonctionnalité est fortement déconseillé.

  Les utilisateurs de PHP 5.6 et suivants doivent laisser cette option vide et définir plutôt l'option input_encoding.

`iconv.output_encoding` string
  Avertissement

  Cette fonctionnalité est OBSOLÈTE à partir de PHP 5.6.0. Dépendre de cette fonctionnalité est fortement déconseillé.

  Les utilisateurs de PHP 5.6 et suivants doivent laisser cette option vide et définir plutôt l'option output_encoding.

`iconv.internal_encoding` string
  Avertissement

  Cette fonctionnalité est OBSOLÈTE à partir de PHP 5.6.0. Dépendre de cette fonctionnalité est fortement déconseillé.

  Les utilisateurs de PHP 5.6 et suivants doivent laisser cette option vide et définir plutôt l'option `default_charset`.

# Constantes pré-définies

Il est possible d'identifier durant l'exécution, la version de la bibliothèque iconv que l'on utilise.

Constantes d'implémentation `iconv`
Constante | Type | Description
--- | --- | ---
`ICONV_IMPL` (string) | string | Le nom de la bibliothèque
`ICONV_VERSION` (string) | string | La version de la bibliothèque

> Note:

> La programmation de scripts dépendant de versions spécifiques, avec ces constantes, est fortement déconseillée.

Les constantes suivantes sont également disponibles :

Autres constantes `iconv`
Constante | Type | Description
--- | --- | ---
`ICONV_MIME_DECODE_STRICT` (int) | int | Un masque utilisé pour iconv_mime_decode()
`ICONV_MIME_DECODE_CONTINUE_ON_ERROR` (int) | int | Un masque utilisé pour iconv_mime_decode()

# Fonctions iconv

# Voir aussi

Voir aussi les fonctions GNU Recode.

# iconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv — Convertit une chaîne de caractères à partir d'un encodage vers un autre

### Description

function iconv(string `$from_encoding`, string `$to_encoding`, string `$string`): string|false

Convertit la chaîne `string` à partir de `from_encoding` vers l'encodage `to_encoding`.

### Liste de paramètres

`from_encoding`

  L'encodage actuellement utilisé pour interpréter `string`.

`to_encoding`

  L'encodage souhaité du résultat.

  Si la chaîne `//TRANSLIT` est ajoutée au paramètre `to_encoding`, alors la translittération est activée. Cela signifie que lorsqu'un caractère ne peut être représenté dans le jeu de caractères cible, il peut être approché par un ou plusieurs caractères d'apparence similaire. Si la chaîne `//IGNORE` est ajoutée, les caractères ne pouvant être représentés dans le jeu de caractères cible seront silencieusement ignorés. Sinon, une `E_NOTICE` sera générée et la fonction retournera `false`.

  Attention

  Si et comment `//TRANSLIT` fonctionne exactement dépend de l'implémentation iconv() du système (cf. `ICONV_IMPL`). Certaines implémentations sont connues pour ignorer `//TRANSLIT`, donc la conversion de caractères illégaux échouera probablement pour `to_encoding`.

`string`

  La chaîne de caractères à convertir.

### Valeurs de retour

Retourne la chaîne de caractères convertie, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec iconv()

    <?php
    $text = "Ceci est le symbole de l'Euro '€'.";

    echo 'Original : ', $text, PHP_EOL;
    echo 'TRANSLIT : ', iconv("UTF-8", "ISO-8859-1//TRANSLIT", $text), PHP_EOL;
    echo 'IGNORE   : ', iconv("UTF-8", "ISO-8859-1//IGNORE", $text), PHP_EOL;
    echo 'Brut     : ', iconv("UTF-8", "ISO-8859-1", $text), PHP_EOL;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Original : Ceci est le symbole de l'Euro '€'.
    TRANSLIT : Ceci est le symbole de l'Euro 'EUR'.
    IGNORE   : Ceci est le symbole de l'Euro ''.
    Brut     :
    Notice: iconv(): Detected an illegal character in input string in .\iconv-example.php on line 7

### Notes

> Note:

> L'encodage de caractères et les options disponibles dépendent de l'implémentation d'iconv. Si l'argument de `from_encoding` ou `to_encoding` n'est pas pris en charge sur le système actuel, `false` sera retourné.

### Voir aussi

- mb_convert_encoding() - Convertir une chaîne d'un codage de caractères à un autre
- UConverter::transcode() - Convertit une chaîne d'un jeu de caractères à un autre

# iconv_get_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_get_encoding — Récupère les variables de configuration interne de l'extension iconv

### Description

function iconv_get_encoding(string `$type` = "all"): array|string|false

Récupère les variables de configuration interne de l'extension iconv.

### Liste de paramètres

`type`

  Les valeurs possibles pour le paramètre optionnel `type` sont :

  - all
  - input_encoding
  - output_encoding
  - internal_encoding

### Valeurs de retour

Retourne la valeur courante de la variable de configuration en cas de succès ou `false` si une erreur survient.

Si `type` est omis ou défini à `all`, iconv_get_encoding() retourne un tableau contenant toutes les valeurs de ces variables.

### Exemples

Exemple #1 Exemple avec iconv_get_encoding()

    <pre>
    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    var_dump(iconv_get_encoding('all'));
    ?>
    </pre>

L'exemple ci-dessus va afficher :

    Array
    (
        [input_encoding] => ISO-8859-1
        [output_encoding] => ISO-8859-1
        [internal_encoding] => UTF-8
    )

### Voir aussi

- iconv_set_encoding() - Modifie le réglage courant pour la conversion d'encodage de caractères
- ob_iconv_handler() - Gestionnaire de sortie pour maîtriser le jeu de caractères de sortie

# iconv_mime_decode

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode — Décode un champ d'en-tête `MIME`

### Description

function iconv_mime_decode(string `$string`, int `$mode` = 0, ?string `$encoding` = `null`): string|false

Décode un champ d'en-tête `MIME`.

### Liste de paramètres

`string`

  L'en-tête encodé, sous la forme d'une chaîne de caractères.

`mode`

  `mode` détermine le comportement dans le cas où iconv_mime_decode() rencontre un champ d'en-tête `MIME` mal formé. Il est possible de spécifier toute combinaison des masques de bits suivants.

  Masques de bits acceptables par iconv_mime_decode()
  Valeur | Constante | Description
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | Si défini, l'en-tête fourni est décodé en pleine conformité avec les standards définis dans la » RFC2047. Cette option est désactivée par défaut, car il existe beaucoup de clients de courriel défectueux qui ne suivent pas la spécification et ne produisent pas d'en-têtes `MIME` corrects.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | Si défini, iconv_mime_decode_headers() tente d'ignorer toute erreur grammaticale et de continuer à traiter un en-tête fourni.

`encoding`

  Le paramètre optionnel `encoding` spécifie le jeu de caractères à utiliser pour représenter le résultat. S'il est omis ou vaut `null`, iconv.internal_encoding sera utilisé.

### Valeurs de retour

Retourne un champ `MIME` décodé en cas de succès, ou `false` si une erreur survient durant le décodage.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Exemple avec iconv_mime_decode()

    <?php
    // Ceci produit : "Subject: Prüfung Prüfung"
    echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
                           0, "ISO-8859-1");
    ?>

### Voir aussi

- iconv_mime_decode_headers() - Décode des en-têtes MIME multiples
- mb_decode_mimeheader() - Décode un en-tête MIME
- imap_mime_header_decode() - Décode les éléments MIME d'un en-tête
- imap_base64() - Décode un texte encodé en BASE64
- imap_qprint() - Convertit une chaîne à guillemets en une chaîne à 8 bits

# iconv_mime_decode_headers

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode_headers — Décode des en-têtes `MIME` multiples

### Description

function iconv_mime_decode_headers(string `$headers`, int `$mode` = 0, ?string `$encoding` = `null`): array|false

iconv_mime_decode_headers() décode les en-têtes `MIME` multiples.

### Liste de paramètres

`headers`

  Les en-têtes encodés, sous la forme d'une chaîne de caractères.

`mode`

  `mode` détermine le comportement de la fonction, si iconv_mime_decode_headers() rencontre un en-tête `MIME` malformé. Il est possible de spécifier toute combinaison des masques suivants.

  Masques acceptés par la fonction iconv_mime_decode_headers()
  Valeur | Constante | Description
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | Si activée, l'en-tête fourni est décodé en respectant scrupuleusement le standard défini dans la » RFC2047. Cette option est désactivée par défaut, car il existe de nombreux clients mail défectueux qui ne suivent pas la spécification et qui ne produisent pas d'en-têtes `MIME` corrects.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | Si cette option est activée, iconv_mime_decode_headers() tente d'ignorer les erreurs de syntaxe et continue de traiter l'en-tête donné.

`encoding`

  Le paramètre optionnel `encoding` spécifie le jeu de caractères utilisé pour représenter le résultat. S'il est omis ou `null`, iconv.internal_encoding sera utilisé.

### Valeurs de retour

Retourne un tableau associatif qui contient l'ensemble des en-têtes `MIME` spécifiés par le paramètre `headers` en cas de succès, ou bien `false` si une erreur survient durant le décodage.

Chaque clé du tableau retourné contient un nom d'en-tête distinct, et sa valeur correspondante. Si plusieurs champs ont le même nom, iconv_mime_decode_headers() fera de ce champ un tableau indexé, avec les valeurs dans leur ordre d'apparence. Il est à noter que les noms d'en-têtes ne sont pas insensibles à la casse.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Exemple avec iconv_mime_decode_headers()

    <?php
    $headers_string = <<<EOF
    Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=
    To: example@example.com
    Date: Thu, 1 Jan 1970 00:00:00 +0000
    Message-Id: <example@example.com>
    Received: from localhost (localhost [127.0.0.1]) by localhost
        with SMTP id example for <example@example.com>;
        Thu, 1 Jan 1970 00:00:00 +0000 (UTC)
        (envelope-from example-return-0000-example=example.com@example.com)
    Received: (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000

    EOF;

    $headers =  iconv_mime_decode_headers($headers_string, 0, "ISO-8859-1");
    print_r($headers);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [Subject] => Prüfung Prüfung
        [To] => example@example.com
        [Date] => Thu, 1 Jan 1970 00:00:00 +0000
        [Message-Id] => <example@example.com>
        [Received] => Array
            (
                [0] => from localhost (localhost [127.0.0.1]) by localhost with SMTP id example for <example@example.com>; Thu, 1 Jan 1970 00:00:00 +0000 (UTC) (envelope-from example-return-0000-example=example.com@example.com)
                [1] => (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
            )

    )

### Voir aussi

- iconv_mime_decode() - Décode un champ d'en-tête MIME
- mb_decode_mimeheader() - Décode un en-tête MIME
- imap_mime_header_decode() - Décode les éléments MIME d'un en-tête
- imap_base64() - Décode un texte encodé en BASE64
- imap_qprint() - Convertit une chaîne à guillemets en une chaîne à 8 bits

# iconv_mime_encode

(PHP 5, PHP 7, PHP 8)

iconv_mime_encode — Construit un en-tête MIME avec les champs field_name et field_value

### Description

function iconv_mime_encode(string `$field_name`, string `$field_value`, array `$options` = []): string|false

iconv_mime_encode() compose et retourne une chaîne de caractères qui représente un champ en-tête `MIME` qui ressemble à :

    Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile

Dans l'exemple ci-dessus, `"Subject"` est le nom du champ et la portion qui commence par `"=?ISO-8859-1?..."` est la valeur du champ.

### Liste de paramètres

`field_name`

  Le nom du champ.

`field_value`

  La valeur du champ.

`options`

  Il est possible de contrôler le comportement de la fonction iconv_mime_encode() en spécifiant un tableau associatif contenant la configuration des éléments dans le paramètre `options`. La liste des éléments supportés par iconv_mime_encode() figure ci-dessous. Il est à noter que les noms des éléments sont sensibles à la casse.

  Liste des éléments supportés par iconv_mime_encode()
  Élément | Type | Description | Valeur par défaut | Exemple
  --- | --- | --- | --- | ---
  scheme | string | Spécifie la méthode d'encodage d'un champ. Les valeurs possibles sont `"B"` ou `"Q"`, où `"B"` signifie que le schéma d'encodage sera `base64` et `"Q"`, `quoted-printable`. | B | B
  input-charset | string | Spécifie le jeu de caractères pour représenter le premier paramètre `field_name` et le second paramètre `field_value`. S'il est omis, iconv_mime_encode() utilisera la directive de configuration iconv.internal_encoding du php.ini pour les représenter. | iconv.internal_encoding | ISO-8859-1
  output-charset | string | Spécifie le jeu de caractères à utiliser pour composer l'en-tête `MIME`. | iconv.internal_encoding | UTF-8
  line-length | int | Spécifie la longueur maximale de chaque en-tête. Si l'en-tête est plus grand que la longueur définie par ce paramètre, l'en-tête résultant sera un en-tête composé de plusieurs lignes conformément au standard » RFC2822 - Internet Message Format. S'il est omis, la longueur maximale sera fixée à 76 caractères. | 76 | 996
  line-break-chars | string | Spécifie les caractères de fin de ligne. S'il est omis, la valeur par défaut sera `"\r\n"` (`CR` `LF`). Il est à noter que ce paramètre est toujours représenté comme une chaîne ASCII au regard de la valeur du paramètre `input-charset`. | \r\n | \n

### Valeurs de retour

Retourne un champ `MIME` en cas de succès, ou `false` si une erreur survient durant l'encodage.

### Exemples

Exemple #1 Exemple avec iconv_mime_encode()

    <?php
    $preferences = array(
        "input-charset" => "ISO-8859-1",
        "output-charset" => "UTF-8",
        "line-length" => 76,
        "line-break-chars" => "\n"
    );
    $preferences["scheme"] = "Q";
    // Ceci donne : "Subject: =?UTF-8?Q?Pr=C3=BCfung=20Pr=C3=BCfung?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);

    $preferences["scheme"] = "B";
    // Ceci donne : "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);
    ?>

### Voir aussi

- imap_binary() - Convertit une chaîne à 8 bits en une chaîne à base64
- mb_encode_mimeheader() - Encode une chaîne pour un en-tête MIME
- imap_8bit() - Convertit une chaîne à 8 bits en une chaîne encodée en Quoted-Printable
- quoted_printable_encode() - Convertit une chaîne 8 bits en une chaîne quoted-printable

# iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_set_encoding — Modifie le réglage courant pour la conversion d'encodage de caractères

### Description

function iconv_set_encoding(string `$type`, string `$encoding`): bool

Modifie la valeur de la variable de configuration interne spécifiée par `type` vers `encoding`.

### Liste de paramètres

`type`

  La valeur de `type` peut être l'une des suivantes :

  - input_encoding
  - output_encoding
  - internal_encoding
`encoding`

  Le jeu de caractères.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec iconv_set_encoding()

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ?>

### Voir aussi

- iconv_get_encoding() - Récupère les variables de configuration interne de l'extension iconv
- ob_iconv_handler() - Gestionnaire de sortie pour maîtriser le jeu de caractères de sortie

# iconv_strlen

(PHP 5, PHP 7, PHP 8)

iconv_strlen — Retourne le nombre de caractères d'une chaîne

### Description

function iconv_strlen(string `$string`, ?string `$encoding` = `null`): int|false

À l'opposé de strlen(), iconv_strlen() compte les occurrences des caractères présents dans la séquence d'octets `string` en se basant sur le jeu de caractères spécifié, ce qui n'est pas nécessairement identique à la longueur de la chaîne en octets.

### Liste de paramètres

`string`

  La chaîne de caractères.

`encoding`

  Si `encoding` est omis ou `null`, `string` est supposée être encodée en iconv.internal_encoding.

### Valeurs de retour

Retourne le nombre de caractères de la chaîne `string`, sous la forme d'un entier, ou `false` si une erreur se produit durant l'encodage.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- grapheme_strlen() - Lit la taille d'une chaîne en nombre de graphème
- mb_strlen() - Retourne la taille d'une chaîne
- strlen() - Calcule la taille d'une chaîne

# iconv_strpos

(PHP 5, PHP 7, PHP 8)

iconv_strpos — Trouve la position de la première occurrence d'une chaîne dans une autre

### Description

function iconv_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Trouve la position de la première occurrence de `needle` dans `haystack`.

À l'opposé de strpos(), la valeur retournée par iconv_strpos() est le nombre de caractères se trouvant avant `needle`, plutôt que la position en octets où `needle` a été trouvé. Les caractères sont comptés en se basant sur le jeu de caractères spécifié par `encoding`.

### Liste de paramètres

`haystack`

  La chaîne de caractères entière.

`needle`

  La chaîne de caractères à chercher.

`offset`

  Le paramètre optionnel `offset` spécifie la position à partir de laquelle la recherche doit commencer. Si la position est négative, elle est comptée depuis la fin de la chaîne de caractères.

`encoding`

  Si le paramètre `encoding` est omis ou `null`, `string` sera encodé en accord avec iconv.internal_encoding.

Si `haystack` ou `needle` ne sont pas des chaînes de caractères, ils sont convertis en entiers et appliqués en tant que valeur ordinale d'un caractère.

### Valeurs de retour

Retourne la position numérique de la première occurrence de `needle` dans `haystack`.

Si `needle` n'est pas trouvé, iconv_strpos() retournera `false`.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.
7.1.0 | Support pour les `offset`s négatifs a été ajouté.

### Voir aussi

- strpos() - Cherche la position de la première occurrence dans une chaîne
- iconv_strrpos() - Trouve la position de la dernière occurrence d'un élément dans une chaîne
- mb_strpos() - Repère la première occurrence d'un caractère dans une chaîne

# iconv_strrpos

(PHP 5, PHP 7, PHP 8)

iconv_strrpos — Trouve la position de la dernière occurrence d'un élément dans une chaîne

### Description

function iconv_strrpos(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int|false

Trouve la dernière occurrence de `needle` dans `haystack`.

À l'opposé de strrpos(), la valeur retournée par iconv_strrpos() est le nombre de caractères qui apparaissent avant l'aiguille, plutôt que la position en octets où l'aiguille a été trouvée. Les caractères sont comptés sur la base du jeu de caractères spécifié par `encoding`.

### Liste de paramètres

`haystack`

  La chaîne de caractères entière.

`needle`

  La chaîne de caractères cherchée.

`encoding`

  Si le paramètre optionnel `encoding` est omis ou `null`, `string` est supposé être encodé en iconv.internal_encoding.

Si `haystack` ou `needle` n'est pas une chaîne de caractères, il sera converti en chaîne de caractères et appliqué comme valeur ordinale d'un caractère.

### Valeurs de retour

Retourne la position numérique de la dernière occurrence de `needle` dans `haystack`.

Si `needle` n'est pas trouvé, iconv_strrpos() retourne `false`.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- strrpos() - Cherche la position de la dernière occurrence d'une sous-chaîne dans une chaîne
- iconv_strpos() - Trouve la position de la première occurrence d'une chaîne dans une autre
- mb_strrpos() - Repère la dernière occurrence d'un caractère dans une chaîne

# iconv_substr

(PHP 5, PHP 7, PHP 8)

iconv_substr — Coupe une partie de chaîne

### Description

function iconv_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string|false

Coupe une partie de la chaîne `string` à partir de la position `offset` et d'une longueur de `length`.

### Liste de paramètres

`string`

  La chaîne de caractères originale.

`offset`

  Si `offset` n'est pas négatif, iconv_substr() retourne le segment de `string` en commençant au caractère numéro `offset`, en comptant à partir de zéro.

  Si `offset` est négatif, iconv_substr() retourne le segment en commençant à la position située à `offset` caractères de la fin de `string`.

`length`

  Si le paramètre `length` est donné et positif, la valeur retournée contiendra au plus `length` caractères de la portion de chaîne qui commence à `offset` (en fonction de la taille de la chaîne `string`).

  Si `length` est passé et négatif, iconv_substr() extrait la portion de `string` depuis le caractère numéro `offset` jusqu'au caractère numéro `length`, compté depuis la fin de la chaîne de caractères. Dans le cas où `offset` est également négatif, la position de départ est calculée en amont, suivant la règle expliquée plus haut.

`encoding`

  Si `encoding` est omis ou `null`, `string` est supposé avoir été encodé en iconv.internal_encoding.

  Il est à noter que `offset` et `length` sont toujours considérés comme représentant des décalages calculés en fonction du jeu de caractères déterminé par `encoding`, tandis que la fonction équivalente substr() utilise toujours des décalages d'octets.

### Valeurs de retour

Retourne la portion de `string` spécifiée par les paramètres `offset` et `length`.

Si `string` est plus court que `offset` caractères, `false` est retourné. Si `string` fait exactement `offset` caractères de long, une chaîne de caractères vide est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | `length` et `encoding` sont désormais nullable.
7.0.11 | Si `string` est égal à `offset` caractères long, une chaîne vide sera retournée. Antérieur à cette version, `false` était retourné dans ce cas.

### Voir aussi

- substr() - Retourne un segment de chaîne
- mb_substr() - Lit une sous-chaîne
- mb_strcut() - Coupe une partie de chaîne

# ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ob_iconv_handler — Gestionnaire de sortie pour maîtriser le jeu de caractères de sortie

### Description

function ob_iconv_handler(string `$contents`, int `$status`): string

Convertit la chaîne utilisant le jeu de caractères `internal_encoding` en une chaîne utilisant celui de `output_encoding`.

`internal_encoding` et `output_encoding` doivent être définis par iconv_set_encoding() ou dans le fichier de configuration php.ini.

### Liste de paramètres

Voir la documentation sur la fonction ob_start() pour plus d'informations sur les paramètres de cette fonction.

### Valeurs de retour

Voir la documentation sur la fonction ob_start() pour plus d'informations sur les valeurs retournées par cette fonction.

### Exemples

Exemple #1 Exemple avec ob_iconv_handler()

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ob_start("ob_iconv_handler"); // Commence la mise en buffer de l'affichage
    ?>

### Voir aussi

- iconv_get_encoding() - Récupère les variables de configuration interne de l'extension iconv
- iconv_set_encoding() - Modifie le réglage courant pour la conversion d'encodage de caractères
- fonctions de buffers de sortie

## Sommaire

- iconv — Convertit une chaîne de caractères à partir d'un encodage vers un autre
- iconv_get_encoding — Récupère les variables de configuration interne de l'extension iconv
- iconv_mime_decode — Décode un champ d'en-tête MIME
- iconv_mime_decode_headers — Décode des en-têtes MIME multiples
- iconv_mime_encode — Construit un en-tête MIME avec les champs field_name et field_value
- iconv_set_encoding — Modifie le réglage courant pour la conversion d'encodage de caractères
- iconv_strlen — Retourne le nombre de caractères d'une chaîne
- iconv_strpos — Trouve la position de la première occurrence d'une chaîne dans une autre
- iconv_strrpos — Trouve la position de la dernière occurrence d'un élément dans une chaîne
- iconv_substr — Coupe une partie de chaîne
- ob_iconv_handler — Gestionnaire de sortie pour maîtriser le jeu de caractères de sortie

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Fonctions iconv
  - iconv — Convertit une chaîne de caractères à partir d'un encodage vers un autre
  - iconv_get_encoding — Récupère les variables de configuration interne de l'extension iconv
  - iconv_mime_decode — Décode un champ d'en-tête MIME
  - iconv_mime_decode_headers — Décode des en-têtes MIME multiples
  - iconv_mime_encode — Construit un en-tête MIME avec les champs field_name et field_value
  - iconv_set_encoding — Modifie le réglage courant pour la conversion d'encodage de caractères
  - iconv_strlen — Retourne le nombre de caractères d'une chaîne
  - iconv_strpos — Trouve la position de la première occurrence d'une chaîne dans une autre
  - iconv_strrpos — Trouve la position de la dernière occurrence d'un élément dans une chaîne
  - iconv_substr — Coupe une partie de chaîne
  - ob_iconv_handler — Gestionnaire de sortie pour maîtriser le jeu de caractères de sortie

# Fonctions d'internationalisation

# Introduction

L'extension d'Internationalization (qui est aussi appelée Intl) est une interface pour la bibliothèque » ICU, qui permet aux développeurs PHP d'effectuer des opérations compatibles avec les paramètres régionaux incluant, mais non limitées à cette liste, le formatage, la translitération, la conversion d'encodage, les opérations de calendrier, la collation » UCA-conforme, la localisation des limites du texte et l'utilisation des identificateurs de paramètres régionaux, des fuseaux horaires et des graphèmes.

Cette extension tend à suivre de près l'API ICU, ce qui fait que ceux qui ont l'expérience de cette bibliothèque en C, C++ ou Java pourront facilement s'y retrouver dans l'API PHP. De plus, la documentation ICU peut être très utile pour comprendre les fonctions ICU.

Intl est constitué de plusieurs modules, chacun exposant des API d'ICU :

- Collator : fournit des outils de comparaison de chaînes, qui supportent les tris en fonction des conventions locales.
- Number Formatter : permet d'afficher des nombres en fonction des conventions locales, ou de modèles particuliers, ou encore de règles d'affichage. et d'analyser des chaînes pour en extraire des nombres.
- Message Formatter : permet de créer des messages en incorporant des données (comme des dates ou des nombres) formatées en fonction des conventions locales ou particulières; permet aussi d'analyser des textes pour extraire ces informations. Il peut gérer les pluriels, les nombres, les devises, les conditions et bien plus encore.
- Normalizer : fournit une fonction pour normaliser un texte dans l'une des normalisations Unicode, et des méthodes pour tester si une chaîne est déjà normalisée.
- Locale : fournit des outils d'interaction avec les identifiants de locale : analyse, compose, recherche et filtre des identifiants de locale.
- Calendar: fournit une classe qui peut être utilisée pour les opérations de régionalisation du calendrier, et obtenir des informations variées telles que le fuseau horaire pour la locale choisie, le premier jour de la semaine, ou si le changement d'heure (été/hiver) est actif.
- Timezone: fournit une surcouche autour de » la base de données "Olson" qui contient des informations sur tous les fuseaux horaires du monde.
- Date formatter: permet d'afficher la date et l'heure en rapport avec le format localisé, ou le schéma donné ou les règles définies, et de transformer une chaîne de caractères en date et heure.
- Transliterator: permet d'obtenir une représentation latine d'une chaîne de caractères dans différents langages.

## Liens

- » Diverses docs ICU

- » Guide utilisateur ICU

- » Algorithme de collation Unicode

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

Pour compiler cette extension, il faut installer la bibliothèque » ICU version 4.0.0 ou plus récent. À partir de PHP 7.4.0 ICU 50.1 ou plus récent est requis.

## Installation

--enable-intl activera l'extension de manière embarquée à la compilation.

Si la bibliothèque ICU est installée dans un dossier non-standard, il faudra peut-être spécifier sa localisation via la variable d'environnement `LD_LIBRARY_PATH`, afin que le compilateur dynamique puisse la trouver :

$ export LD_LIBRARY_PATH=/opt/icu/lib

Autrement, si PHP et ICU sont installés dans leurs dossiers par défaut, alors aucune option particulière n'est nécessaire pour configure.

## Configuration à l'exécution

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

Options de configuration d'internationalisation
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
intl.default_locale |  | `INI_ALL` |
intl.error_level | 0 | `INI_ALL` |
intl.use_exceptions | 0 | `INI_ALL` | Disponible à partir de PECL 3.0.0a1

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

`intl.default_locale` string

  La locale à utiliser avec les fonctions intl lorsqu'aucune n'est spécifiée (soit si elle est omise dans l'argument correspondant, soit si la valeur passée vaut `NULL`). Ce sont des locales ICU, et non des locales système. Les locales ICU internes ainsi que leurs données peuvent être explorées ici » https://unicode-org.github.io/icu/userguide/locale/.

  Par défaut, vaut vide, ce qui force l'utilisation de la locale ICU par défaut. Une fois définie, la configuration ini ne peut être réinitialisée par cette valeur par défaut. Il n'est pas recommandé d'utiliser cette valeur par défaut, sachant qu'elle dépend de l'environnement du serveur.

`intl.error_level` int

  Le type des messages d'erreur générés lorsqu'une erreur survient dans les fonctions ICU. C'est un niveau d'erreur PHP, comme `E_WARNING`. Il peut valoir `0` pour inhiber les messages. Ceci n'affecte pas les valeurs retournées indiquant une erreur ou les valeurs retournées par la fonction intl_get_error_code() ou par les méthodes de classe spécifiques permettant de récupérer les codes et les messages d'erreur.

  La valeur par défaut est `0`.

`intl.use_exceptions` int

  Si vaut `true`, une exception sera levée lorsqu'une erreur survient dans une fonction intl. L'exception sera de type IntlException. L'exception sera émise en plus du message d'erreur généré en raison de la définition de l'option de configuration intl.error_level.

  Par défaut, vaut `false`.

# Constantes pré-définies

`INTL_ICU_DATA_VERSION` (string)
  Version des données dans ICU4C.
`INTL_ICU_VERSION` (string)
  La version courante de la bibliothèque ICU en tant qu'une chaîne décimale séparée par des points.
`INTL_MAX_LOCALE_LEN` (int)
  Limite la taille locale, par défaut à 80 en PHP. Les noms de locales plus grands que cette taille seront interdits.
`IDNA_DEFAULT` (int)
  Interdire le traitement des codepoints non affectés dans l'entrée pour les fonctions IDN et ne vérifient pas si l'entrée est conforme aux règles de noms de domaine ASCII.
`IDNA_ALLOW_UNASSIGNED` (int)
  Autoriser le traitement des codepoints non affectés dans l'entrée pour les fonctions IDN.
`IDNA_USE_STD3_RULES` (int)
  Vérifier si l'entrée pour les fonctions IDN est conforme aux règles de noms de domaine ASCII.
`IDNA_CHECK_BIDI` (int)
  Vérifie si l'entrée est conforme aux règles BiDi. Ignoré par l'implémentation IDNA2003, qui effectue toujours cette vérification.
`IDNA_CHECK_CONTEXTJ` (int)
  Vérifie si l'entrée est conforme aux règles CONTEXTJ. Ignoré par l'implémentation IDNA2003, vu que cette vérification est nouvelle en IDNA2008.
`IDNA_NONTRANSITIONAL_TO_ASCII` (int)
  Option pour une exécution non-transitionnelle dans la fonction idn_to_ascii(). L'exécution transitionnelle est activée par défaut. Cette option est ignorée par l'implémentation IDNA2003.
`IDNA_NONTRANSITIONAL_TO_UNICODE` (int)
  Option pour une exécution non-transitionnelle dans la fonction idn_to_utf8(). L'exécution transitionnelle est activée par défaut. Cette option est ignorée par l'implémentation IDNA2003.
`INTL_IDNA_VARIANT_2003` (int)
  Utilise l'algorithme IDNA 2003 dans la fonction idn_to_utf8() ainsi que dans la fonction idn_to_ascii(). C'est le comportement par défaut. Cette constante et l'usage par défaut ont été dépréciés à partir de la version PHP 7.2.0.
`INTL_IDNA_VARIANT_UTS46` (int)
  Utilise l'algorithme UTS #46 dans la fonction idn_to_utf8() ainsi que dans la fonction idn_to_ascii(). Disponible à partir d'ICU 4.6.
`GRAPHEME_EXTR_COUNT` (int)
  Le nombre de graphèmes par défaut à extraire.
`GRAPHEME_EXTR_MAXBYTES` (int)
  Le nombre maximal d'octets retournés.
`GRAPHEME_EXTR_MAXCHARS` (int)
  Le nombre maximal de caractères UTF-8 retournés.

Les erreurs suivantes font partie d'un masque de bits retourné par l'algorithme UTS #46 dans les fonctions idn_to_utf8() et idn_to_ascii().

`IDNA_ERROR_EMPTY_LABEL` (int)
`IDNA_ERROR_LABEL_TOO_LONG` (int)
`IDNA_ERROR_DOMAIN_NAME_TOO_LONG` (int)
`IDNA_ERROR_LEADING_HYPHEN` (int)
`IDNA_ERROR_TRAILING_HYPHEN` (int)
`IDNA_ERROR_HYPHEN_3_4` (int)
`IDNA_ERROR_LEADING_COMBINING_MARK` (int)
`IDNA_ERROR_DISALLOWED` (int)
`IDNA_ERROR_PUNYCODE` (int)
`IDNA_ERROR_LABEL_HAS_DOT` (int)
`IDNA_ERROR_INVALID_ACE_LABEL` (int)
`IDNA_ERROR_BIDI` (int)
`IDNA_ERROR_CONTEXTJ` (int)
`ULOC_ACTUAL_LOCALE` (int)
  La locale d'où proviennent réellement les données.
`ULOC_VALID_LOCALE` (int)
  La locale la plus spécifique prise en charge par ICU.
`U_AMBIGUOUS_ALIAS_WARNING` (int)
  Cet alias de convertisseur peut aller à différentes implémentations de convertisseur.
`U_BAD_VARIABLE_DEFINITION` (int)
  Manque de `'$'` ou nom de variable en double.
`U_BRK_ASSIGN_ERROR` (int)
  Erreur de syntaxe dans l'instruction d'affectation de la règle RBBI.
`U_BRK_ERROR_LIMIT` (int)
  Cela doit toujours être la dernière valeur pour indiquer la limite des échecs de l'itérateur de coupures.
`U_BRK_ERROR_START` (int)
  Début des codes indiquant les échecs de l'itérateur de coupures.
`U_BRK_HEX_DIGITS_EXPECTED` (int)
  Des chiffres hexadécimaux sont attendus comme partie d'un caractère échappé dans une règle.
`U_BRK_INIT_ERROR` (int)
  Échec de l'initialisation. Données ICU probablement manquantes.
`U_BRK_INTERNAL_ERROR` (int)
  Une erreur interne (bogue) a été détectée.
`U_BRK_MALFORMED_RULE_TAG` (int)
  Le tag `{nnn}` sur une règle est mal formé.
`U_BRK_MISMATCHED_PAREN` (int)
  Parenthèses non appariées dans une règle RBBI.
`U_BRK_NEW_LINE_IN_QUOTED_STRING` (int)
  Guillemet fermant manquant dans une règle RBBI.
`U_BRK_RULE_EMPTY_SET` (int)
  La règle contient un ensemble Unicode vide.
`U_BRK_RULE_SYNTAX` (int)
  Erreur de syntaxe dans la règle RBBI.
`U_BRK_SEMICOLON_EXPECTED` (int)
  Point-virgule `';'` manquant à la fin d'une règle RBBI.
`U_BRK_UNCLOSED_SET` (int)
  Ensemble Unicode dans une règle RBBI manquant un `']'` de fermeture.
`U_BRK_UNDEFINED_VARIABLE` (int)
  Utilisation d'une `$Variable` non définie dans une règle RBBI.
`U_BRK_UNRECOGNIZED_OPTION` (int)
  Option dans les règles RBBI non reconnue.
`U_BRK_VARIABLE_REDFINITION` (int)
  Variable de règle RBBI redéfinie.
`U_BUFFER_OVERFLOW_ERROR` (int)
  Un résultat ne rentrerait pas dans le tampon fourni.
`U_CE_NOT_FOUND_ERROR` (int)
  Actuellement utilisé uniquement lors du réglage du sommet variable, mais peut être utilisé généralement.
`U_COLLATOR_VERSION_MISMATCH` (int)
  La version du collateur n'est pas compatible avec la version de base.
`U_DIFFERENT_UCA_VERSION` (int)
  ucol_open a rencontré une incompatibilité entre la version UCA et la version de l'image du collateur, donc le collateur a été construit à partir de règles. Pas d'impact sur la fonction ultérieure.
`U_ENUM_OUT_OF_SYNC_ERROR` (int)
  `UEnumeration` hors de synchronisation avec la collection sous-jacente.
`U_ERROR_LIMIT` (int)
  Alias de `U_PLUGIN_ERROR_LIMIT`.
`U_ERROR_WARNING_LIMIT` (int)
  Cela doit toujours être la dernière valeur d'avertissement pour indiquer la limite des avertissements UErrorCode (dernier code d'avertissement +1).
`U_ERROR_WARNING_START` (int)
  Début des résultats informationnels (sémantiquement réussis).
`U_FILE_ACCESS_ERROR` (int)
  Le fichier demandé est introuvable.
`U_FMT_PARSE_ERROR_LIMIT` (int)
  La limite des erreurs de la bibliothèque de formatage.
`U_FMT_PARSE_ERROR_START` (int)
  Début des erreurs de la bibliothèque de formatage.
`U_IDNA_ACE_PREFIX_ERROR` (int)
`U_IDNA_CHECK_BIDI_ERROR` (int)
`U_IDNA_DOMAIN_NAME_TOO_LONG_ERROR` (int)
`U_IDNA_ERROR_LIMIT` (int)
`U_IDNA_ERROR_START` (int)
`U_IDNA_LABEL_TOO_LONG_ERROR` (int)
`U_IDNA_PROHIBITED_ERROR` (int)
`U_IDNA_STD3_ASCII_RULES_ERROR` (int)
`U_IDNA_UNASSIGNED_ERROR` (int)
`U_IDNA_VERIFICATION_ERROR` (int)
`U_IDNA_ZERO_LENGTH_LABEL_ERROR` (int)
`U_ILLEGAL_ARGUMENT_ERROR` (int)
  Indique une valeur d'argument incorrecte.
`U_ILLEGAL_CHAR_FOUND` (int)
  Conversion de caractère : séquence d'entrée illégale.
`U_ILLEGAL_CHAR_IN_SEGMENT` (int)
  Non utilisé depuis ICU 2.4.
`U_ILLEGAL_CHARACTER` (int)
  Un caractère spécial est en dehors de son contexte autorisé.
`U_ILLEGAL_ESCAPE_SEQUENCE` (int)
  Séquence d'échappement illégale ISO-2022.
`U_ILLEGAL_PAD_POSITION` (int)
  Symbole de remplissage mal placé dans le modèle numérique.
`U_INDEX_OUTOFBOUNDS_ERROR` (int)
  Tentative d'accès à un index hors limites.
`U_INTERNAL_PROGRAM_ERROR` (int)
  Indique un bogue dans le code de la bibliothèque.
`U_INTERNAL_TRANSLITERATOR_ERROR` (int)
  Erreur interne du système de translittération.
`U_INVALID_CHAR_FOUND` (int)
  Conversion de caractère : séquence d'entrée non mappable. Dans d'autres API : caractère invalide.
`U_INVALID_FORMAT_ERROR` (int)
  Le format des données n'est pas celui attendu.
`U_INVALID_FUNCTION` (int)
  Une règle `'&fn()'` spécifie un translittérateur inconnu.
`U_INVALID_ID` (int)
  Une règle `'::id'` spécifie un translittérateur inconnu.
`U_INVALID_PROPERTY_PATTERN` (int)
  Non utilisé depuis ICU 2.4.
`U_INVALID_RBT_SYNTAX` (int)
  Une règle `'::id'` a été passée à l'analyseur RuleBasedTransliterator.
`U_INVALID_STATE_ERROR` (int)
  L'opération demandée ne peut pas être complétée avec ICU dans son état actuel.
`U_INVALID_TABLE_FILE` (int)
  Fichier de table de conversion introuvable.
`U_INVALID_TABLE_FORMAT` (int)
  Fichier de table de conversion trouvé, mais corrompu.
`U_INVARIANT_CONVERSION_ERROR` (int)
  Impossible de convertir une chaîne `UChar*` en `char*` avec le convertisseur invariant.
`U_MALFORMED_EXPONENTIAL_PATTERN` (int)
  Symbole de groupement dans le modèle d'exposant.
`U_MALFORMED_PRAGMA` (int)
  Un pragma `'use'` est invalide.
`U_MALFORMED_RULE` (int)
  Les éléments d'une règle sont mal placés.
`U_MALFORMED_SET` (int)
  Un modèle `UnicodeSet` est invalide.
`U_MALFORMED_SYMBOL_REFERENCE` (int)
  Non utilisé depuis ICU 2.4.
`U_MALFORMED_UNICODE_ESCAPE` (int)
  Un modèle d'échappement Unicode est invalide.
`U_MALFORMED_VARIABLE_DEFINITION` (int)
  Une définition de variable est invalide.
`U_MALFORMED_VARIABLE_REFERENCE` (int)
  Une référence de variable est invalide.
`U_MEMORY_ALLOCATION_ERROR` (int)
  Erreur d'allocation mémoire.
`U_MESSAGE_PARSE_ERROR` (int)
  Impossible d'analyser un message (format de message).
`U_MISMATCHED_SEGMENT_DELIMITERS` (int)
  Non utilisé depuis ICU 2.4.
`U_MISPLACED_ANCHOR_START` (int)
  Une ancre de début apparaît à une position illégale.
`U_MISPLACED_COMPOUND_FILTER` (int)
  Un filtre composé est dans un emplacement invalide.
`U_MISPLACED_CURSOR_OFFSET` (int)
  Un décalage du curseur se produit à une position illégale.
`U_MISPLACED_QUANTIFIER` (int)
  Un quantificateur apparaît après un délimiteur de fin de segment.
`U_MISSING_OPERATOR` (int)
  Une règle ne contient aucun opérateur.
`U_MISSING_RESOURCE_ERROR` (int)
  La ressource demandée est introuvable.
`U_MISSING_SEGMENT_CLOSE` (int)
  Non utilisé depuis ICU 2.4.
`U_MULTIPLE_ANTE_CONTEXTS` (int)
  Plus d'un contexte antérieur.
`U_MULTIPLE_COMPOUND_FILTERS` (int)
  Plus d'un filtre composé.
`U_MULTIPLE_CURSORS` (int)
  Plus d'un curseur.
`U_MULTIPLE_DECIMAL_SEPARATORS` (int)
  Plus d'un séparateur décimal dans le modèle numérique.
`U_MULTIPLE_DECIMAL_SEPERATORS` (int)
  Alias de `U_MULTIPLE_DECIMAL_SEPARATORS`.
`U_MULTIPLE_EXPONENTIAL_SYMBOLS` (int)
  Plus d'un symbole d'exposant dans le modèle numérique.
`U_MULTIPLE_PAD_SPECIFIERS` (int)
  Plus d'un symbole de remplissage dans le modèle numérique.
`U_MULTIPLE_PERCENT_SYMBOLS` (int)
  Plus d'un symbole de pourcentage dans le modèle numérique.
`U_MULTIPLE_PERMILL_SYMBOLS` (int)
  Plus d'un symbole de pour mille dans le modèle numérique.
`U_MULTIPLE_POST_CONTEXTS` (int)
  Plus d'un contexte postérieur.
`U_NO_SPACE_AVAILABLE` (int)
  Pas d'espace disponible pour l'expansion en mémoire tampon pour la mise en forme arabe.
`U_NO_WRITE_PERMISSION` (int)
  Tentative de modification de données en lecture seule ou de données constantes.
`U_PARSE_ERROR` (int)
  Équivalent à Java `ParseException`.
`U_PARSE_ERROR_LIMIT` (int)
  La limite pour les erreurs du Transliterator.
`U_PARSE_ERROR_START` (int)
  Début des erreurs du Transliterator.
`U_PATTERN_SYNTAX_ERROR` (int)
  Erreur de syntaxe dans le modèle de format.
`U_PRIMARY_TOO_LONG_ERROR` (int)
  L'utilisateur a essayé de définir une variable supérieure à une valeur primaire de plus de deux octets.
`U_REGEX_BAD_ESCAPE_SEQUENCE` (int)
  Séquence d'échappement non reconnue dans le modèle.
`U_REGEX_BAD_INTERVAL` (int)
  Erreur dans l'intervalle `{min,max}`.
`U_REGEX_ERROR_LIMIT` (int)
  Cela doit toujours être la dernière valeur pour indiquer la limite des erreurs d'expressions rationnelles.
`U_REGEX_ERROR_START` (int)
  Début des codes indiquant les échecs des expressions rationnelles.
`U_REGEX_INTERNAL_ERROR` (int)
  Une erreur interne (bogue) a été détectée.
`U_REGEX_INVALID_BACK_REF` (int)
  Référence arrière vers un groupe de capture inexistant.
`U_REGEX_INVALID_FLAG` (int)
  Valeur invalide pour les drapeaux de mode de correspondance.
`U_REGEX_INVALID_STATE` (int)
  `RegexMatcher` dans un état invalide pour l'opération demandée.
`U_REGEX_LOOK_BEHIND_LIMIT` (int)
  Les correspondances de modèle Look-Behind doivent avoir une longueur maximale bornée.
`U_REGEX_MAX_LT_MIN` (int)
  Dans `{min,max}`, max est inférieur à min.
`U_REGEX_MISMATCHED_PAREN` (int)
  Parenthèses incorrectement imbriquées dans le modèle d'expression rationnelle.
`U_REGEX_NUMBER_TOO_BIG` (int)
  Le nombre décimal est trop grand.
`U_REGEX_PROPERTY_SYNTAX` (int)
  Propriété Unicode incorrecte.
`U_REGEX_RULE_SYNTAX` (int)
  Erreur de syntaxe dans le modèle d'expression rationnelle.
`U_REGEX_SET_CONTAINS_STRING` (int)
  Les expressions rationnelles ne peuvent pas contenir de `UnicodeSet`s contenant des chaînes.
`U_REGEX_UNIMPLEMENTED` (int)
  Utilisation d'une fonctionnalité d'expression rationnelle pas encore implémentée.
`U_RESOURCE_TYPE_MISMATCH` (int)
  Une opération est demandée sur une ressource qui ne la prend pas en charge.
`U_RULE_MASK_ERROR` (int)
  Une règle est masquée par une règle antérieure plus générale.
`U_SAFECLONE_ALLOCATED_WARNING` (int)
  Une opération `SafeClone` a nécessité une allocation mémoire (à titre informatif uniquement).
`U_SORT_KEY_TOO_SHORT_WARNING` (int)
  Le nombre de niveaux demandé dans `getBound` est supérieur au nombre de niveaux dans la clé de tri.
`U_STANDARD_ERROR_LIMIT` (int)
  Cela doit toujours être la dernière valeur pour indiquer la limite des erreurs standard.
`U_STATE_OLD_WARNING` (int)
  ICU doit utiliser une couche de compatibilité pour construire le service. Il faut s'attendre à une dégradation des performances/de l'utilisation mémoire.
`U_STATE_TOO_OLD_ERROR` (int)
  ICU ne peut pas construire un service à partir de cet état, car il n'est plus pris en charge.
`U_STRING_NOT_TERMINATED_WARNING` (int)
  Une chaîne en sortie n'a pas pu être terminée par NUL car la longueur de sortie `length==destCapacity`.
`U_STRINGPREP_CHECK_BIDI_ERROR` (int)
  Alias de `U_IDNA_CHECK_BIDI_ERROR`.
`U_STRINGPREP_PROHIBITED_ERROR` (int)
  Alias de `U_IDNA_PROHIBITED_ERROR`.
`U_STRINGPREP_UNASSIGNED_ERROR` (int)
  Alias de `U_IDNA_UNASSIGNED_ERROR`.
`U_TOO_MANY_ALIASES_ERROR` (int)
  Il y a trop d'alias dans le chemin vers la ressource demandée. Il est très probable qu'une définition d'alias circulaire s'est produite.
`U_TRAILING_BACKSLASH` (int)
  Un antislash en suspens.
`U_TRUNCATED_CHAR_FOUND` (int)
  Conversion de caractère : séquence d'entrée incomplète.
`U_UNCLOSED_SEGMENT` (int)
  Un `')'` fermant est manquant.
`U_UNDEFINED_SEGMENT_REFERENCE` (int)
  Une référence de segment ne correspond à aucun segment défini.
`U_UNDEFINED_VARIABLE` (int)
  Une référence de variable ne correspond à aucune variable définie.
`U_UNEXPECTED_TOKEN` (int)
  Erreur de syntaxe dans le modèle de format.
`U_UNMATCHED_BRACES` (int)
  Les accolades ne correspondent pas dans le modèle de message.
`U_UNQUOTED_SPECIAL` (int)
  Un caractère spécial n'a pas été mis entre guillemets ou échappé.
`U_UNSUPPORTED_ATTRIBUTE` (int)
  Non utilisé depuis ICU 2.4.
`U_UNSUPPORTED_ERROR` (int)
  L'opération demandée n'est pas prise en charge dans le contexte courant.
`U_UNSUPPORTED_ESCAPE_SEQUENCE` (int)
  Séquence d'échappement ISO-2022 non prise en charge.
`U_UNSUPPORTED_PROPERTY` (int)
  Non utilisé depuis ICU 2.4.
`U_UNTERMINATED_QUOTE` (int)
  Un guillemet simple fermant est manquant.
`U_USELESS_COLLATOR_ERROR` (int)
  Le collateur ne contient que des options et aucune base n'est spécifiée.
`U_USING_DEFAULT_WARNING` (int)
  Une recherche dans le bundle de ressources a renvoyé un résultat de la locale racine (pas une erreur).
`U_USING_FALLBACK_WARNING` (int)
  Une recherche dans le bundle de ressources a renvoyé un résultat de repli (pas une erreur).
`U_VARIABLE_RANGE_EXHAUSTED` (int)
  Trop de substituts générés pour la plage de variables donnée.
`U_VARIABLE_RANGE_OVERLAP` (int)
  La plage de variables chevauche les caractères utilisés dans les règles.
`U_ZERO_ERROR` (int)
  Pas d'erreur, pas d'avertissement.

# Exemples

## Sommaire

- Utilisation simple de l'extension

## Utilisation simple de l'extension

Chaque module dispose de deux types d'API : une version procédurale, et une version objet. Les deux sont en fait identiques, et décrites dans le document correspondant.

> Note:

> Toutes les chaînes doivent être en UTF-8. Tous les résultats sont aussi en UTF-8.

Exemple #1 Exemple d'API procédurale pour intl

    <?php
    $coll  = collator_create('en_US');
    $result = collator_compare($coll, "string#1", "string#2");
    ?>

Exemple #2 Exemple d'API orientée objet pour intl

    <?php
    $coll = new Collator('en_US');
    $al   = $coll->getLocale(Locale::ACTUAL_LOCALE);
    echo "Actual locale: $al\n";

    $formatter = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    echo $formatter->format(1234567);
    ?>

# La classe Collator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introduction

Fournit des outils de comparaisons de chaînes, avec le support des conventions locales pour les tris.

## Synopsis de la classe

class Collator {
/* Constantes */
public const int DEFAULT_VALUE;
public const int PRIMARY;
public const int SECONDARY;
public const int TERTIARY;
public const int DEFAULT_STRENGTH;
public const int QUATERNARY;
public const int IDENTICAL;
public const int OFF;
public const int ON;
public const int SHIFTED;
public const int NON_IGNORABLE;
public const int LOWER_FIRST;
public const int UPPER_FIRST;
public const int FRENCH_COLLATION;
public const int ALTERNATE_HANDLING;
public const int CASE_FIRST;
public const int CASE_LEVEL;
public const int NORMALIZATION_MODE;
public const int STRENGTH;
public const int HIRAGANA_QUATERNARY_MODE;
public const int NUMERIC_COLLATION;
public const int SORT_REGULAR;
public const int SORT_STRING;
public const int SORT_NUMERIC;
/* Méthodes */
public function __construct(string `$locale`)
public function asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function compare(string `$string1`, string `$string2`): int|false
public static function create(string `$locale`): ?Collator
public function getAttribute(int `$attribute`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getLocale(int `$type`): string|false
public function getSortKey(string `$string`): string|false
public function getStrength(): int
public function setAttribute(int `$attribute`, int `$value`): bool
public function setStrength(int `$strength`): true
public function sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function sortWithSortKeys(array `&$array`): bool
}

## Constantes pré-définies

`Collator::FRENCH_COLLATION` int

  Trie les chaînes avec différents accents, sur la fin de la chaîne. Cet attribut est automatiquement configuré à On pour les locales françaises, et quelques autres. Les utilisateurs n'ont pas besoin de configurer explicitement cet attribut. Il y a un coût de performances lors de la comparaison des chaînes quand cet attribut est à On, mais la taille des clés de tris est inchangée. Les valeurs possibles sont :

  - `Collator::ON`
  - `Collator::OFF`(par défaut)
  - `Collator::DEFAULT_VALUE`

  Exemple #1 Règles de FRENCH_COLLATION

  - F=OFF cote < coté < côte < côté
  - F=ON cote < côte < coté < côté
`Collator::ALTERNATE_HANDLING`

  L'attribut alterné est utilisé pour contrôler la gestion des caractères variables de UCA : les espaces blancs, la ponctuation et les symboles. Si Alternate est configuré à NonIgnorable (N), alors les différences entre ces caractères sont de la même importance que les différences entre les lettres. Si Alternate est configuré à Shifted (S), alors ces caractères seront d'importance mineure. La valeur Shifted est souvent utilisée conjointement avec Quaternary qui vaut Strength. Dans ce cas, les espaces blancs, la ponctuation et les symboles sont considérés lors de la comparaison, mais uniquement si les autres aspects de la chaîne (lettres de base, accents et casse) sont tous identiques. Si Alternate n'est pas configuré à Shifted, il n'y a alors pas de différence entre une Strength de 3 et une Strength de 4. Pour plus d'informations et d'exemples, voir Variable_Weighting dans » UCA. La raison qui fait que les valeurs de Alternate ne sont pas seulement On et Off est que des valeurs supplémentaires pour Alternate pourraient être ajoutées à l'avenir. L'option UCA Blanked est exprimée avec une valeur de Strength à 3, et Alternate configuré à Shifted. La valeur par défaut pour la majorité des locales est NonIgnorable. Si Shifted est sélectionné, il peut être plus lent s'il y a de nombreuses chaînes qui sont identiques, sauf pour la ponctuation : la taille de la clé de tri sera inchangée, à moins que le niveau de Strength ne soit élevé.

  Les valeurs possibles sont :

  - `Collator::NON_IGNORABLE`(par défaut)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  Exemple #2 Règles ALTERNATE_HANDLING

  - S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
  - S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
  - S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
`Collator::CASE_FIRST` int

  L'attribut Case_First est utilisé pour contrôler le fait que les majuscules doivent être considérées comme avant les minuscules, et vice-versa, en l'absence d'autres discriminants. Les valeurs possibles sont Uppercase_First (U) et Lowercase_First (L), plus les valeurs standards Default et Off. Il n'y a presque pas de différence entre Off et Lowercase_First en termes de résultats, ce qui fait que les utilisateurs typiques n'utiliseront pas Lowercase_First : uniquement Off ou Uppercase_First. (ceux qui sont intéressés par les différences entre X et L devront consulter la section `Collation Customization`). Spécifier L ou U ne va pas changer les performances de comparaison, mais va affecter la taille de la clé de tri.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  Exemple #3 Règles CASE_FIRST

  - C=X or C=L "china" < "China" < "denmark" < "Denmark"
  - C=U "China" < "china" < "Denmark" < "denmark"
`Collator::CASE_LEVEL` int

  L'attribut Case_Level est utilisé pour ignorer les accents, mais pas la casse. Dans ces situations, mettez l'attribut Strength à Primary, et Case_Level à On. Dans la plupart des locales, cet attribut est à Off par défaut. Il y a un petit coût de performances pour la comparaison des chaînes, un impact sur la taille des index de tri si cet attribut est à On.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  Exemple #4 Règles CASE_LEVEL

  - S=1, E=X role = Role = rôle
  - S=1, E=O role = rôle < Role
`Collator::NORMALIZATION_MODE` int

  L'attribut Normalization détermine s'il faut normaliser totalement le texte ou non, pour la comparaison. Même si cet attribut est à Off (ce qui est le cas par défaut pour de nombreuses locales), les textes comparés pour un usage ordinaire seront corrects (pour des détails, voir UTN #5). Il n'y aura un problème que si les marques d'accent ne sont pas canoniques. Si cet attribut est à On, alors les meilleurs résultats sont garantis pour tous les textes. Il y a un coût de comparaison moyen si cet attribut vaut On, en fonction de la fréquence des séquences qui requièrent de la normalisation. Il n'y a pas d'effet significatif sur la taille des index de tri. Si le texte est réputé dans les formes de normalisation NFD ou NFKD, il n'y a pas besoin d'activer l'option de Normalization.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  Le service de collation ICU supporte de nombreux niveaux de comparaison (appelés "Levels", mais aussi connus sous le nom de "Strengths"). Avec ces catégories, ICU peut trier les chaînes avec précision, en fonction des conventions locales. Cependant, en permettant l'utilisation sélective des niveaux, la recherche d'une chaîne dans un texte peut être réalisée, à partir de différentes conditions. Pour plus d'informations, voyez le chapitre collator_set_strength().

  Les valeurs possibles sont :

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(par défaut)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  La compatibilité avec JIS x 4061 requiert l'introduction d'un niveau supplémentaire pour distinguer les caractères Hiragana et Katakana. Si la compatibilité avec le standard est nécessaire, alors cet attribut doit être utilisé à On, et la Strength doit prendre la valeur de Quaternary. Cela va affecter la taille des index de tri, et les performances de comparaisons des chaînes.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  Lorsqu'activé, cet attribut génère une clé de collation pour les valeurs numériques de sous-chaînes. C'est une méthode pour que '100' soit trié après '2'.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::DEFAULT_VALUE` int
`Collator::PRIMARY` int
`Collator::SECONDARY` int
`Collator::TERTIARY` int
`Collator::DEFAULT_STRENGTH` int
`Collator::QUATERNARY` int
`Collator::IDENTICAL` int
`Collator::OFF` int
`Collator::ON` int
`Collator::SHIFTED` int
`Collator::NON_IGNORABLE` int
`Collator::LOWER_FIRST` int
`Collator::UPPER_FIRST` int
`Collator::SORT_REGULAR` int

`Collator::SORT_STRING` int

`Collator::SORT_NUMERIC` int

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont désormais typées.

# Collator::asort

# collator_asort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::asort -- collator_asort — Trie un tableau en conservant les clés, avec une collation

### Description

Style orienté objet

public function Collator::asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Style procédural

function collator_asort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Cette fonction trie un tableau en maintenant l'association entre les clés et les valeurs. Elle sert surtout à trier des tableaux associatifs, où l'ordre des éléments est important. Les éléments seront triés en fonction des conventions locales.

Équivalent de la fonction PHP standard asort().

### Liste de paramètres

`object`

  Objet Collator.

`array`

  tableau de chaînes à trier.

`flags`

  Type de tri, optionnel, choisi parmi les constantes suivantes :

  - `Collator::SORT_REGULAR` : compare les éléments normalement (pas de changement de type).

  - `Collator::SORT_NUMERIC` : compare les éléments numériquement.

  - `Collator::SORT_STRING` : compare les éléments littéralement.

  La valeur par défaut de `flags` est `Collator::SORT_REGULAR`. Cette valeur est aussi utilisée si une valeur invalide de `flags` a été fournie.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec collator_asort()

    <?php
    $coll = collator_create( 'en_US' );
    $arr = array(
         'a' => '100',
         'b' => '50',
         'c' => '7'
    );
    collator_asort( $coll, $arr, Collator::SORT_NUMERIC );
    var_export( $arr );

    collator_asort( $coll, $arr, Collator::SORT_STRING );
    var_export( $arr );
    ?>

L'exemple ci-dessus va afficher :

    array (
      'c' => '7',
      'b' => '50',
      'a' => '100',
    )array (
      'a' => '100',
      'b' => '50',
      'c' => '7',
    )

### Voir aussi

- Constantes Collator
- collator_sort() - Trie un tableau avec une collation
- collator_sort_with_sort_keys() - Trie un tableau et ses clés avec une collation

# Collator::compare

# collator_compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::compare -- collator_compare — Compare deux chaînes Unicode

### Description

Style orienté objet

public function Collator::compare(string `$string1`, string `$string2`): int|false

Style procédural

function collator_compare(Collator `$object`, string `$string1`, string `$string2`): int|false

Compare deux chaînes Unicode en fonction des règles de collation.

### Liste de paramètres

`object`

  Objet Collator.

`string1`

  La première chaîne à comparer.

`string2`

  La deuxième chaîne à comparer.

### Valeurs de retour

Résultats de comparaison

- 1 si `string1` est plus grand que `string2` ;

- 0 si `string1` est égal à `string2`;

- -1 si `string1` est plus petit que `string2` .

Retourne `false` en cas d'échec.
Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Exemples

Exemple #1 Exemple avec collator_compare()

    <?php
    $s1 = 'Hello';
    $s2 = 'hello';

    $coll = collator_create( 'en_US' );
    $res  = collator_compare( $coll, $s1, $s2 );

    if ($res === false) {
        echo collator_get_error_message( $coll );
    } else if( $res > 0 ) {
        echo "s1 est plus grand que s2\n";
    } else if( $res < 0 ) {
        echo "s1 est plus petit que s2\n";
    } else {
        echo "s1 est égal à s2\n";
    }
    ?>

L'exemple ci-dessus va afficher :

s1 est plus grand que s2

Exemple #2 Comparer des chaînes sans diacritique ou sensibilité à la casse

    <?php
    $c = new Collator( 'en' );
    $c->setStrength( Collator::PRIMARY );
    if ( $c->compare( 'Séan', 'Sean' ) == 0 )
    {
        echo "The same\n";
    }

L'exemple ci-dessus va afficher :

The same

Cet exemple demande au collator de comparer en ne prenant en compte que les caractères de base. La documentation pour Collator->setStrength() explique les forces différentes.

### Voir aussi

- collator_sort() - Trie un tableau avec une collation

# Collator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::__construct — Création d'un collator

### Description

public function Collator::__construct(string `$locale`)

Création d'une nouvelle instance de Collator.

### Liste de paramètres

`locale`

  La locale dont les règles de collation doivent être respectées. Des valeurs spéciales peuvent être passées dans cet argument : si une chaîne de caractères vide est passée, la locale par défaut sera utilisée. Si le mot clé `"root"` est passé, les règles » UCA seront utilisées.

  L'attribut Locale est généralement l'attribut le plus important pour assurer des tris et comparaisons valides, en fonction des attentes des utilisateurs. L'ordre par défaut » UCA va trier uniquement quelques langues, telles qu'hollandais ou portugais (correctement signifie que le résultat sera conforme aux attentes des utilisateurs de ces langues). Autrement, il faut fournir une locale adaptée aux utilisateurs. Par conséquent, une valeur spécifique de locale doit être fournie pour assurer un service correct. Le choix de la locale va configurer les valeurs de tous ses attributs qui sont les plus pertinentes pour une locale. Par conséquent, la plupart du temps, les attributs n'ont pas besoin d'être explicitement attribués. Dans le même temps, le choix de la locale aura un impact sur les performances de comparaison et de tris.

### Erreurs / Exceptions

Retourne un objet "vide" en cas d'erreur. Utiliser intl_get_error_code() et / ou intl_get_error_message() pour en savoir plus.

### Exemples

Exemple #1 Exemple avec Collator::__construct()

    <?php
    $coll = new Collator('en_CA');
    ?>

### Voir aussi

- Collator::create() - Création d'un collator
- collator_create() - Création d'un collator

# Collator::create

# collator_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::create -- collator_create — Création d'un collator

### Description

Style orienté objet

public static function Collator::create(string `$locale`): ?Collator

Style procédural

function collator_create(string `$locale`): ?Collator

Les chaînes seront comparées et triées avec des conventions locales.

### Liste de paramètres

`locale`

  La locale dont les règles de collation doivent être respectées. Des valeurs spéciales peuvent être passées dans cet argument : si une chaîne de caractères vide est passée, la locale par défaut sera utilisée. Si le mot clé `"root"` est passé, les règles » UCA seront utilisées.

### Valeurs de retour

Retourne une nouvelle instance de la classe Collator, ou `null` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec collator_create()

    <?php
    $coll = collator_create( 'en_US' );

    if( !isset( $coll ) ) {
        printf( "Échec de création de collator : %s\n", intl_get_error_message() );
        exit( 1 );
    }
    ?>

### Voir aussi

- Collator::__construct() - Création d'un collator

# Collator::getAttribute

# collator_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getAttribute -- collator_get_attribute — Lit un attribut de collation

### Description

Style orienté objet

public function Collator::getAttribute(int `$attribute`): int|false

Style procédural

function collator_get_attribute(Collator `$object`, int `$attribute`): int|false

Lit un attribut de collation.

### Liste de paramètres

`object`

  Objet Collator.

`attribute`

  L'attribut à lire.

### Valeurs de retour

La valeur de l'attribut, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec collator_get_attribute()

    <?php
    $coll = collator_create( 'en_CA' );
    $val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
    if( $val === false )
    {
        // Gestion d'erreur
    }
    ?>

### Voir aussi

- Collator constants
- collator_set_attribute() - Configure l'attribut de collation
- collator_get_strength() - Récupère la dureté de classement utilisé

# Collator::getErrorCode

# collator_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorCode -- collator_get_error_code — Lit la dernière erreur du collator

### Description

Style orienté objet

public function Collator::getErrorCode(): int|false

Style procédural

function collator_get_error_code(Collator `$object`): int|false

### Liste de paramètres

`object`

  Objet Collator.

### Valeurs de retour

Le code d'erreur retourné par le dernier appel à un objet de l'API Collator, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec collator_get_error_code()

    <?php
    $coll = collator_create( 'en_US' );
    if( collator_get_attribute( $coll, Collator::FRENCH_COLLATION ) === false )
            handle_error( collator_get_error_code() );
    ?>

### Voir aussi

- collator_get_error_message() - Lit le dernier message d'erreur du collator

# Collator::getErrorMessage

# collator_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorMessage -- collator_get_error_message — Lit le dernier message d'erreur du collator

### Description

Style orienté objet

public function Collator::getErrorMessage(): string|false

Style procédural

function collator_get_error_message(Collator `$object`): string|false

Lit le dernier message d'erreur.

### Liste de paramètres

`object`

  Objet Collator.

### Valeurs de retour

La description d'une erreur survenue lors du dernier appel à une méthode de l'API Collator, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec collator_get_error_message()

    <?php
    $coll = collator_create( 'lt' );
    if( collator_compare( $coll, 'y', 'k' ) === false ) {
        echo collator_get_error_message( $coll );
    }
    ?>

### Voir aussi

- collator_get_error_code() - Lit la dernière erreur du collator

# Collator::getLocale

# collator_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getLocale -- collator_get_locale — Lit le nom de la locale d'un collator

### Description

Style orienté objet

public function Collator::getLocale(int `$type`): string|false

Style procédural

function collator_get_locale(Collator `$object`, int `$type`): string|false

Lit le nom de la locale d'un collator

### Liste de paramètres

`object`

  Objet Collator.

`type`

  Il est possible de choisir entre une valeur valide ou une valeur littérale de la locale (à l'aide des constantes `Locale::VALID_LOCALE` et `Locale::ACTUAL_LOCALE`, respectivement).

### Valeurs de retour

Le nom de la locale pour laquelle le collator est configuré. Si le collator a été configuré à partir de règles, ou si une erreur est survenue retourne `false`.

### Exemples

Exemple #1 Exemple avec collator_get_locale()

    <?php
    $coll    = collator_create( 'en_US_California' );
    $res_val = collator_get_locale( $coll, Locale::VALID_LOCALE );
    $res_act = collator_get_locale( $coll, Locale::ACTUAL_LOCALE );
    printf( "Valid locale name: %s\nActual locale name: %s\n",
             $res_val, $res_act );
    ?>

L'exemple ci-dessus va afficher :

    Requested locale name: en_US_California
    Valid locale name: en_US
    Actual locale name: en

### Voir aussi

- collator_create() - Création d'un collator

# Collator::getSortKey

# collator_get_sort_key

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 1.0.3)

Collator::getSortKey -- collator_get_sort_key — Récupère la clé de tri pour une chaîne

### Description

Style orienté objet

public function Collator::getSortKey(string `$string`): string|false

Style procédural

function collator_get_sort_key(Collator `$object`, string `$string`): string|false

Retourne la clé de la collation pour une chaîne. Les clés de collation peuvent être comparées directement au lieu de chaînes, néanmoins elles sont spécifiques à l'implémentation et peuvent changer entre les versions de la bibliothèque ICU. Les clés de tri sont généralement seulement utiles dans les bases de données ou autres circonstances où les appels de fonctions sont extrêmement chers.

### Liste de paramètres

`object`

  Objet Collator.

`string`

  La chaîne depuis laquelle produire la clé.

### Valeurs de retour

Retourne la clé de collation pour la chaîne, ou `false` si une erreur survient.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Exemples

Exemple #1 Exemple collator_get_sort_key()

    <?php

    $s1 = 'Hello';

    $coll = collator_create('en_US');
    $res  = collator_get_sort_key($coll, $s1);

    echo bin2hex($res);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

3832404046010901dc08

Exemple #2 Collator::getSortKey() : exemple avec usort()

    <?php

    $data = [
        [ 'name' => '🇳🇱 Derick Rethans', 'linked_account' => 'https://phpc.social/users/derickr' ],
        [ 'name' => 'Elephpant', 'linked_account' => 'https://phpc.social/phpc' ],
        [ 'name' => '🇫🇷 Marcus Bointon', 'linked_account' => 'https://phpc.social/users/Synchro' ],
    ];

    /* Créer le collateur */
    $col = new Collator('en');

    /* Trier les lettres majuscules avant les minuscules */
    $col->setAttribute(Collator::CASE_FIRST, Collator::UPPER_FIRST);

    /* Utiliser une fonction définie par l'utilisateur avec sort, qui supprime les émojis */
    usort(
        $data,
        function($a, $b) use ($col) {
            /* Supprimer la classe de caractères 'S' (Symboles) et les espaces
             * (avec trim) */
            $aName = trim(preg_replace('/\p{S}+/u', '', $a['name']));
            $bName = trim(preg_replace('/\p{S}+/u', '', $b['name']));

                                    /* Créer la clé de tri */
            $aKey = $col->getSortKey($aName);
            $bKey = $col->getSortKey($bName);

                                    /* Utiliser la clé de tri pour déterminer l'ordre des éléments */
            return $aKey <=> $bKey;
        }
    );

    var_dump($data);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

array(3) {
[0] =>
array(2) {
'name' =>
string(25) "🇳🇱 Derick Rethans"
'linked_account' =>
string(33) "https://phpc.social/users/derickr"
}
[1] =>
array(2) {
'name' =>
string(9) "Elephpant"
'linked_account' =>
string(24) "https://phpc.social/phpc"
}
[2] =>
array(2) {
'name' =>
string(25) "🇫🇷 Marcus Bointon"
'linked_account' =>
string(33) "https://phpc.social/users/Synchro"
}
}

### Voir aussi

- collator_sort() - Trie un tableau avec une collation
- collator_sort_with_sort_keys() - Trie un tableau et ses clés avec une collation

# Collator::getStrength

# collator_get_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getStrength -- collator_get_strength — Récupère la dureté de classement utilisé

### Description

Style orienté objet

public function Collator::getStrength(): int

Style procédural

function collator_get_strength(Collator `$object`): int

### Liste de paramètres

`object`

  Objet Collator.

### Valeurs de retour

Retourne la force du classement, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec collator_get_strength()

    <?php
    $coll     = collator_create( 'en_US' );
    $strength = collator_get_strength( $coll );
    ?>

### Voir aussi

- Collator constants
- collator_set_strength() - Définit la force de collation
- collator_get_attribute() - Lit un attribut de collation

# Collator::setAttribute

# collator_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setAttribute -- collator_set_attribute — Configure l'attribut de collation

### Description

Style orienté objet

public function Collator::setAttribute(int `$attribute`, int `$value`): bool

Style procédural

function collator_set_attribute(Collator `$object`, int `$attribute`, int `$value`): bool

### Liste de paramètres

`object`

  Objet Collator.

`attribute`

  L'attribut.

`value`

  La valeur de l'attribut.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec collator_set_attribute()

    <?php
    $coll = collator_create('en_CA');
    collator_set_attribute($coll, Collator::NORMALIZATION_MODE, Collator::ON);
    ?>

### Voir aussi

- Collator constants
- collator_get_attribute() - Lit un attribut de collation
- collator_set_strength() - Définit la force de collation

# Collator::setStrength

# collator_set_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setStrength -- collator_set_strength — Définit la force de collation

### Description

Style orienté objet

public function Collator::setStrength(int `$strength`): true

Style procédural

function collator_set_strength(Collator `$object`, int `$strength`): true

Le service de collation » ICU supporte de nombreux niveaux de comparaison (appelés "Levels", mais aussi connus sous le nom de "Strengths"). Avec ces catégories, ICU peut trier les chaînes avec précision, en fonction des conventions locales. Cependant, en permettant l'utilisation sélective des niveaux, la recherche d'une chaîne dans un texte peut être réalisée, à partir de différentes conditions. Pour plus d'informations, voir le chapitre collator_set_strength().

1. Niveau primaire : Typiquement, ceci est utilisé pour faire la différence entre des caractères de bases, comme "a" < "b"). C'est la différence la plus importante. Par exemple, les dictionnaires sont divisés en sections avec les caractères de base. Ceci est aussi appelé le `level 1` de force.

2. Niveau secondaire : Les accents sur les caractères sont considérés comme des différences secondaires. Par exemple, "as" < "às" < "at". D'autres différences entre les caractères peuvent être considérées comme secondaires, en fonction des langues. Une différence secondaire est toujours ignorée quand une différence primaire est présente. Ceci est aussi appelé le `level 2` de force.

   > Note:

   > Note : dans certaines langues, comme le danois, certains caractères accentués sont considérés comme des caractères de bases. Dans la plupart des langues, un caractère accentué est simplement une différence secondaire avec les versions simples de la lettre.

3. Niveau tertiaire : les majuscules et les minuscules sont distinguées au niveau tertiaire. par exemple, "ao" < "Ao" < "aò". De plus, une variante d'une lettre est différente de la forme de base, au niveau ternaire. Par exemple, "a" et "𝒶". Un autre exemple de différence tertiaire est le grand et le petit Kana. Une différence tertiaire est ignorée quand une différence primaire ou secondaire est présente. Ceci est aussi appelé le `level 3` de force.

4. Niveau quaternaire : Lorsque la ponctuation est ignorée, aux niveaux 1-3, un niveau supplémentaire peut être utilisé pour distinguer des mots avec ou sans ponctuation. Par exemple, "ab" < "a-b" < "aB". Cette différence est ignorée lorsqu'il y a une différence de niveau primaire, secondaire ou tertiaire. Ceci est aussi appelé le `level 4` de force. Le niveau quaternaire ne doit être utilisé que lorsqu'il faut ignorer la ponctuation ou traiter du texte japonais (traitement Hiragana).

5. Niveau identique : Lorsque tous les autres niveaux sont égaux, le niveau identique est utilisé pour départager les caractères. Le code Unicode point sur une forme NFD de chaque caractère, et sont comparés à ce niveau, au cas où il n'y aurait pas de différence aux niveaux 1-4. Par exemple, les cantillations hébraïques ne sont distinguées qu'à ce niveau. Ce niveau ne doit être utilisé qu'avec beaucoup de parcimonie, car il fait substantiellement décroître les performances. Ceci est aussi appelé le `level 5` de force.

Par exemple, on peut choisir d'ignorer les accents, les accents et les majuscules dans un texte. Presque tous les caractères sont distingués par les trois premiers niveaux, et la plupart des locales s'arrêtent au niveau trois. Cependant, si l'attribut Alternate prend la valeur de Shifted, alors le quatrième niveau sert à départager les égalités entre les espaces, la ponctuation et les symboles, qui seraient ignorés autrement. Si des différences très subtiles sont nécessaires entre les caractères, le niveau identique peut être utilisé (par exemple, le niveau identique fait la différence entre un A mathématique petit et gras avec un A mathématique italique et petit. Cependant, utiliser ces niveaux implique une dégradation significative des performances lors de la comparaison et le tri des chaînes proches ou égales.

### Liste de paramètres

`object`

  Objet Collator.

`strength`

  Le niveau à choisir.

  Les valeurs possibles sont :

  - `Collator::PRIMARY`

  - `Collator::SECONDARY`

  - `Collator::TERTIARY`

  - `Collator::QUATERNARY`

  - `Collator::IDENTICAL`

  - `Collator::DEFAULT_STRENGTH`

### Valeurs de retour

Retourne toujours `true`.

### Exemples

Exemple #1 Exemple avec collator_set_strength()

    <?php
    $arr  = array( 'aò', 'Ao', 'ao' );
    $coll = collator_create( 'en_US' );

    // Trie un tableau avec le niveau par défaut
    collator_sort( $coll, $arr );
    var_export( $arr );

    // Tri un tableau avec le niveau primaire
    collator_set_strength( $coll, Collator::PRIMARY );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

L'exemple ci-dessus va afficher :

    array (
      0 => 'ao',
      1 => 'Ao',
      2 => 'aò',
    )
    array (
      0 => 'aò',
      1 => 'Ao',
      2 => 'ao',
    )

### Voir aussi

- Constantes Collator
- collator_get_strength() - Récupère la dureté de classement utilisé

# Collator::sort

# collator_sort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sort -- collator_sort — Trie un tableau avec une collation

### Description

Style orienté objet

public function Collator::sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Style procédural

function collator_sort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Cette fonction trie un tableau en fonction des conventions locales.

Équivalent à la fonction standard PHP sort().

### Liste de paramètres

`object`

  Objet Collator.

`array`

  tableau de chaînes à trier.

`flags`

  Type de tri, optionnel, choisi parmi les constantes suivantes :

  - `Collator::SORT_REGULAR` : compare les éléments normalement (pas de changement de type).

  - `Collator::SORT_NUMERIC` : compare les éléments numériquement.

  - `Collator::SORT_STRING` : compare les éléments littéralement.

  Le type de tri par défaut est `Collator::SORT_REGULAR`. Il est également utilisé si une valeur invalide du paramètre `flags` est utilisée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec collator_sort()

    <?php
    $coll = collator_create( 'en_US' );
    $arr  = array( 'at', 'às', 'as' );

    var_export( $arr );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

L'exemple ci-dessus va afficher :

    array (
      0 => 'at',
      1 => 'às',
      2 => 'as',
    )array (
      0 => 'as',
      1 => 'às',
      2 => 'at',
    )

### Voir aussi

- Constantes Collator
- collator_asort() - Trie un tableau en conservant les clés, avec une collation
- collator_sort_with_sort_keys() - Trie un tableau et ses clés avec une collation

# Collator::sortWithSortKeys

# collator_sort_with_sort_keys

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sortWithSortKeys -- collator_sort_with_sort_keys — Trie un tableau et ses clés avec une collation

### Description

Style orienté objet

public function Collator::sortWithSortKeys(array `&$array`): bool

Style procédural

function collator_sort_with_sort_keys(Collator `$object`, array `&$array`): bool

Similaire à collator_sort(), mais utilise le tri de clé ICU de ucol_getSortKey() pour obtenir plus de vitesse sur les grands tableaux.

### Liste de paramètres

`object`

  Objet Collator.

`array`

  tableau de chaînes à trier

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec collator_sort_with_sort_keys()

    <?php
    $arr  = array( 'Köpfe', 'Kypper', 'Kopfe' );
    $coll = collator_create( 'sv' );

    collator_sort_with_sort_keys( $coll, $arr );
    var_export( $arr );
    ?>

L'exemple ci-dessus va afficher :

    array (
      0 => 'Kopfe',
      1 => 'Kypper',
      2 => 'Köpfe',
    )

### Voir aussi

- Constantes Collator
- collator_sort() - Trie un tableau avec une collation
- collator_asort() - Trie un tableau en conservant les clés, avec une collation

## Sommaire

- Collator::asort — Trie un tableau en conservant les clés, avec une collation
- Collator::compare — Compare deux chaînes Unicode
- Collator::__construct — Création d'un collator
- Collator::create — Création d'un collator
- Collator::getAttribute — Lit un attribut de collation
- Collator::getErrorCode — Lit la dernière erreur du collator
- Collator::getErrorMessage — Lit le dernier message d'erreur du collator
- Collator::getLocale — Lit le nom de la locale d'un collator
- Collator::getSortKey — Récupère la clé de tri pour une chaîne
- Collator::getStrength — Récupère la dureté de classement utilisé
- Collator::setAttribute — Configure l'attribut de collation
- Collator::setStrength — Définit la force de collation
- Collator::sort — Trie un tableau avec une collation
- Collator::sortWithSortKeys — Trie un tableau et ses clés avec une collation

# La classe NumberFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introduction

Les programmes stockent et manipulent des nombres en utilisant une représentation locale, binaire et indépendante. Lors de l'affichage d'un nombre, il est converti en une version particulière. Par exemple, un nombre tel que 12345.67 s'écrit "12,345.67" aux USA, "12 345,67" en France et "12.345,67" en Allemagne.

En appelant les méthodes fournies par NumberFormatter, il est possible de formater les nombres, les montants de devises et les pourcentages, en fonction des conventions locales. NumberFormatter prend en compte les conventions, ce qui fait qu'il faut créer un nouvel objet NumberFormatter, pour chaque convention. Les méthodes de NumberFormatter, formatent des types primitifs comme des nombres décimaux, et produisent une chaîne de caractères.

Pour les monnaies, il est possible d'utiliser le format monétaire pour créer un formateur qui retourne une chaîne, avec le symbole de devise approprié. Bien entendu, NumberFormatter ne connait pas les taux de changes, ce qui fait que l'affichage sera fait, quel qu'en soit la devise demandée. Cela signifie que le même nombre aura différentes valeurs monétaires en fonction de la configuration locale. Par exemple, le nombre 9988776.65 s'affichera :

- 9 988 776,65 € en France
- 9.988.776,65 € en Allemagne
- $9,988,776.65 aux USA

Pour formater des pourcentages, il faut créer un formateur local, avec un type de format pourcentage. Avec ce formateur, une fraction décimale telle que 0.75 sera affichée 75%.

Pour des formatages plus complexes, comme des nombres écrits littéralement, des formateurs à règles sont utilisés.

## Synopsis de la classe

class NumberFormatter {
/* Constantes */
public const int PATTERN_DECIMAL;
public const int DECIMAL;
public const int DECIMAL_COMPACT_SHORT;
public const int DECIMAL_COMPACT_LONG;
public const int CURRENCY;
public const int PERCENT;
public const int SCIENTIFIC;
public const int SPELLOUT;
public const int ORDINAL;
public const int DURATION;
public const int PATTERN_RULEBASED;
public const int IGNORE;
public const int CURRENCY_ISO;
public const int CURRENCY_PLURAL;
public const int CURRENCY_ACCOUNTING;
public const int CASH_CURRENCY;
public const int CURRENCY_STANDARD;
public const int DEFAULT_STYLE;
public const int ROUND_CEILING;
public const int ROUND_FLOOR;
public const int ROUND_DOWN;
public const int ROUND_UP;
public const int ROUND_TOWARD_ZERO;
public const int ROUND_AWAY_FROM_ZERO;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFODD;
public const int ROUND_HALFDOWN;
public const int ROUND_HALFUP;
public const int PAD_BEFORE_PREFIX;
public const int PAD_AFTER_PREFIX;
public const int PAD_BEFORE_SUFFIX;
public const int PAD_AFTER_SUFFIX;
public const int PARSE_INT_ONLY;
public const int GROUPING_USED;
public const int DECIMAL_ALWAYS_SHOWN;
public const int MAX_INTEGER_DIGITS;
public const int MIN_INTEGER_DIGITS;
public const int INTEGER_DIGITS;
public const int MAX_FRACTION_DIGITS;
public const int MIN_FRACTION_DIGITS;
public const int FRACTION_DIGITS;
public const int MULTIPLIER;
public const int GROUPING_SIZE;
public const int ROUNDING_MODE;
public const int ROUNDING_INCREMENT;
public const int FORMAT_WIDTH;
public const int PADDING_POSITION;
public const int SECONDARY_GROUPING_SIZE;
public const int SIGNIFICANT_DIGITS_USED;
public const int MIN_SIGNIFICANT_DIGITS;
public const int MAX_SIGNIFICANT_DIGITS;
public const int LENIENT_PARSE;
public const int POSITIVE_PREFIX;
public const int POSITIVE_SUFFIX;
public const int NEGATIVE_PREFIX;
public const int NEGATIVE_SUFFIX;
public const int PADDING_CHARACTER;
public const int CURRENCY_CODE;
public const int DEFAULT_RULESET;
public const int PUBLIC_RULESETS;
public const int DECIMAL_SEPARATOR_SYMBOL;
public const int GROUPING_SEPARATOR_SYMBOL;
public const int PATTERN_SEPARATOR_SYMBOL;
public const int PERCENT_SYMBOL;
public const int ZERO_DIGIT_SYMBOL;
public const int DIGIT_SYMBOL;
public const int MINUS_SIGN_SYMBOL;
public const int PLUS_SIGN_SYMBOL;
public const int CURRENCY_SYMBOL;
public const int INTL_CURRENCY_SYMBOL;
public const int MONETARY_SEPARATOR_SYMBOL;
public const int EXPONENTIAL_SYMBOL;
public const int PERMILL_SYMBOL;
public const int PAD_ESCAPE_SYMBOL;
public const int INFINITY_SYMBOL;
public const int NAN_SYMBOL;
public const int SIGNIFICANT_DIGIT_SYMBOL;
public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;
public const int TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* Méthodes */
public function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function setTextAttribute(int `$attribute`, string `$value`): bool
}

## Constantes pré-définies

## Types de format

Ces styles sont utilisés par numfmt_create() pour définir le type de formateur.

`NumberFormatter::PATTERN_DECIMAL` int
  Format décimal défini par un modèle
`NumberFormatter::DECIMAL` int
  Format décimal
`NumberFormatter::DECIMAL_COMPACT_SHORT` int
  Format décimal exprimé en notation compacte (forme courte), par exemple « 23K », « 45B ». Disponible à partir de PHP 8.5.0 et ICU 56.
`NumberFormatter::DECIMAL_COMPACT_LONG` int
  Format décimal exprimé en notation compacte (forme longue), par exemple « 23 thousand », « 45 billion ». Disponible à partir de PHP 8.5.0 et ICU 56.
`NumberFormatter::CURRENCY` int
  Format monétaire
`NumberFormatter::CURRENCY_ISO` int
  Format monétaire ISO (par exemple, « USD1.00 »). Disponible à partir de PHP 8.5.0.
`NumberFormatter::CURRENCY_PLURAL` int
  Format monétaire pluralisé (par exemple, « 1.00 US dollar » et « 3.00 US dollars »). Disponible à partir de PHP 8.5.0.
`NumberFormatter::CASH_CURRENCY` int
  Symbole monétaire pour l'utilisation en espèces, par exemple « NT$3 » au lieu de « NT$3.23 ». Disponible à partir de PHP 8.5.0 et ICU 54.
`NumberFormatter::CURRENCY_STANDARD` int
  Symbole monétaire, par exemple « $1.00 », utilisant un style non comptable pour les valeurs négatives (par exemple le signe moins). Disponible à partir de PHP 8.5.0 et ICU 56.
`NumberFormatter::PERCENT` int
  Format pourcentage
`NumberFormatter::SCIENTIFIC` int
  Format scientifique
`NumberFormatter::SPELLOUT` int
  Format littéral, basé sur des règles
`NumberFormatter::ORDINAL` int
  Format ordinal, basé sur des règles
`NumberFormatter::DURATION` int
  Format de durée, basé sur des règles
`NumberFormatter::PATTERN_RULEBASED` int
  Format de modèle, basé sur des règles
`NumberFormatter::CURRENCY_ACCOUNTING` int
  Format monétaire pour la comptabilité, par exemple, `($3.00)` pour un montant de devise négatif au lieu de `-$3.00`. Disponible à partir de PHP 7.4.1 et ICU 53.
`NumberFormatter::DEFAULT_STYLE` int
  Format par défaut pour les conventions locales
`NumberFormatter::IGNORE` int
  Alias de PATTERN_DECIMAL

## Spécificateurs de format de nombre

Ces constantes définissent la méthode d'analyse et de formatage des nombres. Elles doivent être utilisées comme arguments des fonctions numfmt_format() et numfmt_parse().

`NumberFormatter::TYPE_DEFAULT` int
  Dérive le type depuis le type de variable
`NumberFormatter::TYPE_INT32` int
  Formate / analyse un entier 32 bits
`NumberFormatter::TYPE_INT64` int
  Formate / analyse un entier 64 bits
`NumberFormatter::TYPE_DOUBLE` int
  Formate / analyse un nombre décimal
`NumberFormatter::TYPE_CURRENCY` int
  Formate / analyse une valeur monétaire. Obsolète à partir de PHP 8.3.0

## Attributs de format de nombre

Attributs de formats de nombre utilisés par numfmt_get_attribute() et numfmt_set_attribute().

`NumberFormatter::PARSE_INT_ONLY` int
  Analyse uniquement les entiers.
`NumberFormatter::GROUPING_USED` int
  Séparateur de groupes.
`NumberFormatter::DECIMAL_ALWAYS_SHOWN` int
  Affiche toujours une virgule décimale.
`NumberFormatter::MAX_INTEGER_DIGITS` int
  Nombre maximal de chiffres.
`NumberFormatter::MIN_INTEGER_DIGITS` int
  Nombre minimal de chiffres.
`NumberFormatter::INTEGER_DIGITS` int
  Nombre de chiffres.
`NumberFormatter::MAX_FRACTION_DIGITS` int
  Nombre maximal de décimales.
`NumberFormatter::MIN_FRACTION_DIGITS` int
  Nombre minimal de décimales.
`NumberFormatter::FRACTION_DIGITS` int
  Nombre de décimales.
`NumberFormatter::MULTIPLIER` int
  Multiplicateur.
`NumberFormatter::GROUPING_SIZE` int
  Taille de regroupement.
`NumberFormatter::ROUNDING_MODE` int
  Mode d'arrondi.
`NumberFormatter::ROUNDING_INCREMENT` int
  Incrément d'arrondi.
`NumberFormatter::FORMAT_WIDTH` int
  La largeur de complément pour le formatage d'un nombre.
`NumberFormatter::PADDING_POSITION` int
  La position à laquelle le complément se fait. Voir les constantes de complément pour avoir les différentes valeurs possibles.
`NumberFormatter::SECONDARY_GROUPING_SIZE` int
  Taille secondaire de groupement.
`NumberFormatter::SIGNIFICANT_DIGITS_USED` int
  Utilise les chiffres significatifs.
`NumberFormatter::MIN_SIGNIFICANT_DIGITS` int
  Nombre minimum de chiffres significatifs.
`NumberFormatter::MAX_SIGNIFICANT_DIGITS` int
  Nombre maximum de chiffres significatifs.
`NumberFormatter::LENIENT_PARSE` int
  Mode d'analyse utilisé par les formats à règles.

## Attributs de texte de format de nombre

Attributs de texte pour les formats de nombres, utilisés par numfmt_get_text_attribute() et numfmt_set_text_attribute().

`NumberFormatter::POSITIVE_PREFIX` int
  Préfixe positif.
`NumberFormatter::POSITIVE_SUFFIX` int
  Suffixe positif.
`NumberFormatter::NEGATIVE_PREFIX` int
  Préfixe négatif.
`NumberFormatter::NEGATIVE_SUFFIX` int
  Suffixe négatif.
`NumberFormatter::PADDING_CHARACTER` int
  Le caractère à utiliser pour compléter les formats jusqu'à la taille.
`NumberFormatter::CURRENCY_CODE` int
  Le code de devise ISO.
`NumberFormatter::DEFAULT_RULESET` int
  Le jeu de règles par défaut. Il est uniquement utilisable avec les formateurs à règles.
`NumberFormatter::PUBLIC_RULESETS` int
  Le jeu de règles publiques. Ceci est uniquement disponible avec les formateurs à règles. C'est un attribut en lecture seule. Les règles publiques sont retournées sous forme d'une seule chaîne, et chaque règle est délimitée par un point-virgule ';'.

## Spécification des Symboles de Format

Les symboles de format utilisés par numfmt_get_symbol() et numfmt_set_symbol().

`NumberFormatter::DECIMAL_SEPARATOR_SYMBOL` int
  Le séparateur décimal.
`NumberFormatter::GROUPING_SEPARATOR_SYMBOL` int
  Le séparateur de groupes.
`NumberFormatter::PATTERN_SEPARATOR_SYMBOL` int
  Le modèle de séparateur.
`NumberFormatter::PERCENT_SYMBOL` int
  Le signe de pourcentage.
`NumberFormatter::ZERO_DIGIT_SYMBOL` int
  Zéro.
`NumberFormatter::DIGIT_SYMBOL` int
  Un caractère représentant un chiffre dans un modèle.
`NumberFormatter::MINUS_SIGN_SYMBOL` int
  Le signe moins.
`NumberFormatter::PLUS_SIGN_SYMBOL` int
  Le signe plus.
`NumberFormatter::CURRENCY_SYMBOL` int
  Le symbole de devise.
`NumberFormatter::INTL_CURRENCY_SYMBOL` int
  Le symbole international de devise.
`NumberFormatter::MONETARY_SEPARATOR_SYMBOL` int
  Le séparateur monétaire.
`NumberFormatter::EXPONENTIAL_SYMBOL` int
  Le symbole d'exponentiel.
`NumberFormatter::PERMILL_SYMBOL` int
  Le symbole par mille.
`NumberFormatter::PAD_ESCAPE_SYMBOL` int
  Le caractère de protection des symboles.
`NumberFormatter::INFINITY_SYMBOL` int
  Le symbole de l'infini.
`NumberFormatter::NAN_SYMBOL` int
  Le symbole "n'est pas un nombre".
`NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL` int
  Le symbole des chiffres significatifs.
`NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL` int
  Le séparateur de groupes monétaires.

## Modes d'arrondi

Les modes d'arrondi utilisés par les fonctions numfmt_get_attribute() et numfmt_set_attribute() avec l'attribut `NumberFormatter::ROUNDING_MODE`.

`NumberFormatter::ROUND_AWAY_FROM_ZERO`
  Alias de `NumberFormatter::ROUND_UP`.
`NumberFormatter::ROUND_CEILING`
  Mode d'arrondi vers l'infini positif.
`NumberFormatter::ROUND_DOWN` int
  Mode d'arrondi vers zéro.
`NumberFormatter::ROUND_FLOOR` int
  Mode d'arrondi vers l'infini négatif.
`NumberFormatter::ROUND_HALFDOWN` int
  Mode d'arrondi vers le plus proche entier, à moins qu'ils soient équidistants : arrondi inférieur dans ce cas.
`NumberFormatter::ROUND_HALFEVEN` int
  Mode d'arrondi vers le plus proche entier, à moins qu'ils soient équidistants : arrondi vers le nombre pair dans ce cas.
`NumberFormatter::ROUND_HALFODD`
  Mode d’arrondi vers le « voisin impair ».
`NumberFormatter::ROUND_HALFUP`
  Mode d'arrondi vers le plus proche entier, à moins qu'ils soient équidistants : arrondi supérieur dans ce cas.
`NumberFormatter::ROUND_TOWARD_ZERO`
  Alias de `NumberFormatter::ROUND_DOWN`.
`NumberFormatter::ROUND_UP` int
  Mode d'arrondi qui éloigne de zéro.

## Spécificateurs de rembourrage

Valeurs de compléments utilisés par numfmt_get_attribute() et numfmt_set_attribute() avec l'attribut `NumberFormatter::PADDING_POSITION`.

`NumberFormatter::PAD_AFTER_PREFIX` int
  Caractères de compléments ajoutés après le préfixe.
`NumberFormatter::PAD_AFTER_SUFFIX` int
  Caractères de compléments ajoutés après le suffixe.
`NumberFormatter::PAD_BEFORE_PREFIX` int
  Caractères de compléments ajoutés avant le préfixe.
`NumberFormatter::PAD_BEFORE_SUFFIX` int
  Caractères de compléments ajoutés avant le suffixe.

## Voir aussi

- » Documentation de formatage ICU
- » Formateurs de nombres ICU
- » Formateur de nombres décimaux ICU
- » Formateurs à règles d'ICU

## Historique

Version | Description
--- | ---
8.5.0 | Ajout de `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY`, `NumberFormatter::CURRENCY_STANDARD`.
8.4.0 | Les constantes de classe sont maintenant typées.

# NumberFormatter::create

# numfmt_create

# NumberFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::create -- numfmt_create -- NumberFormatter::__construct — Crée un formateur de nombre

### Description

Style orienté objet (méthode)

public static function NumberFormatter::create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Style procédural

function numfmt_create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Style orienté objet (constructeur)

public function NumberFormatter::__construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)

Crée un formateur de nombre

### Liste de paramètres

`locale`

  La locale avec laquelle les nombres seront formatés (c.-à-d. en_CA).

`style`

  Le style de format, une des constantes de style de format. Si `NumberFormatter::PATTERN_DECIMAL` ou `NumberFormatter::PATTERN_RULEBASED` est utilisé alors le format de nombre est ouvert avec le modèle fourni, qui doit être compatible avec la syntaxe décrite par la » documentation ICU DecimalFormat ou » documentation ICU RuleBasedNumberFormat, respectivement.

`pattern`

  La chaîne de modèle, en fonction du style de format choisi.

### Valeurs de retour

Retourne un objet NumberFormatter ou `null` en cas d'erreur.

### Erreurs / Exceptions

Une ValueError est levée si `locale` est invalide.

### Historique

Version | Description
--- | ---
8.4.0 | Une ValueError est levée si `locale` est invalide.
8.0.0 | `pattern` est désormais nullable.

### Exemples

Exemple #1 Exemple avec numfmt_create(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    $fmt = numfmt_create( 'it', NumberFormatter::SPELLOUT );
    echo numfmt_format($fmt, 1142)."\n";
    ?>

Exemple #2 Exemple avec NumberFormatter::create(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt = new NumberFormatter( 'it', NumberFormatter::SPELLOUT );
    echo $fmt->format(1142)."\n";
    ?>

L'exemple ci-dessus va afficher :

    1.234.567,891
    millicentoquarantadue

### Voir aussi

- numfmt_format() - Formate un nombre
- numfmt_parse() - Analyse un nombre

# NumberFormatter::format

# numfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::format -- numfmt_format — Formate un nombre

### Description

Style orienté objet

public function NumberFormatter::format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Style procédural

function numfmt_format(NumberFormatter `$formatter`, int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Formate une valeur numérique, selon les règles du formateur.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`num`

  La valeur à formater. Ce peut être un int ou un float. Les autres valeurs seront converties en valeur numérique avant le formatage.

`type`

  Le type de format. Il est à noter que `NumberFormatter::TYPE_CURRENCY` n'est pas pris en charge ; utiliser NumberFormatter::formatCurrency() à la place.

### Valeurs de retour

Retourne la chaîne contenant la valeur formatée, ou `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec numfmt_format(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    var_dump($data);
    ?>

Exemple #2 Exemple avec numfmt_format(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $data = $fmt->format(1234567.891234567890000);
    var_dump($data);
    ?>

L'exemple ci-dessus va afficher :

    string(13) "1.234.567,891"

### Notes

> Note:

> Les formats réalisables par cette méthode de formatage ne peuvent pas utiliser pleinement les possibilités de la bibliothèque ICU sous-jacente, par exemple le formatage de la monnaie avec un symbole monétaire court.

> Pour les utiliser pleinement, utiliser msgfmt_format_message().

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_format_currency() - Formate une valeur monétaire
- numfmt_parse() - Analyse un nombre
- msgfmt_format_message() - Formate rapidement un message

# NumberFormatter::formatCurrency

# numfmt_format_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::formatCurrency -- numfmt_format_currency — Formate une valeur monétaire

### Description

Style orienté objet

public function NumberFormatter::formatCurrency(float `$amount`, string `$currency`): string|false

Style procédural

function numfmt_format_currency(NumberFormatter `$formatter`, float `$amount`, string `$currency`): string|false

Formate une valeur monétaire, en fonction des règles du formateur.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`amount`

  La valeur numérique.

`currency`

  Le code à trois lettres ISO 4217 de la devise à utiliser.

### Valeurs de retour

La chaîne représentant la valeur monétaire formatée, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec numfmt_format_currency(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    $fmt = numfmt_create( 'ru_RU', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    ?>

Exemple #2 Exemple avec numfmt_format_currency(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    $fmt = new NumberFormatter( 'ru_RU', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    ?>

L'exemple ci-dessus va afficher :

    1.234.567,89 €
    1.234.567,89 RUR
    1 234 567,89€
    1 234 567,89р.

### Notes

> Note:

> Les formats réalisables par cette méthode de formatage ne peuvent pas utiliser pleinement les possibilités de la bibliothèque ICU sous-jacente, par exemple le formatage de la monnaie avec un symbole monétaire court.

> Pour les utiliser pleinement, utiliser msgfmt_format_message().

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_format() - Formate un nombre
- numfmt_parse_currency() - Analyse un nombre monétaire
- msgfmt_format_message() - Formate rapidement un message

# NumberFormatter::getAttribute

# numfmt_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getAttribute -- numfmt_get_attribute — Lit un attribut

### Description

Style orienté objet

public function NumberFormatter::getAttribute(int `$attribute`): int|float|false

Style procédural

function numfmt_get_attribute(NumberFormatter `$formatter`, int `$attribute`): int|float|false

Lit un attribut numérique du formateur. Un exemple d'attribut numérique est le nombre de chiffres de la partie entière que le formateur va produire.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`attribute`

  La constante d'attribut, l'une de la liste des attributs numériques.

### Valeurs de retour

Retourne la valeur de l'attribut, en cas de succès, et `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec numfmt_get_attribute(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Décimales :  ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Décimales :  ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemple #2 Exemple avec numfmt_get_attribute(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Décimales :  ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Décimales :  ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

L'exemple ci-dessus va afficher :

    Décimales :  3
    1.234.567,891
    Décimales :  2
    1.234.567,89

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_get_text_attribute() - Lit un attribut textuel
- numfmt_set_attribute() - Affecte un attribut du formateur

# NumberFormatter::getErrorCode

# numfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorCode -- numfmt_get_error_code — Lit le dernier code d'erreur du formateur

### Description

Style orienté objet

public function NumberFormatter::getErrorCode(): int

Style procédural

function numfmt_get_error_code(NumberFormatter `$formatter`): int

Lit le code d'erreur généré par la dernière fonction du formateur.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

### Valeurs de retour

Retourne le code d'erreur du dernier appel au formateur.

### Exemples

Exemple #1 Exemple avec numfmt_get_error_code(), Style procédural

    <?php
    $fmt  = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    if (intl_is_failure(numfmt_get_error_code($fmt))) {
        echo 'Formatter error';
    }
    ?>

Exemple #2 Exemple avec numfmt_get_error_code(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    if (intl_is_failure($fmt->getErrorCode())) {
        echo 'Formatter error';
    }
    ?>

### Voir aussi

- numfmt_get_error_message() - Lit le dernier message d'erreur du formateur
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_is_failure() - Vérifie si un code d'erreur indique un échec

# NumberFormatter::getErrorMessage

# numfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorMessage -- numfmt_get_error_message — Lit le dernier message d'erreur du formateur

### Description

Style orienté objet

public function NumberFormatter::getErrorMessage(): string

Style procédural

function numfmt_get_error_message(NumberFormatter `$formatter`): string

Lit le message d'erreur généré par la dernière fonction du formateur.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

### Valeurs de retour

Retourne le message d'erreur du dernier appel au formateur.

### Exemples

Exemple #1 Exemple avec numfmt_get_error_message(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    if(intl_is_failure(numfmt_get_error_code($fmt))) {
        report_error("Erreur de formateur");
    }
    ?>

Exemple #2 Exemple avec numfmt_get_error_message(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    if(intl_is_failure($fmt->getErrorCode())) {
        report_error("Erreur de formateur");
    }
    ?>

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_is_failure() - Vérifie si un code d'erreur indique un échec

# NumberFormatter::getLocale

# numfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getLocale -- numfmt_get_locale — Lit la locale du formateur

### Description

Style orienté objet

public function NumberFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Style procédural

function numfmt_get_locale(NumberFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Lit le nom de la locale du formateur.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`type`

  Il est possible de choisir entre une valeur valide ou une valeur littérale `Locale::VALID_LOCALE`, `Locale::ACTUAL_LOCALE`, respectivement). La valeur par défaut est la valeur littérale.

### Valeurs de retour

Le nom de la locale utilisée pour créer le formateur, ou `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec numfmt_get_locale(), Style procédural

    <?php
    $req     = 'fr_FR_PARIS';
    $fmt     = numfmt_create( $req,  NumberFormatter::DECIMAL);
    $res_val = numfmt_get_locale( $fmt, Locale::VALID_LOCALE );
    $res_act = numfmt_get_locale( $fmt, Locale::ACTUAL_LOCALE );
    printf( "Nom de la locale demandée : %s\nNom valide de la locale : %s\nValeur littérale de la locale : %s\n",
             $req, $res_val, $res_act );
    ?>

L'exemple ci-dessus va afficher :

    Nom de la locale demandée : fr_FR_PARIS
    Nom valide de la locale : fr_FR
    Valeur littérale de la locale : fr

### Voir aussi

- numfmt_create() - Crée un formateur de nombre
- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur

# NumberFormatter::getPattern

# numfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getPattern -- numfmt_get_pattern — Lit le modèle du formateur

### Description

Style orienté objet

public function NumberFormatter::getPattern(): string|false

Style procédural

function numfmt_get_pattern(NumberFormatter `$formatter`): string|false

Extrait le modèle utilisé par le formateur.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

### Valeurs de retour

La chaîne de caractères de modèle, qui est utilisée par le formateur, ou `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec numfmt_get_pattern(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Modèle : ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Modèle : ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemple #2 Exemple avec numfmt_get_pattern(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Modèle : ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Modèle : ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

L'exemple ci-dessus va afficher :

    Modèle : #,##0.###
    1.234.567,891
    Modèle : #0.# kg
    1234567,9 kg

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_set_pattern() - Configure le modèle du formateur
- numfmt_create() - Crée un formateur de nombre

# NumberFormatter::getSymbol

# numfmt_get_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getSymbol -- numfmt_get_symbol — Lit la valeur du symbole

### Description

Style orienté objet

public function NumberFormatter::getSymbol(int `$symbol`): string|false

Style procédural

function numfmt_get_symbol(NumberFormatter `$formatter`, int `$symbol`): string|false

Lit le symbole associé au formateur. Le formateur utilise des symboles pour représenter des caractères dépendant des conventions locales, comme le signe de pourcentage. Cette API n'est pas supportée par les formateurs à base de règles.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`symbol`

  La constante de symbole, une dans la liste des constantes de symboles de formats.

### Valeurs de retour

La chaîne de symbole ou `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec numfmt_get_symbol(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Séparateur : ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Séparateur : ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemple #2 Exemple avec numfmt_get_symbol(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Séparateur : ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Séparateur : ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

L'exemple ci-dessus va afficher :

    Séparateur : .
    1.234.567,891
    Séparateur : *
    1*234*567,891

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_set_symbol() - Configure le symbole du formateur

# NumberFormatter::getTextAttribute

# numfmt_get_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getTextAttribute -- numfmt_get_text_attribute — Lit un attribut textuel

### Description

Style orienté objet

public function NumberFormatter::getTextAttribute(int `$attribute`): string|false

Style procédural

function numfmt_get_text_attribute(NumberFormatter `$formatter`, int `$attribute`): string|false

Lit un attribut textuel associé à un formateur. Un exemple d'attribut textuel est le suffixe pour les nombres positifs. Si le formateur ne comprend pas cet attribut, une erreur `U_UNSUPPORTED_ERROR` est produite. Les formateurs à règles ne comprennent que `NumberFormatter::DEFAULT_RULESET` et `NumberFormatter::PUBLIC_RULESETS`.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`attribute`

  L'identifiant de l'attribut : une des constantes d'attribut textuel.

### Valeurs de retour

Retourne la valeur de l'attribut en cas de succès, et `false` sinon.

### Exemples

Exemple #1 Exemple avec numfmt_get_text_attribute(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Préfixe : ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Préfixe : ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Exemple #2 Exemple avec numfmt_get_text_attribute(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Préfixe : ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Préfixe : ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

L'exemple ci-dessus va afficher :

    Préfixe : -
    -1.234.567,891
    Préfixe : MINUS
    MINUS1.234.567,891

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_get_attribute() - Lit un attribut
- numfmt_set_text_attribute() - Modifie un attribut texte

# NumberFormatter::parse

# numfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parse -- numfmt_parse — Analyse un nombre

### Description

Style orienté objet

public function NumberFormatter::parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false

Style procédural

function numfmt_parse(
NumberFormatter `$formatter`,
string `$string`,
int `$type` = `NumberFormatter::TYPE_DOUBLE`,
int `&$offset` = `null`
): int|float|false

Analyse une chaîne et extrait un nombre, à l'aide des règles du formateur.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`string`

  La chaîne à analyser pour le nombre.

`type`

  Le type de format à utiliser. Par défaut, `NumberFormatter::TYPE_DOUBLE` est utilisé. Il est à noter que `NumberFormatter::TYPE_CURRENCY` n'est pas pris en charge ; utiliser NumberFormatter::parseCurrency() à la place.

`offset`

  La position de début d'analyse dans la chaîne. En retour, cette valeur contiendra la position de fin d'analyse.

### Valeurs de retour

La valeur de nombre analysé, ou `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec numfmt_parse(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo numfmt_parse($fmt, $num)."\n";
    echo numfmt_parse($fmt, $num, NumberFormatter::TYPE_INT32)."\n";
    ?>

Exemple #2 Exemple avec numfmt_parse(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo $fmt->parse($num)."\n";
    echo $fmt->parse($num, NumberFormatter::TYPE_INT32)."\n";
    ?>

L'exemple ci-dessus va afficher :

    1234567.891
    1234567

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_format() - Formate un nombre
- numfmt_parse_currency() - Analyse un nombre monétaire

# NumberFormatter::parseCurrency

# numfmt_parse_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parseCurrency -- numfmt_parse_currency — Analyse un nombre monétaire

### Description

Style orienté objet

public function NumberFormatter::parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false

Style procédural

function numfmt_parse_currency(
NumberFormatter `$formatter`,
string `$string`,
string `&$currency`,
int `&$offset` = `null`
): float|false

Analyse une chaîne dans un nombre flottant et une devise, à l'aide du formateur.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`currency`

  Le nom de la devise (le code 3 lettres ISO 4217).

`offset`

  La position de début d'analyse dans la chaîne. En retour, cette valeur contiendra la position de fin d'analyse.

### Valeurs de retour

Le nombre décimal ainsi lu, ou `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec numfmt_parse_currency(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "We have ".numfmt_parse_currency($fmt, $num, $curr)." in $curr\n";
    ?>

Exemple #2 Exemple avec numfmt_parse_currency(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "We have ".$fmt->parseCurrency($num, $curr)." in $curr\n";
    ?>

L'exemple ci-dessus va afficher :

    We have 1234567.89 in USD

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_parse() - Analyse un nombre
- numfmt_format_currency() - Formate une valeur monétaire

# NumberFormatter::setAttribute

# numfmt_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setAttribute -- numfmt_set_attribute — Affecte un attribut du formateur

### Description

Style orienté objet

public function NumberFormatter::setAttribute(int `$attribute`, int|float `$value`): bool

Style procédural

function numfmt_set_attribute(NumberFormatter `$formatter`, int `$attribute`, int|float `$value`): bool

Affecte un attribut numérique du formateur. Un exemple d'attribut numérique est le nombre de chiffres de la partie entière que le formateur va produire.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`attribute`

  L'identifiant d'attribut : une des constantes attributs numériques.

`value`

  La valeur de l'attribut.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec numfmt_set_attribute(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemple #2 Exemple avec numfmt_set_attribute(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

L'exemple ci-dessus va afficher :

    Digits: 3
    1.234.567,891
    Digits: 2
    1.234.567,89

Exemple #3 Utilisation de `NumberFormatter::ROUNDING_MODE` pour tronquer les valeurs

Par défaut, NumberFormatter arrondit les valeurs. En utilisant `NumberFormatter::ROUND_DOWN` comme `NumberFormatter::ROUNDING_MODE`, les valeurs sont tronquées au nombre de chiffres fractionnaires spécifié sans arrondi.

    <?php
    $fmt = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    $fmt->setAttribute(NumberFormatter::FRACTION_DIGITS, 2);

    echo "Mode par défaut d'arrondi:\n";
    echo $fmt->format(3.789), "\n"; // 3.79 (arrondi au dessus)
    echo $fmt->format(3.781), "\n"; // 3.78 (arrondi en dessous)

    $fmt->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_DOWN);

    echo "\nAvec ROUND_DOWN (tronquer):\n";
    echo $fmt->format(3.789), "\n"; // 3.78 (tronqué)
    echo $fmt->format(3.781), "\n"; // 3.78 (tronqué)
    ?>

L'exemple ci-dessus va afficher :

    Mode par défaut d'arrondi:
    3.79
    3.78

    Avec ROUND_DOWN (tronquer):
    3.78
    3.78

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_get_attribute() - Lit un attribut
- numfmt_set_text_attribute() - Modifie un attribut texte

# NumberFormatter::setPattern

# numfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setPattern -- numfmt_set_pattern — Configure le modèle du formateur

### Description

Style orienté objet

public function NumberFormatter::setPattern(string `$pattern`): bool

Style procédural

function numfmt_set_pattern(NumberFormatter `$formatter`, string `$pattern`): bool

Configure le modèle utilisé par le formateur. Ne peut pas être utilisé avec un formateur basé sur les règles.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`pattern`

  Le modèle, dans la syntaxe décrite dans la » documentation ICU DecimalFormat.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec numfmt_set_pattern(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Modèle : ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Modèle : ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemple #2 Exemple avec numfmt_set_pattern(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Modèle : ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Modèle : ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

L'exemple ci-dessus va afficher :

    Modèle : #,##0.###
    1.234.567,891
    Modèle : #0.# kg
    1234567,9 kg

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_create() - Crée un formateur de nombre
- numfmt_get_pattern() - Lit le modèle du formateur

# NumberFormatter::setSymbol

# numfmt_set_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setSymbol -- numfmt_set_symbol — Configure le symbole du formateur

### Description

Style orienté objet

public function NumberFormatter::setSymbol(int `$symbol`, string `$value`): bool

Style procédural

function numfmt_set_symbol(NumberFormatter `$formatter`, int `$symbol`, string `$value`): bool

Configure le symbole du formateur. Le formateur utilise le symbole pour caractériser des nombres, comme le pourcentage. Cette API n'est pas supportée pour les formateurs à base de règles.

### Liste de paramètres

`formatter`

  L'objet NumberFormatter.

`symbol`

  L'identifiant de symbole, parmi les constantes de symboles.

`value`

  Le texte du symbole.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec numfmt_set_symbol(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Séparateur décimal : ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Séparateur décimal : ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Exemple #2 Exemple avec numfmt_set_symbol(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Séparateur décimal : ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Séparateur décimal : ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

L'exemple ci-dessus va afficher :

    Séparateur décimal : .
    1.234.567,891
    Séparateur décimal : *
    1*234*567,891

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_get_symbol() - Lit la valeur du symbole

# NumberFormatter::setTextAttribute

# numfmt_set_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setTextAttribute -- numfmt_set_text_attribute — Modifie un attribut texte

### Description

Style orienté objet

public function NumberFormatter::setTextAttribute(int `$attribute`, string `$value`): bool

Style procédural

function numfmt_set_text_attribute(NumberFormatter `$formatter`, int `$attribute`, string `$value`): bool

Modifie l'attribut du texte associé au formateur. Un exemple d'attribut de texte est le suffixe des nombres positifs. Si le formateur ne comprend pas l'attribut, une erreur `U_UNSUPPORTED_ERROR` est produite. Les formateurs à base de règles ne comprennent que `NumberFormatter::DEFAULT_RULESET` et `NumberFormatter::PUBLIC_RULESETS`.

### Liste de paramètres

`formatter`

  Un objet NumberFormatter.

`attribute`

  Un spécificateur d'attribut : une des constantes d' attribut de texte.

`value`

  La valeur de l'attribut du texte.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec numfmt_set_text_attribute(), Style procédural

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Exemple #2 Exemple avec numfmt_set_text_attribute(), style POO

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

L'exemple ci-dessus va afficher :

    Prefix: -
    -1.234.567,891
    Prefix: MINUS
    MINUS1.234.567,891

### Voir aussi

- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur
- numfmt_get_text_attribute() - Lit un attribut textuel
- numfmt_set_attribute() - Affecte un attribut du formateur

## Sommaire

- NumberFormatter::create — Crée un formateur de nombre
- NumberFormatter::format — Formate un nombre
- NumberFormatter::formatCurrency — Formate une valeur monétaire
- NumberFormatter::getAttribute — Lit un attribut
- NumberFormatter::getErrorCode — Lit le dernier code d'erreur du formateur
- NumberFormatter::getErrorMessage — Lit le dernier message d'erreur du formateur
- NumberFormatter::getLocale — Lit la locale du formateur
- NumberFormatter::getPattern — Lit le modèle du formateur
- NumberFormatter::getSymbol — Lit la valeur du symbole
- NumberFormatter::getTextAttribute — Lit un attribut textuel
- NumberFormatter::parse — Analyse un nombre
- NumberFormatter::parseCurrency — Analyse un nombre monétaire
- NumberFormatter::setAttribute — Affecte un attribut du formateur
- NumberFormatter::setPattern — Configure le modèle du formateur
- NumberFormatter::setSymbol — Configure le symbole du formateur
- NumberFormatter::setTextAttribute — Modifie un attribut texte

# La classe Locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introduction

Une "Locale" est un identifiant utilisé pour représenter les comportements régionaux d'une API. Les locales PHP sont organisées et identifiées de la même manière que les CLDR de ICU (et que de nombreux autres éditeurs de système Unix, tels que Mac, Java, etc.). Les locales sont identifiées par les libellés de langage de la RFC 4646 (qui utilise des tirets et pas des soulignés) en plus de la notation traditionnelle avec des soulignés. Sauf contre-indication, les fonctions de cette classe sont capables d'utiliser les deux notations.

Exemple d'identifiants :

- en-US (Anglais, USA)
- zh-Hant-TW (Chinois, traditionnel, Taiwan)
- fr-CA, fr-FR (Français pour le Canada et la France, respectivement)

La classe Locale et les méthodes associées, sont utilisées pour interagir avec les identifiants locaux : pour vérifier qu'un identifiant est bien formé, valide, etc. Les extensions utilisées par CDR dans UAX #35 et héritées par ICU sont valides, et utilisées à chaque fois qu'elles peuvent l'être dans ICU.

Les locales ne peuvent pas être instanciées. Ce sont toutes des fonctions statiques.

La chaîne `null` ou vide permet d'obtenir la locale racine. La racine est l'équivalent de `"en_US_POSIX"` en CLDR. Les libellés de langage (et donc, les identifiants) sont insensibles à la casse. Il existe une fonction de canonicalisation qui permet d'obtenir la spécification exacte.

## Synopsis de la classe

class Locale {
/* Constantes */
public const int ACTUAL_LOCALE;
public const int VALID_LOCALE;
public const null DEFAULT_LOCALE = null;
public const string LANG_TAG;
public const string EXTLANG_TAG;
public const string SCRIPT_TAG;
public const string REGION_TAG;
public const string VARIANT_TAG;
public const string GRANDFATHERED_LANG_TAG;
public const string PRIVATE_TAG;
/* Méthodes */
public static function acceptFromHttp(string `$header`): string|false
public static function canonicalize(string `$locale`): ?string
public static function composeLocale(array `$subtags`): string|false
public static function filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool
public static function getAllVariants(string `$locale`): ?array
public static function getDefault(): string
public static function getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getKeywords(string `$locale`): array|false|null
public static function getPrimaryLanguage(string `$locale`): ?string
public static function getRegion(string `$locale`): ?string
public static function getScript(string `$locale`): ?string
public static function isRightToLeft( string `$locale` = "" ): bool
public static function lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string
public static function parseLocale(string `$locale`): ?array
public static function setDefault(string `$locale`): true
}

## Constantes pré-définies

Ces constantes définissent le comportement de Locale

`Locale::DEFAULT_LOCALE` null
  Utilisée comme paramètre de locale avec les méthodes des différentes classes affectées, telles que NumberFormatter. Cette constante fait qu'on utilise les valeurs par défaut.

Ces constantes décrivent le choix de la locale pour la méthode getLocale de différentes classes.

`Locale::ACTUAL_LOCALE` int
  La locale utilisée par les données entrantes.
`Locale::VALID_LOCALE` int
  C'est la locale la plus spécifique supportée par ICU.

## Sous-libellé de langue

Ces constantes définissent comment les Locales sont analysées ou composées. Elles doivent être utilisées comme clés dans un tableau d'arguments passé à locale_compose() et sont retournées par locale_parse() comme clés d'un array associatif.

`Locale::LANG_TAG` string
  Sous-libellé de langue
`Locale::EXTLANG_TAG` string
  Sous-libellé de langue étendu
`Locale::SCRIPT_TAG` string
  Sous-libellé de script
`Locale::REGION_TAG` string
  Sous-libellé de région
`Locale::VARIANT_TAG` string
  Sous-libellé de variante
`Locale::GRANDFATHERED_LANG_TAG` string
  Sous-libellé d'ascendant de langage
`Locale::PRIVATE_TAG` string
  Sous-libellé privé

## Voir aussi

- » RFC 4646 : libellés pour identifier les langues
- » RFC 4647 : Correspondance des balises de langue
- » Unicode CLDR Project:Common Locale Data Repository
- » IANA Language Subtags Registry
- » ICU User Guide : Locale
- » ICU Locale api

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.

# Locale::acceptFromHttp

# locale_accept_from_http

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::acceptFromHttp -- locale_accept_from_http — Devine la meilleure locale à partir de l'en-tête HTTP `"Accept-Language"`

### Description

Style orienté objet

public static function Locale::acceptFromHttp(string `$header`): string|false

Style procédural

function locale_accept_from_http(string `$header`): string|false

Essaie de trouver une locale qui peut satisfaire la liste de langue qui est demandée par l'en-tête HTTP `"Accept-Language"`.

### Liste de paramètres

`header`

  La chaîne contenant l'en-tête `"Accept-Language"`, au format de la RFC 2616.

### Valeurs de retour

L'identifiant de locale correspondant.

Retourne `false` quand la longueur de `header` dépasse `INTL_MAX_LOCALE_LEN`.

### Exemples

Exemple #1 Exemple avec locale_accept_from_http(), procédural

    <?php
    $locale = locale_accept_from_http($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

Exemple #2 Exemple avec locale_accept_from_http(), POO

    <?php
    $locale = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

L'exemple ci-dessus va afficher :

    en_US

### Voir aussi

- locale_lookup() - Recherche dans la liste la meilleure langue

# Locale::canonicalize

# locale_canonicalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::canonicalize -- locale_canonicalize — Canonise la chaîne représentant la locale

### Description

public static function Locale::canonicalize(string `$locale`): ?string

Canonise la chaîne représentant la locale passée au format ICU.

Ceci ne signifie pas nécessairement ou ne retourne pas une locale valide. C'est seulement une version de l'entrée qui a été canonisée selon les règles d'ICU.

Le comportement de cette fonction dépend de la version d'ICU utilisée par PHP (`INTL_ICU_VERSION`).

### Liste de paramètres

`locale`
  La chaîne de la locale originale

### Valeurs de retour

Chaîne canonisée dans la locale.

Retourne `null` quand la longueur de `locale` excède `INTL_MAX_LOCALE_LEN`.

### Exemples

Exemple #1 Exemple de locale_canonicalize()

    echo Locale::canonicalize('en-US.utf8') . "\n";
    echo Locale::canonicalize('totally-not-valid') . "\n";

Résultat de l'exemple ci-dessus est similaire à :

    en_US
    totally_NOT_VALID

# Locale::composeLocale

# locale_compose

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::composeLocale -- locale_compose — Retourne un identifiant de locale correct

### Description

Style orienté objet

public static function Locale::composeLocale(array `$subtags`): string|false

Style procédural

function locale_compose(array `$subtags`): string|false

Retourne un identifiant de locale correct, ordonné et délimité, avec les clés pour identifier les particularités régionales, et les valeurs associées à ces sous-locales.

### Liste de paramètres

`subtags`

  Un tableau contenant la liste des paires clé-valeurs, où les clés représentent les identifiants de sous-locales, et leur valeur associées sont la valeur des sous-tags.

  > Note:

  > Les sous-tags `'variant'` et `'private'` peuvent prendre jusqu'à 15 valeurs alors que `'extlang'` ne peut prendre qu'un maximum de 3 valeurs. Par exemple les variantes sont autorisées avec un suffixe allant de 0 à 14. Par conséquent, les clés du tableau sont `variant0`, `variant1`, …, `variant14`. Dans l'identifiant de locale retourné, les sous-tags sont ordonnés par suffixe, avec `variant0` suivi de `variant1` suivi de `variant2` et ainsi de suite.

  > Alternativement, les valeurs de `'variant'`, `'private'` et `'extlang'` peuvent être spécifiées en tant qu'un tableau sous une clé spécifique (e.g. `'variant'`). Dans ce cas aucune limite sur le nombre de sous-tags reconnus n'est appliquée.

### Valeurs de retour

L'identifiant de locale correspondant, ou `false` quand `subtags` est vide.

### Exemples

Exemple #1 Exemple avec locale_compose(), procédural

    <?php
    $arr = array(
        'language'=>'en',
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2'
    );
    echo locale_compose($arr);
    ?>

Exemple #2 Exemple avec locale_compose(), POO

    <?php
    $arr = array(
        'language'=>'en',
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2'
    );
    echo Locale::composeLocale($arr);
    ?>

L'exemple ci-dessus va afficher :

    Locale: en_Hans_CN_nedis_rozaj_x_prv1_prv2

Exemple #3 Limites des Sous-tags

Si `subtags` sont fournis en tant que clés différentes avec un suffixe numérique, les clés non supportées sont ignorées silencieusement (dans ce cas `'extlang3'`), et ordonnées dans le résultat par le suffixe numérique. Il n'y a pas de limites, si les sous-tags sont fournis en tant que tableau; leur ordre est comme donné.

    <?php
    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang3' => 'd',
        'extlang2' => 'c',
        'extlang1' => 'b',
        'extlang0' => 'a',
    );
    echo locale_compose($arr), PHP_EOL;
    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang'  => ['a', 'b', 'c', 'd'],
    );
    echo locale_compose($arr), PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    en_a_b_c_Hans_CN
    en_a_b_c_d_Hans_CN

### Voir aussi

- locale_parse() - Retourne les sous-éléments de la locale

# Locale::filterMatches

# locale_filter_matches

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::filterMatches -- locale_filter_matches — Vérifie si le tag de langue correspond à une locale

### Description

Style orienté objet

public static function Locale::filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Style procédural

function locale_filter_matches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Vérifie si le filtre `languageTag` correspond à la `locale` selon la RFC 4647, et son algorithme de filtrage simple.

### Liste de paramètres

`languageTag`

  Le tag de langue à vérifier

`locale`

  L'intervalle de langue cible

`canonicalize`

  Si `true`, les arguments seront convertis dans leur forme canonique avant la recherche.

### Valeurs de retour

`true` si `locale` accepte `languageTag`, et `false` sinon.

Retourne `null` quand la longueur de `locale` excède `INTL_MAX_LOCALE_LEN`.

### Exemples

Exemple #1 Exemple avec locale_filter_matches(), procédural

    <?php
    echo (locale_filter_matches('de-DEVA','de-DE', false)) ? "Correspond" : "Ne correspond pas";
    echo '; ';
    echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Correspond" : "Ne correspond pas";
    ?>

Exemple #2 Exemple avec locale_filter_matches(), POO

    <?php
    echo (Locale::filterMatches('de-DEVA','de-DE', false)) ? "Correspond" : "Ne correspond pas";
    echo '; ';
    echo (Locale::filterMatches('de-DE-1996','de-DE', false)) ? "Correspond" : "Ne correspond pas";
    ?>

L'exemple ci-dessus va afficher :

    Ne correspond pas; Correspond

### Voir aussi

- locale_lookup() - Recherche dans la liste la meilleure langue

# Locale::getAllVariants

# locale_get_all_variants

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getAllVariants -- locale_get_all_variants — Liste toutes les variantes d'une locale

### Description

Style orienté objet

public static function Locale::getAllVariants(string `$locale`): ?array

Style procédural

function locale_get_all_variants(string `$locale`): ?array

Liste toutes les variantes d'une locale

### Liste de paramètres

`locale`

  La locale dont il faut extraire les variantes

### Valeurs de retour

Un tableau contenant la liste de toutes les variantes d'une locale, ou bien `null` si inexistant.

Retourne `null` quand la longueur de `locale` excède `INTL_MAX_LOCALE_LEN`.

### Exemples

Exemple #1 Exemple avec locale_get_all_variants(), procédural

    <?php
    $arr = locale_get_all_variants('sl_IT_NEDIS_ROJAZ_1901');
    var_export( $arr );
    ?>

Exemple #2 Exemple avec locale_get_all_variants(), POO

    <?php
    $arr = Locale::getAllVariants('sl_IT_NEDIS_ROJAZ_1901');
    var_export( $arr );
    ?>

L'exemple ci-dessus va afficher :

    array (
        0 => 'NEDIS',
        1 => 'ROJAZ',
        2 => '1901',
    )

### Voir aussi

- locale_get_primary_language() - Lit la langue principale de la locale
- locale_get_script() - Retourne un code pour le script de la locale
- locale_get_region() - Retourne un code pour la région de la locale

# Locale::getDefault

# locale_get_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDefault -- locale_get_default — Lit la valeur par défaut d'une locale pour la variable globale 'default_locale'

### Description

Style orienté objet

public static function Locale::getDefault(): string

Style procédural

function locale_get_default(): string

Lit la valeur par défaut d'une locale pour la variable globale 'default_locale'. Au moment de l'initialisation de PHP, cette valeur est extraite de la directive 'intl.default_locale' dans php.ini, si cette valeur existe, et de la fonction ICU uloc_getDefault() autrement.

### Liste de paramètres

### Valeurs de retour

La locale par défaut pour l'exécution.

### Exemples

Exemple #1 Exemple avec locale_get_default(), procédural

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo locale_get_default();
    echo '; ';
    locale_set_default('fr');
    echo locale_get_default();
    ?>

Exemple #2 Exemple avec locale_get_default(), POO

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo Locale::getDefault();
    echo '; ';
    Locale::setDefault('fr');
    echo Locale::getDefault();
    ?>

L'exemple ci-dessus va afficher :

    de-DE; fr

### Voir aussi

- locale_set_default() - Configure la locale par défaut

# Locale::getDisplayLanguage

# locale_get_display_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayLanguage -- locale_get_display_language — Retourne un nom approprié pour l'affichage d'un nom de langue

### Description

Style orienté objet

public static function Locale::getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false

Style procédural

function locale_get_display_language(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retourne un nom approprié pour l'affichage d'un nom de langue. Si la valeur `null` est passée en argument, la locale par défaut est utilisée.

### Liste de paramètres

`locale`

  La locale dont il faut retourner le nom de langue

`displayLocale`

  Un format optionnel pour l'affichage du nom de langue.

### Valeurs de retour

Le nom de la langue à afficher pour la `locale`, dans le format défini par `displayLocale`, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `displayLocale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec locale_get_display_language(), procédural

    <?php
    echo locale_get_display_language('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'de');
    ?>

Exemple #2 Exemple avec locale_get_display_language(), POO

    <?php
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'de');
    ?>

L'exemple ci-dessus va afficher :

    Slovenian;
    slov\xc3\xa8ne;
    Slowenisch

### Voir aussi

- locale_get_display_name() - Retourne un nom d'affichage correct pour une locale
- locale_get_display_script() - Retourne le nom du script de la locale
- locale_get_display_region() - Retourne un nom pour la région de la locale
- locale_get_display_variant() - Retourne un nom pour la variante de la locale

# Locale::getDisplayName

# locale_get_display_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayName -- locale_get_display_name — Retourne un nom d'affichage correct pour une locale

### Description

Style orienté objet

public static function Locale::getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false

Style procédural

function locale_get_display_name(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retourne un nom d'affichage correct pour une locale. Si `locale` est `null`, c'est la locale par défaut qui est utilisée.

### Liste de paramètres

`locale`

  La locale dont il faut retourner un nom d'affichage.

`displayLocale`

  Un format d'affichage optionnel

### Valeurs de retour

Le nom d'affichage de la locale, au format donné par `displayLocale`, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `displayLocale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec locale_get_display_name(), procédural

    <?php
    echo locale_get_display_name('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'de');
    ?>

Exemple #2 Exemple avec locale_get_display_name(), POO

    <?php
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'de');
    ?>

L'exemple ci-dessus va afficher :

    Slovenian (Latin, Italy, Natisone dialect);
    slov\xc3\xa8ne (latin, Italie, dialecte de Natisone);
    Slowenisch (Lateinisch, Italien, NEDIS)

### Voir aussi

- locale_get_display_language() - Retourne un nom approprié pour l'affichage d'un nom de langue
- locale_get_display_script() - Retourne le nom du script de la locale
- locale_get_display_region() - Retourne un nom pour la région de la locale
- locale_get_display_variant() - Retourne un nom pour la variante de la locale

# Locale::getDisplayRegion

# locale_get_display_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayRegion -- locale_get_display_region — Retourne un nom pour la région de la locale

### Description

Style orienté objet

public static function Locale::getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false

Style procédural

function locale_get_display_region(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retourne un nom pour la région de la locale. Si `null` est passé, la locale par défaut est utilisée.

### Liste de paramètres

`locale`

  La locale dont il faut extraire le nom de la région.

`displayLocale`

  Un format optionnel pour afficher le nom de la région.

### Valeurs de retour

Le nom de la région de la `locale`, au format `displayLocale`, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `displayLocale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec locale_get_display_region(), procédural

    <?php
    echo locale_get_display_region('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'de');
    ?>

Exemple #2 Exemple avec locale_get_display_region(), POO

    <?php
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'de');
    ?>

L'exemple ci-dessus va afficher :

    Italy;
    Italie;
    Italien

### Voir aussi

- locale_get_display_name() - Retourne un nom d'affichage correct pour une locale
- locale_get_display_language() - Retourne un nom approprié pour l'affichage d'un nom de langue
- locale_get_display_script() - Retourne le nom du script de la locale
- locale_get_display_variant() - Retourne un nom pour la variante de la locale

# Locale::getDisplayScript

# locale_get_display_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayScript -- locale_get_display_script — Retourne le nom du script de la locale

### Description

Style orienté objet

public static function Locale::getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false

Style procédural

function locale_get_display_script(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retourne le nom du script de la locale. Si `null` est passé, la locale par défaut est utilisée.

### Liste de paramètres

`locale`

  La locale dont il faut retourner le script.

`displayLocale`

  Un format optionnel pour afficher le nom du script.

### Valeurs de retour

Affiche le nom du script de la `locale` au format indiqué par `displayLocale`, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `displayLocale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec locale_get_display_script(), procédural

    <?php
    echo locale_get_display_script('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'de');
    ?>

Exemple #2 Exemple avec locale_get_display_script(), POO

    <?php
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'de');
    ?>

L'exemple ci-dessus va afficher :

    Latin;
    latin;
    Lateinisch

### Voir aussi

- locale_get_display_name() - Retourne un nom d'affichage correct pour une locale
- locale_get_display_language() - Retourne un nom approprié pour l'affichage d'un nom de langue
- locale_get_display_region() - Retourne un nom pour la région de la locale
- locale_get_display_variant() - Retourne un nom pour la variante de la locale

# Locale::getDisplayVariant

# locale_get_display_variant

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayVariant -- locale_get_display_variant — Retourne un nom pour la variante de la locale

### Description

Style orienté objet

public static function Locale::getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Style procédural

function locale_get_display_variant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Retourne un nom pour la variante de la locale. Si `null` est passé, la locale par défaut est utilisée.

### Liste de paramètres

`locale`

  La locale dont il faut extraire le nom de la variante.

`displayLocale`

  Un format optionnel pour afficher le nom de la variante.

### Valeurs de retour

Le nom de la variante de la `locale`, au format `displayLocale`, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `displayLocale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec locale_get_display_variant(), procédural

    <?php
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'de');
    ?>

Exemple #2 Exemple avec locale_get_display_variant(), POO

    <?php
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'de');
    ?>

L'exemple ci-dessus va afficher :

    Natisone dialect;
    dialecte de Natisone;
    NEDIS

### Voir aussi

- locale_get_display_name() - Retourne un nom d'affichage correct pour une locale
- locale_get_display_language() - Retourne un nom approprié pour l'affichage d'un nom de langue
- locale_get_display_script() - Retourne le nom du script de la locale
- locale_get_display_region() - Retourne un nom pour la région de la locale

# Locale::getKeywords

# locale_get_keywords

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getKeywords -- locale_get_keywords — Lit les mots-clé de la locale

### Description

Style orienté objet

public static function Locale::getKeywords(string `$locale`): array|false|null

Style procédural

function locale_get_keywords(string `$locale`): array|false|null

Lit les mots-clé de la locale.

### Liste de paramètres

`locale`

  La locale dont il faut extraire les mots-clé.

### Valeurs de retour

Un tableau associatif contenant les paires clé-valeur pour cette locale.

Retourne `null` quand la longueur de `locale` excède `INTL_MAX_LOCALE_LEN`.

### Exemples

Exemple #1 Exemple avec locale_get_keywords(), procédural

    <?php
    $keywords_arr = locale_get_keywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

Exemple #2 Exemple avec locale_get_keywords(), POO

    <?php
    $keywords_arr = Locale::getKeywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

L'exemple ci-dessus va afficher :

    collation = PHONEBOOK
    currency = EUR

### Voir aussi

- locale_get_all_variants() - Liste toutes les variantes d'une locale

# Locale::getPrimaryLanguage

# locale_get_primary_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getPrimaryLanguage -- locale_get_primary_language — Lit la langue principale de la locale

### Description

Style orienté objet

public static function Locale::getPrimaryLanguage(string `$locale`): ?string

Style procédural

function locale_get_primary_language(string `$locale`): ?string

Lit la langue principale de la locale.

### Liste de paramètres

`locale`

  La locale dont il faut extraire la langue principale.

### Valeurs de retour

Le code de langue, associé à la langue.

Retourne `null` quand la longueur de `locale` excède `INTL_MAX_LOCALE_LEN`.

### Exemples

Exemple #1 Exemple avec locale_get_primary_language(), procédural

    <?php
    echo locale_get_primary_language('zh-Hant');
    ?>

Exemple #2 Exemple avec locale_get_primary_language(), POO

    <?php
    echo Locale::getPrimaryLanguage('zh-Hant');
    ?>

L'exemple ci-dessus va afficher :

    zh

### Voir aussi

- locale_get_script() - Retourne un code pour le script de la locale
- locale_get_region() - Retourne un code pour la région de la locale
- locale_get_all_variants() - Liste toutes les variantes d'une locale

# Locale::getRegion

# locale_get_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getRegion -- locale_get_region — Retourne un code pour la région de la locale

### Description

Style orienté objet

public static function Locale::getRegion(string `$locale`): ?string

Style procédural

function locale_get_region(string `$locale`): ?string

Retourne un code pour la région de la locale.

### Liste de paramètres

`locale`

  La locale dont il faut extraire le code de région.

### Valeurs de retour

Le code de région pour la locale, ou bien `null` en cas d'erreur.

Retourne `null` quand la longueur de `locale` excède `INTL_MAX_LOCALE_LEN`.

### Exemples

Exemple #1 Exemple avec locale_get_region(), procédural

    <?php
    echo locale_get_region('de-CH-1901');
    ?>

Exemple #2 Exemple avec locale_get_region(), POO

    <?php
    echo Locale::getRegion('de-CH-1901');
    ?>

L'exemple ci-dessus va afficher :

    CH

### Voir aussi

- locale_get_primary_language() - Lit la langue principale de la locale
- locale_get_script() - Retourne un code pour le script de la locale
- locale_get_all_variants() - Liste toutes les variantes d'une locale

# Locale::getScript

# locale_get_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getScript -- locale_get_script — Retourne un code pour le script de la locale

### Description

Style orienté objet

public static function Locale::getScript(string `$locale`): ?string

Style procédural

function locale_get_script(string `$locale`): ?string

Retourne un code pour le script de la locale

### Liste de paramètres

`locale`

  La locale dont il faut extraire le code du script.

### Valeurs de retour

Le code de script pour la locale ou `null` si absent.

### Exemples

Exemple #1 Exemple avec locale_get_script(), procédural

    <?php
    echo locale_get_script('sr-Cyrl');
    ?>

Exemple #2 Exemple avec locale_get_script(), POO

    <?php
    echo Locale::getScript('sr-Cyrl');
    ?>

L'exemple ci-dessus va afficher :

    Cyrl

### Voir aussi

- locale_get_primary_language() - Lit la langue principale de la locale
- locale_get_region() - Retourne un code pour la région de la locale
- locale_get_all_variants() - Liste toutes les variantes d'une locale

# Locale::isRightToLeft

(No version information available, might only be in Git)

Locale::isRightToLeft — Vérifie si une locale utilise un système d'écriture de droite à gauche

### Description

public static function Locale::isRightToLeft( string `$locale` = "" ): bool

Détermine si une locale utilise un système d'écriture de droite à gauche.

Cette méthode s'appuie sur la bibliothèque ICU et évalue le script dominant associé à la locale.

Si une chaîne vide est fournie, la locale par défaut est utilisée.

### Liste de paramètres

`locale`
  L'identifiant de la locale. Si vide, la locale par défaut est utilisée.

### Valeurs de retour

Retourne `true` si la locale utilise un système d'écriture de droite à gauche, ou `false` sinon.

### Historique

Version | Description
--- | ---
8.5.0 | Ajout de Locale::isRightToLeft().

### Exemples

Exemple #1 Vérifier la direction du texte pour une locale

    <?php

    var_dump(Locale::isRightToLeft('en-US'));
    var_dump(Locale::isRightToLeft('ar'));

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)

# Locale::lookup

# locale_lookup

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::lookup -- locale_lookup — Recherche dans la liste la meilleure langue

### Description

Style orienté objet

public static function Locale::lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Style procédural

function locale_lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Recherche dans la liste `languageTag` la meilleure langue, pour la locale spécifiée par `locale`, en fonction de l'algorithme de la RFC 4647.

### Liste de paramètres

`languageTag`

  Un tableau contenant une liste de langues à comparer à la locale `locale`. Un maximum de 100 éléments est autorisé.

`locale`

  La locale à utiliser pour effectuer la recherche.

`canonicalize`

  Si `true` les arguments seront convertis en leur forme canonique avant leur recherche.

`defaultLocale`

  La locale à utiliser si aucune solution n'est trouvée.

### Valeurs de retour

La langue la plus proche qui ait été trouvée dans la liste, ou bien la valeur par défaut.

Retourne `null` quand la longueur de `locale` excède `INTL_MAX_LOCALE_LEN`.

### Historique

Version | Description
--- | ---
7.4.0 | `defaultLocale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec locale_lookup(), procédural

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo locale_lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

Exemple #2 Exemple avec Locale::lookup(), POO

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo Locale::lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

L'exemple ci-dessus va afficher :

    de_de_1996

### Voir aussi

- locale_filter_matches() - Vérifie si le tag de langue correspond à une locale

# Locale::parseLocale

# locale_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::parseLocale -- locale_parse — Retourne les sous-éléments de la locale

### Description

Style orienté objet

public static function Locale::parseLocale(string `$locale`): ?array

Style procédural

function locale_parse(string `$locale`): ?array

Retourne un tableau de paires clé-valeur pour les éléments du sous-tag de la locale.

### Liste de paramètres

`locale`

  La locale dont il faut extraire le tableau. Il est à noter que 'variant' et 'private' peuvent prendre jusqu'à 15 valeurs au maximum, alors que 'extlang' peut prendre jusqu'à 3 valeurs.

### Valeurs de retour

Retourne un tableau contenant la liste des paires clé-valeur, où les clés sont les noms des éléments, et les valeurs sont leur valeur associée. Le tableau est ordonné de la même manière que les éléments dans la locale, p. ex. si les variantes sont '-varX-varY-varZ' alors le tableau retourné contiendra variant0=>varX , variant1=>varY , variant2=>varZ, etc.

Retourne `null` quand la taille de `locale` dépasse `INTL_MAX_LOCALE_LEN`.

### Exemples

Exemple #1 Exemple avec locale_parse(), procédural

    <?php
    $arr = locale_parse('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

Exemple #2 Exemple avec locale_parse(), POO

    <?php
    $arr = Locale::parseLocale('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

L'exemple ci-dessus va afficher :

    language : sl , script : Latn , region : IT , variant0 : NEDIS ,

### Voir aussi

- locale_compose() - Retourne un identifiant de locale correct

# Locale::setDefault

# locale_set_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::setDefault -- locale_set_default — Configure la locale par défaut

### Description

Style orienté objet

public static function Locale::setDefault(string `$locale`): true

Style procédural

function locale_set_default(string `$locale`): true

Configure la locale par défaut à `locale`. Cela change la valeur de la globale INTL 'default_locale'. Les extensions UAX #35 sont aussi acceptées.

### Liste de paramètres

`locale`

  Une langue au format BCP 47.

### Valeurs de retour

Retourne `true`.

### Exemples

Exemple #1 Exemple avec locale_set_default(), procédural

    <?php
    locale_set_default('de-DE');
    echo locale_get_default();
    ?>

Exemple #2 Exemple avec locale_set_default(), POO

    <?php
    Locale::setDefault('de-DE');
    echo Locale::getDefault();
    ?>

L'exemple ci-dessus va afficher :

    de-DE

### Voir aussi

- locale_get_default() - Lit la valeur par défaut d'une locale pour la variable globale 'default_locale'

## Sommaire

- Locale::acceptFromHttp — Devine la meilleure locale à partir de l'en-tête HTTP "Accept-Language"
- Locale::canonicalize — Canonise la chaîne représentant la locale
- Locale::composeLocale — Retourne un identifiant de locale correct
- Locale::filterMatches — Vérifie si le tag de langue correspond à une locale
- Locale::getAllVariants — Liste toutes les variantes d'une locale
- Locale::getDefault — Lit la valeur par défaut d'une locale pour la variable globale 'default_locale'
- Locale::getDisplayLanguage — Retourne un nom approprié pour l'affichage d'un nom de langue
- Locale::getDisplayName — Retourne un nom d'affichage correct pour une locale
- Locale::getDisplayRegion — Retourne un nom pour la région de la locale
- Locale::getDisplayScript — Retourne le nom du script de la locale
- Locale::getDisplayVariant — Retourne un nom pour la variante de la locale
- Locale::getKeywords — Lit les mots-clé de la locale
- Locale::getPrimaryLanguage — Lit la langue principale de la locale
- Locale::getRegion — Retourne un code pour la région de la locale
- Locale::getScript — Retourne un code pour le script de la locale
- Locale::isRightToLeft — Vérifie si une locale utilise un système d'écriture de droite à gauche
- Locale::lookup — Recherche dans la liste la meilleure langue
- Locale::parseLocale — Retourne les sous-éléments de la locale
- Locale::setDefault — Configure la locale par défaut

# La classe Normalizer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introduction

La normalisation est un processus qui implique la transformation de caractères et de séquences de caractères dans une représentation formelle. Ce processus est important quand des textes doivent être comparés à des fins de tri et de recherche, mais il est aussi important pour le stockage des données, afin que les documents soient cohérents.

Le consortium Unicode a défini un nombre de formes de normalisations pour refléter les différents besoins des applications :

- Normalization Form D (NFD) : décomposition canonique
- Normalization Form C (NFC) : décomposition canonique, suivie d'une composition canonique
- Normalization Form KD (NFKD) : décomposition compatible
- Normalization Form KC (NFKC) : décomposition compatible suivie d'une composition canonique

Les différentes formes sont définies en termes de transformations de texte, transformations qui sont exprimées avec des algorithmes et des fichiers de données.

## Synopsis de la classe

class Normalizer {
/* Constantes */
public const int FORM_D;
public const int NFD;
public const int FORM_KD;
public const int NFKD;
public const int FORM_C;
public const int NFC;
public const int FORM_KC;
public const int NFKC;
public const int FORM_KC_CF;
public const int NFKC_CF;
/* Méthodes */
public static function getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string
public static function isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool
public static function normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false
}

## Constantes pré-définies

Les constantes suivantes définissent les formes de normalisation à appliquer par le normalizer :

`Normalizer::FORM_C` int
  Normalization Form C (NFC) : décomposition canonique suivie d'une composition canonique
`Normalizer::FORM_D` int
  Normalization Form D (NFD) : décomposition canonique
`Normalizer::NFD` int

`Normalizer::FORM_KC` int
  Normalization Form KC (NFKC) : décomposition compatible, suivie d'une composition canonique
`Normalizer::NFKC` int

`Normalizer::FORM_KC_CF` int

`Normalizer::FORM_KD` int
  Normalization Form KD (NFKD) : décomposition compatible
`Normalizer::NFKD` int

`Normalizer::NFC` int

`Normalizer::NFKC_CF` int

## Voir aussi

- » Unicode Normalization
- » Unicode Normalization FAQ
- » ICU User Guide : Normalization
- » ICU API Reference : Normalization

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.
8.0.0 | `Normalizer::NONE` a été supprimé.

# Normalizer::getRawDecomposition

# normalizer_get_raw_decomposition

(PHP 7 >= 7.3, PHP 8)

Normalizer::getRawDecomposition -- normalizer_get_raw_decomposition — Renvoie la propriété Decomposition_Mapping pour le point de code UTF-8 donné

### Description

Style orienté objet

public static function Normalizer::getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Style procédural

function normalizer_get_raw_decomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Renvoie la propriété Decomposition_Mapping, telle que spécifiée dans la base de données de caractères Unicode (UCD), pour le point de code UTF-8 donné.

### Liste de paramètres

`string`

  La chaîne d'entrée, qui doit être un seul point de code UTF-8.

### Valeurs de retour

Renvoie un string contenant la propriété Decomposition_Mapping, si elle est présente dans l'UCD.

Renvoie `null` s'il n'y a pas de propriété Decomposition_Mapping pour le caractère.

### Exemples

Exemple #1 Exemple de Normalizer::getRawDecomposition()

    <?php

    $result = "";
    $strings = [
        "a",
        "\u{FFDA}",
        "\u{FDFA}",
        "",
        "aa",
        "\xF5",
    ];

    foreach ($strings as $string) {
        $decomposition = Normalizer::getRawDecomposition($string);
        // $decomposition = normalizer_get_raw_decomposition($string); Approche procédurale

        $error_code = intl_get_error_code();
        $error_message = intl_get_error_message();

        $string_hex = bin2hex($string);
        $result .= "---------------------\n";

        if ($decomposition === null) {
            $result .= "'$string_hex' has no decomposition mapping\n" ;
        } else {
            $result .= "'$string_hex' has the decomposition mapping '" . bin2hex($decomposition) . "'\n" ;
        }

        $result .= "error info: '$error_message' ($error_code)\n";
    }

    echo $result;
    ?>

L'exemple ci-dessus va afficher :

    ---------------------
    '61' has no decomposition mapping
    error info: 'U_ZERO_ERROR' (0)
    ---------------------
    'efbf9a' has the decomposition mapping 'e385a1'
    error info: 'U_ZERO_ERROR' (0)
    ---------------------
    'efb7ba' has the decomposition mapping 'd8b5d984d98920d8a7d984d984d98720d8b9d984d98ad98720d988d8b3d984d985'
    error info: 'U_ZERO_ERROR' (0)
    ---------------------
    '' has no decomposition mapping
    error info: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    '6161' has no decomposition mapping
    error info: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    'f5' has no decomposition mapping
    error info: 'Code point out of range: U_ILLEGAL_ARGUMENT_ERROR' (1)

### Voir aussi

- Normalizer::normalize() - Normalise une chaîne en entrée
- Normalizer::isNormalized() - Vérifie si une chaîne est normalisée

# Normalizer::isNormalized

# normalizer_is_normalized

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::isNormalized -- normalizer_is_normalized — Vérifie si une chaîne est normalisée

### Description

Style orienté objet

public static function Normalizer::isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Style procédural

function normalizer_is_normalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Vérifie si une chaîne est normalisée.

### Liste de paramètres

`string`

  La chaîne à normaliser.

`form`

  Une des formes de normalisation.

### Valeurs de retour

`true` si la chaîne est normalisée, et `false` sinon ou s'il y a une erreur.

### Exemples

Exemple #1 Exemple avec normalizer_is_normalized(), en style procédural

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( normalizer_is_normalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( normalizer_is_normalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

Exemple #2 Exemple avec normalizer_is_normalized(), en style orienté objet

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( Normalizer::isNormalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( Normalizer::isNormalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

L'exemple ci-dessus va afficher :

    not normalized; normalized

### Voir aussi

- normalizer_normalize() - Normalise une chaîne en entrée

# Normalizer::normalize

# normalizer_normalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::normalize -- normalizer_normalize — Normalise une chaîne en entrée

### Description

Style orienté objet

public static function Normalizer::normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Style procédural

function normalizer_normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Normalise la chaîne en entrée et retourne une chaîne normalisée.

### Liste de paramètres

`string`

  La chaîne à normaliser

`form`

  Une des formes de normalisation.

### Valeurs de retour

La chaîne normalisée, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec normalizer_normalize(), procédural

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = normalizer_normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

Exemple #2 Exemple avec normalizer_normalize(), POO

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = Normalizer::normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

L'exemple ci-dessus va afficher :

    %C3%85 %C3%85

### Voir aussi

- normalizer_is_normalized() - Vérifie si une chaîne est normalisée

## Sommaire

- Normalizer::getRawDecomposition — Renvoie la propriété Decomposition_Mapping pour le point de code UTF-8 donné
- Normalizer::isNormalized — Vérifie si une chaîne est normalisée
- Normalizer::normalize — Normalise une chaîne en entrée

# La classe MessageFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introduction

MessageFormatter est une classe concrète qui permet de produire des messages concaténés, et indépendants de la langue. Les méthodes fournies dans cette classe sont utilisées pour construire des messages qui sont destinés aux utilisateurs finaux.

La classe MessageFormatter assemble les messages à partir de différents fragments (textes, nombres et dates), fournis par le programme. Grâce à la classe MessageFormatter, le programme n'a pas besoin de connaître l'ordre des fragments. La classe utilise des spécifications de formatage pour assembler les fragments en un seul message. Par exemple, MessageFormatter permet d'afficher la phrase `"Fini d'imprimer x fichier sur y..."` d'une manière qui reste souple pour la traduction.

Avant, un message était créé sous forme de phrase, et géré comme une chaîne. Cette procédure créait des problèmes pour les traductions, car la structure de la phrase, l'ordre des mots, le format des nombres, etc. sont très différents d'une langue à l'autre. L'approche de création des messages, indépendante de la langue, permet de séparer le message et les variables. Avec ces variables, MessageFormatter peut concaténer les différentes parties du message, les formater aux conventions correctes, et fournir un message bien formé.

MessageFormatter prend une série d'objets, formate les textes, et les insère dans les chaînes formatées dans les emplacements corrects. Un grand choix de formats peut être utilisé en conjonction avec MessageFormatter pour gérer le pluriel, les nombres, etc. Typiquement, le message est fourni par une ressource, et les arguments sont préparés dynamiquement.

## Synopsis de la classe

class MessageFormatter {
/* Méthodes */
public function __construct(string `$locale`, string `$pattern`)
public static function create(string `$locale`, string `$pattern`): ?MessageFormatter
public function format(array `$values`): string|false
public static function formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(): string
public function getPattern(): string|false
public function parse(string `$string`): array|false
public static function parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false
public function setPattern(string `$pattern`): bool
}

## Voir aussi

- » ICU formatting documentation
- » ICU message formatting description
- » ICU message formatters
- » ICU choice formatters

# MessageFormatter::create

# MessageFormatter::__construct

# msgfmt_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::create -- MessageFormatter::__construct -- msgfmt_create — Construit un nouveau formateur de messages

### Description

Style orienté objet (méthode)

public static function MessageFormatter::create(string `$locale`, string `$pattern`): ?MessageFormatter

Style orienté objet (constructeur)

public function MessageFormatter::__construct(string `$locale`, string `$pattern`)

Style procédural

function msgfmt_create(string `$locale`, string `$pattern`): ?MessageFormatter

Construit un nouveau formateur de messages.

### Liste de paramètres

`locale`

  La locale à utiliser pour le formatage des arguments

`pattern`

  La chaîne dans laquelle il faut insérer les données. Le modèle utilise une syntaxe qui accepte les apostrophes. Voir » Quoting/Escaping pour plus de détails.

### Valeurs de retour

Un objet de formateur de message MessageFormatter, ou `null` en cas d'échec.

### Erreurs / Exceptions

Lorsqu'il est invoqué en tant que constructeur, IntlException est levée en cas d'échec.

### Exemples

Exemple #1 Exemple avec msgfmt_create(), style procédural

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Exemple #2 Exemple avec msgfmt_create(), POO

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

L'exemple ci-dessus va afficher :

    4,560 singes sur 123 arbres font 37.073 singes par arbre
    4.560 Affen über 123 Bäume um 37,073 Affen pro Baum

### Voir aussi

- msgfmt_format() - Formate un message
- msgfmt_parse() - Analyse une chaîne en fonction du modèle
- msgfmt_get_error_code() - Lit le dernier code d'erreur de la dernière opération
- msgfmt_get_error_message() - Lit le message d'erreur de la dernière opération

# MessageFormatter::format

# msgfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::format -- msgfmt_format — Formate un message

### Description

Style orienté objet

public function MessageFormatter::format(array `$values`): string|false

Style procédural

function msgfmt_format(MessageFormatter `$formatter`, array `$values`): string|false

Formate un message en substituant les données dans la chaîne de modèle, en fonction des conventions locales.

### Liste de paramètres

`formatter`

  Un objet de formateur de messages MessageFormatter

`values`

  Les arguments à insérer dans les chaînes

### Valeurs de retour

La chaîne formatée, `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec msgfmt_format(), style procédural

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Exemple #2 Exemple avec msgfmt_format(), style POO

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

L'exemple ci-dessus va afficher :

    4,560 singes sur 123 arbres font 37.073 singes par arbre
    4.560 Affen über 123 Bäume um 37,073 Affen pro Baum

### Voir aussi

- msgfmt_create() - Construit un nouveau formateur de messages
- msgfmt_parse() - Analyse une chaîne en fonction du modèle
- msgfmt_format_message() - Formate rapidement un message
- msgfmt_get_error_code() - Lit le dernier code d'erreur de la dernière opération
- msgfmt_get_error_message() - Lit le message d'erreur de la dernière opération

# MessageFormatter::formatMessage

# msgfmt_format_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::formatMessage -- msgfmt_format_message — Formate rapidement un message

### Description

Style orienté objet

public static function MessageFormatter::formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false

Style procédural

function msgfmt_format_message(string `$locale`, string `$pattern`, array `$values`): string|false

Fonction de formatage rapide, qui formate une chaîne sans avoir à créer explicitement un objet de formatage. Utiliser cette fonction lorsque l'opération de formatage n'est effectuée qu'une seule fois et qu'il n'est pas nécessaire de conserver des paramètres ou des états, ou lorsqu'on souhaite personnaliser la sortie en fournissant directement un contexte supplémentaire à ICU.

### Liste de paramètres

`locale`

  La locale à utiliser pour le formatage

`pattern`

  La chaîne de caractères dans laquelle il faut insérer les données. Le modèle utilise une syntaxe qui accepte les apostrophes; Voir » Quoting/Escaping pour plus de détails.

`values`

  Le tableau de valeurs à insérer dans la chaîne de format.

### Valeurs de retour

La chaîne formatée, ou bien `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec msgfmt_format_message(), style procédural

    <?php
    echo msgfmt_format_message("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo msgfmt_format_message("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";

Exemple #2 Exemple avec msgfmt_format_message(), style POO

    <?php
    echo MessageFormatter::formatMessage("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo MessageFormatter::formatMessage("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";

L'exemple ci-dessus va afficher :

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum
    You finished 3rd!
    There are no apples

Exemple #3 Demander à ICU de formater la devise avec le symbole monétaire commun et avec le symbole monétaire court.

Nécessite ICU ≥ 67.

    <?php
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD}", array(123.45));
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD unit-width-narrow}", array(123.45));

L'exemple ci-dessus va afficher :

    123,45 CA$
    123,45 $

### Voir aussi

- msgfmt_create() - Construit un nouveau formateur de messages
- msgfmt_parse() - Analyse une chaîne en fonction du modèle
- msgfmt_get_error_code() - Lit le dernier code d'erreur de la dernière opération
- msgfmt_get_error_message() - Lit le message d'erreur de la dernière opération

# MessageFormatter::getErrorCode

# msgfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorCode -- msgfmt_get_error_code — Lit le dernier code d'erreur de la dernière opération

### Description

Style orienté objet

public function MessageFormatter::getErrorCode(): int

Style procédural

function msgfmt_get_error_code(MessageFormatter `$formatter`): int

Lit le dernier code d'erreur de la dernière opération.

### Liste de paramètres

`formatter`

  Un objet de formateur de messages MessageFormatter

### Valeurs de retour

Le code d'erreur, une des valeurs UErrorCode. La valeur initiale est U_ZERO_ERROR.

### Voir aussi

- msgfmt_get_error_message() - Lit le message d'erreur de la dernière opération
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_is_failure() - Vérifie si un code d'erreur indique un échec

# MessageFormatter::getErrorMessage

# msgfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorMessage -- msgfmt_get_error_message — Lit le message d'erreur de la dernière opération

### Description

Style orienté objet

public function MessageFormatter::getErrorMessage(): string

Style procédural

function msgfmt_get_error_message(MessageFormatter `$formatter`): string

Lit le message d'erreur de la dernière opération du formateur de messages.

### Liste de paramètres

`formatter`

  Un objet de formateur de messages MessageFormatter

### Valeurs de retour

La description de la dernière erreur.

### Exemples

Exemple #1 Exemple avec msgfmt_get_error_message(), style procédural

    <?php
    $fmt = msgfmt_create("en_US", "{0, number} singes sur {1, number} arbres");
    $str = msgfmt_format($fmt, array());
    if(!$str) {
        echo "Erreur : ".msgfmt_get_error_message($fmt) . " (" . msgfmt_get_error_code($fmt) . ")\n";
    }
    ?>

Exemple #2 Exemple avec msgfmt_get_error_message(), style POO

    <?php
    $fmt = new MessageFormatter("en_US", "{0, number} singes sur {1, number} arbres");
    $str = $fmt->format(array());
    if(!$str) {
        echo "Erreur : ".$fmt->getErrorMessage() . " (" . $fmt->getErrorCode() . ")\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    Erreur : msgfmt_format: not enough parameters: U_ILLEGAL_ARGUMENT_ERROR (1)

### Voir aussi

- msgfmt_get_error_code() - Lit le dernier code d'erreur de la dernière opération
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_is_failure() - Vérifie si un code d'erreur indique un échec

# MessageFormatter::getLocale

# msgfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getLocale -- msgfmt_get_locale — Lit la locale avec laquelle le formateur a été créé

### Description

Style orienté objet

public function MessageFormatter::getLocale(): string

Style procédural

function msgfmt_get_locale(MessageFormatter `$formatter`): string

Lit la locale avec laquelle le formateur a été créé.

### Liste de paramètres

`formatter`

  Un objet de formateur de messages MessageFormatter

### Valeurs de retour

Le nom de la locale

### Exemples

Exemple #1 Exemple avec msgfmt_get_locale(), style procédural

    <?php
    $fmt = msgfmt_create('en_US', "Nombre {0,number}");
    echo msgfmt_get_locale($fmt);
    ?>

Exemple #2 Exemple avec msgfmt_get_locale(), style POO

    <?php
    $fmt = new MessageFormatter('en_US', "Nombre {0,number}");
    echo $fmt->getLocale();
    ?>

L'exemple ci-dessus va afficher :

    en_US

### Voir aussi

- msgfmt_create() - Construit un nouveau formateur de messages

# MessageFormatter::getPattern

# msgfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getPattern -- msgfmt_get_pattern — Lit le modèle utilisé par le formateur de messages

### Description

Style orienté objet

public function MessageFormatter::getPattern(): string|false

Style procédural

function msgfmt_get_pattern(MessageFormatter `$formatter`): string|false

Lit le modèle utilisé par le formateur de messages.

### Liste de paramètres

`formatter`

  Un objet de formateur de messages MessageFormatter

### Valeurs de retour

La chaîne de caractères de modèle du formateur de messages, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec msgfmt_get_pattern(), style procédural

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} singes sur {1, number} arbres" );
    echo "Modèle par défaut : '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Résultat de formatage :  " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} arbres accueillant {1, number} singes" );
    echo "Nouveau modèle :  '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Résultat de formatage : " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Exemple #2 Exemple avec msgfmt_get_pattern(), style POO

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} singes sur {1, number} arbres" );
    echo "Modèle par défaut : '" . $fmt->getPattern() . "'\n";
    echo "Résultat de formatage :  " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} arbres accueillant {1, number} singes" );
    echo "Nouveau modèle :  '" . $fmt->getPattern() . "'\n";
    echo "Résultat de formatage : " . $fmt->format(array(123, 456)) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    Modèle par défaut : '{0,number} singes sur {1,number} arbres'
    Résultat de formatage :  123 singes sur 456 arbres
    Nouveau modèle :  '{0,number} arbres accueillant {1,number} singes'
    Résultat de formatage : 123 arbres accueillant 456 singes

### Voir aussi

- msgfmt_create() - Construit un nouveau formateur de messages
- msgfmt_set_pattern() - Configure le modèle utilisé par le formateur

# MessageFormatter::parse

# msgfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parse -- msgfmt_parse — Analyse une chaîne en fonction du modèle

### Description

Style orienté objet

public function MessageFormatter::parse(string `$string`): array|false

Style procédural

function msgfmt_parse(MessageFormatter `$formatter`, string `$string`): array|false

Analyse la chaîne `string` et retourne les éléments extraits sous forme de tableau.

### Liste de paramètres

`formatter`

  Un objet de formateur de messages MessageFormatter

`string`

  La chaîne de caractères à analyser.

### Valeurs de retour

Un tableau contenant les éléments extraits, ou `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec msgfmt_parse(), style procédural

    <?php
    $fmt = msgfmt_create('en_US', "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    $res = msgfmt_parse($fmt, "4,560 singes sur 123 arbres font 37.073 singes par arbre");
    var_export($res);

    $fmt = msgfmt_create('de', "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    $res = msgfmt_parse($fmt, "4.560 Affen über 123 Bäume um 37,073 Affen pro Baum");
    var_export($res);
    ?>

Exemple #2 Exemple avec msgfmt_parse(), style POO

    <?php
    $fmt = new MessageFormatter('en_US', "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre");
    $res = $fmt->parse("4,560 singes sur 123 arbres font 37.073 singes par arbre");
    var_export($res);

    $fmt = new MessageFormatter('de', "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum");
    $res = $fmt->parse("4.560 Affen über 123 Bäume um 37,073 Affen pro Baum");
    var_export($res);
    ?>

L'exemple ci-dessus va afficher :

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Voir aussi

- msgfmt_create() - Construit un nouveau formateur de messages
- msgfmt_format() - Formate un message
- msgfmt_parse_message() - Analyse rapidement une chaîne

# MessageFormatter::parseMessage

# msgfmt_parse_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parseMessage -- msgfmt_parse_message — Analyse rapidement une chaîne

### Description

Style orienté objet

public static function MessageFormatter::parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false

Style procédural

function msgfmt_parse_message(string `$locale`, string `$pattern`, string `$message`): array|false

Analyse la chaîne d'entrée sans créer explicitement d'objet formateur. Utiliser cette fonction lorsque l'opération de formatage est faite une seule fois, et n'a pas besoin de paramètres ou d'état.

### Liste de paramètres

`locale`

  La locale à utiliser pour analyser les parties de la chaîne

`pattern`

  Le motif à utiliser pour analyser `message`.

`message`

  La string à analyser, conformément à `pattern`.

### Valeurs de retour

Un tableau contenant les éléments extraits, ou `false` en cas d'erreur.

### Exemples

Exemple #1 Exemple avec msgfmt_parse_message(), style procédural

    <?php
    $fmt = msgfmt_parse_message('en_US', "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre",
                                "4,560 singes sur 123 arbres font 37.073 singes par arbre");
    var_export($fmt);

    $fmt = msgfmt_parse_message('de', "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum",
                                "4.560 Affen über 123 Bäume um 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

Exemple #2 Exemple avec msgfmt_parse_message(), style POO

    <?php
    $fmt = MessageFormatter::parseMessage('en_US', "{0,number,integer} singes sur {1,number,integer} arbres font {2,number} singes par arbre",
                                "4,560 singes sur 123 arbres font 37.073 singes par arbre");
    var_export($fmt);

    $fmt = MessageFormatter::parseMessage('de', "{0,number,integer} Affen über {1,number,integer} Bäume um {2,number} Affen pro Baum",
                                "4.560 Affen über 123 Bäume um 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

L'exemple ci-dessus va afficher :

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Voir aussi

- msgfmt_create() - Construit un nouveau formateur de messages
- msgfmt_format_message() - Formate rapidement un message
- msgfmt_parse() - Analyse une chaîne en fonction du modèle

# MessageFormatter::setPattern

# msgfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::setPattern -- msgfmt_set_pattern — Configure le modèle utilisé par le formateur

### Description

Style orienté objet

public function MessageFormatter::setPattern(string `$pattern`): bool

Style procédural

function msgfmt_set_pattern(MessageFormatter `$formatter`, string `$pattern`): bool

Configure le modèle utilisé par le formateur.

### Liste de paramètres

`formatter`

  Un objet de formateur de messages MessageFormatter

`pattern`

  La chaîne de modèle utilisée par le formateur de messages. Le modèle utilise une syntaxe qui accepte les apostrophes; Voir » Quoting/Escaping pour plus de détails.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec msgfmt_set_pattern(), style procédural

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} singes sur {1, number} arbres" );
    echo "Modèle par défaut : '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Résultat formaté : " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} arbres accueillant {1, number} singes" );
    echo "Nouveau modèle :'" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Nombre formaté : " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Exemple #2 Exemple avec msgfmt_set_pattern(), style POO

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} singes sur {1, number} arbres" );
    echo "Modèle par défaut : '" . $fmt->getPattern() . "'\n";
    echo "Résultat formaté : " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} arbres accueillant {1, number} singes" );
    echo "Nouveau modèle :'" . $fmt->getPattern() . "'\n";
    echo "Nombre formaté : " . $fmt->format(array(123, 456)) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    Modèle par défaut : '{0,number} singes sur {1,number} arbres'
    Résultat formaté : 123 singes sur 456 arbres
    Nouveau modèle :'{0,number} arbres accueillant {1,number} singes'
    Nombre formaté : 123 arbres accueillant 456 singes

### Voir aussi

- msgfmt_create() - Construit un nouveau formateur de messages
- msgfmt_get_pattern() - Lit le modèle utilisé par le formateur de messages

## Sommaire

- MessageFormatter::create — Construit un nouveau formateur de messages
- MessageFormatter::format — Formate un message
- MessageFormatter::formatMessage — Formate rapidement un message
- MessageFormatter::getErrorCode — Lit le dernier code d'erreur de la dernière opération
- MessageFormatter::getErrorMessage — Lit le message d'erreur de la dernière opération
- MessageFormatter::getLocale — Lit la locale avec laquelle le formateur a été créé
- MessageFormatter::getPattern — Lit le modèle utilisé par le formateur de messages
- MessageFormatter::parse — Analyse une chaîne en fonction du modèle
- MessageFormatter::parseMessage — Analyse rapidement une chaîne
- MessageFormatter::setPattern — Configure le modèle utilisé par le formateur

# La classe IntlCalendar

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Introduction

## Synopsis de la classe

class IntlCalendar {
/* Constantes */
public const int FIELD_ERA;
public const int FIELD_YEAR;
public const int FIELD_MONTH;
public const int FIELD_WEEK_OF_YEAR;
public const int FIELD_WEEK_OF_MONTH;
public const int FIELD_DATE;
public const int FIELD_DAY_OF_YEAR;
public const int FIELD_DAY_OF_WEEK;
public const int FIELD_DAY_OF_WEEK_IN_MONTH;
public const int FIELD_AM_PM;
public const int FIELD_HOUR;
public const int FIELD_HOUR_OF_DAY;
public const int FIELD_MINUTE;
public const int FIELD_SECOND;
public const int FIELD_MILLISECOND;
public const int FIELD_ZONE_OFFSET;
public const int FIELD_DST_OFFSET;
public const int FIELD_YEAR_WOY;
public const int FIELD_DOW_LOCAL;
public const int FIELD_EXTENDED_YEAR;
public const int FIELD_JULIAN_DAY;
public const int FIELD_MILLISECONDS_IN_DAY;
public const int FIELD_IS_LEAP_MONTH;
public const int FIELD_FIELD_COUNT;
public const int FIELD_DAY_OF_MONTH;
public const int DOW_SUNDAY;
public const int DOW_MONDAY;
public const int DOW_TUESDAY;
public const int DOW_WEDNESDAY;
public const int DOW_THURSDAY;
public const int DOW_FRIDAY;
public const int DOW_SATURDAY;
public const int DOW_TYPE_WEEKDAY;
public const int DOW_TYPE_WEEKEND;
public const int DOW_TYPE_WEEKEND_OFFSET;
public const int DOW_TYPE_WEEKEND_CEASE;
public const int WALLTIME_FIRST;
public const int WALLTIME_LAST;
public const int WALLTIME_NEXT_VALID;
/* Méthodes */
private function __construct()
public function add(int `$field`, int `$value`): bool
public function after(IntlCalendar `$other`): bool
public function before(IntlCalendar `$other`): bool
public function clear(?int `$field` = `null`): true
public static function createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function equals(IntlCalendar `$other`): bool
public function fieldDifference(float `$timestamp`, int `$field`): int|false
public static function fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function get(int `$field`): int|false
public function getActualMaximum(int `$field`): int|false
public function getActualMinimum(int `$field`): int|false
public static function getAvailableLocales(): array
public function getDayOfWeekType(int `$dayOfWeek`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getFirstDayOfWeek(): int|false
public function getGreatestMinimum(int `$field`): int|false
public static function getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function getLeastMaximum(int `$field`): int|false
public function getLocale(int `$type`): string|false
public function getMaximum(int `$field`): int|false
public function getMinimalDaysInFirstWeek(): int|false
public function getMinimum(int `$field`): int|false
public static function getNow(): float
public function getRepeatedWallTimeOption(): int
public function getSkippedWallTimeOption(): int
public function getTime(): float|false
public function getTimeZone(): IntlTimeZone|false
public function getType(): string
public function getWeekendTransition(int `$dayOfWeek`): int|false
public function inDaylightTime(): bool
public function isEquivalentTo(IntlCalendar `$other`): bool
public function isLenient(): bool
public function isSet(int `$field`): bool
public function isWeekend(?float `$timestamp` = `null`): bool
public function roll(int `$field`, int|bool `$value`): bool
public function set(int `$field`, int `$value`): true
public function set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function setFirstDayOfWeek(int `$dayOfWeek`): true
public function setLenient(bool `$lenient`): true
public function setMinimalDaysInFirstWeek(int `$days`): true
public function setRepeatedWallTimeOption(int `$option`): true
public function setSkippedWallTimeOption(int `$option`): true
public function setTime(float `$timestamp`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function toDateTime(): DateTime|false
}

## Constantes pré-définies

`IntlCalendar::FIELD_ERA` int

  Le champ de calendrier numériquement représentant une ère, par exemple `1` pour AD et `0` pour BC dans les calendriers grégorien/julien et `235` pour l'ère Heisei (平成) dans le calendrier japonais. Tous les calendriers n'ont pas plus d'une ère.

`IntlCalendar::FIELD_YEAR` int

  Le champ de calendrier pour l'année. Ceci n'est pas unique à travers les ères. Si le type de calendrier a plus d'une ère, généralement la valeur minimale pour ce champ sera `1`.

`IntlCalendar::FIELD_MONTH` int

  Le champ de calendrier pour le mois. La séquence des mois commence à zéro, donc janvier (ici utilisé pour signifier le premier mois du calendrier; cela peut être appelé un autre nom, tel que Muharram dans le calendrier islamique) est représenté par `0`, février par `1`, …, décembre par `11` et, pour les calendriers qui l'ont, le 13ème ou mois bis par `12`.

`IntlCalendar::FIELD_WEEK_OF_YEAR` int

  Le champ de calendrier pour le numéro de la semaine de l'année. Ceci dépend du jour de la semaine qui est considéré comme le début de la semaine et du nombre minimal de jours dans une semaine.

`IntlCalendar::FIELD_WEEK_OF_MONTH` int

  Le champ de calendrier pour le numéro de la semaine du mois. Ceci dépend du jour de la semaine qui est considéré comme le début de la semaine et du nombre minimal de jours dans une semaine.

`IntlCalendar::FIELD_DATE` int

  Le champ de calendrier pour le jour du mois. Identique à `IntlCalendar::FIELD_DAY_OF_MONTH`, qui a un nom plus clair.

`IntlCalendar::FIELD_DAY_OF_YEAR` int

  Le champ de calendrier pour le jour de l'année. Pour le calendrier grégorien, commence par `1` et se termine par `365` ou `366`.

`IntlCalendar::FIELD_DAY_OF_WEEK` int

  Le champ de calendrier pour le jour de la semaine. Ses valeurs commencent par `1` (dimanche, voir `IntlCalendar::DOW_SUNDAY` et les constantes suivantes) et la dernière valeur valide est `7` (samedi).

`IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH` int

  Donner un jour de la semaine (dimanche, lundi, …), ce champ de calendrier attribue un ordinal à un tel jour de la semaine dans un mois spécifique. Ainsi, si la valeur de ce champ est `1` et la valeur du jour de la semaine est `2` (lundi), alors le jour défini du mois est le premier lundi du mois; la valeur maximale est `5`.

  En plus de cela, la valeur `0` et les valeurs négatives sont également autorisées. La valeur `0` englobe les sept jours qui se produisent immédiatement avant les sept premiers jours d'un mois (qui ont donc un « jour de la semaine dans le mois » avec la valeur `1`). Les valeurs négatives commencent à compter à partir de la fin du mois - `-1` pointe vers la dernière occurrence d'un jour de la semaine dans un mois, `-2` vers l'avant-dernier, et ainsi de suite.

  À la différence de `IntlCalendar::FIELD_WEEK_OF_MONTH` et `IntlCalendar::FIELD_WEEK_OF_YEAR`, cette valeur ne dépend pas de IntlCalendar::getFirstDayOfWeek() ou de IntlCalendar::getMinimalDaysInFirstWeek(). Le premier lundi est le premier lundi, même s'il se trouve dans une semaine qui appartient au mois précédent.

`IntlCalendar::FIELD_AM_PM` int

  Le champ de calendrier indiquant si un temps est avant midi (valeur `0`, AM) ou après (`1`, PM). Minuit est AM, midi est PM.

`IntlCalendar::FIELD_HOUR` int

  Le champ de calendrier pour l'heure, sans spécifier si c'est le matin ou l'après-midi. Les valeurs valides sont de `0` à `11`.

`IntlCalendar::FIELD_HOUR_OF_DAY` int

  Le champ de calendrier pour l'heure complète (24h) du jour. Les valeurs valides sont de `0` à `23`.

`IntlCalendar::FIELD_MINUTE` int

  Le champ de calendrier pour la composante minutes de l'heure.

`IntlCalendar::FIELD_SECOND` int

  Le champ de calendrier pour la composante secondes de l'heure.

`IntlCalendar::FIELD_MILLISECOND` int

  Le champ de calendrier pour la composante millisecondes de l'heure.

`IntlCalendar::FIELD_ZONE_OFFSET` int

  Le champ de calendrier indiquant le décalage brut du fuseau horaire, en millisecondes. Le décalage brut est le décalage du fuseau horaire, excluant tout décalage dû à l'heure d'été.

`IntlCalendar::FIELD_DST_OFFSET` int

  Le champ de calendrier pour le décalage de l'heure d'été du fuseau horaire du calendrier, en millisecondes, si actif pour le fuseau horaire

`IntlCalendar::FIELD_YEAR_WOY` int

  Le champ de calendrier représentant l'année pour les besoins de la semaine de l'année.

`IntlCalendar::FIELD_DOW_LOCAL` int

  Le champ de calendrier pour le jour localisé de la semaine. Ceci est une valeur entre `1` et `7`, `1` étant utilisé pour le jour de la semaine qui correspond à la valeur retournée par IntlCalendar::getFirstDayOfWeek().

`IntlCalendar::FIELD_EXTENDED_YEAR` int

  Le champ de calendrier pour une représentation numérique de l'année qui est continue à travers les ères. Pour le calendrier grégorien, la valeur de ce champ correspond à celle de `IntlCalendar::FIELD_YEAR` pour les années AD; une année BC `y` est représentée par `-y + 1`.

`IntlCalendar::FIELD_JULIAN_DAY` int

  Le champ de calendrier pour un nombre de jours julien modifié. Il est différent d'un nombre de jours julien conventionnel en ce que ses transitions se produisent à minuit du fuseau horaire local plutôt qu'à midi UTC. Il identifie de manière unique une date.

`IntlCalendar::FIELD_MILLISECONDS_IN_DAY` int

  Le champ de calendrier englobant les informations dans `IntlCalendar::FIELD_HOUR_OF_DAY`, `IntlCalendar::FIELD_MINUTE`, `IntlCalendar::FIELD_SECOND` et `IntlCalendar::FIELD_MILLISECOND`. La plage est de `0` à `24 * 3600 * 1000 - 1`. Ce n'est pas le nombre de millisecondes écoulées dans la journée, car lors des transitions DST il aura des discontinuités analogues à celles de l'heure locale.

`IntlCalendar::FIELD_IS_LEAP_MONTH` int

  Le champ de calendrier dont la valeur est `1` pour indiquer un mois bissextile et `0` sinon.

`IntlCalendar::FIELD_FIELD_COUNT` int

  Le nombre total de champs.

`IntlCalendar::FIELD_DAY_OF_MONTH` int

  Un alias de `IntlCalendar::FIELD_DATE`.

`IntlCalendar::DOW_SUNDAY` int

  Dimanche.

`IntlCalendar::DOW_MONDAY` int

  Lundi.

`IntlCalendar::DOW_TUESDAY` int

  Mardi.

`IntlCalendar::DOW_WEDNESDAY` int

  Mercredi.

`IntlCalendar::DOW_THURSDAY` int

  Jeudi.

`IntlCalendar::DOW_FRIDAY` int

  Vendredi.

`IntlCalendar::DOW_SATURDAY` int

  Samedi.

`IntlCalendar::DOW_TYPE_WEEKDAY` int

  La sortie de IntlCalendar::getDayOfWeekType() indiquant qu'un jour de la semaine appartient à la semaine.

`IntlCalendar::DOW_TYPE_WEEKEND` int

  La sortie de IntlCalendar::getDayOfWeekType() indiquant qu'un jour de la semaine appartient au week-end.

`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` int

  La sortie de IntlCalendar::getDayOfWeekType() indiquant que le week-end commence pendant le jour de la semaine donné.

`IntlCalendar::DOW_TYPE_WEEKEND_CEASE` int

  La sortie de IntlCalendar::getDayOfWeekType() indiquant que le week-end se termine pendant le jour de la semaine donné.

`IntlCalendar::WALLTIME_FIRST` int

  La sortie de IntlCalendar::getSkippedWallTimeOption() indiquant que les heures murales dans la plage sautée devraient se référer au même instant que les heures murales avec une heure de moins et de IntlCalendar::getRepeatedWallTimeOption() indiquant que les heures murales dans la plage répétée devraient se référer à l'instant de la première occurrence de cette heure murale.

`IntlCalendar::WALLTIME_LAST` int

  La sortie de IntlCalendar::getSkippedWallTimeOption() indiquant que les heures murales dans la plage sautée devraient se référer au même instant que les heures murales avec une heure de plus et de IntlCalendar::getRepeatedWallTimeOption() indiquant que les heures murales dans la plage répétée devraient se référer à l'instant de la deuxième occurrence de cette heure murale.

`IntlCalendar::WALLTIME_NEXT_VALID` int

  La sortie de IntlCalendar::getSkippedWallTimeOption() indiquant que les heures murales dans la plage sautée devraient se référer à l'instant lorsque la transition de l'heure d'été arrive (débute).

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont désormais typées.

# IntlCalendar::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::add — Ajoute une durée (signée) à un champ

### Description

Style orienté objet

public function IntlCalendar::add(int `$field`, int `$value`): bool

Style procédural

function intlcal_add(IntlCalendar `$calendar`, int `$field`, int `$value`): bool

Ajoute une durée signée à un champ. L'ajout d'une durée positive permet d'avancer dans le temps, même si la valeur numérique du champ décroit (c.-à-d. lorsqu'on travaille sur les années en dates BC).

Les autres champs doivent s'ajuster ; par exemple, l'ajout d'un mois à la date du 31 Janvier retournera le 28 (ou 29) Février. Contrairement à la fonction IntlCalendar::roll(), lorsqu'une valeur englobe plusieurs valeurs, plusieurs champs peuvent changer significativement. Par exemple, l'ajout d'une journée au 31 Janvier retournera le 1 Février, et non le 1 Janvier.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

`value`

  La durée signée à ajouter au champ courant. Si la durée est positive, l'instant va se déplacer en avant ; si elle est négative, l'instant va se déplacer dans le passé. L'unité est implicite suivant le type de champ. Par exemple, ce sera en heures pour la constante `IntlCalendar::FIELD_HOUR_OF_DAY`.

### Valeurs de retour

Retourne `true` en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec IntlCalendar::add()

    <?php
    ini_set('intl.default_locale', 'fr_FR');
    ini_set('date.timezone', 'UTC');

    $cal = new IntlGregorianCalendar(2012, 0 /* January */, 31);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

L'exemple ci-dessus va afficher :

    31 janv. 2012 00:00:00
    29 févr. 2012 00:00:00
    1 mars 2012 00:00:00

# IntlCalendar::after

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::after — Vérifie si l'objet temps courant est dans le futur par rapport à l'objet temps passé

### Description

Style orienté objet

public function IntlCalendar::after(IntlCalendar `$other`): bool

Style procédural

function intlcal_after(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Vérifie si l'objet temps courant est dans le futur par rapport à l'objet temps passé.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`other`

  Le calendrier pour lequel le temps sera vérifié par rapport au temps de l'objet primaire.

### Valeurs de retour

Retourne `true` si l'objet temps courant est dans le futur par rapport au temps de l'argument `calendar`. Retourne `false` sinon.

En cas d&échec `false` est aussi retourné. Pour détecter les conditions d&erreur intl_get_error_code() doit être utilisé, ou paramétrer Intl pour lancer des exceptions.

### Exemples

Exemple #1 Exemple avec IntlCalendar::after()

    <?php
    $cal1 = IntlCalendar::createInstance();
    $cal2 = clone $cal1;

    var_dump($cal1->after($cal2), //false
            $cal2->after($cal1)); //false

    $cal1->roll(IntlCalendar::FIELD_MILLISECOND, true);

    var_dump($cal1->after($cal2), //true
            $cal2->after($cal1)); //false

# IntlCalendar::before

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::before — Vérifie si l'objet temps est dans le passé par rapport à l'objet fourni

### Description

Style orienté objet

public function IntlCalendar::before(IntlCalendar `$other`): bool

Style procédural

function intlcal_before(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Vérifie si l'objet temps est dans le passé par rapport à l'objet fourni.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`other`

  Le calendrier pour lequel le temps sera vérifié par rapport au temps de l'objet primaire.

### Valeurs de retour

Retourne `true` si l'objet temps courant est dans le passé par rapport au temps de l'argument `calendar`. Retourne `false` sinon.

En cas d&échec `false` est aussi retourné. Pour détecter les conditions d&erreur intl_get_error_code() doit être utilisé, ou paramétrer Intl pour lancer des exceptions.

# IntlCalendar::clear

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::clear — Vide un ou tous les champs

### Description

Style orienté objet

public function IntlCalendar::clear(?int `$field` = `null`): true

Style procédural

function intlcal_clear(IntlCalendar `$calendar`, ?int `$field` = `null`): true

Vide soit tous les champs, soit un champ spécifique. Un champ vide est marqué comme non utilisé, lui donnant ainsi la plus petite des priorités par rapport aux champs surchargés ou même les valeurs par défaut lors du calcul du temps. De plus, cette valeur est définie à `0`, donnant ainsi au champ une priorité basse ; cette valeur peut avoir été définie à une autre valeur par la durée que le champ a mis à terminer sa requête.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.2.0 | Le type de retour est maintenant `true`, auparavant il était bool.

### Exemples

Exemple #1 Exemple avec IntlCalendar::clear()

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'UTC');

    $fields = array(
        'FIELD_ERA'                  => 0,
        'FIELD_YEAR'                 => 1,
        'FIELD_MONTH'                => 2,
        'FIELD_WEEK_OF_YEAR'         => 3,
        'FIELD_WEEK_OF_MONTH'        => 4,
        'FIELD_DATE'                 => 5,
        'FIELD_DAY_OF_YEAR'          => 6,
        'FIELD_DAY_OF_WEEK'          => 7,
        'FIELD_DAY_OF_WEEK_IN_MONTH' => 8,
        'FIELD_AM_PM'                => 9,
        'FIELD_HOUR'                 => 10,
        'FIELD_HOUR_OF_DAY'          => 11,
        'FIELD_MINUTE'               => 12,
        'FIELD_SECOND'               => 13,
        'FIELD_MILLISECOND'          => 14,
        'FIELD_ZONE_OFFSET'          => 15,
        'FIELD_DST_OFFSET'           => 16,
        'FIELD_YEAR_WOY'             => 17,
        'FIELD_DOW_LOCAL'            => 18,
        'FIELD_EXTENDED_YEAR'        => 19,
        'FIELD_JULIAN_DAY'           => 20,
        'FIELD_MILLISECONDS_IN_DAY'  => 21,
        'FIELD_IS_LEAP_MONTH'        => 22,
        'FIELD_FIELD_COUNT'          => 23,
    );
    function getSetFields(IntlCalendar $cal) {
        global $fields;
        $ret = array();
        foreach ($fields as $name => $value) {
            if ($cal->isSet($value)) {
                $ret[] = $name;
            }
        }
        return $ret;
    }

    $cal = new IntlGregorianCalendar(2013, 2 /* Mars */, 15);
    echo "Après la création d'un GregorianCalendar\n";
    print_r(getSetFields($cal));
    echo "\n";

    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "Après que le formateur ait demandé l'année étendue\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear(IntlCalendar::FIELD_YEAR);
    echo "Après que l'année ait été vidée, la date reste la même\n";
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "car FIELD_EXTENDED_YEAR est toujours défini\n";
    print_r(getSetFields($cal));
    echo "\n";

    var_dump($cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR));
    echo "Après que l'année étendue ait été vidée\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "\n";

    echo "Après que les champs aient été recalculés,\n"
            . " l'année étendue est de nouveau définie (à 1970)\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear();
    echo "Après l'appel d'une variante sans argument\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";

L'exemple ci-dessus va afficher :

    Après la création d'un GregorianCalendar
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
    )

    15/03/2013 00:00:00
    Après que le formateur ait demandé l'année étendue
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
        [4] => FIELD_EXTENDED_YEAR
    )

    Après que l'année ait été vidée, la date reste la même
    15/03/2013 00:00:00
    car FIELD_EXTENDED_YEAR est toujours défini
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    bool(true)
    Après que l'année étendue ait été vidée
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
    )
    15/03/1970 00:00:00

    Après que les champs aient été recalculés,
     l'année étendue est de nouveau définie (à 1970)
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    Après l'appel d'une variante sans argument
    Array
    (
    )
    01/01/1970 00:00:00

# IntlCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::__construct — Constructeur privé pour la désactivation de l'instanciation

### Description

private function IntlCalendar::__construct()

Un constructeur privé pour désactiver l'instanciation avec l'opérateur new.

Appelez plutôt la méthode IntlCalendar::createInstance().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# IntlCalendar::createInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::createInstance — Crée un nouvel objet IntlCalendar

### Description

Style orienté objet

public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

Style procédural

function intlcal_create_instance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

En fournissant un fuseau horaire, et une locale, cette méthode crée un objet IntlCalendar. Cette méthode d'usine peut retourner une sous-classe de la classe IntlCalendar.

Le calendrier créé représentera l'instance du temps au moment où il a été créé, basé suivant le temps du système. Les champs peuvent être vidés avec la méthode IntCalendar::clear() sans argument. Voir aussi la méthode IntlGregorianCalendar::__construct().

### Liste de paramètres

`timezone`

  Le fuseau horaire à utiliser.

  - `null`, dans quel cas le fuseau horaire par défaut sera utilisé, comme spécifié dans le paramètre de configuration du fichier ini date.timezone ou par la fonction date_default_timezone_set() et comme retourné par date_default_timezone_get().

  - Un IntlTimeZone, qui sera utilisé directement.

  - Un DateTimeZone. Son identifiant sera extrait et un objet de fuseau horaire ICU sera créé; le fuseau horaire sera soutenu par la base de données de l'ICU, et non par PHP.

  - Une chaîne de caractères, qui devrait être un identifiant de fuseau horaire ICU valide. Voir IntlTimeZone::createTimeZoneIDEnumeration(). Les décalages bruts tels que `"GMT+08:30"` sont aussi acceptés.

`locale`

  Une locale à utiliser, ou `null` pour utiliser la locale par défaut.

### Valeurs de retour

L'instance de l'objet IntlCalendar créé, ou `null` si une erreur survient.

### Exemples

Exemple #1 Exemple avec IntlCalendar::createInstance()

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'Europe/Madrid');

    $cal = IntlCalendar::createInstance();
    echo "Aucun argument\n";
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Fuseau horaire explicite\n";
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT());
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Locale explicite (avec le calendrier)\n";
    $cal = IntlCalendar::createInstance(NULL, 'es_ES@calendar=persian');
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));

L'exemple ci-dessus va afficher :

    Aucun argument
    string(21) "IntlGregorianCalendar"
    string(68) "martes 18 de junio de 2013 14:11:02 Hora de verano de Europa Central"

    Fuseau horaire explicite
    string(21) "IntlGregorianCalendar"
    string(45) "martes 18 de junio de 2013 12:11:02 GMT+00:00"

    Locale explicite (avec le calendrier)
    string(12) "IntlCalendar"
    string(70) "martes 28 de Khordad de 1392 14:11:02 Hora de verano de Europa Central"

### Voir aussi

- IntlGregorianCalendar::__construct() - Créer la classe du calendrier grégorien

# IntlCalendar::equals

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::equals — Vérifie si deux objets IntlCalendar sont égaux

### Description

Style orienté objet

public function IntlCalendar::equals(IntlCalendar `$other`): bool

Style procédural

function intlcal_equals(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Retourne `true` si ce calendrier et celui fourni ont le même temps. La configuration, le type de calendrier, et les statuts des champs ne doivent pas être forcément les mêmes.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`other`

  Le calendrier à comparer avec l'objet primaire.

### Valeurs de retour

Retourne `true` si le temps courant est identique à celui de l'objet IntlCalendar ou `false` sinon.

En cas d&échec `false` est aussi retourné. Pour détecter les conditions d&erreur intl_get_error_code() doit être utilisé, ou paramétrer Intl pour lancer des exceptions.

### Exemples

Exemple #1 Exemple avec IntlCalendar::equals()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    $cal2 = clone $cal1;

    var_dump($cal1->equals($cal2)); //TRUE

    //La locale n'est pas incluse dans la comparaison
    $cal2 = IntlCalendar::createInstance(NULL, 'pt_PT');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    //Et les statuts des champs ne sont pas non plus inclus
    $cal2->clear(IntlCalendar::FIELD_YEAR);
    var_dump($cal1->isSet(IntlCalendar::FIELD_YEAR) ==
            $cal2->isSet(IntlCalendar::FIELD_YEAR)); //FALSE
    var_dump($cal1->equals($cal2)); //TRUE

    //Ni le type de calendrier
    $cal2 = IntlCalendar::createInstance(NULL, 'es_ES@calendar=islamic');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    //Seul le temps l'est
    $cal2 = clone $cal1;
    $cal2->setTime($cal1->getTime() + 1.);
    var_dump($cal1->equals($cal2)); //FALSE

# IntlCalendar::fieldDifference

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::fieldDifference — Calcule la différence entre le temps donné et le temps de l'objet

### Description

Style orienté objet

public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false

Style procédural

function intlcal_field_difference(IntlCalendar `$calendar`, float `$timestamp`, int `$field`): int|false

Retourne la différence entre le temps donné et le temps de cet objet, en respectant la quantité spécifiée par le paramètre `field`.

Cette méthode est prévue pour être appelée successivement, tout d'abord avec le champ d'intérêt le plus significatif, puis avec le champ le moins significatif. À la fin, en guise d'effet de bord, la valeur du calendrier pour le champ spécifié sera avancée par la durée retournée.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`timestamp`

  Le temps utilisé pour la comparaison avec la quantité représentée par le champ `field`. Pour que le résultat soit positif, le temps fourni dans ce paramètre doit être dans le futur par rapport au temps de l'objet de la méthode.

`field`

  Le champ qui représente la quantité à comparer.

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

Retourne une différence (signée) de temps, en utilisant l'unité associée avec le champ spécifié ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec IntlCalendar::fieldDifference()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal1 = IntlCalendar::fromDateTime('2012-02-29 09:00:11');
    $cal2 = IntlCalendar::fromDateTime('2013-03-01 09:19:29');
    $time = $cal2->getTime();

    echo "Temps, avant opération : ", IntlDateFormatter::formatObject($cal1), "\n";

    printf(
        "La différence de temps est de %d année(s), %d mois, "
      . "%d jour(s), %d heure(s) et %d minute(s)\n",
        $cal1->fieldDifference($time, IntlCalendar::FIELD_YEAR),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_DAY_OF_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_HOUR_OF_DAY),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MINUTE)
    );

    // maintenant, le temps cible a été avancé, sauf pour les secondes,
    // pour lesquelles nous ne mesurons pas la différence
    echo "Temps, après opération : ", IntlDateFormatter::formatObject($cal1), "\n";

L'exemple ci-dessus va afficher :

    Temps, avant opération : 29 févr. 2012 09:00:11
    La différence de temps est de 1 année(s), 0 mois, 1 jour(s), 0 heure(s) et 19 minute(s)
    Temps, après opération : 1 mars 2013 09:19:11

# IntlCalendar::fromDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::fromDateTime — Créer un IntlCalendar depuis un objet DateTime ou une chaîne de caractères

### Description

Style orienté objet

public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Style procédural

function intlcal_from_date_time(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Crée un objet IntlCalendar soit depuis un objet DateTime ou depuis une chaîne de caractères qui peut être utilisée pour construire un objet DateTime.

Le nouveau calendrier représentera non seulement le même instant que le DateTime donné (sous réserve de la perte de précision pour les dates très anciennes ou futures), mais aussi le même fuseau horaire (sous réserve de la mise en garde que différentes bases de données de fuseaux horaires seront utilisées, et donc les résultats peuvent différer).

### Liste de paramètres

`datetime`

  Un objet DateTime ou une string qui peut être passé à DateTime::__construct().

### Valeurs de retour

L'objet IntlCalendar créé ou `null` en cas d'échec. Si une string est passée, toute exception qui se produit à l'intérieur du constructeur DateTime est propagée.

### Exemples

Exemple #1 IntlCalendar::fromDateTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    //comme IntlCalendar::fromDateTime(new DateTime(...))
    $cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin', 'de_DE');

    //A noter que la timezone est Europe/Berlin, pas celle par défaut Europe/Lisbon
    echo IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'), "\n";

L'exemple ci-dessus va afficher :

    2013 Februar 28 00:01:02 Deutschland Zeit

# IntlCalendar::get

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::get — Récupère la valeur d'une propriété

### Description

Style orienté objet

public function IntlCalendar::get(int `$field`): int|false

Style procédural

function intlcal_get(IntlCalendar `$calendar`, int `$field`): int|false

Récupère la valeur d'une propriété spécifique.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

Un entier contenant la valeur de la propriété.

### Exemples

Exemple #1 IntlCalendar::get()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $class = new ReflectionClass('IntlCalendar');
    $fields = array();
    foreach ($class->getConstants() as $name => $val) {
        if (strpos($name, 'FIELD_') !== 0 || $val > 22)
            continue;
        $fields[$val] = $name;
    }

    $cal = IntlCalendar::createInstance(); // current time
    var_dump(IntlDateFormatter::formatObject($cal));
    foreach ($fields as $val => $name) {
        echo "$val ($name)", "\n    ", $cal->get($val), "\n";
    }

L'exemple ci-dessus va afficher :

    string(23) "Jul 1, 2013, 4:44:44 AM"
    0 (FIELD_ERA)
        1
    1 (FIELD_YEAR)
        2013
    2 (FIELD_MONTH)
        6
    3 (FIELD_WEEK_OF_YEAR)
        27
    4 (FIELD_WEEK_OF_MONTH)
        1
    5 (FIELD_DAY_OF_MONTH)
        1
    6 (FIELD_DAY_OF_YEAR)
        182
    7 (FIELD_DAY_OF_WEEK)
        2
    8 (FIELD_DAY_OF_WEEK_IN_MONTH)
        1
    9 (FIELD_AM_PM)
        0
    10 (FIELD_HOUR)
        4
    11 (FIELD_HOUR_OF_DAY)
        4
    12 (FIELD_MINUTE)
        44
    13 (FIELD_SECOND)
        44
    14 (FIELD_MILLISECOND)
        551
    15 (FIELD_ZONE_OFFSET)
        0
    16 (FIELD_DST_OFFSET)
        3600000
    17 (FIELD_YEAR_WOY)
        2013
    18 (FIELD_DOW_LOCAL)
        2
    19 (FIELD_EXTENDED_YEAR)
        2013
    20 (FIELD_JULIAN_DAY)
        2456475
    21 (FIELD_MILLISECONDS_IN_DAY)
        17084551
    22 (FIELD_IS_LEAP_MONTH)
        0

# IntlCalendar::getActualMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMaximum — La valeur maximale pour un champ, en considérant le temps actuel de l'objet

### Description

Style orienté objet

public function IntlCalendar::getActualMaximum(int `$field`): int|false

Style procédural

function intlcal_get_actual_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Renvoie la valeur maximale pour un champ, en considérant le temps actuel de l'objet. La sémantique exacte varie selon le champ, mais dans le cas général, c'est la valeur qui serait obtenue si on fixait la valeur du champ au plus petit maximum relatif pour le champ et qu'on l'incrémentait jusqu'à atteindre le maximum global ou que la valeur du champ boucle, auquel cas la valeur retournée serait le maximum global ou la valeur avant le bouclage, respectivement.

Par exemple, dans le calendrier grégorien, la valeur maximale réelle pour le jour du mois varierait entre `28` et `31`, selon le mois et l'année du temps actuel.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

Un int représentant la valeur maximale dans les unités associées au `field` donné ou `false` si une erreur survient.

### Exemples

Exemple #1 IntlCalendar::getActualMaximum()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = IntlCalendar::fromDateTime('2013-02-15');
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //28

    $cal->add(IntlCalendar::FIELD_EXTENDED_YEAR, -1);
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //29

L'exemple ci-dessus va afficher :

    int(28)
    int(29)

### Voir aussi

- IntlCalendar::getMaximum() - Obtient la valeur maximale globale pour un champ
- IntlCalendar::getLeastMaximum() - Obtient le plus petit maximum local pour un champ
- IntlCalendar::getActualMinimum() - La valeur minimale pour un champ, en considérant le temps actuel de l'objet

# IntlCalendar::getActualMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMinimum — La valeur minimale pour un champ, en considérant le temps actuel de l'objet

### Description

Style orienté objet

public function IntlCalendar::getActualMinimum(int `$field`): int|false

Style procédural

function intlcal_get_actual_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Renvoie la valeur minimale pour un champ, en considérant le temps actuel de l'objet. La sémantique exacte varie selon le champ, mais dans le cas général, c'est la valeur qui serait obtenue si on fixait la valeur du champ au plus grand minimum relatif pour le champ et qu'on le décrémentait jusqu'à atteindre le minimum global ou que la valeur du champ boucle, auquel cas la valeur retournée serait le minimum global ou la valeur avant le bouclage, respectivement.

Pour le calendrier grégorien, c'est toujours la même valeur que IntlCalendar::getMinimum().

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

Un int représentant la valeur minimale dans lʼunité du champ ou `false` si une erreur survient.

### Voir aussi

- IntlCalendar::getMinimum() - Obtient la valeur minimale globale pour un champ
- IntlCalendar::getGreatestMinimum() - Renvoie la plus grande valeur minimale locale pour un champ
- IntlCalendar::getActualMaximum() - La valeur maximale pour un champ, en considérant le temps actuel de l'objet

# IntlCalendar::getAvailableLocales

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getAvailableLocales — Renvoie un tableau des locales pour lesquelles il y a des données

### Description

Style orienté objet

public static function IntlCalendar::getAvailableLocales(): array

Style procédural

function intlcal_get_available_locales(): array

Donne la liste des locales pour lesquelles les calendriers sont installés. À partir de ICU 51, c'est la liste de toutes les locales ICU installées.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un array de string, un pour chaque locale.

### Exemples

Exemple #1 IntlCalendar::getAvailableLocales()

    <?php
    print_r(IntlCalendar::getAvailableLocales());

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => af
        [1] => af_NA
        [2] => af_ZA
        [3] => agq
        [4] => agq_CM
        [5] => ak
        [6] => ak_GH
        [7] => am
        [8] => am_ET
        [9] => ar
        [10] => ar_001
        [11] => ar_AE
        [12] => ar_BH
        [13] => ar_DJ
        … output abbreviated …
        [595] => zh_Hant_HK
        [596] => zh_Hant_MO
        [597] => zh_Hant_TW
        [598] => zu
        [599] => zu_ZA
    )

# IntlCalendar::getDayOfWeekType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getDayOfWeekType — Indique si un jour est un jour de la semaine, un week-end ou un jour de transition entre les deux

### Description

Style orienté objet

public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false

Style procédural

function intlcal_get_day_of_week_type(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

Renvoie si le jour passé est un jour de semaine (`IntlCalendar::DOW_TYPE_WEEKDAY`), un jour de week-end (`IntlCalendar::DOW_TYPE_WEEKEND`), un jour de transition vers le week-end (`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET`) ou un jour de transition hors du week-end (`IntlCalendar::DOW_TYPE_WEEKEND_CEASE`).

Si le retour est soit `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` ou `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`, alors IntlCalendar::getWeekendTransition() peut être appelée pour obtenir le temps de la transition.

Cette fonction nécessite ICU 4.4 ou plus récent.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`dayOfWeek`

  Une des constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Valeurs de retour

Une des constantes `IntlCalendar::DOW_TYPE_WEEKDAY`, `IntlCalendar::DOW_TYPE_WEEKEND`, `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` ou `IntlCalendar::DOW_TYPE_WEEKEND_CEASE` ou `false` si une erreur survient.

### Exemples

Exemple #1 IntlCalendar::getDayOfWeekType()

    <?php
    foreach (array('en_US', 'ar_SA') as $locale) {
        echo "Locale: ", Locale::getDisplayName($locale, "en_US"), "\n";

        $cal = IntlCalendar::createInstance('UTC', $locale);

        for ($i = IntlCalendar::DOW_SUNDAY; $i <= IntlCalendar::DOW_SATURDAY; $i++) {
            $type = $cal->getDayOfWeekType($i);
            $transition = ($type !== IntlCalendar::DOW_TYPE_WEEKDAY)
                ? $cal->getWeekendTransition($i)
                : '';
            echo $i, " ", $type, " ", $transition, "\n";
        }
        echo "\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    Locale: English (United States)
    1 1 86400000
    2 0
    3 0
    4 0
    5 0
    6 0
    7 1 0

    Locale: Arabic (Saudi Arabia)
    1 0
    2 0
    3 0
    4 0
    5 0
    6 1 0
    7 1 86400000

# IntlCalendar::getErrorCode

# intlcal_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorCode -- intlcal_get_error_code — Renvoie le dernier code d'erreur sur l'objet

### Description

Style orienté objet (méthode):

public function IntlCalendar::getErrorCode(): int|false

Style procédural:

function intlcal_get_error_code(IntlCalendar `$calendar`): int|false

Renvoie le code d'erreur numérique ICU pour le dernier appel sur cet objet (y compris le clonage) ou l'objet IntlCalendar donné pour le paramètre `calendar` (dans la version procédurale). Cela peut indiquer seulement un avertissement (code d'erreur négatif) ou pas d'erreur du tout (`U_ZERO_ERROR`). La présence réelle d'une erreur peut être testée avec intl_is_failure().

Les arguments invalides détectés du côté PHP (avant l'invocation des fonctions de la bibliothèque ICU) ne sont pas enregistrés pour les besoins de cette fonction.

Le dernier code d'erreur qui s'est produit dans n'importe quel appel à une fonction de l'extension intl, y compris les erreurs d'arguments précoces, peut être obtenu avec intl_get_error_code(). Cette fonction réinitialise le code d'erreur global, mais pas le code d'erreur de l'objet.

### Liste de paramètres

`calendar`

  L'objet calendrier, sur l'interface de style procédural.

### Valeurs de retour

Un code d'erreur ICU indiquant soit le succès, l'échec ou un avertissement. Renvoie `false` en cas d'échec.

### Exemples

Exemple #1 IntlCalendar::getErrorCode() et IntlCalendar::getErrorMessage()

    <?php
    ini_set("intl.error_level", E_WARNING);
    ini_set("intl.default_locale", "nl");

    $intlcal = new IntlGregorianCalendar(2012, 1, 29);
    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );
    $intlcal->fieldDifference(-1e100, IntlCalendar::FIELD_SECOND);

    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );

L'exemple ci-dessus va afficher :

    int(0)
    string(12) "U_ZERO_ERROR"

    Warning: IntlCalendar::fieldDifference(): intlcal_field_difference: Call to ICU method has failed in /home/glopes/php/ws/example.php on line 10
    int(1)
    string(81) "intlcal_field_difference: Call to ICU method has failed: U_ILLEGAL_ARGUMENT_ERROR"

### Voir aussi

- IntlCalendar::getErrorMessage() - Renvoie le dernier message d'erreur sur l'objet
- intl_is_failure() - Vérifie si un code d'erreur indique un échec
- intl_error_name() - Lit le nom symbolique d'un code d'erreur donné
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_get_error_message() - Lit la description de la dernière erreur

# IntlCalendar::getErrorMessage

# intlcal_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorMessage -- intlcal_get_error_message — Renvoie le dernier message d'erreur sur l'objet

### Description

Style orienté objet (méthode):

public function IntlCalendar::getErrorMessage(): string|false

Style procédural:

function intlcal_get_error_message(IntlCalendar `$calendar`): string|false

Renvoie (s'il y a) le message d'erreur associé à l'erreur signalée par IntlCalendar::getErrorCode() ou intlcal_get_error_code(). S'il n'y a pas de message d'erreur associé, seule la représentation de chaîne du nom de la constante d'erreur sera renvoyée. Sinon, le message inclut également un message défini du côté de la liaison PHP.

### Liste de paramètres

`calendar`

  L'objet calendrier, sur l'interface de style procédural.

### Valeurs de retour

Le message d'erreur associé à la dernière erreur qui s'est produite dans un appel de fonction sur cet objet, ou une chaîne indiquant la non-existence d'une erreur. Renvoie `false` en cas d'échec.

### Exemples

Exemple #1 IntlCalendar::getErrorMessage()

    <?php
    $cal = IntlCalendar::createInstance('UTC', 'en_US');
    var_dump($cal->getErrorMessage());

    $cal->getWeekendTransition(IntlCalendar::DOW_WEDNESDAY);
    var_dump($cal->getErrorMessage());

L'exemple ci-dessus va afficher :

    string(12) "U_ZERO_ERROR"
    string(82) "intlcal_get_weekend_transition: Error calling ICU method: U_ILLEGAL_ARGUMENT_ERROR"

# IntlCalendar::getFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getFirstDayOfWeek — Renvoie le premier jour de la semaine pour la locale du calendrier

### Description

Style orienté objet

public function IntlCalendar::getFirstDayOfWeek(): int|false

Style procédural

function intlcal_get_first_day_of_week(IntlCalendar `$calendar`): int|false

Renvoie le jour de la semaine qui est considéré comme le premier jour de la semaine, soit la valeur par défaut pour cette locale, soit la valeur définie avec IntlCalendar::setFirstDayOfWeek().

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Une des constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY` ou `false` si une erreur survient.

### Exemples

Exemple #1 IntlCalendar::getFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    var_dump($cal1->getFirstDayOfWeek()); // Lundi
    $cal1->set(2013, 1 /* February */, 3); // un dimanche
    var_dump($cal1->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 5

    $cal2 = IntlCalendar::createInstance(NULL, 'en_US');
    var_dump($cal2->getFirstDayOfWeek()); // Dimanche
    $cal2->set(2013, 1 /* February */, 3); // un dimanche
    var_dump($cal2->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 6

L'exemple ci-dessus va afficher :

    int(2)
    int(5)
    int(1)
    int(6)

### Voir aussi

- IntlCalendar::setFirstDayOfWeek() - Définit le jour de début de la semaine

# IntlCalendar::getGreatestMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getGreatestMinimum — Renvoie la plus grande valeur minimale locale pour un champ

### Description

Style orienté objet

public function IntlCalendar::getGreatestMinimum(int `$field`): int|false

Style procédural

function intlcal_get_greatest_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Renvoie la plus grande valeur minimale locale pour un champ. Cela devrait être une valeur plus grande ou égale à celle retournée par IntlCalendar::getActualMinimum(), qui est à son tour plus grande ou égale à celle retournée par IntlCalendar::getMinimum(). Ces trois fonctions retournent la même valeur pour le calendrier grégorien.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

Un int représentant une valeur de champ, dans lʼunité du champ, ou `false` si une erreur survient.

# IntlCalendar::getKeywordValuesForLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getKeywordValuesForLocale — Renvoie l'ensemble des valeurs de mots-clés de locale

### Description

Style orienté objet

public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

Style procédural

function intlcal_get_keyword_values_for_locale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

Pour une clé de locale donnée, renvoie l'ensemble des valeurs pour cette clé qui entraîneraient un comportement différent. Pour l'instant, seul le mot-clé `'calendar'` est supporté.

Cette fonction requiert ICU 4.2 ou ultérieur.

### Liste de paramètres

`keyword`

  Le mot-clé de locale pour lequel les valeurs pertinentes doivent être interrogées. Seul `'calendar'` est supporté.

`locale`

  La locale sur laquelle la paire mot-clé/valeur doit être ajoutée.

`onlyCommon`

  Indique s'il faut afficher uniquement les valeurs couramment utilisées pour la locale spécifiée.

### Valeurs de retour

Un itérateur qui renvoie des chaînes avec les valeurs de mot-clé de locale ou `false` si une erreur survient.

### Exemples

Exemple #1 IntlCalendar::getKeywordValuesForLocale()

    <?php
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', true)));
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', false)));

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
    )
    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
        [4] => japanese
        [5] => buddhist
        [6] => roc
        [7] => hebrew
        [8] => chinese
        [9] => indian
        [10] => coptic
        [11] => ethiopic
        [12] => ethiopic-amete-alem
    )

# IntlCalendar::getLeastMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLeastMaximum — Obtient le plus petit maximum local pour un champ

### Description

Style orienté objet

public function IntlCalendar::getLeastMaximum(int `$field`): int|false

Style procédural

function intlcal_get_least_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Renvoie le plus petit maximum local pour un champ. Cela devrait être une valeur plus petite ou égale à celle retournée par IntlCalendar::getActualMaximum(), qui est à son tour plus petite ou égale à celle retournée par IntlCalendar::getMaximum().

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

Un int représentant une valeur de champ, dans lʼunité du champ, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de maximum

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'it_IT');

    $cal = new IntlGregorianCalendar(2013, 3 /* April */, 6);
    var_dump(
        $cal->getLeastMaximum(IntlCalendar::FIELD_DAY_OF_MONTH),  // 28
        $cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH), // 30
        $cal->getMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)        // 31
    );

L'exemple ci-dessus va afficher :

    int(28)
    int(30)
    int(31)

### Voir aussi

- IntlCalendar::getActualMaximum() - La valeur maximale pour un champ, en considérant le temps actuel de l'objet
- IntlCalendar::getMaximum() - Obtient la valeur maximale globale pour un champ
- IntlCalendar::getGreatestMinimum() - Renvoie la plus grande valeur minimale locale pour un champ

# IntlCalendar::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLocale — Renvoie la locale associée à l'objet

### Description

Style orienté objet

public function IntlCalendar::getLocale(int `$type`): string|false

Style procédural

function intlcal_get_locale(IntlCalendar `$calendar`, int `$type`): string|false

Renvoie la locale utilisée par cet objet calendrier.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`type`

  Indique si la locale actuelle (la locale à partir de laquelle les données du calendrier proviennent, avec `Locale::ACTUAL_LOCALE`) ou la locale valide, c'est-à-dire la locale la plus spécifique supportée par ICU relativement à la locale demandée – voir `Locale::VALID_LOCALE`. De la plus générale à la plus spécifique, les locales sont ordonnées de cette façon – locale actuelle, locale valide, locale demandée.

### Valeurs de retour

Une chaîne de caractères représentant la locale ou `false` si une erreur survient.

### Exemples

Exemple #1 IntlCalendar::getLocale()

    <?php
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT(), 'en_US_CALIFORNIA');
    var_dump(
        $cal->getLocale(Locale::ACTUAL_LOCALE),
        $cal->getLocale(Locale::VALID_LOCALE)
    );

L'exemple ci-dessus va afficher :

    string(2) "en"
    string(5) "en_US"

# IntlCalendar::getMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMaximum — Obtient la valeur maximale globale pour un champ

### Description

Style orienté objet

public function IntlCalendar::getMaximum(int `$field`): int|false

Style procédural

function intlcal_get_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Renvoie le maximum global pour un champ, dans ce calendrier spécifique. Cette valeur est plus grande ou égale à celle retournée par IntlCalendar::getActualMaximum(), qui est à son tour plus grande ou égale à celle retournée par IntlCalendar::getLeastMaximum().

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

Un int représentant une valeur de champ, dans lʼunité du champ, ou `false` si une erreur survient.

### Voir aussi

- IntlCalendar::getActualMaximum() - La valeur maximale pour un champ, en considérant le temps actuel de l'objet
- IntlCalendar::getLeastMaximum() - Obtient le plus petit maximum local pour un champ
- IntlCalendar::getMinimum() - Obtient la valeur minimale globale pour un champ

# IntlCalendar::getMinimalDaysInFirstWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimalDaysInFirstWeek — Obtient le nombre minimal de jours que la première semaine dʼune année ou dʼun mois peut avoir

### Description

Style orienté objet

public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false

Style procédural

function intlcal_get_minimal_days_in_first_week(IntlCalendar `$calendar`): int|false

Renvoie le plus petit nombre de jours que la première semaine dʼune année ou dʼun mois doit avoir dans la nouvelle année ou le nouveau mois. Par exemple, dans le calendrier grégorien, si cette valeur est 1, alors la première semaine de lʼannée inclura nécessairement le 1er janvier, tandis que si cette valeur est 7, alors la semaine avec le 1er janvier sera la première semaine de lʼannée seulement si le jour de la semaine pour le 1er janvier correspond au jour de la semaine retourné par IntlCalendar::getFirstDayOfWeek(); sinon ce sera la dernière semaine de lʼannée précédente.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Un int représentant un numéro de jour ou `false` si une erreur survient.

### Exemples

Exemple #1 IntlCalendar::getMinimalDaysInFirstWeek()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'en_US');

    $cal = new IntlGregorianCalendar(2013, 0 /* January */, 2);
    var_dump(IntlDateFormatter::formatObject($cal, 'cccc')); // Mercredi

    var_dump($cal->getMinimalDaysInFirstWeek(), // 1
    $cal->getFirstDayofWeek()); // 1 (Dimanche)

    // Semaine 1 de 2013
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

    $cal->setMinimalDaysInFirstWeek(4);
    // Toujours semaine 1 de 2013 (La 1st semaine a 5 jours dans la nouvelle année)
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

    $cal->setMinimalDaysInFirstWeek(6);
    // Semaine 53 de 2012
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

L'exemple ci-dessus va afficher :

    string(9) "Wednesday"
    int(1)
    int(1)
    string(14) "Week 1 of 2013"
    string(14) "Week 1 of 2013"
    string(15) "Week 53 of 2012"

# IntlCalendar::getMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimum — Obtient la valeur minimale globale pour un champ

### Description

Style orienté objet

public function IntlCalendar::getMinimum(int `$field`): int|false

Style procédural

function intlcal_get_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Renvoie la valeur minimale globale pour un champ, dans ce calendrier spécifique. Cette valeur est plus petite ou égale à celle retournée par IntlCalendar::getActualMinimum(), qui est à son tour plus petite ou égale à celle retournée par IntlCalendar::getGreatestMinimum(). Pour le calendrier grégorien, ces trois fonctions retournent toujours la même valeur (pour chaque champ).

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

Un int représentant une valeur de champ, dans lʼunité du champ, ou `false` si une erreur survient.

# IntlCalendar::getNow

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getNow — Récupère le nombre représentant la date courante

### Description

Style orienté objet

public static function IntlCalendar::getNow(): float

Style procédural

function intlcal_get_now(): float

Le nombre de millisecondes qui s'est écoulé depuis la date de référence. Ce nombre est dérivé depuis le temps système.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un nombre à virgule flottante représentant un nombre de millisecondes depuis l'époque, sans compter les secondes intercalaires.

### Exemples

Exemple #1 Exemple avec IntlCalendar::getNow()

    <?php
    $formatter = IntlDateFormatter::create('es_ES',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'Europe/Madrid');

    $val = IntlCalendar::getNow();

    var_dump($val);
    echo $formatter->format(IntlCalendar::getNow() / 1000.), "\n";

L'exemple ci-dessus va afficher :

    float(1371425814666)
    lunes, 17 de junio de 2013 01:36:54 Hora de verano de Europa central

# IntlCalendar::getRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getRepeatedWallTimeOption — Obtient le comportement pour la gestion des heures murales répétées

### Description

Style orienté objet

public function IntlCalendar::getRepeatedWallTimeOption(): int

Style procédural

function intlcal_get_repeated_wall_time_option(IntlCalendar `$calendar`): int

Renvoie la stratégie actuelle pour la gestion des heures murales répétées lorsque l'horloge est remise en arrière lors des transitions de fin d'heure d'été. La valeur par défaut est `IntlCalendar::WALLTIME_LAST`.

Cette fonction requiert ICU 4.9 ou plus récent.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Une des constantes `IntlCalendar::WALLTIME_FIRST` ou `IntlCalendar::WALLTIME_LAST`.

### Exemples

Exemple #1 IntlCalendar::getRepeatedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');
    ini_set('intl.error_level', E_WARNING);

    //Le 27 Octobre à 0200, l'heure reculera d'une heure de GMT+01 à GMT+00
    $cal = new IntlGregorianCalendar(2013, 9 /* October */, 27, 1, 30);

    var_dump($cal->getRepeatedWalltimeOption()); // 0 WALLTIME_LAST

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000.));

    $cal->setRepeatedWalltimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getRepeatedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000.));

L'exemple ci-dessus va afficher :

    int(0)
    string(42) "Sunday, October 27, 2013 at 1:30:00 AM GMT"
    int(1)
    string(43) "Sunday, October 27, 2013 at 12:30:00 AM GMT"

### Voir aussi

- IntlCalendar::getSkippedWallTimeOption() - Obtient le comportement pour la gestion des heures murales sautées
- IntlCalendar::setSkippedWallTimeOption() - Définit le comportement pour la gestion des heures murales sautées lors des transitions de décalage de fuseau horaire positif
- IntlCalendar::setRepeatedWallTimeOption() - Définit le comportement pour la gestion des heures murales répétées lors des transitions de décalage de fuseau horaire négatif

# IntlCalendar::getSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getSkippedWallTimeOption — Obtient le comportement pour la gestion des heures murales sautées

### Description

Style orienté objet

public function IntlCalendar::getSkippedWallTimeOption(): int

Style procédural

function intlcal_get_skipped_wall_time_option(IntlCalendar `$calendar`): int

Renvoie la stratégie actuelle pour la gestion des heures murales sautées lorsque l'horloge est avancée lors des transitions de début d'heure d'été. La valeur par défaut est `IntlCalendar::WALLTIME_LAST`.

Le calendrier doit être tolérant pour que cette option ait un effet, sinon tenter de définir une heure inexistante provoquera une erreur.

Cette fonction requiert ICU 4.9 ou plus récent.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Une des constantes `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` ou `IntlCalendar::WALLTIME_NEXT_VALID`.

### Exemples

Exemple #1 IntlCalendar::getSkippedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');
    ini_set('intl.error_level', E_WARNING);

    //Le 31 Mars à 0100, l'horloge avancera d'une heure de GMT+00 à GMT+01
    $cal = new IntlGregorianCalendar(2013, 2 /* March */, 31, 1, 30);

    var_dump(
        $cal->isLenient(),               // true
        $cal->getSkippedWalltimeOption() // 0 WALLTIME_LAST
    );

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getSkippedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_NEXT_VALID);
    var_dump($cal->getSkippedWalltimeOption()); // 2 WALLTIME_NEXT_VALID
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

L'exemple ci-dessus va afficher :

    bool(true)
    int(0)
    string(40) "Sunday, March 31, 2013 at 1:30:00 AM GMT"
    int(1)
    string(41) "Sunday, March 31, 2013 at 12:30:00 AM GMT"
    int(2)
    string(40) "Sunday, March 31, 2013 at 1:00:00 AM GMT"

### Voir aussi

- IntlCalendar::getRepeatedWallTimeOption() - Obtient le comportement pour la gestion des heures murales répétées
- IntlCalendar::setSkippedWallTimeOption() - Définit le comportement pour la gestion des heures murales sautées lors des transitions de décalage de fuseau horaire positif
- IntlCalendar::setRepeatedWallTimeOption() - Définit le comportement pour la gestion des heures murales répétées lors des transitions de décalage de fuseau horaire négatif

# IntlCalendar::getTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTime — Obtient le temps actuellement représenté par l'objet

### Description

Style orienté objet

public function IntlCalendar::getTime(): float|false

Style procédural

function intlcal_get_time(IntlCalendar `$calendar`): float|false

Renvoie le temps associé à cet objet, exprimé en tant que nombre de millisecondes écoulées depuis l'epoch.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Un float représentant le nombre de millisecondes écoulées depuis le temps de référence (1 Jan 1970 00:00:00 UTC), ou `false` si une erreur survient

### Exemples

Exemple #1 IntlCalendar::getTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = new IntlGregorianCalendar(2013, 4 /* May */, 1, 0, 0, 0);
    $time = $cal->getTime();
    var_dump($time, $time / 1000 == strtotime('2013-05-01 00:00:00')); //true

L'exemple ci-dessus va afficher :

    float(1367362800000)
    bool(true)

### Voir aussi

- IntlCalendar::getNow() - Récupère le nombre représentant la date courante

# IntlCalendar::getTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTimeZone — Récupère le fuseau horaire de l'objet

### Description

Style orienté objet

public function IntlCalendar::getTimeZone(): IntlTimeZone|false

Style procédural

function intlcal_get_time_zone(IntlCalendar `$calendar`): IntlTimeZone|false

Retourne l'objet IntlTimeZone associé avec ce calendrier.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Un objet IntlTimeZone correspondant à celui utilisé en interne de cet objet. Retourne `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec IntlCalendar::getTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = IntlCalendar::createInstance();
    print_r($cal->getTimeZone());

    $cal->setTimeZone('UTC');
    print_r($cal->getTimeZone());

    $cal = IntlCalendar::fromDateTime('2012-01-01 00:00:00 GMT+03:33');
    print_r($cal->getTimeZone());

L'exemple ci-dessus va afficher :

    IntlTimeZone Object
    (
        [valid] => 1
        [id] => Europe/Lisbon
        [rawOffset] => 0
        [currentOffset] => 3600000
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => UTC
        [rawOffset] => 0
        [currentOffset] => 0
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+03:33
        [rawOffset] => 12780000
        [currentOffset] => 12780000
    )

### Voir aussi

- IntlCalendar::setTimeZone() - Définit le fuseau horaire utilisé par ce calendrier
- IntlCalendar::createInstance() - Crée un nouvel objet IntlCalendar
- IntlGregorianCalendar::__construct() - Créer la classe du calendrier grégorien

# IntlCalendar::getType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getType — Récupère le type de calendrier

### Description

Style orienté objet

public function IntlCalendar::getType(): string

Style procédural

function intlcal_get_type(IntlCalendar `$calendar`): string

Une chaîne de caractères décrivant le type de ce calendrier. Cette chaîne sera une parmi les valeurs valides du mot clé `'calendar'` du calendrier.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Une chaîne de caractères string représentant le type de calendrier, par exemple, `'gregorian'`, `'islamic'`, etc.

### Exemples

Exemple #1 Exemple avec IntlCalendar::getType()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = IntlCalendar::createInstance(NULL, '@calendar=ethiopic-amete-alem');
    var_dump($cal->getType());

    $cal = new IntlGregorianCalendar();
    var_dump($cal->getType());

L'exemple ci-dessus va afficher :

    string(19) "ethiopic-amete-alem"
    string(9) "gregorian"

# IntlCalendar::getWeekendTransition

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getWeekendTransition — Obtient l'heure du jour à laquelle le week-end commence ou se termine

### Description

Style orienté objet

public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false

Style procédural

function intlcal_get_weekend_transition(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

Renvoie le nombre de millisecondes écoulées depuis minuit à l'heure à laquelle le week-end commence ou se termine.

Ceci est uniquement applicable pour les jours de la semaine pour lesquels IntlCalendar::getDayOfWeekType() retourne soit `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` ou `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`. Appeler cette fonction pour d'autres jours de la semaine est une condition d'erreur.

Cette fonction requiert ICU 4.4 ou plus.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`dayOfWeek`

  Une des constantes `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Valeurs de retour

Le nombre de millisecondes écoulées depuis minuit à l'heure à laquelle le week-end commence ou se termine ou `false` si une erreur survient.

### Exemples

Voir un exemple sur IntlCalendar::getDayOfWeekType().

# IntlCalendar::inDaylightTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::inDaylightTime — Indique si l'objet est en heure d'été

### Description

Style orienté objet

public function IntlCalendar::inDaylightTime(): bool

Style procédural

function intlcal_in_daylight_time(IntlCalendar `$calendar`): bool

Si, pour l'instant représenté par cet objet et pour le fuseau horaire de cet objet, l'heure d'été est en vigueur.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Renvoie `true` si la date est en heure d'été, sinon `false`.

En cas d&échec `false` est aussi retourné. Pour détecter les conditions d&erreur intl_get_error_code() doit être utilisé, ou paramétrer Intl pour lancer des exceptions.

### Exemples

Exemple #1 IntlCalendar::inDaylightTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1, 4, 56, 31);
    var_dump($cal->inDaylightTime()); // true
    $cal->set(IntlCalendar::FIELD_MONTH, 11 /* December */);
    var_dump($cal->inDaylightTime()); // false

    //Fin de l'heure d'été le 2013-10-27 à 0200 (recul d'une heure)
    $cal = new IntlGregorianCalendar(2013, 9 /* October */, 27, 1, 30, 0);

    var_dump($cal->inDaylightTime()); // false (default WALLTIME_LAST)

    $cal->setRepeatedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1); // force time recalculation
    var_dump($cal->inDaylightTime()); // true

# IntlCalendar::isEquivalentTo

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isEquivalentTo — Indique si un autre calendrier est équivalent, mais pour un autre moment

### Description

Style orienté objet

public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool

Style procédural

function intlcal_is_equivalent_to(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Renvoie si cet objet et celui donné sont équivalents pour tous les usages, sauf pour le moment qu'ils ont défini. Les fuseaux horaires n'ont pas à correspondre, tant qu'aucun changement de comportement n'en résulte. Cela inclut le fuseau horaire, si le mode laxiste est défini, les paramètres de temps de mur répété et sauté, les jours de la semaine où le week-end commence et cesse et les heures où de telles transitions se produisent. Cela peut également inclure d'autres paramètres spécifiques au calendrier, tels que l'instant de transition grégorien/julien.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`other`

  L'autre calendrier par rapport auquel la comparaison doit être faite.

### Valeurs de retour

En supposant qu'il n'y a pas d'erreurs d'argument, renvoie `true` si les calendriers sont équivalents, sauf peut-être pour leur moment défini.

### Exemples

Exemple #1 IntlCalendar::isEquivalentTo()

    <?php
    $cal1 = IntlCalendar::createInstance('Europe/Lisbon', 'pt_PT');
    $cal2 = IntlCalendar::createInstance('Europe/Lisbon', 'es_ES');
    $cal2->clear();

    var_dump($cal1->isEquivalentTo($cal2)); // true

    $cal3 = IntlCalendar::createInstance('Europe/Lisbon', 'en_US');
    var_dump($cal1->isEquivalentTo($cal3)); // false
    var_dump($cal1->getFirstDayOfWeek(),    // 2 (Monday)
    $cal3->getFirstDayOfWeek());            // 1 (Sunday)

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    int(2)
    int(1)

### Voir aussi

- IntlCalendar::equals() - Vérifie si deux objets IntlCalendar sont égaux

# IntlCalendar::isLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isLenient — Indique si l'interprétation de la date/heure est en mode tolérant

### Description

Style orienté objet

public function IntlCalendar::isLenient(): bool

Style procédural

function intlcal_is_lenient(IntlCalendar `$calendar`): bool

Renvoie si l'interprétation de la date/heure est en mode tolérant (le mode par défaut). Si c'est le cas, certaines valeurs hors limites pour les champs seront acceptées au lieu de générer une erreur.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Un bool représentant si le calendrier est en mode tolérant.

### Exemples

Exemple #1 IntlCalendar::isLenient()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');
    ini_set('intl.use_exceptions', '1');

    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
    var_dump(IntlDateFormatter::formatObject($cal), // 01/07/2013, 00:00:00
    $cal->isLenient()); // true

    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // 02/08/2013, 00:00:00

    $cal->setLenient(false);
    var_dump($cal->isLenient()); // false
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // erreur

L'exemple ci-dessus va afficher :

    string(20) "01/07/2013, 00:00:00"
    bool(true)
    string(20) "02/08/2013, 00:00:00"
    bool(false)

    Fatal error: Uncaught exception 'IntlException' with message 'datefmt_format_object: error obtaining instant from IntlCalendar' in /home/foobar/example.php:16
    Stack trace:
    #0 /home/foobar/example.php(16): IntlDateFormatter::formatObject(Object(IntlGregorianCalendar))
    #1 {main}
      thrown in /home/foobar/example.php on line 16

# IntlCalendar::isSet

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isSet — Indique si un champ est défini

### Description

Style orienté objet

public function IntlCalendar::isSet(int `$field`): bool

Style procédural

function intlcal_is_set(IntlCalendar `$calendar`, int `$field`): bool

Renvoie si un champ est défini (par opposition à effacé). Les champs définis ont la priorité sur les champs non définis et leurs valeurs par défaut lors du calcul de la date/heure. Les champs définis plus tard ont la priorité sur les champs définis plus tôt.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

### Valeurs de retour

En supposant qu'il n'y a pas d'erreurs d'arguments, renvoie `true` si le champ est défini.

### Exemples

Voir un exemple sur IntlCalendar::clear().

### Voir aussi

- IntlCalendar::clear() - Vide un ou tous les champs
- IntlCalendar::set() - Définit un champ de temps ou plusieurs champs communs en une seule fois

# IntlCalendar::isWeekend

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isWeekend — Indique si une date/heure est un week-end

### Description

Style orienté objet

public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool

Style procédural

function intlcal_is_weekend(IntlCalendar `$calendar`, ?float `$timestamp` = `null`): bool

Renvoie si l'heure actuelle de l'objet ou le timestamp fourni se produit pendant un week-end dans le système de calendrier de cet objet.

Cette fonction nécessite ICU 4.4 ou plus récent.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`timestamp`

  Un timestamp optionnel représentant le nombre de millisecondes écoulées depuis l'epoch, excluant les secondes intercalaires. Si `null`, le temps actuel de cet objet est utilisé à la place.

### Valeurs de retour

Un bool indiquant si le temps donné ou celui de cet objet se produit pendant un week-end.

En cas d&échec `false` est aussi retourné. Pour détecter les conditions d&erreur intl_get_error_code() doit être utilisé, ou paramétrer Intl pour lancer des exceptions.

### Exemples

Exemple #1 IntlCalendar::isWeekend()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = new IntlGregorianCalendar(NULL, 'en_US');
    $cal->set(2013, 6 /* July */, 7); // un dimanche

    var_dump($cal->isWeekend()); // true
    var_dump($cal->isWeekend(strtotime('2013-07-01 00:00:00'))); // false, Monday

    $cal = new IntlGregorianCalendar(NULL, 'ar_SA');
    $cal->set(2013, 6 /* July */, 7); // un dimanche
    var_dump($cal->isWeekend()); // false, dimanche n'est pas dans le week-end sur ce calendrier

### Voir aussi

- IntlCalendar::getDayOfWeekType() - Indique si un jour est un jour de la semaine, un week-end ou un jour de transition entre les deux
- IntlCalendar::getWeekendTransition() - Obtient l'heure du jour à laquelle le week-end commence ou se termine

# IntlCalendar::roll

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::roll — Ajoute une valeur à un champ sans la reporter sur les champs plus significatifs

### Description

Style orienté objet

public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool

Style procédural

function intlcal_roll(IntlCalendar `$calendar`, int `$field`, int|bool `$value`): bool

Ajoute une valeur (signée) à un champ. La différence avec IntlCalendar::add() est que lorsque la valeur du champ déborde, elle ne se reporte pas sur les champs plus significatifs.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

`value`

  La valeur (signée) à ajouter au champ, `true` pour aller vers le haut (ajoutant `1`), ou `false` pour aller vers le bas (soustrayant `1`).

### Valeurs de retour

Renvoie `true` en cas de succès ou `false` en cas d'échec.

### Exemples

Exemple #1 IntlCalendar::roll()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 5 /* June */, 30);

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/07/2013, 00:00:00"

    $cal->set(2013, 5 /* June */, 30);
    $cal->roll(IntlCalendar::FIELD_DAY_OF_MONTH, true); // aller en up, comme rouler +1
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/06/2013, 00:00:00"

L'exemple ci-dessus va afficher :

    string(20) "01/07/2013, 00:00:00"
    string(20) "01/06/2013, 00:00:00"

### Voir aussi

- IntlCalendar::add() - Ajoute une durée (signée) à un champ
- IntlCalendar::set() - Définit un champ de temps ou plusieurs champs communs en une seule fois

# IntlCalendar::set

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::set — Définit un champ de temps ou plusieurs champs communs en une seule fois

### Description

Style orienté objet

public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true

Style procédural

function intlcal_set(IntlCalendar `$cal`, int `$field`, int `$value`): true
function intlcal_set(
IntlCalendar `$cal`,
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): bool

Définit soit un champ spécifique à la valeur donnée, soit définit en une seule fois plusieurs champs communs. La plage de valeurs acceptées dépend de si le calendrier utilise le mode tolérant.

Pour les champs qui entrent en conflit, les champs définis plus tard ont la priorité.

Cette méthode ne peut pas être appelée avec exactement quatre arguments.

### Liste de paramètres

`cal`
  Une instance IntlCalendar.
`field`

  Une constante de champ date/heure IntlCalendar. Ce sont des valeurs entières comprises entre `0` et `IntlCalendar::FIELD_COUNT`.

`value`

  La nouvelle valeur du champ donné.

`year`

  La nouvelle valeur pour `IntlCalendar::FIELD_YEAR`.

`month`

  La nouvelle valeur pour `IntlCalendar::FIELD_MONTH`. La séquence des mois commence à zéro, c'est-à-dire que janvier est représenté par 0, février par 1, …, décembre par 11 et Undecember (si le calendrier le supporte) par 12.

`dayOfMonth`

  La nouvelle valeur pour `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  La nouvelle valeur pour `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  La nouvelle valeur pour `IntlCalendar::FIELD_MINUTE`.

`second`

  La nouvelle valeur pour `IntlCalendar::FIELD_SECOND`.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.2.0 | Le type de retour est maintenant `true`, auparavant il était bool.
8.4.0 | Ceci a été déprécié au profit des méthodes IntlCalendar::setDate() et IntlCalendar::setDateTime().

### Exemples

Exemple #1 IntlCalendar::set()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    //Les derniers appels ont la priorité
    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    var_dump(IntlDateFormatter::formatObject($cal));

    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    //le temps n'a pas été recalculé. Si nous effaçons l'année étendue,
    //l'année définie avant sera utilisée
    $cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR);
    var_dump(IntlDateFormatter::formatObject($cal));

L'exemple ci-dessus va afficher :

    string(20) "01/07/2011, 00:00:00"
    string(20) "01/07/2012, 00:00:00"

### Voir aussi

- IntlCalendar::get() - Récupère la valeur d'une propriété
- IntlCalendar::add() - Ajoute une durée (signée) à un champ
- IntlCalendar::roll() - Ajoute une valeur à un champ sans la reporter sur les champs plus significatifs

# IntlCalendar::setDate

(PHP 8 >= 8.3.0)

IntlCalendar::setDate — Définit un champ de date

### Description

public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void

Définit un champ de date à la valeur donnée.

### Liste de paramètres

`year`

  La nouvelle valeur pour `IntlCalendar::FIELD_YEAR`.

`month`

  La nouvelle valeur pour `IntlCalendar::FIELD_MONTH`. La séquence des mois commence à zéro, c'est-à-dire que janvier est représenté par 0, février par 1, …, décembre par 11 et Undecember (si le calendrier le supporte) par 12.

`dayOfMonth`

  La nouvelle valeur pour `IntlCalendar::FIELD_DAY_OF_MONTH`.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple de IntlCalendar::setDate()

    <?php
    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDate(2012, 1, 29);
    ?>

# IntlCalendar::setDateTime

(PHP 8 >= 8.3.0)

IntlCalendar::setDateTime — Définit un champ de date et d'heure

### Description

public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void

Définit un champ de date et d'heure à la valeur donnée.

### Liste de paramètres

`year`

  La nouvelle valeur pour `IntlCalendar::FIELD_YEAR`.

`month`

  La nouvelle valeur pour `IntlCalendar::FIELD_MONTH`. La séquence des mois commence à zéro, c'est-à-dire que janvier est représenté par 0, février par 1, …, décembre par 11 et Undecember (si le calendrier le supporte) par 12.

`dayOfMonth`

  La nouvelle valeur pour `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  La nouvelle valeur pour `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  La nouvelle valeur pour `IntlCalendar::FIELD_MINUTE`.

`second`

  La nouvelle valeur pour `IntlCalendar::FIELD_SECOND`.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple de IntlCalendar::setDateTime()

    <?php
    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDateTime(2012, 1, 29, 23, 58);
    ?>

# IntlCalendar::setFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setFirstDayOfWeek — Définit le jour de début de la semaine

### Description

Style orienté objet

public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true

Style procédural

function intlcal_set_first_day_of_week(IntlCalendar `$calendar`, int `$dayOfWeek`): true

Définit le jour de début de la semaine. Ceci affecte le comportement des champs qui dépendent du concept de début et de fin de semaine, comme `IntlCalendar::FIELD_WEEK_OF_YEAR` et `IntlCalendar::FIELD_YEAR_WOY`.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`dayOfWeek`

  Une constante parmi `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.2.0 | Le type de retour est maintenant `true`, auparavant il était bool.

### Exemples

Exemple #1 Exemple avec IntlCalendar::setFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = IntlCalendar::createInstance();
    $cal->set(2013, 5 /* Juin */, 30); // Un dimanche

    var_dump($cal->getFirstDayOfWeek()); // 2 (Lundi)

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'jour local de la semaine : 'cc'
    semaine du mois           : 'W'
    semaine de l'année        : 'ww
    EOD
    ), "\n";

    $cal->setFirstDayOfWeek(IntlCalendar::DOW_SUNDAY);

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'jour local de la semaine : 'cc'
    semaine du mois           : 'W'
    semaine de l'année        : 'ww
    EOD
    ), "\n";

L'exemple ci-dessus va afficher :

    int(2)
    jour local de la semaine  : 7
    semaine du mois           : 4
    semaine de l'année        : 26
    jour local de la semaine  : 1
    semaine du mois           : 5
    semaine de l'année        : 27

# IntlCalendar::setLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setLenient — Définit si l'interprétation de la date/heure est tolérante

### Description

Style orienté objet

public function IntlCalendar::setLenient(bool `$lenient`): true

Style procédural

function intlcal_set_lenient(IntlCalendar `$calendar`, bool `$lenient`): true

Définit si l'interprétation de la date/heure est tolérante. Dans un tel mode, certaines valeurs hors limites pour certains champs sont acceptées, le comportement étant similaire à celui de IntlCalendar::add() (c'est-à-dire, la valeur reboucle, se reportant dans des champs plus significatifs à chaque fois). Si le mode tolérant est désactivé, alors de telles valeurs généreront une erreur.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`lenient`

  Utiliser `true` pour activer le mode tolérant; `false` sinon.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.2.0 | Le type de retour est maintenant `true`, auparavant il était bool.

### Exemples

Voir un exemple sur IntlCalendar::isLenient().

# IntlCalendar::setMinimalDaysInFirstWeek

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

IntlCalendar::setMinimalDaysInFirstWeek — Définit le nombre minimal de jours que la première semaine d'une année ou d'un mois peut avoir

### Description

Style orienté objet

public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true

Style procédural

function intlcal_set_minimal_days_in_first_week(IntlCalendar `$calendar`, int `$days`): true

Définit le nombre minimal de jours que la première semaine d'une année ou d'un mois peut avoir dans la nouvelle année ou le nouveau mois. Par exemple, dans le calendrier grégorien, si cette valeur est 1, alors la première semaine de l'année inclura nécessairement le 1er janvier, tandis que si cette valeur est 7, alors la semaine avec le 1er janvier sera la première semaine de l'année uniquement si le jour de la semaine pour le 1er janvier correspond au jour de la semaine retourné par IntlCalendar::getFirstDayOfWeek(); sinon, ce sera la dernière semaine de l'année précédente.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`days`

  Le nombre de jours minimal à définir.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

ValueError si `days` est hors de portée (moins que `1` ou plus que `7`).

### Historique

Version | Description
--- | ---
8.0.0 | Une ValueError est lancée sur une entrée invalide. Précédemment, `false` était retourné.

# IntlCalendar::setRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setRepeatedWallTimeOption — Définit le comportement pour la gestion des heures murales répétées lors des transitions de décalage de fuseau horaire négatif

### Description

Style orienté objet

public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true

Style procédural

function intlcal_set_repeated_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Définit la stratégie actuelle pour la gestion des heures murales répétées chaque fois que l'horloge est reculée lors des transitions de fin de l'heure d'été. La valeur par défaut est `IntlCalendar::WALLTIME_LAST` (prendre l'instant post-DST). L'autre valeur possible est `IntlCalendar::WALLTIME_FIRST` (prendre l'instant qui se produit pendant l'heure d'été).

Cette fonction nécessite ICU 4.9 ou plus.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`option`

  L'une des constantes `IntlCalendar::WALLTIME_FIRST` ou `IntlCalendar::WALLTIME_LAST`.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.2.0 | Le type de retour est maintenant `true`, auparavant il était bool.

### Exemples

Voir un exemple sur IntlCalendar::getRepeatedWallTimeOption().

### Voir aussi

- intlCalendar::getRepeatedWallTimeOption() - Obtient le comportement pour la gestion des heures murales répétées
- intlCalendar::setSkippedWallTimeOption() - Définit le comportement pour la gestion des heures murales sautées lors des transitions de décalage de fuseau horaire positif
- intlCalendar::getSkippedWallTimeOption() - Obtient le comportement pour la gestion des heures murales sautées

# IntlCalendar::setSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setSkippedWallTimeOption — Définit le comportement pour la gestion des heures murales sautées lors des transitions de décalage de fuseau horaire positif

### Description

Style orienté objet

public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true

Style procédural

function intlcal_set_skipped_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Définit la stratégie actuelle pour la gestion des heures murales sautées chaque fois que l'horloge est avancée lors des transitions de début de l'heure d'été. La valeur par défaut est `IntlCalendar::WALLTIME_LAST` (prendre l'instant post-DST). Les autres valeurs possibles sont `IntlCalendar::WALLTIME_FIRST` (prendre l'instant qui se produit pendant l'heure d'été) et `IntlCalendar::WALLTIME_NEXT_VALID` (prendre l'instant lorsque l'heure d'été commence).

Cela affecte uniquement l'instant représenté par le calendrier (tel que rapporté par IntlCalendar::getTime()), les valeurs des champs ne seront pas réécrites en conséquence.

Le calendrier doit être tolérant pour que cette option ait un effet, sinon tenter de définir un temps inexistant provoquera une erreur.

Cette fonction requiert ICU 4.9 ou plus.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`option`

  L'une des constantes `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` ou `IntlCalendar::WALLTIME_NEXT_VALID`.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.2.0 | Le type de retour est maintenant `true`, auparavant il était bool.

### Exemples

Voir un exemple sur IntlCalendar::getSkippedWallTimeOption().

### Voir aussi

- intlCalendar::getSkippedWallTimeOption() - Obtient le comportement pour la gestion des heures murales sautées
- intlCalendar::setRepeatedWallTimeOption() - Définit le comportement pour la gestion des heures murales répétées lors des transitions de décalage de fuseau horaire négatif
- intlCalendar::getRepeatedWallTimeOption() - Obtient le comportement pour la gestion des heures murales répétées

# IntlCalendar::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTime — Définit le temps du calendrier en milliseconde depuis l'époque

### Description

Style orienté objet

public function IntlCalendar::setTime(float `$timestamp`): bool

Style procédural

function intlcal_set_time(IntlCalendar `$calendar`, float `$timestamp`): bool

Définit l'instant représenté par cet objet. L'instant est représenté par un float dont la valeur est un nombre entier de millisecondes depuis l'époque Unix (1 Jan 1970 00:00:00.000 UTC), en ignorant les secondes intercalaires. Toutes les valeurs des champs seront recalculées en conséquence.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`timestamp`

  Un instant, représenté par le nombre de millisecondes entre l'instant et l'époque Unix, en ignorant les secondes intercalaires.

### Valeurs de retour

Retourne `true` en cas de succès, `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec IntlCalendar::setTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    /* En Europe/Lisbon, le 2013-10-27 à 0200, l'horloge perd une heure
       et le fuseau horaire passe de UTC+01 à UTC+00 */

    $cal->setTime(strtotime('2013-10-27 00:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    $cal->setTime(strtotime('2013-10-27 01:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

L'exemple ci-dessus va afficher :

    samedi 1 juin 2013 12:00:00 heure avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure normale d’Europe de l’Ouest

# IntlCalendar::setTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTimeZone — Définit le fuseau horaire utilisé par ce calendrier

### Description

Style orienté objet

public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Style procédural

function intlcal_set_time_zone(IntlCalendar `$calendar`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Définit un nouveau fuseau horaire pour ce calendrier. Le moment représenté par cet objet est préservé au détriment des valeurs des champs.

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.
`timezone`

  Le nouveau fuseau horaire à utiliser par ce calendrier. Il peut être spécifié de la façon suivante :

  - `null`, dans quel cas le fuseau horaire par défaut sera utilisé, comme spécifié dans le paramètre de configuration du fichier ini date.timezone ou par la fonction date_default_timezone_set() et comme retourné par date_default_timezone_get().

  - Un IntlTimeZone, qui sera utilisé directement.

  - Un DateTimeZone. Son identifiant sera extrait et un objet de fuseau horaire ICU sera créé; le fuseau horaire sera soutenu par la base de données de l'ICU, et non par PHP.

  - Une chaîne de caractères, qui devrait être un identifiant de fuseau horaire ICU valide. Voir IntlTimeZone::createTimeZoneIDEnumeration(). Les décalages bruts tels que `"GMT+08:30"` sont aussi acceptés.

### Valeurs de retour

Retourne `true` en cas de succès, `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec IntlCalendar::setTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone(IntlTimeZone::getGMT());
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone('GMT+03:33');
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

L'exemple ci-dessus va afficher :

    sábado, 1 de junio de 2013 12:00:00 Hora de verano de Europa occidental
    (instant 1370084400000)
    sábado, 1 de junio de 2013 11:00:00 GMT
    (instant 1370084400000)
    sábado, 1 de junio de 2013 14:33:00 GMT+03:33
    (instant 1370084400000)

# IntlCalendar::toDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::toDateTime — Convertit un objet IntlCalendar en un objet DateTime

### Description

Style orienté objet

public function IntlCalendar::toDateTime(): DateTime|false

Style procédural

function intlcal_to_date_time(IntlCalendar `$calendar`): DateTime|false

Crée un objet DateTime qui représente le même instant (avec une précision à la seconde) et avec un fuseau horaire analogue à l'objet initial (la seule différence est que le fuseau horaire de l'objet DateTime sera compris par PHP, alors que le fuseau horaire de l'objet IntlCalendar sera compris par ICU).

### Liste de paramètres

`calendar`
  Une instance IntlCalendar.

### Valeurs de retour

Un objet DateTime avec le même fuseau horaire que l'objet d'origine (en utilisant la base de données PHP au lieu de celle d'ICU) et représentant le même moment, mis à part la précision (précision à la seconde au lieu de milliseconde). Retourne `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec IntlCalendar::toDateTime()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = IntlCalendar::createInstance('Europe/Lisbon'); //temps courant

    $dt = $cal->toDateTime();
    print_r($dt);

L'exemple ci-dessus va afficher :

    DateTime Object
    (
        [date] => 2013-07-02 00:29:13
        [timezone_type] => 3
        [timezone] => Europe/Lisbon
    )

### Voir aussi

- IntlCalendar::fromDateTime() - Créer un IntlCalendar depuis un objet DateTime ou une chaîne de caractères
- IntlCalendar::getTime() - Obtient le temps actuellement représenté par l'objet
- IntlCalendar::createInstance() - Crée un nouvel objet IntlCalendar
- DateTime::__construct() - Retourne un nouvel objet DateTime

## Sommaire

- IntlCalendar::add — Ajoute une durée (signée) à un champ
- IntlCalendar::after — Vérifie si l'objet temps courant est dans le futur par rapport à l'objet temps passé
- IntlCalendar::before — Vérifie si l'objet temps est dans le passé par rapport à l'objet fourni
- IntlCalendar::clear — Vide un ou tous les champs
- IntlCalendar::__construct — Constructeur privé pour la désactivation de l'instanciation
- IntlCalendar::createInstance — Crée un nouvel objet IntlCalendar
- IntlCalendar::equals — Vérifie si deux objets IntlCalendar sont égaux
- IntlCalendar::fieldDifference — Calcule la différence entre le temps donné et le temps de l'objet
- IntlCalendar::fromDateTime — Créer un IntlCalendar depuis un objet DateTime ou une chaîne de caractères
- IntlCalendar::get — Récupère la valeur d'une propriété
- IntlCalendar::getActualMaximum — La valeur maximale pour un champ, en considérant le temps actuel de l'objet
- IntlCalendar::getActualMinimum — La valeur minimale pour un champ, en considérant le temps actuel de l'objet
- IntlCalendar::getAvailableLocales — Renvoie un tableau des locales pour lesquelles il y a des données
- IntlCalendar::getDayOfWeekType — Indique si un jour est un jour de la semaine, un week-end ou un jour de transition entre les deux
- IntlCalendar::getErrorCode — Renvoie le dernier code d'erreur sur l'objet
- IntlCalendar::getErrorMessage — Renvoie le dernier message d'erreur sur l'objet
- IntlCalendar::getFirstDayOfWeek — Renvoie le premier jour de la semaine pour la locale du calendrier
- IntlCalendar::getGreatestMinimum — Renvoie la plus grande valeur minimale locale pour un champ
- IntlCalendar::getKeywordValuesForLocale — Renvoie l'ensemble des valeurs de mots-clés de locale
- IntlCalendar::getLeastMaximum — Obtient le plus petit maximum local pour un champ
- IntlCalendar::getLocale — Renvoie la locale associée à l'objet
- IntlCalendar::getMaximum — Obtient la valeur maximale globale pour un champ
- IntlCalendar::getMinimalDaysInFirstWeek — Obtient le nombre minimal de jours que la première semaine dʼune année ou dʼun mois peut avoir
- IntlCalendar::getMinimum — Obtient la valeur minimale globale pour un champ
- IntlCalendar::getNow — Récupère le nombre représentant la date courante
- IntlCalendar::getRepeatedWallTimeOption — Obtient le comportement pour la gestion des heures murales répétées
- IntlCalendar::getSkippedWallTimeOption — Obtient le comportement pour la gestion des heures murales sautées
- IntlCalendar::getTime — Obtient le temps actuellement représenté par l'objet
- IntlCalendar::getTimeZone — Récupère le fuseau horaire de l'objet
- IntlCalendar::getType — Récupère le type de calendrier
- IntlCalendar::getWeekendTransition — Obtient l'heure du jour à laquelle le week-end commence ou se termine
- IntlCalendar::inDaylightTime — Indique si l'objet est en heure d'été
- IntlCalendar::isEquivalentTo — Indique si un autre calendrier est équivalent, mais pour un autre moment
- IntlCalendar::isLenient — Indique si l'interprétation de la date/heure est en mode tolérant
- IntlCalendar::isSet — Indique si un champ est défini
- IntlCalendar::isWeekend — Indique si une date/heure est un week-end
- IntlCalendar::roll — Ajoute une valeur à un champ sans la reporter sur les champs plus significatifs
- IntlCalendar::set — Définit un champ de temps ou plusieurs champs communs en une seule fois
- IntlCalendar::setDate — Définit un champ de date
- IntlCalendar::setDateTime — Définit un champ de date et d'heure
- IntlCalendar::setFirstDayOfWeek — Définit le jour de début de la semaine
- IntlCalendar::setLenient — Définit si l'interprétation de la date/heure est tolérante
- IntlCalendar::setMinimalDaysInFirstWeek — Définit le nombre minimal de jours que la première semaine d'une année ou d'un mois peut avoir
- IntlCalendar::setRepeatedWallTimeOption — Définit le comportement pour la gestion des heures murales répétées lors des transitions de décalage de fuseau horaire négatif
- IntlCalendar::setSkippedWallTimeOption — Définit le comportement pour la gestion des heures murales sautées lors des transitions de décalage de fuseau horaire positif
- IntlCalendar::setTime — Définit le temps du calendrier en milliseconde depuis l'époque
- IntlCalendar::setTimeZone — Définit le fuseau horaire utilisé par ce calendrier
- IntlCalendar::toDateTime — Convertit un objet IntlCalendar en un objet DateTime

# La classe IntlGregorianCalendar

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

## Synopsis de la classe

class IntlGregorianCalendar extends IntlCalendar {
/* Constantes héritées */
public const int IntlCalendar::FIELD_ERA;
public const int IntlCalendar::FIELD_YEAR;
public const int IntlCalendar::FIELD_MONTH;
public const int IntlCalendar::FIELD_WEEK_OF_YEAR;
public const int IntlCalendar::FIELD_WEEK_OF_MONTH;
public const int IntlCalendar::FIELD_DATE;
public const int IntlCalendar::FIELD_DAY_OF_YEAR;
public const int IntlCalendar::FIELD_DAY_OF_WEEK;
public const int IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH;
public const int IntlCalendar::FIELD_AM_PM;
public const int IntlCalendar::FIELD_HOUR;
public const int IntlCalendar::FIELD_HOUR_OF_DAY;
public const int IntlCalendar::FIELD_MINUTE;
public const int IntlCalendar::FIELD_SECOND;
public const int IntlCalendar::FIELD_MILLISECOND;
public const int IntlCalendar::FIELD_ZONE_OFFSET;
public const int IntlCalendar::FIELD_DST_OFFSET;
public const int IntlCalendar::FIELD_YEAR_WOY;
public const int IntlCalendar::FIELD_DOW_LOCAL;
public const int IntlCalendar::FIELD_EXTENDED_YEAR;
public const int IntlCalendar::FIELD_JULIAN_DAY;
public const int IntlCalendar::FIELD_MILLISECONDS_IN_DAY;
public const int IntlCalendar::FIELD_IS_LEAP_MONTH;
public const int IntlCalendar::FIELD_FIELD_COUNT;
public const int IntlCalendar::FIELD_DAY_OF_MONTH;
public const int IntlCalendar::DOW_SUNDAY;
public const int IntlCalendar::DOW_MONDAY;
public const int IntlCalendar::DOW_TUESDAY;
public const int IntlCalendar::DOW_WEDNESDAY;
public const int IntlCalendar::DOW_THURSDAY;
public const int IntlCalendar::DOW_FRIDAY;
public const int IntlCalendar::DOW_SATURDAY;
public const int IntlCalendar::DOW_TYPE_WEEKDAY;
public const int IntlCalendar::DOW_TYPE_WEEKEND;
public const int IntlCalendar::DOW_TYPE_WEEKEND_OFFSET;
public const int IntlCalendar::DOW_TYPE_WEEKEND_CEASE;
public const int IntlCalendar::WALLTIME_FIRST;
public const int IntlCalendar::WALLTIME_LAST;
public const int IntlCalendar::WALLTIME_NEXT_VALID;
/* Méthodes */
public function __construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function __construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function __construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)
public static function createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static
public static function createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static
public function getGregorianChange(): float
public function isLeapYear(int `$year`): bool
public function setGregorianChange(float `$timestamp`): bool
/* Méthodes héritées */
public function IntlCalendar::add(int `$field`, int `$value`): bool
public function IntlCalendar::after(IntlCalendar `$other`): bool
public function IntlCalendar::before(IntlCalendar `$other`): bool
public function IntlCalendar::clear(?int `$field` = `null`): true
public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::equals(IntlCalendar `$other`): bool
public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false
public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::get(int `$field`): int|false
public function IntlCalendar::getActualMaximum(int `$field`): int|false
public function IntlCalendar::getActualMinimum(int `$field`): int|false
public static function IntlCalendar::getAvailableLocales(): array
public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false
public function IntlCalendar::getErrorCode(): int|false
public function IntlCalendar::getErrorMessage(): string|false
public function IntlCalendar::getFirstDayOfWeek(): int|false
public function IntlCalendar::getGreatestMinimum(int `$field`): int|false
public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function IntlCalendar::getLeastMaximum(int `$field`): int|false
public function IntlCalendar::getLocale(int `$type`): string|false
public function IntlCalendar::getMaximum(int `$field`): int|false
public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false
public function IntlCalendar::getMinimum(int `$field`): int|false
public static function IntlCalendar::getNow(): float
public function IntlCalendar::getRepeatedWallTimeOption(): int
public function IntlCalendar::getSkippedWallTimeOption(): int
public function IntlCalendar::getTime(): float|false
public function IntlCalendar::getTimeZone(): IntlTimeZone|false
public function IntlCalendar::getType(): string
public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false
public function IntlCalendar::inDaylightTime(): bool
public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool
public function IntlCalendar::isLenient(): bool
public function IntlCalendar::isSet(int `$field`): bool
public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool
public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool
public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true
public function IntlCalendar::setLenient(bool `$lenient`): true
public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true
public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true
public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true
public function IntlCalendar::setTime(float `$timestamp`): bool
public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function IntlCalendar::toDateTime(): DateTime|false
}

# IntlGregorianCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::__construct — Créer la classe du calendrier grégorien

### Description

public function IntlGregorianCalendar::__construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function IntlGregorianCalendar::__construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function IntlGregorianCalendar::__construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`tz`

`locale`

`timeZoneOrYear`

`localeOrMonth`

`dayOfMonth`

`hour`

`minute`

`second`

### Historique

Version | Description
--- | ---
8.4.0 | Ceci a été déprécié au profit des méthodes IntlGregorianCalendar::createFromDate() et IntlGregorianCalendar::createFromDateTime().

# IntlGregorianCalendar::createFromDate

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDate — Créer une nouvelle instance de IntlGregorianCalendar à partir d'une date

### Description

public static function IntlGregorianCalendar::createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static

Crée une nouvelle instance de IntlGregorianCalendar à partir d'une date.

### Liste de paramètres

`year`

  La nouvelle valeur pour `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  La nouvelle valeur pour `IntlGregorianCalendar::FIELD_MONTH`. La séquence des mois commence à zéro, c'est-à-dire que janvier est représenté par 0, février par 1, …, décembre est 11 et Undécembre (si le calendrier le permet) est 12.

`dayOfMonth`

  La nouvelle valeur pour `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

### Valeurs de retour

Renvoie une nouvelle instance de IntlGregorianCalendar.

### Exemples

Exemple #1 Exemple de IntlGregorianCalendar::createFromDate()

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDate(2023, 11, 23);
    var_dump($intlCalendar);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(0)
        ["is leap month"]=>
        int(0)
      }
    }

### Voir aussi

- IntlGregorianCalendar::createFromDateTime() - Créer une nouvelle instance de IntlGregorianCalendar à partir d'une date et d'une heure

# IntlGregorianCalendar::createFromDateTime

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDateTime — Créer une nouvelle instance de IntlGregorianCalendar à partir d'une date et d'une heure

### Description

public static function IntlGregorianCalendar::createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static

Crée une nouvelle instance de IntlGregorianCalendar à partir d'une date et d'une heure.

### Liste de paramètres

`year`

  La nouvelle valeur pour `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  La nouvelle valeur pour `IntlGregorianCalendar::FIELD_MONTH`. La séquence des mois commence à zéro, c'est-à-dire que janvier est représenté par 0, février par 1, …, décembre est 11 et Undécembre (si le calendrier le permet) est 12.

`dayOfMonth`

  La nouvelle valeur pour `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  La nouvelle valeur pour `IntlGregorianCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  La nouvelle valeur pour `IntlGregorianCalendar::FIELD_MINUTE`.

`second`

  La nouvelle valeur pour `IntlGregorianCalendar::FIELD_SECOND`.

### Valeurs de retour

Renvoie une nouvelle instance de IntlGregorianCalendar.

### Exemples

Exemple #1 Exemple de IntlGregorianCalendar::createFromDateTime()

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDateTime(2023, 11, 23, 12, 00);
    var_dump($intlCalendar);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(1)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(12)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(43200000)
        ["is leap month"]=>
        int(0)
      }
    }

### Voir aussi

- IntlGregorianCalendar::createFromDate() - Créer une nouvelle instance de IntlGregorianCalendar à partir d'une date

# IntlGregorianCalendar::getGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::getGregorianChange — Renvoie la date de changement du calendrier grégorien

### Description

public function IntlGregorianCalendar::getGregorianChange(): float

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie la date de changement.

# IntlGregorianCalendar::isLeapYear

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::isLeapYear — Détermine si l'année donnée est une année bissextile

### Description

public function IntlGregorianCalendar::isLeapYear(int `$year`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`year`

### Valeurs de retour

Renvoie `true` pour les années bissextiles, `false` sinon et en cas d'échec.

# IntlGregorianCalendar::setGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::setGregorianChange — Définit la date de changement du calendrier grégorien

### Description

public function IntlGregorianCalendar::setGregorianChange(float `$timestamp`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timestamp`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

## Sommaire

- IntlGregorianCalendar::__construct — Créer la classe du calendrier grégorien
- IntlGregorianCalendar::createFromDate — Créer une nouvelle instance de IntlGregorianCalendar à partir d'une date
- IntlGregorianCalendar::createFromDateTime — Créer une nouvelle instance de IntlGregorianCalendar à partir d'une date et d'une heure
- IntlGregorianCalendar::getGregorianChange — Renvoie la date de changement du calendrier grégorien
- IntlGregorianCalendar::isLeapYear — Détermine si l'année donnée est une année bissextile
- IntlGregorianCalendar::setGregorianChange — Définit la date de changement du calendrier grégorien

# La classe IntlTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Introduction

## Synopsis de la classe

class IntlTimeZone {
/* Constantes */
public const int DISPLAY_SHORT;
public const int DISPLAY_LONG;
public const int DISPLAY_SHORT_GENERIC;
public const int DISPLAY_LONG_GENERIC;
public const int DISPLAY_SHORT_GMT;
public const int DISPLAY_LONG_GMT;
public const int DISPLAY_SHORT_COMMONLY_USED;
public const int DISPLAY_GENERIC_LOCATION;
public const int TYPE_ANY;
public const int TYPE_CANONICAL;
public const int TYPE_CANONICAL_LOCATION;
/* Méthodes */
private function __construct()
public static function countEquivalentIDs(string `$timezoneId`): int|false
public static function createDefault(): IntlTimeZone
public static function createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false
public static function createTimeZone(string `$timezoneId`): ?IntlTimeZone
public static function createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false
public static function fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone
public static function getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false
public function getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false
public function getDSTSavings(): int
public static function getEquivalentID(string `$timezoneId`, int `$offset`): string|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public static function getGMT(): IntlTimeZone
public static function getIanaID(string `$timezoneId`): string|false
public function getID(): string|false
public static function getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false
public function getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool
public function getRawOffset(): int
public static function getRegion(string `$timezoneId`): string|false
public static function getTZDataVersion(): string|false
public static function getUnknown(): IntlTimeZone
public static function getWindowsID(string `$timezoneId`): string|false
public function hasSameRules(IntlTimeZone `$other`): bool
public function toDateTimeZone(): DateTimeZone|false
public function useDaylightTime(): bool
}

## Constantes pré-définies

`IntlTimeZone::DISPLAY_SHORT` int

`IntlTimeZone::DISPLAY_LONG` int

`IntlTimeZone::DISPLAY_SHORT_GENERIC` int

`IntlTimeZone::DISPLAY_LONG_GENERIC` int

`IntlTimeZone::DISPLAY_SHORT_GMT` int

`IntlTimeZone::DISPLAY_LONG_GMT` int

`IntlTimeZone::DISPLAY_SHORT_COMMONLY_USED` int

`IntlTimeZone::DISPLAY_GENERIC_LOCATION` int

`IntlTimeZone::TYPE_ANY` int

`IntlTimeZone::TYPE_CANONICAL` int

`IntlTimeZone::TYPE_CANONICAL_LOCATION` int

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.

# IntlTimeZone::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::__construct — Constructeur privé pour empêcher l'instanciation directe

### Description

private function IntlTimeZone::__construct()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# IntlTimeZone::countEquivalentIDs

# intltz_count_equivalent_ids

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::countEquivalentIDs -- intltz_count_equivalent_ids — Récupère le nombre d'IDs dans le groupe d'équivalence qui inclut l'ID fourni

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::countEquivalentIDs(string `$timezoneId`): int|false

Style procédural:

function intltz_count_equivalent_ids(string `$timezoneId`): int|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timezoneId`

### Valeurs de retour

# IntlTimeZone::createDefault

# intltz_create_default

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createDefault -- intltz_create_default — Crée une nouvelle copie du fuseau horaire par défaut pour cet hôte

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::createDefault(): IntlTimeZone

Style procédural:

function intltz_create_default(): IntlTimeZone

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlTimeZone::createEnumeration

# intltz_create_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createEnumeration -- intltz_create_enumeration — Récupère une énumération d'IDs de fuseau horaire associés avec le pays fourni

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Style procédural:

function intltz_create_enumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`countryOrRawOffset`

### Valeurs de retour

# IntlTimeZone::createTimeZone

# intltz_create_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createTimeZone -- intltz_create_time_zone — Crée un objet de fuseau horaire pour l'ID fourni

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::createTimeZone(string `$timezoneId`): ?IntlTimeZone

Style procédural:

function intltz_create_time_zone(string `$timezoneId`): ?IntlTimeZone

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timezoneId`

### Valeurs de retour

# IntlTimeZone::createTimeZoneIDEnumeration

# intltz_create_time_zone_id_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::createTimeZoneIDEnumeration -- intltz_create_time_zone_id_enumeration — Renvoie une énumération sur les identifiants de fuseau horaire système avec les conditions de filtre données

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Style procédural:

function intltz_create_time_zone_id_enumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`type`

`region`

`rawOffset`

### Valeurs de retour

Renvoie IntlIterator ou `false` si une erreur survient.

# IntlTimeZone::fromDateTimeZone

# intltz_from_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::fromDateTimeZone -- intltz_from_date_time_zone — Crée un objet fuseau horaire depuis DateTimeZone

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone

Style procédural:

function intltz_from_date_time_zone(DateTimeZone `$timezone`): ?IntlTimeZone

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timezone`

### Valeurs de retour

# IntlTimeZone::getCanonicalID

# intltz_get_canonical_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getCanonicalID -- intltz_get_canonical_id — Récupère l'identifiant du fuseau horaire système ou l'identifiant normalisé du fuseau horaire personnalisé pour l'ID du fuseau horaire fourni

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Style procédural:

function intltz_get_canonical_id(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timezoneId`

`isSystemId`

### Valeurs de retour

# IntlTimeZone::getDisplayName

# intltz_get_display_name

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDisplayName -- intltz_get_display_name — Récupère un nom du fuseau horaire aux fins de présentation à l'utilisateur

### Description

Style orienté objet (méthode):

public function IntlTimeZone::getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false

Style procédural:

function intltz_get_display_name(
IntlTimeZone `$timezone`,
bool `$dst` = `false`,
int `$style` = `IntlTimeZone::DISPLAY_LONG`,
?string `$locale` = `null`
): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`dst`

`style`

`locale`

### Valeurs de retour

# IntlTimeZone::getDSTSavings

# intltz_get_dst_savings

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDSTSavings -- intltz_get_dst_savings — Récupère la durée à ajouter à l'heure locale pour récupérer l'heure murale locale

### Description

Style orienté objet (méthode):

public function IntlTimeZone::getDSTSavings(): int

Style procédural:

function intltz_get_dst_savings(IntlTimeZone `$timezone`): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlTimeZone::getEquivalentID

# intltz_get_equivalent_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getEquivalentID -- intltz_get_equivalent_id — Récupère un identifiant d'un groupe d'équivalence qui inclut l'identifiant fourni

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::getEquivalentID(string `$timezoneId`, int `$offset`): string|false

Style procédural:

function intltz_get_equivalent_id(string `$timezoneId`, int `$offset`): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timezoneId`

`offset`

### Valeurs de retour

# IntlTimeZone::getErrorCode

# intltz_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorCode -- intltz_get_error_code — Récupère le code de la dernière erreur survenue sur l'objet

### Description

Style orienté objet (méthode):

public function IntlTimeZone::getErrorCode(): int|false

Style procédural:

function intltz_get_error_code(IntlTimeZone `$timezone`): int|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlTimeZone::getErrorMessage

# intltz_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorMessage -- intltz_get_error_message — Récupère le message de la dernière erreur survenue sur l'objet

### Description

Style orienté objet (méthode):

public function IntlTimeZone::getErrorMessage(): string|false

Style procédural:

function intltz_get_error_message(IntlTimeZone `$timezone`): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlTimeZone::getGMT

# intltz_get_gmt

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getGMT -- intltz_get_gmt — Crée un fuseau horaire GMT (UTC)

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::getGMT(): IntlTimeZone

Style procédural:

function intltz_get_gmt(): IntlTimeZone

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlTimeZone::getIanaID

# intltz_get_iana_id

(PHP 8 >= 8.4.0)

IntlTimeZone::getIanaID -- intltz_get_iana_id — Traduit un identifiant de fuseau horaire vers son équivalent IANA

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::getIanaID(string `$timezoneId`): string|false

Style procédural:

function intltz_get_iana_id(string `$timezoneId`): string|false

Traduit un identifiant de fuseau horaire vers son équivalent IANA. Par exemple, `"GMT"` renvoie `"Etc/GMT"`, et `"US/Eastern"` renvoie `"America/New_York"`.

> Note: Cette fonction nécessite ICU version >= 74.

### Liste de paramètres

`timezoneId`
  L'identifiant de fuseau horaire à traduire.

### Valeurs de retour

Renvoie l'identifiant de fuseau horaire IANA sous forme de chaîne de caractères, ou `false` en cas d'échec.

### Voir aussi

- intltz_get_id_for_windows_id() - Traduit un fuseau horaire Windows en un fuseau horaire système
- intltz_get_windows_id() - Traduit un fuseau horaire système en un fuseau horaire Windows
- intltz_create_time_zone() - Crée un objet de fuseau horaire pour l'ID fourni

# IntlTimeZone::getID

# intltz_get_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getID -- intltz_get_id — Récupère l'ID d'un fuseau horaire

### Description

Style orienté objet (méthode):

public function IntlTimeZone::getID(): string|false

Style procédural:

function intltz_get_id(IntlTimeZone `$timezone`): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlTimeZone::getIDForWindowsID

# intltz_get_id_for_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getIDForWindowsID -- intltz_get_id_for_windows_id — Traduit un fuseau horaire Windows en un fuseau horaire système

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false

Style procédural:

function intltz_get_id_for_windows_id(string `$timezoneId`, ?string `$region` = `null`): string|false

Traduit un fuseau horaire Windows (par exemple "Pacific Standard Time") en un fuseau horaire système (par exemple "America/Los_Angeles").

> Note: Cette fonction requiert ICU version ≥ 52.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timezoneId`

`region`

### Valeurs de retour

Renvoie le fuseau horaire système ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `region` est désormais nullable.

### Voir aussi

- IntlTimeZone::getWindowsID() - Traduit un fuseau horaire système en un fuseau horaire Windows

# IntlTimeZone::getOffset

# intltz_get_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getOffset -- intltz_get_offset — Récupère le fuseau horaire brut, et la position GMT pour un moment dans le temps donné

### Description

Style orienté objet (méthode):

public function IntlTimeZone::getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Style procédural:

function intltz_get_offset(
IntlTimeZone `$timezone`,
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timestamp`

`local`

`rawOffset`

`dstOffset`

### Valeurs de retour

# IntlTimeZone::getRawOffset

# intltz_get_raw_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getRawOffset -- intltz_get_raw_offset — Récupère la position brute GMT (avant de prendre en compte l'heure d'été)

### Description

Style orienté objet (méthode):

public function IntlTimeZone::getRawOffset(): int

Style procédural:

function intltz_get_raw_offset(IntlTimeZone `$timezone`): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlTimeZone::getRegion

# intltz_get_region

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getRegion -- intltz_get_region — Renvoie le code de région associé à l'identifiant de fuseau horaire système donné

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::getRegion(string `$timezoneId`): string|false

Style procédural:

function intltz_get_region(string `$timezoneId`): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timezoneId`

### Valeurs de retour

Retourne la région ou `false` si une erreur survient.

# IntlTimeZone::getTZDataVersion

# intltz_get_tz_data_version

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getTZDataVersion -- intltz_get_tz_data_version — Récupère la version du fuseau horaire actuellement utilisé par ICU

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::getTZDataVersion(): string|false

Style procédural:

function intltz_get_tz_data_version(): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlTimeZone::getUnknown

# intltz_get_unknown

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getUnknown -- intltz_get_unknown — Renvoie le fuseau horaire "inconnu"

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::getUnknown(): IntlTimeZone

Style procédural:

function intltz_get_unknown(): IntlTimeZone

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie IntlTimeZone ou `null` en cas d'échec.

# IntlTimeZone::getWindowsID

# intltz_get_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getWindowsID -- intltz_get_windows_id — Traduit un fuseau horaire système en un fuseau horaire Windows

### Description

Style orienté objet (méthode):

public static function IntlTimeZone::getWindowsID(string `$timezoneId`): string|false

Style procédural:

function intltz_get_windows_id(string `$timezoneId`): string|false

Traduit un fuseau horaire système (par exemple "America/Los_Angeles") en un fuseau horaire Windows (par exemple "Pacific Standard Time").

> Note: Cette fonction requiert ICU version ≥ 52.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`timezoneId`

### Valeurs de retour

Renvoie le fuseau horaire Windows ou `false` si une erreur survient.

### Voir aussi

- IntlTimeZone::getIDForWindowsID() - Traduit un fuseau horaire Windows en un fuseau horaire système

# IntlTimeZone::hasSameRules

# intltz_has_same_rules

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::hasSameRules -- intltz_has_same_rules — Vérifie si cette zone a les mêmes règles qu'une autre

### Description

Style orienté objet (méthode):

public function IntlTimeZone::hasSameRules(IntlTimeZone `$other`): bool

Style procédural:

function intltz_has_same_rules(IntlTimeZone `$timezone`, IntlTimeZone `$other`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`other`

### Valeurs de retour

# IntlTimeZone::toDateTimeZone

# intltz_to_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::toDateTimeZone -- intltz_to_date_time_zone — Convertit un objet DateTimeZone

### Description

Style orienté objet (méthode):

public function IntlTimeZone::toDateTimeZone(): DateTimeZone|false

Style procédural:

function intltz_to_date_time_zone(IntlTimeZone `$timezone`): DateTimeZone|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlTimeZone::useDaylightTime

# intltz_use_daylight_time

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::useDaylightTime -- intltz_use_daylight_time — Vérifie si ce fuseau horaire utilise l'heure d'été

### Description

Style orienté objet (méthode):

public function IntlTimeZone::useDaylightTime(): bool

Style procédural:

function intltz_use_daylight_time(IntlTimeZone `$timezone`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

## Sommaire

- IntlTimeZone::__construct — Constructeur privé pour empêcher l'instanciation directe
- IntlTimeZone::countEquivalentIDs — Récupère le nombre d'IDs dans le groupe d'équivalence qui inclut l'ID fourni
- IntlTimeZone::createDefault — Crée une nouvelle copie du fuseau horaire par défaut pour cet hôte
- IntlTimeZone::createEnumeration — Récupère une énumération d'IDs de fuseau horaire associés avec le pays fourni
- IntlTimeZone::createTimeZone — Crée un objet de fuseau horaire pour l'ID fourni
- IntlTimeZone::createTimeZoneIDEnumeration — Renvoie une énumération sur les identifiants de fuseau horaire système avec les conditions de filtre données
- IntlTimeZone::fromDateTimeZone — Crée un objet fuseau horaire depuis DateTimeZone
- IntlTimeZone::getCanonicalID — Récupère l'identifiant du fuseau horaire système ou l'identifiant normalisé du fuseau horaire personnalisé pour l'ID du fuseau horaire fourni
- IntlTimeZone::getDisplayName — Récupère un nom du fuseau horaire aux fins de présentation à l'utilisateur
- IntlTimeZone::getDSTSavings — Récupère la durée à ajouter à l'heure locale pour récupérer l'heure murale locale
- IntlTimeZone::getEquivalentID — Récupère un identifiant d'un groupe d'équivalence qui inclut l'identifiant fourni
- IntlTimeZone::getErrorCode — Récupère le code de la dernière erreur survenue sur l'objet
- IntlTimeZone::getErrorMessage — Récupère le message de la dernière erreur survenue sur l'objet
- IntlTimeZone::getGMT — Crée un fuseau horaire GMT (UTC)
- IntlTimeZone::getIanaID — Traduit un identifiant de fuseau horaire vers son équivalent IANA
- IntlTimeZone::getID — Récupère l'ID d'un fuseau horaire
- IntlTimeZone::getIDForWindowsID — Traduit un fuseau horaire Windows en un fuseau horaire système
- IntlTimeZone::getOffset — Récupère le fuseau horaire brut, et la position GMT pour un moment dans le temps donné
- IntlTimeZone::getRawOffset — Récupère la position brute GMT (avant de prendre en compte l'heure d'été)
- IntlTimeZone::getRegion — Renvoie le code de région associé à l'identifiant de fuseau horaire système donné
- IntlTimeZone::getTZDataVersion — Récupère la version du fuseau horaire actuellement utilisé par ICU
- IntlTimeZone::getUnknown — Renvoie le fuseau horaire "inconnu"
- IntlTimeZone::getWindowsID — Traduit un fuseau horaire système en un fuseau horaire Windows
- IntlTimeZone::hasSameRules — Vérifie si cette zone a les mêmes règles qu'une autre
- IntlTimeZone::toDateTimeZone — Convertit un objet DateTimeZone
- IntlTimeZone::useDaylightTime — Vérifie si ce fuseau horaire utilise l'heure d'été

# La classe IntlDateFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introduction

La classe IntlDateFormatter est une classe concrète, qui active l'analyse et le formatage de dates, basé sur des chaînes modèles, ou des règles.

Cette classe représente les fonctionnalités de formatage des dates ICU. Elle permet aux utilisateurs d'afficher des dates dans un format localisé, ou d'analyser des chaînes PHP pour extraire des dates.

## Class synopsis

class IntlDateFormatter {
/* Constantes */
public const int FULL;
public const int LONG;
public const int MEDIUM;
public const int SHORT;
public const int NONE;
public const int RELATIVE_FULL;
public const int RELATIVE_LONG;
public const int RELATIVE_MEDIUM;
public const int RELATIVE_SHORT;
public const int PATTERN;
public const int GREGORIAN;
public const int TRADITIONAL;
/* Méthodes */
public function __construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)
public static function create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter
public function format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false
public static function formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false
public function getCalendar(): int|false
public function getDateType(): int|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getTimeType(): int|false
public function getTimeZoneId(): string|false
public function getCalendarObject(): IntlCalendar|false|null
public function getTimeZone(): IntlTimeZone|false
public function isLenient(): bool
public function localtime(string `$string`, int `&$offset` = `null`): array|false
public function parse(string `$string`, int `&$offset` = `null`): int|float|false
public function parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false
public function setCalendar(IntlCalendar|int|null `$calendar`): bool
public function setLenient(bool `$lenient`): void
public function setPattern(string `$pattern`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
}

## Historique

Version | Description
--- | ---
8.4.0 | Ajout de la constante `IntlDateFormatter::PATTERN`.

## Voir aussi

- » ICU Date formatter

- » ICU Date formats

## Constantes pré-définies

Ces constantes sont utilisées pour spécifier différents formats dans le constructeur des classes DateType et TimeType.

`IntlDateFormatter::NONE` int
  N'inclut pas cet élément
`IntlDateFormatter::FULL` int
  Style complètement spécifié (`Tuesday, April 12, 1952 AD or 3:30:42pm PST`)
`IntlDateFormatter::LONG` int
  Style long (`January 12, 1952 or 3:30:32pm`)
`IntlDateFormatter::MEDIUM` int
  Style intermédiaire (`Jan 12, 1952`)
`IntlDateFormatter::SHORT` int
  Style abrégé, uniquement les informations essentielles (`12/13/52` ou `3:30pm`)
`IntlDateFormatter::RELATIVE_FULL` int
  Identique à `IntlDateFormatter::FULL`, mais hier, aujourd'hui, et demain sont affichés comme `yesterday`, `today`, et `tomorrow`, respectivement. Disponible à partir de PHP 8.0.0, pour `dateType` uniquement.
`IntlDateFormatter::RELATIVE_LONG` int
  Identique à `IntlDateFormatter::LONG`, mais hier, aujourd'hui, et demain sont affichés comme `yesterday`, `today`, et `tomorrow`, respectivement. Disponible à partir de PHP 8.0.0, pour `dateType` uniquement.
`IntlDateFormatter::RELATIVE_MEDIUM` int
  Identique à `IntlDateFormatter::MEDIUM`, mais hier, aujourd'hui, et demain sont affichés comme `yesterday`, `today`, et `tomorrow`, respectivement. Disponible à partir de PHP 8.0.0, pour `dateType` uniquement.
`IntlDateFormatter::RELATIVE_SHORT` int
  Identique à `IntlDateFormatter::SHORT`, mais hier, aujourd'hui, et demain sont affichés comme `yesterday`, `today`, et `tomorrow`, respectivement. Disponible à partir de PHP 8.0.0, pour `dateType` uniquement.
`IntlDateFormatter::PATTERN` int
  Utilise le modèle donné dans `pattern`. Disponible à partir de PHP 8.4.0.

Les constantes entières suivantes sont utilisées pour spécifier des calendriers. Ces calendriers sont basés directement sur le calendrier grégorien. Les calendriers non-grégoriens doivent être spécifiés dans une locale. Les exemples peuvent inclure `locale="hi@calendar=BUDDHIST"`.

`IntlDateFormatter::TRADITIONAL` int
  Calendrier non-grégorien
`IntlDateFormatter::GREGORIAN` int
  Calendrier grégorien

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont désormais typées.

# IntlDateFormatter::create

# datefmt_create

# IntlDateFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::create -- datefmt_create -- IntlDateFormatter::__construct — Crée un formateur de date

### Description

Style orienté objet

public static function IntlDateFormatter::create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter

Style orienté objet (constructeur)

public function IntlDateFormatter::__construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)

Style procédural

function datefmt_create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter

Crée un formateur de date.

### Liste de paramètres

`locale`

  La locale à utiliser pour formater et analyser ou `null` pour utiliser la valeur spécifiée dans la configuration ini intl.default_locale.

`dateType`

  Le type de date à utiliser (`none`, `short`, `medium`, `long`, `full`). C'est l'une des constantes IntlDateFormatter.

`timeType`

  Format de l'heure déterminé par l'une des constantes d'IntlDateFormatter. La valeur par défaut est `IntlDateFormatter::FULL`.

`timezone`

  L'identifiant du fuseau horaire. Par défaut, (ce sera également la valeur par défaut qui sera utilisée si `null` est fourni) ce sera celui retourné par la fonction date_default_timezone_get() ou, si applicable, celui de l'objet IntlCalendar passé au paramètre `calendar`. Cet identifiant doit être un identifiant valide dans la base de données ICU, ou un identifiant représentant un décalage explicite, comme `GMT-05:30`.

  Ce paramètre peut aussi être un objet IntlTimeZone ou un objet DateTimeZone.

`calendar`

  Calendrier à utiliser pour le formatage ou l'analyse. La valeur par défaut est `null`, ce qui correspond à la constante `IntlDateFormatter::GREGORIAN`. Peut être une des constantes de calendrier IntlDateFormatter ou un IntlCalendar. Tout objet IntlCalendar passé sera cloné ; il ne sera pas modifié par IntlDateFormatter. Il déterminera le type de calendrier utilisé (grégorien, islamique, persan, etc.) et si `null` est fourni dans le paramètre `timezone`, le fuseau horaire sera également utilisé.

`pattern`

  Le modèle à utiliser pour le formatage ou l'analyse. Les modèles disponibles sont documentés sur » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Valeurs de retour

L'objet IntlDateFormatter créé, ou `null` si une erreur survient.

### Erreurs / Exceptions

Une ValueError est levée si `locale` est invalide.

### Historique

Version | Description
--- | ---
8.4.0 | Une ValueError est levée si `locale` est invalide.
8.1.0 | Les paramètres `dateType` et `timeType` sont désormais facultatifs.

### Exemples

Exemple #1 Exemple avec datefmt_create(), procédural

    <?php
    $fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles', IntlDateFormatter::GREGORIAN  );
    echo "Le premier format affiché est ".datefmt_format( $fmt , 0);
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "Le deuxième format affiché est ".datefmt_format( $fmt , 0);

    $fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "Le premier format est affiché avec le modèle : ".datefmt_format( $fmt , 0);
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "Le deuxième format est affiché avec le modèle : ".datefmt_format( $fmt , 0);
    ?>

Exemple #2 Exemple avec datefmt_create(), POO

    <?php
    $fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "Le premier format affiché est ".$fmt->format(0);
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "Le deuxième format affiché est ".$fmt->format(0);

    $fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "Le premier format est affiché avec le modèle : ".$fmt->format(0);
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
          'America/Los_Angeles',IntlDateFormatter::GREGORIAN , "MM/dd/yyyy");
    echo "Le deuxième format est affiché avec le modèle : ".$fmt->format(0);
    ?>

Exemple #3 Exemple de gestion de locale invalide

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'locale_invalide',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'je_ne_sais_pas',
            IntlDateFormatter::GREGORIAN,
        );
    } catch (\Error $e) {
        // ...
    }
    ?>

L'exemple ci-dessus va afficher :

    Le premier format affiché est Wednesday, December 31, 1969 4:00:00 PM PT
    Le deuxième format affiché est Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
    Le premier format est affiché avec le modèle : 12/31/1969
    Le deuxième format est affiché avec le modèle : 12/31/1969

### Voir aussi

- datefmt_format() - Formate la date et l'heure sous forme de chaîne
- datefmt_parse() - Analyse une chaîne vers un timestamp
- datefmt_get_error_code() - Lit le code d'erreur de la dernière opération
- datefmt_get_error_message() - Lit le dernier message d'erreur

# IntlDateFormatter::format

# datefmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::format -- datefmt_format — Formate la date et l'heure sous forme de chaîne

### Description

Style orienté objet

public function IntlDateFormatter::format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Style procédural

function datefmt_format(IntlDateFormatter `$formatter`, IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Formate l'heure sous forme de chaîne.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

`datetime`

  La valeur à formater. Ce peut être un objet DateTimeInterface, un objet IntlCalendar, un type numeric représentant un (peut être fractionné) nombre de secondes depuis l'époque ou un array au format de sortie de la fonction localtime().

  Si un objet DateTime ou un objet IntlCalendar est passé, son décalage horaire ne sera pas considéré. L'objet devra être formaté en utilisant le décalage horaire configuré pour ce formateur. Pour utiliser le décalage horaire de l'objet à formater, la méthode IntlDateFormatter::setTimeZone() devra être appelée avant le décalage horaire de l'objet. Il est aussi possible d'utiliser la méthode IntlDateFormatter::formatObject() pour obtenir le même résultat.

### Valeurs de retour

La chaîne formatée, ou, si une erreur survient, `false`.

### Historique

Version | Description
--- | ---
7.1.5 | Ajout du support pour fournir un objet générique DateTimeInterface pour le paramètre `datetime`. Anciennement, seulement les objets valides DateTime étaient supportés.
PECL intl 3.0.0 | Il est maintenant possible de passer un objet IntlCalendar comme valeur du paramètre `datetime`.

### Exemples

Exemple #1 Exemple avec datefmt_format()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le premier format affiché est ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le deuxième format affiché est ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Le premier format est affiché avec le modèle ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo "Le deuxième format est affiché avec le modèle " . datefmt_format($fmt, 0);
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le premier format affiché est ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le deuxième format affiché est ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Le premier format est affiché avec le modèle ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Le deuxième format est affiché avec le modèle ' . $fmt->format(0);
    ?>

L'exemple ci-dessus va afficher :

    Le premier format affiché est Wednesday, December 31, 1969 4:00:00 PM PT
    Le deuxième format affiché est Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
    Le premier format est affiché avec le modèle : 12/31/1969
    Le deuxième format est affiché avec le modèle : 12/31/1969

Exemple #3 Exemple avec un objet IntlCalendar

    <?php
    $tz = reset(iterator_to_array(IntlTimeZone::createEnumeration('FR')));
    $formatter = IntlDateFormatter::create(
        'fr_FR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        $tz,
        IntlDateFormatter::GREGORIAN
    );

    $cal = IntlCalendar::createInstance($tz, '@calendar=islamic-civil');
    $cal->set(IntlCalendar::FIELD_MONTH, 8); //9ème mois, Ramadan
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 1); //1er jour
    $cal->clear(IntlCalendar::FIELD_HOUR_OF_DAY);
    $cal->clear(IntlCalendar::FIELD_MINUTE);
    $cal->clear(IntlCalendar::FIELD_SECOND);
    $cal->clear(IntlCalendar::FIELD_MILLISECOND);

    echo "Dans l'année Islamique, le Ramadan commence le :\n\t",
            $formatter->format($cal), "\n";

    //C'est le décalage horaire du formateur qui est utilisé ici :
    $formatter->setTimeZone('Asia/Tokyo');
    echo "Après modification du décalage horaire :\n\t",
            $formatter->format($cal), "\n";

L'exemple ci-dessus va afficher :

    Dans l'année Islamique, le Ramadan commence le :
        mardi 9 juillet 2013 19:00:00 heure avancée d’Europe centrale
    Après modification du décalage horaire :
        mercredi 10 juillet 2013 02:00:00 heure normale du Japon

### Voir aussi

- datefmt_create() - Crée un formateur de date
- datefmt_parse() - Analyse une chaîne vers un timestamp
- datefmt_get_error_code() - Lit le code d'erreur de la dernière opération
- datefmt_get_error_message() - Lit le dernier message d'erreur
- datefmt_format_object() - Formate un objet

# IntlDateFormatter::formatObject

# datefmt_format_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::formatObject -- datefmt_format_object — Formate un objet

### Description

Style orienté objet

public static function IntlDateFormatter::formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

Style procédural

function datefmt_format_object(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

Cette fonction permet le formatage d'un objet IntlCalendar ou d'un objet DateTime sans avoir créé auparavant un objet IntlDateFormatter.

L'objet IntlDateFormatter temporaire créé prendra le décalage horaire depuis l'objet passé. La base de données des décalages horaires interne à PHP ne sera pas utilisée - ICU sera utilisé à la place. L'identifiant de décalage horaire utilisé dans les objets DateTime doit toutefois exister également dans la base de données ICU.

### Liste de paramètres

`datetime`

  Un objet de type IntlCalendar ou de type DateTime. L'information de décalage horaire dans l'objet sera utilisée.

`format`

  Format de la date/heure. Peut être soit un tableau avec deux éléments (d'abord le style de la date, puis, le style de l'heure, en utilisant une des constantes suivantes : `IntlDateFormatter::NONE`, `IntlDateFormatter::SHORT`, `IntlDateFormatter::MEDIUM`, `IntlDateFormatter::LONG`, `IntlDateFormatter::FULL`), soit un type int avec la valeur de l'une de ces constantes (auquel cas, il sera utilisé à la fois pour la date et l'heure), ou un type string avec le format décrit dans la » documentation ICU. Si `null` est fourni, le style par défaut sera utilisé.

`locale`

  La locale à utiliser, ou `null` pour utiliser la locale par défaut.

### Valeurs de retour

Une chaîne de caractères contenant le résultat ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec IntlDateFormatter::formatObject()

    <?php
    /* Le décalage horaire par défaut n'est pas significatif ;
       il est pris depuis l'objet */
    ini_set('date.timezone', 'UTC');

    /* La locale par défaut est prise depuis la configuration ini */
    ini_set('intl.default_locale', 'fr_FR');

    $cal = IntlCalendar::fromDateTime("2013-06-06 17:05:06 Europe/Dublin");
    echo "défaut :\n\t",
            IntlDateFormatter::formatObject($cal),
            "\n";

    echo "long \$format (complet) :\n\t",
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL),
            "\n";

    echo "array \$format (aucun, complet) :\n\t",
            IntlDateFormatter::formatObject($cal, array(
                    IntlDateFormatter::NONE,
                    IntlDateFormatter::FULL)),
            "\n";

    echo "string \$format (d 'de' MMMM y):\n\t",
            IntlDateFormatter::formatObject($cal, "d 'de' MMMM y", 'en_US'),
            "\n";

    echo "avec DateTime :\n\t",
            IntlDateFormatter::formatObject(
                    new DateTime("2013-09-09 09:09:09 Europe/Madrid"),
                    IntlDateFormatter::FULL,
                    'es_ES'),
            "\n";

L'exemple ci-dessus va afficher :

    défaut :
        6 juin 2013 17:05:06
    long $format (complet):
        jeudi 6 juin 2013 17:05:06 heure d’été irlandaise
    array $format (aucun, complet):
        17:05:06 heure d’été irlandaise
    string $format (d 'de' MMMM y):
        6 de June 2013
    avec DateTime :
        lunes, 9 de septiembre de 2013 09:09:09 Hora de verano de Europa central

# IntlDateFormatter::getCalendar

# datefmt_get_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getCalendar -- datefmt_get_calendar — Lit le calendrier utilisé par l'objet IntlDateFormatter

### Description

Style orienté objet

public function IntlDateFormatter::getCalendar(): int|false

Style procédural

function datefmt_get_calendar(IntlDateFormatter `$formatter`): int|false

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

### Valeurs de retour

Le type de calendrier utilisé par le formateur. Peut être soit la constante `IntlDateFormatter::TRADITIONAL`, soit la constante `IntlDateFormatter::GREGORIAN`. Retourne `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec datefmt_get_calendar()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le calendrier du formateur est : ' . datefmt_get_calendar($fmt);
    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'Le calendrier est maintenant : ' . datefmt_get_calendar($fmt);
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le calendrier du formateur est : ' . $fmt->getCalendar();
    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'Le calendrier est maintenant : ' . $fmt->getCalendar();

    ?>

Exemple #3 Exemple de gestion de locale invalide

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'locale_invalide',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'je_ne_sais_pas',
            IntlDateFormatter::GREGORIAN,
        );
    } catch (\Error $e) {
        // ...
    }
    ?>

L'exemple ci-dessus va afficher :

    Le calendrier du formateur est : 1
    Le calendrier est maintenant : 0

### Voir aussi

- datefmt_get_calendar_object() - Récupère une copie de l'objet formateur du calendrier
- datefmt_set_calendar() - Définit le type de calendrier utilisé par le formateur
- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::getDateType

# datefmt_get_datetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getDateType -- datefmt_get_datetype — Lit le type de date utilisé par IntlDateFormatter

### Description

Style orienté objet

public function IntlDateFormatter::getDateType(): int|false

Style procédural

function datefmt_get_datetype(IntlDateFormatter `$formatter`): int|false

Retourne le type de date utilisé par le formateur IntlDateFormatter.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

### Valeurs de retour

Le type de date courant du formateur, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec datefmt_get_datetype()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le type de date du formateur est : ' . datefmt_get_datetype($fmt);
    echo 'L\'affichage avec le premier type de date est ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Maintenant, le type de date du formateur est : ' . datefmt_get_datetype($fmt);
    echo 'L\'affichage avec le second type de date est ' . datefmt_format($fmt, 0);

    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le type de date du formateur est : ' . $fmt->getDateType();
    echo 'L\'affichage avec le premier type de date est ' . $fmt->format(0);
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Maintenant, le type de date du formateur est : ' . $fmt->getDateType();
    echo 'L\'affichage avec le second type de date est ' . $fmt->format(0);

    ?>

L'exemple ci-dessus va afficher :

    Le type de date du formateur est : 0
    L'affichage avec le premier type de date est Wednesday, December 31, 1969 4:00:00 PM PT
    Maintenant, le type de date du formateur est : 2
    L'affichage avec le second type de date est 12/31/69 4:00:00 PM PT

### Voir aussi

- datefmt_get_timetype() - Lit le type de temps pour IntlDateFormatter
- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::getErrorCode

# datefmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorCode -- datefmt_get_error_code — Lit le code d'erreur de la dernière opération

### Description

Style orienté objet

public function IntlDateFormatter::getErrorCode(): int

Style procédural

function datefmt_get_error_code(IntlDateFormatter `$formatter`): int

Renvoie le code d'erreur de la dernière opération de formatage.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

### Valeurs de retour

Le code d'erreur, une des valeurs UErrorCode. La valeur initiale est U_ZERO_ERROR.

### Exemples

Exemple #1 Exemple avec datefmt_get_error_code()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt);

    printf(
        "Erreur : %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "Erreur : %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );
    ?>

L'exemple ci-dessus va afficher :

    Erreur : U_ZERO_ERROR (0)

### Voir aussi

- datefmt_get_error_message() - Lit le dernier message d'erreur
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_is_failure() - Vérifie si un code d'erreur indique un échec

# IntlDateFormatter::getErrorMessage

# datefmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorMessage -- datefmt_get_error_message — Lit le dernier message d'erreur

### Description

Style orienté objet

public function IntlDateFormatter::getErrorMessage(): string

Style procédural

function datefmt_get_error_message(IntlDateFormatter `$formatter`): string

Lit le message d'erreur de la dernière opération.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

### Valeurs de retour

La description de la dernière erreur.

### Exemples

Exemple #1 Exemple avec datefmt_get_error_message()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt);

    printf(
        "Erreur : %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "Erreur : %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );

    ?>

L'exemple ci-dessus va afficher :

    Erreur : U_ZERO_ERROR (0)

### Voir aussi

- datefmt_get_error_code() - Lit le code d'erreur de la dernière opération
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_is_failure() - Vérifie si un code d'erreur indique un échec

# IntlDateFormatter::getLocale

# datefmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getLocale -- datefmt_get_locale — Lit la locale utilisée par le formateur

### Description

Style orienté objet

public function IntlDateFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Style procédural

function datefmt_get_locale(IntlDateFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Lit la locale utilisée par le formateur.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

`type`

  Il est possible de choisir entre une valeur valide ou une valeur littérale de la locale (à l'aide des constantes `Locale::VALID_LOCALE` et `Locale::ACTUAL_LOCALE`, respectivement). La valeur par défaut est la valeur littérale.

### Valeurs de retour

La locale de ce formateur, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec datefmt_get_locale()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'La locale du formateur est : ' . datefmt_get_locale($fmt);
    echo 'Le premier format utilisé est ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'La locale du formateur est : ' . datefmt_get_locale($fmt);
    echo 'Le second format utilisé est ' . datefmt_format($fmt, 0);

    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'La locale du formateur est : ' . $fmt->getLocale();
    echo 'Le premier format utilisé est ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'La locale du formateur est : ' . $fmt->getLocale();
    echo 'Le second format utilisé est ' . $fmt->format(0);

    ?>

L'exemple ci-dessus va afficher :

    La locale du formateur est : en
    Le premier format utilisé est Wednesday, December 31, 1969 4:00:00 PM PT
    La locale du formateur est : de
    Le second format utilisé est Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00

### Voir aussi

- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::getPattern

# datefmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getPattern -- datefmt_get_pattern — Lit le modèle utilisé par IntlDateFormatter

### Description

Style orienté objet

public function IntlDateFormatter::getPattern(): string|false

Style procédural

function datefmt_get_pattern(IntlDateFormatter `$formatter`): string|false

Lit le modèle utilisé par le formateur.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

### Valeurs de retour

Le modèle utilisé pour analyser et former, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec datefmt_get_pattern()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Le modèle du formateur est : ' . datefmt_get_pattern($fmt);
    echo 'Le premier résultat avec le modèle est ' . datefmt_format($fmt, 0);
    datefmt_set_pattern($fmt,'yyyymmdd hh:mm:ss z');
    echo 'Maintenant le modèle du formateur est : ' . datefmt_get_pattern($fmt);
    echo 'Le deuxième résultat avec le modèle est ' . datefmt_format($fmt, 0);

    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Le modèle du formateur est : ' . $fmt->getPattern();
    echo 'Le premier résultat avec le modèle est ' . $fmt->format(0);
    $fmt->setPattern('yyyymmdd hh:mm:ss z');
    echo 'Maintenant le modèle du formateur est : ' . $fmt->getPattern();
    echo 'Le deuxième résultat avec le modèle est ' . $fmt->format(0);
    ?>

L'exemple ci-dessus va afficher :

    Le modèle du formateur est : MM/dd/yyyy
    Le premier résultat avec le modèle est 12/31/1969
    Maintenant le modèle du formateur est : yyyymmdd hh:mm:ss z
    Le deuxième résultat avec le modèle est 19690031 04:00:00 PST

### Voir aussi

- datefmt_set_pattern() - Configure le modèle utilisé par le IntlDateFormatter
- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::getTimeType

# datefmt_get_timetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeType -- datefmt_get_timetype — Lit le type de temps pour IntlDateFormatter

### Description

Style orienté objet

public function IntlDateFormatter::getTimeType(): int|false

Style procédural

function datefmt_get_timetype(IntlDateFormatter `$formatter`): int|false

Retourne le type de temps utilisé par le formateur.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

### Valeurs de retour

La valeur courante de type de date utilisé par le formateur, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec datefmt_get_timetype()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le type de temps du formateur est : ' . datefmt_get_timetype($fmt);
    echo 'Le premier résultat avec timetype est ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Maintenant, le timetype du formateur est : ' . datefmt_get_timetype($fmt);
    echo 'Le second résultat avec timetype est ' . datefmt_format($fmt, 0);

    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le type de temps du formateur est : ' . $fmt->getTimeType();
    echo 'Le premier résultat avec timetype est ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Maintenant, le timetype du formateur est : ' . $fmt->getTimeType();
    echo 'Le second résultat avec timetype est ' . $fmt->format(0);

    ?>

L'exemple ci-dessus va afficher :

    Le type de temps du formateur est : 0
    Le premier résultat avec timetype est Wednesday, December 31, 1969 4:00:00 PM PT
    Maintenant, le timetype du formateur est : 3
    Le second résultat avec timetype est Wednesday, December 31, 1969 4:00 PM

### Voir aussi

- datefmt_get_datetype() - Lit le type de date utilisé par IntlDateFormatter
- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::getTimeZoneId

# datefmt_get_timezone_id

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeZoneId -- datefmt_get_timezone_id — Lit le fuseau horaire de IntlDateFormatter

### Description

Style orienté objet

public function IntlDateFormatter::getTimeZoneId(): string|false

Style procédural

function datefmt_get_timezone_id(IntlDateFormatter `$formatter`): string|false

Lit le fuseau horaire utilisé par IntlDateFormatter.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

### Valeurs de retour

L'identifiant du fuseau horaire utilisé par ce formateur, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec datefmt_get_timezone_id()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'timezone_id of the formatter is: ' . datefmt_get_timezone_id($fmt) . "\n";
    datefmt_set_timezone($fmt, 'Europe/Madrid');
    echo 'Now timezone_id of the formatter is: ' . datefmt_get_timezone_id($fmt);

    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'timezone_id of the formatter is: ' . $fmt->getTimezoneId() . "\n";
    $fmt->setTimezone('Europe/Madrid');
    echo 'Now timezone_id of the formatter is: ' . $fmt->getTimezoneId();

    ?>

L'exemple ci-dessus va afficher :

    timezone_id of the formatter is: America/Los_Angeles
    Now timezone_id of the formatter is: Europe/Madrid

### Voir aussi

- datefmt_set_timezone() - Définit le formateur pour le décalage horaire
- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::getCalendarObject

# datefmt_get_calendar_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getCalendarObject -- datefmt_get_calendar_object — Récupère une copie de l'objet formateur du calendrier

### Description

Style orienté objet

public function IntlDateFormatter::getCalendarObject(): IntlCalendar|false|null

Style procédural

function datefmt_get_calendar_object(IntlDateFormatter `$formatter`): IntlCalendar|false|null

Obtient une copie de l'objet calendrier utilisé en interne par ce formateur. Ce calendrier aura un type (comme grégorien, japonais, bouddhiste, islamique, etc.) et un décalage horaire qui correspondent au type et au décalage horaire utilisés par le formateur. La date/heure de l'objet n'est pas spécifiée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une copie de l'objet calendrier interne utilisé par ce formateur, ou `null` si aucun n'a été défini, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec IntlDateFormatter::getCalendarObject()

    <?php
    $formatter = IntlDateFormatter::create(
        "fr_FR@calendar=islamic",
        NULL,
        NULL,
        "GMT-01:00",
        IntlDateFormatter::TRADITIONAL
    );

    $cal = $formatter->getCalendarObject();

    var_dump(
        $cal->getType(),
        $cal->getTimeZone(),
        $cal->getLocale(Locale::VALID_LOCALE)
    );
    ?>

L'exemple ci-dessus va afficher :

    string(7) "islamic"
    object(IntlTimeZone)#3 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(9) "GMT-01:00"
      ["rawOffset"]=>
      int(-3600000)
      ["currentOffset"]=>
      int(-3600000)
    }
    string(5) "fr_FR"

### Voir aussi

- IntlDateFormatter::getCalendar() - Lit le calendrier utilisé par l'objet IntlDateFormatter
- IntlDateFormatter::setCalendar() - Définit le type de calendrier utilisé par le formateur
- IntlCalendar

# IntlDateFormatter::getTimeZone

# datefmt_get_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getTimeZone -- datefmt_get_timezone — Récupère le formateur du décalage horaire

### Description

Style orienté objet

public function IntlDateFormatter::getTimeZone(): IntlTimeZone|false

Style procédural

function datefmt_get_timezone(IntlDateFormatter `$formatter`): IntlTimeZone|false

Retourne un objet IntlTimeZone représentant le décalage horaire utilisé par cet objet pour formater les dates et les heures. Lors du formatage des objets IntlCalendar et DateTime avec ce IntlDateFormatter, le décalage horaire utilisé sera retourné par cette méthode, et non celui associé avec les objets formatés.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet IntlTimeZone associé ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec IntlDateFormatter::getTimeZone()

    <?php

    $madrid = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Madrid');
    $lisbon = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Lisbon');

    var_dump($madrid->getTimezone());
    echo $madrid->getTimezone()->getDisplayName(
            false, IntlTimeZone::DISPLAY_GENERIC_LOCATION, "en_US"), "\n";
    echo $lisbon->getTimeZone()->getId(), "\n";
    // L'identifiant peut également être récupéré avec ->getTimezoneId()
    echo $lisbon->getTimeZoneId(), "\n";

L'exemple ci-dessus va afficher :

    object(IntlTimeZone)#4 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(13) "Europe/Madrid"
      ["rawOffset"]=>
      int(3600000)
      ["currentOffset"]=>
      int(7200000)
    }
    Spain Time
    Europe/Lisbon
    Europe/Lisbon

### Voir aussi

- IntlDateFormatter::getTimeZoneId() - Lit le fuseau horaire de IntlDateFormatter
- IntlDateFormatter::setTimeZone() - Définit le formateur pour le décalage horaire
- IntlTimeZone

# IntlDateFormatter::isLenient

# datefmt_is_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::isLenient -- datefmt_is_lenient — Retourne la sévérité utilisée pour IntlDateFormatter

### Description

Style orienté objet

public function IntlDateFormatter::isLenient(): bool

Style procédural

function datefmt_is_lenient(IntlDateFormatter `$formatter`): bool

Vérifie si l'analyseur est strict ou souple lors de l'interprétation des chaînes qui ne correspondent pas exactement au modèle recherché.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

### Valeurs de retour

`true` si l'analyseur est souple, `false` si l'analyseur est strict. Par défaut, l'analyseur est souple.

### Exemples

Exemple #1 Exemple avec datefmt_is_lenient()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/mm/yyyy'
    );
    echo 'Le formateur est strict : ';
    if ($fmt->isLenient()) {
        echo 'Oui';
    } else {
        echo 'Non';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\n Tentative d'analyse de la date '35/13/1971'.\nLe résultat est : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg est : " . intl_get_error_message();
        echo "\nError_code est : " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt,false);
    echo 'Maintenant, le formateur est strict : ';
    if ($fmt->isLenient()) {
        echo 'Oui';
    } else {
        echo 'Non';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\n Tentative d'analyse de la date '35/13/1971'.Le résultat est : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg est : " . intl_get_error_message();
        echo "\nError_code est : " . intl_get_error_code();
    }

    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        "dd/mm/yyyy"
    );
    echo "Le formateur est strict : ";
    if ($fmt->isLenient()) {
        echo 'Oui';
    } else {
        echo 'Non';
    }
    $fmt->parse('35/13/1971');
    echo "\n Tentative d'analyse de la date '35/13/1971'.\nLe résultat est : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0){
        echo "\nError_msg est : " . intl_get_error_message();
        echo "\nError_code est : " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo 'Now lenient of the formatter is : ';
    if ($fmt->isLenient()) {
        echo 'Oui';
    } else {
        echo 'Non';
    }
    $fmt->parse('35/13/1971');
    echo "\n Tentative d'analyse de la date '35/13/1971'.\nLe résultat est : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg est : " . intl_get_error_message();
        echo "\nError_code est : " . intl_get_error_code();
    }

    ?>

L'exemple ci-dessus va afficher :

    Le formateur est strict : Oui
    Tentative d'analyse de la date '35/13/1971'.
    Le résultat est : 34503180
    Maintenant, le formateur est strict : Non
    Tentative d'analyse de la date '35/13/1971'.
    Le résultat est :
    Error_msg est : Date parsing failed: U_PARSE_ERROR
    Error_code est : 9

### Voir aussi

- datefmt_set_lenient() - Configure la souplesse de l'analyseur
- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::localtime

# datefmt_localtime

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::localtime -- datefmt_localtime — Analyse une chaîne et la convertit en temps

### Description

Style orienté objet

public function IntlDateFormatter::localtime(string `$string`, int `&$offset` = `null`): array|false

Style procédural

function datefmt_localtime(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): array|false

Convertit la chaîne $value en une date décomposée (un tableau de champs), en commençant à la position $parse_pos et en consommant autant de caractères que possible.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

`string`

  La chaîne à convertir.

`offset`

  La position à partir de laquelle commencer l'analyse dans la valeur $value. Les positions commencent à 0. Si aucune erreur ne survient durant l'analyse de $value, $parse_pos contiendra -1, et sinon, il va contenir la position à laquelle l'analyse s'est terminée (et l'erreur est survenue). Cette variable va contenir la position de fin si l'analyse échoue. Si $parse_pos > strlen($value), l'analyse échoue immédiatement.

### Valeurs de retour

Un tableau d'entier compatible avec localtime : il contient l'heure sur 24 heures dans le champ tm_hour, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec datefmt_localtime()

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $arr = datefmt_localtime($fmt, 'Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);
    echo 'Résultat de l\'analyse ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }

    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $arr = $fmt->localtime('Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);
    echo 'Résultat de l\'analyse ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }

    ?>

L'exemple ci-dessus va afficher :

    Résultat de l'analyse tm_sec : 0 , tm_min : 0 , tm_hour : 16 , tm_year : 69 ,
    tm_mday : 31 , tm_wday : 3 , tm_yday : 365 , tm_mon : 11 , tm_isdst : 0 ,

### Voir aussi

- datefmt_create() - Crée un formateur de date
- datefmt_format() - Formate la date et l'heure sous forme de chaîne
- datefmt_parse() - Analyse une chaîne vers un timestamp
- datefmt_get_error_code() - Lit le code d'erreur de la dernière opération
- datefmt_get_error_message() - Lit le dernier message d'erreur

# IntlDateFormatter::parse

# datefmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::parse -- datefmt_parse — Analyse une chaîne vers un timestamp

### Description

Style orienté objet

public function IntlDateFormatter::parse(string `$string`, int `&$offset` = `null`): int|float|false

Style procédural

function datefmt_parse(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): int|float|false

Convertit `string` en une valeur de temps, en commençant à `offset` et en lisant autant de caractères que possible.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

`string`

  La chaîne à convertir en temps.

`offset`

  La position à partir de laquelle commencer l'analyse dans la valeur `string`. Les positions commencent à 0. Si aucune erreur ne survient durant l'analyse de `string`, `offset` contiendra -1, et sinon, il va contenir la position à laquelle l'analyse s'est terminée (et l'erreur est survenue). Cette variable va contenir la position de fin si l'analyse échoue. Si `offset` > `strlen($string)`, l'analyse échoue immédiatement.

### Valeurs de retour

La valeur du timestamp analysé ou `false` si la valeur n'a pu être analysée.

### Exemples

Exemple #1 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le premier format analysé est ' . $fmt->parse('Wednesday, December 20, 1989 4:00:00 PM PT');
    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    ?>

Exemple #2 Exemple avec datefmt_parse()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le premier format analysé est ' . datefmt_parse($fmt, 'Wednesday, December 20, 1989 4:00:00 PM PT');
    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le deuxième format analysé est ' . datefmt_parse($fmt, 'Mittwoch, 20. Dezember 1989 16:00 Uhr GMT-08:00');
    ?>

L'exemple ci-dessus va afficher :

    Le premier format analysé est 630201600
    Le deuxième format analysé est 630201600

### Voir aussi

- datefmt_create() - Crée un formateur de date
- datefmt_format() - Formate la date et l'heure sous forme de chaîne
- datefmt_localtime() - Analyse une chaîne et la convertit en temps
- datefmt_get_error_code() - Lit le code d'erreur de la dernière opération
- datefmt_get_error_message() - Lit le dernier message d'erreur

# IntlDateFormatter::parseToCalendar

(PHP 8 >= 8.4.0)

IntlDateFormatter::parseToCalendar — Analyse une chaîne en timestamp, en mettant à jour un calendrier ouvert

### Description

public function IntlDateFormatter::parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false

Convertit `string` en une valeur temporelle incrémentale, en commençant à `offset` et en consommant autant que possible de la valeur d'entrée.

Cette méthode se comporte comme IntlDateFormatter::parse(), à ceci près que le fuseau horaire du formateur est mis à jour selon les informations de fuseau horaire contenues dans la chaîne `string` analysée.

### Liste de paramètres

`string`
  La chaîne à convertir en temps.
`offset`
  Position à laquelle commencer l'analyse dans `string` (à base zéro). Si aucune erreur ne survient avant que `string` ne soit consommée, `offset` contiendra -1, sinon il contiendra la position à laquelle l'analyse s'est terminée (et où l'erreur est survenue). Cette variable contiendra la position de fin si l'analyse échoue. Si `offset` > `strlen($string)`, l'analyse échoue immédiatement.

### Valeurs de retour

Le timestamp de la valeur analysée, ou `false` si la valeur ne peut être analysée.

### Exemples

Exemple #1 Exemple avec IntlDateFormatter::parseToCalendar()

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo $fmt->parseToCalendar('Wednesday, December 20, 1989 at 4:00:00 PM Pacific Standard Time');
    ?>

L'exemple ci-dessus va afficher :

    630201600

### Voir aussi

- IntlDateFormatter::parse() - Analyse une chaîne vers un timestamp
- IntlDateFormatter::format() - Formate la date et l'heure sous forme de chaîne
- IntlDateFormatter::getErrorCode() - Lit le code d'erreur de la dernière opération
- IntlDateFormatter::getErrorMessage() - Lit le dernier message d'erreur

# IntlDateFormatter::setCalendar

# datefmt_set_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setCalendar -- datefmt_set_calendar — Définit le type de calendrier utilisé par le formateur

### Description

Style orienté objet

public function IntlDateFormatter::setCalendar(IntlCalendar|int|null `$calendar`): bool

Style procédural

function datefmt_set_calendar(IntlDateFormatter `$formatter`, IntlCalendar|int|null `$calendar`): bool

Configure le calendrier ou le type de calendrier à utiliser par le formateur.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

`calendar`

  Peut être : le type de calendrier à utiliser (par défaut, `IntlDateFormatter::GREGORIAN`, qui est aussi utilisé si `null` est spécifié) ou un objet IntlCalendar.

  Tout objet IntlCalendar passé sera cloné ; aucune modification ne sera effectuée sur l'objet en argument.

  Le décalage horaire du formateur ne sera conservé que si un objet IntlCalendar n'est pas passé, sinon, le nouveau décalage horaire sera celui de l'objet passé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
PECL intl 3.0.0 | Il devient possible de passer un objet IntlCalendar.

### Exemples

Exemple #1 Exemple avec datefmt_set_calendar()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le calendrier du formateur est : ' . datefmt_get_calendar($fmt);
    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'Le calendrier est maintenant : ' . datefmt_get_calendar($fmt);
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Le calendrier du formateur est : ' . $fmt->getCalendar();
    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'Le calendrier est maintenant : ' . $fmt->getCalendar();
    ?>

L'exemple ci-dessus va afficher :

    Le calendrier du formateur est : 1
    Le calendrier est maintenant : 0

Exemple #3 Exemple avec des arguments à IntlCalendar

    <?php
    $time = strtotime("2013-03-03 00:00:00 UTC");
    $formatter = IntlDateFormatter::create("en_US", NULL, NULL, "Europe/Amsterdam");

    echo "avant : ", $formatter->format($time), "\n";

    /* notez que la locale du calendrier n'est pas utilisée ! */
    $formatter->setCalendar(IntlCalendar::createInstance(
                   "America/New_York", "pt_PT@calendar=islamic"));

    echo "après :  ", $formatter->format($time), "\n";

L'exemple ci-dessus va afficher :

    avant : Sunday, March 3, 2013 at 1:00:00 AM Central European Standard Time
    après :  Saturday, Rabiʻ II 20, 1434 at 7:00:00 PM Eastern Standard Time

### Voir aussi

- datefmt_get_calendar() - Lit le calendrier utilisé par l'objet IntlDateFormatter
- datefmt_get_calendar_object() - Récupère une copie de l'objet formateur du calendrier
- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::setLenient

# datefmt_set_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setLenient -- datefmt_set_lenient — Configure la souplesse de l'analyseur

### Description

Style orienté objet

public function IntlDateFormatter::setLenient(bool `$lenient`): void

Style procédural

function datefmt_set_lenient(IntlDateFormatter `$formatter`, bool `$lenient`): void

Définit si l'analyseur est strict ou souple lors de l'interprétation des chaînes qui ne correspondent pas exactement au modèle recherché. Activer la souplesse de l'analyseur permet d'accepter des valeurs qui pourraient être considérées comme erronées par l'analyseur strict. Les espaces, les caractères inconnus ou les dates invalides ne sont pas acceptées.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

`lenient`

  Si l'analyseur est souple ou non, par défaut, vaut `true` (souple).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec datefmt_set_lenient()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'Le formateur est strict : ';
    if ($fmt->isLenient()) {
        echo 'Oui';
    } else {
        echo 'Non';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nTentative d'analyse de la date '35/13/1971'.\nLe résultat est : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg est : " . intl_get_error_message();
        echo "\nError_code est : " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt, false);
    echo "\nMaintenant, le formateur est strict : ";
    if ($fmt->isLenient()) {
        echo 'Oui';
    } else {
        echo 'Non';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nTentative d'analyse de la date '35/13/1971'.\nLe résultat est : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg est : ".intl_get_error_message();
        echo "\nError_code est : ".intl_get_error_code();
    }

    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'Le formateur est strict : ';
    if ($fmt->isLenient()) {
        echo 'Oui';
    } else {
        echo 'Non';
    }
    $fmt->parse('35/13/1971');
    echo "\n Tentative d'analyse de la date '35/13/1971'.\nLe résultat est : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg est : " . intl_get_error_message();
        echo "\nError_code est : " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo "\nMaintenant, le formateur est strict : ";
    if ($fmt->isLenient()) {
        echo 'Oui';
    } else {
        echo 'Non';
    }
    $fmt->parse('35/13/1971');
    echo "\n Tentative d'analyse de la date '35/13/1971'.\nLe résultat est : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg est : " . intl_get_error_message();
        echo "\nError_code est : " . intl_get_error_code();
    }

    ?>

L'exemple ci-dessus va afficher :

    Le formateur est strict : Non
    Tentative d'analyse de la date '35/13/1971'.
    Le résultat est : 66038400
    Maintenant, le formateur est strict : Oui
    Tentative d'analyse de la date '35/13/1971'.
    Le résultat est : Error_msg est : Date parsing failed: U_PARSE_ERROR Error_code est : 9

### Voir aussi

- datefmt_is_lenient() - Retourne la sévérité utilisée pour IntlDateFormatter
- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::setPattern

# datefmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setPattern -- datefmt_set_pattern — Configure le modèle utilisé par le IntlDateFormatter

### Description

Style orienté objet

public function IntlDateFormatter::setPattern(string `$pattern`): bool

Style procédural

function datefmt_set_pattern(IntlDateFormatter `$formatter`, string `$pattern`): bool

Configure le modèle utilisé par le IntlDateFormatter.

### Liste de paramètres

`formatter`

  La ressource de formateur IntlDateFormatter.

`pattern`

  Le nouveau masque à utiliser. Les masques possibles sont documentés sur » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient. Un mauvais formatage de la chaîne est généralement la cause de l'échec de cette fonction.

### Exemples

Exemple #1 Exemple avec datefmt_set_pattern()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Pattern of the formatter is : ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'First Formatted output with pattern is ', datefmt_format($fmt, 0), PHP_EOL;
    datefmt_set_pattern($fmt, 'yyyyMMdd hh:mm:ss z');
    echo 'Now pattern of the formatter is : ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'Second Formatted output with pattern is ', datefmt_format($fmt, 0), PHP_EOL;
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Pattern of the formatter is : ', $fmt->getPattern(), PHP_EOL;
    echo 'First Formatted output is ', $fmt->format(0), PHP_EOL;
    $fmt->setPattern('yyyyMMdd hh:mm:ss z');
    echo 'Now pattern of the formatter is : ', $fmt->getPattern(), PHP_EOL;
    echo 'Second Formatted output is ', $fmt->format(0), PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    Pattern of the formatter is : MM/dd/yyyy
    First Formatted output is 12/31/1969
    Now pattern of the formatter is : yyyyMMdd hh:mm:ss z
    Second Formatted output is 19691231 04:00:00 PST

### Voir aussi

- datefmt_get_pattern() - Lit le modèle utilisé par IntlDateFormatter
- datefmt_create() - Crée un formateur de date

# IntlDateFormatter::setTimeZone

# datefmt_set_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::setTimeZone -- datefmt_set_timezone — Définit le formateur pour le décalage horaire

### Description

Style orienté objet

public function IntlDateFormatter::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Style procédural

function datefmt_set_timezone(IntlDateFormatter `$formatter`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Définit le décalage horaire utilisé par l'objet IntlDateFormatter.

### Liste de paramètres

`formatter`

  Le formateur de ressource.

`timezone`

  Le décalage horaire à utiliser avec ce formateur. Peut être spécifié via les formats suivants :

  - `null`, dans quel cas le fuseau horaire par défaut sera utilisé, comme spécifié dans le paramètre de configuration du fichier ini date.timezone ou par la fonction date_default_timezone_set() et comme retourné par date_default_timezone_get().

  - Un IntlTimeZone, qui sera utilisé directement.

  - Un DateTimeZone. Son identifiant sera extrait et un objet de fuseau horaire ICU sera créé; le fuseau horaire sera soutenu par la base de données de l'ICU, et non par PHP.

  - Une chaîne de caractères, qui devrait être un identifiant de fuseau horaire ICU valide. Voir IntlTimeZone::createTimeZoneIDEnumeration(). Les décalages bruts tels que `"GMT+08:30"` sont aussi acceptés.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.3.0 | Cette fonction retourne désormais `true` en cas de succès ; précédemment elle retournait `null`.

### Exemples

Exemple #1 Exemple avec IntlDateFormatter::setTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Amsterdam');

    $formatter = IntlDateFormatter::create(NULL, NULL, NULL, "UTC");

    $formatter->setTimeZone(NULL);
    echo "NULL\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(IntlTimeZone::createTimeZone('Europe/Lisbon'));
    echo "IntlTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(new DateTimeZone('Europe/Paris'));
    echo "DateTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('Europe/Rome');
    echo "String\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('GMT+00:30');
    print_r($formatter->getTimeZone());

L'exemple ci-dessus va afficher :

    NULL
        Europe/Amsterdam
    IntlTimeZone
        Europe/Lisbon
    DateTimeZone
        Europe/Paris
    String
        Europe/Rome
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+00:30
        [rawOffset] => 1800000
        [currentOffset] => 1800000
    )

### Voir aussi

- IntlDateFormatter::getTimeZone() - Récupère le formateur du décalage horaire

## Sommaire

- IntlDateFormatter::create — Crée un formateur de date
- IntlDateFormatter::format — Formate la date et l'heure sous forme de chaîne
- IntlDateFormatter::formatObject — Formate un objet
- IntlDateFormatter::getCalendar — Lit le calendrier utilisé par l'objet IntlDateFormatter
- IntlDateFormatter::getDateType — Lit le type de date utilisé par IntlDateFormatter
- IntlDateFormatter::getErrorCode — Lit le code d'erreur de la dernière opération
- IntlDateFormatter::getErrorMessage — Lit le dernier message d'erreur
- IntlDateFormatter::getLocale — Lit la locale utilisée par le formateur
- IntlDateFormatter::getPattern — Lit le modèle utilisé par IntlDateFormatter
- IntlDateFormatter::getTimeType — Lit le type de temps pour IntlDateFormatter
- IntlDateFormatter::getTimeZoneId — Lit le fuseau horaire de IntlDateFormatter
- IntlDateFormatter::getCalendarObject — Récupère une copie de l'objet formateur du calendrier
- IntlDateFormatter::getTimeZone — Récupère le formateur du décalage horaire
- IntlDateFormatter::isLenient — Retourne la sévérité utilisée pour IntlDateFormatter
- IntlDateFormatter::localtime — Analyse une chaîne et la convertit en temps
- IntlDateFormatter::parse — Analyse une chaîne vers un timestamp
- IntlDateFormatter::parseToCalendar — Analyse une chaîne en timestamp, en mettant à jour un calendrier ouvert
- IntlDateFormatter::setCalendar — Définit le type de calendrier utilisé par le formateur
- IntlDateFormatter::setLenient — Configure la souplesse de l'analyseur
- IntlDateFormatter::setPattern — Configure le modèle utilisé par le IntlDateFormatter
- IntlDateFormatter::setTimeZone — Définit le formateur pour le décalage horaire

# La classe ResourceBundle

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Introduction

Les applications localisées ont souvent besoin de manipuler des données devant être personnalisées en fonction d'une locale considérée, p. ex. : messages, libellés, chaînes de formatage. ICU permet de définir des ressources que l'application pourra charger avec une locale une fois pour toutes : tous les accès ultérieurs se feront au moyen d'une interface unique non dépendante de la locale considérée.

Cette classe permet l'accès aux fichiers de données de ICU. Ces fichiers représentent des tableaux binaires que ICU utilise pour stocker les données localisées.

Les bundles de ressources ICU supportent les ressources simples et complexes. Les ressources complexes sont des conteneurs qui peuvent être indexés numériquement ou littéralement (comme les tableaux PHP). Les ressources simples, elles, peuvent être de type chaîne, entier, binaire ou tableau numérique.

ResourceBundle supporte l'accès direct aux données via la syntaxe des tableaux ainsi que l'itération grâce à foreach. Ces possibilités existent aussi via les méthodes. Le résultat sera une valeur PHP pour les ressources simples, ou un objet ResourceBundle pour les ressources complexes. Les ressources sont en lecture seule.

## Synopsis de la classe

class ResourceBundle implements IteratorAggregate, Countable {
/* Méthodes */
public function __construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)
public function count(): int
public static function create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle
public function get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null
public function getErrorCode(): int
public function getErrorMessage(): string
public static function getLocales(string `$bundle`): array|false
}

## Historique

Version | Description
--- | ---
8.0.0 | La classe ResourceBundle implémente désormais IteratorAggregate. Auparavant, seule Traversable était implémentée.
7.4.0 | La classe ResourceBundle implémente désormais Countable.

## Voir aussi

- » Configuration des ressources ICU
- » ICU Data

# ResourceBundle::count

# resourcebundle_count

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::count -- resourcebundle_count — Récupère le nombre d'éléments dans le faisceau

### Description

Style orienté objet

public function ResourceBundle::count(): int

Style procédural

function resourcebundle_count(ResourceBundle `$bundle`): int

Récupère le nombre d'éléments dans le faisceau.

### Liste de paramètres

`bundle`

  Un objet ResourceBundle.

### Valeurs de retour

Retourne le nombre d'éléments du faisceau.

### Exemples

Exemple #1 Exemple avec resourcebundle_count()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_count($r);
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->count();
    ?>

L'exemple ci-dessus va afficher :

    42

### Voir aussi

- resourcebundle_get() - Récupère les données depuis le faisceau

# ResourceBundle::create

# resourcebundle_create

# ResourceBundle::__construct

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::create -- resourcebundle_create -- ResourceBundle::__construct — Crée une ressource représentant un faisceau

### Description

Style orienté objet (méthode)

public static function ResourceBundle::create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Style procédural

function resourcebundle_create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Style orienté objet (constructeur) :

public function ResourceBundle::__construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)

Crée une ressource représentant un faisceau.

### Liste de paramètres

`locale`

  Locale depuis laquelle les ressources doivent être chargées (nom de la locale, c.-à-d. en_CA).

`bundle`

  Le dossier où les données sont stockées ou le nom du fichier .dat.

`fallback`

  Si la locale doit correspondre exactement ou si le fallback vers la locale parent est autorisé.

### Valeurs de retour

Retourne un objet ResourceBundle ou `null` si une erreur survient.

### Exemples

Exemple #1 Exemple avec resourcebundle_create()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

Exemple #2 Exemple avec ResourceBundle::create()

    <?php
    $r = ResourceBundle::create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

L'exemple ci-dessus va afficher :

    ¡Hola, mundo!

### Voir aussi

- resourcebundle_get() - Récupère les données depuis le faisceau

# ResourceBundle::get

# resourcebundle_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::get -- resourcebundle_get — Récupère les données depuis le faisceau

### Description

Style orienté objet

public function ResourceBundle::get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Style procédural

function resourcebundle_get(ResourceBundle `$bundle`, string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Récupère les données depuis le faisceau par l'index ou la clé.

### Liste de paramètres

`bundle`

  Un objet ResourceBundle.

`index`

  L'index des données ; peut être une chaîne de caractères ou un entier.

`fallback`

  Les paramètres régionaux doivent correspondre exactement ou le retour aux paramètres régionaux parents est autorisé

### Valeurs de retour

Retourne les données situées à un index donné ou `null` si une erreur survient. Les chaînes de caractères, les entiers et les données binaires sont retournés sous leurs formes correspondantes en types PHP ; les tableaux d'entiers sont retournés sous la forme de tableau PHP. Les types complexes sont retournés sous la forme d'objet ResourceBundle.

### Erreurs / Exceptions

Une TypeError est levée si le type du décalage est invalide.

Une ValueError est levée si `index` est une string et est vide ou est un int et ne peut pas être contenu dans un entier 32 bits.

### Historique

Version | Description
--- | ---
8.4.0 | Une TypeError est levée si le type du décalage est invalide. Une ValueError est levée si `index` est une string et est vide ou est un int et ne peut pas être contenu dans un entier 32 bits.

### Exemples

Exemple #1 Exemple avec resourcebundle_get()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_get($r, 'somestring');
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->get('somestring');
    ?>

L'exemple ci-dessus va afficher :

    ?Hola, mundo!

### Voir aussi

- resourcebundle_count() - Récupère le nombre d'éléments dans le faisceau

# ResourceBundle::getErrorCode

# resourcebundle_get_error_code

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorCode -- resourcebundle_get_error_code — Récupère le dernier code erreur du faisceau

### Description

Style orienté objet

public function ResourceBundle::getErrorCode(): int

Style procédural

function resourcebundle_get_error_code(ResourceBundle `$bundle`): int

Récupère le dernier code erreur depuis la dernière fonction exécutée sur l'objet représentant le faisceau.

### Liste de paramètres

`bundle`

  Un objet ResourceBundle.

### Valeurs de retour

Retourne le code erreur depuis le dernier appel à l'objet représentant le faisceau.

### Exemples

Exemple #1 Exemple avec resourcebundle_get_error_code()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Erreur sur le faisceau");
    }
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Erreur sur le faisceau");
    }
    ?>

### Voir aussi

- resourcebundle_get_error_message() - Récupère le dernier message d'erreur depuis le faisceau
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_is_failure() - Vérifie si un code d'erreur indique un échec

# ResourceBundle::getErrorMessage

# resourcebundle_get_error_message

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorMessage -- resourcebundle_get_error_message — Récupère le dernier message d'erreur depuis le faisceau

### Description

Style orienté objet

public function ResourceBundle::getErrorMessage(): string

Style procédural

function resourcebundle_get_error_message(ResourceBundle `$bundle`): string

Récupère le message d'erreur depuis la dernière fonction exécutée sur l'objet du faisceau.

### Liste de paramètres

`bundle`

  Un objet ResourceBundle.

### Valeurs de retour

Retourne le message d'erreur depuis le dernier appel sur l'objet du faisceau.

### Exemples

Exemple #1 Exemple avec resourcebundle_get_error_message()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Erreur sur le faisceau : ".resourcebundle_get_error_message($r));
    }
    ?>

Exemple #2 Exemple orienté objet

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Erreur sur le faisceau : ".ResourceBundle::getErrorMessage($r));
    }
    ?>

### Voir aussi

- resourcebundle_get_error_code() - Récupère le dernier code erreur du faisceau
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_is_failure() - Vérifie si un code d'erreur indique un échec

# ResourceBundle::getLocales

# resourcebundle_locales

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getLocales -- resourcebundle_locales — Récupère les locales supportées

### Description

Style orienté objet

public static function ResourceBundle::getLocales(string `$bundle`): array|false

Style procédural

function resourcebundle_locales(string `$bundle`): array|false

Récupère la liste des locales depuis le nom ResourceBundle.

### Liste de paramètres

`bundle`

  Chemin pour ResourceBundle depuis lequel on récupère les locales disponibles, ou une chaîne vide pour la liste des locales par défaut.

### Valeurs de retour

Retourne la liste des locales supportées par ce faisceau, ou `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec resourcebundle_locales()

    <?php
    $bundle = "/user/share/data/myapp";
    echo join(PHP_EOL, resourcebundle_locales($bundle));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    es
    root

Exemple #2 Exemple orienté objet

    <?php
    $bundle = "/usr/share/data/myapp";
    $r = new ResourceBundle( 'es', $bundle);
    echo join("\n", $r->getLocales($bundle));
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    es
    root

### Voir aussi

- resourcebundle_get() - Récupère les données depuis le faisceau

## Sommaire

- ResourceBundle::count — Récupère le nombre d'éléments dans le faisceau
- ResourceBundle::create — Crée une ressource représentant un faisceau
- ResourceBundle::get — Récupère les données depuis le faisceau
- ResourceBundle::getErrorCode — Récupère le dernier code erreur du faisceau
- ResourceBundle::getErrorMessage — Récupère le dernier message d'erreur depuis le faisceau
- ResourceBundle::getLocales — Récupère les locales supportées

# La classe Spoofchecker

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Introduction

Cette classe est fournie car Unicode contient un grand nombre de caractères et incorpore les systèmes d'écriture variés du monde et leur utilisation incorrecte peut exposer des programmes ou des systèmes à d'éventuelles attaques de sécurité en utilisant la similarité des caractères.

Les méthodes fournies permettent de vérifier si une chaîne individuelle est susceptible d'être une tentative à tromper le lecteur (`détection de tromperie`), tel que dans "pаypаl" orthographié avec un caractère 'а' cyrillique.

## Synopsis de la classe

class Spoofchecker {
/* Constantes */
public const int SINGLE_SCRIPT_CONFUSABLE;
public const int MIXED_SCRIPT_CONFUSABLE;
public const int WHOLE_SCRIPT_CONFUSABLE;
public const int ANY_CASE;
public const int SINGLE_SCRIPT;
public const int INVISIBLE;
public const int CHAR_LIMIT;
public const int ASCII;
public const int HIGHLY_RESTRICTIVE;
public const int MODERATELY_RESTRICTIVE;
public const int MINIMALLY_RESTRICTIVE;
public const int UNRESTRICTIVE;
public const int SINGLE_SCRIPT_RESTRICTIVE;
public const int MIXED_NUMBERS;
public const int HIDDEN_OVERLAY;
public const int IGNORE_SPACE;
public const int CASE_INSENSITIVE;
public const int ADD_CASE_MAPPINGS;
public const int SIMPLE_CASE_INSENSITIVE;
/* Méthodes */
public function __construct()
public function areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool
public function isSuspicious(string `$string`, int `&$errorCode` = `null`): bool
public function setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void
public function setAllowedLocales(string `$locales`): void
public function setChecks(int `$checks`): void
public function setRestrictionLevel(int `$level`): void
}

## Constantes pré-définies

`Spoofchecker::SINGLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::MIXED_SCRIPT_CONFUSABLE` int

`Spoofchecker::WHOLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::ANY_CASE` int

`Spoofchecker::SINGLE_SCRIPT` int

`Spoofchecker::INVISIBLE` int

`Spoofchecker::CHAR_LIMIT` int

`Spoofchecker::ASCII` int

`Spoofchecker::HIGHLY_RESTRICTIVE` int

`Spoofchecker::MODERATELY_RESTRICTIVE` int

`Spoofchecker::MINIMALLY_RESTRICTIVE` int

`Spoofchecker::UNRESTRICTIVE` int

`Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` int

`Spoofchecker::MIXED_NUMBERS` int

`Spoofchecker::HIDDEN_OVERLAY` int

`Spoofchecker::IGNORE_SPACE` int

`Spoofchecker::CASE_INSENSITIVE` int
  Active la correspondance insensible à la casse
`Spoofchecker::ADD_CASE_MAPPINGS` int

  Ajoute toutes les correspondances de casse pour chaque élément de l'ensemble

`Spoofchecker::SIMPLE_CASE_INSENSITIVE` int
  Active la correspondance insensible à la casse

## Historique

Version | Description
--- | ---
8.4.0 | Ajout de `Spoofchecker::IGNORE_SPACE`, `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS`, `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.
8.4.0 | Les constantes de classe sont maintenant typées.
7.3.0 | Les constantes de classe utilisées par Spoofchecker::setRestrictionLevel() telles que `Spoofchecker::ASCII`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE`, `Spoofchecker::UNRESTRICTIVE`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` ont été ajoutées.

# Spoofchecker::areConfusable

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::areConfusable — Vérifie si les chaînes données peuvent être confondues

### Description

public function Spoofchecker::areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool

Vérifie si deux chaînes données peuvent facilement être confondues.

### Liste de paramètres

`string1`

  Première chaîne à vérifier.

`string2`

  Deuxième chaîne à vérifier.

`errorCode`

  Cette variable est définie par référence à un entier contenant une erreur, s'il y en avait.

### Valeurs de retour

Retourne `true` si les deux chaînes données peuvent être confondues, et `false` sinon.

### Exemples

Exemple #1 Exemple Spoofchecker::areConfusable()

    <?php
    $checker = new Spoofchecker();

    $checker->areConfusable('google.com', 'goog1e.com'); // true
    // Le "l" minuscule peut être confondu avec le chiffre un

    $checker->areConfusable('google.com', 'g00g1e.com'); // false
    // Zéro (0) ne peut pas être facilement confondu avec la lettre "o"

# Spoofchecker::__construct

(No version information available, might only be in Git)

Spoofchecker::__construct — Constructeur

### Description

public function Spoofchecker::__construct()

Crée une nouvelle instance de Spoofchecker.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

# Spoofchecker::isSuspicious

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::isSuspicious — Vérifie si un texte contient des caractères suspects

### Description

public function Spoofchecker::isSuspicious(string `$string`, int `&$errorCode` = `null`): bool

Vérifie si la chaîne donnée contient des caractères suspects comme des lettres qui sont presque identiques visuellement, mais sont des caractères Unicode de différents ensembles.

### Liste de paramètres

`string`

  Chaîne à tester.

`errorCode`

  Cette variable est définie par référence à un entier contenant une erreur, s'il y en avait.

### Valeurs de retour

Retourne `true` s'il y a des caractères suspects, et `false` sinon.

### Exemples

Exemple #1 Exemple Spoofchecker::isSuspicious()

    <?php
    $checker = new Spoofchecker();

    $checker->isSuspicious('google.com'); // FALSE: seulement des caractères ASCII

    $checker->isSuspicious('Рaypal.com'); // TRUE
    // La première lettre est Cyrillique, pas un "P" latin

# Spoofchecker::setAllowedChars

(PHP 8 >= 8.4.0)

Spoofchecker::setAllowedChars — Définit l'ensemble des caractères autorisés lors de l'exécution des vérifications

### Description

public function Spoofchecker::setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void

Restreint les caractères considérés comme acceptables par les vérifications suivantes à l'ensemble décrit par `pattern`. Tout caractère en dehors de cet ensemble fait que Spoofchecker::isSuspicious() signale un résultat.

### Liste de paramètres

`pattern`
  Un ensemble de caractères décrit sous forme de motif `UnicodeSet`, c'est-à-dire une classe de caractères de style expression régulière. Il doit commencer par `[` et se terminer par `]`, par exemple `[a-z0-9]`.
`patternOptions`
  Un masque de bits contrôlant la façon dont `pattern` est interprété. Il doit valoir `0`, ou `Spoofchecker::IGNORE_SPACE` seul ou combiné avec exactement l'une des constantes `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS`, ou `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Lance une ValueError si `pattern` n'est pas un motif d'ensemble de caractères valide, ou si `patternOptions` n'est pas une combinaison d'options valide.

### Exemples

Exemple #1 Exemple avec Spoofchecker::setAllowedChars()

    <?php
    $checker = new Spoofchecker();
    $checker->setAllowedChars('[a-z0-9]');

    var_dump($checker->isSuspicious('hello'));
    var_dump($checker->isSuspicious('héllo'));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)

### Voir aussi

- Spoofchecker::setAllowedLocales() - Locales à utiliser lors de la vérification
- Spoofchecker::isSuspicious() - Vérifie si un texte contient des caractères suspects

# Spoofchecker::setAllowedLocales

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setAllowedLocales — Locales à utiliser lors de la vérification

### Description

public function Spoofchecker::setAllowedLocales(string `$locales`): void

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`locales`

### Valeurs de retour

# Spoofchecker::setChecks

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setChecks — Spécifie les vérifications à effectuer

### Description

public function Spoofchecker::setChecks(int `$checks`): void

Définit les contrôles qui seront effectués par SpoofChecker::isSuspicious().

### Liste de paramètres

`checks`

  Les contrôles qui seront effectués par SpoofChecker::isSuspicious(). Un masque de bits de `Spoofchecker::SINGLE_SCRIPT_CONFUSABLE`, `Spoofchecker::MIXED_SCRIPT_CONFUSABLE`, `Spoofchecker::WHOLE_SCRIPT_CONFUSABLE`, `Spoofchecker::ANY_CASE`, `Spoofchecker::SINGLE_SCRIPT`, `Spoofchecker::INVISIBLE` ou `Spoofchecker::CHAR_LIMIT`. Par défaut, toutes les vérifications à partir de ICU 58 ; avant cette version, `Spoofchecker::SINGLE_SCRIPT` était exclu.

### Valeurs de retour

Aucune valeur n'est retournée.

# Spoofchecker::setRestrictionLevel

(PHP 7 >= 7.3.0, PHP 8)

Spoofchecker::setRestrictionLevel — Définit le niveau de restriction

### Description

public function Spoofchecker::setRestrictionLevel(int `$level`): void

Définit le niveau de restriction de SpoofChecker::isSuspicious().

### Liste de paramètres

`level`

  Le niveau de restriction de SpoofChecker::isSuspicious(). Une des `Spoofchecker::ASCII`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE`, ou `Spoofchecker::UNRESTRICTIVE`. Par défaut à `Spoofchecker::HIGHLY_RESTRICTIVE`.

### Valeurs de retour

Aucune valeur n'est retournée.

## Sommaire

- Spoofchecker::areConfusable — Vérifie si les chaînes données peuvent être confondues
- Spoofchecker::__construct — Constructeur
- Spoofchecker::isSuspicious — Vérifie si un texte contient des caractères suspects
- Spoofchecker::setAllowedChars — Définit l'ensemble des caractères autorisés lors de l'exécution des vérifications
- Spoofchecker::setAllowedLocales — Locales à utiliser lors de la vérification
- Spoofchecker::setChecks — Spécifie les vérifications à effectuer
- Spoofchecker::setRestrictionLevel — Définit le niveau de restriction

# La classe Transliterator

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Introduction

La classe Transliterator fournit la translittération des chaînes de caractères.

## Synopsis de la classe

class Transliterator {
/* Constantes */
public const int FORWARD;
public const int REVERSE;
/* Propriétés */
public readonly string $id;
/* Méthodes */
final private function __construct()
public static function create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public static function createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public function createInverse(): ?Transliterator
public function getErrorCode(): int
public function getErrorMessage(): string
public static function listIDs(): array|false
public function transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false
}

## Propriétés

id

## Constantes pré-définies

`Transliterator::FORWARD` int

`Transliterator::REVERSE` int

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.
8.2.0 | La propriété id est désormais readonly.

# Transliterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::__construct — Constructeur privé pour interdire l'instanciation

### Description

final private function Transliterator::__construct()

Cette méthode ne doit pas être appelée. Son seul but est d'interdire l'instanciation avec l'opérateur new.

Utiliser les méthodes d'usine Transliterator::create() et Transliterator::createFromRules() à la place.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- Transliterator::create() - Crée un Transliterator
- Transliterator::createFromRules() - Crée un translittérateur depuis des règles

# Transliterator::create

# transliterator_create

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::create -- transliterator_create — Crée un Transliterator

### Description

Style orienté objet

public static function Transliterator::create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Style procédural

function transliterator_create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Ouvre un Transliterator par son identifiant.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`id`

  L'identifiant. Une liste de tous les identifiants transliterator enregistrés peut être retrouvée en utilisant la méthode Transliterator::listIDs().

`direction`

  La direction, par défaut Transliterator::FORWARD. Peut également être définie à Transliterator::REVERSE.

### Valeurs de retour

Retourne un objet Transliterator en cas de succès, ou `null` si une erreur survient.

### Voir aussi

- Transliterator::getErrorMessage() - Récupère le dernier message d'erreur
- Transliterator::__construct() - Constructeur privé pour interdire l'instanciation

# Transliterator::createFromRules

# transliterator_create_from_rules

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createFromRules -- transliterator_create_from_rules — Crée un translittérateur depuis des règles

### Description

Style orienté objet

public static function Transliterator::createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Style procédural

function transliterator_create_from_rules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Crée un translittérateur depuis des règles.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`rules`

  Les règles comme définies dans Transform Rules Syntax de UTS #35 : Unicode LDML.

`direction`

  La direction, par défaut Transliterator::FORWARD. Peut également être définie à Transliterator::REVERSE.

### Valeurs de retour

Retourne un objet Transliterator en cas de succès, ou `null` si une erreur survient.

### Voir aussi

- Transliterator::getErrorMessage() - Récupère le dernier message d'erreur
- Transliterator::create() - Crée un Transliterator

# Transliterator::createInverse

# transliterator_create_inverse

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createInverse -- transliterator_create_inverse — Crée un translittérateur inverse

### Description

Style orienté objet

public function Transliterator::createInverse(): ?Transliterator

Style procédural

function transliterator_create_inverse(Transliterator `$transliterator`): ?Transliterator

Crée un translittérateur inverse.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet Transliterator en cas de succès, ou `null` si une erreur survient.

### Voir aussi

- Transliterator::getErrorMessage() - Récupère le dernier message d'erreur
- Transliterator::create() - Crée un Transliterator

# Transliterator::getErrorCode

# transliterator_get_error_code

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorCode -- transliterator_get_error_code — Récupère le dernier code erreur

### Description

Style orienté objet

public function Transliterator::getErrorCode(): int

Style procédural

function transliterator_get_error_code(Transliterator `$transliterator`): int

Récupère le dernier code erreur depuis ce translittérateur.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`transliterator`

### Valeurs de retour

Le code erreur en cas de succès, ou `false` s'il n'en existe pas ou si une erreur survient.

### Voir aussi

- Transliterator::getErrorMessage() - Récupère le dernier message d'erreur
- Transliterator::listIDs() - Récupère les identifiants de ce translittérateur

# Transliterator::getErrorMessage

# transliterator_get_error_message

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorMessage -- transliterator_get_error_message — Récupère le dernier message d'erreur

### Description

Style orienté objet

public function Transliterator::getErrorMessage(): string

Style procédural

function transliterator_get_error_message(Transliterator `$transliterator`): string

Récupère le dernier message d'erreur depuis ce translittérateur.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`transliterator`

### Valeurs de retour

Le message d'erreur en cas de succès, ou `false` si aucune erreur n'existe, ou si une erreur survient.

### Voir aussi

- Transliterator::getErrorCode() - Récupère le dernier code erreur
- Transliterator::listIDs() - Récupère les identifiants de ce translittérateur

# Transliterator::listIDs

# transliterator_list_ids

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::listIDs -- transliterator_list_ids — Récupère les identifiants de ce translittérateur

### Description

Style orienté objet

public static function Transliterator::listIDs(): array|false

Style procédural

function transliterator_list_ids(): array|false

Retourne un tableau contenant tous les identifiants enregistrés pour ce translittérateur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau contenant tous les identifiants enregistrés pour ce translittérateur en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Récupération des identifiants transliterator enregistrés

    <?php
    print_r(Transliterator::listIDs());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => ASCII-Latin
        [1] => Accents-Any
        [2] => Amharic-Latin/BGN
        [3] => Any-Accents
        [4] => Any-Publishing
    ...
        [650] => Any-ps_Latn/BGN
        [651] => Any-tk/BGN
        [652] => Any-ch_FONIPA
        [653] => Any-cs_FONIPA
        [654] => Any-cy_FONIPA
    )

### Voir aussi

- Transliterator::getErrorMessage() - Récupère le dernier message d'erreur
- Transliterator::transliterate() - Translittère une chaîne de caractères

# Transliterator::transliterate

# transliterator_transliterate

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::transliterate -- transliterator_transliterate — Translittère une chaîne de caractères

### Description

Style orienté objet

public function Transliterator::transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false

Style procédural

function transliterator_transliterate(
Transliterator|string `$transliterator`,
string `$string`,
int `$start` = 0,
int `$end` = -1
): string|false

Transforme une chaîne de caractères ou seulement une partie en utilisant un translittérateur ICU.

### Liste de paramètres

`transliterator`

  Dans la version procédurale, soit un Transliterator soit une chaîne de caractères depuis laquelle un Transliterator peut être construit.

`string`

  La chaîne de caractères à transformer.

`start`

  L'index de départ (en unité UTF-16) depuis lequel la chaîne commencera à être transformée, inclusif. Les index commencent à 0. Le texte avant cet index restera inchangé.

`end`

  L'index de fin (en unité UTF-16) indiquant la fin de la transformation, exclusif. Les index commencent à 0. Le texte après cet index restera inchangé.

### Valeurs de retour

La chaîne de caractères transformée en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Conversion des échappements en unité UTF-16

    <?php
    $s = "\u304A\u65E9\u3046\u3054\u3056\u3044\u307E\u3059";
    echo transliterator_transliterate("Hex-Any/Java", $s), "\n";

    //maintenant, l'opération inverse avec un caractère supplémentaire
    $supplChar = html_entity_decode('&#x1D11E;');
    echo mb_strlen($supplChar, "UTF-8"), "\n";
    $encSupplChar = transliterator_transliterate("Any-Hex/Java", $supplChar);
    //affiche 2 unités UTF-16 encodées
    echo $encSupplChar, "\n";
    //et le retour...
    echo transliterator_transliterate("Hex-Any/Java", $encSupplChar), "\n";
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    お早うございます
    1
    \uD834\uDD1E
    𝄞

### Voir aussi

- Transliterator::getErrorMessage() - Récupère le dernier message d'erreur
- Transliterator::__construct() - Constructeur privé pour interdire l'instanciation

## Sommaire

- Transliterator::__construct — Constructeur privé pour interdire l'instanciation
- Transliterator::create — Crée un Transliterator
- Transliterator::createFromRules — Crée un translittérateur depuis des règles
- Transliterator::createInverse — Crée un translittérateur inverse
- Transliterator::getErrorCode — Récupère le dernier code erreur
- Transliterator::getErrorMessage — Récupère le dernier message d'erreur
- Transliterator::listIDs — Récupère les identifiants de ce translittérateur
- Transliterator::transliterate — Translittère une chaîne de caractères

# La classe IntlBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

Un "délimiteur de rupture" est un objet ICU qui expose des méthodes pour localiser des délimitations dans du texte (par exemple, des délimitations de mots ou de phrases). La classe IntlBreakIterator de PHP sert de classe de base pour tous les types de délimiteurs de rupture ICU. Lorsqu'une fonctionnalité supplémentaire est disponible, l'extension intl peut exposer le délimiteur de rupture ICU avec des sous-classes appropriées, telles que IntlRuleBasedBreakIterator ou IntlCodePointBreakIterator.

Cette classe implémente IteratorAggregate. Parcourir un IntlBreakIterator produit des valeurs entières non négatives représentant les emplacements successifs des délimitations de texte, exprimées en tant que comptes d'unités de code UTF-8 (octets), pris depuis le début du texte (qui a l'emplacement `0`). Les clés produites par l'itérateur forment simplement la séquence de nombres naturels `{0, 1, 2, …}`.

## Synopsis de la classe

class IntlBreakIterator implements IteratorAggregate {
/* Constantes */
public const int DONE;
public const int WORD_NONE;
public const int WORD_NONE_LIMIT;
public const int WORD_NUMBER;
public const int WORD_NUMBER_LIMIT;
public const int WORD_LETTER;
public const int WORD_LETTER_LIMIT;
public const int WORD_KANA;
public const int WORD_KANA_LIMIT;
public const int WORD_IDEO;
public const int WORD_IDEO_LIMIT;
public const int LINE_SOFT;
public const int LINE_SOFT_LIMIT;
public const int LINE_HARD;
public const int LINE_HARD_LIMIT;
public const int SENTENCE_TERM;
public const int SENTENCE_TERM_LIMIT;
public const int SENTENCE_SEP;
public const int SENTENCE_SEP_LIMIT;
/* Méthodes */
private function __construct()
public static function createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createCodePointInstance(): IntlCodePointBreakIterator
public static function createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function current(): int
public function first(): int
public function following(int `$offset`): int
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type`): string|false
public function getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function getText(): ?string
public function isBoundary(int `$offset`): bool
public function last(): int
public function next(?int `$offset` = `null`): int
public function preceding(int `$offset`): int
public function previous(): int
public function setText(string `$text`): bool
}

## Constantes pré-définies

`IntlBreakIterator::DONE` int

`IntlBreakIterator::WORD_NONE` int

`IntlBreakIterator::WORD_NONE_LIMIT` int

`IntlBreakIterator::WORD_NUMBER` int

`IntlBreakIterator::WORD_NUMBER_LIMIT` int

`IntlBreakIterator::WORD_LETTER` int

`IntlBreakIterator::WORD_LETTER_LIMIT` int

`IntlBreakIterator::WORD_KANA` int

`IntlBreakIterator::WORD_KANA_LIMIT` int

`IntlBreakIterator::WORD_IDEO` int

`IntlBreakIterator::WORD_IDEO_LIMIT` int

`IntlBreakIterator::LINE_SOFT` int

`IntlBreakIterator::LINE_SOFT_LIMIT` int

`IntlBreakIterator::LINE_HARD` int

`IntlBreakIterator::LINE_HARD_LIMIT` int

`IntlBreakIterator::SENTENCE_TERM` int

`IntlBreakIterator::SENTENCE_TERM_LIMIT` int

`IntlBreakIterator::SENTENCE_SEP` int

`IntlBreakIterator::SENTENCE_SEP_LIMIT` int

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont désormais typées.
8.0.0 | IntlBreakIterator implémente désormais IteratorAggregate. Avant, Traversable était implémentée à la place.

# IntlBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::__construct — Constructeur privé pour désactiver l'instantiation

### Description

private function IntlBreakIterator::__construct()

Les instances de IntlBreakIterator devraient être créées en utilisant l'une des méthodes d'usine statiques.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Voir aussi

- IntlBreakIterator::createCharacterInstance() - Crée un itérateur pour les limites des séquences de caractères combinés
- IntlBreakIterator::createCodePointInstance() - Crée un itérateur pour les limites de points de code
- IntlBreakIterator::createLineInstance() - Crée un itérateur pour les coupures de lignes
- IntlBreakIterator::createSentenceInstance() - Crée un itérateur pour les coupures de phrase
- IntlBreakIterator::createTitleInstance() - Crée un itérateur
- IntlBreakIterator::createWordInstance() - Crée un itérateur pour les coupures de mot

# IntlBreakIterator::createCharacterInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCharacterInstance — Crée un itérateur pour les limites des séquences de caractères combinés

### Description

public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`locale`

### Valeurs de retour

# IntlBreakIterator::createCodePointInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCodePointInstance — Crée un itérateur pour les limites de points de code

### Description

public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlBreakIterator::createLineInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createLineInstance — Crée un itérateur pour les coupures de lignes

### Description

public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`locale`

### Valeurs de retour

# IntlBreakIterator::createSentenceInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createSentenceInstance — Crée un itérateur pour les coupures de phrase

### Description

public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`locale`

### Valeurs de retour

# IntlBreakIterator::createTitleInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createTitleInstance — Crée un itérateur

### Description

public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`locale`

### Valeurs de retour

# IntlBreakIterator::createWordInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createWordInstance — Crée un itérateur pour les coupures de mot

### Description

public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`locale`

### Valeurs de retour

# IntlBreakIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::current — Récupère l'index de la position courante

### Description

public function IntlBreakIterator::current(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlBreakIterator::first

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::first — Définit la position au premier caractère du texte

### Description

public function IntlBreakIterator::first(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlBreakIterator::following

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::following — Avance l'itérateur à la première limite suivant la position spécifiée

### Description

public function IntlBreakIterator::following(int `$offset`): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`offset`

### Valeurs de retour

# IntlBreakIterator::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorCode -- intl_get_error_code — Récupère le code de la dernière erreur survenue sur l'objet

### Description

Style orienté objet (méthode):

public function IntlBreakIterator::getErrorCode(): int

Style procédural:

function intl_get_error_code(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlBreakIterator::getErrorMessage

# intl_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorMessage -- intl_get_error_message — Récupère le message de la dernière erreur survenue sur l'objet

### Description

Style orienté objet (méthode):

public function IntlBreakIterator::getErrorMessage(): string

Style procédural:

function intl_get_error_message(): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlBreakIterator::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getLocale — Récupère la locale associée avec l'objet

### Description

public function IntlBreakIterator::getLocale(int `$type`): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`type`

### Valeurs de retour

# IntlBreakIterator::getPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getPartsIterator — Crée un itérateur pour naviguer dans les fragments entre les limites

### Description

public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`type`

  Type de clé (optionnel). Les valeurs possibles sont :

  - `IntlPartsIterator::KEY_SEQUENTIAL` - La valeur par défaut. Entiers séquentiellement croissants utilisés comme clés.
  - `IntlPartsIterator::KEY_LEFT` - Décalage d'octet à gauche de la partie courante utilisée comme clé.
  - `IntlPartsIterator::KEY_RIGHT` - Octet décalage droit de la partie courante utilisée comme clé.

### Valeurs de retour

# IntlBreakIterator::getText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getText — Récupère le texte analysé

### Description

public function IntlBreakIterator::getText(): ?string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlBreakIterator::isBoundary

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::isBoundary — Indique si une position est une position limite

### Description

public function IntlBreakIterator::isBoundary(int `$offset`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`offset`

### Valeurs de retour

# IntlBreakIterator::last

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::last — Définit la position de l'itérateur à l'index après le dernier caractère

### Description

public function IntlBreakIterator::last(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlBreakIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::next — Avance l'itérateur à la prochaine limite

### Description

public function IntlBreakIterator::next(?int `$offset` = `null`): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`offset`

### Valeurs de retour

# IntlBreakIterator::preceding

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::preceding — Définit la position de l'itérateur à la première limite avant la position

### Description

public function IntlBreakIterator::preceding(int `$offset`): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`offset`

### Valeurs de retour

# IntlBreakIterator::previous

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::previous — Définit la position de l'itérateur à la limite immédiate avant la courante

### Description

public function IntlBreakIterator::previous(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlBreakIterator::setText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::setText — Définit le texte à analyser

### Description

public function IntlBreakIterator::setText(string `$text`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`text`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.3.0 | Cette méthode retourne désormais `false` en cas d'échec ; précédemment elle retournait `null`.

## Sommaire

- IntlBreakIterator::__construct — Constructeur privé pour désactiver l'instantiation
- IntlBreakIterator::createCharacterInstance — Crée un itérateur pour les limites des séquences de caractères combinés
- IntlBreakIterator::createCodePointInstance — Crée un itérateur pour les limites de points de code
- IntlBreakIterator::createLineInstance — Crée un itérateur pour les coupures de lignes
- IntlBreakIterator::createSentenceInstance — Crée un itérateur pour les coupures de phrase
- IntlBreakIterator::createTitleInstance — Crée un itérateur
- IntlBreakIterator::createWordInstance — Crée un itérateur pour les coupures de mot
- IntlBreakIterator::current — Récupère l'index de la position courante
- IntlBreakIterator::first — Définit la position au premier caractère du texte
- IntlBreakIterator::following — Avance l'itérateur à la première limite suivant la position spécifiée
- IntlBreakIterator::getErrorCode — Récupère le code de la dernière erreur survenue sur l'objet
- IntlBreakIterator::getErrorMessage — Récupère le message de la dernière erreur survenue sur l'objet
- IntlBreakIterator::getLocale — Récupère la locale associée avec l'objet
- IntlBreakIterator::getPartsIterator — Crée un itérateur pour naviguer dans les fragments entre les limites
- IntlBreakIterator::getText — Récupère le texte analysé
- IntlBreakIterator::isBoundary — Indique si une position est une position limite
- IntlBreakIterator::last — Définit la position de l'itérateur à l'index après le dernier caractère
- IntlBreakIterator::next — Avance l'itérateur à la prochaine limite
- IntlBreakIterator::preceding — Définit la position de l'itérateur à la première limite avant la position
- IntlBreakIterator::previous — Définit la position de l'itérateur à la limite immédiate avant la courante
- IntlBreakIterator::setText — Définit le texte à analyser

# La classe IntlRuleBasedBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

Une sous-classe de IntlBreakIterator qui encapsule les itérateurs de rupture ICU dont le comportement est spécifié à l'aide d'un ensemble de règles. C'est le type d'itérateur de rupture le plus courant.

Ces règles sont décrites dans le » Guide de l'utilisateur de l'analyse des limites ICU.

## Synopsis de la classe

class IntlRuleBasedBreakIterator extends IntlBreakIterator {
/* Constantes héritées */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Méthodes */
public function __construct(string `$rules`, bool `$compiled` = `false`)
public function getBinaryRules(): string|false
public function getRules(): string|false
public function getRuleStatus(): int
public function getRuleStatusVec(): array|false
/* Méthodes héritées */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlRuleBasedBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::__construct — Crée un itérateur depuis un jeu de règles

### Description

public function IntlRuleBasedBreakIterator::__construct(string `$rules`, bool `$compiled` = `false`)

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`rules`

`compiled`

### Valeurs de retour

# IntlRuleBasedBreakIterator::getBinaryRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getBinaryRules — Récupère la forme binaire des règles compilées

### Description

public function IntlRuleBasedBreakIterator::getBinaryRules(): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlRuleBasedBreakIterator::getRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRules — Récupère le jeu de règles utilisé pour créer cet objet

### Description

public function IntlRuleBasedBreakIterator::getRules(): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlRuleBasedBreakIterator::getRuleStatus

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatus — Récupère la valeur de statut la plus grande depuis les règles qui déterminent la position courante d'arrêt

### Description

public function IntlRuleBasedBreakIterator::getRuleStatus(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlRuleBasedBreakIterator::getRuleStatusVec

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatusVec — Récupère les valeurs de statut depuis les règles d'arrêt qui déterminent la position d'arrêt courante

### Description

public function IntlRuleBasedBreakIterator::getRuleStatusVec(): array|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

## Sommaire

- IntlRuleBasedBreakIterator::__construct — Crée un itérateur depuis un jeu de règles
- IntlRuleBasedBreakIterator::getBinaryRules — Récupère la forme binaire des règles compilées
- IntlRuleBasedBreakIterator::getRules — Récupère le jeu de règles utilisé pour créer cet objet
- IntlRuleBasedBreakIterator::getRuleStatus — Récupère la valeur de statut la plus grande depuis les règles qui déterminent la position courante d'arrêt
- IntlRuleBasedBreakIterator::getRuleStatusVec — Récupère les valeurs de statut depuis les règles d'arrêt qui déterminent la position d'arrêt courante

# La classe IntlCodePointBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

Cet itérateur de rupture identifie les limites entre les points de code UTF-8.

## Synopsis de la classe

class IntlCodePointBreakIterator extends IntlBreakIterator {
/* Constantes héritées */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Méthodes */
public function getLastCodePoint(): int
/* Méthodes héritées */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlCodePointBreakIterator::getLastCodePoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlCodePointBreakIterator::getLastCodePoint — Récupère le dernier point de code après avoir avancé ou reculé dans l'itérateur

### Description

public function IntlCodePointBreakIterator::getLastCodePoint(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

## Sommaire

- IntlCodePointBreakIterator::getLastCodePoint — Récupère le dernier point de code après avoir avancé ou reculé dans l'itérateur

# La classe IntlDatePatternGenerator

(PHP 8 >= 8.1.0)

## Introduction

Génère des chaînes de format de date et/ou d'heure localisées adaptées à l'utilisation dans IntlDateFormatter.

## Synopsis de la classe

class IntlDatePatternGenerator {
/* Méthodes */
public function __construct(?string `$locale` = `null`)
public static function create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function getBestPattern(string `$skeleton`): string|false
}

# IntlDatePatternGenerator::create

# IntlDatePatternGenerator::__construct

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::create -- IntlDatePatternGenerator::__construct — Créer une nouvelle instance de IntlDatePatternGenerator

### Description

public static function IntlDatePatternGenerator::create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function IntlDatePatternGenerator::__construct(?string `$locale` = `null`)

Crée une nouvelle instance de IntlDatePatternGenerator.

### Liste de paramètres

`locale`

  La locale. Si `null` est passé, utilise le paramètre ini intl.default_locale.

### Valeurs de retour

Renvoie une instance de IntlDatePatternGenerator en cas de succès, ou `null` en cas d'échec.

# IntlDatePatternGenerator::getBestPattern

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::getBestPattern — Détermine le format de date/heure le plus adapté

### Description

public function IntlDatePatternGenerator::getBestPattern(string `$skeleton`): string|false

Détermine quel format de date/heure est le plus adapté pour une locale donnée.

### Liste de paramètres

`skeleton`

  Le squelette.

### Valeurs de retour

Renvoie un motif de date/heure ICU accepté par IntlDateFormatter en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple de IntlDatePatternGenerator::getBestPattern()

    <?php

    $skeleton = 'YYYYMMdd';
    $today = \DateTimeImmutable::createFromFormat('Y-m-d', '2021-04-24');

    $patternGenerator = new \IntlDatePatternGenerator('de_DE');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'de: ', \IntlDateFormatter::formatObject($today, $pattern, 'de_DE'), "\n";

    $patternGenerator = new \IntlDatePatternGenerator('en_US');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'en: ', \IntlDateFormatter::formatObject($today, $pattern, 'en_US');
    ?>

L'exemple ci-dessus va afficher :

    de: 24.04.2021
    en: 04/24/2021

## Sommaire

- IntlDatePatternGenerator::create — Créer une nouvelle instance de IntlDatePatternGenerator
- IntlDatePatternGenerator::getBestPattern — Détermine le format de date/heure le plus adapté

# La classe IntlPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

Les objets de cette classe peuvent être obtenus à partir d'objets IntlBreakIterator. Alors que les itérateurs de rupture fournissent une séquence de positions de limites lorsqu'ils sont itérés, les objets IntlPartsIterator fournissent, par commodité, les fragments de texte compris entre deux limites successives.

Les clés peuvent représenter le décalage de la limite gauche, de la limite droite, ou elles peuvent simplement être la séquence d'entiers non négatifs. Voir IntlBreakIterator::getPartsIterator().

## Synopsis de la classe

class IntlPartsIterator extends IntlIterator {
/* Constantes */
public const int KEY_SEQUENTIAL;
public const int KEY_LEFT;
public const int KEY_RIGHT;
/* Méthodes */
public function getBreakIterator(): IntlBreakIterator
/* Méthodes héritées */
public function IntlIterator::current(): mixed
public function IntlIterator::key(): mixed
public function IntlIterator::next(): void
public function IntlIterator::rewind(): void
public function IntlIterator::valid(): bool
}

## Constantes pré-définies

`IntlPartsIterator::KEY_SEQUENTIAL` int

`IntlPartsIterator::KEY_LEFT` int

`IntlPartsIterator::KEY_RIGHT` int

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.

# IntlPartsIterator::getBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlPartsIterator::getBreakIterator — Récupère IntlBreakIterator, sauvegardant ainsi cette partie de l'itérateur

### Description

public function IntlPartsIterator::getBreakIterator(): IntlBreakIterator

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

## Sommaire

- IntlPartsIterator::getBreakIterator — Récupère IntlBreakIterator, sauvegardant ainsi cette partie de l'itérateur

# La classe UConverter

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Introduction

## Synopsis de la classe

class UConverter {
/* Constantes */
public const int REASON_UNASSIGNED;
public const int REASON_ILLEGAL;
public const int REASON_IRREGULAR;
public const int REASON_RESET;
public const int REASON_CLOSE;
public const int REASON_CLONE;
public const int UNSUPPORTED_CONVERTER;
public const int SBCS;
public const int DBCS;
public const int MBCS;
public const int LATIN_1;
public const int UTF8;
public const int UTF16_BigEndian;
public const int UTF16_LittleEndian;
public const int UTF32_BigEndian;
public const int UTF32_LittleEndian;
public const int EBCDIC_STATEFUL;
public const int ISO_2022;
public const int LMBCS_1;
public const int LMBCS_2;
public const int LMBCS_3;
public const int LMBCS_4;
public const int LMBCS_5;
public const int LMBCS_6;
public const int LMBCS_8;
public const int LMBCS_11;
public const int LMBCS_16;
public const int LMBCS_17;
public const int LMBCS_18;
public const int LMBCS_19;
public const int LMBCS_LAST;
public const int HZ;
public const int SCSU;
public const int ISCII;
public const int US_ASCII;
public const int UTF7;
public const int BOCU1;
public const int UTF16;
public const int UTF32;
public const int CESU8;
public const int IMAP_MAILBOX;
/* Méthodes */
public function __construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)
public function convert(string `$str`, bool `$reverse` = `false`): string|false
public function fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null
public static function getAliases(string `$name`): array|false|null
public static function getAvailable(): array
public function getDestinationEncoding(): string|false|null
public function getDestinationType(): int|false|null
public function getErrorCode(): int
public function getErrorMessage(): ?string
public function getSourceEncoding(): string|false|null
public function getSourceType(): int|false|null
public static function getStandards(): ?array
public function getSubstChars(): string|false|null
public static function reasonText(int `$reason`): string
public function setDestinationEncoding(string `$encoding`): bool
public function setSourceEncoding(string `$encoding`): bool
public function setSubstChars(string `$chars`): bool
public function toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null
public static function transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false
}

## Constantes pré-définies

`UConverter::REASON_UNASSIGNED` int

`UConverter::REASON_ILLEGAL` int

`UConverter::REASON_IRREGULAR` int

`UConverter::REASON_RESET` int

`UConverter::REASON_CLOSE` int

`UConverter::REASON_CLONE` int

`UConverter::UNSUPPORTED_CONVERTER` int

`UConverter::SBCS` int

`UConverter::DBCS` int

`UConverter::MBCS` int

`UConverter::LATIN_1` int

`UConverter::UTF8` int

`UConverter::UTF16_BigEndian` int

`UConverter::UTF16_LittleEndian` int

`UConverter::UTF32_BigEndian` int

`UConverter::UTF32_LittleEndian` int

`UConverter::EBCDIC_STATEFUL` int

`UConverter::ISO_2022` int

`UConverter::LMBCS_1` int

`UConverter::LMBCS_2` int

`UConverter::LMBCS_3` int

`UConverter::LMBCS_4` int

`UConverter::LMBCS_5` int

`UConverter::LMBCS_6` int

`UConverter::LMBCS_8` int

`UConverter::LMBCS_11` int

`UConverter::LMBCS_16` int

`UConverter::LMBCS_17` int

`UConverter::LMBCS_18` int

`UConverter::LMBCS_19` int

`UConverter::LMBCS_LAST` int

`UConverter::HZ` int

`UConverter::SCSU` int

`UConverter::ISCII` int

`UConverter::US_ASCII` int

`UConverter::UTF7` int

`UConverter::BOCU1` int

`UConverter::UTF16` int

`UConverter::UTF32` int

`UConverter::CESU8` int

`UConverter::IMAP_MAILBOX` int

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont maintenant typées.

# UConverter::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::__construct — Crée un objet UConverter

### Description

public function UConverter::__construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`destination_encoding`

`source_encoding`

### Valeurs de retour

# UConverter::convert

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::convert — Convertit une chaîne d'un jeu de caractères vers un autre jeu de caractères

### Description

public function UConverter::convert(string `$str`, bool `$reverse` = `false`): string|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`str`

`reverse`

### Valeurs de retour

# UConverter::fromUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::fromUCallback — Fonction de rappel "from"

### Description

public function UConverter::fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`reason`

`source`

`codePoint`

`error`

### Valeurs de retour

# UConverter::getAliases

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAliases — Récupère les alias du nom fourni

### Description

public static function UConverter::getAliases(string `$name`): array|false|null

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`name`

### Valeurs de retour

# UConverter::getAvailable

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAvailable — Récupère le nom canonique des convertisseurs disponibles

### Description

public static function UConverter::getAvailable(): array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# UConverter::getDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationEncoding — Récupère l'encodage de la destination

### Description

public function UConverter::getDestinationEncoding(): string|false|null

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# UConverter::getDestinationType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationType — Récupère le type de la destination du convertisseur

### Description

public function UConverter::getDestinationType(): int|false|null

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# UConverter::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorCode -- intl_get_error_code — Récupère le code de la dernière erreur survenue sur l'objet

### Description

public function UConverter::getErrorCode(): int

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# UConverter::getErrorMessage

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorMessage — Récupère le message de la dernière erreur survenue sur l'objet

### Description

public function UConverter::getErrorMessage(): ?string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# UConverter::getSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceEncoding — Récupère l'encodage de la source

### Description

public function UConverter::getSourceEncoding(): string|false|null

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# UConverter::getSourceType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceType — Récupère le type de source du convertisseur

### Description

public function UConverter::getSourceType(): int|false|null

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# UConverter::getStandards

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getStandards — Récupère les normes associées aux noms de conversion

### Description

public static function UConverter::getStandards(): ?array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# UConverter::getSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSubstChars — Récupère les caractères de substitution

### Description

public function UConverter::getSubstChars(): string|false|null

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# UConverter::reasonText

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::reasonText — Récupère la chaîne représentant la raison de la fonction de rappel

### Description

public static function UConverter::reasonText(int `$reason`): string

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`reason`

### Valeurs de retour

# UConverter::setDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setDestinationEncoding — Définit l'encodage de la destination

### Description

public function UConverter::setDestinationEncoding(string `$encoding`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`encoding`

### Valeurs de retour

# UConverter::setSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSourceEncoding — Définit l'encodage de la source

### Description

public function UConverter::setSourceEncoding(string `$encoding`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`encoding`

### Valeurs de retour

# UConverter::setSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSubstChars — Définit les caractères de substitution

### Description

public function UConverter::setSubstChars(string `$chars`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`chars`

### Valeurs de retour

# UConverter::toUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::toUCallback — Fonction de rappel "to"

### Description

public function UConverter::toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`reason`

`source`

`codeUnits`

`error`

### Valeurs de retour

# UConverter::transcode

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::transcode — Convertit une chaîne d'un jeu de caractères à un autre

### Description

public static function UConverter::transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false

Convertit `str` de `fromEncoding` à `toEncoding`.

### Liste de paramètres

`str`

  La chaîne de caractères à convertir.

`toEncoding`

  Le jeu de caractères souhaité pour le résultat.

`fromEncoding`

  Le jeu de caractères actuel utilisé pour interpréter `str`.

`options`

  Un tableau optionnel, qui peut contenir les clés suivantes :

  - `'to_subst'` - le caractère de substitution à utiliser à la place de tout caractère de `str` qui ne peut pas être encodé en `toEncoding`. S'il est spécifié, il doit représenter un seul caractère dans l'encodage cible.

### Valeurs de retour

Retourne la chaîne convertie, ou `false` si une erreur survient.

### Exemples

Exemple #1 Conversion de UTF-8 à UTF-16 et inversement

    <?php
    $utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoë' en UTF-8
    $utf16_string = UConverter::transcode($utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";

    $new_utf8_string = UConverter::transcode($utf16_string, 'UTF-8', 'UTF-16BE');
    echo bin2hex($new_utf8_string), "\n";
    ?>

L'exemple ci-dessus va afficher :

    005a006f00eb
    5a6fc3ab

Exemple #2 Caractères non valides en entrée

Si la chaîne d'entrée contient une séquence d'octets qui n'est pas valide dans l'encodage spécifié par `fromEncoding`, ils sont remplacés par le point de code Unicode U+FFFD (Caractère de remplacement) avant d'être convertis en `toEncoding`.

    <?php
    $invalid_utf8_string = "\xC3"; // séquence multi-octets UTF-8 incomplète
    $utf16_string = UConverter::transcode($invalid_utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";
    ?>

L'exemple ci-dessus va afficher :

    fffd

Exemple #3 Caractères ne pouvant être encodés

Si la chaîne d'entrée contient des caractères qui ne peuvent pas être représentés en `toEncoding`, ils sont remplacés par un seul caractère. Le caractère par défaut à utiliser dépend de l'encodage et peut être contrôlé à l'aide de l'option `'to_subst'`.

    <?php
    $utf8_string = "\xE2\x82\xAC"; // € (signe euro) n'existe pas dans l'ISO 8859-1

    // Le remplacement par défaut dans ISO 8859-1 est "\x1A" (Substitut)
    $iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF-8');
    echo bin2hex($iso8859_1_string), "\n";

    // Spécifie un remplacement de '?' ("\x3F") à la place
    $iso8859_1_string = UConverter::transcode(
        $utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";

    // Puisque l'ISO 8859-1 ne peut pas mapper U+FFFD, l'entrée invalide est également remplacée par to_subst.
    $invalid_utf8_string = "\xC3"; // séquence multi-octets UTF-8 incomplète
    $iso8859_1_string = UConverter::transcode(
        $invalid_utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";
    ?>

L'exemple ci-dessus va afficher :

    1a
    3f
    3f

### Voir aussi

- mb_convert_encoding() - Convertir une chaîne d'un codage de caractères à un autre
- iconv() - Convertit une chaîne de caractères à partir d'un encodage vers un autre

## Sommaire

- UConverter::__construct — Crée un objet UConverter
- UConverter::convert — Convertit une chaîne d'un jeu de caractères vers un autre jeu de caractères
- UConverter::fromUCallback — Fonction de rappel "from"
- UConverter::getAliases — Récupère les alias du nom fourni
- UConverter::getAvailable — Récupère le nom canonique des convertisseurs disponibles
- UConverter::getDestinationEncoding — Récupère l'encodage de la destination
- UConverter::getDestinationType — Récupère le type de la destination du convertisseur
- UConverter::getErrorCode — Récupère le code de la dernière erreur survenue sur l'objet
- UConverter::getErrorMessage — Récupère le message de la dernière erreur survenue sur l'objet
- UConverter::getSourceEncoding — Récupère l'encodage de la source
- UConverter::getSourceType — Récupère le type de source du convertisseur
- UConverter::getStandards — Récupère les normes associées aux noms de conversion
- UConverter::getSubstChars — Récupère les caractères de substitution
- UConverter::reasonText — Récupère la chaîne représentant la raison de la fonction de rappel
- UConverter::setDestinationEncoding — Définit l'encodage de la destination
- UConverter::setSourceEncoding — Définit l'encodage de la source
- UConverter::setSubstChars — Définit les caractères de substitution
- UConverter::toUCallback — Fonction de rappel "to"
- UConverter::transcode — Convertit une chaîne d'un jeu de caractères à un autre

# Fonctions Grapheme

# grapheme_extract

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_extract — Extrait un groupe de graphème d'une chaîne UTF-8

### Description

Style procédural

function grapheme_extract(
string `$haystack`,
int `$size`,
int `$type` = `GRAPHEME_EXTR_COUNT`,
int `$offset` = 0,
int `&$next` = `null`
): string|false

Cette fonction extrait une séquence de groupes de graphèmes par défaut d'un texte en UTF-8.

### Liste de paramètres

`haystack`

  La chaîne à étudier.

`size`

  Le nombre maximal d'éléments, en fonction de `type`, à retourner.

`type`

  Définit le type d'unités indiquées par le paramètre `size` :

  - GRAPHEME_EXTR_COUNT (par défaut) : `size` est le nombre de groupe de graphèmes à extraire.
  - GRAPHEME_EXTR_MAXBYTES : `size` est le nombre d'octets à retourner.
  - GRAPHEME_EXTR_MAXCHARS : `size` est le nombre de caractères UTF-8 à retourner.
`offset`

  La position de début dans `haystack`, exprimée en octets. Elle doit être positive, nulle ou inférieure à la taille de `haystack` en octets, ou une valeur négative, qui compterait à partir de la fin de `haystack`. Si `offset` ne correspond pas au premier octet d'un caractère UTF-8 valide, la position de démarrage sera déplacée au prochain octet valide.

`next`

  Référence à une variable qui recevra la prochaine position de début valide. Lorsque la fonction se termine, cela peut être une position qui est au-delà de la taille de la chaîne.

### Valeurs de retour

Une chaîne qui débute à la position `offset` et se termine à la limite valide d'un graphème, et qui se conforme aux conditions `size` et `type` spécifiées, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.1.0 | Le support des valeurs négatives pour `offset` a été ajouté.

### Exemples

Exemple #1 Exemple avec grapheme_extract()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print urlencode(grapheme_extract( $char_a_ring_nfd . $char_o_diaeresis_nfd, 1, GRAPHEME_EXTR_COUNT, 2));

    ?>

L'exemple ci-dessus va afficher :

    o%CC%88

### Voir aussi

- grapheme_substr() - Retourne une partie d'une chaîne
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_str_split

(PHP 8 >= 8.4.0)

grapheme_str_split — Sépare une chaîne en un tableau

### Description

function grapheme_str_split(string `$string`, int `$length` = 1): array|false

Cette fonction renvoie un tableau de chaînes, c'est une version de str_split() avec le support des caractères de cluster de graphèmes. Si le paramètre `length` est spécifié, la chaîne est séparée en morceaux de la longueur spécifiée en clusters de graphèmes (pas en octets).

### Liste de paramètres

`string`

  La string à séparer en clusters de graphèmes ou en morceaux. `string` doit être un UTF-8 valide.

`length`

  Chaque élément du tableau renvoyé sera composé de `length` clusters de graphèmes.

### Valeurs de retour

grapheme_str_split() renvoie un tableau de chaînes, ou `false` si une erreur survient.

### Erreurs / Exceptions

Si `length` est inférieur à `1`, une ValueError sera lancée.

### Voir aussi

- str_split() - Convertit une chaîne de caractères en tableau
- mb_str_split() - Pour une chaîne multi-octets donnée, renvoie un tableau de ses caractères
- » Segmentation de texte Unicode : Limites des Clusters de Graphèmes

# grapheme_stripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stripos — Trouve la position en graphème de la première occurrence dans une chaîne, insensible à la casse

### Description

Style procédural

function grapheme_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Trouve la position en graphèmes de la première occurrence dans une chaîne, en effectuant une recherche insensible à la casse.

### Liste de paramètres

`haystack`

  La chaîne à étudier. Elle doit être au format UTF-8 valide.

`needle`

  La chaîne à rechercher. Elle doit être au format UTF-8 valide.

`offset`

  Le paramètre `offset` permet de spécifier la position dans la `haystack` de début de recherche, exprimée en graphèmes (et non pas en octets ou caractères). Si l'offset est négatif, il est traité par rapport à la fin de la chaîne de caractères. La position retournée est toujours donnée par rapport au début de `haystack`, quelle que soit la valeur de `offset`.

`locale`
  Locale à utiliser.

### Valeurs de retour

Retourne la position, sous forme d'un entier. Si `needle` n'est pas trouvé, grapheme_stripos() retourne `false`.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `locale` a été ajouté.
7.1.0 | Ajout du support des `offset`s négatifs.

### Exemples

Exemple #1 Exemple avec grapheme_stripos()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forme normalisée "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forme normalisée "D"
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) forme normalisée "D"

    print grapheme_stripos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

    ?>

L'exemple ci-dessus va afficher :

    2

### Voir aussi

- grapheme_stristr() - Retourne la partie d'une chaîne à partir d'une occurrence
- grapheme_strpos() - Trouve la position du premier graphème
- grapheme_strripos() - Trouve la position du dernier graphème, insensible à la casse
- grapheme_strrpos() - Trouve la position du dernier graphème
- grapheme_strstr() - Retourne la partie d'une chaîne à partir d'une occurrence, sensible à la casse
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_stristr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stristr — Retourne la partie d'une chaîne à partir d'une occurrence

### Description

Style procédural

function grapheme_stristr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

Retourne la partie de `haystack` à partir de la première occurrence de `needle` (`needle` inclus) (insensible à la casse), et jusqu'à la fin de la `haystack`.

### Liste de paramètres

`haystack`

  La chaîne à étudier. Elle doit être en UTF-8 valide.

`needle`

  La chaîne à rechercher. Elle doit être en UTF-8 valide.

`beforeNeedle`

  Si `true`, grapheme_stristr() retourne la partie de `haystack` avant la première occurrence (`needle` exclus).

`locale`
  Locale à utiliser.

### Valeurs de retour

Retourne une portion de `haystack`, ou `false` si `needle` n'est pas trouvé.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `locale` a été ajouté.

### Exemples

Exemple #1 Exemple avec grapheme_stristr()

    <?php

    $char_a_ring_nfd  = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5)  forme normalisée "D"
    $char_o_diaeresis_nfd  = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forme  normalisée "D"
    $char_O_diaeresis_nfd =  "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) forme  normalisée "D"

    print  urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd .  $char_a_ring_nfd, $char_O_diaeresis_nfd));

    ?>

L'exemple ci-dessus va afficher :

    o%CC%88a%CC%8A

### Voir aussi

- grapheme_stripos() - Trouve la position en graphème de la première occurrence dans une chaîne, insensible à la casse
- grapheme_strpos() - Trouve la position du premier graphème
- grapheme_strripos() - Trouve la position du dernier graphème, insensible à la casse
- grapheme_strrpos() - Trouve la position du dernier graphème
- grapheme_strstr() - Retourne la partie d'une chaîne à partir d'une occurrence, sensible à la casse
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strlen

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strlen — Lit la taille d'une chaîne en nombre de graphème

### Description

Style procédural

function grapheme_strlen(string `$string`): int|false|null

Lit la taille d'une chaîne en nombre de graphèmes (et non pas en octets ou caractères).

### Liste de paramètres

`string`

  La chaîne à mesurer. Elle doit être une chaîne UTF-8 valide.

### Valeurs de retour

La taille de la chaîne en cas de succès, `null` ou `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec grapheme_strlen()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forme normalisée "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forme normalisée "D"

    print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd);

    ?>

L'exemple ci-dessus va afficher :

    6

### Voir aussi

- » Unicode Text Segmentation: Grapheme Cluster Boundaries
- iconv_strlen() - Retourne le nombre de caractères d'une chaîne
- mb_strlen() - Retourne la taille d'une chaîne
- strlen() - Calcule la taille d'une chaîne

# grapheme_strpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strpos — Trouve la position du premier graphème

### Description

Style procédural

function grapheme_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Trouve la position du premier graphème dans une chaîne.

### Liste de paramètres

`haystack`

  La chaîne à étudier. Elle doit être au format UTF-8 valide.

`needle`

  La chaîne à étudier. Elle doit être au format UTF-8 valide.

`offset`

  Le paramètre `offset` permet de spécifier la position dans la `haystack` de début de recherche, exprimée en graphèmes (et non pas en octets ou caractères). Si l'offset est négatif, il est traité par rapport à la fin de la chaîne de caractères. La position retournée est toujours donnée par rapport au début de `haystack`, quelle que soit la valeur de `offset`.

`locale`
  Locale à utiliser.

### Valeurs de retour

Retourne la position sous forme d'entier. Si `needle` n'est pas trouvé, grapheme_strpos() retourne `false`.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `locale` a été ajouté.
7.1.0 | Ajout du support des `offset`s négatifs.

### Exemples

Exemple #1 Exemple avec grapheme_strpos()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forme normalisée "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forme normalisée "D"

    print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);

    ?>

L'exemple ci-dessus va afficher :

    2

### Voir aussi

- grapheme_stripos() - Trouve la position en graphème de la première occurrence dans une chaîne, insensible à la casse
- grapheme_stristr() - Retourne la partie d'une chaîne à partir d'une occurrence
- grapheme_strripos() - Trouve la position du dernier graphème, insensible à la casse
- grapheme_strrpos() - Trouve la position du dernier graphème
- grapheme_strstr() - Retourne la partie d'une chaîne à partir d'une occurrence, sensible à la casse
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strripos — Trouve la position du dernier graphème, insensible à la casse

### Description

Style procédural

function grapheme_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Trouve la position du dernier graphème, en effectuant une recherche insensible à la casse.

### Liste de paramètres

`haystack`

  La chaîne à étudier. Elle doit être au format UTF-8 valide.

`needle`

  La chaîne à rechercher. Elle doit être au format UTF-8 valide.

`offset`

  Le paramètre `offset` permet de spécifier la position dans la `haystack` de début de recherche, exprimée en graphèmes (et non pas en octets ou caractères). La position retournée est toujours donnée par rapport au début de `haystack`, quelle que soit la valeur de `offset`.

`locale`
  Locale à utiliser.

### Valeurs de retour

Retourne la position sous forme d'entier. Si `needle` n'est pas trouvé, grapheme_strripos() retourne `false`.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `locale` a été ajouté.

### Exemples

Exemple #1 Exemple avec grapheme_strripos()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forme normalisée "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forme normalisée "D"
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) forme normalisée "D"

    print grapheme_strripos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

    ?>

L'exemple ci-dessus va afficher :

    2

### Voir aussi

- grapheme_stripos() - Trouve la position en graphème de la première occurrence dans une chaîne, insensible à la casse
- grapheme_stristr() - Retourne la partie d'une chaîne à partir d'une occurrence
- grapheme_strpos() - Trouve la position du premier graphème
- grapheme_strrpos() - Trouve la position du dernier graphème
- grapheme_strstr() - Retourne la partie d'une chaîne à partir d'une occurrence, sensible à la casse
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strrpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strrpos — Trouve la position du dernier graphème

### Description

Style procédural

function grapheme_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Trouve la position du dernier graphème, en effectuant une recherche sensible à la casse.

### Liste de paramètres

`haystack`

  La chaîne à étudier. Elle doit être au format UTF-8 valide.

`needle`

  La chaîne à rechercher. Elle doit être au format UTF-8 valide.

`offset`

  Le paramètre `offset` permet de spécifier la position dans la `haystack` de début de recherche, exprimée en graphèmes (et non pas en octets ou caractères). La position retournée est toujours donnée par rapport au début de `haystack`, quelle que soit la valeur de `offset`.

`locale`
  Locale à utiliser.

### Valeurs de retour

Retourne la position sous forme d'un entier. Si `needle` n'est pas trouvé, grapheme_strrpos() retourne `false`.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `locale` a été ajouté.

### Exemples

Exemple #1 Exemple avec grapheme_strrpos()

    <?php
    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) forme normalisée "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) forme normalisée "D"

    print grapheme_strrpos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);
    ?>

L'exemple ci-dessus va afficher :

    2

### Voir aussi

- grapheme_stripos() - Trouve la position en graphème de la première occurrence dans une chaîne, insensible à la casse
- grapheme_stristr() - Retourne la partie d'une chaîne à partir d'une occurrence
- grapheme_strpos() - Trouve la position du premier graphème
- grapheme_strripos() - Trouve la position du dernier graphème, insensible à la casse
- grapheme_strstr() - Retourne la partie d'une chaîne à partir d'une occurrence, sensible à la casse
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strstr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strstr — Retourne la partie d'une chaîne à partir d'une occurrence, sensible à la casse

### Description

Style procédural

function grapheme_strstr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

Retourne la partie d'une chaîne à partir de la première occurrence de `needle` (sensible à la casse), et jusqu'à la fin de la chaîne (`needle` inclus).

### Liste de paramètres

`haystack`

  La chaîne à étudier. Elle doit être en UTF-8 valide.

`needle`

  La chaîne à rechercher. Elle doit être en UTF-8 valide.

`beforeNeedle`

  Si `true`, grapheme_strstr() retourne la partie de la `haystack` avant la première occurrence de la `needle` (à l'exclusion du `needle`).

`locale`
  Locale à utiliser.

### Valeurs de retour

Retourne la portion de la `haystack` ou `false` si `needle` n'est pas trouvé.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `locale` a été ajouté.

### Exemples

Exemple #1 Exemple avec grapheme_strstr()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_o_diaeresis_nfd));

    ?>

L'exemple ci-dessus va afficher :

    o%CC%88a%CC%8A

### Voir aussi

- grapheme_stristr() - Retourne la partie d'une chaîne à partir d'une occurrence
- grapheme_stripos() - Trouve la position en graphème de la première occurrence dans une chaîne, insensible à la casse
- grapheme_strpos() - Trouve la position du premier graphème
- grapheme_strripos() - Trouve la position du dernier graphème, insensible à la casse
- grapheme_strrpos() - Trouve la position du dernier graphème
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_substr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_substr — Retourne une partie d'une chaîne

### Description

Style procédural

function grapheme_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
string `$locale` = ""
): string|false

Retourne une partie d'une chaîne.

### Liste de paramètres

`string`

  La chaîne à couper. Doit être UTF-8 et valide.

`offset`

  Position de départ en unités de graphèmes par défaut. Si `offset` est strictement positif, la chaîne renvoyée commencera à la `offset` ème position dans `string`, en comptant à partir de zéro. Si `offset` est négatif, la chaîne renvoyée commencera à la `offset` ème unité de graphèmes à partir de la fin de la chaîne.

`length`

  La taille de la sous-chaîne à extraire, en unités de graphèmes. Si `length` est donné et positif, la chaîne retournée va contenir au plus `length` graphèmes, commençant à `offset` (en fonction de la taille de la chaîne). Si `length` est fourni et est négatif, alors autant de graphèmes seront omis à partir de la fin de la chaîne (après que la position de début ait été calculée, lorsque `offset` est aussi négatif). Si `offset` dénote une position au-delà de la fin de la chaîne, une chaîne vide sera retournée.

`locale`
  Locale à utiliser.

### Valeurs de retour

Retourne la partie de chaîne extraite de `string`, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.5.0 | Le paramètre optionnel `locale` a été ajouté.
8.0.0 | La fonction fixe désormais systématiquement les décalages hors limites à la limite de la chaîne de caractères. Auparavant, `false` était retourné au lieu de la chaîne vide dans certains cas.

### Exemples

Exemple #1 Exemple avec grapheme_substr()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print urlencode(grapheme_substr( "ao" . $char_a_ring_nfd . "bc" . $char_o_diaeresis_nfd . "O", 2, -1 ));
    ?>

L'exemple ci-dessus va afficher :

    a%CC%8Abco%CC%88

### Voir aussi

- grapheme_extract() - Extrait un groupe de graphème d'une chaîne UTF-8
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

## Sommaire

- grapheme_extract — Extrait un groupe de graphème d'une chaîne UTF-8
- grapheme_str_split — Sépare une chaîne en un tableau
- grapheme_stripos — Trouve la position en graphème de la première occurrence dans une chaîne, insensible à la casse
- grapheme_stristr — Retourne la partie d'une chaîne à partir d'une occurrence
- grapheme_strlen — Lit la taille d'une chaîne en nombre de graphème
- grapheme_strpos — Trouve la position du premier graphème
- grapheme_strripos — Trouve la position du dernier graphème, insensible à la casse
- grapheme_strrpos — Trouve la position du dernier graphème
- grapheme_strstr — Retourne la partie d'une chaîne à partir d'une occurrence, sensible à la casse
- grapheme_substr — Retourne une partie d'une chaîne

# Fonctions IDN

# idn_to_ascii

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_ascii — Convertit un nom de domaine au format IDNA ASCII

### Description

Style procédural

function idn_to_ascii(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

Cette fonction convertit un nom de domaine Unicode en un format ASCII compatible IDNA, en minuscules.

### Liste de paramètres

`domain`

  Le domaine à convertir, qui doit être encodé UTF-8.

`flags`

  Options de conversion - combinaison de constantes IDNA_*. (sauf les constantes IDNA_ERROR_*).

`variant`

  Soit `INTL_IDNA_VARIANT_2003` (obsolète à partir de PHP 7.2.0) pour IDNA 2003, soit `INTL_IDNA_VARIANT_UTS46` (seulement disponible à partir de ICU 4.6) pour UTS #46.

`idna_info`

  Ce paramètre ne peut être utilisé que si la constante `INTL_IDNA_VARIANT_UTS46` a été utilisée dans le paramètre `variant`. Dans ce cas, ce sera un tableau avec la clé `'result'` contenant le résultat de la transformation, la clé `'isTransitionalDifferent'` contenant un booléen indiquant l'utilisation du mécanisme transitionnel UTS #46 ayant altéré ou non le résultat, et la clé `'errors'` contenant un int représentant un jeu de bits des constantes d'erreurs IDNA_ERROR_*.

### Valeurs de retour

Le nom de domaine encodé au format ASCII-compatible. ou `false` si une erreur survient

### Historique

Version | Description
--- | ---
8.4.0 | Lance désormais une ValueError si le paramètre `domain` est vide.
8.4.0 | Lance désormais une ValueError si le paramètre `variant` n'est pas `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | La valeur par défaut du paramètre `variant` est maintenant `INTL_IDNA_VARIANT_UTS46` à la place de la constante `INTL_IDNA_VARIANT_2003` dépréciée.
7.2.0 | `INTL_IDNA_VARIANT_2003` a été déprécié ; utiliser `INTL_IDNA_VARIANT_UTS46` à la place.

### Exemples

Exemple #1 Exemple avec idn_to_ascii()

    <?php

    echo idn_to_ascii('täst.de');
    ?>

L'exemple ci-dessus va afficher :

    xn--tst-qla.de

Exemple #2 Les noms de domaine entièrement ASCII sont simplement convertis en minuscules

    <?php

    var_dump(idn_to_ascii('Example.com'));

    ?>

L'exemple ci-dessus va afficher :

    string(11) "example.com"

### Voir aussi

- idn_to_utf8() - Convertit le nom de domaine IDNA ASCII en Unicode

# idn_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_utf8 — Convertit le nom de domaine IDNA ASCII en Unicode

### Description

Style procédural

function idn_to_utf8(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

Cette fonction convertit le nom de domaine au format IDNA ASCII-compatible en Unicode, encodé en UTF-8.

### Liste de paramètres

`domain`

  Domaine à convertir depuis le format IDNA ASCII-compatible.

`flags`

  Options de conversion - une combinaison des constantes IDNA_* (sauf les constantes IDNA_ERROR_*).

`variant`

  Soit `INTL_IDNA_VARIANT_2003` (obsolète à partir de PHP 7.2.0) pour IDNA 2003, soit `INTL_IDNA_VARIANT_UTS46` (seulement disponible à partir de ICU 4.6) pour UTS #46.

`idna_info`

  Ce paramètre ne peut être utilisé que si la constante `INTL_IDNA_VARIANT_UTS46` a été utilisée comme paramètre pour `variant`. Dans ce cas, ce paramètre sera rempli par un tableau dont la clé `'result'` contiendra le résultat de la transformation, la clé `'isTransitionalDifferent'` contiendra un booléen indiquant si l'utilisation du mécanisme transitionnel UTS #46 a altéré ou non le résultat, et la clé `'errors'` contiendra un int représentant un jeu de bits de constantes d'erreurs IDNA_ERROR_*.

### Valeurs de retour

Nom de domaine en Unicode, encodé UTF-8. ou `false` si une erreur survient

### Historique

Version | Description
--- | ---
8.4.0 | Lance désormais une ValueError si le paramètre `domain` est vide.
8.4.0 | Lance désormais une ValueError si le paramètre `variant` n'est pas `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | La valeur par défaut du paramètre `variant` est maintenant `INTL_IDNA_VARIANT_UTS46` à la place de la constante `INTL_IDNA_VARIANT_2003` dépréciée.
7.2.0 | `INTL_IDNA_VARIANT_2003` a été déprécié ; utiliser `INTL_IDNA_VARIANT_UTS46` à la place.

### Exemples

Exemple #1 Exemple avec idn_to_utf8()

    <?php

    echo idn_to_utf8('xn--tst-qla.de');

    ?>

L'exemple ci-dessus va afficher :

    täst.de

### Voir aussi

- idn_to_ascii() - Convertit un nom de domaine au format IDNA ASCII

## Sommaire

- idn_to_ascii — Convertit un nom de domaine au format IDNA ASCII
- idn_to_utf8 — Convertit le nom de domaine IDNA ASCII en Unicode

# IntlChar

(PHP 7, PHP 8)

## Introduction

IntlChar donne accès à un certain nombre de méthodes utilitaires qui peuvent être utilisées pour accéder à des informations sur les caractères Unicode.

Les méthodes et les constantes respectent scrupuleusement les noms et le comportement utilisés par la bibliothèque ICU sous-jacente.

## Synopsis de la classe

class IntlChar {
/* Constantes */
public const string UNICODE_VERSION;
public const int CODEPOINT_MIN;
public const int CODEPOINT_MAX;
public const float NO_NUMERIC_VALUE;
public const int PROPERTY_ALPHABETIC;
public const int PROPERTY_BINARY_START;
public const int PROPERTY_ASCII_HEX_DIGIT;
public const int PROPERTY_BIDI_CONTROL;
public const int PROPERTY_BIDI_MIRRORED;
public const int PROPERTY_DASH;
public const int PROPERTY_DEFAULT_IGNORABLE_CODE_POINT;
public const int PROPERTY_DEPRECATED;
public const int PROPERTY_DIACRITIC;
public const int PROPERTY_EXTENDER;
public const int PROPERTY_FULL_COMPOSITION_EXCLUSION;
public const int PROPERTY_GRAPHEME_BASE;
public const int PROPERTY_GRAPHEME_EXTEND;
public const int PROPERTY_GRAPHEME_LINK;
public const int PROPERTY_HEX_DIGIT;
public const int PROPERTY_HYPHEN;
public const int PROPERTY_ID_CONTINUE;
public const int PROPERTY_ID_START;
public const int PROPERTY_IDEOGRAPHIC;
public const int PROPERTY_IDS_BINARY_OPERATOR;
public const int PROPERTY_IDS_TRINARY_OPERATOR;
public const int PROPERTY_IDS_UNARY_OPERATOR;
public const int PROPERTY_ID_COMPAT_MATH_START;
public const int PROPERTY_ID_COMPAT_MATH_CONTINUE;
public const int PROPERTY_JOIN_CONTROL;
public const int PROPERTY_LOGICAL_ORDER_EXCEPTION;
public const int PROPERTY_LOWERCASE;
public const int PROPERTY_MATH;
public const int PROPERTY_NONCHARACTER_CODE_POINT;
public const int PROPERTY_QUOTATION_MARK;
public const int PROPERTY_RADICAL;
public const int PROPERTY_SOFT_DOTTED;
public const int PROPERTY_TERMINAL_PUNCTUATION;
public const int PROPERTY_UNIFIED_IDEOGRAPH;
public const int PROPERTY_UPPERCASE;
public const int PROPERTY_WHITE_SPACE;
public const int PROPERTY_XID_CONTINUE;
public const int PROPERTY_XID_START;
public const int PROPERTY_CASE_SENSITIVE;
public const int PROPERTY_S_TERM;
public const int PROPERTY_VARIATION_SELECTOR;
public const int PROPERTY_NFD_INERT;
public const int PROPERTY_NFKD_INERT;
public const int PROPERTY_NFC_INERT;
public const int PROPERTY_NFKC_INERT;
public const int PROPERTY_SEGMENT_STARTER;
public const int PROPERTY_PATTERN_SYNTAX;
public const int PROPERTY_PATTERN_WHITE_SPACE;
public const int PROPERTY_POSIX_ALNUM;
public const int PROPERTY_POSIX_BLANK;
public const int PROPERTY_POSIX_GRAPH;
public const int PROPERTY_POSIX_PRINT;
public const int PROPERTY_POSIX_XDIGIT;
public const int PROPERTY_CASED;
public const int PROPERTY_CASE_IGNORABLE;
public const int PROPERTY_CHANGES_WHEN_LOWERCASED;
public const int PROPERTY_CHANGES_WHEN_UPPERCASED;
public const int PROPERTY_CHANGES_WHEN_TITLECASED;
public const int PROPERTY_CHANGES_WHEN_CASEFOLDED;
public const int PROPERTY_CHANGES_WHEN_CASEMAPPED;
public const int PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED;
public const int PROPERTY_BINARY_LIMIT;
public const int PROPERTY_BIDI_CLASS;
public const int PROPERTY_INT_START;
public const int PROPERTY_BLOCK;
public const int PROPERTY_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_DECOMPOSITION_TYPE;
public const int PROPERTY_EAST_ASIAN_WIDTH;
public const int PROPERTY_GENERAL_CATEGORY;
public const int PROPERTY_JOINING_GROUP;
public const int PROPERTY_JOINING_TYPE;
public const int PROPERTY_LINE_BREAK;
public const int PROPERTY_NUMERIC_TYPE;
public const int PROPERTY_SCRIPT;
public const int PROPERTY_HANGUL_SYLLABLE_TYPE;
public const int PROPERTY_NFD_QUICK_CHECK;
public const int PROPERTY_NFKD_QUICK_CHECK;
public const int PROPERTY_NFC_QUICK_CHECK;
public const int PROPERTY_NFKC_QUICK_CHECK;
public const int PROPERTY_LEAD_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_GRAPHEME_CLUSTER_BREAK;
public const int PROPERTY_SENTENCE_BREAK;
public const int PROPERTY_WORD_BREAK;
public const int PROPERTY_BIDI_PAIRED_BRACKET_TYPE;
public const int PROPERTY_INT_LIMIT;
public const int PROPERTY_GENERAL_CATEGORY_MASK;
public const int PROPERTY_MASK_START;
public const int PROPERTY_MASK_LIMIT;
public const int PROPERTY_NUMERIC_VALUE;
public const int PROPERTY_DOUBLE_START;
public const int PROPERTY_DOUBLE_LIMIT;
public const int PROPERTY_AGE;
public const int PROPERTY_STRING_START;
public const int PROPERTY_BIDI_MIRRORING_GLYPH;
public const int PROPERTY_CASE_FOLDING;
public const int PROPERTY_ISO_COMMENT;
public const int PROPERTY_LOWERCASE_MAPPING;
public const int PROPERTY_NAME;
public const int PROPERTY_SIMPLE_CASE_FOLDING;
public const int PROPERTY_SIMPLE_LOWERCASE_MAPPING;
public const int PROPERTY_SIMPLE_TITLECASE_MAPPING;
public const int PROPERTY_SIMPLE_UPPERCASE_MAPPING;
public const int PROPERTY_TITLECASE_MAPPING;
public const int PROPERTY_UNICODE_1_NAME;
public const int PROPERTY_UPPERCASE_MAPPING;
public const int PROPERTY_BIDI_PAIRED_BRACKET;
public const int PROPERTY_STRING_LIMIT;
public const int PROPERTY_SCRIPT_EXTENSIONS;
public const int PROPERTY_OTHER_PROPERTY_START;
public const int PROPERTY_OTHER_PROPERTY_LIMIT;
public const int PROPERTY_INVALID_CODE;
public const int CHAR_CATEGORY_UNASSIGNED;
public const int CHAR_CATEGORY_GENERAL_OTHER_TYPES;
public const int CHAR_CATEGORY_UPPERCASE_LETTER;
public const int CHAR_CATEGORY_LOWERCASE_LETTER;
public const int CHAR_CATEGORY_TITLECASE_LETTER;
public const int CHAR_CATEGORY_MODIFIER_LETTER;
public const int CHAR_CATEGORY_OTHER_LETTER;
public const int CHAR_CATEGORY_NON_SPACING_MARK;
public const int CHAR_CATEGORY_ENCLOSING_MARK;
public const int CHAR_CATEGORY_COMBINING_SPACING_MARK;
public const int CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER;
public const int CHAR_CATEGORY_LETTER_NUMBER;
public const int CHAR_CATEGORY_OTHER_NUMBER;
public const int CHAR_CATEGORY_SPACE_SEPARATOR;
public const int CHAR_CATEGORY_LINE_SEPARATOR;
public const int CHAR_CATEGORY_PARAGRAPH_SEPARATOR;
public const int CHAR_CATEGORY_CONTROL_CHAR;
public const int CHAR_CATEGORY_FORMAT_CHAR;
public const int CHAR_CATEGORY_PRIVATE_USE_CHAR;
public const int CHAR_CATEGORY_SURROGATE;
public const int CHAR_CATEGORY_DASH_PUNCTUATION;
public const int CHAR_CATEGORY_START_PUNCTUATION;
public const int CHAR_CATEGORY_END_PUNCTUATION;
public const int CHAR_CATEGORY_CONNECTOR_PUNCTUATION;
public const int CHAR_CATEGORY_OTHER_PUNCTUATION;
public const int CHAR_CATEGORY_MATH_SYMBOL;
public const int CHAR_CATEGORY_CURRENCY_SYMBOL;
public const int CHAR_CATEGORY_MODIFIER_SYMBOL;
public const int CHAR_CATEGORY_OTHER_SYMBOL;
public const int CHAR_CATEGORY_INITIAL_PUNCTUATION;
public const int CHAR_CATEGORY_FINAL_PUNCTUATION;
public const int CHAR_CATEGORY_CHAR_CATEGORY_COUNT;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR;
public const int CHAR_DIRECTION_ARABIC_NUMBER;
public const int CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_BLOCK_SEPARATOR;
public const int CHAR_DIRECTION_SEGMENT_SEPARATOR;
public const int CHAR_DIRECTION_WHITE_SPACE_NEUTRAL;
public const int CHAR_DIRECTION_OTHER_NEUTRAL;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT;
public const int CHAR_DIRECTION_DIR_NON_SPACING_MARK;
public const int CHAR_DIRECTION_BOUNDARY_NEUTRAL;
public const int CHAR_DIRECTION_FIRST_STRONG_ISOLATE;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE;
public const int CHAR_DIRECTION_CHAR_DIRECTION_COUNT;
public const int BLOCK_CODE_NO_BLOCK;
public const int BLOCK_CODE_BASIC_LATIN;
public const int BLOCK_CODE_LATIN_1_SUPPLEMENT;
public const int BLOCK_CODE_LATIN_EXTENDED_A;
public const int BLOCK_CODE_LATIN_EXTENDED_B;
public const int BLOCK_CODE_IPA_EXTENSIONS;
public const int BLOCK_CODE_SPACING_MODIFIER_LETTERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS;
public const int BLOCK_CODE_GREEK;
public const int BLOCK_CODE_CYRILLIC;
public const int BLOCK_CODE_ARMENIAN;
public const int BLOCK_CODE_HEBREW;
public const int BLOCK_CODE_ARABIC;
public const int BLOCK_CODE_SYRIAC;
public const int BLOCK_CODE_THAANA;
public const int BLOCK_CODE_DEVANAGARI;
public const int BLOCK_CODE_BENGALI;
public const int BLOCK_CODE_GURMUKHI;
public const int BLOCK_CODE_GUJARATI;
public const int BLOCK_CODE_ORIYA;
public const int BLOCK_CODE_TAMIL;
public const int BLOCK_CODE_TELUGU;
public const int BLOCK_CODE_KANNADA;
public const int BLOCK_CODE_MALAYALAM;
public const int BLOCK_CODE_SINHALA;
public const int BLOCK_CODE_THAI;
public const int BLOCK_CODE_LAO;
public const int BLOCK_CODE_TIBETAN;
public const int BLOCK_CODE_MYANMAR;
public const int BLOCK_CODE_GEORGIAN;
public const int BLOCK_CODE_HANGUL_JAMO;
public const int BLOCK_CODE_ETHIOPIC;
public const int BLOCK_CODE_CHEROKEE;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS;
public const int BLOCK_CODE_OGHAM;
public const int BLOCK_CODE_RUNIC;
public const int BLOCK_CODE_KHMER;
public const int BLOCK_CODE_MONGOLIAN;
public const int BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL;
public const int BLOCK_CODE_GREEK_EXTENDED;
public const int BLOCK_CODE_GENERAL_PUNCTUATION;
public const int BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS;
public const int BLOCK_CODE_CURRENCY_SYMBOLS;
public const int BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS;
public const int BLOCK_CODE_LETTERLIKE_SYMBOLS;
public const int BLOCK_CODE_NUMBER_FORMS;
public const int BLOCK_CODE_ARROWS;
public const int BLOCK_CODE_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_MISCELLANEOUS_TECHNICAL;
public const int BLOCK_CODE_CONTROL_PICTURES;
public const int BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERICS;
public const int BLOCK_CODE_BOX_DRAWING;
public const int BLOCK_CODE_BLOCK_ELEMENTS;
public const int BLOCK_CODE_GEOMETRIC_SHAPES;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS;
public const int BLOCK_CODE_DINGBATS;
public const int BLOCK_CODE_BRAILLE_PATTERNS;
public const int BLOCK_CODE_CJK_RADICALS_SUPPLEMENT;
public const int BLOCK_CODE_KANGXI_RADICALS;
public const int BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS;
public const int BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION;
public const int BLOCK_CODE_HIRAGANA;
public const int BLOCK_CODE_KATAKANA;
public const int BLOCK_CODE_BOPOMOFO;
public const int BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO;
public const int BLOCK_CODE_KANBUN;
public const int BLOCK_CODE_BOPOMOFO_EXTENDED;
public const int BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS;
public const int BLOCK_CODE_CJK_COMPATIBILITY;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS;
public const int BLOCK_CODE_YI_SYLLABLES;
public const int BLOCK_CODE_YI_RADICALS;
public const int BLOCK_CODE_HANGUL_SYLLABLES;
public const int BLOCK_CODE_HIGH_SURROGATES;
public const int BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES;
public const int BLOCK_CODE_LOW_SURROGATES;
public const int BLOCK_CODE_PRIVATE_USE_AREA;
public const int BLOCK_CODE_PRIVATE_USE;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS;
public const int BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A;
public const int BLOCK_CODE_COMBINING_HALF_MARKS;
public const int BLOCK_CODE_CJK_COMPATIBILITY_FORMS;
public const int BLOCK_CODE_SMALL_FORM_VARIANTS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B;
public const int BLOCK_CODE_SPECIALS;
public const int BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS;
public const int BLOCK_CODE_OLD_ITALIC;
public const int BLOCK_CODE_GOTHIC;
public const int BLOCK_CODE_DESERET;
public const int BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT;
public const int BLOCK_CODE_TAGS;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENT;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENTARY;
public const int BLOCK_CODE_TAGALOG;
public const int BLOCK_CODE_HANUNOO;
public const int BLOCK_CODE_BUHID;
public const int BLOCK_CODE_TAGBANWA;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_B;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B;
public const int BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_VARIATION_SELECTORS;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B;
public const int BLOCK_CODE_LIMBU;
public const int BLOCK_CODE_TAI_LE;
public const int BLOCK_CODE_KHMER_SYMBOLS;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS;
public const int BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS;
public const int BLOCK_CODE_LINEAR_B_SYLLABARY;
public const int BLOCK_CODE_LINEAR_B_IDEOGRAMS;
public const int BLOCK_CODE_AEGEAN_NUMBERS;
public const int BLOCK_CODE_UGARITIC;
public const int BLOCK_CODE_SHAVIAN;
public const int BLOCK_CODE_OSMANYA;
public const int BLOCK_CODE_CYPRIOT_SYLLABARY;
public const int BLOCK_CODE_TAI_XUAN_JING_SYMBOLS;
public const int BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT;
public const int BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION;
public const int BLOCK_CODE_ANCIENT_GREEK_NUMBERS;
public const int BLOCK_CODE_ARABIC_SUPPLEMENT;
public const int BLOCK_CODE_BUGINESE;
public const int BLOCK_CODE_CJK_STROKES;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT;
public const int BLOCK_CODE_COPTIC;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED;
public const int BLOCK_CODE_ETHIOPIC_SUPPLEMENT;
public const int BLOCK_CODE_GEORGIAN_SUPPLEMENT;
public const int BLOCK_CODE_GLAGOLITIC;
public const int BLOCK_CODE_KHAROSHTHI;
public const int BLOCK_CODE_MODIFIER_TONE_LETTERS;
public const int BLOCK_CODE_NEW_TAI_LUE;
public const int BLOCK_CODE_OLD_PERSIAN;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT;
public const int BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION;
public const int BLOCK_CODE_SYLOTI_NAGRI;
public const int BLOCK_CODE_TIFINAGH;
public const int BLOCK_CODE_VERTICAL_FORMS;
public const int BLOCK_CODE_NKO;
public const int BLOCK_CODE_BALINESE;
public const int BLOCK_CODE_LATIN_EXTENDED_C;
public const int BLOCK_CODE_LATIN_EXTENDED_D;
public const int BLOCK_CODE_PHAGS_PA;
public const int BLOCK_CODE_PHOENICIAN;
public const int BLOCK_CODE_CUNEIFORM;
public const int BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION;
public const int BLOCK_CODE_COUNTING_ROD_NUMERALS;
public const int BLOCK_CODE_SUNDANESE;
public const int BLOCK_CODE_LEPCHA;
public const int BLOCK_CODE_OL_CHIKI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_A;
public const int BLOCK_CODE_VAI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_B;
public const int BLOCK_CODE_SAURASHTRA;
public const int BLOCK_CODE_KAYAH_LI;
public const int BLOCK_CODE_REJANG;
public const int BLOCK_CODE_CHAM;
public const int BLOCK_CODE_ANCIENT_SYMBOLS;
public const int BLOCK_CODE_PHAISTOS_DISC;
public const int BLOCK_CODE_LYCIAN;
public const int BLOCK_CODE_CARIAN;
public const int BLOCK_CODE_LYDIAN;
public const int BLOCK_CODE_MAHJONG_TILES;
public const int BLOCK_CODE_DOMINO_TILES;
public const int BLOCK_CODE_SAMARITAN;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED;
public const int BLOCK_CODE_TAI_THAM;
public const int BLOCK_CODE_VEDIC_EXTENSIONS;
public const int BLOCK_CODE_LISU;
public const int BLOCK_CODE_BAMUM;
public const int BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS;
public const int BLOCK_CODE_DEVANAGARI_EXTENDED;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_A;
public const int BLOCK_CODE_JAVANESE;
public const int BLOCK_CODE_MYANMAR_EXTENDED_A;
public const int BLOCK_CODE_TAI_VIET;
public const int BLOCK_CODE_MEETEI_MAYEK;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_B;
public const int BLOCK_CODE_IMPERIAL_ARAMAIC;
public const int BLOCK_CODE_OLD_SOUTH_ARABIAN;
public const int BLOCK_CODE_AVESTAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PARTHIAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PAHLAVI;
public const int BLOCK_CODE_OLD_TURKIC;
public const int BLOCK_CODE_RUMI_NUMERAL_SYMBOLS;
public const int BLOCK_CODE_KAITHI;
public const int BLOCK_CODE_EGYPTIAN_HIEROGLYPHS;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT;
public const int BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C;
public const int BLOCK_CODE_MANDAIC;
public const int BLOCK_CODE_BATAK;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED_A;
public const int BLOCK_CODE_BRAHMI;
public const int BLOCK_CODE_BAMUM_SUPPLEMENT;
public const int BLOCK_CODE_KANA_SUPPLEMENT;
public const int BLOCK_CODE_PLAYING_CARDS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS;
public const int BLOCK_CODE_EMOTICONS;
public const int BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS;
public const int BLOCK_CODE_ALCHEMICAL_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D;
public const int BLOCK_CODE_ARABIC_EXTENDED_A;
public const int BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS;
public const int BLOCK_CODE_CHAKMA;
public const int BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS;
public const int BLOCK_CODE_MEROITIC_CURSIVE;
public const int BLOCK_CODE_MEROITIC_HIEROGLYPHS;
public const int BLOCK_CODE_MIAO;
public const int BLOCK_CODE_SHARADA;
public const int BLOCK_CODE_SORA_SOMPENG;
public const int BLOCK_CODE_SUNDANESE_SUPPLEMENT;
public const int BLOCK_CODE_TAKRI;
public const int BLOCK_CODE_BASSA_VAH;
public const int BLOCK_CODE_CAUCASIAN_ALBANIAN;
public const int BLOCK_CODE_COPTIC_EPACT_NUMBERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED;
public const int BLOCK_CODE_DUPLOYAN;
public const int BLOCK_CODE_ELBASAN;
public const int BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED;
public const int BLOCK_CODE_GRANTHA;
public const int BLOCK_CODE_KHOJKI;
public const int BLOCK_CODE_KHUDAWADI;
public const int BLOCK_CODE_LATIN_EXTENDED_E;
public const int BLOCK_CODE_LINEAR_A;
public const int BLOCK_CODE_MAHAJANI;
public const int BLOCK_CODE_MANICHAEAN;
public const int BLOCK_CODE_MENDE_KIKAKUI;
public const int BLOCK_CODE_MODI;
public const int BLOCK_CODE_MRO;
public const int BLOCK_CODE_MYANMAR_EXTENDED_B;
public const int BLOCK_CODE_NABATAEAN;
public const int BLOCK_CODE_OLD_NORTH_ARABIAN;
public const int BLOCK_CODE_OLD_PERMIC;
public const int BLOCK_CODE_ORNAMENTAL_DINGBATS;
public const int BLOCK_CODE_PAHAWH_HMONG;
public const int BLOCK_CODE_PALMYRENE;
public const int BLOCK_CODE_PAU_CIN_HAU;
public const int BLOCK_CODE_PSALTER_PAHLAVI;
public const int BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS;
public const int BLOCK_CODE_SIDDHAM;
public const int BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_C;
public const int BLOCK_CODE_TIRHUTA;
public const int BLOCK_CODE_WARANG_CITI;
public const int BLOCK_CODE_COUNT;
public const int BLOCK_CODE_INVALID_CODE;
public const int BPT_NONE;
public const int BPT_OPEN;
public const int BPT_CLOSE;
public const int BPT_COUNT;
public const int EA_NEUTRAL;
public const int EA_AMBIGUOUS;
public const int EA_HALFWIDTH;
public const int EA_FULLWIDTH;
public const int EA_NARROW;
public const int EA_WIDE;
public const int EA_COUNT;
public const int UNICODE_CHAR_NAME;
public const int UNICODE_10_CHAR_NAME;
public const int EXTENDED_CHAR_NAME;
public const int CHAR_NAME_ALIAS;
public const int CHAR_NAME_CHOICE_COUNT;
public const int SHORT_PROPERTY_NAME;
public const int LONG_PROPERTY_NAME;
public const int PROPERTY_NAME_CHOICE_COUNT;
public const int DT_NONE;
public const int DT_CANONICAL;
public const int DT_COMPAT;
public const int DT_CIRCLE;
public const int DT_FINAL;
public const int DT_FONT;
public const int DT_FRACTION;
public const int DT_INITIAL;
public const int DT_ISOLATED;
public const int DT_MEDIAL;
public const int DT_NARROW;
public const int DT_NOBREAK;
public const int DT_SMALL;
public const int DT_SQUARE;
public const int DT_SUB;
public const int DT_SUPER;
public const int DT_VERTICAL;
public const int DT_WIDE;
public const int DT_COUNT;
public const int JT_NON_JOINING;
public const int JT_JOIN_CAUSING;
public const int JT_DUAL_JOINING;
public const int JT_LEFT_JOINING;
public const int JT_RIGHT_JOINING;
public const int JT_TRANSPARENT;
public const int JT_COUNT;
public const int JG_NO_JOINING_GROUP;
public const int JG_AIN;
public const int JG_ALAPH;
public const int JG_ALEF;
public const int JG_BEH;
public const int JG_BETH;
public const int JG_DAL;
public const int JG_DALATH_RISH;
public const int JG_E;
public const int JG_FEH;
public const int JG_FINAL_SEMKATH;
public const int JG_GAF;
public const int JG_GAMAL;
public const int JG_HAH;
public const int JG_TEH_MARBUTA_GOAL;
public const int JG_HAMZA_ON_HEH_GOAL;
public const int JG_HE;
public const int JG_HEH;
public const int JG_HEH_GOAL;
public const int JG_HETH;
public const int JG_KAF;
public const int JG_KAPH;
public const int JG_KNOTTED_HEH;
public const int JG_LAM;
public const int JG_LAMADH;
public const int JG_MEEM;
public const int JG_MIM;
public const int JG_NOON;
public const int JG_NUN;
public const int JG_PE;
public const int JG_QAF;
public const int JG_QAPH;
public const int JG_REH;
public const int JG_REVERSED_PE;
public const int JG_SAD;
public const int JG_SADHE;
public const int JG_SEEN;
public const int JG_SEMKATH;
public const int JG_SHIN;
public const int JG_SWASH_KAF;
public const int JG_SYRIAC_WAW;
public const int JG_TAH;
public const int JG_TAW;
public const int JG_TEH_MARBUTA;
public const int JG_TETH;
public const int JG_WAW;
public const int JG_YEH;
public const int JG_YEH_BARREE;
public const int JG_YEH_WITH_TAIL;
public const int JG_YUDH;
public const int JG_YUDH_HE;
public const int JG_ZAIN;
public const int JG_FE;
public const int JG_KHAPH;
public const int JG_ZHAIN;
public const int JG_BURUSHASKI_YEH_BARREE;
public const int JG_FARSI_YEH;
public const int JG_NYA;
public const int JG_ROHINGYA_YEH;
public const int JG_MANICHAEAN_ALEPH;
public const int JG_MANICHAEAN_AYIN;
public const int JG_MANICHAEAN_BETH;
public const int JG_MANICHAEAN_DALETH;
public const int JG_MANICHAEAN_DHAMEDH;
public const int JG_MANICHAEAN_FIVE;
public const int JG_MANICHAEAN_GIMEL;
public const int JG_MANICHAEAN_HETH;
public const int JG_MANICHAEAN_HUNDRED;
public const int JG_MANICHAEAN_KAPH;
public const int JG_MANICHAEAN_LAMEDH;
public const int JG_MANICHAEAN_MEM;
public const int JG_MANICHAEAN_NUN;
public const int JG_MANICHAEAN_ONE;
public const int JG_MANICHAEAN_PE;
public const int JG_MANICHAEAN_QOPH;
public const int JG_MANICHAEAN_RESH;
public const int JG_MANICHAEAN_SADHE;
public const int JG_MANICHAEAN_SAMEKH;
public const int JG_MANICHAEAN_TAW;
public const int JG_MANICHAEAN_TEN;
public const int JG_MANICHAEAN_TETH;
public const int JG_MANICHAEAN_THAMEDH;
public const int JG_MANICHAEAN_TWENTY;
public const int JG_MANICHAEAN_WAW;
public const int JG_MANICHAEAN_YODH;
public const int JG_MANICHAEAN_ZAYIN;
public const int JG_STRAIGHT_WAW;
public const int JG_COUNT;
public const int GCB_OTHER;
public const int GCB_CONTROL;
public const int GCB_CR;
public const int GCB_EXTEND;
public const int GCB_L;
public const int GCB_LF;
public const int GCB_LV;
public const int GCB_LVT;
public const int GCB_T;
public const int GCB_V;
public const int GCB_SPACING_MARK;
public const int GCB_PREPEND;
public const int GCB_REGIONAL_INDICATOR;
public const int GCB_COUNT;
public const int WB_OTHER;
public const int WB_ALETTER;
public const int WB_FORMAT;
public const int WB_KATAKANA;
public const int WB_MIDLETTER;
public const int WB_MIDNUM;
public const int WB_NUMERIC;
public const int WB_EXTENDNUMLET;
public const int WB_CR;
public const int WB_EXTEND;
public const int WB_LF;
public const int WB_MIDNUMLET;
public const int WB_NEWLINE;
public const int WB_REGIONAL_INDICATOR;
public const int WB_HEBREW_LETTER;
public const int WB_SINGLE_QUOTE;
public const int WB_DOUBLE_QUOTE;
public const int WB_COUNT;
public const int SB_OTHER;
public const int SB_ATERM;
public const int SB_CLOSE;
public const int SB_FORMAT;
public const int SB_LOWER;
public const int SB_NUMERIC;
public const int SB_OLETTER;
public const int SB_SEP;
public const int SB_SP;
public const int SB_STERM;
public const int SB_UPPER;
public const int SB_CR;
public const int SB_EXTEND;
public const int SB_LF;
public const int SB_SCONTINUE;
public const int SB_COUNT;
public const int LB_UNKNOWN;
public const int LB_AMBIGUOUS;
public const int LB_ALPHABETIC;
public const int LB_BREAK_BOTH;
public const int LB_BREAK_AFTER;
public const int LB_BREAK_BEFORE;
public const int LB_MANDATORY_BREAK;
public const int LB_CONTINGENT_BREAK;
public const int LB_CLOSE_PUNCTUATION;
public const int LB_COMBINING_MARK;
public const int LB_CARRIAGE_RETURN;
public const int LB_EXCLAMATION;
public const int LB_GLUE;
public const int LB_HYPHEN;
public const int LB_IDEOGRAPHIC;
public const int LB_INSEPARABLE;
public const int LB_INSEPERABLE;
public const int LB_INFIX_NUMERIC;
public const int LB_LINE_FEED;
public const int LB_NONSTARTER;
public const int LB_NUMERIC;
public const int LB_OPEN_PUNCTUATION;
public const int LB_POSTFIX_NUMERIC;
public const int LB_PREFIX_NUMERIC;
public const int LB_QUOTATION;
public const int LB_COMPLEX_CONTEXT;
public const int LB_SURROGATE;
public const int LB_SPACE;
public const int LB_BREAK_SYMBOLS;
public const int LB_ZWSPACE;
public const int LB_NEXT_LINE;
public const int LB_WORD_JOINER;
public const int LB_H2;
public const int LB_H3;
public const int LB_JL;
public const int LB_JT;
public const int LB_JV;
public const int LB_CLOSE_PARENTHESIS;
public const int LB_CONDITIONAL_JAPANESE_STARTER;
public const int LB_HEBREW_LETTER;
public const int LB_REGIONAL_INDICATOR;
public const int LB_COUNT;
public const int NT_NONE;
public const int NT_DECIMAL;
public const int NT_DIGIT;
public const int NT_NUMERIC;
public const int NT_COUNT;
public const int HST_NOT_APPLICABLE;
public const int HST_LEADING_JAMO;
public const int HST_VOWEL_JAMO;
public const int HST_TRAILING_JAMO;
public const int HST_LV_SYLLABLE;
public const int HST_LVT_SYLLABLE;
public const int HST_COUNT;
public const int FOLD_CASE_DEFAULT;
public const int FOLD_CASE_EXCLUDE_SPECIAL_I;
/* Méthodes */
public static function charAge(int|string `$codepoint`): ?array
public static function charDigitValue(int|string `$codepoint`): ?int
public static function charDirection(int|string `$codepoint`): ?int
public static function charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int
public static function charMirror(int|string `$codepoint`): int|string|null
public static function charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string
public static function charType(int|string `$codepoint`): ?int
public static function chr(int|string `$codepoint`): ?string
public static function digit(int|string `$codepoint`, int `$base` = 10): int|false|null
public static function enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool
public static function enumCharTypes(callable `$callback`): void
public static function foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null
public static function forDigit(int `$digit`, int `$base` = 10): int
public static function getBidiPairedBracket(int|string `$codepoint`): int|string|null
public static function getBlockCode(int|string `$codepoint`): ?int
public static function getCombiningClass(int|string `$codepoint`): ?int
public static function getFC_NFKC_Closure(int|string `$codepoint`): string|false|null
public static function getIntPropertyMaxValue(int `$property`): int
public static function getIntPropertyMinValue(int `$property`): int
public static function getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int
public static function getNumericValue(int|string `$codepoint`): ?float
public static function getPropertyEnum(string `$alias`): int
public static function getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getPropertyValueEnum(int `$property`, string `$name`): int
public static function getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getUnicodeVersion(): array
public static function hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool
public static function isalnum(int|string `$codepoint`): ?bool
public static function isalpha(int|string `$codepoint`): ?bool
public static function isbase(int|string `$codepoint`): ?bool
public static function isblank(int|string `$codepoint`): ?bool
public static function iscntrl(int|string `$codepoint`): ?bool
public static function isdefined(int|string `$codepoint`): ?bool
public static function isdigit(int|string `$codepoint`): ?bool
public static function isgraph(int|string `$codepoint`): ?bool
public static function isIDIgnorable(int|string `$codepoint`): ?bool
public static function isIDPart(int|string `$codepoint`): ?bool
public static function isIDStart(int|string `$codepoint`): ?bool
public static function isISOControl(int|string `$codepoint`): ?bool
public static function isJavaIDPart(int|string `$codepoint`): ?bool
public static function isJavaIDStart(int|string `$codepoint`): ?bool
public static function isJavaSpaceChar(int|string `$codepoint`): ?bool
public static function islower(int|string `$codepoint`): ?bool
public static function isMirrored(int|string `$codepoint`): ?bool
public static function isprint(int|string `$codepoint`): ?bool
public static function ispunct(int|string `$codepoint`): ?bool
public static function isspace(int|string `$codepoint`): ?bool
public static function istitle(int|string `$codepoint`): ?bool
public static function isUAlphabetic(int|string `$codepoint`): ?bool
public static function isULowercase(int|string `$codepoint`): ?bool
public static function isupper(int|string `$codepoint`): ?bool
public static function isUUppercase(int|string `$codepoint`): ?bool
public static function isUWhiteSpace(int|string `$codepoint`): ?bool
public static function isWhitespace(int|string `$codepoint`): ?bool
public static function isxdigit(int|string `$codepoint`): ?bool
public static function ord(int|string `$character`): ?int
public static function tolower(int|string `$codepoint`): int|string|null
public static function totitle(int|string `$codepoint`): int|string|null
public static function toupper(int|string `$codepoint`): int|string|null
}

## Constantes pré-définies

`IntlChar::UNICODE_VERSION` string

`IntlChar::CODEPOINT_MIN` int

`IntlChar::CODEPOINT_MAX` int

`IntlChar::NO_NUMERIC_VALUE` int

  Valeur spéciale qui est retournée par IntlChar::getNumericValue() lorsqu'aucune valeur numérique n'est définie pour un point de code.

`IntlChar::PROPERTY_ALPHABETIC` int

`IntlChar::PROPERTY_BINARY_START` int

`IntlChar::PROPERTY_ASCII_HEX_DIGIT` int

`IntlChar::PROPERTY_BIDI_CONTROL` int

`IntlChar::PROPERTY_BIDI_MIRRORED` int

`IntlChar::PROPERTY_DASH` int

`IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT` int

`IntlChar::PROPERTY_DEPRECATED` int

`IntlChar::PROPERTY_DIACRITIC` int

`IntlChar::PROPERTY_EXTENDER` int

`IntlChar::PROPERTY_FULL_COMPOSITION_EXCLUSION` int

`IntlChar::PROPERTY_GRAPHEME_BASE` int

`IntlChar::PROPERTY_GRAPHEME_EXTEND` int

`IntlChar::PROPERTY_GRAPHEME_LINK` int

`IntlChar::PROPERTY_HEX_DIGIT` int

`IntlChar::PROPERTY_HYPHEN` int

`IntlChar::PROPERTY_ID_CONTINUE` int

`IntlChar::PROPERTY_ID_START` int

`IntlChar::PROPERTY_IDEOGRAPHIC` int

`IntlChar::PROPERTY_IDS_BINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_TRINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_UNARY_OPERATOR` int
  Pour la détermination programmatique des séquences de description idéographique. Disponible à partir de PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_START` int
  Utilisé dans le profil d'identifiant mathématique de l'UAX 31. Disponible à partir de PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE` int
  Utilisé dans le profil d'identifiant mathématique de l'UAX 31. Disponible à partir de PHP 8.4.0.
`IntlChar::PROPERTY_JOIN_CONTROL` int

`IntlChar::PROPERTY_LOGICAL_ORDER_EXCEPTION` int

`IntlChar::PROPERTY_LOWERCASE` int

`IntlChar::PROPERTY_MATH` int

`IntlChar::PROPERTY_NONCHARACTER_CODE_POINT` int

`IntlChar::PROPERTY_QUOTATION_MARK` int

`IntlChar::PROPERTY_RADICAL` int

`IntlChar::PROPERTY_SOFT_DOTTED` int

`IntlChar::PROPERTY_TERMINAL_PUNCTUATION` int

`IntlChar::PROPERTY_UNIFIED_IDEOGRAPH` int

`IntlChar::PROPERTY_UPPERCASE` int

`IntlChar::PROPERTY_WHITE_SPACE` int

`IntlChar::PROPERTY_XID_CONTINUE` int

`IntlChar::PROPERTY_XID_START` int

`IntlChar::PROPERTY_CASE_SENSITIVE` int

`IntlChar::PROPERTY_S_TERM` int

`IntlChar::PROPERTY_VARIATION_SELECTOR` int

`IntlChar::PROPERTY_NFD_INERT` int

`IntlChar::PROPERTY_NFKD_INERT` int

`IntlChar::PROPERTY_NFC_INERT` int

`IntlChar::PROPERTY_NFKC_INERT` int

`IntlChar::PROPERTY_SEGMENT_STARTER` int

`IntlChar::PROPERTY_PATTERN_SYNTAX` int

`IntlChar::PROPERTY_PATTERN_WHITE_SPACE` int

`IntlChar::PROPERTY_POSIX_ALNUM` int

`IntlChar::PROPERTY_POSIX_BLANK` int

`IntlChar::PROPERTY_POSIX_GRAPH` int

`IntlChar::PROPERTY_POSIX_PRINT` int

`IntlChar::PROPERTY_POSIX_XDIGIT` int

`IntlChar::PROPERTY_CASED` int

`IntlChar::PROPERTY_CASE_IGNORABLE` int

`IntlChar::PROPERTY_CHANGES_WHEN_LOWERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_UPPERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_TITLECASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEFOLDED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEMAPPED` int

`IntlChar::PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED` int

`IntlChar::PROPERTY_BINARY_LIMIT` int

`IntlChar::PROPERTY_BIDI_CLASS` int

`IntlChar::PROPERTY_INT_START` int

`IntlChar::PROPERTY_BLOCK` int

`IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_DECOMPOSITION_TYPE` int

`IntlChar::PROPERTY_EAST_ASIAN_WIDTH` int

`IntlChar::PROPERTY_GENERAL_CATEGORY` int

`IntlChar::PROPERTY_JOINING_GROUP` int

`IntlChar::PROPERTY_JOINING_TYPE` int

`IntlChar::PROPERTY_LINE_BREAK` int

`IntlChar::PROPERTY_NUMERIC_TYPE` int

`IntlChar::PROPERTY_SCRIPT` int

`IntlChar::PROPERTY_HANGUL_SYLLABLE_TYPE` int

`IntlChar::PROPERTY_NFD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFC_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKC_QUICK_CHECK` int

`IntlChar::PROPERTY_LEAD_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_GRAPHEME_CLUSTER_BREAK` int

`IntlChar::PROPERTY_SENTENCE_BREAK` int

`IntlChar::PROPERTY_WORD_BREAK` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE` int

`IntlChar::PROPERTY_INT_LIMIT` int

`IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` int

`IntlChar::PROPERTY_MASK_START` int

`IntlChar::PROPERTY_MASK_LIMIT` int

`IntlChar::PROPERTY_NUMERIC_VALUE` int

`IntlChar::PROPERTY_DOUBLE_START` int

`IntlChar::PROPERTY_DOUBLE_LIMIT` int

`IntlChar::PROPERTY_AGE` int

`IntlChar::PROPERTY_STRING_START` int

`IntlChar::PROPERTY_BIDI_MIRRORING_GLYPH` int

`IntlChar::PROPERTY_CASE_FOLDING` int

`IntlChar::PROPERTY_ISO_COMMENT` int

`IntlChar::PROPERTY_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_NAME` int

`IntlChar::PROPERTY_SIMPLE_CASE_FOLDING` int

`IntlChar::PROPERTY_SIMPLE_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_UNICODE_1_NAME` int

`IntlChar::PROPERTY_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET` int

`IntlChar::PROPERTY_STRING_LIMIT` int

`IntlChar::PROPERTY_SCRIPT_EXTENSIONS` int

`IntlChar::PROPERTY_OTHER_PROPERTY_START` int

`IntlChar::PROPERTY_OTHER_PROPERTY_LIMIT` int

`IntlChar::PROPERTY_INVALID_CODE` int

`IntlChar::CHAR_CATEGORY_UNASSIGNED` int

`IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES` int

`IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_TITLECASE_LETTER` int

`IntlChar::CHAR_CATEGORY_MODIFIER_LETTER` int

`IntlChar::CHAR_CATEGORY_OTHER_LETTER` int

`IntlChar::CHAR_CATEGORY_NON_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_ENCLOSING_MARK` int

`IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER` int

`IntlChar::CHAR_CATEGORY_LETTER_NUMBER` int

`IntlChar::CHAR_CATEGORY_OTHER_NUMBER` int

`IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_CONTROL_CHAR` int

`IntlChar::CHAR_CATEGORY_FORMAT_CHAR` int

`IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR` int

`IntlChar::CHAR_CATEGORY_SURROGATE` int

`IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_START_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_END_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_MATH_SYMBOL` int

`IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL` int

`IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_OTHER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR` int

`IntlChar::CHAR_DIRECTION_ARABIC_NUMBER` int

`IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT` int

`IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK` int

`IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE` int

`IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT` int

`IntlChar::BLOCK_CODE_NO_BLOCK` int

`IntlChar::BLOCK_CODE_BASIC_LATIN` int

`IntlChar::BLOCK_CODE_LATIN_1_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_A` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IPA_EXTENSIONS` int

`IntlChar::BLOCK_CODE_SPACING_MODIFIER_LETTERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS` int

`IntlChar::BLOCK_CODE_GREEK` int

`IntlChar::BLOCK_CODE_CYRILLIC` int

`IntlChar::BLOCK_CODE_ARMENIAN` int

`IntlChar::BLOCK_CODE_HEBREW` int

`IntlChar::BLOCK_CODE_ARABIC` int

`IntlChar::BLOCK_CODE_SYRIAC` int

`IntlChar::BLOCK_CODE_THAANA` int

`IntlChar::BLOCK_CODE_DEVANAGARI` int

`IntlChar::BLOCK_CODE_BENGALI` int

`IntlChar::BLOCK_CODE_GURMUKHI` int

`IntlChar::BLOCK_CODE_GUJARATI` int

`IntlChar::BLOCK_CODE_ORIYA` int

`IntlChar::BLOCK_CODE_TAMIL` int

`IntlChar::BLOCK_CODE_TELUGU` int

`IntlChar::BLOCK_CODE_KANNADA` int

`IntlChar::BLOCK_CODE_MALAYALAM` int

`IntlChar::BLOCK_CODE_SINHALA` int

`IntlChar::BLOCK_CODE_THAI` int

`IntlChar::BLOCK_CODE_LAO` int

`IntlChar::BLOCK_CODE_TIBETAN` int

`IntlChar::BLOCK_CODE_MYANMAR` int

`IntlChar::BLOCK_CODE_GEORGIAN` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO` int

`IntlChar::BLOCK_CODE_ETHIOPIC` int

`IntlChar::BLOCK_CODE_CHEROKEE` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS` int

`IntlChar::BLOCK_CODE_OGHAM` int

`IntlChar::BLOCK_CODE_RUNIC` int

`IntlChar::BLOCK_CODE_KHMER` int

`IntlChar::BLOCK_CODE_MONGOLIAN` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL` int

`IntlChar::BLOCK_CODE_GREEK_EXTENDED` int

`IntlChar::BLOCK_CODE_GENERAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS` int

`IntlChar::BLOCK_CODE_CURRENCY_SYMBOLS` int

`IntlChar::BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS` int

`IntlChar::BLOCK_CODE_LETTERLIKE_SYMBOLS` int

`IntlChar::BLOCK_CODE_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_ARROWS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_TECHNICAL` int

`IntlChar::BLOCK_CODE_CONTROL_PICTURES` int

`IntlChar::BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERICS` int

`IntlChar::BLOCK_CODE_BOX_DRAWING` int

`IntlChar::BLOCK_CODE_BLOCK_ELEMENTS` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS` int

`IntlChar::BLOCK_CODE_DINGBATS` int

`IntlChar::BLOCK_CODE_BRAILLE_PATTERNS` int

`IntlChar::BLOCK_CODE_CJK_RADICALS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANGXI_RADICALS` int

`IntlChar::BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS` int

`IntlChar::BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_HIRAGANA` int

`IntlChar::BLOCK_CODE_KATAKANA` int

`IntlChar::BLOCK_CODE_BOPOMOFO` int

`IntlChar::BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO` int

`IntlChar::BLOCK_CODE_KANBUN` int

`IntlChar::BLOCK_CODE_BOPOMOFO_EXTENDED` int

`IntlChar::BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_YI_SYLLABLES` int

`IntlChar::BLOCK_CODE_YI_RADICALS` int

`IntlChar::BLOCK_CODE_HANGUL_SYLLABLES` int

`IntlChar::BLOCK_CODE_HIGH_SURROGATES` int

`IntlChar::BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES` int

`IntlChar::BLOCK_CODE_LOW_SURROGATES` int

`IntlChar::BLOCK_CODE_PRIVATE_USE_AREA` int

`IntlChar::BLOCK_CODE_PRIVATE_USE` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A` int

`IntlChar::BLOCK_CODE_COMBINING_HALF_MARKS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_FORMS` int

`IntlChar::BLOCK_CODE_SMALL_FORM_VARIANTS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B` int

  Bloc des formes de présentation arabes B, incluant des ligatures supplémentaires et des formes contextuelles.

`IntlChar::BLOCK_CODE_SPECIALS` int

  Bloc réservé pour des caractères spéciaux et non standardisés.

`IntlChar::BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS` int

  Bloc des formes demi-largeur et pleine largeur utilisées principalement dans les écritures asiatiques.

`IntlChar::BLOCK_CODE_OLD_ITALIC` int

  Bloc des caractères de l'ancien alphabet italien utilisé dans les inscriptions italiennes antiques.

`IntlChar::BLOCK_CODE_GOTHIC` int

  Bloc des caractères gothiques utilisés dans certaines écritures historiques.

`IntlChar::BLOCK_CODE_DESERET` int

  Bloc des caractères Deseret utilisés dans l'alphabet Deseret créé par l'Église de Jésus-Christ des Saints des Derniers Jours.

`IntlChar::BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS` int

  Bloc des symboles musicaux byzantins utilisés dans la notation musicale historique.

`IntlChar::BLOCK_CODE_MUSICAL_SYMBOLS` int

  Bloc des symboles musicaux utilisés dans la notation musicale moderne.

`IntlChar::BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS` int

  Bloc des symboles alphanumériques mathématiques utilisés dans les expressions et notations mathématiques.

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B` int

  Bloc des idéogrammes unifiés CJK, extension B, ajoutant un grand nombre de caractères supplémentaires.

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT` int

  Bloc des idéogrammes de compatibilité CJK supplémentaire pour des caractères supplémentaires.

`IntlChar::BLOCK_CODE_TAGS` int

  Bloc des caractères de balisage utilisés pour les annotations textuelles.

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENT` int

  Bloc des caractères supplémentaires cyrilliques ajoutant des lettres utilisées dans d'autres langues slaves.

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENTARY` int

  Bloc des caractères cyrilliques supplémentaires utilisés pour des besoins linguistiques spécifiques.

`IntlChar::BLOCK_CODE_TAGALOG` int

  Bloc des caractères Tagalog utilisés dans l'écriture Tagalog.

`IntlChar::BLOCK_CODE_HANUNOO` int

  Bloc des caractères Hanunoo utilisés dans l'écriture Hanunoo.

`IntlChar::BLOCK_CODE_BUHID` int

  Bloc des caractères Buhid utilisés dans l'écriture Buhid.

`IntlChar::BLOCK_CODE_TAGBANWA` int

  Bloc des caractères Tagbanwa utilisés dans l'écriture Tagbanwa.

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A` int

  Bloc des symboles mathématiques divers A utilisés dans divers contextes mathématiques.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_A` int

  Bloc des flèches supplémentaires A offrant des variantes supplémentaires de flèches.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_B` int

  Bloc des flèches supplémentaires B fournissant encore plus de variantes de flèches.

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B` int

  Bloc des symboles mathématiques divers B utilisés dans des domaines spécialisés des mathématiques.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS` int

  Bloc des opérateurs mathématiques supplémentaires pour des opérations avancées.

`IntlChar::BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS` int

  Bloc des extensions phonétiques Katakana pour représenter des sons supplémentaires.

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS` int

  Bloc des sélecteurs de variation utilisés pour spécifier des variantes de présentation des caractères.

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A` int

  Bloc supplémentaire d'utilisation privée A pour des caractères définis par l'utilisateur.

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B` int

  Bloc supplémentaire d'utilisation privée B pour des caractères définis par l'utilisateur.

`IntlChar::BLOCK_CODE_LIMBU` int

  Bloc des caractères Limbu utilisés dans l'écriture Limbu.

`IntlChar::BLOCK_CODE_TAI_LE` int

  Bloc des caractères Tai Le utilisés dans l'écriture Tai Le.

`IntlChar::BLOCK_CODE_KHMER_SYMBOLS` int

  Bloc des symboles Khmers utilisés dans l'écriture khmère.

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS` int

  Bloc des extensions phonétiques ajoutant des caractères pour représenter des sons spécifiques.

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS` int

  Bloc des symboles divers et des flèches utilisées dans divers contextes.

`IntlChar::BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS` int

  Bloc des symboles des hexagrammes du Yi Jing utilisés dans les textes traditionnels chinois.

`IntlChar::BLOCK_CODE_LINEAR_B_SYLLABARY` int

  Bloc des syllabaires Linear B utilisés dans l'écriture minoenne.

`IntlChar::BLOCK_CODE_LINEAR_B_IDEOGRAMS` int

  Bloc des idéogrammes Linear B utilisés dans l'écriture minoenne.

`IntlChar::BLOCK_CODE_AEGEAN_NUMBERS` int

`IntlChar::BLOCK_CODE_UGARITIC` int

`IntlChar::BLOCK_CODE_SHAVIAN` int

`IntlChar::BLOCK_CODE_OSMANYA` int

`IntlChar::BLOCK_CODE_CYPRIOT_SYLLABARY` int

  Bloc des syllabaires cypriotes utilisés dans l'écriture chypriote ancienne.

`IntlChar::BLOCK_CODE_TAI_XUAN_JING_SYMBOLS` int

  Bloc des symboles Tai Xuan Jing utilisés dans le manuscrit classique chinois Tai Xuan Jing.

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT` int

  Bloc des sélecteurs de variation supplémentaires utilisés pour spécifier des variantes de présentation des caractères.

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION` int

  Bloc des notations musicales grecques anciennes utilisées dans les notations musicales de la Grèce antique.

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_NUMBERS` int

  Bloc des nombres grecs anciens utilisés dans les inscriptions et documents historiques grecs.

`IntlChar::BLOCK_CODE_ARABIC_SUPPLEMENT` int

  Bloc de suppléments arabes ajoutant des caractères supplémentaires pour les écritures arabes étendues.

`IntlChar::BLOCK_CODE_BUGINESE` int

  Bloc des caractères Buginese utilisés dans l'écriture Buginese de l'île de Sulawesi en Indonésie.

`IntlChar::BLOCK_CODE_CJK_STROKES` int

  Bloc des traits CJK utilisés pour la composition et la décomposition des idéogrammes chinois, japonais et coréens.

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT` int

  Bloc des marques diacritiques combinantes supplémentaires utilisées pour modifier les caractères de base.

`IntlChar::BLOCK_CODE_COPTIC` int

  Bloc des caractères coptes utilisés dans l'écriture copte de l'Égypte.

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED` int

  Bloc étendu des caractères éthiopiens ajoutant des lettres supplémentaires pour des langues éthiopiennes spécifiques.

`IntlChar::BLOCK_CODE_ETHIOPIC_SUPPLEMENT` int

  Bloc des suppléments éthiopiens ajoutant des caractères supplémentaires pour des besoins linguistiques spécifiques.

`IntlChar::BLOCK_CODE_GEORGIAN_SUPPLEMENT` int

  Bloc des suppléments géorgiens ajoutant des caractères supplémentaires pour l'écriture géorgienne.

`IntlChar::BLOCK_CODE_GLAGOLITIC` int

  Bloc des caractères glagolitiques utilisés dans l'alphabet glagolitique, l'un des premiers alphabets slaves.

`IntlChar::BLOCK_CODE_KHAROSHTHI` int

  Bloc des caractères Kharoshthi utilisés dans l'écriture ancienne de l'Inde du Nord-Ouest.

`IntlChar::BLOCK_CODE_MODIFIER_TONE_LETTERS` int

  Bloc des lettres modificateurs de ton utilisées dans certaines langues pour indiquer des variations tonales.

`IntlChar::BLOCK_CODE_NEW_TAI_LUE` int

  Bloc des caractères New Tai Lue utilisés dans l'écriture Tai Lue pour certaines langues de l'Asie du Sud-Est.

`IntlChar::BLOCK_CODE_OLD_PERSIAN` int

  Bloc des caractères perses anciens utilisés dans l'écriture de l'Empire perse ancien.

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT` int

  Bloc des extensions phonétiques supplémentaires ajoutant des caractères pour représenter des sons spécifiques.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION` int

  Bloc des ponctuations supplémentaires utilisées pour divers besoins typographiques.

`IntlChar::BLOCK_CODE_SYLOTI_NAGRI` int

  Bloc des caractères Syloti Nagri utilisés dans l'écriture Syloti Nagri pour certaines langues de l'Inde.

`IntlChar::BLOCK_CODE_TIFINAGH` int

  Bloc des caractères Tifinagh utilisés dans l'écriture des langues berbères.

`IntlChar::BLOCK_CODE_VERTICAL_FORMS` int

  Bloc des formes verticales utilisées dans certaines écritures pour la présentation verticale des caractères.

`IntlChar::BLOCK_CODE_NKO` int

  Bloc des caractères Nko utilisés dans l'écriture Nko pour certaines langues de l'Afrique de l'Ouest.

`IntlChar::BLOCK_CODE_BALINESE` int

  Bloc des caractères balinais utilisés dans l'écriture balinaise de l'Indonésie.

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_C` int

  Bloc des extensions Latin supplémentaires C ajoutant des caractères additionnels pour l'écriture des langues utilisant l'alphabet latin.

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_D` int

  Bloc des extensions Latin supplémentaires D ajoutant des caractères additionnels pour l'écriture des langues utilisant l'alphabet latin.

`IntlChar::BLOCK_CODE_PHAGS_PA` int

  Bloc des caractères Phags-pa utilisés dans l'écriture Phags-pa, un script historique de l'Empire mongol.

`IntlChar::BLOCK_CODE_PHOENICIAN` int

  Bloc des caractères phéniciens utilisés dans l'écriture phénicienne de l'Antiquité.

`IntlChar::BLOCK_CODE_CUNEIFORM` int

  Bloc des caractères cunéiformes utilisés dans l'écriture cunéiforme de la Mésopotamie ancienne.

`IntlChar::BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION` int

  Bloc des nombres et ponctuations cunéiformes utilisés dans l'écriture cunéiforme.

`IntlChar::BLOCK_CODE_COUNTING_ROD_NUMERALS` int

  Bloc des chiffres en baguette utilisés dans les systèmes de numération anciens.

`IntlChar::BLOCK_CODE_SUNDANESE` int

  Bloc des caractères sundanais utilisés dans l'écriture sundanese de l'Indonésie.

`IntlChar::BLOCK_CODE_LEPCHA` int

  Bloc des caractères Lepcha utilisés dans l'écriture Lepcha de l'Himalaya.

`IntlChar::BLOCK_CODE_OL_CHIKI` int

  Bloc des caractères Ol Chiki utilisés dans l'écriture Ol Chiki pour la langue Santali.

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_A` int

  Bloc des extensions cyrilliques A ajoutant des caractères supplémentaires pour l'écriture des langues slaves et non-slaves.

`IntlChar::BLOCK_CODE_VAI` int

  Bloc des caractères Vai utilisés dans l'écriture Vai de la Sierra Leone.

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_B` int

  Bloc des extensions cyrilliques B ajoutant des caractères supplémentaires pour l'écriture des langues slaves et non-slaves.

`IntlChar::BLOCK_CODE_SAURASHTRA` int

  Bloc des caractères Saurashtra utilisés dans l'écriture Saurashtra de l'Inde.

`IntlChar::BLOCK_CODE_KAYAH_LI` int

  Bloc des caractères Kayah Li utilisés dans l'écriture Kayah Li pour les langues Kayah en Birmanie.

`IntlChar::BLOCK_CODE_REJANG` int

  Bloc des caractères Rejang utilisés dans l'écriture Rejang de l'Indonésie.

`IntlChar::BLOCK_CODE_CHAM` int

  Bloc des caractères Cham utilisés dans l'écriture Cham de l'Asie du Sud-Est.

`IntlChar::BLOCK_CODE_ANCIENT_SYMBOLS` int

  Bloc des symboles anciens utilisés dans divers contextes historiques et culturels.

`IntlChar::BLOCK_CODE_PHAISTOS_DISC` int

  Bloc des caractères du disque de Phaistos utilisés dans l'inscription du disque de Phaistos, un artefact minoen.

`IntlChar::BLOCK_CODE_LYCIAN` int

  Bloc des caractères lyciens utilisés dans l'écriture lycienne de l'ancienne Lycie.

`IntlChar::BLOCK_CODE_CARIAN` int

  Bloc des caractères cariens utilisés dans l'écriture carienne de l'ancienne Carie.

`IntlChar::BLOCK_CODE_LYDIAN` int

  Bloc des caractères lydiens utilisés dans l'écriture lydienne de l'ancienne Lydie.

`IntlChar::BLOCK_CODE_MAHJONG_TILES` int

  Bloc des tuiles Mahjong utilisées dans les jeux de Mahjong.

`IntlChar::BLOCK_CODE_DOMINO_TILES` int

  Bloc des tuiles de dominos utilisées dans les jeux de dominos.

`IntlChar::BLOCK_CODE_SAMARITAN` int

  Bloc des caractères samaritains utilisés dans l'écriture samaritaine.

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED` int

  Bloc étendu des syllabaires aborigènes canadiens unifiés ajoutant des caractères supplémentaires pour certaines langues autochtones.

`IntlChar::BLOCK_CODE_TAI_THAM` int

  Bloc des caractères Tai Tham utilisés dans l'écriture Tai Tham pour certaines langues d'Asie du Sud-Est.

`IntlChar::BLOCK_CODE_VEDIC_EXTENSIONS` int

  Bloc des extensions védiques ajoutant des caractères supplémentaires pour les textes védiques.

`IntlChar::BLOCK_CODE_LISU` int

  Bloc des caractères Lisu utilisés dans l'écriture Lisu de certaines régions d'Asie.

`IntlChar::BLOCK_CODE_BAMUM` int

  Bloc des caractères Bamum utilisés dans l'écriture Bamum du Cameroun.

`IntlChar::BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS` int

  Bloc des formes numériques indic communes utilisées dans les systèmes de numération des langues indo-aryennes.

`IntlChar::BLOCK_CODE_DEVANAGARI_EXTENDED` int

  Bloc étendu des caractères Devanagari ajoutant des caractères supplémentaires pour l'écriture des langues utilisant Devanagari.

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_A` int

  Bloc étendu A des Jamo Hangul ajoutant des caractères supplémentaires pour l'écriture coréenne.

`IntlChar::BLOCK_CODE_JAVANESE` int

  Bloc des caractères javanais utilisés dans l'écriture javanaise de l'Indonésie.

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_A` int

  Bloc étendu A des caractères Myanmar ajoutant des caractères supplémentaires pour l'écriture Myanmar.

`IntlChar::BLOCK_CODE_TAI_VIET` int

  Bloc des caractères Tai Viet utilisés dans l'écriture Tai Viet pour certaines langues d'Asie du Sud-Est.

`IntlChar::BLOCK_CODE_MEETEI_MAYEK` int

  Bloc des caractères Meetei Mayek utilisés dans l'écriture Meetei Mayek pour la langue Meitei.

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_B` int

  Bloc étendu B des Jamo Hangul ajoutant des caractères supplémentaires pour l'écriture coréenne.

`IntlChar::BLOCK_CODE_IMPERIAL_ARAMAIC` int

  Bloc des caractères araméens impériaux utilisés dans l'écriture araméenne ancienne.

`IntlChar::BLOCK_CODE_OLD_SOUTH_ARABIAN` int

  Bloc des caractères arabes du sud anciens utilisés dans l'écriture sud-arabe ancienne.

`IntlChar::BLOCK_CODE_AVESTAN` int

  Bloc des caractères avestans utilisés dans l'écriture avestanique des textes zoroastriens.

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PARTHIAN` int

  Bloc des caractères parthes inscriptionnels utilisés dans l'écriture parthéenne ancienne.

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PAHLAVI` int

  Bloc des caractères pahlavi inscriptionnels utilisés dans l'écriture pahlavi de l'ancienne Perse.

`IntlChar::BLOCK_CODE_OLD_TURKIC` int

  Bloc des caractères turcs anciens utilisés dans l'écriture turque ancienne.

`IntlChar::BLOCK_CODE_RUMI_NUMERAL_SYMBOLS` int

  Bloc des symboles numériques Rumi utilisés dans le système de numération Rumi.

`IntlChar::BLOCK_CODE_KAITHI` int

  Bloc des caractères Kaithi utilisés dans l'écriture Kaithi de l'Inde du Nord.

`IntlChar::BLOCK_CODE_EGYPTIAN_HIEROGLYPHS` int

  Bloc des hiéroglyphes égyptiens utilisés dans l'écriture égyptienne ancienne.

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT` int

  Bloc des suppléments alphanumériques enfermés ajoutant des caractères alphanumériques dans des cercles ou d'autres formes.

`IntlChar::BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT` int

  Bloc des suppléments idéographiques enfermés ajoutant des idéogrammes dans des cercles ou d'autres formes.

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C` int

  Bloc des idéogrammes unifiés CJK, extension C, ajoutant encore plus de caractères.

`IntlChar::BLOCK_CODE_MANDAIC` int

  Bloc des caractères mandaïques utilisés dans l'écriture mandaïque.

`IntlChar::BLOCK_CODE_BATAK` int

  Bloc des caractères Batak utilisés dans l'écriture Batak de l'Indonésie.

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED_A` int

  Bloc étendu A des caractères éthiopiens ajoutant des caractères supplémentaires pour l'écriture éthiopienne.

`IntlChar::BLOCK_CODE_BRAHMI` int

  Bloc des caractères Brahmi utilisés dans l'écriture Brahmi ancienne de l'Inde.

`IntlChar::BLOCK_CODE_BAMUM_SUPPLEMENT` int

  Bloc des suppléments Bamum ajoutant des caractères supplémentaires pour l'écriture Bamum.

`IntlChar::BLOCK_CODE_KANA_SUPPLEMENT` int

  Bloc des suppléments Kana ajoutant des caractères supplémentaires pour l'écriture japonaise Kana.

`IntlChar::BLOCK_CODE_PLAYING_CARDS` int

  Bloc des caractères des cartes à jouer utilisés dans les symboles de jeux de cartes.

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS` int

  Bloc des symboles et pictogrammes divers utilisés dans divers contextes visuels.

`IntlChar::BLOCK_CODE_EMOTICONS` int

  Bloc des émoticônes utilisés pour représenter des expressions faciales et des émotions dans le texte.

`IntlChar::BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS` int

  Bloc des symboles de transport et de cartes utilisés dans les représentations graphiques de systèmes de transport et de cartes.

`IntlChar::BLOCK_CODE_ALCHEMICAL_SYMBOLS` int

  Bloc des symboles alchimiques utilisés dans la représentation des concepts alchimiques historiques.

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D` int

  Bloc des idéogrammes unifiés CJK, extension D, ajoutant encore plus de caractères.

`IntlChar::BLOCK_CODE_ARABIC_EXTENDED_A` int

  Bloc étendu A des caractères arabes ajoutant des caractères supplémentaires pour l'écriture arabe.

`IntlChar::BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS` int

  Bloc des symboles alphabétiques mathématiques arabes utilisés dans les expressions mathématiques.

`IntlChar::BLOCK_CODE_CHAKMA` int

  Bloc des caractères Chakma utilisés dans l'écriture Chakma de l'Inde et du Bangladesh.

`IntlChar::BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS` int

  Bloc des extensions Meetei Mayek ajoutant des caractères supplémentaires pour l'écriture Meetei Mayek.

`IntlChar::BLOCK_CODE_MEROITIC_CURSIVE` int

  Bloc des caractères cursifs méroïtiques utilisés dans l'écriture méroïtique ancienne.

`IntlChar::BLOCK_CODE_MEROITIC_HIEROGLYPHS` int

  Bloc des hiéroglyphes méroïtiques utilisés dans l'écriture méroïtique ancienne.

`IntlChar::BLOCK_CODE_MIAO` int

  Bloc des caractères Miao utilisés dans l'écriture Miao de certaines régions d'Asie.

`IntlChar::BLOCK_CODE_SHARADA` int

  Bloc des caractères Sharada utilisés dans l'écriture Sharada de l'Inde.

`IntlChar::BLOCK_CODE_SORA_SOMPENG` int

  Bloc des caractères Sora Sompeng utilisés dans l'écriture Sora Sompeng de l'Inde.

`IntlChar::BLOCK_CODE_SUNDANESE_SUPPLEMENT` int

  Bloc des suppléments Sundanais ajoutant des caractères supplémentaires pour l'écriture sundanaise.

`IntlChar::BLOCK_CODE_TAKRI` int

  Bloc des caractères Takri utilisés dans l'écriture Takri de l'Inde.

`IntlChar::BLOCK_CODE_BASSA_VAH` int

  Bloc des caractères Bassa Vah utilisés dans l'écriture Bassa Vah de la Guinée.

`IntlChar::BLOCK_CODE_CAUCASIAN_ALBANIAN` int

  Bloc des caractères albanais caucasiens utilisés dans l'écriture albanaise caucasienne ancienne.

`IntlChar::BLOCK_CODE_COPTIC_EPACT_NUMBERS` int

  Bloc des nombres épactes coptes utilisés dans le calcul des épacts pour le calendrier copte.

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED` int

  Bloc des marques diacritiques combinantes étendues ajoutant des caractères supplémentaires pour modifier les caractères de base.

`IntlChar::BLOCK_CODE_DUPLOYAN` int

  Bloc des caractères Duployan utilisés dans l'écriture phonétique du Duployan stenography.

`IntlChar::BLOCK_CODE_ELBASAN` int

  Bloc des caractères Elbasan utilisés dans l'écriture Elbasan de l'Albanie ancienne.

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED` int

  Bloc étendu des formes géométriques ajoutant des formes supplémentaires pour une variété de symboles graphiques.

`IntlChar::BLOCK_CODE_GRANTHA` int

  Bloc des caractères Grantha utilisés dans l'écriture Grantha de l'Inde.

`IntlChar::BLOCK_CODE_KHOJKI` int

  Bloc des caractères Khojki utilisés dans l'écriture Khojki de l'Inde.

`IntlChar::BLOCK_CODE_KHUDAWADI` int

  Bloc des caractères Khudawadi utilisés dans l'écriture Khudawadi de l'Inde.

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_E` int

  Bloc des extensions Latin supplémentaires E ajoutant des caractères supplémentaires pour l'écriture des langues utilisant l'alphabet latin.

`IntlChar::BLOCK_CODE_LINEAR_A` int

  Bloc des caractères Linear A utilisés dans l'écriture Linear A de l'ancienne Crète.

`IntlChar::BLOCK_CODE_MAHAJANI` int

  Bloc des caractères Mahajani utilisés dans l'écriture Mahajani de l'Inde.

`IntlChar::BLOCK_CODE_MANICHAEAN` int

  Bloc des caractères manichéens utilisés dans l'écriture manichéenne ancienne.

`IntlChar::BLOCK_CODE_MENDE_KIKAKUI` int

  Bloc des caractères Mende Kikakui utilisés dans l'écriture Mende Kikakui de la Sierra Leone.

`IntlChar::BLOCK_CODE_MODI` int

  Bloc des caractères Modi utilisés dans l'écriture Modi de l'Inde.

`IntlChar::BLOCK_CODE_MRO` int

  Bloc des caractères Mro utilisés dans l'écriture Mro de certains peuples de l'Asie du Sud-Est.

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_B` int

  Bloc étendu B des caractères Myanmar ajoutant des caractères supplémentaires pour l'écriture Myanmar.

`IntlChar::BLOCK_CODE_NABATAEAN` int

  Bloc des caractères Nabataéens utilisés dans l'écriture Nabataéenne de l'Antiquité.

`IntlChar::BLOCK_CODE_OLD_NORTH_ARABIAN` int

  Bloc des caractères arabes du Nord anciens utilisés dans l'écriture nord-arabe ancienne.

`IntlChar::BLOCK_CODE_OLD_PERMIC` int

  Bloc des caractères permic anciens utilisés dans l'écriture permic de l'ancienne Perse.

`IntlChar::BLOCK_CODE_ORNAMENTAL_DINGBATS` int

  Bloc des dingbats ornementaux utilisés pour ajouter des éléments décoratifs dans le texte.

`IntlChar::BLOCK_CODE_PAHAWH_HMONG` int

  Bloc des caractères Pahawh Hmong utilisés dans l'écriture Pahawh Hmong pour la langue Hmong.

`IntlChar::BLOCK_CODE_PALMYRENE` int

  Bloc des caractères palmyréens utilisés dans l'écriture palmyrène de l'Antiquité.

`IntlChar::BLOCK_CODE_PAU_CIN_HAU` int

  Bloc des caractères Pau Cin Hau utilisés dans l'écriture Pau Cin Hau de certaines communautés en Asie.

`IntlChar::BLOCK_CODE_PSALTER_PAHLAVI` int

  Bloc des caractères pahlavi des psaumes utilisés dans l'écriture pahlavi pour les textes religieux.

`IntlChar::BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS` int

  Bloc des contrôles de format sténographique utilisés pour la sténographie et la transcription rapide.

`IntlChar::BLOCK_CODE_SIDDHAM` int

  Bloc des caractères Siddham utilisés dans l'écriture Siddham de l'Inde ancienne.

`IntlChar::BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS` int

  Bloc des nombres archaïques Sinhala utilisés dans l'écriture Sinhala ancienne.

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_C` int

  Bloc des flèches supplémentaires C ajoutant encore plus de variantes de flèches pour diverses représentations graphiques.

`IntlChar::BLOCK_CODE_TIRHUTA` int

  Bloc des caractères Tirhuta utilisés dans l'écriture Tirhuta de l'Inde du Nord-Est.

`IntlChar::BLOCK_CODE_WARANG_CITI` int

  Bloc des caractères Warang Citi utilisés dans l'écriture Warang Citi pour la langue Ho.

`IntlChar::BLOCK_CODE_COUNT` int

  Bloc code-count définissant le nombre total de blocs disponibles.

`IntlChar::BLOCK_CODE_INVALID_CODE` int

  Bloc code-invalid-code représentant un code de bloc invalide ou non défini.

`IntlChar::BPT_NONE` int

  Type de ponctuation bidirectionnelle : Aucun.

`IntlChar::BPT_OPEN` int

  Type de ponctuation bidirectionnelle : Ouverture.

`IntlChar::BPT_CLOSE` int

  Type de ponctuation bidirectionnelle : Fermeture.

`IntlChar::BPT_COUNT` int

  Nombre total de types de ponctuations bidirectionnelles.

`IntlChar::EA_NEUTRAL` int

  Largeur est-asiatique : Neutre.

`IntlChar::EA_AMBIGUOUS` int

  Largeur est-asiatique : Ambiguë.

`IntlChar::EA_HALFWIDTH` int

  Largeur est-asiatique : Demi-largeur.

`IntlChar::EA_FULLWIDTH` int

  Largeur est-asiatique : Pleine largeur.

`IntlChar::EA_NARROW` int

  Largeur est-asiatique : Étroit.

`IntlChar::EA_WIDE` int

  Largeur est-asiatique : Large.

`IntlChar::EA_COUNT` int

  Nombre total de catégories de largeur est-asiatique.

`IntlChar::UNICODE_CHAR_NAME` int

  Nom de caractère Unicode standard.

`IntlChar::UNICODE_10_CHAR_NAME` int

  Nom de caractère Unicode version 10.

`IntlChar::EXTENDED_CHAR_NAME` int

  Nom de caractère étendu Unicode.

`IntlChar::CHAR_NAME_ALIAS` int

  Alias de nom de caractère Unicode.

`IntlChar::CHAR_NAME_CHOICE_COUNT` int

  Nombre de choix pour les alias de noms de caractères Unicode.

`IntlChar::SHORT_PROPERTY_NAME` int

  Nom de propriété courte.

`IntlChar::LONG_PROPERTY_NAME` int

  Nom de propriété longue.

`IntlChar::PROPERTY_NAME_CHOICE_COUNT` int

  Nombre de choix pour les noms de propriétés.

`IntlChar::DT_NONE` int

  Type de décomposition : Aucun.

`IntlChar::DT_CANONICAL` int

  Type de décomposition : Canonique.

`IntlChar::DT_COMPAT` int

  Type de décomposition : Compatibilité.

`IntlChar::DT_CIRCLE` int

  Type de décomposition : Cercle.

`IntlChar::DT_FINAL` int

  Type de décomposition : Final.

`IntlChar::DT_FONT` int

  Type de décomposition : Police.

`IntlChar::DT_FRACTION` int

  Type de décomposition : Fraction.

`IntlChar::DT_INITIAL` int

  Type de décomposition : Initial.

`IntlChar::DT_ISOLATED` int

  Type de décomposition : Isolé.

`IntlChar::DT_MEDIAL` int

  Type de décomposition : Médial.

`IntlChar::DT_NARROW` int

  Type de décomposition : Étroit.

`IntlChar::DT_NOBREAK` int

  Type de décomposition : Sans rupture.

`IntlChar::DT_SMALL` int

  Type de décomposition : Petit.

`IntlChar::DT_SQUARE` int

  Type de décomposition : Carré.

`IntlChar::DT_SUB` int

  Type de décomposition : Substitutif.

`IntlChar::DT_SUPER` int

  Type de décomposition : Superscript.

`IntlChar::DT_VERTICAL` int

  Type de décomposition : Vertical.

`IntlChar::DT_WIDE` int

  Type de décomposition : Large.

`IntlChar::DT_COUNT` int

  Nombre total de types de décomposition.

`IntlChar::JT_NON_JOINING` int

  Type de jonction : Non-jonctif.

`IntlChar::JT_JOIN_CAUSING` int

  Type de jonction : Causant la jonction.

`IntlChar::JT_DUAL_JOINING` int

  Type de jonction : Jonction double.

`IntlChar::JT_LEFT_JOINING` int

  Type de jonction : Jonction gauche.

`IntlChar::JT_RIGHT_JOINING` int

  Type de jonction : Jonction droite.

`IntlChar::JT_TRANSPARENT` int

  Type de jonction : Transparent.

`IntlChar::JT_COUNT` int

  Nombre total de types de jonction.

`IntlChar::JG_NO_JOINING_GROUP` int

  Groupe de jonction : Pas de groupe de jonction.

`IntlChar::JG_AIN` int

  Groupe de jonction : Ain.

`IntlChar::JG_ALAPH` int

  Groupe de jonction : Alaph.

`IntlChar::JG_ALEF` int

  Groupe de jonction : Alef.

`IntlChar::JG_BEH` int

  Groupe de jonction : Beh.

`IntlChar::JG_BETH` int

  Groupe de jonction : Beth.

`IntlChar::JG_DAL` int

  Groupe de jonction : Dal.

`IntlChar::JG_DALATH_RISH` int

  Groupe de jonction : Dalath Rish.

`IntlChar::JG_E` int

  Groupe de jonction : E.

`IntlChar::JG_FEH` int

  Groupe de jonction : Feh.

`IntlChar::JG_FINAL_SEMKATH` int

  Groupe de jonction : Final Semkath.

`IntlChar::JG_GAF` int

  Groupe de jonction : Gaf.

`IntlChar::JG_GAMAL` int

  Groupe de jonction : Gamal.

`IntlChar::JG_HAH` int

  Groupe de jonction : Hah.

`IntlChar::JG_TEH_MARBUTA_GOAL` int

  Groupe de jonction : Teh Marbuta Goal.

`IntlChar::JG_HAMZA_ON_HEH_GOAL` int

  Groupe de jonction : Hamza sur Heh Goal.

`IntlChar::JG_HE` int

  Groupe de jonction : He.

`IntlChar::JG_HEH` int

  Groupe de jonction : Heh.

`IntlChar::JG_HEH_GOAL` int

  Groupe de jonction : Heh Goal.

`IntlChar::JG_HETH` int

  Groupe de jonction : Heth.

`IntlChar::JG_KAF` int

  Groupe de jonction : Kaf.

`IntlChar::JG_KAPH` int

  Groupe de jonction : Kaph.

`IntlChar::JG_KNOTTED_HEH` int

  Groupe de jonction : Heh noué.

`IntlChar::JG_LAM` int

  Groupe de jonction : Lam.

`IntlChar::JG_LAMADH` int

  Groupe de jonction : Lamadh.

`IntlChar::JG_MEEM` int

  Groupe de jonction : Meem.

`IntlChar::JG_MIM` int

  Groupe de jonction : Mim.

`IntlChar::JG_NOON` int

  Groupe de jonction : Noon.

`IntlChar::JG_NUN` int

  Groupe de jonction : Nun.

`IntlChar::JG_PE` int

  Groupe de jonction : Pe.

`IntlChar::JG_QAF` int

  Groupe de jonction : Qaf.

`IntlChar::JG_QAPH` int

  Groupe de jonction : Qaph.

`IntlChar::JG_REH` int

  Groupe de jonction : Reh.

`IntlChar::JG_REVERSED_PE` int

  Groupe de jonction : Pe inversé.

`IntlChar::JG_SAD` int

  Groupe de jonction : Sad.

`IntlChar::JG_SADHE` int

  Groupe de jonction : Sadhe.

`IntlChar::JG_SEEN` int

  Groupe de jonction : Seen.

`IntlChar::JG_SEMKATH` int

  Groupe de jonction : Semkath.

`IntlChar::JG_SHIN` int

  Groupe de jonction : Shin.

`IntlChar::JG_SWASH_KAF` int

  Groupe de jonction : Swash Kaf.

`IntlChar::JG_SYRIAC_WAW` int

  Groupe de jonction : Waw Syriac.

`IntlChar::JG_TAH` int

  Groupe de jonction : Tah.

`IntlChar::JG_TAW` int

  Groupe de jonction : Taw.

`IntlChar::JG_TEH_MARBUTA` int

  Groupe de jonction : Teh Marbuta.

`IntlChar::JG_TETH` int

  Groupe de jonction : Teth.

`IntlChar::JG_WAW` int

  Groupe de jonction : Waw.

`IntlChar::JG_YEH` int

  Groupe de jonction : Yeh.

`IntlChar::JG_YEH_BARREE` int

  Groupe de jonction : Yeh Barree.

`IntlChar::JG_YEH_WITH_TAIL` int

  Groupe de jonction : Yeh avec queue.

`IntlChar::JG_YUDH` int

  Groupe de jonction : Yudh.

`IntlChar::JG_YUDH_HE` int

  Groupe de jonction : Yudh-He.

`IntlChar::JG_ZAIN` int

  Groupe de jonction : Zain.

`IntlChar::JG_FE` int

  Groupe de jonction : Fe.

`IntlChar::JG_KHAPH` int

  Groupe de jonction : Khaph.

`IntlChar::JG_ZHAIN` int

  Groupe de jonction : Zhain.

`IntlChar::JG_BURUSHASKI_YEH_BARREE` int

  Groupe de jonction : Yeh Barree Burushaski.

`IntlChar::JG_FARSI_YEH` int

  Groupe de jonction : Yeh Farsi.

`IntlChar::JG_NYA` int

  Groupe de jonction : Nya.

`IntlChar::JG_ROHINGYA_YEH` int

  Groupe de jonction : Yeh Rohingya.

`IntlChar::JG_MANICHAEAN_ALEPH` int

  Groupe de jonction : Aleph Manichéen.

`IntlChar::JG_MANICHAEAN_AYIN` int

  Groupe de jonction : Ayin Manichéen.

`IntlChar::JG_MANICHAEAN_BETH` int

  Groupe de jonction : Beth Manichéen.

`IntlChar::JG_MANICHAEAN_DALETH` int

  Groupe de jonction : Daleth Manichéen.

`IntlChar::JG_MANICHAEAN_DHAMEDH` int

  Groupe de jonction : Dhamedh Manichéen.

`IntlChar::JG_MANICHAEAN_FIVE` int

  Groupe de jonction : Cinq Manichéen.

`IntlChar::JG_MANICHAEAN_GIMEL` int

  Groupe de jonction : Gimel Manichéen.

`IntlChar::JG_MANICHAEAN_HETH` int

  Groupe de jonction : Heth Manichéen.

`IntlChar::JG_MANICHAEAN_HUNDRED` int

  Groupe de jonction : Cent Manichéen.

`IntlChar::JG_MANICHAEAN_KAPH` int

  Groupe de jonction : Kaph Manichéen.

`IntlChar::JG_MANICHAEAN_LAMEDH` int

  Groupe de jonction : Lamedh Manichéen.

`IntlChar::JG_MANICHAEAN_MEM` int

  Groupe de jonction : Mem Manichéen.

`IntlChar::JG_MANICHAEAN_NUN` int

  Groupe de jonction : Nun Manichéen.

`IntlChar::JG_MANICHAEAN_ONE` int

  Groupe de jonction : Un Manichéen.

`IntlChar::JG_MANICHAEAN_PE` int

  Groupe de jonction : Pe Manichéen.

`IntlChar::JG_MANICHAEAN_QOPH` int

  Groupe de jonction : Qoph Manichéen.

`IntlChar::JG_MANICHAEAN_RESH` int

  Groupe de jonction : Resh Manichéen.

`IntlChar::JG_MANICHAEAN_SADHE` int

  Groupe de jonction : Sadhe Manichéen.

`IntlChar::JG_MANICHAEAN_SAMEKH` int

  Groupe de jonction : Samekh Manichéen.

`IntlChar::JG_MANICHAEAN_TAW` int

  Groupe de jonction : Taw Manichéen.

`IntlChar::JG_MANICHAEAN_TEN` int

  Groupe de jonction : Dix Manichéen.

`IntlChar::JG_MANICHAEAN_TETH` int

  Groupe de jonction : Teth Manichéen.

`IntlChar::JG_MANICHAEAN_THAMEDH` int

  Groupe de jonction : Thamedh Manichéen.

`IntlChar::JG_MANICHAEAN_TWENTY` int

  Groupe de jonction : Vingt Manichéen.

`IntlChar::JG_MANICHAEAN_WAW` int

  Groupe de jonction : Waw Manichéen.

`IntlChar::JG_MANICHAEAN_YODH` int

  Groupe de jonction : Yodh Manichéen.

`IntlChar::JG_MANICHAEAN_ZAYIN` int

  Groupe de jonction : Zayin Manichéen.

`IntlChar::JG_STRAIGHT_WAW` int

  Groupe de jonction : Waw droit.

`IntlChar::JG_COUNT` int

  Nombre total de groupes de jonction.

`IntlChar::GCB_OTHER` int

  Catégorie de cluster de graphemes : Autre.

`IntlChar::GCB_CONTROL` int

  Catégorie de cluster de graphemes : Contrôle.

`IntlChar::GCB_CR` int

  Catégorie de cluster de graphemes : Retour chariot.

`IntlChar::GCB_EXTEND` int

  Catégorie de cluster de graphemes : Extension.

`IntlChar::GCB_L` int

  Catégorie de cluster de graphemes : Lettre L.

`IntlChar::GCB_LF` int

  Catégorie de cluster de graphemes : Ligne Feed.

`IntlChar::GCB_LV` int

  Catégorie de cluster de graphemes : LV.

`IntlChar::GCB_LVT` int

  Catégorie de cluster de graphemes : LVT.

`IntlChar::GCB_T` int

  Catégorie de cluster de graphemes : T.

`IntlChar::GCB_V` int

  Catégorie de cluster de graphemes : V.

`IntlChar::GCB_SPACING_MARK` int

  Catégorie de cluster de graphèmes : Marque d'espacement.

`IntlChar::GCB_PREPEND` int

  Catégorie de cluster de graphemes : Préfixe.

`IntlChar::GCB_REGIONAL_INDICATOR` int

  Catégorie de cluster de graphemes : Indicateur régional.

`IntlChar::GCB_COUNT` int

  Nombre total de catégories de cluster de graphemes.

`IntlChar::WB_OTHER` int

  Catégorie de séparation de mots : Autre.

`IntlChar::WB_ALETTER` int

  Catégorie de séparation de mots : Lettre A.

`IntlChar::WB_FORMAT` int

  Catégorie de séparation de mots : Format.

`IntlChar::WB_KATAKANA` int

  Catégorie de séparation de mots : Katakana.

`IntlChar::WB_MIDLETTER` int

  Catégorie de séparation de mots : Lettre médiane.

`IntlChar::WB_MIDNUM` int

  Catégorie de séparation de mots : Numéro médian.

`IntlChar::WB_NUMERIC` int

  Catégorie de séparation de mots : Numérique.

`IntlChar::WB_EXTENDNUMLET` int

  Catégorie de séparation de mots : Extension numérique et lettre.

`IntlChar::WB_CR` int

  Catégorie de séparation de mots : Retour chariot.

`IntlChar::WB_EXTEND` int

  Catégorie de séparation de mots : Extension.

`IntlChar::WB_LF` int

  Catégorie de séparation de mots : Ligne Feed.

`IntlChar::WB_MIDNUMLET` int

  Catégorie de séparation de mots : Numéro et lettre médiane.

`IntlChar::WB_NEWLINE` int

  Catégorie de séparation de mots : Nouvelle ligne.

`IntlChar::WB_REGIONAL_INDICATOR` int

  Catégorie de séparation de mots : Indicateur régional.

`IntlChar::WB_HEBREW_LETTER` int

  Catégorie de séparation de mots : Lettre hébraïque.

`IntlChar::WB_SINGLE_QUOTE` int

  Catégorie de séparation de mots : Guillemets simples.

`IntlChar::WB_DOUBLE_QUOTE` int

  Catégorie de séparation de mots : Guillemets doubles.

`IntlChar::WB_COUNT` int

  Nombre total de catégories de séparation de mots.

`IntlChar::SB_OTHER` int

  Catégorie de séparation de phrases : Autre.

`IntlChar::SB_ATERM` int

  Catégorie de séparation de phrases : Aterm.

`IntlChar::SB_CLOSE` int

  Catégorie de séparation de phrases : Fermeture.

`IntlChar::SB_FORMAT` int

  Catégorie de séparation de phrases : Format.

`IntlChar::SB_LOWER` int

  Catégorie de séparation de phrases : Minuscules.

`IntlChar::SB_NUMERIC` int

  Catégorie de séparation de phrases : Numérique.

`IntlChar::SB_OLETTER` int

  Catégorie de séparation de phrases : Lettre O.

`IntlChar::SB_SEP` int

  Catégorie de séparation de phrases : Séparateur.

`IntlChar::SB_SP` int

  Catégorie de séparation de phrases : Espacement.

`IntlChar::SB_STERM` int

  Catégorie de séparation de phrases : Sterm.

`IntlChar::SB_UPPER` int

  Catégorie de séparation de phrases : Majuscules.

`IntlChar::SB_CR` int

  Catégorie de séparation de phrases : Retour chariot.

`IntlChar::SB_EXTEND` int

  Catégorie de séparation de phrases : Extension.

`IntlChar::SB_LF` int

  Catégorie de séparation de phrases : Ligne Feed.

`IntlChar::SB_SCONTINUE` int

  Catégorie de séparation de phrases : Continue.

`IntlChar::SB_COUNT` int

  Nombre total de catégories de séparation de phrases.

`IntlChar::LB_UNKNOWN` int

  Catégorie de séparation de lignes : Inconnue.

`IntlChar::LB_AMBIGUOUS` int

  Catégorie de séparation de lignes : Ambiguë.

`IntlChar::LB_ALPHABETIC` int

  Catégorie de séparation de lignes : Alphabétique.

`IntlChar::LB_BREAK_BOTH` int

  Catégorie de séparation de lignes : Séparation des deux côtés.

`IntlChar::LB_BREAK_AFTER` int

  Catégorie de séparation de lignes : Séparation après.

`IntlChar::LB_BREAK_BEFORE` int

  Catégorie de séparation de lignes : Séparation avant.

`IntlChar::LB_MANDATORY_BREAK` int

  Catégorie de séparation de lignes : Séparation obligatoire.

`IntlChar::LB_CONTINGENT_BREAK` int

  Catégorie de séparation de lignes : Séparation contingente.

`IntlChar::LB_CLOSE_PUNCTUATION` int

  Catégorie de séparation de lignes : Ponctuation fermante.

`IntlChar::LB_COMBINING_MARK` int

  Catégorie de séparation de lignes : Marque combinante.

`IntlChar::LB_CARRIAGE_RETURN` int

  Catégorie de séparation de lignes : Retour chariot.

`IntlChar::LB_EXCLAMATION` int

  Catégorie de séparation de lignes : Point d'exclamation.

`IntlChar::LB_GLUE` int

  Catégorie de séparation de lignes : Colle.

`IntlChar::LB_HYPHEN` int

  Catégorie de séparation de lignes : Tiret.

`IntlChar::LB_IDEOGRAPHIC` int

  Catégorie de séparation de lignes : Idéographique.

`IntlChar::LB_INSEPARABLE` int

  Catégorie de séparation de lignes : Inséparable.

`IntlChar::LB_INSEPERABLE` int

  Catégorie de séparation de lignes : Inséparable.

`IntlChar::LB_INFIX_NUMERIC` int

  Catégorie de séparation de lignes : Numérique intermédiaire.

`IntlChar::LB_LINE_FEED` int

  Catégorie de séparation de lignes : Ligne Feed.

`IntlChar::LB_NONSTARTER` int

  Catégorie de séparation de lignes : Non-initiateur.

`IntlChar::LB_NUMERIC` int

  Catégorie de séparation de lignes : Numérique.

`IntlChar::LB_OPEN_PUNCTUATION` int

  Catégorie de séparation de lignes : Ponctuation ouvrante.

`IntlChar::LB_POSTFIX_NUMERIC` int

  Catégorie de séparation de lignes : Numérique postfixe.

`IntlChar::LB_PREFIX_NUMERIC` int

  Catégorie de séparation de lignes : Numérique préfixe.

`IntlChar::LB_QUOTATION` int

  Catégorie de séparation de lignes : Citation.

`IntlChar::LB_COMPLEX_CONTEXT` int

  Catégorie de séparation de lignes : Contexte complexe.

`IntlChar::LB_SURROGATE` int

  Catégorie de séparation de lignes : Surrogate.

`IntlChar::LB_SPACE` int

  Catégorie de séparation de lignes : Espace.

`IntlChar::LB_BREAK_SYMBOLS` int

  Catégorie de séparation de lignes : Symboles de rupture.

`IntlChar::LB_ZWSPACE` int

  Catégorie de séparation de lignes : Espace zéro largeur.

`IntlChar::LB_NEXT_LINE` int

  Catégorie de séparation de lignes : Ligne suivante.

`IntlChar::LB_WORD_JOINER` int

  Catégorie de séparation de lignes : Relieur de mots.

`IntlChar::LB_H2` int

  Catégorie de séparation de lignes : H2.

`IntlChar::LB_H3` int

  Catégorie de séparation de lignes : H3.

`IntlChar::LB_JL` int

  Catégorie de séparation de lignes : JL.

`IntlChar::LB_JT` int

  Catégorie de séparation de lignes : JT.

`IntlChar::LB_JV` int

  Catégorie de séparation de lignes : JV.

`IntlChar::LB_CLOSE_PARENTHESIS` int

  Catégorie de séparation de lignes : Parenthèse fermante.

`IntlChar::LB_CONDITIONAL_JAPANESE_STARTER` int

  Catégorie de séparation de lignes : Début conditionnel japonais.

`IntlChar::LB_HEBREW_LETTER` int

  Catégorie de séparation de lignes : Lettre hébraïque.

`IntlChar::LB_REGIONAL_INDICATOR` int

  Catégorie de séparation de lignes : Indicateur régional.

`IntlChar::LB_COUNT` int

  Nombre total de catégories de séparation de lignes.

`IntlChar::NT_NONE` int

  Type de nombre : Aucun.

`IntlChar::NT_DECIMAL` int

  Type de nombre : Décimal.

`IntlChar::NT_DIGIT` int

  Type de nombre : Chiffre.

`IntlChar::NT_NUMERIC` int

  Type de nombre : Numérique.

`IntlChar::NT_COUNT` int

  Nombre total de types de nombres.

`IntlChar::HST_NOT_APPLICABLE` int

  Type de syllabe Hangul : Non applicable.

`IntlChar::HST_LEADING_JAMO` int

  Type de syllabe Hangul : Jamo initial.

`IntlChar::HST_VOWEL_JAMO` int

  Type de syllabe Hangul : Jamo voyelle.

`IntlChar::HST_TRAILING_JAMO` int

  Type de syllabe Hangul : Jamo final.

`IntlChar::HST_LV_SYLLABLE` int

  Type de syllabe Hangul : Syllabe LV.

`IntlChar::HST_LVT_SYLLABLE` int

  Type de syllabe Hangul : Syllabe LVT.

`IntlChar::HST_COUNT` int

  Nombre total de types de syllabes Hangul.

`IntlChar::FOLD_CASE_DEFAULT` int

  Option de pliage de casse : Par défaut.

`IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I` int

  Option de pliage de casse : Exclure le I spécial.

## Historique

Version | Description
--- | ---
8.4.0 | Ajout de `IntlChar::PROPERTY_IDS_UNARY_OPERATOR`, `IntlChar::PROPERTY_ID_COMPAT_MATH_START`, `IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE`.
8.4.0 | Les constantes de classe sont maintenant typées.
7.0.6 | La `IntlChar::NO_NUMERIC_VALUE` constante a été ajoutée.

# IntlChar::charAge

(PHP 7, PHP 8)

IntlChar::charAge — Renvoie l'"âge" du point de code

### Description

public static function IntlChar::charAge(int|string `$codepoint`): ?array

Renvoie l'"âge" du point de code.

L'"âge" est la version Unicode lorsque le point de code a été désigné pour la première fois (comme un non-caractère ou pour une utilisation privée) ou attribué à un caractère. Cela peut être utile pour éviter d'émettre des points de code à des processus de réception qui n'acceptent pas les caractères plus récents.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

La version Unicode, sous la forme d'un array. Par exemple, la version 1.3.31.2 serait représentée par `[1, 3, 31, 2]`. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::charage("\u{2603}"));
    var_dump(IntlChar::charage("\u{1F576}"));
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      int(1)
      [1]=>
      int(1)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }
    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Voir aussi

- IntlChar::getUnicodeVersion() - Renvoie la version Unicode
- IntlChar::getIntPropertyMinValue() - Renvoie la valeur minimale pour une propriété Unicode
- IntlChar::getIntPropertyValue() - Renvoie la valeur d'une propriété Unicode pour un point de code

# IntlChar::charDigitValue

(PHP 7, PHP 8)

IntlChar::charDigitValue — Renvoie la valeur décimale du chiffre décimal

### Description

public static function IntlChar::charDigitValue(int|string `$codepoint`): ?int

Renvoie la valeur décimale du chiffre caractère décimal.

De tels caractères ont la catégorie générale "Nd" (chiffres décimaux) et un Numeric_Type de Decimal.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

La valeur décimale du chiffre caractère décimal, ou `-1` s'il n'est pas un caractère décimal. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::charDigitValue("1"));
    var_dump(IntlChar::charDigitValue("\u{0662}"));
    var_dump(IntlChar::charDigitValue("\u{0E53}"));
    ?>

L'exemple ci-dessus va afficher :

    int(1)
    int(2)
    int(3)

### Voir aussi

- IntlChar::getNumericValue() - Renvoie la valeur numérique d'un point de code Unicode

# IntlChar::charDirection

(PHP 7, PHP 8)

IntlChar::charDirection — Renvoie la valeur de la catégorie bidirectionnelle pour un point de code

### Description

public static function IntlChar::charDirection(int|string `$codepoint`): ?int

Renvoie la valeur de la catégorie bidirectionnelle pour un point de code, qui est utilisée dans l'» algorithme bidirectionnel Unicode (UAX #9).

> Note:

> Certains points de code non attribués ont des valeurs de bidirectionnel de R ou AL car ils sont dans des blocs réservés pour les scripts de droite à gauche.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

La valeur de la catégorie bidirectionnelle; une des constantes suivantes:

- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR`
- `IntlChar::CHAR_DIRECTION_ARABIC_NUMBER`
- `IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT`
- `IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK`
- `IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE`
- `IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT`

Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::charDirection("A") === IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT);
    var_dump(IntlChar::charDirection("\u{05E9}") === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::charDirection("+") === IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR);
    var_dump(IntlChar::charDirection(".") === IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::charFromName

(PHP 7, PHP 8)

IntlChar::charFromName — Trouve un caractère Unicode par son nom et renvoie sa valeur de point de code

### Description

public static function IntlChar::charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int

Trouve un caractère Unicode par son nom et renvoie sa valeur de point de code.

Le nom est comparé exactement et complètement. Si le nom ne correspond pas à un point de code, `null` est renvoyé.

Un nom Unicode 1.0 est trouvé uniquement s'il diffère du nom moderne. Les noms Unicode sont tous en majuscules. Les noms étendus sont en minuscules suivis d'un nombre hexadécimal en majuscules, et entre chevrons.

### Liste de paramètres

`name`

  Le nom complet du caractère Unicode.

`type`

  Quels noms utiliser pour la recherche. Peut être une des constantes suivantes:

  - `IntlChar::UNICODE_CHAR_NAME` (défaut)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Valeurs de retour

La valeur Unicode du point de code avec le nom donné (en tant qu'int), ou `null` s'il n'y a pas de tel point de code.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::charFromName("LATIN CAPITAL LETTER A"));
    var_dump(IntlChar::charFromName("SNOWMAN"));
    var_dump(IntlChar::charFromName("RECYCLING SYMBOL FOR TYPE-1 PLASTICS"));
    var_dump(IntlChar::charFromName("A RANDOM STRING WHICH DOESN'T CORRESPOND TO ANY UNICODE CHARACTER"));
    ?>

L'exemple ci-dessus va afficher :

    int(65)
    int(9731)
    int(9843)
    NULL

### Voir aussi

- IntlChar::charName() - Renvoie le nom d'un caractère Unicode
- IntlChar::enumCharNames() - Enumère tous les caractères Unicode assignés dans une plage

# IntlChar::charMirror

(PHP 7, PHP 8)

IntlChar::charMirror — Renvoie le caractère "image-miroir" pour un point de code

### Description

public static function IntlChar::charMirror(int|string `$codepoint`): int|string|null

Lie le caractère spécifié à un caractère "image-miroir".

Pour les caractères avec la propriété Bidi_Mirrored, les implémentations ont parfois besoin d'une correspondance "pauvre" vers un autre point de code Unicode (code point) tel que le glyphe par défaut puisse servir de glyphe miroir du glyphe par défaut du caractère spécifié. Ceci est utile pour la conversion de texte vers et depuis des pages de codes avec un ordre visuel, et pour les affichages sans capacités de sélection de glyphe.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie un autre point de code Unicode qui peut servir de substitut image-miroir, ou `codepoint` lui-même s'il n'y a pas de correspondance ou si `codepoint` n'a pas la propriété Bidi_Mirrored.

Le type retourné sera entier tant que le codepoint a été passé en une chaîne de type chaîne de caractères encodée en UTF-8, auquel cas, une chaîne de caractères est retournée. En cas d'échec, retourne `null`.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::charMirror("A"));
    var_dump(IntlChar::charMirror("<"));
    var_dump(IntlChar::charMirror("("));
    ?>

L'exemple ci-dessus va afficher :

    string(1) "A"
    string(1) ">"
    string(2) ")"

### Voir aussi

- IntlChar::isMirrored() - Vérifie si un point de code a la propriété Bidi_Mirrored
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::charName

(PHP 7, PHP 8)

IntlChar::charName — Renvoie le nom d'un caractère Unicode

### Description

public static function IntlChar::charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string

Renvoie le nom d'un caractère Unicode.

Selon le `type`, le nom du caractère est le nom "moderne" ou le nom qui a été défini dans la version Unicode 1.0. Le nom ne contient que des caractères "invariants" comme A-Z, 0-9, espace et '-'. Les noms Unicode 1.0 ne sont récupérés que s'ils sont différents des noms modernes et si ICU contient les données pour eux.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)
`type`

  Quels noms utiliser pour la recherche. Peut être une des constantes suivantes:

  - `IntlChar::UNICODE_CHAR_NAME` (défaut)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Valeurs de retour

La valeur correspondante, ou une chaîne vide s'il n'y a pas de nom pour ce caractère, ou `null` s'il n'y a pas de point de code.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::charName("."));
    var_dump(IntlChar::charName(".", IntlChar::UNICODE_CHAR_NAME));
    var_dump(IntlChar::charName("\u{2603}"));
    var_dump(IntlChar::charName("\u{0000}"));
    ?>

L'exemple ci-dessus va afficher :

    string(9) "FULL STOP"
    string(9) "FULL STOP"
    string(7) "SNOWMAN"
    string(0) ""

### Voir aussi

- IntlChar::charFromName() - Trouve un caractère Unicode par son nom et renvoie sa valeur de point de code
- IntlChar::enumCharNames() - Enumère tous les caractères Unicode assignés dans une plage

# IntlChar::charType

(PHP 7, PHP 8)

IntlChar::charType — Renvoie la valeur de la catégorie générale pour un point de code

### Description

public static function IntlChar::charType(int|string `$codepoint`): ?int

Renvoie la catégorie générale pour le point de code.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie la catégorie générale, qui peut être une des constantes suivantes:

- `IntlChar::CHAR_CATEGORY_UNASSIGNED`
- `IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES`
- `IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_TITLECASE_LETTER`
- `IntlChar::CHAR_CATEGORY_MODIFIER_LETTER`
- `IntlChar::CHAR_CATEGORY_OTHER_LETTER`
- `IntlChar::CHAR_CATEGORY_NON_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_ENCLOSING_MARK`
- `IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER`
- `IntlChar::CHAR_CATEGORY_LETTER_NUMBER`
- `IntlChar::CHAR_CATEGORY_OTHER_NUMBER`
- `IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR`
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR`
- `IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR`
- `IntlChar::CHAR_CATEGORY_SURROGATE`
- `IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_START_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_END_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_MATH_SYMBOL`
- `IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL`
- `IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_OTHER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT`

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::charType("A") === IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER);
    var_dump(IntlChar::charType(".") === IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION);
    var_dump(IntlChar::charType("\t") === IntlChar::CHAR_CATEGORY_CONTROL_CHAR);
    var_dump(IntlChar::charType("\u{2603}") === IntlChar::CHAR_CATEGORY_OTHER_SYMBOL);
    var_dump(IntlChar::charType("multiple chars") === null);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::chr

(PHP 7, PHP 8)

IntlChar::chr — Renvoie le caractère Unicode par valeur de point de code

### Description

public static function IntlChar::chr(int|string `$codepoint`): ?string

Renvoie une chaîne contenant le caractère spécifié par la valeur de point de code Unicode.

Cette méthode complète IntlChar::ord().

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Une chaîne contenant le caractère unique spécifié par la valeur de point de code Unicode, ou `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    $values = ["A", 63, 123, 9731];
    foreach ($values as $value) {
        var_dump(IntlChar::chr($value));
    }
    ?>

L'exemple ci-dessus va afficher :

    string(1) "A"
    string(1) "?"
    string(1) "{"
    string(3) "☃"

### Voir aussi

- IntlChar::ord() - Renvoie la valeur du point de code Unicode d'un caractère
- mb_chr() - Retourne un caractère par sa valeur de point de code Unicode
- chr() - Générer une chaîne d'un octet à partir d'un nombre

# IntlChar::digit

(PHP 7, PHP 8)

IntlChar::digit — Renvoie le chiffre décimal d'un point de code pour une base de numération donnée

### Description

public static function IntlChar::digit(int|string `$codepoint`, int `$base` = 10): int|false|null

Renvoie la valeur décimale du point de code dans la base de numération spécifiée.

Si la base de numération n'est pas dans la plage `2 <= radix <= 36` ou si la valeur de `codepoint` n'est pas un chiffre valide dans la base spécifiée, `false` est renvoyé. Un caractère est un chiffre valide si au moins une des conditions suivantes est vraie:

- Le caractère a une valeur de chiffre décimal. Ces caractères ont la catégorie générale "Nd" (chiffres décimaux) et un Numeric_Type de "Decimal". Dans ce cas, la valeur est la valeur de chiffre décimal du caractère.
- Le caractère est une des lettres latines majuscules `'A'` à `'Z'`. Dans ce cas, la valeur est `codepoint - 'A' + 10`.
- Le caractère est une des lettres latines minuscules `'a'` à `'z'`. Dans ce cas, la valeur est `codepoint - 'a' + 10`.
- Les lettres latines de la plage ASCII (`0061..007A`, `0041..005A`) ainsi que de la plage ASCII pleine largeur (`FF41..FF5A`, `FF21..FF3A`) sont reconnues.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)
`base`

  La base de numération (défaut à `10`).

### Valeurs de retour

Renvoie la valeur numérique représentée par le caractère dans la base de numération spécifiée, ou `false` s'il n'y a pas de valeur ou si la valeur dépasse la base. Renvoie `null` en cas d'échec.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Exemples

Exemple #1 Test de différents codepoint

    <?php

    var_dump(IntlChar::digit("0"));
    var_dump(IntlChar::digit("3"));

    var_dump(IntlChar::digit("A", 16));
    var_dump(IntlChar::digit("A"));

    ?>

L'exemple ci-dessus va afficher :

    int(0)
    int(3)
    int(10)
    bool(false)

### Voir aussi

- IntlChar::forDigit() - Renvoie la représentation de caractère pour un chiffre donné et une base de numération
- IntlChar::charDigitValue() - Renvoie la valeur décimale du chiffre décimal
- IntlChar::isdigit() - Vérifie si un point de code est un chiffre
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::enumCharNames

(PHP 7, PHP 8)

IntlChar::enumCharNames — Enumère tous les caractères Unicode assignés dans une plage

### Description

public static function IntlChar::enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool

Enumère tous les caractères Unicode assignés entre les points de code de début et de fin (inclusivement le début, exclusivement la fin) et appelle une fonction pour chacun, passant la valeur du point de code et le nom du caractère.

Pour les noms Unicode 1.0, seuls ceux qui diffèrent des noms modernes sont énumérés.

### Liste de paramètres

`start`

  Le premier point de code dans la plage d'énumération.

`end`

  Un ou plusieurs points de code de plus que le dernier point de code dans la plage d'énumération (le premier après la plage).

`callback`

  La fonction qui doit être appelée pour chaque nom de caractère. Les trois arguments suivants lui seront passés :

  - int `$codepoint` - La valeur numérique du point de code
  - int `$nameChoice` - La même valeur que le paramètre `type` ci-dessous
  - string `$name` - Le nom du caractère
`type`

  Un sélecteur pour le type de noms à énumérer. Peut être une des constantes suivantes :

  - `IntlChar::UNICODE_CHAR_NAME` (défaut)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.3.0 | Cette méthode retourne maintenant `false` en cas d'échec ; précédemment elle retournait `null`.

### Exemples

Exemple #1 Enumère une plage d'exemples de points de code

    <?php
    IntlChar::enumCharNames(0x2600, 0x2610, function($codepoint, $nameChoice, $name) {
        printf("U+%04x %s\n", $codepoint, $name);
    });
    ?>

L'exemple ci-dessus va afficher :

    U+2600 BLACK SUN WITH RAYS
    U+2601 CLOUD
    U+2602 UMBRELLA
    U+2603 SNOWMAN
    U+2604 COMET
    U+2605 BLACK STAR
    U+2606 WHITE STAR
    U+2607 LIGHTNING
    U+2608 THUNDERSTORM
    U+2609 SUN
    U+260a ASCENDING NODE
    U+260b DESCENDING NODE
    U+260c CONJUNCTION
    U+260d OPPOSITION
    U+260e BLACK TELEPHONE
    U+260f WHITE TELEPHONE

### Voir aussi

- IntlChar::charName() - Renvoie le nom d'un caractère Unicode
- IntlChar::charFromName() - Trouve un caractère Unicode par son nom et renvoie sa valeur de point de code

# IntlChar::enumCharTypes

(PHP 7, PHP 8)

IntlChar::enumCharTypes — Enumère tous les points de code avec leurs catégories générales Unicode

### Description

public static function IntlChar::enumCharTypes(callable `$callback`): void

Enumère efficacement tous les points de code avec leurs catégories générales Unicode. Ceci est utile pour construire des structures de données, pour énumérer tous les points de code assignés, etc.

Pour chaque plage de points de code contigus avec une catégorie générale donnée ("type de caractère"), la fonction `callback` est appelée. Les plages adjacentes ont des types différents. La norme Unicode garantit que la valeur numérique du type est 0..31.

### Liste de paramètres

`callback`

  La fonction qui doit être appelée pour chaque plage de points de code contigus avec la même catégorie générale. Les trois arguments suivants lui seront passés :

  - int `$start` - Le point de code de début de la plage
  - int `$end` - Le point de code de fin de la plage
  - int `$name` - Le type de caractère (une des constantes `IntlChar::CHAR_CATEGORY_*`)

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Enumère une plage d'exemple de points de code

    <?php
    IntlChar::enumCharTypes(function($start, $end, $type) {
        printf("U+%04x through U+%04x are in category %d\n", $start, $end, $type);
    });
    ?>

L'exemple ci-dessus va afficher :

    U+0000 through U+0020 are in category 15
    U+0020 through U+0021 are in category 12
    U+0021 through U+0024 are in category 23
    U+0024 through U+0025 are in category 25
    U+0025 through U+0028 are in category 23
    U+0028 through U+0029 are in category 20
    U+0029 through U+002a are in category 21
    U+002a through U+002b are in category 23
    U+002b through U+002c are in category 24
    U+002c through U+002d are in category 23
    U+002d through U+002e are in category 19
    U+002e through U+0030 are in category 23
    U+0030 through U+003a are in category 9
    ...

# IntlChar::foldCase

(PHP 7, PHP 8)

IntlChar::foldCase — Effectue le pliage de cas sur un point de code

### Description

public static function IntlChar::foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null

Le caractère donné est mappé à son équivalent de pliage de cas; si le caractère n'a pas d'équivalent de pliage de cas, le caractère lui-même est renvoyé.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)
`options`

  Soit `IntlChar::FOLD_CASE_DEFAULT` (défaut) ou `IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I`.

### Valeurs de retour

Renvoie le pliage de cas simple du point de code, si disponible; sinon le point de code lui-même en cas de succès, ou `null` en cas d'échec.

# IntlChar::forDigit

(PHP 7, PHP 8)

IntlChar::forDigit — Renvoie la représentation de caractère pour un chiffre donné et une base de numération

### Description

public static function IntlChar::forDigit(int `$digit`, int `$base` = 10): int

Détermine la représentation de caractère pour un chiffre spécifique dans la base de numération spécifiée.

Si la valeur de la base de numération n'est pas une base de numération valide, ou si la valeur du chiffre n'est pas un chiffre valide dans la base spécifiée, le caractère nul (`U+0000`) est renvoyé.

La base de numération est valide si elle est supérieure ou égale à `2` et inférieure ou égale à `36`. La valeur du chiffre est valide si `0 <= chiffre < base`.

Si le chiffre est inférieur à `10`, alors '0' + chiffre est renvoyé. Sinon, la valeur 'a' + chiffre - 10 est renvoyée.

### Liste de paramètres

`digit`

  Le chiffre à convertir en caractère.

`base`

  La base de numération (défaut à `10`).

### Valeurs de retour

Le caractère représentant (en tant que int) du chiffre spécifié dans la base de numération spécifiée.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::forDigit(0));
    var_dump(IntlChar::forDigit(3));
    var_dump(IntlChar::forDigit(3, 10));
    var_dump(IntlChar::forDigit(10));
    var_dump(IntlChar::forDigit(10, 16));
    ?>

L'exemple ci-dessus va afficher :

    int(48)
    int(51)
    int(51)
    int(0)
    int(97)

### Voir aussi

- IntlChar::digit() - Renvoie le chiffre décimal d'un point de code pour une base de numération donnée
- IntlChar::charDigitValue() - Renvoie la valeur décimale du chiffre décimal
- IntlChar::isdigit() - Vérifie si un point de code est un chiffre
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::getBidiPairedBracket

(PHP 7, PHP 8)

IntlChar::getBidiPairedBracket — Renvoie le caractère de parenthèse apparié pour un point de code

### Description

public static function IntlChar::getBidiPairedBracket(int|string `$codepoint`): int|string|null

Mappe le caractère spécifié à son caractère de parenthèse apparié.

Pour `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE !== IntlChar::BPT_NONE`, cela équivaut à IntlChar::charMirror(). Sinon, `codepoint` lui-même est renvoyé.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie le point de code de la parenthèse appariée, ou `codepoint` lui-même s'il n'y a pas de mappage. Renvoie `null` en cas d'échec.

Le type retourné sera entier tant que le codepoint a été passé en une chaîne de type chaîne de caractères encodée en UTF-8, auquel cas, une chaîne de caractères est retournée. En cas d'échec, retourne `null`.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::getBidiPairedBracket(91));
    var_dump(IntlChar::getBidiPairedBracket('['));
    ?>

L'exemple ci-dessus va afficher :

    int(93)
    string(1) "]"

### Notes

> Note:

> Cette méthode est disponible depuis la version 52 d'ICU.

### Voir aussi

- IntlChar::charMirror() - Renvoie le caractère "image-miroir" pour un point de code
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET`
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE`

# IntlChar::getBlockCode

(PHP 7, PHP 8)

IntlChar::getBlockCode — Renvoie le bloc d'allocation Unicode contenant un point de code

### Description

public static function IntlChar::getBlockCode(int|string `$codepoint`): ?int

Renvoie le bloc d'allocation Unicode contenant le caractère.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie la valeur du bloc pour `codepoint`. Voir les constantes `IntlChar::BLOCK_CODE_*` pour les valeurs de retour possibles. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::getBlockCode("A") === IntlChar::BLOCK_CODE_BASIC_LATIN);
    var_dump(IntlChar::getBlockCode("Φ") === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getBlockCode("\u{2603}") === IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(true)

# IntlChar::getCombiningClass

(PHP 7, PHP 8)

IntlChar::getCombiningClass — Renvoie la classe de combinaison d'un point de code

### Description

public static function IntlChar::getCombiningClass(int|string `$codepoint`): ?int

Renvoie la classe de combinaison du point de code.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie la classe de combinaison du caractère. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::getCombiningClass("A"));
    var_dump(IntlChar::getCombiningClass("\u{0334}"));
    var_dump(IntlChar::getCombiningClass("\u{0358}"));
    ?>

L'exemple ci-dessus va afficher :

    int(0)
    int(1)
    int(232)

# IntlChar::getFC_NFKC_Closure

(PHP 7, PHP 8)

IntlChar::getFC_NFKC_Closure — Renvoie la propriété FC_NFKC_Closure pour un point de code

### Description

public static function IntlChar::getFC_NFKC_Closure(int|string `$codepoint`): string|false|null

Renvoie la propriété FC_NFKC_Closure pour un caractère.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie la propriété FC_NFKC_Closure pour le `codepoint`, ou une chaîne vide s'il n'y en a pas. Renvoie `null` ou `false` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::getFC_NFKC_Closure("\u{2121}"));
    var_dump(IntlChar::getFC_NFKC_Closure("\u{1D2D}"));
    ?>

L'exemple ci-dessus va afficher :

    string(3) "tel"
    string(2) "æ"

# IntlChar::getIntPropertyMaxValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMaxValue — Renvoie la valeur maximale pour une propriété Unicode

### Description

public static function IntlChar::getIntPropertyMaxValue(int `$property`): int

Renvoie la valeur maximale pour une propriété Unicode énumérée/entière/binaire.

### Liste de paramètres

`property`
  La propriété Unicode à chercher (voir la constante `IntlChar::PROPERTY_*`).

### Valeurs de retour

La valeur maximale renvoyée par IntlChar::getIntPropertyValue() pour une propriété Unicode. `<=0` si le sélecteur de propriété est hors de portée.

### Exemples

Exemple #1 Test de différentes propriétés

    <?php
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMaxValue(999999999)); // Une valeur inventée
    ?>

L'exemple ci-dessus va afficher :

    int(22)
    int(166)
    int(1)
    int(-1)

### Voir aussi

- IntlChar::hasBinaryProperty() - Vérifie une propriété Unicode binaire pour un point de code
- IntlChar::getIntPropertyMinValue() - Renvoie la valeur minimale pour une propriété Unicode
- IntlChar::getIntPropertyValue() - Renvoie la valeur d'une propriété Unicode pour un point de code
- IntlChar::getUnicodeVersion() - Renvoie la version Unicode

# IntlChar::getIntPropertyMinValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMinValue — Renvoie la valeur minimale pour une propriété Unicode

### Description

public static function IntlChar::getIntPropertyMinValue(int `$property`): int

Renvoie la valeur minimale pour une propriété Unicode énumérée/entière/binaire.

### Liste de paramètres

`property`
  La propriété Unicode à chercher (voir la constante `IntlChar::PROPERTY_*`).

### Valeurs de retour

La valeur minimale renvoyée par IntlChar::getIntPropertyValue() pour une propriété Unicode. `0` si le sélecteur de propriété est hors de portée.

### Exemples

Exemple #1 Test de différentes propriétés

    <?php
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMinValue(999999999)); // Une valeur inventée
    ?>

L'exemple ci-dessus va afficher :

    int(0)
    int(0)
    int(0)
    int(0)

### Voir aussi

- IntlChar::hasBinaryProperty() - Vérifie une propriété Unicode binaire pour un point de code
- IntlChar::getIntPropertyMaxValue() - Renvoie la valeur maximale pour une propriété Unicode
- IntlChar::getIntPropertyValue() - Renvoie la valeur d'une propriété Unicode pour un point de code
- IntlChar::getUnicodeVersion() - Renvoie la version Unicode

# IntlChar::getIntPropertyValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyValue — Renvoie la valeur d'une propriété Unicode pour un point de code

### Description

public static function IntlChar::getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int

Renvoie la valeur d'une propriété Unicode énumérée ou entière pour un point de code. Renvoie également les valeurs de propriété binaire et de masque.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)
`property`
  La propriété Unicode à chercher (voir la constante `IntlChar::PROPERTY_*`).

### Valeurs de retour

Renvoie la valeur numérique qui est directement la valeur de la propriété ou, pour les propriétés énumérées, correspond à la valeur numérique de la constante énumérée du type d'énumération de valeur de propriété respective. Renvoie `null` en cas d'échec.

Renvoie `0` ou `1` (pour `false`/`true`) pour les propriétés binaires Unicode.

Renvoie un masque de bits pour les propriétés de masque.

Renvoie `0` si `property` est hors de portée ou si la version Unicode n'a pas de données pour la propriété, ou pas pour ce point de code.

### Exemples

Exemple #1 Test de différentes propriétés

    <?php
    var_dump(IntlChar::getIntPropertyValue("A", IntlChar::PROPERTY_ALPHABETIC) === 1);
    var_dump(IntlChar::getIntPropertyValue("[", IntlChar::PROPERTY_BIDI_MIRRORED) === 1);
    var_dump(IntlChar::getIntPropertyValue("Φ", IntlChar::PROPERTY_BLOCK) === IntlChar::BLOCK_CODE_GREEK);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(true)

### Voir aussi

- IntlChar::hasBinaryProperty() - Vérifie une propriété Unicode binaire pour un point de code
- IntlChar::getIntPropertyMinValue() - Renvoie la valeur minimale pour une propriété Unicode
- IntlChar::getIntPropertyMaxValue() - Renvoie la valeur maximale pour une propriété Unicode
- IntlChar::getUnicodeVersion() - Renvoie la version Unicode

# IntlChar::getNumericValue

(PHP 7, PHP 8)

IntlChar::getNumericValue — Renvoie la valeur numérique d'un point de code Unicode

### Description

public static function IntlChar::getNumericValue(int|string `$codepoint`): ?float

Renvoie la valeur numérique d'un point de code Unicode telle que définie dans la base de données de caractères Unicode.

Pour les caractères sans aucune valeur numérique dans la base de données de caractères Unicode, cette fonction renverra `IntlChar::NO_NUMERIC_VALUE`.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

La valeur numérique du `codepoint`, ou `IntlChar::NO_NUMERIC_VALUE` si aucune n'est définie. Cette constante a été ajoutée dans PHP 7.0.6, avant cette version la valeur littérale (float)`-123456789` peut être utilisée à la place. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::getNumericValue("4"));
    var_dump(IntlChar::getNumericValue("x"));
    var_dump(IntlChar::getNumericValue("\u{216C}"));
    ?>

L'exemple ci-dessus va afficher :

    float(4)
    float(-123456789)
    float(50)

# IntlChar::getPropertyEnum

(PHP 7, PHP 8)

IntlChar::getPropertyEnum — Renvoie la valeur de la constante de propriété pour un nom de propriété donné

### Description

public static function IntlChar::getPropertyEnum(string `$alias`): int

Renvoie la valeur de la constante de propriété pour un nom de propriété donné, tel que spécifié dans le fichier de base de données Unicode PropertyAliases.txt. Les variantes courtes, longues et autres sont reconnues.

De plus, cette fonction mappe les noms synthétiques "gcm" / "General_Category_Mask" à la propriété `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`. Ces noms ne sont pas dans PropertyAliases.txt.

Cette fonction complète IntlChar::getPropertyName().

### Liste de paramètres

`alias`

  Le nom de la propriété à rechercher. Le nom est comparé en utilisant une "correspondance lâche" comme décrit dans PropertyAliases.txt.

### Valeurs de retour

Renvoie une valeur de constante `IntlChar::PROPERTY_`, ou `IntlChar::PROPERTY_INVALID_CODE` si le nom donné ne correspond à aucune propriété.

### Exemples

Exemple #1 Test de différentes propriétés

    <?php
    var_dump(IntlChar::getPropertyEnum('Bidi_Class') === IntlChar::PROPERTY_BIDI_CLASS);
    var_dump(IntlChar::getPropertyEnum('script') === IntlChar::PROPERTY_SCRIPT);
    var_dump(IntlChar::getPropertyEnum('IDEOGRAPHIC') === IntlChar::PROPERTY_IDEOGRAPHIC);
    var_dump(IntlChar::getPropertyEnum('Some made-up string') === IntlChar::PROPERTY_INVALID_CODE);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Voir aussi

- IntlChar::getPropertyName() - Renvoie le nom Unicode d'une propriété

# IntlChar::getPropertyName

(PHP 7, PHP 8)

IntlChar::getPropertyName — Renvoie le nom Unicode d'une propriété

### Description

public static function IntlChar::getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Renvoie le nom Unicode d'une propriété donnée, tel qu'il est donné dans le fichier de base de données Unicode PropertyAliases.txt.

De plus, cette fonction mappe la propriété `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` sur les noms synthétiques "gcm" / "General_Category_Mask". Ces noms ne sont pas dans PropertyAliases.txt.

Cette fonction complète IntlChar::getPropertyEnum().

### Liste de paramètres

`property`
  La propriété Unicode à chercher (voir la constante `IntlChar::PROPERTY_*`).

  `IntlChar::PROPERTY_INVALID_CODE` ne doit pas être utilisé. De plus, si `property` est hors de portée, `false` est retourné.

`type`

  Le sélecteur pour le nom à obtenir. Si hors de portée, `false` est retourné.

  Toutes les propriétés ont un nom long. La plupart ont un nom court, mais certaines n'en ont pas. Unicode permet des noms supplémentaires; s'ils sont présents, ils seront retournés en ajoutant 1, 2, etc. à `IntlChar::LONG_PROPERTY_NAME`.

### Valeurs de retour

Renvoie le nom, ou `false` si soit `property` soit `type` est hors de portée.

Si un `type` donné retourne `false`, alors toutes les valeurs plus grandes de `type` retournent `false`, avec une exception : si `false` est retourné pour `IntlChar::SHORT_PROPERTY_NAME`, alors `IntlChar::LONG_PROPERTY_NAME` (et plus) peut encore retourner une valeur non-`false`.

### Exemples

Exemple #1 Test de différentes propriétés

    <?php
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME + 1));
    ?>

L'exemple ci-dessus va afficher :

    string(10) "Bidi_Class"
    string(2) "bc"
    string(10) "Bidi_Class"
    bool(false)

### Voir aussi

- IntlChar::getPropertyEnum() - Renvoie la valeur de la constante de propriété pour un nom de propriété donné

# IntlChar::getPropertyValueEnum

(PHP 7, PHP 8)

IntlChar::getPropertyValueEnum — Renvoie la valeur de propriété pour un nom de valeur donné

### Description

public static function IntlChar::getPropertyValueEnum(int `$property`, string `$name`): int

Renvoie la valeur de propriété entière pour un nom de valeur donné, tel que spécifié dans le fichier de base de données Unicode PropertyValueAliases.txt. Les variantes courtes, longues et autres sont reconnues.

> Note:

> Quelques noms dans PropertyValueAliases.txt ne seront reconnus qu'avec `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`, pas `IntlChar::PROPERTY_GENERAL_CATEGORY`. Ceux-ci incluent :

> - "C" / "Autre"
> - "L" / "Lettre"
> - "LC" / "Lettre_Majuscule"
> - "M" / "Marque"
> - "N" / "Nombre"
> - "P" / "Ponctuation"
> - "S" / "Symbole"
> - "Z" / "Séparateur"

### Liste de paramètres

`property`
  La propriété Unicode à chercher (voir la constante `IntlChar::PROPERTY_*`).

  Si hors de portée, ou si cette méthode ne fonctionne pas avec la valeur donnée, `IntlChar::PROPERTY_INVALID_CODE` est retourné.

`name`

  La valeur de nom à rechercher. Le nom est comparé en utilisant une "correspondance lâche" comme décrit dans PropertyValueAliases.txt.

### Valeurs de retour

Renvoie la valeur entière correspondante, ou `IntlChar::PROPERTY_INVALID_CODE` si le nom donné ne correspond à aucune valeur de la propriété donnée, ou si la propriété est invalide.

### Exemples

Exemple #1 Test de différentes propriétés

    <?php
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BLOCK, 'greek') === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'RIGHT_TO_LEFT') === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'some made-up string') === IntlChar::PROPERTY_INVALID_CODE);
    var_dump(IntlChar::getPropertyValueEnum(123456789, 'RIGHT_TO_LEFT') === IntlChar::PROPERTY_INVALID_CODE);
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::getPropertyValueName

(PHP 7, PHP 8)

IntlChar::getPropertyValueName — Renvoie le nom Unicode pour une valeur de propriété

### Description

public static function IntlChar::getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Renvoie le nom Unicode pour une valeur de propriété donnée, tel que donné dans le fichier de base de données Unicode PropertyValueAliases.txt.

> Note:

> Quelques noms dans PropertyValueAliases.txt ne peuvent être récupérés qu'en utilisant `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`, pas `IntlChar::PROPERTY_GENERAL_CATEGORY`. Ceux-ci incluent :

> - "C" / "Autre"
> - "L" / "Lettre"
> - "LC" / "Lettre_Majuscule"
> - "M" / "Marque"
> - "N" / "Nombre"
> - "P" / "Ponctuation"
> - "S" / "Symbole"
> - "Z" / "Séparateur"

### Liste de paramètres

`property`
  La propriété Unicode à chercher (voir la constante `IntlChar::PROPERTY_*`).

  Si hors de portée, ou si cette méthode ne fonctionne pas avec la valeur donnée, `false` est retourné.

`value`

  Le sélecteur pour une valeur pour la propriété donnée. Si hors de portée, `false` est retourné.

  En général, les valeurs valides vont de `0` jusqu'à un maximum. Il y a quelques exceptions :

  - `IntlChar::PROPERTY_BLOCK` les valeurs commencent à la valeur non-nulle `IntlChar::BLOCK_CODE_BASIC_LATIN`
  - `IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` les valeurs ne sont pas contiguës et vont de 0 à 240.
`type`

  Le sélecteur pour le nom à obtenir. Si hors de portée, `false` est retourné.

  Toutes les valeurs ont un nom long. La plupart ont un nom court, mais certaines n'en ont pas. Unicode permet des noms supplémentaires; s'ils sont présents, ils seront retournés en ajoutant 1, 2, etc. à `IntlChar::LONG_PROPERTY_NAME`.

### Valeurs de retour

Renvoie le nom, ou `false` si soit `property` soit `type` est hors de portée. Renvoie `null` en cas d'échec.

Si un `type` donné retourne `false`, alors toutes les valeurs plus grandes de `type` retourneront `false`, avec une exception : si `false` est retourné pour `IntlChar::SHORT_PROPERTY_NAME`, alors `IntlChar::LONG_PROPERTY_NAME` (et plus) peut encore retourner une valeur non-`false`.

### Exemples

Exemple #1 Test de différentes propriétés

    <?php
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME + 1));
    ?>

L'exemple ci-dessus va afficher :

    string(16) "Greek_And_Coptic"
    string(5) "Greek"
    string(16) "Greek_And_Coptic"
    bool(false)

# IntlChar::getUnicodeVersion

(PHP 7, PHP 8)

IntlChar::getUnicodeVersion — Renvoie la version Unicode

### Description

public static function IntlChar::getUnicodeVersion(): array

Renvoie les informations de version Unicode.

Le tableau de version est rempli avec les informations de version pour la norme Unicode actuellement utilisée par ICU. Par exemple, la version Unicode 3.1.1 est représentée par un tableau avec les valeurs `[3, 1, 1, 0]`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau contenant le numéro de version Unicode.

### Exemples

Exemple #1 Test de différentes propriétés

    <?php
    var_dump(IntlChar::getUnicodeVersion());
    ?>

L'exemple ci-dessus va afficher :

    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Voir aussi

- IntlChar::charAge() - Renvoie l'"âge" du point de code

# IntlChar::hasBinaryProperty

(PHP 7, PHP 8)

IntlChar::hasBinaryProperty — Vérifie une propriété Unicode binaire pour un point de code

### Description

public static function IntlChar::hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool

Vérifie une propriété Unicode binaire pour un point de code.

Unicode, en particulier dans la version 3.2, définit beaucoup plus de propriétés que l'ensemble original dans UnicodeData.txt.

Les API de propriétés sont destinées à refléter les propriétés Unicode telles que définies dans la base de données de caractères Unicode (UCD) et les rapports techniques Unicode (UTR). Pour plus de détails sur les propriétés, voir » http://www.unicode.org/ucd/. Pour les noms des propriétés Unicode, voir le fichier UCD PropertyAliases.txt.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)
`property`
  La propriété Unicode à chercher (voir la constante `IntlChar::PROPERTY_*`).

### Valeurs de retour

Renvoie `true` ou `false` selon la valeur de la propriété Unicode binaire pour `codepoint`. Renvoie également `false` si `property` est hors de portée ou si la version Unicode n'a pas de données pour la propriété du tout, ou pas pour ce point de code. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différentes propriétés

    <?php
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_BIDI_MIRRORED));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_BIDI_MIRRORED));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Voir aussi

- IntlChar::getIntPropertyValue() - Renvoie la valeur d'une propriété Unicode pour un point de code
- IntlChar::getUnicodeVersion() - Renvoie la version Unicode

# IntlChar::isalnum

(PHP 7, PHP 8)

IntlChar::isalnum — Vérifie si un point de code est un caractère alphanumérique

### Description

public static function IntlChar::isalnum(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère alphanumérique (lettre ou chiffre). `true` pour les caractères avec les catégories générales "L" (lettres) et "Nd" (chiffres décimaux).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère alphanumérique, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isalnum("A"));
    var_dump(IntlChar::isalnum("1"));
    var_dump(IntlChar::isalnum("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)

### Voir aussi

- IntlChar::isalpha() - Vérifie si un point de code est un caractère alphabétique
- IntlChar::isdigit() - Vérifie si un point de code est un chiffre
- ctype_alnum() - Vérifie qu'une chaîne est alphanumérique

# IntlChar::isalpha

(PHP 7, PHP 8)

IntlChar::isalpha — Vérifie si un point de code est un caractère alphabétique

### Description

public static function IntlChar::isalpha(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère alphabétique. `true` pour les catégories générales "L" (lettres).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère alphabétique, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isalpha("A"));
    var_dump(IntlChar::isalpha("1"));
    var_dump(IntlChar::isalpha("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::isalnum() - Vérifie si un point de code est un caractère alphanumérique
- IntlChar::isdigit() - Vérifie si un point de code est un chiffre
- ctype_alpha() - Vérifie qu'une chaîne est alphabétique

# IntlChar::isbase

(PHP 7, PHP 8)

IntlChar::isbase — Vérifie si un point de code est un caractère de base

### Description

public static function IntlChar::isbase(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère de base. `true` pour les catégories générales "L" (lettres), "N" (nombres), "Mc" (marques de combinaison d'espacement), et "Me" (marques d'encadrement).

> Note:

> Cela diffère de la définition Unicode dans le chapitre 3.5, clause de conformité D13, qui définit les caractères de base comme tous les caractères (pas Cn) qui ne se combinent pas graphiquement avec les caractères précédents (M) et qui ne sont ni des caractères de contrôle (Cc) ni des caractères de format (Cf).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère de base, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isbase("A"));
    var_dump(IntlChar::isbase("1"));
    var_dump(IntlChar::isbase("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)

### Voir aussi

- IntlChar::isalpha() - Vérifie si un point de code est un caractère alphabétique
- IntlChar::isdigit() - Vérifie si un point de code est un chiffre

# IntlChar::isblank

(PHP 7, PHP 8)

IntlChar::isblank — Vérifie si un point de code est un caractère "blanc" ou "espace horizontal"

### Description

public static function IntlChar::isblank(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère "blanc" ou "espace horizontal", un caractère qui sépare visuellement les mots sur une ligne.

Les définitions suivantes sont équivalentes:

- `true` pour les caractères Unicode White_Space à l'exception des "contrôles d'espacement vertical" où les "contrôles d'espacement vertical" sont les caractères suivants: U+000A (LF) U+000B (VT) U+000C (FF) U+000D (CR) U+0085 (NEL) U+2028 (LS) U+2029 (PS)
- `true` pour U+0009 (TAB) et les caractères de catégorie générale "Zs" (séparateurs d'espaces) à l'exception de l'espace de largeur zéro (ZWSP, U+200B).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère "blanc" ou "espace horizontal", `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isblank("A"));
    var_dump(IntlChar::isblank(" "));
    var_dump(IntlChar::isblank("\t"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(true)

### Voir aussi

- IntlChar::isspace() - Vérifie si un point de code est un caractère d'espace
- IntlChar::isJavaSpaceChar() - Vérifie si un point de code est un caractère d'espace selon Java
- IntlChar::isUWhiteSpace() - Vérifie si un point de code a la propriété Unicode White_Space
- IntlChar::isWhitespace() - Vérifie si un point de code est un caractère d'espace selon ICU

# IntlChar::iscntrl

(PHP 7, PHP 8)

IntlChar::iscntrl — Vérifie si un point de code est un caractère de contrôle

### Description

public static function IntlChar::iscntrl(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère de contrôle.

Un caractère de contrôle est l'un des suivants:

- Caractère de contrôle ISO 8 bits (U+0000..U+001f et U+007f..U+009f)
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR` (Cc)
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR` (Cf)
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` (Zl)
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` (Zp)

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère de contrôle, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::iscntrl("A"));
    var_dump(IntlChar::iscntrl(" "));
    var_dump(IntlChar::iscntrl("\n"));
    var_dump(IntlChar::iscntrl("\u{200e}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(false)
    bool(true)
    bool(true)

### Voir aussi

- IntlChar::isprint() - Vérifie si un point de code est un caractère affichable
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_cntrl() - Vérifie qu'un caractère est un caractère de contrôle

# IntlChar::isdefined

(PHP 7, PHP 8)

IntlChar::isdefined — Vérifie si un point de code est défini

### Description

public static function IntlChar::isdefined(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est "défini", ce qui signifie généralement qu'il est assigné à un caractère.

`true` pour les catégories générales autres que "Cn" (autre, non assigné).

> Note:

> Il est à noter que les points de code non caractères (par exemple, U+FDD0) ne sont pas "définis" (ils sont Cn), mais les points de code de substitution sont "définis" (Cs).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère défini, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isdefined("A"));
    var_dump(IntlChar::isdefined(" "));
    var_dump(IntlChar::isdefined("\u{FDD0}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)

### Voir aussi

- IntlChar::isdigit() - Vérifie si un point de code est un chiffre
- IntlChar::isalpha() - Vérifie si un point de code est un caractère alphabétique
- IntlChar::isalnum() - Vérifie si un point de code est un caractère alphanumérique
- IntlChar::isupper() - Vérifie si un point de code a la catégorie générale "Lu" (lettre majuscule)
- IntlChar::islower() - Vérifie si un point de code est une lettre minuscule
- IntlChar::istitle() - Vérifie si un point de code est une lettre en titre

# IntlChar::isdigit

(PHP 7, PHP 8)

IntlChar::isdigit — Vérifie si un point de code est un chiffre

### Description

public static function IntlChar::isdigit(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un chiffre.

`true` pour les caractères de catégorie générale "Nd" (chiffres décimaux). À partir de Unicode 4, c'est la même chose que de tester le Type_Numeric de Décimal.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un chiffre, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isdigit("A"));
    var_dump(IntlChar::isdigit("1"));
    var_dump(IntlChar::isdigit("\t"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(false)

### Voir aussi

- IntlChar::isalpha() - Vérifie si un point de code est un caractère alphabétique
- IntlChar::isalnum() - Vérifie si un point de code est un caractère alphanumérique
- IntlChar::isxdigit() - Vérifie si un point de code est un chiffre hexadécimal
- ctype_digit() - Vérifie qu'une chaîne est un entier

# IntlChar::isgraph

(PHP 7, PHP 8)

IntlChar::isgraph — Vérifie si un point de code est un caractère graphique

### Description

public static function IntlChar::isgraph(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère "graphique" (affichable, à l'exclusion des espaces).

`true` pour tous les caractères sauf ceux avec les catégories générales "Cc" (codes de contrôle), "Cf" (contrôles de format), "Cs" (substituts), "Cn" (non assignés) et "Z" (séparateurs).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère "graphique", `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isgraph("A"));
    var_dump(IntlChar::isgraph("1"));
    var_dump(IntlChar::isgraph("\u{2603}"));
    var_dump(IntlChar::isgraph("\n"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Voir aussi

- ctype_graph() - Vérifie qu'une chaîne contient des caractères imprimables sauf l'espace

# IntlChar::isIDIgnorable

(PHP 7, PHP 8)

IntlChar::isIDIgnorable — Vérifie si un point de code est un caractère ignoré

### Description

public static function IntlChar::isIDIgnorable(int|string `$codepoint`): ?bool

Détermine si le caractère spécifié doit être considéré comme un caractère ignoré dans un identifiant.

`true` pour les caractères de catégorie générale "Cf" (contrôles de format) ainsi que les contrôles ISO non espaces (U+0000..U+0008, U+000E..U+001B, U+007F..U+009F).

> Note:

> Il est à noter que Unicode recommande simplement d'ignorer Cf (contrôles de format).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est ignoré dans les identifiants, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isIDIgnorable("A"));
    var_dump(IntlChar::isIDIgnorable(" "));
    var_dump(IntlChar::isIDIgnorable("\u{007F}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(false)
    bool(true)

### Voir aussi

- IntlChar::isIDStart() - Vérifie si un point de code est permis comme premier caractère dans un identifiant
- IntlChar::isIDPart() - Vérifie si un point de code est permis dans un identifiant
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`

# IntlChar::isIDPart

(PHP 7, PHP 8)

IntlChar::isIDPart — Vérifie si un point de code est permis dans un identifiant

### Description

public static function IntlChar::isIDPart(int|string `$codepoint`): ?bool

Détermine si le caractère spécifié est permis dans un identifiant.

`true` pour les caractères de catégories générales "L" (lettres), "Nl" (chiffres lettres), "Nd" (chiffres décimaux), "Mc" et "Mn" (marques de combinaison), "Pc" (ponctuation de connexion), et u_isIDIgnorable(c).

> Note:

> Ceci est presque la même chose que ID_Continue de Unicode (`IntlChar::PROPERTY_ID_CONTINUE`) sauf que Unicode recommande d'ignorer Cf qui est inférieur à IntlChar::isIDIgnorable().

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` peut apparaître dans un identifiant, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isIDPart("A"));
    var_dump(IntlChar::isIDPart("$"));
    var_dump(IntlChar::isIDPart("\n"));
    var_dump(IntlChar::isIDPart("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::isIDIgnorable() - Vérifie si un point de code est un caractère ignoré
- IntlChar::isIDStart() - Vérifie si un point de code est permis comme premier caractère dans un identifiant
- `IntlChar::PROPERTY_ID_CONTINUE`

# IntlChar::isIDStart

(PHP 7, PHP 8)

IntlChar::isIDStart — Vérifie si un point de code est permis comme premier caractère dans un identifiant

### Description

public static function IntlChar::isIDStart(int|string `$codepoint`): ?bool

Détermine si le caractère spécifié est permis comme premier caractère dans un identifiant selon Unicode (The Unicode Standard, Version 3.0, chapitre 5.16 Identifiants).

`true` pour les caractères de catégorie générale "L" (lettres) et "Nl" (chiffres lettres).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` peut commencer un identifiant, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isIDStart("A"));
    var_dump(IntlChar::isIDStart("$"));
    var_dump(IntlChar::isIDStart("\n"));
    var_dump(IntlChar::isIDStart("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::isalpha() - Vérifie si un point de code est un caractère alphabétique
- IntlChar::isIDPart() - Vérifie si un point de code est permis dans un identifiant
- `IntlChar::PROPERTY_ID_START`

# IntlChar::isISOControl

(PHP 7, PHP 8)

IntlChar::isISOControl — Vérifie si un point de code est un caractère de contrôle ISO

### Description

public static function IntlChar::isISOControl(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un code de contrôle ISO.

`true` pour U+0000..U+001f et U+007f..U+009f (catégorie générale "Cc").

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un code de contrôle ISO, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isISOControl(" "));
    var_dump(IntlChar::isISOControl("\n"));
    var_dump(IntlChar::isISOControl("\u{200e}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(false)

### Voir aussi

- IntlChar::iscntrl() - Vérifie si un point de code est un caractère de contrôle

# IntlChar::isJavaIDPart

(PHP 7, PHP 8)

IntlChar::isJavaIDPart — Vérifie si un point de code est permis dans un identifiant Java

### Description

public static function IntlChar::isJavaIDPart(int|string `$codepoint`): ?bool

Détermine si le caractère spécifié est permis dans un identifiant Java.

En plus de IntlChar::isIDPart(), `true` pour les caractères de catégorie générale "Sc" (symboles de devise).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` peut apparaître dans un identifiant Java, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isJavaIDPart("A"));
    var_dump(IntlChar::isJavaIDPart("$"));
    var_dump(IntlChar::isJavaIDPart("\n"));
    var_dump(IntlChar::isJavaIDPart("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::isIDIgnorable() - Vérifie si un point de code est un caractère ignoré
- IntlChar::isIDPart() - Vérifie si un point de code est permis dans un identifiant
- IntlChar::isJavaIDStart() - Vérifie si un point de code est permis comme premier caractère dans un identifiant Java
- IntlChar::isalpha() - Vérifie si un point de code est un caractère alphabétique
- IntlChar::isdigit() - Vérifie si un point de code est un chiffre

# IntlChar::isJavaIDStart

(PHP 7, PHP 8)

IntlChar::isJavaIDStart — Vérifie si un point de code est permis comme premier caractère dans un identifiant Java

### Description

public static function IntlChar::isJavaIDStart(int|string `$codepoint`): ?bool

Détermine si le caractère spécifié est permis comme premier caractère dans un identifiant Java.

En plus de IntlChar::isIDStart(), `true` pour les caractères de catégorie générale "Sc" (symboles de devise) et "Pc" (ponctuation de connexion).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` peut commencer un identifiant Java, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isJavaIDStart("A"));
    var_dump(IntlChar::isJavaIDStart("$"));
    var_dump(IntlChar::isJavaIDStart("\n"));
    var_dump(IntlChar::isJavaIDStart("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::isIDStart() - Vérifie si un point de code est permis comme premier caractère dans un identifiant
- IntlChar::isJavaIDPart() - Vérifie si un point de code est permis dans un identifiant Java
- IntlChar::isalpha() - Vérifie si un point de code est un caractère alphabétique

# IntlChar::isJavaSpaceChar

(PHP 7, PHP 8)

IntlChar::isJavaSpaceChar — Vérifie si un point de code est un caractère d'espace selon Java

### Description

public static function IntlChar::isJavaSpaceChar(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère d'espace selon Java.

`true` pour les caractères de catégorie générale "Z" (séparateurs), ce qui n'inclut pas les codes de contrôle (par exemple, TAB ou Line Feed).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère d'espace selon Java, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isJavaSpaceChar("A"));
    var_dump(IntlChar::isJavaSpaceChar(" "));
    var_dump(IntlChar::isJavaSpaceChar("\n"));
    var_dump(IntlChar::isJavaSpaceChar("\t"));
    var_dump(IntlChar::isJavaSpaceChar("\u{00A0}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Voir aussi

- IntlChar::isspace() - Vérifie si un point de code est un caractère d'espace
- IntlChar::isWhitespace() - Vérifie si un point de code est un caractère d'espace selon ICU
- IntlChar::isUWhiteSpace() - Vérifie si un point de code a la propriété Unicode White_Space

# IntlChar::islower

(PHP 7, PHP 8)

IntlChar::islower — Vérifie si un point de code est une lettre minuscule

### Description

public static function IntlChar::islower(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié a la catégorie générale "Ll" (lettre minuscule).

> Note:

> Cela manque certains caractères qui sont également en minuscules mais ont une valeur de catégorie générale différente. Pour les inclure, utiliser IntlChar::isULowercase().

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est une lettre minuscule, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::islower("A"));
    var_dump(IntlChar::islower("a"));
    var_dump(IntlChar::islower("Φ"));
    var_dump(IntlChar::islower("φ"));
    var_dump(IntlChar::islower("1"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Voir aussi

- IntlChar::isupper() - Vérifie si un point de code a la catégorie générale "Lu" (lettre majuscule)
- IntlChar::istitle() - Vérifie si un point de code est une lettre en titre
- IntlChar::tolower() - Rend un caractère Unicode en minuscule
- IntlChar::toupper() - Rend un caractère Unicode en majuscule
- `IntlChar::PROPERTY_LOWERCASE`
- ctype_lower() - Vérifie qu'une chaîne est en minuscules

# IntlChar::isMirrored

(PHP 7, PHP 8)

IntlChar::isMirrored — Vérifie si un point de code a la propriété Bidi_Mirrored

### Description

public static function IntlChar::isMirrored(int|string `$codepoint`): ?bool

Détermine si le point de code a la propriété Bidi_Mirrored.

Cette propriété est définie pour les caractères qui sont couramment utilisés dans des contextes de droite à gauche et qui doivent être affichés avec un glyphe "miroir".

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` a la propriété Bidi_Mirrored, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isMirrored("A"));
    var_dump(IntlChar::isMirrored("<"));
    var_dump(IntlChar::isMirrored("("));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(true)

### Voir aussi

- IntlChar::charMirror() - Renvoie le caractère "image-miroir" pour un point de code
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::isprint

(PHP 7, PHP 8)

IntlChar::isprint — Vérifie si un point de code est un caractère affichable

### Description

public static function IntlChar::isprint(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère affichable.

`true` pour les catégories générales autres que "C" (contrôles).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère affichable, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isprint("A"));
    var_dump(IntlChar::isprint(" "));
    var_dump(IntlChar::isprint("\n"));
    var_dump(IntlChar::isprint("\u{200e}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::iscntrl() - Vérifie si un point de code est un caractère de contrôle
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_print() - Vérifie qu'une chaîne est imprimable

# IntlChar::ispunct

(PHP 7, PHP 8)

IntlChar::ispunct — Vérifie si un point de code est un caractère de ponctuation

### Description

public static function IntlChar::ispunct(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère de ponctuation.

`true` pour les caractères de catégorie générale "P" (ponctuation).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère de ponctuation, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::ispunct("."));
    var_dump(IntlChar::ispunct(","));
    var_dump(IntlChar::ispunct("\n"));
    var_dump(IntlChar::ispunct("$"));

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Voir aussi

- ctype_punct() - Vérifie qu'une chaîne contient de la ponctuation

# IntlChar::isspace

(PHP 7, PHP 8)

IntlChar::isspace — Vérifie si un point de code est un caractère d'espace

### Description

public static function IntlChar::isspace(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère d'espace.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère d'espace, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isspace("A"));
    var_dump(IntlChar::isspace(" "));
    var_dump(IntlChar::isspace("\n"));
    var_dump(IntlChar::isspace("\t"));
    var_dump(IntlChar::isspace("\u{00A0}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Voir aussi

- IntlChar::isJavaSpaceChar() - Vérifie si un point de code est un caractère d'espace selon Java
- IntlChar::isWhitespace() - Vérifie si un point de code est un caractère d'espace selon ICU
- IntlChar::isUWhiteSpace() - Vérifie si un point de code a la propriété Unicode White_Space
- ctype_space() - Vérifie qu'une chaîne n'est faite que de caractères blancs

# IntlChar::istitle

(PHP 7, PHP 8)

IntlChar::istitle — Vérifie si un point de code est une lettre en titre

### Description

public static function IntlChar::istitle(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est une lettre en titre.

`true` pour la catégorie générale "Lt" (lettre en titre).

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est une lettre en titre, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    // Lettre latine en majuscule Dz avec caron U+01C4
    var_dump(IntlChar::istitle("Ǆ"));
    // Lettre latine en majuscule D avec petite lettre Z avec caron U+01C5
    var_dump(IntlChar::istitle("ǅ"));
    // Lettre latine en minuscule Dz avec caron U+01C6
    var_dump(IntlChar::istitle("ǆ"));

    // Lettre grecque en majuscule Alpha avec prosgegrammeni U+1FBC
    var_dump(IntlChar::istitle("ᾼ"));
    // Lettre grecque en minuscule Alpha avec ypogegrammeni U+1FB3
    var_dump(IntlChar::istitle("ᾳ"));
    // Lettre grecque en majuscule Alpha U+0391
    var_dump(IntlChar::istitle("Α"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::isupper() - Vérifie si un point de code a la catégorie générale "Lu" (lettre majuscule)
- IntlChar::islower() - Vérifie si un point de code est une lettre minuscule
- IntlChar::totitle() - Rend un caractère Unicode en lettre de titre

# IntlChar::isUAlphabetic

(PHP 7, PHP 8)

IntlChar::isUAlphabetic — Vérifie si un point de code a la propriété Unicode Alphabetic

### Description

public static function IntlChar::isUAlphabetic(int|string `$codepoint`): ?bool

Vérifie si un point de code a la propriété Unicode Alphabetic.

Ceci est identique à `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_ALPHABETIC)`

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` a la propriété Unicode Alphabetic, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isUAlphabetic("A"));
    var_dump(IntlChar::isUAlphabetic("1"));
    var_dump(IntlChar::isUAlphabetic("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::isalpha() - Vérifie si un point de code est un caractère alphabétique
- IntlChar::hasBinaryProperty() - Vérifie une propriété Unicode binaire pour un point de code
- `IntlChar::PROPERTY_ALPHABETIC`

# IntlChar::isULowercase

(PHP 7, PHP 8)

IntlChar::isULowercase — Vérifie si un point de code a la propriété Unicode Lowercase

### Description

public static function IntlChar::isULowercase(int|string `$codepoint`): ?bool

Vérifie si un point de code a la propriété Unicode Lowercase.

Ceci est identique à `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_LOWERCASE)`

> Note:

> Ceci est différent de IntlChar::islower() et renverra `true` pour plus de caractères.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` a la propriété Unicode Lowercase, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isULowercase("A"));
    var_dump(IntlChar::isULowercase("a"));
    var_dump(IntlChar::isULowercase("Φ"));
    var_dump(IntlChar::isULowercase("φ"));
    var_dump(IntlChar::isULowercase("1"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Voir aussi

- IntlChar::islower() - Vérifie si un point de code est une lettre minuscule
- IntlChar::hasBinaryProperty() - Vérifie une propriété Unicode binaire pour un point de code
- `IntlChar::PROPERTY_LOWERCASE`

# IntlChar::isupper

(PHP 7, PHP 8)

IntlChar::isupper — Vérifie si un point de code a la catégorie générale "Lu" (lettre majuscule)

### Description

public static function IntlChar::isupper(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié a la catégorie générale "Lu" (lettre majuscule).

> Note:

> Ceci manque certains caractères qui sont également en majuscules mais ont une valeur de catégorie générale différente. Pour les inclure, utiliser IntlChar::isUUppercase().

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est une lettre majuscule, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isupper("A"));
    var_dump(IntlChar::isupper("a"));
    var_dump(IntlChar::isupper("Φ"));
    var_dump(IntlChar::isupper("φ"));
    var_dump(IntlChar::isupper("1"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::islower() - Vérifie si un point de code est une lettre minuscule
- IntlChar::istitle() - Vérifie si un point de code est une lettre en titre
- IntlChar::tolower() - Rend un caractère Unicode en minuscule
- IntlChar::toupper() - Rend un caractère Unicode en majuscule
- `IntlChar::PROPERTY_UPPERCASE`
- ctype_upper() - Vérifie qu'une chaîne est en majuscules

# IntlChar::isUUppercase

(PHP 7, PHP 8)

IntlChar::isUUppercase — Vérifie si un point de code a la propriété Unicode Uppercase

### Description

public static function IntlChar::isUUppercase(int|string `$codepoint`): ?bool

Vérifie si un point de code a la propriété Unicode Uppercase.

Ceci est identique à `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_UPPERCASE)`

> Note:

> Ceci est différent de IntlChar::isupper() et renverra `true` pour plus de caractères.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` a la propriété Unicode Uppercase, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isUUppercase("A"));
    var_dump(IntlChar::isUUppercase("a"));
    var_dump(IntlChar::isUUppercase("Φ"));
    var_dump(IntlChar::isUUppercase("φ"));
    var_dump(IntlChar::isUUppercase("1"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Voir aussi

- IntlChar::isupper() - Vérifie si un point de code a la catégorie générale "Lu" (lettre majuscule)
- IntlChar::hasBinaryProperty() - Vérifie une propriété Unicode binaire pour un point de code
- `IntlChar::PROPERTY_UPPERCASE`

# IntlChar::isUWhiteSpace

(PHP 7, PHP 8)

IntlChar::isUWhiteSpace — Vérifie si un point de code a la propriété Unicode White_Space

### Description

public static function IntlChar::isUWhiteSpace(int|string `$codepoint`): ?bool

Vérifie si un point de code a la propriété Unicode White_Space.

Ceci est identique à `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_WHITE_SPACE)`

> Note:

> Ceci est différent de IntlChar::isspace() et de IntlChar::isWhitespace().

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` a la propriété Unicode White_Space, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isUWhiteSpace("A"));
    var_dump(IntlChar::isUWhiteSpace(" "));
    var_dump(IntlChar::isUWhiteSpace("\n"));
    var_dump(IntlChar::isUWhiteSpace("\t"));
    var_dump(IntlChar::isUWhiteSpace("\u{00A0}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Voir aussi

- IntlChar::isspace() - Vérifie si un point de code est un caractère d'espace
- IntlChar::isWhitespace() - Vérifie si un point de code est un caractère d'espace selon ICU
- IntlChar::isJavaSpaceChar() - Vérifie si un point de code est un caractère d'espace selon Java
- IntlChar::hasBinaryProperty() - Vérifie une propriété Unicode binaire pour un point de code
- `IntlChar::PROPERTY_WHITE_SPACE`

# IntlChar::isWhitespace

(PHP 7, PHP 8)

IntlChar::isWhitespace — Vérifie si un point de code est un caractère d'espace selon ICU

### Description

public static function IntlChar::isWhitespace(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un caractère d'espace selon ICU.

Un caractère est considéré comme un caractère d'espace ICU si et seulement s'il satisfait un des critères suivants :

- Si c'est un caractère d'espace Unicode (catégories "Z" = "Zs" ou "Zl" ou "Zp"), mais n'est pas un espace insécable (U+00A0 NBSP ou U+2007 Figure Space ou U+202F Narrow NBSP).
- Si c'est U+0009 HORIZONTAL TABULATION.
- Si c'est U+000A LINE FEED.
- Si c'est U+000B VERTICAL TABULATION.
- Si c'est U+000C FORM FEED.
- Si c'est U+000D CARRIAGE RETURN.
- Si c'est U+001C FILE SEPARATOR.
- Si c'est U+001D GROUP SEPARATOR.
- Si c'est U+001E RECORD SEPARATOR.
- Si c'est U+001F UNIT SEPARATOR.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un caractère d'espace selon ICU, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::iswhitespace("A"));
    var_dump(IntlChar::iswhitespace(" "));
    var_dump(IntlChar::iswhitespace("\n"));
    var_dump(IntlChar::iswhitespace("\t"));
    var_dump(IntlChar::iswhitespace("\u{00A0}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Voir aussi

- IntlChar::isspace() - Vérifie si un point de code est un caractère d'espace
- IntlChar::isJavaSpaceChar() - Vérifie si un point de code est un caractère d'espace selon Java
- IntlChar::isUWhiteSpace() - Vérifie si un point de code a la propriété Unicode White_Space

# IntlChar::isxdigit

(PHP 7, PHP 8)

IntlChar::isxdigit — Vérifie si un point de code est un chiffre hexadécimal

### Description

public static function IntlChar::isxdigit(int|string `$codepoint`): ?bool

Détermine si le point de code spécifié est un chiffre hexadécimal.

`true` pour les caractères de catégorie générale "Nd" (chiffres décimaux) ainsi que les lettres latines a-f et A-F en ASCII et ASCII complet. (C'est-à-dire pour les lettres avec des points de code 0041..0046, 0061..0066, FF21..FF26, FF41..FF46.)

Ceci est équivalent à `IntlChar::digit($codepoint, 16) >= 0`.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie `true` si `codepoint` est un chiffre hexadécimal, `false` sinon. Renvoie `null` en cas d'échec.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::isxdigit("A"));
    var_dump(IntlChar::isxdigit("1"));
    var_dump(IntlChar::isxdigit("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(true)
    bool(false)

### Notes

> Note:

> Pour restreindre la définition des chiffres hexadécimaux uniquement aux caractères ASCII, utiliser :

>     <?php
>     $isASCIIHexadecimal = IntlChar::ord($codepoint) <= 0x7F && IntlChar::isxdigit($codepoint);
>     ?>

### Voir aussi

- IntlChar::isdigit() - Vérifie si un point de code est un chiffre
- ctype_xdigit() - Vérifie qu'un caractère représente un nombre hexadécimal

# IntlChar::ord

(PHP 7, PHP 8)

IntlChar::ord — Renvoie la valeur du point de code Unicode d'un caractère

### Description

public static function IntlChar::ord(int|string `$character`): ?int

Renvoie la valeur du point de code Unicode du caractère donné.

Cette fonction complète IntlChar::chr().

### Liste de paramètres

`character`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie la valeur du point de code Unicode sous forme d'entier.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::ord("A"));
    var_dump(IntlChar::ord(" "));
    var_dump(IntlChar::ord("\u{2603}"));
    ?>

L'exemple ci-dessus va afficher :

    int(65)
    int(32)
    int(9731)

### Voir aussi

- IntlChar::chr() - Renvoie le caractère Unicode par valeur de point de code
- mb_ord() - Récupère le point de code Unicode d'un caractère
- ord() - Convertit le premier octet d'une chaîne en une valeur entre 0 et 255

# IntlChar::tolower

(PHP 7, PHP 8)

IntlChar::tolower — Rend un caractère Unicode en minuscule

### Description

public static function IntlChar::tolower(int|string `$codepoint`): int|string|null

Le caractère donné est mappé à son équivalent en minuscule. Si le caractère n'a pas d'équivalent en minuscule, le caractère original est retourné.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie le Simple_Lowercase_Mapping du point de code, si disponible ; sinon le point de code lui-même. Renvoie `null` en cas d'échec.

Le type retourné sera entier tant que le codepoint a été passé en une chaîne de type chaîne de caractères encodée en UTF-8, auquel cas, une chaîne de caractères est retournée. En cas d'échec, retourne `null`.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::tolower("A"));
    var_dump(IntlChar::tolower("a"));
    var_dump(IntlChar::tolower("Φ"));
    var_dump(IntlChar::tolower("φ"));
    var_dump(IntlChar::tolower("1"));
    var_dump(IntlChar::tolower(ord("A")));
    var_dump(IntlChar::tolower(ord("a")));
    ?>

L'exemple ci-dessus va afficher :

    string(1) "a"
    string(1) "a"
    string(2) "φ"
    string(2) "φ"
    string(1) "1"
    int(97)
    int(97)

### Voir aussi

- IntlChar::totitle() - Rend un caractère Unicode en lettre de titre
- IntlChar::toupper() - Rend un caractère Unicode en majuscule
- mb_strtolower() - Met tous les caractères en minuscules

# IntlChar::totitle

(PHP 7, PHP 8)

IntlChar::totitle — Rend un caractère Unicode en lettre de titre

### Description

public static function IntlChar::totitle(int|string `$codepoint`): int|string|null

Le caractère donné est mappé à son équivalent en lettre de titre. Si le caractère n'a pas d'équivalent en lettre de titre, le caractère original est retourné.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie le Simple_Titlecase_Mapping du point de code, si disponible ; sinon le point de code lui-même. Renvoie `null` en cas d'échec.

Le type retourné sera entier tant que le codepoint a été passé en une chaîne de type chaîne de caractères encodée en UTF-8, auquel cas, une chaîne de caractères est retournée. En cas d'échec, retourne `null`.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::totitle("Ǆ"));
    var_dump(IntlChar::totitle("ǆ"));
    var_dump(IntlChar::totitle("Φ"));
    var_dump(IntlChar::totitle("φ"));
    var_dump(IntlChar::totitle("1"));
    var_dump(IntlChar::totitle("ᾳ"));
    var_dump(IntlChar::totitle(ord("A")));
    ?>

L'exemple ci-dessus va afficher :

    string(1) "ǅ"
    string(1) "ǅ"
    string(2) "Φ"
    string(2) "φ"
    string(1) "1"
    string(1) "ᾼ"
    int(65)

### Voir aussi

- IntlChar::tolower() - Rend un caractère Unicode en minuscule
- IntlChar::toupper() - Rend un caractère Unicode en majuscule
- IntlChar::istitle() - Vérifie si un point de code est une lettre en titre
- mb_convert_case() - Modifie la casse d'une chaîne

# IntlChar::toupper

(PHP 7, PHP 8)

IntlChar::toupper — Rend un caractère Unicode en majuscule

### Description

public static function IntlChar::toupper(int|string `$codepoint`): int|string|null

Le caractère donné est mappé à son équivalent en majuscule. Si le caractère n'a pas d'équivalent en majuscule, le caractère original est retourné.

### Liste de paramètres

`codepoint`
  La valeur codepoint de type entier (i.e. `0x2603` pour U+2603 SNOWMAN), ou le caractère encodé en UTF-8 de type chaîne de caractères (i.e. `"\u{2603}"`)

### Valeurs de retour

Renvoie le Simple_Uppercase_Mapping du point de code, si disponible ; sinon le point de code lui-même.

Le type retourné sera entier tant que le codepoint a été passé en une chaîne de type chaîne de caractères encodée en UTF-8, auquel cas, une chaîne de caractères est retournée. En cas d'échec, retourne `null`.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    var_dump(IntlChar::toupper("A"));
    var_dump(IntlChar::toupper("a"));
    var_dump(IntlChar::toupper("Φ"));
    var_dump(IntlChar::toupper("φ"));
    var_dump(IntlChar::toupper("1"));
    var_dump(IntlChar::toupper(ord("A")));
    var_dump(IntlChar::toupper(ord("a")));
    ?>

L'exemple ci-dessus va afficher :

    string(1) "A"
    string(1) "A"
    string(2) "Φ"
    string(2) "Φ"
    string(1) "1"
    int(65)
    int(65)

### Voir aussi

- IntlChar::tolower() - Rend un caractère Unicode en minuscule
- IntlChar::totitle() - Rend un caractère Unicode en lettre de titre
- mb_strtoupper() - Met tous les caractères en majuscules

## Sommaire

- IntlChar::charAge — Renvoie l'"âge" du point de code
- IntlChar::charDigitValue — Renvoie la valeur décimale du chiffre décimal
- IntlChar::charDirection — Renvoie la valeur de la catégorie bidirectionnelle pour un point de code
- IntlChar::charFromName — Trouve un caractère Unicode par son nom et renvoie sa valeur de point de code
- IntlChar::charMirror — Renvoie le caractère "image-miroir" pour un point de code
- IntlChar::charName — Renvoie le nom d'un caractère Unicode
- IntlChar::charType — Renvoie la valeur de la catégorie générale pour un point de code
- IntlChar::chr — Renvoie le caractère Unicode par valeur de point de code
- IntlChar::digit — Renvoie le chiffre décimal d'un point de code pour une base de numération donnée
- IntlChar::enumCharNames — Enumère tous les caractères Unicode assignés dans une plage
- IntlChar::enumCharTypes — Enumère tous les points de code avec leurs catégories générales Unicode
- IntlChar::foldCase — Effectue le pliage de cas sur un point de code
- IntlChar::forDigit — Renvoie la représentation de caractère pour un chiffre donné et une base de numération
- IntlChar::getBidiPairedBracket — Renvoie le caractère de parenthèse apparié pour un point de code
- IntlChar::getBlockCode — Renvoie le bloc d'allocation Unicode contenant un point de code
- IntlChar::getCombiningClass — Renvoie la classe de combinaison d'un point de code
- IntlChar::getFC_NFKC_Closure — Renvoie la propriété FC_NFKC_Closure pour un point de code
- IntlChar::getIntPropertyMaxValue — Renvoie la valeur maximale pour une propriété Unicode
- IntlChar::getIntPropertyMinValue — Renvoie la valeur minimale pour une propriété Unicode
- IntlChar::getIntPropertyValue — Renvoie la valeur d'une propriété Unicode pour un point de code
- IntlChar::getNumericValue — Renvoie la valeur numérique d'un point de code Unicode
- IntlChar::getPropertyEnum — Renvoie la valeur de la constante de propriété pour un nom de propriété donné
- IntlChar::getPropertyName — Renvoie le nom Unicode d'une propriété
- IntlChar::getPropertyValueEnum — Renvoie la valeur de propriété pour un nom de valeur donné
- IntlChar::getPropertyValueName — Renvoie le nom Unicode pour une valeur de propriété
- IntlChar::getUnicodeVersion — Renvoie la version Unicode
- IntlChar::hasBinaryProperty — Vérifie une propriété Unicode binaire pour un point de code
- IntlChar::isalnum — Vérifie si un point de code est un caractère alphanumérique
- IntlChar::isalpha — Vérifie si un point de code est un caractère alphabétique
- IntlChar::isbase — Vérifie si un point de code est un caractère de base
- IntlChar::isblank — Vérifie si un point de code est un caractère "blanc" ou "espace horizontal"
- IntlChar::iscntrl — Vérifie si un point de code est un caractère de contrôle
- IntlChar::isdefined — Vérifie si un point de code est défini
- IntlChar::isdigit — Vérifie si un point de code est un chiffre
- IntlChar::isgraph — Vérifie si un point de code est un caractère graphique
- IntlChar::isIDIgnorable — Vérifie si un point de code est un caractère ignoré
- IntlChar::isIDPart — Vérifie si un point de code est permis dans un identifiant
- IntlChar::isIDStart — Vérifie si un point de code est permis comme premier caractère dans un identifiant
- IntlChar::isISOControl — Vérifie si un point de code est un caractère de contrôle ISO
- IntlChar::isJavaIDPart — Vérifie si un point de code est permis dans un identifiant Java
- IntlChar::isJavaIDStart — Vérifie si un point de code est permis comme premier caractère dans un identifiant Java
- IntlChar::isJavaSpaceChar — Vérifie si un point de code est un caractère d'espace selon Java
- IntlChar::islower — Vérifie si un point de code est une lettre minuscule
- IntlChar::isMirrored — Vérifie si un point de code a la propriété Bidi_Mirrored
- IntlChar::isprint — Vérifie si un point de code est un caractère affichable
- IntlChar::ispunct — Vérifie si un point de code est un caractère de ponctuation
- IntlChar::isspace — Vérifie si un point de code est un caractère d'espace
- IntlChar::istitle — Vérifie si un point de code est une lettre en titre
- IntlChar::isUAlphabetic — Vérifie si un point de code a la propriété Unicode Alphabetic
- IntlChar::isULowercase — Vérifie si un point de code a la propriété Unicode Lowercase
- IntlChar::isupper — Vérifie si un point de code a la catégorie générale "Lu" (lettre majuscule)
- IntlChar::isUUppercase — Vérifie si un point de code a la propriété Unicode Uppercase
- IntlChar::isUWhiteSpace — Vérifie si un point de code a la propriété Unicode White_Space
- IntlChar::isWhitespace — Vérifie si un point de code est un caractère d'espace selon ICU
- IntlChar::isxdigit — Vérifie si un point de code est un chiffre hexadécimal
- IntlChar::ord — Renvoie la valeur du point de code Unicode d'un caractère
- IntlChar::tolower — Rend un caractère Unicode en minuscule
- IntlChar::totitle — Rend un caractère Unicode en lettre de titre
- IntlChar::toupper — Rend un caractère Unicode en majuscule

# La classe d'exception pour les erreurs intl

(PHP 5 > 5.5.0, PHP 7, PHP 8, PECL intl > 3.0.0a1)

## Introduction

Cette classe est utilisée pour générer des exceptions lorsque des erreurs se produisent à l'intérieur des fonctions intl. De telles exceptions ne sont générées que lorsque intl.use_exceptions est activé.

## Synopsis de la classe

class IntlException extends Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes héritées */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# La classe IntlIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Introduction

Cette classe représente des objets itérateurs à travers l'extension intl chaque fois que l'itérateur ne peut pas être identifié avec un autre objet fourni par l'extension. L'objet d'itérateur distinct utilisé en interne par la `foreach` ne peut être obtenu (dans la partie pertinente ici) que depuis des objets, donc les objets de cette classe servent à fournir le crochet par lequel cet objet interne peut être obtenu. Par commodité, cette classe implémente également l'interface Iterator, permettant à la collection de valeurs d'être parcourue en utilisant les méthodes définies dans cette interface. Ces méthodes et les objets d'itérateur internes fournis à `foreach` sont soutenus par le même état (par exemple, la position de l'itérateur et sa valeur actuelle).

Les sous-classes peuvent fournir une fonctionnalité plus riche.

## Synopsis de la classe

class IntlIterator implements Iterator {
/* Méthodes */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# IntlIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::current — Récupère l'élément courant

### Description

public function IntlIterator::current(): mixed

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlIterator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::key — Récupère la clé courante

### Description

public function IntlIterator::key(): mixed

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::next — Se déplace sur l'élément suivant

### Description

public function IntlIterator::next(): void

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlIterator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::rewind — Re-positionne l'itérateur au premier élément

### Description

public function IntlIterator::rewind(): void

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# IntlIterator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::valid — Vérifie si la position courante est valide

### Description

public function IntlIterator::valid(): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

## Sommaire

- IntlIterator::current — Récupère l'élément courant
- IntlIterator::key — Récupère la clé courante
- IntlIterator::next — Se déplace sur l'élément suivant
- IntlIterator::rewind — Re-positionne l'itérateur au premier élément
- IntlIterator::valid — Vérifie si la position courante est valide

# Fonctions intl

# intl_error_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_error_name — Lit le nom symbolique d'un code d'erreur donné

### Description

function intl_error_name(int `$errorCode`): string

Retourne le nom du code d'erreur ICU.

### Liste de paramètres

`errorCode`

  Le code d'erreur ICU.

### Valeurs de retour

La chaîne retournée sera celle du nom de la constante équivalente.

### Exemples

Exemple #1 Exemple avec intl_error_name()

    <?php
    $coll     = collator_create( 'en_RU' );
    $err_code = collator_get_error_code( $coll );

    printf( "Le nom symbolique de %d est %s\n.", $err_code, intl_error_name( $err_code ) );
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Symbolic name for -128 is U_USING_FALLBACK_WARNING.

### Voir aussi

- intl_is_failure() - Vérifie si un code d'erreur indique un échec
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_get_error_message() - Lit la description de la dernière erreur

# intl_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_code — Lit le dernier code d'erreur

### Description

function intl_get_error_code(): int

Pratique pour gérer les erreurs qui surviennent dans les méthodes statiques quand il n'y a pas d'objet dont on peut obtenir le message d'erreur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le code d'erreur retourné par le dernier appel à l'API.

### Exemples

Exemple #1 Exemple avec intl_get_error_code()

    <?php
    $coll = collator_create( '<bad_param>' );
    if( !$coll ) {
        handle_error( intl_get_error_code() );
    }
    ?>

### Voir aussi

- intl_is_failure() - Vérifie si un code d'erreur indique un échec
- intl_error_name() - Lit le nom symbolique d'un code d'erreur donné
- intl_get_error_message() - Lit la description de la dernière erreur
- collator_get_error_code() - Lit la dernière erreur du collator
- numfmt_get_error_code() - Lit le dernier code d'erreur du formateur

# intl_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_message — Lit la description de la dernière erreur

### Description

function intl_get_error_message(): string

Lit le message d'erreur de la dernière fonction d'internationalisation appelée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La description de l'erreur qui est survenue durant le dernier appel de l'API.

### Exemples

Exemple #1 Exemple avec intl_get_error_message()

    <?php
    if( Collator::getAvailableLocales() === false ) {
        show_error( intl_get_error_message() );
    }
    ?>

### Voir aussi

- intl_error_name() - Lit le nom symbolique d'un code d'erreur donné
- intl_get_error_code() - Lit le dernier code d'erreur
- intl_is_failure() - Vérifie si un code d'erreur indique un échec
- collator_get_error_message() - Lit le dernier message d'erreur du collator
- numfmt_get_error_message() - Lit le dernier message d'erreur du formateur

# intl_is_failure

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_is_failure — Vérifie si un code d'erreur indique un échec

### Description

function intl_is_failure(int `$errorCode`): bool

### Liste de paramètres

`errorCode`

  une valeur retournée par une des fonctions intl_get_error_code(), collator_get_error_code() .

### Valeurs de retour

`true` si le code indique un échec, et `false` dans le cas d'une réussite ou d'une alerte.

### Exemples

Exemple #1 Exemple avec intl_is_failure()

    <?php
    function check( $err_code )
    {
        var_export( intl_is_failure( $err_code ) );
        echo "\n";
    }

    check( U_ZERO_ERROR );
    check( U_USING_FALLBACK_WARNING );
    check( U_ILLEGAL_ARGUMENT_ERROR );
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    false
    false
    true

### Voir aussi

- intl_get_error_code() - Lit le dernier code d'erreur
- collator_get_error_code() - Lit la dernière erreur du collator
- Collator-getErrorCode()

## Sommaire

- intl_error_name — Lit le nom symbolique d'un code d'erreur donné
- intl_get_error_code — Lit le dernier code d'erreur
- intl_get_error_message — Lit la description de la dernière erreur
- intl_is_failure — Vérifie si un code d'erreur indique un échec

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Exemples
  - Utilisation simple de l'extension
- Collator — La classe Collator
  - Collator::asort — Trie un tableau en conservant les clés, avec une collation
  - Collator::compare — Compare deux chaînes Unicode
  - Collator::__construct — Création d'un collator
  - Collator::create — Création d'un collator
  - Collator::getAttribute — Lit un attribut de collation
  - Collator::getErrorCode — Lit la dernière erreur du collator
  - Collator::getErrorMessage — Lit le dernier message d'erreur du collator
  - Collator::getLocale — Lit le nom de la locale d'un collator
  - Collator::getSortKey — Récupère la clé de tri pour une chaîne
  - Collator::getStrength — Récupère la dureté de classement utilisé
  - Collator::setAttribute — Configure l'attribut de collation
  - Collator::setStrength — Définit la force de collation
  - Collator::sort — Trie un tableau avec une collation
  - Collator::sortWithSortKeys — Trie un tableau et ses clés avec une collation
- NumberFormatter — La classe NumberFormatter
  - NumberFormatter::create — Crée un formateur de nombre
  - NumberFormatter::format — Formate un nombre
  - NumberFormatter::formatCurrency — Formate une valeur monétaire
  - NumberFormatter::getAttribute — Lit un attribut
  - NumberFormatter::getErrorCode — Lit le dernier code d'erreur du formateur
  - NumberFormatter::getErrorMessage — Lit le dernier message d'erreur du formateur
  - NumberFormatter::getLocale — Lit la locale du formateur
  - NumberFormatter::getPattern — Lit le modèle du formateur
  - NumberFormatter::getSymbol — Lit la valeur du symbole
  - NumberFormatter::getTextAttribute — Lit un attribut textuel
  - NumberFormatter::parse — Analyse un nombre
  - NumberFormatter::parseCurrency — Analyse un nombre monétaire
  - NumberFormatter::setAttribute — Affecte un attribut du formateur
  - NumberFormatter::setPattern — Configure le modèle du formateur
  - NumberFormatter::setSymbol — Configure le symbole du formateur
  - NumberFormatter::setTextAttribute — Modifie un attribut texte
- Locale — La classe Locale
  - Locale::acceptFromHttp — Devine la meilleure locale à partir de l'en-tête HTTP "Accept-Language"
  - Locale::canonicalize — Canonise la chaîne représentant la locale
  - Locale::composeLocale — Retourne un identifiant de locale correct
  - Locale::filterMatches — Vérifie si le tag de langue correspond à une locale
  - Locale::getAllVariants — Liste toutes les variantes d'une locale
  - Locale::getDefault — Lit la valeur par défaut d'une locale pour la variable globale 'default_locale'
  - Locale::getDisplayLanguage — Retourne un nom approprié pour l'affichage d'un nom de langue
  - Locale::getDisplayName — Retourne un nom d'affichage correct pour une locale
  - Locale::getDisplayRegion — Retourne un nom pour la région de la locale
  - Locale::getDisplayScript — Retourne le nom du script de la locale
  - Locale::getDisplayVariant — Retourne un nom pour la variante de la locale
  - Locale::getKeywords — Lit les mots-clé de la locale
  - Locale::getPrimaryLanguage — Lit la langue principale de la locale
  - Locale::getRegion — Retourne un code pour la région de la locale
  - Locale::getScript — Retourne un code pour le script de la locale
  - Locale::isRightToLeft — Vérifie si une locale utilise un système d'écriture de droite à gauche
  - Locale::lookup — Recherche dans la liste la meilleure langue
  - Locale::parseLocale — Retourne les sous-éléments de la locale
  - Locale::setDefault — Configure la locale par défaut
- Normalizer — La classe Normalizer
  - Normalizer::getRawDecomposition — Renvoie la propriété Decomposition_Mapping pour le point de code UTF-8 donné
  - Normalizer::isNormalized — Vérifie si une chaîne est normalisée
  - Normalizer::normalize — Normalise une chaîne en entrée
- MessageFormatter — La classe MessageFormatter
  - MessageFormatter::create — Construit un nouveau formateur de messages
  - MessageFormatter::format — Formate un message
  - MessageFormatter::formatMessage — Formate rapidement un message
  - MessageFormatter::getErrorCode — Lit le dernier code d'erreur de la dernière opération
  - MessageFormatter::getErrorMessage — Lit le message d'erreur de la dernière opération
  - MessageFormatter::getLocale — Lit la locale avec laquelle le formateur a été créé
  - MessageFormatter::getPattern — Lit le modèle utilisé par le formateur de messages
  - MessageFormatter::parse — Analyse une chaîne en fonction du modèle
  - MessageFormatter::parseMessage — Analyse rapidement une chaîne
  - MessageFormatter::setPattern — Configure le modèle utilisé par le formateur
- IntlCalendar — La classe IntlCalendar
  - IntlCalendar::add — Ajoute une durée (signée) à un champ
  - IntlCalendar::after — Vérifie si l'objet temps courant est dans le futur par rapport à l'objet temps passé
  - IntlCalendar::before — Vérifie si l'objet temps est dans le passé par rapport à l'objet fourni
  - IntlCalendar::clear — Vide un ou tous les champs
  - IntlCalendar::__construct — Constructeur privé pour la désactivation de l'instanciation
  - IntlCalendar::createInstance — Crée un nouvel objet IntlCalendar
  - IntlCalendar::equals — Vérifie si deux objets IntlCalendar sont égaux
  - IntlCalendar::fieldDifference — Calcule la différence entre le temps donné et le temps de l'objet
  - IntlCalendar::fromDateTime — Créer un IntlCalendar depuis un objet DateTime ou une chaîne de caractères
  - IntlCalendar::get — Récupère la valeur d'une propriété
  - IntlCalendar::getActualMaximum — La valeur maximale pour un champ, en considérant le temps actuel de l'objet
  - IntlCalendar::getActualMinimum — La valeur minimale pour un champ, en considérant le temps actuel de l'objet
  - IntlCalendar::getAvailableLocales — Renvoie un tableau des locales pour lesquelles il y a des données
  - IntlCalendar::getDayOfWeekType — Indique si un jour est un jour de la semaine, un week-end ou un jour de transition entre les deux
  - IntlCalendar::getErrorCode — Renvoie le dernier code d'erreur sur l'objet
  - IntlCalendar::getErrorMessage — Renvoie le dernier message d'erreur sur l'objet
  - IntlCalendar::getFirstDayOfWeek — Renvoie le premier jour de la semaine pour la locale du calendrier
  - IntlCalendar::getGreatestMinimum — Renvoie la plus grande valeur minimale locale pour un champ
  - IntlCalendar::getKeywordValuesForLocale — Renvoie l'ensemble des valeurs de mots-clés de locale
  - IntlCalendar::getLeastMaximum — Obtient le plus petit maximum local pour un champ
  - IntlCalendar::getLocale — Renvoie la locale associée à l'objet
  - IntlCalendar::getMaximum — Obtient la valeur maximale globale pour un champ
  - IntlCalendar::getMinimalDaysInFirstWeek — Obtient le nombre minimal de jours que la première semaine dʼune année ou dʼun mois peut avoir
  - IntlCalendar::getMinimum — Obtient la valeur minimale globale pour un champ
  - IntlCalendar::getNow — Récupère le nombre représentant la date courante
  - IntlCalendar::getRepeatedWallTimeOption — Obtient le comportement pour la gestion des heures murales répétées
  - IntlCalendar::getSkippedWallTimeOption — Obtient le comportement pour la gestion des heures murales sautées
  - IntlCalendar::getTime — Obtient le temps actuellement représenté par l'objet
  - IntlCalendar::getTimeZone — Récupère le fuseau horaire de l'objet
  - IntlCalendar::getType — Récupère le type de calendrier
  - IntlCalendar::getWeekendTransition — Obtient l'heure du jour à laquelle le week-end commence ou se termine
  - IntlCalendar::inDaylightTime — Indique si l'objet est en heure d'été
  - IntlCalendar::isEquivalentTo — Indique si un autre calendrier est équivalent, mais pour un autre moment
  - IntlCalendar::isLenient — Indique si l'interprétation de la date/heure est en mode tolérant
  - IntlCalendar::isSet — Indique si un champ est défini
  - IntlCalendar::isWeekend — Indique si une date/heure est un week-end
  - IntlCalendar::roll — Ajoute une valeur à un champ sans la reporter sur les champs plus significatifs
  - IntlCalendar::set — Définit un champ de temps ou plusieurs champs communs en une seule fois
  - IntlCalendar::setDate — Définit un champ de date
  - IntlCalendar::setDateTime — Définit un champ de date et d'heure
  - IntlCalendar::setFirstDayOfWeek — Définit le jour de début de la semaine
  - IntlCalendar::setLenient — Définit si l'interprétation de la date/heure est tolérante
  - IntlCalendar::setMinimalDaysInFirstWeek — Définit le nombre minimal de jours que la première semaine d'une année ou d'un mois peut avoir
  - IntlCalendar::setRepeatedWallTimeOption — Définit le comportement pour la gestion des heures murales répétées lors des transitions de décalage de fuseau horaire négatif
  - IntlCalendar::setSkippedWallTimeOption — Définit le comportement pour la gestion des heures murales sautées lors des transitions de décalage de fuseau horaire positif
  - IntlCalendar::setTime — Définit le temps du calendrier en milliseconde depuis l'époque
  - IntlCalendar::setTimeZone — Définit le fuseau horaire utilisé par ce calendrier
  - IntlCalendar::toDateTime — Convertit un objet IntlCalendar en un objet DateTime
- IntlGregorianCalendar — La classe IntlGregorianCalendar
  - IntlGregorianCalendar::__construct — Créer la classe du calendrier grégorien
  - IntlGregorianCalendar::createFromDate — Créer une nouvelle instance de IntlGregorianCalendar à partir d'une date
  - IntlGregorianCalendar::createFromDateTime — Créer une nouvelle instance de IntlGregorianCalendar à partir d'une date et d'une heure
  - IntlGregorianCalendar::getGregorianChange — Renvoie la date de changement du calendrier grégorien
  - IntlGregorianCalendar::isLeapYear — Détermine si l'année donnée est une année bissextile
  - IntlGregorianCalendar::setGregorianChange — Définit la date de changement du calendrier grégorien
- IntlTimeZone — La classe IntlTimeZone
  - IntlTimeZone::__construct — Constructeur privé pour empêcher l'instanciation directe
  - IntlTimeZone::countEquivalentIDs — Récupère le nombre d'IDs dans le groupe d'équivalence qui inclut l'ID fourni
  - IntlTimeZone::createDefault — Crée une nouvelle copie du fuseau horaire par défaut pour cet hôte
  - IntlTimeZone::createEnumeration — Récupère une énumération d'IDs de fuseau horaire associés avec le pays fourni
  - IntlTimeZone::createTimeZone — Crée un objet de fuseau horaire pour l'ID fourni
  - IntlTimeZone::createTimeZoneIDEnumeration — Renvoie une énumération sur les identifiants de fuseau horaire système avec les conditions de filtre données
  - IntlTimeZone::fromDateTimeZone — Crée un objet fuseau horaire depuis DateTimeZone
  - IntlTimeZone::getCanonicalID — Récupère l'identifiant du fuseau horaire système ou l'identifiant normalisé du fuseau horaire personnalisé pour l'ID du fuseau horaire fourni
  - IntlTimeZone::getDisplayName — Récupère un nom du fuseau horaire aux fins de présentation à l'utilisateur
  - IntlTimeZone::getDSTSavings — Récupère la durée à ajouter à l'heure locale pour récupérer l'heure murale locale
  - IntlTimeZone::getEquivalentID — Récupère un identifiant d'un groupe d'équivalence qui inclut l'identifiant fourni
  - IntlTimeZone::getErrorCode — Récupère le code de la dernière erreur survenue sur l'objet
  - IntlTimeZone::getErrorMessage — Récupère le message de la dernière erreur survenue sur l'objet
  - IntlTimeZone::getGMT — Crée un fuseau horaire GMT (UTC)
  - IntlTimeZone::getIanaID — Traduit un identifiant de fuseau horaire vers son équivalent IANA
  - IntlTimeZone::getID — Récupère l'ID d'un fuseau horaire
  - IntlTimeZone::getIDForWindowsID — Traduit un fuseau horaire Windows en un fuseau horaire système
  - IntlTimeZone::getOffset — Récupère le fuseau horaire brut, et la position GMT pour un moment dans le temps donné
  - IntlTimeZone::getRawOffset — Récupère la position brute GMT (avant de prendre en compte l'heure d'été)
  - IntlTimeZone::getRegion — Renvoie le code de région associé à l'identifiant de fuseau horaire système donné
  - IntlTimeZone::getTZDataVersion — Récupère la version du fuseau horaire actuellement utilisé par ICU
  - IntlTimeZone::getUnknown — Renvoie le fuseau horaire "inconnu"
  - IntlTimeZone::getWindowsID — Traduit un fuseau horaire système en un fuseau horaire Windows
  - IntlTimeZone::hasSameRules — Vérifie si cette zone a les mêmes règles qu'une autre
  - IntlTimeZone::toDateTimeZone — Convertit un objet DateTimeZone
  - IntlTimeZone::useDaylightTime — Vérifie si ce fuseau horaire utilise l'heure d'été
- IntlDateFormatter — La classe IntlDateFormatter
  - IntlDateFormatter::create — Crée un formateur de date
  - IntlDateFormatter::format — Formate la date et l'heure sous forme de chaîne
  - IntlDateFormatter::formatObject — Formate un objet
  - IntlDateFormatter::getCalendar — Lit le calendrier utilisé par l'objet IntlDateFormatter
  - IntlDateFormatter::getDateType — Lit le type de date utilisé par IntlDateFormatter
  - IntlDateFormatter::getErrorCode — Lit le code d'erreur de la dernière opération
  - IntlDateFormatter::getErrorMessage — Lit le dernier message d'erreur
  - IntlDateFormatter::getLocale — Lit la locale utilisée par le formateur
  - IntlDateFormatter::getPattern — Lit le modèle utilisé par IntlDateFormatter
  - IntlDateFormatter::getTimeType — Lit le type de temps pour IntlDateFormatter
  - IntlDateFormatter::getTimeZoneId — Lit le fuseau horaire de IntlDateFormatter
  - IntlDateFormatter::getCalendarObject — Récupère une copie de l'objet formateur du calendrier
  - IntlDateFormatter::getTimeZone — Récupère le formateur du décalage horaire
  - IntlDateFormatter::isLenient — Retourne la sévérité utilisée pour IntlDateFormatter
  - IntlDateFormatter::localtime — Analyse une chaîne et la convertit en temps
  - IntlDateFormatter::parse — Analyse une chaîne vers un timestamp
  - IntlDateFormatter::parseToCalendar — Analyse une chaîne en timestamp, en mettant à jour un calendrier ouvert
  - IntlDateFormatter::setCalendar — Définit le type de calendrier utilisé par le formateur
  - IntlDateFormatter::setLenient — Configure la souplesse de l'analyseur
  - IntlDateFormatter::setPattern — Configure le modèle utilisé par le IntlDateFormatter
  - IntlDateFormatter::setTimeZone — Définit le formateur pour le décalage horaire
- ResourceBundle — La classe ResourceBundle
  - ResourceBundle::count — Récupère le nombre d'éléments dans le faisceau
  - ResourceBundle::create — Crée une ressource représentant un faisceau
  - ResourceBundle::get — Récupère les données depuis le faisceau
  - ResourceBundle::getErrorCode — Récupère le dernier code erreur du faisceau
  - ResourceBundle::getErrorMessage — Récupère le dernier message d'erreur depuis le faisceau
  - ResourceBundle::getLocales — Récupère les locales supportées
- Spoofchecker — La classe Spoofchecker
  - Spoofchecker::areConfusable — Vérifie si les chaînes données peuvent être confondues
  - Spoofchecker::__construct — Constructeur
  - Spoofchecker::isSuspicious — Vérifie si un texte contient des caractères suspects
  - Spoofchecker::setAllowedChars — Définit l'ensemble des caractères autorisés lors de l'exécution des vérifications
  - Spoofchecker::setAllowedLocales — Locales à utiliser lors de la vérification
  - Spoofchecker::setChecks — Spécifie les vérifications à effectuer
  - Spoofchecker::setRestrictionLevel — Définit le niveau de restriction
- Transliterator — La classe Transliterator
  - Transliterator::__construct — Constructeur privé pour interdire l'instanciation
  - Transliterator::create — Crée un Transliterator
  - Transliterator::createFromRules — Crée un translittérateur depuis des règles
  - Transliterator::createInverse — Crée un translittérateur inverse
  - Transliterator::getErrorCode — Récupère le dernier code erreur
  - Transliterator::getErrorMessage — Récupère le dernier message d'erreur
  - Transliterator::listIDs — Récupère les identifiants de ce translittérateur
  - Transliterator::transliterate — Translittère une chaîne de caractères
- IntlBreakIterator — La classe IntlBreakIterator
  - IntlBreakIterator::__construct — Constructeur privé pour désactiver l'instantiation
  - IntlBreakIterator::createCharacterInstance — Crée un itérateur pour les limites des séquences de caractères combinés
  - IntlBreakIterator::createCodePointInstance — Crée un itérateur pour les limites de points de code
  - IntlBreakIterator::createLineInstance — Crée un itérateur pour les coupures de lignes
  - IntlBreakIterator::createSentenceInstance — Crée un itérateur pour les coupures de phrase
  - IntlBreakIterator::createTitleInstance — Crée un itérateur
  - IntlBreakIterator::createWordInstance — Crée un itérateur pour les coupures de mot
  - IntlBreakIterator::current — Récupère l'index de la position courante
  - IntlBreakIterator::first — Définit la position au premier caractère du texte
  - IntlBreakIterator::following — Avance l'itérateur à la première limite suivant la position spécifiée
  - IntlBreakIterator::getErrorCode — Récupère le code de la dernière erreur survenue sur l'objet
  - IntlBreakIterator::getErrorMessage — Récupère le message de la dernière erreur survenue sur l'objet
  - IntlBreakIterator::getLocale — Récupère la locale associée avec l'objet
  - IntlBreakIterator::getPartsIterator — Crée un itérateur pour naviguer dans les fragments entre les limites
  - IntlBreakIterator::getText — Récupère le texte analysé
  - IntlBreakIterator::isBoundary — Indique si une position est une position limite
  - IntlBreakIterator::last — Définit la position de l'itérateur à l'index après le dernier caractère
  - IntlBreakIterator::next — Avance l'itérateur à la prochaine limite
  - IntlBreakIterator::preceding — Définit la position de l'itérateur à la première limite avant la position
  - IntlBreakIterator::previous — Définit la position de l'itérateur à la limite immédiate avant la courante
  - IntlBreakIterator::setText — Définit le texte à analyser
- IntlRuleBasedBreakIterator — La classe IntlRuleBasedBreakIterator
  - IntlRuleBasedBreakIterator::__construct — Crée un itérateur depuis un jeu de règles
  - IntlRuleBasedBreakIterator::getBinaryRules — Récupère la forme binaire des règles compilées
  - IntlRuleBasedBreakIterator::getRules — Récupère le jeu de règles utilisé pour créer cet objet
  - IntlRuleBasedBreakIterator::getRuleStatus — Récupère la valeur de statut la plus grande depuis les règles qui déterminent la position courante d'arrêt
  - IntlRuleBasedBreakIterator::getRuleStatusVec — Récupère les valeurs de statut depuis les règles d'arrêt qui déterminent la position d'arrêt courante
- IntlCodePointBreakIterator — La classe IntlCodePointBreakIterator
  - IntlCodePointBreakIterator::getLastCodePoint — Récupère le dernier point de code après avoir avancé ou reculé dans l'itérateur
- IntlDatePatternGenerator — La classe IntlDatePatternGenerator
  - IntlDatePatternGenerator::create — Créer une nouvelle instance de IntlDatePatternGenerator
  - IntlDatePatternGenerator::getBestPattern — Détermine le format de date/heure le plus adapté
- IntlPartsIterator — La classe IntlPartsIterator
  - IntlPartsIterator::getBreakIterator — Récupère IntlBreakIterator, sauvegardant ainsi cette partie de l'itérateur
- UConverter — La classe UConverter
  - UConverter::__construct — Crée un objet UConverter
  - UConverter::convert — Convertit une chaîne d'un jeu de caractères vers un autre jeu de caractères
  - UConverter::fromUCallback — Fonction de rappel "from"
  - UConverter::getAliases — Récupère les alias du nom fourni
  - UConverter::getAvailable — Récupère le nom canonique des convertisseurs disponibles
  - UConverter::getDestinationEncoding — Récupère l'encodage de la destination
  - UConverter::getDestinationType — Récupère le type de la destination du convertisseur
  - UConverter::getErrorCode — Récupère le code de la dernière erreur survenue sur l'objet
  - UConverter::getErrorMessage — Récupère le message de la dernière erreur survenue sur l'objet
  - UConverter::getSourceEncoding — Récupère l'encodage de la source
  - UConverter::getSourceType — Récupère le type de source du convertisseur
  - UConverter::getStandards — Récupère les normes associées aux noms de conversion
  - UConverter::getSubstChars — Récupère les caractères de substitution
  - UConverter::reasonText — Récupère la chaîne représentant la raison de la fonction de rappel
  - UConverter::setDestinationEncoding — Définit l'encodage de la destination
  - UConverter::setSourceEncoding — Définit l'encodage de la source
  - UConverter::setSubstChars — Définit les caractères de substitution
  - UConverter::toUCallback — Fonction de rappel "to"
  - UConverter::transcode — Convertit une chaîne d'un jeu de caractères à un autre
- Fonctions Grapheme
  - grapheme_extract — Extrait un groupe de graphème d'une chaîne UTF-8
  - grapheme_str_split — Sépare une chaîne en un tableau
  - grapheme_stripos — Trouve la position en graphème de la première occurrence dans une chaîne, insensible à la casse
  - grapheme_stristr — Retourne la partie d'une chaîne à partir d'une occurrence
  - grapheme_strlen — Lit la taille d'une chaîne en nombre de graphème
  - grapheme_strpos — Trouve la position du premier graphème
  - grapheme_strripos — Trouve la position du dernier graphème, insensible à la casse
  - grapheme_strrpos — Trouve la position du dernier graphème
  - grapheme_strstr — Retourne la partie d'une chaîne à partir d'une occurrence, sensible à la casse
  - grapheme_substr — Retourne une partie d'une chaîne
- Fonctions IDN
  - idn_to_ascii — Convertit un nom de domaine au format IDNA ASCII
  - idn_to_utf8 — Convertit le nom de domaine IDNA ASCII en Unicode
- IntlChar
  - IntlChar::charAge — Renvoie l'"âge" du point de code
  - IntlChar::charDigitValue — Renvoie la valeur décimale du chiffre décimal
  - IntlChar::charDirection — Renvoie la valeur de la catégorie bidirectionnelle pour un point de code
  - IntlChar::charFromName — Trouve un caractère Unicode par son nom et renvoie sa valeur de point de code
  - IntlChar::charMirror — Renvoie le caractère "image-miroir" pour un point de code
  - IntlChar::charName — Renvoie le nom d'un caractère Unicode
  - IntlChar::charType — Renvoie la valeur de la catégorie générale pour un point de code
  - IntlChar::chr — Renvoie le caractère Unicode par valeur de point de code
  - IntlChar::digit — Renvoie le chiffre décimal d'un point de code pour une base de numération donnée
  - IntlChar::enumCharNames — Enumère tous les caractères Unicode assignés dans une plage
  - IntlChar::enumCharTypes — Enumère tous les points de code avec leurs catégories générales Unicode
  - IntlChar::foldCase — Effectue le pliage de cas sur un point de code
  - IntlChar::forDigit — Renvoie la représentation de caractère pour un chiffre donné et une base de numération
  - IntlChar::getBidiPairedBracket — Renvoie le caractère de parenthèse apparié pour un point de code
  - IntlChar::getBlockCode — Renvoie le bloc d'allocation Unicode contenant un point de code
  - IntlChar::getCombiningClass — Renvoie la classe de combinaison d'un point de code
  - IntlChar::getFC_NFKC_Closure — Renvoie la propriété FC_NFKC_Closure pour un point de code
  - IntlChar::getIntPropertyMaxValue — Renvoie la valeur maximale pour une propriété Unicode
  - IntlChar::getIntPropertyMinValue — Renvoie la valeur minimale pour une propriété Unicode
  - IntlChar::getIntPropertyValue — Renvoie la valeur d'une propriété Unicode pour un point de code
  - IntlChar::getNumericValue — Renvoie la valeur numérique d'un point de code Unicode
  - IntlChar::getPropertyEnum — Renvoie la valeur de la constante de propriété pour un nom de propriété donné
  - IntlChar::getPropertyName — Renvoie le nom Unicode d'une propriété
  - IntlChar::getPropertyValueEnum — Renvoie la valeur de propriété pour un nom de valeur donné
  - IntlChar::getPropertyValueName — Renvoie le nom Unicode pour une valeur de propriété
  - IntlChar::getUnicodeVersion — Renvoie la version Unicode
  - IntlChar::hasBinaryProperty — Vérifie une propriété Unicode binaire pour un point de code
  - IntlChar::isalnum — Vérifie si un point de code est un caractère alphanumérique
  - IntlChar::isalpha — Vérifie si un point de code est un caractère alphabétique
  - IntlChar::isbase — Vérifie si un point de code est un caractère de base
  - IntlChar::isblank — Vérifie si un point de code est un caractère "blanc" ou "espace horizontal"
  - IntlChar::iscntrl — Vérifie si un point de code est un caractère de contrôle
  - IntlChar::isdefined — Vérifie si un point de code est défini
  - IntlChar::isdigit — Vérifie si un point de code est un chiffre
  - IntlChar::isgraph — Vérifie si un point de code est un caractère graphique
  - IntlChar::isIDIgnorable — Vérifie si un point de code est un caractère ignoré
  - IntlChar::isIDPart — Vérifie si un point de code est permis dans un identifiant
  - IntlChar::isIDStart — Vérifie si un point de code est permis comme premier caractère dans un identifiant
  - IntlChar::isISOControl — Vérifie si un point de code est un caractère de contrôle ISO
  - IntlChar::isJavaIDPart — Vérifie si un point de code est permis dans un identifiant Java
  - IntlChar::isJavaIDStart — Vérifie si un point de code est permis comme premier caractère dans un identifiant Java
  - IntlChar::isJavaSpaceChar — Vérifie si un point de code est un caractère d'espace selon Java
  - IntlChar::islower — Vérifie si un point de code est une lettre minuscule
  - IntlChar::isMirrored — Vérifie si un point de code a la propriété Bidi_Mirrored
  - IntlChar::isprint — Vérifie si un point de code est un caractère affichable
  - IntlChar::ispunct — Vérifie si un point de code est un caractère de ponctuation
  - IntlChar::isspace — Vérifie si un point de code est un caractère d'espace
  - IntlChar::istitle — Vérifie si un point de code est une lettre en titre
  - IntlChar::isUAlphabetic — Vérifie si un point de code a la propriété Unicode Alphabetic
  - IntlChar::isULowercase — Vérifie si un point de code a la propriété Unicode Lowercase
  - IntlChar::isupper — Vérifie si un point de code a la catégorie générale "Lu" (lettre majuscule)
  - IntlChar::isUUppercase — Vérifie si un point de code a la propriété Unicode Uppercase
  - IntlChar::isUWhiteSpace — Vérifie si un point de code a la propriété Unicode White_Space
  - IntlChar::isWhitespace — Vérifie si un point de code est un caractère d'espace selon ICU
  - IntlChar::isxdigit — Vérifie si un point de code est un chiffre hexadécimal
  - IntlChar::ord — Renvoie la valeur du point de code Unicode d'un caractère
  - IntlChar::tolower — Rend un caractère Unicode en minuscule
  - IntlChar::totitle — Rend un caractère Unicode en lettre de titre
  - IntlChar::toupper — Rend un caractère Unicode en majuscule
- IntlException — La classe d'exception pour les erreurs intl
- IntlIterator — La classe IntlIterator
  - IntlIterator::current — Récupère l'élément courant
  - IntlIterator::key — Récupère la clé courante
  - IntlIterator::next — Se déplace sur l'élément suivant
  - IntlIterator::rewind — Re-positionne l'itérateur au premier élément
  - IntlIterator::valid — Vérifie si la position courante est valide
- Fonctions intl
  - intl_error_name — Lit le nom symbolique d'un code d'erreur donné
  - intl_get_error_code — Lit le dernier code d'erreur
  - intl_get_error_message — Lit la description de la dernière erreur
  - intl_is_failure — Vérifie si un code d'erreur indique un échec

# Chaînes de caractères multioctets

# Introduction

Même si la plupart des langues peuvent être représentées grâce à un jeu de 128 caractères, il y a d'autres langues qui requièrent des jeux de caractères bien plus grands. Des méthodes de caractères multioctets ont été développées pour résoudre ce type de problème.

Lorsqu'on manipule des chaînes de caractères multioctets, pour couper, rechercher ou nettoyer une chaîne, il faut utiliser deux octets consécutifs, qui représentent un seul caractère. Si l'on n'y prend pas garde, on va obtenir une chaîne corrompue et invalide, avec une représentation totalement incompréhensible.

`mbstring` fournit les fonctions spécifiques de manipulations de chaînes qui permettent de travailler avec les encodages multioctets en PHP. En plus de cela, `mbstring` gère la traduction entre les jeux de caractères disponibles. `mbstring` est également connu pour gérer l'Unicode, comme UTF-8 et UCS-2 ainsi que de nombreux autres jeux mono-octets (listés dans Encodages de caractères pris en charge).

# Installation/Configuration

## Sommaire

- Installation
- Configuration à l'exécution

## Installation

`mbstring` est une extension PHP. L'extension doit être activée avec l'option `configure`. Voir la section installation pour plus de détails.

Les options de configurations suivantes sont liées à l'extension `mbstring`.

- --enable-mbstring : Active les fonctions `mbstring`. Cette option est nécessaire pour utiliser les fonctions `mbstring`.

  libmbfl est nécessaire pour `mbstring`. libmbfl est inclus avec `mbstring`. Antérieur à PHP 7.3.0, si libmbfl est déjà installé sur le système, --with-libmbfl[=DIR] peut être spécifié pour utiliser la bibliothèque installée.

- --disable-mbregex : Désactive les fonctions d'expression régulières avec le support des caractères multioctets.

  Oniguruma est nécessaire pour les fonctions d'expression régulière avec le support des caractères multioctets. À partir de PHP 7.4.0, pkg-config est utilisé pour détecter la bibliothèque libonig. Antérieur à PHP 7.4.0, Oniguruma était inclus avec `mbstring`, mais il était possible de compiler contre une version de libonig déjà installée en passant --with-onig[=DIR].

  Il est possible de désactiver la vérification du backtrack (retour sur ses pas) des regex multioctets en spécifiant --disable-mbregex-backtrack.

## Configuration à l'exécution

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

Options de configuration mbstring
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
mbstring.language | "neutral" | `INI_ALL` |
mbstring.detect_order | NULL | `INI_ALL` |
mbstring.http_input | "pass" | `INI_ALL` | Obsolète
mbstring.http_output | "pass" | `INI_ALL` | Obsolète
mbstring.internal_encoding | NULL | `INI_ALL` | Obsolète
mbstring.substitute_character | NULL | `INI_ALL` |
mbstring.func_overload | "0" | `INI_SYSTEM` | Obsolète à partir de PHP 7.2.0; supprimée à partir de PHP 8.0.0.
mbstring.encoding_translation | "0" | `INI_PERDIR` |
mbstring.http_output_conv_mimetypes | "^(text/|application/xhtml\+xml)" | `INI_ALL` |
mbstring.strict_detection | "0" | `INI_ALL` |
mbstring.regex_retry_limit | "1000000" | `INI_ALL` | Disponible à partir de PHP 7.4.0.
mbstring.regex_stack_limit | "100000" | `INI_ALL` | Disponible à partir de PHP 7.3.5.

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`mbstring.language` string

  Définit le langage utilisé par mbstring. À noter que cette option définit `mbstring.internal_encoding` et `mbstring.internal_encoding` doit être placé après `mbstring.language` dans le fichier php.ini

`mbstring.encoding_translation` bool

  Active la détection et la traduction des données d'entrées HTTP vers le codage interne mbstring.

`mbstring.internal_encoding` string
  Avertissement

  Cette fonctionnalité obsolète sera certainement supprimée dans le futur.

  Définit l'encodage interne par défaut.

  Les utilisateurs devraient laisser cette option vide et définir plutôt l'option `default_charset`.

`mbstring.http_input` string
  Avertissement

  Cette fonctionnalité obsolète sera certainement supprimée dans le futur.

  Définit l'encodage de réception HTTP par défaut.

  Les utilisateurs devraient laisser cette option vide et définir plutôt l'option `default_charset`.

`mbstring.http_output` string
  Avertissement

  Cette fonctionnalité obsolète sera certainement supprimée dans le futur.

  Définit l'encodage d'affichage HTTP par défaut (l'affichage sera converti depuis l'encodage interne vers l'encodage HTTP de la sortie, lors de l'affichage).

  Les utilisateurs devraient laisser vide cette option et définir plutôt l'option `default_charset`.

`mbstring.detect_order` string

  Définit l'ordre de détection des encodages par défaut. Voir aussi mb_detect_order().

`mbstring.substitute_character` string

  Définit l'encodage de substitution par défaut : il est utilisé pour les caractères invalides. Voir mb_substitute_character() pour les valeurs supportées.

`mbstring.func_overload` string
  Avertissement

  Cette fonctionnalité est OBSOLÈTE à partir de PHP 7.2.0, et SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonctionnalité est fortement déconseillé.

  Remplace les fonctions de traitement des chaînes par les fonctions mbstring. Voir les fonctions de remplacement pour plus d'informations.

  Ce paramètre ne peut être changé que depuis le fichier php.ini.

`mbstring.http_output_conv_mimetypes` string

`mbstring.strict_detection` bool

  Active la détection stricte de l'encodage. Voir mb_detect_encoding() pour une description et des exemples.

`mbstring.regex_retry_limit` int

  Limite la quantité de retour en arrière qui peut être effectuée pendant une correspondance mbregex.

  Ce paramètre ne prend effet que lors de la liaison avec oniguruma >= 6.8.0.

`mbstring.regex_stack_limit` int

  Limite la profondeur de la pile des expressions régulières mbstring.

En accord avec » HTML 4.01 specification, les navigateurs sont supposés utiliser le même jeu de caractères lorsqu'ils soumettent un formulaire. Mais, tous les navigateurs ne le font pas. Se reporter à la fonction mb_http_input() pour détecter les jeux de caractères utilisés par les navigateurs.

En général, les navigateurs sont suffisamment intelligents pour détecter les jeux de caractères dans le HTML. Néanmoins, il convient de définir le paramètre `charset` de l'en-tête HTTP `Content-Type` à la valeur fournie par la fonction header() ou par l'option de configuration default_charset.

Exemple #1 Configuration de php.ini pour mbstring

    ; Langage par défaut
    mbstring.language        = Neutral; (UTF-8) (par défaut)
    mbstring.language        = English; Anglais
    mbstring.language        = Japanese; Japonais

    ;; Jeu de caractère interne
    ;; Note : assurez-vous que ce jeu fonctionne avec PHP
    mbstring.internal_encoding    = UTF-8

    ;; Activation de la conversion automatique des entrées HTTP
    mbstring.encoding_translation = On

    ;; Jeu de caractères par défaut pour les données d'entrée HTTP
    ;; Note : le script ne peut pas changer cette configuration
    mbstring.http_input           = pass    ; Aucune conversion.
    mbstring.http_input           = auto    ; Utilise auto
                                    ; "auto" est remplacé suivant mbstring.language
    mbstring.http_input           = SJIS    ; Utilise SJIS
    mbstring.http_input           = UTF-8,SJIS,EUC-JP ; Spécifie l'ordre

    ;;Jeu de caractères par défaut pour les données de sortie HTTP
    mbstring.http_output          = pass    ; Aucune conversion
    mbstring.http_output          = UTF-8   ; Utilise UTF-8

    ;; Ordre de détection des jeux de caractères
    mbstring.detect_order         = auto    ; Utilise la détection automatique
    mbstring.detect_order         = ASCII,JIS,UTF-8,SJIS,EUC-JP ; Spécifie l'ordre

    ;; Déterminer le jeu de caractères de substitution par défaut
    mbstring.substitute_character = 12307   ; Spécifie une valeur Unicode
    mbstring.substitute_character = none    ; Ne pas afficher de caractères
    mbstring.substitute_character = long    ; Exemple complet : U+3000,JIS+7E7E

Exemple #2 Configuration de php.ini pour les utilisateurs de `EUC-JP`

    ;; Désactive la bufferisation de sortie
    output_buffering      = Off

    ;; Choisit le jeu de caractères
    default_charset       = EUC-JP

    ;; Le langage par défaut est le japonais
    mbstring.language = Japanese

    ;; Activation de la traduction automatique des données d'entrée HTTP
    mbstring.encoding_translation = On

    ;; Activation de la conversion automatique
    mbstring.http_input   = auto

    ;; Convertit les sorties en EUC-JP
    mbstring.http_output  = EUC-JP

    ;; Utilise le jeu de caractères interne EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; Ne pas afficher les caractères invalides
    mbstring.substitute_character = none

Exemple #3 Configuration de php.ini pour les utilisateurs de `SJIS`

    ;; Active la bufferisation de sortie
    output_buffering     = On

    ;; Utilise le gestionnaire mb_output_handler pour la conversion de sortie
    output_handler       = mb_output_handler

    ;; Choisit le jeu de caractères
    default_charset      = Shift_JIS

    ;; Le langage par défaut est le japonais
    mbstring.language = Japanese

    ;; Activation de la traduction automatique des données d'entrée HTTP
    mbstring.http_input  = auto

    ;; Convertit en SJIS
    mbstring.http_output = SJIS

    ;;Utilise le jeu de caractères interne EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; Ne pas afficher les caractères invalides
    mbstring.substitute_character = none

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`MB_OVERLOAD_MAIL` (int)
  Supprimée à partir de PHP 8.0.0.
`MB_OVERLOAD_STRING` (int)
  Supprimée à partir de PHP 8.0.0.
`MB_OVERLOAD_REGEX` (int)
  Supprimée à partir de PHP 8.0.0.
`MB_CASE_UPPER` (int)
  Convertit tous les caractères en majuscule. Ceci peut modifier la longueur de la chaîne. C'est le mode utilisé par la fonction mb_strtoupper().
`MB_CASE_LOWER` (int)
  Convertit tous les caractères en minuscule. Ceci peut modifier la longueur de la chaîne. C'est le mode utilisé par la fonction mb_strtolower().
`MB_CASE_TITLE` (int)
  Réalise une conversion de la casse du titre, basée sur les propriétés unicode Cased et CaseIgnorable. En particulier, ceci améliore la gestion des guillemets et des apostrophes. Ceci peut modifier la longueur de la chaîne.
`MB_CASE_FOLD` (int)
  Réalise une conversion totale de la casse, qui supprime les distinctions dues à la casse dans la chaîne. Ceci est utilisé pour réaliser des correspondances insensibles à la casse. Ceci peut modifier la longueur de la chaîne. Disponible à partir de PHP 7.3.
`MB_CASE_LOWER_SIMPLE` (int)
  Réalise une conversion simple en minuscule. Ceci ne modifie pas la longueur de la chaîne de caractères. Disponible à partir de PHP 7.3.
`MB_CASE_UPPER_SIMPLE` (int)
  Réalise une conversion simple en majuscule. Ceci ne modifie pas la longueur de la chaîne de caractères. Disponible à partir de PHP 7.3.
`MB_CASE_TITLE_SIMPLE` (int)
  Réalise une conversion simple du titre. Ceci ne modifie pas la longueur de la chaîne. Disponible à partir de PHP 7.3.
`MB_CASE_FOLD_SIMPLE` (int)
  Réalise une conversion de la casse simple, qui supprime les distinctions de casse présentes dans la chaîne. Ceci est utilisé pour la correspondance insensible à la casse. Ceci ne modifie pas la longueur de la chaîne. Utilisé pour les opérations insensibles à la casse, en interne par l'extension MBString. Disponible à partir de PHP 7.3.
`MB_ONIGURUMA_VERSION` (string)
  La version d'Oniguruma, par exemple `6.9.4`. Disponible à partir de PHP 7.4.

# Jeux de caractères supportés

Jeux de caractères supportés
Nom dans le registre IANA | Jeux de caractères | Description | Notes
--- | --- | --- | ---
ISO-10646-UCS-4 | ISO 10646 | Le jeu de caractères universel (`Universal Character Set`), avec 31 bits par caractère, au standard `UCS-4` par `ISO/IEC 10646`. Il est synchronisé avec la dernière version d'Unicode. | Si ce nom est utilisé dans l'outil de conversion, le convertisseur essaie de reconnaître le texte à partir du dernier BOM (`byte order mark`), pour connaître l'ordre des bits.
ISO-10646-UCS-4 | UCS-4 | Voir ci-dessus. | Contrairement à `UCS-4`, les chaînes sont supposées être au format big endian.
ISO-10646-UCS-4 | UCS-4 | Voir ci-dessus. | Contrairement à `UCS-4`, les chaînes sont supposées être au format little endian.
ISO-10646-UCS-2 | UCS-2 | Le jeu de caractères universel (`Universal Character Set`), avec 16 bits par caractère, au standard `UCS-2` par `ISO/IEC 10646`. Il est synchronisé avec la dernière version d'Unicode. | Si ce nom est utilisé dans l'outil de conversion, le convertisseur essaie de reconnaître le texte à partir du dernier BOM (`byte order mark`), pour connaître l'ordre des bits.
ISO-10646-UCS-2 | UCS-2 | Voir ci-dessus. | Contrairement à `UCS-2`, les chaînes sont supposées être au format big endian.
ISO-10646-UCS-2 | UCS-2 | Voir ci-dessus. | Contrairement à `UCS-2`, les chaînes sont supposées être au format little endian.
UTF-32 | Unicode | Format de transformation d'Unicode, de 32 bits, dont les cartes correspondent au jeu standard Unicode. Ce jeu n'est pas identique à `UCS-4` car les caractères Unicode étaient limités à des valeurs de 21 bits. | Si ce nom est utilisé dans l'outil de conversion, le convertisseur essaie de reconnaître le texte à partir du dernier BOM (`byte order mark`), pour connaître l'ordre des bits.
UTF-32BE | Unicode | Voir ci-dessus. | Contrairement à `UTF-32`, les chaînes sont supposées être au format big endian.
UTF-32LE | Unicode | Voir ci-dessus. | Contrairement à `UTF-32`, les chaînes sont supposées être au format little endian.
UTF-16 | Unicode | Format de transformation d'Unicode sur 16 bits. Il faut noter que `UTF-16` n'est plus identique à `UCS-2` car un mécanisme a été introduit en Unicode 2.0 et `UTF-16` fait maintenant référence à un codage de 21 bits. | Si ce nom est utilisé dans l'outil de conversion, le convertisseur essaie de reconnaître le texte à partir du dernier BOM (`byte order mark`), pour connaître l'ordre des bits.
UTF-16BE | Unicode | Voir ci-dessus. | Contrairement à `UTF-16`, les chaînes sont supposées être au format big endian.
UTF-16LE | Unicode | Voir ci-dessus. | Contrairement à `UTF-16`, les chaînes sont supposées être au format little endian.
UTF-8 | Unicode / UCS | Format de transformation Unicode de 8 bits. | none
UTF-7 | Unicode | Un format compatible avec le courrier électronique d'Unicode, spécifié dans » RFC2152. | none
aucun | Unicode | Une variante d'`UTF-7` qui est spécialement utilisée dans le » protocole IMAP. | none
US-ASCII (recommandé) / iso-ir-6 / ANSI_X3.4-1986 / ISO_646.irv:1991 / ASCII / ISO646-US / us / IBM367 / CP367 / csASCII | ASCII / ISO 646 | ASCII, `American Standard Code for Information Interchange` est un format classique de 7 bits. Il est aussi normalisé internationalement, sous le nom `ISO 646`. | (none)
EUC-JP (recommandé) / Extended_UNIX_Code_Packed_Format_for_Japanese / csEUCPkdFmtJapanese | Composé d'US-ASCII / JIS X0201:1997 (hankaku kana) / JIS X0208:1990 / JIS X0212:1990 | Comme on peut le voir, le nom est dérivé de l'abréviation de `Extended UNIX Code Packed Format for Japanese`, ce jeu est essentiellement utilisé sur les plates-formes Unix. Le jeu original, `Extended UNIX Code`, est conçu sur la base de `ISO 2022`. | Le jeu identifié par `EUC-JP` est différent de `IBM932 / CP932`, qui est utilisé par `OS/2®` et Microsoft® Windows®. Pour échanger des informations avec ces plates-formes, utiliser `EUCJP-WIN`.
Shift_JIS (recommandé) / MS_Kanji / csShift_JIS | Composé de JIS X0201:1997 / JIS X0208:1997 | `Shift_JIS` a été développé au début des années 80, et, au même moment, les premiers traitements de textes étaient mis sur le marché. Il a été fait pour conserver la compatibilité avec le jeu `JIS X 0201:1976`. Selon la définition de l'IANA, le jeu de caractères `Shift_JIS` est légèrement différent de `IBM932 / CP932`. Cependant, les noms `"SJIS"` et `"Shift_JIS"` sont souvent utilisés à tort, pour ces jeux. | Pour `CP932`, utiliser `SJIS-WIN`.
(none) | Composé de JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions | Même si ce "jeu de caractères" utilise le même jeu que `EUC-JP`, il est en fait différent. Il a juste quelques caractères de différence. | none
Windows-31J / csWindows31J | Composé de JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions | Même si ce "jeu de caractères" utilise le même jeu que `Shift_JIS`, il est en fait différent. Il a juste quelques caractères de différence. | (none)
ISO-2022-JP (recommandé) / csISO2022JP | US-ASCII / JIS X0201:1976 / JIS X0208:1978 / JIS X0208:1983 | » RFC1468 | aucun
JIS |  |  |
ISO-8859-1 |  |  |
ISO-8859-2 |  |  |
ISO-8859-3 |  |  |
ISO-8859-4 |  |  |
ISO-8859-5 |  |  |
ISO-8859-6 |  |  |
ISO-8859-7 |  |  |
ISO-8859-8 |  |  |
ISO-8859-9 |  |  |
ISO-8859-10 |  |  |
ISO-8859-13 |  |  |
ISO-8859-14 |  |  |
ISO-8859-15 |  |  |
ISO-8859-16 |  |  |
byte2be |  |  |
byte2le |  |  |
byte4be |  |  |
byte4le |  |  |
BASE64 |  |  |
HTML-ENTITIES |  |  |
7bit |  |  |
8bit |  |  |
EUC-CN |  |  |
CP936 |  |  |
HZ |  |  |
EUC-TW |  |  |
CP950 |  |  |
BIG-5 |  |  |
EUC-KR |  |  |
UHC (CP949) |  |  |
ISO-2022-KR |  |  |
Windows-1251 (CP1251) |  |  |
Windows-1252 (CP1252) |  |  |
CP866 (IBM866) |  |  |
KOI8-R |  |  |
KOI8-U |  |  |

# Cas des caractères japonais

Les caractères japonais ne peuvent être représentés qu'avec des encodages multioctets et les standards d'encodage multiple sont utilisés suivant la plate-forme et le texte de référence. Pour faciliter les choses, ces standards d'encodages diffèrent légèrement les uns des autres. Pour développer des applications Web en environnement japonais, le développeur devra garder à l'esprit ces complexités afin de s'assurer que l'encodage de caractères correct est utilisé.

- La taille nécessaire à un caractère peut aller jusqu'à six octets.
- Un caractère japonais multioctets occupe généralement deux octets, à comparer avec les caractères mono-octet traditionnellement utilisés. Ces caractères sont appelés `"zen-kaku"`, ce qui signifie `"grande largeur"`. Les plus petits sont appelés `"han-kaku"`, ce qui signifie `"demi-largeur"`.
- Certains encodages de caractères utilisent des séquences `"shift"` (escape) définies dans la référence ISO-2022 pour basculer vers la carte d'encodage du code spécifique (`00h` à `7fh`).
- ISO-2022-JP doit être utilisé pour les protocoles SMTP/NNTP, et les en-têtes ainsi que les entités devraient être réencodés en accord avec la RFC correspondante. Bien que cela ne soit pas requis, ça reste une bonne idée car beaucoup de user-agent (agents utilisateurs) populaires ne peuvent pas reconnaître d'autre méthode d'encodage.
- Les pages Web créées pour les téléphones portables comme » i-mode, ou » EZweb sont supposées utiliser l'encodage Shift_JIS.
- Les emojis utilisés pour les téléphones mobiles, tel que » i-mode ou » EZweb sont supportés.

# Entrées/Sorties HTTP

La conversion automatique des entrées/sorties HTTP peut aussi convertir des données binaires. Les utilisateurs doivent contrôler les conversions, si des données binaires doivent être utilisées via HTTP.

> Note:

> Si l'attribut `enctype` de la balise `form` vaut `multipart/form-data` et que la directive du php.ini est positionnée à On, les variables et les noms de fichiers téléchargés en méthode POST seront convertis avec l'encodage interne. Cependant, la conversion n'est pas appliquée aux clés de la requête.

- Entrée HTTP

  Il n'y a pas de moyens de contrôler la conversion des caractères HTTP en entrée, depuis un script PHP. Pour désactiver cette conversion, il faut le faire dès le fichier php.ini.

  Exemple #1 Désactive la conversion HTTP dans le php.ini

      ;; Disable HTTP Input conversion
      mbstring.http_input = pass
      ;; Disable HTTP Input conversion
      mbstring.encoding_translation = Off

  Lorsqu'on utilise PHP comme module Apache, il est possible d'annuler la configuration du php.ini pour chaque Virtual Host dans le fichier httpd.conf ou par dossier avec le fichier `.htaccess`. Se reporter à la section de configuration ainsi qu'au manuel Apache.

- Sorties HTTP

  Il y a plusieurs moyens d'activer la conversion en sortie de script PHP. L'un d'entre eux utilise php.ini, un autre utilise ob_start() avec la fonction mb_output_handler() comme fonction de rappel.

Exemple #2 Exemple de configuration de mbstring dans php.ini

    ;; Enable output character encoding conversion for all PHP pages

    ;; Enable Output Buffering
    output_buffering    = On

    ;; Set mb_output_handler to enable output conversion
    output_handler      = mb_output_handler

Exemple #3 Exemple de script avec mbstring

    <?php

    // Enable output character encoding conversion only for this page

    // Set HTTP output character encoding to SJIS
    mb_http_output('SJIS');

    // Start buffering and specify "mb_output_handler" as
    // callback function
    ob_start('mb_output_handler');

    ?>

# Jeux de caractères supportés

Actuellement, les jeux de caractères suivants sont supportés par `mbstring`. L'encodage de caractère peut être spécifié par les paramètres `encoding` dans les fonctions `mbstring`.

Les jeux de caractères suivants sont supportés par `mbstring` :

- UCS-4*
- UCS-4BE
- UCS-4LE*
- UCS-2
- UCS-2BE
- UCS-2LE
- UTF-32*
- UTF-32BE*
- UTF-32LE*
- UTF-16*
- UTF-16BE*
- UTF-16LE*
- UTF-7
- UTF7-IMAP
- UTF-8*
- ASCII*
- EUC-JP*
- SJIS*
- eucJP-win*
- SJIS-win*
- ISO-2022-JP
- ISO-2022-JP-MS
- CP932
- CP51932
- SJIS-mac (alias: MacJapanese)
- SJIS-Mobile#DOCOMO (alias: SJIS-DOCOMO)
- SJIS-Mobile#KDDI (alias: SJIS-KDDI)
- SJIS-Mobile#SOFTBANK (alias: SJIS-SOFTBANK)
- UTF-8-Mobile#DOCOMO (alias: UTF-8-DOCOMO)
- UTF-8-Mobile#KDDI-A
- UTF-8-Mobile#KDDI-B (alias: UTF-8-KDDI)
- UTF-8-Mobile#SOFTBANK (alias: UTF-8-SOFTBANK)
- ISO-2022-JP-MOBILE#KDDI (alias: ISO-2022-JP-KDDI)
- JIS
- JIS-ms
- CP50220
- CP50220raw
- CP50221
- CP50222
- ISO-8859-1*
- ISO-8859-2*
- ISO-8859-3*
- ISO-8859-4*
- ISO-8859-5*
- ISO-8859-6*
- ISO-8859-7*
- ISO-8859-8*
- ISO-8859-9*
- ISO-8859-10*
- ISO-8859-13*
- ISO-8859-14*
- ISO-8859-15*
- ISO-8859-16*
- byte2be
- byte2le
- byte4be
- byte4le
- BASE64
- HTML-ENTITIES (alias: HTML)
- 7bit
- 8bit
- EUC-CN*
- CP936
- GB18030
- HZ
- EUC-TW*
- CP950
- BIG-5*
- EUC-KR*
- UHC (alias: CP949)
- ISO-2022-KR
- Windows-1251 (alias: CP1251)
- Windows-1252 (alias: CP1252)
- CP866 (alias: IBM866)
- KOI8-R*
- KOI8-U*
- ArmSCII-8 (alias: ArmSCII8)

* : encodages également utilisables dans les expressions régulières.

Toutes les entrées du php.ini qui acceptent un nom d'encodage peuvent également utiliser les valeurs "`auto`" et "`pass`". Les fonctions `mbstring`, qui acceptent des noms de jeux de caractères, peuvent également utiliser la valeur "`auto`".

Si "`pass`" est utilisée, aucune conversion n'est effectuée.

Si "`auto`" est défini, la liste sera étendue à la liste des encodages définis par NLS. Par exemple, si `NLS` vaut `Japanese`, les valeurs seront "`ASCII,JIS,UTF-8,EUC-JP,SJIS`".

Voir aussi mb_detect_order().

# Fonctionnalité de surcharge de fonctions

Avertissement

Cette fonctionnalité est OBSOLÈTE à partir de PHP 7.2.0, et SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonctionnalité est fortement déconseillé.

Il est possible que l'on trouve difficile de faire fonctionner une application PHP existante dans un environnement multioctets. Ceci est dû au fait que la plupart des applications PHP sont écrites avec des fonctions de chaînes de caractères standards comme la fonction substr(), qui est connue pour ne pas gérer proprement les chaînes multioctets.

Mbstring supporte aussi la surcharge de fonctions, pour permettre le support des chaînes multioctets sans modifier les scripts PHP. En utilisant ce système de surcharge de fonctions, certaines fonctions PHP seront remplacées par leur équivalent de mbstring. Par exemple mb_substr() remplacera substr(). Ce système de remplacement transparent, permet un portage simple et efficace des applications.

Pour utiliser la surcharge de fonctions, définissez `mbstring.func_overload`, dans le php.ini, à une valeur positive qui représente une combinaison de masques d'octets spécifiant les catégories de fonctions à surcharger. Il doit être défini à 1 pour surcharger la fonction mail(), 2 pour les fonctions de chaînes, 4 pour les fonctions d'expression régulières. Par exemple, avec la valeur 7, toutes les fonctions précédentes seront surchargées. Voici la liste complète des fonctions surchargées, avec leur fonction de remplacement.

Fonctions de remplacement
Valeur de mbstring.func_overload | Fonction originale | Fonction de remplacement
--- | --- | ---
1 | mail() | mb_send_mail()
2 | strlen() | mb_strlen()
2 | strpos() | mb_strpos()
2 | strrpos() | mb_strrpos()
2 | substr() | mb_substr()
2 | strtolower() | mb_strtolower()
2 | strtoupper() | mb_strtoupper()
2 | stripos() | mb_stripos()
2 | strripos() | mb_strripos()
2 | strstr() | mb_strstr()
2 | stristr() | mb_stristr()
2 | strrchr() | mb_strrchr()
2 | substr_count() | mb_substr_count()

> Note:

> Il n'est pas recommandé d'utiliser le remplacement des fonctions mbstring dans un contexte de `per-directory`, car il n'est pas confirmé encore qu'elles sont suffisamment stables dans un environnement de production et peuvent conduire à des résultats incohérents.

# Prérequis de l'encodage en PHP

Les jeux de caractères suivants sont bien supportés par PHP.

- Jeux de caractères mono-octets :

  - qui sont compatibles avec la norme ASCII (compatible ISO646) pour les caractères de l'intervalle `00h` à `7fh`.

- Jeux de caractères multioctets :

  - qui sont compatibles avec la norme ASCII (compatible ISO646) pour les caractères de l'intervalle `00h` à `7fh`.
  - qui n'utilisent pas les séquences de type ISO2022.
  - qui n'utilisent pas de valeur dans l'intervalle `00h` à `7fh` dans les séquences composées, qui représentent un caractère unique.

Les jeux de caractères suivants risquent de ne pas fonctionner en PHP.

    JIS, SJIS, ISO-2022-JP, BIG-5

Même si aucun script PHP écrit avec ces jeux de caractères ne fonctionne, notamment si des chaînes encodées sont utilisées comme identifiants, ou valeurs littérales dans le script, il est possible d'éviter d'utiliser ces jeux en activant le filtre transparent `mbstring` pour les données d'entrées HTTP.

> Note:

> Il est déconseillé d'utiliser les jeux SJIS, BIG5, CP936, CP949 et GB18030 pour l'encodage interne, à moins que l'on ne soit très familier avec l'analyseur, l'exécuteur et le jeu de caractère lui-même.

> Note:

> Si l'on se connecte à une base de données avec PHP, il est recommandé d'utiliser le même jeu de caractères pour la base de données et pour le `jeu interne` pour améliorer le confort d'utilisation mais aussi les performances.

> Lors de l'utilisation de PostgreSQL, le jeu de caractères utilisé dans la base de données et celui de PHP peuvent différer car cette base supporte la traduction automatique de jeu de caractères.

# Fonctions sur les chaînes de caractères multioctets

# Références

Les jeux de caractères multioctets et leurs techniques sont très complexes et ne peuvent être traités totalement dans cette documentation. Se reporter aux URL suivantes pour d'autres ressources complémentaires :

- Unicode/UTF/UCS/etc

  » http://www.unicode.org/

- Japonais/coréen/Chinois

  » https://resources.oreilly.com/examples/9781565922242/blob/master/doc/cjk.inf

# mb_check_encoding

(PHP 4 >= 4.4.3, PHP 5 >= 5.1.3, PHP 7, PHP 8)

mb_check_encoding — Vérifie si les chaînes sont valides pour l'encodage spécifié

### Description

function mb_check_encoding(array|string|null `$value` = `null`, ?string `$encoding` = `null`): bool

Vérifie si le flux d'octets est valide pour l'encodage spécifique. Si `value` est de type tableau, toutes les clés et les valeurs sont validées de manière récursive. Il est utile pour prévenir ce que l'on appelle « l'attaque par encodage invalide ».

### Liste de paramètres

`value`

  Le flux d'octets ou tableau à vérifier. Si elle est omise, cette fonction vérifie toutes les entrées depuis le début de la requête.

  Avertissement

  À partir de PHP 8.1.0, l'omission de ce paramètre ou le passage de `null` est obsolète.

`encoding`

  Encodage attendu.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | L'appel de cette fonction avec `null` comme `value` ou sans argument est obsolète.
8.0.0 | `value` et `encoding` sont désormais nullable.
7.2.0 | Cette fonction accepte maintenant également un tableau comme valeur de `value`. Auparavant, seules les chaîne de caractères étaient prises en charge.

# mb_chr

(PHP 7 >= 7.2.0, PHP 8)

mb_chr — Retourne un caractère par sa valeur de point de code Unicode

### Description

function mb_chr(int `$codepoint`, ?string `$encoding` = `null`): string|false

Retourne une chaîne contenant le caractère spécifié par la valeur du point de code Unicode, encodé dans l'encodage spécifié.

Cette fonction complémente mb_ord().

### Liste de paramètres

`codepoint`

  Une valeur de point de code Unicode, p. ex. `128024` pour U+1F418 ELEPHANT

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Une chaîne contenant le caractère demandé, s'il peut être représenté dans l'encodage spécifié ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Test de différents codepoint

    <?php
    $values = [65, 63, 0x20AC, 128024];
    foreach ($values as $value) {
        var_dump(mb_chr($value, 'UTF-8'));
        var_dump(mb_chr($value, 'ISO-8859-1'));
    }
    ?>

L'exemple ci-dessus va afficher :

    string(1) "A"
    string(1) "A"
    string(1) "?"
    string(1) "?"
    string(3) "€"
    bool(false)
    string(4) "🐘"
    bool(false)

### Voir aussi

- mb_internal_encoding() - Lit/modifie l'encodage interne
- mb_ord() - Récupère le point de code Unicode d'un caractère
- IntlChar::ord() - Renvoie la valeur du point de code Unicode d'un caractère
- chr() - Générer une chaîne d'un octet à partir d'un nombre

# mb_convert_case

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_convert_case — Modifie la casse d'une chaîne

### Description

function mb_convert_case(string `$string`, int `$mode`, ?string `$encoding` = `null`): string

Effectue la modification de la casse de la chaîne spécifiée, suivant le `mode` spécifié.

### Liste de paramètres

`string`

  La chaîne à convertir.

`mode`

  Le mode de conversion. Peut être un parmi : `MB_CASE_UPPER`, `MB_CASE_LOWER`, `MB_CASE_TITLE`, `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE`, `MB_CASE_FOLD_SIMPLE`.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

La chaîne dont la casse a été changée, suivant le `mode` fourni.

### Historique

Version | Description
--- | ---
8.3.0 | Mise en œuvre des règles de mise en minuscule conditionnelle pour la lettre grecque sigma, qui s'appliquent uniquement aux modes `MB_CASE_LOWER` et `MB_CASE_TITLE`, mais pas aux modes `MB_CASE_LOWER_SIMPLE` et `MB_CASE_TITLE_SIMPLE`.
7.3.0 | Ajout du support de `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE`, et `MB_CASE_FOLD_SIMPLE` en tant que `mode`.

### Exemples

Exemple #1 Exemple avec mb_convert_case()

    <?php
    $str = "mary had a Little lamb and she loved it so";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

Exemple #2 Exemple avec mb_convert_case() avec du texte UTF-8 non latin

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

### Notes

Contrairement aux fonctions standards comme strtolower() et strtoupper(), la modification est réalisée en se basant sur le dictionnaire Unicode. Par conséquent, le comportement de cette fonction n'est pas modifié par des configurations locales, et il peut convertir n'importe quel caractère qui a des propriétés alphabétiques, comme le a majuscule tréma (`A-umlaut`, Ä).

Pour plus d'informations sur les propriétés de l'Unicode, visitez le site de » http://www.unicode.org/reports/tr21/.

### Voir aussi

- mb_strtolower() - Met tous les caractères en minuscules
- mb_strtoupper() - Met tous les caractères en majuscules
- strtolower() - Renvoie une chaîne en minuscules
- strtoupper() - Renvoie une chaîne en majuscules
- ucfirst() - Met le premier caractère en majuscule
- ucwords() - Met en majuscule la première lettre de tous les mots

# mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_encoding — Convertir une chaîne d'un codage de caractères à un autre

### Description

function mb_convert_encoding(array|string `$string`, string `$to_encoding`, array|string|null `$from_encoding` = `null`): array|string|false

Convertit la `string` à partir de `from_encoding`, ou l'encodage interne actuel, en `to_encoding`. Si `string` est un tableau, toutes ses valeurs chaîne de caractères seront converties récursivement.

### Liste de paramètres

`string`

  La chaîne de caractères ou tableau à convertir.

`to_encoding`

  L'encodage désiré du résultat.

`from_encoding`

  L'encodage actuel utilisé pour interpréter la `string`. Plusieurs encodages peuvent être spécifiés sous forme de tableau (tableau) ou de liste séparée par des virgules. Dans ce cas, l'encodage correct sera deviné en utilisant le même algorithme que mb_detect_encoding().

  Si `from_encoding` est omis ou `null`, le paramètre mbstring.internal_encoding sera utilisé s'il est défini, sinon le paramètre default_charset sera utilisé.

  Voir encodages pris en charge pour les valeurs valides de `to_encoding` et `from_encoding`.

### Valeurs de retour

La chaîne de caractères ou tableau encodé en cas de succès, ou `false` si une erreur survient.

### Erreurs / Exceptions

À partir de PHP 8.0.0, une ValueError est lancée si la valeur de `to_encoding` ou `from_encoding` est un encodage invalide. Antérieur à PHP 8.0.0, une `E_WARNING` était émise à la place.

### Historique

Version | Description
--- | ---
8.2.0 | mb_convert_encoding() ne renverra plus les encodages non textuels suivants : `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` et `"8 bit"`.
8.0.0 | mb_convert_encoding() lancera désormais une ValueError quand un encodage invalide est passé à `to_encoding`.
8.0.0 | mb_convert_encoding() lancera désormais une ValueError quand un encodage invalide est passé à `from_encoding`.
8.0.0 | `from_encoding` est désormais nullable.
7.2.0 | Cette fonction accepte désormais un tableau en tant que `string`. Auparavant, seulement les chaîne de caractères étaient supportées.

### Exemples

Exemple #1 Exemple avec mb_convert_encoding()

    <?php
    /* Convertit l'encodage interne vers SJIS */
    $str = mb_convert_encoding($str, "SJIS");

    /* Convertit EUC-JP en UTF-7 */
    $str = mb_convert_encoding($str, "UTF-7", "EUC-JP");

    /* Détecte automatiquement un encodage entre JIS, eucjp-win ou sjis-win,
       Puis convertit en UCS-2LE */
    $str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win");

    /* Si mbstring.language est "Japanese", "auto" est étendu à "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
    $str = mb_convert_encoding($str, "EUC-JP", "auto");
    ?>

### Voir aussi

- mb_detect_order() - Lit/modifie l'ordre de détection des encodages
- UConverter::transcode() - Convertit une chaîne d'un jeu de caractères à un autre
- iconv() - Convertit une chaîne de caractères à partir d'un encodage vers un autre

# mb_convert_kana

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_kana — Convertit un "kana" en un autre ("zen-kaku", "han-kaku" et plus)

### Description

function mb_convert_kana(string `$string`, string `$mode` = "KV", ?string `$encoding` = `null`): string

Effectue une conversion "han-kaku" - "zen-kaku" sur la chaîne `string`. Cette fonction est uniquement utile pour les japonais.

### Liste de paramètres

`string`

  La chaîne à convertir.

`mode`

  L'option de conversion.

  Spécifier les conversions en combinant les valeurs suivantes.

  Options de conversions disponibles
  Option | Signification
  --- | ---
  `r` | Convertit l'alphabet "zen-kaku" en "han-kaku"
  `R` | Convertit l'alphabet "han-kaku" en "zen-kaku"
  `n` | Convertit les nombres "zen-kaku" en "han-kaku"
  `N` | Convertit les nombres "han-kaku" en "zen-kaku"
  `a` | Convertit les nombres et alphabet "zen-kaku" en "han-kaku"
  `A` | Convertit les nombres et alphabet "han-kaku" en "zen-kaku". (Les caractères inclus dans les options "a", "A" sont U+0021 - U+007E en excluant U+0022, U+0027, U+005C, U+007E)
  `s` | Convertit "zen-kaku" en "han-kaku" (U+3000 -> U+0020)
  `S` | Convertit "han-kaku" en "zen-kaku" (U+0020 -> U+3000)
  `k` | Convertit "zen-kaku kata-kana" en "han-kaku kata-kana"
  `K` | Convertit "han-kaku kata-kana" en "zen-kaku kata-kana"
  `h` | Convertit "zen-kaku hira-gana" en "han-kaku kata-kana"
  `H` | Convertit "han-kaku kata-kana" en "zen-kaku hira-gana"
  `c` | Convertit "zen-kaku kata-kana" en "zen-kaku hira-gana"
  `C` | Convertit "zen-kaku hira-gana" en "zen-kaku kata-kana"
  `V` | Supprime les notations vocales, et les convertit en caractères. À utiliser avec "K","H"

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

La chaîne convertie.

### Erreurs / Exceptions

Lance une ValueError si la combinaison de différents `mode` n'est pas valide. Par exemple `"sS"`.

### Historique

Version | Description
--- | ---
8.2.0 | Une ValueError est désormais lancée si la combinaison de différents `mode`s n'est pas valide.
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Exemple avec mb_convert_kana()

    <?php
    /* Convertit tous les "han-kaku" "kata-kana" en "zen-kaku" "hira-gana" */
    echo mb_convert_kana('ﾔﾏﾀﾞ ﾊﾅｺ', "HV") . "\n";

    /* Convertit "han-kaku" "kata-kana" en "zen-kaku" "kata-kana"
       et "zen-kaku" alphanumérique en "han-kaku" */
    echo mb_convert_kana('ｺｳｻﾞﾊﾞﾝｺﾞｳ ０１２３４５６', "KVa") . "\n";
    ?>

L'exemple ci-dessus va afficher :

    やまだ はなこ
    コウザバンゴウ 0123456

# mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_variables — Convertit l'encodage de variables

### Description

function mb_convert_variables(
string `$to_encoding`,
array|string `$from_encoding`,
mixed `&$var`,
mixed `&...$vars`
): string|false

Convertit l'encodage des variables `var` et `vars` depuis l'encodage `from_encoding` vers l'encodage `to_encoding`

mb_convert_variables() place les chaînes dans un tableau ou un objet pour détecter l'encodage, mais la détection a tendance à échouer pour les chaînes de caractères de petites tailles. De ce fait, il est impossible de mixer les encodages dans un tableau ou un objet "simple".

### Liste de paramètres

`to_encoding`

  L'encodage dans lequel la chaîne doit être convertie.

`from_encoding`

  `from-encoding` est une liste d'encodages possibles pour les variables `vars`, fourni sous forme d'un tableau ou d'une liste d'encodages, séparés par des virgules. Si `from_encoding` est omis, les encodages fournis dans mb_detect_order() sont utilisés.

`var`

  `var` est une référence sur une variable à convertir. Les chaînes, tableaux et objets sont aussi supportés. mb_convert_variables() prend tous ces paramètres avec le même encodage.

`vars`

  Variables additionnelles.

### Valeurs de retour

L'encodage avant conversion en cas de succès, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mb_convert_variables()

    <?php
    /* Convertit les variables $post1, $post2 en encodage interne */
    $interenc = mb_internal_encoding();
    $inputenc = mb_convert_variables($interenc, "ASCII,UTF-8,SJIS-win", $post1, $post2);
    ?>

# mb_decode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_mimeheader — Décode un en-tête MIME

### Description

function mb_decode_mimeheader(string `$string`): string

Décode la chaîne encodée `string` dans l'en-tête MIME.

### Liste de paramètres

`string`

  La chaîne à décoder.

### Valeurs de retour

La chaîne décodée, avec un encodage interne.

### Historique

Version | Description
--- | ---
8.3.0 | Les traits de soulignement sont convertis en espaces comme spécifié par » RFC 2047.

### Voir aussi

- mb_encode_mimeheader() - Encode une chaîne pour un en-tête MIME

# mb_decode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_numericentity — Décode les entités HTML en caractères

### Description

function mb_decode_numericentity(string `$string`, array `$map`, ?string `$encoding` = `null`): string

Convertit la chaîne d'entités HTML `string` en chaîne.

### Liste de paramètres

`string`

  La chaîne de caractères à décoder.

`map`

  `map` est un tableau qui spécifie les codes à convertir.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

La chaîne de caractères convertie.

### Erreurs / Exceptions

Lève une exception ValueError si `map` n'est pas une liste d'entiers.

### Historique

Version | Description
--- | ---
8.4.0 | mb_decode_numericentity() lève désormais une exception ValueError si `map` n'est pas une liste d'entiers.
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Exemple avec `map`

    <?php
    $convmap = array (
       int start_code1, int end_code1, int offset1, int mask1,
       int start_code2, int end_code2, int offset2, int mask2,
       // ........
       int start_codeN, int end_codeN, int offsetN, int maskN );
    // Spécifie les valeurs Unicode de début (start_codeN) et fin (end_codeN)
    // Ajoutez offsetN à la valeur, et faites un ET bit-à-bit avec maskN, puis
    // il convertit la valeur obtenue en entité numérique
    ?>

Exemple #2 L'exemple `map` échappe la chaîne JavaScript

    <?php
    function escape_javascript_string($str) {
      $map = [
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,0,0, // 49
              0,0,0,0,0,0,0,0,1,1,
              1,1,1,1,1,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,1,1,1,1,1,1,0,0,0, // 99
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 149
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 199
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 249
              1,1,1,1,1,1,1, // 255
              ];
      // L'encodage de char est UTF-8
      $mblen = mb_strlen($str, 'UTF-8');
      $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
      for ($i=0, $encoded=''; $i < $mblen; $i++) {
          $u = substr($utf32, $i*8, 8);
          $v = base_convert($u, 16, 10);
          if ($v < 256 && $map[$v]) {
            $encoded .= '\\x'.substr($u, 6,2);
          } else if ($v == 2028) {
            $encoded .= '\\u2028';
          } else if ($v == 2029) {
            $encoded .= '\\u2029';
          } else {
            $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
          }
       }
       return $encoded;
    }

    // Données de tests
    $convmap = [ 0x0, 0xffff, 0, 0xffff ];
    $msg = '';
    for ($i=0; $i < 1000; $i++) {
      // chr() ne peut pas générer de données correctes UTF-8 plus grande valeur que 128, utiliser mb_decode_numericentity().
      $msg .= mb_decode_numericentity('&#'.$i.';', $convmap, 'UTF-8');
    }

    // var_dump($msg);
    var_dump(escape_javascript_string($msg));

### Voir aussi

- mb_encode_numericentity() - Encode les caractères en référence numérique HTML

# mb_detect_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_encoding — Détecte un encodage

### Description

function mb_detect_encoding(string `$string`, array|string|null `$encodings` = `null`, bool `$strict` = `false`): string|false

Détecte l'encodage le plus probable pour la chaîne de caractères `string` depuis une liste de candidats.

À partir de PHP 8.1, cette fonction utilise des heuristiques pour détecter lequel des encodages de texte valides dans la liste spécifiée est le plus susceptible d'être correct et peut ne pas être dans l'ordre des `encodings` fournis.

La détection automatique du jeu d'encodage prévu n'est jamais totalement fiable ; sans information additionnelle, c'est similaire à décoder une chaîne chiffrée sans la clé. Il est toujours préférable d'utiliser une indication du jeu d'encodage stockée ou transmise avec les données, tel que l'en-tête HTTP "Content-Type".

Cette fonction est la plus utile avec les encodages multioctets, où pas toutes les séquences d'octets forment une chaîne valide. Si la chaîne d'entrée contient une telle séquence, cet encodage sera rejeté.

Avertissement

# Le résultat n’est pas fiable

Le nom de cette fonction est trompeur, elle effectue une « supposition » plutôt qu’une « détection ».

Les suppositions sont loin d’être précises, et par conséquent, cette fonction ne permet pas de détecter avec fiabilité l’encodage correct des caractères.

### Liste de paramètres

`string`

  La string inspectée.

`encodings`

  Une liste d'encodages de caractères à essayer. Cette liste peut être spécifiée comme un tableau de chaîne de caractères, ou en tant qu'une chaîne de caractères unique séparée par des virgules.

  Si `encodings` est omis ou `null`, le detect_order actuel (défini avec l'option de configuration mbstring.detect_order, ou la fonction mb_detect_order()) sera utilisé.

`strict`

  Contrôle le comportement quand `string` n'est valide dans aucun des `encodings` listés. Si `strict` est défini à `false`, l'encodage qui correspond le plus sera retourné ; si `strict` est défini à `true`, `false` sera retourné.

  La valeur par défaut de `strict` peut être définie avec l'option de configuration mbstring.strict_detection.

### Valeurs de retour

L'encodage de caractère détecté, ou `false` si la chaîne n'est valide dans aucun des encodages listés.

### Historique

Version | Description
--- | ---
8.2.0 | mb_detect_encoding() ne renverra plus les encodages non textuels suivants : `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` et `"8 bit"`.

### Exemples

Exemple #1 Exemple avec mb_detect_encoding()

    <?php

    $str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";

    // Détecte l'encodage avec le detect_order actuel
    var_dump(mb_detect_encoding($str));

    // "auto" est modifié selon mbstring.language
    var_dump(mb_detect_encoding($str, "auto"));

    // Spécifie le paramètre "encodings" avec une liste à virgules
    var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));

    // Utilisation d'un tableau pour spécifier le paramètre "encodings"
    $encodings = [
      "ASCII",
      "JIS",
      "EUC-JP"
    ];
    var_dump(mb_detect_encoding($str, $encodings));
    ?>

L'exemple ci-dessus va afficher :

    string(5) "ASCII"
    string(5) "ASCII"
    string(8) "SJIS-win"
    string(5) "ASCII"

Exemple #2 Effet du paramètre `strict`

    <?php
    // 'áéóú' encodées en ISO-8859-1
    $str = "\xE1\xE9\xF3\xFA";

    // La chaîne n'est pas valide en ASCII ou UTF-8, mais l'UTF-8 est considéré comme une correspondance plus proche
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

    // Si un encodage valide est trouvé, le paramètre strict ne change pas le résultat
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], true));
    ?>

L'exemple ci-dessus va afficher :

    string(5) "UTF-8"
    bool(false)
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"

Dans certains cas, la même séquence d'octets peut former une chaîne valide dans différents encodages de caractères, et il est impossible de déterminer quelle interprétation était prévue. Un exemple, parmi tant d'autres, la séquence d'octets "\xC4\xA2" pourrait être :

- "Ä¢" (U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS suivi d'U+00A2 CENT SIGN) encodé en ISO-8859-1, ISO-8859-15, ou Windows-1252
- "ФЂ" (U+0424 CYRILLIC CAPITAL LETTER EF suivi d'U+0402 CYRILLIC CAPITAL LETTER DJE) encodé en ISO-8859-5
- "Ģ" (U+0122 LATIN CAPITAL LETTER G WITH CEDILLA) encodé en UTF-8

Exemple #3 Effet de l'ordre quand plusieurs encodages correspondent

    <?php
    $str = "\xC4\xA2";

    // La chaîne est valide dans les trois encodages, mais le premier listé n'est pas toujours celui retourné
    var_dump(mb_detect_encoding($str, ['UTF-8']));
    var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5'])); // as of php8.1 this returns ISO-8859-1 instead of UTF-8
    var_dump(mb_detect_encoding($str, ['ISO-8859-1', 'ISO-8859-5', 'UTF-8']));
    var_dump(mb_detect_encoding($str, ['ISO-8859-5', 'UTF-8', 'ISO-8859-1']));
    ?>

L'exemple ci-dessus va afficher :

    string(5) "UTF-8"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-5"

### Voir aussi

- mb_detect_order() - Lit/modifie l'ordre de détection des encodages

# mb_detect_order

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_order — Lit/modifie l'ordre de détection des encodages

### Description

function mb_detect_order(array|string|null `$encoding` = `null`): array|bool

Remplace l'ordre de détection des encodages courant par `encoding`.

### Liste de paramètres

`encoding`

  `encoding` est un tableau, ou une liste d'encodages séparés par une virgule. Voir les encodages supportés.

  Si `encoding` est omis ou `null`, mb_detect_order() retourne l'ordre de détection courant des encodages dans un tableau.

  Ce paramétrage affecte les fonctions mb_detect_encoding() et mb_send_mail().

  Actuellement, `mbstring` supporte les filtres de détections ci-dessous. Si une séquence d'octets est invalide pour l'un des filtres suivants, la détection échouera.

  `UTF-8`, `UTF-7`, `ASCII`, `EUC-JP`,`SJIS`, `eucJP-win`, `SJIS-win`, `JIS`, `ISO-2022-JP`

  Pour `ISO-8859-*`, `mbstring` détecte toujours `ISO-8859-*`.

  Pour `UTF-16`, `UTF-32`, `UCS2` et `UCS4` la détection échouera toujours.

### Valeurs de retour

Lors de la définition de l'ordre de détection de codage, `true` est retourné en cas de succès ou `false` en cas d'échec.

Lors de l'obtention de l'ordre de détection de l'encodage, un tableau ordonné des encodages est retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Exemple avec mb_detect_order()

    <?php
    /* Remplace l'ordre de détection par une liste énumérée */
    mb_detect_order("eucjp-win,sjis-win,UTF-8");

    /* Remplace l'ordre de détection par un tableau */
    $ary[] = "ASCII";
    $ary[] = "JIS";
    $ary[] = "EUC-JP";
    mb_detect_order($ary);

    /* Affiche l'ordre de détection courant */
    echo implode(", ", mb_detect_order());
    ?>

Exemple #2 Exemple d'ordre de détection inutile

    ; Toujours détecté comme ISO-8859-1
    detect_order = ISO-8859-1, UTF-8

    ; Toujours détecté comme UTF-8, car les valeurs ASCII/UTF-7
    ; sont valides pour UTF-8
    detect_order = UTF-8, ASCII, UTF-7

### Voir aussi

- mb_internal_encoding() - Lit/modifie l'encodage interne
- mb_http_input() - Détecte le type d'encodage d'un caractère HTTP
- mb_http_output() - Lit/modifie l'encodage d'affichage
- mb_send_mail() - Envoie un mail encodé

# mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_mimeheader — Encode une chaîne pour un en-tête MIME

### Description

function mb_encode_mimeheader(
string `$string`,
?string `$charset` = `null`,
?string `$transfer_encoding` = `null`,
string `$newline` = "\r\n",
int `$indent` = 0
): string

Encode une chaîne de caractères `string` donnée en un en-tête MIME.

### Liste de paramètres

`string`

  La chaîne de caractères à encoder. Son encodage devrait être identique à mb_internal_encoding().

`charset`

  `charset` est le nom de l'encodage utilisé par la chaîne `string`. La valeur par défaut est déterminée par les paramètres courants du NLS (`mbstring.language`).

`transfer_encoding`

  `transfer_encoding` est l'encodage de transfert. Il peut être `"B"` (Base64) ou `"Q"` (Quoted-Printable). Par défaut, c'est `"B"`.

`newline`

  `newline` spécifie les fins de lignes (EOF : `end-of-line`) utilisées par mb_encode_mimeheader() pour formater la chaîne (une » RFC définie la longueur d'une chaîne à partir de laquelle on doit ajouter une fin de ligne. La longueur courante est 74 caractères). La valeur par défaut est `"\r\n"` (CRLF).

`indent`

  Indentation de la première ligne (nombre de caractères dans l'en-tête avant `string`).

### Valeurs de retour

Une version convertie de la chaîne de caractères en ASCII.

### Historique

Version | Description
--- | ---
8.3.0 | Les octets `NUL` (0) ne sont plus supprimés lors de l'encodage en Quoted-Printable, mais encodés en `=00`.
8.0.0 | `charset` et `transfer_encoding` sont désormais nullable.

### Exemples

Exemple #1 Exemple avec mb_encode_mimeheader()

    <?php
    $name = "太郎"; // kanji
    $mbox = "kru";
    $doma = "gtinn.mon";
    $addr = '"' . addcslashes(mb_encode_mimeheader($name, "UTF-7", "Q"), '"') . '" <' . $mbox . "@" . $doma . ">";
    echo $addr;
    ?>

L'exemple ci-dessus va afficher :

    "=?UTF-7?Q?+WSqQzg-?=" <kru@gtinn.mon>

### Notes

> Note:

> Cette fonction n'est pas conçue pour couper les lignes en milieu de mots. Ce comportement peut ajouter des espaces non désirées dans un mot de la chaîne originale.

### Voir aussi

- mb_decode_mimeheader() - Décode un en-tête MIME

# mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_numericentity — Encode les caractères en référence numérique HTML

### Description

function mb_encode_numericentity(
string `$string`,
array `$map`,
?string `$encoding` = `null`,
bool `$hex` = `false`
): string

Convertit les codes des caractères spécifiés de la chaîne de caractères `string` en référence numérique HTML.

### Liste de paramètres

`string`

  La chaîne de caractères à encoder.

`map`

  `map` est un tableau qui spécifie les codes à convertir.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.
`hex`

  Si l'entité de référence retournée devrait être en notation hexadécimale (sinon il est en notation décimale).

### Valeurs de retour

La chaîne de caractères convertie.

### Erreurs / Exceptions

Lève une exception ValueError si `map` n'est pas une liste d'entiers.

### Historique

Version | Description
--- | ---
8.4.0 | mb_encode_numericentity() lève désormais une exception ValueError si `map` n'est pas une liste d'entiers.
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Exemple avec `map`

    <?php
    $convmap = array (
     int start_code1, int end_code1, int offset1, int mask1,
     int start_code2, int end_code2, int offset2, int mask2,
     ........
     int start_codeN, int end_codeN, int offsetN, int maskN );
    // Spécifie les valeurs Unicode de début (start_codeN) et fin (end_codeN)
    // Ajoutez offsetN à la valeur, et faites un ET bit-à-bit avec maskN, puis
    // il convertit la valeur obtenue en entité numérique
    ?>

Exemple #2 Exemple avec mb_encode_numericentity()

    <?php
    $str = "aAæÆあア𩸽";

    /* Convertit tous les caractères UTF-8 jusqu’à 4 octets en références numériques HTML */
    $convmap = [0, 0x1FFFFF, 0, 0x10FFFF];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));

    /* Convertit uniquement les caractères UTF-8 de 2 et 4 octets en références numériques HTML */
    $convmap = [
        0x80, 0x7FF, 0, 0x10FFFF,
        0x10000, 0x1FFFFF, 0, 0x10FFFF,
    ];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));
    ?>

L'exemple ci-dessus va afficher :

    string(46) "&#97;&#65;&#230;&#198;&#12354;&#12450;&#40509;"
    string(28) "aA&#230;&#198;あア&#40509;"

### Voir aussi

- mb_decode_numericentity() - Décode les entités HTML en caractères

# mb_encoding_aliases

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mb_encoding_aliases — Récupère les alias d'un type d'encodage connu

### Description

function mb_encoding_aliases(string `$encoding`): array

Retourne un tableau d'aliases pour un type connu d'encodage.

### Liste de paramètres

`encoding`

  Le type d'encodage à vérifier, pour les aliases.

### Valeurs de retour

Retourne un tableau indexé numériquement d'alias d'encodage.

### Erreurs / Exceptions

Lève une ValueError si `encoding` est inconnu.

### Historique

Version | Description
--- | ---
8.0.0 | Si le paramètre `encoding` est inconnu, une ValueError est désormais levée ; précédemment, une `E_WARNING` était émise, et la fonction retournait `false`.

### Exemples

Exemple #1 Exemple avec mb_encoding_aliases()

    <?php
    $encoding        = 'ASCII';
    $known_encodings = mb_list_encodings();

    if (in_array($encoding, $known_encodings)) {

        $aliases = mb_encoding_aliases($encoding);
        print_r($aliases);

    } else {

        echo "Encodage ($encoding) inconnu.\n";

    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => ANSI_X3.4-1968
        [1] => iso-ir-6
        [2] => ANSI_X3.4-1986
        [3] => ISO_646.irv:1991
        [4] => US-ASCII
        [5] => ISO646-US
        [6] => us
        [7] => IBM367
        [8] => cp367
        [9] => csASCII
    )

### Voir aussi

- mb_list_encodings() - Retourne un tableau contenant tous les encodages supportés

# mb_ereg

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg — Recherche par expression rationnelle avec support des caractères multioctets

### Description

function mb_ereg(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Recherche par expression rationnelle avec support des caractères multioctets.

### Liste de paramètres

`pattern`

  Le masque de recherche.

`string`

  La chaîne sur laquelle porte la recherche.

`matches`

  Si des correspondances sont trouvées pour les sous-chaînes entre parenthèses de `pattern` et si la fonction est appelée avec le troisième argument `matches`, les correspondances seront stockées dans les éléments du tableau `matches`. Si aucune correspondance n'est trouvée, `matches` a pour valeur un tableau vide.

  $matches[1] contiendra la sous-chaîne qui commence à la première parenthèse gauche; $matches[2] contiendra la sous-chaîne commençant à la seconde, et ainsi de suite. $matches[0] contiendra une copie de la chaîne complète assortie.

### Valeurs de retour

Retourne si une correspondance de `pattern` a été trouvée dans `string`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction retourne désormais `true` en cas de succès. Auparavant, elle retournait la longueur d'octet de la chaîne trouvée, si une correspondance pour `pattern` était trouvée dans `string` et que `matches` était fourni. Si le paramètre optionnel `matches` n'était pas fourni ou que la longueur de la chaîne correspondante était `0`, cette fonction retournait `1`.
7.1.0 | mb_ereg() va maintenant affecter `matches` à un array vide, si rien ne correspond. Auparavant, les `matches` n'étaient pas modifiées dans ce cas.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_eregi() - Expression rationnelle insensible à la casse avec le support des caractères multioctets

# mb_ereg_match

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_match — Expression rationnelle POSIX pour les chaînes multioctets

### Description

function mb_ereg_match(string `$pattern`, string `$string`, ?string `$options` = `null`): bool

Exécute l'expression rationnelle POSIX pour les chaînes multioctets.

> Note: `pattern` est uniquement associé au début de `string`.

### Liste de paramètres

`pattern`

  L'expression rationnelle.

`string`

  La chaîne à évaluer.

`options`

  L'option de recherche. Pour plus d'explications, consulter mb_regex_set_options().

### Valeurs de retour

`string` retourne `true` si `string` vérifie l'expression rationnelle `pattern`, `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0 | `options` est désormais nullable.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg() - Recherche par expression rationnelle avec support des caractères multioctets

# mb_ereg_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_replace — Remplace des segments de chaîne à l'aide des expressions régulières

### Description

function mb_ereg_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Recherche dans la chaîne `string` des occurrences correspondant au motif `pattern`, puis, les remplace avec le texte de remplacement `replacement`.

### Liste de paramètres

`pattern`

  L'expression rationnelle.

  Les caractères multi octets peuvent être utilisés dans `pattern`.

`replacement`

  Le texte de remplacement.

`string`

  La chaîne à analyser.

`options`
  L'option de recherche. Pour plus d'explications, consulter mb_regex_set_options().

### Valeurs de retour

La chaîne résultante en cas de succès, ou `false` si une erreur survient. Si `string` n'est pas valide pour l'encodage courant, `null` est retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `options` est désormais nullable.
7.1.0 | Cette fonction vérifie si `string` est valide pour l'encodage courant.
7.1.0 | Le modificateur `e` est désormais obsolète.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

Avertissement

N'utilisez jamais l'option `e` lorsque vous travaillez avec des données entrantes. Aucune protection automatique n'est appliquée (sous la forme de la fonction preg_replace()). Si vous omettez cette étape, vous allez certainement crée des failles dans votre application.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_eregi_replace() - Expression rationnelle avec support des caractères multioctets, sans tenir compte de la casse

# mb_ereg_replace_callback

(PHP 5 >= 5.4.1, PHP 7, PHP 8)

mb_ereg_replace_callback — Rechercher et remplacer par expression régulière avec support multi octets utilisant une fonction de callback

### Description

function mb_ereg_replace_callback(
string `$pattern`,
callable `$callback`,
string `$string`,
?string `$options` = `null`
): string|false|null

Recherche les `string` qui correspondent au paramètre `pattern`, puis remplace les textes qui correspondent avec le retour de la fonction `callback`.

Le comportement de cette fonction est presque identique à mb_ereg_replace(), à part le fait que le paramètre `replacement`, doit spécifier une fonction de retour `callback`.

### Liste de paramètres

`pattern`

  L'expression régulière.

  Les caractères multi octets peuvent être utilisés dans le `pattern`.

`callback`

  Un callback qui sera appelé et lui sera passé un tableau d'éléments correspondants dans la chaîne de caractères `string`. Le callback doit retourner la chaîne remplacée.

  On aura souvent besoin de la fonction `callback` pour mb_ereg_replace_callback() juste une fois. Dans ce cas il est possible d'utiliser les fonctions anonymes pour déclarer une fonction de rappel lors de l'appel de la fonction mb_ereg_replace_callback(). En faisant cela de cette manière on a toutes les informations nécessaires à l'appel de la fonction en un seul endroit, ce qui permet d'éviter d'encombrer l'espace de noms des fonctions avec un callback de fonction qui n'est pas utilisé ailleurs.

`string`

  La string qui doit être vérifiée.

`options`

  L'option de recherche. Pour plus d'explications, consulter mb_regex_set_options().

### Valeurs de retour

Retourne un string en cas de succès, ou `false` en cas d'erreur. Si `string` n'est pas valide pour l'encodage courant, `null` est retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `options` est désormais nullable.
7.1.0 | Cette fonction vérifie si `string` est valide pour l'encodage courant.

### Exemples

Exemple #1 Exemple avec mb_ereg_replace_callback()

    <?php
    // this text was used in 2002
    // we want to get this up to date for 2003
    $text = "April fools day is 04/01/2002\n";
    $text.= "Last christmas was 12/24/2001\n";
    // the callback function
    function next_year($matches)
    {
      // as usual: $matches[0] is the complete match
      // $matches[1] the match for the first subpattern
      // enclosed in '(...)' and so on
      return $matches[1].($matches[2]+1);
    }
    echo mb_ereg_replace_callback(
                "(\d{2}/\d{2}/)(\d{4})",
                "next_year",
                $text);

    ?>

L'exemple ci-dessus va afficher :

    April fools day is 04/01/2003
    Last christmas was 12/24/2002

Exemple #2 mb_ereg_replace_callback() utilisant les fonctions anonymes

    <?php
    // this text was used in 2002
    // we want to get this up to date for 2003
    $text = "April fools day is 04/01/2002\n";
    $text.= "Last christmas was 12/24/2001\n";

    echo mb_ereg_replace_callback(
                "(\d{2}/\d{2}/)(\d{4})",
                function ($matches) {
                   return $matches[1].($matches[2]+1);
                },
                $text);
    ?>

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg_replace() - Remplace des segments de chaîne à l'aide des expressions régulières
- Fonctions anonymes

# mb_ereg_search

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search — Recherche par expression rationnelle multioctets

### Description

function mb_ereg_search(?string `$pattern` = `null`, ?string `$options` = `null`): bool

Recherche par expression rationnelle multioctets.

### Liste de paramètres

`pattern`

  Le masque de recherche.

`options`

  L'option de recherche. Pour plus d'explications, consulter mb_regex_set_options().

### Valeurs de retour

mb_ereg_search() retourne `true` si la chaîne multioctets correspond au masque d'expression rationnelle, ou bien `false` sinon. La chaîne à étudier a été configurée avec la fonction mb_ereg_search_init(). Si le masque `pattern` n'est pas spécifié, le précédent sera utilisé.

### Historique

Version | Description
--- | ---
8.0.0 | `pattern` et `options` sont désormais nullable.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg_search_init() - Configure les chaînes et les expressions régulières pour le support des caractères multioctets

# mb_ereg_search_getpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getpos — Retourne la position du début du prochain segment repéré par une expression rationnelle

### Description

function mb_ereg_search_getpos(): int

Retourne la position du début du prochain segment repéré par une expression rationnelle.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

mb_ereg_search_getpos() retourne la position du prochain segment de code qui correspond au masque utilisé dans mb_ereg_search(), mb_ereg_search_pos() et mb_ereg_search_regs(). La position est le nombre d'octets depuis le début de la chaîne.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg_search_setpos() - Choisit le point de départ de la recherche par expression rationnelle

# mb_ereg_search_getregs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getregs — Lit le dernier segment de chaîne multioctets qui correspond au masque

### Description

function mb_ereg_search_getregs(): array|false

Lit le dernier segment de chaîne multioctets qui correspond au masque.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

un tableau incluant toutes les sous-chaînes qui ont été trouvées par mb_ereg_search(), mb_ereg_search_pos() et mb_ereg_search_regs(). S'il y a une solution qui a été trouvée, le premier élément sera la sous-chaîne trouvée, le second représentera la première parenthèse capturante, le troisième représentera la deuxième parenthèse capturante, etc. Cette fonction retourne `false` en cas d'erreur.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg_search_init() - Configure les chaînes et les expressions régulières pour le support des caractères multioctets

# mb_ereg_search_init

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_init — Configure les chaînes et les expressions régulières pour le support des caractères multioctets

### Description

function mb_ereg_search_init(string `$string`, ?string `$pattern` = `null`, ?string `$options` = `null`): bool

mb_ereg_search_init() configure `string` et `pattern` pour supporter les expressions régulières multioctets. Ces valeurs sont utilisées par mb_ereg_search(), mb_ereg_search_pos() et mb_ereg_search_regs().

### Liste de paramètres

`string`

  La chaîne à chercher.

`pattern`

  Le masque de recherche.

`options`

  L'option de recherche. Pour plus d'explications, consulter mb_regex_set_options().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `pattern` et `options` sont désormais nullable.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg_search_regs() - Retourne le segment de chaîne trouvé par une expression rationnelle multioctets

# mb_ereg_search_pos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_pos — Retourne la position et la longueur du segment de chaîne qui vérifie le masque de l'expression rationnelle

### Description

function mb_ereg_search_pos(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Retourne la position et la longueur du segment de chaîne qui vérifie le masque de l'expression rationnelle.

La chaîne à utiliser est spécifiée par mb_ereg_search_init(). Si elle n'est pas spécifiée, la précédente sera utilisée.

### Liste de paramètres

`pattern`

  Le masque de recherche.

`options`

  L'option de recherche. Pour plus d'explications, consulter mb_regex_set_options().

### Valeurs de retour

Un tableau contenant deux éléments. Le premier élément est la position, en octets, où la correspondance commence relativement au début de la chaîne recherchée, et le second élément est la longueur, en octets, de la correspondance.

Si une erreur survient, `false` sera retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `pattern` et `options` sont désormais nullable.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg_search_init() - Configure les chaînes et les expressions régulières pour le support des caractères multioctets

# mb_ereg_search_regs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_regs — Retourne le segment de chaîne trouvé par une expression rationnelle multioctets

### Description

function mb_ereg_search_regs(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Retourne le segment de chaîne trouvé par une expression rationnelle multioctets.

### Liste de paramètres

`pattern`

  Le masque de recherche.

`options`

  L'option de recherche. Pour plus d'explications, consulter mb_regex_set_options().

### Valeurs de retour

mb_ereg_search_regs() exécute l'expression rationnelle `pattern`, et, si un segment de chaîne correspond, elle le retourne dans un tableau, dont le premier élément est le segment de chaîne trouvé, le deuxième le contenu de la première parenthèse capturante, le troisième le contenu de la seconde parenthèse capturante, etc. La fonction retourne `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.0.0 | `pattern` et `options` sont désormais nullable.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg_search_init() - Configure les chaînes et les expressions régulières pour le support des caractères multioctets

# mb_ereg_search_setpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_setpos — Choisit le point de départ de la recherche par expression rationnelle

### Description

function mb_ereg_search_setpos(int `$offset`): bool

mb_ereg_search_setpos() choisit le point de départ de la recherche que va effectuer la fonction mb_ereg_search().

### Liste de paramètres

`offset`

  La position à définir. Si elle est négative, elle compte à partir de la fin de la chaîne.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
7.1.0 | La prise en charge d'une `offset` négative a été ajoutée.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg_search_init() - Configure les chaînes et les expressions régulières pour le support des caractères multioctets

# mb_eregi

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi — Expression rationnelle insensible à la casse avec le support des caractères multioctets

### Description

function mb_eregi(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Exécute l'expression rationnelle insensible à la casse avec le support des caractères multioctets.

### Liste de paramètres

`pattern`

  L'expression rationnelle.

`string`

  La chaîne à chercher.

`matches`

  Si au moins une séquence est trouvée (éventuellement dans les parenthèses capturantes de `pattern`), et que la fonction est appelée avec un troisième argument `matches`, les résultats seront enregistrés dans `matches`.

  $matches[1] contiendra la première parenthèse capturante (celle qui commence le plus tôt), $matches[2] contiendra la deuxième parenthèse capturante (celle qui commence après la première), et ainsi de suite. $matches[0] contient une copie de la chaîne.

### Valeurs de retour

Retourne si une correspondance de `pattern` a été trouvée dans `string`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction retourne désormais `true` en cas de succès. Auparavant, elle retournait la longueur d'octet de la chaîne trouvée, si une correspondance pour `pattern` était trouvée dans `string` et que `matches` était fourni. Si le paramètre optionnel `matches` n'était pas fourni ou que la longueur de la chaîne correspondante était `0`, cette fonction retournait `1`.
7.1.0 | mb_eregi() définira désormais `matches` en un tableau vide, s'il n'y a aucune correspondance. Auparavant, `matches` n'était pas modifié dans ce cas.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg() - Recherche par expression rationnelle avec support des caractères multioctets

# mb_eregi_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi_replace — Expression rationnelle avec support des caractères multioctets, sans tenir compte de la casse

### Description

function mb_eregi_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Analyse la chaîne `string` avec le masque d'expression rationnelle `pattern`, puis remplace le texte trouvé par `replacement`.

### Liste de paramètres

`pattern`

  L'expression rationnelle. Les caractères multi octets peuvent être utilisés. La casse sera ignorée.

`replacement`

  Le texte de substitution.

`string`

  La chaîne recherchée.

`options`
  Les options de recherche. Voir mb_regex_set_options() pour des explications.

### Valeurs de retour

La chaîne résultante, ou `false` si une erreur survient. Si `string` n'est pas valide pour l'encodage courant, `null` est retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `options` est désormais nullable.
7.1.0 | Cette fonction vérifie si `string` est valide pour l'encodage courant.
7.1.0 | Le modificateur `e` est désormais obsolète.

### Notes

> Note: L'encodage interne ou l'encodage des caractères spécifié par la fonction mb_regex_encoding() sera utilisé comme encodage de caractères pour cette fonction.

Avertissement

N'utilisez jamais l'option `e` lorsque vous travaillez avec des données entrantes. Aucune protection automatique n'est appliquée (sous la forme de la fonction preg_replace()). Si vous omettez cette étape, vous allez certainement crée des failles dans votre application.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg_replace() - Remplace des segments de chaîne à l'aide des expressions régulières

# mb_get_info

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_get_info — Lit la configuration interne de l'extension mbstring

### Description

function mb_get_info(string `$type` = "all"): array|string|int|false|null

mb_get_info() lit la configuration interne de l'extension mbstring.

### Liste de paramètres

`type`

  Si `type` n'est pas demandé explicitement, ou s'il vaut `"all"`, `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` et `"strict_detection"` sera retourné.

  Si `type` est spécifié en tant que `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` ou `"strict_detection"` le paramètre spécifié sera retourné.

### Valeurs de retour

Un array d'informations si `type` n'est pas spécifié, sinon, un `type` spécifique, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Les `type`s `"func_overload"` et `"func_overload_list"` ne sont désormais plus supportés.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_http_output() - Lit/modifie l'encodage d'affichage

# mb_http_input

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_input — Détecte le type d'encodage d'un caractère HTTP

### Description

function mb_http_input(?string `$type` = `null`): array|string|false

Détecte le type d'encodage d'un caractère HTTP.

### Liste de paramètres

`type`

  Le paramètre `type` spécifie le type d'entrée HTTP. Il peut prendre l'une des valeurs suivantes : `"G"` pour GET, `"P"` pour POST, `"C"` pour COOKIE, `"S"` pour chaîne de caractères, `"L"` pour la liste, `"I"` pour la liste complète (retournera array). Si `type` est omis, il prend la valeur du dernier type utilisé.

### Valeurs de retour

Le nom de l'encodage des caractères en fonction de `type`, ou un tableau de nom de jeux d'encodage, si `type` est `"I"`. Si mb_http_input() ne traite pas l'entrée HTTP spécifiée, elle retournera `false`.

### Erreurs / Exceptions

Lève une exception ValueError si `type` est invalide.

### Historique

Version | Description
--- | ---
8.4.0 | mb_http_input() lève désormais une exception ValueError si `type` est invalide.
8.0.0 | `type` est désormais nullable.

### Voir aussi

- mb_internal_encoding() - Lit/modifie l'encodage interne
- mb_http_output() - Lit/modifie l'encodage d'affichage
- mb_detect_order() - Lit/modifie l'ordre de détection des encodages

# mb_http_output

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_output — Lit/modifie l'encodage d'affichage

### Description

function mb_http_output(?string `$encoding` = `null`): string|bool

Lit/modifie l'encodage d'affichage. L'affichage après l'appel de cette fonction sera converti depuis l'encodage interne vers l'encodage fourni par le paramètre `encoding`.

### Liste de paramètres

`encoding`

  Si `encoding` est fourni, mb_http_output() utilisera dorénavant l'encodage `encoding` pour les affichages HTTP : les caractères qui seront envoyés aux clients web seront convertis dans le jeu de caractères `encoding`.

  Si `encoding` est omis, mb_http_output() retourne l'encodage d'affichage courant.

### Valeurs de retour

Si le paramètre `encoding` est omis, mb_http_output() retourne l'encodage courant HTTP. Sinon, Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Lève une exception ValueError si `encoding` contient des octets nuls.

### Historique

Version | Description
--- | ---
8.4.0 | mb_http_output() lève désormais une exception ValueError si `encoding` contient des octets nuls.
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- mb_internal_encoding() - Lit/modifie l'encodage interne
- mb_http_input() - Détecte le type d'encodage d'un caractère HTTP
- mb_detect_order() - Lit/modifie l'ordre de détection des encodages

# mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_internal_encoding — Lit/modifie l'encodage interne

### Description

function mb_internal_encoding(?string `$encoding` = `null`): string|bool

Lit/modifie l'encodage interne.

### Liste de paramètres

`encoding`

  `encoding` sert lors des conversions des chaînes en provenance et en direction du web, ainsi que lors de la création de chaînes avec le module mbstring. Il faut garder à l'esprit que l'encodage interne est totalement différent de celui pour les regex multioctets.

### Valeurs de retour

Si `encoding` est fourni, Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient. Dans ce cas, l'encodage des caractères pour les regex multioctets n'est pas changé. Si `encoding` est omis, mb_internal_encoding() retourne le nom de l'encodage courant.

### Erreurs / Exceptions

À partir de PHP 8.0.0, une ValueError est lancée si la valeur de `encoding` est un encodage invalide. Antérieurement à PHP 8.0.0, une `E_WARNING` était émise à la place.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.
8.0.0 | Lance désormais une ValueError si `encoding` est un encodage invalide. Auparavant, une `E_WARNING` était émise à la place.

### Exemples

Exemple #1 Exemple avec mb_internal_encoding()

    <?php
    /* Utilise l'encodage interne UTF-8 */
    mb_internal_encoding("UTF-8");

    /* Affiche l'encodage interne courant */
    echo mb_internal_encoding();
    ?>

### Voir aussi

- mb_http_input() - Détecte le type d'encodage d'un caractère HTTP
- mb_http_output() - Lit/modifie l'encodage d'affichage
- mb_detect_order() - Lit/modifie l'ordre de détection des encodages
- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets

# mb_language

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_language — Définit/Récupère le langage courant

### Description

function mb_language(?string `$language` = `null`): string|bool

Définit/Récupère le langage courant.

### Liste de paramètres

`language`

  Utilisé pour encoder les courriels électroniques. Les langages valides sont énumérés dans le tableau suivant. mb_send_mail() utilise cette option pour encoder les e-mails.

  Language | Charset | Encoding | Alias
  --- | --- | --- | ---
  German/de | ISO-8859-15 | Quoted-Printable | Deutsch
  English/en | ISO-8859-1 | Quoted-Printable |
  Armenian/hy | ArmSCII-8 | Quoted-Printable |
  Japanese/ja | ISO-2022-JP | BASE64 |
  Korean/ko | ISO-2022-KR | BASE64 |
  neutral | UTF-8 | BASE64 |
  Russian/ru | KOI8-R | Quoted-Printable |
  Turkish/tr | ISO-8859-9 | Quoted-Printable |
  Ukrainian/ua | KOI8-U | Quoted-Printable |
  uni | UTF-8 | BASE64 | universal
  Simplified Chinese/zh-cn | HZ | BASE64 |
  Traditional Chinese/zh-tw | BIG-5 | BASE64 |

### Valeurs de retour

Si `language` est fourni et `language` est valide, retourne `true`. Sinon, retourne `false`. Lorsque `language` est omis ou `null`, retourne le nom du langage courant, en tant que chaîne de caractères.

### Historique

Version | Description
--- | ---
8.0.0 | `language` est désormais nullable.

### Voir aussi

- mb_send_mail() - Envoie un mail encodé

# mb_lcfirst

(PHP 8 >= 8.4.0)

mb_lcfirst — Rend la première lettre d'une chaîne en minuscule

### Description

function mb_lcfirst(string `$string`, ?string `$encoding` = `null`): string

Effectue une opération lcfirst() multi-octets sûre, et renvoie une chaîne avec la première lettre de `string` en minuscule.

### Liste de paramètres

`string`
  La chaîne d'entrée.
`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Renvoie la chaîne de résultat.

### Voir aussi

- mb_ucfirst() - Rend une chaîne avec la première lettre en majuscule
- lcfirst() - Met le premier caractère en minuscule

# mb_list_encodings

(PHP 5, PHP 7, PHP 8)

mb_list_encodings — Retourne un tableau contenant tous les encodages supportés

### Description

function mb_list_encodings(): array

Retourne un tableau contenant tous les encodages supportés.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau indexé numériquement.

### Erreurs / Exceptions

Cette fonction n'émet aucune erreur.

### Exemples

Exemple #1 Exemple avec mb_list_encodings()

    <?php

    print_r(mb_list_encodings());

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => pass
        [1] => auto
        [2] => wchar
        [3] => byte2be
        [4] => byte2le
        [5] => byte4be
        [6] => byte4le
        [7] => BASE64
        [8] => UUENCODE
        [9] => HTML-ENTITIES
        [10] => Quoted-Printable
        [11] => 7bit
        [12] => 8bit
        [13] => UCS-4
        [14] => UCS-4BE
        [15] => UCS-4LE
        [16] => UCS-2
        [17] => UCS-2BE
        [18] => UCS-2LE
        [19] => UTF-32
        [20] => UTF-32BE
        [21] => UTF-32LE
        [22] => UTF-16
        [23] => UTF-16BE
        [24] => UTF-16LE
        [25] => UTF-8
        [26] => UTF-7
        [27] => UTF7-IMAP
        [28] => ASCII
        [29] => EUC-JP
        [30] => SJIS
        [31] => eucJP-win
        [32] => SJIS-win
        [33] => JIS
        [34] => ISO-2022-JP
        [35] => Windows-1252
        [36] => ISO-8859-1
        [37] => ISO-8859-2
        [38] => ISO-8859-3
        [39] => ISO-8859-4
        [40] => ISO-8859-5
        [41] => ISO-8859-6
        [42] => ISO-8859-7
        [43] => ISO-8859-8
        [44] => ISO-8859-9
        [45] => ISO-8859-10
        [46] => ISO-8859-13
        [47] => ISO-8859-14
        [48] => ISO-8859-15
        [49] => EUC-CN
        [50] => CP936
        [51] => HZ
        [52] => EUC-TW
        [53] => BIG-5
        [54] => EUC-KR
        [55] => UHC
        [56] => ISO-2022-KR
        [57] => Windows-1251
        [58] => CP866
        [59] => KOI8-R
    )

### Voir aussi

- mb_encoding_aliases() - Récupère les alias d'un type d'encodage connu

# mb_ltrim

(PHP 8 >= 8.4.0)

mb_ltrim — Supprime les espaces (ou d'autres caractères) du début d'une chaîne

### Description

function mb_ltrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Effectue une opération ltrim() multi-octets sûre. Supprime les espaces (ou d'autres caractères) du début d'une chaîne.

Sans le deuxième paramètre, mb_ltrim() supprimera les caractères suivants :

- `" "` (Unicode U+0020), un espace ordinaire.
- `"\t"` (Unicode U+0009), une tabulation.
- `"\n"` (Unicode U+000A), un saut de ligne.
- `"\r"` (Unicode U+000D), un retour chariot.
- `"\0"` (Unicode U+0000), l'octet NUL.
- `"\v"` (Unicode U+000B), une tabulation verticale.
- `"\f"` (Unicode U+000C), une avance de page.
- `"\u00A0"` (Unicode U+00A0), un ESPACE INSÉCABLE.
- `"\u1680"` (Unicode U+1680), une MARQUE D'ESPACE OGHAM.
- `"\u2000"` (Unicode U+2000), un CADRATIN MOYEN.
- `"\u2001"` (Unicode U+2001), un CADRATIN.
- `"\u2002"` (Unicode U+2002), un ESPACE MOYEN.
- `"\u2003"` (Unicode U+2003), un ESPACE CADRATIN.
- `"\u2004"` (Unicode U+2004), un ESPACE D'UN-TIERS-DE-CADRATIN.
- `"\u2005"` (Unicode U+2005), un ESPACE D'UN-QUART-DE-CADRATIN.
- `"\u2006"` (Unicode U+2006), un ESPACE D'UN-SIXIÈME-DE-CADRATIN.
- `"\u2007"` (Unicode U+2007), un ESPACE POUR CHIFFRES.
- `"\u2008"` (Unicode U+2008), un ESPACE DE PONCTUATION.
- `"\u2009"` (Unicode U+2009), un ESPACE FINE.
- `"\u200A"` (Unicode U+200A), un ESPACE CHEVEU.
- `"\u2028"` (Unicode U+2028), un SÉPARATEUR DE LIGNE.
- `"\u2029"` (Unicode U+2029), un SÉPARATEUR DE PARAGRAPHE.
- `"\u202F"` (Unicode U+202F), un ESPACE INSÉCABLE ÉTROIT.
- `"\u205F"` (Unicode U+205F), un ESPACE MATHÉMATIQUE MOYEN.
- `"\u3000"` (Unicode U+3000), un ESPACE IDÉOGRAPHIQUE.
- `"\u0085"` (Unicode U+0085), une LIGNE SUIVANTE (NEL).
- `"\u180E"` (Unicode U+180E), un SÉPARATEUR DE VOYELLE MONGOL.

### Liste de paramètres

`string`
  La chaîne d'entrée.
`characters`
  Optionnellement, les caractères à supprimer peuvent aussi être spécifiés en utilisant le paramètre `characters`. Il suffit de lister tous les caractères à supprimer.
`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Cette fonction renvoie une chaîne avec les espaces supprimés du début de `string`.

### Voir aussi

- mb_trim() - Supprime les espaces (ou d'autres caractères) du début et de la fin d'une chaîne
- mb_rtrim() - Supprime les espaces (ou d'autres caractères) de la fin d'une chaîne
- ltrim() - Supprime les espaces (ou d'autres caractères) de début de chaîne

# mb_ord

(PHP 7 >= 7.2.0, PHP 8)

mb_ord — Récupère le point de code Unicode d'un caractère

### Description

function mb_ord(string `$string`, ?string `$encoding` = `null`): int|false

Retourne le point de code Unicode pour le caractère fourni.

Cette fonction complémente mb_chr().

### Liste de paramètres

`string`

  Une chaîne de caractères

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Le point de code Unicode pour le premier caractère de `string` ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Un exemple basique de mb_ord()

    <?php
    var_dump(mb_ord("A", "UTF-8"));
    var_dump(mb_ord("🐘", "UTF-8"));
    var_dump(mb_ord("\x80", "ISO-8859-1"));
    var_dump(mb_ord("\x80", "Windows-1252"));
    ?>

L'exemple ci-dessus va afficher :

int(65)
int(128024)
int(128)
int(8364)

### Voir aussi

- mb_internal_encoding() - Lit/modifie l'encodage interne
- mb_chr() - Retourne un caractère par sa valeur de point de code Unicode
- IntlChar::ord() - Renvoie la valeur du point de code Unicode d'un caractère
- ord() - Convertit le premier octet d'une chaîne en une valeur entre 0 et 255

# mb_output_handler

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_output_handler — Fonction de traitement des affichages

### Description

function mb_output_handler(string `$string`, int `$status`): string

mb_output_handler() est la fonction à fournir à ob_start(). mb_output_handler() convertit les caractères envoyés au client dans l'encodage paramétré avec mb_http_output().

### Liste de paramètres

`string`

  Le contenu du buffer de sortie.

`status`

  Le statut du buffer de sortie.

### Valeurs de retour

La chaîne convertie.

### Exemples

Exemple #1 Exemple avec mb_output_handler()

    <?php
    mb_http_output("UTF-8");
    ob_start("mb_output_handler");
    ?>

### Notes

> Note:

> Pour envoyer des données binaires telles des images, l'en-tête `Content-Type: header` doit être défini en utilisant la fonction header() avant d'envoyer les données binaires au client (p. ex. `header("Content-Type: image/png"`)). Si `Content-Type: header` est envoyé, la conversion de l'encodage de sortie ne sera pas effectuée.

> À noter que si `Content-Type: text/*` est envoyé, le contenu du corps est vu comme du texte ; la conversion sera effectuée.

### Voir aussi

- ob_start() - Enclenche la temporisation de sortie

# mb_parse_str

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_parse_str — Analyse les données HTTP GET/POST/COOKIE et assigne les variables globales

### Description

function mb_parse_str(string `$string`, array `&$result`): bool

Analyse les données d'entrées HTTP GET/POST/COOKIE et assigne les variables globales. Étant donné que PHP ne fournit pas de valeurs brutes de POST/COOKIE, cette fonction n'est utilisable que sur les données en méthode GET. mb_parse_str() prend les données de l'URL appelante, détecte le jeu de caractères, convertit les données en jeu de caractères interne, et affecte les valeurs au tableau de variables globales.

### Liste de paramètres

`string`

  Les données encodées URL.

`result`

  Un tableau contenant les valeurs décodées, et les noms des jeux de caractères.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Le second paramètre n'est plus optionnel.
7.2.0 | Un appel à la fonction mb_parse_str() sans le second paramètre est devenu obsolète.

### Voir aussi

- mb_detect_order() - Lit/modifie l'ordre de détection des encodages
- mb_internal_encoding() - Lit/modifie l'encodage interne

# mb_preferred_mime_name

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_preferred_mime_name — Détecte l'encodage MIME

### Description

function mb_preferred_mime_name(string `$encoding`): string|false

Récupère le nom de l'encodage MIME d'une chaîne.

### Liste de paramètres

`encoding`

  L'encodage à vérifier.

### Valeurs de retour

Le nom de l'encodage MIME pour l'encodage `encoding`, ou `false` si aucun jeu de caractère n'est préféré pour l'`encoding` donnée.

### Exemples

Exemple #1 Exemple avec mb_preferred_mime_name()

    <?php
    $outputenc = "sjis-win";
    mb_http_output($outputenc);
    ob_start("mb_output_handler");
    header("Content-Type: text/html; charset=" . mb_preferred_mime_name($outputenc));
    ?>

# mb_regex_encoding

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_regex_encoding — Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets

### Description

function mb_regex_encoding(?string `$encoding` = `null`): string|bool

Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets.

### Liste de paramètres

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Si `encoding` est défini, alors Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.. Dans ce cas, l'encodage de caractères interne n'est pas modifié. Si l'argument `encoding` est omis, alors le nom de l'encodage de caractères courant pour les expressions régulières multioctets sera retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- mb_internal_encoding() - Lit/modifie l'encodage interne
- mb_ereg() - Recherche par expression rationnelle avec support des caractères multioctets

# mb_regex_set_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_regex_set_options — Lit et modifie les options des fonctions d'expression rationnelle à support de caractères multioctets

### Description

function mb_regex_set_options(?string `$options` = `null`): string

Configure les options par défaut avec les nouvelles valeurs contenues dans `options`, pour les fonctions d'expression rationnelle à support de caractères multioctets.

### Liste de paramètres

`options`

  Les options à définir, sous la forme d'une chaîne dont chaque caractère est une option. Pour définir un mode, il faut placer le caractère représentant ce mode en dernier, le reste des caractères sera les options. On ne peut définir qu'un seul mode, alors que l'on peut définir plusieurs options.

  Options pour l'expression
  Option | Signification | Historique
  --- | --- | ---
  i | Active l'ambiguïté |
  x | Active les masques étendus |
  m | Le caractère `'.'` correspond également à de nouvelles lignes |
  s | `'^'` -> `'\A'`, `'$'` -> `'\Z'` |
  p | Identique aux options `m` et `s` |
  l | Trouve la plus longue correspondance |
  n | Ignore les correspondances vides |
  e | Utilise la fonction eval() sur le résultat | Obsolète à partir de PHP 7.1.0 et supprimée à partir de PHP 8.0.0

  > Note:

  > L'option `"e"` n'a pas d'effet lorsqu'elle est définie par la mb_regex_set_options(). Utiliser-la avec mb_ereg_replace() ou mb_eregi_replace().

  Modes de syntaxe de l'expression rationnelle (un seul peut être défini)
  Mode | Signification
  --- | ---
  j | Java (Sun java.util.regex)
  u | GNU regex
  g | grep
  c | Emacs
  r | Ruby
  z | Perl
  b | POSIX Basic regex
  d | POSIX Extended regex

### Valeurs de retour

Les options précédentes. Si le paramètre `options` est omis ou `null`, une chaîne de caractères décrivant les options courantes sera retournée.

### Historique

Version | Description
--- | ---
8.0.0 | Si le paramètre `options` est fourni et non `null`, les options précédentes sont retournées. Auparavant, les options courantes étaient retournées.
8.0.0 | `options` est désormais nullable.
8.0.0 | L'option `"e"` lance désormais une ValueError.
7.1.0 | L'option `"e"` émet désormais une `E_DEPRECATED`.

### Voir aussi

- mb_split() - Scinde une chaîne en tableau avec une expression rationnelle multioctets
- mb_ereg() - Recherche par expression rationnelle avec support des caractères multioctets
- mb_eregi() - Expression rationnelle insensible à la casse avec le support des caractères multioctets

# mb_rtrim

(PHP 8 >= 8.4.0)

mb_rtrim — Supprime les espaces (ou d'autres caractères) de la fin d'une chaîne

### Description

function mb_rtrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Effectue une opération rtrim() multi-octets sûre, et renvoie une chaîne avec les espaces (ou d'autres caractères) de la fin de `string` supprimés.

Sans le deuxième paramètre, mb_rtrim() supprimera les caractères suivants :

- `" "` (Unicode U+0020), un espace ordinaire.
- `"\t"` (Unicode U+0009), une tabulation.
- `"\n"` (Unicode U+000A), un saut de ligne.
- `"\r"` (Unicode U+000D), un retour chariot.
- `"\0"` (Unicode U+0000), l'octet NUL.
- `"\v"` (Unicode U+000B), une tabulation verticale.
- `"\f"` (Unicode U+000C), une avance de page.
- `"\u00A0"` (Unicode U+00A0), un ESPACE INSÉCABLE.
- `"\u1680"` (Unicode U+1680), une MARQUE D'ESPACE OGHAM.
- `"\u2000"` (Unicode U+2000), un CADRATIN MOYEN.
- `"\u2001"` (Unicode U+2001), un CADRATIN.
- `"\u2002"` (Unicode U+2002), un ESPACE MOYEN.
- `"\u2003"` (Unicode U+2003), un ESPACE CADRATIN.
- `"\u2004"` (Unicode U+2004), un ESPACE D'UN-TIERS-DE-CADRATIN.
- `"\u2005"` (Unicode U+2005), un ESPACE D'UN-QUART-DE-CADRATIN.
- `"\u2006"` (Unicode U+2006), un ESPACE D'UN-SIXIÈME-DE-CADRATIN.
- `"\u2007"` (Unicode U+2007), un ESPACE POUR CHIFFRES.
- `"\u2008"` (Unicode U+2008), un ESPACE DE PONCTUATION.
- `"\u2009"` (Unicode U+2009), un ESPACE FINE.
- `"\u200A"` (Unicode U+200A), un ESPACE CHEVEU.
- `"\u2028"` (Unicode U+2028), un SÉPARATEUR DE LIGNE.
- `"\u2029"` (Unicode U+2029), un SÉPARATEUR DE PARAGRAPHE.
- `"\u202F"` (Unicode U+202F), un ESPACE INSÉCABLE ÉTROIT.
- `"\u205F"` (Unicode U+205F), un ESPACE MATHÉMATIQUE MOYEN.
- `"\u3000"` (Unicode U+3000), un ESPACE IDÉOGRAPHIQUE.
- `"\u0085"` (Unicode U+0085), une LIGNE SUIVANTE (NEL).
- `"\u180E"` (Unicode U+180E), un SÉPARATEUR DE VOYELLE MONGOL.

### Liste de paramètres

`string`
  La chaîne d'entrée.
`characters`
  Optionnellement, les caractères à supprimer peuvent aussi être spécifiés en utilisant le paramètre `characters`. Il suffit de lister tous les caractères à supprimer.
`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Renvoie la chaîne modifiée.

### Voir aussi

- mb_trim() - Supprime les espaces (ou d'autres caractères) du début et de la fin d'une chaîne
- mb_ltrim() - Supprime les espaces (ou d'autres caractères) du début d'une chaîne
- rtrim() - Supprime les espaces (ou d'autres caractères) de fin de chaîne

# mb_scrub

(PHP 7 >= 7.2.0, PHP 8)

mb_scrub — Remplace les séquences d'octets mal formées par le caractère de substitution.

### Description

function mb_scrub(string `$string`, ?string `$encoding` = `null`): string

Effectue une conversion de jeu de caractères depuis l'encodage spécifié, ou depuis l'encodage par défaut si aucun encodage n'a été spécifié, vers le même encodage. Cela a pour effet de remplacer toute séquence d'octets invalide par le caractère de substitution.

### Liste de paramètres

`string`

  La chaîne d'entrée.

`encoding`

  L'encodage utilisé pour interpréter `string`. S'il est omis ou `null`, le paramètre mbstring.internal_encoding sera utilisé s'il est défini, sinon le paramètre default_charset sera utilisé.

### Valeurs de retour

Le résultat chaîne de caractères avec les séquences d'octets invalides remplacées.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

# mb_send_mail

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_send_mail — Envoie un mail encodé

### Description

function mb_send_mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
?string `$additional_params` = `null`
): bool

Envoie un courrier électronique. Les en-têtes et le corps du message sont convertis et encodés en accord avec mb_language(). mb_send_mail() est une version adaptée de mail(). Voir la fonction mail() pour plus de détails.

### Liste de paramètres

`to`

  `to` est l'adresse de destination du mail. Les adresses multiples peuvent être spécifiées en les séparant par des virgules. Ce paramètre n'est pas encodé automatiquement.

`subject`

  Le sujet du mail.

`message`

  Le message du mail.

`additional_headers` (optionnel)

  chaîne de caractères ou tableau à insérer à la fin de l'en-tête mail.

  Ce paramètre est typiquement utilisé pour ajouter des en-têtes supplémentaires (From, Cc, and Bcc). Les différents ajouts doivent être séparés par un CRLF (\r\n). Ce paramètre doit être validé afin d'éviter l'injection d'en-tête non désiré par des personnes malveillantes.

  Si un tableau est fourni, ses clés sont les noms des en-têtes et ses valeurs sont les valeurs respectives des en-têtes.

  > Note:

  > Lors de l'envoi d'un mail, il doit contenir un en-tête `From`. Il peut être défini via le paramètre `additional_headers` ou en tant que valeur par défaut dans le php.ini.

  > Si on ne le fait pas, une erreur similaire à : `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing` sera émise. L'en-tête `From` définit également `Return-Path` sous Windows.

  > Note:

  > Si les messages ne sont pas reçus, tentez d'utiliser uniquement un LF (\n). Quelques agents de transfert de mails Unix (en particulier » qmail) remplacent un LF par un CRLF automatiquement (ce qui résulte en un doublement du CR si CRLF est utilisé). Il faut tenter cette correction en dernier recours, sachant que cela ne respecte pas la » RFC 2822.

`additional_params`

  `additional_params` est une ligne de paramètres MTA. Il est pratique lorsqu'on veut définir un `Return-Path` correct lorsqu'on utilise `sendmail`.

  Ce paramètre est échappé par la fonction escapeshellcmd() en interne afin de prévenir les exécutions de commande. La fonction escapeshellcmd() prévient d'exécution de commande, mais autorise les paramètres additionnels. Pour des raisons de sécurité, ce paramètre doit être validé.

  Étant donné que la fonction escapeshellcmd() est appliquée automatiquement en interne, quelques caractères autorisés dans les adresses mails par les RFCs d'internet ne peuvent plus être utilisés. Les programmes qui doivent utiliser ces caractères, la fonction mail() ne peut plus être utilisée.

  L'utilisateur faisant fonctionner le serveur Web doit être ajouté comme utilisateur de confiance dans la configuration de l'envoi de mails afin d'éviter l'ajout d'un en-tête 'X-Warning' dans le message lorsque l'enveloppe de l'envoyeur (-f) est définie comme utilisant cette méthode. Pour les utilisateurs de sendmail, ce fichier se trouve en utilisant le chemin /etc/mail/trusted-users.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `additional_params` est désormais nullable.
7.2.0 | Le paramètre `additional_headers` accepte désormais un tableau.

### Voir aussi

- mail() - Envoi de mail
- mb_encode_mimeheader() - Encode une chaîne pour un en-tête MIME
- mb_language() - Définit/Récupère le langage courant

# mb_split

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_split — Scinde une chaîne en tableau avec une expression rationnelle multioctets

### Description

function mb_split(string `$pattern`, string `$string`, int `$limit` = -1): array|false

Scinde la chaîne multioctets `string` en utilisant l'expression rationnelle `pattern` puis en retournant le résultat sous forme de tableau.

### Liste de paramètres

`pattern`

  Le masque de l'expression rationnelle.

`string`

  La chaîne à scinder.

`limit`
  Si le paramètre optionnel `limit` est spécifié, la chaîne sera scindée en `limit` éléments au plus.

### Valeurs de retour

Le résultat, sous la forme d'un tableau, ou `false` si une erreur survient.

### Notes

> Note: L'encodage de caractères spécifié par mb_regex_encoding() sera utilisé comme encodage pour cette fonction par défaut.

### Voir aussi

- mb_regex_encoding() - Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_ereg() - Recherche par expression rationnelle avec support des caractères multioctets
- explode() - Scinde une chaîne de caractères en segments

# mb_str_pad

(PHP 8 >= PHP 8.3.0)

mb_str_pad — Remplit une chaîne multioctets à une certaine longueur avec une autre chaîne multioctets

### Description

function mb_str_pad(
string `$string`,
int `$length`,
string `$pad_string` = " ",
int `$pad_type` = `STR_PAD_RIGHT`,
?string `$encoding` = `null`
): string

Cette fonction renvoie le `string` rempli sur la gauche, la droite, ou les deux côtés à la longueur de remplissage spécifiée, où la longueur est mesurée en points de code Unicode. Si l'argument optionnel `pad_string` n'est pas fourni, le `string` est rempli avec des espaces, sinon il est rempli avec des caractères de `pad_string` jusqu'à la limite.

### Liste de paramètres

`string`

  La chaîne d'entrée.

`length`

  Si la valeur de `length` est négative, inférieure ou égale à la longueur de la chaîne d'entrée, aucun remplissage n'a lieu, et `string` sera renvoyé.

`pad_string`

  > Note:

  > Le `pad_string` peut être tronqué si le nombre requis de caractères de remplissage ne peut pas être divisé de manière égale par la longueur du `pad_string`.

`pad_type`

  L'argument optionnel `pad_type` peut être `STR_PAD_RIGHT`, `STR_PAD_LEFT`, ou `STR_PAD_BOTH`. Par défaut `STR_PAD_RIGHT`.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Renvoie la chaîne remplie.

### Exemples

Exemple #1 Exemple avec mb_str_pad()

    <?php
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_RIGHT)); // string(18) "▶▶❤❓❇❤"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_LEFT));  // string(18) "❤❓❇❤▶▶"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_BOTH));  // string(18) "❤❓▶▶❤❓"

    var_dump(mb_str_pad("🎉", 3, "祝", STR_PAD_LEFT));   // string(10) "祝祝🎉"
    ?>

# mb_str_split

(PHP 7 >= 7.4.0, PHP 8)

mb_str_split — Pour une chaîne multi-octets donnée, renvoie un tableau de ses caractères

### Description

function mb_str_split(string `$string`, int `$length` = 1, ?string `$encoding` = `null`): array

Cette fonction renverra un tableau de chaînes, c'est une version de str_split() avec une prise en charge des encodages de taille de caractère variable ainsi que des encodages de taille fixe de caractères de 1, 2 ou 4 octets. Si le paramètre `length` est spécifié, la chaîne est décomposée en blocs de la longueur spécifiée en caractères (et non en octets). Le paramètre `encoding` est facultatif mais il est recommandé de le fournir.

### Liste de paramètres

`string`

  La chaîne de caractères à diviser en caractères ou en morceaux.

`length`

  Si spécifié, chaque élément du tableau retourné sera composé de plusieurs caractères au lieu d'un seul caractère.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

  Une chaîne de caractères spécifiant l'un des encodages pris en charge.

### Valeurs de retour

mb_str_split() renvoie un tableau de chaînes de caractères.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.
8.0.0 | Cette fonction ne renvoie plus `false` en cas d'échec.

### Voir aussi

- str_split() - Convertit une chaîne de caractères en tableau
- grapheme_str_split() - Sépare une chaîne en un tableau
- explode() - Scinde une chaîne de caractères en segments

# mb_strcut

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strcut — Coupe une partie de chaîne

### Description

function mb_strcut(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

mb_strcut() extrait une sous-chaîne depuis une chaîne, d'une façon similaire à la fonction mb_substr(), mais opère sur les octets au lieu des caractères. Si le découpage intervient entre 2 octets d'un caractère multioctets, le découpage sera effectué au début du premier octet de ce caractère. C'est également la différence avec la fonction substr() qui coupera la chaîne au milieu des octets, résultant ainsi en une séquence d'octets mal-formée.

### Liste de paramètres

`string`

  La chaîne à couper.

`start`

  Si `start` est positif, la chaîne retournée commencera à l'octet numéro `start`, dans la chaîne `string`. Le premier caractère est numéroté zéro. En effet, dans la chaîne '`abcdef`', l'octet à la position `0` est '`a`', l'octet à la position `2` est '`c`', et ainsi de suite.

  Si `start` est négatif, la chaîne retournée commencera à l'octet numéro `start` à compter de la fin de la chaîne `string`. Cependant, si le nombre négatif passé en paramètre `start` est supérieur à la longueur de la chaîne, la portion retournée commencera depuis le début de la chaîne `string`.

`length`

  Longueur en octets. Si ce paramètre est omis, ou vaut `NULL`, tous les octets jusqu'à la fin de la chaîne seront extraits.

  Si `length` est négatif, la chaîne retournée se finira à la position `length` en comptant en arrière depuis la fin de la chaîne `string`. Cependant, si le nombre négatif passé au paramètre `length` est plus grand que le nombre de caractères après la position `start`, une chaîne vide sera retournée.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

mb_strcut() retourne la portion de la chaîne `string` qui commence au caractère `start` et a la longueur de `length` caractères.

### Historique

Version | Description
--- | ---
8.4.0 | Le comportement est désormais plus cohérent sur les chaînes `UTF-8` et `UTF-16` invalides.
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- mb_substr() - Lit une sous-chaîne
- mb_internal_encoding() - Lit/modifie l'encodage interne

# mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strimwidth — Tronque une chaîne

### Description

function mb_strimwidth(
string `$string`,
int `$start`,
int `$width`,
string `$trim_marker` = "",
?string `$encoding` = `null`
): string

Tronque la chaîne `string` à la longueur `width` spécifiée, où les caractères à demi-chasse comptent en tant que `1`, et les caractères à pleine chasse comptent en tant que `2`. Voir » http://www.unicode.org/reports/tr11/ pour plus de détails concernant les chasses des caractères asiatiques de l'Est.

### Liste de paramètres

`string`

  La chaîne à tronquer.

`start`

  `start` est la position de départ, en nombre de caractères depuis le début de la chaîne (premier caractère est 0), ou si la position est négative, nombre de caractères à partir de la fin de la chaîne de caractères.

`width`

  La largeur de la troncation souhaitée. Si une largeur négative est spécifiée, il faut compter à partir de la fin de la chaîne.

  > Note:

  > Fournir une largeur négative est obsolète à partir de PHP 8.3.0.

`trim_marker`

  `trim_marker` est la chaîne ajoutée à la fin de la chaîne tronquée.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

La chaîne tronquée. Si `trim_marker` est défini, `trim_marker` remplace les derniers caractères pour correspondre à la taille `width`.

### Historique

Version | Description
--- | ---
8.3.0 | Fournir une `width` négative à mb_strimwidth() est désormais obsolète.
8.0.0 | `encoding` est désormais nullable.
7.1.0 | Support pour `start`s et `width`s négatifs a été ajouté.

### Exemples

Exemple #1 Exemple avec mb_strimwidth()

    <?php
    echo mb_strimwidth("Hello World", 0, 10, "...");
    // Affiche : "Hello W..."
    ?>

### Voir aussi

- mb_strwidth() - Retourne la taille d'une chaîne
- mb_internal_encoding() - Lit/modifie l'encodage interne

# mb_stripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stripos — Trouve la première occurrence d'une chaîne dans une autre, sans tenir compte de la casse

### Description

function mb_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_stripos() retourne la position numérique de la première occurrence de `needle` dans la chaîne `haystack`. Contrairement à mb_strpos(), mb_stripos() est insensible à la casse. Si `needle` n'est pas trouvé, la fonction retournera `false`.

### Liste de paramètres

`haystack`

  La chaîne depuis laquelle on récupère la position de la première occurrence de `needle`

`needle`

  La chaîne à chercher dans `haystack`

`offset`

  La position dans `haystack` où l'on doit commencer à chercher. Une position négative compte à partir de la fin de la chaîne de caractères.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la position numérique de la première occurrence de `needle` dans la chaîne `haystack` ou `false` si `needle` n'est pas trouvé.

### Erreurs / Exceptions

- Si `offset` est supérieur à la longueur de `haystack`, une ValueError sera levée.

### Historique

Version | Description
--- | ---
8.0.0 | `needle` accepte désormais une chaîne vide.
8.0.0 | `encoding` est désormais nullable.
7.1.0 | Support pour `offset`s négatifs a été ajouté.

### Voir aussi

- stripos() - Recherche la position de la première occurrence dans une chaîne, sans tenir compte de la casse
- strpos() - Cherche la position de la première occurrence dans une chaîne
- mb_strpos() - Repère la première occurrence d'un caractère dans une chaîne

# mb_stristr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stristr — Trouve la première occurrence d'une chaîne dans une autre, sans tenir compte de la casse

### Description

function mb_stristr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_stristr() trouve la première occurrence de `needle` dans `haystack` et retourne la portion de `haystack`. Contrairement à mb_strstr(), mb_stristr() est insensible à la casse. Si `needle` n'est pas trouvé, la fonction retournera `false`.

### Liste de paramètres

`haystack`

  La chaîne depuis laquelle on récupère la première occurrence de `needle`

`needle`

  La chaîne à chercher dans `haystack`

`before_needle`

  Détermine quelle portion de `haystack` cette fonction retourne. Si défini à `true`, la fonction retournera toute la chaîne `haystack` depuis le début jusqu'à la première occurrence de `needle` (`needle` exclus). Si défini à `false`, la fonction retournera toute la chaîne `haystack` depuis la première occurrence de `needle` jusqu'à la fin (`needle` inclus).

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la portion de `haystack`, ou `false` si `needle` n'est pas trouvé.

### Historique

Version | Description
--- | ---
8.0.0 | `needle` accepte désormais une chaîne vide.
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- stristr() - Version insensible à la casse de strstr
- strstr() - Trouve la première occurrence dans une chaîne
- mb_strstr() - Trouve la première occurrence d'une chaîne dans une autre

# mb_strlen

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strlen — Retourne la taille d'une chaîne

### Description

function mb_strlen(string `$string`, ?string `$encoding` = `null`): int

Récupère la taille de la chaîne fournie.

### Liste de paramètres

`string`

  La chaîne à analyser.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne le nombre de caractères dans la chaîne `string`, avec l'encodage `encoding`. Un caractère multioctets est alors compté pour 1.

### Erreurs / Exceptions

Si l'encodage est inconnu, une erreur de niveau `E_WARNING` est générée.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- mb_internal_encoding() - Lit/modifie l'encodage interne
- grapheme_strlen() - Lit la taille d'une chaîne en nombre de graphème
- iconv_strlen() - Retourne le nombre de caractères d'une chaîne
- strlen() - Calcule la taille d'une chaîne

# mb_strpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strpos — Repère la première occurrence d'un caractère dans une chaîne

### Description

function mb_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Repère la position de la première occurrence de `needle` dans la chaîne `haystack`.

Effectue une recherche de type strpos(), en tenant compte des caractères multioctets. La position de `needle` est comptée à partir du début de la chaîne `haystack` : les positions commencent à 0.

### Liste de paramètres

`haystack`

  La chaîne dans laquelle récupérer la position de la première occurrence de `needle`

`needle`

  La chaîne de caractères à trouver dans le paramètre `haystack`. A contrario de la fonction strpos(), les valeurs numériques ne sont pas appliquées comme valeur ordinale d'un caractère.

`offset`

  La position de début de recherche. S'il est omis, zéro sera utilisé. Une position négative compte à partir de la fin de la chaîne de caractères.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la position numérique de la première occurrence du caractère `needle` dans la chaîne `haystack`. Si `needle` est introuvable, mb_strpos() retourne `false`.

### Erreurs / Exceptions

- Si `offset` est supérieur à la longueur de `haystack`, une ValueError sera levée.

### Historique

Version | Description
--- | ---
8.0.0 | `needle` accepte désormais une chaîne vide.
8.0.0 | `encoding` est désormais nullable.
7.1.0 | Support pour `offset`s négatifs a été ajouté.

### Voir aussi

- mb_internal_encoding() - Lit/modifie l'encodage interne
- strpos() - Cherche la position de la première occurrence dans une chaîne

# mb_strrchr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrchr — Trouve la dernière occurrence d'un caractère d'une chaîne dans une autre

### Description

function mb_strrchr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrchr() trouve la dernière occurrence de `needle` dans `haystack` et retourne la portion de `haystack`. Si `needle` n'est pas trouvé, la fonction retournera `false`.

### Liste de paramètres

`haystack`

  La chaîne depuis laquelle on doit récupérer la dernière occurrence de `needle`

`needle`

  La chaîne à trouver dans `haystack`

`before_needle`

  Détermine quelle portion de `haystack` cette fonction retourne. Si défini à `true`, la fonction retourne toute la chaîne `haystack` depuis le début jusqu'à la dernière occurrence de `needle`. Si défini à `false`, la fonction retourne toute la chaîne `haystack` depuis la dernière occurrence de `needle` jusqu'à la fin.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la portion de `haystack`. ou `false` si `needle` n'est pas trouvé.

### Historique

Version | Description
--- | ---
8.0.0 | `needle` accepte désormais une chaîne vide.
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- strrchr() - Trouve la dernière occurrence d'un caractère dans une chaîne
- mb_strstr() - Trouve la première occurrence d'une chaîne dans une autre
- mb_strrichr() - Trouve la dernière occurrence d'un caractère d'une chaîne dans une autre, insensible à la casse

# mb_strrichr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrichr — Trouve la dernière occurrence d'un caractère d'une chaîne dans une autre, insensible à la casse

### Description

function mb_strrichr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrichr() trouve la dernière occurrence de `needle` dans `haystack` et retourne la portion de `haystack`. Contrairement à mb_strrchr(), mb_strrichr() n'est pas sensible à la casse. Si `needle` n'est pas trouvé, la fonction retournera `false`.

### Liste de paramètres

`haystack`

  La chaîne depuis laquelle on doit chercher la dernière occurrence de `needle`

`needle`

  La chaîne à chercher dans `haystack`

`before_needle`

  Détermine quelle portion de `haystack` cette fonction retourne. Si défini à `true`, la fonction retourne toute la chaîne `haystack` depuis le début jusqu'à la dernière occurrence de `needle`. Si défini à `false`, la fonction retourne toute la chaîne `haystack` depuis la dernière occurrence de `needle` jusqu'à la fin.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la portion de `haystack`. ou `false` si `needle` n'est pas trouvé.

### Historique

Version | Description
--- | ---
8.0.0 | `needle` accepte désormais une chaîne vide.
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- mb_stristr() - Trouve la première occurrence d'une chaîne dans une autre, sans tenir compte de la casse
- mb_strrchr() - Trouve la dernière occurrence d'un caractère d'une chaîne dans une autre

# mb_strripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strripos — Trouve la position de la dernière occurrence d'une chaîne dans une autre, en ne tenant pas compte de la casse

### Description

function mb_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_strripos() effectue une opération strripos() basée sur le nombre de caractères. La position `needle` est comptée depuis le début de `haystack`. La position du premier caractère est 0. Le second a comme position 1, etc. Contrairement à mb_strrpos(), mb_strripos() n'est pas sensible à la casse.

### Liste de paramètres

`haystack`

  La chaîne depuis laquelle on récupère la position de la dernière occurrence de `needle`.

`needle`

  La chaîne à chercher dans `haystack`.

`offset`

  Peut spécifier la position de départ de la recherche à partir d'un certain nombre de caractères arbitraire dans `haystack`. Les valeurs négatives arrêtent la recherche à partir d'une position arbitraire depuis la fin de `haystack`.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la position numérique de la dernière occurrence de `needle` dans la chaîne `haystack`, ou `false` si `needle` n'est pas trouvé.

### Erreurs / Exceptions

- Si `offset` est supérieur à la longueur de `haystack`, une ValueError sera levée.

### Historique

Version | Description
--- | ---
8.0.0 | `needle` accepte désormais une chaîne vide.
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- strripos() - Cherche la position de la dernière occurrence d'une chaîne contenue dans une autre, de façon insensible à la casse
- strrpos() - Cherche la position de la dernière occurrence d'une sous-chaîne dans une chaîne
- mb_strrpos() - Repère la dernière occurrence d'un caractère dans une chaîne

# mb_strrpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strrpos — Repère la dernière occurrence d'un caractère dans une chaîne

### Description

function mb_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_strrpos() effectue une recherche de type strpos(), en tenant compte des caractères multioctets. La position de `needle` est comptée à partir du début de la chaîne `haystack` : les positions commencent à 0.

### Liste de paramètres

`haystack`

  La chaîne à analyser.

`needle`

  La chaîne à chercher dans la chaîne `haystack`.

`offset`
  Peut spécifier la position de départ de la recherche à partir d'un certain nombre de caractères arbitraire dans `haystack`. Les valeurs négatives arrêtent la recherche à partir d'une position arbitraire depuis la fin de `haystack`.
`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la position numérique de la dernière occurrence du caractère `needle` dans la chaîne `haystack`. Si `needle` est introuvable, mb_strrpos() retourne `false`.

### Erreurs / Exceptions

- Si `offset` est supérieur à la longueur de `haystack`, une ValueError sera levée.

### Historique

Version | Description
--- | ---
8.0.0 | `needle` accepte désormais une chaîne vide.
8.0.0 | Passer `encoding` comme troisième argument au lieu de `offset` a été supprimée.
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- mb_strpos() - Repère la première occurrence d'un caractère dans une chaîne
- mb_internal_encoding() - Lit/modifie l'encodage interne
- strrpos() - Cherche la position de la dernière occurrence d'une sous-chaîne dans une chaîne

# mb_strstr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strstr — Trouve la première occurrence d'une chaîne dans une autre

### Description

function mb_strstr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strstr() trouve la première occurrence de `needle` dans `haystack` et retourne la portion de `haystack`. Si `needle` n'est pas trouvé, la fonction retournera `false`.

### Liste de paramètres

`haystack`

  La chaîne dans laquelle on doit chercher la première occurrence de `needle`

`needle`

  La chaîne à chercher dans `haystack`

`before_needle`

  Détermine quelle portion de `haystack` cette fonction retourne. Si défini à `true`, la fonction retournera toute la chaîne `haystack` depuis le début jusqu'à la première occurrence de `needle` (`needle` exclus). Si défini à `false`, la fonction retournera toute la chaîne `haystack` depuis la première occurrence de `needle` jusqu'à la fin (`needle` inclus).

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la portion de `haystack`, ou `false` si `needle` n'est pas trouvé.

### Historique

Version | Description
--- | ---
8.0.0 | `needle` accepte désormais une chaîne vide.
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- stristr() - Version insensible à la casse de strstr
- strstr() - Trouve la première occurrence dans une chaîne
- mb_stristr() - Trouve la première occurrence d'une chaîne dans une autre, sans tenir compte de la casse

# mb_strtolower

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtolower — Met tous les caractères en minuscules

### Description

function mb_strtolower(string `$string`, ?string `$encoding` = `null`): string

Retourne la chaîne `string` après avoir converti tous les caractères alphabétiques en minuscules.

### Liste de paramètres

`string`

  La chaîne à mettre en minuscule.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la chaîne `string` dont tous les caractères alphabétiques ont été mis en minuscule.

### Historique

Version | Description
--- | ---
8.3.0 | Mise en œuvre des règles de mise en minuscule conditionnelle pour la lettre grecque sigma.

### Exemples

Exemple #1 Exemple avec mb_strtolower()

    <?php
    $str = "Marie A Un Petit Agneau Et Elle L'Aime BEAUCOUP.";
    $str = mb_strtolower($str);
    echo $str; // marie a un petit agneau et elle l'aime beaucoup
    ?>

Exemple #2 Exemple avec mb_strtolower() avec du texte UTF-8 non latin

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtolower($str, 'UTF-8');
    echo $str; // Affiche τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός
    ?>

### Notes

Contrairement à strtolower(), le concept de caractère 'alphabétique' est déterminé par les propriétés Unicode. De ce fait, le comportement de cette fonction n'est pas modifié par les configurations locales, et elle peut convertir tous les caractères qui sont considérés comme alphabétiques comme le c cédille (ç).

Pour plus d'informations sur les propriétés de l'Unicode, voir » http://www.unicode.org/reports/tr21/.

### Voir aussi

- mb_strtoupper() - Met tous les caractères en majuscules
- mb_convert_case() - Modifie la casse d'une chaîne
- strtolower() - Renvoie une chaîne en minuscules

# mb_strtoupper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtoupper — Met tous les caractères en majuscules

### Description

function mb_strtoupper(string `$string`, ?string `$encoding` = `null`): string

Retourne la chaîne `string` après avoir converti tous les caractères alphabétiques en majuscules.

### Liste de paramètres

`string`

  La chaîne à mettre en majuscules.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne la chaîne `string` dont tous les caractères ont été mis en majuscule.

### Exemples

Exemple #1 Exemple avec mb_strtoupper()

    <?php
    $str = "Marie A Un Petit Agneau Et Elle L'Aime BEAUCOUP.";
    $str = mb_strtoupper($str);
    echo $str; // MARIE A UN PETIT AGNEAU ET ELLE L'AIME BEAUCOUP.
    ?>

Exemple #2 Exemple avec mb_strtoupper() et du texte UTF-8 non latin

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtoupper($str, 'UTF-8');
    echo $str; // Affiche ΤΆΧΙΣΤΗ ΑΛΏΠΗΞ ΒΑΦΉΣ ΨΗΜΈΝΗ ΓΗ, ΔΡΑΣΚΕΛΊΖΕΙ ΥΠΈΡ ΝΩΘΡΟΎ ΚΥΝΌΣ
    ?>

### Notes

Contrairement à strtoupper(), le concept de caractère 'alphabétique' est déterminé par les propriétés Unicode. De ce fait, le comportement de cette fonction n'est pas modifié par les configurations locales, et elle peut convertir tous les caractères qui sont considérés comme alphabétiques comme le c cédille (ç).

Pour plus d'informations sur les propriétés de l'Unicode, voir » http://www.unicode.org/reports/tr21/.

### Voir aussi

- mb_strtolower() - Met tous les caractères en minuscules
- mb_convert_case() - Modifie la casse d'une chaîne
- strtoupper() - Renvoie une chaîne en majuscules

# mb_strwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strwidth — Retourne la taille d'une chaîne

### Description

function mb_strwidth(string `$string`, ?string `$encoding` = `null`): int

Retourne la chasse de string `string`, où les caractères à demi-chasse comptent en tant que `1`, et les caractères à pleine chasse comptent en tant que `2`. Voir » http://www.unicode.org/reports/tr11/ pour plus de détails concernant les chasses des caractères asiatiques de l'Est.

Les caractères à pleine chasse sont : `U+1100`-`U+115F`, `U+11A3`-`U+11A7`, `U+11FA`-`U+11FF`, `U+2329`-`U+232A`, `U+2E80`-`U+2E99`, `U+2E9B`-`U+2EF3`, `U+2F00`-`U+2FD5`, `U+2FF0`-`U+2FFB`, `U+3000`-`U+303E`, `U+3041`-`U+3096`, `U+3099`-`U+30FF`, `U+3105`-`U+312D`, `U+3131`-`U+318E`, `U+3190`-`U+31BA`, `U+31C0`-`U+31E3`, `U+31F0`-`U+321E`, `U+3220`-`U+3247`, `U+3250`-`U+32FE`, `U+3300`-`U+4DBF`, `U+4E00`-`U+A48C`, `U+A490`-`U+A4C6`, `U+A960`-`U+A97C`, `U+AC00`-`U+D7A3`, `U+D7B0`-`U+D7C6`, `U+D7CB`-`U+D7FB`, `U+F900`-`U+FAFF`, `U+FE10`-`U+FE19`, `U+FE30`-`U+FE52`, `U+FE54`-`U+FE66`, `U+FE68`-`U+FE6B`, `U+FF01`-`U+FF60`, `U+FFE0`-`U+FFE6`, `U+1B000`-`U+1B001`, `U+1F200`-`U+1F202`, `U+1F210`-`U+1F23A`, `U+1F240`-`U+1F248`, `U+1F250`-`U+1F251`, `U+20000`-`U+2FFFD`, `U+30000`-`U+3FFFD`. Tous les autres caractères sont des caractères à demi chasse.

### Liste de paramètres

`string`

  La chaîne à analyser.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

La taille de la string `string`.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Exemple mb_strwidth()

    <?php
    var_dump(
        mb_strwidth('a'),       // LATIN SMALL LETTER A
        mb_strwidth("\u{ff41}") // FULLWIDTH LATIN SMALL LETTER A
    );
    ?>

L'exemple ci-dessus va afficher :

    int(1)
    int(2)

### Voir aussi

- mb_strimwidth() - Tronque une chaîne
- mb_internal_encoding() - Lit/modifie l'encodage interne

# mb_substitute_character

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substitute_character — Définit/Récupère les caractères de substitution

### Description

function mb_substitute_character(string|int|null `$substitute_character` = `null`): string|int|bool

Spécifie le caractère de substitution des caractères invalides, ou des encodages invalides. Les caractères invalides peuvent être remplacés par `"none"` (pas d'affichage, ils sont supprimés), une chaîne de caractères ou une valeur entier (valeur d'un code de caractère Unicode).

Ce paramétrage affecte mb_convert_encoding(), mb_convert_variables(), mb_output_handler(), mb_scrub(), et mb_send_mail().

### Liste de paramètres

`substitute_character`

  Spécifie une valeur Unicode sous la forme d'un entier, ou bien une chaîne de caractères sous ces formes :

  - `"none"` : pas d'affichage
  - `"long"` : affiche la valeur hexadécimale (Exemple : `U+3000`, `JIS+7E7E`)
  - `"entity"` : affiche l'entité du caractère (Exemple : `&#x200;`)

### Valeurs de retour

Si `substitute_character` est fourni, mb_substitute_character() retourne `true` en cas de succès, et `false` en cas d'erreur. Si `substitute_character` est omis, mb_substitute_character() retourne une valeur Unicode, ou bien "`none`"/"`long`".

### Historique

Version | Description
--- | ---
8.0.0 | Passer une chaîne vide à `substitute_character` n'est plus supporté; `"none"` devrait être fourni à la place.
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Exemple avec mb_substitute_character()

    <?php
    /* Configure le caractère de substitution avec U+3013 (GETA MARK) */
    mb_substitute_character(0x3013);

    /* Configure le caractère de substitution avec un format hexadécimal */
    mb_substitute_character("long");

    /* Affiche la configuration courante */
    echo mb_substitute_character();
    ?>

# mb_substr

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substr — Lit une sous-chaîne

### Description

function mb_substr(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

Effectue une opération de type substr() basée sur le nombre de caractères. La position est celle depuis le début de la chaîne de caractères `string`. La position du premier caractère est `0`, le second, un, etc.

### Liste de paramètres

`string`

  La chaîne depuis laquelle extraire la sous-chaîne.

`start`

  Si `start` est positif, la chaîne retournée commencera au caractère numéro `start`, dans la chaîne `string`. Le premier caractère est numéroté zéro. En effet, dans la chaîne '`abcdef`', le caractère à la position `0` est '`a`', le caractère à la position `2` est '`c`', et ainsi de suite.

  Si `start` est négatif, la chaîne retournée commencera au caractère numéro `start` à compter de la fin de la chaîne `string`.

`length`

  Nombre maximal de caractères à utiliser depuis `string`. Si ce paramètre est omis, ou vaut `NULL`, tous les caractères jusqu'à la fin de la chaîne seront extraits.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

mb_substr() retourne la portion de la chaîne `string` qui commence au caractère `start` et a la longueur de `length` caractères.

### Historique

Version | Description
--- | ---
8.4.0 | Sur les chaînes invalides (celles comportant des erreurs d'encodage), les indices de caractères sont désormais interprétés de la même manière que la plupart des autres fonctions mbstring. Cela signifie que les indices de caractères retournés par mb_strpos() peuvent être passés directement.
8.0.0 | `encoding` est désormais nullable.

### Voir aussi

- mb_strcut() - Coupe une partie de chaîne
- mb_internal_encoding() - Lit/modifie l'encodage interne

# mb_substr_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_substr_count — Compte le nombre d'occurrences d'une sous-chaîne

### Description

function mb_substr_count(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int

Compte le nombre d'occurrences de la chaîne `needle` dans la chaîne `haystack`.

### Liste de paramètres

`haystack`

  La chaîne à analyser.

`needle`

  La chaîne à chercher.

`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

Retourne le nombre de fois où la chaîne `needle` apparaît dans la chaîne `haystack`.

### Historique

Version | Description
--- | ---
8.0.0 | `encoding` est désormais nullable.

### Exemples

Exemple #1 Exemple avec mb_substr_count()

    <?php
    echo mb_substr_count("Ceci est un test", "es"); // affiche 2
    ?>

### Voir aussi

- mb_strpos() - Repère la première occurrence d'un caractère dans une chaîne
- mb_substr() - Lit une sous-chaîne
- substr_count() - Compte le nombre d'occurrences de segments dans une chaîne

# mb_trim

(PHP 8 >= 8.4.0)

mb_trim — Supprime les espaces (ou d'autres caractères) du début et de la fin d'une chaîne

### Description

function mb_trim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Effectue une opération trim() multi-octets sûre, et renvoie une chaîne avec les espaces supprimés du début et de la fin de `string`. Sans le deuxième paramètre, mb_trim() supprimera les caractères suivants :

- `" "` (Unicode U+0020), un espace ordinaire.
- `"\t"` (Unicode U+0009), une tabulation.
- `"\n"` (Unicode U+000A), un saut de ligne.
- `"\r"` (Unicode U+000D), un retour chariot.
- `"\0"` (Unicode U+0000), l'octet NUL.
- `"\v"` (Unicode U+000B), une tabulation verticale.
- `"\f"` (Unicode U+000C), une avance de page.
- `"\u00A0"` (Unicode U+00A0), un ESPACE INSÉCABLE.
- `"\u1680"` (Unicode U+1680), une MARQUE D'ESPACE OGHAM.
- `"\u2000"` (Unicode U+2000), un CADRATIN MOYEN.
- `"\u2001"` (Unicode U+2001), un CADRATIN.
- `"\u2002"` (Unicode U+2002), un ESPACE MOYEN.
- `"\u2003"` (Unicode U+2003), un ESPACE CADRATIN.
- `"\u2004"` (Unicode U+2004), un ESPACE D'UN-TIERS-DE-CADRATIN.
- `"\u2005"` (Unicode U+2005), un ESPACE D'UN-QUART-DE-CADRATIN.
- `"\u2006"` (Unicode U+2006), un ESPACE D'UN-SIXIÈME-DE-CADRATIN.
- `"\u2007"` (Unicode U+2007), un ESPACE POUR CHIFFRES.
- `"\u2008"` (Unicode U+2008), un ESPACE DE PONCTUATION.
- `"\u2009"` (Unicode U+2009), un ESPACE FINE.
- `"\u200A"` (Unicode U+200A), un ESPACE CHEVEU.
- `"\u2028"` (Unicode U+2028), un SÉPARATEUR DE LIGNE.
- `"\u2029"` (Unicode U+2029), un SÉPARATEUR DE PARAGRAPHE.
- `"\u202F"` (Unicode U+202F), un ESPACE INSÉCABLE ÉTROIT.
- `"\u205F"` (Unicode U+205F), un ESPACE MATHÉMATIQUE MOYEN.
- `"\u3000"` (Unicode U+3000), un ESPACE IDÉOGRAPHIQUE.
- `"\u0085"` (Unicode U+0085), une LIGNE SUIVANTE (NEL).
- `"\u180E"` (Unicode U+180E), un SÉPARATEUR DE VOYELLE MONGOL.

### Liste de paramètres

`string`
  La string qui sera trimmée.
`characters`
  Optionnellement, les caractères à supprimer peuvent aussi être spécifiés en utilisant le paramètre `characters`. Il suffit de lister tous les caractères à supprimer.
`encoding`
  Le paramètre `encoding` est l'encodage des caractères. S'il est omis ou `null`, l'encodage de caractères interne sera utilisé.

### Valeurs de retour

La chaîne trimmée.

### Voir aussi

- mb_ltrim() - Supprime les espaces (ou d'autres caractères) du début d'une chaîne
- mb_rtrim() - Supprime les espaces (ou d'autres caractères) de la fin d'une chaîne
- trim() - Supprime les espaces (ou d'autres caractères) en début et fin de chaîne

# mb_ucfirst

(PHP 8 >= 8.4.0)

mb_ucfirst — Rend une chaîne avec la première lettre en majuscule

### Description

function mb_ucfirst(string `$string`, ?string `$encoding` = `null`): string

Effectue une opération ucfirst() multi-octets sûre, et renvoie une chaîne avec la première lettre de `string` en majuscule.

### Liste de paramètres

`string`
  La chaîne d'entrée.
`encoding`
  La chaîne d'encodage.

### Valeurs de retour

Renvoie la chaîne de résultat.

### Notes

> Note:

> Contrairement aux fonctions de conversion de casse standard telles que strtolower() et strtoupper(), la conversion de casse est effectuée sur la base des propriétés des caractères Unicode. Ainsi, le comportement de cette fonction n'est pas affecté par les paramètres régionaux, et elle peut convertir tous les caractères ayant la propriété 'alphabétique', comme le tréma sur le "a" (ä).

Pour plus d'informations sur les propriétés Unicode, veuillez consulter » http://www.unicode.org/reports/tr21/.

### Voir aussi

- mb_lcfirst() - Rend la première lettre d'une chaîne en minuscule
- mb_convert_case() - Modifie la casse d'une chaîne
- ucfirst() - Met le premier caractère en majuscule

## Sommaire

- mb_check_encoding — Vérifie si les chaînes sont valides pour l'encodage spécifié
- mb_chr — Retourne un caractère par sa valeur de point de code Unicode
- mb_convert_case — Modifie la casse d'une chaîne
- mb_convert_encoding — Convertir une chaîne d'un codage de caractères à un autre
- mb_convert_kana — Convertit un "kana" en un autre ("zen-kaku", "han-kaku" et plus)
- mb_convert_variables — Convertit l'encodage de variables
- mb_decode_mimeheader — Décode un en-tête MIME
- mb_decode_numericentity — Décode les entités HTML en caractères
- mb_detect_encoding — Détecte un encodage
- mb_detect_order — Lit/modifie l'ordre de détection des encodages
- mb_encode_mimeheader — Encode une chaîne pour un en-tête MIME
- mb_encode_numericentity — Encode les caractères en référence numérique HTML
- mb_encoding_aliases — Récupère les alias d'un type d'encodage connu
- mb_ereg — Recherche par expression rationnelle avec support des caractères multioctets
- mb_ereg_match — Expression rationnelle POSIX pour les chaînes multioctets
- mb_ereg_replace — Remplace des segments de chaîne à l'aide des expressions régulières
- mb_ereg_replace_callback — Rechercher et remplacer par expression régulière avec support multi octets utilisant une fonction de callback
- mb_ereg_search — Recherche par expression rationnelle multioctets
- mb_ereg_search_getpos — Retourne la position du début du prochain segment repéré par une expression rationnelle
- mb_ereg_search_getregs — Lit le dernier segment de chaîne multioctets qui correspond au masque
- mb_ereg_search_init — Configure les chaînes et les expressions régulières pour le support des caractères multioctets
- mb_ereg_search_pos — Retourne la position et la longueur du segment de chaîne qui vérifie le masque de l'expression rationnelle
- mb_ereg_search_regs — Retourne le segment de chaîne trouvé par une expression rationnelle multioctets
- mb_ereg_search_setpos — Choisit le point de départ de la recherche par expression rationnelle
- mb_eregi — Expression rationnelle insensible à la casse avec le support des caractères multioctets
- mb_eregi_replace — Expression rationnelle avec support des caractères multioctets, sans tenir compte de la casse
- mb_get_info — Lit la configuration interne de l'extension mbstring
- mb_http_input — Détecte le type d'encodage d'un caractère HTTP
- mb_http_output — Lit/modifie l'encodage d'affichage
- mb_internal_encoding — Lit/modifie l'encodage interne
- mb_language — Définit/Récupère le langage courant
- mb_lcfirst — Rend la première lettre d'une chaîne en minuscule
- mb_list_encodings — Retourne un tableau contenant tous les encodages supportés
- mb_ltrim — Supprime les espaces (ou d'autres caractères) du début d'une chaîne
- mb_ord — Récupère le point de code Unicode d'un caractère
- mb_output_handler — Fonction de traitement des affichages
- mb_parse_str — Analyse les données HTTP GET/POST/COOKIE et assigne les variables globales
- mb_preferred_mime_name — Détecte l'encodage MIME
- mb_regex_encoding — Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
- mb_regex_set_options — Lit et modifie les options des fonctions d'expression rationnelle à support de caractères multioctets
- mb_rtrim — Supprime les espaces (ou d'autres caractères) de la fin d'une chaîne
- mb_scrub — Remplace les séquences d'octets mal formées par le caractère de substitution.
- mb_send_mail — Envoie un mail encodé
- mb_split — Scinde une chaîne en tableau avec une expression rationnelle multioctets
- mb_str_pad — Remplit une chaîne multioctets à une certaine longueur avec une autre chaîne multioctets
- mb_str_split — Pour une chaîne multi-octets donnée, renvoie un tableau de ses caractères
- mb_strcut — Coupe une partie de chaîne
- mb_strimwidth — Tronque une chaîne
- mb_stripos — Trouve la première occurrence d'une chaîne dans une autre, sans tenir compte de la casse
- mb_stristr — Trouve la première occurrence d'une chaîne dans une autre, sans tenir compte de la casse
- mb_strlen — Retourne la taille d'une chaîne
- mb_strpos — Repère la première occurrence d'un caractère dans une chaîne
- mb_strrchr — Trouve la dernière occurrence d'un caractère d'une chaîne dans une autre
- mb_strrichr — Trouve la dernière occurrence d'un caractère d'une chaîne dans une autre, insensible à la casse
- mb_strripos — Trouve la position de la dernière occurrence d'une chaîne dans une autre, en ne tenant pas compte de la casse
- mb_strrpos — Repère la dernière occurrence d'un caractère dans une chaîne
- mb_strstr — Trouve la première occurrence d'une chaîne dans une autre
- mb_strtolower — Met tous les caractères en minuscules
- mb_strtoupper — Met tous les caractères en majuscules
- mb_strwidth — Retourne la taille d'une chaîne
- mb_substitute_character — Définit/Récupère les caractères de substitution
- mb_substr — Lit une sous-chaîne
- mb_substr_count — Compte le nombre d'occurrences d'une sous-chaîne
- mb_trim — Supprime les espaces (ou d'autres caractères) du début et de la fin d'une chaîne
- mb_ucfirst — Rend une chaîne avec la première lettre en majuscule

- Installation/Configuration
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Jeux de caractères supportés
- Cas des caractères japonais
- Entrées/Sorties HTTP
- Jeux de caractères supportés
- Fonctionnalité de surcharge de fonctions
- Prérequis de l'encodage en PHP
- Fonctions sur les chaînes de caractères multioctets
  - mb_check_encoding — Vérifie si les chaînes sont valides pour l'encodage spécifié
  - mb_chr — Retourne un caractère par sa valeur de point de code Unicode
  - mb_convert_case — Modifie la casse d'une chaîne
  - mb_convert_encoding — Convertir une chaîne d'un codage de caractères à un autre
  - mb_convert_kana — Convertit un "kana" en un autre ("zen-kaku", "han-kaku" et plus)
  - mb_convert_variables — Convertit l'encodage de variables
  - mb_decode_mimeheader — Décode un en-tête MIME
  - mb_decode_numericentity — Décode les entités HTML en caractères
  - mb_detect_encoding — Détecte un encodage
  - mb_detect_order — Lit/modifie l'ordre de détection des encodages
  - mb_encode_mimeheader — Encode une chaîne pour un en-tête MIME
  - mb_encode_numericentity — Encode les caractères en référence numérique HTML
  - mb_encoding_aliases — Récupère les alias d'un type d'encodage connu
  - mb_ereg — Recherche par expression rationnelle avec support des caractères multioctets
  - mb_ereg_match — Expression rationnelle POSIX pour les chaînes multioctets
  - mb_ereg_replace — Remplace des segments de chaîne à l'aide des expressions régulières
  - mb_ereg_replace_callback — Rechercher et remplacer par expression régulière avec support multi octets utilisant une fonction de callback
  - mb_ereg_search — Recherche par expression rationnelle multioctets
  - mb_ereg_search_getpos — Retourne la position du début du prochain segment repéré par une expression rationnelle
  - mb_ereg_search_getregs — Lit le dernier segment de chaîne multioctets qui correspond au masque
  - mb_ereg_search_init — Configure les chaînes et les expressions régulières pour le support des caractères multioctets
  - mb_ereg_search_pos — Retourne la position et la longueur du segment de chaîne qui vérifie le masque de l'expression rationnelle
  - mb_ereg_search_regs — Retourne le segment de chaîne trouvé par une expression rationnelle multioctets
  - mb_ereg_search_setpos — Choisit le point de départ de la recherche par expression rationnelle
  - mb_eregi — Expression rationnelle insensible à la casse avec le support des caractères multioctets
  - mb_eregi_replace — Expression rationnelle avec support des caractères multioctets, sans tenir compte de la casse
  - mb_get_info — Lit la configuration interne de l'extension mbstring
  - mb_http_input — Détecte le type d'encodage d'un caractère HTTP
  - mb_http_output — Lit/modifie l'encodage d'affichage
  - mb_internal_encoding — Lit/modifie l'encodage interne
  - mb_language — Définit/Récupère le langage courant
  - mb_lcfirst — Rend la première lettre d'une chaîne en minuscule
  - mb_list_encodings — Retourne un tableau contenant tous les encodages supportés
  - mb_ltrim — Supprime les espaces (ou d'autres caractères) du début d'une chaîne
  - mb_ord — Récupère le point de code Unicode d'un caractère
  - mb_output_handler — Fonction de traitement des affichages
  - mb_parse_str — Analyse les données HTTP GET/POST/COOKIE et assigne les variables globales
  - mb_preferred_mime_name — Détecte l'encodage MIME
  - mb_regex_encoding — Définit/Récupère l'encodage des caractères pour les expressions régulières multioctets
  - mb_regex_set_options — Lit et modifie les options des fonctions d'expression rationnelle à support de caractères multioctets
  - mb_rtrim — Supprime les espaces (ou d'autres caractères) de la fin d'une chaîne
  - mb_scrub — Remplace les séquences d'octets mal formées par le caractère de substitution.
  - mb_send_mail — Envoie un mail encodé
  - mb_split — Scinde une chaîne en tableau avec une expression rationnelle multioctets
  - mb_str_pad — Remplit une chaîne multioctets à une certaine longueur avec une autre chaîne multioctets
  - mb_str_split — Pour une chaîne multi-octets donnée, renvoie un tableau de ses caractères
  - mb_strcut — Coupe une partie de chaîne
  - mb_strimwidth — Tronque une chaîne
  - mb_stripos — Trouve la première occurrence d'une chaîne dans une autre, sans tenir compte de la casse
  - mb_stristr — Trouve la première occurrence d'une chaîne dans une autre, sans tenir compte de la casse
  - mb_strlen — Retourne la taille d'une chaîne
  - mb_strpos — Repère la première occurrence d'un caractère dans une chaîne
  - mb_strrchr — Trouve la dernière occurrence d'un caractère d'une chaîne dans une autre
  - mb_strrichr — Trouve la dernière occurrence d'un caractère d'une chaîne dans une autre, insensible à la casse
  - mb_strripos — Trouve la position de la dernière occurrence d'une chaîne dans une autre, en ne tenant pas compte de la casse
  - mb_strrpos — Repère la dernière occurrence d'un caractère dans une chaîne
  - mb_strstr — Trouve la première occurrence d'une chaîne dans une autre
  - mb_strtolower — Met tous les caractères en minuscules
  - mb_strtoupper — Met tous les caractères en majuscules
  - mb_strwidth — Retourne la taille d'une chaîne
  - mb_substitute_character — Définit/Récupère les caractères de substitution
  - mb_substr — Lit une sous-chaîne
  - mb_substr_count — Compte le nombre d'occurrences d'une sous-chaîne
  - mb_trim — Supprime les espaces (ou d'autres caractères) du début et de la fin d'une chaîne
  - mb_ucfirst — Rend une chaîne avec la première lettre en majuscule

# Pspell

# Introduction

Avertissement

Cette extension est DÉPRÉCIÉE et SÉPARÉE à partir de PHP 8.4.0.

La bibliothèque pspell permet de vérifier l'orthographe d'un mot, et suggérer des corrections.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Types de ressources

## Pré-requis

Pour compiler PHP avec le support pspell, on aura besoin de la bibliothèque aspell, disponible à » http://aspell.net/.

## Installation

## PHP 8.4

Cette extension a été déplacée dans le module » PECL et ne sera plus intégrée dans PHP à partir de PHP 8.4.0

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/pspell.

## PHP < 8.4

Pour activer cette extension, compilez PHP avec l'option --with-pspell[=dir].

> Note: Note pour les utilisateurs Win32

> Afin de faire fonctionner cette extension, quelques bibliothèques DLL doivent être disponibles via le PATH du système Windows. Lisez la F.A.Q intitulée "Comment ajouter mon dossier PHP à mon PATH Windows" pour plus d'informations. Le fait de copier les bibliothèques DLL depuis le dossier PHP dans le dossier système Windows fonctionne également (car le dossier système est par défaut dans le PATH système), mais cette méthode n'est pas recommandée. Cette extension nécessite que les fichiers suivants se trouvent dans le PATH : aspell-15.dll depuis le dossier bin de l'installation d'aspell.

> Le support Win32 nécessite au moins la version 0.50 d'aspell.

## Types de ressources

Antérieur à PHP 8.1.0, il y avait deux types de resource dans cette extension. Le premier étant le lien d'identification de dictionnaire, le second est une ressource qui tient la configuration pspell.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`PSPELL_FAST` (int)
`PSPELL_NORMAL` (int)
`PSPELL_BAD_SPELLERS` (int)
`PSPELL_RUN_TOGETHER` (int)

# Fonctions Pspell

# pspell_add_to_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_personal — Ajoute le mot au dictionnaire personnel

### Description

function pspell_add_to_personal(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_personal() ajoute un mot au dictionnaire personnel. Lors de l'utilisation de pspell_new_config() avec pspell_config_personal() pour ouvrir le dictionnaire, il sera possible de sauver le dictionnaire personnel ultérieurement avec pspell_save_wordlist().

### Liste de paramètres

`dictionary`
  Une instance de PSpell\Dictionary.
`word`

  Le mot ajouté.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `dictionary` attend désormais une instance de PSpell\Dictionary ; auparavant, une resource était expected.

### Exemples

Exemple #1 pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Notes

> Note:

> Cette fonction ne marchera que si l'on a pspell .11.2 et aspell .32.5 ou ultérieurs.

# pspell_add_to_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_session — Ajoute le mot au dictionnaire personnel de la session courante

### Description

function pspell_add_to_session(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_session() ajoute un mot au dictionnaire personnel associé à la session courante. C'est une fonction similaire à pspell_add_to_personal().

### Liste de paramètres

`dictionary`
  Une instance de PSpell\Dictionary.
`word`

  Le mot ajouté.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `dictionary` attend désormais une instance de PSpell\Dictionary ; auparavant, une resource était expected.

# pspell_check

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_check — Vérifie un mot

### Description

function pspell_check(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_check() vérifie l'orthographe d'un mot.

### Liste de paramètres

`dictionary`
  Une instance de PSpell\Dictionary.
`word`

  Le mot testé.

### Valeurs de retour

Retourne `true` si l'orthographe est correcte, `false` sinon.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `dictionary` attend désormais une instance de PSpell\Dictionary ; auparavant, une resource était expected.

### Exemples

Exemple #1 Exemple avec pspell_check()

    <?php
    $pspell = pspell_new ("fr");

    if (pspell_check($pspell, "testt")) {
        echo 'L\'orthographe est exacte';
    } else {
        echo 'Désolé, mauvaise orthographe';
    }
    ?>

# pspell_clear_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_clear_session — Remet à zéro la session courante

### Description

function pspell_clear_session(PSpell\Dictionary `$dictionary`): bool

pspell_clear_session() remet à zéro la session courante. Le dictionnaire personnel est vidé et, par exemple, si l'on tente de l'enregistrer avec pspell_save_wordlist(), rien ne se passera.

### Liste de paramètres

`dictionary`
  Une instance de PSpell\Dictionary.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `dictionary` attend désormais une instance de PSpell\Dictionary ; auparavant, une resource était expected.

### Exemples

Exemple #1 Exemple avec pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_clear_session($pspell);
    pspell_save_wordlist($pspell);  //"Vlad" ne sera pas sauvé
    ?>

# pspell_config_create

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_create — Crée une configuration utilisée pour ouvrir un dictionnaire

### Description

function pspell_config_create(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = ""
): PSpell\Config

Crée une configuration utilisée pour ouvrir un dictionnaire.

pspell_config_create() a une syntaxe similaire à celle de pspell_new(). En fait, utiliser pspell_config_create() suivi immédiatement par pspell_new_config() produira exactement le même résultat. Cependant, après avoir créé une nouvelle configuration, il est aussi possible d'utiliser les fonctions pspell_config_*() avant d'appeler pspell_new_config() pour tirer profit des fonctionnalités avancées.

Pour davantage d'information et d'exemples, jetez un oeil au manuel en ligne sur le site de pspell : » http://aspell.net/.

### Liste de paramètres

`language`

  Le paramètre de langage `language` est le code de langue en deux lettres, défini dans la norme ISO 639, et deux lettres optionnelles ISO 3166, après un tiret ou un souligné (_).

`spelling`

  Le paramètre d'orthographe `spelling` est nécessaire pour les langues qui ont plus d'une orthographe, comme l'anglais. Les valeurs reconnues sont alors 'american' (américain) , 'british' (anglais), et 'canadian' (canadien).

`jargon`

  Le paramètre de jargon `jargon` contient des informations supplémentaires pour distinguer deux dictionnaires distincts pour la même langue et le même paramètre d'orthographe `spelling`.

`encoding`

  Le paramètre d'encodage `encoding` indique l'encodage attendu pour la réponse. Les valeurs valides sont : 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. Ce paramètre n'a pas été testé de manière exhaustive, alors soyez prudent.

### Valeurs de retour

Retourne une instance de PSpell\Config.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PSpell\Config ; auparavant, une resource était retournée.

### Exemples

Exemple #1 pspell_config_create()

    <?php
    $pspell_config = pspell_config_create("fr");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_personal($pspell_config, "fr");
    ?>

# pspell_config_data_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_data_dir — Dossier qui contient les fichiers de données linguistiques

### Description

function pspell_config_data_dir(PSpell\Config `$config`, string `$directory`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `config` attend désormais une instance de PSpell\Config ; auparavant, une resource était expected.

# pspell_config_dict_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_dict_dir — Endroit où se trouve le fichier global des mots

### Description

function pspell_config_dict_dir(PSpell\Config `$config`, string `$directory`): bool

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `config` attend désormais une instance de PSpell\Config ; auparavant, une resource était expected.

# pspell_config_ignore

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_ignore — Ignore les mots de moins de N caractères

### Description

function pspell_config_ignore(PSpell\Config `$config`, int `$min_length`): bool

pspell_config_ignore() doit être utilisée avec une configuration avant d'appeler pspell_new_config(). Cette fonction permet au vérificateur d'ignorer les mots courts.

### Liste de paramètres

`config`
  Une instance de PSpell\Config.
`min_length`

  Les mots de moins de `min_length` caractères seront ignorés.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `config` attend désormais une instance de PSpell\Config ; auparavant, une resource était expected.

### Exemples

Exemple #1 pspell_config_ignore()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_ignore($pspell_config, 5);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "abcd");  // Ce mot ne provoquera pas d'erreur
    ?>

# pspell_config_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_mode — Change le mode de suggestion

### Description

function pspell_config_mode(PSpell\Config `$config`, int `$mode`): bool

pspell_config_mode() doit être appelée dans une configuration avant pspell_new_config(). Cette fonction détermine le nombre de suggestions qui seront retournées par pspell_suggest().

### Liste de paramètres

`config`
  Une instance de PSpell\Config.
`mode`

  Le paramètre de mode est le mode de travail du vérificateur d'orthographe. Plusieurs modes sont disponibles :

  - `PSPELL_FAST` - Mode rapide (moins de suggestions)
  - `PSPELL_NORMAL` - Mode normal (plus de suggestions)
  - `PSPELL_BAD_SPELLERS` - Mode lent (beaucoup plus de suggestions)

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `config` attend désormais une instance de PSpell\Config ; auparavant, une resource était expected.

### Exemples

Exemple #1 Exemple avec pspell_config_mode()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_mode($pspell_config, PSPELL_FAST);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_personal — Choisit le fichier qui contient le dictionnaire personnel

### Description

function pspell_config_personal(PSpell\Config `$config`, string `$filename`): bool

Choisit le fichier qui contient le dictionnaire personnel. Le dictionnaire personnel sera chargé et utilisé en plus du dictionnaire standard, une fois que l'on aura appelé pspell_new_config(). Le fichier est aussi là où pspell_save_wordlist() sauvegardera le dictionnaire personnel.

pspell_config_personal() doit être appelée dans une configuration avant d'appeler pspell_new_config().

### Liste de paramètres

`config`
  Une instance de PSpell\Config.
`filename`

  Le dictionnaire personnel. Si le fichier n'existe pas, il sera créé. Le fichier doit être accessible en écriture pour l'utilisateur invoquant PHP (ex. nobody).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `config` attend désormais une instance de PSpell\Config ; auparavant, une resource était expected.

### Exemples

Exemple #1 pspell_config_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

### Notes

> Note:

> Cette fonction ne marchera qu'avec pspell .11.2 et aspell .32.5 ou ultérieurs.

# pspell_config_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_repl — Choisit le fichier qui contient les paires de remplacement

### Description

function pspell_config_repl(PSpell\Config `$config`, string `$filename`): bool

Choisit le fichier qui contient les paires de remplacement.

Les paires de remplacement améliorent la qualité du vérificateur. Lorsqu'un mot est mal orthographié et qu'aucune suggestion valable n'est trouvée dans le dictionnaire, pspell_store_replacement() sera utilisée pour enregistrer une paire de remplacement et pspell_save_wordlist() pour sauver le dictionnaire avec les paires de remplacement.

pspell_config_repl() doit être utilisé avec une configuration avant d'appeler pspell_new_config().

### Liste de paramètres

`config`
  Une instance de PSpell\Config.
`filename`

  Le fichier doit être accessible en écriture pour l'utilisateur invoquant PHP (ex. nobody).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `config` attend désormais une instance de PSpell\Config ; auparavant, une resource était expected.

### Exemples

Exemple #1 pspell_config_repl()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

### Notes

> Note:

> Cette fonction ne marchera qu'avec pspell .11.2 et aspell .32.5 ou ultérieurs.

# pspell_config_runtogether

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_runtogether — Considère deux mots accolés comme un composé

### Description

function pspell_config_runtogether(PSpell\Config `$config`, bool `$allow`): bool

Cette fonction indique si deux mots accolés doivent être traités comme un composé valide. Ainsi "lechat" sera traité comme un composé valide bien qu'il devrait y avoir un espace entre ces deux mots. Modifier cette configuration n'affecte que les résultats retournés par pspell_check(); pspell_suggest() retournera toujours des suggestions.

pspell_config_runtogether() doit être appelée dans une configuration avant pspell_new_config().

### Liste de paramètres

`config`
  Une instance de PSpell\Config.
`allow`

  `true` si deux mots accolés doivent être traités comme un composé valide, `false` sinon.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `config` attend désormais une instance de PSpell\Config ; auparavant, une resource était expected.

### Exemples

Exemple #1 pspell_config_runtogether()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_runtogether($pspell_config, true);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_save_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_save_repl — Détermine s'il faut sauver les paires de remplacement avec le dictionnaire

### Description

function pspell_config_save_repl(PSpell\Config `$config`, bool `$save`): bool

pspell_config_save_repl() détermine si pspell_save_wordlist() doit sauver les paires de remplacement avec le dictionnaire. Généralement, il n'y a pas besoin d'utiliser cette fonction car, si pspell_config_repl() est utilisée, les paires de remplacement seront sauvées de toute façon par pspell_save_wordlist(), et, si ce n'est pas le cas, elles ne le seront pas.

pspell_config_save_repl() doit être appelée dans une configuration avant d'appeler pspell_new_config().

### Liste de paramètres

`config`
  Une instance de PSpell\Config.
`save`

  `true` si les paires de remplacement doivent être sauvées, `false` sinon.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `config` attend désormais une instance de PSpell\Config ; auparavant, une resource était expected.

### Notes

> Note:

> Cette fonction ne marchera qu'avec pspell .11.2 et aspell .32.5 ou ultérieurs.

# pspell_new

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new — Charge un nouveau dictionnaire

### Description

function pspell_new(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new() ouvre un nouveau dictionnaire et retourne une instance de PSpell\Dictionary, pour être utilisée avec d'autres fonctions pspell.

Pour plus d'informations et d'exemples, se reporter au site » http://aspell.net/.

### Liste de paramètres

`language`

  Le paramètre de langue `language` est constitué des deux lettres du codage de langue ISO 639, et du codage optionnel de pays ISO 3166, séparés par un '_'.

`spelling`

  Ce paramètre est nécessaire pour les langues qui ont plus d'une orthographe, comme l'anglais ou le français. Les valeurs reconnues sont 'american', 'british', et 'canadian'.

`jargon`

  Le paramètre `jargon` contient des informations supplémentaires pour distinguer deux listes de mots qui ont le même marquage de langue et d'orthographe.

`encoding`

  Le paramètre `encoding` est le type d'encodage des mots. Les valeurs valides sont 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. Ce paramètre n'ayant pas été testé de façon exhaustive, il convient d'être prudent lors de son utilisation.

`mode`

  Le paramètre `mode` est le mode de travail du vérificateur d'orthographe. Plusieurs modes sont disponibles :

  - `PSPELL_FAST` - Mode rapide (moins de suggestions)
  - `PSPELL_NORMAL` - Mode normal (plus de suggestions)
  - `PSPELL_BAD_SPELLERS` - Mode lent (beaucoup plus de suggestions)
  - `PSPELL_RUN_TOGETHER` - Considère que des mots accolés forment un composé autorisé. Ainsi, "lechat" sera un composé valide. Cette option ne modifie que les résultats retournés par pspell_check(); pspell_suggest() retournera toujours des suggestions.
  `mode` est un masque construit à partir des constantes listées ci-dessus. Cependant, `PSPELL_FAST`, `PSPELL_NORMAL` et `PSPELL_BAD_SPELLERS` sont mutuellement exclusives : on ne doit en utiliser qu'un à la fois.

### Valeurs de retour

Retourne une instance de PSpell\Dictionary en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PSpell\Dictionary ; auparavant, une resource était retournée.

### Exemples

Exemple #1 pspell_new()

    <?php
    $pspell = pspell_new("en", "", "", "",
                         (PSPELL_FAST|PSPELL_RUN_TOGETHER));
    ?>

# pspell_new_config

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_config — Charge un nouveau dictionnaire avec les paramètres spécifiés dans une configuration

### Description

function pspell_new_config(PSpell\Config `$config`): PSpell\Dictionary|false

pspell_new_config() ouvre un nouveau dictionnaire avec les paramétrages de la configuration `config`, créée avec pspell_config_create() et modifiée avec les fonctions pspell_config_*(). Cette méthode donne le maximum de flexibilité, et dispose de toutes les fonctionnalités fournies par pspell_new() et pspell_new_personal().

### Liste de paramètres

`config`

  Le `config` est celui qui est retourné par pspell_config_create() lorsque la configuration est créée.

### Valeurs de retour

Retourne une instance de PSpell\Dictionary en cas de succès, ou `false` si une erreur survient

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `config` attend désormais une instance de PSpell\Config ; auparavant, une resource était expected.
8.1.0 | Retourne désormais une instance de PSpell\Dictionary ; auparavant, une resource était retournée.

### Exemples

Exemple #1 pspell_new_config()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    ?>

# pspell_new_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_personal — Charge un nouveau dictionnaire avec un dictionnaire personnel

### Description

function pspell_new_personal(
string `$filename`,
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new_personal() charge un nouveau dictionnaire avec un dictionnaire personnel. Ce dernier peut être modifié et sauvé avec pspell_save_wordlist(). Cependant, les paires de remplacement ne seront pas sauvées. Pour ce faire, il faut créer une configuration qui utilise pspell_config_create(), choisir le fichier de destination du dictionnaire personnel avec pspell_config_personal(), choisir le fichier de paires de remplacement avec pspell_config_repl() et ouvrir un nouveau dictionnaire avec pspell_new_config().

Pour davantage d'information et d'exemples, jetez un oeil sur le manuel en ligne sur le site web de pspell : » http://aspell.net/.

### Liste de paramètres

`filename`

  Le fichier où seront ajoutés les mots du dictionnaire personnel. Ce doit être un chemin absolu, qui commence par '/' car, sinon, il sera relatif à $HOME, qui est "/root" sur la plupart des systèmes, et probablement pas ce que l'on souhaite.

`language`

  Le paramètre de langage `language` est le code de langue ISO 639 en deux lettres, suivi de deux lettres optionnelles ISO 3166, après un tiret ou un souligné (_).

`spelling`

  Le paramètre d'orthographe `spelling` est nécessaire pour les langues qui ont plus d'une orthographe, comme l'anglais. Les valeurs reconnues sont alors 'american' (américain) , 'british' (anglais), et 'canadian' (canadien).

`jargon`

  Informations supplémentaires pour distinguer deux dictionnaires distincts pour la même langue et le même paramètre d'orthographe `spelling`.

`encoding`

  L'encodage attendu pour la réponse. Les valeurs valides sont : `utf-8`, `iso8859-*`, `koi8-r`, `viscii`, `cp1252`, `machine unsigned 16`, `machine unsigned 32`.

`mode`

  Le mode de travail du vérificateur d'orthographe. Plusieurs modes sont disponibles :

  - `PSPELL_FAST` - Mode rapide (moins de suggestions)
  - `PSPELL_NORMAL` - Mode normal (plus de suggestions)
  - `PSPELL_BAD_SPELLERS` - Mode lent (beaucoup plus de suggestions)
  - `PSPELL_RUN_TOGETHER` - Considère les mots attachés comme légaux. De ce fait, "lechat" sera un mot composé légal, bien qu'il devrait y avoir un espace entre les deux mots. Changer cette configuration n'affecte que le résultat retourné par pspell_check(); pspell_suggest() continuera de retourner les suggestions.
  Le mode est un masque construit depuis les différentes constantes listées ci-dessous. Cependant, les constantes `PSPELL_FAST`, `PSPELL_NORMAL` et `PSPELL_BAD_SPELLERS` sont mutuellement exclusives, donc on ne doit sélectionner qu'une seule d'entre elles.

### Valeurs de retour

Retourne une instance de PSpell\Dictionary en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PSpell\Dictionary ; auparavant, une resource était retournée.

### Exemples

Exemple #1 pspell_new_personal()

    <?php
    $pspell = pspell_new_personal ("/var/dictionaries/custom.pws",
            "en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER);
    ?>

# pspell_save_wordlist

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_save_wordlist — Sauve le dictionnaire personnel dans un fichier

### Description

function pspell_save_wordlist(PSpell\Dictionary `$dictionary`): bool

pspell_save_wordlist() sauve le dictionnaire personnel de la session courante. La localisation des fichiers doit avoir été spécifiée avec pspell_config_personal() et (éventuellement) pspell_config_repl().

### Liste de paramètres

`dictionary`
  Une instance de PSpell\Dictionary.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `dictionary` attend désormais une instance de PSpell\Dictionary ; auparavant, une resource était expected.

### Exemples

Exemple #1 pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/tmp/dicts/newdict");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Notes

> Note:

> Cette fonction ne marchera qu'avec pspell .11.2 et aspell .32.5 ou ultérieurs.

# pspell_store_replacement

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_store_replacement — Enregistre une paire de remplacement pour un mot

### Description

function pspell_store_replacement(PSpell\Dictionary `$dictionary`, string `$misspelled`, string `$correct`): bool

pspell_store_replacement() enregistre une paire de remplacement pour un mot de façon à ce que cette suggestion soit retournée par pspell_suggest() plus tard. Pour pouvoir utiliser cette fonction, il faut utiliser pspell_new_personal() pour ouvrir le dictionnaire. Pour pouvoir sauver tout le temps les paires de remplacement, il faut utiliser pspell_config_personal() et pspell_config_repl() pour indiquer le lieu de sauvegarde des dictionnaires personnels, et pspell_save_wordlist() pour enregistrer les modifications sur le disque.

### Liste de paramètres

`dictionary`
  Une instance de PSpell\Dictionary.
`misspelled`

  Le mot mal orthographié.

`correct`

  La bonne orthographe du mot `misspelled`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `dictionary` attend désormais une instance de PSpell\Dictionary ; auparavant, une resource était expected.

### Exemples

Exemple #1 pspell_store_replacement()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);

    pspell_store_replacement($pspell, $misspelled, $correct);
    pspell_save_wordlist($pspell);
    ?>

### Notes

> Note:

> Cette fonction ne marchera qu'avec pspell .11.2 et aspell .32.5 ou ultérieurs.

# pspell_suggest

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_suggest — Suggère l'orthographe d'un mot

### Description

function pspell_suggest(PSpell\Dictionary `$dictionary`, string `$word`): array|false

pspell_suggest() retourne un tableau de suggestions pour le mot `word`.

### Liste de paramètres

`dictionary`
  Une instance de PSpell\Dictionary.
`word`

  Le mot testé.

### Valeurs de retour

Retourne un tableau de suggestions pour le mot `word`.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `dictionary` attend désormais une instance de PSpell\Dictionary ; auparavant, une resource était expected.

### Exemples

Exemple #1 Exemple avec pspell_suggest()

    <?php
    $pspell = pspell_new("en");

    if (!pspell_check($pspell, "testt")) {
        $suggestions = pspell_suggest($pspell, "testt");

        foreach ($suggestions as $suggestion) {
            echo "Orthographes suggérées : $suggestion<br />";
        }
    }
    ?>

## Sommaire

- pspell_add_to_personal — Ajoute le mot au dictionnaire personnel
- pspell_add_to_session — Ajoute le mot au dictionnaire personnel de la session courante
- pspell_check — Vérifie un mot
- pspell_clear_session — Remet à zéro la session courante
- pspell_config_create — Crée une configuration utilisée pour ouvrir un dictionnaire
- pspell_config_data_dir — Dossier qui contient les fichiers de données linguistiques
- pspell_config_dict_dir — Endroit où se trouve le fichier global des mots
- pspell_config_ignore — Ignore les mots de moins de N caractères
- pspell_config_mode — Change le mode de suggestion
- pspell_config_personal — Choisit le fichier qui contient le dictionnaire personnel
- pspell_config_repl — Choisit le fichier qui contient les paires de remplacement
- pspell_config_runtogether — Considère deux mots accolés comme un composé
- pspell_config_save_repl — Détermine s'il faut sauver les paires de remplacement avec le dictionnaire
- pspell_new — Charge un nouveau dictionnaire
- pspell_new_config — Charge un nouveau dictionnaire avec les paramètres spécifiés dans une configuration
- pspell_new_personal — Charge un nouveau dictionnaire avec un dictionnaire personnel
- pspell_save_wordlist — Sauve le dictionnaire personnel dans un fichier
- pspell_store_replacement — Enregistre une paire de remplacement pour un mot
- pspell_suggest — Suggère l'orthographe d'un mot

# La classe PSpell\Dictionary

(PHP 8 >= 8.1.0)

## Introduction

Une classe complètement opaque qui remplace la resource `pspell` à partir de PHP 8.1.0.

## Synopsis de la classe

final class PSpell\Dictionary {
}

# La classe PSpell\Config

(PHP 8 >= 8.1.0)

## Introduction

Une classe complètement opaque qui remplace la resource `pspell config` à partir de PHP 8.1.0.

## Synopsis de la classe

final class PSpell\Config {
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Types de ressources
- Constantes pré-définies
- Fonctions Pspell
  - pspell_add_to_personal — Ajoute le mot au dictionnaire personnel
  - pspell_add_to_session — Ajoute le mot au dictionnaire personnel de la session courante
  - pspell_check — Vérifie un mot
  - pspell_clear_session — Remet à zéro la session courante
  - pspell_config_create — Crée une configuration utilisée pour ouvrir un dictionnaire
  - pspell_config_data_dir — Dossier qui contient les fichiers de données linguistiques
  - pspell_config_dict_dir — Endroit où se trouve le fichier global des mots
  - pspell_config_ignore — Ignore les mots de moins de N caractères
  - pspell_config_mode — Change le mode de suggestion
  - pspell_config_personal — Choisit le fichier qui contient le dictionnaire personnel
  - pspell_config_repl — Choisit le fichier qui contient les paires de remplacement
  - pspell_config_runtogether — Considère deux mots accolés comme un composé
  - pspell_config_save_repl — Détermine s'il faut sauver les paires de remplacement avec le dictionnaire
  - pspell_new — Charge un nouveau dictionnaire
  - pspell_new_config — Charge un nouveau dictionnaire avec les paramètres spécifiés dans une configuration
  - pspell_new_personal — Charge un nouveau dictionnaire avec un dictionnaire personnel
  - pspell_save_wordlist — Sauve le dictionnaire personnel dans un fichier
  - pspell_store_replacement — Enregistre une paire de remplacement pour un mot
  - pspell_suggest — Suggère l'orthographe d'un mot
- PSpell\Dictionary — La classe PSpell\Dictionary
- PSpell\Config — La classe PSpell\Config

# GNU Recode

# Introduction

Avertissement

Cette extension est non maintenue.

Ce module contient une interface à la bibliothèque GNU Recode. La bibliothèque GNU Recode convertit les fichiers entre divers codages. Lorsque cette conversion n'a pu être effectuée de manière précise, des approximations sont effectuées. La bibliothèque reconnaît environ 150 jeux de caractères différents et est capable de convertir des fichiers en les utilisant. La plupart des jeux de caractères » RFC 1345 sont supportés.

> Note: Cette extension a été retirée et déplacée dans » PECL à partir de PHP 7.4.0. Considérez l'utilisation des extensions Chaînes Multioctets ou iconv à la place.

> Note: Cette extension n'est pas disponible sur les plates-formes Windows.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Il faut avoir GNU Recode 3.5 ou supérieur installé sur le système. Il est possible de télécharger le paquet depuis » http://directory.fsf.org/All_GNU_Packages/recode.html.

Avertissement

La version 3.6 de la bibliothèque Recode ajoute des caractères étranges à la suite des chaînes converties sous certaines circonstances. Aussi, il est préférable d'utiliser Recode v3.5 ou une bibliothèque alternative disponible, comme l'extension iconv ou l'extension mbstring.

## Installation

## PHP 7.4

Cette extension a été déplacée dans le module » PECL et ne sera plus intégrée dans PHP à partir de PHP 7.4.0

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/recode.

## PHP < 7.4

Pour utiliser les fonctions définies dans ce module PHP doit être compilé avec l'option --with-recode[=DIR].

Avertissement

Des crashs et des problèmes de démarrage de PHP peuvent être rencontrés lorsque l'extension recode est chargée après les extensions MySQL ou imap. Charger l'extension recode avant ces deux extensions corrige le problème. Ceci est dû à un problème technique car la bibliothèque c-client de IMAP et recode ont toutes les deux leur propre fonction `hash_lookup()` et les extensions mysql et recode ont toutes les deux leur fonction `hash_insert`.

Avertissement

Les extensions IMAP, recode et YAZ ne peuvent être utilisées simultanément puisqu'elles utilisent un symbole interne commun. Note: Yaz 2.0 et supérieur ne souffre plus de ce problème.

# Fonctions Recode

# recode

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode — Alias de recode_string()

### Description

Cette fonction est un alias de : recode_string().

# recode_file

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_file — Recodage de fichier à fichier, en fonction de la demande

### Description

function recode_file(string `$request`, resource `$input`, resource `$output`): bool

Recode le fichier identifié par `input` dans le fichier identifié par `output` en fonction de la requête de recodage `request`.

### Liste de paramètres

`request`
  Le type de requête recode désiré
`input`
  Un gestionnaire de fichier local pour le paramètre `input`
`output`
  Un gestionnaire de fichier local pour le paramètre `output`

### Valeurs de retour

Retourne `false`, en cas d'échec, et `true` sinon.

### Exemples

Exemple #1 Exemple avec recode_file()

    <?php
    $input = fopen('input.txt', 'r');
    $output = fopen('output.txt', 'w');
    recode_file("us..flat", $input, $output);
    ?>

### Notes

Cette fonction ne gère pas encore les fichiers distants (URL). Les deux fichiers doivent faire référence à des fichiers locaux.

### Voir aussi

- fopen() - Ouvre un fichier ou une URL

# recode_string

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_string — Recode une chaîne en fonction de la requête

### Description

function recode_string(string `$request`, string `$string`): string

Recode la chaîne `string` en fonction de la requête `request`.

### Liste de paramètres

`request`
  Le type de requête recode désiré
`string`
  La chaîne de caractères à recoder

### Valeurs de retour

Retourne la chaîne recodée en cas de succès et `false` sinon.

### Exemples

Exemple #1 Exemple avec recode_string()

    <?php
    echo recode_string("us..flat", "Le caractère suivant est diacritique : á");
    ?>

### Notes

Une requête simple de recodage peut être "lat1..iso646-de".

### Voir aussi

- Se reporter à la documentation GNU Recode de l'installation pour plus de détails sur les requêtes.
- mb_convert_encoding() - Convertir une chaîne d'un codage de caractères à un autre
- UConverter::transcode() - Convertit une chaîne d'un jeu de caractères à un autre
- iconv() - Convertit une chaîne de caractères à partir d'un encodage vers un autre

## Sommaire

- recode — Alias de recode_string
- recode_file — Recodage de fichier à fichier, en fonction de la demande
- recode_string — Recode une chaîne en fonction de la requête

- Installation/Configuration
  - Pré-requis
  - Installation
- Fonctions Recode
  - recode — Alias de recode_string
  - recode_file — Recodage de fichier à fichier, en fonction de la demande
  - recode_string — Recode une chaîne en fonction de la requête

- Enchant — Bibliothèque d'orthographe Enchant
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions Enchant
  - EnchantBroker — La classe EnchantBroker
  - EnchantDictionary — La classe EnchantDictionary
- Gender — Détermine le sexe d'un prénom
  - Installation/Configuration
  - Exemples
  - Gender\Gender — La classe Gender\Gender
- Gettext
  - Installation/Configuration
  - Fonctions Gettext
- iconv
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions iconv
- intl — Fonctions d'internationalisation
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Collator — La classe Collator
  - NumberFormatter — La classe NumberFormatter
  - Locale — La classe Locale
  - Normalizer — La classe Normalizer
  - MessageFormatter — La classe MessageFormatter
  - IntlCalendar — La classe IntlCalendar
  - IntlGregorianCalendar — La classe IntlGregorianCalendar
  - IntlTimeZone — La classe IntlTimeZone
  - IntlDateFormatter — La classe IntlDateFormatter
  - ResourceBundle — La classe ResourceBundle
  - Spoofchecker — La classe Spoofchecker
  - Transliterator — La classe Transliterator
  - IntlBreakIterator — La classe IntlBreakIterator
  - IntlRuleBasedBreakIterator — La classe IntlRuleBasedBreakIterator
  - IntlCodePointBreakIterator — La classe IntlCodePointBreakIterator
  - IntlDatePatternGenerator — La classe IntlDatePatternGenerator
  - IntlPartsIterator — La classe IntlPartsIterator
  - UConverter — La classe UConverter
  - Fonctions Grapheme
  - Fonctions IDN
  - IntlChar
  - IntlException — La classe d'exception pour les erreurs intl
  - IntlIterator — La classe IntlIterator
  - Fonctions intl
- Chaînes de caractères multioctets
  - Installation/Configuration
  - Constantes pré-définies
  - Jeux de caractères supportés
  - Cas des caractères japonais
  - Entrées/Sorties HTTP
  - Jeux de caractères supportés
  - Fonctionnalité de surcharge de fonctions
  - Prérequis de l'encodage en PHP
  - Fonctions sur les chaînes de caractères multioctets
- Pspell
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Pspell
  - PSpell\Dictionary — La classe PSpell\Dictionary
  - PSpell\Config — La classe PSpell\Config
- Recode — GNU Recode
  - Installation/Configuration
  - Fonctions Recode

# Génération et traitement des images

# Informations Exif

# Introduction

Avec l'extension exif, il est possible de travailler sur les métadonnées des images. Par exemple, il est possible d'utiliser les fonctions exif pour lire les métadonnées des images prises par des appareils numériques, stockées dans les en-têtes. Elles sont communément présentes dans les images JPEG et TIFF.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

Le PHP doit être compilé avec l'option `--enable-exif`. Pour activer le support des tags EXIF multibyte, l'extension mbstring doit être activée lors de la compilation avec `--enable-mbstring`. PHP n'a besoin d'aucune bibliothèque additionnelle pour faire fonctionner le module exif.

## Installation

Pour activer le support EXIF en PHP, il suffit d'ajouter l'option de compilation --enable-exif.

Les utilisateurs Windows doivent s'assurer que les bibliothèques DLL php_mbstring.dll et php_exif.dll sont spécifiées dans le fichier php.ini. La bibliothèque php_mbstring.dll doit être chargée avant la bibliothèque php_exif.dll : il convient d'ajuster le php.ini.

## Configuration à l'exécution

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

EXIF supporte automatiquement la conversion pour les encodages Unicode et JIS des commentaires utilisateurs, lorsque le module mbstring est compilé avec PHP. Cela se fait en décodant le commentaire avec le jeu de caractères spécifié. Le résultat est ensuite codé avec un autre jeu de caractères, compatible avec la sortie `HTTP`.

Options de configuration Exif
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
exif.encode_unicode | "ISO-8859-15" | `INI_ALL` |
exif.decode_unicode_motorola | "UCS-2BE" | `INI_ALL` |
exif.decode_unicode_intel | "UCS-2LE" | `INI_ALL` |
exif.encode_jis | "" | `INI_ALL` |
exif.decode_jis_motorola | "JIS" | `INI_ALL` |
exif.decode_jis_intel | "JIS" | `INI_ALL` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`exif.encode_unicode` string
  `exif.encode_unicode` définit la méthode de gestion des commentaires écrits en Unicode. La valeur par défaut est `ISO-8859-15`, qui devrait fonctionner pour la plupart des pays non-asiatiques. Cette directive peut être laissée vide, ou prendre un des jeux de caractères supporté par mbstring. Si elle est vide, le jeu de caractères interne de mbstring sera utilisé.
`exif.decode_unicode_motorola` string
  `exif.decode_unicode_motorola` définit le jeu de caractères de remplacement pour les commentaires utilisateurs écrits en Unicode, si l'ordre des bits est celui de Motorola (big-endian). Cette directive ne peut être laissée vide, et doit être un des jeux de caractères supportés par l'extension mbstring. La valeur par défaut est `UCS-2BE`.
`exif.decode_unicode_intel` string
  `exif.decode_unicode_intel` définit le jeu de caractères de remplacement pour les commentaires utilisateurs écrits en Unicode, si l'ordre des bits est celui d'Intel (little-endian). Cette directive ne peut être laissée vide, et doit être un des jeux de caractères supportés par l'extension mbstring. La valeur par défaut est `UCS-2LE`.
`exif.encode_jis` string
  `exif.encode_jis` définit la méthode de gestion des commentaires écrits en caractères JIS. La valeur par défaut est une chaîne vide, qui fait que le jeu de caractères interne de mbstring est utilisé.
`exif.decode_jis_motorola` string
  `exif.decode_jis_motorola` définit le jeu de caractères de remplacement pour les commentaires utilisateurs écrits en JIS, si l'ordre des bits est celui de Motorola (big-endian). Cette directive ne peut être laissée vide, et doit être un des jeux de caractères supportés par l'extension mbstring. La valeur par défaut est `JIS`.
`exif.decode_jis_intel` string
  `exif.decode_jis_intel` définit le jeu de caractères de remplacement pour les commentaires utilisateurs écrits en JIS, si l'ordre des bits est celui d'Intel (little-endian). Cette directive ne peut être laissée vide, et doit être un des jeux de caractères supportés par l'extension mbstring. La valeur par défaut est `JIS`.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`EXIF_USE_MBSTRING` (int)
  Cette constante a la valeur `1` si mbstring est activé, sinon sa valeur est `0`.

La fonction exif_imagetype() liste plusieurs constantes intégrées connexes.

# Fonctions Exif

# exif_imagetype

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

exif_imagetype — Détermine le type d'une image

### Description

function exif_imagetype(string `$filename`): int|false

exif_imagetype() lit les premiers octets du fichier d'image `filename`, et vérifie sa signature.

exif_imagetype() peut être utilisée pour éviter les appels aux autres fonctions exif pour les formats de fichiers qui ne sont pas supportés, ou en conjonction avec $_SERVER['HTTP_ACCEPT'] pour vérifier si l'utilisateur pourra voir cette image dans son navigateur.

### Liste de paramètres

`filename`
  L'image à vérifier.

### Valeurs de retour

Lorsqu'une valeur valide est trouvée, la constante appropriée est retournée, et sinon, `false`. La valeur retournée est la même que la fonction getimagesize() à l'index 2, mais cette fonction est bien plus rapide.

Les constantes suivantes sont définies et représentent les valeurs possibles de retour de la fonction exif_imagetype() :

Constantes de type d'images
Valeur | Constante
--- | ---
1 | `IMAGETYPE_GIF`
2 | `IMAGETYPE_JPEG`
3 | `IMAGETYPE_PNG`
4 | `IMAGETYPE_SWF`
5 | `IMAGETYPE_PSD`
6 | `IMAGETYPE_BMP`
7 | `IMAGETYPE_TIFF_II` (ordre d'octets d'Intel)
8 | `IMAGETYPE_TIFF_MM` (ordre d'octets Motorola)
9 | `IMAGETYPE_JPC`
10 | `IMAGETYPE_JP2`
11 | `IMAGETYPE_JPX`
12 | `IMAGETYPE_JB2`
13 | `IMAGETYPE_SWC`
14 | `IMAGETYPE_IFF`
15 | `IMAGETYPE_WBMP`
16 | `IMAGETYPE_XBM`
17 | `IMAGETYPE_ICO`
18 | `IMAGETYPE_WEBP`
19 | `IMAGETYPE_AVIF`
20 | `IMAGETYPE_HEIF`

> Note: La fonction exif_imagetype() émet une alerte de niveau `E_NOTICE` et retourne `false` si elle n'est pas capable de lire assez d'octets depuis le fichier pour y déterminer le type d'image.

### Historique

Version | Description
--- | ---
7.1.0 | Ajout de la prise en charge de WebP.
8.1.0 | Ajout de la prise en charge de AVIF.
8.5.0 | Ajout de la prise en charge de HEIF.

### Exemples

Exemple #1 Exemple avec exif_imagetype()

    <?php
    if (exif_imagetype('image.gif') != IMAGETYPE_GIF) {
        echo 'Cette image n\'est pas un gif';
    }
    ?>

### Voir aussi

- image_type_to_mime_type() - Lit le Mime-Type d'un type d'image
- getimagesize() - Retourne la taille d'une image

# exif_read_data

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_read_data — Lit les en-têtes EXIF dans les images

### Description

function exif_read_data(
resource|string `$file`,
?string `$required_sections` = `null`,
bool `$as_arrays` = `false`,
bool `$read_thumbnail` = `false`
): array|false

exif_read_data() lit les en-têtes EXIF des images. Avec cette fonction, il est possible de lire les métadonnées générées par les appareils photos numériques.

Les en-têtes EXIF tendent à être présents dans les images JPEG/TIFF générées par les appareils photos numériques, mais malheureusement, chaque fabricant d'appareil photo numérique a une idée différente de la façon dont leurs images doivent être marquées, donc, il n'est pas possible de toujours compter sur un en-tête EXIF spécifique, bien que présent.

Les paramètres `Height` et `Width` sont calculés de la même façon que pour la fonction getimagesize(), donc leurs valeurs ne feront partie d'aucun en-tête retourné. De même, l'index `html` est la représentation textuelle de la hauteur/largeur utilisée dans une balise image HTML classique.

Lorsqu'un en-tête EXIF contient une note de Copyright, cette note peut elle-même contenir deux valeurs. Comme cette solution est incohérente avec les standards EXIF 2.10, la section `COMPUTED` retournera les deux en-têtes, `Copyright.Photographer` et `Copyright.Editor`, tandis que les sections `IFD0` contiennent le tableau d'octets avec le caractère NULL séparant les deux entrées ; ou bien, juste la première entrée si le type de données était erroné (comportement par défaut d'EXIF). La section `COMPUTED` va aussi contenir une entrée `Copyright`, qui sera soit la chaîne originale de copyright, soit une liste séparée par des virgules du copyright du photographe et de l'éditeur.

La balise `UserComment` présente le même problème que la balise Copyright. Elle peut stocker deux valeurs : en premier, le jeu de caractères utilisé, puis la valeur elle-même. Si c'est le cas, la section `IFD` contiendra uniquement le jeu de caractères, ou bien un tableau d'octets. La section `COMPUTED` va stocker les deux entrées `UserCommentEncoding` et `UserComment`. L'index `UserComment` est disponible dans les deux cas, et il est préférable de l'utiliser, plutôt que la valeur de la section `IFD0`.

exif_read_data() valide les données des balises EXIF en accord avec la spécification EXIF (» http://exif.org/Exif2-2.PDF, page 20).

### Liste de paramètres

`file`
  L'emplacement du fichier image. Il peut s'agir soit d'un chemin d'accès au fichier (les enveloppes de flux sont également supportées comme d'habitude), soit d'un flux resource.
`required_sections`

  Liste séparée par des virgules de sections devant être présentes dans le fichier pour produire un tableau de résultat. Si aucune des sections demandées n'est trouvée, la valeur retournée est `false`.

  FILE | FileName (nom du fichier), FileSize (taille du fichier), FileDateTime (date de modification du fichier), SectionsFound (sections trouvées)
  COMPUTED | Attribut HTML, largeur, hauteur, couleur ou noir et blanc et plus si disponible. La largeur et la hauteur sont calculées de la même façon que la fonction getimagesize(), donc leurs valeurs ne doivent faire partie d'aucun en-tête retourné. De même, l'index `html` est la représentation textuelle de la hauteur/largeur utilisée dans une balise image HTML classique.
  ANY_TAG | Toute information ayant un Tag, comme `IFD0`, `EXIF`, ...
  IFD0 | Toutes les balises `IFD0`. Dans les images normales, elles contiennent les dimensions de l'image, etc.
  THUMBNAIL | Un fichier qui contient une miniature, s'il y a un second `IFD`. Toutes les informations mises en balises à propos de cette miniature seront stockées dans cette section.
  COMMENT | En-tête de commentaire des images JPEG.
  EXIF | La section EXIF est une sous section de la section `IFD0`. Elle contient des informations plus détaillées sur les images. La plupart de ces index sont reliés aux appareils numériques.

`as_arrays`
  Spécifie si chaque section doit devenir un tableau ou non. Les `required_sections` `COMPUTED`, `THUMBNAIL` et `COMMENT` seront toujours transformées en tableau, car elles contiennent des noms qui risquent d'être en conflit.
`read_thumbnail`
  Lorsque défini à `true`, la miniature elle-même est lue. Sinon, seules les données contenues dans le tag seront lues.

### Valeurs de retour

Retourne un tableau associatif où les index sont les noms des en-têtes et les valeurs sont les valeurs associées à ces en-têtes. Si aucune donnée ne peut être retournée, exif_read_data() retournera `false`.

### Erreurs / Exceptions

Des erreurs de niveau `E_WARNING` et/ou `E_NOTICE` peuvent être levées pour des tags non supportés ou autres conditions d'erreur potentielle, mais la fonction tente quand même de lire toutes les informations compréhensibles.

### Historique

Version | Description
--- | ---
8.0.0 | `required_sections` est désormais nullable.
7.2.0 | Le paramètre `file` supporte désormais les fichiers locaux et les flux de ressources.
7.2.0 | Le support des formats EXIF suivants a été ajouté : Samsung DJI Panasonic Sony Pentax Minolta Sigma/Foveon AGFA Kyocera Ricoh Epson

### Exemples

Exemple #1 Exemple avec exif_read_data()

    <?php
    echo "test1.jpg:<br />\n";
    $exif = exif_read_data('tests/test1.jpg', 'IFD0');
    echo $exif===false ? "Aucun en-tête de données n'a été trouvé.<br />\n" : "L'image contient des en-têtes<br />\n";

    $exif = exif_read_data('tests/test2.jpg', 0, true);
    echo "test2.jpg:<br />\n";
    foreach ($exif as $key => $section) {
        foreach ($section as $name => $val) {
            echo "$key.$name: $val<br />\n";
        }
    }
    ?>

Le premier appel échoue car l'image n'a pas d'en-tête d'information.

Résultat de l'exemple ci-dessus est similaire à :

    test1.jpg:
    Aucun en-tête de données n'a été trouvé.
    test2.jpg:
    FILE.FileName: test2.jpg
    FILE.FileDateTime: 1017666176
    FILE.FileSize: 1240
    FILE.FileType: 2
    FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT
    COMPUTED.html: width="1" height="1"
    COMPUTED.Height: 1
    COMPUTED.Width: 1
    COMPUTED.IsColor: 1
    COMPUTED.ByteOrderMotorola: 1
    COMPUTED.UserComment: Exif test image.
    COMPUTED.UserCommentEncoding: ASCII
    COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger.
    COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
    COMPUTED.Copyright.Editor: Edited by M.Boerger.
    IFD0.Copyright: Photo (c) M.Boerger
    IFD0.UserComment: ASCII
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.JPEGInterchangeFormatLength: 523
    COMMENT.0: Comment #1.
    COMMENT.1: Comment #2.
    COMMENT.2: Comment #3end
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.Thumbnail.Height: 1
    THUMBNAIL.Thumbnail.Height: 1

Exemple #2 exif_read_data() avec les flux disponibles à partir de PHP 7.2.0

    <?php
    // Ouvrir le fichier, cela devrait être en mode binaire
    $fp = fopen('/path/to/image.jpg', 'rb');

    if (!$fp) {
        echo 'Erreur : Impossible d\'ouvrir l\'image en lecture';
        exit;
    }

    // Essayez de lire les en-têtes EXIF
    $headers = exif_read_data($fp);

    if (!$headers) {
        echo 'Erreur : Impossible de lire les en-têtes EXIF';
        exit;
    }

    // Afficher les en-têtes 'COMPUTED'
    echo 'En-têtes EXIF :' . PHP_EOL;

    foreach ($headers['COMPUTED'] as $header => $value) {
        printf(' %s => %s%s', $header, $value, PHP_EOL);
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    En-têtes EXIF :
     Height => 576
     Width => 1024
     IsColor => 1
     ByteOrderMotorola => 0
     ApertureFNumber => f/5.6
     UserComment =>
     UserCommentEncoding => UNDEFINED
     Copyright => Denis
     Thumbnail.FileType => 2
     Thumbnail.MimeType => image/jpeg

### Notes

> Note: Si mbstring est activé, EXIF va tenter de traiter l'Unicode et de choisir un jeu de caractères comme spécifié par exif.decode_unicode_motorola et exif.decode_unicode_intel. L'extension EXIF ne tentera pas de déterminer l'encodage d'elle-même, et il appartient à l'utilisateur de spécifier correctement l'encodage à utiliser pour le décodage en définissant l'une des deux directives INI avant d'appeler exif_read_data().

> Note: Si le paramètre `file` est utilisé pour passer un flux à la fonction, alors le flux doit être repositionnable. Il est à noter que la position du pointeur d'un fichier n'est pas modifiée après le retour de cette fonction.

### Voir aussi

- exif_thumbnail() - Récupère la miniature embarquée d'une image
- getimagesize() - Retourne la taille d'une image
- Liste des protocoles et des gestionnaires supportés

# exif_tagname

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_tagname — Récupère le nom d'en-tête EXIF d'un index

### Description

function exif_tagname(int `$index`): string|false

### Liste de paramètres

`index`
  L'id de Tag pour lequel un nom sera recherché.

### Valeurs de retour

exif_tagname() retourne `false` si `index` n'est pas un id de tag EXIF défini, sinon elle retourne le nom de l'en-tête.

### Exemples

Exemple #1 Exemple pour exif_tagname()

    <?php
    echo "256: ".exif_tagname(256).PHP_EOL;
    echo "257: ".exif_tagname(257).PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    256: ImageWidth
    257: ImageLength

### Voir aussi

- exif_imagetype() - Détermine le type d'une image
- » EXIF Specification
- » EXIF Tags

# exif_thumbnail

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_thumbnail — Récupère la miniature embarquée d'une image

### Description

function exif_thumbnail(
resource|string `$file`,
int `&$width` = `null`,
int `&$height` = `null`,
int `&$image_type` = `null`
): string|false

exif_thumbnail() lit la miniature de l'image.

Pour afficher des miniatures avec cette fonction, il est recommandé d'envoyer le bon type MIME avec la fonction header().

Il est possible que la fonction exif_thumbnail() n'arrive pas à créer l'image mais peut déterminer sa taille. Dans ce cas, la fonction retourne `false` mais les paramètres `width` et `height` sont définis.

### Liste de paramètres

`file`
  Localisation du fichier image. Il peut s'agir soit d'un chemin d'accès au fichier, soit d'un flux resource.
`width`
  La largeur de la miniature retournée.
`height`
  La hauteur de la miniature retournée.
`image_type`
  Le type de l'image de la miniature retournée. Peut être soit TIFF, soit JPEG.

### Valeurs de retour

Retourne la miniature embarquée ou `false` si l'image ne contient pas de miniature.

### Historique

Version | Description
--- | ---
7.2.0 | Le paramètre `file` supporte les fichiers locaux ou les ressources de flux.

### Exemples

Exemple #1 Exemple avec exif_thumbnail()

    <?php
    if (array_key_exists('file', $_REQUEST)) {
        $image = exif_thumbnail($_REQUEST['file'], $width, $height, $type);
    } else {
        $image = false;
    }
    if ($image!==false) {
        header('Content-type: ' .image_type_to_mime_type($type));
        echo $image;
        exit;
    } else {
        // aucune miniature de disponible, traitement de l'erreur ici
        echo 'No thumbnail available';
    }
    ?>

### Notes

> Note: Si le paramètre `file` est utilisé pour passer un flux à la fonction, alors le flux doit être repositionnable. Il est à noter que la position du pointeur d'un fichier n'est pas modifiée après le retour de cette fonction.

### Voir aussi

- exif_read_data() - Lit les en-têtes EXIF dans les images
- image_type_to_mime_type() - Lit le Mime-Type d'un type d'image

# read_exif_data

(PHP 4 >= 4.0.1, PHP 5, PHP 7)

read_exif_data — Alias de exif_read_data()

Avertissement

Cet alias est OBSOLÈTE en PHP 7.2.0, et SUPPRIMÉ à partir de PHP 8.0.0.

### Description

Cette fonction est un alias de : exif_read_data().

### Historique

Version | Description
--- | ---
7.2.0 | Cet alias de fonction a été déprécié.

## Sommaire

- exif_imagetype — Détermine le type d'une image
- exif_read_data — Lit les en-têtes EXIF dans les images
- exif_tagname — Récupère le nom d'en-tête EXIF d'un index
- exif_thumbnail — Récupère la miniature embarquée d'une image
- read_exif_data — Alias de exif_read_data

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Fonctions Exif
  - exif_imagetype — Détermine le type d'une image
  - exif_read_data — Lit les en-têtes EXIF dans les images
  - exif_tagname — Récupère le nom d'en-tête EXIF d'un index
  - exif_thumbnail — Récupère la miniature embarquée d'une image
  - read_exif_data — Alias de exif_read_data

# Traitement des images et GD

# Introduction

PHP ne se limite pas à la génération de pages HTML. Il peut aussi servir à créer et manipuler des images, dans un grand choix de formats, comme GIF, PNG, JPEG, WBMP et XPM. Et PHP peut même générer directement des images pour le navigateur, avec la bibliothèque GD. GD et PHP auront aussi besoin d'autres bibliothèques, en fonction des formats à utiliser.

Il est possible d'utiliser les fonctions PHP pour obtenir les tailles des images aux formats JPEG, GIF, PNG, SWF, TIFF et JPEG2000.

Avec l'extension exif, il sera possible de travailler avec les informations stockées dans les en-têtes des images JPEG et TIFF. De cette façon, il sera possible de lire les métadonnées générées par les appareils numériques. Les fonctions exif ne nécessitent pas la bibliothèque GD.

> Note: Se reporter à la section sur les besoins pour savoir comment étendre les capacités des fonctions sur les images pour lire, écrire et modifier les images. Pour lire les métadonnées des photos prises avec des appareils numériques, il faut utiliser l'extension exif mentionnée ci-dessus.

> Note: La fonction getimagesize() ne nécessite pas l'extension GD.

Attention

Tandis que la version empaquetée de la bibliothèque GD utilise le gestionnaire de mémoire Zend pour allouer de la mémoire, les versions système ne le font pas, donc memory_limit ne s'applique pas.

GD supporte un grand nombre de formats ; voici une liste de formats supportés par GD ainsi que des notes spécifiant la disponibilité du support en lecture/écriture.

Formats supportés par GD
Format | Support en lecture | Support en écriture | Notes
--- | --- | --- | ---
JPEG | `true` | `true` |
PNG | `true` | `true` |
GIF | `true` | `true` |
XBM | `true` | `true` |
XPM | `true` | `false` |
WBMP | `true` | `true` |
WebP | `true` | `true` |
BMP | `true` | `true` | Disponible à partir de PHP 7.2.0

Malgré le fait que la plupart des formats soient disponibles avec un support en lecture et en écriture dans le tableau ci-dessus, cela ne signifie pas que PHP a été compilé avec le support adéquat. Pour connaître les formats supportés par GD durant la compilation, il est possible d'utiliser la fonction gd_info() ; pour plus d'informations sur le support lors de la compilation d'un ou plusieurs formats, se reporter au chapitre sur l'installation.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

En disposant de la bibliothèque GD (disponible à » http://www.libgd.org/) il sera possible d'aussi créer et manipuler des images.

Les formats des images qu'il sera possible de manipuler dépendent de la version de GD que l'on installera, et de toutes autres bibliothèques dont GD a besoin pour traiter ces images.

> Note: libgd-2.1.0 ou supérieur est requis. Alternativement, utiliser la bibliothèque GD fournie avec PHP.

> Note: La bibliothèque GD requiert zlib >= 1.2.0.4.

Il est aussi possible d'améliorer GD en lui ajoutant des formats d'images supplémentaires.

Formats d'images supportés
Format d'image | Bibliothèque à télécharger | Notes
--- | --- | ---
`gif` |  |
`avif` |  |
`jpeg` | » http://www.ijg.org/ | Lors de la compilation de la bibliothèque jpeg (avant celle de PHP), il faut utiliser l'option de configuration --enable-shared. Dans le cas contraire, une erreur sera affichée disant que `libjpeg.(a|so) not found` lorsqu'on tentera de configurer PHP avant de compiler.
`png` | » http://www.libpng.org/pub/png/libpng.html |
`xpm` | » http://www.ibiblio.org/pub/Linux/libs/X/!INDEX.html | Il est probable que l'on ait déjà cette bibliothèque disponible si le système dispose d'un environnement X.
`webp` |  |

Il est possible de vouloir étendre GD pour traiter différentes polices de caractères. La bibliothèque » FreeType 2 est supportée.

## Installation

Pour activer le support de GD, il faut compiler PHP avec l'option --with-gd[=DIR], où DIR est le dossier d'installation de GD. Il est recommandé d'utiliser la version de GD qui est distribuée avec PHP, en utilisant simplement l'option --with-gd. La bibliothèque GD requiert libpng et libjpeg pour compiler. À partir de PHP 7.4.0, --with-gd devient --enable-gd (pour activer ou non l'extension) et --with-external-gd (pour choisir d'utiliser une libgd externe, plutôt que celle fournie).

Sous Windows, il faut inclure la bibliothèque php_gd.dll comme extension dans le fichier php.ini. Avant PHP 8.0.0, la DLL était nommée php_gd2.dll.

Pour étendre les possibilités de GD à gérer d'autres formats d'images, il est possible de spécifier les options `--with-XXXX` de compilation suivantes :

Formats d'image supportés
Format d'image | Option de compilation
--- | ---
`avif` | Pour activer le support de la bibliothèque avif, ajouter l'option --with-avif. Disponible à partir de PHP 8.1.0.
`jpeg` | Pour activer le support de la bibliothèque JPEG, ajouter l'option --with-jpeg-dir=DIR. Jpeg 6b, 7 ou 8 sont supportés. À partir de PHP 7.4.0, utiliser à la place --with-jpeg
`png` | Pour activer le support de la bibliothèque PNG, ajouter l'option --with-png-dir=DIR. Il est à noter que libpng requiert la bibliothèque zlib et, donc, il faudra ajouter aussi --with-zlib-dir[=DIR] dans la ligne de compilation. À partir de PHP 7.4.0, --with-png-dir et --with-zlib-dir ont été supprimées. libpng et zlib sont nécessaires.
`xpm` | Pour activer le support de la bibliothèque XPM, ajouter l'option --with-xpm-dir=DIR. Si le script de compilation n'est pas capable de trouver les bibliothèques nécessaires, il faudra ajouter le chemin vers les bibliothèques X11. À partir de PHP 7.4.0, utiliser à la place --with-xpm
`webp` | Pour activer le support de WebP, ajouter --with-webp-dir=DIR. À partir de PHP 7.4.0, utiliser à la place --with-webp

> Note: Lorsqu'on compile PHP avec libpng, il faut utiliser la même version que celle liée à la bibliothèque GD.

Pour étendre les possibilités de GD à manipuler différents types de polices de caractères, il est possible d'ajouter les options `--with-XXXX` de compilation suivantes :

Bibliothèques des polices de caractères supportées
Bibliothèque | Option de configuration
--- | ---
`FreeType 2` | Pour activer le support de FreeType 2, ajouter l'option --with-freetype-dir=DIR. À partir de PHP 7.4.0 utiliser --with-freetype à la place, qui dépend de pkg-config.
`Chaînes TrueType` | Pour activer le support des chaînes de caractères TrueType, ajouter l'option --enable-gd-native-ttf. (Cette option n'a aucun effet et a été supprimée à partir de PHP 7.2.0.)

## Configuration à l'exécution

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

Options de configuration image
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
gd.jpeg_ignore_warning | "1" | `INI_ALL` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`gd.jpeg_ignore_warning` bool

  Ignore les alertes (mais pas les erreurs) créées par libjpeg(-turbo).

Historique pour `gd.jpeg_ignore_warning`
Version | Description
--- | ---
7.1.0 | La valeur par défaut de gd.jpeg_ignore_warning a été changée de 0 à 1.

Voir aussi les directives de configuration exif.

Avertissement

Les fonctions sur les images sont très gourmandes en termes de mémoire. Il faut s'assurer de définir une valeur assez importante pour memory_limit si l'on utilise la bibliothèque GD intégrée.

## Types de ressources

Cette extension définit les types de ressources suivantes :

Liste des ressources dans GD
Nom | Description | Notes
--- | --- | ---
`gd` | Ressource Image, utilisée par des fonctions comme imagecreatefrompng() | Antérieur à PHP 8.0.0
`gd font` | Ressource Police créée en interne par imageloadfont() | Antérieur à PHP 8.1.0

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`GD_VERSION` (string)
  La version GD de PHP.
`GD_MAJOR_VERSION` (int)
  La version majeure GD de PHP.
`GD_MINOR_VERSION` (int)
  La version mineure GD de PHP.
`GD_RELEASE_VERSION` (int)
  La version GD fournie avec PHP.
`GD_EXTRA_VERSION` (string)
  La version "extra" GD (beta/rc..) de PHP.
`GD_BUNDLED` (int)
  Lorsque la version interne de GD est utilisée, cette constante vaut 1, sinon, elle vaut 0.
`IMG_AVIF` (int)
  Utilisée comme valeur retournée par la fonction imagetypes() (Disponible à partir de PHP 8.1.0)
`IMG_BMP` (int)
  Utilisée comme valeur retournée par la fonction imagetypes()
`IMG_GIF` (int)
  Utilisée comme valeur retournée par la fonction imagetypes()
`IMG_JPG` (int)
  Utilisée comme valeur retournée par la fonction imagetypes()
`IMG_JPEG` (int)
  Utilisée comme valeur retournée par la fonction imagetypes()

  > Note:

  > Cette constante a la même valeur que `IMG_JPG`

`IMG_PNG` (int)
  Utilisée comme valeur retournée par la fonction imagetypes()
`IMG_TGA` (int)
  Utilisée comme valeur retournée par la fonction imagetypes() (Disponible à partir de PHP 7.4.0)
`IMG_WBMP` (int)
  Utilisée comme valeur retournée par la fonction imagetypes()
`IMG_XPM` (int)
  Utilisée comme valeur retournée par la fonction imagetypes()
`IMG_WEBP` (int)
  Utilisée comme valeur retournée par la fonction imagetypes() (Disponible à partir de PHP 7.0.10)
`IMG_WEBP_LOSSLESS` (int)
  (Disponible à partir de PHP 8.1.0)
`IMG_COLOR_TILED` (int)
  Option spéciale de couleur qui peut être utilisée à la place d'une couleur allouée avec la fonction imagecolorallocate() ou la fonction imagecolorallocatealpha().
`IMG_COLOR_STYLED` (int)
  Option spéciale de couleur qui peut être utilisée à la place d'une couleur allouée avec la fonction imagecolorallocate() ou la fonction imagecolorallocatealpha().
`IMG_COLOR_BRUSHED` (int)
  Option spéciale de couleur qui peut être utilisée à la place d'une couleur allouée avec la fonction imagecolorallocate() ou la fonction imagecolorallocatealpha().
`IMG_COLOR_STYLEDBRUSHED` (int)
  Option spéciale de couleur qui peut être utilisée à la place d'une couleur allouée avec la fonction imagecolorallocate() ou la fonction imagecolorallocatealpha().
`IMG_COLOR_TRANSPARENT` (int)
  Option spéciale de couleur qui peut être utilisée à la place d'une couleur allouée avec la fonction imagecolorallocate() ou la fonction imagecolorallocatealpha().
`IMG_AFFINE_TRANSLATE` (int)
  Un type de constante de transformation affinée utilisé par la fonction imageaffinematrixget().
`IMG_AFFINE_SCALE` (int)
  Un type de constante de transformation affinée utilisé par la fonction imageaffinematrixget().
`IMG_AFFINE_ROTATE` (int)
  Un type de constante de transformation affinée utilisé par la fonction imageaffinematrixget().
`IMG_AFFINE_SHEAR_HORIZONTAL` (int)
  Un type de constante de transformation affinée utilisé par la fonction imageaffinematrixget().
`IMG_AFFINE_SHEAR_VERTICAL` (int)
  Un type de constante de transformation affinée utilisé par la fonction imageaffinematrixget().
`IMG_ARC_ROUNDED` (int)
  Une constante de style utilisée par la fonction imagefilledarc().

  > Note:

  > Cette constante a la même valeur que `IMG_ARC_PIE`

`IMG_ARC_PIE` (int)
  Une constante de style utilisée par la fonction imagefilledarc().
`IMG_ARC_CHORD` (int)
  Une constante de style utilisée par la fonction imagefilledarc().
`IMG_ARC_NOFILL` (int)
  Une constante de style utilisée par la fonction imagefilledarc().
`IMG_ARC_EDGED` (int)
  Une constante de style utilisée par la fonction imagefilledarc().
`IMG_GD2_RAW` (int)
  Un type de constante utilisé par la fonction imagegd2().
`IMG_GD2_COMPRESSED` (int)
  Un type de constante utilisé par la fonction imagegd2().
`IMG_EFFECT_REPLACE` (int)
  Un effet d'alpha blending utilisé par la fonction imagelayereffect().
`IMG_EFFECT_ALPHABLEND` (int)
  Un effet d'alpha blending utilisé par la fonction imagelayereffect().
`IMG_EFFECT_NORMAL` (int)
  Un effet d'alpha blending utilisé par la fonction imagelayereffect().
`IMG_EFFECT_OVERLAY` (int)
  Un effet d'alpha blending utilisé par la fonction imagelayereffect().
`IMG_EFFECT_MULTIPLY` (int)
  Un effet d'alpha blending utilisé par la fonction imagelayereffect().
`IMG_FILTER_NEGATE` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_GRAYSCALE` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_BRIGHTNESS` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_CONTRAST` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_COLORIZE` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_EDGEDETECT` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_GAUSSIAN_BLUR` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_SELECTIVE_BLUR` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_EMBOSS` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_MEAN_REMOVAL` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_SMOOTH` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_PIXELATE` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter().
`IMG_FILTER_SCATTER` (int)
  Un filtre spécial GD utilisé par la fonction imagefilter(). (Disponible à partir de PHP 7.4.0)
`IMAGETYPE_GIF` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_JPEG` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_JPEG2000` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_PNG` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_SWF` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_PSD` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_BMP` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_WBMP` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_XBM` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_TIFF_II` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_TIFF_MM` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_IFF` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_JB2` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_JPC` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_JP2` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_JPX` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_SWC` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_ICO` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_WEBP` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension(). (Disponible à partir de PHP 7.1.0)
`IMAGETYPE_AVIF` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension(). (Disponible à partir de PHP 8.1.0)
`IMAGETYPE_HEIF` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension(). (Disponible à partir de PHP 8.5.0)
`IMAGETYPE_UNKNOWN` (int)
  Une constante de type d'image utilisée par la fonction image_type_to_mime_type() et la fonction image_type_to_extension().
`IMAGETYPE_COUNT` (int)
  Le nombre de constantes de type d'image (y compris le type "inconnu") supportées par les fonctions image_type_to_mime_type() et image_type_to_extension()
`PNG_NO_FILTER` (int)
  Un filtre PNG spécial, utilisé par la fonction imagepng().
`PNG_FILTER_NONE` (int)
  Un filtre PNG spécial, utilisé par la fonction imagepng().
`PNG_FILTER_SUB` (int)
  Un filtre PNG spécial, utilisé par la fonction imagepng().
`PNG_FILTER_UP` (int)
  Un filtre PNG spécial, utilisé par la fonction imagepng().
`PNG_FILTER_AVG` (int)
  Un filtre PNG spécial, utilisé par la fonction imagepng().
`PNG_FILTER_PAETH` (int)
  Un filtre PNG spécial, utilisé par la fonction imagepng().
`PNG_ALL_FILTERS` (int)
  Un filtre PNG spécial, utilisé par la fonction imagepng().
`IMG_FLIP_VERTICAL` (int)
  Utilisé avec la fonction imageflip(), disponible à partir de PHP 5.5.0.
`IMG_FLIP_HORIZONTAL` (int)
  Utilisé avec la fonction imageflip(), disponible à partir de PHP 5.5.0.
`IMG_FLIP_BOTH` (int)
  Utilisé avec la fonction imageflip(), disponible à partir de PHP 5.5.0.
`IMG_BELL` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_BESSEL` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_BILINEAR_FIXED` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_BICUBIC` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_BICUBIC_FIXED` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_BLACKMAN` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_BOX` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_BSPLINE` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_CATMULLROM` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_GAUSSIAN` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_GENERALIZED_CUBIC` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_HERMITE` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_HAMMING` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_HANNING` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_MITCHELL` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_POWER` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_QUADRATIC` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_SINC` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_NEAREST_NEIGHBOUR` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_WEIGHTED4` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_TRIANGLE` (int)
  Utilisé avec la fonction imagesetinterpolation(), disponible à partir de PHP 5.5.0.
`IMG_CROP_BLACK` (int)
  Recadre un fond noir.
`IMG_CROP_DEFAULT` (int)
  Identique à `IMG_CROP_TRANSPARENT`. Avant PHP 7.4.0, la libgd incluse revenait à `IMG_CROP_SIDES` si l'image n'avait pas de couleur transparente.
`IMG_CROP_SIDES` (int)
  Utilise les 4 coins de l'image pour tenter de détecter le fond à recadrer.
`IMG_CROP_THRESHOLD` (int)
  Recadre une image en utilisant le `seuil` et la `couleur` donnés.
`IMG_CROP_TRANSPARENT` (int)
  Recadre un fond transparent.
`IMG_CROP_WHITE` (int)
  Recadre un fond blanc.

# Exemples

## Sommaire

- Création d'une image PNG avec PHP
- Ajout d'un tatouage numérique sur des images en utilisant un canal Alpha
- Exemple avec imagecopymerge pour créer un tatouage numérique translucide

## Création d'une image PNG avec PHP

Exemple #1 Création d'une image PNG avec PHP

    <?php

    header("Content-type: image/png");
    $string = $_GET['text'];
    $im     = imagecreatefrompng("images/button1.png");
    $orange = imagecolorallocate($im, 220, 210, 60);
    $px     = (imagesx($im) - 7.5 * strlen($string)) / 2;
    imagestring($im, 3, $px, 9, $string, $orange);
    imagepng($im);

    ?>

Cet exemple doit être appelé depuis une page HTML avec une balise image telle que : `<img src="button.php?text=text">`. Le script ci-dessus, button.php, prend la chaîne `"text"` et l'inscrit sur le fond d'image appelé `"images/button1.png"`, puis l'affiche. C'est une méthode très pratique pour éviter de redessiner une nouvelle image de bouton à chaque changement de texte. Avec cette méthode, ils sont générés dynamiquement.

## Ajout d'un tatouage numérique sur des images en utilisant un canal Alpha

Exemple #1 Ajout d'un tatouage numérique sur des images en utilisant un canal Alpha

    <?php
    // Charge le cachet et la photo afin d'y appliquer le tatouage numérique
    $stamp = imagecreatefrompng('stamp.png');
    $im = imagecreatefromjpeg('photo.jpeg');

    // Définit les marges pour le cachet et récupère la hauteur et la largeur de celui-ci
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Copie le cachet sur la photo en utilisant les marges et la largeur de la
    // photo originale afin de calculer la position du cachet
    imagecopy($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp));

    // Affichage
    header('Content-type: image/png');
    imagepng($im);
    ?>

Cet exemple montre un moyen courant d'appliquer un tatouage numérique et un cachet aux photos et aux images sous licence. Il est à noter la présence d'un canal Alpha dans le cachet ainsi que du texte anti-aliasé. Ces 2 éléments seront préservés lors de la copie.

## Exemple avec imagecopymerge() pour créer un tatouage numérique translucide

Exemple #1 Exemple avec imagecopymerge() pour créer un tatouage numérique translucide

    <?php
    // Charge le cachet et la photo afin d'y appliquer le tatouage numérique
    $im = imagecreatefromjpeg('photo.jpeg');

    // Tout d'abord, nous créons un cachet manuellement grâce à GD
    $stamp = imagecreatetruecolor(100, 70);
    imagefilledrectangle($stamp, 0, 0, 99, 69, 0x0000FF);
    imagefilledrectangle($stamp, 9, 9, 90, 60, 0xFFFFFF);
    imagestring($stamp, 5, 20, 20, 'libGD', 0x0000FF);
    imagestring($stamp, 3, 20, 40, '(c) 2007-9', 0x0000FF);

    // Définit les marges du cachet et récupère la largeur et la hauteur du cachet
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Fusionne le cachet dans notre photo avec une opacité de 50%
    imagecopymerge($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp), 50);

    // Sauvegarde l'image dans un fichier
    imagepng($im, 'photo_stamp.png');

    ?>

Cet exemple utilise imagecopymerge() pour fusionner le cachet avec l'image originale. Avec cette fonction, il est possible de définir l'opacité du cachet : dans cet exemple, elle est fixée à 50%. En pratique, cela est utile pour la protection des droits d'auteur, car les tatouages semi-transparents sont difficiles à retirer tout en permettant aux personnes qui regardent l'image de la voir.

# Fonctions GD et images

# gd_info

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

gd_info — Retourne des informations à propos de la bibliothèque GD installée

### Description

function gd_info(): array

Retourne des informations à propos de la bibliothèque GD installée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif.

Éléments du tableau retourné par gd_info()
Attribut | Signification
--- | ---
GD Version | chaîne de caractères décrivant la version de `libgd` qui est installée.
FreeType Support | booléen. `true` si le support FreeType est installé.
FreeType Linkage | chaîne de caractères décrivant la façon dont FreeType a été lié. Les valeurs attendues sont : '`with freetype`', '`with TTF library`' et '`with unknown library`'. Cet élément ne sera défini que si `FreeType Support` est évalué `true`.
GIF Read Support | booléen. `true` si le support pour la lecture des images `GIF` est inclus.
GIF Create Support | booléen. `true` si le support pour la création des images `GIF` est inclus.
JPEG Support | booléen. `true` si le support de `JPEG` est inclus.
PNG Support | booléen. `true` si le support de `PNG` est inclus.
WBMP Support | booléen. `true` si le support de `WBMP` est inclus.
XBM Support | booléen. `true` si le support de `XBM` est inclus.
WebP Support | Valeur bool. `true` si le support `WebP` est inclus.
AVIF Support | Valeur bool. `true` si le support `AVIF` est inclus. Disponible à partir de PHP 8.1.0.

### Exemples

Exemple #1 Exemple avec gd_info()

    <?php
    var_dump(gd_info());
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(10) {
      ["GD Version"]=>
      string(24) "bundled (2.1.0 compatible)"
      ["FreeType Support"]=>
      bool(false)
      ["GIF Read Support"]=>
      bool(true)
      ["GIF Create Support"]=>
      bool(false)
      ["JPEG Support"]=>
      bool(false)
      ["PNG Support"]=>
      bool(true)
      ["WBMP Support"]=>
      bool(true)
      ["XBM Support"]=>
      bool(false)
      ["WebP Support"]=>
      bool(false)
      ["AVIF Support"]=>
      bool(false)
    }

### Voir aussi

- imagepng() - Envoie une image PNG vers un navigateur ou un fichier
- imagejpeg() - Affichage de l'image vers le navigateur ou dans un fichier
- imagegif() - Affichage de l'image vers le navigateur ou dans un fichier
- imagewbmp() - Affichage de l'image vers le navigateur ou dans un fichier
- imagewebp() - Affiche une image WebP vers un navigateur ou un fichier
- imageavif() - Affichage de l'image vers le navigateur ou dans un fichier
- imagetypes() - Retourne les types d'images supportés par la version courante de PHP

# getimagesize

(PHP 4, PHP 5, PHP 7, PHP 8)

getimagesize — Retourne la taille d'une image

### Description

function getimagesize(string `$filename`, array `&$image_info` = `null`): array|false

getimagesize() détermine la taille de toute image supportée fournie et en retourne les dimensions, le type d'image et une chaîne de texte de type `height/width` à placer dans une balise HTML `IMG` normale et le type de contenu HTTP correspondant.

getimagesize() peut également retourner plus d'informations dans le paramètre `image_info`.

Attention

Cette fonction s'attend à ce que `filename` soit un fichier image valide. Si un fichier non image est fourni, il peut être détecté de manière incorrecte en tant qu'image et la fonction retourne avec succès, mais le tableau peut contenir des valeurs absurdes.

Il ne faut pas utiliser getimagesize() pour vérifier qu'un fichier donné est une image valide. Il faut utiliser à la place une solution prévue pour cela telle que l'extension Fileinfo.

> Note: Il est à noter que JPC et JP2 sont capables d'avoir des composants avec une profondeur de bit différente. Dans ce cas, la valeur de "bits" est la plus grande profondeur de bit rencontrée. De même, les fichiers JP2 disposent du support de `multiple JPEG 2000 codestreams`. Dans ce cas, getimagesize() retourne les valeurs pour le premier codestream rencontré à la racine du fichier.

> Note: Les informations sur les icônes sont récupérées depuis l'icône possédant le plus haut débit.

> Note: Les images GIF sont constituées d'un ou plusieurs cadres, où chaque cadre peut occuper uniquement une partie de l'image. La taille de l'image qui est rapportée par getimagesize() est la taille globale (lue depuis le descripteur logique de l'écran).

### Liste de paramètres

`filename`

  Ce paramètre spécifie le fichier dont l'on veut récupérer les informations. Il peut être un fichier local ou (suivant la configuration), un fichier distant en utilisant un des flux supportés.

`image_info`

  Ce paramètre optionnel permet d'extraire des informations supplémentaires du fichier image. Actuellement, cette option va retourner différents marqueurs JPG APP dans un tableau associatif. Certains programmes utilisent ces marqueurs APP pour intégrer des informations textuelles dans les images. Un cas très répandu consiste à intégrer des informations » IPTC dans le marqueur APP13. Il est possible d'utiliser la fonction iptcparse() pour analyser ce marqueur APP13 binaire, et obtenir des informations intelligibles.

  > Note:

  > `image_info` supporte uniquement les fichiers JFIF.

### Valeurs de retour

Retourne un tableau contenant jusqu'à 7 éléments. Tous les types d'images n'incluent pas les éléments `channels` et `bits`.

Les indices 0 et 1 contiennent respectivement la largeur et la hauteur de l'image.

> Note:

> Certains formats peuvent ne contenir aucune image, ou bien plusieurs. Dans ces cas-là, getimagesize() peut ne pas être capable de déterminer correctement la taille de l'image. getimagesize() retourne alors zéro comme taille de hauteur et largeur.

> Note: getimagesize() est indépendante des métadonnées de l'image. Par exemple, si le drapeau Exif `Orientation` est défini sur une valeur qui fait pivoter l'image de 90 ou 270 degrés, les indices 0 et 1 sont échangés, c'est-à-dire qu'ils contiennent respectivement la hauteur et la largeur.

L'index 2 est une constante parmi `IMAGETYPE_*`, indiquant le type de l'image.

L'index 3 est une chaîne de texte avec la chaîne `height="yyy" width="xxx"` correcte qui peut être utilisée directement dans une balise IMG.

`mime` correspond au type MIME d'une image. Cette information peut être utilisée pour envoyer l'en-tête HTTP `Content-type` correct :

Exemple #1 getimagesize() et types MIME

    <?php
    $size = getimagesize($filename);
    $fp = fopen($filename, "rb");
    if ($size && $fp) {
        header("Content-type: {$size['mime']}");
        fpassthru($fp);
        exit;
    } else {
        // error
    }
    ?>

`channels` sera 3 pour des images RGB et 4 pour des images CMYK.

`bits` est le nombre de bits pour chaque couleur.

Pour certains types d'images, la présence des valeurs de `channels` et de `bits` peut prêter à confusion. Par exemple, une image GIF utilise toujours trois canaux par pixel, mais le nombre de bits par pixel ne peut être calculé dans le cas d'une image animée GIF ayant une table de couleur globale.

Si une erreur survient, `false` est retourné.

### Erreurs / Exceptions

Si l'accès à `filename` est impossible, getimagesize() générera une erreur de niveau `E_WARNING`. Si une erreur survient lors de la lecture, getimagesize() générera une erreur de niveau `E_NOTICE`.

À partir de PHP 8.0.0, une ValueError est lancée si `filename` est vide.

### Historique

Version | Description
--- | ---
8.2.0 | Retourne désormais les dimensions réelles de l'image, les bits et les canaux des images AVIF ; précédemment, les dimensions étaient rapportées en tant que `0x0`, et les bits et les canaux n'étaient pas rapportés du tout.
8.0.0 | Une ValueError est désormais lancée si `filename` est vide ; précédemment un `E_WARNING` était émis et la fonction retournait `false`.
7.1.0 | Ajout du support de WebP.

### Exemples

Exemple #2 Exemple avec getimagesize()

    <?php
    list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
    echo "<img src=\"img/flag.jpg\" $attr alt=\"Exemple avec getimagesize()\" />";
    ?>

Exemple #3 getimagesize() avec une URL

    <?php
    $size = getimagesize("http://www.example.com/gifs/logo.gif");

    // Si le nom du fichier comporte des espaces, encodez-le !
    $size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

    ?>

Exemple #4 getimagesize() qui retourne IPTC

    <?php
    $size = getimagesize("testimg.jpg", $info);
    if (isset($info["APP13"])) {
        $iptc = iptcparse($info["APP13"]);
        var_dump($iptc);
    }
    ?>

### Notes

> Note: Cette fonction ne nécessite pas la bibliothèque GD.

### Voir aussi

- image_type_to_mime_type() - Lit le Mime-Type d'un type d'image
- exif_imagetype() - Détermine le type d'une image
- exif_read_data() - Lit les en-têtes EXIF dans les images
- exif_thumbnail() - Récupère la miniature embarquée d'une image
- imagesx() - Retourne la largeur d'une image
- imagesy() - Retourne la hauteur de l'image

# getimagesizefromstring

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

getimagesizefromstring — Récupère la taille d'une image depuis une chaîne

### Description

function getimagesizefromstring(string `$string`, array `&$image_info` = `null`): array|false

Identique à la fonction getimagesize() excepté le fait que la fonction getimagesizefromstring() accepte une chaîne au lieu d'un nom de fichier comme premier paramètre.

Voir la documentation sur la fonction getimagesize() pour plus de détails sur le fonctionnement de cette fonction.

### Liste de paramètres

`string`

  Les données de l'image, sous la forme d'une chaîne.

`image_info`

  Voir la fonction getimagesize().

### Valeurs de retour

Voir la fonction getimagesize().

### Exemples

Exemple #1 Exemple avec getimagesizefromstring()

    <?php
    $img = '/path/to/test.png';

    // Ouverture via un fichier
    $size_info1 = getimagesize($img);

    // Ou ouverture via une chaîne
    $data       = file_get_contents($img);
    $size_info2 = getimagesizefromstring($data);
    ?>

### Voir aussi

- getimagesize() - Retourne la taille d'une image

# image_type_to_extension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

image_type_to_extension — Retourne l'extension du fichier pour le type d'image

### Description

function image_type_to_extension(int `$image_type`, bool `$include_dot` = `true`): string|false

image_type_to_extension() retourne l'extension pour la constante `IMAGETYPE_*` fournie.

### Liste de paramètres

`image_type`

  Une des constantes `IMAGETYPE_*`.

`include_dot`

  Indique s'il faut ajouter un point à l'extension ou non. Par défaut, vaut `true`.

### Valeurs de retour

Une chaîne de caractères avec l'extension, correspondant au type de l'image fournie, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec image_type_to_extension()

    <?php
    // Création d'une instance d'image
    $im = imagecreatetruecolor(100, 100);

    // Sauvegarde de l'image
    imagepng($im, './test' . image_type_to_extension(IMAGETYPE_PNG));
    ?>

### Notes

> Note: Cette fonction ne nécessite pas la bibliothèque GD.

# image_type_to_mime_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

image_type_to_mime_type — Lit le Mime-Type d'un type d'image

### Description

function image_type_to_mime_type(int `$image_type`): string

Détermine le type MIME (`Mime-Type`), à utiliser dans l'en-tête HTTP `Content-type`.

### Liste de paramètres

`image_type`

  Une des constantes `IMAGETYPE_*`.

### Valeurs de retour

Les valeurs retournées sont les suivantes

Valeurs des constantes retournées
`image_type` | Valeur retournée
--- | ---
`IMAGETYPE_GIF` | `image/gif`
`IMAGETYPE_JPEG` | `image/jpeg`
`IMAGETYPE_PNG` | `image/png`
`IMAGETYPE_SWF` | `application/x-shockwave-flash`
`IMAGETYPE_PSD` | `image/psd`
`IMAGETYPE_BMP` | `image/bmp`
`IMAGETYPE_TIFF_II` (ordre intel) | `image/tiff`
`IMAGETYPE_TIFF_MM` (ordre motorola) | `image/tiff`
`IMAGETYPE_JPC` | `application/octet-stream`
`IMAGETYPE_JP2` | `image/jp2`
`IMAGETYPE_JPX` | `application/octet-stream`
`IMAGETYPE_JB2` | `application/octet-stream`
`IMAGETYPE_SWC` | `application/x-shockwave-flash`
`IMAGETYPE_IFF` | `image/iff`
`IMAGETYPE_WBMP` | `image/vnd.wap.wbmp`
`IMAGETYPE_XBM` | `image/xbm`
`IMAGETYPE_ICO` | `image/vnd.microsoft.icon`
`IMAGETYPE_WEBP` | `image/webp`
`IMAGETYPE_AVIF` | `image/avif`
`IMAGETYPE_HEIF` | `image/heif`

### Exemples

Exemple #1 Exemple avec image_type_to_mime_type()

    <?php
    header("Content-type: " . image_type_to_mime_type(IMAGETYPE_PNG));
    ?>

### Notes

> Note: Cette fonction ne nécessite pas la bibliothèque GD.

### Voir aussi

- getimagesize() - Retourne la taille d'une image
- exif_imagetype() - Détermine le type d'une image
- exif_read_data() - Lit les en-têtes EXIF dans les images
- exif_thumbnail() - Récupère la miniature embarquée d'une image

# image2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

image2wbmp — Affichage de l'image vers le navigateur ou dans un fichier

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.3.0, et a été SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function image2wbmp(resource `$image`, string `$filename` = ?, int `$foreground` = ?): bool

image2wbmp() affiche ou enregistre une version WBMP de l'image `image` fournie.

### Liste de paramètres

`image`

  Une ressource d'image, retournée par une des fonctions de création d'image, telles que imagecreatetruecolor().

`filename`

  Chemin vers le fichier de sauvegarde. S'il n'est pas fourni, le flux de l'image sera directement affiché.

`foreground`

  La couleur du premier plan peut être définie avec ce paramètre en fournissant un identifiant obtenu avec imagecolorallocate(). La couleur du premier plan par défaut est noir.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Exemples

Exemple #1 Exemple avec image2wbmp()

    <?php

    $file = 'php.png';
    $image = imagecreatefrompng($file);

    header('Content-Type: ' . image_type_to_mime_type(IMAGETYPE_WBMP));
    image2wbmp($image); // Affichage direct

    ?>

### Voir aussi

- imagewbmp() - Affichage de l'image vers le navigateur ou dans un fichier

# imageaffine

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffine — Retourne une image contenant l'image source transformée, en utilisant optionnellement une zone de découpe

### Description

function imageaffine(GdImage `$image`, array `$affine`, ?array `$clip` = `null`): GdImage|false

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`affine`

  Un tableau avec les clés de 0 à 5.

`clip`

  Un tableau avec les clés "x", "y", "width" et "height"; ou `null`.

### Valeurs de retour

Retourne l'objet image transformée en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `clip` est désormais nullable.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.

# imageaffinematrixconcat

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixconcat — Concatène deux matrices de transformation affine

### Description

function imageaffinematrixconcat(array `$matrix1`, array `$matrix2`): array|false

Retourne la concaténation de deux matrices de transformation affine, ce qui est utile si plusieurs transformations devraient être appliquées à la même image en une seule fois.

### Liste de paramètres

`matrix1`

  Une matrice de transformation affine (un tableau avec des clés de `0` à `5` et nombres décimaux en valeur).

`matrix2`

  Une matrice de transformation affine (un tableau avec des clés de `0` à `5` et nombres décimaux en valeur).

### Valeurs de retour

Une matrice de transformation affine (un tableau avec des clés de `0` à `5` et nombres décimaux en valeur). ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple pour imageaffinematrixconcat()

    <?php
    $m1 = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    $m2 = imageaffinematrixget(IMG_AFFINE_SCALE, array('x' => 4, 'y' => 5));
    $matrix = imageaffinematrixconcat($m1, $m2);
    print_r($matrix);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => 4
        [1] => 0
        [2] => 0
        [3] => 5
        [4] => 8
        [5] => 15
    )

### Voir aussi

- imageaffine() - Retourne une image contenant l'image source transformée, en utilisant optionnellement une zone de découpe
- imageaffinematrixget() - Obtenir une matrice de transformation affine

# imageaffinematrixget

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixget — Obtenir une matrice de transformation affine

### Description

function imageaffinematrixget(int `$type`, array|float `$options`): array|false

Retourne une matrice de transformation affine.

### Liste de paramètres

`type`

  Une constante parmi `IMG_AFFINE_*`.

`options`

  Si `type` est `IMG_AFFINE_TRANSLATE` ou `IMG_AFFINE_SCALE`, `options` doit être un array avec les clés `x` et `y`, les deux étant des valeurs float.

  Si `type` est `IMG_AFFINE_ROTATE`, `IMG_AFFINE_SHEAR_HORIZONTAL` ou `IMG_AFFINE_SHEAR_VERTICAL`, `options` doit être une valeur float spécifiant l'angle.

### Valeurs de retour

Une matrice de transformation affine (un tableau avec des clés de `0` à `5` et des valeurs de type float). ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple pour imageaffinematrixget()

    <?php
    $matrix = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    print_r($matrix);
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => 1
        [1] => 0
        [2] => 0
        [3] => 1
        [4] => 2
        [5] => 3
    )

### Voir aussi

- imageaffine() - Retourne une image contenant l'image source transformée, en utilisant optionnellement une zone de découpe
- imageaffinematrixconcat() - Concatène deux matrices de transformation affine

# imagealphablending

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagealphablending — Modifie le mode de blending d'une image

### Description

function imagealphablending(GdImage `$image`, bool `$enable`): true

imagealphablending() permet deux modes différents de dessin sur les images en vraies couleurs (truecolor). En mode "blending", la composante du canal alpha de la couleur fournie à toutes les fonctions de dessin, telles que imagesetpixel(), détermine dans quelle mesure la couleur sous-jacente doit transparaître. En conséquence, GD mélange automatiquement la couleur existante en ce point avec la couleur de dessin, et stocke le résultat dans l'image. Le pixel résultant est opaque. En mode non-blending, la couleur de dessin est copiée littéralement avec ses informations de canal alpha, en remplaçant le pixel de destination. Le mode blending n'est pas disponible lors du dessin sur les images à palette.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`enable`

  S'il faut activer le mode blending ou non. Sur les images en vraies couleurs, la valeur par défaut est `true`, sinon, la valeur par défaut est `false`.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagealphablending()

    <?php
    // Création d'une image
    $im = imagecreatetruecolor(100, 100);

    // Définit l'alphablending à on
    imagealphablending($im, true);

    // Dessine un carré
    imagefilledrectangle($im, 30, 30, 70, 70, imagecolorallocate($im, 255, 0, 0));

    // Affichage
    header('Content-Type: image/png');

    imagepng($im);
    ?>

# imageantialias

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageantialias — Utiliser ou non les fonctions d'antialias

### Description

function imageantialias(GdImage `$image`, bool `$enable`): true

Active les méthodes de dessin rapide antialias concernant les lignes et les polygones filaires. Les composantes alpha ne sont pas supportées. Fonctionne en utilisant une opération directe de mélange, uniquement avec les images truecolor.

L'épaisseur et les styles ne sont pas supportés.

L'utilisation des primitives antialias avec des arrière-plans transparents peut mener à des résultats imprévus. La méthode de mélange utilise la couleur d'arrière-plan comme toute autre couleur. L'absence de support du composant alpha empêche l'utilisation d'antialias basé sur l'alpha.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`enable`

  Si l'on doit activer l'antialias ou non.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
7.2.0 | imageantialias() est maintenant généralement disponible. Antérieurement, elle était seulement disponible si PHP était compilé avec la version groupée de la bibliothèque GD.

### Exemples

Exemple #1 Comparaison de 2 lignes, dont l'une est anti-aliasée

    <?php
    // Définit une image anti-aliasée et une normale
    $aa = imagecreatetruecolor(400, 100);
    $normal = imagecreatetruecolor(200, 100);

    // Active l'antialiasing pour une image
    imageantialias($aa, true);

    // Alloue les couleurs
    $red = imagecolorallocate($normal, 255, 0, 0);
    $red_aa = imagecolorallocate($aa, 255, 0, 0);

    // Dessine 2 lignes, dont l'une avec l'antialiasing
    imageline($normal, 0, 0, 200, 100, $red);
    imageline($aa, 0, 0, 200, 100, $red_aa);

    // Fusionne les 2 images, côté par côté pour l'affichage
    // (AA: gauche, Normal: droite)
    imagecopymerge($aa, $normal, 200, 0, 0, 0, 200, 100, 100);

    // Affichage de l'image
    header('Content-type: image/png');

    imagepng($aa);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies

# imagearc

(PHP 4, PHP 5, PHP 7, PHP 8)

imagearc — Dessine un arc

### Description

function imagearc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`
): true

imagearc() dessine un arc de cercle, centré sur les coordonnées fournies.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`center_x`

  Coordonnée x du centre.

`center_y`

  Coordonnée y du centre.

`width`

  La largeur de l'arc.

`height`

  La hauteur de l'arc.

`start_angle`

  L'angle de début de l'arc, en degrés.

`end_angle`

  L'angle de fin de l'arc, en degrés. 0° correspond à la position "trois heures" et l'arc est dessiné dans le sens des aiguilles d'une montre.

`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Dessin d'un cercle avec imagearc()

    <?php

    // Création d'une image 200*200
    $img = imagecreatetruecolor(200, 200);

    // Allocation de couleurs
    $white = imagecolorallocate($img, 255, 255, 255);
    $red   = imagecolorallocate($img, 255,   0,   0);
    $green = imagecolorallocate($img,   0, 255,   0);
    $blue  = imagecolorallocate($img,   0,   0, 255);

    // Dessine la tête
    imagearc($img, 100, 100, 200, 200,  0, 360, $white);
    // La bouche
    imagearc($img, 100, 100, 150, 150, 25, 155, $red);
    // les yeux gauche et droit
    imagearc($img,  60,  75,  50,  50,  0, 360, $green);
    imagearc($img, 140,  75,  50,  50,  0, 360, $blue);

    // Affichage au navigateur
    header("Content-type: image/png");
    imagepng($img);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagefilledarc() - Dessine un arc partiel et le remplit
- imageellipse() - Dessine une ellipse
- imagefilledellipse() - Dessine une ellipse pleine

# imageavif

(PHP 8 >= 8.1.0)

imageavif — Affichage de l'image vers le navigateur ou dans un fichier

### Description

function imageavif(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$speed` = -1
): bool

Affiche ou sauvegarde une image au format AVIF en utilisant l'`image` fournie.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`file`

  Le chemin ou un flux de ressource ouvert (qui sera automatiquement fermé après le retour de cette fonction) vers lequel le fichier sera sauvegardé. Si non-défini ou `null`, le flux brute de l'image sera affiché directement.

`quality`

  `quality` est un paramètre optionnel dont la plage varie de 0 (pire qualité, plus petit fichier) à 100 (meilleure qualité, plus grand fichier). Si `-1` est passé en paramètre, la valeur par défaut `52` sera utilisée.

`speed`

  `speed` est un paramètre optionnel dont la plage varie de 0 (encodage lent, plus petit fichier) à 10 (encodage rapide, plus grand fichier). Si `-1` est passé en paramètre, la valeur par défaut `6` sera utilisée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Erreurs / Exceptions

Lève une ValueError si `quality` ou `speed` est invalide.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `quality` ou `speed` est invalide.

### Voir aussi

- imagepng() - Envoie une image PNG vers un navigateur ou un fichier
- imagewbmp() - Affichage de l'image vers le navigateur ou dans un fichier
- imagejpeg() - Affichage de l'image vers le navigateur ou dans un fichier
- imagetypes() - Retourne les types d'images supportés par la version courante de PHP

# imagebmp

(PHP 7 >= 7.2.0, PHP 8)

imagebmp — Affiche ou enregistre une image BMP au navigateur ou dans un fichier

### Description

function imagebmp(GdImage `$image`, resource|string|null `$file` = `null`, bool `$compressed` = `true`): bool

Affiche ou enregistre une version BMP de l'`image` fournie.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`file`

  Le chemin ou un flux de ressource ouvert (qui sera automatiquement fermé après le retour de cette fonction) vers lequel le fichier sera sauvegardé. Si non-défini ou `null`, le flux brute de l'image sera affiché directement.

  > Note:

  > `null` est invalide si l'argument `compressed` n'est pas utilisé.

`compressed`

  Si le BMP doit être compressé avec run-length encoding (RLE), ou pas.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
8.0.0 | Le type de `compressed` est désormais booléen ; antérieurement c'était entier.

### Exemples

Exemple #1 Enregistrer un fichier BMP

    <?php
    // Créer une image vierge et ajouter du texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'BMP with PHP', $text_color);

    // Enregistre l'image
    imagebmp($im, 'php.bmp');
    ?>

# imagechar

(PHP 4, PHP 5, PHP 7, PHP 8)

imagechar — Dessine un caractère horizontalement

### Description

function imagechar(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

imagechar() dessine le premier caractère de la chaîne `char` dans l'image `image` avec le coin supérieur gauche placé à la position `x`,`y` (le coin en haut à gauche est l'origine (0,0)) avec la couleur `color`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`font`
  Peut être 1, 2, 3, 4, 5 pour les polices internes d'encodage Latin2 (où les plus grands nombres correspondent aux polices larges) ou une instance de GdFont retourné par imageloadfont().
`x`

  Coordonnée X de départ.

`y`

  Coordonnée Y de départ.

`char`

  Le caractère à dessiner.

`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `font` accepte désormais une instance de GdFont et un entier; auparavant seulement un entier était accepté.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagechar()

    <?php

    $im = imagecreate(100, 100);

    $string = 'PHP';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // affiche un "P" noir dans le coin supérieur gauche
    imagechar($im, 1, 0, 0, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagecharup() - Dessine un caractère verticalement
- imageloadfont() - Charge une nouvelle police

# imagecharup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecharup — Dessine un caractère verticalement

### Description

function imagecharup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

Dessine le premier caractère de la chaîne `char` verticalement dans l'image `image` fournie.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`font`
  Peut être 1, 2, 3, 4, 5 pour les polices internes d'encodage Latin2 (où les plus grands nombres correspondent aux polices larges) ou une instance de GdFont retourné par imageloadfont().
`x`

  Coordonnée x du point de départ.

`y`

  Coordonnée y du point de départ.

`char`

  Le caractère à dessiner.

`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `font` accepte désormais une instance de GdFont et un entier; auparavant seulement un entier était accepté.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagecharup()

    <?php

    $im = imagecreate(100, 100);

    $string = 'Notez que la première lettre est un N';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // affiche un "Z" noir sur un fond blanc
    imagecharup($im, 3, 10, 10, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagechar() - Dessine un caractère horizontalement
- imageloadfont() - Charge une nouvelle police

# imagecolorallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorallocate — Alloue une couleur pour une image

### Description

function imagecolorallocate(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int|false

Retourne un identifiant de couleur, représentant la couleur composée avec les couleurs RGB.

imagecolorallocate() doit être appelée pour créer chaque couleur qui sera représentée par `image`.

> Note:

> Le premier appel à imagecolorallocate() remplit la couleur de fond avec la palette des images - images créées en utilisant imagecreate().

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

Ces paramètres sont des entiers compris entre 0 et 255 ou des hexadécimaux compris entre 0x00 et 0xFF.

### Valeurs de retour

Un identifiant de couleur ou `false` si l'allocation échoue.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagecolorallocate()

    <?php

    $im = imagecreate(100, 100);

    // Le fond de l'image est en rouge
    $background = imagecolorallocate($im, 255, 0, 0);

    // On définit des couleurs avec des entiers ..
    $white = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // .. ou des hexadécimaux
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    ?>

### Voir aussi

- imagecolorallocatealpha() - Alloue une couleur à une image
- imagecolordeallocate() - Supprime une couleur d'une image

# imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagecolorallocatealpha — Alloue une couleur à une image

### Description

function imagecolorallocatealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int|false

imagecolorallocatealpha() se comporte comme imagecolorallocate() avec en plus le paramètre de transparence `alpha`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

`alpha`

  Une valeur entre `0` et `127`. `0` indique une opacité complète tandis que `127` indique une transparence complète.

Les paramètres `red`, `green` et `blue` sont des entiers compris entre 0 et 255, ou des hexadécimaux compris entre 0x00 et 0xFF.

### Valeurs de retour

Un identifiant de couleur ou `false` si l'allocation échoue.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple d'utilisation de imagecolorallocatealpha()

    <?php
    $size = 300;
    $image=imagecreatetruecolor($size, $size);

    // quelque chose pour obtenir un fond blanc avec une bordure noire
    $back = imagecolorallocate($image, 255, 255, 255);
    $border = imagecolorallocate($image, 0, 0, 0);
    imagefilledrectangle($image, 0, 0, $size - 1, $size - 1, $back);
    imagerectangle($image, 0, 0, $size - 1, $size - 1, $border);

    $yellow_x = 100;
    $yellow_y = 75;
    $red_x    = 120;
    $red_y    = 165;
    $blue_x   = 187;
    $blue_y   = 125;
    $radius   = 150;

    // alloue des couleurs avec des valeurs alpha
    $yellow = imagecolorallocatealpha($image, 255, 255, 0, 75);
    $red    = imagecolorallocatealpha($image, 255, 0, 0, 75);
    $blue   = imagecolorallocatealpha($image, 0, 0, 255, 75);

    // Dessine 3 cercles superposés
    imagefilledellipse($image, $yellow_x, $yellow_y, $radius, $radius, $yellow);
    imagefilledellipse($image, $red_x, $red_y, $radius, $radius, $red);
    imagefilledellipse($image, $blue_x, $blue_y, $radius, $radius, $blue);

    // Ne pas oublier d'envoyer un en-tête correct
    header('Content-Type: image/png');

    // et finalement, afficher le résultat
    imagepng($image);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Exemple #2 Conversion de valeur alpha typique pour l'utiliser avec imagecolorallocatealpha()

Généralement les valeurs alpha `0` désignent les pixels complètement transparents, et le canal alpha a 8 bits. Pour convertir de telles valeurs alpha pour être compatible avec imagecolorallocatealpha(), un peu d'arithmétique simple est suffisante :

    <?php
    $alpha8 = 0; // totalement transparent
    var_dump(127 - ($alpha8 >> 1));
    $alpha8 = 255; // totalement opaque
    var_dump(127 - ($alpha8 >> 1));
    ?>

L'exemple ci-dessus va afficher :

    int(127)
    int(0)

### Voir aussi

- imagecolorallocate() - Alloue une couleur pour une image
- imagecolordeallocate() - Supprime une couleur d'une image

# imagecolorat

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorat — Retourne l'index de la couleur d'un pixel donné

### Description

function imagecolorat(GdImage `$image`, int `$x`, int `$y`): int|false

Retourne l'index de la couleur du pixel situé aux coordonnées spécifiées, dans l'image `image`.

Si l'image est une image en truecolor, cette fonction retourne la valeur RGB du pixel, sous forme d'un entier. Il faut utiliser les opérateurs de bits et les masques pour distinguer les composantes rouge, verte et bleue :

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`x`

  X : coordonnée du point.

`y`

  Y : coordonnée du point.

### Valeurs de retour

Retourne l'index de la couleur ou `false` si une erreur survient.

Avertissement

Cette fonction peut retourner `false`, mais elle peut aussi retourner une valeur équivalent à `false`. Veuillez lire la section sur les booléens pour plus d'informations. Utilisez l'opérateur === pour tester la valeur de retour exacte de cette fonction.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Accès aux valeurs RGB

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);
    $r = ($rgb >> 16) & 0xFF;
    $g = ($rgb >> 8) & 0xFF;
    $b = $rgb & 0xFF;
    var_dump($r, $g, $b);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    int(119)
    int(123)
    int(180)

Exemple #2 Valeurs RVB lisibles en utilisant la fonction imagecolorsforindex()

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);

    $colors = imagecolorsforindex($im, $rgb);

    var_dump($colors);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    array(4) {
      ["red"]=>
      int(119)
      ["green"]=>
      int(123)
      ["blue"]=>
      int(180)
      ["alpha"]=>
      int(127)
    }

### Voir aussi

- imagecolorset() - Change la couleur dans une palette à l'index donné
- imagecolorsforindex() - Retourne la couleur associée à un index
- imagesetpixel() - Dessine un pixel

# imagecolorclosest

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorclosest — Retourne l'index de la couleur la plus proche d'une couleur donnée

### Description

function imagecolorclosest(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Retourne l'index de la couleur de la palette qui est la plus proche de la valeur RGB passée.

La "distance" entre la couleur souhaitée et les couleurs de la palette est calculée en considérant l'espace RGB comme un espace à 3 dimensions.

Si vous créez l'image depuis un fichier, seules les couleurs utilisées dans l'image seront résolues. Les couleurs uniquement présentes dans la palette ne le seront pas.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

Les paramètres sur les couleurs sont des entiers compris entre 0 et 255 ou des hexadécimaux compris entre 0x00 et 0xFF.

### Valeurs de retour

Retourne l'index de la couleur la plus proche, dans la palette de l'image, de celle donnée.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Recherche d'un jeu de couleur dans une image

    <?php
    // On commence avec une image et on la convertit en une image à palette
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Couleurs recherchées (RVB)
    $colors = array(
        array(254, 145, 154),
        array(153, 145, 188),
        array(153, 90, 145),
        array(255, 137, 92)
    );

    // On boucle sur chaque recherche et on trouve la couleur de la palette la plus proche.
    // Retourne le numéro de la recherche, le RVB cherché et la correspondance en RVB
    foreach($colors as $id => $rgb)
    {
        $result = imagecolorclosest($im, $rgb[0], $rgb[1], $rgb[2]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']})";

        echo "#$id: Recherche ($rgb[0], $rgb[1], $rgb[2]); Correspondance : $result.\n";
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    #0: Recherche (254, 145, 154); Correspondance : (252, 150, 148).
    #1: Recherche (153, 145, 188); Correspondance : (148, 150, 196).
    #2: Recherche (153, 90, 145); Correspondance : (148, 90, 156).
    #3: Recherche (255, 137, 92); Correspondance : (252, 150, 92).

### Voir aussi

- imagecolorexact() - Retourne l'index de la couleur donnée
- imagecolorclosestalpha() - Retourne la couleur la plus proche, en tenant compte du canal alpha
- imagecolorclosesthwb() - Récupère l'index de la couleur ayant la teinte, le blanc et le noir

# imagecolorclosestalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorclosestalpha — Retourne la couleur la plus proche, en tenant compte du canal alpha

### Description

function imagecolorclosestalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Retourne l'index de la couleur, dans la palette de l'image `image`, la plus proche de la couleur spécifiée par les autres paramètres, au format RGB et de canal alpha `alpha`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

`alpha`

  Une valeur comprise entre `0` et `127`. `0` indique une opacité complète tandis que `127` indique une transparence complète.

Les paramètres de couleur sont des entiers compris entre 0 et 255 ou des hexadécimaux compris entre 0x00 et 0xFF.

### Valeurs de retour

Retourne l'index de la couleur la plus proche dans la palette.

### Exemples

Exemple #1 Cherche un jeu de couleurs dans une image

    <?php
    // On commence avec une image et on la convertit en palette
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Recherche des couleurs (RVB)
    $colors = array(
        array(254, 145, 154, 50),
        array(153, 145, 188, 127),
        array(153, 90, 145, 0),
        array(255, 137, 92, 84)
    );

    // On boucle sur chaque recherche et on trouve la couleur la plus proche de la palette.
    // Retourne le numéro de la recherche, la recherche RVB et le résultat converti en RVB
    foreach($colors as $id => $rgb)
    {
        $result = imagecolorclosestalpha($im, $rgb[0], $rgb[1], $rgb[2], $rgb[3]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']}, {$result['alpha']})";

        echo "#$id: Recherche ($rgb[0], $rgb[1], $rgb[2], $rgb[3]); Résultat le plus proche : $result.\n";
    }

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    #0: Recherche (254, 145, 154, 50); Résultat le plus proche : (252, 150, 148, 0).
    #1: Recherche (153, 145, 188, 127); Résultat le plus proche : (148, 150, 196, 0).
    #2: Recherche (153, 90, 145, 0); Résultat le plus proche : (148, 90, 156, 0).
    #3: Recherche (255, 137, 92, 84); Résultat le plus proche : (252, 150, 92, 0).

### Voir aussi

- imagecolorexactalpha() - Retourne l'index d'une couleur avec son canal alpha
- imagecolorclosest() - Retourne l'index de la couleur la plus proche d'une couleur donnée
- imagecolorclosesthwb() - Récupère l'index de la couleur ayant la teinte, le blanc et le noir

# imagecolorclosesthwb

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecolorclosesthwb — Récupère l'index de la couleur ayant la teinte, le blanc et le noir

### Description

function imagecolorclosesthwb(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Récupère l'index de la couleur ayant la teinte, le blanc et le noir les plus proches de la couleur donnée.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

### Valeurs de retour

Retourne un entier correspondant à l'index de la couleur ayant la teinte, le blanc et le noir les plus proches de la couleur donnée.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagecolorclosesthwb()

    <?php
    $im = imagecreatefromgif('php.gif');

    echo 'HWB: ' . imagecolorclosesthwb($im, 116, 115, 152);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    HWB: 33

### Voir aussi

- imagecolorclosest() - Retourne l'index de la couleur la plus proche d'une couleur donnée

# imagecolordeallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolordeallocate — Supprime une couleur d'une image

### Description

function imagecolordeallocate(GdImage `$image`, int `$color`): true

Supprime une couleur précédemment allouée avec imagecolorallocate() ou imagecolorallocatealpha().

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`color`

  L'identifiant de la couleur.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagecolordeallocate()

    <?php
    $white = imagecolorallocate($im, 255, 255, 255);
    imagecolordeallocate($im, $white);
    ?>

### Voir aussi

- imagecolorallocate() - Alloue une couleur pour une image
- imagecolorallocatealpha() - Alloue une couleur à une image

# imagecolorexact

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorexact — Retourne l'index de la couleur donnée

### Description

function imagecolorexact(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Retourne l'index de la couleur spécifiée dans la palette de l'image `image`.

Si vous créez l'image depuis un fichier, seules les couleurs utilisées dans l'image seront résolues. Les couleurs uniquement présentes dans la palette ne le seront pas.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

### Valeurs de retour

Retourne l'index de la couleur spécifiée dans la palette, ou -1 si la couleur n'existe pas.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Récupération des couleurs composant le logo GD

    <?php
    // Définit l'image
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = Array();
    $colors[] = imagecolorexact($im, 255, 0, 0);
    $colors[] = imagecolorexact($im, 0, 0, 0);
    $colors[] = imagecolorexact($im, 255, 255, 255);
    $colors[] = imagecolorexact($im, 100, 255, 52);

    print_r($colors);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 16711680
        [1] => 0
        [2] => 16777215
        [3] => 6618932
    )

### Voir aussi

- imagecolorclosest() - Retourne l'index de la couleur la plus proche d'une couleur donnée

# imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorexactalpha — Retourne l'index d'une couleur avec son canal alpha

### Description

function imagecolorexactalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Retourne l'index de la couleur spécifiée et son canal alpha dans la palette de l'image.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

`alpha`

  Une valeur comprise entre `0` et `127`. `0` indique une opacité complète tandis que `127` indique une transparence complète.

Les paramètres sur les couleurs sont des entiers compris entre 0 et 255 ou des hexadécimaux compris entre 0x00 et 0xFF.

### Valeurs de retour

Retourne l'index de la couleur fournie et son canal alpha dans la palette de l'image, ou -1 si la couleur n'existe pas dans la palette de l'image.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Récupération des couleurs composant le logo GD

    <?php

    // Définit l'image
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = Array();
    $colors[] = imagecolorexactalpha($im, 255, 0, 0, 0);
    $colors[] = imagecolorexactalpha($im, 0, 0, 0, 127);
    $colors[] = imagecolorexactalpha($im, 255, 255, 255, 55);
    $colors[] = imagecolorexactalpha($im, 100, 255, 52, 20);

    print_r($colors);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 16711680
        [1] => 2130706432
        [2] => 939524095
        [3] => 342163252
    )

### Voir aussi

- imagecolorclosestalpha() - Retourne la couleur la plus proche, en tenant compte du canal alpha

# imagecolormatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagecolormatch — Fait correspondre un peu plus les couleurs de la version palette d'une image aux couleurs de sa version truecolor

### Description

function imagecolormatch(GdImage `$image1`, GdImage `$image2`): true

Fait correspondre un peu plus les couleurs de la version palette d'une image aux couleurs de sa version truecolor.

### Liste de paramètres

`image1`

  Un objet d'image truecolor.

`image2`

  Un objet image en palette pointant sur une image de même taille que `image1`.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image1` et `image2` attendent désormais des instances de GdImage ; antérieurement, des resources étaient attendues.

### Exemples

Exemple #1 Exemple avec imagecolormatch()

    <?php
    // Définit l'image true color et la palette
    $im1 = imagecreatefrompng('./gdlogo.png');
    $im2 = imagecreate(imagesx($im1), imagesy($im1));

    // Ajout de quelques couleurs à $im2
    $colors   = Array();
    $colors[] = imagecolorallocate($im2, 255, 36, 74);
    $colors[] = imagecolorallocate($im2, 40, 0, 240);
    $colors[] = imagecolorallocate($im2, 82, 100, 255);
    $colors[] = imagecolorallocate($im2, 84, 63, 44);

    // Fait correspondre ces couleurs avec l'image true color
    imagecolormatch($im1, $im2);
    ?>

### Voir aussi

- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies

# imagecolorresolve

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorresolve — Retourne l'index de la couleur donnée, ou la plus proche possible

### Description

function imagecolorresolve(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

imagecolorresolve() retourne un index de couleur à tous les coups. Soit il arrive à trouver la couleur demandée dans la palette, soit il trouve la couleur la plus proche.

Si vous créez l'image depuis un fichier, seules les couleurs utilisées dans l'image seront résolues. Les couleurs uniquement présentes dans la palette ne le seront pas.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

### Valeurs de retour

Retourne un index de couleur.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagecoloresolve() pour récupérer les couleurs d'une image

    <?php
    // Chargement d'une image
    $im = imagecreatefromgif('phplogo.gif');

    // Récupération des couleurs les plus proches de l'image
    $colors = array();
    $colors[] = imagecolorresolve($im, 255, 255, 255);
    $colors[] = imagecolorresolve($im, 0, 0, 200);

    // Affichage
    print_r($colors);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 89
        [1] => 85
    )

### Voir aussi

- imagecolorclosest() - Retourne l'index de la couleur la plus proche d'une couleur donnée

# imagecolorresolvealpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorresolvealpha — Retourne un index de couleur ou son alternative la plus proche, y compris le canal alpha

### Description

function imagecolorresolvealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

imagecolorresolvealpha() retourne toujours un index de couleur, disponible dans la palette de l'image `image` : soit c'est la couleur exacte, soit c'est la meilleure approximation.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

`alpha`

  Une valeur comprise entre `0` et `127`. `0` indique une opacité complète tandis que `127` indique une transparence complète.

Les paramètres sur les couleurs sont des entiers entre 0 et 255 ou des hexadécimaux compris entre 0x00 et 0xFF.

### Valeurs de retour

Retourne un index de couleur.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagecoloresolvealpha() pour récupérer les couleurs d'une image

    <?php
    // Chargement de l'image
    $im = imagecreatefromgif('phplogo.gif');

    // Récupération des couleurs les plus proches de l'image
    $colors = array();
    $colors[] = imagecolorresolvealpha($im, 255, 255, 255, 0);
    $colors[] = imagecolorresolvealpha($im, 0, 0, 200, 127);

    // Affichage
    print_r($colors);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 89
        [1] => 85
    )

### Voir aussi

- imagecolorclosestalpha() - Retourne la couleur la plus proche, en tenant compte du canal alpha

# imagecolorset

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorset — Change la couleur dans une palette à l'index donné

### Description

function imagecolorset(
GdImage `$image`,
int `$color`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha` = 0
): ?false

Affecte la couleur spécifiée à l'index spécifié dans la palette. Cela est utile pour créer des effets similaires à un remplissage par diffusion dans les images à palette, sans le surcoût d'effectuer le remplissage réel.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`color`

  Un index de la palette.

`red`

  Valeur du composant rouge.

`green`

  Valeur du composant vert.

`blue`

  Valeur du composant bleu.

`alpha`

  Valeur du composant alpha.

### Valeurs de retour

La fonction retourne `null` en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagecolorset()

    <?php
    // Création d'une image de 300x100 pixels
    $im = imagecreate(300, 100);

    // Définit la couleur d'arrière-plan à rouge
    imagecolorallocate($im, 255, 0, 0);

    // Récupération de l'index de la couleur d'arrière-plan
    $bg = imagecolorat($im, 0, 0);

    // Définit la couleur d'arrière-plan à bleu
    imagecolorset($im, $bg, 0, 0, 255);

    // Affiche l'image dans le navigateur
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Voir aussi

- imagecolorat() - Retourne l'index de la couleur d'un pixel donné

# imagecolorsforindex

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorsforindex — Retourne la couleur associée à un index

### Description

function imagecolorsforindex(GdImage `$image`, int `$color`): array

Retourne la couleur associée à un index spécifié.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`color`

  L'index de la couleur.

### Valeurs de retour

Retourne un tableau associatif avec les clés `"red"`, `"green"`, `"blue"` et `"alpha"` qui contiennent les valeurs pour l'index de la couleur spécifiée.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
8.0.0 | La fonction imagecolorsforindex() lance désormais une exception ValueError si `color` est hors plage ; antérieur à cela, `false` était retourné à la place.

### Exemples

Exemple #1 Exemple avec imagecolorsforindex()

    <?php

    // on ouvre une image
    $im = imagecreatefrompng('nexen.png');

    // on obtient une couleur
    $start_x = 40;
    $start_y = 50;
    $color_index = imagecolorat($im, $start_x, $start_y);

    // on la rend lisible
    $color_tran = imagecolorsforindex($im, $color_index);

    // quelle est-elle ?
    print_r($color_tran);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
       [red] => 226
       [green] => 222
       [blue] => 252
       [alpha] => 0
    )

### Voir aussi

- imagecolorat() - Retourne l'index de la couleur d'un pixel donné
- imagecolorexact() - Retourne l'index de la couleur donnée

# imagecolorstotal

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorstotal — Calcule le nombre de couleurs d'une palette

### Description

function imagecolorstotal(GdImage `$image`): int

Retourne le nombre de couleurs de la palette de l'image.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().

### Valeurs de retour

Retourne le nombre de couleurs de la palette pour l'image `image` ou 0 pour les images truecolor.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Récupération du nombre total de couleurs dans une image en utilisant la fonction imagecolorstotal()

    <?php
    // Création d'une instance d'image
    $im = imagecreatefromgif('php.gif');

    echo 'Nombre total de couleurs dans l\'image : ' . imagecolorstotal($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Nombre total de couleurs dans l'image : 128

### Voir aussi

- imagecolorat() - Retourne l'index de la couleur d'un pixel donné
- imagecolorsforindex() - Retourne la couleur associée à un index
- imageistruecolor() - Détermine si une image est une image truecolor

# imagecolortransparent

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolortransparent — Définit la couleur transparente

### Description

function imagecolortransparent(GdImage `$image`, ?int `$color` = `null`): int

Récupère ou définit la couleur transparente pour l'`image` fournie.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

L'identifiant de la nouvelle couleur transparente (ou l'actuelle, si aucune n'est spécifiée) est retourné. Si le paramètre `color` est `null`, et que l'image n'a pas de couleur transparente, l'identifiant retourné sera `-1`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
8.0.0 | `color` est désormais nullable.

### Exemples

Exemple #1 Exemple avec imagecolortransparent()

    <?php
    // Création d'une image de 55x30
    $im = imagecreatetruecolor(55, 30);
    $red = imagecolorallocate($im, 255, 0, 0);
    $black = imagecolorallocate($im, 0, 0, 0);

    // On rend l'arrière-plan transparent
    imagecolortransparent($im, $black);

    // On dessine un rectangle rouge
    imagefilledrectangle($im, 4, 4, 50, 25, $red);

    // On sauvegarde l'image
    imagepng($im, './imagecolortransparent.png');
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Notes

> Note: La transparence est copiée uniquement avec la fonction imagecopymerge() et les images en couleurs vraies, non pas avec la fonction imagecopy() ou les images de palette.

> Note:

> La couleur de transparence est une propriété de l'image, elle n'est pas une propriété de la couleur. Une fois que l'on a défini la couleur de transparence, chaque région de l'image de cette couleur que l'on a dessinée précédemment sera transparente.

# imageconvolution

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

imageconvolution — Applique une matrice de convolution 3x3, en utilisant un coefficient et un décalage

### Description

function imageconvolution(
GdImage `$image`,
array `$matrix`,
float `$divisor`,
float `$offset`
): bool

Applique une matrice de convolution sur l'image, en utilisant le coefficient et le décalage donnés.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`matrix`

  Une matrice 3x3 : un tableau contenant trois tableaux de trois nombres à virgule flottante.

`divisor`

  Le diviseur du résultat de la convolution, utilisé pour la normalisation.

`offset`

  Le décalage de couleur.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Embossage du logo PHP.net

    <?php
    $image = imagecreatefromgif('http://www.php.net/images/php.gif');

    $emboss = array(array(2, 0, 0), array(0, -1, 0), array(0, 0, -1));
    imageconvolution($image, $emboss, 1, 127);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

L'exemple ci-dessus va afficher :

Exemple #2 Flou gaussien

    <?php
    $image = imagecreatetruecolor(180,40);

    // Écrit le texte et applique un flou gaussien sur l'image
    imagestring($image, 5, 10, 8, 'Texte flou gaussien', 0x00ff00);
    $gaussian = array(array(1.0, 2.0, 1.0), array(2.0, 4.0, 2.0), array(1.0, 2.0, 1.0));
    imageconvolution($image, $gaussian, 16, 0);

    // Réécrit le texte pour la comparaison
    imagestring($image, 5, 10, 18, 'Texte flou gaussien', 0x00ff00);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

L'exemple ci-dessus va afficher :

### Voir aussi

- imagefilter() - Applique un filtre à une image

# imagecopy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopy — Copie une partie d'une image

### Description

function imagecopy(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`
): true

Copie une partie de l'image `src_image` sur l'image de destination `dst_image`, en commençant aux coordonnées `src_x`, `src_y` et sur la largeur de `src_width` et la hauteur de `src_height`. La portion ainsi définie sera copiée et placée aux coordonnées `dst_x` et `dst_y`.

### Liste de paramètres

`dst_image`

  Ressource cible de l'image.

`src_image`

  Ressource source de l'image.

`dst_x`

  Coordonnée x du point de destination.

`dst_y`

  Coordonnée y du point de destination.

`src_x`

  Coordonnée x du point source.

`src_y`

  Coordonnée y du point source.

`src_width`

  Largeur de la source.

`src_height`

  Hauteur de la source.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `dst_image` et `src_image` attendent désormais des instances de GdImage ; auparavant, des resources étaient attendues.

### Exemples

Exemple #1 On coupe le logo PHP.net

    <?php
    // Création des instances d'image
    $src = imagecreatefromgif('php.gif');
    $dest = imagecreatetruecolor(80, 40);

    // Copie
    imagecopy($dest, $src, 0, 0, 20, 13, 80, 40);

    // Affichage et libération de la mémoire
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagecrop() - Recadre une image sur le rectangle donné

# imagecopymerge

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecopymerge — Copie et fusionne une partie d'une image

### Description

function imagecopymerge(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

Copie une partie de l'image `src_image` dans l'image de destination `dst_image` en commençant aux coordonnées (`src_x`, `src_y`), avec la largeur `src_width` et la hauteur `src_height`. La zone de l'image ainsi définie sera copiée aux coordonnées (`dst_x`, `dst_y`), dans l'image de destination.

### Liste de paramètres

`dst_image`

  Ressource cible de l'image.

`src_image`

  Ressource source de l'image.

`dst_x`

  X : coordonnée du point de destination.

`dst_y`

  Y : coordonnée du point de destination.

`src_x`

  X : coordonnée du point source.

`src_y`

  Y : coordonnée du point source.

`src_width`

  Largeur de la source.

`src_height`

  Hauteur de la source.

`pct`
  Les deux images seront fusionnées suivant le paramètre `pct`, qui peut valoir de 0 à 100. Si `pct` = 0, aucune action n'est faite, alors que si `pct` = 100, imagecopymerge() se comporte de manière identique à imagecopy() pour les images de palette, à l'exception du fait qu'elle ignore les composants alpha, tandis qu'elle implémente la transparence alpha pour les images en couleurs vraies.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `dst_image` et `src_image` attendent désormais des instances de GdImage ; auparavant, des resources étaient attendues.

### Exemples

Exemple #1 Fusionne 2 copies du logo PHP.net avec 75% de transparence

    <?php
    // Création des instances d'image
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Copie et fusionne
    imagecopymerge($dest, $src, 10, 10, 0, 0, 100, 47, 75);

    // Affichage
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopymergegray — Copie et fusionne une partie d'une image en niveaux de gris

### Description

function imagecopymergegray(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

imagecopymergegray() copie une partie de l'image `src_image` dans l'image de destination `dst_image` commençant aux coordonnées (`src_x`, `src_y`), avec la largeur `src_width` et la hauteur `src_height`. La zone de l'image ainsi définie sera copiée aux coordonnées (`dst_x`, `dst_y`), dans l'image de destination.

Cette fonction est identique à la fonction imagecopymerge(), hormis le fait que lors de la fusion, la teinte de la source est conservée en convertissant les pixels de destination en niveaux de gris avant l'opération de copie.

### Liste de paramètres

`dst_image`

  Ressource cible de l'image.

`src_image`

  Ressource source de l'image.

`dst_x`

  X : coordonnée du point de destination.

`dst_y`

  Y : coordonnée du point de destination.

`src_x`

  X : coordonnée du point source.

`src_y`

  Y : coordonnée du point source.

`src_width`

  Largeur de la source.

`src_height`

  Hauteur de la source.

`pct`
  Le paramètre `src_image` sera converti en niveaux de gris selon le paramètre `pct` où 0 correspond à une conversion totale en niveaux de gris et 100 ne modifie rien. Lorsque `pct` = 100, cette fonction se comporte de manière identique à la fonction imagecopy() pour les images en palette, à l'exception du fait qu'elle ignore les composants alpha, alors qu'elle implémente la transparence alpha pour les images en couleurs vraies.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `dst_image` et `src_image` attendent désormais des instances de GdImage ; auparavant, des resources étaient attendues.

### Exemples

Exemple #1 Exemple avec imagecopymergegray()

    <?php
    // Création des instances d'image
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Copie et fusionne - Gris = 20%
    imagecopymergegray($dest, $src, 10, 10, 0, 0, 100, 47, 20);

    // Affichage et libère la mémoire
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopyresampled — Copie, redimensionne, rééchantillonne une image

### Description

function imagecopyresampled(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

imagecopyresampled() copie une zone rectangulaire de l'image `src_image` vers l'image `dst_image`. Durant la copie, la zone est rééchantillonnée de manière à conserver la clarté de l'image durant une réduction.

En d'autres termes, imagecopyresampled() prendra une forme rectangulaire `src_image` d'une largeur de `src_width` et d'une hauteur `src_height` à la position (`src_x`,`src_y`) et le placera dans une zone rectangulaire `dst_image` d'une largeur de `dst_width` et d'une hauteur de `dst_height` à la position (`dst_x`,`dst_y`).

Si les hauteurs et largeurs des source et destination diffèrent, l'image copiée sera étirée de manière appropriée. Les coordonnées sont celles du coin supérieur gauche. imagecopyresampled() peut servir à copier des zones d'une image vers elle-même, (si `dst_image` est la même que `src_image`) mais si les régions se chevauchent, les résultats sont imprévisibles.

### Liste de paramètres

`dst_image`

  Ressource cible de l'image.

`src_image`

  Ressource source de l'image.

`dst_x`

  Coordonnée x du point de destination.

`dst_y`

  Coordonnée y du point de destination.

`src_x`

  Coordonnée x du point source.

`src_y`

  Coordonnée y du point source.

`dst_width`

  Largeur de la destination.

`dst_height`

  Hauteur de la destination.

`src_width`

  Largeur de la source.

`src_height`

  Hauteur de la source.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.5.0 | Le type de retour est désormais `true` ; auparavant, il s'agissait de bool.
8.0.0 | `dst_image` et `src_image` attendent désormais des instances de GdImage ; auparavant, des resources étaient attendues.

### Exemples

Exemple #1 Exemple simple

Cet exemple redimensionne une image à la moitié de sa taille originale.

    <?php
    // Le fichier
    $filename = 'test.jpg';
    $percent = 0.5;

    // Content type
    header('Content-Type: image/jpeg');

    // Calcul des nouvelles dimensions
    list($width, $height) = getimagesize($filename);
    $new_width = $width * $percent;
    $new_height = $height * $percent;

    // Redimensionnement
    $image_p = imagecreatetruecolor($new_width, $new_height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $new_width, $new_height, $width, $height);

    // Affichage
    imagejpeg($image_p, null, 100);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Exemple #2 Redimensionnement proportionnel d'une image

Cet exemple affichera une image avec une largeur ou une hauteur maximale de 200 pixels.

    <?php
    // Le fichier
    $filename = 'test.jpg';

    // Définition de la largeur et de la hauteur maximale
    $width = 200;
    $height = 200;

    // Content type
    header('Content-Type: image/jpeg');

    // Calcul des nouvelles dimensions
    list($width_orig, $height_orig) = getimagesize($filename);

    $ratio_orig = $width_orig/$height_orig;

    if ($width/$height > $ratio_orig) {
       $width = $height*$ratio_orig;
    } else {
       $height = $width/$ratio_orig;
    }

    // Redimensionnement
    $image_p = imagecreatetruecolor($width, $height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig);

    // Affichage
    imagejpeg($image_p, null, 100);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Notes

> Note:

> Il y a un problème dû aux limitations de la taille de la palette (255 + 1 couleurs différentes). Filtrer ou rééchantillonner une image demande plus de 255 couleurs, une approximation est alors utilisée pour calculer le nouveau nombre de couleurs. Avec une palette, si une nouvelle couleur ne peut être allouée, la couleur la plus proche (en théorie) est utilisée. Ce n'est pas toujours la couleur la plus proche visuellement. Cela peut générer des problèmes étranges, comme des images blanches. Pour éviter ce problème, il faut utiliser une image TrueColor, telle que celle générée par la fonction imagecreatetruecolor().

### Voir aussi

- imagecopyresized() - Copie et redimensionne une partie d'une image
- imagescale() - Met à l'échelle une image en utilisant une hauteur et une largeur fournies
- imagecrop() - Recadre une image sur le rectangle donné

# imagecopyresized

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopyresized — Copie et redimensionne une partie d'une image

### Description

function imagecopyresized(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

imagecopyresized() copie une partie rectangulaire d'une image dans une autre image de destination. `dst_image` est l'image de destination, `src_image` est l'image source.

En d'autres termes, imagecopyresized() prendra une zone rectangulaire de `src_image` d'une largeur de `src_width` et d'une hauteur `src_height` à la position (`src_x`,`src_y`) et la placera dans une zone rectangulaire de `dst_image` d'une largeur de `dst_width` et d'une hauteur de `dst_height` à la position (`dst_x`,`dst_y`).

Si les coordonnées et les dimensions de la source et de la destination diffèrent, un étirement ou un rétrécissement approprié du fragment d'image sera effectué. Les coordonnées sont définies par rapport au coin supérieur gauche. Cette fonction peut être utilisée pour copier des régions à l'intérieur d'une même image (si `dst_image` et `src_image` sont identiques), mais si les régions se chevauchent, les résultats seront imprévisibles.

### Liste de paramètres

`dst_image`

  Ressource cible de l'image.

`src_image`

  Ressource source de l'image.

`dst_x`

  Coordonnée x du point de destination.

`dst_y`

  Coordonnée y du point de destination.

`src_x`

  Coordonnée x du point source.

`src_y`

  Coordonnée y du point source.

`dst_width`

  Largeur de la destination.

`dst_height`

  Hauteur de la destination.

`src_width`

  Largeur de la source.

`src_height`

  Hauteur de la source.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `dst_image` et `src_image` attendent désormais des instances de GdImage ; auparavant, des resources étaient attendues.

### Exemples

Exemple #1 Redimensionnement d'une image

Cet exemple affichera l'image redimensionnée à la moitié de sa taille d'origine.

    <?php
    // Fichier et nouvelle taille
    $filename = 'test.jpg';
    $percent = 0.5;

    // Content type
    header('Content-Type: image/jpeg');

    // Calcul des nouvelles dimensions
    list($width, $height) = getimagesize($filename);
    $newwidth = $width * $percent;
    $newheight = $height * $percent;

    // Chargement
    $thumb = imagecreatetruecolor($newwidth, $newheight);
    $source = imagecreatefromjpeg($filename);

    // Redimensionnement
    imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);

    // Affichage
    imagejpeg($thumb);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

L'image sera affichée à la moitié de sa taille, bien qu'une meilleure qualité puisse être obtenue en utilisant imagecopyresampled().

### Notes

> Note:

> Il y a un problème dû aux limitations des images à palette (255 + 1 couleurs). Le rééchantillonnage ou le filtrage d'une image nécessite généralement plus de 255 couleurs, une sorte d'approximation est alors utilisée pour calculer le nouveau pixel rééchantillonné et sa couleur. Avec une image à palette, une tentative d'allocation d'une nouvelle couleur est effectuée et, en cas d'échec, la couleur la plus proche (en théorie) est choisie. Ce n'est pas toujours la couleur visuellement la plus proche. Cela peut produire un résultat étrange, comme des images blanches (ou visuellement blanches). Pour éviter ce problème, il faut utiliser une image TrueColor comme image de destination, telle qu'une image créée par imagecreatetruecolor().

### Voir aussi

- imagecopyresampled() - Copie, redimensionne, rééchantillonne une image
- imagescale() - Met à l'échelle une image en utilisant une hauteur et une largeur fournies
- imagecrop() - Recadre une image sur le rectangle donné

# imagecreate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreate — Crée une nouvelle image à palette

### Description

function imagecreate(int `$width`, int `$height`): GdImage|false

imagecreate() retourne un identifiant d'image représentant une image vide de la taille spécifiée.

En général, il est recommandé d'utiliser la fonction imagecreatetruecolor() au lieu de la fonction imagecreate() afin que l'opération sur l'image s'effectue avec la plus haute qualité possible. Pour produire une image à palette, la fonction imagetruecolortopalette() doit être appelée immédiatement avant l'enregistrement de l'image avec la fonction imagepng() ou la fonction imagegif().

### Liste de paramètres

`width`

  La largeur de l'image.

`height`

  La hauteur de l'image.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.

### Exemples

Exemple #1 Création d'un nouveau flux d'image GD et affichage d'une image.

    <?php
    header("Content-Type: image/png");
    $im = @imagecreate(110, 20)
        or die("Impossible d'initialiser le nouveau flux d'image GD");
    $background_color = imagecolorallocate($im, 0, 0, 0);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Une simple chaîne de texte", $text_color);
    imagepng($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies

# imagecreatefromavif

(PHP 8 >= 8.1.0)

imagecreatefromavif — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefromavif(string `$filename`): GdImage|false

imagecreatefromavif() retourne un objet image représentant l'image obtenue à partir du fichier `filename` donné.

### Liste de paramètres

`filename`

  Chemin vers l'image matricielle AVIF.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

# imagecreatefrombmp

(PHP 7 >= 7.2.0, PHP 8)

imagecreatefrombmp — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefrombmp(string `$filename`): GdImage|false

imagecreatefrombmp() retourne un identifiant d'image représentant l'image obtenue à partir du nom de fichier fourni.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin de l'image BMP.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieurement, une resource était retournée.

### Exemples

Exemple #1 Convertit une image BMP en image PNG en utilisant imagecreatefrombmp()

    <?php
    // Charge le fichier BMP
    $im = imagecreatefrombmp('./example.bmp');

    // Le convertit en fichier PNG avec les paramètres par défaut
    imagepng($im, './example.png');
    ?>

# imagecreatefromgd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd — Crée une nouvelle image à partir d'un fichier GD ou d'une URL

### Description

function imagecreatefromgd(string `$filename`): GdImage|false

Crée une nouvelle image depuis un fichier GD ou une URL.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers un fichier GD.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieurement, une resource était retournée.

### Exemples

Exemple #1 Exemple avec imagecreatefromgd()

    <?php
    // Charge une image GD
    $im = @imagecreatefromgd('./test.gd');

    // Vérifie si l'image est bien chargée
    if(!$im)
    {
         die('Impossible de charger l\'image GD');
    }

    // Des opérations sur l'image ici

    // Sauvegarde de l'image
    imagegd($im, './test_updated.gd');
    ?>

### Notes

Avertissement

Les formats d'image GD et GD2 sont des formats d'images propriétaire de libgd. Ils doivent être considérés obsolète, et devraient seulement être utilisé lors du développement et la phase de test.

# imagecreatefromgd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2 — Crée une nouvelle image à partir d'un fichier GD2 ou d'une URL

### Description

function imagecreatefromgd2(string `$filename`): GdImage|false

Crée une nouvelle image depuis un fichier GD2 ou une URL.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers l'image GD2.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieur à cela, une resource était retournée.

### Exemples

Exemple #1 Exemple avec imagecreatefromgd2()

    <?php
    // Charge l'image gd2
    $im = imagecreatefromgd2('./test.gd2');

    // Applique un effet sur l'image, dans ce cas
    // on inverse les couleurs de l'image
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_NEGATE);
    }

    // Sauvegarde de l'image
    imagegd2($im, './test_updated.gd2');
    ?>

### Notes

Avertissement

Les formats d'image GD et GD2 sont des formats d'images propriétaire de libgd. Ils doivent être considérés obsolète, et devraient seulement être utilisé lors du développement et la phase de test.

# imagecreatefromgd2part

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2part — Crée une nouvelle image à partir d'une partie de fichier GD2 ou d'une URL

### Description

function imagecreatefromgd2part(
string `$filename`,
int `$x`,
int `$y`,
int `$width`,
int `$height`
): GdImage|false

Crée une nouvelle image à partir d'une partie de fichier GD2 ou d'une URL.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers l'image GD2.

`x`

  Coordonnée en X du point source.

`y`

  Coordonnée en Y du point source.

`width`

  Largeur de la source.

`height`

  Hauteur de la source.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieur à PHP 8.0.0, une resource était retournée.

### Exemples

Exemple #1 Exemple avec imagecreatefromgd2part()

    <?php
    // Pour cet exemple, nous avons tout d'abord besoin des dimensions de l'image
    $image = getimagesize('./test.gd2');

    // Création de l'instance d'image maintenant que nous avons les dimensions
    $im = imagecreatefromgd2part('./test.gd2', 4, 4, ($image[0] / 2) - 6, ($image[1] / 2) - 6);

    // Opération sur l'image : ici, nous appliquons un effet de relief
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_EMBOSS);
    }

    // Sauvegarde de l'image optimisée
    imagegd2($im, './test_emboss.gd2');
    ?>

### Notes

Avertissement

Les formats d'image GD et GD2 sont des formats d'images propriétaire de libgd. Ils doivent être considérés obsolète, et devraient seulement être utilisé lors du développement et la phase de test.

# imagecreatefromgif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromgif — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefromgif(string `$filename`): GdImage|false

imagecreatefromgif() retourne un identifiant d'image qui représente l'image obtenue à partir du fichier dont le nom est donné par `filename`.

Attention

Lors de la lecture en mémoire de fichiers GIF animés, seule la première image est retournée dans l'objet image. La taille de l'image n'est pas forcément celle rapportée par getimagesize().

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers l'image GIF.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieur à PHP 8.0.0, une resource était retournée.

### Exemples

Exemple #1 Exemple de prise en charge d'une erreur lors du chargement d'une image GIF

    <?php
    function LoadGif($imgname)
    {
        /* Tente d'ouvrir l'image */
        $im = @imagecreatefromgif($imgname);

        /* Traitement si l'ouverture a échoué */
        if(!$im)
        {
            /* Création d'une image vide */
            $im = imagecreatetruecolor (150, 30);
            $bgc = imagecolorallocate ($im, 255, 255, 255);
            $tc = imagecolorallocate ($im, 0, 0, 0);

            imagefilledrectangle ($im, 0, 0, 150, 30, $bgc);

            /* Affiche un message d'erreur dans l'image */
            imagestring ($im, 1, 5, 5, 'Erreur de chargement ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/gif');

    $img = LoadGif('bogus.image');

    imagegif($img);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imagecreatefromjpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromjpeg — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefromjpeg(string `$filename`): GdImage|false

imagecreatefromjpeg() retourne un identifiant d'image représentant l'image obtenue à partir du fichier `filename` donné.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers l'image JPEG.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieurement, une resource était retournée.

### Exemples

Exemple #1 Exemple de gestion d'une erreur lors du chargement d'une image JPEG

    <?php
    function LoadJpeg($imgname)
    {
        /* Tente d'ouvrir l'image */
        $im = @imagecreatefromjpeg($imgname);

        /* Traitement en cas d'échec */
        if(!$im)
        {
            /* Création d'une image vide */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* On y affiche un message d'erreur */
            imagestring($im, 1, 5, 5, 'Erreur de chargement ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/jpeg');

    $img = LoadJpeg('bogus.image');

    imagejpeg($img);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imagecreatefrompng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefrompng — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefrompng(string `$filename`): GdImage|false

imagecreatefrompng() retourne un identifiant d'image représentant l'image obtenue à partir du fichier `filename`.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers l'image PNG.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieurement, une resource était retournée.

### Exemples

Exemple #1 Exemple de gestion d'une erreur lors du chargement d'une image PNG

    <?php
    function LoadPNG($imgname)
    {
        /* Tente d'ouvrir l'image */
        $im = @imagecreatefrompng($imgname);

        /* Traitement en cas d'échec */
        if(!$im)
        {
            /* Création d'une image vide */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* On y affiche un message d'erreur */
            imagestring($im, 1, 5, 5, 'Erreur de chargement ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/png');

    $img = LoadPNG('bogus.image');

    imagepng($img);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

imagecreatefromstring — Crée une image à partir d'une chaîne

### Description

function imagecreatefromstring(string `$data`): GdImage|false

imagecreatefromstring() retourne un identifiant d'image représentant l'image obtenue depuis la chaîne `data`. Ces types seront automatiquement détectés si la compilation de PHP les supporte : JPEG, PNG, GIF, BMP, WBMP, GD2, WEBP et AVIF.

### Liste de paramètres

`data`

  Une chaîne contenant les données de l'image.

### Valeurs de retour

Un objet d'image sera retourné en cas de succès. `false` est retourné si le type de l'image n'est pas supporté, si les données ne sont pas dans un format reconnu ou si l'image est corrompue et donc ne peut être chargée.

### Erreurs / Exceptions

imagecreatefromstring() émet une erreur de niveau E_WARNING si les données ne sont pas dans un format reconnu.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieurement, une resource était retournée.
7.3.0 | WEBP est désormais supporté (si supporté par la libgd utilisée).

### Exemples

Exemple #1 Exemple avec imagecreatefromstring()

    <?php
    $data = 'iVBORw0KGgoAAAANSUhEUgAAABwAAAASCAMAAAB/2U7WAAAABl'
           . 'BMVEUAAAD///+l2Z/dAAAASUlEQVR4XqWQUQoAIAxC2/0vXZDr'
           . 'EX4IJTRkb7lobNUStXsB0jIXIAMSsQnWlsV+wULF4Avk9fLq2r'
           . '8a5HSE35Q3eO2XP1A1wQkZSgETvDtKdQAAAABJRU5ErkJggg==';
    $data = base64_decode($data);

    $im = imagecreatefromstring($data);
    if ($im !== false) {
        header('Content-Type: image/png');
        imagepng($im);
    }
    else {
        echo 'Une erreur est survenue.';
    }
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagecreatefromjpeg() - Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefrompng() - Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefromgif() - Crée une nouvelle image depuis un fichier ou une URL
- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies

# imagecreatefromtga

(PHP 7 >= 7.4.0, PHP 8)

imagecreatefromtga — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefromtga(string `$filename`): GdImage|false

imagecreatefromtga() retourne un objet image représentant l'image obtenue à partir du nom de fichier donné.

### Liste de paramètres

`filename`

  Chemin d'accès à l'image TGA Truevision.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; précédemment, une resource était retournée.

# imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromwbmp — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefromwbmp(string `$filename`): GdImage|false

imagecreatefromwbmp() retourne un identifiant d'image représentant l'image obtenue à partir du nom de fichier donné.

> Note: Les images WBMP sont des Wireless Bitmaps, et non des Windows Bitmaps. Ces dernières peuvent être chargées grâce à imagecreatefrombmp().

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers l'image WBMP.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.

### Exemples

Exemple #1 Exemple de gestion d'une erreur lors du chargement d'une image WBMP

    <?php
    function LoadWBMP($imgname)
    {
        /* Tente d'ouvrir l'image */
        $im = @imagecreatefromwbmp($imgname);

        /* Traitement en cas d'échec */
        if(!$im)
        {
            /* Création d'une image vide */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* On y affiche un message d'erreur */
            imagestring($im, 1, 5, 5, 'Erreur de chargement ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/vnd.wap.wbmp');

    $img = LoadWBMP('bogus.image');

    imagewbmp($img);
    ?>

# imagecreatefromwebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagecreatefromwebp — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefromwebp(string `$filename`): GdImage|false

imagecreatefromwebp() retourne un identifiant d'image représentant l'image obtenue depuis le fichier fourni. Il est à noter que les fichiers WebP animés ne peuvent pas être lus.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers l'image WebP.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieurement, une resource était retournée.

### Exemples

Exemple #1 Convertit une image WebP en une image jpeg en utilisant la fonction imagecreatefromwebp()

    <?php
    // Charge le fichier WebP
    $im = imagecreatefromwebp('./example.webp');

    // On la convertit en un fichier jpeg avec une qualité à 100%
    imagejpeg($im, './example.jpeg', 100);
    ?>

# imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxbm — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefromxbm(string `$filename`): GdImage|false

imagecreatefromxbm() retourne un identifiant d'image représentant l'image obtenue à partir du fichier `filename`.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers l'image XBM.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; antérieurement, une resource était retournée.

### Exemples

Exemple #1 Convertit une image XBM en une image PNG en utilisant la fonction imagecreatefromxbm()

    <?php
    // Chargement du fichier XBM
    $xbm = imagecreatefromxbm('./example.xbm');

    // On la convertit en fichier PNG
    imagepng($xbm, './example.png');
    ?>

# imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxpm — Crée une nouvelle image depuis un fichier ou une URL

### Description

function imagecreatefromxpm(string `$filename`): GdImage|false

imagecreatefromxpm() retourne un identifiant d'image représentant l'image obtenue à partir du fichier `filename`.

Astuce

Vous pouvez utiliser une URL comme nom de fichier avec cette fonction, si le gestionnaire fopen a été activé. Voyez fopen() pour plus de détails sur la façon de spécifier le nom du fichier. Reportez-vous aux Liste des protocoles et des gestionnaires supportés pour plus d'informations sur les capacités des différents gestionnaires, les notes sur leur utilisation, ainsi que les informations sur les variables prédéfinies qu'elles fournissent.

### Liste de paramètres

`filename`

  Chemin vers l'image XPM.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.

### Exemples

Exemple #1 Création d'une instance d'image en utilisant la fonction imagecreatefromxpm()

    <?php
    // Vérifie le support XPM
    if(!(imagetypes() & IMG_XPM))
    {
        die('Le support pour xpm n\'a pas été trouvé !');
    }

    // Création de l'instance d'image
    $xpm = imagecreatefromxpm('./example.xpm');

    // Effectuer ici les opérations sur l'image

    // PHP ne supporte pas l'écriture des images xpm
    // aussi, dans ce cas, l'image est sauvegardée
    // dans un fichier jpeg avec une qualité de 100%
    imagejpeg($xpm, './example.jpg', 100);
    ?>

# imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecreatetruecolor — Crée une nouvelle image en couleurs vraies

### Description

function imagecreatetruecolor(int `$width`, int `$height`): GdImage|false

imagecreatetruecolor() retourne un objet image représentant une image noire de la taille spécifiée.

### Liste de paramètres

`width`

  Largeur de l'image.

`height`

  Hauteur de l'image.

### Valeurs de retour

Retourne un objet d'image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.

### Exemples

Exemple #1 Création d'un nouveau flux d'image GD et affichage d'une image.

    <?php
    header ('Content-Type: image/png');
    $im = @imagecreatetruecolor(120, 20)
          or die('Impossible de créer un flux d\'image GD');
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Une simple chaîne de texte', $text_color);
    imagepng($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagecreate() - Crée une nouvelle image à palette

# imagecrop

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecrop — Recadre une image sur le rectangle donné

### Description

function imagecrop(GdImage `$image`, array `$rectangle`): GdImage|false

Recadre une image à la zone rectangulaire donnée et retourne l'image résultante. L'`image` n'est pas modifiée.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`rectangle`

  Le rectangle de recadrage sous forme de array contenant les clés `x`, `y`, `width` et `height`.

### Valeurs de retour

Retourne l'objet de l'image recadrée en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.

### Exemples

Exemple #1 Exemple avec imagecrop()

Cet exemple montre comment rogner une image sur une zone carrée.

    <?php
    $im = imagecreatefrompng('example.png');
    $size = min(imagesx($im), imagesy($im));
    $im2 = imagecrop($im, ['x' => 0, 'y' => 0, 'width' => $size, 'height' => $size]);
    if ($im2 !== FALSE) {
        imagepng($im2, 'example-cropped.png');
    }
    ?>

### Voir aussi

- imagecropauto() - Recadre une image automatiquement en utilisant un des modes disponibles

# imagecropauto

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecropauto — Recadre une image automatiquement en utilisant un des modes disponibles

### Description

function imagecropauto(
GdImage `$image`,
int `$mode` = `IMG_CROP_DEFAULT`,
float `$threshold` = 0.5,
int `$color` = -1
): GdImage|false

Rogne automatiquement une image selon le `mode`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`mode`

  Une constante parmi :

  `IMG_CROP_DEFAULT`
    Identique à `IMG_CROP_TRANSPARENT`. Antérieurement à PHP 7.4.0, la bibliothèque libgd intégrée utilisait `IMG_CROP_SIDES` en tant que solution de repli, si l'image n'avait pas de couleur de transparence.
  `IMG_CROP_TRANSPARENT`
    Rogne le fond transparent.
  `IMG_CROP_BLACK`
    Rogne le fond noir.
  `IMG_CROP_WHITE`
    Rogne le fond blanc.
  `IMG_CROP_SIDES`
    Utilise les 4 coins de l'image pour tenter de détecter l'arrière-plan à rogner.
  `IMG_CROP_THRESHOLD`
    Rogne l'image en utilisant le seuil `threshold` et `color`.
`threshold`

  Spécifie la tolérance en pourcentage à utiliser lors de la comparaison de la couleur d'image et de la couleur à rogner. La méthode utilisée pour calculer la différence de couleur est basée sur la distance des couleurs dans le cube RVB(a).

  Utilisé uniquement en mode `IMG_CROP_THRESHOLD`.

  > Note: Antérieurement à PHP 7.4.0, la bibliothèque libgd intégrée utilisait un algorithme quelque peu différent, donc le même `threshold` produisait des résultats différents pour libgd système et intégré.

`color`

  Soit une valeur de couleur RVB, soit un index de palette.

  Utilisé uniquement en mode `IMG_CROP_THRESHOLD`.

### Valeurs de retour

Retourne l'objet de l'image rognée en cas de succès ou `false` si une erreur survient. `false` sera aussi retourné si toute l'image a été rognée.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.
7.4.0 | Le comportement de imagecropauto de la bibliothèque libgd intégrée a été synchronisé avec celle de libgd système : `IMG_CROP_DEFAULT` n'utilise plus `IMG_CROP_SIDES` comme solution de repli et la tolérance de rognage utilise désormais le même algorithme que libgd système.
7.4.0 | La valeur par défaut de `mode` a été modifiée en `IMG_CROP_AUTO`. Antérieurement, la valeur par défaut était `-1` qui correspond à `IMG_CROP_DEFAULT`, mais passer `-1` est désormais obsolète.

### Exemples

Exemple #1 Rognage automatique correct

Comme indiqué dans la section valeur de retour, imagecropauto() retourne `false` si l'image entière a été rognée. Dans cet exemple, nous avons un objet d'image `$im` qui ne devrait être automatiquement rogné que s'il y a quelque chose à rogner ; sinon, nous voulons conserver l'image originale.

    <?php
    $cropped = imagecropauto($im, IMG_CROP_DEFAULT);
    if ($cropped !== false) { // Si un nouvel objet d'image a été retourné
        $im = $cropped;       // et assigne l'image rognée à $im
    }
    ?>

### Voir aussi

- imagecrop() - Recadre une image sur le rectangle donné

# imagedashedline

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedashedline — Dessine une ligne pointillée

### Description

function imagedashedline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

imagedashedline() est obsolète. Il est préférable d'utiliser une combinaison des fonctions imagesetstyle() et imageline(). Le point 0, 0 est le coin en haut à gauche de l'image.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`x1`

  Coordonnée x du premier point.

`y1`

  Coordonnée y du premier point.

`x2`

  Coordonnée x du second point.

`y2`

  Coordonnée y du second point.

`color`

  La couleur de remplissage. Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagedashedline()

    <?php
    // Crée une image de 100x100 pixels
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Dessine une ligne verticale en pointillé
    imagedashedline($im, 50, 25, 50, 75, $white);

    // Sauvegarde l'image
    imagepng($im, './dashedline.png');
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Exemple #2 Alternative à la fonction imagedashedline()

    <?php
    // Crée une image de 100x100 pixels
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Définit le style : Les 4 premiers pixels sont blancs et les 4 suivants
    // sont transparents. Ceci va créer l'effet de pointillé
    $style = Array(
                    $white,
                    $white,
                    $white,
                    $white,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT
                    );

    imagesetstyle($im, $style);

    // Dessine la ligne pointillée
    imageline($im, 50, 25, 50, 75, IMG_COLOR_STYLED);

    // Sauvegarde de l'image
    imagepng($im, './imageline.png');
    ?>

### Voir aussi

- imagesetstyle() - Configure le style pour le dessin des lignes
- imageline() - Dessine une ligne

# imagedestroy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedestroy — Détruit une image

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 8.5.0. Dépendre de cette fonction est fortement déconseillé.

### Description

#[\Deprecated]
function imagedestroy(GdImage `$image`): true

> Note: Cette fonction n'a aucun effet. Antérieur à PHP 8.0.0, cette fonction était utilisé pour fermer une ressource.

Antérieur à PHP 8.0.0, imagedestroy() libérait toute la mémoire associée à la ressource `image`. À partir de la version 8.0.0, l'extension GD utilise des objets au lieu de ressources, et les objets ne peuvent pas être fermés explicitement.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.5.0 | Cette fonction a été rendue obsolète.
8.0.0 | Cette fonction est désormais un NOP.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Utilisation de imagedestroy() antérieur à PHP 8.0.0

    <?php
    // Crée une image de 100 x 100 pixels
    $im = imagecreatetruecolor(100, 100);

    // Modification et/ou sauvegarde de l'image

    // Libération de la mémoire associée
    imagedestroy($im);
    ?>

# imageellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imageellipse — Dessine une ellipse

### Description

function imageellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Dessine une ellipse centrée sur le point spécifié.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`center_x`

  X : coordonnée du centre.

`center_y`

  Y : coordonnée du centre.

`width`

  La largeur de l'ellipse.

`height`

  La hauteur de l'ellipse.

`color`

  La couleur de l'ellipse. Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imageellipse()

    <?php
    // Création d'une image vide
    $image = imagecreatetruecolor(400, 300);

    // Choix de la couleur d'arrière-plan
    $bg = imagecolorallocate($image, 0, 0, 0);

    // Remplit l'arrière-plan avec la couleur sélectionnée
    imagefill($image, 0, 0, $bg);

    // Choix de la couleur de l'ellipse
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // On dessine l'ellipse
    imageellipse($image, 200, 150, 300, 200, $col_ellipse);

    // On affiche l'image
    header("Content-type: image/png");
    imagepng($image);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Notes

> Note:

> imageellipse() ignore imagesetthickness().

### Voir aussi

- imagefilledellipse() - Dessine une ellipse pleine
- imagearc() - Dessine un arc

# imagefill

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefill — Remplissage par diffusion

### Description

function imagefill(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

Effectue un remplissage avec la couleur `color`, dans l'image `image`, à partir du point de coordonnées (`x`, `y`) (le coin supérieur gauche est l'origine (0,0)).

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`x`

  Coordonnée X du point de départ.

`y`

  Coordonnée Y du point de départ.

`color`

  La couleur de remplissage. Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagefill()

    <?php

    $im = imagecreatetruecolor(100, 100);

    // Définit le fond en rouge
    $red = imagecolorallocate($im, 255, 0, 0);
    imagefill($im, 0, 0, $red);

    header('Content-type: image/png');
    imagepng($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagecolorallocate() - Alloue une couleur pour une image

# imagefilledarc

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledarc — Dessine un arc partiel et le remplit

### Description

function imagefilledarc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`,
int `$style`
): true

Dessine un arc partiel, centré aux coordonnées spécifiées dans l'image fournie.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`center_x`

  X : coordonnée du centre.

`center_y`

  Y : coordonnée du centre.

`width`

  La largeur de l'arc.

`height`

  La hauteur de l'arc.

`start_angle`

  L'angle de début de l'arc, en degrés.

`end_angle`

  L'angle de fin de l'arc, en degrés. 0° est situé à la position de trois heures, et l'arc est dessiné dans le sens des aiguilles d'une montre.

`color`

  Un identificateur de couleur créé avec imagecolorallocate().

`style`

  Un OU bit à bit des possibilités suivantes :

  1. `IMG_ARC_PIE`
  2. `IMG_ARC_CHORD`
  3. `IMG_ARC_NOFILL`
  4. `IMG_ARC_EDGED`
  `IMG_ARC_PIE` et `IMG_ARC_CHORD` sont mutuellement exclusives ; `IMG_ARC_CHORD` ne fait que connecter les angles de début et de fin avec une ligne droite, tandis que `IMG_ARC_PIE` produit un bord arrondi. `IMG_ARC_NOFILL` indique que l'arc ou la corde devrait être tracé sans remplissage. `IMG_ARC_EDGED`, utilisé conjointement avec `IMG_ARC_NOFILL`, indique que les angles de début et de fin devraient être connectés au centre : c'est une bonne manière de tracer le contour (au lieu de remplir) d'une « part de camembert ».

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Création d'un camembert en 3D

    <?php

    // Création de l'image
    $image = imagecreatetruecolor(100, 100);

    // Allocation de quelques couleurs
    $white    = imagecolorallocate($image, 0xFF, 0xFF, 0xFF);
    $gray     = imagecolorallocate($image, 0xC0, 0xC0, 0xC0);
    $darkgray = imagecolorallocate($image, 0x90, 0x90, 0x90);
    $navy     = imagecolorallocate($image, 0x00, 0x00, 0x80);
    $darknavy = imagecolorallocate($image, 0x00, 0x00, 0x50);
    $red      = imagecolorallocate($image, 0xFF, 0x00, 0x00);
    $darkred  = imagecolorallocate($image, 0x90, 0x00, 0x00);

    // Création de l'effet 3D
    for ($i = 60; $i > 50; $i--) {
       imagefilledarc($image, 50, $i, 100, 50, 0, 45, $darknavy, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 45, 75 , $darkgray, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 75, 360 , $darkred, IMG_ARC_PIE);
    }

    imagefilledarc($image, 50, 50, 100, 50, 0, 45, $navy, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 45, 75 , $gray, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 75, 360 , $red, IMG_ARC_PIE);

    // Affichage de l'image
    header('Content-type: image/png');
    imagepng($image);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledellipse — Dessine une ellipse pleine

### Description

function imagefilledellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Dessine une ellipse centrée sur les coordonnées spécifiées sur l'image fournie.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`center_x`

  X : coordonnée du centre.

`center_y`

  Y : coordonnée du centre.

`width`

  La largeur de l'ellipse.

`height`

  La hauteur de l'ellipse.

`color`

  La couleur de remplissage. Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagefilledellipse()

    <?php

    // Nouvelle image
    $image = imagecreatetruecolor(400, 300);

    // Couleur de fond
    $bg = imagecolorallocate($image, 0, 0, 0);

    // Couleur de remplissage de l'ellipse
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // On dessine l'ellipse blanche
    imagefilledellipse($image, 200, 150, 300, 200, $col_ellipse);

    // On affiche l'image
    header("Content-type: image/png");
    imagepng($image);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Notes

> Note:

> imagefilledellipse() ignore imagesetthickness().

### Voir aussi

- imageellipse() - Dessine une ellipse
- imagefilledarc() - Dessine un arc partiel et le remplit

# imagefilledpolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledpolygon — Dessine un polygone rempli

### Description

Signature à partir de PHP 8.0.0 (non supportée avec les arguments nommés)

function imagefilledpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Signature alternative (obsolète à partir de PHP 8.1.0)

function imagefilledpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagefilledpolygon() dessine un polygone rempli dans l'image `image`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`points`

  Un tableau contenant successivement les coordonnées `x` et `y` des sommets du polygone.

`num_points`

  Nombre total de points (sommets), qui doit être d'au moins 3.

  Si ce paramètre est omis conformément à la deuxième signature, `points` doit avoir un nombre pair d'éléments, et `num_points` est supposé valoir `count($points)/2`.
`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `num_points` a été rendu obsolète.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagefilledpolygon()

    <?php
    // Définition du tableau de points pour le polygone
    $values = array(
                40,  50,  // Point 1 (x, y)
                20,  240, // Point 2 (x, y)
                60,  60,  // Point 3 (x, y)
                240, 20,  // Point 4 (x, y)
                50,  40,  // Point 5 (x, y)
                10,  10   // Point 6 (x, y)
                );

    // Création d'une image
    $image = imagecreatetruecolor(250, 250);

    // Alloue quelques couleurs
    $bg   = imagecolorallocate($image, 0, 0, 0);
    $blue = imagecolorallocate($image, 0, 0, 255);

    // Remplit l'arrière-plan
    imagefilledrectangle($image, 0, 0, 249, 249, $bg);

    // Dessine le polygone
    imagefilledpolygon($image, $values, $blue);

    // Affichage de l'image
    header('Content-type: image/png');
    imagepng($image);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagepolygon() - Dessine un polygone

# imagefilledrectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledrectangle — Dessine un rectangle rempli

### Description

function imagefilledrectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Dessine un rectangle de couleur `color` dans l'image `image`, en commençant par le sommet supérieur gauche (1) et finissant au sommet inférieur droit (2). Le coin supérieur gauche est l'origine (0, 0).

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`x1`

  Coordonnée x du point 1.

`y1`

  Coordonnée y du point 1.

`x2`

  Coordonnée x du point 2.

`y2`

  Coordonnée y du point 2.

`color`

  La couleur de remplissage. Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagefilledrectangle()

    <?php
    // Création d'une image de 55x30 pixels
    $im = imagecreatetruecolor(55, 30);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Dessine un rectangle blanc
    imagefilledrectangle($im, 4, 4, 50, 25, $white);

    // Sauvegarde l'image
    imagepng($im, './imagefilledrectangle.png');
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imagefilltoborder

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilltoborder — Remplit une région avec une couleur spécifique

### Description

function imagefilltoborder(
GdImage `$image`,
int `$x`,
int `$y`,
int `$border_color`,
int `$color`
): true

imagefilltoborder() remplit avec la couleur `color` toute la région à l'intérieur de la région limitée par la couleur `border_color`. Le point de départ est (`x`, `y`) (le coin supérieur gauche est l'origine (0,0)) et la couleur de la région est `color`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`x`

  Coordonnée x du point de départ.

`y`

  Coordonnée y du point de départ.

`border_color`

  La couleur de la bordure. Un identificateur de couleur créé avec imagecolorallocate().

`color`

  La couleur de remplissage. Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Remplissage d'une ellipse avec une couleur

    <?php
    // Création d'un gestionnaire d'image, puis définit la couleur d'arrière-plan
    // à blanc
    $im = imagecreatetruecolor(100, 100);
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 255, 255, 255));

    // Dessine une ellipse dont les bordures seront noires
    imageellipse($im, 50, 50, 50, 50, imagecolorallocate($im, 0, 0, 0));

    // Définit la bordure et remplit l'ellipse de la couleur choisie
    $border = imagecolorallocate($im, 0, 0, 0);
    $fill = imagecolorallocate($im, 255, 0, 0);

    // Remplit la sélection
    imagefilltoborder($im, 50, 50, $border, $fill);

    // Affichage et libération de la mémoire
    header('Content-type: image/png');
    imagepng($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Notes

L'algorithme ne se souvient pas explicitement de quels pixels ont déjà été définis, mais plutôt l'infère à partir de la couleur du pixel, donc il ne peut pas faire la distinction entre un pixel qui vient juste d'être défini et un pixel qui était déjà présent. Ceci signifie que choisir toute couleur de remplissage qui est déjà présente dans l'image peut produire des résultats indésirables.

# imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — Applique un filtre à une image

### Description

function imagefilter(GdImage `$image`, int `$filter`, array|int|float|bool `...$args`): bool

imagefilter() applique le filtre donné `filter` sur l'`image`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`filter`

  `filter` peut être l'un des éléments suivants :

  - `IMG_FILTER_NEGATE` : Inverse toutes les couleurs de l'image.
  - `IMG_FILTER_GRAYSCALE` : Convertit l'image en niveaux de gris en changeant les composantes rouge, verte et bleue en leur somme pondérée en utilisant les mêmes coefficients que le calcul luma REC.601 (Y'). Les composantes alpha sont conservées. Pour les images de la palette, le résultat peut être différent en raison des limitations de la palette.
  - `IMG_FILTER_BRIGHTNESS` : Modifie la luminosité de l'image. Utiliser `args` pour définir le niveau de luminosité. La plage de luminosité est comprise entre -255 et 255.
  - `IMG_FILTER_CONTRAST` : Modifie le contraste de l'image. Utiliser `args` pour définir le niveau de contraste.
  - `IMG_FILTER_COLORIZE` : similaire à `IMG_FILTER_GRAYSCALE`, sauf qu'il est possible de spécifier la couleur. Utiliser `args`, `arg2` et `arg3` sous la forme `red`, `green`, `blue` et `arg4` pour le canal `alpha`. La plage de chaque couleur est comprise entre 0 et 255.
  - `IMG_FILTER_EDGEDETECT` : Utilise la détection des contours pour mettre en évidence les contours de l'image.
  - `IMG_FILTER_EMBOSS` : Permet d'embosser l'image.
  - `IMG_FILTER_GAUSSIAN_BLUR` : Floute l'image à l'aide de la méthode gaussienne.
  - `IMG_FILTER_SELECTIVE_BLUR` : Floute l'image.
  - `IMG_FILTER_MEAN_REMOVAL` : Utilise la suppression de la moyenne pour obtenir un effet "croquis".
  - `IMG_FILTER_SMOOTH` : Rend l'image plus lisse. Utiliser `args` pour définir le niveau de lissage.
  - `IMG_FILTER_PIXELATE` : Applique un effet de pixellisation à l'image, utiliser `args` pour définir la taille du bloc et `arg2` pour définir le mode d'effet de pixellisation.
  - `IMG_FILTER_SCATTER` : Applique un effet de dispersion à l'image, utiliser `args` et `arg2` pour définir l'intensité de l'effet et `arg3` pour n'appliquer l'effet que sur certaines couleurs de pixels.
`args`

  - `IMG_FILTER_BRIGHTNESS` : Niveau de luminosité.
  - `IMG_FILTER_CONTRAST` : Niveau de contraste.
  - `IMG_FILTER_COLORIZE` : Valeur du composant rouge.
  - `IMG_FILTER_SMOOTH` : Niveau de lissage.
  - `IMG_FILTER_PIXELATE` : Taille du bloc en pixels.
  - `IMG_FILTER_SCATTER` : Niveau de soustraction de l'effet. Il ne doit pas être supérieur ou égal au niveau d'addition défini par `arg2`.
`arg2`

  - `IMG_FILTER_COLORIZE` : Valeur du composant vert.
  - `IMG_FILTER_PIXELATE` : Utilisation ou non de l'effet de pixellisation avancé (la valeur par défaut est `false`).
  - `IMG_FILTER_SCATTER` : Niveau d'addition de l'effet.
`arg3`

  - `IMG_FILTER_COLORIZE` : Valeur du composant bleu.
  - `IMG_FILTER_SCATTER` : Tableau optionnel de valeurs de couleur indexées pour appliquer l'effet.
`arg4`

  - `IMG_FILTER_COLORIZE` canal Alpha, une valeur entre 0 et 127. 0 indique une opacité totale tandis que 127 indique une transparence totale.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Lève une ValueError si `sub` ou `plus` provoque un dépassement ou un sous-dépassement avec le `IMG_FILTER_SCATTER` `filter`.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `sub` ou `plus` provoque un dépassement ou un sous-dépassement avec le `IMG_FILTER_SCATTER` `filter`.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
7.4.0 | La prise en charge de la dispersion (`IMG_FILTER_SCATTER`) a été ajoutée.

### Exemples

Exemple #1 Exemple de niveaux de gris avec imagefilter()

    <?php
    $im = imagecreatefrompng('dave.png');

    if($im && imagefilter($im, IMG_FILTER_GRAYSCALE))
    {
        echo 'Image converted to grayscale.';

        imagepng($im, 'dave.png');
    }
    else
    {
        echo 'Conversion to grayscale failed.';
    }
    ?>

Exemple #2 Exemple de luminosité avec imagefilter()

    <?php
    $im = imagecreatefrompng('sean.png');

    if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
    {
        echo 'Image brightness changed.';

        imagepng($im, 'sean.png');
    }
    else
    {
        echo 'Image brightness change failed.';
    }
    ?>

Exemple #3 Exemple de colorisation avec imagefilter()

    <?php
    $im = imagecreatefrompng('philip.png');

    /* R, G, B, so 0, 255, 0 is green */
    if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
    {
        echo 'Image successfully shaded green.';

        imagepng($im, 'philip.png');
    }
    else
    {
        echo 'Green shading failed.';
    }
    ?>

Exemple #4 Exemple de négatif avec imagefilter()

    <?php
    // Définit la fonction negate afin qu'elle soit portable pour
    // les versions de php sans imagefilter()
    function negate($im)
    {
        if(function_exists('imagefilter'))
        {
            return imagefilter($im, IMG_FILTER_NEGATE);
        }

        for($x = 0; $x < imagesx($im); ++$x)
        {
            for($y = 0; $y < imagesy($im); ++$y)
            {
                $index = imagecolorat($im, $x, $y);
                $rgb = imagecolorsforindex($index);
                $color = imagecolorallocate($im, 255 - $rgb['red'], 255 - $rgb['green'], 255 - $rgb['blue']);

                imagesetpixel($im, $x, $y, $color);
            }
        }

        return(true);
    }

    $im = imagecreatefromjpeg('kalle.jpg');

    if($im && negate($im))
    {
        echo 'Image successfully converted to negative colors.';

        imagejpeg($im, 'kalle.jpg', 100);
    }
    else
    {
        echo 'Converting to negative colors failed.';
    }
    ?>

Exemple #5 Exemple de pixellisation avec imagefilter()

    <?php
    // Charge le logo PHP, nous devons créer deux instances
    // pour voir les différences
    $logo1 = imagecreatefrompng('./php.png');
    $logo2 = imagecreatefrompng('./php.png');

    // Création de l'instance d'image sur laquelle nous voulons
    // voir les différences
    $output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

    // Applique la pixellisation sur chaque instance avec une
    // taille de bloc de 3
    imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
    imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

    // Fusionne les différences sur l'image de sortie
    imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
    imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);

    // Affiche les différences
    header('Content-Type: image/png');
    imagepng($output);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Exemple #6 Exemple de dispersion avec imagefilter()

    <?php
    // Charge l'image
    $logo = imagecreatefrompng('./php.png');

    // Applique un effet de dispersion très doux à l'image
    imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

    // Affiche l'image avec l'effet de dispersion
    header('Content-Type: image/png');
    imagepng($logo);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Notes

> Note: Le résultat de `IMG_FILTER_SCATTER` est toujours aléatoire.

### Voir aussi

- imageconvolution() - Applique une matrice de convolution 3x3, en utilisant un coefficient et un décalage

# imageflip

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageflip — Retourne une image en utilisant le mode fourni

### Description

function imageflip(GdImage `$image`, int `$mode`): true

Retourne l'image `image` en utilisant le `mode` fourni.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`mode`

  Mode de retournement ; peut être une des constantes `IMG_FLIP_*` :

  Constante | Signification
  --- | ---
  `IMG_FLIP_HORIZONTAL` | Retourne l'image horizontalement.
  `IMG_FLIP_VERTICAL` | Retourne l'image verticalement.
  `IMG_FLIP_BOTH` | Retourne l'image à la fois horizontalement et verticalement.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Retourne une image verticalement

Cet exemple utilise la constante `IMG_FLIP_VERTICAL`.

    <?php
    // Fichier
    $filename = 'phplogo.png';

    // Type de contenu
    header('Content-type: image/png');

    // Chargement
    $im = imagecreatefrompng($filename);

    // Retournement vertical
    imageflip($im, IMG_FLIP_VERTICAL);

    // Affichage
    imagejpeg($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Exemple #2 Retourne une image horizontalement

Cet exemple utilise la constante `IMG_FLIP_HORIZONTAL`.

    <?php
    // Fichier
    $filename = 'phplogo.png';

    // Type de contenu
    header('Content-type: image/png');

    // Chargement
    $im = imagecreatefrompng($filename);

    // Retournement horizontal
    imageflip($im, IMG_FLIP_HORIZONTAL);

    // Affichage
    imagejpeg($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imagefontheight

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontheight — Retourne la hauteur de la police

### Description

function imagefontheight(GdFont|int `$font`): int

Retourne la hauteur de la police `font` en pixels.

### Liste de paramètres

`font`
  Peut être 1, 2, 3, 4, 5 pour les polices internes d'encodage Latin2 (où les plus grands nombres correspondent aux polices larges) ou une instance de GdFont retourné par imageloadfont().

### Valeurs de retour

Retourne la hauteur de la police, en pixels.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `font` accepte désormais une instance de GdFont et un entier; auparavant seulement un entier était accepté.

### Exemples

Exemple #1 Exemple avec imagefontheight() et des polices internes

    <?php
    echo 'Hauteur de la police : ' . imagefontheight(4);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Hauteur de la police : 16

Exemple #2 Exemple avec imagefontheight() et imageloadfont()

    <?php
    // Chargement d'une police .gdf
    $font = imageloadfont('anonymous.gdf');

    echo 'Hauteur de la police : ' . imagefontheight($font);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Hauteur de la police : 43

### Voir aussi

- imagefontwidth() - Retourne la largeur de la police
- imageloadfont() - Charge une nouvelle police

# imagefontwidth

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontwidth — Retourne la largeur de la police

### Description

function imagefontwidth(GdFont|int `$font`): int

Retourne la largeur de la police `font` en pixels.

### Liste de paramètres

`font`
  Peut être 1, 2, 3, 4, 5 pour les polices internes d'encodage Latin2 (où les plus grands nombres correspondent aux polices larges) ou une instance de GdFont retourné par imageloadfont().

### Valeurs de retour

Retourne la largeur de la police.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `font` accepte désormais une instance de GdFont et un entier; auparavant seulement un entier était accepté.

### Exemples

Exemple #1 Exemple avec imagefontwidth() et les polices internes

    <?php
    echo 'Largeur de la police : ' . imagefontwidth(4);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Largeur de la police : 8

Exemple #2 Exemple avec imagefontwidth() et imageloadfont()

    <?php
    // Chargement d'une police .gdf
    $font = imageloadfont('anonymous.gdf');

    echo 'Largeur de la police : ' . imagefontwidth($font);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Largeur de la police : 23

### Voir aussi

- imagefontheight() - Retourne la hauteur de la police
- imageloadfont() - Charge une nouvelle police

# imageftbbox

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imageftbbox — Calcule le rectangle d'encadrement pour un texte, en utilisant la police courante et freetype2

### Description

function imageftbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

Cette fonction calcule et retourne le rectangle d'encadrement en pixels pour un texte FreeType.

> Note:

> Antérieurement à PHP 8.0.0, imageftbbox() était une variante étendue de imagettfbbox() qui en plus supportait `options`. À partir de PHP 8.0.0, imagettfbbox() est un alias de imageftbbox().

### Liste de paramètres

`size`

  La taille de la police de caractères en point.

`angle`

  Angle, en degrés, dans lequel le paramètre `string` sera mesuré.

`font_filename`

  Le nom du fichier de la police TrueType (peut être une URL). Suivant la version de GD utilisée par PHP, il sera recherché les fichiers qui ne commencent pas par un '/', en y ajoutant l'extension '.ttf', et suivant le chemin des polices défini par la bibliothèque.

`string`

  La chaîne à mesurer.

`options`

  Index possibles pour le tableau `options`
  Clé | Type | Signification
  --- | --- | ---
  `linespacing` | float | Représente l'espacement entre les lignes lors du dessin

### Valeurs de retour

imageftbbox() retourne un tableau contenant 8 éléments représentant les 4 points du rectangle entourant le texte :

0 | Coin en bas, à gauche, position en X
1 | Coin en bas, à gauche, position en Y
2 | Coin en bas, à droite, position en X
3 | Coin en bas, à droite, position en Y
4 | Coin en haut, à droite, position en X
5 | Coin en haut, à droite, position en Y
6 | Coin en haut, à gauche, position en X
7 | Coin en haut, à gauche, position en Y

Les points sont relatifs au texte indépendamment du paramètre `angle`, ainsi, "en haut à gauche" signifie le coin en haut à gauche lorsque l'on regarde le texte horizontalement.

En cas d'échec, `false` est retourné.

### Exemples

Exemple #1 Exemple avec imageftbbox()

    <?php
    // Création d'une image de 300x150 pixels
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Définit l'arrière-plan en blanc
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Chemin vers notre fichier de police
    $font = './arial.ttf';

    // D'abord, nous créons un rectangle contenant notre texte
    $bbox = imageftbbox(10, 0, $font, 'The PHP Documentation Group');

    // Nos coordonnées en X et en Y
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 5;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    imagefttext($im, 10, 0, $x, $y, $black, $font, 'The PHP Documentation Group');

    // Affichage vers le navigateur
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Notes

> Note: Cette fonction n'est disponible que si si PHP est compilé avec le support Freetype (--with-freetype-dir=DIR)

### Voir aussi

- imagefttext() - Écrit du texte dans une image avec la police courante FreeType 2
- imagettfbbox() - Retourne le rectangle entourant un texte et dessiné avec une police TrueType

# imagefttext

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagefttext — Écrit du texte dans une image avec la police courante FreeType 2

### Description

function imagefttext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

> Note:

> Antérieur à PHP 8.0.0, imagefttext() était une variante étendue de imagettftext() qui en plus supportait `options`. À partir de PHP 8.0.0, imagettftext() est un alias de imagefttext().

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`size`

  La taille de la police à utiliser, en nombre de points.

`angle`

  L'angle, en degrés ; 0 degré pour une lecture du texte de gauche à droite. Les grandes valeurs représentent une rotation dans le sens inverse des aiguilles d'une montre. Par exemple, une valeur de 90 aura pour effet de lire le texte du bas vers le haut.

`x`

  Les coordonnées, fournies par `x` et `y` définissent le point de départ du premier caractère (et plus précisément, le coin en bas à gauche du caractère). C'est un comportement différent de la fonction imagestring(), où `x` et `y` définissent le coin en haut, à gauche du premier caractère. Par exemple, en haut à gauche vaut 0, 0.

`y`

  L'ordonnée. Ce paramètre configure la position de base de la police, et non pas le bas de cette dernière.

`color`

  L'index de la couleur désirée pour le texte, voir la fonction imagecolorexact().

`font_filename`

  Le chemin vers la police TrueType à utiliser.

  Suivant la version de GD utilisée par PHP, il sera recherché les fichiers qui ne commencent pas par un '`/`', en y ajoutant l'extension '`.ttf`', et suivant le chemin des polices défini par la bibliothèque.

  Dans la plupart des cas, lorsque la police se trouve dans le même dossier que le script qui cherche à l'utiliser, la solution suivante permet de s'affranchir de tous les problèmes relatifs à l'inclusion.

      <?php
      // Définit la variable d'environnement pour GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Nom de la police à utiliser (note qu'il n'y a pas d'extension .ttf)
      $font = 'SomeFont';
      ?>

`text`

  Le texte à insérer dans l'image.

`options`

  Index possibles pour le tableau `options`
  Clé | Type | Signification
  --- | --- | ---
  `linespacing` | float | Définit l'espacement entre les lignes lors du dessin

### Valeurs de retour

Cette fonction retourne un tableau définissant les 4 points d'une boîte, en commençant par le coin en bas, à gauche, puis, les suivants, dans le sens inverse des aiguilles d'une montre :

0 | x : coordonnée en bas, à gauche
1 | y : coordonnée en bas, à gauche
2 | x : coordonnée en bas, à droite
3 | y : coordonnée en bas, à droite
4 | x : coordonnée en haut, à droite
5 | y : coordonnée en haut, à droite
6 | x : coordonnée en haut, à gauche
7 | y : coordonnée en haut, à gauche

En cas d'échec, `false` est retourné.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagefttext()

    <?php
    // Création d'une image de 300x100 pixels
    $im = imagecreatetruecolor(300, 100);
    $red = imagecolorallocate($im, 0xFF, 0x00, 0x00);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Définit l'arrière-plan en rouge
    imagefilledrectangle($im, 0, 0, 299, 99, $red);

    // Chemin vers notre fichier de police ttf
    $font_file = './arial.ttf';

    // Dessine le texte 'PHP Manual' en utilisant une police de taille 13
    imagefttext($im, 13, 0, 105, 55, $black, $font_file, 'PHP Manual');

    // Affichage de l'image sur le navigateur
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Notes

> Note: Cette fonction n'est disponible que si si PHP est compilé avec le support Freetype (--with-freetype-dir=DIR)

### Voir aussi

- imageftbbox() - Calcule le rectangle d'encadrement pour un texte, en utilisant la police courante et freetype2
- imagettftext() - Dessine un texte avec une police TrueType

# imagegammacorrect

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegammacorrect — Applique une correction gamma à l'image GD

### Description

function imagegammacorrect(GdImage `$image`, float `$input_gamma`, float `$output_gamma`): true

Applique une correction gamma à l'image GD `image` en fonction d'un gamma d'entrée et d'un gamma de sortie.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`input_gamma`

  Le facteur gamma d'entrée.

`output_gamma`

  Le facteur gamma de sortie.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagegammacorrect()

    <?php
    // Création d'une image
    $im = imagecreatefromgif('php.gif');

    // Correction gamma, sortie à 1.537
    imagegammacorrect($im, 1.0, 1.537);

    // Sauvegarde et libération de la mémoire
    imagegif($im, './php_gamma_corrected.gif');
    ?>

# imagegd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd — Génère une image au format GD, vers le navigateur ou un fichier

### Description

function imagegd(GdImage `$image`, ?string `$file` = `null`): bool

Génère ou sauvegarde le fichier `file` au format GD.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`file`

  Le chemin ou un flux de ressource ouvert (qui sera automatiquement fermé après le retour de cette fonction) vers lequel le fichier sera sauvegardé. Si non-défini ou `null`, le flux brute de l'image sera affiché directement.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Historique

Version | Description
--- | ---
8.0.3 | `file` est désormais nullable.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
7.2.0 | imagegd() permet maintenant de produire des images TrueColor. Antérieurement, elles étaient implicitement converties en palette.

### Exemples

Exemple #1 Affichage d'une image GD

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Un texte simple", $text_color);

    // Affichage de l'image
    imagegd($im);
    ?>

Exemple #2 Sauvegarde d'une image GD

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Un texte simple", $text_color);

    // Sauvegarde de l'image GD
    // Le format de fichier pour les images GD est .gd, voir http://www.libgd.org/GdFileFormats
    imagegd($im, 'simple.gd');
    ?>

### Notes

> Note:

> Le format GD est communément utilisé pour autoriser le chargement rapide des parties d'une image. Il est à noter que le format GD est uniquement utilisable dans les applications compatibles GD.

Avertissement

Les formats d'image GD et GD2 sont des formats d'images propriétaire de libgd. Ils doivent être considérés obsolète, et devraient seulement être utilisé lors du développement et la phase de test.

### Voir aussi

- imagegd2() - Génère une image au format GD2, vers le navigateur ou un fichier

# imagegd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd2 — Génère une image au format GD2, vers le navigateur ou un fichier

### Description

function imagegd2(
GdImage `$image`,
?string `$file` = `null`,
int `$chunk_size` = 128,
int `$mode` = `IMG_GD2_RAW`
): bool

Génère ou sauvegarde le fichier `file` au format GD2.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`file`

  Le chemin ou un flux de ressource ouvert (qui sera automatiquement fermé après le retour de cette fonction) vers lequel le fichier sera sauvegardé. Si non-défini ou `null`, le flux brute de l'image sera affiché directement.

`chunk_size`

  Taille du fragment.

`mode`

  Soit `IMG_GD2_RAW`, soit `IMG_GD2_COMPRESSED`. Par défaut, vaut `IMG_GD2_RAW`.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Historique

Version | Description
--- | ---
8.0.3 | `file` est désormais nullable.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Affichage d'une image GD2

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Un texte simple", $text_color);

    // Affichage de l'image
    imagegd2($im);

    ?>

Exemple #2 Sauvegarde d'une image GD2

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Un texte simple", $text_color);

    // Sauvegarde de l'image GD2
    // Le format de fichier pour les images GD2 est .gd2, voir http://www.libgd.org/GdFileFormats
    imagegd2($im, 'simple.gd2');

    ?>

### Notes

> Note:

> Le format GD2 est communément utilisé pour charger rapidement les parties d'une image. Il est à noter que le format GD2 est uniquement utilisable dans les applications compatibles GD2.

Avertissement

Les formats d'image GD et GD2 sont des formats d'images propriétaire de libgd. Ils doivent être considérés obsolète, et devraient seulement être utilisé lors du développement et la phase de test.

### Voir aussi

- imagegd() - Génère une image au format GD, vers le navigateur ou un fichier

# imagegetclip

(PHP 7 >= 7.2.0, PHP 8)

imagegetclip — Récupère le rectangle de coupure

### Description

function imagegetclip(GdImage `$image`): array

imagegetclip() récupère le rectangle de coupure actuel, c'est-à-dire la zone au-delà de laquelle aucun pixel ne sera dessiné.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().

### Valeurs de retour

La fonction retourne un tableau indexé avec les coordonnées du rectangle de coupure avec les entrées suivantes :

- la coordonnée x du coin supérieur gauche
- la coordonnée y du coin supérieur gauche
- la coordonnée x du coin inférieur droit
- la coordonnée y du coin inférieur droit

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagegetclip()

Définir et récupérer le rectangle de coupure.

    <?php
    $im = imagecreate(100, 100);
    imagesetclip($im, 10,10, 89,89);
    print_r(imagegetclip($im));

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => 10
        [1] => 10
        [2] => 89
        [3] => 89
    )

### Voir aussi

- imagesetclip() - Définit le rectangle de coupure

# imagegetinterpolation

(PHP 8)

imagegetinterpolation — Récupère la méthode d'interpolation

### Description

function imagegetinterpolation(GdImage `$image`): int

Récupère la méthode d'interpolation actuellement définie pour l'`image`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().

### Valeurs de retour

Retourne la méthode d'interpolation.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Voir aussi

- imagesetinterpolation() - Définit la méthode d'interpolation

# imagegif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegif — Affichage de l'image vers le navigateur ou dans un fichier

### Description

function imagegif(GdImage `$image`, resource|string|null `$file` = `null`): bool

imagegif() crée un fichier image GIF dans `file` d'après l'image `image`. L'argument `image` est un identifiant valide retourné par la fonction imagecreate() ou les fonctions `imagecreatefrom*`.

Le format de l'image sera GIF87a, à moins que l'image n'ait une couleur transparente (mise en place grâce à la fonction imagecolortransparent()), ce qui fera qu'elle sera au format GIF89a.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`file`

  Le chemin ou un flux de ressource ouvert (qui sera automatiquement fermé après le retour de cette fonction) vers lequel le fichier sera sauvegardé. Si non-défini ou `null`, le flux brute de l'image sera affiché directement.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Affichage d'une image en utilisant imagegif()

    <?php
    // Création d'une image
    $im = imagecreatetruecolor(100, 100);

    // Définit l'arrière-plan en blanc
    imagefilledrectangle($im, 0, 0, 99, 99, 0xFFFFFF);

    // Dessine un texte dans l'image
    imagestring($im, 3, 40, 20, 'GD Library', 0xFFBA00);

    // Affiche l'image sur le navigateur
    header('Content-Type: image/gif');

    imagegif($im);
    ?>

Exemple #2 Conversion d'une image PNG en GIF, en utilisant imagegif()

    <?php
    // Chargement de l'image PNG
    $png = imagecreatefrompng('./php.png');

    // Sauvegarde de l'image en GIF
    imagegif($png, './php.gif');

    // C'est fait !
    echo 'Conversion avec succès de l\'image PNG en GIF !';
    ?>

### Notes

> Note:

> Le code suivant permet d'écrire des scripts PHP plus portables : le type de GD est automatiquement détecté. Il remplace la séquence `header ("Content-Type: image/gif"); imagegif ($im);` par un code plus souple :

>     <?php
>     // Création d'une image
>     $im = imagecreatetruecolor(100, 100);

>     // On fait quelques opérations sur l'image ici...

>     // Gestion de l'affichage
>     if(function_exists('imagegif'))
>     {
>         // Pour GIF
>         header('Content-Type: image/gif');

>         imagegif($im);
>     }
>     elseif(function_exists('imagejpeg'))
>     {
>         // Pour JPEG
>         header('Content-Type: image/jpeg');

>         imagejpeg($im, NULL, 100);
>     }
>     elseif(function_exists('imagepng'))
>     {
>         // Pour PNG
>         header('Content-Type: image/png');

>         imagepng($im);
>     }
>     elseif(function_exists('imagewbmp'))
>     {
>         // Pour WBMP
>         header('Content-Type: image/vnd.wap.wbmp');

>         imagewbmp($im);
>     }
>     else
>     {
>         die('Aucun support sur ce serveur PHP n\'a été trouvé');
>     }

>     ?>

> Note:

> Il est possible d'utiliser la fonction imagetypes() au lieu de function_exists() pour vérifier la présence des différents formats d'images supportés :

>     <?php
>     if(imagetypes() & IMG_GIF)
>     {
>         header('Content-Type: image/gif');
>         imagegif($im);
>     }
>     elseif(imagetypes() & IMG_JPG)
>     {
>         /* ... etc. */
>     }
>     ?>

### Voir aussi

- imagepng() - Envoie une image PNG vers un navigateur ou un fichier
- imagewbmp() - Affichage de l'image vers le navigateur ou dans un fichier
- imagejpeg() - Affichage de l'image vers le navigateur ou dans un fichier
- imagetypes() - Retourne les types d'images supportés par la version courante de PHP

# imagegrabscreen

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabscreen — Capture l'écran complet

### Description

function imagegrabscreen(): GdImage|false

imagegrabscreen() effectue une capture de la totalité de l'écran.

> Note:

> Cette fonction n'est disponible que sous Windows.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet image en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.

### Exemples

Exemple #1 Exemple avec imagegrabscreen()

Cet exemple montre comment effectuer une capture d'écran et la sauvegarder dans une image png.

    <?php
    $im = imagegrabscreen();
    imagepng($im, "myscreenshot.png");
    ?>

### Voir aussi

- imagegrabwindow() - Capture une fenêtre

# imagegrabwindow

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabwindow — Capture une fenêtre

### Description

function imagegrabwindow(int `$handle`, bool `$client_area` = `false`): GdImage|false

Capture une fenêtre ou l'espace de son client, en utilisant un gestionnaire de fenêtre (propriété HWND de l'instance COM).

> Note:

> Cette fonction n'est disponible que sous Windows.

### Liste de paramètres

`handle`

  L'identifiant HWND de la fenêtre.

`client_area`

  Inclure ou non l'espace du client de la fenêtre de l'application.

### Valeurs de retour

Retourne un objet image en cas de succès, ou `false` si une erreur survient.

### Erreurs / Exceptions

Une alerte de type E_NOTICE est émise si `handle` est un gestionnaire de fenêtre invalide. Une alerte de type E_WARNING est émise si l'API Windows est trop ancienne.

### Historique

Version | Description
--- | ---
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.
8.0.0 | `client_area` attend désormais un bool ; auparavant il s'attendait à un int.

### Exemples

Exemple #1 Exemple avec imagegrabwindow()

Capture une fenêtre (IE par exemple).

    <?php
    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $im = imagegrabwindow($handle);
    $browser->Quit();
    imagepng($im, "iesnap.png");
    ?>

Capture une fenêtre (IE par exemple) mais avec son contenu.

    <?php
    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $browser->Navigate("http://www.libgd.org");

    /* Fonctionne toujours ? */
    while ($browser->Busy) {
        com_message_pump(4000);
    }
    $im = imagegrabwindow($handle, 0);
    $browser->Quit();
    imagepng($im, "iesnap.png");
    ?>

### Voir aussi

- imagegrabscreen() - Capture l'écran complet

# imageinterlace

(PHP 4, PHP 5, PHP 7, PHP 8)

imageinterlace — Active ou désactive l'entrelacement

### Description

function imageinterlace(GdImage `$image`, ?bool `$enable` = `null`): bool

imageinterlace() active ou désactive le bit d'entrelacement.

Si l'entrelacement est à 1 et l'image est JPEG, l'image créée sera un JPEG progressif.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`enable`

  Si `true`, l'image sera entrelacée, si `false` le bit d'entrelacement est désactivé. Passer `null` fera que le comportement d'entrelacement n'est pas changé.

### Valeurs de retour

Retourne `true` si l'entrelacement est activé pour l'image, `false` sinon.

### Historique

Version | Description
--- | ---
8.0.5 | imageinterlace() retourne désormais un bool ; antérieurement un int était retourné (non-zéro pour les images entrelacées, zéro sinon).
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
8.0.0 | `enable` attend désormais un bool ; antérieurement il attendait un int.

### Exemples

Exemple #1 Activation de l'entrelacement en utilisant la fonction imageinterlace()

    <?php
    // Création d'une image
    $im = imagecreatefromgif('php.gif');

    // Activation de l'entrelacement
    imageinterlace($im, true);

    // Sauvegarde de l'image
    imagegif($im, './php_interlaced.gif');
    ?>

# imageistruecolor

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageistruecolor — Détermine si une image est une image truecolor

### Description

function imageistruecolor(GdImage `$image`): bool

imageistruecolor() détermine si l'image `image` est une image truecolor.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().

### Valeurs de retour

Retourne `true` si l'image est truecolor, `false` sinon.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Détection simple d'une image en truecolor avec imageistruecolor()

    <?php
    // $im est une instance d'image

    // Vérifie si l'image est en truecolor ou non
    if(!imageistruecolor($im))
    {
        // Création d'une nouvelle image en truecolor
        $tc = imagecreatetruecolor(imagesx($im), imagesy($im));

        // Copie sur les pixels
        imagecopy($tc, $im, 0, 0, 0, 0, imagesx($im), imagesy($im));

        $im = $tc;
        $tc = NULL;

        // Ou utiliser imagepalettetotruecolor()
    }

    // On continue de travailler avec l'instance de l'image
    ?>

### Voir aussi

- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies
- imagepalettetotruecolor() - Convertit une image basée sur une palette en couleur vraie

# imagejpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagejpeg — Affichage de l'image vers le navigateur ou dans un fichier

### Description

function imagejpeg(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

imagejpeg() crée un fichier JPEG depuis l'image fournie.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`file`

  Le chemin ou un flux de ressource ouvert (qui sera automatiquement fermé après le retour de cette fonction) vers lequel le fichier sera sauvegardé. Si non-défini ou `null`, le flux brute de l'image sera affiché directement.

`quality`

  `quality` est optionnel, et prend des valeurs dans l'intervalle 0 (pire qualité, petit fichier) à 100 (meilleure qualité, gros fichier). Par défaut (`-1`), utilise la valeur de la qualité IJG par défaut (environ 75).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Erreurs / Exceptions

Lève une ValueError si `quality` est invalide.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `quality` est invalide.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Affichage d'une image JPEG vers le navigateur

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Définit le contenu de l'en-tête - dans ce cas, image/jpeg
    header('Content-Type: image/jpeg');

    // Affichage de l'image
    imagejpeg($im);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

Exemple #2 Sauvegarde d'une image JPEG dans un fichier

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texte simple', $text_color);

    // Sauvegarde de l'image sous le nom 'simpletext.jpg'
    imagejpeg($im, 'simpletext.jpg');

    ?>

Exemple #3 Affichage de l'image avec une qualité de 75% vers le navigateur

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texte simple', $text_color);

    // Définit le contenu de l'en-tête - dans ce cas,  image/jpeg
    header('Content-Type: image/jpeg');

    // On ne fournit pas le nom du fichier (utilisation de la valeur NULL),
    // puis, on définit la qualité à 75%
    imagejpeg($im, NULL, 75);

    ?>

### Notes

> Note:

> Pour générer des images JPEG progressives, il faut activer l'entrelacement à l'aide de la fonction imageinterlace().

### Voir aussi

- imagepng() - Envoie une image PNG vers un navigateur ou un fichier
- imagegif() - Affichage de l'image vers le navigateur ou dans un fichier
- imagewbmp() - Affichage de l'image vers le navigateur ou dans un fichier
- imageinterlace() - Active ou désactive l'entrelacement
- imagetypes() - Retourne les types d'images supportés par la version courante de PHP

# imagelayereffect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagelayereffect — Active l'option d'alpha blending, pour utiliser les effets de libgd

### Description

function imagelayereffect(GdImage `$image`, int `$effect`): true

Active l'option d'alpha blending, pour utiliser les effets libgd.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`effect`

  Une des constantes suivantes :

  `IMG_EFFECT_REPLACE`
    Utilise le remplacement de pixels (équivalent à passer `true` à la fonction imagealphablending())
  `IMG_EFFECT_ALPHABLEND`
    Utilise le blending normal de pixels (équivalent à passer `false` à la fonction imagealphablending())
  `IMG_EFFECT_NORMAL`
    Identique à la constante `IMG_EFFECT_ALPHABLEND`.
  `IMG_EFFECT_OVERLAY`
    L'overlay a pour effet que les pixels noirs du fond resteront noirs, les blancs du fond resteront blancs, mais les gris du fond prendront la couleur du pixel de premier plan.
  `IMG_EFFECT_MULTIPLY`
    L'overlay avec un effet de multiplication.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
7.2.0 | Ajout de la constante `IMG_EFFECT_MULTIPLY` (nécessite la libgd système >= 2.1.1 ou la libgd embarquée).

### Exemples

Exemple #1 Exemple avec imagelayereffect()

    <?php
    // Création d'une image
    $im = imagecreatetruecolor(100, 100);

    // Définit l'arrière-plan
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 220, 220, 220));

    // Applique l'overlay
    imagelayereffect($im, IMG_EFFECT_OVERLAY);

    // Dessine 2 ellipses grises
    imagefilledellipse($im, 50, 50, 40, 40, imagecolorallocate($im, 100, 255, 100));
    imagefilledellipse($im, 50, 50, 50, 80, imagecolorallocate($im, 100, 100, 255));
    imagefilledellipse($im, 50, 50, 80, 50, imagecolorallocate($im, 255, 100, 100));

    // Affichage
    header('Content-type: image/png');

    imagepng($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imageline

(PHP 4, PHP 5, PHP 7, PHP 8)

imageline — Dessine une ligne

### Description

function imageline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Dessine une ligne entre deux points fournis.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`x1`

  X : coordonnée du premier point.

`y1`

  Y : coordonnée du premier point.

`x2`

  X : coordonnée du second point.

`y2`

  Y : coordonnée du second point.

`color`

  La couleur de la ligne. Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Trace une ligne épaisse

    <?php

    function imagelinethick($image, $x1, $y1, $x2, $y2, $color, $thick = 1)
    {
        /* de cette manière, ça ne marche bien que pour les lignes orthogonales
        imagesetthickness($image, $thick);
        return imageline($image, $x1, $y1, $x2, $y2, $color);
        */
        if ($thick == 1) {
            return imageline($image, $x1, $y1, $x2, $y2, $color);
        }
        $t = $thick / 2 - 0.5;
        if ($x1 == $x2 || $y1 == $y2) {
            return imagefilledrectangle($image, round(min($x1, $x2) - $t), round(min($y1, $y2) - $t), round(max($x1, $x2) + $t), round(max($y1, $y2) + $t), $color);
        }
        $k = ($y2 - $y1) / ($x2 - $x1); //y = kx + q
        $a = $t / sqrt(1 + pow($k, 2));
        $points = array(
            round($x1 - (1+$k)*$a), round($y1 + (1-$k)*$a),
            round($x1 - (1-$k)*$a), round($y1 - (1+$k)*$a),
            round($x2 + (1+$k)*$a), round($y2 - (1-$k)*$a),
            round($x2 + (1-$k)*$a), round($y2 + (1+$k)*$a),
        );
        imagefilledpolygon($image, $points, 4, $color);
        return imagepolygon($image, $points, 4, $color);
    }

    ?>

### Voir aussi

- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies
- imagecolorallocate() - Alloue une couleur pour une image

# imageloadfont

(PHP 4, PHP 5, PHP 7, PHP 8)

imageloadfont — Charge une nouvelle police

### Description

function imageloadfont(string `$filename`): GdFont|false

imageloadfont() charge une nouvelle police utilisateur et retourne son identifiant.

### Liste de paramètres

`filename`

  Le format des fichiers de polices est actuellement binaire et dépendant de l'architecture. Cela signifie qu'il faut générer les fichiers de polices sur le même type de processeur que la machine qui fait tourner PHP.

  Format de fichier de police
  Position | Type de données C | Description
  --- | --- | ---
  Octets 0-3 | int | Nombre de caractères de la police
  Octets 4-7 | int | Valeur du premier caractère de la police (souvent 32 pour espace)
  Octets 8-11 | int | Largeur en pixels des caractères
  Octets 12-15 | int | Hauteur en pixels des caractères
  Octets 16- | char | Tableau avec les données des caractères, un octet par pixel pour chaque caractère, avec un total de (nombre de caractères * largeur * hauteur) octets.

### Valeurs de retour

Retourne une instance GdFont, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de GdFont; auparavant, un entier était retourné.

### Exemples

Exemple #1 Exemple avec imageloadfont()

    <?php
    // Création d'une nouvelle image
    $im = imagecreatetruecolor(50, 20);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Définit l'arrière-plan en blanc
    imagefilledrectangle($im, 0, 0, 49, 19, $white);

    // Charge la police GD et écrit 'Bonjour !'
    $font = imageloadfont('./04b.gdf');
    imagestring($im, $font, 0, 0, 'Bonjour !', $black);

    // Affichage sur le navigateur
    header('Content-type: image/png');

    imagepng($im);
    ?>

### Voir aussi

- imagefontwidth() - Retourne la largeur de la police
- imagefontheight() - Retourne la hauteur de la police
- imagestring() - Dessine une chaîne horizontale

# imageopenpolygon

(PHP 7 >= 7.2.0, PHP 8)

imageopenpolygon — Dessine un polygone ouvert

### Description

Signature à partir de PHP 8.0.0 (non supportée avec les arguments nommés)

function imageopenpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Signature alternative (obsolète à partir de PHP 8.1.0)

function imageopenpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imageopenpolygon() dessine un polygone ouvert sur l'`image`. Contrairement à imagepolygon(), aucune ligne n'est dessinée entre le dernier et le premier point.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`points`

  Un tableau contenant les sommets du polygone, par exemple :

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Nombre total de points (sommets), qui doit être d'au moins 3.

  Si ce paramètre est omis conformément à la deuxième signature, `points` doit avoir un nombre pair d'éléments, et `num_points` est supposé valoir `count($points)/2`.
`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `num_points` a été rendu obsolète.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imageopenpolygon()

    <?php
    // Créer une image vide
    $image = imagecreatetruecolor(400, 300);

    // Alloue une couleur pour le polygone
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // Dessine le polygone
    imageopenpolygon($image, array(
            0,   0,
            100, 200,
            300, 200
        ),
        $col_poly);

    // Affiche l'image dans le navigateur
    header('Content-type: image/png');

    imagepng($image);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagepolygon() - Dessine un polygone

# imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagepalettecopy — Copie la palette d'une image à l'autre

### Description

function imagepalettecopy(GdImage `$dst`, GdImage `$src`): void

imagepalettecopy() copie la palette de l'image `src` dans l'image `dst`.

### Liste de paramètres

`dst`

  L'objet de l'image de destination.

`src`

  L'objet de l'image source.

### Valeurs de retour

Aucune valeur n'est retournée.

### Historique

Version | Description
--- | ---
8.0.0 | `dst` et `src` attendent désormais des instances de GdImage ; antérieurement, des resources étaient attendues.

### Exemples

Exemple #1 Exemple avec imagepalettecopy()

    <?php
    // Création de 2 palettes
    $palette1 = imagecreate(100, 100);
    $palette2 = imagecreate(100, 100);

    // Définit l'arrière-plan en vert
    // pour la première
    $green = imagecolorallocate($palette1, 0, 255, 0);

    // Copie la première palette dans la deuxième
    imagepalettecopy($palette2, $palette1);

    // Sachant que la palette est maintenant copiée, nous pouvons
    // utiliser la couleur verte allouée à la première palette
    // sans pour autant utiliser de nouveau la fonction imagecolorallocate()
    imagefilledrectangle($palette2, 0, 0, 99, 99, $green);

    // Affichage de l'image sur le navigateur
    header('Content-type: image/png');

    imagepng($palette2);
    ?>

# imagepalettetotruecolor

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagepalettetotruecolor — Convertit une image basée sur une palette en couleur vraie

### Description

function imagepalettetotruecolor(GdImage `$image`): bool

Convertit une image basée sur une palette, créée par une fonction comme imagecreate(), en une image en couleur vraie, comme imagecreatetruecolor().

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().

### Valeurs de retour

Retourne `true` si la conversion a été un succès, ou si l'image source est déjà en couleur vraie, sinon, retourne `false`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Convertit n'importe quel objet image en couleur vraie

    <?php
    // Compatibilité ascendante
    if(!function_exists('imagepalettetotruecolor'))
    {
        function imagepalettetotruecolor(&$src)
        {
            if(imageistruecolor($src))
            {
                return(true);
            }

            $dst = imagecreatetruecolor(imagesx($src), imagesy($src));

            imagecopy($dst, $src, 0, 0, 0, 0, imagesx($src), imagesy($src));

            $src = $dst;

            return(true);
        }
    }

    // Utilisation d'une Closure
    $typeof = function() use($im)
    {
        echo 'typeof($im) = ' . (imageistruecolor($im) ? 'true color' : 'palette'), PHP_EOL;
    };

    // Crée une image basée sur une palette
    $im = imagecreate(100, 100);
    $typeof();

    // On la convertit en couleur vraie
    imagepalettetotruecolor($im);
    $typeof();

    ?>

L'exemple ci-dessus va afficher :

    typeof($im) = palette
    typeof($im) = true color

### Voir aussi

- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies
- imageistruecolor() - Détermine si une image est une image truecolor

# imagepng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepng — Envoie une image PNG vers un navigateur ou un fichier

### Description

function imagepng(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$filters` = -1
): bool

imagepng() affiche ou sauvegarde une image au format PNG en utilisant l'image `image`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`file`

  Le chemin ou un flux de ressource ouvert (qui sera automatiquement fermé après le retour de cette fonction) vers lequel le fichier sera sauvegardé. Si non-défini ou `null`, le flux brute de l'image sera affiché directement.

  > Note:

  > La valeur `null` est invalide si le paramètre `quality` et le paramètre `filters` ne sont pas utilisés.

`quality`

  Degré de compression : de 0 (aucune compression) à 9. La valeur par défaut (`-1`) utilise la compression par défaut de zlib. Pour plus d'informations, voir le » manuel zlib.

`filters`

  Permet la réduction de la taille du fichier PNG. C'est un masque qui peut être défini par une combinaison des constantes `PNG_FILTER_*`. `PNG_NO_FILTER` ou `PNG_ALL_FILTERS` peuvent également être utilisés pour, respectivement, désactiver ou activer tous les filtres. La valeur par défaut (`-1`) désactive le filtrage.

  Attention

  Le paramètre `filters` est ignoré par la version système de libgd.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Erreurs / Exceptions

Lève une ValueError si `quality` est invalide.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `quality` est invalide.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

    <?php
    $im = imagecreatefrompng("test.png");

    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Voir aussi

- imagegif() - Affichage de l'image vers le navigateur ou dans un fichier
- imagewbmp() - Affichage de l'image vers le navigateur ou dans un fichier
- imagejpeg() - Affichage de l'image vers le navigateur ou dans un fichier
- imagetypes() - Retourne les types d'images supportés par la version courante de PHP
- imagesavealpha() - Détermine si les informations complètes du canal alpha doivent être conservées lors de la sauvegarde d'images

# imagepolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepolygon — Dessine un polygone

### Description

Signature à partir de PHP 8.0.0 (non supportée avec les arguments nommés)

function imagepolygon(GdImage `$image`, array `$points`, int `$color`): bool

Signature alternative (obsolète à partir de PHP 8.1.0)

function imagepolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagepolygon() dessine un polygone dans l'image `image`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`points`

  Un tableau contenant les sommets du polygone, p. ex. :

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Nombre total de points (sommets), qui doit être d'au moins 3.

  Si ce paramètre est omis conformément à la deuxième signature, `points` doit avoir un nombre pair d'éléments, et `num_points` est supposé valoir `count($points)/2`.
`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `num_points` a été rendu obsolète.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagepolygon()

    <?php
    // Création d'une image vide
    $image = imagecreatetruecolor(400, 300);

    // Alloue une couleur pour le polygone
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // Dessine le polygone
    imagepolygon($image, array(
            0,   0,
            100, 200,
            300, 200
        ),
        $col_poly);

    // Affichage de l'image sur le navigateur
    header('Content-type: image/png');

    imagepng($image);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagefilledpolygon() - Dessine un polygone rempli
- imageopenpolygon() - Dessine un polygone ouvert
- imagecreate() - Crée une nouvelle image à palette
- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies

# imagerectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagerectangle — Dessine un rectangle

### Description

function imagerectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

imagerectangle() dessine un rectangle aux coordonnées spécifiées. Le point 0, 0 est le coin en haut à gauche de l'image.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`x1`

  X : coordonnée du coin en haut, à gauche.

`y1`

  Y : coordonnée du coin en haut, à gauche.

`x2`

  X : coordonnée du point en bas, à droite.

`y2`

  Y : coordonnée du point en bas, à droite.

`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagerectangle()

    <?php
    // Création d'une image de 200 x 200 pixels
    $canvas = imagecreatetruecolor(200, 200);

    // Alloue les couleurs
    $pink = imagecolorallocate($canvas, 255, 105, 180);
    $white = imagecolorallocate($canvas, 255, 255, 255);
    $green = imagecolorallocate($canvas, 132, 135, 28);

    // Dessine 3 rectangles, chacun avec sa couleur
    imagerectangle($canvas, 50, 50, 150, 150, $pink);
    imagerectangle($canvas, 45, 60, 120, 100, $white);
    imagerectangle($canvas, 100, 120, 75, 160, $green);

    // Affichage
    header('Content-Type: image/jpeg');
    imagejpeg($canvas);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imageresolution

(PHP 7 >= 7.2.0, PHP 8)

imageresolution — Récupère ou définit la résolution de l'image

### Description

function imageresolution(GdImage `$image`, ?int `$resolution_x` = `null`, ?int `$resolution_y` = `null`): array|true

imageresolution() permet de définir et récupérer la résolution d'une image en DPI (dots per inch/point par pouce). Si les paramètres optionnels sont `null`, la résolution actuelle est retournée dans un tableau indexé. Si uniquement `resolution_x` n'est pas `null`, les résolutions horizontale et verticale sont définies à cette valeur. Si aucun des paramètres optionnels n'est `null`, les résolutions horizontale et verticale sont définies à ces valeurs, respectivement.

La résolution est uniquement utilisée en tant que métadonnées quand les images sont lues depuis ou écrites vers des formats supportant ce genre d'information (actuellement PNG et JPEG). Ceci n'affecte pas les opérations de dessin. La résolution par défaut des nouvelles images est 96 DPI.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`resolution_x`

  La résolution horizontale en DPI/PPP.

`resolution_y`

  La résolution verticale en DPI/PPP.

### Valeurs de retour

Quand utilisé en tant que récupérateur, ceci retourne un tableau indexé avec les résolutions horizontale et verticale en cas de succès. Quand utilisé en tant que définisseur, ceci retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `resolution_x` et `resolution_y` sont désormais nullable.

### Exemples

Exemple #1 Définir et récupérer la résolution d'une image

    <?php
    $im = imagecreatetruecolor(100, 100);
    imageresolution($im, 200);
    print_r(imageresolution($im));
    imageresolution($im, 300, 72);
    print_r(imageresolution($im));
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [0] => 200
        [1] => 200
    )
    Array
    (
        [0] => 300
        [1] => 72
    )

# imagerotate

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagerotate — Fait tourner une image d'un angle

### Description

function imagerotate(GdImage `$image`, float `$angle`, int `$background_color`): GdImage|false

imagerotate() fait tourner l'image `image` d'un angle de `angle`, en degrés.

Le centre de rotation est le centre de l'image, et l'image tournée peut avoir des dimensions différentes de l'image originale.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`angle`

  L'angle de rotation, en degrés. L'angle de rotation est interprété comme étant le nombre de degrés à tourner l'image dans le sens inverse des aiguilles d'une montre.

`background_color`

  Spécifie la couleur des zones qui seront découvertes après la rotation.

### Valeurs de retour

Retourne un objet d'image correspondant à l'image après rotation, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.3.0 | Le paramètre inutilisé `ignore_transparent` a été complètement supprimé.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
8.0.0 | Le paramètre inutilisé `ignore_transparent` attend désormais un bool ; auparavant il s'attendait à un int.

### Exemples

Exemple #1 Rotation d'une image de 180 degrés

Cet exemple tourne une image de 180 degrés - à l'envers.

    <?php
    // Fichier et degrés de rotation
    $filename = 'test.jpg';
    $degrees = 180;

    // Content type
    header('Content-type: image/jpeg');

    // Chargement
    $source = imagecreatefromjpeg($filename);

    // Rotation
    $rotate = imagerotate($source, $degrees, 0);

    // Affichage
    imagejpeg($rotate);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Notes

> Note: Cette fonction est affectée par la méthode d'interpolation, définie par la fonction imagesetinterpolation().

### Voir aussi

- imagesetinterpolation() - Définit la méthode d'interpolation

# imagesavealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagesavealpha — Détermine si les informations complètes du canal alpha doivent être conservées lors de la sauvegarde d'images

### Description

function imagesavealpha(GdImage `$image`, bool `$enable`): true

imagesavealpha() définit le drapeau qui détermine si les informations du canal alpha (en opposition à la transparence à couleur unique) doivent être conservées lors de la sauvegarde d'images. Cela est supporté seulement pour les formats d'images qui supportent la totalité des informations du canal alpha, c'est-à-dire `PNG`, `WebP` et `AVIF`.

> Note: imagesavealpha() est seulement significatif pour les images `PNG`, puisque le canal alpha complet est toujours sauvegardé pour `WebP` et `AVIF`. Il n'est pas recommandé de se reposer sur ce comportement, cela pourrait changer dans le futur. Ainsi, imagesavealpha() devrait être appelé intentionnellement aussi pour les images `WebP` et `AVIF`.

L'alpha blending doit être désactivé (`imagealphablending($im, false)`) pour conserver le canal alpha en premier lieu.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`enable`

  Si l'on doit ou non sauvegarder le canal alpha. Par défaut `false`.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Utilisation simple de imagesavealpha()

    <?php
    // Charge une image PNG avec un canal alpha
    $png = imagecreatefrompng('./alphachannel_example.png');

    // Désactiver le alpha blending
    imagealphablending($png, false);

    // Faire les opérations désirées

    // Définir le drapeau alpha
    imagesavealpha($png, true);

    // Affiche l'image au navigateur
    header('Content-Type: image/png');

    imagepng($png);
    ?>

### Voir aussi

- imagealphablending() - Modifie le mode de blending d'une image

# imagescale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagescale — Met à l'échelle une image en utilisant une hauteur et une largeur fournies

### Description

function imagescale(
GdImage `$image`,
int `$width`,
int `$height` = -1,
int `$mode` = `IMG_BILINEAR_FIXED`
): GdImage|false

imagescale() met à l'échelle une image en utilisant l'algorithme d'interpolation donné.

> Note:

> Contrairement à beaucoup d'autres fonctions d'image, imagescale() ne modifie pas l'`image` fournie ; à la place, une nouvelle image est retournée.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`width`

  La largeur à utiliser pour la mise à l'échelle de l'image.

`height`

  La hauteur à utiliser pour la mise à l'échelle de l'image. Si omise ou négative, le ratio de l'image sera préservé.

`mode`

  Une des constantes `IMG_NEAREST_NEIGHBOUR`, `IMG_BILINEAR_FIXED`, `IMG_BICUBIC`, `IMG_BICUBIC_FIXED` ou toute autre (utilisera deux passages).

  > Note: `IMG_WEIGHTED4` n'est pas encore supporté.

### Valeurs de retour

Retourne l'objet de l'image mise à l'échelle en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Lève une ValueError si `width` ou `height` provoque un dépassement ou un sous-dépassement.

Lève une ValueError si `mode` est invalide.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `width` ou `height` provoque un dépassement ou un sous-dépassement.
8.4.0 | Lève désormais une ValueError si `mode` est invalide.
8.0.0 | En cas de succès, cette fonction retourne désormais une instance de GDImage ; auparavant, une resource était retournée.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Voir aussi

- imagecopyresized() - Copie et redimensionne une partie d'une image
- imagecopyresampled() - Copie, redimensionne, rééchantillonne une image

# imagesetbrush

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetbrush — Modifie la brosse pour le dessin des lignes

### Description

function imagesetbrush(GdImage `$image`, GdImage `$brush`): true

imagesetbrush() remplace la brosse courante pour le dessin des lignes par `brush`. Cette brosse sera alors utilisée avec des fonctions comme imageline() ou imagepolygon() et avec les couleurs spéciales `IMG_COLOR_BRUSHED` ou `IMG_COLOR_STYLEDBRUSHED`.

Attention

Il n'y a rien à faire lorsqu'on en a terminé avec une brosse, mais en cas de destruction de l'image de brosse, il ne FAUT plus utiliser les options `IMG_COLOR_BRUSHED` et `IMG_COLOR_STYLEDBRUSHED` avant d'avoir créé une nouvelle brosse.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`brush`

  Un objet d'image.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` et `brush` attendent désormais des instances de GdImage ; auparavant, des resources étaient attendues.

### Exemples

Exemple #1 Exemple avec imagesetbrush()

    <?php

    // Charge un mini-logo PHP
    $php = imagecreatefrompng('./php.png');

    // Création de l'image principale, 100x100
    $im = imagecreatetruecolor(100, 100);

    // Définit l'arrière-plan en blanc
    $white = imagecolorallocate($im, 255, 255, 255);
    imagefilledrectangle($im, 0, 0, 99, 99, $white);

    // Définit la brosse
    imagesetbrush($im, $php);

    // Dessine quelques brosses, chacune chevauchant la précédente
    imageline($im, 50, 50, 50, 60, IMG_COLOR_BRUSHED);

    // Affiche l'image dans le navigateur
    header('Content-type: image/png');

    imagepng($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imagesetclip

(PHP 7 >= 7.2.0, PHP 8)

imagesetclip — Définit le rectangle de coupure

### Description

function imagesetclip(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`
): true

imagesetclip() définit le rectangle de coupure actuel, c'est-à-dire la zone au-delà de laquelle aucun pixel ne sera dessiné.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`x1`

  La coordonnée x du coin supérieur gauche.

`y1`

  La coordonnée y du coin supérieur gauche.

`x2`

  La coordonnée x du coin inférieur droit.

`y2`

  La coordonnée y du coin inférieur droit.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Voir aussi

- imagegetclip() - Récupère le rectangle de coupure

# imagesetinterpolation

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagesetinterpolation — Définit la méthode d'interpolation

### Description

function imagesetinterpolation(GdImage `$image`, int `$method` = `IMG_BILINEAR_FIXED`): bool

Définit la méthode d'interpolation ; le fait de définir une méthode d'interpolation affecte le rendu de plusieurs fonctions en GD, par exemple la fonction imagerotate().

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`method`

  La méthode d'interpolation, qui peut être une parmi :

  - `IMG_BELL` : filtre Bell.
  - `IMG_BESSEL` : filtre Bessel.
  - `IMG_BICUBIC` : interpolation bicubique.
  - `IMG_BICUBIC_FIXED` : implémentation de point fixe d'une interpolation bicubique.
  - `IMG_BILINEAR_FIXED` : implémentation de point fixe d'une interpolation bilinéaire (`par défaut (y compris pour la création d'image)`).
  - `IMG_BLACKMAN` : fonction de fenêtre Blackman.
  - `IMG_BOX` : filtre de flou Box.
  - `IMG_BSPLINE` : interpolation Spline.
  - `IMG_CATMULLROM` : interpolation cubique Hermite spline.
  - `IMG_GAUSSIAN` : fonction gaussienne.
  - `IMG_GENERALIZED_CUBIC` : interpolation fractale cubique généralisée spline.
  - `IMG_HERMITE` : interpolation Hermite.
  - `IMG_HAMMING` : filtre Hamming.
  - `IMG_HANNING` : filtre Hanning.
  - `IMG_MITCHELL` : filtre Mitchell.
  - `IMG_POWER` : interpolation Power.
  - `IMG_QUADRATIC` : interpolation quadratique inverse.
  - `IMG_SINC` : fonction Sinc.
  - `IMG_NEAREST_NEIGHBOUR` : interpolation du voisin le plus proche.
  - `IMG_WEIGHTED4` : filtre Weighting.
  - `IMG_TRIANGLE` : interpolation Triangle.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagesetinterpolation()

    <?php
    // Chargement de l'image
    $im = imagecreate(500, 500);

    // Par défaut, l'interpolation est IMG_BILINEAR_FIXED ; utilisation
    // du filtre 'Mitchell' :
    imagesetinterpolation($im, IMG_MITCHELL);

    // On continue de travailler avec $im ...
    ?>

### Notes

La modification de la méthode d'interpolation affecte les fonctions suivantes lors du rendu :

- imageaffine()
- imagerotate()

### Voir aussi

- imagegetinterpolation() - Récupère la méthode d'interpolation

# imagesetpixel

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesetpixel — Dessine un pixel

### Description

function imagesetpixel(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

imagesetpixel() dessine un pixel aux coordonnées spécifiées.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`x`

  Coordonnée X.

`y`

  Coordonnée Y.

`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagesetpixel()

Un dessin aléatoire qui se termine par une image régulière.

    <?php

    $x = 200;
    $y = 200;

    $gd = imagecreatetruecolor($x, $y);

    $corners[0] = array('x' => 100, 'y' =>  10);
    $corners[1] = array('x' =>   0, 'y' => 190);
    $corners[2] = array('x' => 200, 'y' => 190);

    $red = imagecolorallocate($gd, 255, 0, 0);

    for ($i = 0; $i < 100000; $i++) {
      imagesetpixel($gd, round($x), round($y), $red);
      $a = rand(0, 2);
      $x = ($x + $corners[$a]['x']) / 2;
      $y = ($y + $corners[$a]['y']) / 2;
    }

    header('Content-Type: image/png');
    imagepng($gd);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies
- imagecolorallocate() - Alloue une couleur pour une image
- imagecolorat() - Retourne l'index de la couleur d'un pixel donné

# imagesetstyle

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetstyle — Configure le style pour le dessin des lignes

### Description

function imagesetstyle(GdImage `$image`, array `$style`): bool

imagesetstyle() permet de choisir le style à utiliser lors du dessin des lignes (comme avec les fonctions imageline() et imagepolygon()) lors de l'utilisation de la couleur spéciale `IMG_COLOR_STYLED` ou bien lors du dessin de lignes avec la couleur `IMG_COLOR_STYLEDBRUSHED`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`style`

  Un tableau de couleurs de pixels. Il est possible d'utiliser la constante `IMG_COLOR_TRANSPARENT` pour ajouter un pixel transparent. Il est à noter que `style` ne doit pas être un tableau array vide.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

L'exemple suivant dessine une ligne pointillée depuis le coin supérieur gauche vers le coin inférieur droit de l'image :

Exemple #1 Exemple pour imagesetstyle()

    <?php
    header("Content-type: image/jpeg");
    $im  = imagecreatetruecolor(100, 100);
    $w   = imagecolorallocate($im, 255, 255, 255);
    $red = imagecolorallocate($im, 255, 0, 0);

    /* Dessine une ligne pointillée de 5 pixels rouges, 5 pixels blancs */
    $style = array($red, $red, $red, $red, $red, $w, $w, $w, $w, $w);
    imagesetstyle($im, $style);
    imageline($im, 0, 0, 100, 100, IMG_COLOR_STYLED);

    /* Dessine une ligne avec des smileys, en utilisant imagesetbrush() et imagesetstyle */
    $style = array($w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $red);
    imagesetstyle($im, $style);

    $brush = imagecreatefrompng("http://www.libpng.org/pub/png/images/smile.happy.png");
    $w2 = imagecolorallocate($brush, 255, 255, 255);
    imagecolortransparent($brush, $w2);
    imagesetbrush($im, $brush);
    imageline($im, 100, 0, 0, 100, IMG_COLOR_STYLEDBRUSHED);

    imagejpeg($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagesetbrush() - Modifie la brosse pour le dessin des lignes
- imageline() - Dessine une ligne

# imagesetthickness

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetthickness — Modifie l'épaisseur d'un trait

### Description

function imagesetthickness(GdImage `$image`, int `$thickness`): true

imagesetthickness() modifie l'épaisseur du trait des lignes de l'image `image`. Cette épaisseur intervient dans les dessins de polygones, cercles, rectangles, etc. `thickness` est en pixels.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`thickness`

  L'épaisseur, en pixels.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagesetthickness()

    <?php

    // Création d'une image en 200x100
    $im = imagecreatetruecolor(200, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Définit l'arrière-plan en blanc
    imagefilledrectangle($im, 0, 0, 199, 99, $white);

    // Définit l'épaisseur de la ligne à 5
    imagesetthickness($im, 5);

    // Dessine le rectangle
    imagerectangle($im, 14, 14, 185, 85, $black);

    // Affichage de l'image sur le navigateur
    header('Content-Type: image/png');

    imagepng($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imagesettile

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesettile — Modifie l'image utilisée pour le carrelage

### Description

function imagesettile(GdImage `$image`, GdImage `$tile`): true

imagesettile() remplace l'image de pavement courante par l'image `tile`, à utiliser dans tous les remplissages (comme avec les fonctions imagefill() et imagefilledpolygon()) lors des remplissages avec l'option `IMG_COLOR_TILED`.

Une image de carrelage est une image utilisée pour remplir une zone, de manière répétitive. N'importe quelle image GD peut servir d'image de remplissage. L'utilisation de la couleur transparente (gérée avec la fonction imagecolortransparent()) permet à certaines zones d'apparaître à travers le carrelage.

Attention

Il n'y a rien à faire lorsqu'on en a terminé avec un carrelage, mais en cas de destruction de l'image de carrelage (ou si PHP la détruit), il ne FAUT plus utiliser l'option `IMG_COLOR_TILED` des fonctions imagefill() et imagefilledpolygon(), avant d'avoir créé un nouveau carrelage.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`tile`

  L'objet image à utiliser en tant que carrelage.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` et `tile` attendent désormais des instances de GdImage ; auparavant, des resources étaient attendues.

### Exemples

Exemple #1 Exemple avec imagesettile()

    <?php
    // Chargement d'une image externe
    $zend = imagecreatefromgif('./zend.gif');

    // Création d'une image de 200x200 pixels
    $im = imagecreatetruecolor(200, 200);

    // Définition du carrelage
    imagesettile($im, $zend);

    // Répétition de l'image
    imagefilledrectangle($im, 0, 0, 199, 199, IMG_COLOR_TILED);

    // Affichage vers le navigateur
    header('Content-Type: image/png');

    imagepng($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# imagestring

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestring — Dessine une chaîne horizontale

### Description

function imagestring(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Dessine une chaîne aux coordonnées spécifiées.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`font`
  Peut être 1, 2, 3, 4, 5 pour les polices internes d'encodage Latin2 (où les plus grands nombres correspondent aux polices larges) ou une instance de GdFont retourné par imageloadfont().
`x`

  X : coordonnée du coin en haut, à gauche.

`y`

  Y : coordonnée du coin en haut, à gauche.

`string`

  La chaîne de caractères à écrire.

`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `font` accepte désormais une instance de GdFont et un entier; auparavant seulement un entier était accepté.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagestring()

    <?php
    // Nouvelle image 100*30
    $im = imagecreate(100, 30);

    // Fond blanc et texte bleu
    $bg = imagecolorallocate($im, 255, 255, 255);
    $textcolor = imagecolorallocate($im, 0, 0, 255);

    // Ajout de la phrase en haut à gauche
    imagestring($im, 5, 0, 0, 'Hello world!', $textcolor);

    // Affichage de l'image
    header('Content-type: image/png');

    imagepng($im);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagestringup() - Dessine une chaîne verticale
- imageloadfont() - Charge une nouvelle police
- imagettftext() - Dessine un texte avec une police TrueType

# imagestringup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestringup — Dessine une chaîne verticale

### Description

function imagestringup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Dessine une chaîne sur une ligne verticale dans l'image `image` aux coordonnées spécifiées.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`font`
  Peut être 1, 2, 3, 4, 5 pour les polices internes d'encodage Latin2 (où les plus grands nombres correspondent aux polices larges) ou une instance de GdFont retourné par imageloadfont().
`x`

  Coordonnée X du coin en bas, à gauche.

`y`

  Coordonnée Y du coin en bas, à gauche.

`string`

  La chaîne de caractères à écrire.

`color`

  Un identificateur de couleur créé avec imagecolorallocate().

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.1.0 | Le paramètre `font` accepte désormais une instance de GdFont et un entier; auparavant seulement un entier était accepté.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagestringup()

    <?php
    // Création d'une image de 100*100 pixels
    $im = imagecreatetruecolor(100, 100);

    // Dessine un texte
    $textcolor = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    imagestringup($im, 3, 40, 80, 'gd library', $textcolor);

    // Sauvegarde l'image
    imagepng($im, './stringup.png');
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- imagestring() - Dessine une chaîne horizontale
- imageloadfont() - Charge une nouvelle police

# imagesx

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesx — Retourne la largeur d'une image

### Description

function imagesx(GdImage `$image`): int

Retourne la largeur de l'objet image `image`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().

### Valeurs de retour

Retourne la largeur de l'image `image`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagesx()

    <?php

    // Création d'une image 300*200
    $img = imagecreatetruecolor(300, 200);

    echo imagesx($img); // 300

    ?>

### Voir aussi

- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies
- getimagesize() - Retourne la taille d'une image
- imagesy() - Retourne la hauteur de l'image

# imagesy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesy — Retourne la hauteur de l'image

### Description

function imagesy(GdImage `$image`): int

Retourne la hauteur de l'image `image`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().

### Valeurs de retour

Retourne la hauteur de l'image `image`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Exemple avec imagesy()

    <?php

    // Création d'une image 300*200
    $img = imagecreatetruecolor(300, 200);

    echo imagesy($img); // 200

    ?>

### Voir aussi

- imagecreatetruecolor() - Crée une nouvelle image en couleurs vraies
- getimagesize() - Retourne la taille d'une image
- imagesx() - Retourne la largeur d'une image

# imagetruecolortopalette

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagetruecolortopalette — Convertit une image en couleurs vraies en image à palette

### Description

function imagetruecolortopalette(GdImage `$image`, bool `$dither`, int `$num_colors`): bool

imagetruecolortopalette() convertit l'image en vraies couleurs `image` en image à palette. Le code de cette fonction est directement tiré de la bibliothèque du `Independent JPEG Group`, qui est tout simplement génial. Le code a été modifié pour préserver l'essentiel du canal alpha dans la nouvelle palette, en plus de conserver les couleurs du mieux possible. Mais cela ne fonctionne pas toujours comme voulu. Il est alors préférable de générer un résultat en vraies couleurs, ce qui donne toujours le meilleur rendu.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`dither`

  Indique si l'image doit être granuleuse - si défini à `true`, alors l'image sera un peu plus granuleuse mais l'approximation des couleurs sera meilleure.

`num_colors`

  Le nombre maximal de couleurs dans la palette finale.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Conversion d'une image truecolor en une palette

    <?php
    // Création d'une image truecolor
    $im = imagecreatetruecolor(100, 100);

    // Conversion en palette sans tramage et avec 255 couleurs
    imagetruecolortopalette($im, false, 255);

    // Sauvegarde de l'image
    imagepng($im, './paletteimage.png');
    ?>

# imagettfbbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettfbbox — Retourne le rectangle entourant un texte et dessiné avec une police TrueType

### Description

function imagettfbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

Cette fonction calcule et retourne le rectangle entourant, en pixels, pour un texte TrueType.

> Note:

> Antérieur à PHP 8.0.0, imageftbbox() était une variante étendue de imagettfbbox() qui en plus supportait `extrainfo`. À partir de PHP 8.0.0, imagettfbbox() est un alias de imageftbbox().

### Liste de paramètres

`size`

  La taille de la police de caractères en point.

`angle`

  L'angle, en degrés, dans lequel le paramètre `string` sera mesuré.

`fontfile`
  Le chemin d'accès à la police TrueType que vous souhaitez utiliser. Selon la version de la bibliothèque GD que PHP utilise, quand `fontfile` ne commence pas par une premier `/` alors `.ttf` sera ajouté au nom de fichier et la bibliothèque essaiera de rechercher ce nom de fichier le long d'un chemin de police défini par la bibliothèque. Lorsque vous utilisez des versions de la bibliothèque GD inférieure à 2.0.18, un caractère `espace`, plutôt qu'un point-virgule, a été utilisé comme séparateur de chemin d'accès pour différents fichiers de police. L'utilisation involontaire de cette fonctionnalité se traduira par le message d'avertissement: `Avertissement: impossible de trouver/ouvrir la police`. Pour ces versions affectées, la seule solution consiste à déplacer la police vers un chemin qui ne contient pas d'espaces.

  Dans de nombreux cas où une police réside dans le même répertoire que le script en l'utilisant l'astuce suivante permettra d'atténuer les problèmes d'inclusion.

      <?php
      // Définir la variable d'environnement pour GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Nommez la police à utiliser (Notez l'absence de l'extension .ttf)
      $font = 'SomeFont';
      ?>

  > Note: Notez que open_basedir ne s'applique pas à `fontfile`.

`string`

  La chaîne à mesurer.

`options`

  Similaire à imagettftext().

### Valeurs de retour

imagettfbbox() retourne un tableau avec 8 éléments représentant les 4 sommets du rectangle en cas de succès, `false` si une erreur survient.

Clé | Signification
--- | ---
0 | Coin inférieur gauche, abscisse
1 | Coin inférieur gauche, ordonnée
2 | Coin inférieur droit, abscisse
3 | Coin inférieur droit, ordonnée
4 | Coin supérieur droit, abscisse
5 | Coin supérieur droit, ordonnée
6 | Coin supérieur gauche, abscisse
7 | Coin supérieur gauche, ordonnée

Les positions des points sont relatives au texte text, indépendamment de l'angle : coin supérieur gauche fait référence au coin supérieur gauche du texte écrit horizontalement.

### Historique

Version | Description
--- | ---
8.0.0 | Le paramètre `options` a été ajouté.

### Exemples

Exemple #1 Exemple avec imagettfbbox()

    <?php
    // Création d'une image de 300x150 pixels
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Définit l'arrière-plan en blanc
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Chemin vers le fichier de police
    $font = './arial.ttf';

    // Tout d'abord, nous créons notre rectangle entourant notre premier texte
    $bbox = imagettfbbox(10, 45, $font, 'Powered by PHP ' . phpversion());

    // Nos coordonnées en X et en Y
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 25;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Dessin du texte
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'Powered by PHP ' . phpversion());

    // Nous créons notre rectangle entourant notre second texte
    $bbox = imagettfbbox(10, 45, $font, 'and Zend Engine ' . zend_version());

    // Définit les coordonnées afin que le second texte suive le premier
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) + 10;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Dessin du texte
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'and Zend Engine ' . zend_version());

    // Affichage vers le navigateur
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Notes

> Note: Cette fonction n'est disponible que si si PHP est compilé avec le support Freetype (--with-freetype-dir=DIR)

### Voir aussi

- imagettftext() - Dessine un texte avec une police TrueType
- imageftbbox() - Calcule le rectangle d'encadrement pour un texte, en utilisant la police courante et freetype2

# imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext — Dessine un texte avec une police TrueType

### Description

function imagettftext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

imagettftext() dessine le texte `text` avec la police TrueType `fontfile`.

> Note:

> Antérieur à PHP 8.0.0, imagefttext() était une variante étendue de imagettftext() qui en plus supportait `extrainfo`. À partir de PHP 8.0.0, imagettftext() est un alias de imagefttext().

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`size`

  La taille de la police de caractères en point.

`angle`

  L'angle, en degrés ; 0 degré correspond à la lecture du texte de gauche à droite. Des valeurs plus élevées représentent une rotation dans le sens contraire des aiguilles d'une montre. Par exemple, une valeur de 90 correspondra à une lecture du texte de bas en haut.

`x`

  Les coordonnées données par `x` et `y` définiront le point de base du premier caractère (approximativement le coin bas-gauche du caractère). Cela est différent de la fonction imagestring(), où `x` et `y` définissent le coin haut-gauche du premier caractère. Par exemple, "haut gauche" correspond à 0, 0.

`y`

  L'ordonnée Y. Cela définit la position de la ligne de base de la police, et non pas le bas des caractères.

`color`

  L'index de la couleur. Utiliser un index de couleur négatif désactivera l'antialiasing. Voir la fonction imagecolorallocate().

`fontfile`
  Le chemin d'accès à la police TrueType que vous souhaitez utiliser. Selon la version de la bibliothèque GD que PHP utilise, quand `fontfile` ne commence pas par une premier `/` alors `.ttf` sera ajouté au nom de fichier et la bibliothèque essaiera de rechercher ce nom de fichier le long d'un chemin de police défini par la bibliothèque. Lorsque vous utilisez des versions de la bibliothèque GD inférieure à 2.0.18, un caractère `espace`, plutôt qu'un point-virgule, a été utilisé comme séparateur de chemin d'accès pour différents fichiers de police. L'utilisation involontaire de cette fonctionnalité se traduira par le message d'avertissement: `Avertissement: impossible de trouver/ouvrir la police`. Pour ces versions affectées, la seule solution consiste à déplacer la police vers un chemin qui ne contient pas d'espaces.

  Dans de nombreux cas où une police réside dans le même répertoire que le script en l'utilisant l'astuce suivante permettra d'atténuer les problèmes d'inclusion.

      <?php
      // Définir la variable d'environnement pour GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Nommez la police à utiliser (Notez l'absence de l'extension .ttf)
      $font = 'SomeFont';
      ?>

  > Note: Notez que open_basedir ne s'applique pas à `fontfile`.

`text`

  La chaîne de texte, en UTF-8.

  Peut inclure des références à des caractères numériques décimales (sous la forme : `&#8364;`) pour accéder aux caractères d'une police au-delà de la position 127. Le format hexadécimal (comme `&#xA9;`) est pris en charge. Les chaînes de caractères encodées en UTF-8 peuvent être passées directement.

  Les entités nommées, comme `&copy;`, ne sont pas supportées. Utiliser la fonction html_entity_decode() pour décoder ces entités nommées en chaînes UTF-8.

  Si un caractère est utilisé dans une chaîne qui n'est pas supportée par la police, un rectangle creux remplacera le caractère.

`options`

  Un tableau avec une clé `linespacing` contenant une valeur float.

### Valeurs de retour

Retourne un tableau de 8 éléments représentant quatre points marquant les limites du texte. L'ordre des points est : inférieur gauche, inférieur droit, supérieur droit, supérieur gauche. Les points sont relatifs au texte par rapport à l'angle, donc, "supérieur gauche" signifie dans le coin en haut à gauche lorsqu'on regarde le texte horizontalement. Retourne `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | Le paramètre `options` a été ajouté.

### Exemples

Exemple #1 Exemple avec imagettftext()

Cet exemple produira une image PNG blanche de 400x30 pixels, avec le texte `"Test..."` en noir, avec une ombre grise, utilisant la police Arial.

    <?php

    // Définition du content-type
    header('Content-Type: image/png');

    // Création de l'image
    $im = imagecreatetruecolor(400, 30);

    // Création de quelques couleurs
    $white = imagecolorallocate($im, 255, 255, 255);
    $grey = imagecolorallocate($im, 128, 128, 128);
    $black = imagecolorallocate($im, 0, 0, 0);
    imagefilledrectangle($im, 0, 0, 399, 29, $white);

    // Le texte à dessiner
    $text = 'Test...';

    // Remplacez le chemin par votre propre chemin de police
    $font = 'arial.ttf';

    // Ajout d'ombres au texte
    imagettftext($im, 20, 0, 11, 21, $grey, $font, $text);

    // Ajout du texte
    imagettftext($im, 20, 0, 10, 20, $black, $font, $text);

    // Utiliser imagepng() donnera un texte plus clair,
    // comparé à l'utilisation de la fonction imagejpeg()
    imagepng($im);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Notes

> Note: Cette fonction n'est disponible que si si PHP est compilé avec le support Freetype (--with-freetype-dir=DIR)

### Voir aussi

- imagettfbbox() - Retourne le rectangle entourant un texte et dessiné avec une police TrueType
- imagefttext() - Écrit du texte dans une image avec la police courante FreeType 2
- imagestring() - Dessine une chaîne horizontale

# imagetypes

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

imagetypes — Retourne les types d'images supportés par la version courante de PHP

### Description

function imagetypes(): int

Retourne un champ de bits correspondant aux formats d'images supportés par la version PHP utilisée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un champ de bits correspondant aux formats d'images supportés par la version de GD utilisée. Les valeurs suivantes sont possibles : `IMG_AVIF` | `IMG_BMP` | `IMG_GIF` | `IMG_JPG` | `IMG_PNG` | `IMG_WBMP` | `IMG_XPM` | `IMG_WEBP`.

### Historique

Version | Description
--- | ---
8.1.0 | Ajout de la constante `IMG_AVIF`.
7.2.0 | Ajout de la constante `IMG_BMP`.
7.0.10 | Ajout de la constante `IMG_WEBP`.

### Exemples

Exemple #1 Exemple avec imagetypes()

    <?php
    if (imagetypes() & IMG_PNG) {
        echo "Le type PNG est supporté";
    }
    ?>

### Voir aussi

- gd_info() - Retourne des informations à propos de la bibliothèque GD installée

# imagewbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagewbmp — Affichage de l'image vers le navigateur ou dans un fichier

### Description

function imagewbmp(GdImage `$image`, resource|string|null `$file` = `null`, ?int `$foreground_color` = `null`): bool

imagewbmp() affiche ou sauvegarde une version WBMP de l'image `image`.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`file`

  Le chemin ou un flux de ressource ouvert (qui sera automatiquement fermé après le retour de cette fonction) vers lequel le fichier sera sauvegardé. Si non-défini ou `null`, le flux brute de l'image sera affiché directement.

`foreground_color`

  Il est possible de choisir la couleur de premier plan avec ce paramètre. Il convient d'utiliser l'identifiant retourné par imagecolorallocate() comme valeur de ce paramètre. La couleur de premier plan par défaut est noire.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
8.0.0 | `foreground_color` est désormais nullable.

### Exemples

Exemple #1 Affichage d'une image WBMP

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texte simple', $text_color);

    // Définit le contenu de l'en-tête - dans ce cas, image/vnd.wap.wbmp
    // Astuce : voir la fonction image_type_to_mime_type() pour les types de contenu
    header('Content-Type: image/vnd.wap.wbmp');

    // Affichage de l'image
    imagewbmp($im);

    ?>

Exemple #2 Sauvegarde de l'image WBMP

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texte simple', $text_color);

    // Sauvegarde de l'image
    imagewbmp($im, 'simpletext.wbmp');

    ?>

Exemple #3 Affichage de l'image avec un premier-plan différent

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texte simple', $text_color);

    // Définit le contenu de l'en-tête - dans ce cas, image/vnd.wap.wbmp
    // Astuce : voir la fonction image_type_to_mime_type() pour les types de contenu
    header('Content-type: image/vnd.wap.wbmp');

    // Définit un premier-plan
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    imagewbmp($im, NULL, $foreground_color);

    ?>

### Voir aussi

- image2wbmp() - Affichage de l'image vers le navigateur ou dans un fichier
- imagepng() - Envoie une image PNG vers un navigateur ou un fichier
- imagegif() - Affichage de l'image vers le navigateur ou dans un fichier
- imagejpeg() - Affichage de l'image vers le navigateur ou dans un fichier
- imagetypes() - Retourne les types d'images supportés par la version courante de PHP

# imagewebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagewebp — Affiche une image WebP vers un navigateur ou un fichier

### Description

function imagewebp(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

Affiche ou sauvegarde une version WebP de l'`image` fournie.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`file`

  Le chemin ou un flux de ressource ouvert (qui sera automatiquement fermé après le retour de cette fonction) vers lequel le fichier sera sauvegardé. Si non-défini ou `null`, le flux brute de l'image sera affiché directement.

`quality`

  `quality` plage de 0 (la pire qualité, plus petit fichier) à 100 (meilleure qualité, plus grand fichier). Si la valeur `-1` est fournie, la valeur par défaut `80` est utilisée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Erreurs / Exceptions

Lève une ValueError si `quality` est invalide.

### Historique

Version | Description
--- | ---
8.4.0 | Lève désormais une ValueError si `quality` est invalide.
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.

### Exemples

Exemple #1 Sauvegarde d'un fichier WebP

    <?php
    // Crée une image vide et on y ajoute du texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'WebP avec PHP', $text_color);

    // Sauvegarde de l'image
    imagewebp($im, 'php.webp');

    ?>

# imagexbm

(PHP 5, PHP 7, PHP 8)

imagexbm — Génère une image au format XBM

### Description

function imagexbm(GdImage `$image`, ?string `$filename`, ?int `$foreground_color` = `null`): bool

Affiche ou sauvegarde une version XBM de l'image `image`.

> Note: imagexbm() n'applique pas de rembourrage, de sorte que la largeur de l'image doit être un multiple de 8. Cette restriction ne s'applique plus à partir de PHP 7.0.9.

### Liste de paramètres

`image`
  Un objet GdImage, retournée par une des fonctions de création d'images, comme imagecreatetruecolor().
`filename`

  Chemin d'accès où le fichier sera enregistré, sous la forme d'une chaîne de caractères. S'il n'est pas défini, le flux d'images RAW sera directement affiché sur la sortie standard.

  Le nom de fichier `filename` (sans l'extension .xbm) est également utilisé pour les identificateurs C du XBM, auquel cas les caractères non alphanumériques des paramètres régionaux actuels sont remplacés par des tirets bas. Si `filename` a la valeur `null`, `image` est utilisé pour générer les identificateurs C.

`foreground_color`

  Il est possible de définir la couleur du premier plan avec ce paramètre, en utilisant un identifiant obtenu depuis la fonction imagecolorallocate(). Par défaut, la couleur du premier plan est noire. Toutes les autres couleurs sont traitées comme arrière-plan.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Historique

Version | Description
--- | ---
8.0.0 | `image` attend une instance de GdImage désormais; auparavant, une resource `gd` était attendue.
8.0.0 | `foreground_color` est désormais nullable.
8.0.0 | Le quatrième paramètre, qui n'était pas utilisé, a été supprimé.

### Exemples

Exemple #1 Sauvegarde d'un fichier XBM

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texte simple', $text_color);

    // Sauvegarde de l'image
    imagexbm($im, 'simpletext.xbm');

    ?>

Exemple #2 Sauvegarde d'un fichier XBM avec une couleur de premier plan différente

    <?php
    // Création d'une image vide et ajout d'un texte
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Un texte simple', $text_color);

    // Définit la couleur de premier plan
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    // Sauvegarde de l'image
    imagexbm($im, NULL, $foreground_color);

    ?>

# iptcembed

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcembed — Intègre des données binaires IPTC dans une image JPEG

### Description

function iptcembed(string `$iptc_data`, string `$filename`, int `$spool` = 0): string|bool

iptcembed() intègre des données binaires IPTC dans une image JPEG.

### Liste de paramètres

`iptc_data`

  Les données à écrire.

`filename`

  Chemin vers le fichier JPEG.

`spool`

  Le drapeau de la bobine. Si la bobine est inférieure à 2, alors le fichier JPEG sera retourné sous la forme d'une chaîne de caractères. Autrement le fichier JPEG sera envoyé à STDOUT.

### Valeurs de retour

Si `spool` est inférieur à 2, le fichier JPEG sera retourné, ou `false` si une erreur survient. Sinon retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec iptcembed()

    <?php

    // Fonction iptc_make_tag() par Thies C. Arntzen
    function iptc_make_tag($rec, $data, $value)
    {
        $length = strlen($value);
        $retval = chr(0x1C) . chr($rec) . chr($data);

        if($length < 0x8000)
        {
            $retval .= chr($length >> 8) .  chr($length & 0xFF);
        }
        else
        {
            $retval .= chr(0x80) .
                       chr(0x04) .
                       chr(($length >> 24) & 0xFF) .
                       chr(($length >> 16) & 0xFF) .
                       chr(($length >> 8) & 0xFF) .
                       chr($length & 0xFF);
        }

        return $retval . $value;
    }

    // Chemin vers le fichier JPEG
    $path = './phplogo.jpg';

    // Définit les étiquettes IPTC
    $iptc = array(
        '2#120' => 'Test image',
        '2#116' => 'Copyright 2008-2009, The PHP Group'
    );

    // Conversion des étiquettes IPTC en code binaire
    $data = '';

    foreach($iptc as $tag => $string)
    {
        $tag = substr($tag, 2);
        $data .= iptc_make_tag(2, $tag, $string);
    }

    // Intégration des données IPTC
    $content = iptcembed($data, $path);

    // Écrit les données de la nouvelle image dans un fichier.
    $fp = fopen($path, "wb");
    fwrite($fp, $content);
    fclose($fp);
    ?>

### Notes

> Note: Cette fonction ne nécessite pas la bibliothèque GD.

# iptcparse

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcparse — Analyse un bloc binaire IPTC et recherche les balises simples

### Description

function iptcparse(string `$iptc_block`): array|false

Analyse un bloc binaire » IPTC et recherche les balises simples.

### Liste de paramètres

`iptc_block`

  Un bloc binaire IPTC.

### Valeurs de retour

Retourne un tableau avec les balises comme index et les valeurs de ces balises IPTC dans les valeurs de tableau correspondantes. En cas d'erreur, ou si aucune balise IPTC n'a été trouvée, cette fonction retourne `false`.

### Exemples

Exemple #1 Exemple avec iptcparse() et getimagesize()

    <?php
    $size = getimagesize('./test.jpg', $info);
    if(isset($info['APP13']))
    {
        $iptc = iptcparse($info['APP13']);
        var_dump($iptc);
    }
    ?>

### Notes

> Note: Cette fonction ne nécessite pas la bibliothèque GD.

# jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

jpeg2wbmp — Convertit une image JPEG en image WBMP

Avertissement

Cette fonctionnalité est OBSOLÈTE à partir de PHP 7.2.0 et a été SUPPRIMÉE à partir de PHP 8.0.0.

### Description

function jpeg2wbmp(
string `$jpegname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Convertit une image JPEG en image WBMP.

### Liste de paramètres

`jpegname`

  Le chemin vers le fichier JPEG.

`wbmpname`

  Chemin vers le fichier final WBMP.

`dest_height`

  Hauteur de l'image de destination.

`dest_width`

  Largeur de l'image de destination.

`threshold`

  Valeur du seuil, entre 0 et 8 inclus.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Exemples

Exemple #1 Exemple avec jpeg2wbmp()

    <?php
    // Chemin vers la cible jpeg
    $path = './test.jpg';

    // Récupération de la taille de l'image
    $image = getimagesize($path);

    // Conversion de l'image
    jpeg2wbmp($path, './test.wbmp', $image[1], $image[0], 5);
    ?>

### Voir aussi

- png2wbmp() - Convertit une image PNG en image WBMP

# png2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

png2wbmp — Convertit une image PNG en image WBMP

Avertissement

Cette fonctionnalité est OBSOLÈTE à partir de PHP 7.2.0 et a été SUPPRIMÉE à partir de PHP 8.0.0.

### Description

function png2wbmp(
string `$pngname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Convertit une image PNG en image WBMP.

### Liste de paramètres

`pngname`

  Chemin vers le fichier PNG.

`wbmpname`

  Chemin vers le fichier final WBMP.

`dest_height`

  Hauteur de l'image de destination.

`dest_width`

  Largeur de l'image de destination.

`threshold`

  Valeur du seuil, entre 0 et 8 (inclus).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

Attention

Toutefois, si libgd ne parvient pas à produire l'image, cette fonction retourne `true`.

### Exemples

Exemple #1 Exemple avec png2wbmp()

    <?php
    // Chemin vers la cible png
    $path = './test.png';

    // Récupération de la taille de l'image
    $image = getimagesize($path);

    // Conversion de l'image
    png2wbmp($path, './test.wbmp', $image[1], $image[0], 7);
    ?>

### Voir aussi

- jpeg2wbmp() - Convertit une image JPEG en image WBMP

## Sommaire

- gd_info — Retourne des informations à propos de la bibliothèque GD installée
- getimagesize — Retourne la taille d'une image
- getimagesizefromstring — Récupère la taille d'une image depuis une chaîne
- image_type_to_extension — Retourne l'extension du fichier pour le type d'image
- image_type_to_mime_type — Lit le Mime-Type d'un type d'image
- image2wbmp — Affichage de l'image vers le navigateur ou dans un fichier
- imageaffine — Retourne une image contenant l'image source transformée, en utilisant optionnellement une zone de découpe
- imageaffinematrixconcat — Concatène deux matrices de transformation affine
- imageaffinematrixget — Obtenir une matrice de transformation affine
- imagealphablending — Modifie le mode de blending d'une image
- imageantialias — Utiliser ou non les fonctions d'antialias
- imagearc — Dessine un arc
- imageavif — Affichage de l'image vers le navigateur ou dans un fichier
- imagebmp — Affiche ou enregistre une image BMP au navigateur ou dans un fichier
- imagechar — Dessine un caractère horizontalement
- imagecharup — Dessine un caractère verticalement
- imagecolorallocate — Alloue une couleur pour une image
- imagecolorallocatealpha — Alloue une couleur à une image
- imagecolorat — Retourne l'index de la couleur d'un pixel donné
- imagecolorclosest — Retourne l'index de la couleur la plus proche d'une couleur donnée
- imagecolorclosestalpha — Retourne la couleur la plus proche, en tenant compte du canal alpha
- imagecolorclosesthwb — Récupère l'index de la couleur ayant la teinte, le blanc et le noir
- imagecolordeallocate — Supprime une couleur d'une image
- imagecolorexact — Retourne l'index de la couleur donnée
- imagecolorexactalpha — Retourne l'index d'une couleur avec son canal alpha
- imagecolormatch — Fait correspondre un peu plus les couleurs de la version palette d'une image aux couleurs de sa version truecolor
- imagecolorresolve — Retourne l'index de la couleur donnée, ou la plus proche possible
- imagecolorresolvealpha — Retourne un index de couleur ou son alternative la plus proche, y compris le canal alpha
- imagecolorset — Change la couleur dans une palette à l'index donné
- imagecolorsforindex — Retourne la couleur associée à un index
- imagecolorstotal — Calcule le nombre de couleurs d'une palette
- imagecolortransparent — Définit la couleur transparente
- imageconvolution — Applique une matrice de convolution 3x3, en utilisant un coefficient et un décalage
- imagecopy — Copie une partie d'une image
- imagecopymerge — Copie et fusionne une partie d'une image
- imagecopymergegray — Copie et fusionne une partie d'une image en niveaux de gris
- imagecopyresampled — Copie, redimensionne, rééchantillonne une image
- imagecopyresized — Copie et redimensionne une partie d'une image
- imagecreate — Crée une nouvelle image à palette
- imagecreatefromavif — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefrombmp — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefromgd — Crée une nouvelle image à partir d'un fichier GD ou d'une URL
- imagecreatefromgd2 — Crée une nouvelle image à partir d'un fichier GD2 ou d'une URL
- imagecreatefromgd2part — Crée une nouvelle image à partir d'une partie de fichier GD2 ou d'une URL
- imagecreatefromgif — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefromjpeg — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefrompng — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefromstring — Crée une image à partir d'une chaîne
- imagecreatefromtga — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefromwbmp — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefromwebp — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefromxbm — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatefromxpm — Crée une nouvelle image depuis un fichier ou une URL
- imagecreatetruecolor — Crée une nouvelle image en couleurs vraies
- imagecrop — Recadre une image sur le rectangle donné
- imagecropauto — Recadre une image automatiquement en utilisant un des modes disponibles
- imagedashedline — Dessine une ligne pointillée
- imagedestroy — Détruit une image
- imageellipse — Dessine une ellipse
- imagefill — Remplissage par diffusion
- imagefilledarc — Dessine un arc partiel et le remplit
- imagefilledellipse — Dessine une ellipse pleine
- imagefilledpolygon — Dessine un polygone rempli
- imagefilledrectangle — Dessine un rectangle rempli
- imagefilltoborder — Remplit une région avec une couleur spécifique
- imagefilter — Applique un filtre à une image
- imageflip — Retourne une image en utilisant le mode fourni
- imagefontheight — Retourne la hauteur de la police
- imagefontwidth — Retourne la largeur de la police
- imageftbbox — Calcule le rectangle d'encadrement pour un texte, en utilisant la police courante et freetype2
- imagefttext — Écrit du texte dans une image avec la police courante FreeType 2
- imagegammacorrect — Applique une correction gamma à l'image GD
- imagegd — Génère une image au format GD, vers le navigateur ou un fichier
- imagegd2 — Génère une image au format GD2, vers le navigateur ou un fichier
- imagegetclip — Récupère le rectangle de coupure
- imagegetinterpolation — Récupère la méthode d'interpolation
- imagegif — Affichage de l'image vers le navigateur ou dans un fichier
- imagegrabscreen — Capture l'écran complet
- imagegrabwindow — Capture une fenêtre
- imageinterlace — Active ou désactive l'entrelacement
- imageistruecolor — Détermine si une image est une image truecolor
- imagejpeg — Affichage de l'image vers le navigateur ou dans un fichier
- imagelayereffect — Active l'option d'alpha blending, pour utiliser les effets de libgd
- imageline — Dessine une ligne
- imageloadfont — Charge une nouvelle police
- imageopenpolygon — Dessine un polygone ouvert
- imagepalettecopy — Copie la palette d'une image à l'autre
- imagepalettetotruecolor — Convertit une image basée sur une palette en couleur vraie
- imagepng — Envoie une image PNG vers un navigateur ou un fichier
- imagepolygon — Dessine un polygone
- imagerectangle — Dessine un rectangle
- imageresolution — Récupère ou définit la résolution de l'image
- imagerotate — Fait tourner une image d'un angle
- imagesavealpha — Détermine si les informations complètes du canal alpha doivent être conservées lors de la sauvegarde d'images
- imagescale — Met à l'échelle une image en utilisant une hauteur et une largeur fournies
- imagesetbrush — Modifie la brosse pour le dessin des lignes
- imagesetclip — Définit le rectangle de coupure
- imagesetinterpolation — Définit la méthode d'interpolation
- imagesetpixel — Dessine un pixel
- imagesetstyle — Configure le style pour le dessin des lignes
- imagesetthickness — Modifie l'épaisseur d'un trait
- imagesettile — Modifie l'image utilisée pour le carrelage
- imagestring — Dessine une chaîne horizontale
- imagestringup — Dessine une chaîne verticale
- imagesx — Retourne la largeur d'une image
- imagesy — Retourne la hauteur de l'image
- imagetruecolortopalette — Convertit une image en couleurs vraies en image à palette
- imagettfbbox — Retourne le rectangle entourant un texte et dessiné avec une police TrueType
- imagettftext — Dessine un texte avec une police TrueType
- imagetypes — Retourne les types d'images supportés par la version courante de PHP
- imagewbmp — Affichage de l'image vers le navigateur ou dans un fichier
- imagewebp — Affiche une image WebP vers un navigateur ou un fichier
- imagexbm — Génère une image au format XBM
- iptcembed — Intègre des données binaires IPTC dans une image JPEG
- iptcparse — Analyse un bloc binaire IPTC et recherche les balises simples
- jpeg2wbmp — Convertit une image JPEG en image WBMP
- png2wbmp — Convertit une image PNG en image WBMP

# La classe GdImage

(PHP 8)

## Introduction

Une classe totalement opaque qui remplace les ressources `gd` à partir de PHP 8.0.0.

## Synopsis de la classe

final class GdImage {
}

# La classe GdFont

(PHP 8 >= 8.1.0)

## Introduction

Une classe complètement opaque qui remplace la resource `gd font` à partir de PHP 8.1.0.

## Synopsis de la classe

final class GdFont {
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Exemples
  - Création d'une image PNG avec PHP
  - Ajout d'un tatouage numérique sur des images en utilisant un canal Alpha
  - Exemple avec imagecopymerge pour créer un tatouage numérique translucide
- Fonctions GD et images
  - gd_info — Retourne des informations à propos de la bibliothèque GD installée
  - getimagesize — Retourne la taille d'une image
  - getimagesizefromstring — Récupère la taille d'une image depuis une chaîne
  - image_type_to_extension — Retourne l'extension du fichier pour le type d'image
  - image_type_to_mime_type — Lit le Mime-Type d'un type d'image
  - image2wbmp — Affichage de l'image vers le navigateur ou dans un fichier
  - imageaffine — Retourne une image contenant l'image source transformée, en utilisant optionnellement une zone de découpe
  - imageaffinematrixconcat — Concatène deux matrices de transformation affine
  - imageaffinematrixget — Obtenir une matrice de transformation affine
  - imagealphablending — Modifie le mode de blending d'une image
  - imageantialias — Utiliser ou non les fonctions d'antialias
  - imagearc — Dessine un arc
  - imageavif — Affichage de l'image vers le navigateur ou dans un fichier
  - imagebmp — Affiche ou enregistre une image BMP au navigateur ou dans un fichier
  - imagechar — Dessine un caractère horizontalement
  - imagecharup — Dessine un caractère verticalement
  - imagecolorallocate — Alloue une couleur pour une image
  - imagecolorallocatealpha — Alloue une couleur à une image
  - imagecolorat — Retourne l'index de la couleur d'un pixel donné
  - imagecolorclosest — Retourne l'index de la couleur la plus proche d'une couleur donnée
  - imagecolorclosestalpha — Retourne la couleur la plus proche, en tenant compte du canal alpha
  - imagecolorclosesthwb — Récupère l'index de la couleur ayant la teinte, le blanc et le noir
  - imagecolordeallocate — Supprime une couleur d'une image
  - imagecolorexact — Retourne l'index de la couleur donnée
  - imagecolorexactalpha — Retourne l'index d'une couleur avec son canal alpha
  - imagecolormatch — Fait correspondre un peu plus les couleurs de la version palette d'une image aux couleurs de sa version truecolor
  - imagecolorresolve — Retourne l'index de la couleur donnée, ou la plus proche possible
  - imagecolorresolvealpha — Retourne un index de couleur ou son alternative la plus proche, y compris le canal alpha
  - imagecolorset — Change la couleur dans une palette à l'index donné
  - imagecolorsforindex — Retourne la couleur associée à un index
  - imagecolorstotal — Calcule le nombre de couleurs d'une palette
  - imagecolortransparent — Définit la couleur transparente
  - imageconvolution — Applique une matrice de convolution 3x3, en utilisant un coefficient et un décalage
  - imagecopy — Copie une partie d'une image
  - imagecopymerge — Copie et fusionne une partie d'une image
  - imagecopymergegray — Copie et fusionne une partie d'une image en niveaux de gris
  - imagecopyresampled — Copie, redimensionne, rééchantillonne une image
  - imagecopyresized — Copie et redimensionne une partie d'une image
  - imagecreate — Crée une nouvelle image à palette
  - imagecreatefromavif — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatefrombmp — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatefromgd — Crée une nouvelle image à partir d'un fichier GD ou d'une URL
  - imagecreatefromgd2 — Crée une nouvelle image à partir d'un fichier GD2 ou d'une URL
  - imagecreatefromgd2part — Crée une nouvelle image à partir d'une partie de fichier GD2 ou d'une URL
  - imagecreatefromgif — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatefromjpeg — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatefrompng — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatefromstring — Crée une image à partir d'une chaîne
  - imagecreatefromtga — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatefromwbmp — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatefromwebp — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatefromxbm — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatefromxpm — Crée une nouvelle image depuis un fichier ou une URL
  - imagecreatetruecolor — Crée une nouvelle image en couleurs vraies
  - imagecrop — Recadre une image sur le rectangle donné
  - imagecropauto — Recadre une image automatiquement en utilisant un des modes disponibles
  - imagedashedline — Dessine une ligne pointillée
  - imagedestroy — Détruit une image
  - imageellipse — Dessine une ellipse
  - imagefill — Remplissage par diffusion
  - imagefilledarc — Dessine un arc partiel et le remplit
  - imagefilledellipse — Dessine une ellipse pleine
  - imagefilledpolygon — Dessine un polygone rempli
  - imagefilledrectangle — Dessine un rectangle rempli
  - imagefilltoborder — Remplit une région avec une couleur spécifique
  - imagefilter — Applique un filtre à une image
  - imageflip — Retourne une image en utilisant le mode fourni
  - imagefontheight — Retourne la hauteur de la police
  - imagefontwidth — Retourne la largeur de la police
  - imageftbbox — Calcule le rectangle d'encadrement pour un texte, en utilisant la police courante et freetype2
  - imagefttext — Écrit du texte dans une image avec la police courante FreeType 2
  - imagegammacorrect — Applique une correction gamma à l'image GD
  - imagegd — Génère une image au format GD, vers le navigateur ou un fichier
  - imagegd2 — Génère une image au format GD2, vers le navigateur ou un fichier
  - imagegetclip — Récupère le rectangle de coupure
  - imagegetinterpolation — Récupère la méthode d'interpolation
  - imagegif — Affichage de l'image vers le navigateur ou dans un fichier
  - imagegrabscreen — Capture l'écran complet
  - imagegrabwindow — Capture une fenêtre
  - imageinterlace — Active ou désactive l'entrelacement
  - imageistruecolor — Détermine si une image est une image truecolor
  - imagejpeg — Affichage de l'image vers le navigateur ou dans un fichier
  - imagelayereffect — Active l'option d'alpha blending, pour utiliser les effets de libgd
  - imageline — Dessine une ligne
  - imageloadfont — Charge une nouvelle police
  - imageopenpolygon — Dessine un polygone ouvert
  - imagepalettecopy — Copie la palette d'une image à l'autre
  - imagepalettetotruecolor — Convertit une image basée sur une palette en couleur vraie
  - imagepng — Envoie une image PNG vers un navigateur ou un fichier
  - imagepolygon — Dessine un polygone
  - imagerectangle — Dessine un rectangle
  - imageresolution — Récupère ou définit la résolution de l'image
  - imagerotate — Fait tourner une image d'un angle
  - imagesavealpha — Détermine si les informations complètes du canal alpha doivent être conservées lors de la sauvegarde d'images
  - imagescale — Met à l'échelle une image en utilisant une hauteur et une largeur fournies
  - imagesetbrush — Modifie la brosse pour le dessin des lignes
  - imagesetclip — Définit le rectangle de coupure
  - imagesetinterpolation — Définit la méthode d'interpolation
  - imagesetpixel — Dessine un pixel
  - imagesetstyle — Configure le style pour le dessin des lignes
  - imagesetthickness — Modifie l'épaisseur d'un trait
  - imagesettile — Modifie l'image utilisée pour le carrelage
  - imagestring — Dessine une chaîne horizontale
  - imagestringup — Dessine une chaîne verticale
  - imagesx — Retourne la largeur d'une image
  - imagesy — Retourne la hauteur de l'image
  - imagetruecolortopalette — Convertit une image en couleurs vraies en image à palette
  - imagettfbbox — Retourne le rectangle entourant un texte et dessiné avec une police TrueType
  - imagettftext — Dessine un texte avec une police TrueType
  - imagetypes — Retourne les types d'images supportés par la version courante de PHP
  - imagewbmp — Affichage de l'image vers le navigateur ou dans un fichier
  - imagewebp — Affiche une image WebP vers un navigateur ou un fichier
  - imagexbm — Génère une image au format XBM
  - iptcembed — Intègre des données binaires IPTC dans une image JPEG
  - iptcparse — Analyse un bloc binaire IPTC et recherche les balises simples
  - jpeg2wbmp — Convertit une image JPEG en image WBMP
  - png2wbmp — Convertit une image PNG en image WBMP
- GdImage — La classe GdImage
- GdFont — La classe GdFont

# Gmagick

# Introduction

Avertissement

Cette extension est EXPERIMENTALE. Le comportement de cette extension, les noms de ses fonctions, et toute la documentation autour de cette extension peut changer sans préavis dans une prochaine version de PHP. Cette extension doit être utilisée à vos risques et périls.

Gmagick est une extension PHP pour créer, modifier et obtenir des informations méta sur des images en utilisant l'API GraphicsMagick.

GraphicsMagick s'enorgueillit d'être le couteau suisse du traitement de l'image. Il fonctionne avec quelque 88 formats majeurs, incluant des formats importants comme DPX, GIF, JPEG, JPEG-2000, PNG, PDF, PNM, et TIFF.

Gmagick est composé d'une classe principale Gmagick, d'une classe GmagickDraw qui s'occupe du dessin et d'une classe GmagickPixel dont les instances représentent un seul pixel d'une image (couleur, opacité).

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Cette extension fonctionne parfaitement avec GraphicsMagick version 1.4+. Gmagick devrait fonctionner avec les anciennes versions et ce, depuis la version 1.2.6 de GraphicsMagick mais quelques fonctionnalités et formats n'y sont pas supportés. La version Windows de GraphicsMagick est disponible depuis le site web de GraphicsMagick. Pour connaître les différences entre ImageMagick et GraphicsMagick, lire la » FAQ.

## Installation

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/gmagick.

> Note: Le nom officiel de cette extension est gmagick.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Constantes relatives aux types de couleur
`Gmagick::COLOR_BLACK` (int)
  Noir
`Gmagick::COLOR_BLUE` (int)
  Bleu
`Gmagick::COLOR_CYAN` (int)
  Cyan
`Gmagick::COLOR_GREEN` (int)
  Vert
`Gmagick::COLOR_RED` (int)
  Rouge
`Gmagick::COLOR_YELLOW` (int)
  Jaune
`Gmagick::COLOR_MAGENTA` (int)
  Magenta
`Gmagick::COLOR_OPACITY` (int)
  Opacité
`Gmagick::COLOR_ALPHA` (int)
  Alpha
`Gmagick::COLOR_FUZZ` (int)
  Fuzz

Constantes relatives aux opérateurs composite
`Gmagick::COMPOSITE_DEFAULT` (int)
  L'opérateur composite par défaut
`Gmagick::COMPOSITE_UNDEFINED` (int)
  Opérateur composite indéfini
`Gmagick::COMPOSITE_NO` (int)
  Aucun opérateur composite de défini
`Gmagick::COMPOSITE_ADD` (int)
  Le résultat d'une image + une image
`Gmagick::COMPOSITE_ATOP` (int)
  Le résultat est la même forme qu'une image ; là où l'image composite obscurcie l'image, l'image de la forme la superpose.
`Gmagick::COMPOSITE_BLEND` (int)
  Mélange l'image
`Gmagick::COMPOSITE_BUMPMAP` (int)
  Identique à COMPOSITE_MULTIPLY, mis à part que la source est convertie d'abord en niveaux de gris.
`Gmagick::COMPOSITE_CLEAR` (int)
  Rend la cible de l'image transparente
`Gmagick::COMPOSITE_COLORBURN` (int)
  Noircit l'image de destination pour refléter l'image source
`Gmagick::COMPOSITE_COLORDODGE` (int)
  Éclaircit l'image de destination pour refléter l'image source
`Gmagick::COMPOSITE_COLORIZE` (int)
  Colorise l'image cible en utilisant l'image composite
`Gmagick::COMPOSITE_COPYBLACK` (int)
  Copie les noirs depuis la source vers la cible
`Gmagick::COMPOSITE_COPYBLUE` (int)
  Copie les bleus depuis la source vers la cible
`Gmagick::COMPOSITE_COPY` (int)
  Copie l'image source sur l'image cible
`Gmagick::COMPOSITE_COPYCYAN` (int)
  Copie le cyan depuis la source vers la cible
`Gmagick::COMPOSITE_COPYGREEN` (int)
  Copie le vert depuis la source vers la cible
`Gmagick::COMPOSITE_COPYMAGENTA` (int)
  Copie le magenta depuis la source vers la cible
`Gmagick::COMPOSITE_COPYOPACITY` (int)
  Copie l'opacité depuis la source vers la cible
`Gmagick::COMPOSITE_COPYRED` (int)
  Copie le rouge depuis la source vers la cible
`Gmagick::COMPOSITE_COPYYELLOW` (int)
  Copie le jaune depuis la source vers la cible
`Gmagick::COMPOSITE_DARKEN` (int)
  Assombrit l'image cible
`Gmagick::COMPOSITE_DSTATOP` (int)
  La partie de la destination située à l'intérieur de la source devient composite sur la source et remplace la destination
`Gmagick::COMPOSITE_DST` (int)
  La cible est conservée sans modification
`Gmagick::COMPOSITE_DSTIN` (int)
  La partie de la source remplace la cible
`Gmagick::COMPOSITE_DSTOUT` (int)
  La partie à l'extérieur de la source remplace la cible
`Gmagick::COMPOSITE_DSTOVER` (int)
  La cible remplace la source
`Gmagick::COMPOSITE_DIFFERENCE` (int)
  Soustrait la plus sombre des deux couleurs élémentaires depuis la plus claire
`Gmagick::COMPOSITE_DISPLACE` (int)
  Décale les pixels de l'image cible tel que défini par la source
`Gmagick::COMPOSITE_DISSOLVE` (int)
  Dissous la source dans la cible
`Gmagick::COMPOSITE_EXCLUSION` (int)
  Produit un effet similaire à Gmagick::COMPOSITE_DIFFERENCE, mais apparaît avec un contraste plus faible
`Gmagick::COMPOSITE_HARDLIGHT` (int)
  Multiplie ou superpose les couleurs, en fonction de la valeur de couleur de source
`Gmagick::COMPOSITE_HUE` (int)
  Modifie la teinte de la cible telle que définie par la source
`Gmagick::COMPOSITE_IN` (int)
  Effectue un composite de la source dans la cible
`Gmagick::COMPOSITE_LIGHTEN` (int)
  Éclaircit la cible telle que définie par la source
`Gmagick::COMPOSITE_LUMINIZE` (int)
  Illumine la cible telle que définie par la source
`Gmagick::COMPOSITE_MINUS` (int)
  Soustrait la source de la cible
`Gmagick::COMPOSITE_MODULATE` (int)
  Module la luminosité cible, la saturation et la teinte tel que défini par la source
`Gmagick::COMPOSITE_MULTIPLY` (int)
  Multiplie la cible à la source
`Gmagick::COMPOSITE_OUT` (int)
  Effectue un composite des parties extérieures de la source sur la cible
`Gmagick::COMPOSITE_OVER` (int)
  Effectue un composite par dessus la cible
`Gmagick::COMPOSITE_OVERLAY` (int)
  Superpose la source sur la cible
`Gmagick::COMPOSITE_PLUS` (int)
  Ajoute la source à la cible
`Gmagick::COMPOSITE_REPLACE` (int)
  Remplace la cible par la source
`Gmagick::COMPOSITE_SATURATE` (int)
  Sature la cible tel que défini par la source
`Gmagick::COMPOSITE_SCREEN` (int)
  La source et la destination sont complémentés, puis multipliés, puis remplace la destination
`Gmagick::COMPOSITE_SOFTLIGHT` (int)
  Assombrit ou éclaire les couleurs, suivant la source
`Gmagick::COMPOSITE_SRCATOP` (int)
  La partie de la source se trouvant dans la destination est composée sur la destination
`Gmagick::COMPOSITE_SRC` (int)
  La source est copiée vers la destination
`Gmagick::COMPOSITE_SRCIN` (int)
  La partie de la source se trouvant dans la destination remplace la destination
`Gmagick::COMPOSITE_SRCOUT` (int)
  La partie de la source se trouvant en dehors de la destination remplace la destination
`Gmagick::COMPOSITE_SRCOVER` (int)
  La source remplace la destination
`Gmagick::COMPOSITE_SUBTRACT` (int)
  Soustrait les couleurs de l'image source dans l'image de destination
`Gmagick::COMPOSITE_THRESHOLD` (int)
  La source est composée de la cible, telle que définie par la source
`Gmagick::COMPOSITE_XOR` (int)
  La partie de la source qui se trouve en dehors de la destination est combinée avec la partie de la destination se trouvant en dehors de la source

Constantes de mode Montage
`Gmagick::MONTAGEMODE_FRAME` (int)
`Gmagick::MONTAGEMODE_UNFRAME` (int)
`Gmagick::MONTAGEMODE_CONCATENATE` (int)

Constantes de style
`Gmagick::STYLE_NORMAL` (int)
`Gmagick::STYLE_ITALIC` (int)
`Gmagick::STYLE_OBLIQUE` (int)
`Gmagick::STYLE_ANY` (int)

Constantes de filtre
`Gmagick::FILTER_UNDEFINED` (int)
`Gmagick::FILTER_POINT` (int)
`Gmagick::FILTER_BOX` (int)
`Gmagick::FILTER_TRIANGLE` (int)
`Gmagick::FILTER_HERMITE` (int)
`Gmagick::FILTER_HANNING` (int)
`Gmagick::FILTER_HAMMING` (int)
`Gmagick::FILTER_BLACKMAN` (int)
`Gmagick::FILTER_GAUSSIAN` (int)
`Gmagick::FILTER_QUADRATIC` (int)
`Gmagick::FILTER_CUBIC` (int)
`Gmagick::FILTER_CATROM` (int)
`Gmagick::FILTER_MITCHELL` (int)
`Gmagick::FILTER_LANCZOS` (int)
`Gmagick::FILTER_BESSEL` (int)
`Gmagick::FILTER_SINC` (int)

Constantes de type d'image
`Gmagick::IMGTYPE_UNDEFINED` (int)
`Gmagick::IMGTYPE_BILEVEL` (int)
`Gmagick::IMGTYPE_GRAYSCALE` (int)
`Gmagick::IMGTYPE_GRAYSCALEMATTE` (int)
`Gmagick::IMGTYPE_PALETTE` (int)
`Gmagick::IMGTYPE_PALETTEMATTE` (int)
`Gmagick::IMGTYPE_TRUECOLOR` (int)
`Gmagick::IMGTYPE_TRUECOLORMATTE` (int)
`Gmagick::IMGTYPE_COLORSEPARATION` (int)
`Gmagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`Gmagick::IMGTYPE_OPTIMIZE` (int)

Constantes de résolution
`Gmagick::RESOLUTION_UNDEFINED` (int)
`Gmagick::RESOLUTION_PIXELSPERINCH` (int)
`Gmagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

Constantes de compression
`Gmagick::COMPRESSION_UNDEFINED` (int)
`Gmagick::COMPRESSION_NO` (int)
`Gmagick::COMPRESSION_BZIP` (int)
`Gmagick::COMPRESSION_FAX` (int)
`Gmagick::COMPRESSION_GROUP4` (int)
`Gmagick::COMPRESSION_JPEG` (int)
`Gmagick::COMPRESSION_JPEG2000` (int)
`Gmagick::COMPRESSION_LOSSLESSJPEG` (int)
`Gmagick::COMPRESSION_LZW` (int)
`Gmagick::COMPRESSION_RLE` (int)
`Gmagick::COMPRESSION_ZIP` (int)

Constantes de dessin
`Gmagick::PAINT_POINT` (int)
`Gmagick::PAINT_REPLACE` (int)
`Gmagick::PAINT_FLOODFILL` (int)
`Gmagick::PAINT_FILLTOBORDER` (int)
`Gmagick::PAINT_RESET` (int)

Constantes de gravité
`Gmagick::GRAVITY_NORTHWEST` (int)
`Gmagick::GRAVITY_NORTH` (int)
`Gmagick::GRAVITY_NORTHEAST` (int)
`Gmagick::GRAVITY_WEST` (int)
`Gmagick::GRAVITY_CENTER` (int)
`Gmagick::GRAVITY_EAST` (int)
`Gmagick::GRAVITY_SOUTHWEST` (int)
`Gmagick::GRAVITY_SOUTH` (int)
`Gmagick::GRAVITY_SOUTHEAST` (int)

Constantes d'étirement
`Gmagick::STRETCH_NORMAL` (int)
`Gmagick::STRETCH_ULTRACONDENSED` (int)
`Gmagick::STRETCH_CONDENSED` (int)
`Gmagick::STRETCH_SEMICONDENSED` (int)
`Gmagick::STRETCH_SEMIEXPANDED` (int)
`Gmagick::STRETCH_EXPANDED` (int)
`Gmagick::STRETCH_EXTRAEXPANDED` (int)
`Gmagick::STRETCH_ULTRAEXPANDED` (int)
`Gmagick::STRETCH_ANY` (int)

Constantes d'alignement
`Gmagick::ALIGN_UNDEFINED` (int)
`Gmagick::ALIGN_LEFT` (int)
`Gmagick::ALIGN_CENTER` (int)
`Gmagick::ALIGN_RIGHT` (int)

Constantes de décoration
`Gmagick::DECORATION_NO` (int)
`Gmagick::DECORATION_UNDERLINE` (int)
`Gmagick::DECORATION_OVERLINE` (int)
`Gmagick::DECORATION_LINETROUGH` (int)

Constantes de bruit
`Gmagick::NOISE_UNIFORM` (int)
`Gmagick::NOISE_GAUSSIAN` (int)
`Gmagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`Gmagick::NOISE_IMPULSE` (int)
`Gmagick::NOISE_LAPLACIAN` (int)
`Gmagick::NOISE_POISSON` (int)

Constantes de canal
`Gmagick::CHANNEL_UNDEFINED` (int)
`Gmagick::CHANNEL_RED` (int)
`Gmagick::CHANNEL_GRAY` (int)
`Gmagick::CHANNEL_CYAN` (int)
`Gmagick::CHANNEL_GREEN` (int)
`Gmagick::CHANNEL_MAGENTA` (int)
`Gmagick::CHANNEL_BLUE` (int)
`Gmagick::CHANNEL_YELLOW` (int)
`Gmagick::CHANNEL_ALPHA` (int)
`Gmagick::CHANNEL_OPACITY` (int)
`Gmagick::CHANNEL_MATTE` (int)
`Gmagick::CHANNEL_BLACK` (int)
`Gmagick::CHANNEL_INDEX` (int)
`Gmagick::CHANNEL_ALL` (int)

Constantes de mesure
`Gmagick::METRIC_UNDEFINED` (int)
`Gmagick::METRIC_MEANABSOLUTEERROR` (int)
`Gmagick::METRIC_MEANSQUAREERROR` (int)
`Gmagick::METRIC_PEAKABSOLUTEERROR` (int)
`Gmagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`Gmagick::METRIC_ROOTMEANSQUAREDERROR` (int)

Constantes de pixel
`Gmagick::PIXEL_CHAR` (int)
`Gmagick::PIXEL_DOUBLE` (int)
`Gmagick::PIXEL_FLOAT` (int)
`Gmagick::PIXEL_INTEGER` (int)
`Gmagick::PIXEL_LONG` (int)
`Gmagick::PIXEL_QUANTUM` (int)
`Gmagick::PIXEL_SHORT` (int)

Constantes d'espace de couleurs
`Gmagick::COLORSPACE_UNDEFINED` (int)
`Gmagick::COLORSPACE_RGB` (int)
`Gmagick::COLORSPACE_GRAY` (int)
`Gmagick::COLORSPACE_TRANSPARENT` (int)
`Gmagick::COLORSPACE_OHTA` (int)
`Gmagick::COLORSPACE_LAB` (int)
`Gmagick::COLORSPACE_XYZ` (int)
`Gmagick::COLORSPACE_YCBCR` (int)
`Gmagick::COLORSPACE_YCC` (int)
`Gmagick::COLORSPACE_YIQ` (int)
`Gmagick::COLORSPACE_YPBPR` (int)
`Gmagick::COLORSPACE_YUV` (int)
`Gmagick::COLORSPACE_CMYK` (int)
`Gmagick::COLORSPACE_SRGB` (int)
`Gmagick::COLORSPACE_HSB` (int)
`Gmagick::COLORSPACE_HSL` (int)
`Gmagick::COLORSPACE_HWB` (int)
`Gmagick::COLORSPACE_REC601LUMA` (int)
`Gmagick::COLORSPACE_REC709LUMA` (int)
`Gmagick::COLORSPACE_LOG` (int)

Constantes de méthode pour les pixels virtuels
`Gmagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`Gmagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`Gmagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`Gmagick::VIRTUALPIXELMETHOD_EDGE` (int)
`Gmagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`Gmagick::VIRTUALPIXELMETHOD_TILE` (int)
`Gmagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)

Constantes de prévisualisation
`Gmagick::PREVIEW_UNDEFINED` (int)
`Gmagick::PREVIEW_ROTATE` (int)
`Gmagick::PREVIEW_SHEAR` (int)
`Gmagick::PREVIEW_ROLL` (int)
`Gmagick::PREVIEW_HUE` (int)
`Gmagick::PREVIEW_SATURATION` (int)
`Gmagick::PREVIEW_BRIGHTNESS` (int)
`Gmagick::PREVIEW_GAMMA` (int)
`Gmagick::PREVIEW_SPIFF` (int)
`Gmagick::PREVIEW_DULL` (int)
`Gmagick::PREVIEW_GRAYSCALE` (int)
`Gmagick::PREVIEW_QUANTIZE` (int)
`Gmagick::PREVIEW_DESPECKLE` (int)
`Gmagick::PREVIEW_REDUCENOISE` (int)
`Gmagick::PREVIEW_ADDNOISE` (int)
`Gmagick::PREVIEW_SHARPEN` (int)
`Gmagick::PREVIEW_BLUR` (int)
`Gmagick::PREVIEW_THRESHOLD` (int)
`Gmagick::PREVIEW_EDGEDETECT` (int)
`Gmagick::PREVIEW_SPREAD` (int)
`Gmagick::PREVIEW_SOLARIZE` (int)
`Gmagick::PREVIEW_SHADE` (int)
`Gmagick::PREVIEW_RAISE` (int)
`Gmagick::PREVIEW_SEGMENT` (int)
`Gmagick::PREVIEW_SWIRL` (int)
`Gmagick::PREVIEW_IMPLODE` (int)
`Gmagick::PREVIEW_WAVE` (int)
`Gmagick::PREVIEW_OILPAINT` (int)
`Gmagick::PREVIEW_CHARCOALDRAWING` (int)
`Gmagick::PREVIEW_JPEG` (int)

Constantes de rendu
`Gmagick::RENDERINGINTENT_UNDEFINED` (int)
`Gmagick::RENDERINGINTENT_SATURATION` (int)
`Gmagick::RENDERINGINTENT_PERCEPTUAL` (int)
`Gmagick::RENDERINGINTENT_ABSOLUTE` (int)
`Gmagick::RENDERINGINTENT_RELATIVE` (int)

Constantes de règle de remplissage
`Gmagick::FILLRULE_UNDEFINED` (int)
`Gmagick::FILLRULE_EVENODD` (int)
`Gmagick::FILLRULE_NONZERO` (int)

Constantes Pathunit
`Gmagick::PATHUNITS_UNDEFINED` (int)
`Gmagick::PATHUNITS_USERSPACE` (int)
`Gmagick::PATHUNITS_USERSPACEONUSE` (int)
`Gmagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

Constantes Linecap
`Gmagick::LINECAP_UNDEFINED` (int)
`Gmagick::LINECAP_BUTT` (int)
`Gmagick::LINECAP_ROUND` (int)
`Gmagick::LINECAP_SQUARE` (int)

Constantes de jointure de lignes
`Gmagick::LINEJOIN_UNDEFINED` (int)
`Gmagick::LINEJOIN_MITER` (int)
`Gmagick::LINEJOIN_ROUND` (int)
`Gmagick::LINEJOIN_BEVEL` (int)

Constantes de type de ressources
`Gmagick::RESOURCETYPE_UNDEFINED` (int)
`Gmagick::RESOURCETYPE_AREA` (int)
`Gmagick::RESOURCETYPE_DISK` (int)
`Gmagick::RESOURCETYPE_FILE` (int)
`Gmagick::RESOURCETYPE_MAP` (int)
`Gmagick::RESOURCETYPE_MEMORY` (int)

Constantes d'orientation
`Gmagick::ORIENTATION_UNDEFINED` (int)
`Gmagick::ORIENTATION_TOPLEFT` (int)
`Gmagick::ORIENTATION_TOPRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMLEFT` (int)
`Gmagick::ORIENTATION_LEFTTOP` (int)
`Gmagick::ORIENTATION_RIGHTTOP` (int)
`Gmagick::ORIENTATION_RIGHTBOTTOM` (int)
`Gmagick::ORIENTATION_LEFTBOTTOM` (int)

Constantes d'entrelacement
`Gmagick::INTERLACE_UNDEFINED` (int)
`Gmagick::INTERLACE_NO` (int)
`Gmagick::INTERLACE_NONE` (int)
`Gmagick::INTERLACE_LINE` (int)
`Gmagick::INTERLACE_PLANE` (int)
`Gmagick::INTERLACE_PARTITION` (int)

# Exemples

Ce qui suit montre quelques opérations communes avec Gmagick.

Exemple #1 Exemple Gmagick

    <?php
    //Instantiation d'un nouvel objet Gmagick
    $image = new Gmagick('example.jpg');

    // Crée une miniature depuis l'image chargée. 0 pour un des axes préservera le ratio
    $image->thumbnailimage(100, 0);

    // Crée une bordure autour de l'image, puis, simule la façon dont sera rendue l'image
    // après un rendu à la peinture à l'huile.
    // Notez le chaînage des méthodes supporté par Gmagick
    $image->borderimage("yellow", 8, 8)->oilpaintimage(0.3);

    // Ecrit l'image courante dans un fichier
    $image->write('example_thumbnail.jpg');
    ?>

# La classe Gmagick

(PECL gmagick >= Unknown)

## Introduction

## Synopsis de la classe

class Gmagick {
/* Méthodes */
public function __construct(string `$filename` = ?)
public function addimage(Gmagick `$source`): Gmagick
public function addnoiseimage(int `$noise_type`): Gmagick
public function annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick
public function blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick
public function borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick
public function charcoalimage(float `$radius`, float `$sigma`): Gmagick
public function chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick
public function clear(): Gmagick
public function commentimage(string `$comment`): Gmagick
public function compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick
public function cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick
public function cropthumbnailimage(int `$width`, int `$height`): Gmagick
public function current(): Gmagick
public function cyclecolormapimage(int `$displace`): Gmagick
public function deconstructimages(): Gmagick
public function despeckleimage(): Gmagick
public function destroy(): bool
public function drawimage(GmagickDraw `$GmagickDraw`): Gmagick
public function edgeimage(float `$radius`): Gmagick
public function embossimage(float `$radius`, float `$sigma`): Gmagick
public function enhanceimage(): Gmagick
public function equalizeimage(): Gmagick
public function flipimage(): Gmagick
public function flopimage(): Gmagick
public function frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick
public function gammaimage(float `$gamma`): Gmagick
public function getcopyright(): string
public function getfilename(): string
public function getimagebackgroundcolor(): GmagickPixel
public function getimageblueprimary(): array
public function getimagebordercolor(): GmagickPixel
public function getimagechanneldepth(int `$channel_type`): int
public function getimagecolors(): int
public function getimagecolorspace(): int
public function getimagecompose(): int
public function getimagedelay(): int
public function getimagedepth(): int
public function getimagedispose(): int
public function getimageextrema(): array
public function getimagefilename(): string
public function getimageformat(): string
public function getimagegamma(): float
public function getimagegreenprimary(): array
public function getimageheight(): int
public function getimagehistogram(): array
public function getimageindex(): int
public function getimageinterlacescheme(): int
public function getimageiterations(): int
public function getimagematte(): int
public function getimagemattecolor(): GmagickPixel
public function getimageprofile(string `$name`): string
public function getimageredprimary(): array
public function getimagerenderingintent(): int
public function getimageresolution(): array
public function getimagescene(): int
public function getimagesignature(): string
public function getimagetype(): int
public function getimageunits(): int
public function getimagewhitepoint(): array
public function getimagewidth(): int
public function getpackagename(): string
public function getquantumdepth(): array
public function getreleasedate(): string
public function getsamplingfactors(): array
public function getsize(): array
public function getversion(): array
public function hasnextimage(): mixed
public function haspreviousimage(): mixed
public function implodeimage(float `$radius`): mixed
public function labelimage(string `$label`): mixed
public function levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed
public function magnifyimage(): mixed
public function mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick
public function medianfilterimage(float `$radius`): void
public function minifyimage(): Gmagick
public function modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick
public function motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick
public function newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick
public function nextimage(): bool
public function normalizeimage(int `$channel` = ?): Gmagick
public function oilpaintimage( float `$radius` ): Gmagick
public function previousimage(): bool
public function profileimage(string `$name`, string `$profile`): Gmagick
public function quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function queryfontmetrics(GmagickDraw `$draw`, string `$text`): array
public function queryfonts(string `$pattern` = "*"): array
public function queryformats(string `$pattern` = "*"): array
public function radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick
public function raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick
public function read(string `$filename`): Gmagick
public function readimage(string `$filename`): Gmagick
public function readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick
public function readimagefile(resource `$fp`, string `$filename` = ?): Gmagick
public function reducenoiseimage(float `$radius`): Gmagick
public function removeimage(): Gmagick
public function removeimageprofile(string `$name`): string
public function resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick
public function resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick
public function rollimage(int `$x`, int `$y`): Gmagick
public function rotateimage(mixed `$color`, float `$degrees`): Gmagick
public function scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function separateimagechannel(int `$channel`): Gmagick
function setCompressionQuality( int `$quality` ): Gmagick
public function setfilename(string `$filename`): Gmagick
public function setimagebackgroundcolor(GmagickPixel `$color`): Gmagick
public function setimageblueprimary(float `$x`, float `$y`): Gmagick
public function setimagebordercolor(GmagickPixel `$color`): Gmagick
public function setimagechanneldepth(int `$channel`, int `$depth`): Gmagick
public function setimagecolorspace(int `$colorspace`): Gmagick
public function setimagecompose(int `$composite`): Gmagick
public function setimagedelay(int `$delay`): Gmagick
public function setimagedepth(int `$depth`): Gmagick
public function setimagedispose(int `$disposeType`): Gmagick
public function setimagefilename(string `$filename`): Gmagick
public function setimageformat(string `$imageFormat`): Gmagick
public function setimagegamma(float `$gamma`): Gmagick
public function setimagegreenprimary(float `$x`, float `$y`): Gmagick
public function setimageindex(int `$index`): Gmagick
public function setimageinterlacescheme(int `$interlace`): Gmagick
public function setimageiterations(int `$iterations`): Gmagick
public function setimageprofile(string `$name`, string `$profile`): Gmagick
public function setimageredprimary(float `$x`, float `$y`): Gmagick
public function setimagerenderingintent(int `$rendering_intent`): Gmagick
public function setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick
public function setimagescene(int `$scene`): Gmagick
public function setimagetype(int `$imgType`): Gmagick
public function setimageunits(int `$resolution`): Gmagick
public function setimagewhitepoint(float `$x`, float `$y`): Gmagick
public function setsamplingfactors(array `$factors`): Gmagick
public function setsize(int `$columns`, int `$rows`): Gmagick
public function shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick
public function solarizeimage(int `$threshold`): Gmagick
public function spreadimage(float `$radius`): Gmagick
public function stripimage(): Gmagick
public function swirlimage(float `$degrees`): Gmagick
public function thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function trimimage(float `$fuzz`): Gmagick
public function writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick
}

# Gmagick::addimage

(PECL gmagick >= Unknown)

Gmagick::addimage — Ajoute une nouvelle image à la liste des images de l'objet Gmagick

### Description

public function Gmagick::addimage(Gmagick `$source`): Gmagick

Ajoute une nouvelle image à l'objet Gmagick depuis la position courante de l'objet source. Après l'opération, l'itérateur de position est déplacé à la fin de la liste.

### Liste de paramètres

`source`
  L'objet Gmagick source

### Valeurs de retour

L'objet Gmagick contenant la nouvelle image chargée.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::addnoiseimage

(PECL gmagick >= Unknown)

Gmagick::addnoiseimage — Ajoute du bruit aléatoirement dans l'image

### Description

public function Gmagick::addnoiseimage(int `$noise_type`): Gmagick

Ajoute du bruit aléatoirement dans l'image.

### Liste de paramètres

`noise_type`
  Le type de bruit. Se reporter à la liste des constantes relatives au bruit.

### Valeurs de retour

L'objet Gmagick dont le bruit a été ajouté.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::annotateimage

(PECL gmagick >= Unknown)

Gmagick::annotateimage — Annote une image avec du texte

### Description

public function Gmagick::annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick

Annote une image avec du texte.

### Liste de paramètres

`GmagickDraw`
  L'objet GmagickDraw contenant la configuration afin de dessiner le texte.
`x`
  Position horizontale, en pixels, du bord gauche du texte.
`y`
  Position verticale, en pixels, du bas du texte.
`angle`
  L'angle utilisé pour écrire le texte.
`text`
  Le texte à dessiner.

### Valeurs de retour

L'objet Gmagick contenant l'annotation.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::blurimage

(PECL gmagick >= Unknown)

Gmagick::blurimage — Ajoute un filtre flou à l'image

### Description

public function Gmagick::blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick

Ajoute un filtre flou à l'image.

### Liste de paramètres

`radius`
  Rayon utilisé pour le flou
`sigma`
  Déviation standard

### Valeurs de retour

L'objet Gmagick flouté.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::borderimage

(PECL gmagick >= Unknown)

Gmagick::borderimage — Ajoute une bordure à l'image

### Description

public function Gmagick::borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick

Ajoute une bordure à l'image dont la couleur sera définie par l'objet GmagickPixel ou une couleur sous forme de chaîne de caractères.

### Liste de paramètres

`color`
  Objet GmagickPixel ou une chaîne de caractères contenant la couleur de la bordure.
`width`
  Épaisseur de la bordure.
`height`
  Hauteur de la bordure.

### Valeurs de retour

L'objet Gmagick dont la bordure a été ajoutée

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::charcoalimage

(PECL gmagick >= Unknown)

Gmagick::charcoalimage — Simule un dessin au fusain

### Description

public function Gmagick::charcoalimage(float `$radius`, float `$sigma`): Gmagick

Simule un dessin au fusain.

### Liste de paramètres

`radius`
  Le rayon du Gaussien, en pixels, sans compter le pixel central.
`sigma`
  La déviation standard du Gaussien, en pixels.

### Valeurs de retour

L'objet Gmagick contenant la simulation du dessin au fusain.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::chopimage

(PECL gmagick >= Unknown)

Gmagick::chopimage — Supprime une région de l'image

### Description

public function Gmagick::chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick

Supprime une région de l'image et la repositionne afin d'occuper la portion effacée.

### Liste de paramètres

`width`
  Longueur de la région à supprimer.
`height`
  Hauteur de la région à supprimer.
`x`
  Origine en X de la région à supprimer.
`y`
  Origine en Y de la région à supprimer.

### Valeurs de retour

L'objet Gmagick dont la région a été supprimée.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::clear

(PECL gmagick >= Unknown)

Gmagick::clear — Efface toutes les ressources associées à l'objet Gmagick

### Description

public function Gmagick::clear(): Gmagick

Efface toutes les ressources associées à l'objet Gmagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick nettoyé.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::commentimage

(PECL gmagick >= Unknown)

Gmagick::commentimage — Ajoute un commentaire à l'image

### Description

public function Gmagick::commentimage(string `$comment`): Gmagick

Ajoute un commentaire à l'image.

### Liste de paramètres

`comment`
  Le commentaire à ajouter.

### Valeurs de retour

L'objet Gmagick contenant le commentaire.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::compositeimage

(PECL gmagick >= Unknown)

Gmagick::compositeimage — Assemble 2 images

### Description

public function Gmagick::compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick

Assemble 2 images à une position spécifique.

### Liste de paramètres

`source`
  L'objet Gmagick qui contient l'image à assembler.
`COMPOSE`
  L'opérateur d'assemblage.
`x`
  La position de la colonne de l'image assemblée.
`y`
  La position de la ligne de l'image assemblée.

### Valeurs de retour

L'objet Gmagick contenant l'assemblage.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::__construct

(PECL gmagick >= Unknown)

Gmagick::__construct — Le constructeur Gmagick

### Description

public function Gmagick::__construct(string `$filename` = ?)

Le constructeur Gmagick.

### Liste de paramètres

`filename`
  Le chemin vers une image à charger ou un tableau de chemins.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::cropimage

(PECL gmagick >= Unknown)

Gmagick::cropimage — Extrait une portion d'une image

### Description

public function Gmagick::cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick

Extrait une portion de l'image.

### Liste de paramètres

`width`
  La longueur de la portion.
`height`
  La hauteur de la région.
`x`
  La coordonnée en X de la portion à extraire, en commençant par le coin en haut, à gauche.
`y`
  La coordonnée en Y de la portion à extraire, en commençant par le coin en haut, à gauche.

### Valeurs de retour

L'objet Gmagick représentant la portion extraite.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::cropthumbnailimage

(PECL gmagick >= Unknown)

Gmagick::cropthumbnailimage — Crée une miniature recadrée

### Description

public function Gmagick::cropthumbnailimage(int `$width`, int `$height`): Gmagick

Crée une miniature de taille fixe en commençant par une mise à l'échelle de l'image, puis, en recadrant la région spécifique depuis le centre.

### Liste de paramètres

`width`
  La longueur de la miniature.
`height`
  La hauteur de la miniature.

### Valeurs de retour

L'objet Gmagick recadré.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::current

(PECL gmagick >= Unknown)

Gmagick::current — Le contexte courant

### Description

public function Gmagick::current(): Gmagick

Retourne une référence vers l'objet Gmagick courant avec le pointeur de l'image à la bonne séquence.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le contexte en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::cyclecolormapimage

(PECL gmagick >= Unknown)

Gmagick::cyclecolormapimage — Déplace la carte des couleurs d'une image

### Description

public function Gmagick::cyclecolormapimage(int `$displace`): Gmagick

Déplace la carte des couleurs d'une image d'un nombre de positions donné. En déplaçant plusieurs fois la carte des couleurs, il est possible de produire un effet psychédélique.

### Liste de paramètres

`displace`
  Le nombre de positions dont on doit déplacer la carte des couleurs.

### Valeurs de retour

Retourne le contexte en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::deconstructimages

(PECL gmagick >= Unknown)

Gmagick::deconstructimages — Retourne les pixels différents entre des images

### Description

public function Gmagick::deconstructimages(): Gmagick

Compare chaque image avec la suivante de la séquence et retourne les pixels différents découverts.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::despeckleimage

(PECL gmagick >= Unknown)

Gmagick::despeckleimage — Le but de despeckleimage

### Description

public function Gmagick::despeckleimage(): Gmagick

Réduit le bruit speckle d'une image tout en préservant les bords de l'image originale.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick sans bruit en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

### Exemples

Exemple #1 Exemple avec Gmagick::despeckleimage()

    <?php
    /* ... */
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    ...

# Gmagick::destroy

(PECL gmagick >= Unknown)

Gmagick::destroy — Le but de la méthode destroy

### Description

public function Gmagick::destroy(): bool

Détruit l'objet Gmagick et libère toutes les ressources associées.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::drawimage

(PECL gmagick >= Unknown)

Gmagick::drawimage — Fait un rendu de l'objet GmagickDraw sur l'image courante

### Description

public function Gmagick::drawimage(GmagickDraw `$GmagickDraw`): Gmagick

Fait un rendu de l'objet GmagickDraw sur l'image courante.

### Liste de paramètres

`GmagickDraw`
  L'opération de dessin à exécuter sur l'image.

### Valeurs de retour

L'objet Gmagick dessiné.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::edgeimage

(PECL gmagick >= Unknown)

Gmagick::edgeimage — Améliore les bords intérieurs de l'image

### Description

public function Gmagick::edgeimage(float `$radius`): Gmagick

Améliore les bords intérieurs de l'image avec un filtre de convolution utilisant le rayon fourni. En utilisant un rayon de 0, la méthode le choisira automatiquement.

### Liste de paramètres

`radius`
  Le rayon utilisé pour l'opération.

### Valeurs de retour

L'objet Gmagick dont les bords intérieurs ont été améliorés.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::embossimage

(PECL gmagick >= Unknown)

Gmagick::embossimage — Retourne une image en niveaux de gris avec un effet à 3 dimensions

### Description

public function Gmagick::embossimage(float `$radius`, float `$sigma`): Gmagick

Retourne une image en niveaux de gris avec un effet à 3 dimensions. L'image est transformée avec un opérateur Gaussien utilisant le rayon donné, et une déviation standard (sigma). Pour obtenir un résultat convenable, le rayon doit être supérieur au sigma. Si l'on spécifie un rayon de 0, la méthode choisira le meilleur rayon à sa place.

### Liste de paramètres

`radius`
  Le rayon de l'effet.
`sigma`
  Le sigma de l'effet.

### Valeurs de retour

L'objet Gmagick en relief.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::enhanceimage

(PECL gmagick >= Unknown)

Gmagick::enhanceimage — Améliore la qualité d'une image contenant du bruit

### Description

public function Gmagick::enhanceimage(): Gmagick

Applique un filtre numérique qui améliore la qualité d'une image contenant du bruit.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick amélioré.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::equalizeimage

(PECL gmagick >= Unknown)

Gmagick::equalizeimage — Égalise l'histogramme de l'image

### Description

public function Gmagick::equalizeimage(): Gmagick

Égalise l'histogramme de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick égalisé.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::flipimage

(PECL gmagick >= Unknown)

Gmagick::flipimage — Crée une image miroir verticale

### Description

public function Gmagick::flipimage(): Gmagick

Crée une image miroir verticale en reflétant les pixels autour du centre de l'axe X.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick reflété.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

### Voir aussi

- Gmagick::flopimage() - Crée une image miroir horizontale

# Gmagick::flopimage

(PECL gmagick >= Unknown)

Gmagick::flopimage — Crée une image miroir horizontale

### Description

public function Gmagick::flopimage(): Gmagick

Crée une image miroir horizontale en reflétant les pixels autour du centre de l'axe Y.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick reflété.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

### Voir aussi

- Gmagick::flipimage() - Crée une image miroir verticale

# Gmagick::frameimage

(PECL gmagick >= Unknown)

Gmagick::frameimage — Ajoute une bordure afin de simuler un effet 3D

### Description

public function Gmagick::frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick

Ajoute une bordure simulant un effet 3D à l'image. La largeur et la hauteur spécifient la largeur de la bordure verticale et horizontale de la frame. Les paramètres `inner_bevel` et `outer_bevel` indiquent la largeur interne et externe de l'ombre de la frame.

### Liste de paramètres

`color`
  Un objet GmagickPixel ou un nombre à virgule flottante représentant la couleur mate.
`width`
  La largeur de la bordure.
`height`
  La hauteur de la bordure.
`inner_bevel`
  La largeur du bevel interne.
`outer_bevel`
  La largeur du bevel externe.

### Valeurs de retour

L'objet Gmagick dont la bordure 3D a été ajoutée.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::gammaimage

(PECL gmagick >= Unknown)

Gmagick::gammaimage — Corrige le gamma d'une image

### Description

public function Gmagick::gammaimage(float `$gamma`): Gmagick

Corrige le gamma d'une image. La même image vue sur différents médias aura plusieurs différences suivant l'intensité représentée sur l'écran. Il est possible d'ainsi jouer sur le niveau de gamma pour les canaux rouges, verts et bleus, ou ajuster les 3 avec le paramètre gamma. Les valeurs sont typiquement dans l'intervalle 0.8 à 2.3.

### Liste de paramètres

`gamma`
  La quantité de correction gamma.

### Valeurs de retour

L'objet Gmagick dont le gamma a été corrigé.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getcopyright

(PECL gmagick >= Unknown)

Gmagick::getcopyright — Retourne le copyright de l'API GraphicsMagick

### Description

public function Gmagick::getcopyright(): string

Retourne le copyright de l'API GraphicsMagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères contenant le copyright de l'API GraphicsMagick ainsi que celui de l'API Magickwand.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getfilename

(PECL gmagick >= Unknown)

Gmagick::getfilename — Retourne le nom du fichier associé avec une séquence d'image

### Description

public function Gmagick::getfilename(): string

Retourne le nom du fichier associé avec une séquence d'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::getimagebackgroundcolor — Retourne la couleur d'arrière plan de l'image

### Description

public function Gmagick::getimagebackgroundcolor(): GmagickPixel

Retourne la couleur d'arrière plan de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet GmagickPixel défini à la couleur d'arrière plan de l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::getimageblueprimary — Retourne le point bleu primaire chromatique

### Description

public function Gmagick::getimageblueprimary(): array

Retourne le point bleu primaire chromatique de l'image.

### Liste de paramètres

`x`
  Coordonnée en X du point bleu primaire chromatique.
`y`
  Coordonnée en Y du point bleu primaire chromatique.

### Valeurs de retour

Un tableau contenant les coordonnées en X et en Y du point.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::getimagebordercolor — Retourne la couleur du bord de l'image

### Description

public function Gmagick::getimagebordercolor(): GmagickPixel

Retourne la couleur du bord de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet GmagickPixel représentant la couleur du bord de l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::getimagechanneldepth — Récupère la profondeur d'un canal particulier de l'image

### Description

public function Gmagick::getimagechanneldepth(int `$channel_type`): int

Récupère la profondeur d'un canal particulier de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La profondeur du canal de l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagecolors

(PECL gmagick >= Unknown)

Gmagick::getimagecolors — Retourne la couleur de l'indice de la carte des couleurs spécifiée

### Description

public function Gmagick::getimagecolors(): int

Retourne la couleur de l'indice de la carte des couleurs spécifiée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Le nombre de couleurs dans l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::getimagecolorspace — Récupère l'espace colorimétrique de l'image

### Description

public function Gmagick::getimagecolorspace(): int

Récupère l'espace colorimétrique de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'espace colorimétrique.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagecompose

(PECL gmagick >= Unknown)

Gmagick::getimagecompose — Retourne l'opérateur de composition associé avec l'image

### Description

public function Gmagick::getimagecompose(): int

Retourne l'opérateur de composition associé avec l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'opérateur de composition associé avec l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagedelay

(PECL gmagick >= Unknown)

Gmagick::getimagedelay — Récupère le délai de l'image

### Description

public function Gmagick::getimagedelay(): int

Récupère le délai de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'opérateur de composition associé avec l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagedepth

(PECL gmagick >= Unknown)

Gmagick::getimagedepth — Récupère la profondeur de l'image

### Description

public function Gmagick::getimagedepth(): int

Récupère la profondeur de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La profondeur de l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagedispose

(PECL gmagick >= Unknown)

Gmagick::getimagedispose — Récupère la méthode de disposition de l'image

### Description

public function Gmagick::getimagedispose(): int

Récupère la méthode de disposition de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la méthode de disposition de l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageextrema

(PECL gmagick >= Unknown)

Gmagick::getimageextrema — Récupère les extrémités de l'image

### Description

public function Gmagick::getimageextrema(): array

Retourne un tableau associatif contenant les clés "min" et "max". Émet une exception GmagickException en cas d'erreur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif contenant les clés "min" et "max".

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagefilename

(PECL gmagick >= Unknown)

Gmagick::getimagefilename — Récupère le nom du fichier d'une image particulière dans une séquence

### Description

public function Gmagick::getimagefilename(): string

Récupère le nom du fichier d'une image particulière dans une séquence.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères représentant le nom du fichier image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageformat

(PECL gmagick >= Unknown)

Gmagick::getimageformat — Récupère le format d'une image particulière dans une séquence

### Description

public function Gmagick::getimageformat(): string

Récupère le format d'une image particulière dans une séquence.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères contenant le format de l'image en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagegamma

(PECL gmagick >= Unknown)

Gmagick::getimagegamma — Récupère le gamma de l'image

### Description

public function Gmagick::getimagegamma(): float

Récupère le gamma de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le gamma de l'image en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::getimagegreenprimary — Récupère le point chromatique primaire vert

### Description

public function Gmagick::getimagegreenprimary(): array

Récupère le point chromatique primaire vert.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau contenant les clés "x" et "y" en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageheight

(PECL gmagick >= Unknown)

Gmagick::getimageheight — Récupère la hauteur de l'image

### Description

public function Gmagick::getimageheight(): int

Récupère la hauteur de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la hauteur de l'image, en pixels.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagehistogram

(PECL gmagick >= Unknown)

Gmagick::getimagehistogram — Récupère l'histogramme de l'image

### Description

public function Gmagick::getimagehistogram(): array

Récupère l'histogramme de l'image. Lance une exception GmagickException en cas d'erreur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'histogramme de l'image sous la forme d'un tableau d'objets GmagickPixel.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageindex

(PECL gmagick >= Unknown)

Gmagick::getimageindex — Récupère l'indice de l'image active courante

### Description

public function Gmagick::getimageindex(): int

Récupère l'indice de l'image active courante dans l'objet Gmagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'indice de l'image courante active.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::getimageinterlacescheme — Récupère le schéma d'entrelacement de l'image

### Description

public function Gmagick::getimageinterlacescheme(): int

Récupère le schéma d'entrelacement de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le schéma d'entrelacement de l'image, sous la forme d'un entier en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageiterations

(PECL gmagick >= Unknown)

Gmagick::getimageiterations — Récupère les itérations de l'image

### Description

public function Gmagick::getimageiterations(): int

Récupère les itérations de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les itérations de l'image, sous la forme d'un entier.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagematte

(PECL gmagick >= Unknown)

Gmagick::getimagematte — Vérifie si l'image a un canal mate

### Description

public function Gmagick::getimagematte(): int

Retourne `true` si l'image a un canal mate, `false` sinon.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'image a un canal mate, `false` sinon.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagemattecolor

(PECL gmagick >= Unknown)

Gmagick::getimagemattecolor — Récupère la couleur mate de l'image

### Description

public function Gmagick::getimagemattecolor(): GmagickPixel

Retourne un objet GmagickPixel en cas de succès. Lance une exception GmagickException en cas d'erreur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet GmagickPixel.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageprofile

(PECL gmagick >= Unknown)

Gmagick::getimageprofile — Récupère le nom du profil de l'image

### Description

public function Gmagick::getimageprofile(string `$name`): string

Récupère le nom du profil de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères représentant le profil de l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageredprimary

(PECL gmagick >= Unknown)

Gmagick::getimageredprimary — Récupère le point chromatique primaire rouge

### Description

public function Gmagick::getimageredprimary(): array

Récupère le point chromatique primaire rouge, sous la forme d'un tableau contenant les clés "x" et "y".

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le point chromatique primaire rouge, sous la forme d'un tableau contenant les clés "x" et "y".

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::getimagerenderingintent — Récupère l'image de rendu

### Description

public function Gmagick::getimagerenderingintent(): int

Récupère l'image de rendu.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Extrait une région de l'image et la retourne en tant que nouvelle baguette magique.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageresolution

(PECL gmagick >= Unknown)

Gmagick::getimageresolution — Récupère la résolution de l'image

### Description

public function Gmagick::getimageresolution(): array

Récupère la résolution de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la résolution sous la forme d'un tableau.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagescene

(PECL gmagick >= Unknown)

Gmagick::getimagescene — Récupère la scène de l'image

### Description

public function Gmagick::getimagescene(): int

Récupère la scène de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la scène de l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagesignature

(PECL gmagick >= Unknown)

Gmagick::getimagesignature — Génère la signature SHA-256 de l'image

### Description

public function Gmagick::getimagesignature(): string

Génère la signature SHA-256 de l'image depuis le flux de pixels.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères contenant la signature SHA-256 hash.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagetype

(PECL gmagick >= Unknown)

Gmagick::getimagetype — Récupère le type potentiel d'une image

### Description

public function Gmagick::getimagetype(): int

Récupère le type potentiel d'une image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le type potentiel d'une image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimageunits

(PECL gmagick >= Unknown)

Gmagick::getimageunits — Récupère les unités utilisées pour la résolution de l'image

### Description

public function Gmagick::getimageunits(): int

Récupère les unités utilisées pour la résolution de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les unités utilisées pour la résolution de l'image.

# Gmagick::getimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::getimagewhitepoint — Récupère le point chromatique blanc

### Description

public function Gmagick::getimagewhitepoint(): array

Récupère le point chromatique blanc.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le point chromatique blanc, sous la forme d'un tableau associatif contenant les clés "x" et "y".

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getimagewidth

(PECL gmagick >= Unknown)

Gmagick::getimagewidth — Récupère la largeur de l'image

### Description

public function Gmagick::getimagewidth(): int

Récupère la largeur de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la largeur de l'image.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getpackagename

(PECL gmagick >= Unknown)

Gmagick::getpackagename — Récupère le nom du paquet GraphicsMagick

### Description

public function Gmagick::getpackagename(): string

Récupère le nom du paquet GraphicsMagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nom du paquet GraphicsMagick, sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getquantumdepth

(PECL gmagick >= Unknown)

Gmagick::getquantumdepth — Récupère la profondeur du quantum Gmagick

### Description

public function Gmagick::getquantumdepth(): array

Récupère la profondeur du quantum Gmagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la profondeur du quantum Gmagick, sous la forme d'un chaîne de caractères.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getreleasedate

(PECL gmagick >= Unknown)

Gmagick::getreleasedate — Récupère la date de sortie de la version courante de GraphicsMagick

### Description

public function Gmagick::getreleasedate(): string

Récupère la date de sortie de la version courante de GraphicsMagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la date de sortie de la version courante de GraphicsMagick sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::getsamplingfactors — Récupère le facteur d'échantillonnage horizontal et vertical

### Description

public function Gmagick::getsamplingfactors(): array

Récupère le facteur d'échantillonnage horizontal et vertical.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif contenant le facteur d'échantillonnage vertical et horizontal.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getsize

(PECL gmagick >= Unknown)

Gmagick::getsize — Récupère la taille associée avec l'objet Gmagick

### Description

public function Gmagick::getsize(): array

Récupère la taille associée avec l'objet Gmagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la taille associée avec l'objet Gmagick sous la forme d'un tableau contenant les clés "columns" et "rows".

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::getversion

(PECL gmagick >= Unknown)

Gmagick::getversion — Récupère la version de l'API GraphicsMagick

### Description

public function Gmagick::getversion(): array

Récupère la version de l'API GraphicsMagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la version de l'API GraphicsMagick, sous la forme d'une chaîne de caractères et d'un nombre.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::hasnextimage

(PECL gmagick >= Unknown)

Gmagick::hasnextimage — Vérifie si l'objet contient au moins une autre image

### Description

public function Gmagick::hasnextimage(): mixed

Vérifie si l'objet contient au moins une image suivante.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'objet a au moins une image suivante, `false` sinon.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::haspreviousimage

(PECL gmagick >= Unknown)

Gmagick::haspreviousimage — Vérifie si l'objet contient une image précédente

### Description

public function Gmagick::haspreviousimage(): mixed

Vérifie si l'objet contient une image précédente.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'objet a au moins une image précédente, `false` sinon.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::implodeimage

(PECL gmagick >= Unknown)

Gmagick::implodeimage — Crée une image à partir d'une copie

### Description

public function Gmagick::implodeimage(float `$radius`): mixed

Crée une nouvelle image à partir d'une copie d'une image existante dont les pixels ont été modifiés suivant le pourcentage fourni.

### Liste de paramètres

`radius`
  Le rayon d'implosion des pixels.

### Valeurs de retour

Retourne un objet Gmagick dont les pixels ont été modifiés.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::labelimage

(PECL gmagick >= Unknown)

Gmagick::labelimage — Ajoute un libellé à une image

### Description

public function Gmagick::labelimage(string `$label`): mixed

Ajoute un libellé à une image.

### Liste de paramètres

`label`
  Le libellé à ajouter

### Valeurs de retour

Gmagick avec un libellé.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::levelimage

(PECL gmagick >= Unknown)

Gmagick::levelimage — Ajuste les niveaux d'une image

### Description

public function Gmagick::levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed

Ajuste les niveaux d'une image en balançant les couleurs situées entre les points blancs et noirs spécifiés, vers un intervalle quantum disponible. Les paramètres indiquent les points blancs, milieux et noirs. Le point noir spécifie la couleur la plus sombre de l'image. Les couleurs plus sombres que le point noir seront définies à zéro. Le point milieu spécifie une correction gamma à appliquer à l'image. Le point blanc spécifie la couleur la plus claire de l'image. Les couleurs plus claires que le point blanc seront définies à la valeur maximale du quantum.

### Liste de paramètres

`blackPoint`
  Le point noir de l'image.
`gamma`
  La valeur gamma.
`whitePoint`
  Le point blanc de l'image.
`channel`
  Une constante de canaux valide pour le mode de canal utilisé. Pour l'appliquer à plus d'un canal, combinez les constantes de type de canaux en utilisant un opérateur bit à bit. Se reporter à la liste des constantes de canaux.

### Valeurs de retour

L'objet Gmagick dont les niveaux ont été modifiés.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::magnifyimage

(PECL gmagick >= Unknown)

Gmagick::magnifyimage — Retaille par 2 une image en conservant les proportions

### Description

public function Gmagick::magnifyimage(): mixed

Retaille par 2 une image en conservant les proportions.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick modifié.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::mapimage

(PECL gmagick >= Unknown)

Gmagick::mapimage — Remplace les couleurs d'une image avec les couleurs les plus proches d'une image de référence

### Description

public function Gmagick::mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick

Remplace les couleurs d'une image avec les couleurs les plus proches d'une image de référence.

### Liste de paramètres

`gmagick`
  L'image de référence.
`dither`
  Entier plus grand que 0 pour appliquer le tramage à l'image mappée.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::medianfilterimage

(PECL gmagick >= Unknown)

Gmagick::medianfilterimage — Applique un filtre numérique

### Description

public function Gmagick::medianfilterimage(float `$radius`): void

Applique un filtre numérique qui améliore la qualité du bruit d'une image. Chaque pixel est remplacé par la médiane dans un jeu de pixels voisins tel que défini par le rayon.

### Liste de paramètres

`radius`
  Le rayon des pixels voisins.

### Valeurs de retour

L'objet Gmagick dont le filtre a été appliqué.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::minifyimage

(PECL gmagick >= Unknown)

Gmagick::minifyimage — Réduit une image de moitié en gardant les proportions

### Description

public function Gmagick::minifyimage(): Gmagick

Réduit une image de moitié en gardant les proportions.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::modulateimage

(PECL gmagick >= Unknown)

Gmagick::modulateimage — Contrôle la luminosité, la saturation et la teinte

### Description

public function Gmagick::modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick

Permet de contrôler la luminosité, la saturation et la teinte d'une image. La teinte est un pourcentage d'une rotation absolue depuis la position courante. Par exemple, 50 correspond à une rotation de 90 degrés dans le sens inverse des aiguilles d'une montre, 150, une rotation de 90 degrés dans le sens des aiguilles d'une montre, ou encore, 0 ou 200 correspond à une rotation de 180 degrés.

### Liste de paramètres

`brightness`
  Le nombre de pourcentage à modifier pour la luminosité (-100 à +100).
`saturation`
  Le nombre de pourcentage à modifier pour la saturation (-100 à +100).
`hue`
  Le nombre de pourcentage à modifier pour la teinte (-100 à +100).

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::motionblurimage

(PECL gmagick >= Unknown)

Gmagick::motionblurimage — Simule un flou cinétique

### Description

public function Gmagick::motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick

Simule un flou cinétique. L'image est traitée avec un opérateur Gaussien d'un rayon donné et d'une déviation standard (sigma). Pour de bons résultats, le rayon doit être plus élevé que le sigma. En utilisant un rayon de 0, la méthode Gmagick::motionblurimage() sélectionne automatiquement le meilleur rayon. Le paramètre `angle` fournit l'angle du flou cinétique.

### Liste de paramètres

`radius`
  Le rayon du Gaussien, en pixels, sans compter le pixel central.
`sigma`
  La déviation standard du Gaussien, en pixels.
`angle`
  Applique l'effet tout le long de l'angle.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::newimage

(PECL gmagick >= Unknown)

Gmagick::newimage — Crée une nouvelle image

### Description

public function Gmagick::newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick

Crée une nouvelle image avec la couleur d'arrière-plan spécifiée.

### Liste de paramètres

`width`
  Largeur de la nouvelle image.
`height`
  Hauteur de la nouvelle image.
`background`
  La couleur d'arrière-plan à utiliser pour l'image (sous la forme d'un nombre à virgule flottante)
`format`
  Le format de l'image.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::nextimage

(PECL gmagick >= Unknown)

Gmagick::nextimage — Se déplace sur l'image suivante

### Description

public function Gmagick::nextimage(): bool

Associe l'image suivante dans la liste des images avec un objet Gmagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::normalizeimage

(PECL gmagick >= Unknown)

Gmagick::normalizeimage — Améliore le contraste de la couleur de l'image

### Description

public function Gmagick::normalizeimage(int `$channel` = ?): Gmagick

Améliore le contraste de la couleur de l'image en ajustant la couleur des pixels pour correspondre à l'intervalle de couleurs disponibles.

### Liste de paramètres

`channel`
  Canal à normaliser.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::oilpaintimage

(PECL gmagick >= Unknown)

Gmagick::oilpaintimage — Simule une peinture à l'huile

### Description

public function Gmagick::oilpaintimage( float `$radius` ): Gmagick

Applique un effet spécial qui simule une peinture à l'huile. Chaque pixel est remplacé par la couleur survenant le plus grand nombre de fois dans une région circulaire définie par un rayon.

### Liste de paramètres

`radius`
  Le rayon de la région circulaire voisine.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::previousimage

(PECL gmagick >= Unknown)

Gmagick::previousimage — Se déplace vers l'image précédente de l'objet

### Description

public function Gmagick::previousimage(): bool

Associe l'image précédente de la liste d'images avec l'objet Gmagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::profileimage

(PECL gmagick >= Unknown)

Gmagick::profileimage — Ajoute ou supprime un profil d'une image

### Description

public function Gmagick::profileimage(string `$name`, string `$profile`): Gmagick

Ajoute ou supprime un profil ICC, IPTC ou générique d'une image. Si le profil est `null`, il sera supprimé de l'image, sinon, il sera ajouté. En utilisant `*` comme nom et un profil `null`, il est possible de supprimer tous les profils de l'image.

### Liste de paramètres

`name`
  Nom du profil à ajouter ou à supprimer : profil ICC, IPTC, ou générique.
`profile`
  Le profil.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::quantizeimage

(PECL gmagick >= Unknown)

Gmagick::quantizeimage — Analyse les couleurs d'une image de référence

### Description

public function Gmagick::quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Analyse les couleurs d'une image de référence et choisit un nombre fixe de couleurs représentant l'image. Le but de l'algorithme est de minimiser les différences de couleurs entre l'image d'entrée et celle de sortie lors d'un processus d'optimisation.

### Liste de paramètres

`numColors`
  Le nombre de couleurs.
`colorspace`
  Effectue la réduction de couleurs dans cet espace de couleurs, typiquement RGBColorspace.
`treeDepth`
  Normalement, la valeur de cet entier est zéro ou un. Une telle valeur demande à Quantize de choisir une profondeur optionnelle de Log4(number_colors). Un arbre de cette profondeur autorise généralement la meilleure représentation de l'image de référence tout en utilisant une quantité de mémoire raisonnable ainsi qu'une rapidité d'exécution optimum. Dans certains cas, comme avec une image contenant des dispersions de couleurs basses (un petit nombre de couleurs), une valeur autre que Log4(number_colors) est nécessaire. Pour étendre totalement l'arbre de couleurs, il convient d'utiliser la valeur 8.
`dither`
  Une valeur autre que zéro distribue la différence entre l'image originale et la couleur correspondante réduite par l'algorithme vers les pixels voisins le long de la courbe Hilbert.
`measureError`
  Une valeur autre que zéro mesure la différence entre l'image originale et l'image optimisée. Cette différence représente l'erreur totale de quantification. L'erreur est calculée en faisant la somme de tous les pixels dans une image carrée de la distance dans l'espace RVB entre chaque valeur de pixel de référence et sa valeur quantifiée.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::quantizeimages

(PECL gmagick >= Unknown)

Gmagick::quantizeimages — Le but de quantizeimages

### Description

public function Gmagick::quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Analyse les couleurs d'une séquence d'images et choisit un nombre fixe de couleurs pour représenter l'image. Le but de cet algorithme est de minimiser les différences de couleurs entre l'image d'entrée et celle de sortie lors d'un processus d'optimisation.

### Liste de paramètres

`numColors`
  Le nombre de couleurs.
`colorspace`
  Effectue une réduction de couleur dans cet espace de couleur, habituellement, RGBColorspace.
`treeDepth`
  Normalement, cet entier vaut zéro ou un. Ces valeurs indiquent au Quantize de choisir une profondeur d'arbre optimale de Log4(number_colors). Un arbre de cette profondeur autorise généralement la meilleure représentation de l'image de référence, avec un minimum de mémoire, et une rapidité d'exécution optimale. Dans certains cas, comme une image avec peu de dispersion de couleurs (un nombre peu élevé de couleurs), une valeur autre que Log4(number_colors) est nécessaire. Pour étendre l'arbre des couleurs complètement, il convient d'utiliser la valeur 8.
`dither`
  Une valeur autre que 0 distribue la différence entre l'image originale et la couleur correspondante réduite par l'algorithme aux pixels voisins le long d'une courbe Hilbert.
`measureError`
  Une valeur autre que 0 mesure la différence entre l'image originale et celle quantifiée. La différence représente les erreurs de quantification. L'erreur est calculée en faisant la somme de tous les pixels dans une image carrée de la distance dans l'espace RVB entre chaque valeur de pixel de référence et sa valeur quantifiée.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::queryfontmetrics

(PECL gmagick >= Unknown)

Gmagick::queryfontmetrics — Retourne un tableau représentant la métrique pour la police de caractères

### Description

public function Gmagick::queryfontmetrics(GmagickDraw `$draw`, string `$text`): array

MagickQueryFontMetrics() retourne un tableau représentant la métrique pour la police de caractères.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::queryfonts

(PECL gmagick >= Unknown)

Gmagick::queryfonts — Retourne les polices de caractères configurées

### Description

public function Gmagick::queryfonts(string `$pattern` = "*"): array

Retourne les polices de caractères supportées par Gmagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::queryformats

(PECL gmagick >= Unknown)

Gmagick::queryformats — Retourne les formats supportés par Gmagick

### Description

public function Gmagick::queryformats(string `$pattern` = "*"): array

Retourne les formats supportés par Gmagick.

### Liste de paramètres

`pattern`
  Spécifie un string contenant un masque.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::radialblurimage

(PECL gmagick >= Unknown)

Gmagick::radialblurimage — Brouille une image suivant un rayon

### Description

public function Gmagick::radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick

Brouille une image suivant un rayon.

### Liste de paramètres

`angle`
  L'angle de brouillage, en degrés.
`channel`
  Canal concerné.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::raiseimage

(PECL gmagick >= Unknown)

Gmagick::raiseimage — Crée un bouton avec un effet 3D

### Description

public function Gmagick::raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick

Crée un bouton avec un effet 3D en éclaircissant et en noircissant les angles de l'image. La hauteur et la largeur des membres de raise_info définissent la largeur du coin vertical et horizontal de l'effet.

### Liste de paramètres

`width`
  Largeur de la zone à traiter.
`height`
  Hauteur de la zone à traiter.
`x`
  Coordonnée en X.
`y`
  Coordonnée en Y.
`raise`
  Une valeur, autre que 0, pour créer l'effet 3D, sinon, l'effet sera amoindri.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::read

(PECL gmagick >= Unknown)

Gmagick::read — Lit une image depuis un fichier

### Description

public function Gmagick::read(string `$filename`): Gmagick

Lit une image depuis un fichier.

### Liste de paramètres

`filename`
  Le nom du fichier image.

### Valeurs de retour

Un objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::readimage

(PECL gmagick >= Unknown)

Gmagick::readimage — Lit une image depuis un fichier

### Description

public function Gmagick::readimage(string `$filename`): Gmagick

Lit une image depuis un fichier.

### Liste de paramètres

`filename`
  Le nom du fichier image.

### Valeurs de retour

Un objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::readimageblob

(PECL gmagick >= Unknown)

Gmagick::readimageblob — Lit une image depuis une chaîne binaire

### Description

public function Gmagick::readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick

Lit une image depuis une chaîne binaire.

### Liste de paramètres

`imageContents`
  Contenu de l'image.
`filename`
  Le nom du fichier image.

### Valeurs de retour

Un objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::readimagefile

(PECL gmagick >= Unknown)

Gmagick::readimagefile — Le but de readimagefile

### Description

public function Gmagick::readimagefile(resource `$fp`, string `$filename` = ?): Gmagick

Lit une image ou une séquence d'images depuis un descripteur de fichier ouvert.

### Liste de paramètres

`fp`
  Le descripteur de fichier.

### Valeurs de retour

Un objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::reducenoiseimage

(PECL gmagick >= Unknown)

Gmagick::reducenoiseimage — Lisse les contours de l'image

### Description

public function Gmagick::reducenoiseimage(float `$radius`): Gmagick

Lisse les contours de l'image tout en conservant les informations des coins. L'algorithme fonctionne en remplaçant chaque pixel avec son voisin le plus proche de sa valeur. Un voisin est défini par son rayon. En utilisant un rayon de 0, la méthode Gmagick::reducenoiseimage() sélectionnera un rayon approprié automatiquement.

### Liste de paramètres

`radius`
  Le rayon du pixel voisin.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::removeimage

(PECL gmagick >= Unknown)

Gmagick::removeimage — Supprime une image depuis la liste des images

### Description

public function Gmagick::removeimage(): Gmagick

Supprime une image depuis la liste des images.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::removeimageprofile

(PECL gmagick >= Unknown)

Gmagick::removeimageprofile — Supprime un profil nommé de l'image

### Description

public function Gmagick::removeimageprofile(string `$name`): string

Supprime un profil nommé de l'image.

### Liste de paramètres

`name`
  Nom du profil à retourner : ICC, IPTC, ou un profil générique.

### Valeurs de retour

Le profil nommé

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::resampleimage

(PECL gmagick >= Unknown)

Gmagick::resampleimage — Échantillonne l'image à la résolution désirée

### Description

public function Gmagick::resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick

Échantillonne l'image à la résolution désirée.

### Liste de paramètres

`xResolution`
  La nouvelle résolution en X de l'image.
`yResolution`
  La nouvelle résolution en Y de l'image.
`filter`
  Filtre de l'image à utiliser.
`blur`
  Le facteur de flou où la valeur supérieure à 1 correspond à entièrement flou, et la valeur inférieure à 1, l'inverse.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::resizeimage

(PECL gmagick >= Unknown)

Gmagick::resizeimage — Redimensionne une image

### Description

public function Gmagick::resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick

Redimensionne une image aux dimensions voulues, avec un filtre.

### Liste de paramètres

`width`
  Le nombre de colonnes dans l'image redimensionnée.
`height`
  Le nombre de lignes dans l'image redimensionnée.
`filter`
  Le filtre de l'image à utiliser.
`blur`
  Le facteur de flou, où les valeurs supérieures à 1 correspondent à entièrement flou, et les valeurs inférieures à 1, l'inverse.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::rollimage

(PECL gmagick >= Unknown)

Gmagick::rollimage — Repositionne une image

### Description

public function Gmagick::rollimage(int `$x`, int `$y`): Gmagick

Repositionne une image en utilisant les paramètres `x` et `y`.

### Liste de paramètres

`x`
  La position en X.
`y`
  La position en Y.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::rotateimage

(PECL gmagick >= Unknown)

Gmagick::rotateimage — Effectue une rotation de l'image

### Description

public function Gmagick::rotateimage(mixed `$color`, float `$degrees`): Gmagick

Effectue une rotation de l'image d'un degré spécifié. Les triangles vides non traités par la rotation seront remplis par la couleur d'arrière-plan.

### Liste de paramètres

`color`
  Le pixel d'arrière-plan.
`degrees`
  Le degré de rotation de l'image.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::scaleimage

(PECL gmagick >= Unknown)

Gmagick::scaleimage — Met à l'échelle une image

### Description

public function Gmagick::scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Met à l'échelle une image aux dimensions fournies. Les autres paramètres seront calculés si 0 est passé en tant que paramètre.

### Liste de paramètres

`width`
  Le nombre de colonnes dans l'image mise à l'échelle.
`height`
  Le nombre de lignes dans l'image mise à l'échelle.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::separateimagechannel

(PECL gmagick >= Unknown)

Gmagick::separateimagechannel — Sépare un canal depuis une image

### Description

public function Gmagick::separateimagechannel(int `$channel`): Gmagick

Sépare un canal depuis une image et retourne une image en niveaux de gris. Un canal est un composant d'une couleur particulière de chaque pixel d'une image.

### Liste de paramètres

`channel`
  Une des constantes de canaux (`Gmagick::CHANNEL_*`).

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setCompressionQuality

(No version information available, might only be in Git)

Gmagick::setCompressionQuality — Définit la qualité de compression par défaut de l'objet

### Description

function Gmagick::setCompressionQuality( int `$quality` ): Gmagick

Définit la qualité de compression par défaut de l'objet.

### Liste de paramètres

`quality`
  La valeur par défaut de GraphicsMagick est 75.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

### Exemples

Exemple #1 Exemple avec Gmagick::setCompressionQuality()

    <?php
    $gm = new Gmagick();
    $gm->read("magick:rose");
    $gm->setCompressionQuality(2);
    ?>

# Gmagick::setfilename

(PECL gmagick >= Unknown)

Gmagick::setfilename — Définit le nom de fichier avant la lecture ou l'écriture d'une image

### Description

public function Gmagick::setfilename(string `$filename`): Gmagick

Définit le nom de fichier avant la lecture ou l'écriture d'une image.

### Liste de paramètres

`filename`
  Le nom de fichier de l'image.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::setimagebackgroundcolor — Définit la couleur d'arrière-plan de l'image

### Description

public function Gmagick::setimagebackgroundcolor(GmagickPixel `$color`): Gmagick

Définit la couleur d'arrière-plan de l'image.

### Liste de paramètres

`color`
  La couleur d'arrière-plan.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::setimageblueprimary — Définit le point bleu primaire de l'image chromatique

### Description

public function Gmagick::setimageblueprimary(float `$x`, float `$y`): Gmagick

Définit le point bleu primaire de l'image chromatique.

### Liste de paramètres

`x`
  Coordonnée en X du point du bleu primaire.
`y`
  Coordonnée en Y du point du bleu primaire.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::setimagebordercolor — Définit la couleur de la bordure de l'image

### Description

public function Gmagick::setimagebordercolor(GmagickPixel `$color`): Gmagick

Définit la couleur de la bordure de l'image.

### Liste de paramètres

`color`
  La couleur de la bordure.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::setimagechanneldepth — Définit la profondeur d'un canal particulier de l'image

### Description

public function Gmagick::setimagechanneldepth(int `$channel`, int `$depth`): Gmagick

Définit la profondeur d'un canal particulier de l'image.

### Liste de paramètres

`channel`
  Une des constantes de canaux (`Gmagick::CHANNEL_*`).
`depth`
  La profondeur de l'image, en bits.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::setimagecolorspace — Définit l'espace de couleurs de l'image

### Description

public function Gmagick::setimagecolorspace(int `$colorspace`): Gmagick

Définit l'espace de couleurs de l'image.

### Liste de paramètres

`colorspace`
  Une des constantes d'espace de couleurs de l'image (`Gmagick::COLORSPACE_*`).

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagecompose

(PECL gmagick >= Unknown)

Gmagick::setimagecompose — Définit l'opérateur de composition de l'image

### Description

public function Gmagick::setimagecompose(int `$composite`): Gmagick

Définit l'opérateur de composition de l'image.

### Liste de paramètres

`composite`
  L'opérateur de composition de l'image.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagedelay

(PECL gmagick >= Unknown)

Gmagick::setimagedelay — Définit le délai de l'image

### Description

public function Gmagick::setimagedelay(int `$delay`): Gmagick

Définit le délai de l'image.

### Liste de paramètres

`delay`
  Le délai de l'image, au 1/100ème de seconde.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagedepth

(PECL gmagick >= Unknown)

Gmagick::setimagedepth — Définit la profondeur de l'image

### Description

public function Gmagick::setimagedepth(int `$depth`): Gmagick

Définit la profondeur de l'image.

### Liste de paramètres

`depth`
  La profondeur de l'image, en bits : 8, 16, ou 32.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagedispose

(PECL gmagick >= Unknown)

Gmagick::setimagedispose — Définit la méthode de disposition de l'image

### Description

public function Gmagick::setimagedispose(int `$disposeType`): Gmagick

Définit la méthode de disposition de l'image.

### Liste de paramètres

`disposeType`
  Le type de disposition de l'image.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagefilename

(PECL gmagick >= Unknown)

Gmagick::setimagefilename — Définit le nom du fichier pour une image particulière d'une séquence

### Description

public function Gmagick::setimagefilename(string `$filename`): Gmagick

Définit le nom du fichier pour une image particulière d'une séquence.

### Liste de paramètres

`filename`
  Le nom du fichier de l'image.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimageformat

(PECL gmagick >= Unknown)

Gmagick::setimageformat — Définit le format d'une image

### Description

public function Gmagick::setimageformat(string `$imageFormat`): Gmagick

Définit le format d'une image particulière d'une séquence.

### Liste de paramètres

`imageFormat`
  Le format de l'image.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagegamma

(PECL gmagick >= Unknown)

Gmagick::setimagegamma — Définit le gamma de l'image

### Description

public function Gmagick::setimagegamma(float `$gamma`): Gmagick

Définit le gamma de l'image.

### Liste de paramètres

`gamma`
  Le gamma de l'image.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::setimagegreenprimary — Définit le point vert sur l'image chromatique primaire

### Description

public function Gmagick::setimagegreenprimary(float `$x`, float `$y`): Gmagick

Définit le point vert sur l'image chromatique primaire.

### Liste de paramètres

`x`
  Coordonnée en X du point vert de l'image chromatique.
`y`
  Coordonnée en Y du point vert de l'image chromatique.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimageindex

(PECL gmagick >= Unknown)

Gmagick::setimageindex — Définit l'itérateur à la position spécifiée dans l'image de la liste pointée par son index

### Description

public function Gmagick::setimageindex(int `$index`): Gmagick

Définit l'itérateur à la position spécifiée dans l'image de la liste pointée par son index.

### Liste de paramètres

`index`
  Le numéro de la scène.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::setimageinterlacescheme — Définit le schéma d'entrelacement de l'image

### Description

public function Gmagick::setimageinterlacescheme(int `$interlace`): Gmagick

Définit le schéma d'entrelacement de l'image.

### Liste de paramètres

`interlace`
  Une des constantes des schémas d'entrelacement de l'image (`Gmagick::INTERLACE_*`).

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimageiterations

(PECL gmagick >= Unknown)

Gmagick::setimageiterations — Définit les itérations de l'image

### Description

public function Gmagick::setimageiterations(int `$iterations`): Gmagick

Définit les itérations de l'image.

### Liste de paramètres

`iterations`
  Le délai de l'image au 1/100ème de seconde.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimageprofile

(PECL gmagick >= Unknown)

Gmagick::setimageprofile — Ajoute un profil nommé à l'objet Gmagick

### Description

public function Gmagick::setimageprofile(string `$name`, string `$profile`): Gmagick

Ajoute un profil nommé à l'objet Gmagick. Si un profil avec le même nom existe déjà, il sera remplacé. Cette méthode diffère de la méthode Gmagick::profileImage() dans le fait qu'elle n'applique aucun profil de couleur CMS.

### Liste de paramètres

`name`
  Nom du profil à ajouter ou à effacer : ICC, IPTC, ou un profil générique.
`profile`
  Le profil.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimageredprimary

(PECL gmagick >= Unknown)

Gmagick::setimageredprimary — Définit le point rouge sur l'image chromatique primaire

### Description

public function Gmagick::setimageredprimary(float `$x`, float `$y`): Gmagick

Définit le point rouge sur l'image chromatique primaire.

### Liste de paramètres

`x`
  Coordonnée en X du point rouge de l'image chromatique.
`y`
  Coordonnée en Y du point rouge de l'image chromatique.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::setimagerenderingintent — Définit l'image de rendu

### Description

public function Gmagick::setimagerenderingintent(int `$rendering_intent`): Gmagick

Définit l'image de rendu.

### Liste de paramètres

`rendering_intent`
  Une des constantes de rendu d'image (`Gmagick::RENDERINGINTENT_*`).

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimageresolution

(PECL gmagick >= Unknown)

Gmagick::setimageresolution — Définit la résolution de l'image

### Description

public function Gmagick::setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick

Définit la résolution de l'image.

### Liste de paramètres

`xResolution`
  La résolution en X de l'image.
`yResolution`
  La résolution en Y de l'image.

### Valeurs de retour

L'objet Gmagick en cas de succès.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagescene

(PECL gmagick >= Unknown)

Gmagick::setimagescene — Définit l'image de scène

### Description

public function Gmagick::setimagescene(int `$scene`): Gmagick

Définit l'image de scène.

### Liste de paramètres

`scene`
  Le numéro de la scène dans l'image.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagetype

(PECL gmagick >= Unknown)

Gmagick::setimagetype — Définit le type de l'image

### Description

public function Gmagick::setimagetype(int `$imgType`): Gmagick

Définit le type de l'image.

### Liste de paramètres

`imgType`
  Une des constantes de type d'image (`Gmagick::IMGTYPE_*`).

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimageunits

(PECL gmagick >= Unknown)

Gmagick::setimageunits — Définit les unités à utiliser pour la résolution de l'image

### Description

public function Gmagick::setimageunits(int `$resolution`): Gmagick

Définit les unités à utiliser pour la résolution de l'image.

### Liste de paramètres

`resolution`
  Une des constantes de résolution (`Gmagick::RESOLUTION_*`).

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::setimagewhitepoint — Définit le point blanc sur l'image chromatique primaire

### Description

public function Gmagick::setimagewhitepoint(float `$x`, float `$y`): Gmagick

Définit le point blanc sur l'image chromatique primaire.

### Liste de paramètres

`x`
  Coordonnée en X du point blanc de l'image chromatique.
`y`
  Coordonnée en Y du point blanc de l'image chromatique.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::setsamplingfactors — Définit les facteurs d'échantillonnage de l'image

### Description

public function Gmagick::setsamplingfactors(array `$factors`): Gmagick

Définit les facteurs d'échantillonnage de l'image.

### Liste de paramètres

`factors`
  Un tableau de floats, représentant le facteur d'échantillonnage pour chaque composant de couleur (dans l'ordre RVB).

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::setsize

(PECL gmagick >= Unknown)

Gmagick::setsize — Définit la taille de l'objet Gmagick

### Description

public function Gmagick::setsize(int `$columns`, int `$rows`): Gmagick

Définit la taille de l'objet Gmagick. Cette taille doit être définie avant de lire une image brute au format `Gmagick::COLORSPACE_RGB`, `Gmagick::COLORSPACE_GRAY`, ou `Gmagick::COLORSPACE_CMYK`.

### Liste de paramètres

`columns`
  La largeur, en pixels.
`rows`
  La hauteur, en pixels.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::shearimage

(PECL gmagick >= Unknown)

Gmagick::shearimage — Crée un parallélogramme

### Description

public function Gmagick::shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick

Bouge un coin de l'image le long des axes X ou Y pour créer un parallélogramme. Une direction en X bouge le long de l'axe X, tandis qu'une direction en Y bouge le long de l'axe Y. La quantité de cisaillement est contrôlée par un angle de cisaillement. Pour les cisaillements en direction X, x_shear est mesuré relativement à l'axe Y, et inversement, pour les cisaillements en direction Y, y_shear est mesuré relativement à l'axe X. Les triangles vides ainsi créés lors du cisaillement de l'image seront remplis par la couleur d'arrière-plan.

### Liste de paramètres

`color`
  Le pixel d'arrière-plan.
`xShear`
  Le degré de cisaillement de l'image.
`yShear`
  Le degré de cisaillement de l'image.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::solarizeimage

(PECL gmagick >= Unknown)

Gmagick::solarizeimage — Applique un effet de solarisation à l'image

### Description

public function Gmagick::solarizeimage(int `$threshold`): Gmagick

Applique un effet de solarisation à l'image, similaire à l'effet créé dans une photo en chambre noire, en exposant les zones d'une photo sur papier sensitif à la lumière. Le seuil varie de 0 à QuantumRange et est une mesure de l'étendue de la solarisation.

### Liste de paramètres

`threshold`
  Définit l'étendue de la solarisation.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::spreadimage

(PECL gmagick >= Unknown)

Gmagick::spreadimage — Déplace aléatoirement chaque pixel d'un bloc

### Description

public function Gmagick::spreadimage(float `$radius`): Gmagick

Effet spécial qui déplace aléatoirement chaque pixel d'un bloc défini par le paramètre `radius`.

### Liste de paramètres

`radius`
  Choisit des pixels aléatoirement dans le voisinage de cette étendue.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::stripimage

(PECL gmagick >= Unknown)

Gmagick::stripimage — Supprime d'une image tous les profils et tous les commentaires

### Description

public function Gmagick::stripimage(): Gmagick

Supprime d'une image tous les profils et tous les commentaires.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::swirlimage

(PECL gmagick >= Unknown)

Gmagick::swirlimage — Remous les pixels du centre de l'image

### Description

public function Gmagick::swirlimage(float `$degrees`): Gmagick

Remous les pixels du centre de l'image, où les degrés indiquent l'arc de remous autour duquel les pixels sont déplacés. Il est possible d'obtenir un effet de plus en plus soutenu en modifiant les degrés de 1 à 360.

### Liste de paramètres

`degrees`
  Définit la finesse de l'effet de remous.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::thumbnailimage

(PECL gmagick >= Unknown)

Gmagick::thumbnailimage — Modifie la taille d'une image

### Description

public function Gmagick::thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Modifie la taille d'une image aux dimensions données et supprime les profils associés. Le but est de produire une image miniature, moins lourde, aux fins d'affichage sur le Web. Si `true` est fourni comme valeur du 3ème paramètre, alors les paramètres `width` et `height` sont utilisés comme valeurs maximales pour chaque côté. Les 2 côtés seront mis à l'échelle lors de l'opération.

### Liste de paramètres

`width`
  largeur de l'image.
`height`
  Hauteur de l'image.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::trimimage

(PECL gmagick >= Unknown)

Gmagick::trimimage — Supprime les coins de l'image

### Description

public function Gmagick::trimimage(float `$fuzz`): Gmagick

Supprime les coins qui sont de la couleur de l'arrière-plan depuis l'image.

### Liste de paramètres

`fuzz`
  Par défaut, la cible doit correspondre exactement à la couleur du pixel précis. Cependant, dans beaucoup de cas, 2 couleurs peuvent différer très légèrement. Ce paramètre indique donc la tolérance acceptable à considérer 2 couleurs comme identiques.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

# Gmagick::write

(PECL gmagick >= Unknown)

Gmagick::write — Alias de Gmagick::writeimage()

### Description

Cette méthode est un alias de: Gmagick::writeimage().

# Gmagick::writeimage

(PECL gmagick >= Unknown)

Gmagick::writeimage — Écrit une image dans un fichier

### Description

public function Gmagick::writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick

Écrit une image dans un fichier spécifique. Si le paramètre `filename` vaut `null`, l'image sera écrite dans le fichier défini par la méthode Gmagick::readimage() ou la méthode Gmagick::setimagefilename().

### Liste de paramètres

`filename`
  Le nom du fichier.

### Valeurs de retour

L'objet Gmagick.

### Erreurs / Exceptions

Émet une exception GmagickException en cas d'erreur.

## Sommaire

- Gmagick::addimage — Ajoute une nouvelle image à la liste des images de l'objet Gmagick
- Gmagick::addnoiseimage — Ajoute du bruit aléatoirement dans l'image
- Gmagick::annotateimage — Annote une image avec du texte
- Gmagick::blurimage — Ajoute un filtre flou à l'image
- Gmagick::borderimage — Ajoute une bordure à l'image
- Gmagick::charcoalimage — Simule un dessin au fusain
- Gmagick::chopimage — Supprime une région de l'image
- Gmagick::clear — Efface toutes les ressources associées à l'objet Gmagick
- Gmagick::commentimage — Ajoute un commentaire à l'image
- Gmagick::compositeimage — Assemble 2 images
- Gmagick::__construct — Le constructeur Gmagick
- Gmagick::cropimage — Extrait une portion d'une image
- Gmagick::cropthumbnailimage — Crée une miniature recadrée
- Gmagick::current — Le contexte courant
- Gmagick::cyclecolormapimage — Déplace la carte des couleurs d'une image
- Gmagick::deconstructimages — Retourne les pixels différents entre des images
- Gmagick::despeckleimage — Le but de despeckleimage
- Gmagick::destroy — Le but de la méthode destroy
- Gmagick::drawimage — Fait un rendu de l'objet GmagickDraw sur l'image courante
- Gmagick::edgeimage — Améliore les bords intérieurs de l'image
- Gmagick::embossimage — Retourne une image en niveaux de gris avec un effet à 3 dimensions
- Gmagick::enhanceimage — Améliore la qualité d'une image contenant du bruit
- Gmagick::equalizeimage — Égalise l'histogramme de l'image
- Gmagick::flipimage — Crée une image miroir verticale
- Gmagick::flopimage — Crée une image miroir horizontale
- Gmagick::frameimage — Ajoute une bordure afin de simuler un effet 3D
- Gmagick::gammaimage — Corrige le gamma d'une image
- Gmagick::getcopyright — Retourne le copyright de l'API GraphicsMagick
- Gmagick::getfilename — Retourne le nom du fichier associé avec une séquence d'image
- Gmagick::getimagebackgroundcolor — Retourne la couleur d'arrière plan de l'image
- Gmagick::getimageblueprimary — Retourne le point bleu primaire chromatique
- Gmagick::getimagebordercolor — Retourne la couleur du bord de l'image
- Gmagick::getimagechanneldepth — Récupère la profondeur d'un canal particulier de l'image
- Gmagick::getimagecolors — Retourne la couleur de l'indice de la carte des couleurs spécifiée
- Gmagick::getimagecolorspace — Récupère l'espace colorimétrique de l'image
- Gmagick::getimagecompose — Retourne l'opérateur de composition associé avec l'image
- Gmagick::getimagedelay — Récupère le délai de l'image
- Gmagick::getimagedepth — Récupère la profondeur de l'image
- Gmagick::getimagedispose — Récupère la méthode de disposition de l'image
- Gmagick::getimageextrema — Récupère les extrémités de l'image
- Gmagick::getimagefilename — Récupère le nom du fichier d'une image particulière dans une séquence
- Gmagick::getimageformat — Récupère le format d'une image particulière dans une séquence
- Gmagick::getimagegamma — Récupère le gamma de l'image
- Gmagick::getimagegreenprimary — Récupère le point chromatique primaire vert
- Gmagick::getimageheight — Récupère la hauteur de l'image
- Gmagick::getimagehistogram — Récupère l'histogramme de l'image
- Gmagick::getimageindex — Récupère l'indice de l'image active courante
- Gmagick::getimageinterlacescheme — Récupère le schéma d'entrelacement de l'image
- Gmagick::getimageiterations — Récupère les itérations de l'image
- Gmagick::getimagematte — Vérifie si l'image a un canal mate
- Gmagick::getimagemattecolor — Récupère la couleur mate de l'image
- Gmagick::getimageprofile — Récupère le nom du profil de l'image
- Gmagick::getimageredprimary — Récupère le point chromatique primaire rouge
- Gmagick::getimagerenderingintent — Récupère l'image de rendu
- Gmagick::getimageresolution — Récupère la résolution de l'image
- Gmagick::getimagescene — Récupère la scène de l'image
- Gmagick::getimagesignature — Génère la signature SHA-256 de l'image
- Gmagick::getimagetype — Récupère le type potentiel d'une image
- Gmagick::getimageunits — Récupère les unités utilisées pour la résolution de l'image
- Gmagick::getimagewhitepoint — Récupère le point chromatique blanc
- Gmagick::getimagewidth — Récupère la largeur de l'image
- Gmagick::getpackagename — Récupère le nom du paquet GraphicsMagick
- Gmagick::getquantumdepth — Récupère la profondeur du quantum Gmagick
- Gmagick::getreleasedate — Récupère la date de sortie de la version courante de GraphicsMagick
- Gmagick::getsamplingfactors — Récupère le facteur d'échantillonnage horizontal et vertical
- Gmagick::getsize — Récupère la taille associée avec l'objet Gmagick
- Gmagick::getversion — Récupère la version de l'API GraphicsMagick
- Gmagick::hasnextimage — Vérifie si l'objet contient au moins une autre image
- Gmagick::haspreviousimage — Vérifie si l'objet contient une image précédente
- Gmagick::implodeimage — Crée une image à partir d'une copie
- Gmagick::labelimage — Ajoute un libellé à une image
- Gmagick::levelimage — Ajuste les niveaux d'une image
- Gmagick::magnifyimage — Retaille par 2 une image en conservant les proportions
- Gmagick::mapimage — Remplace les couleurs d'une image avec les couleurs les plus proches d'une image de référence
- Gmagick::medianfilterimage — Applique un filtre numérique
- Gmagick::minifyimage — Réduit une image de moitié en gardant les proportions
- Gmagick::modulateimage — Contrôle la luminosité, la saturation et la teinte
- Gmagick::motionblurimage — Simule un flou cinétique
- Gmagick::newimage — Crée une nouvelle image
- Gmagick::nextimage — Se déplace sur l'image suivante
- Gmagick::normalizeimage — Améliore le contraste de la couleur de l'image
- Gmagick::oilpaintimage — Simule une peinture à l'huile
- Gmagick::previousimage — Se déplace vers l'image précédente de l'objet
- Gmagick::profileimage — Ajoute ou supprime un profil d'une image
- Gmagick::quantizeimage — Analyse les couleurs d'une image de référence
- Gmagick::quantizeimages — Le but de quantizeimages
- Gmagick::queryfontmetrics — Retourne un tableau représentant la métrique pour la police de caractères
- Gmagick::queryfonts — Retourne les polices de caractères configurées
- Gmagick::queryformats — Retourne les formats supportés par Gmagick
- Gmagick::radialblurimage — Brouille une image suivant un rayon
- Gmagick::raiseimage — Crée un bouton avec un effet 3D
- Gmagick::read — Lit une image depuis un fichier
- Gmagick::readimage — Lit une image depuis un fichier
- Gmagick::readimageblob — Lit une image depuis une chaîne binaire
- Gmagick::readimagefile — Le but de readimagefile
- Gmagick::reducenoiseimage — Lisse les contours de l'image
- Gmagick::removeimage — Supprime une image depuis la liste des images
- Gmagick::removeimageprofile — Supprime un profil nommé de l'image
- Gmagick::resampleimage — Échantillonne l'image à la résolution désirée
- Gmagick::resizeimage — Redimensionne une image
- Gmagick::rollimage — Repositionne une image
- Gmagick::rotateimage — Effectue une rotation de l'image
- Gmagick::scaleimage — Met à l'échelle une image
- Gmagick::separateimagechannel — Sépare un canal depuis une image
- Gmagick::setCompressionQuality — Définit la qualité de compression par défaut de l'objet
- Gmagick::setfilename — Définit le nom de fichier avant la lecture ou l'écriture d'une image
- Gmagick::setimagebackgroundcolor — Définit la couleur d'arrière-plan de l'image
- Gmagick::setimageblueprimary — Définit le point bleu primaire de l'image chromatique
- Gmagick::setimagebordercolor — Définit la couleur de la bordure de l'image
- Gmagick::setimagechanneldepth — Définit la profondeur d'un canal particulier de l'image
- Gmagick::setimagecolorspace — Définit l'espace de couleurs de l'image
- Gmagick::setimagecompose — Définit l'opérateur de composition de l'image
- Gmagick::setimagedelay — Définit le délai de l'image
- Gmagick::setimagedepth — Définit la profondeur de l'image
- Gmagick::setimagedispose — Définit la méthode de disposition de l'image
- Gmagick::setimagefilename — Définit le nom du fichier pour une image particulière d'une séquence
- Gmagick::setimageformat — Définit le format d'une image
- Gmagick::setimagegamma — Définit le gamma de l'image
- Gmagick::setimagegreenprimary — Définit le point vert sur l'image chromatique primaire
- Gmagick::setimageindex — Définit l'itérateur à la position spécifiée dans l'image de la liste pointée par son index
- Gmagick::setimageinterlacescheme — Définit le schéma d'entrelacement de l'image
- Gmagick::setimageiterations — Définit les itérations de l'image
- Gmagick::setimageprofile — Ajoute un profil nommé à l'objet Gmagick
- Gmagick::setimageredprimary — Définit le point rouge sur l'image chromatique primaire
- Gmagick::setimagerenderingintent — Définit l'image de rendu
- Gmagick::setimageresolution — Définit la résolution de l'image
- Gmagick::setimagescene — Définit l'image de scène
- Gmagick::setimagetype — Définit le type de l'image
- Gmagick::setimageunits — Définit les unités à utiliser pour la résolution de l'image
- Gmagick::setimagewhitepoint — Définit le point blanc sur l'image chromatique primaire
- Gmagick::setsamplingfactors — Définit les facteurs d'échantillonnage de l'image
- Gmagick::setsize — Définit la taille de l'objet Gmagick
- Gmagick::shearimage — Crée un parallélogramme
- Gmagick::solarizeimage — Applique un effet de solarisation à l'image
- Gmagick::spreadimage — Déplace aléatoirement chaque pixel d'un bloc
- Gmagick::stripimage — Supprime d'une image tous les profils et tous les commentaires
- Gmagick::swirlimage — Remous les pixels du centre de l'image
- Gmagick::thumbnailimage — Modifie la taille d'une image
- Gmagick::trimimage — Supprime les coins de l'image
- Gmagick::write — Alias de Gmagick::writeimage
- Gmagick::writeimage — Écrit une image dans un fichier

# La classe GmagickDraw

(PECL gmagick >= Unknown)

## Introduction

## Synopsis de la classe

class GmagickDraw {
/* Méthodes */
public function annotate(float `$x`, float `$y`, string `$text`): GmagickDraw
public function arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw
public function bezier(array `$coordinate_array`): GmagickDraw
public function ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw
public function getfillcolor(): GmagickPixel
public function getfillopacity(): float
public function getfont(): mixed
public function getfontsize(): float
public function getfontstyle(): int
public function getfontweight(): int
public function getstrokecolor(): GmagickPixel
public function getstrokeopacity(): float
public function getstrokewidth(): float
public function gettextdecoration(): int
public function gettextencoding(): mixed
public function line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw
public function point(float `$x`, float `$y`): GmagickDraw
public function polygon(array `$coordinates`): GmagickDraw
public function polyline(array `$coordinate_array`): GmagickDraw
public function rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw
public function rotate(float `$degrees`): GmagickDraw
public function roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw
public function scale(float `$x`, float `$y`): GmagickDraw
public function setfillcolor(mixed `$color`): GmagickDraw
public function setfillopacity(float `$fill_opacity`): GmagickDraw
public function setfont(string `$font`): GmagickDraw
public function setfontsize(float `$pointsize`): GmagickDraw
public function setfontstyle(int `$style`): GmagickDraw
public function setfontweight(int `$weight`): GmagickDraw
public function setstrokecolor(mixed `$color`): GmagickDraw
public function setstrokeopacity(float `$stroke_opacity`): GmagickDraw
public function setstrokewidth(float `$width`): GmagickDraw
public function settextdecoration(int `$decoration`): GmagickDraw
public function settextencoding(string `$encoding`): GmagickDraw
}

# GmagickDraw::annotate

(PECL gmagick >= Unknown)

GmagickDraw::annotate — Dessine un texte sur l'image

### Description

public function GmagickDraw::annotate(float `$x`, float `$y`, string `$text`): GmagickDraw

Dessine un texte sur l'image.

### Liste de paramètres

`x`
  Coordonnée en X de la gauche du texte.
`y`
  Coordonnée en Y de la base du texte.
`text`
  Le texte à dessiner.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::arc

(PECL gmagick >= Unknown)

GmagickDraw::arc — Dessine un arc

### Description

public function GmagickDraw::arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw

Dessine un arc dans un rectangle spécifié sur l'image.

### Liste de paramètres

`sx`
  Coordonnée en X du début du rectangle conteneur.
`sy`
  Coordonnée en Y du début du rectangle conteneur.
`ex`
  Coordonnée en X de la fin du rectangle conteneur.
`ey`
  Coordonnée en Y de la fin du rectangle conteneur.
`sd`
  Degré de départ de la rotation.
`ed`
  Degré de fin de la rotation.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::bezier

(PECL gmagick >= Unknown)

GmagickDraw::bezier — Dessine une courbe de Bézier

### Description

public function GmagickDraw::bezier(array `$coordinate_array`): GmagickDraw

Dessine une courbe de Bézier sur un jeu de points de l'image.

### Liste de paramètres

`coordinate_array`
  Tableau de coordonnées

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::ellipse

(PECL gmagick >= Unknown)

GmagickDraw::ellipse — Dessine une ellipse sur l'image

### Description

public function GmagickDraw::ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw

Dessine une ellipse sur l'image.

### Liste de paramètres

`ox`
  Coordonnée en X d'origine.
`oy`
  Coordonnée en Y d'origine.
`rx`
  Rayon en X.
`ry`
  Rayon en Y.
`start`
  Rotation de départ, en degrés.
`end`
  Rotation de fin, en degrés.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::getfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::getfillcolor — Retourne la couleur de remplissage

### Description

public function GmagickDraw::getfillcolor(): GmagickPixel

Retourne la couleur de remplissage utilisée pour dessiner les objets pleins.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La couleur de remplissage GmagickPixel utilisée pour dessiner les objets pleins.

# GmagickDraw::getfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::getfillopacity — Retourne l'opacité utilisée lors d'un dessin

### Description

public function GmagickDraw::getfillopacity(): float

Retourne l'opacité utilisée lors d'un dessin.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'opacité utilisée lors d'un dessin utilisant une couleur de remplissage ou une texture de remplissage. Pour une opacité totalement opaque, la valeur 1.0 doit être utilisée.

# GmagickDraw::getfont

(PECL gmagick >= Unknown)

GmagickDraw::getfont — Retourne la police de caractères

### Description

public function GmagickDraw::getfont(): mixed

Retourne une chaîne spécifiant la police de caractères utilisée lors d'une annotation.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères en cas de succès, et `false` si la police de caractères n'est pas définie.

# GmagickDraw::getfontsize

(PECL gmagick >= Unknown)

GmagickDraw::getfontsize — Retourne la taille du point d'une police de caractères

### Description

public function GmagickDraw::getfontsize(): float

Retourne la taille du point d'une police de caractères utilisée lors d'une annotation.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la taille de la police de caractères associée avec l'objet GmagickDraw courant.

# GmagickDraw::getfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::getfontstyle — Retourne le style de la police de caractères

### Description

public function GmagickDraw::getfontstyle(): int

Retourne le style de la police de caractères utilisée lors d'une annotation.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la constante (STYLE_) représentant le style de la police de caractères associée avec l'objet GmagickDraw ou `0` si le style n'est pas défini.

# GmagickDraw::getfontweight

(PECL gmagick >= Unknown)

GmagickDraw::getfontweight — Retourne le poids de la police de caractères

### Description

public function GmagickDraw::getfontweight(): int

Retourne le poids de la police de caractères utilisée lors d'une annotation.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier en cas de succès, et 0 si le poids n'est pas défini.

# GmagickDraw::getstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::getstrokecolor — Retourne la couleur utilisée pour tracer les contours de l'objet

### Description

public function GmagickDraw::getstrokecolor(): GmagickPixel

Retourne la couleur utilisée pour tracer les contours de l'objet.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet GmagickPixel qui décrit la couleur.

# GmagickDraw::getstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::getstrokeopacity — Retourne l'opacité du tracé des contours de l'objet

### Description

public function GmagickDraw::getstrokeopacity(): float

Retourne l'opacité du tracé des contours de l'objet.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un float, décrivant l'opacité.

# GmagickDraw::getstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::getstrokewidth — Retourne la largeur utilisée pour les contours de l'objet

### Description

public function GmagickDraw::getstrokewidth(): float

Retourne la largeur utilisée pour les contours de l'objet.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un float décrivant la largeur des contours.

# GmagickDraw::gettextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::gettextdecoration — Retourne la décoration du texte

### Description

public function GmagickDraw::gettextdecoration(): int

Retourne la décoration à appliquer à du texte lors d'une annotation.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une constante parmi les constantes DECORATION_ et 0 si aucune décoration n'est définie.

# GmagickDraw::gettextencoding

(PECL gmagick >= Unknown)

GmagickDraw::gettextencoding — Retourne le code du jeu de caractères à utiliser pour les annotations

### Description

public function GmagickDraw::gettextencoding(): mixed

Retourne le code du jeu de caractères à utiliser pour les annotations.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères spécifiant le code du jeu de caractères ou `false` si l'encodage n'est pas défini.

# GmagickDraw::line

(PECL gmagick >= Unknown)

GmagickDraw::line — Trace une ligne

### Description

public function GmagickDraw::line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw

Trace une ligne sur l'image en utilisant la couleur de contour courante, l'opacité des contours courante, ainsi que l'épaisseur du contour courant.

### Liste de paramètres

`sx`
  Coordonnée de départ en X.
`sy`
  Coordonnée de départ en Y.
`ex`
  Coordonnée de fin en X.
`ey`
  Coordonnée de fin en Y.

### Valeurs de retour

L'objet GmagickDraw en cas de succès.

# GmagickDraw::point

(PECL gmagick >= Unknown)

GmagickDraw::point — Dessine un point

### Description

public function GmagickDraw::point(float `$x`, float `$y`): GmagickDraw

Dessine un point en utilisant la couleur et l'épaisseur courants du contour aux coordonnées spécifiées.

### Liste de paramètres

`x`
  Coordonnée cible en X.
`y`
  Coordonnée cible en Y.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::polygon

(PECL gmagick >= Unknown)

GmagickDraw::polygon — Dessine un polygone

### Description

public function GmagickDraw::polygon(array `$coordinates`): GmagickDraw

Dessine un polygone en utilisant les paramètres courants du contour, la couleur ou la texture de remplissage, et en utilisant le tableau de coordonnées spécifié.

### Liste de paramètres

`coordinates`
  Tableau de coordonnées.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::polyline

(PECL gmagick >= Unknown)

GmagickDraw::polyline — Dessine une polyligne

### Description

public function GmagickDraw::polyline(array `$coordinate_array`): GmagickDraw

Dessine une polyligne en utilisant les paramètres courants du contour, et la couleur ou la texture de remplissage, et en utilisant le tableau de coordonnées spécifié.

### Liste de paramètres

`coordinate_array`
  Le tableau de coordonnées.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::rectangle

(PECL gmagick >= Unknown)

GmagickDraw::rectangle — Dessine un rectangle

### Description

public function GmagickDraw::rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw

Dessine un rectangle en utilisant 2 coordonnées, et en utilisant les paramètres de contour et de remplissage courants.

### Liste de paramètres

`x1`
  Coordonnée en X du premier point.
`y1`
  Coordonnée en Y du premier point.
`x2`
  Coordonnée en X du second point.
`y2`
  Coordonnée en Y du second point.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::rotate

(PECL gmagick >= Unknown)

GmagickDraw::rotate — Applique une rotation

### Description

public function GmagickDraw::rotate(float `$degrees`): GmagickDraw

Applique une rotation spécifiée à l'espace courant.

### Liste de paramètres

`degrees`
  Degrés pour la rotation.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::roundrectangle

(PECL gmagick >= Unknown)

GmagickDraw::roundrectangle — Dessine un rectangle arrondi

### Description

public function GmagickDraw::roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw

Dessine un rectangle arrondi en utilisant les paramètres fournis.

### Liste de paramètres

`x1`
  Coordonnée en X du premier point.
`y1`
  Coordonnée en Y du premier point.
`x2`
  Coordonnée en X du second point.
`y2`
  Coordonnée en Y du second point.
`rx`
  Le rayon du coin en direction horizontale.
`ry`
  Le rayon du coin en direction verticale.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::scale

(PECL gmagick >= Unknown)

GmagickDraw::scale — Ajuste le facteur d'échelle

### Description

public function GmagickDraw::scale(float `$x`, float `$y`): GmagickDraw

Ajuste le facteur d'échelle à appliquer aux directions horizontale et verticale de l'espace courant.

### Liste de paramètres

`x`
  Facteur d'échelle horizontal.
`y`
  Facteur d'échelle vertical.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::setfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::setfillcolor — Définit la couleur de remplissage à utiliser pour dessiner des objets pleins

### Description

public function GmagickDraw::setfillcolor(mixed `$color`): GmagickDraw

Définit la couleur de remplissage à utiliser pour dessiner des objets pleins.

### Liste de paramètres

`color`
  Objet GmagickPixel ou string indiquant la couleur de remplissage.

### Valeurs de retour

L'objet GmagickDraw en cas de succès.

# GmagickDraw::setfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::setfillopacity — Le but de la méthode setfillopacity

### Description

public function GmagickDraw::setfillopacity(float `$fill_opacity`): GmagickDraw

Définit l'opacité à utiliser lors d'un dessin en utilisant une couleur ou une texture de remplissage. Le fait de définir la valeur à 1.0 signifie que le remplissage sera totalement opaque.

### Liste de paramètres

`fill_opacity`
  Opacité du remplissage.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::setfont

(PECL gmagick >= Unknown)

GmagickDraw::setfont — Définit la police de caractère à utiliser lors d'une annotation

### Description

public function GmagickDraw::setfont(string `$font`): GmagickDraw

Définit la police de caractère à utiliser lors d'une annotation.

### Liste de paramètres

`font`
  Le nom de la police de caractère.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::setfontsize

(PECL gmagick >= Unknown)

GmagickDraw::setfontsize — Définit la taille, en points, de la police de caractère utilisée lors d'une annotation

### Description

public function GmagickDraw::setfontsize(float `$pointsize`): GmagickDraw

Définit la taille, en points, de la police de caractère utilisée lors d'une annotation.

### Liste de paramètres

`pointsize`
  La taille, en points, du texte.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::setfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::setfontstyle — Définit le style de police de caractères à utiliser lors d'une annotation

### Description

public function GmagickDraw::setfontstyle(int `$style`): GmagickDraw

Définit le style de police de caractères à utiliser lors d'une annotation. L'énumération AnyStyle agit comme une option jocker.

### Liste de paramètres

`style`
  Style de la police de caractères (NormalStyle, ItalicStyle, ObliqueStyle, AnyStyle)

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::setfontweight

(PECL gmagick >= Unknown)

GmagickDraw::setfontweight — Définit le poids de la police de caractères

### Description

public function GmagickDraw::setfontweight(int `$weight`): GmagickDraw

Définit le poids de la police de caractères à utiliser lors d'une annotation.

### Liste de paramètres

`weight`
  Poids de la police de caractères (intervalle valide entre 100-900).

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::setstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::setstrokecolor — Définit la couleur à utiliser pour tracer les contours de l'objet

### Description

public function GmagickDraw::setstrokecolor(mixed `$color`): GmagickDraw

Définit la couleur à utiliser pour tracer les contours de l'objet.

### Liste de paramètres

`color`
  Objet GmagickPixel ou string représentant la couleur pour les contours.

### Valeurs de retour

L'objet GmagickDraw en cas de succès.

# GmagickDraw::setstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::setstrokeopacity — Spécifie l'opacité pour les contours de l'objet

### Description

public function GmagickDraw::setstrokeopacity(float `$stroke_opacity`): GmagickDraw

Spécifie l'opacité pour les contours de l'objet.

### Liste de paramètres

`stroke_opacity`
  L'opacité. La valeur 1.0 représente une opacité opaque.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::setstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::setstrokewidth — Définit la largeur des contours de l'objet

### Description

public function GmagickDraw::setstrokewidth(float `$width`): GmagickDraw

Définit la largeur des contours de l'objet.

### Liste de paramètres

`width`
  La largeur des contours.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::settextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::settextdecoration — Spécifie une décoration

### Description

public function GmagickDraw::settextdecoration(int `$decoration`): GmagickDraw

Spécifie une décoration à appliquer au texte lors d'une annotation.

### Liste de paramètres

`int`
  La décoration du texte. Une constante parmi NoDecoration, UnderlineDecoration, OverlineDecoration, ou LineThroughDecoration.

### Valeurs de retour

L'objet GmagickDraw.

# GmagickDraw::settextencoding

(PECL gmagick >= Unknown)

GmagickDraw::settextencoding — Spécifie le code du jeu de caractères à utiliser

### Description

public function GmagickDraw::settextencoding(string `$encoding`): GmagickDraw

Spécifie le code du jeu de caractères à utiliser pour le texte des annotations. Le seul jeu de caractères qui peut être actuellement spécifié est "UTF-8" pour représenter l'Unicode comme séquence d'octets. En spécifiant une chaîne vide pour définir l'encodage du texte conformément à celui du système. Un texte utilisant l'Unicode sera représenté correctement lors de l'utilisation d'une police de caractères qui supporte l'Unicode.

### Liste de paramètres

`encoding`
  Chaîne spécifiant l'encodage du texte.

### Valeurs de retour

L'objet GmagickDraw.

## Sommaire

- GmagickDraw::annotate — Dessine un texte sur l'image
- GmagickDraw::arc — Dessine un arc
- GmagickDraw::bezier — Dessine une courbe de Bézier
- GmagickDraw::ellipse — Dessine une ellipse sur l'image
- GmagickDraw::getfillcolor — Retourne la couleur de remplissage
- GmagickDraw::getfillopacity — Retourne l'opacité utilisée lors d'un dessin
- GmagickDraw::getfont — Retourne la police de caractères
- GmagickDraw::getfontsize — Retourne la taille du point d'une police de caractères
- GmagickDraw::getfontstyle — Retourne le style de la police de caractères
- GmagickDraw::getfontweight — Retourne le poids de la police de caractères
- GmagickDraw::getstrokecolor — Retourne la couleur utilisée pour tracer les contours de l'objet
- GmagickDraw::getstrokeopacity — Retourne l'opacité du tracé des contours de l'objet
- GmagickDraw::getstrokewidth — Retourne la largeur utilisée pour les contours de l'objet
- GmagickDraw::gettextdecoration — Retourne la décoration du texte
- GmagickDraw::gettextencoding — Retourne le code du jeu de caractères à utiliser pour les annotations
- GmagickDraw::line — Trace une ligne
- GmagickDraw::point — Dessine un point
- GmagickDraw::polygon — Dessine un polygone
- GmagickDraw::polyline — Dessine une polyligne
- GmagickDraw::rectangle — Dessine un rectangle
- GmagickDraw::rotate — Applique une rotation
- GmagickDraw::roundrectangle — Dessine un rectangle arrondi
- GmagickDraw::scale — Ajuste le facteur d'échelle
- GmagickDraw::setfillcolor — Définit la couleur de remplissage à utiliser pour dessiner des objets pleins
- GmagickDraw::setfillopacity — Le but de la méthode setfillopacity
- GmagickDraw::setfont — Définit la police de caractère à utiliser lors d'une annotation
- GmagickDraw::setfontsize — Définit la taille, en points, de la police de caractère utilisée lors d'une annotation
- GmagickDraw::setfontstyle — Définit le style de police de caractères à utiliser lors d'une annotation
- GmagickDraw::setfontweight — Définit le poids de la police de caractères
- GmagickDraw::setstrokecolor — Définit la couleur à utiliser pour tracer les contours de l'objet
- GmagickDraw::setstrokeopacity — Spécifie l'opacité pour les contours de l'objet
- GmagickDraw::setstrokewidth — Définit la largeur des contours de l'objet
- GmagickDraw::settextdecoration — Spécifie une décoration
- GmagickDraw::settextencoding — Spécifie le code du jeu de caractères à utiliser

# La classe GmagickPixel

(PECL gmagick >= Unknown)

## Introduction

## Synopsis de la classe

class GmagickPixel {
/* Méthodes */
public function __construct(string `$color` = ?)
public function getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed
public function getcolorcount(): int
public function getcolorvalue(int `$color`): float
public function setcolor(string `$color`): GmagickPixel
public function setcolorvalue(int `$color`, float `$value`): GmagickPixel
}

# GmagickPixel::__construct

(PECL gmagick >= Unknown)

GmagickPixel::__construct — Le constructeur GmagickPixel

### Description

public function GmagickPixel::__construct(string `$color` = ?)

Construit un nouvel objet GmagickPixel. Si une couleur est spécifiée, l'objet est construit puis initialisé en utilisant cette couleur avant d'être retourné.

### Liste de paramètres

`color`
  La couleur à utiliser comme valeur initiale de cet objet (optionnel).

# GmagickPixel::getcolor

(PECL gmagick >= Unknown)

GmagickPixel::getcolor — Retourne la couleur

### Description

public function GmagickPixel::getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed

Retourne la couleur décrite par l'objet GmagickPixel, sous la forme d'une chaîne de caractères ou un tableau. Si la couleur a un canal d'opacité défini, il sera spécifié comme 4ème valeur de la liste.

### Liste de paramètres

`as_array`
  `true` pour indiquer que la valeur retournée doit être un tableau au lieu d'une chaîne de caractères.
`normalize_array`
  `true` pour normaliser les valeurs de couleur.

### Valeurs de retour

Une chaîne de caractères ou un tableau des valeurs de canaux, dont chacun est normalisé si `true` est fourni pour `normalize_array`. Émet une exception GmagickPixelException en cas d'erreur.

# GmagickPixel::getcolorcount

(PECL gmagick >= Unknown)

GmagickPixel::getcolorcount — Retourne le nombre de couleurs associées avec cette couleur

### Description

public function GmagickPixel::getcolorcount(): int

Retourne le nombre de couleurs associées avec cette couleur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de couleurs, sous la forme d'un entier en cas de succès, et émet une exception GmagickPixelException si une erreur survient.

# GmagickPixel::getcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::getcolorvalue — Récupère la valeur normalisée du canal de la couleur fournie

### Description

public function GmagickPixel::getcolorvalue(int `$color`): float

Récupère la valeur normalisée du canal de la couleur fournie, sous la forme d'un nombre à virgule flottante compris entre 0 et 1.

### Liste de paramètres

`color`
  Le canal à vérifier, spécifié sous la forme d'une des constantes de canal Gmagick.

### Valeurs de retour

La valeur du canal, sous la forme d'un nombre à virgule flottante normalisé, et émet une exception GmagickPixelException si une erreur survient.

# GmagickPixel::setcolor

(PECL gmagick >= Unknown)

GmagickPixel::setcolor — Définit la couleur

### Description

public function GmagickPixel::setcolor(string `$color`): GmagickPixel

Définit la couleur décrite par l'objet GmagickPixel, avec une chaîne de caractères (c.-à-d. "blue", "#0000ff", "rgb(0,0,255)", "cmyk(100,100,100,10)", etc.).

### Liste de paramètres

`color`
  La définition de la couleur à utiliser pour initialiser l'objet GmagickPixel.

### Valeurs de retour

L'objet GmagickPixel en cas de succès.

# GmagickPixel::setcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::setcolorvalue — Définit la valeur normalisée d'un des canaux

### Description

public function GmagickPixel::setcolorvalue(int `$color`, float `$value`): GmagickPixel

Définit la valeur du canal spécifié de cet objet à une valeur fournie, qui doit être entre 0 et 1. Cette fonction peut être utilisée pour fournir un canal d'opacité à l'objet GmagickPixel.

### Liste de paramètres

`color`
  Une des constantes de couleur de canal Gmagick.
`value`
  La valeur à utiliser pour définir ce canal, comprise entre 0 et 1.

### Valeurs de retour

L'objet GmagickPixel en cas de succès.

## Sommaire

- GmagickPixel::__construct — Le constructeur GmagickPixel
- GmagickPixel::getcolor — Retourne la couleur
- GmagickPixel::getcolorcount — Retourne le nombre de couleurs associées avec cette couleur
- GmagickPixel::getcolorvalue — Récupère la valeur normalisée du canal de la couleur fournie
- GmagickPixel::setcolor — Définit la couleur
- GmagickPixel::setcolorvalue — Définit la valeur normalisée d'un des canaux

- Installation/Configuration
  - Pré-requis
  - Installation
- Constantes pré-définies
- Exemples
- Gmagick — La classe Gmagick
  - Gmagick::addimage — Ajoute une nouvelle image à la liste des images de l'objet Gmagick
  - Gmagick::addnoiseimage — Ajoute du bruit aléatoirement dans l'image
  - Gmagick::annotateimage — Annote une image avec du texte
  - Gmagick::blurimage — Ajoute un filtre flou à l'image
  - Gmagick::borderimage — Ajoute une bordure à l'image
  - Gmagick::charcoalimage — Simule un dessin au fusain
  - Gmagick::chopimage — Supprime une région de l'image
  - Gmagick::clear — Efface toutes les ressources associées à l'objet Gmagick
  - Gmagick::commentimage — Ajoute un commentaire à l'image
  - Gmagick::compositeimage — Assemble 2 images
  - Gmagick::__construct — Le constructeur Gmagick
  - Gmagick::cropimage — Extrait une portion d'une image
  - Gmagick::cropthumbnailimage — Crée une miniature recadrée
  - Gmagick::current — Le contexte courant
  - Gmagick::cyclecolormapimage — Déplace la carte des couleurs d'une image
  - Gmagick::deconstructimages — Retourne les pixels différents entre des images
  - Gmagick::despeckleimage — Le but de despeckleimage
  - Gmagick::destroy — Le but de la méthode destroy
  - Gmagick::drawimage — Fait un rendu de l'objet GmagickDraw sur l'image courante
  - Gmagick::edgeimage — Améliore les bords intérieurs de l'image
  - Gmagick::embossimage — Retourne une image en niveaux de gris avec un effet à 3 dimensions
  - Gmagick::enhanceimage — Améliore la qualité d'une image contenant du bruit
  - Gmagick::equalizeimage — Égalise l'histogramme de l'image
  - Gmagick::flipimage — Crée une image miroir verticale
  - Gmagick::flopimage — Crée une image miroir horizontale
  - Gmagick::frameimage — Ajoute une bordure afin de simuler un effet 3D
  - Gmagick::gammaimage — Corrige le gamma d'une image
  - Gmagick::getcopyright — Retourne le copyright de l'API GraphicsMagick
  - Gmagick::getfilename — Retourne le nom du fichier associé avec une séquence d'image
  - Gmagick::getimagebackgroundcolor — Retourne la couleur d'arrière plan de l'image
  - Gmagick::getimageblueprimary — Retourne le point bleu primaire chromatique
  - Gmagick::getimagebordercolor — Retourne la couleur du bord de l'image
  - Gmagick::getimagechanneldepth — Récupère la profondeur d'un canal particulier de l'image
  - Gmagick::getimagecolors — Retourne la couleur de l'indice de la carte des couleurs spécifiée
  - Gmagick::getimagecolorspace — Récupère l'espace colorimétrique de l'image
  - Gmagick::getimagecompose — Retourne l'opérateur de composition associé avec l'image
  - Gmagick::getimagedelay — Récupère le délai de l'image
  - Gmagick::getimagedepth — Récupère la profondeur de l'image
  - Gmagick::getimagedispose — Récupère la méthode de disposition de l'image
  - Gmagick::getimageextrema — Récupère les extrémités de l'image
  - Gmagick::getimagefilename — Récupère le nom du fichier d'une image particulière dans une séquence
  - Gmagick::getimageformat — Récupère le format d'une image particulière dans une séquence
  - Gmagick::getimagegamma — Récupère le gamma de l'image
  - Gmagick::getimagegreenprimary — Récupère le point chromatique primaire vert
  - Gmagick::getimageheight — Récupère la hauteur de l'image
  - Gmagick::getimagehistogram — Récupère l'histogramme de l'image
  - Gmagick::getimageindex — Récupère l'indice de l'image active courante
  - Gmagick::getimageinterlacescheme — Récupère le schéma d'entrelacement de l'image
  - Gmagick::getimageiterations — Récupère les itérations de l'image
  - Gmagick::getimagematte — Vérifie si l'image a un canal mate
  - Gmagick::getimagemattecolor — Récupère la couleur mate de l'image
  - Gmagick::getimageprofile — Récupère le nom du profil de l'image
  - Gmagick::getimageredprimary — Récupère le point chromatique primaire rouge
  - Gmagick::getimagerenderingintent — Récupère l'image de rendu
  - Gmagick::getimageresolution — Récupère la résolution de l'image
  - Gmagick::getimagescene — Récupère la scène de l'image
  - Gmagick::getimagesignature — Génère la signature SHA-256 de l'image
  - Gmagick::getimagetype — Récupère le type potentiel d'une image
  - Gmagick::getimageunits — Récupère les unités utilisées pour la résolution de l'image
  - Gmagick::getimagewhitepoint — Récupère le point chromatique blanc
  - Gmagick::getimagewidth — Récupère la largeur de l'image
  - Gmagick::getpackagename — Récupère le nom du paquet GraphicsMagick
  - Gmagick::getquantumdepth — Récupère la profondeur du quantum Gmagick
  - Gmagick::getreleasedate — Récupère la date de sortie de la version courante de GraphicsMagick
  - Gmagick::getsamplingfactors — Récupère le facteur d'échantillonnage horizontal et vertical
  - Gmagick::getsize — Récupère la taille associée avec l'objet Gmagick
  - Gmagick::getversion — Récupère la version de l'API GraphicsMagick
  - Gmagick::hasnextimage — Vérifie si l'objet contient au moins une autre image
  - Gmagick::haspreviousimage — Vérifie si l'objet contient une image précédente
  - Gmagick::implodeimage — Crée une image à partir d'une copie
  - Gmagick::labelimage — Ajoute un libellé à une image
  - Gmagick::levelimage — Ajuste les niveaux d'une image
  - Gmagick::magnifyimage — Retaille par 2 une image en conservant les proportions
  - Gmagick::mapimage — Remplace les couleurs d'une image avec les couleurs les plus proches d'une image de référence
  - Gmagick::medianfilterimage — Applique un filtre numérique
  - Gmagick::minifyimage — Réduit une image de moitié en gardant les proportions
  - Gmagick::modulateimage — Contrôle la luminosité, la saturation et la teinte
  - Gmagick::motionblurimage — Simule un flou cinétique
  - Gmagick::newimage — Crée une nouvelle image
  - Gmagick::nextimage — Se déplace sur l'image suivante
  - Gmagick::normalizeimage — Améliore le contraste de la couleur de l'image
  - Gmagick::oilpaintimage — Simule une peinture à l'huile
  - Gmagick::previousimage — Se déplace vers l'image précédente de l'objet
  - Gmagick::profileimage — Ajoute ou supprime un profil d'une image
  - Gmagick::quantizeimage — Analyse les couleurs d'une image de référence
  - Gmagick::quantizeimages — Le but de quantizeimages
  - Gmagick::queryfontmetrics — Retourne un tableau représentant la métrique pour la police de caractères
  - Gmagick::queryfonts — Retourne les polices de caractères configurées
  - Gmagick::queryformats — Retourne les formats supportés par Gmagick
  - Gmagick::radialblurimage — Brouille une image suivant un rayon
  - Gmagick::raiseimage — Crée un bouton avec un effet 3D
  - Gmagick::read — Lit une image depuis un fichier
  - Gmagick::readimage — Lit une image depuis un fichier
  - Gmagick::readimageblob — Lit une image depuis une chaîne binaire
  - Gmagick::readimagefile — Le but de readimagefile
  - Gmagick::reducenoiseimage — Lisse les contours de l'image
  - Gmagick::removeimage — Supprime une image depuis la liste des images
  - Gmagick::removeimageprofile — Supprime un profil nommé de l'image
  - Gmagick::resampleimage — Échantillonne l'image à la résolution désirée
  - Gmagick::resizeimage — Redimensionne une image
  - Gmagick::rollimage — Repositionne une image
  - Gmagick::rotateimage — Effectue une rotation de l'image
  - Gmagick::scaleimage — Met à l'échelle une image
  - Gmagick::separateimagechannel — Sépare un canal depuis une image
  - Gmagick::setCompressionQuality — Définit la qualité de compression par défaut de l'objet
  - Gmagick::setfilename — Définit le nom de fichier avant la lecture ou l'écriture d'une image
  - Gmagick::setimagebackgroundcolor — Définit la couleur d'arrière-plan de l'image
  - Gmagick::setimageblueprimary — Définit le point bleu primaire de l'image chromatique
  - Gmagick::setimagebordercolor — Définit la couleur de la bordure de l'image
  - Gmagick::setimagechanneldepth — Définit la profondeur d'un canal particulier de l'image
  - Gmagick::setimagecolorspace — Définit l'espace de couleurs de l'image
  - Gmagick::setimagecompose — Définit l'opérateur de composition de l'image
  - Gmagick::setimagedelay — Définit le délai de l'image
  - Gmagick::setimagedepth — Définit la profondeur de l'image
  - Gmagick::setimagedispose — Définit la méthode de disposition de l'image
  - Gmagick::setimagefilename — Définit le nom du fichier pour une image particulière d'une séquence
  - Gmagick::setimageformat — Définit le format d'une image
  - Gmagick::setimagegamma — Définit le gamma de l'image
  - Gmagick::setimagegreenprimary — Définit le point vert sur l'image chromatique primaire
  - Gmagick::setimageindex — Définit l'itérateur à la position spécifiée dans l'image de la liste pointée par son index
  - Gmagick::setimageinterlacescheme — Définit le schéma d'entrelacement de l'image
  - Gmagick::setimageiterations — Définit les itérations de l'image
  - Gmagick::setimageprofile — Ajoute un profil nommé à l'objet Gmagick
  - Gmagick::setimageredprimary — Définit le point rouge sur l'image chromatique primaire
  - Gmagick::setimagerenderingintent — Définit l'image de rendu
  - Gmagick::setimageresolution — Définit la résolution de l'image
  - Gmagick::setimagescene — Définit l'image de scène
  - Gmagick::setimagetype — Définit le type de l'image
  - Gmagick::setimageunits — Définit les unités à utiliser pour la résolution de l'image
  - Gmagick::setimagewhitepoint — Définit le point blanc sur l'image chromatique primaire
  - Gmagick::setsamplingfactors — Définit les facteurs d'échantillonnage de l'image
  - Gmagick::setsize — Définit la taille de l'objet Gmagick
  - Gmagick::shearimage — Crée un parallélogramme
  - Gmagick::solarizeimage — Applique un effet de solarisation à l'image
  - Gmagick::spreadimage — Déplace aléatoirement chaque pixel d'un bloc
  - Gmagick::stripimage — Supprime d'une image tous les profils et tous les commentaires
  - Gmagick::swirlimage — Remous les pixels du centre de l'image
  - Gmagick::thumbnailimage — Modifie la taille d'une image
  - Gmagick::trimimage — Supprime les coins de l'image
  - Gmagick::write — Alias de Gmagick::writeimage
  - Gmagick::writeimage — Écrit une image dans un fichier
- GmagickDraw — La classe GmagickDraw
  - GmagickDraw::annotate — Dessine un texte sur l'image
  - GmagickDraw::arc — Dessine un arc
  - GmagickDraw::bezier — Dessine une courbe de Bézier
  - GmagickDraw::ellipse — Dessine une ellipse sur l'image
  - GmagickDraw::getfillcolor — Retourne la couleur de remplissage
  - GmagickDraw::getfillopacity — Retourne l'opacité utilisée lors d'un dessin
  - GmagickDraw::getfont — Retourne la police de caractères
  - GmagickDraw::getfontsize — Retourne la taille du point d'une police de caractères
  - GmagickDraw::getfontstyle — Retourne le style de la police de caractères
  - GmagickDraw::getfontweight — Retourne le poids de la police de caractères
  - GmagickDraw::getstrokecolor — Retourne la couleur utilisée pour tracer les contours de l'objet
  - GmagickDraw::getstrokeopacity — Retourne l'opacité du tracé des contours de l'objet
  - GmagickDraw::getstrokewidth — Retourne la largeur utilisée pour les contours de l'objet
  - GmagickDraw::gettextdecoration — Retourne la décoration du texte
  - GmagickDraw::gettextencoding — Retourne le code du jeu de caractères à utiliser pour les annotations
  - GmagickDraw::line — Trace une ligne
  - GmagickDraw::point — Dessine un point
  - GmagickDraw::polygon — Dessine un polygone
  - GmagickDraw::polyline — Dessine une polyligne
  - GmagickDraw::rectangle — Dessine un rectangle
  - GmagickDraw::rotate — Applique une rotation
  - GmagickDraw::roundrectangle — Dessine un rectangle arrondi
  - GmagickDraw::scale — Ajuste le facteur d'échelle
  - GmagickDraw::setfillcolor — Définit la couleur de remplissage à utiliser pour dessiner des objets pleins
  - GmagickDraw::setfillopacity — Le but de la méthode setfillopacity
  - GmagickDraw::setfont — Définit la police de caractère à utiliser lors d'une annotation
  - GmagickDraw::setfontsize — Définit la taille, en points, de la police de caractère utilisée lors d'une annotation
  - GmagickDraw::setfontstyle — Définit le style de police de caractères à utiliser lors d'une annotation
  - GmagickDraw::setfontweight — Définit le poids de la police de caractères
  - GmagickDraw::setstrokecolor — Définit la couleur à utiliser pour tracer les contours de l'objet
  - GmagickDraw::setstrokeopacity — Spécifie l'opacité pour les contours de l'objet
  - GmagickDraw::setstrokewidth — Définit la largeur des contours de l'objet
  - GmagickDraw::settextdecoration — Spécifie une décoration
  - GmagickDraw::settextencoding — Spécifie le code du jeu de caractères à utiliser
- GmagickPixel — La classe GmagickPixel
  - GmagickPixel::__construct — Le constructeur GmagickPixel
  - GmagickPixel::getcolor — Retourne la couleur
  - GmagickPixel::getcolorcount — Retourne le nombre de couleurs associées avec cette couleur
  - GmagickPixel::getcolorvalue — Récupère la valeur normalisée du canal de la couleur fournie
  - GmagickPixel::setcolor — Définit la couleur
  - GmagickPixel::setcolorvalue — Définit la valeur normalisée d'un des canaux

# Traitement des images (ImageMagick)

# Introduction

Avertissement

Cette extension est EXPERIMENTALE. Le comportement de cette extension, les noms de ses fonctions, et toute la documentation autour de cette extension peut changer sans préavis dans une prochaine version de PHP. Cette extension doit être utilisée à vos risques et périls.

Imagick est une extension PHP native permettant de créer et de modifier des images en utilisant l'API ImageMagick.

## À propos d'ImageMagick

ImageMagick est une suite de logiciels permettant la création, l'édition et la composition d'images bitmap. Elle peut lire, convertir et écrire des images dans divers formats (plus d'une centaine) dont DPX, EXR, GIF, JPEG, JPEG-2000, PDF, PhotoCD, PNG, Postscript, SVG et TIFF.

ImageMagick Studio LLC est une organisation à but non lucratif dont la vocation est de rendre librement disponibles des solutions logicielles de traitement d'images.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

## Configuration nécessaire pour l'installation sous les plates-formes différentes de Windows

ImageMagick >= 6.2.4 est nécessaire. Le nombre de formats supportés par Imagick est totalement dépendant de ceux supportés par l'installation ImageMagick. Par exemple, ImageMagick a besoin de ghostscript pour effectuer les opérations relatives aux PDF.

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/imagick.

> Note: Le nom officiel de cette extension est imagick.

Les utilisateurs de Windows peuvent télécharger une DLL préconstruite depuis le site de PECL : » PECL. Ces paquets contiennent déjà la DLL d'extension (php_imagick.dll) qui doit être placée dans le extension_dir. Ils contiennent également les DLL d'ImageMagick, qui doivent être placées quelque part dans le PATH. À partir d'Imagick 3.6.0, ils contiennent également des fichiers de configuration XML dans config; pour les utiliser à la place des valeurs par défaut intégrées, ils doivent être placés dans `%USERPROFILE%/.config/ImageMagick`, ou alternativement dans le chemin donné par la variable d'environnement MAGICK_CONFIGURE_PATH. Se reporter à la » Documentation sur les fichiers de configuration d'ImageMagick pour plus de détails.

## Configuration à l'exécution

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

Options de configuration Imagick
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
imagick.locale_fix | `false` | `INI_ALL` | Disponible depuis 2.1.0
imagick.progress_monitor | `false` | `INI_SYSTEM` | Disponible depuis Imagick 2.2.2
imagick.skip_version_check | `false` | `INI_SYSTEM` | Disponible depuis Imagick 3.3.0

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`imagick.locale_fix` bool

  Corrige un bogue sur le dessin lorsque les locales utilisent le caractère '`,`' comme séparateurs.

`imagick.progress_monitor` bool

  Utilisé pour activer la surveillance de la progression de l'image.

`imagick.skip_version_check` bool

  Lorsque Imagick est chargé, le numéro de version d'ImageMagick utilisé pendant la compilation est vérifié, et est comparé avec le numéro de version actuellement utilisé ; une alerte est émise si les deux versions ne correspondent pas. Cette alerte peut être supprimée en activant cette option de configuration.

  Le fait d'utiliser une version d'Imagick différente de la version d'ImageMagick n'est pas recommandé. Malgré le fait que cela peut fonctionner, il peut en résulter des erreurs aléatoires ou des comportements non définis.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Constantes `COLOR_*`

Constantes sur les types de couleur. Ces constantes sont surtout utilisées avec la classe ImagickPixel.

`imagick::COLOR_BLACK` (int)
  Couleur noire
`imagick::COLOR_BLUE` (int)
  Couleur bleue
`imagick::COLOR_CYAN` (int)
  Couleur cyan
`imagick::COLOR_GREEN` (int)
  Couleur verte
`imagick::COLOR_RED` (int)
  Couleur rouge
`imagick::COLOR_YELLOW` (int)
  Couleur jaune
`imagick::COLOR_MAGENTA` (int)
  Couleur magenta
`imagick::COLOR_OPACITY` (int)
  Couleur de l'opacité
`imagick::COLOR_ALPHA` (int)
  Couleur de l'alpha
`imagick::COLOR_FUZZ` (int)
  Couleur du fuzz

Constantes `DISPOSE_*`

Constantes relatives aux types de disposition

`imagick::DISPOSE_UNRECOGNIZED` (int)
  Type de disposition non reconnu
`imagick::DISPOSE_UNDEFINED` (int)
  Type de disposition non défini
`imagick::DISPOSE_NONE` (int)
  Aucun type de disposition
`imagick::DISPOSE_BACKGROUND` (int)
  Disposition du fond
`imagick::DISPOSE_PREVIOUS` (int)
  Disposition précédente

Constantes `COMPOSITE_*`
`imagick::COMPOSITE_DEFAULT` (int)
  L'opérateur de composition par défaut.
`imagick::COMPOSITE_UNDEFINED` (int)
  Opérateur de composition indéfini
`imagick::COMPOSITE_NO` (int)
  Pas d'opérateur de composition défini
`imagick::COMPOSITE_ADD` (int)
  Le résultat d'image + image
`imagick::COMPOSITE_ATOP` (int)
  Le résultat a la même forme que l'image, avec l'image composée qui remplit l'image là où la forme d'image chevauche l'image
`imagick::COMPOSITE_BLEND` (int)
  Combine les images image (blending)
`imagick::COMPOSITE_BUMPMAP` (int)
  La même chose que COMPOSITE_MULTIPLY, hormis le fait que la source est d'abord convertie en niveaux de gris
`imagick::COMPOSITE_CLEAR` (int)
  Rend l'image cible transparente
`imagick::COMPOSITE_COLORBURN` (int)
  Assombrit l'image de destination pour refléter l'image source
`imagick::COMPOSITE_COLORDODGE` (int)
  Éclaire l'image de destination pour refléter l'image source
`imagick::COMPOSITE_COLORIZE` (int)
  Colorie l'image cible avec l'image composée
`imagick::COMPOSITE_COPYBLACK` (int)
  Copie le noir de la source vers la cible
`imagick::COMPOSITE_COPYBLUE` (int)
  Copie le bleu de la source vers la cible
`imagick::COMPOSITE_COPY` (int)
  Copie la source vers la cible
`imagick::COMPOSITE_COPYCYAN` (int)
  Copie le Cyan de la source vers la cible
`imagick::COMPOSITE_COPYGREEN` (int)
  Copie le vert de la source vers la cible
`imagick::COMPOSITE_COPYMAGENTA` (int)
  Copie le magenta de la source vers la cible
`imagick::COMPOSITE_COPYOPACITY` (int)
  Copie l'opacité de la source vers la cible
`imagick::COMPOSITE_COPYRED` (int)
  Copie le rouge de la source vers la cible
`imagick::COMPOSITE_COPYYELLOW` (int)
  Copie le jaune de la source vers la cible
`imagick::COMPOSITE_DARKEN` (int)
  Assombrit l'image cible
`imagick::COMPOSITE_DSTATOP` (int)
  La partie de l'image de destination qui est à l'intérieur de la source est composée avec la source, et placée dans la destination.
`imagick::COMPOSITE_DST` (int)
  La cible est laissée intacte
`imagick::COMPOSITE_DSTIN` (int)
  La partie à l'intérieur de la source remplace la cible
`imagick::COMPOSITE_DSTOUT` (int)
  La partie à l'extérieur de la source remplace la cible
`imagick::COMPOSITE_DSTOVER` (int)
  La cible remplace la source
`imagick::COMPOSITE_DIFFERENCE` (int)
  Soustrait la couleur sombre de la couleur claire
`imagick::COMPOSITE_DISPLACE` (int)
  Décale les pixels de la cible tel que défini par la source
`imagick::COMPOSITE_DISSOLVE` (int)
  Dissout la source dans la cible
`imagick::COMPOSITE_EXCLUSION` (int)
  Produit un effet similaire à imagick::COMPOSITE_DIFFERENCE, mais avec un contraste plus faible
`imagick::COMPOSITE_HARDLIGHT` (int)
  Multiplie ou superpose les couleurs, selon la valeur de la couleur source
`imagick::COMPOSITE_HUE` (int)
  Modifie la teinte de la cible, tel que défini par la source
`imagick::COMPOSITE_IN` (int)
  Compose la source dans la cible
`imagick::COMPOSITE_LIGHTEN` (int)
  Éclaircit la cible, tel que défini par la source
`imagick::COMPOSITE_LUMINIZE` (int)
  Illumine la cible tel que défini par la source
`imagick::COMPOSITE_MINUS` (int)
  Soustrait la source de la cible
`imagick::COMPOSITE_MODULATE` (int)
  Module la clarté de la cible, sa saturation et sa teinte tel que défini par la source
`imagick::COMPOSITE_MULTIPLY` (int)
  Multiplie la cible avec la source
`imagick::COMPOSITE_OUT` (int)
  Compose l'extérieur de la source dans la cible
`imagick::COMPOSITE_OVER` (int)
  Compose la source sur la cible
`imagick::COMPOSITE_OVERLAY` (int)
  Surimprime la source sur la cible
`imagick::COMPOSITE_PLUS` (int)
  Ajoute la source sur la cible
`imagick::COMPOSITE_REPLACE` (int)
  Remplace la cible avec la source
`imagick::COMPOSITE_SATURATE` (int)
  Sature la cible tel que défini par la source
`imagick::COMPOSITE_SCREEN` (int)
  La source et la cible sont complétées puis multipliées et finalement elles remplacent la cible
`imagick::COMPOSITE_SOFTLIGHT` (int)
  Assombrit ou éclaire les couleurs, en fonction de la source
`imagick::COMPOSITE_SRCATOP` (int)
  La partie de la source qui est dans la cible est composée sur la cible
`imagick::COMPOSITE_SRC` (int)
  La source est copiée sur la destination
`imagick::COMPOSITE_SRCIN` (int)
  La partie de la source qui est dans la destination, remplace la destination.
`imagick::COMPOSITE_SRCOUT` (int)
  La partie de la source qui est hors de la destination remplace la destination
`imagick::COMPOSITE_SRCOVER` (int)
  La source remplace la cible
`imagick::COMPOSITE_SUBTRACT` (int)
  Soustrait les couleurs de la source de celles de la cible
`imagick::COMPOSITE_THRESHOLD` (int)
  La source est composée sur la cible, tel que défini par les seuils de la source
`imagick::COMPOSITE_XOR` (int)
  La partie de la source qui est hors de la destination et combinée avec la partie de la destination qui est hors de la source

Constantes `MONTAGEMODE_*`

`imagick::MONTAGEMODE_FRAME` (int)
`imagick::MONTAGEMODE_UNFRAME` (int)
`imagick::MONTAGEMODE_CONCATENATE` (int)

Constantes `STYLE_*`

`imagick::STYLE_NORMAL` (int)
`imagick::STYLE_ITALIC` (int)
`imagick::STYLE_OBLIQUE` (int)
`imagick::STYLE_ANY` (int)

Constantes `FILTER_*`

`imagick::FILTER_UNDEFINED` (int)
`imagick::FILTER_POINT` (int)
`imagick::FILTER_BOX` (int)
`imagick::FILTER_TRIANGLE` (int)
`imagick::FILTER_HERMITE` (int)
`imagick::FILTER_HANNING` (int)
`imagick::FILTER_HAMMING` (int)
`imagick::FILTER_BLACKMAN` (int)
`imagick::FILTER_GAUSSIAN` (int)
`imagick::FILTER_QUADRATIC` (int)
`imagick::FILTER_CUBIC` (int)
`imagick::FILTER_CATROM` (int)
`imagick::FILTER_MITCHELL` (int)
`imagick::FILTER_LANCZOS` (int)
`imagick::FILTER_BESSEL` (int)
`imagick::FILTER_SINC` (int)

Constantes `IMGTYPE_*`

`imagick::IMGTYPE_UNDEFINED` (int)
`imagick::IMGTYPE_BILEVEL` (int)
`imagick::IMGTYPE_GRAYSCALE` (int)
`imagick::IMGTYPE_GRAYSCALEMATTE` (int)
`imagick::IMGTYPE_PALETTE` (int)
`imagick::IMGTYPE_PALETTEMATTE` (int)
`imagick::IMGTYPE_TRUECOLOR` (int)
`imagick::IMGTYPE_TRUECOLORMATTE` (int)
`imagick::IMGTYPE_COLORSEPARATION` (int)
`imagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`imagick::IMGTYPE_OPTIMIZE` (int)

Constantes `RESOLUTION_*`

`imagick::RESOLUTION_UNDEFINED` (int)
`imagick::RESOLUTION_PIXELSPERINCH` (int)
`imagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

Constantes `COMPRESSION_*`

`imagick::COMPRESSION_UNDEFINED` (int)
`imagick::COMPRESSION_NO` (int)
`imagick::COMPRESSION_BZIP` (int)
`imagick::COMPRESSION_FAX` (int)
`imagick::COMPRESSION_GROUP4` (int)
`imagick::COMPRESSION_JPEG` (int)
`imagick::COMPRESSION_JPEG2000` (int)
`imagick::COMPRESSION_LOSSLESSJPEG` (int)
`imagick::COMPRESSION_LZW` (int)
`imagick::COMPRESSION_RLE` (int)
`imagick::COMPRESSION_ZIP` (int)
`imagick::COMPRESSION_DXT1` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.0 ou supérieur.
`imagick::COMPRESSION_DXT3` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.0 ou supérieur.
`imagick::COMPRESSION_DXT5` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.0 ou supérieur.

Constantes `PAINT_*`

`imagick::PAINT_POINT` (int)
`imagick::PAINT_REPLACE` (int)
`imagick::PAINT_FLOODFILL` (int)
`imagick::PAINT_FILLTOBORDER` (int)
`imagick::PAINT_RESET` (int)

Constantes `GRAVITY_*`

`imagick::GRAVITY_NORTHWEST` (int)
`imagick::GRAVITY_NORTH` (int)
`imagick::GRAVITY_NORTHEAST` (int)
`imagick::GRAVITY_WEST` (int)
`imagick::GRAVITY_CENTER` (int)
`imagick::GRAVITY_EAST` (int)
`imagick::GRAVITY_SOUTHWEST` (int)
`imagick::GRAVITY_SOUTH` (int)
`imagick::GRAVITY_SOUTHEAST` (int)

Constantes `STRETCH_*`

`imagick::STRETCH_NORMAL` (int)
`imagick::STRETCH_ULTRACONDENSED` (int)
`imagick::STRETCH_CONDENSED` (int)
`imagick::STRETCH_SEMICONDENSED` (int)
`imagick::STRETCH_SEMIEXPANDED` (int)
`imagick::STRETCH_EXPANDED` (int)
`imagick::STRETCH_EXTRAEXPANDED` (int)
`imagick::STRETCH_ULTRAEXPANDED` (int)
`imagick::STRETCH_ANY` (int)

Constantes `ALIGN_*`

`imagick::ALIGN_UNDEFINED` (int)
`imagick::ALIGN_LEFT` (int)
`imagick::ALIGN_CENTER` (int)
`imagick::ALIGN_RIGHT` (int)

Constantes `DECORATION_*`

`imagick::DECORATION_NO` (int)
`imagick::DECORATION_UNDERLINE` (int)
`imagick::DECORATION_OVERLINE` (int)
`imagick::DECORATION_LINETROUGH` (int)

Constantes `NOISE_*`

`imagick::NOISE_UNIFORM` (int)
`imagick::NOISE_GAUSSIAN` (int)
`imagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`imagick::NOISE_IMPULSE` (int)
`imagick::NOISE_LAPLACIAN` (int)
`imagick::NOISE_POISSON` (int)
`imagick::NOISE_RANDOM` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

Constantes `CHANNEL_*`

`imagick::CHANNEL_UNDEFINED` (int)
`imagick::CHANNEL_RED` (int)
`imagick::CHANNEL_GRAY` (int)
`imagick::CHANNEL_CYAN` (int)
`imagick::CHANNEL_GREEN` (int)
`imagick::CHANNEL_MAGENTA` (int)
`imagick::CHANNEL_BLUE` (int)
`imagick::CHANNEL_YELLOW` (int)
`imagick::CHANNEL_ALPHA` (int)
`imagick::CHANNEL_OPACITY` (int)
`imagick::CHANNEL_MATTE` (int)
`imagick::CHANNEL_BLACK` (int)
`imagick::CHANNEL_INDEX` (int)
`imagick::CHANNEL_ALL` (int)
`imagick::CHANNEL_DEFAULT` (int)

Constantes `METRIC_*`

`imagick::METRIC_UNDEFINED` (int)
`imagick::METRIC_MEANABSOLUTEERROR` (int)
`imagick::METRIC_MEANSQUAREERROR` (int)
`imagick::METRIC_PEAKABSOLUTEERROR` (int)
`imagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`imagick::METRIC_ROOTMEANSQUAREDERROR` (int)

Constantes `PIXEL_*`

`imagick::PIXEL_CHAR` (int)
`imagick::PIXEL_DOUBLE` (int)
`imagick::PIXEL_FLOAT` (int)
`imagick::PIXEL_INTEGER` (int)
  Seulement disponible avec ImageMagick < 7.
`imagick::PIXEL_LONG` (int)
`imagick::PIXEL_QUANTUM` (int)
`imagick::PIXEL_SHORT` (int)

Constantes `EVALUATE_*`

`imagick::EVALUATE_UNDEFINED` (int)
`imagick::EVALUATE_ADD` (int)
`imagick::EVALUATE_AND` (int)
`imagick::EVALUATE_DIVIDE` (int)
`imagick::EVALUATE_LEFTSHIFT` (int)
`imagick::EVALUATE_MAX` (int)
`imagick::EVALUATE_MIN` (int)
`imagick::EVALUATE_MULTIPLY` (int)
`imagick::EVALUATE_OR` (int)
`imagick::EVALUATE_RIGHTSHIFT` (int)
`imagick::EVALUATE_SET` (int)
`imagick::EVALUATE_SUBTRACT` (int)
`imagick::EVALUATE_XOR` (int)
`imagick::EVALUATE_POW` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_LOG` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_THRESHOLD` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_THRESHOLDBLACK` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_THRESHOLDWHITE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_GAUSSIANNOISE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_IMPULSENOISE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_LAPLACIANNOISE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_MULTIPLICATIVENOISE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_POISSONNOISE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_UNIFORMNOISE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_COSINE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_SINE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.
`imagick::EVALUATE_ADDMODULUS` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.

Constantes `COLORSPACE_*`

`imagick::COLORSPACE_UNDEFINED` (int)
`imagick::COLORSPACE_RGB` (int)
`imagick::COLORSPACE_GRAY` (int)
`imagick::COLORSPACE_TRANSPARENT` (int)
`imagick::COLORSPACE_OHTA` (int)
`imagick::COLORSPACE_LAB` (int)
`imagick::COLORSPACE_XYZ` (int)
`imagick::COLORSPACE_YCBCR` (int)
`imagick::COLORSPACE_YCC` (int)
`imagick::COLORSPACE_YIQ` (int)
`imagick::COLORSPACE_YPBPR` (int)
`imagick::COLORSPACE_YUV` (int)
`imagick::COLORSPACE_CMYK` (int)
`imagick::COLORSPACE_SRGB` (int)
`imagick::COLORSPACE_HSB` (int)
`imagick::COLORSPACE_HSL` (int)
`imagick::COLORSPACE_HWB` (int)
`imagick::COLORSPACE_REC601LUMA` (int)
`imagick::COLORSPACE_REC709LUMA` (int)
`imagick::COLORSPACE_LOG` (int)
`imagick::COLORSPACE_CMY` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.2 ou supérieur.

Constantes `VIRTUALPIXELMETHOD_*`

`imagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`imagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`imagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`imagick::VIRTUALPIXELMETHOD_EDGE` (int)
`imagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`imagick::VIRTUALPIXELMETHOD_TILE` (int)
`imagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)
`imagick::VIRTUALPIXELMETHOD_MASK` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.2 ou supérieur.
`imagick::VIRTUALPIXELMETHOD_BLACK` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.2 ou supérieur.
`imagick::VIRTUALPIXELMETHOD_GRAY` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.2 ou supérieur.
`imagick::VIRTUALPIXELMETHOD_WHITE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.2 ou supérieur.
`imagick::VIRTUALPIXELMETHOD_HORIZONTALTILE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.3 ou supérieur.
`imagick::VIRTUALPIXELMETHOD_VERTICALTILE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.3 ou supérieur.

Constantes `PREVIEW_*`

`imagick::PREVIEW_UNDEFINED` (int)
`imagick::PREVIEW_ROTATE` (int)
`imagick::PREVIEW_SHEAR` (int)
`imagick::PREVIEW_ROLL` (int)
`imagick::PREVIEW_HUE` (int)
`imagick::PREVIEW_SATURATION` (int)
`imagick::PREVIEW_BRIGHTNESS` (int)
`imagick::PREVIEW_GAMMA` (int)
`imagick::PREVIEW_SPIFF` (int)
`imagick::PREVIEW_DULL` (int)
`imagick::PREVIEW_GRAYSCALE` (int)
`imagick::PREVIEW_QUANTIZE` (int)
`imagick::PREVIEW_DESPECKLE` (int)
`imagick::PREVIEW_REDUCENOISE` (int)
`imagick::PREVIEW_ADDNOISE` (int)
`imagick::PREVIEW_SHARPEN` (int)
`imagick::PREVIEW_BLUR` (int)
`imagick::PREVIEW_THRESHOLD` (int)
`imagick::PREVIEW_EDGEDETECT` (int)
`imagick::PREVIEW_SPREAD` (int)
`imagick::PREVIEW_SOLARIZE` (int)
`imagick::PREVIEW_SHADE` (int)
`imagick::PREVIEW_RAISE` (int)
`imagick::PREVIEW_SEGMENT` (int)
`imagick::PREVIEW_SWIRL` (int)
`imagick::PREVIEW_IMPLODE` (int)
`imagick::PREVIEW_WAVE` (int)
`imagick::PREVIEW_OILPAINT` (int)
`imagick::PREVIEW_CHARCOALDRAWING` (int)
`imagick::PREVIEW_JPEG` (int)

Constantes `RENDERINGINTENT_*`

`imagick::RENDERINGINTENT_UNDEFINED` (int)
`imagick::RENDERINGINTENT_SATURATION` (int)
`imagick::RENDERINGINTENT_PERCEPTUAL` (int)
`imagick::RENDERINGINTENT_ABSOLUTE` (int)
`imagick::RENDERINGINTENT_RELATIVE` (int)

Constantes `INTERLACE_*`

`imagick::INTERLACE_UNDEFINED` (int)
`imagick::INTERLACE_NO` (int)
`imagick::INTERLACE_LINE` (int)
`imagick::INTERLACE_PLANE` (int)
`imagick::INTERLACE_PARTITION` (int)
`imagick::INTERLACE_GIF` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.4 ou supérieur.
`imagick::INTERLACE_JPEG` (int)
`imagick::INTERLACE_PNG` (int)

Constantes `FILLRULE_*`

`imagick::FILLRULE_UNDEFINED` (int)
`imagick::FILLRULE_EVENODD` (int)
`imagick::FILLRULE_NONZERO` (int)

Constantes `PATHUNITS_*`

`imagick::PATHUNITS_UNDEFINED` (int)
`imagick::PATHUNITS_USERSPACE` (int)
`imagick::PATHUNITS_USERSPACEONUSE` (int)
`imagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

Constantes `LINECAP_*`

`imagick::LINECAP_UNDEFINED` (int)
`imagick::LINECAP_BUTT` (int)
`imagick::LINECAP_ROUND` (int)
`imagick::LINECAP_SQUARE` (int)

Constantes `LINEJOIN_*`

`imagick::LINEJOIN_UNDEFINED` (int)
`imagick::LINEJOIN_MITER` (int)
`imagick::LINEJOIN_ROUND` (int)
`imagick::LINEJOIN_BEVEL` (int)

Constantes `RESOURCETYPE_*`

`imagick::RESOURCETYPE_UNDEFINED` (int)
`imagick::RESOURCETYPE_AREA` (int)
  Définit la largeur et la hauteur maximales d'une image qui peut être mise dans la mémoire cache des pixels.
`imagick::RESOURCETYPE_DISK` (int)
  Définit la taille maximale de l'espace disque autorisée à stocker le cache des pixels.
`imagick::RESOURCETYPE_FILE` (int)
  Définit le nombre maximal de fichiers de cache de pixels ouverts.
`imagick::RESOURCETYPE_MAP` (int)
  Définit la taille maximale de mémoire en octets, à allouer au cache de pixels.
`imagick::RESOURCETYPE_MEMORY` (int)
  Définit la taille maximale de la mémoire, en octets, à allouer au cache de pixels.
`imagick::RESOURCETYPE_THREAD` (int)
  Définit le nombre maximal de threads parallèles. Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.7.8 ou supérieur.

Constantes `LAYERMETHOD_*`

`imagick::LAYERMETHOD_UNDEFINED` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.
`imagick::LAYERMETHOD_COALESCE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.
`imagick::LAYERMETHOD_COMPAREANY` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.
`imagick::LAYERMETHOD_COMPARECLEAR` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.
`imagick::LAYERMETHOD_COMPAREOVERLAY` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.
`imagick::LAYERMETHOD_DISPOSE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.
`imagick::LAYERMETHOD_OPTIMIZE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.
`imagick::LAYERMETHOD_OPTIMIZEPLUS` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.
`imagick::LAYERMETHOD_OPTIMIZEIMAGE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::LAYERMETHOD_OPTIMIZETRANS` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::LAYERMETHOD_REMOVEDUPS` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::LAYERMETHOD_REMOVEZERO` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::LAYERMETHOD_COMPOSITE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::LAYERMETHOD_MERGE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.7 ou supérieur.
`imagick::LAYERMETHOD_FLATTEN` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.7 ou supérieur.
`imagick::LAYERMETHOD_MOSAIC` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.7 ou supérieur.

Constantes `ORIENTATION_*`

`imagick::ORIENTATION_UNDEFINED` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::ORIENTATION_TOPLEFT` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::ORIENTATION_TOPRIGHT` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::ORIENTATION_BOTTOMRIGHT` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::ORIENTATION_BOTTOMLEFT` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::ORIENTATION_LEFTTOP` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::ORIENTATION_RIGHTTOP` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::ORIENTATION_RIGHTBOTTOM` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.
`imagick::ORIENTATION_LEFTBOTTOM` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.0 ou supérieur.

Constantes `DISTORTION_*`

`imagick::DISTORTION_UNDEFINED` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.
`imagick::DISTORTION_AFFINE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.
`imagick::DISTORTION_AFFINEPROJECTION` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.
`imagick::DISTORTION_ARC` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.
`imagick::DISTORTION_BILINEAR` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.
`imagick::DISTORTION_PERSPECTIVE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.
`imagick::DISTORTION_PERSPECTIVEPROJECTION` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.
`imagick::DISTORTION_SCALEROTATETRANSLATE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.
`imagick::DISTORTION_POLYNOMIAL` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::DISTORTION_POLAR` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::DISTORTION_DEPOLAR` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::DISTORTION_BARREL` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::DISTORTION_BARRELINVERSE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::DISTORTION_SHEPARDS` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::DISTORTION_SENTINEL` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.

Constantes `ALPHACHANNEL_*`

`imagick::ALPHACHANNEL_ACTIVATE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.8 ou supérieur.
`imagick::ALPHACHANNEL_DEACTIVATE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.8 ou supérieur.
`imagick::ALPHACHANNEL_RESET` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.8 ou supérieur.
`imagick::ALPHACHANNEL_SET` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.8 ou supérieur.
`imagick::ALPHACHANNEL_UNDEFINED` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::ALPHACHANNEL_COPY` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::ALPHACHANNEL_EXTRACT` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::ALPHACHANNEL_OPAQUE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::ALPHACHANNEL_SHAPE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::ALPHACHANNEL_TRANSPARENT` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::ALPHACHANNEL_BACKGROUND` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.5.3 ou supérieur.
`imagick::ALPHACHANNEL_REMOVE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.7.8 ou supérieur.
`imagick::ALPHACHANNEL_ASSOCIATE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.9.0 ou supérieur.
`imagick::ALPHACHANNEL_DISSOCIATE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.9.0 ou supérieur.
`imagick::ALPHACHANNEL_ON` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 7.0.0 ou supérieur.
`imagick::ALPHACHANNEL_OFF` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 7.0.0 ou supérieur.
`imagick::ALPHACHANNEL_DISCRETE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 7.0.0 ou supérieur.

Constantes `SPARSECOLORMETHOD_*`

`imagick::SPARSECOLORMETHOD_UNDEFINED` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::SPARSECOLORMETHOD_BARYCENTRIC` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::SPARSECOLORMETHOD_BILINEAR` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::SPARSECOLORMETHOD_POLYNOMIAL` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::SPARSECOLORMETHOD_SPEPARDS` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::SPARSECOLORMETHOD_VORONOI` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.

Constantes `FUNCTION_*`

`imagick::FUNCTION_UNDEFINED` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.9 ou supérieur.
`imagick::FUNCTION_POLYNOMIAL` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.9 ou supérieur.
`imagick::FUNCTION_SINUSOID` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.9 ou supérieur.

Constantes `INTERPOLATE_*`

`imagick::INTERPOLATE_UNDEFINED` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.
`imagick::INTERPOLATE_AVERAGE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.
`imagick::INTERPOLATE_BICUBIC` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.
`imagick::INTERPOLATE_BILINEAR` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.
`imagick::INTERPOLATE_FILTER` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.
`imagick::INTERPOLATE_INTEGER` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.
`imagick::INTERPOLATE_MESH` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.
`imagick::INTERPOLATE_NEARESTNEIGHBOR` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.
`imagick::INTERPOLATE_SPLINE` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.4 ou supérieur.

Constantes `DITHERMETHOD_*`

`imagick::DITHERMETHOD_UNDEFINED` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::DITHERMETHOD_NO` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::DITHERMETHOD_RIEMERSMA` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.
`imagick::DITHERMETHOD_FLOYDSTEINBERG` (int)
  Cette constante n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.6 ou supérieur.

# Exemples

## Sommaire

- Utilisation simple

## Utilisation simple

Imagick rend la manipulation des images via PHP extrêmement facile grâce à une interface orientée objet. Voici un exemple rapide illustrant la création d'une miniature :

Exemple #1 Création d'une miniature avec Imagick

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('image.jpg');

    // Si 0 est fourni comme paramètre de hauteur ou de largeur,
    // les proportions seront conservées
    $image->thumbnailImage(100, 0);

    echo $image;

    ?>

En utilisant SPL ou toute autre fonctionnalité orientée objet supportée par Imagick, il devient simple de redimensionner tous les fichiers d'un dossier (utile pour des scripts batch redimensionnant des images issues d'un appareil photo numérique afin de les rendre lisibles sur le web). Voici un exemple de redimensionnement de toutes les images JPG d'un dossier, tout en conservant les métadonnées :

Exemple #2 Création de miniature de toutes les images JPG d'un dossier

    <?php

    $images = new Imagick(glob('images/*.JPG'));

    foreach($images as $image) {

        // On fournit 0 en guise de paramètre afin de conserver les proportions
        $image->thumbnailImage(1024,0);

    }

    $images->writeImages();

    ?>

Voici un exemple permettant de créer le reflet d'une image. Ce reflet est créé en retournant l'image et en y ajoutant un dégradé. Ensuite, l'image originale et son reflet sont ajoutés dans une nouvelle image.

Exemple #3 Création d'un reflet sur une image

    <?php
    /* Lecture de l'image */
    $im = new Imagick("test.png");

    /* Création d'une miniature de l'image */
    $im->thumbnailImage(200, null);

    /* Création d'une bordure */
    $im->borderImage(new ImagickPixel("white"), 5, 5);

    /* Clône l'image et on la retourne */
    $reflection = $im->clone();
    $reflection->flipImage();

    /* Création du dégradé. Il sera ajouté à l'image retournée */
    $gradient = new Imagick();

    /* Le dégradé doit être assez large pour l'image et ses bordures */
    $gradient->newPseudoImage($reflection->getImageWidth() + 10, $reflection->getImageHeight() + 10, "gradient:transparent-black");

    /* Ajout du dégradé sur l'image retournée */
    $reflection->compositeImage($gradient, imagick::COMPOSITE_OVER, 0, 0);

    /* Ajout d'un peu d'opacité. Nécessite ImageMagick 6.2.9 ou supérieur */
    $reflection->setImageOpacity( 0.3 );

    /* Création d'une image vide */
    $canvas = new Imagick();

    /* L'image vide doit être assez large pour contenir les 2 images */
    $width = $im->getImageWidth() + 40;
    $height = ($im->getImageHeight() * 2) + 30;
    $canvas->newImage($width, $height, new ImagickPixel("black"));
    $canvas->setImageFormat("png");

    /* Ajout de l'image originale et de l'image retournée dans notre nouvelle image */
    $canvas->compositeImage($im, imagick::COMPOSITE_OVER, 20, 10);
    $canvas->compositeImage($reflection, imagick::COMPOSITE_OVER, 20, $im->getImageHeight() + 10);

    /* Affichage de l'image */
    header("Content-Type: image/png");
    echo $canvas;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Voici un exemple montrant comment remplir un masque lors du dessin de l'image.

Exemple #4 Remplissage d'un texte avec un dégradé

    <?php

    /* Création d'un nouvel objet imagick */
    $im = new Imagick();

    /* Création d'une nouvelle image. Elle sera utilisée comme masque de remplissage */
    $im->newPseudoImage(50, 50, "gradient:red-black");

    /* Création d'un nouvel objet imagickdraw */
    $draw = new ImagickDraw();

    /* On commence un nouveau masque nommé "gradient" */
    $draw->pushPattern('gradient', 0, 0, 50, 50);

    /* Ajout du dégradé sur le masque */
    $draw->composite(Imagick::COMPOSITE_OVER, 0, 0, 50, 50, $im);

    /* Fermeture du masque */
    $draw->popPattern();

    /* Utilisation du masque nommé "gradient" comme remplissage */
    $draw->setFillPatternURL('#gradient');

    /* Définition de la taille du texte à 52 */
    $draw->setFontSize(52);

    /* Ajout d'un texte */
    $draw->annotation(20, 50, "Bonjour le monde !");

    /* Création d'un nouvel objet et d'une image blanche */
    $canvas = new Imagick();
    $canvas->newImage(350, 70, "white");

    /* Dessine le ImagickDraw sur la nouvelle image */
    $canvas->drawImage($draw);

    /* Une bordure noire d'un pixel autour de l'image */
    $canvas->borderImage('black', 1, 1);

    /* Définition du format à PNG */
    $canvas->setImageFormat('png');

    /* Affiche l'image */
    header("Content-Type: image/png");
    echo $canvas;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Exemple avec des images GIF animées

Exemple #5 Lit une image GIF et redimensionne toutes les frames

    <?php

    /* Crée un nouvel objet imagick et lit une image GIF */
    $im = new Imagick("example.gif");

    /* Redimensionne toutes les frames */
    foreach ($im as $frame) {
        /* 50x50 frames */
        $frame->thumbnailImage(50, 50);

        /* Définit le canevas virtuel à la bonne taille */
        $frame->setImagePage(50, 50, 0, 0);
    }

    /* Notez l'utilisation de writeImages au lieu de writeImage */
    $im->writeImages("example_small.gif", true);
    ?>

Exemple avec des ellipses primitives et des polices personnalisées

Exemple #6 Création d'un logo PHP

    <?php
    /* Définit la largeur et la hauteur en proportion du logo PHP */
    $width = 400;
    $height = 210;

    /* Crée un objet Imagick avec une toile transparente */
    $img = new Imagick();
    $img->newImage($width, $height, new ImagickPixel('transparent'));

    /* Nouvelle instance ImagickDraw pour dessiner l'ellipse */
    $draw = new ImagickDraw();
    /* Définit la couleur violette pour remplir l'ellipse */
    $draw->setFillColor('#777bb4');
    /* Définit les dimensions de l'ellipse */
    $draw->ellipse($width / 2, $height / 2, $width / 2, $height / 2, 0, 360);
    /* Dessine l'ellipse dans la toile */
    $img->drawImage($draw);

    /* Réinitialise la couleur de remplissage, passant du violet au noir pour le texte (note : nous ré-utilisons l'objet ImagickDraw) */
    $draw->setFillColor('black');
    /* Définit à blanc la couleur du trait de la bordure */
    $draw->setStrokeColor('white');
    /* Rend plus fin le trait de la bordure */
    $draw->setStrokeWidth(2);
    /* Définit le crénage de la police (une valeur négative signifie que les lettres sont proches les unes des autres) */
    $draw->setTextKerning(-8);
    /* Définit la police et sa taille à utiliser dans le logo PHP */
    $draw->setFont('Handel Gothic.ttf');
    $draw->setFontSize(150);
    /* On centre le texte horizontalement et verticalement */
    $draw->setGravity(Imagick::GRAVITY_CENTER);

    /* Ajout de "php" au centre, avec une position en Y de -10 dans la toile (à l'intérieur de l'ellipse) */
    $img->annotateImage($draw, 0, -10, 0, 'php');
    $img->setImageFormat('png');

    /* On définit l'en-tête approprié pour le PNG et on affiche l'image */
    header('Content-Type: image/png');
    echo $img;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# La classe Imagick

(PECL imagick 2, PECL imagick 3)

## Synopsis de la classe

class Imagick implements Iterator {
public function __construct(mixed `$files` = ?)
public function adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool
public function addImage(Imagick `$source`): bool
public function addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function affineTransformImage(ImagickDraw `$matrix`): bool
public function animateImages(string `$x_server`): bool
public function annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool
public function appendImages(bool `$stack`): Imagick
public function autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function averageImages(): Imagick
public function blackThresholdImage(mixed `$threshold`): bool
public function blueShiftImage(float `$factor` = 1.5): bool
public function blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool
public function borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool
public function brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function charcoalImage(float `$radius`, float `$sigma`): bool
public function chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function clear(): bool
public function clipImage(): bool
public function clipImagePath(string `$pathname`, string `$inside`): void
public function clipPathImage(string `$pathname`, bool `$inside`): bool
public function clone(): Imagick
public function clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function coalesceImages(): Imagick
public function colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function colorMatrixImage(array `$color_matrix`): bool
public function combineImages(int `$channelType`): Imagick
public function commentImage(string `$comment`): bool
public function compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array
public function compareImageLayers(int `$method`): Imagick
public function compareImages(Imagick `$compare`, int `$metric`): array
public function compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function contrastImage(bool `$sharpen`): bool
public function contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function count(int `$mode` = 0): int
public function cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool
public function current(): Imagick
public function cycleColormapImage(int `$displace`): bool
public function decipherImage(string `$passphrase`): bool
public function deconstructImages(): Imagick
public function deleteImageArtifact(string `$artifact`): bool
public function deleteImageProperty(string `$name`): bool
public function deskewImage(float `$threshold`): bool
public function despeckleImage(): bool
public function destroy(): bool
public function displayImage(string `$servername`): bool
public function displayImages(string `$servername`): bool
public function distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool
public function drawImage(ImagickDraw `$draw`): bool
public function edgeImage(float `$radius`): bool
public function embossImage(float `$radius`, float `$sigma`): bool
public function encipherImage(string `$passphrase`): bool
public function enhanceImage(): bool
public function equalizeImage(): bool
public function evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array
public function extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool
public function flattenImages(): Imagick
public function flipImage(): bool
public function floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function flopImage(): bool
public function forwardFourierTransformimage(bool `$magnitude`): bool
public function frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool
public function functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick
public function gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function getColorspace(): int
public function getCompression(): int
public function getCompressionQuality(): int
public static function getCopyright(): string
public function getFilename(): string
public function getFont(): string
public function getFormat(): string
public function getGravity(): int
public static function getHomeURL(): string
public function getImage(): Imagick
public function getImageAlphaChannel(): bool
public function getImageArtifact(string `$artifact`): string
public function getImageAttribute(string `$key`): string
public function getImageBackgroundColor(): ImagickPixel
public function getImageBlob(): string
public function getImageBluePrimary(): array
public function getImageBorderColor(): ImagickPixel
public function getImageChannelDepth(int `$channel`): int
public function getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float
public function getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float
public function getImageChannelExtrema(int `$channel`): array
public function getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array
public function getImageChannelMean(int `$channel`): array
public function getImageChannelRange(int `$channel`): array
public function getImageChannelStatistics(): array
public function getImageClipMask(): Imagick
public function getImageColormapColor(int `$index`): ImagickPixel
public function getImageColors(): int
public function getImageColorspace(): int
public function getImageCompose(): int
public function getImageCompression(): int
public function getImageCompressionQuality(): int
public function getImageDelay(): int
public function getImageDepth(): int
public function getImageDispose(): int
public function getImageDistortion(MagickWand `$reference`, int `$metric`): float
public function getImageExtrema(): array
public function getImageFilename(): string
public function getImageFormat(): string
public function getImageGamma(): float
public function getImageGeometry(): array
public function getImageGravity(): int
public function getImageGreenPrimary(): array
public function getImageHeight(): int
public function getImageHistogram(): array
public function getImageIndex(): int
public function getImageInterlaceScheme(): int
public function getImageInterpolateMethod(): int
public function getImageIterations(): int
public function getImageLength(): int
public function getImageMatte(): bool
public function getImageMatteColor(): ImagickPixel
public function getImageMimeType(): string
public function getImageOrientation(): int
public function getImagePage(): array
public function getImagePixelColor(int `$x`, int `$y`): ImagickPixel
public function getImageProfile(string `$name`): string
public function getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperty(string `$name`): string
public function getImageRedPrimary(): array
public function getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick
public function getImageRenderingIntent(): int
public function getImageResolution(): array
public function getImagesBlob(): string
public function getImageScene(): int
public function getImageSignature(): string
public function getImageSize(): int
public function getImageTicksPerSecond(): int
public function getImageTotalInkDensity(): float
public function getImageType(): int
public function getImageUnits(): int
public function getImageVirtualPixelMethod(): int
public function getImageWhitePoint(): array
public function getImageWidth(): int
public function getInterlaceScheme(): int
public function getIteratorIndex(): int
public function getNumberImages(): int
public function getOption(string `$key`): string
public static function getPackageName(): string
public function getPage(): array
public function getPixelIterator(): ImagickPixelIterator
public function getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator
public function getPointSize(): float
public static function getQuantum(): int
public static function getQuantumDepth(): array
public static function getQuantumRange(): array
public static function getRegistry(string `$key`): string
public static function getReleaseDate(): string
public static function getResource(int `$type`): int
public static function getResourceLimit(int `$type`): int
public function getSamplingFactors(): array
public function getSize(): array
public function getSizeOffset(): int
public static function getVersion(): array
public function haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function hasNextImage(): bool
public function hasPreviousImage(): bool
public function identifyFormat(string `$embedText`): string|false
public function identifyImage(bool `$appendRawOutput` = `false`): array
public function implodeImage(float `$radius`): bool
public function importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool
public function inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool
public function labelImage(string `$label`): bool
public function levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool
public function liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool
public static function listRegistry(): array
public function magnifyImage(): bool
public function mapImage(Imagick `$map`, bool `$dither`): bool
public function matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function medianFilterImage(float `$radius`): bool
public function mergeImageLayers(int `$layer_method`): Imagick
public function minifyImage(): bool
public function modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool
public function montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick
public function morphImages(int `$number_frames`): Imagick
public function morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function mosaicImages(): Imagick
public function motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool
public function newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool
public function nextImage(): bool
public function normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function oilPaintImage(float `$radius`): bool
public function opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function optimizeImageLayers(): bool
public function orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool
public function pingImage(string `$filename`): bool
public function pingImageBlob(string `$image`): bool
public function pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool
public function polaroidImage(ImagickDraw `$properties`, float `$angle`): bool
public function posterizeImage(int `$levels`, bool `$dither`): bool
public function previewImages(int `$preview`): bool
public function previousImage(): bool
public function profileImage(string `$name`, string `$profile` = ?): bool
public function quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array
public static function queryFonts(string `$pattern` = "*"): array
public static function queryFormats(string `$pattern` = "*"): array
public function radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool
public function randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function readImage(string `$filename`): bool
public function readImageBlob(string `$image`, string `$filename` = ?): bool
public function readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool
public function readImages(array `$filenames`): bool
public function recolorImage(array `$matrix`): bool
public function reduceNoiseImage(float `$radius`): bool
public function remapImage(Imagick `$replacement`, int `$DITHER`): bool
public function removeImage(): bool
public function removeImageProfile(string `$name`): string
public function render(): bool
public function resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool
public function resetImagePage(string `$page`): bool
public function resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function rollImage(int `$x`, int `$y`): bool
public function rotateImage(mixed `$background`, float `$degrees`): bool
public function rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool
public function sampleImage(int `$columns`, int `$rows`): bool
public function scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool
public function selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function separateImageChannel(int `$channel`): bool
public function sepiaToneImage(float `$threshold`): bool
public function setBackgroundColor(mixed `$background`): bool
public function setColorspace(int `$COLORSPACE`): bool
public function setCompression(int `$compression`): bool
public function setCompressionQuality(int `$quality`): bool
public function setFilename(string `$filename`): bool
public function setFirstIterator(): bool
public function setFont(string `$font`): bool
public function setFormat(string `$format`): bool
public function setGravity(int `$gravity`): bool
public function setImage(Imagick `$replace`): bool
public function setImageAlphaChannel(int `$mode`): bool
public function setImageArtifact(string `$artifact`, string `$value`): bool
public function setImageAttribute(string `$key`, string `$value`): bool
public function setImageBackgroundColor(mixed `$background`): bool
public function setImageBias(float `$bias`): bool
public function setImageBiasQuantum(float `$bias`): void
public function setImageBluePrimary(float `$x`, float `$y`): bool
public function setImageBorderColor(mixed `$border`): bool
public function setImageChannelDepth(int `$channel`, int `$depth`): bool
public function setImageClipMask(Imagick `$clip_mask`): bool
public function setImageColormapColor(int `$index`, ImagickPixel `$color`): bool
public function setImageColorspace(int `$colorspace`): bool
public function setImageCompose(int `$compose`): bool
public function setImageCompression(int `$compression`): bool
public function setImageCompressionQuality(int `$quality`): bool
public function setImageDelay(int `$delay`): bool
public function setImageDepth(int `$depth`): bool
public function setImageDispose(int `$dispose`): bool
public function setImageExtent(int `$columns`, int `$rows`): bool
public function setImageFilename(string `$filename`): bool
public function setImageFormat(string `$format`): bool
public function setImageGamma(float `$gamma`): bool
public function setImageGravity(int `$gravity`): bool
public function setImageGreenPrimary(float `$x`, float `$y`): bool
public function setImageIndex(int `$index`): bool
public function setImageInterlaceScheme(int `$interlace_scheme`): bool
public function setImageInterpolateMethod(int `$method`): bool
public function setImageIterations(int `$iterations`): bool
public function setImageMatte(bool `$matte`): bool
public function setImageMatteColor(mixed `$matte`): bool
public function setImageOpacity(float `$opacity`): bool
public function setImageOrientation(int `$orientation`): bool
public function setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setImageProfile(string `$name`, string `$profile`): bool
public function setImageProperty(string `$name`, string `$value`): bool
public function setImageRedPrimary(float `$x`, float `$y`): bool
public function setImageRenderingIntent(int `$rendering_intent`): bool
public function setImageResolution(float `$x_resolution`, float `$y_resolution`): bool
public function setImageScene(int `$scene`): bool
public function setImageTicksPerSecond(int `$ticks_per_second`): bool
public function setImageType(int `$image_type`): bool
public function setImageUnits(int `$units`): bool
public function setImageVirtualPixelMethod(int `$method`): bool
public function setImageWhitePoint(float `$x`, float `$y`): bool
public function setInterlaceScheme(int `$interlace_scheme`): bool
public function setIteratorIndex(int `$index`): bool
public function setLastIterator(): bool
public function setOption(string `$key`, string `$value`): bool
public function setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setPointSize(float `$point_size`): bool
public function setProgressMonitor(callable `$callback`): bool
public static function setRegistry(string `$key`, string `$value`): bool
public function setResolution(float `$x_resolution`, float `$y_resolution`): bool
public static function setResourceLimit(int `$type`, int `$limit`): bool
public function setSamplingFactors(array `$factors`): bool
public function setSize(int `$columns`, int `$rows`): bool
public function setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool
public function setType(int `$image_type`): bool
public function shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool
public function shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool
public function sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function shaveImage(int `$columns`, int `$rows`): bool
public function shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool
public function sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool
public function smushImages(bool `$stack`, int `$offset`): Imagick
public function solarizeImage(int `$threshold`): bool
public function sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function spreadImage(float `$radius`): bool
public function statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick
public function stereoImage(Imagick `$offset_wand`): bool
public function stripImage(): bool
public function subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick
function swirlImage(float `$degrees`): bool
function textureImage(Imagick `$texture_wand`): Imagick
public function thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool
public function tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function __toString(): string
public function transformImage(string `$crop`, string `$geometry`): Imagick
public function transformImageColorspace(int `$colorspace`): bool
public function transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool
public function transposeImage(): bool
public function transverseImage(): bool
public function trimImage(float `$fuzz`): bool
public function uniqueImageColors(): bool
public function unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function valid(): bool
public function vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool
public function waveImage(float `$amplitude`, float `$length`): bool
public function whiteThresholdImage(mixed `$threshold`): bool
public function writeImage(string `$filename` = NULL): bool
public function writeImageFile(resource `$filehandle`, string `$format` = ?): bool
public function writeImages(string `$filename`, bool `$adjoin`): bool
public function writeImagesFile(resource `$filehandle`, string `$format` = ?): bool
}

## Méthodes Image et méthodes globales

La classe Imagick permet d'agir sur plusieurs images simultanément et ce, grâce à une pile interne. Il y a toujours un pointeur interne, pointant sur l'image courante. Quelques fonctions agissent sur toutes les images d'une classe Imagick, mais la plupart uniquement sur l'image courante au regard de cette pile. Tout comme les conversions, les noms des méthodes peuvent contenir le nom de l'image, relatant uniquement l'effet sur l'image de la pile.

## Méthodes de la classe

Vu le nombre de méthodes, voici une liste les présentant de façon générale :

Méthodes de la classe
Effets sur l'image | Méthodes de récupération | Méthodes de définition | Lecture/écriture de l'image | Autres
--- | --- | --- | --- | ---
Imagick::adaptiveBlurImage() | Imagick::getCompression() | Imagick::setBackgroundColor() | Imagick::__construct() | Imagick::clear()
Imagick::adaptiveResizeImage() | Imagick::getFilename() | Imagick::setCompressionQuality() | Imagick::addImage() | Imagick::clone()
Imagick::adaptiveSharpenImage() | Imagick::getFormat() | Imagick::setCompression() | Imagick::appendImages() | Imagick::current()
Imagick::adaptiveThresholdImage() | Imagick::getImageBackgroundColor() | Imagick::setFilename() | Imagick::getFilename() | Imagick::destroy()
Imagick::addNoiseImage() | Imagick::getImageBlob() | Imagick::getImagesBlob() | Imagick::setFormat() | Imagick::getFormat()
Imagick::affinetransformimage() | Imagick::getImageBluePrimary() | Imagick::setImageBackgroundColor() | Imagick::getImageFilename() | Imagick::getHomeURL()
Imagick::annotateImage() | Imagick::getImageBorderColor() | Imagick::setFirstIterator() | Imagick::getImageFormat() | Imagick::commentImage()
Imagick::averageImages() | Imagick::getImageChannelDepth() | Imagick::setImageBias() | Imagick::getImage() | Imagick::getNumberImages()
Imagick::blackThresholdImage() | Imagick::getImageChannelDistortion() | Imagick::setImageBluePrimary() | Imagick::setImageFilename() | Imagick::getReleaseDate()
Imagick::blurImage() | Imagick::getImageChannelExtrema() | Imagick::setImageBorderColor() | Imagick::setImageFormat() | Imagick::getVersion()
Imagick::borderImage() | Imagick::getImageChannelMean() | Imagick::setImageChannelDepth() | Imagick::readImageFile() | Imagick::hasNextImage()
Imagick::charcoalImage() | Imagick::getImageChannelStatistics() | Imagick::setImageColormapColor() | Imagick::readImage() | Imagick::hasPreviousImage()
Imagick::chopImage() | Imagick::getImageColormapColor() | Imagick::setImageColorSpace() | Imagick::writeImages() | Imagick::labelImage()
Imagick::clipImage() | Imagick::getImageColorspace() | Imagick::setImageCompose() | Imagick::writeImage() | Imagick::newImage()
Imagick::clipPathImage() | Imagick::getImageColors() | Imagick::setImageCompression() |  | Imagick::newPseudoImage()
Imagick::coalesceImages() | Imagick::getImageCompose() | Imagick::setImageDelay() |  | Imagick::nextImage()
Imagick::colorFloodFillImage() | Imagick::getImageDelay() | Imagick::setImageDepth() |  | Imagick::pingImageBlob()
Imagick::colorizeImage() | Imagick::getImageDepth() | Imagick::setImageDispose() |  | Imagick::pingImageFile()
Imagick::combineImages() | Imagick::getImageDispose() | Imagick::setImageDispose() |  | Imagick::pingImage()
Imagick::compareImageChannels() | Imagick::getImageDistortion() | Imagick::setImageExtent() |  | Imagick::previousImage()
Imagick::compareImageLayers() | Imagick::getImageExtrema() | Imagick::setImageFilename() |  | Imagick::profileImage()
Imagick::compositeImage() | Imagick::getImageFilename() | Imagick::setImageFormat() |  | Imagick::queryFormats()
Imagick::contrastImage() | Imagick::getImageFormat() | Imagick::setImageGamma() |  | Imagick::removeImageProfile()
Imagick::contrastStretchImage() | Imagick::getImageGamma() | Imagick::setImageGreenPrimary() |  | Imagick::removeImage()
Imagick::convolveImage() | Imagick::getImageGeometry() | Imagick::setImageIndex() |  | Imagick::setFirstIterator()
Imagick::cropImage() | Imagick::getImageGreenPrimary() | Imagick::setImageInterpolateMethod() |  | Imagick::setImageIndex()
Imagick::cycleColormapImage() | Imagick::getImageHeight() | Imagick::setImageIterations() |  | Imagick::valid()
Imagick::deconstructImages() | Imagick::getImageHistogram() | Imagick::setImageMatteColor() |  | Imagick::getCopyright()
Imagick::drawImage() | Imagick::getImageIndex() | Imagick::setImageMatte() |  |
Imagick::edgeImage() | Imagick::getImageInterlaceScheme() | Imagick::setImagePage() |  |
Imagick::embossImage() | Imagick::getImageInterpolateMethod() | Imagick::setImageProfile() |  |
Imagick::enhanceImage() | Imagick::getImageIterations() | Imagick::setImageProperty() |  |
Imagick::equalizeImage() | Imagick::getImageMatteColor() | Imagick::setImageRedPrimary() |  |
Imagick::evaluateImage() | Imagick::getImageMatte() | Imagick::setImageRenderingIntent() |  |
Imagick::flattenImages() | Imagick::getImagePage() | Imagick::setImageResolution() |  |
Imagick::flipImage() | Imagick::getImagePixelColor() | Imagick::setImageScene() |  |
Imagick::flopImage() | Imagick::getImageProfile() | Imagick::setImageTicksPerSecond() |  |
| Imagick::getImageProperty() | Imagick::setImageType() |  |
Imagick::fxImage() | Imagick::getImageRedPrimary() | Imagick::setImageUnits() |  |
Imagick::gammaImage() | Imagick::getImageRegion() | Imagick::setImageVirtualPixelMethod() |  |
Imagick::gaussianBlurImage() | Imagick::getImageRenderingIntent() | Imagick::setImageWhitepoint() |  |
Imagick::implodeImage() | Imagick::getImageResolution() | Imagick::setInterlaceScheme() |  |
Imagick::levelImage() | Imagick::getImageScene() | Imagick::setOption() |  |
Imagick::linearStretchImage() | Imagick::getImageSignature() | Imagick::setPage() |  |
Imagick::magnifyImage() | Imagick::getImageTicksPerSecond() | Imagick::setResolution() |  |
Imagick::matteFloodFillImage() | Imagick::getImageTotalInkDensity() | Imagick::setResourceLimit() |  |
Imagick::medianFilterImage() | Imagick::getImageType() | Imagick::setSamplingFactors() |  |
Imagick::minifyImage() | Imagick::getImageUnits() | Imagick::setSizeOffset() |  |
Imagick::modulateImage() | Imagick::getImageVirtualPixelMethod() | Imagick::setSize() |  |
Imagick::montageImage() | Imagick::getImageWhitepoint() | Imagick::setType() |  |
Imagick::morphImages() | Imagick::getImageWidth() |  |  |
Imagick::mosaicImages() | Imagick::getImage() |  |  |
Imagick::motionBlurImage() | Imagick::getInterlaceScheme() |  |  |
Imagick::negateImage() | Imagick::getNumberImages() |  |  |
Imagick::normalizeImage() | Imagick::getOption() |  |  |
Imagick::oilPaintImage() | Imagick::getPackageName() |  |  |
Imagick::optimizeImageLayers() | Imagick::getPage() |  |  |
Imagick::paintOpaqueImage() | Imagick::getPixelIterator() |  |  |
Imagick::paintTransparentImage() | Imagick::getPixelRegionIterator() |  |  |
Imagick::posterizeImage() | Imagick::getQuantumDepth() |  |  |
Imagick::radialBlurImage() | Imagick::getQuantumRange() |  |  |
Imagick::raiseImage() | Imagick::getResourceLimit() |  |  |
Imagick::randomThresholdImage() | Imagick::getResource() |  |  |
Imagick::reduceNoiseImage() | Imagick::getSamplingFactors() |  |  |
Imagick::render() | Imagick::getSizeOffset() |  |  |
Imagick::resampleImage() | Imagick::getSize() |  |  |
Imagick::resizeImage() | Imagick::identifyImage() |  |  |
Imagick::rollImage() | Imagick::getImageSize() |  |  |
Imagick::rotateImage() |  |  |  |
Imagick::sampleImage() |  |  |  |
Imagick::scaleImage() |  |  |  |
Imagick::separateImageChannel() |  |  |  |
Imagick::sepiaToneImage() |  |  |  |
Imagick::shadeImage() |  |  |  |
Imagick::shadowImage() |  |  |  |
Imagick::sharpenImage() |  |  |  |
Imagick::shaveImage() |  |  |  |
Imagick::shearImage() |  |  |  |
Imagick::sigmoidalContrastImage() |  |  |  |
Imagick::sketchImage() |  |  |  |
Imagick::solarizeImage() |  |  |  |
Imagick::spliceImage() |  |  |  |
Imagick::spreadImage() |  |  |  |
Imagick::steganoImage() |  |  |  |
Imagick::stereoImage() |  |  |  |
Imagick::stripImage() |  |  |  |
Imagick::swirlImage() |  |  |  |
Imagick::textureImage() |  |  |  |
Imagick::thresholdImage() |  |  |  |
Imagick::thumbnailImage() |  |  |  |
Imagick::tintImage() |  |  |  |
Imagick::transverseImage() |  |  |  |
Imagick::trimImage() |  |  |  |
Imagick::uniqueImageColors() |  |  |  |
Imagick::unsharpMaskImage() |  |  |  |
Imagick::vignetteImage() |  |  |  |
Imagick::waveImage() |  |  |  |
Imagick::whiteThresholdImage() |  |  |  |

# Imagick::adaptiveBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveBlurImage — Ajoute un flou adaptatif à l'image

### Description

public function Imagick::adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Ajoute un flou adaptatif à l'image. L'intensité du flou est diminuée aux bords de l'image, mais uniforme au centre. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`radius`

  Le rayon de la gaussienne, en pixels, sans compter le centre. Avec une valeur de 0, le rayon sera choisi automatiquement.

`sigma`

  La déviation standard de la gaussienne, en pixels.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::adaptiveBlurImage()

Flou adaptatif d'une image, puis affichage au navigateur.

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('test.jpg');

    $image->adaptiveBlurImage(5,3);
    echo $image;

    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- Imagick::blurImage() - Ajoute un filtre de flou à une image
- Imagick::motionBlurImage() - Ajoute un flou de déplacement
- Imagick::radialBlurImage() - Flou radial d'une image

# Imagick::adaptiveResizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveResizeImage — Redimensionne adaptativement une image par triangulation

### Description

public function Imagick::adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Redimensionne une image adaptativement par triangulation. Cette fonction évite les effets de flou dans les images à contraste fort. Elle fonctionne au mieux avec des images qu'il faut réduire légèrement à une taille Web standard; ne fonctionne pas toujours quand il faut réduire une grosse image à une miniature. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

> Note: Le comportement du paramètre `bestfit` a changé avec Imagick 3.0.0. Avant cette version, fournir les dimensions 400x400 à une image de dimensions 200x150 faisait que la partie gauche était inchangée. Avec Imagick 3.0.0 et suivants, l'image est réduite à la taille 400x300, sachant que c'est le meilleur résultat pour ces dimensions. Si le paramètre `bestfit` est utilisé, la largeur et la hauteur doivent être fournies.

### Liste de paramètres

`columns`

  Le nombre de colonnes dans l'image cible.

`rows`

  Le nombre de lignes dans l'image cible.

`bestfit`

  Indique s'il faut conserver l'image dans le rectangle de délimitation.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Ajout d'un paramètre optionnel de fit.
PECL imagick 2.1.0 | Cette méthode supporte maintenant la mise à l'échelle proportionnelle. Utiliser la valeur zéro comme paramètre pour une mise à l'échelle proportionnelle.

### Exemples

Exemple #1 Exemple avec Imagick::adaptiveResizeImage()

Redimensionne une image à une taille standard pour le Web. Cette méthode fonctionne au mieux lorsqu'il faut redimensionner à une taille légèrement inférieure à l'image précédente.

    <?php
    header('Content-type: image/jpeg');

    $image = new Imagick('image.jpg');
    $image->adaptiveResizeImage(1024,768);

    echo $image;
    ?>

### Voir aussi

- Imagick::chopImage() - Supprime une région d'une image et retaille
- Imagick::cropImage() - Extrait une région d'une image
- Imagick::magnifyImage() - Double la taille d'une image, proportionnellement
- Imagick::minifyImage() - Met à l'échelle une image proportionnellement pour la réduire de moitié de taille
- Imagick::resizeImage() - Redimensionne une image
- Imagick::scaleImage() - Met à l'échelle la taille de l'image
- Imagick::shaveImage() - Supprime les pixels du bord de l'image
- Imagick::thumbnailImage() - Modifie la taille d'une image
- Imagick::trimImage() - Supprime les bords de l'image

# Imagick::adaptiveSharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveSharpenImage — Augmente le contraste de l'image

### Description

public function Imagick::adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Augmente le contraste adaptativement, en l'augmentant au niveau des bords, et en le diminuant dans le cœur. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`radius`

  Le rayon de la gaussienne, en pixels, sans compter le pixel du centre. Utiliser 0 pour l'auto-sélection.

`sigma`

  La déviation standard de la gaussienne, en pixels.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::adaptiveSharpenImage()

Augmente le contraste de l'image avec un rayon de 2 et un sigma de 1.

    <?php
    try {
        $image = new Imagick('image.png');
        $image->adaptiveSharpenImage(2,1);
    } catch(ImagickException $e) {
        echo 'Erreur : ' , $e->getMessage();
        die();
    }
    header('Content-type: image/png');
    echo $image;
    ?>

### Voir aussi

- Imagick::sharpenImage() - Aiguise une image

# Imagick::adaptiveThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveThresholdImage — Sélectionne le niveau de chaque pixel, à partir d'un intervalle d'intensité

### Description

public function Imagick::adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool

Sélectionne un seuil individuel pour chaque pixel, en se basant sur l'intervalle des valeurs d'intensité dans son voisinage local. Cela permet d'appliquer un seuillage à une image dont l'histogramme global d'intensité ne contient pas de pic distinct.

### Liste de paramètres

`width`

  La largeur du voisinage local.

`height`

  La hauteur du voisinage local.

`offset`

  Le décalage de la moyenne.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::adaptiveThresholdImage()

    <?php
    function adaptiveThresholdImage($imagePath, $width, $height, $adaptiveOffset) {
        $imagick = new \Imagick(realpath($imagePath));
        $adaptiveOffsetQuantum = intval($adaptiveOffset * \Imagick::getQuantum());
        $imagick->adaptiveThresholdImage($width, $height, $adaptiveOffsetQuantum);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::addImage

(PECL imagick 2, PECL imagick 3)

Imagick::addImage — Ajoute une nouvelle image à la liste d'images Imagick

### Description

public function Imagick::addImage(Imagick `$source`): bool

Ajoute une nouvelle image à la liste d'images Imagick, à partir de la position courante de l'objet source. Après cette opération, l'itérateur est placé à la fin de la liste.

### Liste de paramètres

`source`

  L'objet source Imagick.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::addNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::addNoiseImage — Ajoute un bruit aléatoire à une image

### Description

public function Imagick::addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Ajoute un bruit aléatoire à une image.

### Liste de paramètres

`noise_type`

  Le type de bruit, dans la liste des constantes de bruit.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::addNoiseImage()

    <?php
    function addNoiseImage($noiseType, $imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->addNoiseImage($noiseType, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::affineTransformImage

(PECL imagick 2, PECL imagick 3)

Imagick::affineTransformImage — Transforme une image

### Description

public function Imagick::affineTransformImage(ImagickDraw `$matrix`): bool

Transforme une image, à l'aide d'une matrice affine.

### Liste de paramètres

`matrix`

  La matrice affine.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::affineTransformImage()

    <?php
    function affineTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $draw = new \ImagickDraw();

        $angle = deg2rad(40);

        $affineRotate = array(
            "sx" => cos($angle), "sy" => cos($angle),
            "rx" => sin($angle), "ry" => -sin($angle),
            "tx" => 0, "ty" => 0,
        );

        $draw->affine($affineRotate);

        $imagick->affineTransformImage($draw);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::animateImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::animateImages — Anime une ou plusieurs images

### Description

public function Imagick::animateImages(string `$x_server`): bool

Cette méthode anime l'image sur un serveur X local ou distant. Cette méthode n'est pas disponible sur Windows. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`x_server`

  Adresse du serveur X.

### Valeurs de retour

Retourne `true` en cas de succès.

### Voir aussi

- Imagick::displayImage() - Affiche une image

# Imagick::annotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::annotateImage — Annote une image avec un texte

### Description

public function Imagick::annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool

Annote une image avec un texte.

### Liste de paramètres

`draw_settings`

  L'objet ImagickDraw qui contient les directives pour dessiner le texte

`x`

  La position horizontale du texte, en pixels depuis la gauche du texte

`y`

  La position verticale du texte, en pixels depuis la ligne de base du texte

`angle`

  L'angle auquel écrire le texte

`text`

  La chaîne à dessiner

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::annotateImage()

Annote un texte dans une image vide

    <?php
    /* Création de quelques objets */
    $image = new Imagick();
    $draw = new ImagickDraw();
    $pixel = new ImagickPixel( 'gray' );

    /* Nouvelle image */
    $image->newImage(800, 75, $pixel);

    /* Texte noir */
    $draw->setFillColor('black');

    /* Propriétés du texte */
    $draw->setFont('Bookman-DemiItalic');
    $draw->setFontSize( 30 );

    /* Création du texte */
    $image->annotateImage($draw, 10, 45, 0, 'The quick brown fox jumps over the lazy dog');

    /* Format de l'image */
    $image->setImageFormat('png');

    /* Affichage de l'image avec les entêtes */
    header('Content-type: image/png');
    echo $image;

    ?>

### Voir aussi

- ImagickDraw::annotation() - Dessine un texte sur une image
- ImagickDraw::setFont() - Configure la police complète pour les textes

# Imagick::appendImages

(PECL imagick 2, PECL imagick 3)

Imagick::appendImages — Ajoute un jeu d'images

### Description

public function Imagick::appendImages(bool `$stack`): Imagick

Ajoute un jeu d'images dans une image plus large.

### Liste de paramètres

`stack`

  Si l'on doit placer les images dans la pile de façon verticale. Par défaut (ou si `false` est spécifié), les images sont placées dans la pile de gauche à droite. Si le paramètre `stack` vaut `true`, les images sont placées dans la pile de haut en bas.

### Valeurs de retour

Retourne un nouvel objet Imagick en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::appendImages()

    <?php

    /* Crée un nouvel objet imagick */
    $im = new Imagick();

    /* Crée des images rouges, vertes et bleues */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Ajoute les images dans une autre */
    $im->resetIterator();
    $combined = $im->appendImages(true);

    /* Affiche l'image */
    $combined->setImageFormat("png");
    header("Content-Type: image/png");
    echo $combined;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# Imagick::autoLevelImage

(PECL imagick 3 >= 3.3.0)

Imagick::autoLevelImage — Ajuste le niveau d'un canal d'une image particulière

### Description

public function Imagick::autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Ajuste le niveau d'un canal d'une image particulière en mettant à l'échelle les valeurs minimales et maximales à la plage quantique complète.

### Liste de paramètres

`channel`

  Quel canal doit être utilisé pour l'auto-nivellement.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::autoLevelImage()

    <?php
    function autoLevelImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->autoLevelImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::averageImages

(PECL imagick 2, PECL imagick 3)

Imagick::averageImages — Moyenne d'un jeu d'images

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::averageImages(): Imagick

Fait la moyenne d'un jeu d'images.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un nouvel objet Imagick en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::blackThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::blackThresholdImage — Force tous les pixels en dessous d'un seuil à noir

### Description

public function Imagick::blackThresholdImage(mixed `$threshold`): bool

Équivalent de la fonction Imagick::thresholdImage(), mais force tous les pixels en dessous du seuil `threshold` en noir, et laisse les autres pixels inchangés.

### Liste de paramètres

`threshold`

  Le seuil en dessous duquel tout doit devenir noir

### Valeurs de retour

Retourne `true` en cas de succès.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

### Exemples

Exemple #1 Exemple avec Imagick::blackThresholdImage()

    <?php
    function blackThresholdImage($imagePath, $thresholdColor) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blackthresholdimage($thresholdColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blueShiftImage

(PECL imagick 3 >= 3.3.0)

Imagick::blueShiftImage — Atténue les couleurs de l'image

### Description

public function Imagick::blueShiftImage(float `$factor` = 1.5): bool

Atténue les couleurs de l'image pour simuler une scène nocturne à la lumière de la lune.

### Liste de paramètres

`factor`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::blueShiftImage()

    <?php
    function blueShiftImage($imagePath, $blueShift) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blueShiftImage($blueShift);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blurImage

(PECL imagick 2, PECL imagick 3)

Imagick::blurImage — Ajoute un filtre de flou à une image

### Description

public function Imagick::blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool

Ajoute un filtre de flou à une image. Le troisième paramètre `channel`, optionnel, ajoute le flou à un canal particulier.

### Liste de paramètres

`radius`

  Le rayon du flou

`sigma`

  La déviation standard

`channel`

  La constante de type de canal. Si elle n'est pas fournie, tous les canaux sont utilisés.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::blurImage()

Ajoute du flou à une image, puis affiche dans le navigateur.

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('test.jpg');

    $image->blurImage(5,3);
    echo $image;

    ?>

### Voir aussi

- Imagick::adaptiveBlurImage() - Ajoute un flou adaptatif à l'image
- Imagick::motionBlurImage() - Ajoute un flou de déplacement
- Imagick::radialBlurImage() - Flou radial d'une image

# Imagick::borderImage

(PECL imagick 2, PECL imagick 3)

Imagick::borderImage — Encadre une image avec un bord

### Description

public function Imagick::borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool

Encadre une image avec un bord de couleur, défini par l'attribut `bordercolor` d'un objet ImagickPixel.

### Liste de paramètres

`bordercolor`

  Objet ImagickPixel ou une chaîne contenant la couleur du bord

`width`

  La largeur du bord

`height`

  La hauteur du bord

### Valeurs de retour

Retourne `true` en cas de succès.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

### Exemples

Exemple #1 Exemple avec Imagick::borderImage()

    <?php
    function borderImage($imagePath, $color, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->borderImage($color, $width, $height);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::brightnessContrastImage

(PECL imagick 3 >= 3.3.0)

Imagick::brightnessContrastImage — Change la luminosité et/ou le contraste d'une image

### Description

public function Imagick::brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Change la luminosité et/ou le contraste d'une image. Il convertit les paramètres de luminosité et de contraste en pente et en ordonnée à l'origine et appelle une fonction polynomiale à appliquer à l'image.

### Liste de paramètres

`brightness`

`contrast`

`channel`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::brightnessContrastImage()

    <?php
    function brightnessContrastImage($imagePath, $brightness, $contrast, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->brightnessContrastImage($brightness, $contrast, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::charcoalImage

(PECL imagick 2, PECL imagick 3)

Imagick::charcoalImage — Simule un dessin au fusain

### Description

public function Imagick::charcoalImage(float `$radius`, float `$sigma`): bool

Simule un dessin au fusain

### Liste de paramètres

`radius`

  Le rayon de la gaussienne, en pixels, sans compter le pixel du centre

`sigma`

  La déviation standard de la gaussienne, en pixels

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::charcoalImage()

    <?php
    function charcoalImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->charcoalImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::chopImage

(PECL imagick 2, PECL imagick 3)

Imagick::chopImage — Supprime une région d'une image et retaille

### Description

public function Imagick::chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Supprime une région d'une image, retaille et déplace le reste de l'image pour occuper la portion coupée.

### Liste de paramètres

`width`

  La largeur de la région à retirer

`height`

  La hauteur de la région à retirer

`x`

  L'abscisse de la région retirée

`y`

  L'ordonnée de la région retirée

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::chopImage()

Exemple avec Imagick::chopImage

    <?php
    /* Crée un objet */
    $image = new Imagick();
    $pixel = new ImagickPixel( 'gray' );

    /* Nouvelle image */
    $image->newImage(400, 200, $pixel);

    /* Découpe l'image */
    $image->chopImage(200, 200, 0, 0);

    /* Donne un format à l'image */
    $image->setImageFormat('png');

    /* Envoie l'image */
    header('Content-type: image/png');
    echo $image;

    ?>

### Voir aussi

- Imagick::cropImage() - Extrait une région d'une image

# Imagick::clampImage

(PECL imagick 3 >= 3.3.0)

Imagick::clampImage — Restreint la plage de couleurs de 0 à la profondeur quantique

### Description

public function Imagick::clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Restreint la plage de couleurs de 0 à la profondeur quantique.

### Liste de paramètres

`channel`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# Imagick::clear

(PECL imagick 2, PECL imagick 3)

Imagick::clear — Libère toutes les ressources associées à un objet Imagick

### Description

public function Imagick::clear(): bool

Libère toutes les ressources associées à un objet Imagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::clipImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipImage — Découpe le long du premier chemin du profil 8BIM

### Description

public function Imagick::clipImage(): bool

Découpe le long du premier chemin du profil 8BIM, si présent.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::clipImagePath

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::clipImagePath — Découpe le long des chemins nommés du profil 8BIM, si présent

### Description

public function Imagick::clipImagePath(string `$pathname`, string `$inside`): void

Découpe le long des chemins nommés du profil 8BIM, si présent. Les opérations ultérieures prennent effet à l'intérieur du chemin. Id peut être un nombre s'il est précédé de #, pour travailler sur un chemin numéroté, par exemple, "#1" pour utiliser le premier chemin.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`pathname`

`inside`

### Valeurs de retour

# Imagick::clipPathImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipPathImage — Découpe le long du chemin d'un profil 8BIM

### Description

public function Imagick::clipPathImage(string `$pathname`, bool `$inside`): bool

Découpe le long du chemin d'un profil 8BIM, s'il est présent. Les opérations suivantes auront lieu dans ce chemin. Cela peut être un nombre, s'il est précédé par #, pour utiliser un chemin numéroté, p. ex. "#1" pour utiliser le premier chemin.

### Liste de paramètres

`pathname`

  Le nom du chemin

`inside`

  Si `true` les prochaines opérations auront lieu dans le chemin. Sinon, les prochaines opérations auront lieu hors du chemin.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::clone

(PECL imagick 2, PECL imagick 3)

Imagick::clone — Fait une copie exacte d'un objet Imagick

### Description

public function Imagick::clone(): Imagick

Fait une copie exacte d'un objet Imagick.

Avertissement

Cette fonction est devenue OBSOLETE à partir d'imagick 3.1.0. Il faut désormais utiliser le mot clé clone.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une copie de l'objet Imagick.

### Historique

Version | Description
--- | ---
PECL imagick 3.1.0 | Cette méthode est devenue obsolète en faveur du mot clé clone.

### Exemples

Exemple #1 Clonage d'objet Imagick avec différentes versions d'Imagick

    <?php
    // Clonage d'un objet Imagick en utilisant la version 2.x et 3.0 :
    $newImage = $image->clone();

    // Clonage d'un objet Imagick à partir de la version 3.1.0 :
    $newImage = clone $image;
    ?>

# Imagick::clutImage

(PECL imagick 2, PECL imagick 3)

Imagick::clutImage — Remplace les couleurs d'une image

### Description

public function Imagick::clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Remplace les couleurs dans l'image à l'aide d'une table de correspondance. Un second paramètre optionnel remplace les couleurs dans un canal particulier. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`lookup_table`

  Un objet Imagick contenant la table de correspondance

`channel`

  La constante de type de canal. S'il n'est pas fourni, les canaux par défaut sont utilisés.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::clutImage()

Remplace les couleurs dans une image à partir d'une table de correspondance

    <?php
    $image = new Imagick('test.jpg');
    $clut = new Imagick();
    $clut->newImage(1, 1, new ImagickPixel('black'));
    $image->clutImage($clut);
    $image->writeImage('test_out.jpg');
    ?>

### Voir aussi

- Imagick::adaptiveBlurImage() - Ajoute un flou adaptatif à l'image
- Imagick::motionBlurImage() - Ajoute un flou de déplacement
- Imagick::radialBlurImage() - Flou radial d'une image

# Imagick::coalesceImages

(PECL imagick 2, PECL imagick 3)

Imagick::coalesceImages — Compose un jeu d'images

### Description

public function Imagick::coalesceImages(): Imagick

Compose un jeu d'images en respectant toutes les positions et les méthodes de dispositions. Les séquences d'animations GIF, MIFF, et MNG, commencent typiquement par une image de fond, puis toutes les images suivantes varient en taille et position. Retourne un nouvel objet Imagick où chaque image de la séquence est de la même taille que la première, et composée avec la suivante dans la séquence.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un nouvel objet Imagick en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::colorFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorFloodfillImage — Change la couleur d'un pixel

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Change la couleur d'un pixel qui correspond à une cible, et ses voisins immédiats.

### Liste de paramètres

`fill`

  L'objet ImagickPixel contenant la couleur de remplissage

`fuzz`

  La quantité de bruit. Par exemple, un bruit de 10 et la couleur rouge à l'intensité de 100 et 102, respectivement, sont maintenant interprétés comme la même couleur, dans le cadre de ce remplissage.

`bordercolor`

  L'objet ImagickPixel contenant la couleur de frontière

`x`

  L'abscisse de début de remplissage

`y`

  L'ordonnée de début de remplissage

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet maintenant à une chaîne représentant la couleur comme premier argument et troisième paramètre. Les versions précédentes n'autorisaient que les objets ImagickPixel.

# Imagick::colorizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorizeImage — Mélange la couleur de remplissage avec l'image

### Description

public function Imagick::colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool

Mélange la couleur de remplissage avec l'image.

### Liste de paramètres

`colorize`

  L'objet ImagickPixel ou une chaîne contenant la couleur de colorisation

`opacity`

  L'objet ImagickPixel ou un nombre décimal contenant la valeur de l'opacité. 1.0 est totalement opaque, et 0.0 est totalement transparent.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Maintenant, permet à une chaîne représentant la couleur comme premier argument et un décimal représentant l'opacité comme second paramètre. Les versions précédentes ne permettaient que l'utilisation d'objets ImagickPixel.

### Exemples

Exemple #1 Exemple avec Imagick::colorizeImage()

    <?php
    function colorizeImage($imagePath, $color, $opacity) {
        $imagick = new \Imagick(realpath($imagePath));
        $opacity = $opacity / 255.0;
        $opacityColor = new \ImagickPixel("rgba(0, 0, 0, $opacity)");
        $imagick->colorizeImage($color, $opacityColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::colorMatrixImage

(PECL imagick 3 >= 3.3.0)

Imagick::colorMatrixImage — Applique une transformation de couleur à une image

### Description

public function Imagick::colorMatrixImage(array `$color_matrix`): bool

Applique une transformation de couleur à une image. La méthode permet des changements de saturation, une rotation de teinte, une luminance en alpha, et divers autres effets. Bien que des matrices de transformation de taille variable puissent être utilisées, on utilise généralement une matrice 5x5 pour une image RGBA et une 6x6 pour CMYKA (ou RGBA avec des décalages). La matrice est similaire à celles utilisées par Adobe Flash, sauf que les décalages sont dans la colonne 6 plutôt que 5 (en support des images CMYKA) et les décalages sont normalisés (diviser le décalage Flash par 255).

### Liste de paramètres

`color_matrix`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::colorMatrixImage()

    <?php
    function colorMatrixImage($imagePath, $colorMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOpacity(1);

        //Une matrice de couleur devrait ressembler à:
        //    $colorMatrix = [
        //        1.5, 0.0, 0.0, 0.0, 0.0, -0.157,
        //        0.0, 1.0, 0.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 1.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 0.0, 1.0, 0.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 1.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 0.0,  1.0
        //    ];

        $background = new \Imagick();
        $background->newPseudoImage($imagick->getImageWidth(), $imagick->getImageHeight(),  "pattern:checkerboard");

        $background->setImageFormat('png');

        $imagick->setImageFormat('png');
        $imagick->colorMatrixImage($colorMatrix);

        $background->compositeImage($imagick, \Imagick::COMPOSITE_ATOP, 0, 0);

        header("Content-Type: image/png");
        echo $background->getImageBlob();
    }

    ?>

# Imagick::combineImages

(PECL imagick 2, PECL imagick 3)

Imagick::combineImages — Combine plusieurs images en une seule

### Description

public function Imagick::combineImages(int `$channelType`): Imagick

Combine une ou plusieurs images en une seule. Les niveaux de gris des pixels de chaque image en séquence sont assignés en ordre à des canaux spécifiés de l'image combinée. L'ordre typique serait image 1 => Rouge, 2 => Vert, 3 => Bleu, etc.

### Liste de paramètres

`channelType`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::commentImage

(PECL imagick 2, PECL imagick 3)

Imagick::commentImage — Ajoute un commentaire à une image

### Description

public function Imagick::commentImage(string `$comment`): bool

Ajoute un commentaire à une image.

### Liste de paramètres

`comment`

  Le commentaire à ajouter.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::commentImage()

Ajout d'un commentaire d'image et lecture du commentaire

    <?php

    /* Crée un nouvel objet Imagick */
    $im = new imagick();

    /* Création d'une image vide */
    $im->newImage(100, 100, new ImagickPixel("red"));

    /* Ajoute un commentaire à une image */
    $im->commentImage("Bonjour le monde!");

    /* Affichage du commentaire */
    echo $im->getImageProperty("comment");

    ?>

# Imagick::compareImageChannels

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageChannels — Retourne la différence entre plusieurs images

### Description

public function Imagick::compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array

Compare une ou plusieurs images et retourne la différence.

### Liste de paramètres

`image`

  un objet Imagick contenant l'image à comparer

`channelType`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

`metricType`

  Une des constantes de type de métrique.

### Valeurs de retour

Un tableau contenant `new_wand` et `distortion`.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::compareImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageLayers — Retourne la région d'encadrement maximale entre deux images

### Description

public function Imagick::compareImageLayers(int `$method`): Imagick

Compare chaque image avec la suivante, dans la séquence, et retourne la région d'encadrement maximale de chaque pixel différent entre les images. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`method`

  Une des constantes de méthode de couche.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::compareImageLayers()

Comparaison de deux calques d'image

    <?php
    /* création d'un nouvel objet imagick */
    $im = new Imagick("test.gif");

    /* optimisation des calques */
    $result = $im->compareImageLayers(imagick::LAYERMETHOD_COALESCE);

    /* Travail sur le résultat */
    ?>

### Voir aussi

- Imagick::optimizeImageLayers() - Supprime les portions récurrentes d'images à optimiser
- Imagick::writeImages() - Écrit une image ou une séquence d'images
- Imagick::writeImage() - Écrit une image dans le fichier spécifié

# Imagick::compareImages

(PECL imagick 2, PECL imagick 3)

Imagick::compareImages — Compare une image avec une image reconstituée

### Description

public function Imagick::compareImages(Imagick `$compare`, int `$metric`): array

Retourne un tableau contenant l'image reconstituée et les différences entre les images.

### Liste de paramètres

`compare`

  Une image à comparer.

`metric`

  Une constante de type de métrique. Voir la liste des constantes de métriques.

### Valeurs de retour

Retourne un tableau contenant une image reconstruite et la différence entre les images.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::compareImages()

Compare des images et affiche l'image reconstituée

    <?php

    $image1 = new imagick("image1.png");
    $image2 = new imagick("image2.png");

    $result = $image1->compareImages($image2, Imagick::METRIC_MEANSQUAREERROR);
    $result[0]->setImageFormat("png");

    header("Content-Type: image/png");
    echo $result[0];

    ?>

# Imagick::compositeImage

(PECL imagick 2, PECL imagick 3)

Imagick::compositeImage — Compose une image avec une autre

### Description

public function Imagick::compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Compose une image dans une autre, à la position donnée. Tout paramètre supplémentaire nécessaire à l'algorithme de composition doit être passé à setImageArtifact avec comme premier paramètre 'compose:args' et les données en second paramètre.

### Liste de paramètres

`composite_object`

  Objet Imagick qui contient l'image composite

`compose`

  L'opérateur de composition. Voir la liste des constantes d'opérateurs de composition

`x`

  La colonne de position dans l'image composée

`y`

  La ligne de position dans l'image composée

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Utilisation de Imagick::compositeImage()

Compose deux images avec la méthode de composition 'mathematics'.

    <?php

    // Equivalent à lancer la commande
    // convert src1.png src2.png -compose mathematics -define compose:args="1,0,-0.5,0.5" -composite output.png

    $src1 = new \Imagick("./src1.png");
    $src2 = new \Imagick("./src2.png");

    $src1->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
    $src1->setImageArtifact('compose:args', "1,0,-0.5,0.5");
    $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);
    $src1->writeImage("./output.png");

    ?>

### Voir aussi

- Imagick::setImageArtifact() - Définit l'artefact de l'image

# Imagick::__construct

(PECL imagick 2, PECL imagick 3)

Imagick::__construct — Le constructeur Imagick

### Description

public function Imagick::__construct(mixed `$files` = ?)

Crée une instance Imagick pour une image spécifique ou pour un jeu d'images.

### Liste de paramètres

`files`

  Le chemin jusqu'à l'image à charger, ou un tableau de chemins. Ils peuvent inclure des jokers dans les noms des fichiers, ou peuvent être des URLs.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::contrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastImage — Change le contraste de l'image

### Description

public function Imagick::contrastImage(bool `$sharpen`): bool

Améliore l'intensité des différences entre les éléments clairs et sombres de l'image. Donner une valeur différente de zéro pour améliorer le contraste, et sinon, il sera réduit.

### Liste de paramètres

`sharpen`

  La valeur de contraste.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::contrastImage()

    <?php
    function contrastImage($imagePath, $contrastType) {
        $imagick = new \Imagick(realpath($imagePath));
        if ($contrastType != 2) {
            $imagick->contrastImage($contrastType);
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::contrastStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastStretchImage — Améliore le contraste d'une image

### Description

public function Imagick::contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Améliore le contraste d'une image en ajustant les couleurs des pixels sur l'ensemble de la gamme des couleurs. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`black_point`

  Le point noir.

`white_point`

  Le point blanc.

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Par défaut, c'est `Imagick::CHANNEL_ALL`. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::convolveImage

(PECL imagick 2, PECL imagick 3)

Imagick::convolveImage — Applique un noyau de convolution à une image

### Description

public function Imagick::convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Applique un noyau de convolution à une image.

### Liste de paramètres

`kernel`

  Le noyau de convolution

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::convolveImage()

    <?php
    function convolveImage($imagePath, $bias, $kernelMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        //$edgeFindingKernel = [-1, -1, -1, -1, 8, -1, -1, -1, -1,];
        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($kernelMatrix);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::count

(PECL imagick 3 >= 3.3.0)

Imagick::count — Renvoie le nombre d'images

### Description

public function Imagick::count(int `$mode` = 0): int

Renvoie le nombre d'images.

### Liste de paramètres

`mode`

  Un argument non utilisé. Actuellement, il existe une fonctionnalité non particulièrement bien définie en PHP où l'appel de count() sur un objet comptable pourrait (ou non) nécessiter que cette méthode accepte un paramètre. Ce paramètre est ici pour être conforme à l'interface de countable, même si le paramètre n'est pas utilisé.

### Valeurs de retour

Renvoie le nombre d'images.

# Imagick::cropImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropImage — Extrait une région d'une image

### Description

public function Imagick::cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Extrait une région d'une image.

### Liste de paramètres

`width`

  La largeur du retaillage

`height`

  La hauteur du retaillage

`x`

  L'abscisse, coordonnée X, de la région retaillée, coin haut gauche

`y`

  L'ordonnée, coordonnée Y, de la région retaillée, coin haut gauche

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::cropImage()

    <?php
    function cropImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->cropImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::cropThumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropThumbnailImage — Crée une miniature par retaillage

### Description

public function Imagick::cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool

Crée une miniature de taille fixe, en agrandissant ou en réduisant sa taille, en recadrant l'image autour du centre.

### Liste de paramètres

`width`

  La largeur de la miniature

`height`

  La hauteur de la miniature

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::current

(PECL imagick 2, PECL imagick 3)

Imagick::current — Retourne une référence sur l'objet imagick courant

### Description

public function Imagick::current(): Imagick

Retourne une référence sur l'objet courant, à partir d'une référence de séquence.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne self en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::cycleColormapImage

(PECL imagick 2, PECL imagick 3)

Imagick::cycleColormapImage — Déplace la carte des couleurs d'une image

### Description

public function Imagick::cycleColormapImage(int `$displace`): bool

Déplace la carte de couleurs, d'un nombre donné de positions. Si l'on fait tourner la carte des couleurs plusieurs fois, il est possible de produire des effets psychédéliques.

### Liste de paramètres

`displace`

  Le déplacement de la carte des couleurs.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::decipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::decipherImage — Déchiffre une image

### Description

public function Imagick::decipherImage(string `$passphrase`): bool

Déchiffre une image. L'image doit être chiffrée à l'aide de la fonction Imagick::encipherImage(). Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.9 ou supérieur.

### Liste de paramètres

`passphrase`

  Le mot de passe.

### Valeurs de retour

Retourne `true` en cas de succès.

### Voir aussi

- Imagick::encipherImage() - Chiffre une image

# Imagick::deconstructImages

(PECL imagick 2, PECL imagick 3)

Imagick::deconstructImages — Retourne les différences de certains pixels entre deux images

### Description

public function Imagick::deconstructImages(): Imagick

Compare chaque image avec la suivante dans la séquence, et retourne la région maximale d'encadrement des pixels différents qu'il découvre.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un nouvel objet Imagick en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::deleteImageArtifact

(PECL imagick 3)

Imagick::deleteImageArtifact — Supprime l'artefact d'une image

### Description

public function Imagick::deleteImageArtifact(string `$artifact`): bool

Supprime un artefact associé à l'image. La différence entre les propriétés de l'image et les artefacts de l'image est que les propriétés sont publiques, alors que les artefacts sont privés. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.5.7 ou supérieur.

### Liste de paramètres

`artifact`

  Le nom de l'artefact à supprimer.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Voir aussi

- Imagick::setImageArtifact() - Définit l'artefact de l'image
- Imagick::getImageArtifact() - Récupère l'artefact de l'image

# Imagick::deleteImageProperty

(PECL imagick 3 >= 3.3.0)

Imagick::deleteImageProperty — Supprime une propriété d'image

### Description

public function Imagick::deleteImageProperty(string `$name`): bool

Supprime une propriété d'image.

### Liste de paramètres

`name`

  Le nom de la propriété à supprimer.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::deskewImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.3.0)

Imagick::deskewImage — Supprime le biais de l'image

### Description

public function Imagick::deskewImage(float `$threshold`): bool

Cette méthode peut être utilisée pour supprimer le biais depuis, par exemple, les images scannées où le papier n'a pas été placé correctement sur la surface. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.5 ou supérieur.

### Liste de paramètres

`threshold`

  Seuil de redressement.

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec Imagick::deskewImage()

    <?php
    function deskewImage($threshold) {
        $imagick = new \Imagick(realpath("images/NYTimes-Page1-11-11-1918.jpg"));
        $deskewImagick = clone $imagick;

        // Il ne suffit que cela pour le redressement.
        $deskewImagick->deskewImage($threshold);

        // Le reste de l'exemple ne fait que rendre le résultat évident -
        // sans cela, la modification ne serait pas tellement visible.
        $trim = 9;

        $deskewImagick->cropImage($deskewImagick->getImageWidth() - $trim, $deskewImagick->getImageHeight(), $trim, 0);
        $imagick->cropImage($imagick->getImageWidth() - $trim, $imagick->getImageHeight(), $trim, 0);
        $deskewImagick->resizeimage($deskewImagick->getImageWidth() / 2, $deskewImagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $imagick->resizeimage($imagick->getImageWidth() / 2, $imagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $newCanvas = new \Imagick();
        $newCanvas->newimage($imagick->getImageWidth() + $deskewImagick->getImageWidth() + 20, $imagick->getImageHeight(), 'red', 'jpg');
        $newCanvas->compositeimage($imagick, \Imagick::COMPOSITE_COPY, 5, 0);
        $newCanvas->compositeimage($deskewImagick, \Imagick::COMPOSITE_COPY, $imagick->getImageWidth() + 10, 0);

        header("Content-Type: image/jpg");
        echo $newCanvas->getImageBlob();
    }

    ?>

# Imagick::despeckleImage

(PECL imagick 2, PECL imagick 3)

Imagick::despeckleImage — Réduit le bruit speckle d'une image

### Description

public function Imagick::despeckleImage(): bool

Réduit le bruit speckle d'une image, en préservant les bords de l'image originale.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::despeckleImage()

    <?php
    function despeckleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->despeckleImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::destroy

(PECL imagick 2, PECL imagick 3)

Imagick::destroy — Détruit un objet Imagick

### Description

public function Imagick::destroy(): bool

Détruit l'objet Imagick et libère toutes les ressources associées. Cette méthode est obsolète, en faveur de la méthode Imagick::clear.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::displayImage

(PECL imagick 2, PECL imagick 3)

Imagick::displayImage — Affiche une image

### Description

public function Imagick::displayImage(string `$servername`): bool

Cette méthode affiche une image sur un serveur X.

### Liste de paramètres

`servername`

  Le nom du serveur X

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::displayImages

(PECL imagick 2, PECL imagick 3)

Imagick::displayImages — Affiche une image ou une séquence

### Description

public function Imagick::displayImages(string `$servername`): bool

Affiche une image ou une séquence sur un serveur X.

### Liste de paramètres

`servername`

  Le nom du serveur X

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::distortImage

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::distortImage — Déforme une image avec différentes méthodes

### Description

public function Imagick::distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool

Déforme une image en utilisant différentes méthodes, en associant des couleurs de l'image source à celle d'une image de destination, généralement de la même taille, à moins que l'argument `bestfit` soit configuré à `true`.

Si `bestfit` est activé, et que la déformation le permet, l'image de destination est ajustée pour s'assurer que toute l'image source va tenir dans l'image de destination, qui sera redimensionnée et repositionnée en fonction. De plus, dans de nombreux cas, la position virtuelle de l'image sera prise en compte dans l'association.

Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`method`

  La méthode de déformation de l'image. Voir les constantes de déformation

`arguments`

  Les arguments de cette méthode de déformation

`bestfit`

  Tentative de redimensionnement de l'image de destination pour s'assurer de la taille

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::distortImage()

Déformation d'une image, et affichage sur le navigateur.

    <?php
    /* Crée un nouvel objet */
    $im = new Imagick();

    /* Crée un nouveau motif d'échiquier */
    $im->newPseudoImage(100, 100, "pattern:checkerboard");

    /* Configure l'image en PNG */
    $im->setImageFormat('png');

    /* Remplit la nouvelle zone visible à transparent */
    $im->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);

    /* Active le mate */
    $im->setImageMatte(true);

    /* Contrôle les points de déformation */
    $controlPoints = array( 10, 10,
                            10, 5,

                            10, $im->getImageHeight() - 20,
                            10, $im->getImageHeight() - 5,

                            $im->getImageWidth() - 10, 10,
                            $im->getImageWidth() - 10, 20,

                            $im->getImageWidth() - 10, $im->getImageHeight() - 10,
                            $im->getImageWidth() - 10, $im->getImageHeight() - 30);

    /* Effectue la déformation */
    $im->distortImage(Imagick::DISTORTION_PERSPECTIVE, $controlPoints, true);

    /* Envoie l'image */
    header("Content-Type: image/png");
    echo $im;
    ?>

Résultat de l'exemple ci-dessus est similaire à :

### Voir aussi

- Imagick::blurImage() - Ajoute un filtre de flou à une image
- Imagick::motionBlurImage() - Ajoute un flou de déplacement
- Imagick::radialBlurImage() - Flou radial d'une image

# Imagick::drawImage

(PECL imagick 2, PECL imagick 3)

Imagick::drawImage — Affiche un objet ImagickDraw dans l'image courante

### Description

public function Imagick::drawImage(ImagickDraw `$draw`): bool

Affiche un objet ImagickDraw dans l'image courante.

### Liste de paramètres

`draw`

  Les opérations de dessins pour dessiner l'image.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::edgeImage

(PECL imagick 2, PECL imagick 3)

Imagick::edgeImage — Renforce les bords dans l'image

### Description

public function Imagick::edgeImage(float `$radius`): bool

Renforce les bords dans l'image, avec un filtre de convolution, pour un rayon donné. Avec un rayon de zéro, Imagick va choisir lui-même la valeur du rayon.

### Liste de paramètres

`radius`

  Le rayon de l'opération.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::edgeImage()

    <?php
    function edgeImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->edgeImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::embossImage

(PECL imagick 2, PECL imagick 3)

Imagick::embossImage — Retourne une image en niveau de gris, avec un effet 3D

### Description

public function Imagick::embossImage(float `$radius`, float `$sigma`): bool

Retourne une image en niveau de gris, avec un effet 3D. Une convolution d'image avec opérateur gaussien est appliquée, avec un rayon et une déviation standard donnée. Pour des résultats raisonnables, le rayon doit être plus grand que sigma (la déviation standard). Un rayon de zéro conduit à laisser Imagick choisir sa valeur.

### Liste de paramètres

`radius`

  Le rayon de l'effet

`sigma`

  Le sigma de l'effet

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::embossImage()

    <?php
    function embossImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->embossImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::encipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::encipherImage — Chiffre une image

### Description

public function Imagick::encipherImage(string `$passphrase`): bool

Convertit les pixels en pixels chiffrés. L'image n'est plus lisible jusqu'à ce qu'elle ait été déchiffrée à l'aide de Imagick::decipherImage() Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.9 ou supérieur.

### Liste de paramètres

`passphrase`

  Le mot de passe.

### Valeurs de retour

Retourne `true` en cas de succès.

### Voir aussi

- Imagick::decipherImage() - Déchiffre une image

# Imagick::enhanceImage

(PECL imagick 2, PECL imagick 3)

Imagick::enhanceImage — Améliore la qualité d'une image bruitée

### Description

public function Imagick::enhanceImage(): bool

Améliore la qualité d'une image bruitée avec un filtre numérique.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::enhanceImage()

    <?php
    function enhanceImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->enhanceImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::equalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::equalizeImage — Égalise l'histogramme d'une image

### Description

public function Imagick::equalizeImage(): bool

Égalise l'histogramme d'une image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::equalizeImage()

    <?php
    function equalizeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->equalizeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::evaluateImage

(PECL imagick 2, PECL imagick 3)

Imagick::evaluateImage — Applique une expression à une image

### Description

public function Imagick::evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Applique une expression arithmétique, relationnelle ou logique à une image. Utiliser ces opérateurs pour éclaircir ou assombrir une image, pour augmenter ou réduire le contraste, ou encore, produire une image inversée.

### Liste de paramètres

`op`

  L'opérateur d'évaluation

`constant`

  La valeur de l'opérateur

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::evaluateImage()

Utilisation d'evaluateImage pour réduire l'opacité d'une image.

    <?php
    // Création d'un nouvel objet avec l'image
    $im = new Imagick('example-alpha.png');

    // Réduction de l'alpha de 50%
    $im->evaluateImage(Imagick::EVALUATE_DIVIDE, 2, Imagick::CHANNEL_ALPHA);

    // Affichage de l'image
    header("Content-Type: image/png");
    echo $im;
    ?>

# Imagick::exportImagePixels

(PECL imagick 2 >=2.3.0, PECL imagick 3)

Imagick::exportImagePixels — Exporte les pixels bruts de l'image

### Description

public function Imagick::exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array

Exporte les pixels de l'image dans un tableau. La carte définit l'ordre d'exportation des pixels. La taille du tableau retourné correspond à `width * height * strlen(map)`. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.7 ou supérieur.

### Liste de paramètres

`x`

  Coordonnée en X de l'espace exporté.

`y`

  Coordonnée en Y de l'espace exporté.

`width`

  Largeur de l'espace exporté.

`height`

  Hauteur de l'espace exporté.

`map`

  Ordre des pixels exportés. Par exemple, `"RGB"`. Les caractères valides pour la carte sont R, G, B, A, O, C, Y, M, K, I et P.

`STORAGE`

  Se référer à la liste des constantes de type pixel

### Valeurs de retour

Retourne un tableau contenant les valeurs des pixels.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::exportImagePixels()

Exportation des pixels de l'image dans un tableau.

    <?php

    /* Crée un nouvel objet */
    $im = new Imagick();

    /* Crée une nouvelle image */
    $im->newPseudoImage(0, 0, "magick:rose");

    /* Exporte les pixels de l'image */
    $pixels = $im->exportImagePixels(10, 10, 2, 2, "RGB", Imagick::PIXEL_CHAR);

    /* Affichage */
    var_dump($pixels);
    ?>

L'exemple ci-dessus va afficher :

    array(12) {
      [0]=>
      int(72)
      [1]=>
      int(64)
      [2]=>
      int(57)
      [3]=>
      int(69)
      [4]=>
      int(59)
      [5]=>
      int(43)
      [6]=>
      int(124)
      [7]=>
      int(120)
      [8]=>
      int(-96)
      [9]=>
      int(91)
      [10]=>
      int(84)
      [11]=>
      int(111)
    }

# Imagick::extentImage

(PECL imagick 2, PECL imagick 3)

Imagick::extentImage — Définit la taille de l'image

### Description

public function Imagick::extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Cette méthode est utile pour définir la taille de l'image. La méthode définit la taille de l'image et autorise la configuration des coordonnées x, y définissant le début du nouvel espace. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.1 ou supérieur.

Attention

Avant ImageMagick 6.5.7-8 (1623), $x était positif lors d'un déplacement vers la gauche, et négatif lors d'un déplacement vers la droite, et $y était positif lors d'un déplacement de l'image vers le haut, et négatif lors d'un déplacement de l'image vers le bas. Quelque part entre les versions ImageMagick 6.3.7 (1591) et ImageMagick 6.5.7-8 (1623), les axes de $x et $y ont été inversés, aussi, $x était négatif lors d'un déplacement vers la gauche et positif lors d'un déplacement vers la droite, et $y était négatif lors d'un déplacement de l'image vers le haut, et positif, lors d'un déplacement vers le bas. Quelque part entre les versions ImageMagick 6.5.7-8 (1623) et ImageMagick 6.6.9-7 (1641), le comportement est revenu tel qu'il était avant ImageMagick 6.5.7-8 (1623).

### Liste de paramètres

`width`

  La nouvelle largeur.

`height`

  La nouvelle hauteur.

`x`

  La position en X pour la nouvelle taille.

`y`

  La position en Y pour la nouvelle taille.

### Valeurs de retour

Retourne `true` en cas de succès.

### Voir aussi

- Imagick::resizeImage() - Redimensionne une image
- Imagick::thumbnailImage() - Modifie la taille d'une image
- Imagick::cropImage() - Extrait une région d'une image

# Imagick::filter

(PECL imagick 3 >= 3.3.0)

Imagick::filter — Applique un noyau de convolution personnalisé à l'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool

Applique un noyau de convolution personnalisé à l'image.

### Liste de paramètres

`ImagickKernel`

  Une instance de ImagickKernel qui représente soit un seul noyau, soit une série de noyaux liés.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::filter()

    <?php
    function filter($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $matrix = [
            [-1, 0, -1],
            [0,  5,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $strength = 0.5;
        $kernel->scale($strength, \Imagick::NORMALIZE_KERNEL_VALUE);
        $kernel->addUnityKernel(1 - $strength);

        $imagick->filter($kernel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::flattenImages

(PECL imagick 2, PECL imagick 3)

Imagick::flattenImages — Fusionne une séquence d'images

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::flattenImages(): Imagick

Fusionne une séquence d'images. Ceci est pratique pour combiner une série de couches Photoshop en une seule image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::flipImage

(PECL imagick 2, PECL imagick 3)

Imagick::flipImage — Crée une image par miroir vertical

### Description

public function Imagick::flipImage(): bool

Crée une image par miroir vertical, à l'aide d'une symétrie autour de l'axe des abscisses.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::flipImage()

    <?php
    function flipImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flipImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Voir aussi

- Imagick::flopimage() - Crée une image par miroir horizontal

# Imagick::floodFillPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::floodFillPaintImage — Modifie la valeur de la couleur de chaque pixel correspondant à la cible

### Description

public function Imagick::floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Modifie la valeur de la couleur de chaque pixel correspondant à la cible et qui se trouve dans le voisinage immédiat. Cette méthode est un remplacement de la méthode obsolète Imagick::paintFloodFillImage(). Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.8 ou supérieur.

### Liste de paramètres

`fill`

  Objet ImagickPixel ou une chaîne contenant la couleur de remplissage.

`fuzz`

  La quantité de poussière de papier. Par exemple, le fait de définir la poussière de papier à 10 et la couleur rouge à une intensité de 100 et de 102 ne sera pas interprété comme la même couleur.

`target`

  Objet ImagickPixel ou une chaîne contenant la couleur cible à peindre.

`x`

  Position de départ en X du pot de peinture.

`y`

  Position de départ en Y du pot de peinture.

`invert`

  Si vaut `true`, peint chaque pixel qui ne correspond pas à la couleur cible.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::floodfillPaintImage()

    <?php

    /* Crée un nouvel objet imagick */
    $im = new Imagick();

    /* Crée les images bleus, vertes et rouges */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Ajoute l'image dans une autre */
    $im->resetIterator();
    $combined = $im->appendImages(true);

    /* Sauvegarde de l'image intermédiaire pour comparaison */
    $combined->writeImage("floodfillpaint_intermediate.png");

    /* Le pixel cible à peindre */
    $x = 1;
    $y = 1;

    /* Récupère la couleur à utiliser pour peindre */
    $target = $combined->getImagePixelColor($x, $y);

    /* Peint le pixel à la position 1,1 en noir, ainsi que tous les pixels voisins
       qui correspondent à la couleur cible */
    $combined->floodfillPaintImage("black", 1, $target, $x, $y, false);

    /* Sauvegarde le résultat */
    $combined->writeImage("floodfillpaint_result.png");
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# Imagick::flopImage

(PECL imagick 2, PECL imagick 3)

Imagick::flopImage — Crée une image par miroir horizontal

### Description

public function Imagick::flopImage(): bool

Crée une image par miroir horizontal, à l'aide d'une symétrie autour de l'axe des ordonnées.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::flopImage()

    <?php
    function flopImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flopImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Voir aussi

- Imagick::flipimage() - Crée une image par miroir vertical

# Imagick::forwardFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::forwardFourierTransformImage — Implémente la transformée de Fourier discrète (Discrete Fourier Transform - DFT)

### Description

public function Imagick::forwardFourierTransformimage(bool `$magnitude`): bool

Implémente la transformée de Fourier discrète (DFT) de l'image soit en tant que paire d'images magnitude / phase, soit en tant que paire d'images réelles / imaginaires.

### Liste de paramètres

`magnitude`

  Si vrai, retourne en tant que paire magnitude / phase, sinon une paire d'images réelles / imaginaires.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::forwardFourierTransformImage()

    <?php
    //Utility function for forwardTransformImage
    function createMask() {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(0);
        $draw->setStrokeColor('rgb(255, 255, 255)');
        $draw->setFillColor('rgb(255, 255, 255)');

        // Dessine un cercle sur l'axe des y, avec son centre
        // à x, y qui touche l'origine
        $draw->circle(250, 250, 220, 250);

        $imagick = new \Imagick();
        $imagick->newImage(512, 512, "black");
        $imagick->drawImage($draw);
        $imagick->gaussianBlurImage(20, 20);
        $imagick->autoLevelImage();

        return $imagick;
    }

    function forwardFourierTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->resizeimage(512, 512, \Imagick::FILTER_LANCZOS, 1);

        $mask = createMask();
        $imagick->forwardFourierTransformImage(true);

        @$imagick->setimageindex(0);
        $magnitude = $imagick->getimage();

        @$imagick->setimageindex(1);
        $imagickPhase = $imagick->getimage();

        if (true) {
            $imagickPhase->compositeImage($mask, \Imagick::COMPOSITE_MULTIPLY, 0, 0);
        }

        if (false) {
            $output = clone $imagickPhase;
            $output->setimageformat('png');
            header("Content-Type: image/png");
            echo $output->getImageBlob();
        }

        $magnitude->inverseFourierTransformImage($imagickPhase, true);

        $magnitude->setimageformat('png');
        header("Content-Type: image/png");
        echo $magnitude->getImageBlob();
    }

    ?>

# Imagick::frameImage

(PECL imagick 2, PECL imagick 3)

Imagick::frameImage — Ajoute un bord 3D

### Description

public function Imagick::frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool

Ajoute un bord 3D. La largeur et la hauteur configurent la largeur et la hauteur de la bordure du cadre. Le chanfrein intérieur et extérieur indique la largeur de l'ombre interne et externe.

### Liste de paramètres

`matte_color`

  Un objet ImagickPixel ou une chaîne représentant la couleur

`width`

  La largeur de la bordure

`height`

  La hauteur de la bordure

`inner_bevel`

  La largeur du chanfrein intérieur

`outer_bevel`

  La largeur du chanfrein extérieur

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

### Exemples

Exemple #1 Exemple avec Imagick::frameImage()

    <?php
    function frameImage($imagePath, $color, $width, $height, $innerBevel, $outerBevel) {
        $imagick = new \Imagick(realpath($imagePath));

        $width = $width + $innerBevel + $outerBevel;
        $height = $height + $innerBevel + $outerBevel;

        $imagick->frameimage(
            $color,
            $width,
            $height,
            $innerBevel,
            $outerBevel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::functionImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::functionImage — Applique une fonction sur l'image

### Description

public function Imagick::functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Applique une expression arithmétique, relationnelle ou logique à une pseudo-image.

Voir aussi les » exemples d'ImageMagick v6 - Transformations d'images — Fonction, évaluation de plusieurs arguments.

Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.9 ou supérieur.

### Liste de paramètres

`function`

  Se référer à la liste des constantes de fonction.

`arguments`

  Tableau d'arguments à passer à la fonction.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Crée un gradient sinusoïdal

    <?php
    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(3, -90);
    $imagick->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    header("Content-Type: image/png");
    $imagick->setImageFormat("png");
    echo $imagick->getImageBlob();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Exemple #2 Crée un gradient depuis le polynôme (4x^2 - 4x + 1)

    <?php
    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(4, -4, 1);
    $imagick->functionImage(Imagick::FUNCTION_POLYNOMIAL, $arguments);

    header("Content-Type: image/png");
    $imagick->setimageformat("png");
    echo $imagick->getImageBlob();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

Exemple #3 Crée un gradient complexe depuis le polynôme (4x^2 - 4x^2 + 1) modulé par un gradient sinusoïdal

    <?php
    $imagick1 = new Imagick();
    $imagick1->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(9, -90);
    $imagick1->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    $imagick2 = new Imagick();
    $imagick2->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(0.5, 0);
    $imagick2->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);
    $imagick1->compositeimage($imagick2, Imagick::COMPOSITE_MULTIPLY, 0, 0);

    header("Content-Type: image/png");
    $imagick1->setImageFormat("png");
    echo $imagick1->getImageBlob();
    ?>

Résultat de l'exemple ci-dessus est similaire à :

# Imagick::fxImage

(PECL imagick 2, PECL imagick 3)

Imagick::fxImage — Évalue une expression pour chaque pixel d'une image

### Description

public function Imagick::fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick

Évalue une expression pour chaque pixel d'une image. Consulter » `The Fx Special Effects Image Operator` pour plus de détails (en anglais).

### Liste de paramètres

`expression`

  L'expression.

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::fxImage()

    <?php
    function fxImage() {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(200, 200, "xc:white");

        $fx = 'xx=i-w/2; yy=j-h/2; rr=hypot(xx,yy); (.5-rr/140)*1.2+.5';
        $fxImage = $imagick->fxImage($fx);

        header("Content-Type: image/png");
        $fxImage->setimageformat('png');
        echo $fxImage->getImageBlob();
    }

    ?>

# Imagick::gammaImage

(PECL imagick 2, PECL imagick 3)

Imagick::gammaImage — Applique une correction gamma à l'image

### Description

public function Imagick::gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Applique une correction gamma à l'image. La même image vue sur différents écrans aura des différences de perception dans la représentation des intensités. Spécifier des corrections gamma individuelles pour les différentes couleurs, ou bien ajuster les trois corrections gamma d'un seul coup. Les valeurs typiques vont de 0.8 à 2.3.

### Liste de paramètres

`gamma`

  La correction gamma.

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::gammaImage()

    <?php
    function gammaImage($imagePath, $gamma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gammaImage($gamma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::gaussianBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::gaussianBlurImage — Ajoute du flou à une image

### Description

public function Imagick::gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Ajoute du flou à une image. Une convolution est appliquée avec un rayon et une déviation standard données. Pour des résultats raisonnables, il est recommandé d'utiliser une taille de rayon supérieure à sigma. Un rayon de zéro force la fonction à choisir les valeurs.

### Liste de paramètres

`radius`

  Le rayon de la gaussienne, en pixels, sans compter le pixel du centre.

`sigma`

  La déviation standard de la gaussienne, en pixels.

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::gaussianBlurImage()

    <?php
    function gaussianBlurImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gaussianBlurImage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::getColorspace

(PECL imagick 3)

Imagick::getColorspace — Récupère l'espace de couleurs

### Description

public function Imagick::getColorspace(): int

Récupère la valeur globale de l'espace de couleurs. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.5.7 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier qui peut être comparé avec les constantes COLORSPACE.

# Imagick::getCompression

(PECL imagick 2, PECL imagick 3)

Imagick::getCompression — Lit le type de compression

### Description

public function Imagick::getCompression(): int

Lit le type de compression.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la constante de compression.

# Imagick::getCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::getCompressionQuality — Lit la qualité de la compression

### Description

public function Imagick::getCompressionQuality(): int

Lit la qualité de la compression.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier décrivant la qualité de la compression.

# Imagick::getCopyright

(PECL imagick 2, PECL imagick 3)

Imagick::getCopyright — Retourne le copyright de l'API ImageMagick

### Description

public static function Imagick::getCopyright(): string

Retourne le copyright de l'API ImageMagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne, en cas de succès.

# Imagick::getFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getFilename — Lit le nom du fichier associé à une séquence

### Description

public function Imagick::getFilename(): string

Lit le nom du fichier associé à une séquence.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getFont — Récupère la police de caractères

### Description

public function Imagick::getFont(): string

Retourne la propriété de la police de caractères de l'objet. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.7 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne de caractères contenant le nom de la police de caractères ou `false` si la police n'est pas définie.

### Voir aussi

- Imagick::setFont() - Configure la police
- ImagickDraw::setFont() - Configure la police complète pour les textes
- ImagickDraw::getFont() - Retourne la police

# Imagick::getFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getFormat — Retourne le format de l'image Imagick

### Description

public function Imagick::getFormat(): string

Retourne le format de l'image Imagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le format de l'image Imagick.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getGravity

(PECL imagick 2, PECL imagick 3)

Imagick::getGravity — Récupère la gravité

### Description

public function Imagick::getGravity(): int

Récupère la propriété globale de la gravité pour l'objet Imagick. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.0 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la propriété de gravité. Se référer à la liste des constantes de gravité.

# Imagick::getHomeURL

(PECL imagick 2, PECL imagick 3)

Imagick::getHomeURL — Retourne l'URL de ImageMagick

### Description

public static function Imagick::getHomeURL(): string

Retourne l'URL de ImageMagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'URL de ImageMagick.

# Imagick::getImage

(PECL imagick 2, PECL imagick 3)

Imagick::getImage — Retourne un nouvel objet Imagick

### Description

public function Imagick::getImage(): Imagick

Retourne un nouvel objet Imagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un nouvel objet Imagick.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageAlphaChannel

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageAlphaChannel — Vérifie si l'image a un canal alpha

### Description

public function Imagick::getImageAlphaChannel(): bool

Retourne si l'image a un canal alpha.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'image a une valeur de canal alpha et `false` sinon, c'est-à-dire que l'image est RGB plutôt que RGBA ou CMYK plutôt que CMYKA.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 3.6.0 | Retourne un booléen maintenant ; auparavant, un entier était retourné.

# Imagick::getImageArtifact

(PECL imagick 3)

Imagick::getImageArtifact — Récupère l'artefact de l'image

### Description

public function Imagick::getImageArtifact(string `$artifact`): string

Récupère l'artefact associé à l'image. La différence entre les propriétés de l'image et les artefacts de l'image est que les propriétés sont publiques, alors que les artefacts sont privés. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.5.7 ou supérieur.

### Liste de paramètres

`artifact`

  Le nom de l'artefact.

### Valeurs de retour

Retourne la valeur de l'artefact en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Voir aussi

- Imagick::setImageArtifact() - Définit l'artefact de l'image
- Imagick::deleteImageArtifact() - Supprime l'artefact d'une image

# Imagick::getImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::getImageAttribute — Obtient un attribut nommé

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::getImageAttribute(string `$key`): string

Obtient un attribut nommé.

### Liste de paramètres

`key`

  La clé de l'attribut à obtenir.

### Valeurs de retour

# Imagick::getImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBackgroundColor — Retourne la couleur de fond

### Description

public function Imagick::getImageBackgroundColor(): ImagickPixel

Retourne la couleur de fond.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la couleur de fond sous forme d'objet ImagickPixel.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBlob — Retourne la séquence d'images comme un blob

### Description

public function Imagick::getImageBlob(): string

Implémente un formatage direct en mémoire. Il retourne la séquence d'images sous forme de chaîne. Le format de l'image détermine le format du BLOB retourné (GIF, JPEG, PNG, etc.). Pour retourner un format différent, utiliser Imagick::setImageFormat().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne contenant les images.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBluePrimary — Retourne la chromaticité de la couleur bleue

### Description

public function Imagick::getImageBluePrimary(): array

Retourne la chromaticité de la couleur bleue. Retourne un tableau avec les clés "x" et "y".

### Liste de paramètres

`x`

  L'abscisse du point.

`y`

  L'ordonnée du point.

### Valeurs de retour

Retourne un tableau avec les clés "x" et "y", en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBorderColor — Retourne la couleur de bordure de l'image

### Description

public function Imagick::getImageBorderColor(): ImagickPixel

Retourne la couleur de bordure de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDepth — Lit la profondeur d'un des canaux de l'image

### Description

public function Imagick::getImageChannelDepth(int `$channel`): int

Lit la profondeur d'un des canaux de l'image.

### Liste de paramètres

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::getImageChannelDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDistortion — Compare les canaux d'une image reconstituée

### Description

public function Imagick::getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float

Compare un ou plusieurs canaux d'une image reconstituée et retourne la métrique de déformation demandée.

### Liste de paramètres

`reference`

  L'objet Imagick avec lequel se comparer.

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

`metric`

  Une des constantes de type de métrique.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageChannelDistortions

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelDistortions — Récupère les distorsions d'un canal

### Description

public function Imagick::getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float

Compare un ou plusieurs canaux d'une image avec une image reconstruite, et retourne les mesures de la distorsion spécifiée. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.

### Liste de paramètres

`reference`

  Objet Imagick contenant la référence de l'image.

`metric`

  Se référer à la liste des constantes de type de mesures.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne un float, décrivant la distorsion du canal.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageChannelExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelExtrema — Lit les extrêmes pour les canaux de l'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::getImageChannelExtrema(int `$channel`): array

Lit les extrêmes pour l'un ou plusieurs canaux de l'image. La valeur retournée est un tableau associatif avec les clés "minima" et "maxima".

### Liste de paramètres

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageChannelKurtosis

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelKurtosis — Le but de getImageChannelKurtosis

### Description

public function Imagick::getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array

Récupère le kurtosis et l'asymétrie d'un canal spécifique. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.9 ou supérieur.

### Liste de paramètres

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne un tableau avec les membres `kurtosis` et `skewness`.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageChannelMean

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelMean — Lit la moyenne et la déviation standard

### Description

public function Imagick::getImageChannelMean(int `$channel`): array

Récupère la moyenne et la déviation standard d'un ou plusieurs des canaux de l'image.

### Liste de paramètres

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne un tableau avec les membres `"mean"` et `"standardDeviation"`.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageChannelRange

(PECL imagick 2 >= 2.2.1, PECL imagick 3)

Imagick::getImageChannelRange — Récupère l'intervalle du canal

### Description

public function Imagick::getImageChannelRange(int `$channel`): array

Récupère l'intervalle pour un ou plusieurs canaux de l'image. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.0 ou supérieur.

### Liste de paramètres

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne un tableau contenant les valeurs minimales et maximales du ou des canaux.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageChannelStatistics

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelStatistics — Retourne des statistiques sur chaque canal de l'image

### Description

public function Imagick::getImageChannelStatistics(): array

Retourne des statistiques sur chaque canal de l'image. Les statistiques incluent la profondeur du canal, ses minima et maxima, la moyenne, et la déviation standard.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::getImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageClipMask — Récupère le masque du clip de l'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::getImageClipMask(): Imagick

Retourne le masque du clip de l'image. Le masque du clip est un objet Imagick contenant le masque du clip. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet Imagick contenant le masque du clip.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColormapColor — Retourne la couleur à l'index de la carte de couleurs

### Description

public function Imagick::getImageColormapColor(int `$index`): ImagickPixel

Retourne la couleur à l'index de la carte de couleurs.

### Liste de paramètres

`index`

  La position dans la carte des couleurs.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageColors

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColors — Lit le nombre de couleurs uniques de l'image

### Description

public function Imagick::getImageColors(): int

Lit le nombre de couleurs uniques de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un int, le nombre de couleurs uniques dans l'image.

# Imagick::getImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColorspace — Lit l'espace de couleurs de l'image

### Description

public function Imagick::getImageColorspace(): int

Lit l'espace de couleurs de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier qui peut être comparé aux constantes COLORSPACE.

# Imagick::getImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageCompose — Retourne l'opérateur de composition associé à une image

### Description

public function Imagick::getImageCompose(): int

Retourne l'opérateur de composition associé à une image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::getImageCompression

(PECL imagick 3 >= 3.3.0)

Imagick::getImageCompression — Lit le type de compression de l'image

### Description

public function Imagick::getImageCompression(): int

Lit le type de compression de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une constante de compression.

# Imagick::getImageCompressionQuality

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::getImageCompressionQuality — Lit la qualité de compression de l'image

### Description

public function Imagick::getImageCompressionQuality(): int

Lit la qualité de compression de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier qui décrit la qualité de la compression de l'image.

# Imagick::getImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDelay — Lit le délai de l'image

### Description

public function Imagick::getImageDelay(): int

Lit le délai de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le délai de l'image. Émet une exception ImagickException en cas d'échec.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDepth — Lit la profondeur de l'image

### Description

public function Imagick::getImageDepth(): int

Lit la profondeur de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La profondeur de l'image.

# Imagick::getImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDispose — Lit la méthode de récupération

### Description

public function Imagick::getImageDispose(): int

Lit la méthode de récupération.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la méthode de récupération en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDistortion — Compare une image à une image reconstituée

### Description

public function Imagick::getImageDistortion(MagickWand `$reference`, int `$metric`): float

Compare une image à une image reconstituée et retourne une métrique.

### Liste de paramètres

`reference`

  L'objet Imagick avec lequel se comparer.

`metric`

  Une des constantes de type de métrique.

### Valeurs de retour

Retourne la métrique de déformation (ou la meilleure évaluation possible).

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageExtrema — Lit les extrêmes d'une image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::getImageExtrema(): array

Lit les extrêmes d'une image. Retourne un tableau associatif, avec les clés "min" et "max".

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif, avec les clés "min" et "max".

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFilename — Retourne le nom d'un fichier pour une image dans une séquence

### Description

public function Imagick::getImageFilename(): string

Retourne le nom d'un fichier pour une image dans une séquence.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne avec le nom du fichier de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFormat — Retourne le format d'une image dans une séquence

### Description

public function Imagick::getImageFormat(): string

Retourne le format d'une image dans une séquence.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le format d'une image dans une séquence.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGamma — Lit le gamma de l'image

### Description

public function Imagick::getImageGamma(): float

Lit le gamma de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le gamma de l'image en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageGeometry

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGeometry — Lit les dimensions de l'image dans un tableau

### Description

public function Imagick::getImageGeometry(): array

Retourne la largeur et la hauteur de l'image sous forme de tableau associatif.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau avec les dimensions de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Utilisation de Imagick::getImageGeometry()

    <?php
    $imagick = new Imagick();
    $imagick->newImage(100, 200, "black");
    print_r($imagick->getImageGeometry());
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [width] => 100
        [height] => 200
    )

# Imagick::getImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageGravity — Récupère la gravité de l'image

### Description

public function Imagick::getImageGravity(): int

Récupère la valeur de la gravité courante de l'image. Contrairement à la méthode Imagick::getGravity(), cette méthode retourne la gravité définie pour la séquence courante de l'image. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la propriété de la gravité de l'image. Se référer à la liste des constantes de gravité.

# Imagick::getImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGreenPrimary — Retourne la chromaticité de la couleur verte

### Description

public function Imagick::getImageGreenPrimary(): array

Retourne la chromaticité de la couleur verte. Retourne un tableau avec les clés "x" et "y".

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau avec les clés "x" et "y", en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageHeight

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHeight — Retourne la hauteur de l'image

### Description

public function Imagick::getImageHeight(): int

Retourne la hauteur de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la hauteur de l'image en pixels.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageHistogram

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHistogram — Retourne l'histogramme de l'image

### Description

public function Imagick::getImageHistogram(): array

Retourne l'histogramme de l'image, sous forme d'un tableau d'objets ImagickPixel.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau d'objets ImagickPixel. Émet une exception ImagickException en cas d'échec.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::getImageHistogram()

    <?php
    function getColorStatistics($histogramElements, $colorChannel) {
        $colorStatistics = [];

        foreach ($histogramElements as $histogramElement) {
            $color = $histogramElement->getColorValue($colorChannel);
            $color = intval($color * 255);
            $count = $histogramElement->getColorCount();

            if (array_key_exists($color, $colorStatistics)) {
                $colorStatistics[$color] += $count;
            }
            else {
                $colorStatistics[$color] = $count;
            }
        }

        ksort($colorStatistics);

        return $colorStatistics;
    }

    function getImageHistogram($imagePath) {

        $backgroundColor = 'black';

        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(0); // rend les lignes les plus fines possible

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        $histogramWidth = 256;
        $histogramHeight = 100; // la hauteur de chaque segment RGB

        $imagick = new \Imagick(realpath($imagePath));
        //Resize the image to be small, otherwise PHP tends to run out of memory
        //This might lead to bad results for images that are pathologically 'pixelly'
        $imagick->adaptiveResizeImage(200, 200, true);
        $histogramElements = $imagick->getImageHistogram();

        $histogram = new \Imagick();
        $histogram->newpseudoimage($histogramWidth, $histogramHeight * 3, 'xc:black');
        $histogram->setImageFormat('png');

        $getMax = function ($carry, $item)  {
            if ($item > $carry) {
                return $item;
            }
            return $carry;
        };

        $colorValues = [
            'red' => getColorStatistics($histogramElements, \Imagick::COLOR_RED),
            'lime' => getColorStatistics($histogramElements, \Imagick::COLOR_GREEN),
            'blue' => getColorStatistics($histogramElements, \Imagick::COLOR_BLUE),
        ];

        $max = array_reduce($colorValues['red'] , $getMax, 0);
        $max = array_reduce($colorValues['lime'] , $getMax, $max);
        $max = array_reduce($colorValues['blue'] , $getMax, $max);

        $scale =  $histogramHeight / $max;

        $count = 0;
        foreach ($colorValues as $color => $values) {
            $draw->setstrokecolor($color);

            $offset = ($count + 1) * $histogramHeight;

            foreach ($values as $index => $value) {
                $draw->line($index, $offset, $index, $offset - ($value * $scale));
            }
            $count++;
        }

        $histogram->drawImage($draw);

        header( "Content-Type: image/png" );
        echo $histogram;
    }

    ?>

# Imagick::getImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIndex — Lit l'index de l'image courante

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::getImageIndex(): int

Retourne l'index de l'image courante dans la séquence Imagick. Cette méthode est obsolète. Se reporter à la fonction Imagick::getIteratorIndex().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterlaceScheme — Lit le schéma d'entrelacement de l'image

### Description

public function Imagick::getImageInterlaceScheme(): int

Lit le schéma d'entrelacement de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le schéma d'entrelacement de l'image en cas de succès. Émet une exception ImagickException en cas d'échec.

# Imagick::getImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterpolateMethod — Retourne la méthode d'interpolation

### Description

public function Imagick::getImageInterpolateMethod(): int

Retourne la méthode d'interpolation de l'image spécifiée. La méthode est une des constantes `Imagick::INTERPOLATE_*`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la méthode d'interpolation en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIterations — Lit les itérations de l'image

### Description

public function Imagick::getImageIterations(): int

Lit les itérations de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les itérations de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageLength

(PECL imagick 2, PECL imagick 3)

Imagick::getImageLength — Retourne la taille de l'image en octets

### Description

public function Imagick::getImageLength(): int

Retourne la taille de l'image en octets.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier.

### Exemples

Exemple #1 Exemple avec Imagick::getImageLength():

Récupère la taille de l'image, en octets

    <?php
    $image = new Imagick('test.jpg');
    echo $image->getImageLength() . ' octets';
    ?>

# Imagick::getImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatte — Indique si l'image a un canal mat

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::getImageMatte(): bool

Retourne `true` si l'image a un canal mat, et sinon, `false` Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::getImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatteColor — Retourne la couleur mate de l'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::getImageMatteColor(): ImagickPixel

Retourne la couleur mate de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet ImagickPixel en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageMimeType

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageMimeType — Renvoie le type MIME de l'image

### Description

public function Imagick::getImageMimeType(): string

Renvoie le type MIME de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# Imagick::getImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::getImageOrientation — Lit l'orientation de l'image

### Description

public function Imagick::getImageOrientation(): int

Lit l'orientation de l'image. La valeur retournée est une des constantes d'orientation.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePage — Retourne la géométrie de la page

### Description

public function Imagick::getImagePage(): array

Retourne la géométrie de la page d'une image, sous la forme d'un tableau avec les clés `"width"`, `"height"`, `"x"` et `"y"`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la géométrie de la page d'une image, sous la forme d'un tableau avec les clés `"width"`, `"height"`, `"x"` et `"y"`.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImagePixelColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePixelColor — Retourne la couleur d'un pixel

### Description

public function Imagick::getImagePixelColor(int `$x`, int `$y`): ImagickPixel

Retourne la couleur d'un pixel.

### Liste de paramètres

`x`

  L'abscisse du pixel

`y`

  L'ordonnée du pixel

### Valeurs de retour

Retourne un objet ImagickPixel qui représente la couleur, pour ces coordonnées.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfile — Retourne un profil d'une image

### Description

public function Imagick::getImageProfile(string `$name`): string

Retourne un profil d'une image, à partir de son nom.

### Liste de paramètres

`name`

  Le nom du profil à lire.

### Valeurs de retour

Retourne une chaîne contenant le profil de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageProfiles

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfiles — Retourne les profils de l'image

### Description

public function Imagick::getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array

Retourne les profils de l'image qui correspondent à un modèle. Si `false` est passé comme second paramètre, seuls les noms des profils sont retournés. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`pattern`

  Le modèle de profil à lire.

`include_values`

  S'il faut retourner seulement les noms des profils. Si `false` est fourni, seuls les noms des profils seront retournés.

### Valeurs de retour

Retourne un tableau avec les profils de l'image, ou bien seulement les noms des profils.

# Imagick::getImageProperties

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperties — Retourne les propriétés EXIF de l'image

### Description

public function Imagick::getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array

Retourne toutes les propriétés de l'image, qui satisfont un modèle. Si `false` est passé comme second paramètre, seuls les noms des propriétés sont retournés. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`pattern`

  Le modèle pour les noms de propriétés.

`include_values`

  S'il faut retourner uniquement les noms des propriétés. Si `false` est fourni, alors seuls les noms des propriétés seront retournés.

### Valeurs de retour

Retourne un tableau contenant les propriétés de l'image, ou leurs noms.

### Exemples

Exemple #1 Exemple avec Imagick::getImageProperties()

Exemple d'extraction d'informations EXIF.

    <?php

    /* Crée un objet */
    $im = new imagick("/path/to/example.jpg");

    /* Lit les informations EXIF */
    $exifArray = $im->getImageProperties("exif:*");

    /* Passe en revue les propriétés EXIF */
    foreach ($exifArray as $name => $property)
    {
        echo "{$name} => {$property}<br />\n";
    }

    ?>

# Imagick::getImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperty — Retourne une propriété d'une image

### Description

public function Imagick::getImageProperty(string `$name`): string

Retourne une propriété d'une image. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.

### Liste de paramètres

`name`

  Le nom de la propriété (par exemple, `Exif:DateTime`)

### Valeurs de retour

Retourne une propriété d'une image, ou `false` si le nom demandé n'existe pas.

### Exemples

Exemple #1 Exemple avec Imagick::getImageProperty()

Définition et récupération des propriétés de l'image.

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Voir aussi

- Imagick::setImageProperty() - Configure une propriété d'image

# Imagick::getImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRedPrimary — Retourne la chromaticité du point rouge

### Description

public function Imagick::getImageRedPrimary(): array

Retourne la chromaticité du point rouge sous la forme d'un tableau avec les clés "x" et "y".

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la chromaticité du point rouge sous la forme d'un tableau avec les clés "x" et "y". Émet une exception ImagickException en cas d'échec.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageRegion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRegion — Extrait une région d'une image

### Description

public function Imagick::getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick

Extrait une région d'une image et la retourne sous la forme d'un nouvel objet Imagick.

### Liste de paramètres

`width`

  La largeur de la région extraite.

`height`

  La hauteur de la région extraite.

`x`

  L'abscisse du coin supérieur gauche de la région extraite.

`y`

  L'ordonnée du coin supérieur gauche de la région extraite.

### Valeurs de retour

Extrait une région d'une image et la retourne sous la forme d'un nouvel objet Imagick.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRenderingIntent — Lit la méthode de rendu de l'image

### Description

public function Imagick::getImageRenderingIntent(): int

Lit la méthode de rendu de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la constante de rendu.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::getImageResolution — Lit les résolutions en X et Y d'une image

### Description

public function Imagick::getImageResolution(): array

Lit les résolutions en X et Y d'une image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Lit les résolutions en X et Y d'une image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImagesBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImagesBlob — Retourne toutes les images de la séquence en un BLOB

### Description

public function Imagick::getImagesBlob(): string

Implémente le formatage direct en mémoire. Il retourne toutes les images de la séquence sous forme de chaîne. Le format de l'image détermine le format du BLOB retourné (GIF, JPEG, PNG, etc.). Pour retourner un format d'image différent, utiliser Imagick::setImageFormat().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne contenant toutes les images. Émet une exception ImagickException en cas d'échec.

# Imagick::getImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::getImageScene — Retourne la scène de l'image

### Description

public function Imagick::getImageScene(): int

Retourne la scène de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la scène de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageSignature

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSignature — Génère une signature SHA-256

### Description

public function Imagick::getImageSignature(): string

Génère une signature SHA-256 de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne une chaîne contenant la signature SHA-256 de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageSize

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSize — Retourne la taille de l'image en octets

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::getImageSize(): int

Retourne la taille de l'image en octets. Cette méthode est obsolète en faveur de la méthode Imagick::getImageLength()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier représentant la taille de l'image en octets.

# Imagick::getImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTicksPerSecond — Lit les ticks-par-seconde de l'image

### Description

public function Imagick::getImageTicksPerSecond(): int

Lit les ticks-par-seconde de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Lit les ticks-par-seconde de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageTotalInkDensity

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTotalInkDensity — Lit la densité totale d'encre de l'image

### Description

public function Imagick::getImageTotalInkDensity(): float

Lit la densité totale d'encre de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Lit la densité totale d'encre de l'image. Émet une exception ImagickException en cas d'échec.

# Imagick::getImageType

(PECL imagick 2, PECL imagick 3)

Imagick::getImageType — Lit le type possible d'image

### Description

public function Imagick::getImageType(): int

Retourne le type possible d'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Lit le type possible d'image.

- `imagick::IMGTYPE_UNDEFINED`
- `imagick::IMGTYPE_BILEVEL`
- `imagick::IMGTYPE_GRAYSCALE`
- `imagick::IMGTYPE_GRAYSCALEMATTE`
- `imagick::IMGTYPE_PALETTE`
- `imagick::IMGTYPE_PALETTEMATTE`
- `imagick::IMGTYPE_TRUECOLOR`
- `imagick::IMGTYPE_TRUECOLORMATTE`
- `imagick::IMGTYPE_COLORSEPARATION`
- `imagick::IMGTYPE_COLORSEPARATIONMATTE`
- `imagick::IMGTYPE_OPTIMIZE`

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::getImageUnits — Retourne les unités de résolution de l'image

### Description

public function Imagick::getImageUnits(): int

Retourne les unités de résolution de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne les unités de résolution de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageVirtualPixelMethod — Retourne la méthode du pixel virtuel

### Description

public function Imagick::getImageVirtualPixelMethod(): int

Retourne la méthode du pixel virtuel pour l'image spécifiée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la méthode du pixel virtuel pour l'image spécifiée.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWhitePoint — Retourne la chromaticité du point blanc

### Description

public function Imagick::getImageWhitePoint(): array

Retourne la chromaticité du point blanc, sous la forme d'un tableau associatif avec les clés "x" et "y".

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la chromaticité du point blanc, sous la forme d'un tableau associatif avec les clés "x" et "y".

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getImageWidth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWidth — Retourne la largeur de l'image

### Description

public function Imagick::getImageWidth(): int

Retourne la largeur de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la largeur de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getInterlaceScheme — Lit le schéma d'entrelacement de l'objet

### Description

public function Imagick::getInterlaceScheme(): int

Lit le schéma d'entrelacement de l'objet.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Lit la constante d'entrelacement.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getIteratorIndex — Lit l'index de l'image active courante

### Description

public function Imagick::getIteratorIndex(): int

Lit l'index de l'image active courante dans l'objet Imagick. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un entier représentant l'index de l'image dans la file d'attente.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::getIteratorIndex()

Crée des images, définit et récupère l'index de l'itérateur.

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Voir aussi

- Imagick::setIteratorIndex() - Déplace l'itérateur
- Imagick::getImageIndex() - Lit l'index de l'image courante
- Imagick::setImageIndex() - Modifie la position de l'itérateur

# Imagick::getNumberImages

(PECL imagick 2, PECL imagick 3)

Imagick::getNumberImages — Retourne le nombre d'images d'un objet

### Description

public function Imagick::getNumberImages(): int

Retourne le nombre d'images d'un objet Imagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre d'images d'un objet Imagick.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getOption

(PECL imagick 2, PECL imagick 3)

Imagick::getOption — Retourne la valeur d'une option

### Description

public function Imagick::getOption(string `$key`): string

Retourne la valeur d'une option pour l'objet Imagick.

### Liste de paramètres

`key`

  Le nom de l'option

### Valeurs de retour

Retourne la valeur associée à l'option.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getPackageName

(PECL imagick 2, PECL imagick 3)

Imagick::getPackageName — Retourne le nom du paquet ImageMagick

### Description

public static function Imagick::getPackageName(): string

Retourne le nom du paquet ImageMagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nom du paquet ImageMagick.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getPage

(PECL imagick 2, PECL imagick 3)

Imagick::getPage — Retourne la géométrie de la page

### Description

public function Imagick::getPage(): array

Retourne la géométrie de l'objet Imagick, sous forme d'un tableau associatif, avec les clés `"width"`, `"height"`, `"x"` et `"y"`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la géométrie de l'objet Imagick, sous forme d'un tableau associatif, avec les clés `"width"`, `"height"`, `"x"` et `"y"`. Émet une exception ImagickException en cas d'échec.

# Imagick::getPixelIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelIterator — Retourne un MagickPixelIterator

### Description

public function Imagick::getPixelIterator(): ImagickPixelIterator

Retourne un MagickPixelIterator.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un objet MagickPixelIterator.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::getPixelIterator()

    <?php
    function getPixelIterator($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelIterator();

        foreach ($imageIterator as $row => $pixels) { /* On parcourt les lignes de pixels */
            foreach ($pixels as $column => $pixel) { /* On parcourt les pixels dans la ligne (colonne) */
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    $pixel->setColor("rgba(0, 0, 0, 0)"); /* On peint tous les seconds pixels en noir */
                }
            }
            $imageIterator->syncIterator(); /* On synchronise l'itérateur, c'est important de le faire à chaque itération */
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# Imagick::getPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelRegionIterator — Lit un objet ImagickPixelIterator pour une section d'image

### Description

public function Imagick::getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator

Lit un objet ImagickPixelIterator pour une section d'image.

### Liste de paramètres

`x`

  L'abscisse de la région.

`y`

  L'ordonnée de la région.

`columns`

  La largeur de la région.

`rows`

  La hauteur de la région.

### Valeurs de retour

Retourne un objet ImagickPixelIterator pour une section d'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Imagick::getPixelRegionIterator() example

Itère sur les pixels du coin en haut à gauche de l'image, pour les peindre en noir.

    <?php
    $im = new Imagick(realpath("./testImage.png"));
    $areaIterator = $im->getPixelRegionIterator(0, 0, 10, 10);

    foreach ($areaIterator as $rowIterator) {
        foreach ($rowIterator as $pixel) {
            // Peint les pixels en noir
            $pixel->setColor("rgba(0, 0, 0, 0)");
        }
        $areaIterator->syncIterator();
    }
    $im->writeImage("./output.png");
    ?>

# Imagick::getPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getPointSize — Récupère la taille du point

### Description

public function Imagick::getPointSize(): float

Retourne la propriété de la taille du point de l'objet. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.7 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un nombre décimal contenant la taille du point.

### Voir aussi

- Imagick::setPointSize() - Définit la taille du point

# Imagick::getQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::getQuantum — Renvoie la plage quantique d'ImageMagick

### Description

public static function Imagick::getQuantum(): int

Renvoie la plage quantique d'ImageMagick. Si HDRI est activé, le type est un flottant, sinon c'est un entier.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# Imagick::getQuantumDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumDepth — Lit la profondeur quantique

### Description

public static function Imagick::getQuantumDepth(): array

Retourne la profondeur quantique.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau avec les membres `"quantumDepthLong"` et `"quantumDepthString"`.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getQuantumRange

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumRange — Retourne l'intervalle quantique de Imagick

### Description

public static function Imagick::getQuantumRange(): array

Retourne l'intervalle quantique de l'instance Imagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif contenant l'intervalle quantique sous la forme d'un entier (`"quantumRangeLong"`) et sous la forme d'une chaîne de caractères (`"quantumRangeString"`).

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::getRegistry — Obtient un élément de StringRegistry

### Description

public static function Imagick::getRegistry(string `$key`): string

Obtient l'entrée StringRegistry pour la clé nommée ou false si elle n'est pas définie.

### Liste de paramètres

`key`

  L'entrée à obtenir.

### Valeurs de retour

# Imagick::getReleaseDate

(PECL imagick 2, PECL imagick 3)

Imagick::getReleaseDate — Retourne la date de publication de ImageMagick

### Description

public static function Imagick::getReleaseDate(): string

Retourne la date de publication de ImageMagick, sous forme de chaîne.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la date de publication de ImageMagick, sous forme de chaîne.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getResource

(PECL imagick 2, PECL imagick 3)

Imagick::getResource — Retourne la consommation de mémoire de la ressource

### Description

public static function Imagick::getResource(int `$type`): int

Retourne la consommation de mémoire de la ressource, en mégaoctets.

### Liste de paramètres

`type`

  Voir la liste des constantes de type de ressources.

### Valeurs de retour

Retourne la consommation de mémoire de la ressource, en mégaoctets.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::getResourceLimit — Retourne la limite de la ressource

### Description

public static function Imagick::getResourceLimit(int `$type`): int

Retourne la limite de la ressource.

### Liste de paramètres

`type`

  L'une des constantes de type de ressources.

### Valeurs de retour

Retourne la limite de ressource spécifiée. L'unité dépend du type de ressource qui est limitée.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Voir aussi

- Imagick::setResourceLimit() - Définit la limite pour une ressource particulière

# Imagick::getSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::getSamplingFactors — Lit le facteur d'échantillonnage horizontal et vertical

### Description

public function Imagick::getSamplingFactors(): array

Lit le facteur d'échantillonnage horizontal et vertical.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau associatif avec les facteurs d'échantillonnage horizontal et vertical de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getSize

(PECL imagick 2, PECL imagick 3)

Imagick::getSize — Retourne la taille associée avec un objet Imagick

### Description

public function Imagick::getSize(): array

Obtenir la taille associée avec un objet Imagick, précédemment défini par Imagick::setSize().

> Note:

> Cette méthode retourne simplement la taille qui a été définie à l'aide de Imagick::setSize(). Pour obtenir la largeur/hauteur réelle de l'image, utiliser Imagick::getImageWidth() et Imagick::getImageHeight().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la taille associée avec un objet Imagick, sous forme de tableau, avec les clés "`columns`" (colonnes) et "`rows`" (lignes).

### Exemples

Exemple #1 Obtention de la taille d'une image RVB brute définie à 200x400, après mise à l'échelle à 400x800 (par rapport à la largeur/hauteur)

    <?php
    //Set size first and then load the raw image
    $img = new Imagick();
    $img->setSize(200, 400);
    $img->readImage("image.rgb");

    $img->scaleImage(400, 800);

    $size = $img->getSize();
    print_r($size);

    echo $img->getImageWidth()."x".$img->getImageHeight();
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [columns] => 200
        [rows] => 400
    )
    400x800

# Imagick::getSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::getSizeOffset — Retourne la taille de la position

### Description

public function Imagick::getSizeOffset(): int

Retourne la taille de la position associée avec l'objet Imagick. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la taille de la position associée avec l'objet Imagick.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::getVersion

(PECL imagick 2, PECL imagick 3)

Imagick::getVersion — Retourne la version de l'API ImageMagick

### Description

public static function Imagick::getVersion(): array

Retourne la version de l'API ImageMagick, sous forme de chaîne et de nombre.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la version de l'API ImageMagick, sous forme de chaîne et de nombre.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::haldClutImage

(PECL imagick 3)

Imagick::haldClutImage — Remplace les couleurs de l'image

### Description

public function Imagick::haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Remplace les couleurs de l'image en utilisant la table de correspondance Hald. Les images Hald peuvent être créées en utilisant le codeur de couleur HALD.

### Liste de paramètres

`clut`

  Objet Imagick contenant l'image de correspondance Hald.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::haldClutImage()

    <?php
    function haldClutImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagickPalette = new \Imagick(realpath("images/hald/hald_8.png"));
        $imagickPalette->sepiatoneImage(55);
        $imagick->haldClutImage($imagickPalette);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::hasNextImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasNextImage — Vérifie si un objet a une image suivante

### Description

public function Imagick::hasNextImage(): bool

Retourne `true` si l'objet a encore des images, pour passer en revue la liste.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'objet a une image suivante, et `false` sinon.

# Imagick::hasPreviousImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasPreviousImage — Vérifie si un objet a une image précédente

### Description

public function Imagick::hasPreviousImage(): bool

Retourne `true` si l'objet a une image précédente, pour pouvoir passer en revue la liste en ordre inverse.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` si l'objet a une image précédente, et `false` sinon.

# Imagick::identifyFormat

(PECL imagick 3 >= 3.3.0)

Imagick::identifyFormat — Formate une chaîne avec les détails de l'image

### Description

public function Imagick::identifyFormat(string `$embedText`): string|false

Remplace tous les caractères de formatage intégrés par la propriété d'image appropriée et renvoie le texte interprété. Voir http://www.imagemagick.org/script/escape.php pour les séquences d'échappement.

### Liste de paramètres

`embedText`

  Une chaîne contenant des séquences de formatage, par exemple "Boîte de rognage: %@ nombre de couleurs uniques: %k".

### Valeurs de retour

Renvoie le format ou `false` si une erreur survient.

### Exemples

Exemple #1 Imagick::identifyFormat()

    <?php
            $output = "Output of 'Trim box: %@ number of unique colors: %k' is: <br/>";
            $imagick = new \Imagick(realpath("./images/artifact/mask.png"));
            $output .= $imagick->identifyFormat("Trim box: %@ number of unique colors: %k");

    ?>

# Imagick::identifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::identifyImage — Identifie une image et lit ses attributs

### Description

public function Imagick::identifyImage(bool `$appendRawOutput` = `false`): array

Identifie une image et retourne ses attributs. Les attributs sont sa largeur, hauteur, taille et d'autres.

### Liste de paramètres

`appendRawOutput`

  Si `true`, la sortie brute est ajoutée au tableau

### Valeurs de retour

Identifie une image et retourne ses attributs. Les attributs sont sa largeur, hauteur, taille et d'autres.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple de format du résultat

    Array
    (
        [imageName] => /some/path/image.jpg
        [format] => JPEG (Joint Photographic Experts Group JFIF format)
        [geometry] => Array
            (
                [width] => 90
                [height] => 90
            )

        [type] => TrueColor
        [colorSpace] => RGB
        [resolution] => Array
            (
                [x] => 300
                [y] => 300
            )

        [units] => PixelsPerInch
        [fileSize] => 1.88672kb
        [compression] => JPEG
        [signature] => 9a6dc8f604f97d0d691c0286176ddf992e188f0bebba98494b2146ee2d7118da
    )

# Imagick::implodeImage

(PECL imagick 2, PECL imagick 3)

Imagick::implodeImage — Crée une nouvelle copie d'image

### Description

public function Imagick::implodeImage(float `$radius`): bool

Crée une nouvelle copie d'image, avec chaque pixel "implosé" par un pourcentage spécifique.

### Liste de paramètres

`radius`

  Le rayon de l'implosion

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::implodeImage()

    <?php
    function implodeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->implodeImage(0.0001);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# Imagick::importImagePixels

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::importImagePixels — Importe des pixels dans une image

### Description

public function Imagick::importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool

Importe des pixels depuis un tableau dans une image. Le paramètre `map` vaut généralement 'RGB'. Cette méthode impose les contraintes suivantes pour les paramètres : le nombre de pixels du tableau doit correspondre à la longueur `width` x `height` x de la carte. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.5 ou supérieur.

### Liste de paramètres

`x`

  La position en X de l'image.

`y`

  La position en Y de l'image.

`width`

  La largeur de l'image.

`height`

  La hauteur de l'image.

`map`

  La carte de l'ordre des pixels, sous la forme d'une chaîne de caractères. Par exemple `RGB`. La valeur peut être une combinaison ou un ordre de R = rouge, G = vert, B = bleu, A = alpha (0 correspond à transparent), O = opacité (0 correspond à opaque), C = cyan, Y = jaune, M = magenta, K = noir, I = intensité (pour les niveaux de gris), P = pad.

`storage`

  La méthode de stockage des pixels. Se référer à la liste des constantes de pixels.

`pixels`

  Le tableau de pixels.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::importImagePixels()

    <?php

    /* Génère un tableau de pixels. 2000 pixels par bande de couleurs */
    $count = 2000 * 3;

    $pixels =
       array_merge(array_pad(array(), $count, 0),
                   array_pad(array(), $count, 255),
                   array_pad(array(), $count, 0),
                   array_pad(array(), $count, 255),
                   array_pad(array(), $count, 0));

    /* Largeur et hauteur. L'espace correspond aux pixels, divisés
       par 3. 3 provient de 'RGB', 3 valeurs par pixel */
    $width = $height = pow((count($pixels) / 3), 0.5);

    /* Crée une image vide */
    $im = new Imagick();
    $im->newImage($width, $height, 'gray');

    /* Importe les pixels dans l'image.
       width * height * strlen("RGB") doit correspondre à count($pixels) */
    $im->importImagePixels(0, 0, $width, $height, "RGB", Imagick::PIXEL_CHAR, $pixels);

    /* Affiche l'image sous la forme d'une image jpeg */
    $im->setImageFormat('jpg');
    header("Content-Type: image/jpg");
    echo $im;

    ?>

Résultat de l'exemple ci-dessus est similaire à :

# Imagick::inverseFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::inverseFourierTransformImage — Implémente la transformée de Fourier discrète inverse (Discrete Fourier Transform - DFT)

### Description

public function Imagick::inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool

Implémente la transformée de Fourier discrète inverse (DFT) de l'image soit en tant que paire d'images magnitude / phase, soit en tant que paire d'images réelles / imaginaires.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`complement`

  La seconde image à combiner avec celle-ci pour former soit la paire d'images magnitude / phase, soit la paire d'images réelles / imaginaires.

`magnitude`

  Si vrai, combine en tant que paire magnitude / phase, sinon une paire d'images réelles / imaginaires.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::labelImage

(PECL imagick 2, PECL imagick 3)

Imagick::labelImage — Ajoute un libellé à une image

### Description

public function Imagick::labelImage(string `$label`): bool

Ajoute un libellé à une image.

### Liste de paramètres

`label`

  Le libellé à ajouter

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::levelImage

(PECL imagick 2, PECL imagick 3)

Imagick::levelImage — Ajuste les niveaux de l'image

### Description

public function Imagick::levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Ajuste les niveaux d'une image en modifiant les couleurs qui sont entre deux couleurs données. Les paramètres représentent le noir, le gris et le blanc. Le noir est la couleur la plus sombre dans l'image. Les couleurs qui sont plus sombres que la couleur noire sont alors mises à zéro. La couleur grise spécifie une correction gamma à appliquer à l'image. La couleur blanche spécifie la couleur la plus claire. Les couleurs plus claires sont alors mises à l'intensité maximale.

### Liste de paramètres

`blackPoint`

  Le point noir de l'image

`gamma`

  La correction gamma

`whitePoint`

  Le point blanc de l'image

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::levelImage()

    <?php
    function levelImage($blackPoint, $gamma, $whitePoint) {
        $imagick = new \Imagick();
        $imagick->newPseudoimage(500, 500, 'gradient:black-white');

        $imagick->setFormat('png');
        $quantum = $imagick->getQuantum();
        $imagick->levelImage($blackPoint / 100 , $gamma, $quantum * $whitePoint / 100);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::linearStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::linearStretchImage — Étire la saturation de l'intensité de l'image

### Description

public function Imagick::linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool

Étire la saturation de l'intensité de l'image.

### Liste de paramètres

`blackPoint`

  Le point noir de l'image.

`whitePoint`

  Le point blanc de l'image.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::linearStretchImage()

    <?php
    function linearStretchImage($imagePath, $blackThreshold, $whiteThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $pixels = $imagick->getImageWidth() * $imagick->getImageHeight();
        $imagick->linearStretchImage($blackThreshold * $pixels, $whiteThreshold * $pixels);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::liquidRescaleImage

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::liquidRescaleImage — Redimensionne une image par mise à l'échelle liquide

### Description

public function Imagick::liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool

Cette méthode met à l'échelle les images en utilisant la méthode de mise à l'échelle liquide. Cette méthode est une implémentation d'une technique appelée "seam carving". Pour que cette méthode fonctionne telle que convenue, ImageMagick doit avoir été compilé avec le support liblqr. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.9 ou supérieur.

### Liste de paramètres

`width`

  La largeur de la taille cible.

`height`

  La hauteur de la taille cible.

`delta_x`

  Le nombre de coutures pouvant traverser l'axe X. Le fait de passer 0 signifie que la couture se fera sur la droite.

`rigidity`

  Introduit une rigidité pour les coutures non droites. Ce paramètre est habituellement à 0.

### Valeurs de retour

Retourne `true` en cas de succès.

### Voir aussi

- Imagick::resizeImage() - Redimensionne une image

# Imagick::listRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::listRegistry — Liste tous les paramètres du registre

### Description

public static function Imagick::listRegistry(): array

Liste tous les paramètres du registre. Renvoie un tableau de toutes les paires clé/valeur du registre.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un tableau contenant les clés/valeurs du registre.

# Imagick::magnifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::magnifyImage — Double la taille d'une image, proportionnellement

### Description

public function Imagick::magnifyImage(): bool

Cette méthode est un raccourci pour doubler la taille d'une image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::magnifyImage()

    <?php
    function magnifyImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->magnifyImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mapImage

(PECL imagick 2, PECL imagick 3)

Imagick::mapImage — Remplace la couleur d'une image par celle d'une image de référence

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::mapImage(Imagick `$map`, bool `$dither`): bool

### Liste de paramètres

`map`

`dither`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::matteFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::matteFloodfillImage — Change la transparence d'une couleur

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Change la transparence d'un pixel cible, et ses voisins immédiats. Si la méthode `FillToBorderMethod` est spécifiée, la valeur de la transparence est modifiée pour tous les pixels voisins qui ne correspondent pas à une couleur de bordercolor.

### Liste de paramètres

`alpha`

  Le niveau de transparence : 1.0 représente une couleur opaque, alors que 0.0 est totalement transparent.

`fuzz`

  Cet argument représente la tolérance acceptable pour que deux couleurs soient considérées comme identiques.

`bordercolor`

  Un objet ImagickPixel ou une chaîne représentant la couleur de bordure.

`x`

  L'abscisse d'origine de l'opération.

`y`

  L'ordonnée d'origine de l'opération.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

# Imagick::medianFilterImage

(PECL imagick 2, PECL imagick 3)

Imagick::medianFilterImage — Applique un filtre numérique

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::medianFilterImage(float `$radius`): bool

Applique un filtre numérique qui améliore la qualité d'une image avec du bruit. Chaque pixel est remplacé par la médiane de son voisinage. Le voisinage est défini par un rayon.

### Liste de paramètres

`radius`

  Le rayon du voisinage.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::medianFilterImage()

    <?php
    function medianFilterImage($radius, $imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->medianFilterImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mergeImageLayers

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::mergeImageLayers — Fusionne les calques de l'image

### Description

public function Imagick::mergeImageLayers(int `$layer_method`): Imagick

Fusionne les calques de l'image en un seul. Cette méthode est utile lors de l'utilisation de formats d'image qui utilisent plusieurs calques, comme les PSD. La fusion est contrôlée en utilisant le paramètre `layer_method` qui définit la façon dont les calques doivent fusionner. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.7 ou supérieur.

### Liste de paramètres

`layer_method`

  Une constante parmi les constantes `Imagick::LAYERMETHOD_*`.

### Valeurs de retour

Retourne un objet Imagick contenant l'image fusionnée.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::mergeImageLayers()

    <?php
    function mergeImageLayers($layerMethodType, $imagePath1, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath1));

        $imagick2 = new \Imagick(realpath($imagePath2));
        $imagick->addImage($imagick2);
        $imagick->setImageFormat('png');

        $result = $imagick->mergeImageLayers($layerMethodType);
        header("Content-Type: image/png");
        echo $result->getImageBlob();
    }

    ?>

### Voir aussi

- Imagick::flattenImages() - Fusionne une séquence d'images

# Imagick::minifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::minifyImage — Met à l'échelle une image proportionnellement pour la réduire de moitié de taille

### Description

public function Imagick::minifyImage(): bool

Cette fonction est un raccourci pratique pour mettre à l'échelle une image proportionnellement pour la réduire de moitié de taille.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::modulateImage

(PECL imagick 2, PECL imagick 3)

Imagick::modulateImage — Contrôle la saturation, l'intensité et la teinte

### Description

public function Imagick::modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool

Contrôle l'intensité, la saturation et la teinte d'une image. La teinte est le pourcentage de rotation absolue depuis la position courante. Par exemple, la valeur 50 engendre une rotation anti-horaire de 90 degrés, 150 produit une rotation horaire de 90 degrés, tandis que 0 et 200 produisent des rotations de 180 degrés.

### Liste de paramètres

`brightness`

`saturation`

`hue`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::modulateImage()

    <?php
    function modulateImage($imagePath, $hue, $brightness, $saturation) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->modulateImage($brightness, $saturation, $hue);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::montageImage

(PECL imagick 2, PECL imagick 3)

Imagick::montageImage — Crée une image composite

### Description

public function Imagick::montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick

Crée une image composite en combinant plusieurs images. Les images sont utilisées comme carreaux dans l'image composite, avec leur nom optionnellement en dessous.

### Liste de paramètres

`draw`

  Le nom de la police, la taille et la couleur sont demandés à cet objet.

`tile_geometry`

  Le nombre de carreaux par ligne et par page (p. ex. `6x4+0+0`).

`thumbnail_geometry`

  La taille demandée pour l'image et sa bordure pour chaque miniature (p. ex. 120x120+4+3).

`mode`

  Le mode de cadrage des miniatures. Voir la liste des constantes de mode de montage.

`frame`

  Encadre l'image avec un bord d'ornement (p. ex. 15x15+3+3). La couleur du bord est la couleur mate de la miniature.

### Valeurs de retour

Crée une image composée et la retourne en tant que nouvel objet Imagick.

# Imagick::morphImages

(PECL imagick 2, PECL imagick 3)

Imagick::morphImages — Réalise un morphing entre deux images

### Description

public function Imagick::morphImages(int `$number_frames`): Imagick

Réalise un morphing d'images. La taille et la couleur des pixels sont linéairement interpolés pour donner l'apparence d'une métamorphose d'une image à l'autre.

### Liste de paramètres

`number_frames`

  Le nombre d'images à générer entre les deux images.

### Valeurs de retour

Cette méthode retourne un nouvel objet Imagick. Émet une exception ImagickException en cas d'échec.

# Imagick::morphology

(PECL imagick 3 >= 3.3.0)

Imagick::morphology — Applique un noyau personnalisé à l'image selon la méthode de morphologie donnée

### Description

public function Imagick::morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Applique un noyau personnalisé à l'image selon la méthode de morphologie donnée.

### Liste de paramètres

`morphologyMethod`

  Quelle méthode de morphologie utiliser parmi les constantes \Imagick::MORPHOLOGY_*.

`iterations`

  Le nombre d'itérations à appliquer à la fonction de morphologie. Une valeur de -1 signifie boucler jusqu'à ce qu'aucun changement ne soit trouvé. Comment cela est appliqué peut dépendre de la méthode de morphologie. Typiquement, il s'agit d'une valeur de 1.

`ImagickKernel`

`channel`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Convolution Imagick::morphology()

    <?php
            $imagick = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_GAUSSIAN, "5,1");
            $imagick->morphology(\Imagick::MORPHOLOGY_CONVOLVE, 2, $kernel);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();

    ?>

Exemple #2 Corréler Imagick::morphology()

    <?php

            // Le pixel en haut à gauche doit être noir
            // Le pixel en bas à droite doit être blanc
            // Le reste n'a pas d'importance.

            $imagick = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromMatrix(self::$correlateMatrix, [2, 2]);
            $imagick->morphology(\Imagick::MORPHOLOGY_CORRELATE, 1, $kernel);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();

    ?>

Exemple #3 Eroder Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_ERODE, 2, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #4 Eroder l'intensité Imagick::morphology()

    <?php
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
            $canvas->morphology(\Imagick::MORPHOLOGY_ERODE_INTENSITY, 2, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #5 Dilater Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_DILATE, 4, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #6 Dilater l'intensité Imagick::morphology()

    <?php
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
            $canvas->morphology(\Imagick::MORPHOLOGY_DILATE_INTENSITY, 4, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #7 Distancer avec le noyau de Chebyshev Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CHEBYSHEV, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #8 Distancer avec le noyau de Manhattan Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_MANHATTAN, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #9 Distancer avec le noyau octagonal Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGONAL, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #10 Distancer avec le noyau euclidien Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_EUCLIDEAN, "4");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #11 Border Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #12 Ouvrir Imagick::morphology()

    <?php
            // En conséquence, vous verrez que 'Ouvrir' a lissé le contour, en arrondissant les points saillants, et en supprimant les parties plus petites que la forme utilisée. Il déconnectera également ou 'ouvrira' les ponts minces.
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_OPEN, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #13 Open intensity Imagick::morphology()

    <?php
            // En conséquence, vous verrez que 'Ouvrir' a lissé le contour, en arrondissant les points saillants, et en supprimant les parties plus petites que la forme utilisée. Il déconnectera également ou 'ouvrira' les ponts minces.

            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_OPEN_INTENSITY, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #14 Fermer Imagick::morphology()

    <?php
            //L'utilisation de base de la méthode 'Fermer' est de réduire ou de supprimer les 'trous' ou les 'lacunes' d'environ la taille de l'élément de structure du noyau. C'est-à-dire 'fermer' les parties de l'arrière-plan qui sont d'environ cette taille.
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #15 Fermer l'intensité Imagick::morphology()

    <?php
            //L'utilisation de base de la méthode 'Fermer' est de réduire ou de supprimer les 'trous' ou les 'lacunes' d'environ la taille de l'élément de structure du noyau. C'est-à-dire 'fermer' les parties de l'arrière-plan qui sont d'environ cette taille.
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE_INTENSITY, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #16 Lisser Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_SMOOTH, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #17 Border l'intérieurImagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_IN, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #18 Border l'extérieur Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_OUT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #19 La méthode 'TopHat', ou plus spécifiquement 'White Top Hat', renvoie les pixels qui ont été supprimés par une Ouverture de la forme, c'est-à-dire les pixels qui ont été supprimés pour arrondir les points, et les ponts de connexion entre les formes. Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_TOP_HAT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #20 La méthode 'BottomHat', également connue sous le nom de 'Black TopHat', est les pixels qu'une Fermeture de la forme ajoute à l'image. C'est-à-dire les pixels qui ont été utilisés pour remplir les 'trous', les 'lacunes' et les 'ponts'. Imagick::morphology()

    <?php

            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_BOTTOM_HAT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #21 Toucher et manquer Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            //Cela trouve tous les pixels avec 3 pixels de l'arête droite
            $matrix = [[1, false, false, 0]];
            $kernel = \ImagickKernel::fromMatrix(
                $matrix,
                [0, 0]
            );
            $canvas->morphology(\Imagick::MORPHOLOGY_HIT_AND_MISS, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #22 Amincir Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
            $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
            $leftEdgeKernel->addKernel($rightEdgeKernel);

            $canvas->morphology(\Imagick::MORPHOLOGY_THINNING, 3, $leftEdgeKernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #23 Épaissir Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
            $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
            $leftEdgeKernel->addKernel($rightEdgeKernel);

            $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, 3, $leftEdgeKernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #24 Amincir pour générer une coque convexe Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $diamondKernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "1");
            $convexKernel =  \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CONVEX_HULL, "");

            // La morphologie d'amincissement ne gère pas les petits espaces. Nous les fermons
            // avec la morphologie de fermeture.
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);
            $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, -1, $convexKernel);
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);

            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #25 La morphologie itérative Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "2");
            $canvas->morphology(\Imagick::MORPHOLOGY_ITERATIVE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Exemple #26 La fonction d'aide pour obtenir un contour d'image Imagick::morphology()

    <?php
    function getCharacterOutline() {
        $imagick = new \Imagick(realpath("./images/character.png"));
        $character = new \Imagick();
        $character->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:white"
        );
        $canvas = new \Imagick();
        $canvas->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:black"
        );

        $character->compositeimage(
            $imagick,
            \Imagick::COMPOSITE_COPYOPACITY,
            0, 0
        );
        $canvas->compositeimage(
            $character,
            \Imagick::COMPOSITE_ATOP,
            0, 0
        );
        $canvas->setFormat('png');

        return $canvas;
    }
    ?>

# Imagick::mosaicImages

(PECL imagick 2, PECL imagick 3)

Imagick::mosaicImages — Forme une mosaïque d'images

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::mosaicImages(): Imagick

Aligne les images d'une séquence pour former une seule image cohérente. La fonction retourne une baguette avec chaque image de la séquence, à l'endroit du décalage de l'image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::motionBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::motionBlurImage — Ajoute un flou de déplacement

### Description

public function Imagick::motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Ajoute un flou de déplacement. Une convolution de l'image avec un opérateur gaussien, pour un rayon et une déviation donnés est utilisée. Pour des résultats raisonnables, le rayon doit être plus grand que la déviation. Utiliser un rayon de zéro, et Imagick va choisir sa valeur pour. L'angle donne la direction du flou de déplacement.

### Liste de paramètres

`radius`

  Le rayon de la gaussienne, en pixels, sans compter le pixel du centre.

`sigma`

  La déviation standard de la gaussienne, en pixels.

`angle`

  L'angle du flou.

`channel`

  Une constante de canal, valide pour le mode de canal. Pour spécifier un ou plusieurs canaux, il faut combiner les constantes de canaux avec les opérateurs bit à bit. Voir la liste de constantes de canaux. L'argument de canal est disponible uniquement si Imagick est compilé avec ImageMagick, version 6.4.4 ou plus récente.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::motionBlurImage()

    <?php
    function motionBlurImage($imagePath, $radius, $sigma, $angle, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->motionBlurImage($radius, $sigma, $angle, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::negateImage

(PECL imagick 2, PECL imagick 3)

Imagick::negateImage — Effectue la négation des couleurs d'une image de référence

### Description

public function Imagick::negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Effectue la négation des couleurs d'une image de référence. L'option de niveau de gris signifie que seules les valeurs en niveau de gris de l'image sont soumises à la transformation.

### Liste de paramètres

`gray`

  S'il faut effectuer la négation sur les niveaux de gris.

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::negateImage()

    <?php
    function negateImage($imagePath, $grayOnly, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->negateImage($grayOnly, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::newImage

(PECL imagick 2, PECL imagick 3)

Imagick::newImage — Crée une nouvelle image

### Description

public function Imagick::newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool

Crée une nouvelle image et lui associe un objet ImagickPixel pour la couleur de fond

### Liste de paramètres

`cols`

  Le nombre de colonnes de la nouvelle image

`rows`

  Le nombre de lignes de la nouvelle image

`background`

  La couleur de fond utilisée pour cette image

`format`

  Le format de l'image. Ce paramètre a été ajouté en Imagick version 2.0.1.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

### Exemples

Exemple #1 Exemple avec Imagick::newImage()

Crée une nouvelle image et l'affiche.

    <?php

    $image = new Imagick();
    $image->newImage(100, 100, new ImagickPixel('red'));
    $image->setImageFormat('png');

    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::newPseudoImage

(PECL imagick 2, PECL imagick 3)

Imagick::newPseudoImage — Crée une nouvelle image

### Description

public function Imagick::newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool

Crée une nouvelle image en utilisant les pseudoformats ImageMagick.

### Liste de paramètres

`columns`

  Le nombre de colonnes dans la nouvelle image

`rows`

  Le nombre de lignes dans la nouvelle image

`pseudoString`

  Une chaîne contenant une pseudodéfinition d'image.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::newPseudoImage()

    <?php
    function newPseudoImage($canvasType) {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(300, 300, $canvasType);
        $imagick->setImageFormat("png");
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    //newPseudoImage('gradient:red-rgba(64, 255, 255, 0.5)');
    //newPseudoImage("radial-gradient:red-blue");
    newPseudoImage("plasma:fractal");

    ?>

# Imagick::nextImage

(PECL imagick 2, PECL imagick 3)

Imagick::nextImage — Passe à la prochaine image

### Description

public function Imagick::nextImage(): bool

Passe à la prochaine image dans la liste de l'objet Imagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::normalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::normalizeImage — Améliore le contraste de l'image

### Description

public function Imagick::normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Améliore le contraste de l'image en ajustant la couleur des pixels à travers toute la gamme des couleurs de l'image.

### Liste de paramètres

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::normalizeImage()

    <?php
    function normalizeImage($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $original = clone $imagick;
        $original->cropimage($original->getImageWidth() / 2, $original->getImageHeight(), 0, 0);
        $imagick->normalizeImage($channel);
        $imagick->compositeimage($original, \Imagick::COMPOSITE_ATOP, 0, 0);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::oilPaintImage

(PECL imagick 2, PECL imagick 3)

Imagick::oilPaintImage — Simule une peinture à l'huile

### Description

public function Imagick::oilPaintImage(float `$radius`): bool

Applique un filtre spécial qui simule une peinture à l'huile. Chaque pixel est remplacé par la couleur la plus fréquente dans son voisinage.

### Liste de paramètres

`radius`

  Le rayon du voisinage circulaire.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::oilPaintImage()

    <?php
    function oilPaintImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->oilPaintImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::opaquePaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::opaquePaintImage — Modifie la valeur de la couleur de tous les pixels correspondant à la cible

### Description

public function Imagick::opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Modifie tous les pixels correspondant à la couleur avec la couleur définie par le paramètre `fill`. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.8 ou supérieur.

### Liste de paramètres

`target`

  Un objet ImagickPixel ou une chaîne de caractères contenant la couleur à modifier.

`fill`

  La couleur de remplacement.

`fuzz`

  La quantité de poussière de papier. Par exemple, le fait de définir la poussière de papier à 10 et la couleur rouge à une intensité de 100 et de 102 ne sera pas interprété comme la même couleur.

`invert`

  Si vaut `true`, colorise tous les pixels qui ne correspondent pas à la couleur cible.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::optimizeImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::optimizeImageLayers — Supprime les portions récurrentes d'images à optimiser

### Description

public function Imagick::optimizeImageLayers(): bool

Compare chaque image GIF à la précédente dans la séquence. A partir de là, la méthode tente de sélectionner la plus petite partie d'image à remplacer à chaque image, tout en préservant les résultats de l'animation. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::optimizeImageLayers()

Lecture, optimisation et écriture d'une image GIF

    <?php
    /* création d'un nouvel objet imagick */
    $im = new Imagick("test.gif");

    /* optimisation des calques */
    $im->optimizeImageLayers();

    /* écriture de l'image */
    $im->writeImages("test_optimized.gif", true);
    ?>

### Voir aussi

- Imagick::compareImageLayers() - Retourne la région d'encadrement maximale entre deux images
- Imagick::writeImages() - Écrit une image ou une séquence d'images
- Imagick::writeImage() - Écrit une image dans le fichier spécifié

# Imagick::orderedPosterizeImage

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::orderedPosterizeImage — Effectue un dither ordonné

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Effectue un dither ordonné, basé sur un nombre prédéfini de cartes de seuil de dither, mais avec plusieurs niveaux d'intensité, qui peuvent être différents sur différents canaux, suivant les arguments. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.1 ou supérieur.

### Liste de paramètres

`threshold_map`

  Une chaîne contenant le nom de la carte de seuils de dither

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::orderedPosterizeImage()

    <?php
    function orderedPosterizeImage($imagePath, $orderedPosterizeType) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->orderedPosterizeImage($orderedPosterizeType);
        $imagick->setImageFormat('png');

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    //orderedPosterizeImage($imagePath, 'o4x4,3,3');
    //orderedPosterizeImage($imagePath, 'o8x8,6,6');
    orderedPosterizeImage($imagePath, 'h8x8a');

    ?>

# Imagick::paintFloodfillImage

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::paintFloodfillImage — Change les pixels qui sont d'une couleur

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Change les pixels qui correspondent à une couleur en une couleur de remplissage, et qui sont un voisin immédiat. Depuis ImageMagick 6.3.8, cette méthode est obsolète et la méthode Imagick::floodfillPaintImage() doit être utilisée à la place.

### Liste de paramètres

`fill`

  L'objet ImagickPixel ou une chaîne de caractères contenant la couleur de remplissage.

`fuzz`

  La quantité de bruit. Par exemple, un bruit de 10 et la couleur rouge à l'intensité de 100 et 102, respectivement, sont maintenant interprétés comme la même couleur, dans le cadre de ce remplissage.

`bordercolor`

  Un objet ImagickPixel ou une chaîne de caractères contenant la couleur de la bordure

`x`

  L'abscisse position d'origine du remplissage

`y`

  L'ordonnée position d'origine du remplissage

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::paintOpaqueImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintOpaqueImage — Change les pixels qui sont d'une couleur

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Change les pixels qui correspondent à une couleur en une couleur de remplissage.

### Liste de paramètres

`target`

  La couleur cible, avec son opacité. Un objet ImagickPixel ou bien une chaîne représentant la couleur cible.

`fill`

  Un objet ImagickPixel ou une chaîne représentant une couleur de remplissage.

`fuzz`

  Ce paramètre indique la tolérance qui permet de considérer que deux couleurs sont identiques.

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

# Imagick::paintTransparentImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintTransparentImage — Remplit les pixels avec une couleur

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool

Change les pixels qui correspondent à une couleur en une couleur de remplissage.

### Liste de paramètres

`target`

  La couleur cible, avec son opacité.

`alpha`

  Le niveau de transparence : 1.0 est totalement opaque, et 0 est totalement transparent.

`fuzz`

  Ce paramètre indique la tolérance qui permet de considérer que deux couleurs sont identiques.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

# Imagick::pingImage

(PECL imagick 2, PECL imagick 3)

Imagick::pingImage — Lit des attributs simples sans ouvrir une image

### Description

public function Imagick::pingImage(string `$filename`): bool

Cette méthode peut être utilisée pour obtenir les dimensions de l'image sans lire toute l'image en mémoire.

### Liste de paramètres

`filename`

  Le nom du fichier qui contient l'image.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::pingImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageBlob — Lit rapidement les attributs

### Description

public function Imagick::pingImageBlob(string `$image`): bool

Cette méthode peut être utilisée pour obtenir les dimensions de l'image sans lire toute l'image en mémoire. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`image`

  Une chaîne contenant l'image.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::pingImageBlob()

Récupère une image depuis une chaîne

    <?php
    /* Lit le contenu de l'image */
    $image = file_get_contents("test.jpg");

    /* Crée un nouvel objet imagick */
    $im = new Imagick();

    /* Passe la chaîne à l'objet imagick */
    $im->pingImageBlob($image);

    /* Affiche les dimensions de l'image */
    echo $im->getImageWidth() . 'x' . $im->getImageHeight();
    ?>

### Voir aussi

- Imagick::pingImage() - Lit des attributs simples sans ouvrir une image
- Imagick::pingImageFile() - Lit les attributs simples d'une image
- Imagick::readImage() - Lit une image depuis un fichier
- Imagick::readImageBlob() - Lit une image depuis une chaîne binaire
- Imagick::readImageFile() - Lit une image à partir d'une ressource fichier

# Imagick::pingImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageFile — Lit les attributs simples d'une image

### Description

public function Imagick::pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool

Cette méthode peut être utilisée pour connaître les dimensions d'une image, sans lire toute l'image. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`filehandle`

  Un flux ouvert sur une image.

`fileName`

  Le nom du fichier d'image, optionnellement.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::pingImageFile()

Ouverture d'une image distante.

    <?php
    /* Ouverture d'une image distante */
    $fp = fopen("http://example.com/test.jpg");

    /* Création d'un nouvel objet imagick */
    $im = new Imagick();

    /* Passe le gestionnaire à imagick */
    $im->pingImageFile($fp);
    ?>

### Voir aussi

- Imagick::pingImage() - Lit des attributs simples sans ouvrir une image
- Imagick::pingImageBlob() - Lit rapidement les attributs
- Imagick::readImage() - Lit une image depuis un fichier
- Imagick::readImageBlob() - Lit une image depuis une chaîne binaire
- Imagick::readImageFile() - Lit une image à partir d'une ressource fichier

# Imagick::polaroidImage

(PECL imagick 2, PECL imagick 3)

Imagick::polaroidImage — Simule une photo Polaroid

### Description

public function Imagick::polaroidImage(ImagickDraw `$properties`, float `$angle`): bool

Simule une photo Polaroid. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.

### Liste de paramètres

`properties`

  Les propriétés Polaroid

`angle`

  L'angle Polaroid

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::polaroidImage()

Un exemple d'utilisation de Imagick::polaroidImage()

    <?php
    /* Création de l'objet */
    $image = new Imagick('source.png');

    /* Définit l'opacité */
    $image->polaroidImage(new ImagickDraw(), 25);

    /* Affiche l'image */
    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::posterizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::posterizeImage — Réduit une image à un nombre limité de couleurs

### Description

public function Imagick::posterizeImage(int `$levels`, bool `$dither`): bool

Réduit une image à un nombre limité de couleurs.

### Liste de paramètres

`levels`

`dither`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::posterizeImage()

    <?php
    function posterizeImage($imagePath, $posterizeType, $numberLevels) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->posterizeImage($numberLevels, $posterizeType);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    posterizeImage($imagePath, \Imagick::DITHERMETHOD_RIEMERSMA, 8);

    ?>

# Imagick::previewImages

(PECL imagick 2, PECL imagick 3)

Imagick::previewImages — Teste rapidement différents paramètres pour un traitement d'images

### Description

public function Imagick::previewImages(int `$preview`): bool

Crée un panorama de 9 miniatures de l'image spécifiée avec un traitement appliqué à différents niveaux. Cela est pratique pour tester rapidement différents paramètres d'un filtre.

### Liste de paramètres

`preview`

  Type de prévisualisation. Voir la liste des constantes de prévisualisation

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::previousImage

(PECL imagick 2, PECL imagick 3)

Imagick::previousImage — Passe à l'image précédente dans une séquence d'images

### Description

public function Imagick::previousImage(): bool

Passe à l'image précédente dans une séquence d'images Imagick.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::profileImage

(PECL imagick 2, PECL imagick 3)

Imagick::profileImage — Ajoute ou retire un profil d'une image

### Description

public function Imagick::profileImage(string `$name`, string `$profile` = ?): bool

Ajoute ou retire un profil ICC, IPTC, ou générique d'une image. Si le `profile` est `null`, il est retiré de l'image plutôt qu'ajouté.

Pour retirer tous les profils de l'image, utiliser `'*'` comme `name` et `null` pour le `profile`.

### Liste de paramètres

`name`
  Le nom du profil.
`profile`
  Les données du profil. Si `null`, le profil spécifié sera supprimé.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::quantizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImage — Analyse les couleurs dans une référence d'image

### Description

public function Imagick::quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Liste de paramètres

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::quantizeImage()

    <?php
    function quantizeImage($imagePath, $numberColors, $colorSpace, $treeDepth, $dither) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->quantizeImage($numberColors, $colorSpace, $treeDepth, $dither, false);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::quantizeImages

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImages — Analyse les couleurs d'une séquence d'images

### Description

public function Imagick::quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Liste de paramètres

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::queryFontMetrics

(PECL imagick 2, PECL imagick 3)

Imagick::queryFontMetrics — Retourne un tableau représentant les dimensions de la police

### Description

public function Imagick::queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array

Retourne un tableau multidimensionnel représentant les dimensions de la police.

### Liste de paramètres

`properties`

  Un objet ImagickDraw contenant des attributs de police

`text`

  Le texte

`multiline`

  Un paramètre multiligne. S'il est laissé vide, il est auto-détecté.

### Valeurs de retour

Retourne un tableau de plusieurs dimensions contenant les dimensions de la police.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::queryFontMetrics()

Demande les dimensions du texte, et affiche les valeurs à l'écran

    <?php
    /* Crée un nouvel objet Imagick */
    $im = new Imagick();

    /* Crée un objet ImagickDraw */
    $draw = new ImagickDraw();

    /* Configure la police */
    $draw->setFont('/path/to/font.ttf');

    /* Affiche les dimensions de la police, auto-détecte le multiligne */
    var_dump($im->queryFontMetrics($draw, "Hello World!"));
    ?>

# Imagick::queryFonts

(PECL imagick 2, PECL imagick 3)

Imagick::queryFonts — Retourne la liste de polices configurées

### Description

public static function Imagick::queryFonts(string `$pattern` = "*"): array

Retourne la liste de polices configurées pour Imagick.

### Liste de paramètres

`pattern`

  Le modèle de recherche

### Valeurs de retour

Retourne un tableau contenant les polices configurées.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::queryFonts()

    <?php
            $output = '';
            $output .= "Fonts that match 'Helvetica*' are:<br/>";

            $fontList = \Imagick::queryFonts("Helvetica*");

            foreach ($fontList as $fontName) {
                $output .= '<li>'. $fontName."</li>";
            }

            return $output;

    ?>

# Imagick::queryFormats

(PECL imagick 2, PECL imagick 3)

Imagick::queryFormats — Retourne les formats supportés par Imagick

### Description

public static function Imagick::queryFormats(string `$pattern` = "*"): array

Retourne les formats supportés par Imagick.

### Liste de paramètres

`pattern`

### Valeurs de retour

Retourne un tableau contenant les formats supportés par Imagick.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::queryFormats()

    <?php
        function render() {
            $output = "";
            $input = \Imagick::queryformats();
            $columns = 6;

            $output .= "<table border='2'>";

            for ($i=0; $i < count($input); $i += $columns) {
                $output .= "<tr>";
                for ($c=0; $c<$columns; $c++) {
                    $output .= "<td>";
                    if (($i + $c) <  count($input)) {
                        $output .= $input[$i + $c];
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

    ?>

# Imagick::radialBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::radialBlurImage — Flou radial d'une image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Flou radial d'une image.

### Liste de paramètres

`angle`

`channel`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::radialBlurImage()

    <?php
    function radialBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        //Blur 3 times with different radii
        $imagick->radialBlurImage(3);
        $imagick->radialBlurImage(5);
        $imagick->radialBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::raiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::raiseImage — Crée un effet 3D de bouton

### Description

public function Imagick::raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool

Crée un effet 3D de bouton, en éclairant et assombrissant les bords de l'image. Les membres width et height de raise_info définissent la largeur et la hauteur de l'effet vertical.

### Liste de paramètres

`width`

`height`

`x`

`y`

`raise`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::raiseImage()

    <?php
    function raiseImage($imagePath, $width, $height, $x, $y, $raise) {
        $imagick = new \Imagick(realpath($imagePath));

        //x et y ne font rien ? ;)
        $imagick->raiseImage($width, $height, $x, $y, $raise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::randomThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::randomThresholdImage — Crée une image en deux couleurs, à haut contraste

### Description

public function Imagick::randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Change la valeur de chaque pixel en fonction de l'intensité de la couleur, et la compare à un seuil. Le résultat est une image en deux couleurs, à haut contraste. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`low`

  Le point inférieur.

`high`

  Le point supérieur.

`channel`

  Fournit une constante de canal valide pour le mode de canal. Pour utiliser plus d'un canal, il faut combiner les constantes de type de canal en utilisant les opérateurs bit à bit. Se reporter à la liste des constantes de canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::randomThresholdImage()

    <?php
    function randomThresholdimage($imagePath, $lowThreshold, $highThreshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->randomThresholdimage(
            $lowThreshold * \Imagick::getQuantum(),
            $highThreshold * \Imagick::getQuantum(),
            $channel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::readImage

(PECL imagick 2, PECL imagick 3)

Imagick::readImage — Lit une image depuis un fichier

### Description

public function Imagick::readImage(string `$filename`): bool

Lit une image depuis un fichier.

### Liste de paramètres

`filename`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::readImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::readImageBlob — Lit une image depuis une chaîne binaire

### Description

public function Imagick::readImageBlob(string `$image`, string `$filename` = ?): bool

Lit une image depuis une chaîne binaire.

### Liste de paramètres

`image`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::readImageBlob()

    <?php
    function readImageBlob() {
        $base64 = "iVBORw0KGgoAAAANSUhEUgAAAM0AAAD
     NCAMAAAAsYgRbAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5c
     cllPAAAABJQTFRF3NSmzMewPxIG//ncJEJsldTou1jHgAAAARBJREFUeNrs2EEK
     gCAQBVDLuv+V20dENbMY831wKz4Y/VHb/5RGQ0NDQ0NDQ0NDQ0NDQ0NDQ
     0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0PzMWtyaGhoaGhoaGhoaGhoaGhoxtb0QGho
     aGhoaGhoaGhoaGhoaMbRLEvv50VTQ9OTQ5OpyZ01GpM2g0bfmDQaL7S+ofFC6x
     v3ZpxJiywakzbvd9r3RWPS9I2+MWk0+kbf0Hih9Y17U0nTHibrDDQ0NDQ0NDQ0
     NDQ0NDQ0NTXbRSL/AK72o6GhoaGhoRlL8951vwsNDQ0NDQ1NDc0WyHtDTEhD
     Q0NDQ0NTS5MdGhoaGhoaGhoaGhoaGhoaGhoaGhoaGposzSHAAErMwwQ2HwRQ
     AAAAAElFTkSuQmCC";

        $imageBlob = base64_decode($base64);

        $imagick = new Imagick();
        $imagick->readImageBlob($imageBlob);

        header("Content-Type: image/png");
        echo $imagick;
    }

    ?>

# Imagick::readImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::readImageFile — Lit une image à partir d'une ressource fichier

### Description

public function Imagick::readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool

Lit une image à partir d'une ressource fichier.

### Liste de paramètres

`filehandle`

`fileName`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::readimages

(PECL imagick 2, PECL imagick 3)

Imagick::readimages — Lit une image à partir d'un tableau de noms de fichiers

### Description

public function Imagick::readImages(array `$filenames`): bool

Lit une image à partir d'un tableau de noms de fichiers. Toutes les images sont stockées dans un seul objet Imagick.

### Liste de paramètres

`filenames`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::recolorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::recolorImage — Recolore l'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::recolorImage(array `$matrix`): bool

Traduit, met à l'échelle, cisaille et fait pivoter les couleurs de l'image. Cette méthode supporte les matrices variables de mise à l'échelle, mais normalement, la matrice 5x5 est utilisée pour RGBA et une matrice 6x6 est utilisée pour CMYK. La dernière ligne doit contenir les valeurs normalisées. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`matrix`

  La matrice contenant les valeurs des couleurs.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::recolorImage()

    <?php
    function recolorImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $remapColor = [ 1, 0, 0,
            0, 0, 1,
            0, 1, 0,];

    //$remapColor = [
    //    1.438, -0.122, -0.016,  0, 0, -0.03,
    //    -0.062,  1.378, -0.016,  0, 0,  0.05,
    //    -0.062, -0.122, 1.483,   0, 0, -0.02,
    //];

        @$imagick->recolorImage($remapColor);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Voir aussi

- Imagick::displayImage() - Affiche une image

# Imagick::reduceNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::reduceNoiseImage — Adoucit les contours d'une image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::reduceNoiseImage(float `$radius`): bool

Adoucit les contours d'une image, tout en préservant les informations de bords. L'algorithme fonctionne en remplaçant chaque pixel avec la valeur la plus proche de ses voisins. Un voisin est défini par un rayon. En utilisant un rayon de 0, Imagick::reduceNoiseImage() sélectionne un rayon automatiquement.

### Liste de paramètres

`radius`

  Le rayon de définition d'un voisin.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::reduceNoiseImage()

    <?php
    function reduceNoiseImage($imagePath, $reduceNoise) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->reduceNoiseImage($reduceNoise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::remapImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::remapImage — Reconfigure les couleurs de l'image

### Description

public function Imagick::remapImage(Imagick `$replacement`, int `$DITHER`): bool

Remplace les couleurs de l'image avec celles définies par le paramètre `replacement`. Les couleurs sont remplacées avec les couleurs les plus proches possibles. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.5 ou supérieur.

### Liste de paramètres

`replacement`

  Un objet Imagick contenant les couleurs de remplacement.

`DITHER`

  Se référer à la liste des constantes de la méthode dither.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::removeImage

(PECL imagick 2, PECL imagick 3)

Imagick::removeImage — Retire une image de la liste

### Description

public function Imagick::removeImage(): bool

Retire une image de la liste.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::removeImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::removeImageProfile — Supprime le profil de l'image et le retourne

### Description

public function Imagick::removeImageProfile(string `$name`): string

Supprime le profil de l'image et le retourne.

### Liste de paramètres

`name`

### Valeurs de retour

Retourne une chaîne contenant le profil de l'image.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::render

(PECL imagick 2, PECL imagick 3)

Imagick::render — Affiche toutes les commandes de dessins précédentes

### Description

public function Imagick::render(): bool

Affiche toutes les commandes de dessins précédentes.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::resampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::resampleImage — Rééchantillonne l'image

### Description

public function Imagick::resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool

Rééchantillonne l'image à la résolution désirée.

### Liste de paramètres

`x_resolution`

`y_resolution`

`filter`

`blur`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::resampleImage()

    <?php
    function resampleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resampleImage(200, 200, \Imagick::FILTER_LANCZOS, 1);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::resetImagePage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::resetImagePage — Réinitialise la page de l'image

### Description

public function Imagick::resetImagePage(string `$page`): bool

La définition de la page sous la forme d'une chaîne de caractères. La chaîne est au format WxH+x+y. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`page`

  La définition de la page. Par exemple, `7168x5147+0+0`.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::resizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::resizeImage — Redimensionne une image

### Description

public function Imagick::resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Redimensionne une image aux dimensions désirées, avec un filtre.

> Note: Le comportement du paramètre `bestfit` a changé avec Imagick 3.0.0. Avant cette version, fournir les dimensions 400x400 à une image de dimensions 200x150 faisait que la partie gauche était inchangée. Avec Imagick 3.0.0 et suivants, l'image est réduite à la taille 400x300, sachant que c'est le meilleur résultat pour ces dimensions. Si le paramètre `bestfit` est utilisé, la largeur et la hauteur doivent être fournies.

### Liste de paramètres

`columns`

  La largeur de l'image cible.

`rows`

  La hauteur de l'image cible.

`filter`

  Une constante de filtre.

`blur`

  Le facteur de flou, où > 1 est flou, et < 1 est net.

`bestfit`

  Paramètre optionnel de fit.

### Valeurs de retour

Retourne `true` en cas de succès.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Ajout d'un paramètre optionnel de fit. Cette méthode supporte maintenant la mise à l'échelle proportionnelle. Passez zéro comme valeur de paramètre pour une mise à l'échelle proportionnelle.

### Exemples

Exemple #1 Exemple avec Imagick::resizeImage()

    <?php
    function resizeImage($imagePath, $width, $height, $filterType, $blur, $bestFit, $cropZoom) {
        // Le facteur de flou où > 1 correspond à totalement flou, et < 1 correspond à fort.
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resizeImage($width, $height, $filterType, $blur, $bestFit);

        $cropWidth = $imagick->getImageWidth();
        $cropHeight = $imagick->getImageHeight();

        if ($cropZoom) {
            $newWidth = $cropWidth / 2;
            $newHeight = $cropHeight / 2;

            $imagick->cropimage(
                $newWidth,
                $newHeight,
                ($cropWidth - $newWidth) / 2,
                ($cropHeight - $newHeight) / 2
            );

            $imagick->scaleimage(
                $imagick->getImageWidth() * 4,
                $imagick->getImageHeight() * 4
            );
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rollImage

(PECL imagick 2, PECL imagick 3)

Imagick::rollImage — Décale une image

### Description

public function Imagick::rollImage(int `$x`, int `$y`): bool

Décale une image, d'un vecteur x, y.

### Liste de paramètres

`x`

  Le décalage en abscisse.

`y`

  Le décalage en ordonnée.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::rollImage()

    <?php
    function rollImage($imagePath, $rollX, $rollY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rollimage($rollX, $rollY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::rotateImage — Tourne une image

### Description

public function Imagick::rotateImage(mixed `$background`, float `$degrees`): bool

Tourne une image d'un nombre de degrés spécifié par `degrees`. Les triangles vides ainsi créés sont remplis avec la couleur de fond.

### Liste de paramètres

`background`

  La couleur de fond

`degrees`

  Angle de rotation, en degrés. L'angle de rotation est interprété comme le nombre de degrés pour la rotation dans le sens des aiguilles d'une montre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

### Exemples

Exemple #1 Exemple avec Imagick::rotateImage()

    <?php
    function rotateImage($imagePath, $angle, $color) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotateimage($color, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotationalBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::rotationalBlurImage — Flou de rotation d'une image

### Description

public function Imagick::rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Flou de rotation d'une image.

### Liste de paramètres

`angle`

  L'angle sur lequel appliquer le flou.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::rotationalBlurImage()

    <?php
    function rotationalBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotationalBlurImage(3);
        $imagick->rotationalBlurImage(5);
        $imagick->rotationalBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::roundCorners

(PECL imagick 2, PECL imagick 3)

Imagick::roundCorners — Arrondit les coins d'une image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool

Arrondit les coins d'une image. Les deux premiers paramètres contrôlent le niveau d'arrondi, et le troisième peut être utilisé pour affiner ce processus. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur. Cette méthode n'est pas disponible si Imagick a été compilé avec ImageMagick version 7.0.0 ou supérieur.

### Liste de paramètres

`x_rounding`

  Arrondi en x

`y_rounding`

  Arrondi en y

`stroke_width`

  Largeur du trait

`displace`

  Déplacement de l'image

`size_correction`

  Correction de taille

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::roundCorners():

Arrondit les coins d'une image.

    <?php

    $image = new Imagick();
    $image->newPseudoImage(100, 100, "magick:rose");
    $image->setImageFormat("png");

    $image->roundCorners(5,3);
    $image->writeImage("rounded.png");
    ?>

# Imagick::sampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::sampleImage — Met à l'échelle une image avec échantillonnage de pixels

### Description

public function Imagick::sampleImage(int `$columns`, int `$rows`): bool

Met à l'échelle une image aux dimensions désirées, à l'aide de la méthode d'échantillonnage de pixels. Contrairement aux autres méthodes, cette méthode n'introduit pas de nouvelle couleur dans l'image.

### Liste de paramètres

`columns`

`rows`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::scaleImage

(PECL imagick 2, PECL imagick 3)

Imagick::scaleImage — Met à l'échelle la taille de l'image

### Description

public function Imagick::scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Met à l'échelle la taille de l'image, aux dimensions voulues. Dans le cas où l'un des paramètres est égal à 0, il sera automatiquement calculé.

> Note: Le comportement du paramètre `bestfit` a changé avec Imagick 3.0.0. Avant cette version, fournir les dimensions 400x400 à une image de dimensions 200x150 faisait que la partie gauche était inchangée. Avec Imagick 3.0.0 et suivants, l'image est réduite à la taille 400x300, sachant que c'est le meilleur résultat pour ces dimensions. Si le paramètre `bestfit` est utilisé, la largeur et la hauteur doivent être fournies.

### Liste de paramètres

`columns`

`rows`

`bestfit`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Ajout d'un paramètre optionnel de fit. Cette méthode supporte désormais la mise à l'échelle proportionnelle. Passez zéro dans l'un des paramètres pour activer cette option.

### Exemples

Exemple #1 Exemple avec Imagick::scaleImage()

    <?php
    function scaleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->scaleImage(150, 150, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::segmentImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::segmentImage — Segmente une image

### Description

public function Imagick::segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool

Analyse l'image et identifie les unités similaires. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.5 ou supérieur.

### Liste de paramètres

`COLORSPACE`

  Une constante parmi les constantes COLORSPACE.

`cluster_threshold`

  Un pourcentage décrivant le nombre minimal de pixels contenus dans l'hexedra avant qu'il ne soit considéré comme valide.

`smooth_threshold`

  Élimine le bruit depuis l'histogramme.

`verbose`

  Si l'on doit ou non afficher les informations détaillées sur la reconnaissance des classes.

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec Imagick::segmentImage()

    <?php
    function segmentImage($imagePath, $colorSpace, $clusterThreshold, $smoothThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->segmentImage($colorSpace, $clusterThreshold, $smoothThreshold);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    segmentImage($imagePath, \Imagick::COLORSPACE_RGB, 5, 5);

    ?>

# Imagick::selectiveBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::selectiveBlurImage — Floute sélectivement une image dans un seuil de contraste

### Description

public function Imagick::selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Floute sélectivement une image dans un seuil de contraste. Il est similaire au masque de flou qui accentue tout avec un contraste supérieur à un certain seuil.

### Liste de paramètres

`radius`

`sigma`

`threshold`

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::selectiveBlurImage()

    <?php
    function selectiveBlurImage($imagePath, $radius, $sigma, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->selectiveBlurImage($radius, $sigma, $threshold, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::separateImageChannel

(PECL imagick 2, PECL imagick 3)

Imagick::separateImageChannel — Sépare un canal d'une image

### Description

public function Imagick::separateImageChannel(int `$channel`): bool

Sépare un canal d'une image, et retourne une image en niveaux de gris. Un canal est un composant de couleur particulier, de chaque pixel de l'image.

### Liste de paramètres

`channel`

  Le canal à retourner. Pour les espaces de couleurs différentes de RGB, il est possible de continuer d'utiliser les constantes CHANNEL_RED, CHANNEL_GREEN, CHANNEL_BLUE pour indiquer le premier, second ou troisième canal.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::separateImageChannel()

    <?php
    function separateImageChannel($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->separateimagechannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    separateImageChannel($imagePath, \Imagick::CHANNEL_GREEN);

    ?>

# Imagick::sepiaToneImage

(PECL imagick 2, PECL imagick 3)

Imagick::sepiaToneImage — Passe une image en tons sépia

### Description

public function Imagick::sepiaToneImage(float `$threshold`): bool

Applique un effet spécial à une image, similaire à l'effet de tons sépia, obtenus dans les chambres noires de photographie. Le seuil va de 0 jusqu'à QuantumRange et est une mesure de l'intervalle de tons sépia. Une valeur raisonnable est 80.

### Liste de paramètres

`threshold`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::sepiaToneImage()

    <?php
    function sepiaToneImage($imagePath, $sepia) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sepiaToneImage($sepia);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setBackgroundColor — Configure la couleur de fond par défaut

### Description

public function Imagick::setBackgroundColor(mixed `$background`): bool

Configure la couleur de fond par défaut.

### Liste de paramètres

`background`

### Valeurs de retour

Retourne `true` en cas de succès.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

# Imagick::setColorspace

(PECL imagick 3)

Imagick::setColorspace — Définit l'espace de couleurs

### Description

public function Imagick::setColorspace(int `$COLORSPACE`): bool

Définit la valeur globale de l'espace de couleurs pour l'objet. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.5.7 ou supérieur.

### Liste de paramètres

`COLORSPACE`

  Une constante parmi les constantes COLORSPACE.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setCompression — Configure le type de compression de l'objet

### Description

public function Imagick::setCompression(int `$compression`): bool

Configure le type de compression de l'objet.

### Liste de paramètres

`compression`

  Le type de compression. Voir les constantes Imagick::COMPRESSION_*.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setCompressionQuality — Configure la compression par défaut de l'objet

### Description

public function Imagick::setCompressionQuality(int `$quality`): bool

Configure la compression par défaut de l'objet.

Attention

Cette méthode ne fonctionne qu'avec les nouvelles images, c.-à-d. celles créées avec la méthode Imagick::newPseudoImage. Pour les images existantes, il est recommandé d'utiliser la méthode Imagick::setImageCompressionQuality().

### Liste de paramètres

`quality`

  Un entier entre 1 et 100, 1 = compression élevée, 100 compression faible.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::setCompressionQuality()

    <?php
    function setCompressionQuality($imagePath, $quality) {

        $backgroundImagick = new \Imagick(realpath($imagePath));
        $imagick = new \Imagick();
        $imagick->setCompressionQuality($quality);
        $imagick->newPseudoImage(
            $backgroundImagick->getImageWidth(),
            $backgroundImagick->getImageHeight(),
            'canvas:white'
        );

        $imagick->compositeImage(
            $backgroundImagick,
            \Imagick::COMPOSITE_ATOP,
            0,
            0
        );

        $imagick->setFormat("jpg");
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setFilename — Configure le nom du fichier d'image avant d'y accéder

### Description

public function Imagick::setFilename(string `$filename`): bool

Configure le nom du fichier d'image avant d'y accéder.

### Liste de paramètres

`filename`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setFirstIterator

(PECL imagick 2, PECL imagick 3)

Imagick::setFirstIterator — Place l'itérateur de Imagick sur la première image

### Description

public function Imagick::setFirstIterator(): bool

Place l'itérateur de Imagick sur la première image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setFont — Configure la police

### Description

public function Imagick::setFont(string `$font`): bool

Configure la police de l'image. Cette méthode est utilisée pour configurer la police utilisée par le pseudoformat : `caption`. La police doit être configurée dans la configuration d'ImageMagick ou bien, un fichier portant le nom de la police `font` doit exister. Cette méthode ne doit pas être confondue avec la méthode ImagickDraw::setFont() qui définit la police pour un objet ImagickDraw spécifique. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.7 ou supérieur.

### Liste de paramètres

`font`

  Le nom de la police ou le nom du fichier

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::setFont()

Exemple d'utilisation de Imagick::setFont().

    <?php
    /* Crée un nouvel objet Imagick */
    $im = new Imagick();

    /* Configure la police de l'objet */
    $im->setFont("example.ttf");

    /* Crée un nouveau message */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Suite du traitement de l'image */
    ?>

### Voir aussi

- Imagick::getFont() - Récupère la police de caractères
- ImagickDraw::setFont() - Configure la police complète pour les textes
- ImagickDraw::getFont() - Retourne la police

# Imagick::setFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setFormat — Configure le format de l'objet Imagick

### Description

public function Imagick::setFormat(string `$format`): bool

Configure le format de l'objet Imagick.

### Liste de paramètres

`format`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setGravity

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::setGravity — Définit la gravité

### Description

public function Imagick::setGravity(int `$gravity`): bool

Définit la propriété globale de gravité pour l'objet Imagick. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.0 ou supérieur.

### Liste de paramètres

`gravity`

  La propriété de gravité. Se référer à la liste des constantes de gravité.

### Valeurs de retour

Aucune valeur n'est retournée.

# Imagick::setImage

(PECL imagick 2, PECL imagick 3)

Imagick::setImage — Remplace l'image dans l'objet

### Description

public function Imagick::setImage(Imagick `$replace`): bool

Remplace l'image dans la séquence d'images de l'objet.

### Liste de paramètres

`replace`

  L'objet Imagick de remplacement

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::setImage()

Un exemple avec Imagick::setImage()

    <?php
    /* Crée les objets */
    $image = new Imagick('source.jpg');
    $replace = new Imagick('replace.jpg');

    /* source.jpg est remplacé par replace.jpg */
    $image->setImage($replace);

    /* Affichage de l'image */
    header('Content-type: image/jpeg');
    echo $image;

    ?>

# Imagick::setImageAlphaChannel

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setImageAlphaChannel — Définit le canal alpha de l'image

### Description

public function Imagick::setImageAlphaChannel(int `$mode`): bool

Active ou désactive le canal alpha de l'image. Le `mode` est l'une des constantes `Imagick::ALPHACHANNEL_*`. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.8 ou supérieur.

### Liste de paramètres

`mode`

  Une constante parmi les constantes `Imagick::ALPHACHANNEL_*`.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Voir aussi

- Imagick::setImageMatte() - Configure le canal mate de l'image
- Les constantes du canal Alpha Imagick

# Imagick::setImageArtifact

(PECL imagick 3)

Imagick::setImageArtifact — Définit l'artefact de l'image

### Description

public function Imagick::setImageArtifact(string `$artifact`, string `$value`): bool

Associe un artefact avec l'image. La différence entre les propriétés de l'image et l'artefact de l'image est que les propriétés sont publiques alors que les artefacts sont privés. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.5.7 ou supérieur.

### Liste de paramètres

`artifact`

  Le nom de l'artefact.

`value`

  La valeur de l'artefact.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::setImageArtifact()

    <?php
    function setImageArtifact() {

        $src1 = new \Imagick(realpath("./images/artifact/source1.png"));
        $src2 = new \Imagick(realpath("./images/artifact/source2.png"));

        $src2->setImageVirtualPixelMethod(\Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
        $src2->setImageArtifact('compose:args', "1,0,-0.5,0.5");
        $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);

        $src1->setImageFormat('png');
        header("Content-Type: image/png");
        echo $src1->getImagesBlob();
    }

    ?>

### Voir aussi

- Imagick::getImageArtifact() - Récupère l'artefact de l'image
- Imagick::deleteImageArtifact() - Supprime l'artefact d'une image

# Imagick::setImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::setImageAttribute — Définit un attribut d'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::setImageAttribute(string `$key`, string `$value`): bool

Définit un attribut d'image.

### Liste de paramètres

`key`

`value`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBackgroundColor — Configure la couleur de fond d'image

### Description

public function Imagick::setImageBackgroundColor(mixed `$background`): bool

Configure la couleur de fond d'image.

### Liste de paramètres

`background`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

# Imagick::setImageBias

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBias — Configure le biais pour les convolutions

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::setImageBias(float `$bias`): bool

Configure le biais pour les convolutions, utilisées avec la fonction Imagick::ConvolveImage().

### Liste de paramètres

`bias`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::setImageBias()

    <?php
    // Requiert ImageMagick version 6.9.0-1 pour avoir un effet sur convolveImage
    function setImageBias($bias) {
        $imagick = new \Imagick(realpath("images/stack.jpg"));

        $xKernel = array(
            -0.70, 0, 0.70,
            -0.70, 0, 0.70,
            -0.70, 0, 0.70
        );

        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($xKernel, \Imagick::CHANNEL_ALL);

        $imagick->setImageFormat('png');

        header('Content-type: image/png');
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageBiasQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::setImageBiasQuantum — Définit le biais de l'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::setImageBiasQuantum(float `$bias`): void

Définit le biais de l'image. Le biais doit être mis à l'échelle avec `0` (pas d'ajustement) à `1` (valeur quantique).

### Liste de paramètres

`bias`

### Valeurs de retour

# Imagick::setImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBluePrimary — Configure la chromaticité du point bleu

### Description

public function Imagick::setImageBluePrimary(float `$x`, float `$y`): bool

Configure la chromaticité du point bleu.

### Liste de paramètres

`x`

`y`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBorderColor — Configure la couleur de bordure

### Description

public function Imagick::setImageBorderColor(mixed `$border`): bool

Configure la couleur de bordure.

### Liste de paramètres

`border`

  La couleur de bordure

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

# Imagick::setImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageChannelDepth — Configure la profondeur d'un canal

### Description

public function Imagick::setImageChannelDepth(int `$channel`, int `$depth`): bool

Configure la profondeur d'un canal.

### Liste de paramètres

`channel`

`depth`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageClipMask — Définit le masque du clip de l'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::setImageClipMask(Imagick `$clip_mask`): bool

Définit le masque du clip de l'image depuis un autre objet Imagick. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`clip_mask`

  L'objet Imagick contenant le masque du clip.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::setImageClipMask()

    <?php
    function setImageClipMask($imagePath) {
        $imagick = new \Imagick();
        $imagick->readImage(realpath($imagePath));

        $width = $imagick->getImageWidth();
        $height = $imagick->getImageHeight();

        $clipMask = new \Imagick();
        $clipMask->newPseudoImage(
            $width,
            $height,
            "canvas:transparent"
        );

        $draw = new \ImagickDraw();
        $draw->setFillColor('white');
        $draw->circle(
            $width / 2,
            $height / 2,
            ($width / 2) + ($width / 4),
            $height / 2
        );
        $clipMask->drawImage($draw);
        $imagick->setImageClipMask($clipMask);

        $imagick->negateImage(false);
        $imagick->setFormat("png");

        header("Content-Type: image/png");
        echo $imagick->getImagesBlob();

    }

    ?>

# Imagick::setImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColormapColor — Configure une couleur de la carte

### Description

public function Imagick::setImageColormapColor(int `$index`, ImagickPixel `$color`): bool

Configure une couleur de la carte de couleurs de l'image.

### Liste de paramètres

`index`

`color`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColorspace — Configure l'espace de couleurs de l'image

### Description

public function Imagick::setImageColorspace(int `$colorspace`): bool

Configure l'espace de couleurs de l'image. Cette méthode doit être utilisée lors de la création de nouvelles images. Pour changer l'espace de couleurs d'une image existante, il faut utiliser la méthode Imagick::transformImageColorspace().

### Liste de paramètres

`colorspace`

  Une des constantes COLORSPACE

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompose — Configure l'opérateur de composition de l'image

### Description

public function Imagick::setImageCompose(int `$compose`): bool

Configure l'opérateur de composition de l'image. Cette fonction est pratique pour spécifier la méthode de composition des miniatures, lors de l'utilisation de la méthode Imagick::montageImage().

### Liste de paramètres

`compose`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompression — Configure la compression de l'image

### Description

public function Imagick::setImageCompression(int `$compression`): bool

Configure la compression de l'image.

### Liste de paramètres

`compression`

  Une des constantes `COMPRESSION`.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompressionQuality — Spécifie la qualité de compression de l'image

### Description

public function Imagick::setImageCompressionQuality(int `$quality`): bool

Spécifie la qualité de compression de l'image.

### Liste de paramètres

`quality`

  La qualité de compression de l'image sous forme d'entier.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::setImageCompressionQuality()

    <?php
    function setImageCompressionQuality($imagePath, $quality) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageCompressionQuality($quality);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDelay — Configure le délai de l'image

### Description

public function Imagick::setImageDelay(int `$delay`): bool

Configure le délai de l'image. Pour une image animée, ce sera le temps pendant lequel la frame sera affichée, avant d'afficher la frame suivante.

Le délai peut être défini individuellement pour chaque frame de l'image.

### Liste de paramètres

`delay`

  Le temps, exprimé en 'ticks', pendant lequel l'image sera affichée. Pour les GIFs animés, il y a 100 ticks par seconde, aussi, une valeur de 20 vaudra 20/100 d'une seconde, soit 1/5ème de seconde.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Modification d'un GIF animé avec Imagick::setImageDelay()

    <?php

    // Modifie un GIF animé permettant d'afficher les frames avec une vitesse variable,
    // allant de 50ms à 0ms, ce qui fera que la frame ne sera pas affichée dans
    // la plupart des navigateurs.
    $imagick = new Imagick(realpath("Test.gif"));
    $imagick = $imagick->coalesceImages();

    $frameCount = 0;

    foreach ($imagick as $frame) {
        $imagick->setImageDelay((($frameCount % 11) * 5));
        $frameCount++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/chemin/de/sauvegarde/output.gif", true);

    ?>

# Imagick::setImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDepth — Configure la profondeur de l'image

### Description

public function Imagick::setImageDepth(int `$depth`): bool

Configure la profondeur de l'image.

### Liste de paramètres

`depth`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDispose — Configure la méthode de récupération

### Description

public function Imagick::setImageDispose(int `$dispose`): bool

Configure la méthode de récupération.

### Liste de paramètres

`dispose`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageExtent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageExtent — Configure la taille d'une image

### Description

public function Imagick::setImageExtent(int `$columns`, int `$rows`): bool

Configure la taille d'une image (le nombre de colonnes et de lignes).

### Liste de paramètres

`columns`

`rows`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFilename — Configure le nom de fichier d'une image dans une séquence

### Description

public function Imagick::setImageFilename(string `$filename`): bool

Configure le nom de fichier d'une image dans une séquence.

### Liste de paramètres

`filename`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFormat — Configure le format d'une image dans une séquence

### Description

public function Imagick::setImageFormat(string `$format`): bool

Configure le format d'une image dans une séquence.

### Liste de paramètres

`format`

  La représentation en chaîne du format d'image. Les formats supportés dépendent de l'installation ImageMagick.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGamma — Configure la correction gamma

### Description

public function Imagick::setImageGamma(float `$gamma`): bool

Configure la correction gamma.

### Liste de paramètres

`gamma`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageGravity — Définit la gravité de l'image

### Description

public function Imagick::setImageGravity(int `$gravity`): bool

Définit la propriété de gravité pour l'image courante. Cette méthode peut être utilisée pour définir la propriété de gravité pour une seule image d'une séquence. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.4 ou supérieur.

### Liste de paramètres

`gravity`

  La propriété de gravité. Se référer à la liste des constantes de gravité.

### Valeurs de retour

Aucune valeur n'est retournée.

# Imagick::setImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGreenPrimary — Configure la chromaticité du point vert

### Description

public function Imagick::setImageGreenPrimary(float `$x`, float `$y`): bool

Configure la chromaticité du point vert.

### Liste de paramètres

`x`

`y`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIndex — Modifie la position de l'itérateur

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::setImageIndex(int `$index`): bool

Modifie la position de l'itérateur à l'index `index`.

Cette méthode est obsolète. Voir Imagick::setIteratorIndex()

### Liste de paramètres

`index`

  La position à laquelle mettre l'itérateur

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterlaceScheme — Configure la méthode d'entrelacement de l'image

### Description

public function Imagick::setImageInterlaceScheme(int `$interlace_scheme`): bool

Configure la méthode d'entrelacement de l'image.

### Liste de paramètres

`interlace_scheme`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterpolateMethod — Configure la méthode d'interpolation de l'image

### Description

public function Imagick::setImageInterpolateMethod(int `$method`): bool

Configure la méthode d'interpolation de l'image.

### Liste de paramètres

`method`

  Une constante `Imagick::INTERPOLATE_*`.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIterations — Configure les itérations de l'image

### Description

public function Imagick::setImageIterations(int `$iterations`): bool

Configure le nombre d'itérations d'affichage d'une image.

### Liste de paramètres

`iterations`

  Le nombre d'itérations de l'image. Défini à 0, la boucle sera infinie.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Utilisation basique de la méthode Imagick::setImageIterations()

    <?php

    $imagick = new Imagick(realpath("Test.gif"));

    $imagick = $imagick->coalesceImages();
    $imagick->setImageIterations(1);
    $imagick = $imagick->deconstructImages();

    $imagick->writeImages('/chemin/de/sauvegarde/OnceOnly.gif', true);

    ?>

# Imagick::setImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatte — Configure le canal mate de l'image

### Description

public function Imagick::setImageMatte(bool `$matte`): bool

Configure le canal mate de l'image. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`matte`

  `true` active le canal mate, et `false` le désactive.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatteColor — Configure la couleur mate

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::setImageMatteColor(mixed `$matte`): bool

Configure la couleur mate.

### Liste de paramètres

`matte`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Permet désormais l'utilisation d'une chaîne pour représenter la couleur. Les versions précédentes ne permettaient que les objets ImagickPixel.

# Imagick::setImageOpacity

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOpacity — Configure le niveau d'opacité de l'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::setImageOpacity(float `$opacity`): bool

Configure le niveau d'opacité de l'image. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.1 ou supérieur. Cette méthode opère sur tous les canaux, ce qui signifie que, par exemple, une valeur d'opacité de 0.5 va définir toutes les zones transparentes en partiellement opaques. Pour ajouter de la transparence aux zones qui ne sont actuellement pas transparentes, utiliser la méthode Imagick::evaluateImage().

### Liste de paramètres

`opacity`

  Le niveau de transparence : 1.0 est totalement opaque, et 0.0 est totalement transparent.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::setImageOpacity()

Un exemple avec Imagick::setImageOpacity()

    <?php
    /* Crée un objet  */
    $image = new Imagick('source.png');

    /* Configure l'opacité */
    $image->setImageOpacity(0.7);

    /* Affiche l'image */
    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::setImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOrientation — Configure l'orientation de l'image

### Description

public function Imagick::setImageOrientation(int `$orientation`): bool

Configure l'orientation de l'image.

### Liste de paramètres

`orientation`

  Une des constantes d'orientation

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::setImageOrientation()

    <?php
    function setImageOrientation($imagePath, $orientationType) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOrientation($orientationType);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::setImagePage — Configure la géométrie de la page de l'image

### Description

public function Imagick::setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Configure la géométrie de la page de l'image.

### Liste de paramètres

`width`

`height`

`x`

`y`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProfile — Ajoute un profil à un objet Imagick

### Description

public function Imagick::setImageProfile(string `$name`, string `$profile`): bool

Ajoute un nouveau profil à un objet Imagick. Si un profil ajouté a le même nom qu'un profil déjà ajouté, il sera remplacé. Cette méthode diffère de Imagick::ProfileImage(), car elle n'applique aucun profil CMS.

### Liste de paramètres

`name`

`profile`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProperty — Configure une propriété d'image

### Description

public function Imagick::setImageProperty(string `$name`, string `$value`): bool

Configure la propriété d'image `name` à la valeur `value`. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.2 ou supérieur.

### Liste de paramètres

`name`

`value`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::setImageProperty()

Définit et récupère les propriétés d'une image.

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Voir aussi

- Imagick::getImageProperty() - Retourne une propriété d'une image

# Imagick::setImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRedPrimary — Configure la chromaticité du point rouge

### Description

public function Imagick::setImageRedPrimary(float `$x`, float `$y`): bool

Configure la chromaticité du point rouge.

### Liste de paramètres

`x`

`y`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRenderingIntent — Configure le type de rendu de l'image

### Description

public function Imagick::setImageRenderingIntent(int `$rendering_intent`): bool

Configure le type de rendu de l'image.

### Liste de paramètres

`rendering_intent`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setImageResolution — Configure la résolution de l'image

### Description

public function Imagick::setImageResolution(float `$x_resolution`, float `$y_resolution`): bool

Configure la résolution de l'image.

### Liste de paramètres

`x_resolution`

`y_resolution`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::setImageResolution()

    <?php
    function setImageResolution($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageResolution(50, 50);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::setImageScene — Configure la scène de l'image

### Description

public function Imagick::setImageScene(int `$scene`): bool

Configure la scène de l'image.

### Liste de paramètres

`scene`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::setImageTicksPerSecond — Configure le nombre de ticks par seconde de l'image

### Description

public function Imagick::setImageTicksPerSecond(int `$ticks_per_second`): bool

Ajuste la durée qu'une frame d'une image animée sera affichée.

> Note:

> Pour les GIFs animés, cette méthode ne modifie pas le nombre de 'ticks' par seconde, qui sera toujours défini à 100. Au lieu de cela, la méthode va ajuster la durée d'affichage de la frame pour simuler une modification du ticks par seconde.

> Par exemple, pour un GIF animé où chaque frame est affichée pendant 20 ticks (1/5ème d'une seconde), lorsque cette méthode est appelée sur chaque frame de l'image avec un argument de `50`, les frames seront ajustées pour s'afficher pendant 40 ticks (2/5ème d'une seconde) et l'animation sera jouée à une vitesse de moitié moins par rapport à la vitesse originale.

### Liste de paramètres

`ticks_per_second`

  La durée pendant laquelle une image sera affichée, exprimée en ticks par seconde.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Modification d'un GIF animé avec la méthode Imagick::setImageTicksPerSecond()

    <?php

    // Modification d'un GIF animé pour que la première moitié du GIF soit jouée
    // à une vitesse moitié moindre, et que la seconde moitié soit jouée à une vitesse
    // double de la vitesse courante.

    $imagick = new Imagick(realpath("Test.gif"));
    $imagick = $imagick->coalesceImages();

    $totalFrames = $imagick->getNumberImages();

    $frameCount = 0;

    foreach ($imagick as $frame) {
        $imagick->setImageTicksPerSecond(50);

        if ($frameCount < ($totalFrames / 2)) {
            // Modification de la frame pour qu'elle s'affiche pendant deux fois plus de temps qu'actuellement
            $imagick->setImageTicksPerSecond(50);
        } else {

            // Modification de la frame pour qu'elle s'affiche pendant deux fois moins de temps qu'actuellement
            $imagick->setImageTicksPerSecond(200);
        }

        $frameCount++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/chemin/de/sauvegarde/output.gif", true);

    ?>

# Imagick::setImageType

(PECL imagick 2, PECL imagick 3)

Imagick::setImageType — Configure le type d'image

### Description

public function Imagick::setImageType(int `$image_type`): bool

Configure le type d'image.

### Liste de paramètres

`image_type`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::setImageUnits — Configure les unités de résolution de l'image

### Description

public function Imagick::setImageUnits(int `$units`): bool

Configure les unités de résolution de l'image.

### Liste de paramètres

`units`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageVirtualPixelMethod — Configure la méthode du point virtuel de l'image

### Description

public function Imagick::setImageVirtualPixelMethod(int `$method`): bool

Configure la méthode du point virtuel de l'image.

### Liste de paramètres

`method`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::setImageWhitePoint — Configure la chromaticité du point blanc

### Description

public function Imagick::setImageWhitePoint(float `$x`, float `$y`): bool

Configure la chromaticité du point blanc.

### Liste de paramètres

`x`

`y`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::setInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setInterlaceScheme — Configure la compression de l'image

### Description

public function Imagick::setInterlaceScheme(int `$interlace_scheme`): bool

Configure la compression de l'image.

### Liste de paramètres

`interlace_scheme`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setIteratorIndex — Déplace l'itérateur

### Description

public function Imagick::setIteratorIndex(int `$index`): bool

Déplace l'itérateur à la position `index` dans la séquence d'images. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`index`

  La position finale de l'itérateur

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::setIteratorIndex()

Crée des images, définit et récupère l'index de l'itérateur.

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Voir aussi

- Imagick::getIteratorIndex() - Lit l'index de l'image active courante
- Imagick::getImageIndex() - Lit l'index de l'image courante
- Imagick::setImageIndex() - Modifie la position de l'itérateur

# Imagick::setLastIterator

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::setLastIterator — Positionne l'itérateur Imagick à la dernière image

### Description

public function Imagick::setLastIterator(): bool

Positionne l'itérateur Imagick à la dernière image.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setOption

(PECL imagick 2, PECL imagick 3)

Imagick::setOption — Configure une option d'un objet Imagick

### Description

public function Imagick::setOption(string `$key`, string `$value`): bool

Configure une ou plusieurs options de l'objet Imagick.

### Liste de paramètres

`key`

`value`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Tentative d'atteindre la taille '$extent' avec Imagick::setOption()

    <?php
        function renderJPG($extent) {
            $imagePath = $this->control->getImagePath();
            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('jpg');
            $imagick->setOption('jpeg:extent', $extent);
            header("Content-Type: image/jpg");
            echo $imagick->getImageBlob();
        }

    ?>

Exemple #2 Exemple avec Imagick::setOption()

    <?php
        function renderPNG($imagePath, $format) {

            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('png');
            $imagick->setOption('png:format', $format);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

        //Save as 64bit PNG.
        renderPNG($imagePath, 'png64');

    ?>

Exemple #3 Exemple avec Imagick::setOption()

    <?php
        function renderCustomBitDepthPNG() {
            $imagePath = $this->control->getImagePath();
            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('png');

            $imagick->setOption('png:bit-depth', '16');
            $imagick->setOption('png:color-type', 6);
            header("Content-Type: image/png");
            $crash = true;
            if ($crash) {
                echo $imagick->getImageBlob();
            }
            else {
                $tempFilename = tempnam('./', 'imagick');
                $imagick->writeimage(realpath($tempFilename));
                echo file_get_contents($tempFilename);
            }
        }

    ?>

# Imagick::setPage

(PECL imagick 2, PECL imagick 3)

Imagick::setPage — Configure la géométrie de la page de l'objet Imagick

### Description

public function Imagick::setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Configure la géométrie de la page de l'objet Imagick.

### Liste de paramètres

`width`

`height`

`x`

`y`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setPointSize — Définit la taille du point

### Description

public function Imagick::setPointSize(float `$point_size`): bool

Définit la propriété de la taille du point de l'objet. Cette méthode peut être utilisée pour, par exemple, définir la taille de la police de caractères pour la légende : pseudo-format. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.7 ou supérieur.

### Liste de paramètres

`point_size`

  La taille du point.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::setPointSize()

Exemple d'utilisation de la méthode Imagick::setPointSize

    <?php
    /* Crée un nouvel objet imagick */
    $im = new Imagick();

    /* Définit la police de caractères pour l'objet */
    $im->setFont("example.ttf");

    /* Définit la taille du point */
    $im->setPointSize(12);

    /* Crée une nouvelle légende */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Faites quelques choses avec votre nouvelle image */
    ?>

### Voir aussi

- Imagick::getPointSize() - Récupère la taille du point

# Imagick::setProgressMonitor

(PECL imagick 3 >= 3.3.0)

Imagick::setProgressMonitor — Définit une fonction de rappel à appeler pendant le traitement

### Description

public function Imagick::setProgressMonitor(callable `$callback`): bool

Définit une fonction de rappel qui sera appelée pendant le traitement de l'image Imagick.

### Liste de paramètres

`callback`

  La fonction de progression à appeler. Elle doit retourner true si le traitement de l'image doit continuer, ou false si elle doit être annulée. Le paramètre offset indique la progression et le paramètre span indique la quantité totale de travail à effectuer.

  function callback ( mixed `$offset` , mixed `$span` ): bool
  Attention

  Les valeurs passées à la fonction de rappel ne sont pas cohérentes. En particulier, le paramètre span peut augmenter pendant le traitement de l'image. En raison de cela, le calcul du pourcentage complet d'une opération d'image n'est pas trivial.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::setProgressMonitor()

    <?php
            $abortReason = null;

            try {
                $imagick = new \Imagick(realpath($this->control->getImagePath()));
                $startTime = time();

                $callback = function ($offset, $span)  use ($startTime, &$abortReason) {
                    if (((100 * $offset) / $span)  > 20) {
                        $abortReason = "Processing reached 20%";
                        return false;
                    }

                    $nowTime = time();

                    if ($nowTime - $startTime > 5) {
                        $abortReason = "Image processing took more than 5 seconds";
                        return false;
                    }
                    if (($offset % 5) == 0) {
                        echo "Progress: $offset / $span <br/>";
                    }
                    return true;
                };

                $imagick->setProgressMonitor($callback);

                $imagick->waveImage(2, 15);

                echo "Data len is: ".strlen($imagick->getImageBlob());
            }
            catch(\ImagickException $e) {
                if ($abortReason != null) {
                    echo "Image processing was aborted: ".$abortReason."<br/>";
                }
                else {
                    echo "ImagickException caught: ".$e->getMessage()." Exception type is ".get_class($e);
                }
            }

    ?>

# Imagick::setRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::setRegistry — Définit l'entrée du registre ImageMagick nommée clé pour valeur

### Description

public static function Imagick::setRegistry(string `$key`, string `$value`): bool

Définit l'entrée du registre ImageMagick nommée clé pour value. C'est le plus utile pour définir "temporary-path" qui contrôle où ImageMagick crée des images temporaires par exemple lors du traitement de PDF.

### Liste de paramètres

`key`

`value`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setResolution — Configure la résolution de l'image

### Description

public function Imagick::setResolution(float `$x_resolution`, float `$y_resolution`): bool

Configure la résolution de l'image.

### Liste de paramètres

`x_resolution`

  La résolution horizontale.

`y_resolution`

  La résolution verticale.

### Valeurs de retour

Retourne `true` en cas de succès.

### Notes

Imagick::setResolution() doit être appelée avant le chargement ou la création d'une image.

### Voir aussi

- Imagick::setImageResolution() - Configure la résolution de l'image
- Imagick::getImageResolution() - Lit les résolutions en X et Y d'une image

# Imagick::setResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::setResourceLimit — Définit la limite pour une ressource particulière

### Description

public static function Imagick::setResourceLimit(int `$type`, int `$limit`): bool

Cette méthode est utilisée pour modifier les limites de la ressource de la bibliothèque sous-jacente ImageMagick.

### Liste de paramètres

`type`

  Se référer à la liste des constantes de type de ressources.

`limit`

  L'une des constantes de type de ressources. L'unité dépend du type de la ressource à limiter.

### Valeurs de retour

Retourne `true` en cas de succès.

### Voir aussi

- Imagick::getResourceLimit() - Retourne la limite de la ressource

# Imagick::setSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::setSamplingFactors — Configure les facteurs d'échantillonnage de l'image

### Description

public function Imagick::setSamplingFactors(array `$factors`): bool

Configure les facteurs d'échantillonnage de l'image.

### Liste de paramètres

`factors`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::setSamplingFactors()

    <?php
    function setSamplingFactors($imagePath) {

        $imagePath = "../imagick/images/FineDetail.png";
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('jpg');
        $imagick->setSamplingFactors(array('2x2', '1x1', '1x1'));

        $compressed = $imagick->getImageBlob();

        $reopen = new \Imagick();
        $reopen->readImageBlob($compressed);

        $reopen->resizeImage(
            $reopen->getImageWidth() * 4,
            $reopen->getImageHeight() * 4,
            \Imagick::FILTER_POINT,
            1
        );

        header("Content-Type: image/jpg");
        echo $reopen->getImageBlob();
    }

    ?>

# Imagick::setSize

(PECL imagick 2, PECL imagick 3)

Imagick::setSize — Configure la taille de l'objet Imagick

### Description

public function Imagick::setSize(int `$columns`, int `$rows`): bool

Configure la taille de l'objet Imagick. Configurer cet attribut avant d'ouvrir une image brute, aux formats RGB, GRAY ou CMYK.

### Liste de paramètres

`columns`

`rows`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::setSizeOffset — Configure la taille et la position de l'objet Imagick

### Description

public function Imagick::setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool

Configure la taille et la position de l'objet Imagick. Configurer ces attributs avant de lire une image brute, aux formats RGB, GRAY ou CMYK. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`columns`

`rows`

`offset`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::setType

(PECL imagick 2, PECL imagick 3)

Imagick::setType — Configure l'attribut de l'image

### Description

public function Imagick::setType(int `$image_type`): bool

Configure l'attribut de l'image.

### Liste de paramètres

`image_type`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::shadeImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadeImage — Crée un effet 3D

### Description

public function Imagick::shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool

Projette une lumière distante sur l'image pour créer un effet 3D. Il est possible de contrôler le positionnement de la lumière avec l'azimut et l'élévation ; l'azimut est mesuré en degré de l'axe X et l'élévation est mesurée sur l'axe Z. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`gray`

`azimuth`

`elevation`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException en cas d'échec.

### Exemples

Exemple #1 Exemple avec Imagick::shadeImage()

    <?php
    function shadeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadeImage(true, 45, 20);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shadowImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadowImage — Simule une ombre sur l'image

### Description

public function Imagick::shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool

Simule une ombre sur l'image.

### Liste de paramètres

`opacity`

`sigma`

`x`

`y`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::shadowImage()

    <?php
    function shadowImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadowImage(0.4, 10, 50, 5);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::sharpenImage — Aiguise une image

### Description

public function Imagick::sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Aiguise une image. Nous modifions l'image avec un opérateur Gaussien utilisant le paramètre `radius` et la déviation standard `sigma`. Pour de bons résultats, le paramètre `radius` doit être plus élevé que le paramètre `sigma`. Utiliser un `radius` de 0 et Imagick::sharpenImage() choisira un bon `radius` à sa place.

### Liste de paramètres

`radius`

`sigma`

`channel`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::sharpenImage()

    <?php
    function sharpenImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sharpenimage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shaveImage

(PECL imagick 2, PECL imagick 3)

Imagick::shaveImage — Supprime les pixels du bord de l'image

### Description

public function Imagick::shaveImage(int `$columns`, int `$rows`): bool

Supprime les pixels du bord de l'image. Alloue la mémoire nécessaire pour la structure de la nouvelle image et retourne un pointeur vers la nouvelle image.

### Liste de paramètres

`columns`

`rows`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::shaveImage()

    <?php
    function shaveImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shaveImage(100, 50);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shearImage

(PECL imagick 2, PECL imagick 3)

Imagick::shearImage — Crée un parallélogramme

### Description

public function Imagick::shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool

Bouge le côté d'une image le long des axes X ou Y, créant un parallélogramme. Une direction X coupe le côté le long de l'axe X, tandis qu'une direction Y coupe le côté le long de l'axe Y. La coupe est contrôlée par l'angle de coupe. Pour une coupe de direction X, x_shear sera mesuré relativement à l'axe Y, et similairement, pour une coupe de direction Y, y_shear est mesuré relativement à l'axe X. Les triangles vides laissés après la coupe seront remplis avec la couleur d'arrière plan.

### Liste de paramètres

`background`

  La couleur d'arrière plan

`x_shear`

  Le nombre de degrés à couper suivant l'axe X

`y_shear`

  Le nombre de degrés à couper suivant l'axe Y

### Valeurs de retour

Retourne `true` en cas de succès.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Autorise maintenant une chaîne représentant la couleur comme premier paramètre. Les anciennes versions n'autorisent que des objets ImagickPixel.

### Exemples

Exemple #1 Exemple avec Imagick::shearImage()

    <?php
    function shearImage($imagePath, $color, $shearX, $shearY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shearimage($color, $shearX, $shearY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sigmoidalContrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::sigmoidalContrastImage — Ajuste le contraste de l'image

### Description

public function Imagick::sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Ajuste le contraste de l'image avec un algorithme de contraste sigmoïde non linéaire. Augmenter le contraste de l'image en utilisant une fonction de transfert sigmoïde sans saturer les lumières hautes et les ombres. Le contraste indique de combien il faut augmenter le contraste (0 pour ne rien faire, 3 est une valeur typique, 20 est une valeur élevée) ; le point du milieu indique où les tons moyens seront dans l'image résultante (0 correspond à blanc, 50 correspond à gris, 100 correspond à noir). Définir le paramètre `sharpen` à `true` pour augmenter le contraste de l'image, sinon, le contraste sera réduit.

Voir aussi les » exemples d'ImageMagick V6 - Les transformations d'images - Le contraste non-linéaire

### Liste de paramètres

`sharpen`

  Si vaut `true`, le contraste augmentera, sinon, le contraste diminuera.

`alpha`

  La quantité de contraste à appliquer. -1 représente une toute petite quantité, 5 représente une quantité significative, et 20 est le maximum.

`beta`
  Où doit se situer le milieu du gradient. Cette valeur doit être dans l'intervalle 0-1, multiplié par la valeur du quantum pour ImageMagick.
`channel`

  Canaux de couleurs sur lesquels le contraste doit s'appliquer.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Crée un gradient d'image en utilisant la méthode Imagick::sigmoidalContrastImage() pour mélanger deux images en douceur, où le mélange est défini par les variables $contrast et $midpoint.

    <?php

    function generateBlendImage($width, $height, $contrast = 10, $midpoint = 0.5) {
        $imagick = new Imagick();
        $imagick->newPseudoImage($width, $height, 'gradient:black-white');
        $quanta = $imagick->getQuantumRange();
        $imagick->sigmoidalContrastImage(true, $contrast, $midpoint * $quanta["quantumRangeLong"]);

        return $imagick;
    }

    ?>

# Imagick::sketchImage

(PECL imagick 2, PECL imagick 3)

Imagick::sketchImage — Simule un crayon à main levée

### Description

public function Imagick::sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool

Simule un crayon à main levée. Nous modifions l'image en utilisant un opérateur Gaussien avec le paramètre `radius` et la déviation standard `sigma`. Pour de bons résultats, le paramètre `radius` doit être plus élevé que le paramètre `sigma`. Utiliser un `radius` de 0 et Imagick::sketchImage() sélectionnera automatiquement un bon radius à sa place. Le paramètre `angle` fournit l'angle du flou du mouvement. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`radius`

`sigma`

`angle`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::sketchImage()

    <?php
    function sketchImage($imagePath, $radius, $sigma, $angle) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sketchimage($radius, $sigma, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::smushImages

(PECL imagick 3 >= 3.3.0)

Imagick::smushImages — Prend toutes les images du pointeur d'image actuel jusqu'à la fin de la liste d'images et les écrase

### Description

public function Imagick::smushImages(bool `$stack`, int `$offset`): Imagick

Prend toutes les images du pointeur d'image actuel jusqu'à la fin de la liste d'images et les écrase les unes sur les autres de haut en bas si le paramètre stack est vrai, sinon de gauche à droite.

### Liste de paramètres

`stack`

`offset`

### Valeurs de retour

La nouvelle image écrasée.

### Exemples

Exemple #1 Imagick::smushImages()

    <?php
    function smushImages($imagePath, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = new \Imagick(realpath($imagePath2));

        $imagick->addimage($imagick2);
        $smushed = $imagick->smushImages(false, 50);
        $smushed->setImageFormat('jpg');
        header("Content-Type: image/jpg");
        echo $smushed->getImageBlob();
    }

    ?>

# Imagick::solarizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::solarizeImage — Applique un effet de solarisation à l'image

### Description

public function Imagick::solarizeImage(int `$threshold`): bool

Applique un effet de solarisation à l'image, similaire à l'effet effectué dans une chambre noire en exposant des zones du papier photo sensible à la lumière. Le seuil `threshold` peut aller de 0 à `QuantumRange` et mesure la densité de la solarisation.

### Liste de paramètres

`threshold`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::solarizeImage()

    <?php
    function solarizeImage($imagePath, $solarizeThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->solarizeImage($solarizeThreshold * \Imagick::getQuantum());
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sparseColorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::sparseColorImage — Interpole les couleurs

### Description

public function Imagick::sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Le tableau fourni par le paramètre `arguments` contient les valeurs numériques utilisées par cette méthode pour interpoler les couleurs trouvées aux coordonnées de l'image entière en utilisant le paramètre `sparse_method`. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.4.5 ou supérieur.

### Liste de paramètres

`SPARSE_METHOD`

  Se référer à la liste des constantes pour la méthode sparse.

`arguments`

  Un tableau contenant les coordonnées. Le tableau est au format `array(1,1, 2,45)`.

`channel`

  Fournit une constante de canal valide pour votre mode de canal. Pour l'appliquer à plus d'un canal, combinez les constantes de canaux en utilisant un opérateur sur les bits. Par défaut, vaut `Imagick::CHANNEL_DEFAULT`. Reportez-vous à la liste des constantes de canaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::sparseColorImage() et SPARSECOLORMETHOD_BARYCENTRIC

    <?php
        function renderImageBarycentric2() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(
                400, 400,
                $points,
                \Imagick::SPARSECOLORMETHOD_BARYCENTRIC
            );
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemple #2 Exemple avec Imagick::sparseColorImage() et SPARSECOLORMETHOD_BILINEAR

    <?php
        function renderImageBilinear() {
            $points = [[0.30, 0.10, 'red'], [0.10, 0.80, 'blue'], [0.70, 0.60, 'lime'], [0.80, 0.20, 'yellow'],];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_BILINEAR);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemple #3 Exemple avec Imagick::sparseColorImage() et SPARSECOLORMETHOD_SPEPARDS

    <?php
        function renderImageShepards() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(600, 600, $points, \Imagick::SPARSECOLORMETHOD_SPEPARDS);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemple #4 Exemple avec Imagick::sparseColorImage() et SPARSECOLORMETHOD_VORONOI

    <?php
        function renderImageVoronoi() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_VORONOI);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemple #5 Exemple avec Imagick::sparseColorImage() et SPARSECOLORMETHOD_BARYCENTRIC

    <?php
        function renderImageBarycentric() {
            $points = [
                [0, 0, 'skyblue'],
                [-1, 1, 'skyblue'],
                [1, 1, 'black'],
            ];
            $imagick = createGradientImage(600, 200, $points, \Imagick::SPARSECOLORMETHOD_BARYCENTRIC);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Exemple #6 createGradientImage est utilisé par les autres exemples. Imagick::sparseColorImage()

    <?php
    function createGradientImage($width, $height, $colorPoints, $sparseMethod, $absolute = false) {

        $imagick = new \Imagick();
        $imagick->newImage($width, $height, "white");
        $imagick->setImageFormat("png");

        $barycentricPoints = array();

        foreach ($colorPoints as $colorPoint) {

            if ($absolute == true) {
                $barycentricPoints[] = $colorPoint[0];
                $barycentricPoints[] = $colorPoint[1];
            }
            else {
                $barycentricPoints[] = $colorPoint[0] * $width;
                $barycentricPoints[] = $colorPoint[1] * $height;
            }

            if (is_string($colorPoint[2])) {
                $imagickPixel = new \ImagickPixel($colorPoint[2]);
            }
            else if ($colorPoint[2] instanceof \ImagickPixel) {
                $imagickPixel = $colorPoint[2];
            }
            else{
                $errorMessage = sprintf(
                    "Value %s is neither a string nor an ImagickPixel class. Cannot use as a color.",
                    $colorPoint[2]
                );

                throw new \InvalidArgumentException(
                    $errorMessage
                );
            }

            $red = $imagickPixel->getColorValue(\Imagick::COLOR_RED);
            $green = $imagickPixel->getColorValue(\Imagick::COLOR_GREEN);
            $blue = $imagickPixel->getColorValue(\Imagick::COLOR_BLUE);
            $alpha = $imagickPixel->getColorValue(\Imagick::COLOR_ALPHA);

            $barycentricPoints[] = $red;
            $barycentricPoints[] = $green;
            $barycentricPoints[] = $blue;
            $barycentricPoints[] = $alpha;
        }

        $imagick->sparseColorImage($sparseMethod, $barycentricPoints);

        return $imagick;
    }

    ?>

# Imagick::spliceImage

(PECL imagick 2, PECL imagick 3)

Imagick::spliceImage — Joint une couleur solide dans l'image

### Description

public function Imagick::spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Joint une couleur solide dans l'image.

### Liste de paramètres

`width`

`height`

`x`

`y`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::spliceImage()

    <?php
    function spliceImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spliceImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::spreadImage

(PECL imagick 2, PECL imagick 3)

Imagick::spreadImage — Bouge aléatoirement chaque pixel d'un bloc

### Description

public function Imagick::spreadImage(float `$radius`): bool

Effet spécial qui bouge aléatoirement chaque pixel d'un bloc, défini par le paramètre `radius`.

### Liste de paramètres

`radius`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::spreadImage()

    <?php
    function spreadImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spreadImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::statisticImage

(PECL imagick 3 >= 3.3.0)

Imagick::statisticImage — Modifie une image en utilisant une fonction statistique

### Description

public function Imagick::statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Remplace chaque pixel par la statistique correspondante du voisinage de la largeur et de la hauteur spécifiées.

### Liste de paramètres

`type`

`width`

`height`

`channel`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::statisticImage()

    <?php
    function statisticImage($imagePath, $statisticType, $width, $height, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->statisticImage(
            $statisticType,
            $width,
            $height,
            $channel
        );

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    statisticImage($imagePath, \Imagick::STATISTIC_MEDIAN, 5, 5, \Imagick::CHANNEL_DEFAULT);

    ?>

# Imagick::steganoImage

(PECL imagick 2, PECL imagick 3)

Imagick::steganoImage — Cache un filigrane numérique dans l'image

### Description

public function Imagick::steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick

Cache un filigrane numérique dans l'image. Récupérer le filigrane plus tard pour prouver l'authenticité de l'image. Le paramètre `offset` définit la position de départ à partir de laquelle on cache le filigrane.

### Liste de paramètres

`watermark_wand`

`offset`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::stereoImage

(PECL imagick 2, PECL imagick 3)

Imagick::stereoImage — Fusionne 2 images

### Description

public function Imagick::stereoImage(Imagick `$offset_wand`): bool

Fusionne 2 images et produit une seule image représentant la fusion de l'image de gauche et de droite d'une paire stéréo.

### Liste de paramètres

`offset_wand`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::stripImage

(PECL imagick 2, PECL imagick 3)

Imagick::stripImage — Supprime d'une image tous les profils et les commentaires

### Description

public function Imagick::stripImage(): bool

Supprime d'une image tous les profils et les commentaires.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

# Imagick::subImageMatch

(PECL imagick 3 >= 3.3.0)

Imagick::subImageMatch — Recherche une sous-image dans l'image courante et renvoie une image de similarité

### Description

public function Imagick::subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick

Recherche une sous-image dans l'image courante et renvoie une image de similarité telle qu'un emplacement de correspondance exacte est complètement blanc et si aucun des pixels ne correspond, noir, sinon un certain niveau de gris entre les deux. Il est également possible de passer les paramètres facultatifs bestMatch et similarity. Après avoir appelé la fonction, similarity sera défini sur le 'score' de la similarité entre la sous-image et la position correspondante dans l'image plus grande, bestMatch contiendra un tableau associatif avec les éléments x, y, width, height qui décrivent la région correspondante.

### Liste de paramètres

`Imagick`

`offset`

`similarity`

  Une nouvelle image qui affiche la quantité de similarité à chaque pixel.

### Valeurs de retour

### Exemples

Exemple #1 Imagick::subImageMatch()

    <?php
    function subImageMatch($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = clone $imagick;
        $imagick2->cropimage(40, 40, 250, 110);
        $imagick2->vignetteimage(0, 1, 3, 3);

        $similarity = null;
        $bestMatch = null;
        $comparison = $imagick->subImageMatch($imagick2, $bestMatch, $similarity);

        $comparison->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::swirlImage

(PECL imagick 2, PECL imagick 3)

Imagick::swirlImage — Tourbillonne les pixels du centre de l'image

### Description

function Imagick::swirlImage(float `$degrees`): bool

Tourbillonne les pixels du centre de l'image, où le paramètre `degrees` indique le degré du tourbillon de l'arc autour duquel les pixels sont bougés. Le résultat sera des effets différents suivant le degré choisi, entre 1 et 360.

### Liste de paramètres

`degrees`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::swirlImage()

    <?php
    function swirlImage($imagePath, $swirl) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->swirlImage($swirl);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::textureImage

(PECL imagick 2, PECL imagick 3)

Imagick::textureImage — Répète les carreaux de la texture d'une image

### Description

function Imagick::textureImage(Imagick `$texture_wand`): Imagick

Répète les carreaux de la texture d'une image via le canevas de l'image.

### Liste de paramètres

`texture_wand`

  Objet Imagick à utiliser comme image de texture

### Valeurs de retour

Retourne un nouvel objet Imagick, qui a la texture répétée appliquée.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::textureImage()

    <?php
    function textureImage($imagePath) {
        $image = new \Imagick();
        $image->newImage(640, 480, new \ImagickPixel('pink'));
        $image->setImageFormat("jpg");
        $texture = new \Imagick(realpath($imagePath));
        $texture->scaleimage($image->getimagewidth() / 4, $image->getimageheight() / 4);
        $image = $image->textureImage($texture);
        header("Content-Type: image/jpg");
        echo $image;
    }

    ?>

# Imagick::thresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::thresholdImage — Modifie la valeur des pixels individuels, basée sur un seuil

### Description

public function Imagick::thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Modifie la valeur des pixels individuels, basée sur l'intensité de chaque pixel, comparée au seuil. Le résultat sera une image d'un contraste élevé comprenant 2 couleurs.

### Liste de paramètres

`threshold`

`channel`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::thresholdImage()

    <?php
    function thresholdimage($imagePath, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->thresholdimage($threshold * \Imagick::getQuantum(), $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::thumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::thumbnailImage — Modifie la taille d'une image

### Description

public function Imagick::thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool

Modifie la taille d'une image dans les dimensions données et supprime tous les profils associés. Le but est de produire une miniature à faible coût pour l'afficher sur le web. Si `true` est fourni comme troisième paramètre, alors les paramètres `columns` et `rows` seront utilisés comme maximum de chacun des côtés. Chaque côté sera abaissé tant que la taille désirée ne sera pas atteinte.

> Note: Le comportement du paramètre `bestfit` a changé avec Imagick 3.0.0. Avant cette version, fournir les dimensions 400x400 à une image de dimensions 200x150 faisait que la partie gauche était inchangée. Avec Imagick 3.0.0 et suivants, l'image est réduite à la taille 400x300, sachant que c'est le meilleur résultat pour ces dimensions. Si le paramètre `bestfit` est utilisé, la largeur et la hauteur doivent être fournies.

### Liste de paramètres

`columns`

  Largeur de l'image

`rows`

  Hauteur de l'image

`bestfit`

  Si l'on doit forcer les valeurs maximales

`fill`

  Si l’image ne remplit pas entièrement la boîte, alors celle-ci est remplie avec la couleur d’arrière-plan de l’image.

`legacy`

  Arrondit la plus petite dimension à l’entier inférieur le plus proche.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::thumbnailImage()

    <?php
    function thumbnailImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setbackgroundcolor('rgb(64, 64, 64)');
        $imagick->thumbnailImage(100, 100, true, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::tintImage

(PECL imagick 2, PECL imagick 3)

Imagick::tintImage — Applique un vecteur de couleur à chaque pixel de l'image

### Description

public function Imagick::tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool

Applique un vecteur de couleur à chaque pixel de l'image. La longueur du vecteur est 0 pour noir et blanc et à son maximum pour des tons moyens. La fonction de vecteur est `f(x)=(1-(4.0*((x-0.5)*(x-0.5))))`.

### Liste de paramètres

`tint`

`opacity`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Autorise maintenant une chaîne représentant la couleur en tant que premier paramètre et un nombre décimal représentant la valeur d'opacité comme deuxième paramètre. Les anciennes versions autorisent uniquement des objets ImagickPixel.

### Exemples

Exemple #1 Exemple avec Imagick::tintImage()

    <?php
    function tintImage($r, $g, $b, $a) {
        $a = $a / 100;

        $imagick = new \Imagick();
        $imagick->newPseudoImage(400, 400, 'gradient:black-white');

        $tint = new \ImagickPixel("rgb($r, $g, $b)");
        $opacity = new \ImagickPixel("rgb(128, 128, 128, $a)");
        $imagick->tintImage($tint, $opacity);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::__toString

(PECL imagick 2, PECL imagick 3)

Imagick::__toString — Renvoie l'image sous forme de chaîne

### Description

public function Imagick::__toString(): string

Renvoie l'image actuelle sous forme de chaîne. Cela ne renverra qu'une seule image ; cela ne doit pas être utilisé pour les objets Imagick qui contiennent plusieurs images, par exemple un GIF animé ou un PDF avec plusieurs pages.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le contenu de la chaîne en cas de succès ou une chaîne vide en cas d'échec.

### Voir aussi

- Imagick::getImageBlob() - Retourne la séquence d'images comme un blob
- Imagick::getImagesBlob() - Retourne toutes les images de la séquence en un BLOB

# Imagick::transformImage

(PECL imagick 2, PECL imagick 3)

Imagick::transformImage — Méthode de convenance pour définir la taille de rognage et la géométrie de l'image

Avertissement

Cette fonction est OBSOLÈTE à partir de Imagick 3.4.4. Dépendre de cette fonctionnalité est fortement déconseillé.

### Description

public function Imagick::transformImage(string `$crop`, string `$geometry`): Imagick

Méthode de convenance pour définir la taille de rognage et la géométrie de l'image depuis des chaînes de caractères. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`crop`

  Une géométrie de rognage. Cette géométrie définit une sous-région de l'image à rogner.

`geometry`

  Une géométrie. Cette géométrie définit la taille finale de l'image.

### Valeurs de retour

Retourne un objet Imagick contenant l'image transformée.

### Exemples

Exemple #1 Exemple avec Imagick::transformImage():

L'exemple crée une image noire 100x100.

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");
    $new_image = $image->transformImage("100x100", "100x100");
    $new_image->writeImage('test_out.jpg');
    ?>

### Voir aussi

- Imagick::cropImage() - Extrait une région d'une image
- Imagick::resizeImage() - Redimensionne une image
- Imagick::thumbnailImage() - Modifie la taille d'une image

# Imagick::transformImageColorspace

(PECL imagick 3)

Imagick::transformImageColorspace — Transforme une image dans un nouvel espace de couleur

### Description

public function Imagick::transformImageColorspace(int `$colorspace`): bool

Transforme une image dans un nouvel espace de couleur.

### Liste de paramètres

`colorspace`

  L'espace de couleur dans lequel l'image doit être transformée, l'une des constantes COLORSPACE par exemple Imagick::COLORSPACE_CMYK.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Imagick::transformImageColorspace() example

Transforme une image dans un nouvel espace de couleur, puis extrait un seul canal pour que les valeurs de canal individuelles puissent être visualisées.

    <?php
    function transformImageColorspace($imagePath, $colorSpace, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transformimagecolorspace($colorSpace);
        //channel doit être une des constantes de canal par exemple \Imagick::CHANNEL_BLUE
        $imagick->separateImageChannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }
    ?>

### Voir aussi

- Imagick::setColorSpace() - Définit l'espace de couleurs

# Imagick::transparentPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::transparentPaintImage — Rend des pixels transparents

### Description

public function Imagick::transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool

Rend transparents les pixels correspondant à la couleur cible. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.8 ou supérieur.

### Liste de paramètres

`target`

  La couleur cible à rendre transparente.

`alpha`

  Le degré de transparence : 1.0 correspond à totalement opaque et 0.0 à totalement transparent.

`fuzz`

  La quantité de poussière de papier. Par exemple, le fait de définir la poussière de papier à 10 et la couleur rouge à une intensité de 100 et de 102 ne sera pas interprété comme la même couleur.

`invert`

  Si `true`, rend transparents tous les pixels qui ne correspondent pas à la couleur cible.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::transparentPaintImage()

    <?php
    function transparentPaintImage($color, $alpha, $fuzz) {
        $imagick = new \Imagick(realpath("images/BlueScreen.jpg"));

        //Need to be in a format that supports transparency
        $imagick->setimageformat('png');

        $imagick->transparentPaintImage(
            $color, $alpha, $fuzz * \Imagick::getQuantum(), false
        );

        //Not required, but helps tidy up left over pixels
        $imagick->despeckleimage();

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::transposeImage

(PECL imagick 2, PECL imagick 3)

Imagick::transposeImage — Applique une symétrie verticale

### Description

public function Imagick::transposeImage(): bool

Applique une symétrie verticale, en créant la réflexion de chaque pixel autour d'un axe horizontal, avec une rotation de 90 degrés. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::transposeImage()

    <?php
    function transposeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transposeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Voir aussi

- Imagick::transverseImage() - Crée un miroir horizontal de l'image

# Imagick::transverseImage

(PECL imagick 2, PECL imagick 3)

Imagick::transverseImage — Crée un miroir horizontal de l'image

### Description

public function Imagick::transverseImage(): bool

Crée un miroir horizontal de l'image en reflétant les pixels autour d'un axe Y central, et en effectuant une rotation de 270 degrés. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::transverseImage()

    <?php
    function transverseImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transverseImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Voir aussi

- Imagick::transposeImage() - Applique une symétrie verticale

# Imagick::trimImage

(PECL imagick 2, PECL imagick 3)

Imagick::trimImage — Supprime les bords de l'image

### Description

public function Imagick::trimImage(float `$fuzz`): bool

Supprime les bords qui correspondent à la couleur d'arrière-plan de l'image. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`fuzz`

  Par défaut, la cible doit correspondre à une couleur particulière de pixel. Cependant, dans la plupart des cas, 2 couleurs peuvent différer légèrement. Le paramètre `fuzz` de l'image définit la tolérance acceptée afin de considérer deux couleurs comme couleurs identiques. Ce paramètre représente les variations d'intervalle quantique.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::trimImage():

Tronque l'image, puis l'affiche au navigateur.

    <?php
    /* Crée l'objet et lit l'image */
    $im = new Imagick("image.jpg");

    /* Tronque l'image. */
    $im->trimImage(0);

    /* Affiche l'image */
    header("Content-Type: image/" . $im->getImageFormat());
    echo $im;
    ?>

### Voir aussi

- Imagick::getQuantumDepth() - Lit la profondeur quantique
- Imagick::getQuantumRange() - Retourne l'intervalle quantique de Imagick
- imagecropauto() - Recadre une image automatiquement en utilisant un des modes disponibles

# Imagick::uniqueImageColors

(PECL imagick 2,PECL imagick 3)

Imagick::uniqueImageColors — Ne conserve qu'une couleur de pixel

### Description

public function Imagick::uniqueImageColors(): bool

Ne conserve qu'une couleur de pixel et supprime les autres. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::uniqueImageColors()

    <?php
    function uniqueImageColors($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        //Reduce the image to 256 colours nicely.
        $imagick->quantizeImage(256, \Imagick::COLORSPACE_YIQ, 0, false, false);
        $imagick->uniqueImageColors();
        $imagick->scaleimage($imagick->getImageWidth(), $imagick->getImageHeight() * 20);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::unsharpMaskImage

(PECL imagick 2, PECL imagick 3)

Imagick::unsharpMaskImage — Rend une image plus nette

### Description

public function Imagick::unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Rend une image plus nette. L'image est traitée avec un opérateur Gaussien d'un rayon donné et d'une déviation standard (sigma). Pour de bons résultats, le rayon doit être supérieur au sigma. Avec un rayon de 0, Imagick::UnsharpMaskImage() sélectionne un bon rayon automatiquement.

### Liste de paramètres

`radius`

`sigma`

`amount`

`threshold`

`channel`

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::unsharpMaskImage()

    <?php
    function unsharpMaskImage($imagePath, $radius, $sigma, $amount, $unsharpThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->unsharpMaskImage($radius, $sigma, $amount, $unsharpThreshold);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::valid

(PECL imagick 2, PECL imagick 3)

Imagick::valid — Vérifie si l'élément courant est valide

### Description

public function Imagick::valid(): bool

Vérifie si l'élément courant est valide.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::vignetteImage

(PECL imagick 2, PECL imagick 3)

Imagick::vignetteImage — Ajoute un filtre vignette à l'image

### Description

public function Imagick::vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool

Adoucit les contours de l'image, à la mode des vignettes. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`blackPoint`

  Le point noir.

`whitePoint`

  Le point blanc.

`x`

  L'abscisse de l'ellipse.

`y`

  L'ordonnée de l'ellipse.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::vignetteImage()

    <?php
    function vignetteImage($imagePath, $blackPoint, $whitePoint, $x, $y) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->vignetteImage($blackPoint, $whitePoint, $x, $y);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Voir aussi

- Imagick::waveImage() - Ajoute un filtre de vagues à l'image
- Imagick::swirlImage() - Tourbillonne les pixels du centre de l'image

# Imagick::waveImage

(PECL imagick 2, PECL imagick 3)

Imagick::waveImage — Ajoute un filtre de vagues à l'image

### Description

public function Imagick::waveImage(float `$amplitude`, float `$length`): bool

Ajoute un filtre de vagues à l'image. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.2.9 ou supérieur.

### Liste de paramètres

`amplitude`

  Amplitude de la vague.

`length`

  Longueur de la vague.

### Valeurs de retour

Retourne `true` en cas de succès.

### Erreurs / Exceptions

Lance une exception ImagickException si une erreur survient.

### Exemples

Exemple #1 WaveImage peut être très lent ; Imagick::waveImage()

    <?php
    function waveImage($imagePath, $amplitude, $length) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->waveImage($amplitude, $length);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Voir aussi

- Imagick::solarizeImage() - Applique un effet de solarisation à l'image
- Imagick::oilpaintImage() - Simule une peinture à l'huile
- Imagick::embossImage() - Retourne une image en niveau de gris, avec un effet 3D
- Imagick::addNoiseImage() - Ajoute un bruit aléatoire à une image
- Imagick::swirlImage() - Tourbillonne les pixels du centre de l'image

# Imagick::whiteThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::whiteThresholdImage — Force tous les pixels au-dessus du seuil en blanc

### Description

public function Imagick::whiteThresholdImage(mixed `$threshold`): bool

Identique à Imagick::ThresholdImage() mais force tous les pixels au-dessus du seuil en blanc, laissant inchangés tous les pixels en dessous du seuil.

### Liste de paramètres

`threshold`

### Valeurs de retour

Retourne `true` en cas de succès.

### Historique

Version | Description
--- | ---
PECL imagick 2.1.0 | Autorise désormais une chaîne représentant la couleur comme paramètre. Les anciennes versions ne permettaient qu'un objet ImagickPixel.

### Exemples

Exemple #1 Exemple avec Imagick::whiteThresholdImage()

    <?php
    function whiteThresholdImage($imagePath, $color) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->whiteThresholdImage($color);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::writeImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImage — Écrit une image dans le fichier spécifié

### Description

public function Imagick::writeImage(string `$filename` = NULL): bool

Écrit une image dans un fichier spécifié. Si le paramètre `filename` vaut `null`, l'image sera écrite dans le fichier défini par Imagick::readImage() ou Imagick::setImageFilename().

### Liste de paramètres

`filename`

  Nom du fichier dans lequel l'image sera écrite. L'extension du fichier définit le type de fichier. Le format peut être forcé malgré l'extension de fichier en utilisant format: préfixe, par exemple "jpg:test.png".

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::writeImageFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImageFile — Écrit une image dans un descripteur de fichier

### Description

public function Imagick::writeImageFile(resource `$filehandle`, string `$format` = ?): bool

Écrit la séquence de l'image dans un descripteur de fichier ouvert. Le descripteur doit avoir été ouvert avec, par exemple, la fonction fopen. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`filehandle`

  Descripteur de fichier dans lequel l'image sera écrite.

`format`

  Le format de l'image. La liste des spécificateurs de format valides dépend du jeu de fonctionnalités compilé d'ImageMagick, et peut être interrogée au moment de l'exécution via Imagick::queryFormats().

### Valeurs de retour

Retourne `true` en cas de succès.

### Voir aussi

- Imagick::queryFormats() - Retourne les formats supportés par Imagick

# Imagick::writeImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImages — Écrit une image ou une séquence d'images

### Description

public function Imagick::writeImages(string `$filename`, bool `$adjoin`): bool

Écrit une image ou une séquence d'images.

### Liste de paramètres

`filename`

`adjoin`

### Valeurs de retour

Retourne `true` en cas de succès.

# Imagick::writeImagesFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImagesFile — Écrit des frames dans un descripteur de fichiers

### Description

public function Imagick::writeImagesFile(resource `$filehandle`, string `$format` = ?): bool

Écrit toutes les frames d'une image dans un descripteur de fichier. Cette méthode peut être utilisée pour écrire des gifs animés ou d'autres images composées de plusieurs frames dans un descripteur de fichier ouvert. Cette méthode n'est disponible que si Imagick a été compilé avec ImageMagick version 6.3.6 ou supérieur.

### Liste de paramètres

`filehandle`

  Descripteur de fichier dans lequel les frames seront écrites.

`format`

  Le format de l'image. La liste des spécificateurs de format valides dépend du jeu de fonctionnalités compilé d'ImageMagick, et peut être interrogée au moment de l'exécution via Imagick::queryFormats().

### Valeurs de retour

Retourne `true` en cas de succès.

### Voir aussi

- Imagick::queryFormats() - Retourne les formats supportés par Imagick

## Sommaire

- Imagick::adaptiveBlurImage — Ajoute un flou adaptatif à l'image
- Imagick::adaptiveResizeImage — Redimensionne adaptativement une image par triangulation
- Imagick::adaptiveSharpenImage — Augmente le contraste de l'image
- Imagick::adaptiveThresholdImage — Sélectionne le niveau de chaque pixel, à partir d'un intervalle d'intensité
- Imagick::addImage — Ajoute une nouvelle image à la liste d'images Imagick
- Imagick::addNoiseImage — Ajoute un bruit aléatoire à une image
- Imagick::affineTransformImage — Transforme une image
- Imagick::animateImages — Anime une ou plusieurs images
- Imagick::annotateImage — Annote une image avec un texte
- Imagick::appendImages — Ajoute un jeu d'images
- Imagick::autoLevelImage — Ajuste le niveau d'un canal d'une image particulière
- Imagick::averageImages — Moyenne d'un jeu d'images
- Imagick::blackThresholdImage — Force tous les pixels en dessous d'un seuil à noir
- Imagick::blueShiftImage — Atténue les couleurs de l'image
- Imagick::blurImage — Ajoute un filtre de flou à une image
- Imagick::borderImage — Encadre une image avec un bord
- Imagick::brightnessContrastImage — Change la luminosité et/ou le contraste d'une image
- Imagick::charcoalImage — Simule un dessin au fusain
- Imagick::chopImage — Supprime une région d'une image et retaille
- Imagick::clampImage — Restreint la plage de couleurs de 0 à la profondeur quantique
- Imagick::clear — Libère toutes les ressources associées à un objet Imagick
- Imagick::clipImage — Découpe le long du premier chemin du profil 8BIM
- Imagick::clipImagePath — Découpe le long des chemins nommés du profil 8BIM, si présent
- Imagick::clipPathImage — Découpe le long du chemin d'un profil 8BIM
- Imagick::clone — Fait une copie exacte d'un objet Imagick
- Imagick::clutImage — Remplace les couleurs d'une image
- Imagick::coalesceImages — Compose un jeu d'images
- Imagick::colorFloodfillImage — Change la couleur d'un pixel
- Imagick::colorizeImage — Mélange la couleur de remplissage avec l'image
- Imagick::colorMatrixImage — Applique une transformation de couleur à une image
- Imagick::combineImages — Combine plusieurs images en une seule
- Imagick::commentImage — Ajoute un commentaire à une image
- Imagick::compareImageChannels — Retourne la différence entre plusieurs images
- Imagick::compareImageLayers — Retourne la région d'encadrement maximale entre deux images
- Imagick::compareImages — Compare une image avec une image reconstituée
- Imagick::compositeImage — Compose une image avec une autre
- Imagick::__construct — Le constructeur Imagick
- Imagick::contrastImage — Change le contraste de l'image
- Imagick::contrastStretchImage — Améliore le contraste d'une image
- Imagick::convolveImage — Applique un noyau de convolution à une image
- Imagick::count — Renvoie le nombre d'images
- Imagick::cropImage — Extrait une région d'une image
- Imagick::cropThumbnailImage — Crée une miniature par retaillage
- Imagick::current — Retourne une référence sur l'objet imagick courant
- Imagick::cycleColormapImage — Déplace la carte des couleurs d'une image
- Imagick::decipherImage — Déchiffre une image
- Imagick::deconstructImages — Retourne les différences de certains pixels entre deux images
- Imagick::deleteImageArtifact — Supprime l'artefact d'une image
- Imagick::deleteImageProperty — Supprime une propriété d'image
- Imagick::deskewImage — Supprime le biais de l'image
- Imagick::despeckleImage — Réduit le bruit speckle d'une image
- Imagick::destroy — Détruit un objet Imagick
- Imagick::displayImage — Affiche une image
- Imagick::displayImages — Affiche une image ou une séquence
- Imagick::distortImage — Déforme une image avec différentes méthodes
- Imagick::drawImage — Affiche un objet ImagickDraw dans l'image courante
- Imagick::edgeImage — Renforce les bords dans l'image
- Imagick::embossImage — Retourne une image en niveau de gris, avec un effet 3D
- Imagick::encipherImage — Chiffre une image
- Imagick::enhanceImage — Améliore la qualité d'une image bruitée
- Imagick::equalizeImage — Égalise l'histogramme d'une image
- Imagick::evaluateImage — Applique une expression à une image
- Imagick::exportImagePixels — Exporte les pixels bruts de l'image
- Imagick::extentImage — Définit la taille de l'image
- Imagick::filter — Applique un noyau de convolution personnalisé à l'image
- Imagick::flattenImages — Fusionne une séquence d'images
- Imagick::flipImage — Crée une image par miroir vertical
- Imagick::floodFillPaintImage — Modifie la valeur de la couleur de chaque pixel correspondant à la cible
- Imagick::flopImage — Crée une image par miroir horizontal
- Imagick::forwardFourierTransformImage — Implémente la transformée de Fourier discrète (Discrete Fourier Transform - DFT)
- Imagick::frameImage — Ajoute un bord 3D
- Imagick::functionImage — Applique une fonction sur l'image
- Imagick::fxImage — Évalue une expression pour chaque pixel d'une image
- Imagick::gammaImage — Applique une correction gamma à l'image
- Imagick::gaussianBlurImage — Ajoute du flou à une image
- Imagick::getColorspace — Récupère l'espace de couleurs
- Imagick::getCompression — Lit le type de compression
- Imagick::getCompressionQuality — Lit la qualité de la compression
- Imagick::getCopyright — Retourne le copyright de l'API ImageMagick
- Imagick::getFilename — Lit le nom du fichier associé à une séquence
- Imagick::getFont — Récupère la police de caractères
- Imagick::getFormat — Retourne le format de l'image Imagick
- Imagick::getGravity — Récupère la gravité
- Imagick::getHomeURL — Retourne l'URL de ImageMagick
- Imagick::getImage — Retourne un nouvel objet Imagick
- Imagick::getImageAlphaChannel — Vérifie si l'image a un canal alpha
- Imagick::getImageArtifact — Récupère l'artefact de l'image
- Imagick::getImageAttribute — Obtient un attribut nommé
- Imagick::getImageBackgroundColor — Retourne la couleur de fond
- Imagick::getImageBlob — Retourne la séquence d'images comme un blob
- Imagick::getImageBluePrimary — Retourne la chromaticité de la couleur bleue
- Imagick::getImageBorderColor — Retourne la couleur de bordure de l'image
- Imagick::getImageChannelDepth — Lit la profondeur d'un des canaux de l'image
- Imagick::getImageChannelDistortion — Compare les canaux d'une image reconstituée
- Imagick::getImageChannelDistortions — Récupère les distorsions d'un canal
- Imagick::getImageChannelExtrema — Lit les extrêmes pour les canaux de l'image
- Imagick::getImageChannelKurtosis — Le but de getImageChannelKurtosis
- Imagick::getImageChannelMean — Lit la moyenne et la déviation standard
- Imagick::getImageChannelRange — Récupère l'intervalle du canal
- Imagick::getImageChannelStatistics — Retourne des statistiques sur chaque canal de l'image
- Imagick::getImageClipMask — Récupère le masque du clip de l'image
- Imagick::getImageColormapColor — Retourne la couleur à l'index de la carte de couleurs
- Imagick::getImageColors — Lit le nombre de couleurs uniques de l'image
- Imagick::getImageColorspace — Lit l'espace de couleurs de l'image
- Imagick::getImageCompose — Retourne l'opérateur de composition associé à une image
- Imagick::getImageCompression — Lit le type de compression de l'image
- Imagick::getImageCompressionQuality — Lit la qualité de compression de l'image
- Imagick::getImageDelay — Lit le délai de l'image
- Imagick::getImageDepth — Lit la profondeur de l'image
- Imagick::getImageDispose — Lit la méthode de récupération
- Imagick::getImageDistortion — Compare une image à une image reconstituée
- Imagick::getImageExtrema — Lit les extrêmes d'une image
- Imagick::getImageFilename — Retourne le nom d'un fichier pour une image dans une séquence
- Imagick::getImageFormat — Retourne le format d'une image dans une séquence
- Imagick::getImageGamma — Lit le gamma de l'image
- Imagick::getImageGeometry — Lit les dimensions de l'image dans un tableau
- Imagick::getImageGravity — Récupère la gravité de l'image
- Imagick::getImageGreenPrimary — Retourne la chromaticité de la couleur verte
- Imagick::getImageHeight — Retourne la hauteur de l'image
- Imagick::getImageHistogram — Retourne l'histogramme de l'image
- Imagick::getImageIndex — Lit l'index de l'image courante
- Imagick::getImageInterlaceScheme — Lit le schéma d'entrelacement de l'image
- Imagick::getImageInterpolateMethod — Retourne la méthode d'interpolation
- Imagick::getImageIterations — Lit les itérations de l'image
- Imagick::getImageLength — Retourne la taille de l'image en octets
- Imagick::getImageMatte — Indique si l'image a un canal mat
- Imagick::getImageMatteColor — Retourne la couleur mate de l'image
- Imagick::getImageMimeType — Renvoie le type MIME de l'image
- Imagick::getImageOrientation — Lit l'orientation de l'image
- Imagick::getImagePage — Retourne la géométrie de la page
- Imagick::getImagePixelColor — Retourne la couleur d'un pixel
- Imagick::getImageProfile — Retourne un profil d'une image
- Imagick::getImageProfiles — Retourne les profils de l'image
- Imagick::getImageProperties — Retourne les propriétés EXIF de l'image
- Imagick::getImageProperty — Retourne une propriété d'une image
- Imagick::getImageRedPrimary — Retourne la chromaticité du point rouge
- Imagick::getImageRegion — Extrait une région d'une image
- Imagick::getImageRenderingIntent — Lit la méthode de rendu de l'image
- Imagick::getImageResolution — Lit les résolutions en X et Y d'une image
- Imagick::getImagesBlob — Retourne toutes les images de la séquence en un BLOB
- Imagick::getImageScene — Retourne la scène de l'image
- Imagick::getImageSignature — Génère une signature SHA-256
- Imagick::getImageSize — Retourne la taille de l'image en octets
- Imagick::getImageTicksPerSecond — Lit les ticks-par-seconde de l'image
- Imagick::getImageTotalInkDensity — Lit la densité totale d'encre de l'image
- Imagick::getImageType — Lit le type possible d'image
- Imagick::getImageUnits — Retourne les unités de résolution de l'image
- Imagick::getImageVirtualPixelMethod — Retourne la méthode du pixel virtuel
- Imagick::getImageWhitePoint — Retourne la chromaticité du point blanc
- Imagick::getImageWidth — Retourne la largeur de l'image
- Imagick::getInterlaceScheme — Lit le schéma d'entrelacement de l'objet
- Imagick::getIteratorIndex — Lit l'index de l'image active courante
- Imagick::getNumberImages — Retourne le nombre d'images d'un objet
- Imagick::getOption — Retourne la valeur d'une option
- Imagick::getPackageName — Retourne le nom du paquet ImageMagick
- Imagick::getPage — Retourne la géométrie de la page
- Imagick::getPixelIterator — Retourne un MagickPixelIterator
- Imagick::getPixelRegionIterator — Lit un objet ImagickPixelIterator pour une section d'image
- Imagick::getPointSize — Récupère la taille du point
- Imagick::getQuantum — Renvoie la plage quantique d'ImageMagick
- Imagick::getQuantumDepth — Lit la profondeur quantique
- Imagick::getQuantumRange — Retourne l'intervalle quantique de Imagick
- Imagick::getRegistry — Obtient un élément de StringRegistry
- Imagick::getReleaseDate — Retourne la date de publication de ImageMagick
- Imagick::getResource — Retourne la consommation de mémoire de la ressource
- Imagick::getResourceLimit — Retourne la limite de la ressource
- Imagick::getSamplingFactors — Lit le facteur d'échantillonnage horizontal et vertical
- Imagick::getSize — Retourne la taille associée avec un objet Imagick
- Imagick::getSizeOffset — Retourne la taille de la position
- Imagick::getVersion — Retourne la version de l'API ImageMagick
- Imagick::haldClutImage — Remplace les couleurs de l'image
- Imagick::hasNextImage — Vérifie si un objet a une image suivante
- Imagick::hasPreviousImage — Vérifie si un objet a une image précédente
- Imagick::identifyFormat — Formate une chaîne avec les détails de l'image
- Imagick::identifyImage — Identifie une image et lit ses attributs
- Imagick::implodeImage — Crée une nouvelle copie d'image
- Imagick::importImagePixels — Importe des pixels dans une image
- Imagick::inverseFourierTransformImage — Implémente la transformée de Fourier discrète inverse (Discrete Fourier Transform - DFT)
- Imagick::labelImage — Ajoute un libellé à une image
- Imagick::levelImage — Ajuste les niveaux de l'image
- Imagick::linearStretchImage — Étire la saturation de l'intensité de l'image
- Imagick::liquidRescaleImage — Redimensionne une image par mise à l'échelle liquide
- Imagick::listRegistry — Liste tous les paramètres du registre
- Imagick::magnifyImage — Double la taille d'une image, proportionnellement
- Imagick::mapImage — Remplace la couleur d'une image par celle d'une image de référence
- Imagick::matteFloodfillImage — Change la transparence d'une couleur
- Imagick::medianFilterImage — Applique un filtre numérique
- Imagick::mergeImageLayers — Fusionne les calques de l'image
- Imagick::minifyImage — Met à l'échelle une image proportionnellement pour la réduire de moitié de taille
- Imagick::modulateImage — Contrôle la saturation, l'intensité et la teinte
- Imagick::montageImage — Crée une image composite
- Imagick::morphImages — Réalise un morphing entre deux images
- Imagick::morphology — Applique un noyau personnalisé à l'image selon la méthode de morphologie donnée
- Imagick::mosaicImages — Forme une mosaïque d'images
- Imagick::motionBlurImage — Ajoute un flou de déplacement
- Imagick::negateImage — Effectue la négation des couleurs d'une image de référence
- Imagick::newImage — Crée une nouvelle image
- Imagick::newPseudoImage — Crée une nouvelle image
- Imagick::nextImage — Passe à la prochaine image
- Imagick::normalizeImage — Améliore le contraste de l'image
- Imagick::oilPaintImage — Simule une peinture à l'huile
- Imagick::opaquePaintImage — Modifie la valeur de la couleur de tous les pixels correspondant à la cible
- Imagick::optimizeImageLayers — Supprime les portions récurrentes d'images à optimiser
- Imagick::orderedPosterizeImage — Effectue un dither ordonné
- Imagick::paintFloodfillImage — Change les pixels qui sont d'une couleur
- Imagick::paintOpaqueImage — Change les pixels qui sont d'une couleur
- Imagick::paintTransparentImage — Remplit les pixels avec une couleur
- Imagick::pingImage — Lit des attributs simples sans ouvrir une image
- Imagick::pingImageBlob — Lit rapidement les attributs
- Imagick::pingImageFile — Lit les attributs simples d'une image
- Imagick::polaroidImage — Simule une photo Polaroid
- Imagick::posterizeImage — Réduit une image à un nombre limité de couleurs
- Imagick::previewImages — Teste rapidement différents paramètres pour un traitement d'images
- Imagick::previousImage — Passe à l'image précédente dans une séquence d'images
- Imagick::profileImage — Ajoute ou retire un profil d'une image
- Imagick::quantizeImage — Analyse les couleurs dans une référence d'image
- Imagick::quantizeImages — Analyse les couleurs d'une séquence d'images
- Imagick::queryFontMetrics — Retourne un tableau représentant les dimensions de la police
- Imagick::queryFonts — Retourne la liste de polices configurées
- Imagick::queryFormats — Retourne les formats supportés par Imagick
- Imagick::radialBlurImage — Flou radial d'une image
- Imagick::raiseImage — Crée un effet 3D de bouton
- Imagick::randomThresholdImage — Crée une image en deux couleurs, à haut contraste
- Imagick::readImage — Lit une image depuis un fichier
- Imagick::readImageBlob — Lit une image depuis une chaîne binaire
- Imagick::readImageFile — Lit une image à partir d'une ressource fichier
- Imagick::readimages — Lit une image à partir d'un tableau de noms de fichiers
- Imagick::recolorImage — Recolore l'image
- Imagick::reduceNoiseImage — Adoucit les contours d'une image
- Imagick::remapImage — Reconfigure les couleurs de l'image
- Imagick::removeImage — Retire une image de la liste
- Imagick::removeImageProfile — Supprime le profil de l'image et le retourne
- Imagick::render — Affiche toutes les commandes de dessins précédentes
- Imagick::resampleImage — Rééchantillonne l'image
- Imagick::resetImagePage — Réinitialise la page de l'image
- Imagick::resizeImage — Redimensionne une image
- Imagick::rollImage — Décale une image
- Imagick::rotateImage — Tourne une image
- Imagick::rotationalBlurImage — Flou de rotation d'une image
- Imagick::roundCorners — Arrondit les coins d'une image
- Imagick::sampleImage — Met à l'échelle une image avec échantillonnage de pixels
- Imagick::scaleImage — Met à l'échelle la taille de l'image
- Imagick::segmentImage — Segmente une image
- Imagick::selectiveBlurImage — Floute sélectivement une image dans un seuil de contraste
- Imagick::separateImageChannel — Sépare un canal d'une image
- Imagick::sepiaToneImage — Passe une image en tons sépia
- Imagick::setBackgroundColor — Configure la couleur de fond par défaut
- Imagick::setColorspace — Définit l'espace de couleurs
- Imagick::setCompression — Configure le type de compression de l'objet
- Imagick::setCompressionQuality — Configure la compression par défaut de l'objet
- Imagick::setFilename — Configure le nom du fichier d'image avant d'y accéder
- Imagick::setFirstIterator — Place l'itérateur de Imagick sur la première image
- Imagick::setFont — Configure la police
- Imagick::setFormat — Configure le format de l'objet Imagick
- Imagick::setGravity — Définit la gravité
- Imagick::setImage — Remplace l'image dans l'objet
- Imagick::setImageAlphaChannel — Définit le canal alpha de l'image
- Imagick::setImageArtifact — Définit l'artefact de l'image
- Imagick::setImageAttribute — Définit un attribut d'image
- Imagick::setImageBackgroundColor — Configure la couleur de fond d'image
- Imagick::setImageBias — Configure le biais pour les convolutions
- Imagick::setImageBiasQuantum — Définit le biais de l'image
- Imagick::setImageBluePrimary — Configure la chromaticité du point bleu
- Imagick::setImageBorderColor — Configure la couleur de bordure
- Imagick::setImageChannelDepth — Configure la profondeur d'un canal
- Imagick::setImageClipMask — Définit le masque du clip de l'image
- Imagick::setImageColormapColor — Configure une couleur de la carte
- Imagick::setImageColorspace — Configure l'espace de couleurs de l'image
- Imagick::setImageCompose — Configure l'opérateur de composition de l'image
- Imagick::setImageCompression — Configure la compression de l'image
- Imagick::setImageCompressionQuality — Spécifie la qualité de compression de l'image
- Imagick::setImageDelay — Configure le délai de l'image
- Imagick::setImageDepth — Configure la profondeur de l'image
- Imagick::setImageDispose — Configure la méthode de récupération
- Imagick::setImageExtent — Configure la taille d'une image
- Imagick::setImageFilename — Configure le nom de fichier d'une image dans une séquence
- Imagick::setImageFormat — Configure le format d'une image dans une séquence
- Imagick::setImageGamma — Configure la correction gamma
- Imagick::setImageGravity — Définit la gravité de l'image
- Imagick::setImageGreenPrimary — Configure la chromaticité du point vert
- Imagick::setImageIndex — Modifie la position de l'itérateur
- Imagick::setImageInterlaceScheme — Configure la méthode d'entrelacement de l'image
- Imagick::setImageInterpolateMethod — Configure la méthode d'interpolation de l'image
- Imagick::setImageIterations — Configure les itérations de l'image
- Imagick::setImageMatte — Configure le canal mate de l'image
- Imagick::setImageMatteColor — Configure la couleur mate
- Imagick::setImageOpacity — Configure le niveau d'opacité de l'image
- Imagick::setImageOrientation — Configure l'orientation de l'image
- Imagick::setImagePage — Configure la géométrie de la page de l'image
- Imagick::setImageProfile — Ajoute un profil à un objet Imagick
- Imagick::setImageProperty — Configure une propriété d'image
- Imagick::setImageRedPrimary — Configure la chromaticité du point rouge
- Imagick::setImageRenderingIntent — Configure le type de rendu de l'image
- Imagick::setImageResolution — Configure la résolution de l'image
- Imagick::setImageScene — Configure la scène de l'image
- Imagick::setImageTicksPerSecond — Configure le nombre de ticks par seconde de l'image
- Imagick::setImageType — Configure le type d'image
- Imagick::setImageUnits — Configure les unités de résolution de l'image
- Imagick::setImageVirtualPixelMethod — Configure la méthode du point virtuel de l'image
- Imagick::setImageWhitePoint — Configure la chromaticité du point blanc
- Imagick::setInterlaceScheme — Configure la compression de l'image
- Imagick::setIteratorIndex — Déplace l'itérateur
- Imagick::setLastIterator — Positionne l'itérateur Imagick à la dernière image
- Imagick::setOption — Configure une option d'un objet Imagick
- Imagick::setPage — Configure la géométrie de la page de l'objet Imagick
- Imagick::setPointSize — Définit la taille du point
- Imagick::setProgressMonitor — Définit une fonction de rappel à appeler pendant le traitement
- Imagick::setRegistry — Définit l'entrée du registre ImageMagick nommée clé pour valeur
- Imagick::setResolution — Configure la résolution de l'image
- Imagick::setResourceLimit — Définit la limite pour une ressource particulière
- Imagick::setSamplingFactors — Configure les facteurs d'échantillonnage de l'image
- Imagick::setSize — Configure la taille de l'objet Imagick
- Imagick::setSizeOffset — Configure la taille et la position de l'objet Imagick
- Imagick::setType — Configure l'attribut de l'image
- Imagick::shadeImage — Crée un effet 3D
- Imagick::shadowImage — Simule une ombre sur l'image
- Imagick::sharpenImage — Aiguise une image
- Imagick::shaveImage — Supprime les pixels du bord de l'image
- Imagick::shearImage — Crée un parallélogramme
- Imagick::sigmoidalContrastImage — Ajuste le contraste de l'image
- Imagick::sketchImage — Simule un crayon à main levée
- Imagick::smushImages — Prend toutes les images du pointeur d'image actuel jusqu'à la fin de la liste d'images et les écrase
- Imagick::solarizeImage — Applique un effet de solarisation à l'image
- Imagick::sparseColorImage — Interpole les couleurs
- Imagick::spliceImage — Joint une couleur solide dans l'image
- Imagick::spreadImage — Bouge aléatoirement chaque pixel d'un bloc
- Imagick::statisticImage — Modifie une image en utilisant une fonction statistique
- Imagick::steganoImage — Cache un filigrane numérique dans l'image
- Imagick::stereoImage — Fusionne 2 images
- Imagick::stripImage — Supprime d'une image tous les profils et les commentaires
- Imagick::subImageMatch — Recherche une sous-image dans l'image courante et renvoie une image de similarité
- Imagick::swirlImage — Tourbillonne les pixels du centre de l'image
- Imagick::textureImage — Répète les carreaux de la texture d'une image
- Imagick::thresholdImage — Modifie la valeur des pixels individuels, basée sur un seuil
- Imagick::thumbnailImage — Modifie la taille d'une image
- Imagick::tintImage — Applique un vecteur de couleur à chaque pixel de l'image
- Imagick::__toString — Renvoie l'image sous forme de chaîne
- Imagick::transformImage — Méthode de convenance pour définir la taille de rognage et la géométrie de l'image
- Imagick::transformImageColorspace — Transforme une image dans un nouvel espace de couleur
- Imagick::transparentPaintImage — Rend des pixels transparents
- Imagick::transposeImage — Applique une symétrie verticale
- Imagick::transverseImage — Crée un miroir horizontal de l'image
- Imagick::trimImage — Supprime les bords de l'image
- Imagick::uniqueImageColors — Ne conserve qu'une couleur de pixel
- Imagick::unsharpMaskImage — Rend une image plus nette
- Imagick::valid — Vérifie si l'élément courant est valide
- Imagick::vignetteImage — Ajoute un filtre vignette à l'image
- Imagick::waveImage — Ajoute un filtre de vagues à l'image
- Imagick::whiteThresholdImage — Force tous les pixels au-dessus du seuil en blanc
- Imagick::writeImage — Écrit une image dans le fichier spécifié
- Imagick::writeImageFile — Écrit une image dans un descripteur de fichier
- Imagick::writeImages — Écrit une image ou une séquence d'images
- Imagick::writeImagesFile — Écrit des frames dans un descripteur de fichiers

# La classe ImagickDraw

(PECL imagick 2, PECL imagick 3)

## Synopsis de la classe

class ImagickDraw {
public function affine(array `$affine`): bool
public function annotation(float `$x`, float `$y`, string `$text`): bool
public function arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
public function bezier(array `$coordinates`): bool
public function circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
public function clear(): bool
public function clone(): ImagickDraw
public function color(float `$x`, float `$y`, int `$paint`): bool
public function comment(string `$comment`): bool
public function composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
public function destroy(): bool
public function ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
public function getClipPath(): false|string
public function getClipRule(): int
public function getClipUnits(): int
public function getFillColor(): ImagickPixel
public function getFillOpacity(): float
public function getFillRule(): int
public function getFont(): string
public function getFontFamily(): string
public function getFontSize(): float
public function getFontStretch(): int
public function getFontStyle(): int
public function getFontWeight(): int
public function getGravity(): int
public function getStrokeAntialias(): bool
public function getStrokeColor(): ImagickPixel
public function getStrokeDashArray(): array
public function getStrokeDashOffset(): float
public function getStrokeLineCap(): int
public function getStrokeLineJoin(): int
public function getStrokeMiterLimit(): int
public function getStrokeOpacity(): float
public function getStrokeWidth(): float
public function getTextAlignment(): int
public function getTextAntialias(): bool
public function getTextDecoration(): int
public function getTextEncoding(): false|string
public function getTextInterlineSpacing(): float
public function getTextInterwordSpacing(): float
public function getTextKerning(): float
public function getTextUnderColor(): ImagickPixel
public function getVectorGraphics(): string
public function line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
public function matte(float `$x`, float `$y`, int `$paint`): bool
public function pathClose(): bool
public function pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierSmoothAbsolute(float `$x`, float `$y`): bool
public function pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
public function pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathFinish(): bool
public function pathLineToAbsolute(float `$x`, float `$y`): bool
public function pathLineToHorizontalAbsolute(float `$x`): bool
public function pathLineToHorizontalRelative(float `$x`): bool
public function pathLineToRelative(float `$x`, float `$y`): bool
public function pathLineToVerticalAbsolute(float `$y`): bool
public function pathLineToVerticalRelative(float `$y`): bool
public function pathMoveToAbsolute(float `$x`, float `$y`): bool
public function pathMoveToRelative(float `$x`, float `$y`): bool
public function pathStart(): bool
public function point(float `$x`, float `$y`): bool
public function polygon(array `$coordinates`): bool
public function polyline(array `$coordinates`): bool
public function pop(): bool
public function popClipPath(): bool
public function popDefs(): bool
public function popPattern(): bool
public function push(): bool
public function pushClipPath(string `$clip_mask_id`): bool
public function pushDefs(): bool
public function pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
public function rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
public function render(): bool
public function resetVectorGraphics(): bool
public function rotate(float `$degrees`): bool
public function roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
public function scale(float `$x`, float `$y`): bool
public function setClipPath(string `$clip_mask`): bool
public function setClipRule(int `$fillrule`): bool
public function setClipUnits(int `$pathunits`): bool
public function setFillAlpha(float `$alpha`): bool
public function setFillColor(ImagickPixel|string `$fill_color`): bool
public function setFillOpacity(float `$opacity`): bool
public function setFillPatternURL(string `$fill_url`): bool
public function setFillRule(int `$fillrule`): bool
public function setFont(string `$font_name`): bool
public function setFontFamily(string `$font_family`): bool
public function setFontSize(float `$point_size`): bool
public function setFontStretch(int `$stretch`): bool
public function setFontStyle(int `$style`): bool
public function setFontWeight(int `$weight`): bool
public function setGravity(int `$gravity`): bool
public function setResolution(float `$resolution_x`, float `$resolution_y`): bool
public function setStrokeAlpha(float `$alpha`): bool
public function setStrokeAntialias(bool `$enabled`): bool
public function setStrokeColor(ImagickPixel|string `$color`): bool
public function setStrokeDashArray(?array `$dashes`): bool
public function setStrokeDashOffset(float `$dash_offset`): bool
public function setStrokeLineCap(int `$linecap`): bool
public function setStrokeLineJoin(int `$linejoin`): bool
public function setStrokeMiterLimit(int `$miterlimit`): bool
public function setStrokeOpacity(float `$opacity`): bool
public function setStrokePatternURL(string `$stroke_url`): bool
public function setStrokeWidth(float `$width`): bool
public function setTextAlignment(int `$align`): bool
public function setTextAntialias(bool `$antialias`): bool
public function setTextDecoration(int `$decoration`): bool
public function setTextEncoding(string `$encoding`): bool
public function setTextInterlineSpacing(float `$spacing`): bool
public function setTextInterwordSpacing(float `$spacing`): bool
public function setTextKerning(float `$kerning`): bool
public function setTextUnderColor(ImagickPixel|string `$under_color`): bool
public function setVectorGraphics(string `$xml`): bool
public function setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
public function skewX(float `$degrees`): bool
public function skewY(float `$degrees`): bool
public function translate(float `$x`, float `$y`): bool
}

# ImagickDraw::affine

(PECL imagick 2, PECL imagick 3)

ImagickDraw::affine — Ajuste la matrice de transformation affine courante

### Description

public function ImagickDraw::affine(array `$affine`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Ajuste la matrice de transformation affine courante, avec la nouvelle matrice de transformation.

### Liste de paramètres

`affine`

  Paramètres de matrice de transformation affine.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::affine()

    <?php
    function affine($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $PI = 3.141592653589794;
        $angle = 60 * $PI / 360;

        //Scale the drawing co-ordinates.
        $affineScale = array("sx" => 1.75, "sy" => 1.75, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

        //Shear the drawing co-ordinates.
        $affineShear = array("sx" => 1, "sy" => 1, "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0);

        //Rotate the drawing co-ordinates. The shear affine matrix
        //produces incorrectly scaled drawings.
        $affineRotate = array("sx" => cos($angle), "sy" => cos($angle), "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0,);

        //Translate (offset) the drawing
        $affineTranslate = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 30, "ty" => 30);

        //The identity affine matrix
        $affineIdentity = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

        $examples = [$affineScale, $affineShear, $affineRotate, $affineTranslate, $affineIdentity,];

        $count = 0;

        foreach ($examples as $example) {
            $draw->push();
            $draw->translate(($count % 2) * 250, intval($count / 2) * 250);
            $draw->translate(100, 100);
            $draw->affine($example);
            $draw->rectangle(-50, -50, 50, 50);
            $draw->pop();
            $count++;
        }

        //Create an image object which the draw commands can be rendered into
        $image = new \Imagick();
        $image->newImage(500, 750, $backgroundColor);
        $image->setImageFormat("png");

        //Render the draw commands in the ImagickDraw object
        //into the image.
        $image->drawImage($draw);

        //Send the image to the browser
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::annotation

(PECL imagick 2, PECL imagick 3)

ImagickDraw::annotation — Dessine un texte sur une image

### Description

public function ImagickDraw::annotation(float `$x`, float `$y`, string `$text`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine un texte sur une image.

### Liste de paramètres

`x`

  L'abscisse du texte à dessiner.

`y`

  L'ordonnée du texte à dessiner.

`text`

  Le texte à dessiner.

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::arc

(PECL imagick 2, PECL imagick 3)

ImagickDraw::arc — Dessine un arc

### Description

public function ImagickDraw::arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine un arc, placé à l'intérieur d'un rectangle.

### Liste de paramètres

`start_x`

  Abscisse du point de début d'arc dans le rectangle d'encadrement

`start_y`

  Ordonnée du point de début d'arc dans le rectangle d'encadrement

`end_x`

  Abscisse du point de fin d'arc dans le rectangle d'encadrement

`end_y`

  Ordonnée du point de fin d'arc dans le rectangle d'encadrement

`start_angle`

  Degré de rotation initial

`end_angle`

  Degré de rotation final

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::arc()

    <?php
    function arc($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $startAngle, $endAngle) {

        //Create a ImagickDraw object to draw into.
        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);

        $draw->arc($startX, $startY, $endX, $endY, $startAngle, $endAngle);

        //Create an image object which the draw commands can be rendered into
        $image = new \Imagick();
        $image->newImage(IMAGE_WIDTH, IMAGE_HEIGHT, $backgroundColor);
        $image->setImageFormat("png");

        //Render the draw commands in the ImagickDraw object
        //into the image.
        $image->drawImage($draw);

        //Send the image to the browser
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::bezier

(PECL imagick 2, PECL imagick 3)

ImagickDraw::bezier — Dessine une courbe de Bézier

### Description

public function ImagickDraw::bezier(array `$coordinates`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une courbe de Bézier, à l'aide d'une série de points de contrôle.

### Liste de paramètres

`coordinates`

  Tableau multidimensionnel tel que `array( array( 'x' => 1, 'y' => 2 ), array( 'x' => 3, 'y' => 4 ) )`

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::bezier()

    <?php
    function bezier($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $smoothPointsSet = [
            [
                ['x' => 10.0 * 5, 'y' => 10.0 * 5],
                ['x' => 30.0 * 5, 'y' => 90.0 * 5],
                ['x' => 25.0 * 5, 'y' => 10.0 * 5],
                ['x' => 50.0 * 5, 'y' => 50.0 * 5],
            ],
            [
                ['x' => 50.0 * 5, 'y' => 50.0 * 5],
                ['x' => 75.0 * 5, 'y' => 90.0 * 5],
                ['x' => 70.0 * 5, 'y' => 10.0 * 5],
                ['x' => 90.0 * 5, 'y' => 40.0 * 5],
            ],
        ];

        foreach ($smoothPointsSet as $points) {
            $draw->bezier($points);
        }

        $disjointPoints = [
            [
                ['x' => 10 * 5, 'y' => 10 * 5],
                ['x' => 30 * 5, 'y' => 90 * 5],
                ['x' => 25 * 5, 'y' => 10 * 5],
                ['x' => 50 * 5, 'y' => 50 * 5],
            ],
            [
                ['x' => 50 * 5, 'y' => 50 * 5],
                ['x' => 80 * 5, 'y' => 50 * 5],
                ['x' => 70 * 5, 'y' => 10 * 5],
                ['x' => 90 * 5, 'y' => 40 * 5],
             ]
        ];
        $draw->translate(0, 200);

        foreach ($disjointPoints as $points) {
            $draw->bezier($points);
        }

        //Création d'un objet image dans lequel on appliquera les commandes de dessin
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        //On applique les commandes de dessin à l'objet ImagickDraw
        //et dans l'image.
        $imagick->drawImage($draw);

        //On envoie l'image au navigateur
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::circle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::circle — Dessine un cercle

### Description

public function ImagickDraw::circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine un cercle.

### Liste de paramètres

`origin_x`

  abscisse de l'origine

`origin_y`

  ordonnée de l'origine

`perimeter_x`

  abscisse du périmètre

`perimeter_y`

  ordonnée du périmètre

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::circle()

    <?php
    function circle($strokeColor, $fillColor, $backgroundColor, $originX, $originY, $endX, $endY) {

        //Création d'un objet ImagickDraw.
        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->circle($originX, $originY, $endX, $endY);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::clear

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clear — Efface tout l'objet ImagickDraw

### Description

public function ImagickDraw::clear(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Efface tout l'objet ImagickDraw et toutes les commandes accumulées, puis remet les directives à leur valeur par défaut.

### Valeurs de retour

Retourne un objet ImagickDraw.

# ImagickDraw::clone

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clone — Fait une copie exacte de l'objet ImagickDraw

### Description

public function ImagickDraw::clone(): ImagickDraw
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Fait une copie exacte de l'objet ImagickDraw.

### Valeurs de retour

Retourne une copie exacte de l'objet ImagickDraw.

# ImagickDraw::color

(PECL imagick 2, PECL imagick 3)

ImagickDraw::color — Dessine une couleur sur une image

### Description

public function ImagickDraw::color(float `$x`, float `$y`, int `$paint`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une couleur sur une image, avec la couleur de remplissage courante, en commençant à une position donnée, et en utilisant la méthode de coloration indiquée.

### Liste de paramètres

`x`

  abscisse du point de peinture

`y`

  ordonnée du point de peinture

`paint`

  Une des constantes PAINT (`imagick::PAINT_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::comment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::comment — Ajoute un commentaire

### Description

public function ImagickDraw::comment(string `$comment`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Ajoute un commentaire au flux de sortie.

### Liste de paramètres

`comment`

  La chaîne de commentaire

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::composite

(PECL imagick 2, PECL imagick 3)

ImagickDraw::composite — Compose une image avec une autre

### Description

public function ImagickDraw::composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Compose une image avec une autre image, en utilisant l'opérateur de composition, à la position et à la taille indiquées.

### Liste de paramètres

`composite`

  l'opérateur de composition. Une des constantes d'opérateur de composition (`imagick::COMPOSITE_*`).

`x`

  abscisse du coin supérieur gauche.

`y`

  ordonnée du coin supérieur gauche.

`width`

  largeur de l'image de composition.

`height`

  hauteur de l'image de composition.

`image`

  L'objet Imagick où la composition est prise.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickDraw::composite()

    <?php
    function composite($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setFillOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFont("../fonts/CANDY.TTF");
        $draw->setFontSize(140);
        $draw->rectangle(0, 0, 1000, 300);
        $draw->setFillColor('white');
        $draw->setfillopacity(1);
        $draw->annotation(50, 180, "Lorem Ipsum!");

        //Crée un objet image servant de base
        $imagick = new \Imagick();
        $imagick->newImage(1000, 302, $backgroundColor);
        $imagick->setImageFormat("png");

        //On applique les commandes de dessin dans l'objet ImagickDraw
        //et dans l'image.
        $imagick->drawImage($draw);

        //On envoie l'image au navigateur
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::__construct

(PECL imagick 2, PECL imagick 3)

ImagickDraw::__construct — Le constructeur ImagickDraw

### Description

public function ImagickDraw::__construct()
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Le constructeur de la classe ImagickDraw.

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::destroy

(PECL imagick 2, PECL imagick 3)

ImagickDraw::destroy — Libère toutes les ressources associées à un objet ImagickDraw

### Description

public function ImagickDraw::destroy(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Libère toutes les ressources associées à un objet ImagickDraw.

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::ellipse

(PECL imagick 2, PECL imagick 3)

ImagickDraw::ellipse — Dessine une ellipse sur une image

### Description

public function ImagickDraw::ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une ellipse sur une image.

### Liste de paramètres

`origin_x`

`origin_y`

`radius_x`

`radius_y`

`angle_start`

`angle_end`

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::ellipse()

    <?php
    function ellipse($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->ellipse(125, 70, 100, 50, 0, 360);
        $draw->ellipse(350, 70, 100, 50, 0, 315);

        $draw->push();
        $draw->translate(125, 250);
        $draw->rotate(30);
        $draw->ellipse(0, 0, 100, 50, 0, 360);
        $draw->pop();

        $draw->push();
        $draw->translate(350, 250);
        $draw->rotate(30);
        $draw->ellipse(0, 0, 100, 50, 0, 315);
        $draw->pop();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::getClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipPath — Retourne l'identifiant du chemin courant

### Description

public function ImagickDraw::getClipPath(): false|string
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne l'identifiant du chemin courant.

### Valeurs de retour

Retourne une chaîne, ou `false` si aucun chemin n'existe.

# ImagickDraw::getClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipRule — Retourne la règle de remplissage courante pour les polygones

### Description

public function ImagickDraw::getClipRule(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la règle de remplissage courante pour les polygones.

### Valeurs de retour

Retourne une constante FILLRULE (`imagick::FILLRULE_*`).

# ImagickDraw::getClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipUnits — Retourne l'unité d'interprétation des chemins

### Description

public function ImagickDraw::getClipUnits(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne l'unité d'interprétation des chemins.

### Valeurs de retour

Retourne un entier en cas de succès.

# ImagickDraw::getFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillColor — Retourne la couleur de remplissage

### Description

public function ImagickDraw::getFillColor(): ImagickPixel
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la couleur de remplissage utilisée pour les objets pleins.

### Valeurs de retour

Retourne un objet ImagickPixel.

# ImagickDraw::getFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillOpacity — Retourne l'opacité de dessin

### Description

public function ImagickDraw::getFillOpacity(): float
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne l'opacité de dessin. 1.0 représente l'opacité totale.

### Valeurs de retour

L'opacité.

# ImagickDraw::getFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillRule — Retourne la règle de remplissage

### Description

public function ImagickDraw::getFillRule(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la règle de remplissage utilisée lors du dessin des polygones.

### Valeurs de retour

Retourne une constante FILLRULE (`imagick::FILLRULE_*`).

# ImagickDraw::getFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFont — Retourne la police

### Description

public function ImagickDraw::getFont(): string
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne une chaîne spécifiant la police utilisée pour les annotations.

### Valeurs de retour

Retourne une chaîne en cas de succès, et `false` sinon.

# ImagickDraw::getFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontFamily — Retourne la famille de police

### Description

public function ImagickDraw::getFontFamily(): string
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la famille de police des annotations.

### Valeurs de retour

Retourne la famille de police des annotations, ou `false` si la famille de police n'est pas configurée.

# ImagickDraw::getFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontSize — Retourne la taille de la police

### Description

public function ImagickDraw::getFontSize(): float
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la taille de la police.

### Valeurs de retour

Retourne la taille de la police utilisée par l'objet ImagickDraw.

# ImagickDraw::getFontStretch

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickDraw::getFontStretch — Renvoie l'étirement de la police à utiliser lors de l'annotation avec du texte

### Description

public function ImagickDraw::getFontStretch(): int

Renvoie l'étirement de la police à utiliser lors de l'annotation avec du texte. Renvoie un StretchType.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# ImagickDraw::getFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontStyle — Retourne le style de la police

### Description

public function ImagickDraw::getFontStyle(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne le style de la police.

### Valeurs de retour

Retourne une constante STYLE (`imagick::STYLE_*`), associée à l'objet ImagickDraw, ou 0 si le style n'est pas fait.

# ImagickDraw::getFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontWeight — Retourne le poids de la police

### Description

public function ImagickDraw::getFontWeight(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne le poids de la police.

### Valeurs de retour

Retourne un entier en cas de succès, et 0 si le poids n'est pas configuré.

# ImagickDraw::getGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getGravity — Retourne la gravité de placement de texte

### Description

public function ImagickDraw::getGravity(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la gravité de placement de texte, utilisée lors de l'annotation.

### Valeurs de retour

Retourne une constante GRAVITY (`imagick::GRAVITY_*`) en cas de succès, ou 0 si la gravité n'est pas configurée.

# ImagickDraw::getStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeAntialias — Retourne la configuration d'anti-aliasing de trait

### Description

public function ImagickDraw::getStrokeAntialias(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la configuration d'anti-aliasing de trait. Les traits de dessins sont anti-aliasés par défaut. Lorsque l'anti-aliasing est désactivé, les pixels sont évalués à partir d'un seuil, pour déterminer si la couleur de trait ou de fond doit être utilisée.

### Valeurs de retour

Retourne `true` si l'anti-aliasing est activé, ou `false` sinon.

# ImagickDraw::getStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeColor — Retourne la couleur des contours d'objets

### Description

public function ImagickDraw::getStrokeColor(): ImagickPixel
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la couleur des contours d'objets.

### Liste de paramètres

`stroke_color`

### Valeurs de retour

Retourne un objet ImagickPixel qui décrit la couleur.

# ImagickDraw::getStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashArray — Retourne un tableau représentant le motif de pointillés

### Description

public function ImagickDraw::getStrokeDashArray(): array
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne un tableau représentant le motif de pointillés, les vides et les pleins.

### Valeurs de retour

Retourne un tableau en cas de succès, et un tableau vide sinon.

# ImagickDraw::getStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashOffset — Retourne l'offset du pointillé dans le motif

### Description

public function ImagickDraw::getStrokeDashOffset(): float
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne l'offset du pointillé dans le motif.

### Valeurs de retour

Retourne un nombre décimal représentant le début du pointillé dans le motif.

# ImagickDraw::getStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineCap — Retourne la forme à utiliser pour dessiner les bouts de sous-chemins

### Description

public function ImagickDraw::getStrokeLineCap(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la forme à utiliser pour dessiner les bouts de sous-chemins.

### Valeurs de retour

Retourne une constante LINECAP (`imagick::LINECAP_*`), ou 0 si les bouts de lignes ne sont pas configurés.

# ImagickDraw::getStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineJoin — Retourne la forme à utiliser pour dessiner les coins d'un chemin

### Description

public function ImagickDraw::getStrokeLineJoin(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la forme à utiliser pour dessiner les coins d'un chemin (ou d'autres formes vectorielles), quand ils sont dessinés.

### Valeurs de retour

Retourne une constante LINEJOIN (`imagick::LINEJOIN_*`), ou 0 si les coins ne sont pas configurés.

# ImagickDraw::getStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeMiterLimit — Retourne la 'miterLimit'

### Description

public function ImagickDraw::getStrokeMiterLimit(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la 'miterLimit'. Lorsque deux segments se rencontrent à angle aigu, que des jointures miter ont été spécifiées pour `'lineJoin'`, il est possible pour le miter de dépasser l'épaisseur du trait du chemin. La 'miterLimit' impose une limite au ratio entre la longueur du miter et `'lineWidth'`.

### Valeurs de retour

Retourne un entier décrivant la 'miterLimit', et 0 si la 'miterLimit' n'est pas configurée.

# ImagickDraw::getStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeOpacity — Retourne l'opacité des contours d'un objet

### Description

public function ImagickDraw::getStrokeOpacity(): float
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne l'opacité des contours d'un objet.

### Valeurs de retour

Retourne un float décrivant l'opacité des contours d'un objet.

# ImagickDraw::getStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeWidth — Retourne la largeur du trait utilisé

### Description

public function ImagickDraw::getStrokeWidth(): float
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la largeur du trait utilisé.

### Valeurs de retour

Retourne un float qui décrit la largeur du trait.

# ImagickDraw::getTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAlignment — Retourne l'alignement du texte

### Description

public function ImagickDraw::getTextAlignment(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne l'alignement du texte.

### Valeurs de retour

Retourne une constante ALIGN (`imagick::ALIGN_*`), ou 0 si l'alignement n'est pas configuré.

# ImagickDraw::getTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAntialias — Retourne la configuration de l'anti-aliasing de texte

### Description

public function ImagickDraw::getTextAntialias(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la configuration de l'anti-aliasing de texte, qui détermine si le texte est anti-aliasé ou pas. Les textes sont anti-aliasés par défaut.

### Valeurs de retour

Retourne `true` si le texte est anti-aliasé, et `false` sinon.

# ImagickDraw::getTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextDecoration — Retourne la décoration du texte

### Description

public function ImagickDraw::getTextDecoration(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la décoration du texte d'annotation.

### Valeurs de retour

Retourne une constante DECORATION (`imagick::DECORATION_*`), ou bien 0 si aucune décoration n'est configurée.

# ImagickDraw::getTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextEncoding — Retourne le jeu de caractères utilisé pour les annotations de texte

### Description

public function ImagickDraw::getTextEncoding(): false|string
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne le jeu de caractères utilisé pour les annotations de texte.

### Valeurs de retour

Retourne une chaîne spécifiant le jeu de caractères, ou bien `false` si le jeu de caractères n'est pas configuré.

# ImagickDraw::getTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterlineSpacing — Récupère l'espacement interlignes d'un texte.

### Description

public function ImagickDraw::getTextInterlineSpacing(): float

Récupère l'espacement interlignes d'un texte.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# ImagickDraw::getTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterwordSpacing — Récupère l'espace entre les mots d'un texte.

### Description

public function ImagickDraw::getTextInterwordSpacing(): float

Récupère l'espace entre les mots d'un texte.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# ImagickDraw::getTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextKerning — Récupère le crénage d'un texte.

### Description

public function ImagickDraw::getTextKerning(): float

Récupère le crénage d'un texte.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# ImagickDraw::getTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextUnderColor — Retourne la couleur sous le texte

### Description

public function ImagickDraw::getTextUnderColor(): ImagickPixel
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la couleur du rectangle placé sous le texte des annotations.

### Valeurs de retour

Retourne un objet ImagickPixel, qui décrit la couleur.

# ImagickDraw::getVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getVectorGraphics — Retourne une chaîne contenant le vecteur graphique

### Description

public function ImagickDraw::getVectorGraphics(): string
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne une chaîne contenant le vecteur graphique, généré par les appels graphiques depuis que l'objet ImagickDraw a été créé.

### Valeurs de retour

Retourne une chaîne contenant les vecteurs graphiques.

# ImagickDraw::line

(PECL imagick 2, PECL imagick 3)

ImagickDraw::line — Dessine une ligne

### Description

public function ImagickDraw::line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une ligne en utilisant la couleur de trait courante, son opacité, et sa largeur.

### Liste de paramètres

`start_x`

  L'abscisse de début

`start_y`

  L'ordonnée de début

`end_x`

  L'abscisse de fin

`end_y`

  L'ordonnée de fin

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::line()

    <?php
    function line($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->line(125, 70, 100, 50);
        $draw->line(350, 170, 100, 150);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::matte

(PECL imagick 2, PECL imagick 3)

ImagickDraw::matte — Dessine sur le canal d'opacité de l'image

### Description

public function ImagickDraw::matte(float `$x`, float `$y`, int `$paint`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine sur le canal d'opacité de l'image, afin de rendre transparent les pixels indiqués.

### Liste de paramètres

`x`

  abscisse du mate

`y`

  ordonnée du mate

`paint`

  Une des constantes PAINT (`imagick::PAINT_*`).

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ImagickDraw::matte()

    <?php
    function matte($strokeColor, $fillColor, $backgroundColor, $paintType) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->matte(120, 120, $paintType);
        $draw->rectangle(100, 100, 300, 200);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::pathClose

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathClose — Ajoute un élément de chemin au chemin courant

### Description

public function ImagickDraw::pathClose(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Ajoute un élément de chemin au chemin courant, qui va clore le sous-chemin en dessinant une ligne droite depuis le point courant jusqu'au point de démarrage le plus récent (généralement, le dernier point de déplacement).

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathCurveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToAbsolute — Dessine une courbe de Bézier cubique, en coordonnées absolues

### Description

public function ImagickDraw::pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une courbe de Bézier cubique, à partir du point courant (`x`,`y`) en utilisant le point (`x1`,`y1`) comme point de contrôle au début de la courbe et (`x2`,`y2`) comme point de contrôle à la fin de la courbe, en utilisant des coordonnées absolues. À la fin de la commande, le nouveau point courant est le point final (`x`,`y`), utilisé par le polybezier.

### Liste de paramètres

`x1`

  abscisse du premier point de contrôle

`y1`

  ordonnée du premier point de contrôle

`x2`

  abscisse du second point de contrôle

`y2`

  ordonnée du second point de contrôle

`x`

  abscisse de la fin de la courbe

`y`

  ordonnée de la fin de la courbe

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathCurveToQuadraticBezierAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierAbsolute — Dessine une courbe de Bézier quadratique, en coordonnées absolues

### Description

public function ImagickDraw::pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une courbe de Bézier quadratique, depuis le point courant jusqu'à (`x`,`y`), en utilisant le point (`x1`,`y1`) comme point de contrôle, en coordonnées absolues. À la fin du dessin, le nouveau point courant devient le point final (`x`,`y`) utilisé par le polybezier.

### Liste de paramètres

`x1`

  abscisse du point de contrôle

`y1`

  ordonnée du point de contrôle

`x_end`

  abscisse du point final

`y`

  ordonnée du point final

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::pathCurveToQuadraticBezierAbsolute()

    <?php
    function pathCurveToQuadraticBezierAbsolute($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50,250);

        // This specifies a quadratic bezier curve with the current position as the start
        // point, the control point is the first two params, and the end point is the last two params.
        $draw->pathCurveToQuadraticBezierAbsolute(
            150,50,
            250,250
        );

        // This specifies a quadratic bezier curve with the current position as the start
        // point, the control point is mirrored from the previous curves control point
        // and the end point is defined by the x, y values.
        $draw->pathCurveToQuadraticBezierSmoothAbsolute(
            450,250
        );

        // This specifies a quadratic bezier curve with the current position as the start
        // point, the control point is mirrored from the previous curves control point
        // and the end point is defined relative from the current position by the x, y values.
        $draw->pathCurveToQuadraticBezierSmoothRelative(
            200,-100
        );

        $draw->pathFinish();

        $imagick = new \Imagick();
        $imagick->newImage(700, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickDraw::pathCurveToQuadraticBezierRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierRelative — Dessine une courbe de Bézier quadratique, en coordonnées relatives

### Description

public function ImagickDraw::pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une courbe de Bézier quadratique, en coordonnées relatives, par rapport au point courant (`x`,`y`), en utilisant le point (`x1`,`y1`) comme point de contrôle. À la fin du dessin, le nouveau point courant devient le point final (`x`,`y`) utilisé par le polybezier.

### Liste de paramètres

`x1`

  abscisse de départ

`y1`

  ordonnée de départ

`x_end`

  abscisse de fin

`y`

  ordonnée de fin

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Dessine une courbe de Bézier quadratique, en coordonnées absolues

### Description

public function ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute(float `$x`, float `$y`): bool

Dessine une courbe de Bézier quadratique, en coordonnées absolues, à partir du point courant (`x`, `y`). Le point de contrôle est la réflexion du point de contrôle sur la commande de dessin en coordonnées absolues. S'il n'y a pas eu de commande précédente ou si la commande précédente n'était pas ImagickDraw::DrawPathCurveToQuadraticBezierAbsolute(), ImagickDraw::DrawPathCurveToQuadraticBezierRelative() ou ImagickDraw::DrawPathCurveToQuadraticBezierSmoothRelative(), on suppose que le point de contrôle coïncide avec le point courant. À la fin de la commande, le nouveau point courant devient le point final (`x`, `y`), utilisé par le polybezier.

Cette fonction ne peut pas être utilisée pour lisser une courbe de Bézier cubique. Elle peut uniquement lisser une courbe quadratique.

### Liste de paramètres

`x`

  L'abscisse du point de fin

`y`

  L'ordonnée du point de fin

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute()

    <?php
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor("black");
    $draw->setFillColor("blue");

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50,250);

    // Ceci définit une courbe de Bezier quadratique avec la position courante comme
    // point de départ, le point de contrôle correspond aux deux premiers paramètres
    // et le point final aux deux derniers paramètres.
    $draw->pathCurveToQuadraticBezierAbsolute(
        150,50,
        250,250
    );

    // Ceci définit une courbe de Bezier quadratique avec la position courante comme
    // point de départ, le point de contrôle est obtenu par effet miroir des points
    // de contrôle des précédentes courbes et le point final est défini par les
    // valeurs x, y.
    $draw->pathCurveToQuadraticBezierSmoothAbsolute(
        450,250
    );

    // Ceci définit une courbe de Bezier quadratique avec la position courante comme
    // point de départ, le point de contrôle est obtenu par effet miroir des points
    // de contrôle des précédentes courbes et le point final est défini relativement
    // à la position courante par les valeurs x, y
    $draw->pathCurveToQuadraticBezierSmoothRelative(
        200,-100
    );

    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(700, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
    ?>

# ImagickDraw::pathCurveToQuadraticBezierSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Dessine une courbe de Bézier quadratique, en coordonnées relatives

### Description

public function ImagickDraw::pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une courbe de Bézier quadratique, en coordonnées relatives, à partir du point courant (`x`, `y`). Le point de contrôle est la réflexion du point de contrôle sur la commande de dessin en coordonnées relatives. S'il n'y a pas eu de commande précédente ou si la commande précédente n'était pas ImagickDraw::DrawPathCurveToQuadraticBezierAbsolute(), ImagickDraw::DrawPathCurveToQuadraticBezierRelative(), ImagickDraw::DrawPathCurveToQuadraticBezierSmoothAbsolut() ou ImagickDraw::DrawPathCurveToQuadraticBezierSmoothRelative() on suppose que le point de contrôle coïncide avec le point courant. À la fin de la commande, le nouveau point courant devient le point final (`x`, `y`), utilisé par le polybezier.

Cette fonction ne peut pas être utilisée pour lisser une courbe de Bézier cubique. Elle peut uniquement lisser une courbe quadratique.

### Liste de paramètres

`x`

  L'abscisse du point de fin

`y`

  L'ordonnée du point de fin

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::pathCurveToQuadraticBezierSmoothRelative()

    <?php
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor("black");
    $draw->setFillColor("blue");

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50,250);

    // Ceci définit une courbe de Bezier quadratique avec la position courante comme
    // point de départ, le point de contrôle correspond aux deux premiers paramètres
    // et le point final aux deux derniers paramètres.
    $draw->pathCurveToQuadraticBezierAbsolute(
        150,50,
        250,250
    );

    // Ceci définit une courbe de Bezier quadratique avec la position courante comme
    // point de départ, le point de contrôle est obtenu par effet miroir des points
    // de contrôle des précédentes courbes et le point final est défini par les
    // valeurs x, y.
    $draw->pathCurveToQuadraticBezierSmoothAbsolute(
        450,250
    );

    // Ceci définit une courbe de Bezier quadratique avec la position courante comme
    // point de départ, le point de contrôle est obtenu par effet miroir des points
    // de contrôle des précédentes courbes et le point final est défini relativement
    // à la position courante par les valeurs x, y
    $draw->pathCurveToQuadraticBezierSmoothRelative(
        200,-100
    );

    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(700, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
    ?>

# ImagickDraw::pathCurveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToRelative — Dessine une courbe de Bézier cubique, en coordonnées relatives

### Description

public function ImagickDraw::pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une courbe de Bézier cubique, à partir du point courant (`x`,`y`) en utilisant le point (`x1`,`y1`) comme point de contrôle au début de la courbe et (`x2`,`y2`) comme point de contrôle à la fin de la courbe, en utilisant des coordonnées relatives. À la fin de la commande, le nouveau point courant est le point final (`x`,`y`), utilisé par le polybezier.

### Liste de paramètres

`x1`

  abscisse du point de départ

`y1`

  ordonnée du point de départ

`x2`

  abscisse du point de contrôle final

`y2`

  ordonnée du point de contrôle final

`x`

  abscisse du point final

`y`

  ordonnée du point final

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathCurveToSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothAbsolute — Dessine une courbe de Bézier, en coordonnées absolues

### Description

public function ImagickDraw::pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une courbe de Bézier, en coordonnées absolues, à partir du point courant (`x`,`y`). Le premier point de contrôle est la réflexion du second point de contrôle de la commande précédente, relative au point courant. S'il n'y a pas eu de commande précédente, ou que la commande précédente n'était pas DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute ou DrawPathCurveToSmoothRelative, on suppose alors que le premier point de contrôle coïncide avec le point courant. (`x2`,`y2`) est le second point de contrôle (c.-à-d., le point de contrôle à la fin de la ligne). À la fin de la commande, le nouveau point courant est le point final, de coordonnées (`x`,`y`), dans le polybezier.

### Liste de paramètres

`x2`

  abscisse du deuxième point de contrôle

`y2`

  ordonnée du deuxième point de contrôle

`x`

  abscisse du point de contrôle final

`y`

  ordonnée du point de contrôle final

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathCurveToSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothRelative — Dessine une courbe de Bézier, en coordonnées relatives

### Description

public function ImagickDraw::pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une courbe de Bézier, en coordonnées relatives, à partir du point courant (`x`,`y`). Le premier point de contrôle est la réflexion du second point de contrôle de la commande précédente, relative au point courant. S'il n'y a pas eu de commande précédente, ou que la commande précédente n'était pas DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute ou DrawPathCurveToSmoothRelative, on suppose alors que le premier point de contrôle coïncide avec le point courant. (`x2`,`y2`) est le second point de contrôle (c.-à-d., le point de contrôle à la fin de la ligne). À la fin de la commande, le nouveau point courant est le point final, de coordonnées (`x`,`y`), dans le polybezier.

### Liste de paramètres

`x2`

  abscisse du deuxième point de contrôle

`y2`

  ordonnée du deuxième point de contrôle

`x`

  abscisse du point de contrôle final

`y`

  ordonnée du point de contrôle final

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathEllipticArcAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcAbsolute — Dessine un arc d'ellipse, en coordonnées absolues

### Description

public function ImagickDraw::pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine un arc d'ellipse à partir du point courant (`x`, `y`), en utilisant des coordonnées absolues. La taille et l'orientation de l'ellipse sont définies par deux rayons, (`rx`, `ry`) et une rotation xAxisRotation, qui indique comment l'ellipse, dans son ensemble, est située dans le système de coordonnées. Le centre (`cx`, `cy`) de l'ellipse est calculé automatiquement pour satisfaire aux contraintes des autres paramètres. Si `large_arc` vaut `true`, alors c'est l'arc le plus grand qui est dessiné. Si `sweep` vaut `true`, alors le dessin de l'arc se fait dans le sens horaire.

### Liste de paramètres

`rx`

  Rayon X

`ry`

  Rayon Y

`x_axis_rotation`

  Rotation sur l'axe des X

`large_arc`

  option `large_arc_flag`

`sweep`

  Option `sweep_flag`

`x`

  L'abscisse

`y`

  L'ordonnée

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathEllipticArcRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcRelative — Dessine un arc d'ellipse, en coordonnées relatives

### Description

public function ImagickDraw::pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine un arc d'ellipse à partir du point courant (`x`, `y`), en utilisant des coordonnées relatives. La taille et l'orientation de l'ellipse sont définies par deux rayons, (`rx`, `ry`) et une rotation xAxisRotation, qui indique comment l'ellipse, dans son ensemble, est située dans le système de coordonnées. Le centre (`cx`, `cy`) de l'ellipse est calculé automatiquement pour satisfaire aux contraintes des autres paramètres. Si `large_arc` vaut `true`, alors c'est l'arc le plus grand qui est dessiné. Si `sweep` vaut `true`, alors le dessin de l'arc se fait dans le sens horaire.

### Liste de paramètres

`rx`

  Rayon X

`ry`

  Rayon Y

`x_axis_rotation`

  Rotation sur l'axe des X

`large_arc`

  L'option `large_arc_flag`

`sweep`

  L'option `sweep_flag`

`x`

  L'abscisse

`y`

  L'ordonnée

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathFinish

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathFinish — Termine le chemin courant

### Description

public function ImagickDraw::pathFinish(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Termine le chemin courant.

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathLineToAbsolute

(PECL imagick 2)

ImagickDraw::pathLineToAbsolute — Dessine une ligne de chemin, en coordonnées absolues

### Description

public function ImagickDraw::pathLineToAbsolute(float `$x`, float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une ligne à partir du point courant, jusqu'au point cible, en utilisant des coordonnées absolues. Le point cible devient alors le point courant.

### Liste de paramètres

`x`

  L'abscisse de départ

`y`

  L'abscisse de fin

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathLineToHorizontalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalAbsolute — Dessine une ligne de chemin horizontale, en coordonnées absolues

### Description

public function ImagickDraw::pathLineToHorizontalAbsolute(float `$x`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une ligne horizontale à partir du point courant, jusqu'au point cible, en utilisant des coordonnées absolues. Le point cible devient alors le point courant.

### Liste de paramètres

`x`

  L'abscisse

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathLineToHorizontalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalRelative — Dessine une ligne de chemin horizontale, en coordonnées relatives

### Description

public function ImagickDraw::pathLineToHorizontalRelative(float `$x`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une ligne horizontale à partir du point courant, jusqu'au point cible, en utilisant des coordonnées relatives. Le point cible devient alors le point courant.

### Liste de paramètres

`x`

  L'abscisse

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathLineToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToRelative — Dessine une ligne de chemin, en coordonnées relatives

### Description

public function ImagickDraw::pathLineToRelative(float `$x`, float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une ligne à partir du point courant, jusqu'au point cible, en utilisant des coordonnées relatives. Le point cible devient alors le point courant.

### Liste de paramètres

`x`

  abscisse de départ

`y`

  ordonnée de départ

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathLineToVerticalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalAbsolute — Dessine une ligne de chemin verticale, en coordonnées absolues

### Description

public function ImagickDraw::pathLineToVerticalAbsolute(float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une ligne verticale à partir du point courant, jusqu'au point cible, en utilisant des coordonnées absolues. Le point cible devient alors le point courant.

### Liste de paramètres

`y`

  Ordonnée

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathLineToVerticalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalRelative — Dessine une ligne de chemin verticale, en coordonnées relatives

### Description

public function ImagickDraw::pathLineToVerticalRelative(float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une ligne verticale à partir du point courant, jusqu'au point cible, en utilisant des coordonnées relatives. Le point cible devient alors le point courant.

### Liste de paramètres

`y`

  ordonnée cible

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathMoveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToAbsolute — Commence un nouveau sous-chemin, en coordonnées absolues

### Description

public function ImagickDraw::pathMoveToAbsolute(float `$x`, float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Commence un nouveau sous-chemin à partir des coordonnées indiquées, en utilisant des coordonnées absolues. Le point courant devient alors les coordonnées spécifiées.

### Liste de paramètres

`x`

  L'abscisse cible

`y`

  L'ordonnée cible

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathMoveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToRelative — Commence un nouveau sous-chemin, en coordonnées relatives

### Description

public function ImagickDraw::pathMoveToRelative(float `$x`, float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Commence un nouveau sous-chemin à partir des coordonnées indiquées, en utilisant des coordonnées relatives. Le point courant devient alors les coordonnées spécifiées.

### Liste de paramètres

`x`

  L'abscisse cible

`y`

  L'ordonnée cible

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pathStart

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathStart — Déclare le début d'un chemin de dessin

### Description

public function ImagickDraw::pathStart(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Déclare le début d'un chemin de dessin, qui sera terminé par la commande sœur ImagickDraw::DrawPathFinish(). Toutes les commandes autres que ImagickDraw::DrawPath() doivent être encadrées par ImagickDraw::pathStart() et ImagickDraw::DrawPathFinish(). Ceci est lié au fait que les commandes suivantes sont des commandes subordonnées.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::pathStart()

    <?php
    function pathStart($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 50);
        $draw->pathLineToAbsolute(100, 50);
        $draw->pathLineToRelative(0, 50);
        $draw->pathLineToHorizontalRelative(-50);
        $draw->pathFinish();

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 50);
        $draw->pathMoveToRelative(300, 0);
        $draw->pathLineToRelative(50, 0);
        $draw->pathLineToVerticalRelative(50);
        $draw->pathLineToHorizontalAbsolute(350);
        $draw->pathclose();
        $draw->pathFinish();

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 300);
        $draw->pathCurveToAbsolute(50, 300, 100, 200, 300, 300);
        $draw->pathLineToVerticalAbsolute(350);
        $draw->pathFinish();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::point

(PECL imagick 2, PECL imagick 3)

ImagickDraw::point — Dessine un point

### Description

public function ImagickDraw::point(float `$x`, float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine un point en utilisant la couleur de trait courante, ainsi que l'épaisseur, dans les coordonnées spécifiées.

### Liste de paramètres

`x`

  L'abscisse du point

`y`

  L'ordonnée du point

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::point()

    <?php
    function point($fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setFillColor($fillColor);

        for ($x = 0; $x < 10000; $x++) {
            $draw->point(rand(0, 500), rand(0, 500));
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::polygon

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polygon — Dessine un polygone

### Description

public function ImagickDraw::polygon(array `$coordinates`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine un polygone, en utilisant le trait courant, sa largeur, sa couleur de remplissage, ainsi que le tableau de coordonnées indiqué.

### Liste de paramètres

`coordinates`

  Tableau multidimensionnel de coordonnées, tel que `array( array( 'x' => 3, 'y' => 4 ), array( 'x' => 2, 'y' => 6 ) );`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickDraw::polygon()

    <?php
    function polygon($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(4);

        $draw->setFillColor($fillColor);

        $points = [
            ['x' => 40 * 5, 'y' => 10 * 5],
            ['x' => 20 * 5, 'y' => 20 * 5],
            ['x' => 70 * 5, 'y' => 50 * 5],
            ['x' => 60 * 5, 'y' => 15 * 5],
        ];

        $draw->polygon($points);

        $image = new \Imagick();
        $image->newImage(500, 300, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::polyline

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polyline — Dessine une ligne brisée

### Description

public function ImagickDraw::polyline(array `$coordinates`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine une ligne brisée, en utilisant le trait courant, sa largeur et son motif, ainsi que sa couleur de remplissage ou sa texture, en utilisant les coordonnées spécifiées.

### Liste de paramètres

`coordinates`

  Tableau avec les coordonnées "x" et "y" `array( array( 'x' => 4, 'y' => 6 ), array( 'x' => 8, 'y' => 10 ) )`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickDraw::polyline()

    <?php
    function polyline($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(5);

        $points = [
            ['x' => 40 * 5, 'y' => 10 * 5],
            ['x' => 20 * 5, 'y' => 20 * 5],
            ['x' => 70 * 5, 'y' => 50 * 5],
            ['x' => 60 * 5, 'y' => 15 * 5]
        ];

        $draw->polyline($points);

        $image = new \Imagick();
        $image->newImage(500, 300, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::pop

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pop — Détruit l'objet ImagickDraw courant dans la pile, et retourne son précédent

### Description

public function ImagickDraw::pop(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Détruit l'objet ImagickDraw courant dans la pile, et retourne son précédent. Plusieurs objets ImagickDraw peuvent exister. C'est une erreur que de tenter d'extraire plus d'objets ImagickDraw qu'il n'y en a, et il est recommandé d'en extraire juste le bon nombre.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ImagickDraw::popClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popClipPath — Termine la définition d'un chemin

### Description

public function ImagickDraw::popClipPath(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Termine la définition d'un chemin.

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::popDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popDefs — Termine une définition de liste

### Description

public function ImagickDraw::popDefs(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Termine une définition de liste.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::popDefs()

    <?php
    function popDefs($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setstrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->pushDefs();
        $draw->setStrokeColor('white');
        $draw->rectangle(50, 50, 200, 200);
        $draw->popDefs();

        $draw->rectangle(300, 50, 450, 200);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::popPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popPattern — Termine une définition de motif

### Description

public function ImagickDraw::popPattern(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Termine une définition de motif.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ImagickDraw::push

(PECL imagick 2, PECL imagick 3)

ImagickDraw::push — Clone l'objet ImagickDraw courant et le pousse dans la pile

### Description

public function ImagickDraw::push(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Clone l'objet ImagickDraw courant et le pousse dans la pile, en l'ajoutant à la fin. L'objet ImagickDraw original peut être retrouvé en appliquant la méthode ImagickDraw::pop() à la pile. Les objets ImagickDraws sont stockés dans une pile ImagickDraw. Pour chaque pop, il faut qu'il y ait eu un push équivalent.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ImagickDraw::push()

    <?php
    function push($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillModifiedColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->push();
        $draw->translate(50, 50);
        $draw->rectangle(200, 200, 300, 300);
        $draw->pop();
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::pushClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushClipPath — Commence la définition d'un chemin

### Description

public function ImagickDraw::pushClipPath(string `$clip_mask_id`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Commence la définition d'un chemin, qui est constitué de n'importe quel nombre de commandes de dessins, et terminé par une commande ImagickDraw::popClipPath().

### Liste de paramètres

`clip_mask_id`

  L'identifiant du masque de clip

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pushDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushDefs — Indique que la commande suivante crée des éléments nommés pour pré-traitement

### Description

public function ImagickDraw::pushDefs(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Indique que les commandes jusqu'à la commande terminante de ImagickDraw::popDefs() créent des éléments nommés (p. ex., des chemins, des textures, etc.), qui peuvent être traités au plus tôt par simple souci d'efficacité.

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::pushPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushPattern — Configure un espace de dessin

### Description

public function ImagickDraw::pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure ImagickDraw pour que les commandes jusqu'à la fonction DrawPopPattern() incluent la définition d'un nom de motif. L'espace de motif reçoit les coordonnées du coin supérieur gauche, de la hauteur et largeur, et devient un espace de dessin en lui-même. Tout ce qui peut être dessiné peut être dessiné dans un motif. Des motifs peuvent aussi définir des traits ou des brosses.

### Liste de paramètres

`pattern_id`

  L'identifiant du motif

`x`

  L'abscisse du coin supérieur gauche

`y`

  L'ordonnée du coin supérieur gauche

`width`

  La largeur du motif

`height`

  La hauteur du motif

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ImagickDraw::pushPattern()

    <?php
    function pushPattern($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(1);

        $draw->pushPattern("MyFirstPattern", 0, 0, 50, 50);
        for ($x = 0; $x < 50; $x += 10) {
            for ($y = 0; $y < 50; $y += 5) {
                $positionX = $x + (($y / 5) % 5);
                $draw->rectangle($positionX, $y, $positionX + 5, $y + 5);
            }
        }
        $draw->popPattern();

        $draw->setFillOpacity(0);
        $draw->rectangle(100, 100, 400, 400);
        $draw->setFillOpacity(1);

        $draw->setFillOpacity(1);

        $draw->push();
        $draw->setFillPatternURL('#MyFirstPattern');
        $draw->setFillColor('yellow');
        $draw->rectangle(100, 100, 400, 400);
        $draw->pop();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::rectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rectangle — Dessine un rectangle

### Description

public function ImagickDraw::rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine un rectangle à partir de ses coordonnées et en utilisant le trait courant, sa largeur et son motif.

### Liste de paramètres

`top_left_x`

  abscisse du coin supérieur gauche

`top_left_y`

  ordonnée du coin supérieur gauche

`bottom_right_x`

  abscisse du coin inférieur droit

`bottom_right_y`

  ordonnée du coin inférieur droit

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::rectangle()

    <?php
    function rectangle($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->rectangle(200, 200, 300, 300);
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::render

(PECL imagick 2, PECL imagick 3)

ImagickDraw::render — Effectue le rendu de tous les dessins à l'image

### Description

public function ImagickDraw::render(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Effectue le rendu de tous les dessins à l'image.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ImagickDraw::resetVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::resetVectorGraphics — Réinitialise les graphiques vectoriels

### Description

public function ImagickDraw::resetVectorGraphics(): bool

Réinitialise les graphiques vectoriels.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickDraw::rotate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rotate — Applique une rotation

### Description

public function ImagickDraw::rotate(float `$degrees`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Applique une rotation d'un angle donné aux coordonnées de l'espace courant.

### Liste de paramètres

`degrees`

  Angle de rotation, en degrés.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::rotate()

    <?php
    function rotate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeOpacity(1);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);
        $draw->setFillColor($fillModifiedColor);
        $draw->rotate(15);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::roundRectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::roundRectangle — Dessine un rectangle aux coins arrondis

### Description

public function ImagickDraw::roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Dessine un rectangle aux coins arrondis, à partir de deux coordonnées, x & y, du rayon de coin et en utilisant le trait courant, son épaisseur et sa couleur de remplissage.

### Liste de paramètres

`top_left_x`

  L'abscisse du coin supérieur gauche

`top_left_y`

  L'ordonnée du coin supérieur gauche

`bottom_right_x`

  L'abscisse du coin inférieur droit

`bottom_right_y`

  L'ordonnée du coin inférieur droit

`rounding_x`

  Le rayon en x

`rounding_y`

  Le rayon en y

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::roundRectangle()

    <?php
    function roundRectangle($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $roundX, $roundY) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->roundRectangle($startX, $startY, $endX, $endY, $roundX, $roundY);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::scale

(PECL imagick 2, PECL imagick 3)

ImagickDraw::scale — Ajuste le facteur de mise à l'échelle

### Description

public function ImagickDraw::scale(float `$x`, float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Ajuste le facteur de mise à l'échelle à appliquer aux directions verticales et horizontales de l'espace de coordonnées courant.

### Liste de paramètres

`x`

  facteur horizontal

`y`

  facteur vertical

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::scale()

    <?php
    function scale($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(4);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);
        $draw->setFillColor($fillModifiedColor);
        $draw->scale(1.4, 1.4);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipPath — Associe un chemin avec une image

### Description

public function ImagickDraw::setClipPath(string `$clip_mask`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Associe un chemin avec une image. Seules les surfaces dessinées sur le chemin seront modifiées tant qu'il reste actif.

### Liste de paramètres

`clip_mask`

  Le nom du chemin

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setClipPath()

    <?php
    function setClipPath($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $clipPathName = 'testClipPath';

        $draw->pushClipPath($clipPathName);
        $draw->rectangle(0, 0, 250, 250);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);
        $draw->rectangle(100, 100, 400, 400);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipRule — Configure la règle de remplissage du polygone à utiliser avec les chemins

### Description

public function ImagickDraw::setClipRule(int `$fillrule`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la règle de remplissage du polygone à utiliser avec les chemins.

### Liste de paramètres

`fillrule`

  Une des constantes FILLRULE (`imagick::FILLRULE_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setClipRule()

    <?php
    function setClipRule($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        //\Imagick::FILLRULE_EVENODD
        //\Imagick::FILLRULE_NONZERO

        $clipPathName = 'testClipPath';
        $draw->pushClipPath($clipPathName);
        $draw->setClipRule(\Imagick::FILLRULE_EVENODD);
        $draw->rectangle(0, 0, 300, 500);
        $draw->rectangle(200, 0, 500, 500);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);
        $draw->rectangle(200, 200, 300, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipUnits — Configure le mode d'interprétation des unités de chemin

### Description

public function ImagickDraw::setClipUnits(int `$pathunits`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure le mode d'interprétation des unités de chemin.

### Liste de paramètres

`pathunits`

  Le nombre d'unités de clip

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setClipUnits()

    <?php
    function setClipUnits($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $clipPathName = 'testClipPath';
        $draw->setClipUnits(\Imagick::RESOLUTION_PIXELSPERINCH);
        $draw->pushClipPath($clipPathName);
        $draw->rectangle(0, 0, 250, 250);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);

        //RESOLUTION_PIXELSPERINCH
        //RESOLUTION_PIXELSPERCENTIMETER

        $draw->rectangle(200, 200, 300, 300);
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillAlpha — Configure l'opacité de la couleur de remplissage

### Description

public function ImagickDraw::setFillAlpha(float `$alpha`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure l'opacité à utiliser quand la couleur de remplissage est utilisée. 1.0 est totalement opaque.

### Liste de paramètres

`alpha`

  Canal alpha de la couleur de remplissage

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFillAlpha()

    <?php
    function setFillAlpha($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->rectangle(100, 200, 200, 300);
        @$draw->setFillAlpha(0.4);
        $draw->rectangle(300, 200, 400, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillColor — Configure la couleur de dessin des objets remplis

### Description

public function ImagickDraw::setFillColor(ImagickPixel|string `$fill_color`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la couleur de dessin des objets remplis.

### Liste de paramètres

`fill_color`

  L'objet ImagickPixel à utiliser pour la couleur.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFillColor()

    <?php
    function setFillColor($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(1.5);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle(50, 50, 150, 150);

        $draw->setFillColor("rgb(200, 32, 32)");
        $draw->rectangle(200, 50, 300, 150);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillOpacity — Configure l'opacité à utiliser pour le remplissage

### Description

public function ImagickDraw::setFillOpacity(float `$opacity`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure l'opacité à utiliser pour le remplissage. Totalement opaque est 1.0.

### Liste de paramètres

`opacity`

  L'opacité de remplissage.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFillOpacity()

    <?php
    function setFillOpacity($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->rectangle(100, 200, 200, 300);

        $draw->setFillOpacity(0.4);
        $draw->rectangle(300, 200, 400, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillPatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillPatternURL — Configure l'URL du motif de remplissage des surfaces

### Description

public function ImagickDraw::setFillPatternURL(string `$fill_url`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure l'URL du motif de remplissage des surfaces. Seules les URL locales (`"#identifier"`) sont supportées actuellement. Ces URL sont normalement créées en définissant un nom de motif de remplissage avec DrawPushPattern/DrawPopPattern.

### Liste de paramètres

`fill_url`

  L'URL à utiliser pour accéder au motif.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# ImagickDraw::setFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillRule — Configure la règle de remplissage des polygones

### Description

public function ImagickDraw::setFillRule(int `$fillrule`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la règle de remplissage des polygones.

### Liste de paramètres

`fillrule`

  Une des constantes FILLRULE (`imagick::FILLRULE_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFillRule()

    <?php
    function setFillRule($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $fillRules = [\Imagick::FILLRULE_NONZERO, \Imagick::FILLRULE_EVENODD];

        $points = 11;
        $size = 150;

        $draw->translate(175, 160);

        for ($x = 0; $x < 2; $x++) {
            $draw->setFillRule($fillRules[$x]);
            $draw->pathStart();
            for ($n = 0; $n < $points * 2; $n++) {

                if ($n >= $points) {
                    $angle = fmod($n * 360 * 4 / $points, 360) * pi() / 180;
                }
                else {
                    $angle = fmod($n * 360 * 3 / $points, 360) * pi() / 180;
                }

                $positionX = $size * sin($angle);
                $positionY = $size * cos($angle);

                if ($n == 0) {
                    $draw->pathMoveToAbsolute($positionX, $positionY);
                }
                else {
                    $draw->pathLineToAbsolute($positionX, $positionY);
                }
            }

            $draw->pathClose();
            $draw->pathFinish();

            $draw->translate(325, 0);
        }

        $image = new \Imagick();
        $image->newImage(700, 320, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFont — Configure la police complète pour les textes

### Description

public function ImagickDraw::setFont(string `$font_name`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la police complète pour les textes.

### Liste de paramètres

`font_name`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFont()

    <?php
    function setFont($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(36);

        $draw->setFont("../fonts/Arial.ttf");
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFont("../fonts/Consolas.ttf");
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFont("../fonts/CANDY.TTF");
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFont("../fonts/Inconsolata-dz.otf");
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontFamily — Configure la famille de police pour les textes

### Description

public function ImagickDraw::setFontFamily(string `$font_family`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la famille de police pour les textes.

### Liste de paramètres

`font_family`

  La famille de police

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFontFamily()

    <?php
    function setFontFamily($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $draw->setFontSize(48);

        $draw->setFontFamily("Times");
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontFamily("AvantGarde");
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontFamily("NewCenturySchlbk");
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFontFamily("Palatino");
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(450, 250, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontSize — Configure la taille de point pour les textes

### Description

public function ImagickDraw::setFontSize(float `$point_size`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la taille de point pour les textes.

### Liste de paramètres

`point_size`

  La taille de point.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFontSize()

    <?php
    function setFontSize($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFont("../fonts/Arial.ttf");

        $sizes = [24, 36, 48, 60, 72];

        foreach ($sizes as $size) {
            $draw->setFontSize($size);
            $draw->annotation(50, ($size * $size / 16), "Lorem Ipsum!");
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontStretch

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStretch — Configure l'étirement du texte

### Description

public function ImagickDraw::setFontStretch(int `$stretch`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure l'étirement du texte pour le dessin des annotations. L'énumération `AnyStretch` sert de joker et signifie "peu importe".

### Liste de paramètres

`stretch`

  Une des constantes STRETCH (`imagick::STRETCH_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFontStretch()

    <?php
    function setFontStretch($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(36);

        $fontStretchTypes = [
            \Imagick::STRETCH_ULTRACONDENSED,
            \Imagick::STRETCH_CONDENSED,
            \Imagick::STRETCH_SEMICONDENSED,
            \Imagick::STRETCH_SEMIEXPANDED,
            \Imagick::STRETCH_EXPANDED,
            \Imagick::STRETCH_EXTRAEXPANDED,
            \Imagick::STRETCH_ULTRAEXPANDED,
            \Imagick::STRETCH_ANY
        ];

        $offset = 0;
        foreach ($fontStretchTypes as $fontStretch) {
            $draw->setFontStretch($fontStretch);
            $draw->annotation(50, 75 + $offset, "Lorem Ipsum!");
            $offset += 50;
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStyle — Configure le style de police

### Description

public function ImagickDraw::setFontStyle(int `$style`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure le style de police utilisée pour dessiner les annotations. L'énumération `AnyStyle` joue le rôle de joker, et signifie "peu importe".

### Liste de paramètres

`style`

  Une des constantes STYLE (`imagick::STYLE_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFontStyle()

    <?php
    function setFontStyle($fillColor, $strokeColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(36);
        $draw->setFontStyle(\Imagick::STYLE_NORMAL);
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontStyle(\Imagick::STYLE_ITALIC);
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontStyle(\Imagick::STYLE_OBLIQUE);
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(350, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontWeight — Configure le poids de la police

### Description

public function ImagickDraw::setFontWeight(int `$weight`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure le poids de la police pour dessiner les annotations.

### Liste de paramètres

`weight`

### Valeurs de retour

### Exemples

Exemple #1 Exemple avec ImagickDraw::setFontWeight()

    <?php
    function setFontWeight($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(1);

        $draw->setFontSize(36);

        $draw->setFontWeight(100);
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontWeight(200);
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontWeight(400);
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFontWeight(800);
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setGravity — Configure la gravité de placement de texte

### Description

public function ImagickDraw::setGravity(int `$gravity`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la gravité de placement de texte, à utiliser pour dessiner les annotations.

### Liste de paramètres

`gravity`

  Une des constantes GRAVITY (`imagick::GRAVITY_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setGravity()

    <?php
    function setGravity($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(24);

        $gravitySettings = array(
            \Imagick::GRAVITY_NORTHWEST => 'NorthWest',
            \Imagick::GRAVITY_NORTH => 'North',
            \Imagick::GRAVITY_NORTHEAST => 'NorthEast',
            \Imagick::GRAVITY_WEST => 'West',
            \Imagick::GRAVITY_CENTER => 'Centre',
            \Imagick::GRAVITY_SOUTHWEST => 'SouthWest',
            \Imagick::GRAVITY_SOUTH => 'South',
            \Imagick::GRAVITY_SOUTHEAST => 'SouthEast',
            \Imagick::GRAVITY_EAST => 'East'
        );

        $draw->setFont("../fonts/Arial.ttf");

        foreach ($gravitySettings as $type => $description) {
            $draw->setGravity($type);
            $draw->annotation(50, 50, '"' . $description . '"');
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setResolution

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setResolution — Définit la résolution

### Description

public function ImagickDraw::setResolution(float `$resolution_x`, float `$resolution_y`): bool

Définit la résolution.

### Liste de paramètres

`resolution_x`

`resolution_y`

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickDraw::setStrokeAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAlpha — Spécifie l'opacité des contours d'objets

### Description

public function ImagickDraw::setStrokeAlpha(float `$alpha`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie l'opacité des contours d'objets.

### Liste de paramètres

`alpha`

  L'opacité

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeAlpha()

    <?php
    function setStrokeAlpha($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeOpacity(0.1);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAntialias — Contrôle l'anti-aliasing des pointillés

### Description

public function ImagickDraw::setStrokeAntialias(bool `$enabled`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Contrôle l'anti-aliasing des pointillés. Les contours à traits sont anti-aliasés par défaut. Lorsque l'anti-aliasing est désactivé, les pointillés utilisent une valeur de seuil pour définir si le pixel sous-jacent doit être coloré ou pas.

### Liste de paramètres

`enabled`

  La configuration d'utilisation de l'anti-aliasing

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeAntialias()

    <?php
    function setStrokeAntialias($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setStrokeAntialias(false);
        $draw->line(100, 100, 400, 105);

        $draw->line(100, 140, 400, 185);

        $draw->setStrokeAntialias(true);
        $draw->line(100, 110, 400, 115);
        $draw->line(100, 150, 400, 195);

        $image = new \Imagick();
        $image->newImage(500, 250, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeColor — Configure la couleur utilisée pour dessiner les objets

### Description

public function ImagickDraw::setStrokeColor(ImagickPixel|string `$color`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la couleur utilisée pour dessiner les objets.

### Liste de paramètres

`color`

  La couleur du trait.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeColor()

    <?php
    function setStrokeColor($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(5);

        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);

        $draw->setStrokeOpacity(0.1);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashArray — Spécifie le motif de pointillé

### Description

public function ImagickDraw::setStrokeDashArray(?array `$dashes`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie le motif de pointillé, les pleins et vides. L'objet strokeDashArray représente un tableau de nombres qui spécifie les longueurs des pleins et vides, en pixels. Si un nombre impair de valeurs est fourni, alors la liste est répétée pour obtenir un nombre pair de valeurs. Pour retirer un tableau de motif existant, passez un nombre d'éléments à zéro, et `null` comme deuxième valeur. Un tableau strokeDashArray typique contient les membres 5 3 2.

### Liste de paramètres

`dashes`

  Un tableau de nombres décimaux

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeDashArray()

    <?php
    function setStrokeDashArray($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);

        $draw->setStrokeDashArray([10, 10]);
        $draw->rectangle(100, 50, 225, 175);

        $draw->setStrokeDashArray([20, 5, 20, 5, 5, 5,]);
        $draw->rectangle(275, 50, 400, 175);

        $draw->setStrokeDashArray([20, 5, 20, 5, 5]);
        $draw->rectangle(100, 200, 225, 350);

        $draw->setStrokeDashArray([1, 1, 1, 1, 2, 2, 3, 3, 5, 5, 8, 8, 13, 13, 21, 21, 34, 34, 55, 55, 89, 89, 144, 144, 233, 233, 377, 377, 610, 610, 987, 987, 1597, 1597, 2584, 2584, 4181, 4181,]);

        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashOffset — Spécifie la position dans le motif pour commencer le pointillé

### Description

public function ImagickDraw::setStrokeDashOffset(float `$dash_offset`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie la position dans le motif pour commencer le pointillé.

### Liste de paramètres

`dash_offset`

  La position de début du pointillé

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeDashOffset()

    <?php
    function setStrokeDashOffset($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);
        $draw->setStrokeDashArray([20, 20]);
        $draw->setStrokeDashOffset(0);
        $draw->rectangle(100, 50, 225, 175);

        //Start the dash effect halfway through the solid portion
        $draw->setStrokeDashOffset(10);
        $draw->rectangle(275, 50, 400, 175);

        //Start the dash effect on the space portion
        $draw->setStrokeDashOffset(20);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeDashOffset(5);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineCap — Spécifie la forme à utiliser à la fin des sous-chemins

### Description

public function ImagickDraw::setStrokeLineCap(int `$linecap`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie la forme à utiliser à la fin des sous-chemins.

### Liste de paramètres

`linecap`

  Une des constantes LINECAP (`imagick::LINECAP_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeLineCap()

    <?php
    function setStrokeLineCap($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(25);

        $lineTypes = [\Imagick::LINECAP_BUTT, \Imagick::LINECAP_ROUND, \Imagick::LINECAP_SQUARE,];

        $offset = 0;

        foreach ($lineTypes as $lineType) {
            $draw->setStrokeLineCap($lineType);
            $draw->line(50 + $offset, 50, 50 + $offset, 250);
            $offset += 50;
        }

        $imagick = new \Imagick();
        $imagick->newImage(300, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineJoin — Spécifie la forme à utiliser aux coins des chemins

### Description

public function ImagickDraw::setStrokeLineJoin(int `$linejoin`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie la forme à utiliser aux coins des chemins (ou d'autres formes vectorielles), quand ils utilisent un trait.

### Liste de paramètres

`linejoin`

  Une des constantes LINEJOIN (`imagick::LINEJOIN_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeLineJoin()

    <?php
    function setStrokeLineJoin($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(20);

        $offset = 220;

        $lineJoinStyle = [
            \Imagick::LINEJOIN_MITER,
            \Imagick::LINEJOIN_ROUND,
            \Imagick::LINEJOIN_BEVEL,
            ];

        for ($x = 0; $x < count($lineJoinStyle); $x++) {
            $draw->setStrokeLineJoin($lineJoinStyle[$x]);
            $points = [
                ['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
                ['x' => 20 * 5, 'y' => 20 * 5 + $x * $offset],
                ['x' => 70 * 5, 'y' => 50 * 5 + $x * $offset],
                ['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
            ];

            $draw->polyline($points);
        }

        $image = new \Imagick();
        $image->newImage(500, 700, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeMiterLimit — Spécifie la limite miter

### Description

public function ImagickDraw::setStrokeMiterLimit(int `$miterlimit`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie la limite miter. Lorsque deux lignes se rejoignent à angle aigu, et que la limite miter a été configurée à `"lineJoin"`, il est possible que le miter dépasse l'épaisseur de la ligne. La limite miter impose un ratio entre la longueur de miter et l'épaisseur de la ligne `"lineWidth"`.

### Liste de paramètres

`miterlimit`

  La limite miter

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeMiterLimit()

    <?php
    function setStrokeMiterLimit($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeOpacity(0.6);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(10);

        $yOffset = 100;

        $draw->setStrokeLineJoin(\Imagick::LINEJOIN_MITER);

        for ($y = 0; $y < 3; $y++) {

            $draw->setStrokeMiterLimit(40 * $y);

            $points = [
                ['x' => 22 * 3, 'y' => 15 * 4 + $y * $yOffset],
                ['x' => 20 * 3, 'y' => 20 * 4 + $y * $yOffset],
                ['x' => 70 * 5, 'y' => 45 * 4 + $y * $yOffset],
            ];

            $draw->polygon($points);
        }

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        $image->setImageType(\Imagick::IMGTYPE_PALETTE);
        $image->setImageCompressionQuality(100);
        $image->stripImage();

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeOpacity — Spécifie l'opacité pour dessiner les contours

### Description

public function ImagickDraw::setStrokeOpacity(float `$opacity`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie l'opacité pour dessiner les contours.

### Liste de paramètres

`opacity`

  L'opacité du trait. 1.0 est totalement opaque.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeOpacity()

    <?php
    function setStrokeOpacity($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(10);
        $draw->setStrokeOpacity(1);
        $draw->line(100, 80, 400, 125);
        $draw->rectangle(25, 200, 150, 350);
        $draw->setStrokeOpacity(0.5);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(200, 200, 325, 350);
        $draw->setStrokeOpacity(0.2);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(375, 200, 500, 350);

        $image = new \Imagick();
        $image->newImage(550, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokePatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokePatternURL — Configure le motif utilisé pour dessiner les contours

### Description

public function ImagickDraw::setStrokePatternURL(string `$stroke_url`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure le motif utilisé pour dessiner les contours.

### Liste de paramètres

`stroke_url`

  L'URL du motif du trait

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickDraw::setStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeWidth — Configure la largeur du trait pour dessiner les contours

### Description

public function ImagickDraw::setStrokeWidth(float `$width`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la largeur du trait pour dessiner les contours.

### Liste de paramètres

`width`

  La largeur du trait

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setStrokeWidth()

    <?php
    function setStrokeWidth($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeWidth(5);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAlignment — Spécifie l'alignement du texte

### Description

public function ImagickDraw::setTextAlignment(int `$align`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie l'alignement du texte à appliquer au texte d'une annotation.

### Liste de paramètres

`align`

  Une des constantes ALIGN (`imagick::ALIGN_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setTextAlignment()

    <?php
    function setTextAlignment($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(36);

        $draw->setTextAlignment(\Imagick::ALIGN_LEFT);
        $draw->annotation(250, 75, "Lorem Ipsum!");
        $draw->setTextAlignment(\Imagick::ALIGN_CENTER);
        $draw->annotation(250, 150, "Lorem Ipsum!");
        $draw->setTextAlignment(\Imagick::ALIGN_RIGHT);
        $draw->annotation(250, 225, "Lorem Ipsum!");
        $draw->line(250, 0, 250, 500);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAntialias — Contrôle l'anti-aliasing du texte

### Description

public function ImagickDraw::setTextAntialias(bool `$antialias`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Contrôle l'anti-aliasing du texte. Les textes sont anti-aliasés par défaut.

### Liste de paramètres

`antialias`

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setTextAntialias()

    <?php
    function setTextAntialias($fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor('none');
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(32);
        $draw->setTextAntialias(false);
        $draw->annotation(5, 30, "Lorem Ipsum!");
        $draw->setTextAntialias(true);
        $draw->annotation(5, 65, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(220, 80, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        //Scale the image so that people can see the aliasing.
        $imagick->scaleImage(220 * 6, 80 * 6);
        $imagick->cropImage(640, 480, 0, 0);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextDecoration — Spécifie les ornements de texte

### Description

public function ImagickDraw::setTextDecoration(int `$decoration`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie les ornements de texte utilisés pour les annotations.

### Liste de paramètres

`decoration`

  Une des constantes DECORATION (`imagick::DECORATION_*`).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setTextDecoration()

    <?php
    function setTextDecoration($strokeColor, $fillColor, $backgroundColor, $textDecoration) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->setTextDecoration($textDecoration);
        $draw->annotation(50, 75, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 200, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextEncoding — Spécifie le jeu de caractères

### Description

public function ImagickDraw::setTextEncoding(string `$encoding`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie le jeu de caractères à utiliser pour les annotations de texte. Le seul jeu de caractères qui peut être spécifié actuellement est "UTF-8", qui représente l'Unicode sous forme d'une séquence d'octets. Spécifier une chaîne vide pour utiliser le jeu de caractères du système. Le dessin des textes peut avoir besoin d'une police qui supporte Unicode.

### Liste de paramètres

`encoding`

  Le jeu de caractères

### Valeurs de retour

Aucune valeur n'est retournée.

# ImagickDraw::setTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setTextInterlineSpacing — Définit l'espace entre les lignes d'un texte

### Description

public function ImagickDraw::setTextInterlineSpacing(float `$spacing`): bool

Définit l'espace entre les lignes d'un texte.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`spacing`

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickDraw::setTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextInterwordSpacing — Définit l'espace entre les mots d'un texte

### Description

public function ImagickDraw::setTextInterwordSpacing(float `$spacing`): bool

Définit l'espace entre les mots d'un texte.

### Liste de paramètres

`spacing`

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickDraw::setTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextKerning — Définit le crénage d'un texte

### Description

public function ImagickDraw::setTextKerning(float `$kerning`): bool

Définit le crénage d'un texte.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`kerning`

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickDraw::setTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextUnderColor — Spécifie la couleur de fond d'un rectangle

### Description

public function ImagickDraw::setTextUnderColor(ImagickPixel|string `$under_color`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Spécifie la couleur de fond d'un rectangle à placer sous les textes.

### Liste de paramètres

`under_color`

  La couleur de fond

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setTextUnderColor()

    <?php
    function setTextUnderColor($strokeColor, $fillColor, $backgroundColor, $textUnderColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->annotation(50, 75, "Lorem Ipsum!");
        $draw->setTextUnderColor($textUnderColor);
        $draw->annotation(50, 175, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setVectorGraphics — Configure le vecteur graphique

### Description

public function ImagickDraw::setVectorGraphics(string `$xml`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure le vecteur graphique associé à l'objet ImagickDraw. Utiliser cette méthode avec ImagickDraw::getVectorGraphics(), pour faire persister l'état du vecteur graphique.

### Liste de paramètres

`xml`

  Code XML contenant le vecteur graphique

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setVectorGraphics()

    <?php
    function setVectorGraphics() {
        //Setup a draw object with some drawing in it.
        $draw = new \ImagickDraw();
        $draw->setFillColor("red");
        $draw->circle(20, 20, 50, 50);
        $draw->setFillColor("blue");
        $draw->circle(50, 70, 50, 50);
        $draw->rectangle(50, 120, 80, 150);

        //Get the drawing as a string
        $SVG = $draw->getVectorGraphics();

        //$svg is a string, and could be saved anywhere a string can be saved

        //Use the saved drawing to generate a new draw object
        $draw2 = new \ImagickDraw();
        //Apparently the SVG text is missing the root element.
        $draw2->setVectorGraphics("<root>".$SVG."</root>");

        $imagick = new \Imagick();
        $imagick->newImage(200, 200, 'white');
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw2);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setViewbox

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setViewbox — Configure la taille du canevas

### Description

public function ImagickDraw::setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Configure la taille du canevas général, à enregistrer avec les données vectorielles. Généralement, on configure cette valeur avec la même taille que l'image. Lorsque les données vectorielles sont sauvées en SVG ou MVG, la boîte de vue est utilisée pour spécifier la taille de l'image dans laquelle le visualiseur va dessiner les données.

### Liste de paramètres

`left_x`

  Abscisse gauche

`top_y`

  Ordonnée gauche

`right_x`

  Abscisse droite

`bottom_y`

  Ordonnée droite

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::setViewBox()

    <?php
    function setViewBox($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        /*

        Sets the overall canvas size to be recorded with the drawing vector data. Usually this will be specified using the same size as the canvas image. When the vector data is saved to SVG or MVG formats, the viewbox is use to specify the size of the canvas image that a viewer will render the vector data on.

         */

        $draw->circle(250, 250, 250, 0);
        $draw->setviewbox(0, 0, 200, 200);
        $draw->circle(125, 250, 250, 250);
        $draw->translate(250, 125);
        $draw->circle(0, 0, 125, 0);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::skewX

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewX — Biaise les coordonnées dans la direction horizontale

### Description

public function ImagickDraw::skewX(float `$degrees`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Biaise les coordonnées dans la direction horizontale.

### Liste de paramètres

`degrees`

  Degré de biaisage

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::skewX()

    <?php
    function skewX($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                   $startX, $startY, $endX, $endY, $skew) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);
        $draw->setFillColor($fillModifiedColor);
        $draw->skewX($skew);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::skewY

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewY — Incline les coordonnées dans la direction verticale

### Description

public function ImagickDraw::skewY(float `$degrees`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Incline les coordonnées dans la direction verticale.

### Liste de paramètres

`degrees`

  Le nombre de degrés d'inclinaison

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::skewY()

    <?php
    function skewY($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                   $startX, $startY, $endX, $endY, $skew) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);
        $draw->setFillColor($fillModifiedColor);
        $draw->skewY($skew);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::translate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::translate — Applique une translation

### Description

public function ImagickDraw::translate(float `$x`, float `$y`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Applique une translation au système de coordonnées actuel, qui déplace l'origine de ce système.

### Liste de paramètres

`x`

  Translation horizontale

`y`

  Translation verticale

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec ImagickDraw::translate()

    <?php
    function translate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                       $startX, $startY, $endX, $endY, $translateX, $translateY) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $draw->setFillColor($fillModifiedColor);
        $draw->translate($translateX, $translateY);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

## Sommaire

- ImagickDraw::affine — Ajuste la matrice de transformation affine courante
- ImagickDraw::annotation — Dessine un texte sur une image
- ImagickDraw::arc — Dessine un arc
- ImagickDraw::bezier — Dessine une courbe de Bézier
- ImagickDraw::circle — Dessine un cercle
- ImagickDraw::clear — Efface tout l'objet ImagickDraw
- ImagickDraw::clone — Fait une copie exacte de l'objet ImagickDraw
- ImagickDraw::color — Dessine une couleur sur une image
- ImagickDraw::comment — Ajoute un commentaire
- ImagickDraw::composite — Compose une image avec une autre
- ImagickDraw::__construct — Le constructeur ImagickDraw
- ImagickDraw::destroy — Libère toutes les ressources associées à un objet ImagickDraw
- ImagickDraw::ellipse — Dessine une ellipse sur une image
- ImagickDraw::getClipPath — Retourne l'identifiant du chemin courant
- ImagickDraw::getClipRule — Retourne la règle de remplissage courante pour les polygones
- ImagickDraw::getClipUnits — Retourne l'unité d'interprétation des chemins
- ImagickDraw::getFillColor — Retourne la couleur de remplissage
- ImagickDraw::getFillOpacity — Retourne l'opacité de dessin
- ImagickDraw::getFillRule — Retourne la règle de remplissage
- ImagickDraw::getFont — Retourne la police
- ImagickDraw::getFontFamily — Retourne la famille de police
- ImagickDraw::getFontSize — Retourne la taille de la police
- ImagickDraw::getFontStretch — Renvoie l'étirement de la police à utiliser lors de l'annotation avec du texte
- ImagickDraw::getFontStyle — Retourne le style de la police
- ImagickDraw::getFontWeight — Retourne le poids de la police
- ImagickDraw::getGravity — Retourne la gravité de placement de texte
- ImagickDraw::getStrokeAntialias — Retourne la configuration d'anti-aliasing de trait
- ImagickDraw::getStrokeColor — Retourne la couleur des contours d'objets
- ImagickDraw::getStrokeDashArray — Retourne un tableau représentant le motif de pointillés
- ImagickDraw::getStrokeDashOffset — Retourne l'offset du pointillé dans le motif
- ImagickDraw::getStrokeLineCap — Retourne la forme à utiliser pour dessiner les bouts de sous-chemins
- ImagickDraw::getStrokeLineJoin — Retourne la forme à utiliser pour dessiner les coins d'un chemin
- ImagickDraw::getStrokeMiterLimit — Retourne la 'miterLimit'
- ImagickDraw::getStrokeOpacity — Retourne l'opacité des contours d'un objet
- ImagickDraw::getStrokeWidth — Retourne la largeur du trait utilisé
- ImagickDraw::getTextAlignment — Retourne l'alignement du texte
- ImagickDraw::getTextAntialias — Retourne la configuration de l'anti-aliasing de texte
- ImagickDraw::getTextDecoration — Retourne la décoration du texte
- ImagickDraw::getTextEncoding — Retourne le jeu de caractères utilisé pour les annotations de texte
- ImagickDraw::getTextInterlineSpacing — Récupère l'espacement interlignes d'un texte.
- ImagickDraw::getTextInterwordSpacing — Récupère l'espace entre les mots d'un texte.
- ImagickDraw::getTextKerning — Récupère le crénage d'un texte.
- ImagickDraw::getTextUnderColor — Retourne la couleur sous le texte
- ImagickDraw::getVectorGraphics — Retourne une chaîne contenant le vecteur graphique
- ImagickDraw::line — Dessine une ligne
- ImagickDraw::matte — Dessine sur le canal d'opacité de l'image
- ImagickDraw::pathClose — Ajoute un élément de chemin au chemin courant
- ImagickDraw::pathCurveToAbsolute — Dessine une courbe de Bézier cubique, en coordonnées absolues
- ImagickDraw::pathCurveToQuadraticBezierAbsolute — Dessine une courbe de Bézier quadratique, en coordonnées absolues
- ImagickDraw::pathCurveToQuadraticBezierRelative — Dessine une courbe de Bézier quadratique, en coordonnées relatives
- ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Dessine une courbe de Bézier quadratique, en coordonnées absolues
- ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Dessine une courbe de Bézier quadratique, en coordonnées relatives
- ImagickDraw::pathCurveToRelative — Dessine une courbe de Bézier cubique, en coordonnées relatives
- ImagickDraw::pathCurveToSmoothAbsolute — Dessine une courbe de Bézier, en coordonnées absolues
- ImagickDraw::pathCurveToSmoothRelative — Dessine une courbe de Bézier, en coordonnées relatives
- ImagickDraw::pathEllipticArcAbsolute — Dessine un arc d'ellipse, en coordonnées absolues
- ImagickDraw::pathEllipticArcRelative — Dessine un arc d'ellipse, en coordonnées relatives
- ImagickDraw::pathFinish — Termine le chemin courant
- ImagickDraw::pathLineToAbsolute — Dessine une ligne de chemin, en coordonnées absolues
- ImagickDraw::pathLineToHorizontalAbsolute — Dessine une ligne de chemin horizontale, en coordonnées absolues
- ImagickDraw::pathLineToHorizontalRelative — Dessine une ligne de chemin horizontale, en coordonnées relatives
- ImagickDraw::pathLineToRelative — Dessine une ligne de chemin, en coordonnées relatives
- ImagickDraw::pathLineToVerticalAbsolute — Dessine une ligne de chemin verticale, en coordonnées absolues
- ImagickDraw::pathLineToVerticalRelative — Dessine une ligne de chemin verticale, en coordonnées relatives
- ImagickDraw::pathMoveToAbsolute — Commence un nouveau sous-chemin, en coordonnées absolues
- ImagickDraw::pathMoveToRelative — Commence un nouveau sous-chemin, en coordonnées relatives
- ImagickDraw::pathStart — Déclare le début d'un chemin de dessin
- ImagickDraw::point — Dessine un point
- ImagickDraw::polygon — Dessine un polygone
- ImagickDraw::polyline — Dessine une ligne brisée
- ImagickDraw::pop — Détruit l'objet ImagickDraw courant dans la pile, et retourne son précédent
- ImagickDraw::popClipPath — Termine la définition d'un chemin
- ImagickDraw::popDefs — Termine une définition de liste
- ImagickDraw::popPattern — Termine une définition de motif
- ImagickDraw::push — Clone l'objet ImagickDraw courant et le pousse dans la pile
- ImagickDraw::pushClipPath — Commence la définition d'un chemin
- ImagickDraw::pushDefs — Indique que la commande suivante crée des éléments nommés pour pré-traitement
- ImagickDraw::pushPattern — Configure un espace de dessin
- ImagickDraw::rectangle — Dessine un rectangle
- ImagickDraw::render — Effectue le rendu de tous les dessins à l'image
- ImagickDraw::resetVectorGraphics — Réinitialise les graphiques vectoriels
- ImagickDraw::rotate — Applique une rotation
- ImagickDraw::roundRectangle — Dessine un rectangle aux coins arrondis
- ImagickDraw::scale — Ajuste le facteur de mise à l'échelle
- ImagickDraw::setClipPath — Associe un chemin avec une image
- ImagickDraw::setClipRule — Configure la règle de remplissage du polygone à utiliser avec les chemins
- ImagickDraw::setClipUnits — Configure le mode d'interprétation des unités de chemin
- ImagickDraw::setFillAlpha — Configure l'opacité de la couleur de remplissage
- ImagickDraw::setFillColor — Configure la couleur de dessin des objets remplis
- ImagickDraw::setFillOpacity — Configure l'opacité à utiliser pour le remplissage
- ImagickDraw::setFillPatternURL — Configure l'URL du motif de remplissage des surfaces
- ImagickDraw::setFillRule — Configure la règle de remplissage des polygones
- ImagickDraw::setFont — Configure la police complète pour les textes
- ImagickDraw::setFontFamily — Configure la famille de police pour les textes
- ImagickDraw::setFontSize — Configure la taille de point pour les textes
- ImagickDraw::setFontStretch — Configure l'étirement du texte
- ImagickDraw::setFontStyle — Configure le style de police
- ImagickDraw::setFontWeight — Configure le poids de la police
- ImagickDraw::setGravity — Configure la gravité de placement de texte
- ImagickDraw::setResolution — Définit la résolution
- ImagickDraw::setStrokeAlpha — Spécifie l'opacité des contours d'objets
- ImagickDraw::setStrokeAntialias — Contrôle l'anti-aliasing des pointillés
- ImagickDraw::setStrokeColor — Configure la couleur utilisée pour dessiner les objets
- ImagickDraw::setStrokeDashArray — Spécifie le motif de pointillé
- ImagickDraw::setStrokeDashOffset — Spécifie la position dans le motif pour commencer le pointillé
- ImagickDraw::setStrokeLineCap — Spécifie la forme à utiliser à la fin des sous-chemins
- ImagickDraw::setStrokeLineJoin — Spécifie la forme à utiliser aux coins des chemins
- ImagickDraw::setStrokeMiterLimit — Spécifie la limite miter
- ImagickDraw::setStrokeOpacity — Spécifie l'opacité pour dessiner les contours
- ImagickDraw::setStrokePatternURL — Configure le motif utilisé pour dessiner les contours
- ImagickDraw::setStrokeWidth — Configure la largeur du trait pour dessiner les contours
- ImagickDraw::setTextAlignment — Spécifie l'alignement du texte
- ImagickDraw::setTextAntialias — Contrôle l'anti-aliasing du texte
- ImagickDraw::setTextDecoration — Spécifie les ornements de texte
- ImagickDraw::setTextEncoding — Spécifie le jeu de caractères
- ImagickDraw::setTextInterlineSpacing — Définit l'espace entre les lignes d'un texte
- ImagickDraw::setTextInterwordSpacing — Définit l'espace entre les mots d'un texte
- ImagickDraw::setTextKerning — Définit le crénage d'un texte
- ImagickDraw::setTextUnderColor — Spécifie la couleur de fond d'un rectangle
- ImagickDraw::setVectorGraphics — Configure le vecteur graphique
- ImagickDraw::setViewbox — Configure la taille du canevas
- ImagickDraw::skewX — Biaise les coordonnées dans la direction horizontale
- ImagickDraw::skewY — Incline les coordonnées dans la direction verticale
- ImagickDraw::translate — Applique une translation

# La classe ImagickDrawException

(PECL imagick 3)

## Introduction

## Synopsis de la classe

class ImagickDrawException extends Exception implements Throwable {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
/* Méthodes héritées */
}

# La classe ImagickException

(PECL imagick 3)

## Introduction

## Synopsis de la classe

class ImagickException extends Exception implements Throwable {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
/* Méthodes héritées */
}

# La classe ImagickKernel

(PECL imagick >= 3.3.0)

## Introduction

## Synopsis de la classe

class ImagickKernel {
/* Méthodes */
public function addKernel(ImagickKernel `$ImagickKernel`): void
public function addUnityKernel(float `$scale`): void
public static function fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel
public static function fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel
public function getMatrix(): array
public function scale(float `$scale`, int `$normalizeFlag` = ?): void
public function separate(): array
}

# ImagickKernel::addKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addKernel — Attache un autre noyau à une liste de noyaux

### Description

public function ImagickKernel::addKernel(ImagickKernel `$ImagickKernel`): void

Attache un autre noyau à ce noyau pour leur permettre d'être tous deux appliqués dans une seule fonction de morphologie ou de filtre. Renvoie le nouveau noyau combiné.

### Liste de paramètres

`ImagickKernel`

### Valeurs de retour

### Exemples

Exemple #1 ImagickKernel::addKernel()

    <?php
    function addKernel($imagePath) {
        $matrix1 = [
            [-1, -1, -1],
            [ 0,  0,  0],
            [ 1,  1,  1],
        ];

        $matrix2 = [
            [-1,  0,  1],
            [-1,  0,  1],
            [-1,  0,  1],
        ];

        $kernel1 = ImagickKernel::fromMatrix($matrix1);
        $kernel2 = ImagickKernel::fromMatrix($matrix2);
        $kernel1->addKernel($kernel2);

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->filter($kernel1);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickKernel::addUnityKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addUnityKernel — Ajoute un noyau Unity à la liste des noyaux

### Description

public function ImagickKernel::addUnityKernel(float `$scale`): void

Ajoute une quantité donnée du noyau de convolution 'Unity' au noyau de convolution pré-échelonné et normalisé donné. Cela a pour effet d'ajouter cette quantité de l'image d'origine dans le noyau de convolution résultant. L'effet résultant est de convertir les noyaux définis en flous doux mélangés, en noyaux non tranchants ou en noyaux de netteté.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 ImagickKernel::addUnityKernel()

    <?php

        function renderKernelTable($matrix) {
            $output = "<table class='infoTable'>";

            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output = "Before adding unity kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());
        $kernel->addUnityKernel(0.5);
        $output .= "After adding unity kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output .= "After renormalizing kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        echo $output;

    ?>

Exemple #2 ImagickKernel::addUnityKernel()

    <?php
    function addUnityKernel($imagePath) {

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = ImagickKernel::fromMatrix($matrix);

        $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
        $kernel->addUnityKernel(0.5);

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->filter($kernel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickKernel::fromBuiltIn

(PECL imagick >= 3.3.0)

ImagickKernel::fromBuiltIn — Crée un noyau à partir d'un noyau intégré

### Description

public static function ImagickKernel::fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel

Crée un noyau à partir d'un noyau intégré. Voir http://www.imagemagick.org/Usage/morphology/#kernel pour des exemples. Actuellement, les symboles de 'rotation' ne sont pas supportés. Exemple : $diamondKernel = ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "2");

### Liste de paramètres

`kerneltype`

  Le type de noyau à construire par exemple \Imagick::KERNEL_DIAMOND

`kernelString`

  Une chaîne qui décrit les paramètres par exemple "4,2.5"

### Valeurs de retour

### Exemples

Exemple #1 ImagickKernel::fromBuiltin()

    <?php

    function renderKernel(ImagickKernel $imagickKernel) {
        $matrix = $imagickKernel->getMatrix();

        $imageMargin = 20;

        $tileSize = 20;
        $tileSpace = 4;
        $shadowSigma = 4;
        $shadowDropX = 20;
        $shadowDropY = 0;

        $radius = ($tileSize / 2) * 0.9;

        $rows = count($matrix);
        $columns = count($matrix[0]);

        $imagickDraw = new \ImagickDraw();

        $imagickDraw->setFillColor('#afafaf');
        $imagickDraw->setStrokeColor('none');

        $imagickDraw->translate($imageMargin, $imageMargin);
        $imagickDraw->push();

        ksort($matrix);

        foreach ($matrix as $row) {
            ksort($row);
            $imagickDraw->push();
            foreach ($row as $cell) {
                if ($cell !== false) {
                    $color = intval(255 * $cell);
                    $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                    $imagickDraw->setFillColor($colorString);
                    $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
                }
                $imagickDraw->translate(($tileSize + $tileSpace), 0);
            }
            $imagickDraw->pop();
            $imagickDraw->translate(0, ($tileSize + $tileSpace));
        }

        $imagickDraw->pop();

        $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
        $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

        $imagickDraw->push();
        $imagickDraw->translate($width/2 , $height/2);
        $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
        $imagickDraw->setStrokeColor('white');
        $imagickDraw->circle(0, 0, $radius - 1, 0);
        $imagickDraw->setStrokeColor('black');
        $imagickDraw->circle(0, 0, $radius, 0);
        $imagickDraw->pop();

        $canvasWidth = $width + (2 * $imageMargin);
        $canvasHeight = $height + (2 * $imageMargin);

        $kernel = new \Imagick();
        $kernel->newPseudoImage(
            $canvasWidth,
            $canvasHeight,
            'canvas:none'
        );

        $kernel->setImageFormat('png');
        $kernel->drawImage($imagickDraw);

        /* créer une ombre portée sur sa propre couche */
        $canvas = $kernel->clone();
        $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
        $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

        $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
        $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

        /* composite original text_layer onto shadow_layer */
        $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
        $canvas->setImageFormat('png');

        return $canvas;
    }

    function createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
        $string = '';

        if ($kernelFirstTerm != false && strlen(trim($kernelFirstTerm)) != 0) {
            $string .= $kernelFirstTerm;

            if ($kernelSecondTerm != false && strlen(trim($kernelSecondTerm)) != 0) {
                $string .= ','.$kernelSecondTerm;
                if ($kernelThirdTerm != false && strlen(trim($kernelThirdTerm)) != 0) {
                    $string .= ','.$kernelThirdTerm;
                }
            }
        }

        $kernel = ImagickKernel::fromBuiltIn(
            $kernelType,
            $string
        );

        return $kernel;
    }

    function fromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
        $diamondKernel = createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm);
        $imagick = renderKernel($diamondKernel);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    fromBuiltin(\Imagick::KERNEL_DIAMOND, 2, false, false);

    ?>

# ImagickKernel::fromMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::fromMatrix — Créer un noyau à partir d'une matrice 2D de valeurs

### Description

public static function ImagickKernel::fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel

Crée un noyau à partir d'une matrice 2D de valeurs. Chaque valeur doit être soit un flottant (si l'élément doit être utilisé) ou 'false' si l'élément doit être ignoré. Pour les matrices qui ont des tailles impaires dans les deux dimensions, le pixel d'origine sera par défaut au centre du noyau. Pour toutes les autres tailles de noyau, le pixel d'origine doit être spécifié.

### Liste de paramètres

`array`

  Une matrice (c'est-à-dire un tableau 2D) de valeurs qui définissent le noyau. Chaque élément doit être soit une valeur flottante, ou FALSE si cet élément ne doit pas être utilisé par le noyau.

`array`

  Quel élément du noyau doit être utilisé comme pixel d'origine. Par exemple, pour une matrice 3x3 spécifiant l'origine comme [2, 2] spécifierait que l'élément en bas à droite devrait être le pixel d'origine.

### Valeurs de retour

L'objet ImagickKernel généré.

### Exemples

Exemple #1 ImagickKernel::fromMatrix()

    <?php

    function renderKernel(ImagickKernel $imagickKernel) {
        $matrix = $imagickKernel->getMatrix();

        $imageMargin = 20;

        $tileSize = 20;
        $tileSpace = 4;
        $shadowSigma = 4;
        $shadowDropX = 20;
        $shadowDropY = 0;

        $radius = ($tileSize / 2) * 0.9;

        $rows = count($matrix);
        $columns = count($matrix[0]);

        $imagickDraw = new \ImagickDraw();

        $imagickDraw->setFillColor('#afafaf');
        $imagickDraw->setStrokeColor('none');

        $imagickDraw->translate($imageMargin, $imageMargin);
        $imagickDraw->push();

        ksort($matrix);

        foreach ($matrix as $row) {
            ksort($row);
            $imagickDraw->push();
            foreach ($row as $cell) {
                if ($cell !== false) {
                    $color = intval(255 * $cell);
                    $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                    $imagickDraw->setFillColor($colorString);
                    $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
                }
                $imagickDraw->translate(($tileSize + $tileSpace), 0);
            }
            $imagickDraw->pop();
            $imagickDraw->translate(0, ($tileSize + $tileSpace));
        }

        $imagickDraw->pop();

        $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
        $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

        $imagickDraw->push();
        $imagickDraw->translate($width/2 , $height/2);
        $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
        $imagickDraw->setStrokeColor('white');
        $imagickDraw->circle(0, 0, $radius - 1, 0);
        $imagickDraw->setStrokeColor('black');
        $imagickDraw->circle(0, 0, $radius, 0);
        $imagickDraw->pop();

        $canvasWidth = $width + (2 * $imageMargin);
        $canvasHeight = $height + (2 * $imageMargin);

        $kernel = new \Imagick();
        $kernel->newPseudoImage(
            $canvasWidth,
            $canvasHeight,
            'canvas:none'
        );

        $kernel->setImageFormat('png');
        $kernel->drawImage($imagickDraw);

        /* créer une ombre portée sur sa propre couche */
        $canvas = $kernel->clone();
        $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
        $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

        $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
        $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

        /* composite original text_layer onto shadow_layer */
        $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
        $canvas->setImageFormat('png');

        return $canvas;
    }

    function createFromMatrix() {
        $matrix = [
            [0.5, 0, 0.2],
            [0, 1, 0],
            [0.9, 0, false],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);

        return $kernel;
    }

    function fromMatrix() {
        $kernel = createFromMatrix();
        $imagick = renderKernel($kernel);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickKernel::getMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::getMatrix — Renvoie la matrice 2D des valeurs utilisées dans ce noyau

### Description

public function ImagickKernel::getMatrix(): array

Renvoie la matrice 2D des valeurs utilisées dans ce noyau. Les éléments sont soit des flottants pour les éléments qui sont utilisés, soit 'false' si l'élément doit être ignoré.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Une matrice (tableau 2D) des valeurs qui représentent le noyau.

### Exemples

Exemple #1 ImagickKernel::getMatrix()

    <?php

    function renderKernelTable($matrix) {
        $output = "<table class='infoTable'>";

        foreach ($matrix as $row) {
            $output .= "<tr>";
            foreach ($row as $cell) {
                $output .= "<td style='text-align:left'>";
                if ($cell === false) {
                    $output .= "false";
                }
                else {
                    $output .= round($cell, 3);
                }
                $output .= "</td>";
            }
            $output .= "</tr>";
        }

        $output .= "</table>";

        return $output;
    }

        $output = "The built-in kernel name 'ring' with parameters of '2,3.5':<br/>";
        $kernel = \ImagickKernel::fromBuiltIn(
            \Imagick::KERNEL_RING,
            "2,3.5"
        );
        $matrix = $kernel->getMatrix();
        $output .= renderKernelTable($matrix);

        echo $output;

    ?>

# ImagickKernel::scale

(PECL imagick >= 3.3.0)

ImagickKernel::scale — Dimensionne une liste de noyaux par la quantité donnée

### Description

public function ImagickKernel::scale(float `$scale`, int `$normalizeFlag` = ?): void

Dimensionne la liste de noyaux donnée par la quantité donnée, avec ou sans normalisation de la somme des valeurs du noyau (selon les indicateurs donnés). Le comportement exact de cette fonction dépend du type de normalisation utilisé. Veuillez consulter http://www.imagemagick.org/api/morphology.php#ScaleKernelInfo pour plus de détails.

### Liste de paramètres

`scale`

`normalizeFlag`

  - Imagick::NORMALIZE_KERNEL_NONE
  - Imagick::NORMALIZE_KERNEL_VALUE
  - Imagick::NORMALIZE_KERNEL_CORRELATE
  - Imagick::NORMALIZE_KERNEL_PERCENT

### Valeurs de retour

### Exemples

Exemple #1 ImagickKernel::scale()

    <?php

        function renderKernelTable($matrix) {
            $output = "<table class='infoTable'>";

            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $output = "";

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernelClone = clone $kernel;

        $output .= "Start kernel<br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        $output .= "Scaling with NORMALIZE_KERNEL_VALUE. The  <br/>";
        $kernel->scale(2, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output .= renderKernelTable($kernel->getMatrix());

        $kernel = clone $kernelClone;
        $output .= "Scaling by percent<br/>";
        $kernel->scale(2, \Imagick::NORMALIZE_KERNEL_PERCENT);
        $output .= renderKernelTable($kernel->getMatrix());

        $matrix2 = [
            [-1, -1, 1],
            [ -1, false,  1],
            [1, 1, 1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix2);
        $output .= "Scaling by correlate<br/>";
        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_CORRELATE);
        $output .= renderKernelTable($kernel->getMatrix());

        return $output;
    ?>

# ImagickKernel::separate

(PECL imagick >= 3.3.0)

ImagickKernel::separate — Sépare un ensemble de noyaux liés et renvoie un tableau d'ImagickKernels

### Description

public function ImagickKernel::separate(): array

Sépare un ensemble de noyaux liés et renvoie un tableau d'ImagickKernels.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

### Exemples

Exemple #1 ImagickKernel::separate()

    <?php

        function renderKernelTable($matrix) {

            $output = "<table class='infoTable'>";
            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
        $diamondKernel = \ImagickKernel::fromBuiltIn(
            \Imagick::KERNEL_DIAMOND,
            "2"
        );

        $kernel->addKernel($diamondKernel);

        $kernelList = $kernel->separate();

        $output = '';
        $count = 0;
        foreach ($kernelList as $kernel) {
            $output .= "<br/>Kernel $count<br/>";
            $output .= renderKernelTable($kernel->getMatrix());
            $count++;
        }

        return $output;

    ?>

## Sommaire

- ImagickKernel::addKernel — Attache un autre noyau à une liste de noyaux
- ImagickKernel::addUnityKernel — Ajoute un noyau Unity à la liste des noyaux
- ImagickKernel::fromBuiltIn — Crée un noyau à partir d'un noyau intégré
- ImagickKernel::fromMatrix — Créer un noyau à partir d'une matrice 2D de valeurs
- ImagickKernel::getMatrix — Renvoie la matrice 2D des valeurs utilisées dans ce noyau
- ImagickKernel::scale — Dimensionne une liste de noyaux par la quantité donnée
- ImagickKernel::separate — Sépare un ensemble de noyaux liés et renvoie un tableau d'ImagickKernels

# La classe ImagickKernelException

(PECL imagick 3)

## Introduction

## Synopsis de la classe

class ImagickKernelException extends Exception {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
/* Méthodes héritées */
}

# La classe ImagickPixel

(PECL imagick 2, PECL imagick 3)

## Synopsis de la classe

class ImagickPixel {
public function clear(): bool
public function __construct(string `$color` = ?)
public function destroy(): bool
public function getColor(int `$normalized` = 0): array
public function getColorAsString(): string
public function getColorCount(): int
public function getColorQuantum(): array
public function getColorValue(int `$color`): float
public function getColorValueQuantum(int `$color`): int|float
public function getHSL(): array
public function getIndex(): int
public function isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool
public function isSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function setColor(string `$color`): bool
public function setcolorcount(int `$colorCount`): bool
public function setColorValue(int `$color`, float `$value`): bool
public function setColorValueQuantum(int `$color`, int|float `$value`): bool
public function setHSL(float `$hue`, float `$saturation`, float `$luminosity`): bool
public function setIndex(int `$index`): bool
}

# ImagickPixel::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixel::clear — Supprime toutes les ressources associées avec l'objet

### Description

public function ImagickPixel::clear(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Supprime l'objet ImagickPixel, le laissant dans un statut initial. Supprime également toutes les couleurs associées avec l'objet.

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickPixel::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixel::__construct — Le constructeur ImagickPixel

### Description

public function ImagickPixel::__construct(string `$color` = ?)
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Construit un objet ImagickPixel. Si une couleur est spécifiée, l'objet est construit, puis initialisé avec cette couleur avant d'être retourné.

### Liste de paramètres

`color`

  Une chaîne représentant la couleur optionnelle à utiliser comme valeur initiale de l'objet.

### Valeurs de retour

Retourne un objet ImagickPixel en cas de succès ou lance une exception ImagickPixelException si une erreur survient.

### Exemples

Exemple #1 Exemple avec ImagickPixel::construct()

    <?php
    function construct() {

        $columns = 4;

        $exampleColors = array(
            "rgba(100%, 0%, 0%, 0.5)",
            "hsb(33.3333%, 100%,  75%)", // vert moyen
            "hsl(120, 255,   191.25)", //vert moyen
            "graya(50%, 0.5)", //  gris moyen, semi-transparent
            "LightCoral", "none", //"cmyk(0.9, 0.48, 0.83, 0.50)",
            "#f00", //  #rgb
            "#ff0000", //  #rrggbb
            "#ff0000ff", //  #rrggbbaa
            "#ffff00000000", //  #rrrrggggbbbb
            "#ffff00000000ffff", //  #rrrrggggbbbbaaaa
            "rgb(255, 0, 0)", //  un entier dans l'intervalle 0—255 pour chaque composant
            "rgb(100.0%, 0.0%, 0.0%)", //  un nombre à virgule flottante, dans l'intervalle 0-100% pour chaque composant
            "rgb(255, 0, 0)", //  intervalle 0 - 255
            "rgba(255, 0, 0, 1.0)", //  pareil, mais avec une valeur alpha explicite
            "rgb(100%, 0%, 0%)", //  intervalle 0.0% - 100.0%
            "rgba(100%, 0%, 0%, 1.0)", //  pareil, mais avec une valeur alpha explicite
        );

        $draw = new \ImagickDraw();
        $count = 0;
        $black = new \ImagickPixel('rgb(0, 0, 0)');

        foreach ($exampleColors as $exampleColor) {
            $color = new \ImagickPixel($exampleColor);

            $draw->setstrokewidth(1.0);
            $draw->setStrokeColor($black);
            $draw->setFillColor($color);
            $offsetX = ($count % $columns) * 50 + 5;
            $offsetY = intval($count / $columns) * 50 + 5;
            $draw->rectangle(0 + $offsetX, 0 + $offsetY, 40 + $offsetX, 40 + $offsetY);
            $count++;
        }

        $image = new \Imagick();
        $image->newImage(350, 350, "blue");
        $image->setImageFormat("png");
        $image->drawImage($draw);
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixel::destroy — Libère les ressources associées avec l'objet

### Description

public function ImagickPixel::destroy(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Libère toutes les ressources utilisées par l'objet ImagickPixel et supprime toutes les couleurs associées. L'objet ne doit pas être utilisé après l'appel de cette fonction.

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickPixel::getColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColor — Retourne la couleur

### Description

public function ImagickPixel::getColor(int `$normalized` = 0): array

Retourne la couleur décrite par l'objet ImagickPixel, sous la forme d'un tableau. Si la couleur contient un canal d'opacité, il sera fourni comme quatrième valeur de la liste.

### Liste de paramètres

`normalized`

  Normalise les valeurs de couleurs. Les valeurs possibles sont `0`, `1` ou `2`.

  Liste des valeurs possibles pour `normalized`
  `normalized` | Description
  --- | ---
  `0` | Les valeurs RGB sont retournées en tant que ints dans l'intervalle (inclusive) `0` à `255`. La valeur alpha est retournée en tant que int et est soit `0` ou `1`.
  `1` | Les valeurs RGBA sont retournées en tant que floats dans l'intervalle (inclusive) `0` à `1`.
  `2` | Les valeurs RGBA sont retournées en tant que ints dans l'intervalle (inclusive) `0` à `255`.

### Valeurs de retour

Un tableau des valeurs des canaux. Lance ImagickPixelException en cas d'erreur.

### Exemples

Exemple #1 Utilisation simple de la méthode Imagick::getColor()

    <?php

    // Crée un objet ImagickPixel avec comme couleur prédéfinie 'marron'
    $color = new ImagickPixel('brown');

    // Définit la couleur pour avoir un canal alpha de 25%
    $color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

    $colorInfo = $color->getColor();

    echo "Valeurs standards :".PHP_EOL;
    print_r($colorInfo);

    $colorInfo = $color->getColor(1);

    echo "Valeurs normalisées :".PHP_EOL;
    print_r($colorInfo);

    ?>

L'exemple ci-dessus va afficher :

    Valeurs standards :
    Array
    (
        [r] => 165
        [g] => 42
        [b] => 42
        [a] => 0
    )
    Valeurs normalisées :
    Array
    (
        [r] => 0.64705882352941
        [g] => 0.16470588235294
        [b] => 0.16470588235294
        [a] => 0.25000381475547
    )

# ImagickPixel::getColorAsString

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

ImagickPixel::getColorAsString — Retourne une couleur

### Description

public function ImagickPixel::getColorAsString(): string

Retourne la couleur de l'objet ImagickPixel, sous la forme d'une chaîne de caractères.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la couleur de l'objet ImagickPixel, sous la forme d'une chaîne de caractères.

### Exemples

Exemple #1 Utilisation basique de la méthode Imagick::getColorAsString()

    <?php

    //Crée un objet ImagickPixel avec comme couleur prédéfinie le 'marron'
    $color = new ImagickPixel('brown');

    $color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

    $colorInfo = $color->getColorAsString();

    print_r($colorInfo);
    ?>

L'exemple ci-dessus va afficher :

    rgb(165,42,42)

### Notes

> Note: Alpha non retourné

> Cette méthode ne retourne pas la valeur de l'alpha de la couleur dans la chaîne.

# ImagickPixel::getColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorCount — Retourne le nombre de couleurs associé avec une couleur

### Description

public function ImagickPixel::getColorCount(): int

Retourne le nombre de couleurs associé avec la couleur.

Le nombre de pixels de l'image ayant la même couleur que ce ImagickPixel.

ImagickPixel::getColorCount semble fonctionner uniquement pour les objets ImagickPixel créés via Imagick::getImageHistogram()

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le nombre de couleurs, sous la forme d'un entier en cas de succès ou lance une exception ImagickPixelException si une erreur survient.

### Exemples

Exemple #1 ImagickPixel getColorCount()

    <?php
        $imagick = new \Imagick();
        $imagick->newPseudoImage(640, 480, "magick:logo");
        $histogramElements = $imagick->getImageHistogram();
        $lastColor = array_pop($histogramElements);
        echo "Last pixel color count is: ".$lastColor->getColorCount();
    ?>

La sortie sera similaire à :

    Last pixel color count is: 256244

# ImagickPixel::getColorQuantum

(No version information available, might only be in Git)

ImagickPixel::getColorQuantum — Renvoie la couleur du pixel dans un tableau en tant que valeurs quantiques

### Description

public function ImagickPixel::getColorQuantum(): array

Renvoie la couleur du pixel dans un tableau en tant que valeurs quantiques. Si ImageMagick a été compilé en tant que HDRI, ces valeurs seront des flottants, sinon elles seront des entiers.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un tableau avec les clés `"r"`, `"g"`, `"b"`, `"a"`.

# ImagickPixel::getColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorValue — Récupère la valeur normalisée du canal de la couleur fournie

### Description

public function ImagickPixel::getColorValue(int `$color`): float

Récupère la valeur du canal de la couleur spécifiée, sous la forme d'un nombre à virgule flottante compris entre 0 et 1.

### Liste de paramètres

`color`

  La couleur pour laquelle la valeur sera récupérée, spécifiée sous forme de constante de couleurs Imagick. Peut être des couleurs RGB, des couleurs CMYK, alpha et opacité, c.-à-d. Imagick::COLOR_BLUE ou Imagick::COLOR_MAGENTA.

### Valeurs de retour

La valeur du canal, sous la forme d'un nombre à virgule flottante normalisé, ou lance une exception ImagickPixelException si une erreur survient.

### Exemples

Exemple #1 Utilisation basique de la méthode Imagick::getColorValue()

    <?php

    $color = new ImagickPixel('rgba(90%, 20%, 20%, 0.75)');

    echo "La valeur alpha est ".$color->getColorValue(Imagick::COLOR_ALPHA).PHP_EOL;
    echo "".PHP_EOL;
    echo "La valeur rouge est ".$color->getColorValue(Imagick::COLOR_RED).PHP_EOL;
    echo "La valeur verte est ".$color->getColorValue(Imagick::COLOR_GREEN).PHP_EOL;
    echo "La valeur bleue est ".$color->getColorValue(Imagick::COLOR_BLUE).PHP_EOL;
    echo "".PHP_EOL;
    echo "La valeur Cyan est ".$color->getColorValue(Imagick::COLOR_CYAN).PHP_EOL;
    echo "La valeur Magenta est ".$color->getColorValue(Imagick::COLOR_MAGENTA).PHP_EOL;
    echo "La valeur jaune est ".$color->getColorValue(Imagick::COLOR_YELLOW).PHP_EOL;
    echo "La valeur noire est ".$color->getColorValue(Imagick::COLOR_BLACK).PHP_EOL;

    ?>

L'exemple ci-dessus va afficher :

    La valeur alpha est 0.74999618524453

    La valeur rouge est 0.90000762951095
    La valeur verte est 0.2
    La valeur bleue est 0.2

    La valeur Cyan est 0.90000762951095
    La valeur Magenta est 0.2
    La valeur jaune est 0.2
    La valeur noire est 0

# ImagickPixel::getColorValueQuantum

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getColorValueQuantum — Renvoie la valeur quantique d'une couleur dans ImagickPixel

### Description

public function ImagickPixel::getColorValueQuantum(int `$color`): int|float

Renvoie la valeur quantique d'une couleur dans ImagickPixel. La valeur de retour est un flottant si ImageMagick a été compilé avec HDRI, sinon un entier.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La valeur quantique de l'élément de couleur. Flottant si ImageMagick a été compilé avec HDRI, sinon un entier.

### Exemples

Exemple #1 ImagickPixel::getColorValueQuantum()

    <?php
            $color = new \ImagickPixel('rgb(128, 5, 255)');
            $colorRed = $color->getColorValueQuantum(\Imagick::COLOR_RED);
            $colorGreen = $color->getColorValueQuantum(\Imagick::COLOR_GREEN);
            $colorBlue = $color->getColorValueQuantum(\Imagick::COLOR_BLUE);
            $colorAlpha = $color->getColorValueQuantum(\Imagick::COLOR_ALPHA);

            printf(
                "Red: %s Green: %s  Blue %s Alpha: %s",
                $colorRed,
                $colorGreen,
                $colorBlue,
                $colorAlpha
            );

    ?>

# ImagickPixel::getHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getHSL — Retourne la couleur HSL normalisée de l'objet ImagickPixel

### Description

public function ImagickPixel::getHSL(): array

Retourne la couleur HSL normalisée, décrite par l'objet ImagickPixel, dont chacune des trois valeurs sera un nombre décimal, compris entre 0.0 et 1.0.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne la valeur HSL dans un tableau contenant les clés `"hue"`, `"saturation"` et `"luminosity"`. Lance une exception ImagickPixelException si une erreur survient.

### Exemples

Exemple #1 Exemple avec Imagick::getHSL()

    <?php

    $color = new ImagickPixel('rgb(90%, 10%, 10%)');

    $colorInfo = $color->getHSL();

    print_r($colorInfo);

    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [hue] => 0
        [saturation] => 0.80001220740379
        [luminosity] => 0.50000762951095
    )

### Notes

> Note:

> Disponible avec la version 6.2.9 et supérieure de la bibliothèque ImageMagick.

# ImagickPixel::getIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getIndex — Renvoie l'index de la carte de couleurs du pixel

### Description

public function ImagickPixel::getIndex(): int

Renvoie l'index de la carte de couleurs du pixel.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

# ImagickPixel::isPixelSimilar

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilar — Vérifie la distance entre cette couleur et une autre

### Description

public function ImagickPixel::isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool

Vérifie la distance entre la couleur décrite par cet objet ImagickPixel et celle de l'objet fourni. Si la distance entre les deux points est inférieure à la valeur du paramètre fuzz fourni, la couleur est similaire. Cette méthode remplace la méthode ImagickPixel::isSimilar() et normalise correctement la valeur fuzz d'ImageMagick QuantumRange.

### Liste de paramètres

`color`

  L'objet ImagickPixel à utiliser pour la comparaison.

`fuzz`

  La distance maximale pour laquelle on considère les couleurs comme similaires. La valeur maximale théorique pour cette valeur est la racine carrée de trois (1.732).

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickPixel::isPixelSimilarQuantum

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilarQuantum — Renvoie si deux couleurs diffèrent de moins de la distance spécifiée

### Description

public function ImagickPixel::isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool

Renvoie si deux couleurs diffèrent de moins de la distance spécifiée. La valeur de flou doit être comprise entre 0 et QuantumRange. La valeur maximale représente la distance la plus longue possible dans l'espace colorimétrique. par exemple de RGB(0, 0, 0) à RGB(255, 255, 255) pour l'espace colorimétrique RGB

### Liste de paramètres

`color`

`fuzz`

### Valeurs de retour

# ImagickPixel::isSimilar

(PECL imagick 2, PECL imagick 3)

ImagickPixel::isSimilar — Vérifie la distance entre 2 couleurs

### Description

public function ImagickPixel::isSimilar(ImagickPixel `$color`, float `$fuzz`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Vérifie la distance entre la couleur décrite par l'objet ImagickPixel et celle de l'objet fourni, en plaçant leurs valeurs RGB sur le cube de couleur. Si la distance entre les 2 points est inférieure à la valeur du paramètre `fuzz`, la couleur est similaire. Obsolète en faveur de la méthode ImagickPixel::isPixelSimilar().

### Liste de paramètres

`color`

  L'objet ImagickPixel utilisé pour la comparaison.

`fuzz`

  La distance maximale utilisée pour considérer que les couleurs sont similaires. La valeur maximale théorique est la racine carrée de 3 (1.732).

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickPixel::isSimilar()

    <?php
            // Le test ci-dessous a été écrit avec une distance maximale de 255,
            // aussi, nous devons le mettre à l'échelle avec une racine carrée de 3 -
            // la longueur de la diagonale d'un cube.
            $root3 = 1.732050807568877;

            $tests = array(
                ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',   9 / $root3,         false,],
                ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',  10 / $root3,         true,],
                ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',     9 / $root3,         false,],
                ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',    10 / $root3,         true,],
                ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)', 9 / $root3,         false,],
                ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)',    10 / $root3,     true,],
                ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   7 / $root3,     false,],
                ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   8 / $root3,     true,],
                ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   254.9,          false,],
                ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   255,            true,],
                ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     254.9,          false,],
                ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     255,            true,],
                ['black',               'rgba(0, 0, 0)',        0.0,            true],
                ['black',               'rgba(10, 0, 0, 1.0)',  10.0 / $root3,  true],);

            $output = "<table width='100%' class='infoTable'><thead>
                    <tr>
                    <th>
                    Color 1
                    </th>
                    <th>
                    Color 2
                    </th>
                    <th>
                        Test distance * 255
                    </th>
                    <th>
                        Is within distance
                    </th>
                    </tr>
            </thead>";

            $output .= "<tbody>";

            foreach ($tests as $testInfo) {
                $color1 = $testInfo[0];
                $color2 = $testInfo[1];
                $distance = $testInfo[2];
                $expectation = $testInfo[3];
                $testDistance = ($distance / 255.0);

                $color1Pixel = new \ImagickPixel($color1);
                $color2Pixel = new \ImagickPixel($color2);

                $isSimilar = $color1Pixel->isPixelSimilar($color2Pixel, $testDistance);

                if ($isSimilar !== $expectation) {
                    echo "Test distance failed. Color [$color1] compared to color [$color2] is not within distance $testDistance FAILED.".NL;
                }

                $layout = "<tr>
                    <td>%s</td>
                    <td>%s</td>
                    <td>%s</td>
                    <td style='text-align: center;'>%s</td>
                </tr>";

                $output .= sprintf(
                    $layout,
                    $color1,
                    $color2,
                    $distance,
                    $isSimilar ? 'yes' : 'no'
                );
            }

            $output .= "</tbody></table>";

            return $output;

    ?>

# ImagickPixel::setColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColor — Définit la couleur

### Description

public function ImagickPixel::setColor(string `$color`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Définit la couleur, décrite par l'objet ImagickPixel, avec une chaîne de caractères (p. ex. `"blue"`, `"#0000ff"`, `"rgb(0,0,255)"`, `"cmyk(100,100,100,10)"`, etc.).

### Liste de paramètres

`color`

  La définition de la couleur à utiliser afin d'initialiser l'objet ImagickPixel.

### Valeurs de retour

Retourne `true` si la couleur spécifiée a été définie ou `false` sinon.

### Exemples

Exemple #1 Exemple avec ImagickPixel::setColor()

    <?php
    function setColor() {
        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel('green');
        $fillColor = new \ImagickPixel();
        $fillColor->setColor('rgba(100%, 75%, 0%, 1.0)');

        $draw->setstrokewidth(3.0);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, "SteelBlue2");
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::setColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorCount — Définit la quantité de couleurs associée à ce pixel

### Description

public function ImagickPixel::setcolorcount(int `$colorCount`): bool

Définit la quantité de couleurs associée à ce pixel.

### Liste de paramètres

`colorCount`

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickPixel::setColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorValue — Définit la valeur normalisée d'un des canaux

### Description

public function ImagickPixel::setColorValue(int `$color`, float `$value`): bool

Définit la valeur du canal spécifié de l'objet à la valeur spécifiée, qui doit être comprise entre 0 et 1. Cette fonction peut être utilisée pour fournir un canal d'opacité à l'objet ImagickPixel.

### Liste de paramètres

`color`

  Une constante de couleur Imagick, c.-à-d. \Imagick::COLOR_GREEN ou \Imagick::COLOR_ALPHA.

`value`

  La valeur à définir pour ce canal, comprise entre 0 et 1.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec Imagick::setColorValue()

    <?php

    $color  = new \ImagickPixel('firebrick');

    $color->setColorValue(Imagick::COLOR_ALPHA, 0.5);

    print_r($color->getcolor(true));
    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [r] => 0.69803921568627
        [g] => 0.13333333333333
        [b] => 0.13333333333333
        [a] => 0.50000762951095
    )

# ImagickPixel::setColorValueQuantum

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickPixel::setColorValueQuantum — Définit la valeur quantique d'un élément de couleur de ImagickPixel

### Description

public function ImagickPixel::setColorValueQuantum(int `$color`, int|float `$value`): bool

Définit la valeur quantique d'un élément de couleur de ImagickPixel.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`color`

  Quelle couleur définir, par exemple \Imagick::COLOR_GREEN.

`value`

  La valeur quantique à définir pour l'élément de couleur. Cela devrait être un flottant si ImageMagick a été compilé avec HDRI, sinon un entier dans la plage 0 à Imagick::getQuantum().

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 ImagickPixel::setColorValueQuantum()

    <?php
    function setColorValueQuantum() {
        $image = new \Imagick();

        $quantumRange = $image->getQuantumRange();

        $draw = new \ImagickDraw();
        $color = new \ImagickPixel('blue');
        $color->setcolorValueQuantum(\Imagick::COLOR_RED, 128 * $quantumRange['quantumRangeLong'] / 256);

        $draw->setstrokewidth(1.0);
        $draw->setStrokeColor($color);
        $draw->setFillColor($color);
        $draw->rectangle(200, 200, 300, 300);

        $image->newImage(500, 500, "SteelBlue2");
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::setHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setHSL — Définit la couleur HSL normalisée

### Description

public function ImagickPixel::setHSL(float `$hue`, float `$saturation`, float `$luminosity`): bool

Définit la couleur décrite par l'objet ImagickPixel en utilisant les valeurs normalisées pour la teinte, la saturation et la luminosité.

### Liste de paramètres

`hue`

  La valeur normalisée pour la teinte, décrite par un arc fractionnel (entre 0 et 1) du cercle des teintes, dont la valeur zéro correspond à rouge.

`saturation`

  La valeur normalisée pour la saturation, dont 1 correspond à une saturation complète.

`luminosity`

  La valeur normalisée pour la luminosité, comprise entre 0 (noir) et 1 (blanc), avec la valeur HS complète à 0.5 de luminosité.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickPixel::setHSL() pour modifier une couleur

    <?php

    // Crée un rouge pure
    $color = new ImagickPixel('rgb(90%, 10%, 10%)');

    // Récupère ses valeurs HSL
    $colorInfo = $color->getHSL();

    // Effectue une rotation de la teinte de 180 degrés
    $newHue = $colorInfo['hue'] + 0.5;
    if ($newHue > 1) {
        $newHue = $newHue - 1;
    }

    // Définit l'objet ImagickPixel à la nouvelle couleur
    $colorInfo = $color->setHSL($newHue, $colorInfo['saturation'], $colorInfo['luminosity']);

    // Vérifie que la nouvelle couleur est bien bleu/verte
    $colorInfo = $color->getcolor();
    print_r($colorInfo);

    ?>

L'exemple ci-dessus va afficher :

    Array
    (
        [r] => 26
        [g] => 230
        [b] => 230
        [a] => 255
    )

### Notes

> Note:

> Disponible avec la version 6.2.9 et supérieure de la bibliothèque ImageMagick.

# ImagickPixel::setIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::setIndex — Définit l'index de la carte de couleurs du pixel

### Description

public function ImagickPixel::setIndex(int `$index`): bool

Définit l'index de la carte de couleurs du pixel.

### Liste de paramètres

`index`

### Valeurs de retour

Retourne `true` en cas de succès.

## Sommaire

- ImagickPixel::clear — Supprime toutes les ressources associées avec l'objet
- ImagickPixel::__construct — Le constructeur ImagickPixel
- ImagickPixel::destroy — Libère les ressources associées avec l'objet
- ImagickPixel::getColor — Retourne la couleur
- ImagickPixel::getColorAsString — Retourne une couleur
- ImagickPixel::getColorCount — Retourne le nombre de couleurs associé avec une couleur
- ImagickPixel::getColorQuantum — Renvoie la couleur du pixel dans un tableau en tant que valeurs quantiques
- ImagickPixel::getColorValue — Récupère la valeur normalisée du canal de la couleur fournie
- ImagickPixel::getColorValueQuantum — Renvoie la valeur quantique d'une couleur dans ImagickPixel
- ImagickPixel::getHSL — Retourne la couleur HSL normalisée de l'objet ImagickPixel
- ImagickPixel::getIndex — Renvoie l'index de la carte de couleurs du pixel
- ImagickPixel::isPixelSimilar — Vérifie la distance entre cette couleur et une autre
- ImagickPixel::isPixelSimilarQuantum — Renvoie si deux couleurs diffèrent de moins de la distance spécifiée
- ImagickPixel::isSimilar — Vérifie la distance entre 2 couleurs
- ImagickPixel::setColor — Définit la couleur
- ImagickPixel::setColorCount — Définit la quantité de couleurs associée à ce pixel
- ImagickPixel::setColorValue — Définit la valeur normalisée d'un des canaux
- ImagickPixel::setColorValueQuantum — Définit la valeur quantique d'un élément de couleur de ImagickPixel
- ImagickPixel::setHSL — Définit la couleur HSL normalisée
- ImagickPixel::setIndex — Définit l'index de la carte de couleurs du pixel

# La classe ImagickPixelException

(PECL imagick 3)

## Introduction

## Synopsis de la classe

class ImagickPixelException extends Exception implements Throwable {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
/* Méthodes héritées */
}

# La classe ImagickPixelIterator

(PECL imagick 2, PECL imagick 3)

## Synopsis de la classe

class ImagickPixelIterator {
public function clear(): bool
public function __construct(Imagick `$wand`)
public function destroy(): bool
public function getCurrentIteratorRow(): array
public function getIteratorRow(): int
public function getNextIteratorRow(): array
public function getPreviousIteratorRow(): array
public function newPixelIterator(Imagick `$wand`): bool
public function newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
public function resetIterator(): bool
public function setIteratorFirstRow(): bool
public function setIteratorLastRow(): bool
public function setIteratorRow(int `$row`): bool
public function syncIterator(): bool
}

# ImagickPixelIterator::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::clear — Efface toutes les ressources associées à PixelIterator

### Description

public function ImagickPixelIterator::clear(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Efface toutes les ressources associées à PixelIterator.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickPixelIterator::clear()

    <?php
    function clear($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));

        $imageIterator = $imagick->getPixelRegionIterator(100, 100, 250, 200);

        /* On parcourt les lignes de pixels */
        foreach ($imageIterator as $pixels) {
            /** @var $pixel \ImagickPixel */
            /* On parcourt les pixels de la ligne (colonne) */
            foreach ($pixels as $column => $pixel) {
                if ($column % 2) {
                    /* Paint every second pixel black*/
                    $pixel->setColor("rgba(0, 0, 0, 0)");
                }
            }
            /* On synchronise l'itérateur, ceci est important à chaque itération */
            $imageIterator->syncIterator();
        }

        $imageIterator->clear();

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::__construct — Le constructeur ImagickPixelIterator

### Description

public function ImagickPixelIterator::__construct(Imagick `$wand`)
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Le constructeur de la classe ImagickPixelIterator.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickPixelIterator::construct()

    <?php
    function construct($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = new \ImagickPixelIterator($imagick);

        /* On parcourt les lignes de pixels */
        foreach ($imageIterator as $pixels) {
            /* On parcourt les pixels de la ligne (colonne) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    /* On teint tous les deux pixels en noir */
                    $pixel->setColor("rgba(0, 0, 0, 0)");
                }
            }
            /* On synchronise l'itérateur, ceci est important à chaque itération */
            $imageIterator->syncIterator();
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::destroy — Libère les ressources associées à PixelIterator

### Description

public function ImagickPixelIterator::destroy(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Libère les ressources associées à PixelIterator.

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickPixelIterator::getCurrentIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getCurrentIteratorRow — Retourne la ligne courante des objets ImagickPixel

### Description

public function ImagickPixelIterator::getCurrentIteratorRow(): array
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la ligne courante, en tant que tableau, des objets ImagickPixel depuis l'itérateur de pixel.

### Valeurs de retour

Retourne une ligne, en tant que tableau, des objets ImagickPixel, qui peut être elle-même itérée.

# ImagickPixelIterator::getIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getIteratorRow — Retourne la ligne courante de l'itérateur de pixel

### Description

public function ImagickPixelIterator::getIteratorRow(): int
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la ligne courante de l'itérateur de pixel.

### Valeurs de retour

Retourne la position, sous la forme d'un entier de la ligne ou lance une exception ImagickPixelIteratorException si une erreur survient.

# ImagickPixelIterator::getNextIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getNextIteratorRow — Retourne la prochaine ligne de l'itérateur de pixel

### Description

public function ImagickPixelIterator::getNextIteratorRow(): array
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la prochaine ligne, sous la forme d'un tableau, depuis l'itérateur de pixel.

### Valeurs de retour

Retourne la prochaine ligne, sous la forme d'un tableau d'objets ImagickPixel, ou lance une exception ImagickPixelIteratorException si une erreur survient.

### Exemples

Exemple #1 Exemple avec ImagickPixelIterator::getNextIteratorRow()

    <?php
    function getNextIteratorRow($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelIterator();

        $count = 0;
        while ($pixels = $imageIterator->getNextIteratorRow()) {
            if (($count % 3) == 0) {
                /* On parcourt les pixels de la ligne (colonne) */
                foreach ($pixels as $column => $pixel) {
                    /** @var $pixel \ImagickPixel */
                    if ($column % 2) {
                        /* On teint tous les deux pixels en noir */
                        $pixel->setColor("rgba(0, 0, 0, 0)");
                    }
                }
                /* On synchronise l'itérateur, ceci est important à chaque itération */
                $imageIterator->syncIterator();
            }

            $count += 1;
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::getPreviousIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getPreviousIteratorRow — Retourne la ligne précédente

### Description

public function ImagickPixelIterator::getPreviousIteratorRow(): array
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne la ligne précédente, sous la forme d'un tableau, depuis l'itérateur de pixel.

### Valeurs de retour

Retourne la ligne précédente, sous la forme d'un tableau d'objets ImagickPixelWand, ou lance une exception ImagickPixelIteratorException si une erreur survient.

# ImagickPixelIterator::newPixelIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelIterator — Retourne un nouvel itérateur de pixels

### Description

public function ImagickPixelIterator::newPixelIterator(Imagick `$wand`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne un nouvel itérateur de pixels.

### Valeurs de retour

Retourne `true` en cas de succès.. Lance une exception ImagickPixelIteratorException si une erreur survient.

# ImagickPixelIterator::newPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelRegionIterator — Retourne un nouvel itérateur de pixels

### Description

public function ImagickPixelIterator::newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Retourne un nouvel itérateur de pixels.

### Liste de paramètres

`wand`

`x`

`y`

`columns`

`rows`

### Valeurs de retour

Retourne un nouveau ImagickPixelIterator en cas de succès ou lance une exception ImagickPixelIteratorException si une erreur survient.

# ImagickPixelIterator::resetIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::resetIterator — Réinitialise l'itérateur de pixel

### Description

public function ImagickPixelIterator::resetIterator(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Réinitialise l'itérateur de pixel. Utiliser cette méthode avec ImagickPixelIterator::getNextIteratorRow() pour itérer sur tous les pixels d'un conteneur de pixels.

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickPixelIterator::resetIterator()

    <?php
    function resetIterator($imagePath) {

        $imagick = new \Imagick(realpath($imagePath));

        $imageIterator = $imagick->getPixelIterator();

        /* On parcourt les lignes de pixels */
        foreach ($imageIterator as $pixels) {
            /* On parcourt les pixels de la ligne (colonne) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {

                    /* Tous les deux pixels, on ajoute 25% de rouge */
                    $pixel->setColorValue(\Imagick::COLOR_RED, 64);
                }
            }
            /* On synchronise l'itérateur, ceci est important à chaque itération */
            $imageIterator->syncIterator();
        }

        $imageIterator->resetiterator();

        /* On parcourt les lignes de pixels */
        foreach ($imageIterator as $pixels) {
            /* On parcourt les pixels de la ligne (colonne) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 3) {
                    $pixel->setColorValue(\Imagick::COLOR_BLUE, 64); /* Tous les deux pixels, on les rend un peu plus bleu */
                    //$pixel->setColor("rgba(0, 0, 128, 0)"); /* On teint tous les deux pixels en noir */
                }
            }
            $imageIterator->syncIterator(); /* On synchronise l'itérateur, ceci est important à chaque itération */
        }

        $imageIterator->clear();

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::setIteratorFirstRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorFirstRow — Définit l'itérateur de pixel sur la première ligne de pixels

### Description

public function ImagickPixelIterator::setIteratorFirstRow(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Définit l'itérateur de pixel sur la première ligne de pixels.

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickPixelIterator::setIteratorLastRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorLastRow — Définit l'itérateur de pixel sur la dernière ligne de pixels

### Description

public function ImagickPixelIterator::setIteratorLastRow(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Définit l'itérateur de pixel sur la dernière ligne de pixels.

### Valeurs de retour

Retourne `true` en cas de succès.

# ImagickPixelIterator::setIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorRow — Définit la ligne de l'itérateur de pixel

### Description

public function ImagickPixelIterator::setIteratorRow(int `$row`): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Définit la ligne de l'itérateur de pixel.

### Liste de paramètres

`row`

### Valeurs de retour

Retourne `true` en cas de succès.

### Exemples

Exemple #1 Exemple avec ImagickPixelIterator::setIteratorRow()

    <?php
    function setIteratorRow($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelRegionIterator(200, 100, 200, 200);

        for ($x = 0; $x < 20; $x++) {
            $imageIterator->setIteratorRow($x * 5);
            $pixels = $imageIterator->getCurrentIteratorRow();
            /* On parcourt les pixels de la ligne (colonne) */
            foreach ($pixels as $pixel) {
                /** @var $pixel \ImagickPixel */
                /* On teint tous les pixels en noir */
                $pixel->setColor("rgba(0, 0, 0, 0)");
            }

            /* On synchronise l'itérateur ; ceci est important à chaque itération */
            $imageIterator->syncIterator();
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::syncIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::syncIterator — Synchronise l'itérateur de pixel

### Description

public function ImagickPixelIterator::syncIterator(): bool
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

Synchronise l'itérateur de pixel.

### Valeurs de retour

Retourne `true` en cas de succès.

## Sommaire

- ImagickPixelIterator::clear — Efface toutes les ressources associées à PixelIterator
- ImagickPixelIterator::__construct — Le constructeur ImagickPixelIterator
- ImagickPixelIterator::destroy — Libère les ressources associées à PixelIterator
- ImagickPixelIterator::getCurrentIteratorRow — Retourne la ligne courante des objets ImagickPixel
- ImagickPixelIterator::getIteratorRow — Retourne la ligne courante de l'itérateur de pixel
- ImagickPixelIterator::getNextIteratorRow — Retourne la prochaine ligne de l'itérateur de pixel
- ImagickPixelIterator::getPreviousIteratorRow — Retourne la ligne précédente
- ImagickPixelIterator::newPixelIterator — Retourne un nouvel itérateur de pixels
- ImagickPixelIterator::newPixelRegionIterator — Retourne un nouvel itérateur de pixels
- ImagickPixelIterator::resetIterator — Réinitialise l'itérateur de pixel
- ImagickPixelIterator::setIteratorFirstRow — Définit l'itérateur de pixel sur la première ligne de pixels
- ImagickPixelIterator::setIteratorLastRow — Définit l'itérateur de pixel sur la dernière ligne de pixels
- ImagickPixelIterator::setIteratorRow — Définit la ligne de l'itérateur de pixel
- ImagickPixelIterator::syncIterator — Synchronise l'itérateur de pixel

# La classe ImagickPixelIteratorException

(PECL imagick 3)

## Introduction

## Synopsis de la classe

class ImagickPixelIteratorException extends Exception implements Throwable {
/* Propriétés héritées */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Méthodes */
/* Méthodes héritées */
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Exemples
  - Utilisation simple
- Imagick — La classe Imagick
  - Imagick::adaptiveBlurImage — Ajoute un flou adaptatif à l'image
  - Imagick::adaptiveResizeImage — Redimensionne adaptativement une image par triangulation
  - Imagick::adaptiveSharpenImage — Augmente le contraste de l'image
  - Imagick::adaptiveThresholdImage — Sélectionne le niveau de chaque pixel, à partir d'un intervalle d'intensité
  - Imagick::addImage — Ajoute une nouvelle image à la liste d'images Imagick
  - Imagick::addNoiseImage — Ajoute un bruit aléatoire à une image
  - Imagick::affineTransformImage — Transforme une image
  - Imagick::animateImages — Anime une ou plusieurs images
  - Imagick::annotateImage — Annote une image avec un texte
  - Imagick::appendImages — Ajoute un jeu d'images
  - Imagick::autoLevelImage — Ajuste le niveau d'un canal d'une image particulière
  - Imagick::averageImages — Moyenne d'un jeu d'images
  - Imagick::blackThresholdImage — Force tous les pixels en dessous d'un seuil à noir
  - Imagick::blueShiftImage — Atténue les couleurs de l'image
  - Imagick::blurImage — Ajoute un filtre de flou à une image
  - Imagick::borderImage — Encadre une image avec un bord
  - Imagick::brightnessContrastImage — Change la luminosité et/ou le contraste d'une image
  - Imagick::charcoalImage — Simule un dessin au fusain
  - Imagick::chopImage — Supprime une région d'une image et retaille
  - Imagick::clampImage — Restreint la plage de couleurs de 0 à la profondeur quantique
  - Imagick::clear — Libère toutes les ressources associées à un objet Imagick
  - Imagick::clipImage — Découpe le long du premier chemin du profil 8BIM
  - Imagick::clipImagePath — Découpe le long des chemins nommés du profil 8BIM, si présent
  - Imagick::clipPathImage — Découpe le long du chemin d'un profil 8BIM
  - Imagick::clone — Fait une copie exacte d'un objet Imagick
  - Imagick::clutImage — Remplace les couleurs d'une image
  - Imagick::coalesceImages — Compose un jeu d'images
  - Imagick::colorFloodfillImage — Change la couleur d'un pixel
  - Imagick::colorizeImage — Mélange la couleur de remplissage avec l'image
  - Imagick::colorMatrixImage — Applique une transformation de couleur à une image
  - Imagick::combineImages — Combine plusieurs images en une seule
  - Imagick::commentImage — Ajoute un commentaire à une image
  - Imagick::compareImageChannels — Retourne la différence entre plusieurs images
  - Imagick::compareImageLayers — Retourne la région d'encadrement maximale entre deux images
  - Imagick::compareImages — Compare une image avec une image reconstituée
  - Imagick::compositeImage — Compose une image avec une autre
  - Imagick::__construct — Le constructeur Imagick
  - Imagick::contrastImage — Change le contraste de l'image
  - Imagick::contrastStretchImage — Améliore le contraste d'une image
  - Imagick::convolveImage — Applique un noyau de convolution à une image
  - Imagick::count — Renvoie le nombre d'images
  - Imagick::cropImage — Extrait une région d'une image
  - Imagick::cropThumbnailImage — Crée une miniature par retaillage
  - Imagick::current — Retourne une référence sur l'objet imagick courant
  - Imagick::cycleColormapImage — Déplace la carte des couleurs d'une image
  - Imagick::decipherImage — Déchiffre une image
  - Imagick::deconstructImages — Retourne les différences de certains pixels entre deux images
  - Imagick::deleteImageArtifact — Supprime l'artefact d'une image
  - Imagick::deleteImageProperty — Supprime une propriété d'image
  - Imagick::deskewImage — Supprime le biais de l'image
  - Imagick::despeckleImage — Réduit le bruit speckle d'une image
  - Imagick::destroy — Détruit un objet Imagick
  - Imagick::displayImage — Affiche une image
  - Imagick::displayImages — Affiche une image ou une séquence
  - Imagick::distortImage — Déforme une image avec différentes méthodes
  - Imagick::drawImage — Affiche un objet ImagickDraw dans l'image courante
  - Imagick::edgeImage — Renforce les bords dans l'image
  - Imagick::embossImage — Retourne une image en niveau de gris, avec un effet 3D
  - Imagick::encipherImage — Chiffre une image
  - Imagick::enhanceImage — Améliore la qualité d'une image bruitée
  - Imagick::equalizeImage — Égalise l'histogramme d'une image
  - Imagick::evaluateImage — Applique une expression à une image
  - Imagick::exportImagePixels — Exporte les pixels bruts de l'image
  - Imagick::extentImage — Définit la taille de l'image
  - Imagick::filter — Applique un noyau de convolution personnalisé à l'image
  - Imagick::flattenImages — Fusionne une séquence d'images
  - Imagick::flipImage — Crée une image par miroir vertical
  - Imagick::floodFillPaintImage — Modifie la valeur de la couleur de chaque pixel correspondant à la cible
  - Imagick::flopImage — Crée une image par miroir horizontal
  - Imagick::forwardFourierTransformImage — Implémente la transformée de Fourier discrète (Discrete Fourier Transform - DFT)
  - Imagick::frameImage — Ajoute un bord 3D
  - Imagick::functionImage — Applique une fonction sur l'image
  - Imagick::fxImage — Évalue une expression pour chaque pixel d'une image
  - Imagick::gammaImage — Applique une correction gamma à l'image
  - Imagick::gaussianBlurImage — Ajoute du flou à une image
  - Imagick::getColorspace — Récupère l'espace de couleurs
  - Imagick::getCompression — Lit le type de compression
  - Imagick::getCompressionQuality — Lit la qualité de la compression
  - Imagick::getCopyright — Retourne le copyright de l'API ImageMagick
  - Imagick::getFilename — Lit le nom du fichier associé à une séquence
  - Imagick::getFont — Récupère la police de caractères
  - Imagick::getFormat — Retourne le format de l'image Imagick
  - Imagick::getGravity — Récupère la gravité
  - Imagick::getHomeURL — Retourne l'URL de ImageMagick
  - Imagick::getImage — Retourne un nouvel objet Imagick
  - Imagick::getImageAlphaChannel — Vérifie si l'image a un canal alpha
  - Imagick::getImageArtifact — Récupère l'artefact de l'image
  - Imagick::getImageAttribute — Obtient un attribut nommé
  - Imagick::getImageBackgroundColor — Retourne la couleur de fond
  - Imagick::getImageBlob — Retourne la séquence d'images comme un blob
  - Imagick::getImageBluePrimary — Retourne la chromaticité de la couleur bleue
  - Imagick::getImageBorderColor — Retourne la couleur de bordure de l'image
  - Imagick::getImageChannelDepth — Lit la profondeur d'un des canaux de l'image
  - Imagick::getImageChannelDistortion — Compare les canaux d'une image reconstituée
  - Imagick::getImageChannelDistortions — Récupère les distorsions d'un canal
  - Imagick::getImageChannelExtrema — Lit les extrêmes pour les canaux de l'image
  - Imagick::getImageChannelKurtosis — Le but de getImageChannelKurtosis
  - Imagick::getImageChannelMean — Lit la moyenne et la déviation standard
  - Imagick::getImageChannelRange — Récupère l'intervalle du canal
  - Imagick::getImageChannelStatistics — Retourne des statistiques sur chaque canal de l'image
  - Imagick::getImageClipMask — Récupère le masque du clip de l'image
  - Imagick::getImageColormapColor — Retourne la couleur à l'index de la carte de couleurs
  - Imagick::getImageColors — Lit le nombre de couleurs uniques de l'image
  - Imagick::getImageColorspace — Lit l'espace de couleurs de l'image
  - Imagick::getImageCompose — Retourne l'opérateur de composition associé à une image
  - Imagick::getImageCompression — Lit le type de compression de l'image
  - Imagick::getImageCompressionQuality — Lit la qualité de compression de l'image
  - Imagick::getImageDelay — Lit le délai de l'image
  - Imagick::getImageDepth — Lit la profondeur de l'image
  - Imagick::getImageDispose — Lit la méthode de récupération
  - Imagick::getImageDistortion — Compare une image à une image reconstituée
  - Imagick::getImageExtrema — Lit les extrêmes d'une image
  - Imagick::getImageFilename — Retourne le nom d'un fichier pour une image dans une séquence
  - Imagick::getImageFormat — Retourne le format d'une image dans une séquence
  - Imagick::getImageGamma — Lit le gamma de l'image
  - Imagick::getImageGeometry — Lit les dimensions de l'image dans un tableau
  - Imagick::getImageGravity — Récupère la gravité de l'image
  - Imagick::getImageGreenPrimary — Retourne la chromaticité de la couleur verte
  - Imagick::getImageHeight — Retourne la hauteur de l'image
  - Imagick::getImageHistogram — Retourne l'histogramme de l'image
  - Imagick::getImageIndex — Lit l'index de l'image courante
  - Imagick::getImageInterlaceScheme — Lit le schéma d'entrelacement de l'image
  - Imagick::getImageInterpolateMethod — Retourne la méthode d'interpolation
  - Imagick::getImageIterations — Lit les itérations de l'image
  - Imagick::getImageLength — Retourne la taille de l'image en octets
  - Imagick::getImageMatte — Indique si l'image a un canal mat
  - Imagick::getImageMatteColor — Retourne la couleur mate de l'image
  - Imagick::getImageMimeType — Renvoie le type MIME de l'image
  - Imagick::getImageOrientation — Lit l'orientation de l'image
  - Imagick::getImagePage — Retourne la géométrie de la page
  - Imagick::getImagePixelColor — Retourne la couleur d'un pixel
  - Imagick::getImageProfile — Retourne un profil d'une image
  - Imagick::getImageProfiles — Retourne les profils de l'image
  - Imagick::getImageProperties — Retourne les propriétés EXIF de l'image
  - Imagick::getImageProperty — Retourne une propriété d'une image
  - Imagick::getImageRedPrimary — Retourne la chromaticité du point rouge
  - Imagick::getImageRegion — Extrait une région d'une image
  - Imagick::getImageRenderingIntent — Lit la méthode de rendu de l'image
  - Imagick::getImageResolution — Lit les résolutions en X et Y d'une image
  - Imagick::getImagesBlob — Retourne toutes les images de la séquence en un BLOB
  - Imagick::getImageScene — Retourne la scène de l'image
  - Imagick::getImageSignature — Génère une signature SHA-256
  - Imagick::getImageSize — Retourne la taille de l'image en octets
  - Imagick::getImageTicksPerSecond — Lit les ticks-par-seconde de l'image
  - Imagick::getImageTotalInkDensity — Lit la densité totale d'encre de l'image
  - Imagick::getImageType — Lit le type possible d'image
  - Imagick::getImageUnits — Retourne les unités de résolution de l'image
  - Imagick::getImageVirtualPixelMethod — Retourne la méthode du pixel virtuel
  - Imagick::getImageWhitePoint — Retourne la chromaticité du point blanc
  - Imagick::getImageWidth — Retourne la largeur de l'image
  - Imagick::getInterlaceScheme — Lit le schéma d'entrelacement de l'objet
  - Imagick::getIteratorIndex — Lit l'index de l'image active courante
  - Imagick::getNumberImages — Retourne le nombre d'images d'un objet
  - Imagick::getOption — Retourne la valeur d'une option
  - Imagick::getPackageName — Retourne le nom du paquet ImageMagick
  - Imagick::getPage — Retourne la géométrie de la page
  - Imagick::getPixelIterator — Retourne un MagickPixelIterator
  - Imagick::getPixelRegionIterator — Lit un objet ImagickPixelIterator pour une section d'image
  - Imagick::getPointSize — Récupère la taille du point
  - Imagick::getQuantum — Renvoie la plage quantique d'ImageMagick
  - Imagick::getQuantumDepth — Lit la profondeur quantique
  - Imagick::getQuantumRange — Retourne l'intervalle quantique de Imagick
  - Imagick::getRegistry — Obtient un élément de StringRegistry
  - Imagick::getReleaseDate — Retourne la date de publication de ImageMagick
  - Imagick::getResource — Retourne la consommation de mémoire de la ressource
  - Imagick::getResourceLimit — Retourne la limite de la ressource
  - Imagick::getSamplingFactors — Lit le facteur d'échantillonnage horizontal et vertical
  - Imagick::getSize — Retourne la taille associée avec un objet Imagick
  - Imagick::getSizeOffset — Retourne la taille de la position
  - Imagick::getVersion — Retourne la version de l'API ImageMagick
  - Imagick::haldClutImage — Remplace les couleurs de l'image
  - Imagick::hasNextImage — Vérifie si un objet a une image suivante
  - Imagick::hasPreviousImage — Vérifie si un objet a une image précédente
  - Imagick::identifyFormat — Formate une chaîne avec les détails de l'image
  - Imagick::identifyImage — Identifie une image et lit ses attributs
  - Imagick::implodeImage — Crée une nouvelle copie d'image
  - Imagick::importImagePixels — Importe des pixels dans une image
  - Imagick::inverseFourierTransformImage — Implémente la transformée de Fourier discrète inverse (Discrete Fourier Transform - DFT)
  - Imagick::labelImage — Ajoute un libellé à une image
  - Imagick::levelImage — Ajuste les niveaux de l'image
  - Imagick::linearStretchImage — Étire la saturation de l'intensité de l'image
  - Imagick::liquidRescaleImage — Redimensionne une image par mise à l'échelle liquide
  - Imagick::listRegistry — Liste tous les paramètres du registre
  - Imagick::magnifyImage — Double la taille d'une image, proportionnellement
  - Imagick::mapImage — Remplace la couleur d'une image par celle d'une image de référence
  - Imagick::matteFloodfillImage — Change la transparence d'une couleur
  - Imagick::medianFilterImage — Applique un filtre numérique
  - Imagick::mergeImageLayers — Fusionne les calques de l'image
  - Imagick::minifyImage — Met à l'échelle une image proportionnellement pour la réduire de moitié de taille
  - Imagick::modulateImage — Contrôle la saturation, l'intensité et la teinte
  - Imagick::montageImage — Crée une image composite
  - Imagick::morphImages — Réalise un morphing entre deux images
  - Imagick::morphology — Applique un noyau personnalisé à l'image selon la méthode de morphologie donnée
  - Imagick::mosaicImages — Forme une mosaïque d'images
  - Imagick::motionBlurImage — Ajoute un flou de déplacement
  - Imagick::negateImage — Effectue la négation des couleurs d'une image de référence
  - Imagick::newImage — Crée une nouvelle image
  - Imagick::newPseudoImage — Crée une nouvelle image
  - Imagick::nextImage — Passe à la prochaine image
  - Imagick::normalizeImage — Améliore le contraste de l'image
  - Imagick::oilPaintImage — Simule une peinture à l'huile
  - Imagick::opaquePaintImage — Modifie la valeur de la couleur de tous les pixels correspondant à la cible
  - Imagick::optimizeImageLayers — Supprime les portions récurrentes d'images à optimiser
  - Imagick::orderedPosterizeImage — Effectue un dither ordonné
  - Imagick::paintFloodfillImage — Change les pixels qui sont d'une couleur
  - Imagick::paintOpaqueImage — Change les pixels qui sont d'une couleur
  - Imagick::paintTransparentImage — Remplit les pixels avec une couleur
  - Imagick::pingImage — Lit des attributs simples sans ouvrir une image
  - Imagick::pingImageBlob — Lit rapidement les attributs
  - Imagick::pingImageFile — Lit les attributs simples d'une image
  - Imagick::polaroidImage — Simule une photo Polaroid
  - Imagick::posterizeImage — Réduit une image à un nombre limité de couleurs
  - Imagick::previewImages — Teste rapidement différents paramètres pour un traitement d'images
  - Imagick::previousImage — Passe à l'image précédente dans une séquence d'images
  - Imagick::profileImage — Ajoute ou retire un profil d'une image
  - Imagick::quantizeImage — Analyse les couleurs dans une référence d'image
  - Imagick::quantizeImages — Analyse les couleurs d'une séquence d'images
  - Imagick::queryFontMetrics — Retourne un tableau représentant les dimensions de la police
  - Imagick::queryFonts — Retourne la liste de polices configurées
  - Imagick::queryFormats — Retourne les formats supportés par Imagick
  - Imagick::radialBlurImage — Flou radial d'une image
  - Imagick::raiseImage — Crée un effet 3D de bouton
  - Imagick::randomThresholdImage — Crée une image en deux couleurs, à haut contraste
  - Imagick::readImage — Lit une image depuis un fichier
  - Imagick::readImageBlob — Lit une image depuis une chaîne binaire
  - Imagick::readImageFile — Lit une image à partir d'une ressource fichier
  - Imagick::readimages — Lit une image à partir d'un tableau de noms de fichiers
  - Imagick::recolorImage — Recolore l'image
  - Imagick::reduceNoiseImage — Adoucit les contours d'une image
  - Imagick::remapImage — Reconfigure les couleurs de l'image
  - Imagick::removeImage — Retire une image de la liste
  - Imagick::removeImageProfile — Supprime le profil de l'image et le retourne
  - Imagick::render — Affiche toutes les commandes de dessins précédentes
  - Imagick::resampleImage — Rééchantillonne l'image
  - Imagick::resetImagePage — Réinitialise la page de l'image
  - Imagick::resizeImage — Redimensionne une image
  - Imagick::rollImage — Décale une image
  - Imagick::rotateImage — Tourne une image
  - Imagick::rotationalBlurImage — Flou de rotation d'une image
  - Imagick::roundCorners — Arrondit les coins d'une image
  - Imagick::sampleImage — Met à l'échelle une image avec échantillonnage de pixels
  - Imagick::scaleImage — Met à l'échelle la taille de l'image
  - Imagick::segmentImage — Segmente une image
  - Imagick::selectiveBlurImage — Floute sélectivement une image dans un seuil de contraste
  - Imagick::separateImageChannel — Sépare un canal d'une image
  - Imagick::sepiaToneImage — Passe une image en tons sépia
  - Imagick::setBackgroundColor — Configure la couleur de fond par défaut
  - Imagick::setColorspace — Définit l'espace de couleurs
  - Imagick::setCompression — Configure le type de compression de l'objet
  - Imagick::setCompressionQuality — Configure la compression par défaut de l'objet
  - Imagick::setFilename — Configure le nom du fichier d'image avant d'y accéder
  - Imagick::setFirstIterator — Place l'itérateur de Imagick sur la première image
  - Imagick::setFont — Configure la police
  - Imagick::setFormat — Configure le format de l'objet Imagick
  - Imagick::setGravity — Définit la gravité
  - Imagick::setImage — Remplace l'image dans l'objet
  - Imagick::setImageAlphaChannel — Définit le canal alpha de l'image
  - Imagick::setImageArtifact — Définit l'artefact de l'image
  - Imagick::setImageAttribute — Définit un attribut d'image
  - Imagick::setImageBackgroundColor — Configure la couleur de fond d'image
  - Imagick::setImageBias — Configure le biais pour les convolutions
  - Imagick::setImageBiasQuantum — Définit le biais de l'image
  - Imagick::setImageBluePrimary — Configure la chromaticité du point bleu
  - Imagick::setImageBorderColor — Configure la couleur de bordure
  - Imagick::setImageChannelDepth — Configure la profondeur d'un canal
  - Imagick::setImageClipMask — Définit le masque du clip de l'image
  - Imagick::setImageColormapColor — Configure une couleur de la carte
  - Imagick::setImageColorspace — Configure l'espace de couleurs de l'image
  - Imagick::setImageCompose — Configure l'opérateur de composition de l'image
  - Imagick::setImageCompression — Configure la compression de l'image
  - Imagick::setImageCompressionQuality — Spécifie la qualité de compression de l'image
  - Imagick::setImageDelay — Configure le délai de l'image
  - Imagick::setImageDepth — Configure la profondeur de l'image
  - Imagick::setImageDispose — Configure la méthode de récupération
  - Imagick::setImageExtent — Configure la taille d'une image
  - Imagick::setImageFilename — Configure le nom de fichier d'une image dans une séquence
  - Imagick::setImageFormat — Configure le format d'une image dans une séquence
  - Imagick::setImageGamma — Configure la correction gamma
  - Imagick::setImageGravity — Définit la gravité de l'image
  - Imagick::setImageGreenPrimary — Configure la chromaticité du point vert
  - Imagick::setImageIndex — Modifie la position de l'itérateur
  - Imagick::setImageInterlaceScheme — Configure la méthode d'entrelacement de l'image
  - Imagick::setImageInterpolateMethod — Configure la méthode d'interpolation de l'image
  - Imagick::setImageIterations — Configure les itérations de l'image
  - Imagick::setImageMatte — Configure le canal mate de l'image
  - Imagick::setImageMatteColor — Configure la couleur mate
  - Imagick::setImageOpacity — Configure le niveau d'opacité de l'image
  - Imagick::setImageOrientation — Configure l'orientation de l'image
  - Imagick::setImagePage — Configure la géométrie de la page de l'image
  - Imagick::setImageProfile — Ajoute un profil à un objet Imagick
  - Imagick::setImageProperty — Configure une propriété d'image
  - Imagick::setImageRedPrimary — Configure la chromaticité du point rouge
  - Imagick::setImageRenderingIntent — Configure le type de rendu de l'image
  - Imagick::setImageResolution — Configure la résolution de l'image
  - Imagick::setImageScene — Configure la scène de l'image
  - Imagick::setImageTicksPerSecond — Configure le nombre de ticks par seconde de l'image
  - Imagick::setImageType — Configure le type d'image
  - Imagick::setImageUnits — Configure les unités de résolution de l'image
  - Imagick::setImageVirtualPixelMethod — Configure la méthode du point virtuel de l'image
  - Imagick::setImageWhitePoint — Configure la chromaticité du point blanc
  - Imagick::setInterlaceScheme — Configure la compression de l'image
  - Imagick::setIteratorIndex — Déplace l'itérateur
  - Imagick::setLastIterator — Positionne l'itérateur Imagick à la dernière image
  - Imagick::setOption — Configure une option d'un objet Imagick
  - Imagick::setPage — Configure la géométrie de la page de l'objet Imagick
  - Imagick::setPointSize — Définit la taille du point
  - Imagick::setProgressMonitor — Définit une fonction de rappel à appeler pendant le traitement
  - Imagick::setRegistry — Définit l'entrée du registre ImageMagick nommée clé pour valeur
  - Imagick::setResolution — Configure la résolution de l'image
  - Imagick::setResourceLimit — Définit la limite pour une ressource particulière
  - Imagick::setSamplingFactors — Configure les facteurs d'échantillonnage de l'image
  - Imagick::setSize — Configure la taille de l'objet Imagick
  - Imagick::setSizeOffset — Configure la taille et la position de l'objet Imagick
  - Imagick::setType — Configure l'attribut de l'image
  - Imagick::shadeImage — Crée un effet 3D
  - Imagick::shadowImage — Simule une ombre sur l'image
  - Imagick::sharpenImage — Aiguise une image
  - Imagick::shaveImage — Supprime les pixels du bord de l'image
  - Imagick::shearImage — Crée un parallélogramme
  - Imagick::sigmoidalContrastImage — Ajuste le contraste de l'image
  - Imagick::sketchImage — Simule un crayon à main levée
  - Imagick::smushImages — Prend toutes les images du pointeur d'image actuel jusqu'à la fin de la liste d'images et les écrase
  - Imagick::solarizeImage — Applique un effet de solarisation à l'image
  - Imagick::sparseColorImage — Interpole les couleurs
  - Imagick::spliceImage — Joint une couleur solide dans l'image
  - Imagick::spreadImage — Bouge aléatoirement chaque pixel d'un bloc
  - Imagick::statisticImage — Modifie une image en utilisant une fonction statistique
  - Imagick::steganoImage — Cache un filigrane numérique dans l'image
  - Imagick::stereoImage — Fusionne 2 images
  - Imagick::stripImage — Supprime d'une image tous les profils et les commentaires
  - Imagick::subImageMatch — Recherche une sous-image dans l'image courante et renvoie une image de similarité
  - Imagick::swirlImage — Tourbillonne les pixels du centre de l'image
  - Imagick::textureImage — Répète les carreaux de la texture d'une image
  - Imagick::thresholdImage — Modifie la valeur des pixels individuels, basée sur un seuil
  - Imagick::thumbnailImage — Modifie la taille d'une image
  - Imagick::tintImage — Applique un vecteur de couleur à chaque pixel de l'image
  - Imagick::__toString — Renvoie l'image sous forme de chaîne
  - Imagick::transformImage — Méthode de convenance pour définir la taille de rognage et la géométrie de l'image
  - Imagick::transformImageColorspace — Transforme une image dans un nouvel espace de couleur
  - Imagick::transparentPaintImage — Rend des pixels transparents
  - Imagick::transposeImage — Applique une symétrie verticale
  - Imagick::transverseImage — Crée un miroir horizontal de l'image
  - Imagick::trimImage — Supprime les bords de l'image
  - Imagick::uniqueImageColors — Ne conserve qu'une couleur de pixel
  - Imagick::unsharpMaskImage — Rend une image plus nette
  - Imagick::valid — Vérifie si l'élément courant est valide
  - Imagick::vignetteImage — Ajoute un filtre vignette à l'image
  - Imagick::waveImage — Ajoute un filtre de vagues à l'image
  - Imagick::whiteThresholdImage — Force tous les pixels au-dessus du seuil en blanc
  - Imagick::writeImage — Écrit une image dans le fichier spécifié
  - Imagick::writeImageFile — Écrit une image dans un descripteur de fichier
  - Imagick::writeImages — Écrit une image ou une séquence d'images
  - Imagick::writeImagesFile — Écrit des frames dans un descripteur de fichiers
- ImagickDraw — La classe ImagickDraw
  - ImagickDraw::affine — Ajuste la matrice de transformation affine courante
  - ImagickDraw::annotation — Dessine un texte sur une image
  - ImagickDraw::arc — Dessine un arc
  - ImagickDraw::bezier — Dessine une courbe de Bézier
  - ImagickDraw::circle — Dessine un cercle
  - ImagickDraw::clear — Efface tout l'objet ImagickDraw
  - ImagickDraw::clone — Fait une copie exacte de l'objet ImagickDraw
  - ImagickDraw::color — Dessine une couleur sur une image
  - ImagickDraw::comment — Ajoute un commentaire
  - ImagickDraw::composite — Compose une image avec une autre
  - ImagickDraw::__construct — Le constructeur ImagickDraw
  - ImagickDraw::destroy — Libère toutes les ressources associées à un objet ImagickDraw
  - ImagickDraw::ellipse — Dessine une ellipse sur une image
  - ImagickDraw::getClipPath — Retourne l'identifiant du chemin courant
  - ImagickDraw::getClipRule — Retourne la règle de remplissage courante pour les polygones
  - ImagickDraw::getClipUnits — Retourne l'unité d'interprétation des chemins
  - ImagickDraw::getFillColor — Retourne la couleur de remplissage
  - ImagickDraw::getFillOpacity — Retourne l'opacité de dessin
  - ImagickDraw::getFillRule — Retourne la règle de remplissage
  - ImagickDraw::getFont — Retourne la police
  - ImagickDraw::getFontFamily — Retourne la famille de police
  - ImagickDraw::getFontSize — Retourne la taille de la police
  - ImagickDraw::getFontStretch — Renvoie l'étirement de la police à utiliser lors de l'annotation avec du texte
  - ImagickDraw::getFontStyle — Retourne le style de la police
  - ImagickDraw::getFontWeight — Retourne le poids de la police
  - ImagickDraw::getGravity — Retourne la gravité de placement de texte
  - ImagickDraw::getStrokeAntialias — Retourne la configuration d'anti-aliasing de trait
  - ImagickDraw::getStrokeColor — Retourne la couleur des contours d'objets
  - ImagickDraw::getStrokeDashArray — Retourne un tableau représentant le motif de pointillés
  - ImagickDraw::getStrokeDashOffset — Retourne l'offset du pointillé dans le motif
  - ImagickDraw::getStrokeLineCap — Retourne la forme à utiliser pour dessiner les bouts de sous-chemins
  - ImagickDraw::getStrokeLineJoin — Retourne la forme à utiliser pour dessiner les coins d'un chemin
  - ImagickDraw::getStrokeMiterLimit — Retourne la 'miterLimit'
  - ImagickDraw::getStrokeOpacity — Retourne l'opacité des contours d'un objet
  - ImagickDraw::getStrokeWidth — Retourne la largeur du trait utilisé
  - ImagickDraw::getTextAlignment — Retourne l'alignement du texte
  - ImagickDraw::getTextAntialias — Retourne la configuration de l'anti-aliasing de texte
  - ImagickDraw::getTextDecoration — Retourne la décoration du texte
  - ImagickDraw::getTextEncoding — Retourne le jeu de caractères utilisé pour les annotations de texte
  - ImagickDraw::getTextInterlineSpacing — Récupère l'espacement interlignes d'un texte.
  - ImagickDraw::getTextInterwordSpacing — Récupère l'espace entre les mots d'un texte.
  - ImagickDraw::getTextKerning — Récupère le crénage d'un texte.
  - ImagickDraw::getTextUnderColor — Retourne la couleur sous le texte
  - ImagickDraw::getVectorGraphics — Retourne une chaîne contenant le vecteur graphique
  - ImagickDraw::line — Dessine une ligne
  - ImagickDraw::matte — Dessine sur le canal d'opacité de l'image
  - ImagickDraw::pathClose — Ajoute un élément de chemin au chemin courant
  - ImagickDraw::pathCurveToAbsolute — Dessine une courbe de Bézier cubique, en coordonnées absolues
  - ImagickDraw::pathCurveToQuadraticBezierAbsolute — Dessine une courbe de Bézier quadratique, en coordonnées absolues
  - ImagickDraw::pathCurveToQuadraticBezierRelative — Dessine une courbe de Bézier quadratique, en coordonnées relatives
  - ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Dessine une courbe de Bézier quadratique, en coordonnées absolues
  - ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Dessine une courbe de Bézier quadratique, en coordonnées relatives
  - ImagickDraw::pathCurveToRelative — Dessine une courbe de Bézier cubique, en coordonnées relatives
  - ImagickDraw::pathCurveToSmoothAbsolute — Dessine une courbe de Bézier, en coordonnées absolues
  - ImagickDraw::pathCurveToSmoothRelative — Dessine une courbe de Bézier, en coordonnées relatives
  - ImagickDraw::pathEllipticArcAbsolute — Dessine un arc d'ellipse, en coordonnées absolues
  - ImagickDraw::pathEllipticArcRelative — Dessine un arc d'ellipse, en coordonnées relatives
  - ImagickDraw::pathFinish — Termine le chemin courant
  - ImagickDraw::pathLineToAbsolute — Dessine une ligne de chemin, en coordonnées absolues
  - ImagickDraw::pathLineToHorizontalAbsolute — Dessine une ligne de chemin horizontale, en coordonnées absolues
  - ImagickDraw::pathLineToHorizontalRelative — Dessine une ligne de chemin horizontale, en coordonnées relatives
  - ImagickDraw::pathLineToRelative — Dessine une ligne de chemin, en coordonnées relatives
  - ImagickDraw::pathLineToVerticalAbsolute — Dessine une ligne de chemin verticale, en coordonnées absolues
  - ImagickDraw::pathLineToVerticalRelative — Dessine une ligne de chemin verticale, en coordonnées relatives
  - ImagickDraw::pathMoveToAbsolute — Commence un nouveau sous-chemin, en coordonnées absolues
  - ImagickDraw::pathMoveToRelative — Commence un nouveau sous-chemin, en coordonnées relatives
  - ImagickDraw::pathStart — Déclare le début d'un chemin de dessin
  - ImagickDraw::point — Dessine un point
  - ImagickDraw::polygon — Dessine un polygone
  - ImagickDraw::polyline — Dessine une ligne brisée
  - ImagickDraw::pop — Détruit l'objet ImagickDraw courant dans la pile, et retourne son précédent
  - ImagickDraw::popClipPath — Termine la définition d'un chemin
  - ImagickDraw::popDefs — Termine une définition de liste
  - ImagickDraw::popPattern — Termine une définition de motif
  - ImagickDraw::push — Clone l'objet ImagickDraw courant et le pousse dans la pile
  - ImagickDraw::pushClipPath — Commence la définition d'un chemin
  - ImagickDraw::pushDefs — Indique que la commande suivante crée des éléments nommés pour pré-traitement
  - ImagickDraw::pushPattern — Configure un espace de dessin
  - ImagickDraw::rectangle — Dessine un rectangle
  - ImagickDraw::render — Effectue le rendu de tous les dessins à l'image
  - ImagickDraw::resetVectorGraphics — Réinitialise les graphiques vectoriels
  - ImagickDraw::rotate — Applique une rotation
  - ImagickDraw::roundRectangle — Dessine un rectangle aux coins arrondis
  - ImagickDraw::scale — Ajuste le facteur de mise à l'échelle
  - ImagickDraw::setClipPath — Associe un chemin avec une image
  - ImagickDraw::setClipRule — Configure la règle de remplissage du polygone à utiliser avec les chemins
  - ImagickDraw::setClipUnits — Configure le mode d'interprétation des unités de chemin
  - ImagickDraw::setFillAlpha — Configure l'opacité de la couleur de remplissage
  - ImagickDraw::setFillColor — Configure la couleur de dessin des objets remplis
  - ImagickDraw::setFillOpacity — Configure l'opacité à utiliser pour le remplissage
  - ImagickDraw::setFillPatternURL — Configure l'URL du motif de remplissage des surfaces
  - ImagickDraw::setFillRule — Configure la règle de remplissage des polygones
  - ImagickDraw::setFont — Configure la police complète pour les textes
  - ImagickDraw::setFontFamily — Configure la famille de police pour les textes
  - ImagickDraw::setFontSize — Configure la taille de point pour les textes
  - ImagickDraw::setFontStretch — Configure l'étirement du texte
  - ImagickDraw::setFontStyle — Configure le style de police
  - ImagickDraw::setFontWeight — Configure le poids de la police
  - ImagickDraw::setGravity — Configure la gravité de placement de texte
  - ImagickDraw::setResolution — Définit la résolution
  - ImagickDraw::setStrokeAlpha — Spécifie l'opacité des contours d'objets
  - ImagickDraw::setStrokeAntialias — Contrôle l'anti-aliasing des pointillés
  - ImagickDraw::setStrokeColor — Configure la couleur utilisée pour dessiner les objets
  - ImagickDraw::setStrokeDashArray — Spécifie le motif de pointillé
  - ImagickDraw::setStrokeDashOffset — Spécifie la position dans le motif pour commencer le pointillé
  - ImagickDraw::setStrokeLineCap — Spécifie la forme à utiliser à la fin des sous-chemins
  - ImagickDraw::setStrokeLineJoin — Spécifie la forme à utiliser aux coins des chemins
  - ImagickDraw::setStrokeMiterLimit — Spécifie la limite miter
  - ImagickDraw::setStrokeOpacity — Spécifie l'opacité pour dessiner les contours
  - ImagickDraw::setStrokePatternURL — Configure le motif utilisé pour dessiner les contours
  - ImagickDraw::setStrokeWidth — Configure la largeur du trait pour dessiner les contours
  - ImagickDraw::setTextAlignment — Spécifie l'alignement du texte
  - ImagickDraw::setTextAntialias — Contrôle l'anti-aliasing du texte
  - ImagickDraw::setTextDecoration — Spécifie les ornements de texte
  - ImagickDraw::setTextEncoding — Spécifie le jeu de caractères
  - ImagickDraw::setTextInterlineSpacing — Définit l'espace entre les lignes d'un texte
  - ImagickDraw::setTextInterwordSpacing — Définit l'espace entre les mots d'un texte
  - ImagickDraw::setTextKerning — Définit le crénage d'un texte
  - ImagickDraw::setTextUnderColor — Spécifie la couleur de fond d'un rectangle
  - ImagickDraw::setVectorGraphics — Configure le vecteur graphique
  - ImagickDraw::setViewbox — Configure la taille du canevas
  - ImagickDraw::skewX — Biaise les coordonnées dans la direction horizontale
  - ImagickDraw::skewY — Incline les coordonnées dans la direction verticale
  - ImagickDraw::translate — Applique une translation
- ImagickDrawException — La classe ImagickDrawException
- ImagickException — La classe ImagickException
- ImagickKernel — La classe ImagickKernel
  - ImagickKernel::addKernel — Attache un autre noyau à une liste de noyaux
  - ImagickKernel::addUnityKernel — Ajoute un noyau Unity à la liste des noyaux
  - ImagickKernel::fromBuiltIn — Crée un noyau à partir d'un noyau intégré
  - ImagickKernel::fromMatrix — Créer un noyau à partir d'une matrice 2D de valeurs
  - ImagickKernel::getMatrix — Renvoie la matrice 2D des valeurs utilisées dans ce noyau
  - ImagickKernel::scale — Dimensionne une liste de noyaux par la quantité donnée
  - ImagickKernel::separate — Sépare un ensemble de noyaux liés et renvoie un tableau d'ImagickKernels
- ImagickKernelException — La classe ImagickKernelException
- ImagickPixel — La classe ImagickPixel
  - ImagickPixel::clear — Supprime toutes les ressources associées avec l'objet
  - ImagickPixel::__construct — Le constructeur ImagickPixel
  - ImagickPixel::destroy — Libère les ressources associées avec l'objet
  - ImagickPixel::getColor — Retourne la couleur
  - ImagickPixel::getColorAsString — Retourne une couleur
  - ImagickPixel::getColorCount — Retourne le nombre de couleurs associé avec une couleur
  - ImagickPixel::getColorQuantum — Renvoie la couleur du pixel dans un tableau en tant que valeurs quantiques
  - ImagickPixel::getColorValue — Récupère la valeur normalisée du canal de la couleur fournie
  - ImagickPixel::getColorValueQuantum — Renvoie la valeur quantique d'une couleur dans ImagickPixel
  - ImagickPixel::getHSL — Retourne la couleur HSL normalisée de l'objet ImagickPixel
  - ImagickPixel::getIndex — Renvoie l'index de la carte de couleurs du pixel
  - ImagickPixel::isPixelSimilar — Vérifie la distance entre cette couleur et une autre
  - ImagickPixel::isPixelSimilarQuantum — Renvoie si deux couleurs diffèrent de moins de la distance spécifiée
  - ImagickPixel::isSimilar — Vérifie la distance entre 2 couleurs
  - ImagickPixel::setColor — Définit la couleur
  - ImagickPixel::setColorCount — Définit la quantité de couleurs associée à ce pixel
  - ImagickPixel::setColorValue — Définit la valeur normalisée d'un des canaux
  - ImagickPixel::setColorValueQuantum — Définit la valeur quantique d'un élément de couleur de ImagickPixel
  - ImagickPixel::setHSL — Définit la couleur HSL normalisée
  - ImagickPixel::setIndex — Définit l'index de la carte de couleurs du pixel
- ImagickPixelException — La classe ImagickPixelException
- ImagickPixelIterator — La classe ImagickPixelIterator
  - ImagickPixelIterator::clear — Efface toutes les ressources associées à PixelIterator
  - ImagickPixelIterator::__construct — Le constructeur ImagickPixelIterator
  - ImagickPixelIterator::destroy — Libère les ressources associées à PixelIterator
  - ImagickPixelIterator::getCurrentIteratorRow — Retourne la ligne courante des objets ImagickPixel
  - ImagickPixelIterator::getIteratorRow — Retourne la ligne courante de l'itérateur de pixel
  - ImagickPixelIterator::getNextIteratorRow — Retourne la prochaine ligne de l'itérateur de pixel
  - ImagickPixelIterator::getPreviousIteratorRow — Retourne la ligne précédente
  - ImagickPixelIterator::newPixelIterator — Retourne un nouvel itérateur de pixels
  - ImagickPixelIterator::newPixelRegionIterator — Retourne un nouvel itérateur de pixels
  - ImagickPixelIterator::resetIterator — Réinitialise l'itérateur de pixel
  - ImagickPixelIterator::setIteratorFirstRow — Définit l'itérateur de pixel sur la première ligne de pixels
  - ImagickPixelIterator::setIteratorLastRow — Définit l'itérateur de pixel sur la dernière ligne de pixels
  - ImagickPixelIterator::setIteratorRow — Définit la ligne de l'itérateur de pixel
  - ImagickPixelIterator::syncIterator — Synchronise l'itérateur de pixel
- ImagickPixelIteratorException — La classe ImagickPixelIteratorException

- Exif — Informations Exif
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Exif
- GD — Traitement des images et GD
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions GD et images
  - GdImage — La classe GdImage
  - GdFont — La classe GdFont
- Gmagick
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Gmagick — La classe Gmagick
  - GmagickDraw — La classe GmagickDraw
  - GmagickPixel — La classe GmagickPixel
- ImageMagick — Traitement des images (ImageMagick)
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Imagick — La classe Imagick
  - ImagickDraw — La classe ImagickDraw
  - ImagickDrawException — La classe ImagickDrawException
  - ImagickException — La classe ImagickException
  - ImagickKernel — La classe ImagickKernel
  - ImagickKernelException — La classe ImagickKernelException
  - ImagickPixel — La classe ImagickPixel
  - ImagickPixelException — La classe ImagickPixelException
  - ImagickPixelIterator — La classe ImagickPixelIterator
  - ImagickPixelIteratorException — La classe ImagickPixelIteratorException

# Extensions relatives aux emails

# IMAP, POP3 et NNTP

# Introduction

Avertissement

Cette extension est OBSOLÈTE et SÉPARÉE à partir de PHP 8.4.0.

Ces fonctions permettent d'utiliser le protocole IMAP, mais aussi les protocoles NNTP, POP3 et les boîtes aux lettres locales.

Cependant, il faut être prudent, car quelques fonctions IMAP ne fonctionnent pas correctement avec le protocole POP.

Avertissement

L'extension IMAP n'est pas sécurisée au niveau des threads ; elle ne doit pas être utilisée avec ZTS.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution
- Types de ressources

## Pré-requis

Cette extension requiert la bibliothèque C cliente. Téléchargez cette dernière version à » https://github.com/uw-imap/imap et compilez-la.

Il est important de ne pas copier les fichiers sources IMAP directement dans le dossier d'inclusion système sous peine de conflits. À la place de cela, créez un nouveau dossier dans le dossier d'inclusion système, comme /usr/local/imap-2000b/ (le chemin et le nom dépendent de la configuration et de la version d'IMAP) et dans ce nouveau dossier, créez les dossiers nommés lib/ et include/. Depuis le dossier c-client des sources IMAP, copiez tous les fichiers *.h dans le dossier include/ et tous les fichiers *.c dans le dossier lib/. Additionnellement, lorsqu'on compile IMAP, un fichier nommé c-client.a est créé. Mettez-le également dans le dossier lib/ mais renommez-le en libc-client.a.

> Note:

> Pour compiler la bibliothèque C cliente avec SSL et/ou avec le support Kerberos, consulter la doc fournie dans la distribution.

> Note: Sur Mandrake Linux, la bibliothèque IMAP (libc-client.a) est compilée sans le support Kerberos. Une version séparée avec SSL (client-PHP4.a) est installée. La bibliothèque doit être recompilée pour ajouter le support Kerberos.

## Installation

## PHP 8.4

Cette extension a été déplacée dans le module » PECL et ne sera plus intégrée dans PHP à partir de PHP 8.4.0

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/imap.

## PHP < 8.4

Pour que ces fonctions fonctionnent, il faut compiler PHP avec --with-imap[=DIR], où DIR est le préfixe d'installation de c-client. Dans notre exemple ci-dessus, l'on utiliserait --with-imap=/usr/local/imap-2000b. Cet emplacement dépend de l'endroit où l'on a créé ce répertoire, comme indiqué dans la description précédente. Les utilisateurs de Windows peuvent inclure la DLL php_imap.dll dans php.ini.

> Note: Selon la manière dont c-client a été configuré, il serait possible d'également avoir besoin d'ajouter --with-imap-ssl=/path/to/openssl/ et/ou --with-kerberos=/path/to/kerberos à la ligne de configuration de PHP.

Avertissement

L'extension IMAP n'est pas thread-safe ; elle ne doit pas être utilisée avec des builds ZTS.

Avertissement

Les extensions IMAP, recode et YAZ ne peuvent être utilisées simultanément puisqu'elles utilisent un symbole interne commun. Note: Yaz 2.0 et supérieur ne souffre plus de ce problème.

## Configuration à l'exécution

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

IMAP Options de configuration
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
imap.enable_insecure_rsh | "0" | `INI_SYSTEM` | Disponible à partir de PHP 7.1.25, 7.2.13 et 7.3.0. Auparavant, c'était activé implicitement.

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`imap.enable_insecure_rsh` bool

  Établir une connexion à un serveur peut invoquer des commandes rsh ou ssh, sauf si cette option php.ini est désactivée.

  Avertissement

  Ni PHP ni la bibliothèque IMAP ne filtrent les noms des boîtes aux lettres avant de les passer aux commandes rsh ou ssh, par conséquent passer des données non fiables à cette fonction sans désactiver cette option php.ini est dangereux.

## Types de ressources

Antérieur à PHP 8.1.0, cette extension utilisait un type de ressource `imap` retourné par imap_open() qui fait référence à un flux IMAP ouvert.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`NIL` (int)
  Obsolète à partir de PHP 8.1.0.
`OP_DEBUG` (int)
`OP_READONLY` (int)
  Ouvre une boîte aux lettres en lecture seule
`OP_ANONYMOUS` (int)
  Ne pas utiliser, ou modifier le fichier .newsrc pour les news, (NNTP uniquement).
`OP_SHORTCACHE` (int)
`OP_SILENT` (int)
`OP_PROTOTYPE` (int)
`OP_HALFOPEN` (int)
  Pour les noms IMAP et NNTP, ouvre une connexion mais n'ouvre pas une boîte aux lettres.
`OP_EXPUNGE` (int)
`OP_SECURE` (int)
`CL_EXPUNGE` (int)
  purger automatiquement la boîte aux lettres lors de l'appel de imap_close()
`FT_UID` (int)
  Le paramètre est un UID.
`FT_PEEK` (int)
  Ne pas lever le drapeau \Seen (Message lu) s'il n'est pas déjà levé.
`FT_NOT` (int)
`FT_INTERNAL` (int)
  La chaîne renvoyée est au format interne, et ne va pas canoniser les CRLF.
`FT_PREFETCHTEXT` (int)
`ST_UID` (int)
  la séquence contient des UID au lieu de numéros de séquence
`ST_SILENT` (int)
`ST_SET` (int)
`CP_UID` (int)
  La séquence de nombres contient des UID
`CP_MOVE` (int)
  Efface les messages après copie avec imap_mail_copy()
`SE_UID` (int)
  Retourne des UID à la place de numéros
`SE_FREE` (int)
`SE_NOPREFETCH` (int)
  Ne pas prétélécharger les messages trouvés
`SO_FREE` (int)
`SO_NOSERVER` (int)
`SA_MESSAGES` (int)
`SA_RECENT` (int)
`SA_UNSEEN` (int)
`SA_UIDNEXT` (int)
`SA_UIDVALIDITY` (int)
`SA_ALL` (int)
`LATT_NOINFERIORS` (int)
  Cette boîte aux lettres n'a pas d'"enfants" (il n'y a plus de boîtes aux lettres en dessous de celle-ci).
`LATT_NOSELECT` (int)
  Ceci est juste un container, pas une boîte aux lettres (il n'est pas possible de l'ouvrir).
`LATT_MARKED` (int)
  Cette boîte aux lettres est marquée. Utilisé uniquement avec UW-IMAPD.
`LATT_UNMARKED` (int)
  Cette boîte aux lettres n'est pas marquée. Utilisé uniquement avec UW-IMAPD.
`LATT_REFERRAL` (int)
  Ce conteneur a une référence vers une boîte aux lettres distante.
`LATT_HASCHILDREN` (int)
  Cette boîte aux lettres a des inférieurs sélectionnables.
`LATT_HASNOCHILDREN` (int)
  Cette boîte aux lettres n'a pas d'inférieurs sélectionnables.
`SORTDATE` (int)
  Critère de tri pour imap_sort() : Date du message
`SORTARRIVAL` (int)
  Critère de tri pour imap_sort() : Date d'arrivée
`SORTFROM` (int)
  Critère de tri pour imap_sort() : Nom de la première boîte aux lettres de l'adresse d'origine (From address)
`SORTSUBJECT` (int)
  Critère de tri pour imap_sort() : Sujet du message
`SORTTO` (int)
  Critère de tri pour imap_sort() : Nom de la première boîte aux lettres de destination (To address)
`SORTCC` (int)
  Critère de tri pour imap_sort() : Nom de la boîte aux lettres de copie cachée (cc address)
`SORTSIZE` (int)
  Critère de tri pour imap_sort() : Taille du message en octets
`TYPETEXT` (int)
  Type de corps primaire : texte non formaté
`TYPEMULTIPART` (int)
  Type de corps primaire : plusieurs parties
`TYPEMESSAGE` (int)
  Type de corps primaire : message encapsulé
`TYPEAPPLICATION` (int)
  Type de corps primaire : données d'application
`TYPEAUDIO` (int)
  Type de corps primaire : audio
`TYPEIMAGE` (int)
  Type de corps primaire : image statique
`TYPEVIDEO` (int)
  Type de corps primaire : vidéo
`TYPEMODEL` (int)
  Type de corps primaire : modèle
`TYPEOTHER` (int)
  Type de corps primaire : inconnu
`ENC7BIT` (int)
  Encodage du corps : données sémantiques SMTP 7 bits
`ENC8BIT` (int)
  Encodage du corps : données sémantiques SMTP 8 bits
`ENCBINARY` (int)
  Encodage du corps : données binaires 8 bits
`ENCBASE64` (int)
  Encodage du corps : données encodées en base-64
`ENCQUOTEDPRINTABLE` (int)
  Encodage du corps : données 8-7-bit lisibles par l'Homme
`ENCOTHER` (int)
  Encodage du corps : inconnu
`IMAP_OPENTIMEOUT` (int)
`IMAP_READTIMEOUT` (int)
`IMAP_WRITETIMEOUT` (int)
`IMAP_CLOSETIMEOUT` (int)
`IMAP_GC_ELT` (int)
  Collecte de la mémoire, suppression des caches d'éléments de message.
`IMAP_GC_ENV` (int)
  Collecte de la mémoire, suppression des enveloppes et corps.
`IMAP_GC_TEXTS` (int)
  Collecte de la mémoire, suppression des textes.

# Fonctions IMAP

# Voir aussi

Ce document ne peut entrer dans les détails de tous les sujets abordés. Plus d'informations sont disponibles avec la documentation de la bibliothèque C (docs/internal.txt) ainsi que les RFC suivantes :

- » RFC2821 : `Simple Mail Transfer Protocol` (SMTP).
- » RFC2822 : `Standard for ARPA internet text messages`.
- » RFC2060 : `Internet Message Access Protocol` (IMAP) Version 4rev1.
- » RFC1939 : `Post Office Protocol Version 3` (POP3).
- » RFC977 : `Network News Transfer Protocol` (NNTP).
- » RFC2076 : `Common Internet Message Headers`.
- » RFC2045 , » RFC2046 , » RFC2047 , » RFC2048 et » RFC2049: `Multipurpose Internet Mail Extensions` (MIME).

Une étude approfondie est aussi disponible dans les livres suivants (en anglais) : » `Programming Internet Email` par David Wood et » Managing IMAP par Dianna Mullet & Kevin Mullet.

# imap_8bit

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_8bit — Convertit une chaîne à 8 bits en une chaîne encodée en Quoted-Printable

### Description

function imap_8bit(string `$string`): string|false

Convertit la chaîne à 8 bits en une chaîne encodée en Quoted-Printable (selon la » RFC 2045, Section 6.7).

### Liste de paramètres

`string`

  La chaîne 8 bits à convertir

### Valeurs de retour

Retourne une chaîne encodée en Quoted-Printable, ou `false` si une erreur survient.

### Voir aussi

- imap_qprint() - Convertit une chaîne à guillemets en une chaîne à 8 bits

# imap_alerts

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_alerts — Retourne toutes les alertes

### Description

function imap_alerts(): array|false

Retourne un tableau de tous les messages d'alerte IMAP générés depuis le dernier appel à imap_alerts() ou depuis le début de la page.

Lorsque imap_alerts() est appelée, la pile d'alertes est vidée. Les spécifications IMAP requièrent que ces messages soient passés à l'utilisateur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un tableau contenant tous les messages d'alerte IMAP générés ou `false` si aucun message d'alerte n'est disponible.

### Voir aussi

- imap_errors() - Retourne toutes les erreurs IMAP survenues

# imap_append

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_append — Ajoute un message dans une boîte aux lettres

### Description

function imap_append(
IMAP\Connection `$imap`,
string `$folder`,
string `$message`,
?string `$options` = `null`,
?string `$internal_date` = `null`
): bool

Ajoute un `message` au `folder` spécifié.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`folder`

  Le nom de la boîte aux lettres, voir la documentation sur la fonction imap_open() pour plus d'informations

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`message`

  Le message à ajouter, sous la forme d'une chaîne de caractères

  Lors des échanges avec le serveur Cyrus IMAP, il faudra utiliser "\r\n" comme terminaison de ligne, à la place de "\n" ou l'opération échouera.

`options`

  Si fourni, le paramètre `options` sera également écrit dans la boîte `folder`

`internal_date`

  Si ce paramètre est défini, il mettra les INTERNALDATE sur le message joint. Le paramètre doit être une chaîne de date qui est conforme aux spécifications du rfc2060 pour une valeur date_time.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.
8.0.0 | `options` et `internal_date` sont désormais nullable.

### Exemples

Exemple #1 Exemple avec imap_append()

    <?php
    $imap = imap_open("{imap.example.org}INBOX.Drafts", "username", "password");

    $check = imap_check($imap);
    echo "Msg Count before append: ". $check->Nmsgs . "\n";

    imap_append($imap, "{imap.example.org}INBOX.Drafts"
                       , "From: me@example.com\r\n"
                       . "To: you@example.com\r\n"
                       . "Subject: test\r\n"
                       . "\r\n"
                       . "Ceci est un message de test. Ignorez le.\r\n"
                       );

    $check = imap_check($imap);
    echo "Nombre de messages après ajout : ". $check->Nmsgs . "\n";

    imap_close($imap);
    ?>

# imap_base64

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_base64 — Décode un texte encodé en BASE64

### Description

function imap_base64(string `$string`): string|false

Décode le texte `string` encodé en BASE64.

### Liste de paramètres

`string`

  Le texte encodé.

### Valeurs de retour

Retourne le texte décodé, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Voir aussi

- imap_binary() - Convertit une chaîne à 8 bits en une chaîne à base64
- base64_encode() - Encode une chaîne en MIME base64
- base64_decode() - Décode une chaîne en MIME base64
- » RFC2045, Section 6.8

# imap_binary

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_binary — Convertit une chaîne à 8 bits en une chaîne à base64

### Description

function imap_binary(string `$string`): string|false

Convertit la chaîne à 8 bits `string` en une chaîne à base64 (selon la » RFC2045, Section 6.8).

### Liste de paramètres

`string`

  La chaîne 8 bits

### Valeurs de retour

Retourne la chaîne encodée en base64, ou `false` si une erreur survient.

### Voir aussi

- imap_base64() - Décode un texte encodé en BASE64

# imap_body

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_body — Lit le corps d'un message

### Description

function imap_body(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

imap_body() retourne le corps du message numéro `message_num` de la boîte aux lettres courante.

imap_body() va retourner une copie brute du corps du message. Pour extraire les sous-parties MIME du message, il convient d'utiliser imap_fetchstructure() pour analyser la structure, et imap_fetchbody() pour extraire une copie d'une des sous-parties.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_num`

  Le numéro du message

`flags`

  Le paramètre `flags` optionnel est un masque qui peut contenir les valeurs suivantes :

  - `FT_UID` - `message_num` est un UID
  - `FT_PEEK` - Ne pas lever le drapeau \Seen (Message lu) s'il n'est pas déjà levé.
  - `FT_INTERNAL` - La chaîne renvoyée est au format interne, et ne va pas canoniser les CRLF.

### Valeurs de retour

Retourne le corps du message spécifié, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

# imap_bodystruct

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_bodystruct — Lit la structure d'une section du corps d'un mail

### Description

function imap_bodystruct(IMAP\Connection `$imap`, int `$message_num`, string `$section`): stdClass|false

Lit la structure d'une section spécifiée du corps d'un mail.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_num`

  Le numéro du message

`section`

  La section du corps à lire

### Valeurs de retour

Retourne les informations dans un objet, ou `false` si une erreur survient. Pour une description détaillée de la structure de l'objet ainsi que de ses propriétés, se reporter à la fonction imap_fetchstructure().

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_fetchstructure() - Lit la structure d'un message

# imap_check

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_check — Vérifie la boîte aux lettres courante

### Description

function imap_check(IMAP\Connection `$imap`): stdClass|false

Vérifie les informations de la boîte aux lettres courante.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.

### Valeurs de retour

Retourne les informations dans un objet contenant les propriétés suivantes :

- `Date` - Date de dernière modification du contenu de la boîte aux lettres en accord avec la » RFC2822
- `Driver` - protocole utilisé pour accéder à la boîte aux lettres: POP3, IMAP, NNTP.
- `Mailbox` - nom de la boîte aux lettres
- `Nmsgs` - nombre de messages de la boîte aux lettres
- `Recent` - nombre de messages récents de la boîte aux lettres

Retourne `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_check()

    <?php

    $imap = imap_check($imap_stream);
    var_dump($imap);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    object(stdClass)(5) {
      ["Date"]=>
      string(37) "Wed, 10 Dec 2003 17:56:54 +0100 (CET)"
      ["Driver"]=>
      string(4) "imap"
      ["Mailbox"]=>
      string(54)
      "{www.example.com:143/imap/user="foo@example.com"}INBOX"
      ["Nmsgs"]=>
      int(1)
      ["Recent"]=>
      int(0)
    }

# imap_clearflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_clearflag_full — Supprime un flag (drapeau) sur un message

### Description

function imap_clearflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

imap_clearflag_full() efface le flag `flag` dans les messages de la séquence `sequence`, du flux imap `stream`.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`sequence`

  Une séquence de numéro de messages. Il est possible d'énumérer les messages désirés avec la syntaxe `X,Y`, ou récupérer tous les messages contenus dans un intervalle, avec la syntaxe `X:Y`

`flag`

  Les flags `flag` qu'il est possible d'effacer sont "\\Seen", "\\Answered", "\\Flagged", "\\Deleted" et "\\Draft" (tels que définis dans la » RFC2060)

`options`

  `options` est un masque de bits, qui accepte uniquement la valeur suivante :

  - `ST_UID` - la séquence contient des UID au lieu de numéros de séquence

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Lance une exception ValueError si le paramètre `options` est invalide.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.
8.0.0 | Une exception ValueError est désormais lancée pour des valeurs invalides du paramètre `options`. Auparavant, un avertissement était émis et la fonction retournait `false`.

### Voir aussi

- imap_setflag_full() - Positionne un drapeau sur un message

# imap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_close — Termine un flux IMAP

### Description

function imap_close(IMAP\Connection `$imap`, int `$flags` = 0): true

Termine un flux IMAP.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`flags`

  S'il est défini à `CL_EXPUNGE`, la fonction effectuera une purge automatique de la boîte aux lettres avant de la fermer, supprimant tous les messages marqués pour l'effacement. Il est possible d'effectuer la même chose avec la fonction imap_expunge()

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Lance une exception ValueError si le paramètre `flags` est invalide.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.
8.0.0 | Une exception ValueError est désormais lancée pour des valeurs de paramètre `flags` invalides. Auparavant, un avertissement était émis et la fonction retournait `false`.

### Voir aussi

- imap_open() - Ouvre un flux IMAP vers une boîte aux lettres

# imap_create

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_create — Alias de imap_createmailbox()

### Description

Cette fonction est un alias de : imap_createmailbox().

# imap_createmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_createmailbox — Crée une nouvelle boîte aux lettres

### Description

function imap_createmailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Crée une nouvelle boîte aux lettres nommée `mailbox`.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`mailbox`

  Le nom de la boîte aux lettres, voir la documentation sur la fonction imap_open() pour plus d'informations. Les noms contenant des caractères internationaux doivent être encodés par la fonction imap_utf7_encode()

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_createmailbox()

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
         or die("connexion impossible : " . imap_last_error());

    $name1 = "phpnewbox";
    $name2 = imap_utf7_encode("phpnewböx"); // phpnewb&w7Y-x

    $newname = $name1;

    echo "Le nouveau nom sera '$name1'<br />\n";

    // Nous allons créer maintenant une nouvelle boîte aux lettres "phptestbox"
    // dans votre dossier inbox, vérifier son état et, finalement, la supprimer
    // pour remettre votre inbox dans son état initial.

    if (@imap_createmailbox($mbox, imap_utf7_encode("{imap.example.org}INBOX.$newname"))) {
        $status = @imap_status($mbox, "{imap.example.org}INBOX.$newname", SA_ALL);
        if ($status) {
            echo "Votre nouvelle boîte '$name1' est dans l'état suivant :<br />\n";
            echo "Messages :   " . $status->messages    . "<br />\n";
            echo "Récent :     " . $status->recent      . "<br />\n";
            echo "Non lus :     " . $status->unseen      . "<br />\n";
            echo "UIDnext :    " . $status->uidnext     . "<br />\n";
            echo "UIDvalidity :" . $status->uidvalidity . "<br />\n";

            if (imap_renamemailbox($mbox, "{imap.example.org}INBOX.$newname", "{imap.example.org}INBOX.$name2")) {
                echo "renommage de la boîte aux lettres '$name1' en '$name2'<br />\n";
                $newname = $name2;
            } else {
                echo "imap_renamemailbox sur la nouvelle boîte aux lettres a échoué : " . imap_last_error() . "<br />\n";
            }
        } else {
            echo "imap_status sur la nouvelle boîte aux lettres a échoué : " . imap_last_error() . "<br />\n";
        }

        if (@imap_deletemailbox($mbox, "{imap.example.org}INBOX.$newname")) {
            echo "nouvelle boîte aux lettres supprimée pour remettre tout en état<br />\n";
        } else {
            echo "imap_deletemailbox sur la nouvelle boîte aux lettres a échoué : " . implode("<br />\n", imap_errors()) . "<br />\n";
        }

    } else {
        echo "Impossible de créer une nouvelle boîte aux lettres : " . implode("<br />\n", imap_errors()) . "<br />\n";
    }

    imap_close($mbox);
    ?>

### Voir aussi

- imap_renamemailbox() - Renomme une boîte aux lettres
- imap_deletemailbox() - Efface une boîte aux lettres

# imap_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_delete — Marque le message pour l'effacement, dans la boîte aux lettres courante

### Description

function imap_delete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Marque les messages `message_nums` pour l'effacement. L'effacement réel n'interviendra que lors de l'appel de la fonction imap_expunge() ou de imap_close() avec le paramètre optionnel `CL_EXPUNGE`.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_nums`

  Une chaîne de caractères représentant un ou plusieurs messages dans un style de format d'une séquence IMAP4 (`"n"`, `"n:m"`, ou une combinaison de ceci, délimité par des virgules).

`flags`

  Il est possible de le définir à `FT_UID` qui demande à la fonction de traiter l'argument `message_nums` comme un `UID`.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Lance une exception ValueError si le paramètre `flags` est invalide.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.
8.0.0 | Une exception ValueError est désormais lancée pour des valeurs de paramètre `flags` invalides. Auparavant, un avertissement était émis et la fonction retournait `false`.

### Exemples

Exemple #1 Exemple avec imap_delete()

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
        or die("Connexion impossible : " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);
    echo "Nombre de messages avant effacement : " . $check->Nmsgs . "<br />\n";

    imap_delete($mbox, 1);

    $check = imap_mailboxmsginfo($mbox);
    echo "Nombre de messages après effacement : " . $check->Nmsgs . "<br />\n";

    imap_expunge($mbox);

    $check = imap_mailboxmsginfo($mbox);
    echo "Nombre de messages après imap_expunge : " . $check->Nmsgs . "<br />\n";

    imap_close($mbox);
    ?>

### Notes

> Note:

> Les boîtes aux lettres IMAP n'ont pas les flags de leurs messages sauvegardés entre les connexions, aussi la fonction imap_expunge() doit être appelée pendant la même connexion pour que les messages marqués pour effacement soient réellement purgés.

### Voir aussi

- imap_undelete() - Enlève la marque d'effacement d'un message
- imap_expunge() - Efface tous les messages marqués pour l'effacement
- imap_close() - Termine un flux IMAP

# imap_deletemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_deletemailbox — Efface une boîte aux lettres

### Description

function imap_deletemailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Efface la boîte aux lettres spécifiée.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`mailbox`

  Le nom de la boîte aux lettres, voir la documentation sur la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_createmailbox() - Crée une nouvelle boîte aux lettres
- imap_renamemailbox() - Renomme une boîte aux lettres
- imap_open() - Ouvre un flux IMAP vers une boîte aux lettres pour le format `mbox`

# imap_errors

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_errors — Retourne toutes les erreurs IMAP survenues

### Description

function imap_errors(): array|false

Cette fonction retourne un tableau de tous les messages d'erreurs IMAP générés depuis le dernier appel à imap_errors() ou depuis le début de la page.

Lorsque imap_errors() est appelée, la pile d'erreurs est vidée.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Cette fonction retourne un tableau contenant tous les messages d'erreur IMAP générés depuis le dernier appel à la fonction imap_errors() ou depuis le début de la page. Retourne `false` si aucun message d'erreur n'est disponible.

### Voir aussi

- imap_last_error() - Retourne la dernière erreur survenue
- imap_alerts() - Retourne toutes les alertes

# imap_expunge

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_expunge — Efface tous les messages marqués pour l'effacement

### Description

function imap_expunge(IMAP\Connection `$imap`): true

Efface tous les messages marqués pour l'effacement par imap_delete(), imap_mail_move(), ou imap_setflag_full().

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

# imap_fetch_overview

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetch_overview — Lit le sommaire des en-têtes de messages

### Description

function imap_fetch_overview(IMAP\Connection `$imap`, string `$sequence`, int `$flags` = 0): array|false

Lit les en-têtes des courriers électroniques de la séquence `sequence` et retourne un sommaire de leur contenu.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`sequence`

  Une description de la séquence du message. Il est possible d'énumérer les messages désirés avec la syntaxe `X,Y`, ou récupérer tous les messages d'un intervalle, avec la syntaxe `X:Y`

`flags`

  `sequence` va contenir une séquence d'indice de message ou d'UID, si `flags` contient `FT_UID`.

### Valeurs de retour

Retourne un tableau d'objets décrivant l'en-tête de chaque message. L'objet ne définira une propriété que si elle existe. Les propriétés possibles sont :

- `subject` : le sujet du message
- `from` : l'expéditeur
- `to` : le destinataire
- `date` : la date d'expédition
- `message_id` : l'identification du message
- `references` : la référence sur l'id de ce message
- `in_reply_to` : la réponse à cet identifiant de message
- `size` : la taille en octets
- `uid` : UID du message dans la boîte aux lettres
- `msgno` : le numéro de séquence du message dans la boîte
- `recent` : ce message est récent
- `flagged` : ce message est marqué
- `answered` : ce message a donné lieu à une réponse
- `deleted` : ce message est marqué pour l'effacement
- `seen` : ce message est déjà lu
- `draft` : ce message est un brouillon
- `udate` : l'horodatage UNIX de l'heure d'arrivée

La fonction retourne `false` en cas d'échec.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_fetch_overview()

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password")
         or die("Connexion impossible : " . imap_last_error());

    $MC = imap_check($mbox);

    // Récupère le sommaire pour tous les messages contenus dans INBOX
    $result = imap_fetch_overview($mbox,"1:{$MC->Nmsgs}",0);
    foreach ($result as $overview) {
        echo "#{$overview->msgno} ({$overview->date}) - From: {$overview->from}
        {$overview->subject}\n";
    }
    imap_close($mbox);
    ?>

### Voir aussi

- imap_fetchheader() - Retourne l'en-tête d'un message

# imap_fetchbody

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchbody — Retourne une section extraite du corps d'un message

### Description

function imap_fetchbody(
IMAP\Connection `$imap`,
int `$message_num`,
string `$section`,
int `$flags` = 0
): string|false

Récupère une section particulière du corps des messages spécifiés. Les parties du corps ne sont pas décodées par cette fonction.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_num`

  Le numéro du message

`section`

  Le numéro de la section. C'est une chaîne d'entiers, délimités par un point qui correspondent aux index dans la liste des sections du message, tel que prévu par la spécification IMAP4.

`flags`

  L'option imap_fetchbody() est un masque qui peut contenir les valeurs suivantes :

  - `FT_UID` - `message_num` est un UID
  - `FT_PEEK` - Ne pas lever le drapeau \Seen (Message lu) s'il n'est pas déjà levé.
  - `FT_INTERNAL` - La chaîne renvoyée est au format interne, et ne va pas canoniser les CRLF.

### Valeurs de retour

Retourne une section particulière du corps des messages spécifiés, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_savebody() - Sauvegarde une partie spécifique du corps dans un fichier
- imap_fetchstructure() - Lit la structure d'un message

# imap_fetchheader

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchheader — Retourne l'en-tête d'un message

### Description

function imap_fetchheader(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

imap_fetchheader() retourne l'en-tête brut et complet » RFC2822 du message `msgno`, sous la forme d'une chaîne.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_num`

  Le numéro du message

`flags`

  Les options possibles sont :

  - `FT_UID` - `message_num` est un UID
  - `FT_INTERNAL` - La chaîne renvoyée est au format "internal" , c'est-à-dire sans canonisation des CRLF
  - `FT_PREFETCHTEXT` - RFC822.TEXT doit être pré téléchargé en même temps que l'en-tête. Cela réduit le RTT sur une connexion IMAP, si le message complet est souhaité. (p. ex. dans une opération de sauvegarde dans un fichier).

### Valeurs de retour

Retourne l'en-tête du message spécifié, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_fetch_overview() - Lit le sommaire des en-têtes de messages

# imap_fetchmime

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

imap_fetchmime — Récupère les en-têtes MIME pour une section particulière du message

### Description

function imap_fetchmime(
IMAP\Connection `$imap`,
int `$message_num`,
string `$section`,
int `$flags` = 0
): string|false

Récupère les en-têtes MIME pour une section particulière du corps d'un message spécifique.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_num`

  Le numéro du message.

`section`

  Le numéro de la section. C'est une chaîne d'entiers délimités par un point qui représente l'index de la liste des sections du corps du message, tel que spécifié par l'IMAP4.

`flags`

  Un masque d'une ou plusieurs options suivantes :

  - `FT_UID` - Le paramètre `message_num` est un UID.
  - `FT_PEEK` - Ne pas placer le drapeau \Seen s'il n'est pas déjà défini.
  - `FT_INTERNAL` - La chaîne retournée est en un format interne, et ne sera pas canonisée en CRLF.

### Valeurs de retour

Retourne les en-têtes MIME d'une section particulière du corps du message spécifié, sous la forme d'une chaîne de caractères, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_fetchbody() - Retourne une section extraite du corps d'un message
- imap_fetchstructure() - Lit la structure d'un message
- imap_fetchheader() - Retourne l'en-tête d'un message

# imap_fetchstructure

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchstructure — Lit la structure d'un message

### Description

function imap_fetchstructure(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): stdClass|false

imap_fetchstructure() lit la structure du message `msg_number`.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_num`

  Le numéro du message

`flags`

  Ce paramètre optionnel n'a qu'une seule option, `FT_UID`, qui demande à la fonction de traiter l'argument `message_num` comme un `UID`.

### Valeurs de retour

Retourne un objet dont les propriétés sont listées dans la table ci-dessous, ou `false` si une erreur survient.

Objet retourné par imap_fetchstructure()
type | Type primaire de corps
encoding | Codage de transfert du corps
ifsubtype | `true` s'il y a une chaîne de sous type
subtype | sous type MIME
ifdescription | `true` s'il y a une chaîne de description
description | Chaîne de description du contenu
ifid | `true` s'il y a une chaîne d'identification
id | Chaîne d'identification
lines | Nombre de lignes
bytes | Nombre d'octets
ifdisposition | `true` s'il y a une chaîne de disposition
disposition | Chaîne de disposition
ifdparameters | `true` s'il y a un tableau de paramètres dparameters
dparameters | tableau d'objets où chaque objet a une propriété `"attribute"` et une propriété `"value"` correspondant aux paramètres d'en-têtes `Content-disposition` MIME.
ifparameters | `true` si le tableau de paramètres existe
parameters | Tableau d'objets où chacun a une propriété `"attribute"` et une propriété `"value"`.
parts | Tableau d'objets décrivant chaque partie MIME du message

Type primaire de corps (peut varier suivant la bibliothèque utilisée)
Valeur | Type | Constante
--- | --- | ---
0 | texte | TYPETEXT
1 | multipart | TYPEMULTIPART
2 | message | TYPEMESSAGE
3 | application | TYPEAPPLICATION
4 | audio | TYPEAUDIO
5 | image | TYPEIMAGE
6 | vidéo | TYPEVIDEO
7 | modèle | TYPEMODEL
8 | autre | TYPEOTHER

Codage de transfert (peut varier suivant la bibliothèque utilisée)
Valeur | Type | Constante
--- | --- | ---
0 | 7 bit | ENC7BIT
1 | 8 bit | ENC8BIT
2 | Binaire | ENCBINARY
3 | Base 64 | ENCBASE64
4 | Cité imprimable | ENCQUOTEDPRINTABLE
5 | Autre | ENCOTHER

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_fetchbody() - Retourne une section extraite du corps d'un message
- imap_bodystruct() - Lit la structure d'une section du corps d'un mail

# imap_fetchtext

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchtext — Alias de imap_body()

### Description

Cette fonction est un alias de : imap_body().

# imap_gc

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_gc — Efface le cache IMAP

### Description

function imap_gc(IMAP\Connection `$imap`, int `$flags`): true

Supprime toutes les entrées d'un type donné dans le cache IMAP.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`flags`

  Indique le type de cache à purger. Cela peut être la combinaison des constantes suivantes : `IMAP_GC_ELT` (cache des éléments de message), `IMAP_GC_ENV` (enveloppe et corps), `IMAP_GC_TEXTS` (textes).

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Lance une exception ValueError si le paramètre `flags` est invalide.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.
8.0.0 | Une exception ValueError est désormais lancée pour des valeurs de paramètre `flags` invalides. Auparavant, un avertissement était émis et la fonction retournait `false`.

### Exemples

Exemple #1 Exemple avec imap_gc()

    <?php

    $mbox = imap_open("{imap.example.org:143}", "username", "password");

    imap_gc($mbox, IMAP_GC_ELT);

    ?>

# imap_get_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_get_quota — Lit les quotas des boîtes aux lettres ainsi que des statistiques sur chacune d'elles

### Description

function imap_get_quota(IMAP\Connection `$imap`, string `$quota_root`): array|false

Lit les quotas des boîtes aux lettres ainsi que des statistiques sur chacune d'elles.

Pour une version utilisateur, non administrateur, de cette fonction, se reporter à la fonction imap_get_quotaroot().

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`quota_root`

  `quota_root` doit être de la forme : "`user.nom`", où "nom" est le nom de la boîte aux lettres que l'on souhaite analyser.

### Valeurs de retour

Retourne un tableau contenant les valeurs de quota et courante de la boîte aux lettres `quota_root`. Le quota représente la taille maximale de la boîte aux lettres. La valeur courante est l'espace actuellement utilisé par la boîte aux lettres. imap_get_quota() retourne `false` en cas d'échec.

À partir de PHP 4.3, la fonction reflète plus fidèlement les fonctionnalités édictées par la » RFC2087. Le tableau retourné a changé pour supporter un nombre illimité de ressources retournées (c.-à-d. messages ou sous-dossiers) avec chaque ressource nommée qui est identifiée par une clé. Chaque clé contient alors un autre tableau avec l'utilisation et le quota. L'exemple ci-dessous montre comment l'utiliser.

Pour des raisons de compatibilité, la méthode d'accès originale est toujours disponible, mais il est recommandé de l'abandonner.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_get_quota()

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("Impossible de se connecter : " . imap_last_error());

    $quota_value = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_value)) {
        echo "Niveau d'utilisation : " . $quota_value['usage'];
        echo "Quota : " . $quota_value['limit'];
    }

    imap_close($mbox);
    ?>

Exemple #2 Exemple avec imap_get_quota() 4.3 ou supérieur

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("Impossible de se connecter : " . imap_last_error());

    $quota_values = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_values)) {
       $storage = $quota_values['STORAGE'];
       echo "Utilisation actuelle de la capacité de stockage : " .  $storage['usage'];
       echo "Quota actuel de stockage  : " .  $storage['limit'];

       $message = $quota_values['MESSAGE'];
       echo "Niveau d'utilisation de MESSAGE  : " .  $message['usage'];
       echo "Quota de MESSAGE : " .  $message['limit'];

       /* ...  */
    }

    imap_close($mbox);
    ?>

### Notes

imap_get_quota() ne fonctionne actuellement qu'avec les bibliothèques c-client2000.

Le `imap` donné doit être ouvert en tant qu'administrateur mail, sinon cette fonction échoue.

### Voir aussi

- imap_open() - Ouvre un flux IMAP vers une boîte aux lettres
- imap_set_quota() - Modifie le quota d'une boîte aux lettres
- imap_get_quotaroot() - Lit les quotas de chaque utilisateur

# imap_get_quotaroot

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imap_get_quotaroot — Lit les quotas de chaque utilisateur

### Description

function imap_get_quotaroot(IMAP\Connection `$imap`, string `$mailbox`): array|false

Récupère les quotas de chaque utilisateur. La valeur limite représente l'espace limite alloué pour cet utilisateur pour l'utilisation de sa boîte aux lettres. La valeur de l'utilisation représente la taille actuelle de la boîte aux lettres.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`mailbox`

  `mailbox` doit être un nom de boîte aux lettres (c.-à-d. INBOX).

### Valeurs de retour

Retourne un tableau d'entiers, contenant les quotas de la boîte aux lettres de l'utilisateur. Toutes les valeurs sont représentées par une clé basée sur le nom de la boîte, et par un tableau représentant le niveau d'utilisation et les limites.

Cette fonction retourne `false` si une erreur est survenue, et un tableau de données si la réponse du serveur n'a pu être comprise.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_get_quotaroot()

    <?php
    $mbox = imap_open("{imap.example.org}", "kalowsky", "password", OP_HALFOPEN)
          or die("Connexion impossible : " . imap_last_error());

    $quota = imap_get_quotaroot($mbox, "INBOX");
    if (is_array($quota)) {
       $storage = $quota['STORAGE'];
       echo "STORAGE niveau d'utilisation : " .  $storage['usage'];
       echo "STORAGE taille limite : " .  $storage['limit'];

       $message = $quota['MESSAGE'];
       echo "MESSAGE niveau d'utilisation : " .  $message['usage'];
       echo "MESSAGE taille limite : " .  $message['limit'];

       /* ...  */

    }

    imap_close($mbox);
    ?>

### Notes

Cette fonction est uniquement accessible aux utilisateurs de la bibliothèque c-client2000 ou plus récente.

`imap` devrait être ouvert en tant que l'utilisateur dont la boîte mail que l'on veut vérifier.

### Voir aussi

- imap_open() - Ouvre un flux IMAP vers une boîte aux lettres
- imap_set_quota() - Modifie le quota d'une boîte aux lettres
- imap_get_quota() - Lit les quotas des boîtes aux lettres ainsi que des statistiques sur chacune d'elles

# imap_getacl

(PHP 5, PHP 7, PHP 8)

imap_getacl — Retourne le ACL pour la boîte aux lettres

### Description

function imap_getacl(IMAP\Connection `$imap`, string `$mailbox`): array|false

Récupère l'ACL pour la boîte aux lettres donnée.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`mailbox`

  Le nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails.

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

### Valeurs de retour

Retourne un tableau associatif sous la forme "folder" => "acl", ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_getacl()

    <?php

    print_r(imap_getacl($imap, 'user.joecool'));

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [asubfolder] => lrswipcda
        [anothersubfolder] => lrswipcda
    )

### Notes

Cette fonction n'est actuellement disponible que pour les utilisateurs de la bibliothèque `c-client2000` ou supérieure.

### Voir aussi

- imap_setacl() - Modifie le ACL de la boîte aux lettres

# imap_getmailboxes

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getmailboxes — Liste les boîtes aux lettres, et retourne les détails de chacune

### Description

function imap_getmailboxes(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Liste les boîtes aux lettres.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`reference`

  `reference` ne devrait être que le serveur sous la forme décrite dans imap_open()

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`pattern`
  Spécifie la position dans la hiérarchie des boîtes aux lettres, où il faut commencer à chercher.Il y a deux caractères spéciaux que vous pouvez utiliser dans `pattern` : '`*`' et '`%`'. '`*`' signifie : toutes les boîtes aux lettres. Si vous passez `pattern` comme '`*`', vous obtiendrez la liste complète des boîtes aux lettres de la hiérarchie. '`%`' signifie qu'on ne s'intéresse qu'au niveau courant. '`%`' passé à `pattern` ne retournera que les boîtes aux lettres de niveau supérieur; '`~/mail/%`' sous `UW_IMAPD` retournera toutes les boîtes aux lettres du dossier ~/mail directory, mais pas leurs enfants.

### Valeurs de retour

Retourne un tableau d'objets contenant les informations sur les boîtes aux lettres. Chaque objet possède un attribut de `name`, qui contient le nom complet de la boîte aux lettres, `delimiter` qui est le délimiteur hiérarchique et `attributes`. `attributes` est un masque de bits, qui contient :

- `LATT_NOINFERIORS` - Cette boîte aux lettres n'a pas d'"enfants" (il n'y a plus de boîtes aux lettres en dessous de celle-ci) et ne peut en contenir aucun. Un appel à la fonction imap_createmailbox() ne fonctionnera pas sur cette boîte.

- `LATT_NOSELECT` - Ceci est juste un container, pas une boîte aux lettres (il n'est pas possible de l'ouvrir).

- `LATT_MARKED` - Cette boîte aux lettres est marquée. Ceci signifie qu'elle peut contenir des nouveaux messages depuis la dernière fois qu'elle a été vérifiée. Ce marqueur n'est pas fourni avec tous les serveurs IMAP.

- `LATT_UNMARKED` - Cette boîte aux lettres n'est pas marquée et ne contient pas de nouveaux messages. Si `MARKED` ou `UNMARKED` est fourni, il est possible de supposer que le serveur IMAP supporte cette fonctionnalité pour cette boîte aux lettres.

- `LATT_REFERRAL` - Ce conteneur a une référence vers une boîte aux lettres distante.

- `LATT_HASCHILDREN` - Cette boîte aux lettres a des inférieurs sélectionnables.

- `LATT_HASNOCHILDREN` - Cette boîte aux lettres n'a pas d'inférieurs sélectionnables.

Retourne `false` en cas d'échec.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_getmailboxes()

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("Connexion impossible : " . imap_last_error());

    $list = imap_getmailboxes($mbox, "{imap.example.org}", "*");
    if (is_array($list)) {
        foreach ($list as $key => $val) {
            echo "($key) ";
            echo imap_utf7_decode($val->name) . ",";
            echo "'" . $val->delimiter . "',";
            echo $val->attributes . "<br />\n";
        }
    } else {
        echo "imap_getmailboxes a échoué : " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### Voir aussi

- imap_getsubscribed() - Liste toutes les boîtes aux lettres souscrites

# imap_getsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getsubscribed — Liste toutes les boîtes aux lettres souscrites

### Description

function imap_getsubscribed(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Liste toutes les boîtes aux lettres souscrites.

imap_getsubscribed() est identique à imap_getmailboxes(), mais ne retourne que les boîtes aux lettres auxquelles l'utilisateur est inscrit.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`reference`

  `reference` ne devrait être que le serveur sous la forme décrite dans imap_open()

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`pattern`
  Spécifie la position dans la hiérarchie des boîtes aux lettres, où il faut commencer à chercher.Il y a deux caractères spéciaux que vous pouvez utiliser dans `pattern` : '`*`' et '`%`'. '`*`' signifie : toutes les boîtes aux lettres. Si vous passez `pattern` comme '`*`', vous obtiendrez la liste complète des boîtes aux lettres de la hiérarchie. '`%`' signifie qu'on ne s'intéresse qu'au niveau courant. '`%`' passé à `pattern` ne retournera que les boîtes aux lettres de niveau supérieur; '`~/mail/%`' sous `UW_IMAPD` retournera toutes les boîtes aux lettres du dossier ~/mail directory, mais pas leurs enfants.

### Valeurs de retour

Retourne un tableau d'objets contenant les informations sur les boîtes aux lettres. Chaque objet possède un attribut de `name`, qui contient le nom complet de la boîte aux lettres, `delimiter` qui est le délimiteur hiérarchique et `attributes`. `attributes` est un masque de bits, qui contient :

- `LATT_NOINFERIORS` - Cette boîte aux lettres n'a pas d'"enfants" (il n'y a plus de boîtes aux lettres en dessous de celle-ci).
- `LATT_NOSELECT` - Ceci est juste un container, pas une boîte aux lettres (il n'est pas possible de l'ouvrir).
- `LATT_MARKED` - Cette boîte aux lettres est marquée. Utilisé uniquement avec UW-IMAPD.
- `LATT_UNMARKED` - Cette boîte aux lettres n'est pas marquée. Utilisé uniquement avec UW-IMAPD.
- `LATT_REFERRAL` - Ce conteneur a une référence vers une boîte aux lettres distante.
- `LATT_HASCHILDREN` - Cette boîte aux lettres a des inférieurs sélectionnables.
- `LATT_HASNOCHILDREN` - Cette boîte aux lettres n'a pas d'inférieurs sélectionnables.

La fonction retourne `false` en cas d'échec.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

# imap_header

(PHP 4, PHP 5, PHP 7)

imap_header — Alias de imap_headerinfo()

Avertissement

Cet alias est SUPPRIMÉ à partir de PHP 8.0.0.

### Description

Cette fonction est un alias de : imap_headerinfo().

# imap_headerinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headerinfo — Lit l'en-tête du message

### Description

function imap_headerinfo(
IMAP\Connection `$imap`,
int `$message_num`,
int `$from_length` = 0,
int `$subject_length` = 0
): stdClass|false

Récupère les informations sur un numéro de message donné en lisant ses en-têtes.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_num`

  Le numéro du message

`from_length`

  Nombre de caractères pour la propriété `fetchfrom`. Doit être plus grand ou égal à `0`.

`subject_length`

  Nombre de caractères pour la propriété `fetchsubject`. Doit être plus grand ou égal à `0`.

### Valeurs de retour

Retourne `false` en cas d'erreurs ou, en cas de succès, les informations dans un objet contenant les propriétés suivantes :

- `"toaddress"` : toute la ligne d'en-tête to: jusqu'à 1024 caractères
- `"to"` : un tableau d'objets issus de la ligne to: avec les propriétés suivantes : `personal`, `adl`, `mailbox`, et `host`
- `"fromaddress"` : toute la ligne d'en-tête from: jusqu'à 1024 caractères
- `"from"` : un tableau d'objets issus de la ligne From: avec les propriétés suivantes : `personal`, `adl`, `mailbox`, et `host`
- `"ccaddress"` : toute la ligne d'en-tête cc: jusqu'à 1024 caractères
- `"cc"` : un tableau d'objets issus de la ligne cc: avec les propriétés suivantes : `personal`, `adl`, `mailbox`, et `host`
- `"bccaddress"` : toute la ligne d'en-tête bcc: jusqu'à 1024 caractères
- `"bcc"` : un tableau d'objets issus de la ligne Bcc: avec les propriétés suivantes : `personal`, `adl`, `mailbox`, et `host`
- `"reply_toaddress"` : toute la ligne d'en-tête Reply_to: jusqu'à 1024 caractères
- `"reply_to"` : un tableau d'objets issus de la ligne Reply_to: avec les propriétés suivantes : `personal`, `adl`, `mailbox`, et `host`
- `"senderaddress"` : toute la ligne d'en-tête Sender: jusqu'à 1024 caractères
- `"sender"` : un tableau d'objets issus de la ligne Sender: avec les propriétés suivantes : `personal`, `adl`, `mailbox`, et `host`
- `"return_pathaddress"` : toute la ligne d'en-tête Return-path: jusqu'à 1024 caractères
- `"return_path"` : un tableau d'objets issus de la ligne Return-path: avec les propriétés suivantes : `personal`, `adl`, `mailbox`, et `host`
- remail -
- `"date"` : La date du message, telle que trouvée dans les en-têtes
- `"Date"` : Identique à `"date"`
- `"subject"` : Le sujet du message
- `"Subject"` : Identique à `"subject"`
- `"in_reply_to"` :
- `"message_id"` :
- `"newsgroups"` :
- `"followup_to"` :
- `"references"` :
- `"Recent"` : `R` si le message est récent et lu, `N` si le message est récent et non lu, `" "` si le message n'est pas récent.
- `"Unseen"` : `U` si le message est non lu ET non récent, `" "` si le message est non lu et récent
- `"Flagged"` : `F` si le message contient un drapeau, `" "` sinon
- `"Answered"` : `A` si une réponse a été faite à ce message, `" "` sinon
- `"Deleted"` : `D` si le message est effacé, `" "` sinon
- `"Draft"` : `X` si le message est un brouillon, `" "` sinon
- `"Msgno"` : Le numéro du message
- `"MailDate"` :
- `"Size"` : La taille du message
- `"udate"` : Date de l'envoi du message, sous la forme d'une date Unix
- `"fetchfrom"` : Ligne `"from"` formatée afin de tenir dans `from_length` caractères
- `"fetchsubject"` : Ligne `"subject"` formatée afin de tenir dans `subject_length` caractères

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.
8.0.0 | Le paramètre `defaulthost` inutilisé a été supprimé.

### Voir aussi

- imap_fetch_overview() - Lit le sommaire des en-têtes de messages

# imap_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headers — Retourne les en-têtes de tous les messages d'une boîte aux lettres

### Description

function imap_headers(IMAP\Connection `$imap`): array|false

Retourne les en-têtes de tous les messages d'une boîte aux lettres.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.

### Valeurs de retour

Retourne un tableau de chaînes contenant les en-têtes des messages : une chaîne par message. Retourne `false` en cas d'échec.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

# imap_is_open

(PHP 8 >= 8.2.1)

imap_is_open — Vérifier si le flux IMAP est toujours valide

### Description

function imap_is_open(IMAP\Connection `$imap`): bool

Vérifie si le flux IMAP est toujours valide.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.

### Valeurs de retour

Retourne `true` si le flux est toujours valide, `false` sinon.

### Exemples

Exemple #1 Exemple de imap_is_open()

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
    imap_is_open($mbox);
    // ...
    ?>

# imap_last_error

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_last_error — Retourne la dernière erreur survenue

### Description

function imap_last_error(): string|false

imap_last_error() retourne le texte complet de la dernière erreur IMAP (si elle existe) qui est survenue lors de la dernière requête. La pile d'erreur n'est pas touchée. Appeler imap_last_error() successivement, sans de nouvelles erreurs, retournera la même erreur.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le texte complet du dernier message d'erreur IMAP survenu sur la page courante. Retourne `false` si aucun message n'est disponible.

### Voir aussi

- imap_errors() - Retourne toutes les erreurs IMAP survenues

# imap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_list — Lit la liste des boîtes aux lettres

### Description

function imap_list(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Lit la liste des boîtes aux lettres.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`reference`

  `reference` ne devrait être que le serveur sous la forme décrite dans imap_open()

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`pattern`
  Spécifie la position dans la hiérarchie des boîtes aux lettres, où il faut commencer à chercher.Il y a deux caractères spéciaux que vous pouvez utiliser dans `pattern` : '`*`' et '`%`'. '`*`' signifie : toutes les boîtes aux lettres. Si vous passez `pattern` comme '`*`', vous obtiendrez la liste complète des boîtes aux lettres de la hiérarchie. '`%`' signifie qu'on ne s'intéresse qu'au niveau courant. '`%`' passé à `pattern` ne retournera que les boîtes aux lettres de niveau supérieur; '`~/mail/%`' sous `UW_IMAPD` retournera toutes les boîtes aux lettres du dossier ~/mail directory, mais pas leurs enfants.

### Valeurs de retour

Retourne un tableau contenant les noms des boîtes aux lettres, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_list()

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("Connexion impossible : " . imap_last_error());

    $list = imap_list($mbox, "{imap.example.org}", "*");
    if (is_array($list)) {
        foreach ($list as $val) {
            echo imap_utf7_decode($val) . "\n";
        }
    } else {
        echo "imap_list a échoué : " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### Voir aussi

- imap_getmailboxes() - Liste les boîtes aux lettres, et retourne les détails de chacune
- imap_lsub() - Liste toutes les boîtes aux lettres enregistrées

# imap_listmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listmailbox — Alias de imap_list()

### Description

Cette fonction est un alias de : imap_list().

# imap_listscan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listscan — Lit la liste des boîtes aux lettres, et y recherche une chaîne

### Description

function imap_listscan(
IMAP\Connection `$imap`,
string `$reference`,
string `$pattern`,
string `$content`
): array|false

Retourne un tableau contenant les noms des boîtes aux lettres qui contiennent la chaîne `content` dans leur nom.

Cette fonction est similaire à imap_listmailbox(), mais va aussi vérifier la présence de la chaîne `content` dans les messages de la boîte aux lettres.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`reference`

  `reference` ne devrait être que le serveur sous la forme décrite dans imap_open()

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`pattern`
  Spécifie la position dans la hiérarchie des boîtes aux lettres, où il faut commencer à chercher.Il y a deux caractères spéciaux que vous pouvez utiliser dans `pattern` : '`*`' et '`%`'. '`*`' signifie : toutes les boîtes aux lettres. Si vous passez `pattern` comme '`*`', vous obtiendrez la liste complète des boîtes aux lettres de la hiérarchie. '`%`' signifie qu'on ne s'intéresse qu'au niveau courant. '`%`' passé à `pattern` ne retournera que les boîtes aux lettres de niveau supérieur; '`~/mail/%`' sous `UW_IMAPD` retournera toutes les boîtes aux lettres du dossier ~/mail directory, mais pas leurs enfants.
`content`

  La chaîne cherchée

### Valeurs de retour

Retourne un tableau contenant les noms des boîtes aux lettres qui contiennent la chaîne `content` dans le nom de la boîte aux lettres, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_listmailbox() - Alias de imap_list
- imap_search() - Retourne un tableau de messages après recherche

# imap_listsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listsubscribed — Alias de imap_lsub()

### Description

Cette fonction est un alias de : imap_lsub().

# imap_lsub

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_lsub — Liste toutes les boîtes aux lettres enregistrées

### Description

function imap_lsub(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Récupère un tableau contenant toutes les boîtes aux lettres auxquelles l'on a souscrit.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`reference`

  `reference` ne devrait être que le serveur sous la forme décrite dans imap_open()

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`pattern`
  Spécifie la position dans la hiérarchie des boîtes aux lettres, où il faut commencer à chercher.Il y a deux caractères spéciaux que vous pouvez utiliser dans `pattern` : '`*`' et '`%`'. '`*`' signifie : toutes les boîtes aux lettres. Si vous passez `pattern` comme '`*`', vous obtiendrez la liste complète des boîtes aux lettres de la hiérarchie. '`%`' signifie qu'on ne s'intéresse qu'au niveau courant. '`%`' passé à `pattern` ne retournera que les boîtes aux lettres de niveau supérieur; '`~/mail/%`' sous `UW_IMAPD` retournera toutes les boîtes aux lettres du dossier ~/mail directory, mais pas leurs enfants.

### Valeurs de retour

Retourne un tableau contenant toutes les boîtes aux lettres souscrites, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_list() - Lit la liste des boîtes aux lettres
- imap_getmailboxes() - Liste les boîtes aux lettres, et retourne les détails de chacune

# imap_mail

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail — Envoie un message mail

### Description

function imap_mail(
string `$to`,
string `$subject`,
string `$message`,
?string `$additional_headers` = `null`,
?string `$cc` = `null`,
?string `$bcc` = `null`,
?string `$return_path` = `null`
): bool

imap_mail() permet d'envoyer des mails avec une gestion correcte des destinataires Cc et Bcc.

Les paramètres `to`, `cc` et `bcc` sont tous des chaînes et sont analysées comme des listes d'adresses » RFC822.

### Liste de paramètres

`to`

  Le destinataire

`subject`

  Le sujet du mail

`message`

  Le corps du mail ; voir la fonction imap_mail_compose().

`additional_headers`

  Une chaîne de caractères contenant les en-têtes additionnels à envoyer avec le mail

`cc`

`bcc`

  Les destinataires spécifiés dans le `bcc` recevront le mail mais sont exclus des en-têtes.

`return_path`

  Utiliser ce paramètre pour spécifier le chemin de retour en cas d'échec de délivrance du mail. C'est utile lors de l'utilisation de PHP comme client mail pour plusieurs utilisateurs.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.0.0 | `additional_headers`, `cc`, `bcc`, et `return_path` sont désormais nullable.

### Voir aussi

- mail() - Envoi de mail
- imap_mail_compose() - Crée un message MIME

# imap_mail_compose

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_compose — Crée un message MIME

### Description

function imap_mail_compose(array `$envelope`, array `$bodies`): string|false

Crée un message MIME basé sur l'enveloppe `envelope` et les sections `bodies`.

### Liste de paramètres

`envelope`

  Un tableau associatif contenant les champs des en-têtes. Les clés valides sont : `"remail"`, `"return_path"`, `"date"`, `"from"`, `"reply_to"`, `"in_reply_to"`, `"subject"`, `"to"`, `"cc"`, `"bcc"` et `"message_id"`, qui définit les en-têtes respectifs à la chaîne de caractères donnée. Pour définir des en-têtes additionnels, la clé `"custom_headers"` est supportée, qui attend un tableau de ces en-têtes, par exemple `["User-Agent: My Mail Client"]`.

`bodies`

  Un tableau indexé des corps. Le premier corps est le corps principal du message ; seulement s'il est du type `TYPEMULTIPART`, les corps suivants seront traités ; ces corps constituent les corps des parties.

  Structure d'un Tableau d'un Corps
  Clé | Type | Description
  --- | --- | ---
  `type` | int | Le type MIME. Un de `TYPETEXT` (par défaut), `TYPEMULTIPART`, `TYPEMESSAGE`, `TYPEAPPLICATION`, `TYPEAUDIO`, `TYPEIMAGE`, `TYPEMODEL` ou `TYPEOTHER`.
  `encoding` | int | Le `Content-Transfer-Encoding`. Un de `ENC7BIT` (par défaut), `ENC8BIT`, `ENCBINARY`, `ENCBASE64`, `ENCQUOTEDPRINTABLE` ou `ENCOTHER`.
  `charset` | string | Le jeu d'encodage du paramètre du type MIME.
  `type.parameters` | array | Un tableau associatif de nom de paramètre `Content-Type` et leurs valeurs.
  `subtype` | string | Le sous-type MIME, p. ex. `'jpeg'` pour `TYPEIMAGE`.
  `id` | string | Le `Content-ID`.
  `description` | string | Le `Content-Description`.
  `disposition.type` | string | Le `Content-Disposition`, p. ex. `'attachment'`.
  `disposition` | array | Un tableau associatif de nom de paramètre `Content-Disposition` et leurs valeurs.
  `contents.data` | string | La charge utile.
  `lines` | int | La taille de la charge utile en lignes.
  `bytes` | int | La taille de la charge utile en octets.
  `md5` | string | La checksum MD5 de la charge utile.

### Valeurs de retour

Retourne le message MIME en tant que chaîne de caractères, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec imap_mail_compose()

    <?php

    $envelope["from"]= "joe@example.com";
    $envelope["to"]  = "foo@example.com";
    $envelope["cc"]  = "bar@example.com";

    $part1["type"] = TYPEMULTIPART;
    $part1["subtype"] = "mixed";

    $filename = "/tmp/imap.c.gz";
    $fp = fopen($filename, "r");
    $contents = fread($fp, filesize($filename));
    fclose($fp);

    $part2["type"] = TYPEAPPLICATION;
    $part2["encoding"] = ENCBINARY;
    $part2["subtype"] = "octet-stream";
    $part2["description"] = basename($filename);
    $part2["contents.data"] = $contents;

    $part3["type"] = TYPETEXT;
    $part3["subtype"] = "plain";
    $part3["description"] = "description3";
    $part3["contents.data"] = "contents.data3\n\n\n\t";

    $body[1] = $part1;
    $body[2] = $part2;
    $body[3] = $part3;

    echo nl2br(imap_mail_compose($envelope, $body));

    ?>

# imap_mail_copy

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_copy — Copie les messages spécifiés dans une boîte aux lettres

### Description

function imap_mail_copy(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

Copie les messages email spécifiés par `message_nums` dans la boîte aux lettres spécifiée.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_nums`

  `message_nums` est un intervalle, et pas seulement une liste de numéros de message (comme décrit dans la » RFC2060).

`mailbox`

  Le nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`flags`

  `flags` est un masque, qui peut contenir une ou plusieurs des valeurs suivantes :

  - `CP_UID` - la séquence de nombre contient des UIDS
  - `CP_MOVE` - Efface les messages après copie. Si ce drapeau est défini, la fonction se comporte de manière identique à imap_mail_move().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_mail_move() - Déplace des messages dans une boîte aux lettres

# imap_mail_move

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_move — Déplace des messages dans une boîte aux lettres

### Description

function imap_mail_move(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

imap_mail_move() déplace les messages spécifiés par `message_nums` dans la boîte aux lettres `mailbox`. À noter que les messages sont en réalité copiés dans la boîte aux lettres `mailbox`, et les messages originaux sont marqués pour être supprimés. Ceci implique que les messages dans `mailbox` sont assignés de nouveaux UIDs.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_nums`

  `message_nums` est un intervalle, et pas seulement une liste de messages (comme décrit dans la » RFC2060).

`mailbox`

  Le nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`flags`

  `flags` est un champ de bits et peut contenir une seule valeur :

  - `CP_UID` - La séquence de nombres contient des UID

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Notes

> Note:

> imap_mail_move() va marquer l'email original avec un marqueur de suppression, pour effectivement le supprimer, un appel à imap_expunge() est nécessaire.

### Voir aussi

- imap_mail_copy() - Copie les messages spécifiés dans une boîte aux lettres

# imap_mailboxmsginfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mailboxmsginfo — Lit les informations à propos de la boîte aux lettres courante

### Description

function imap_mailboxmsginfo(IMAP\Connection `$imap`): stdClass

imap_mailboxmsginfo() vérifie le statut courant de la boîte aux lettres sur le serveur. C'est similaire à l'utilisation de la fonction imap_status(), mais fournit également la taille totale des messages de la boîte aux lettres, ce qui demande un peu plus de temps à l'exécution.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.

### Valeurs de retour

Retourne un objet avec les propriétés suivantes :

Propriétés de boîte aux lettres
Date | Date de dernière modification du contenu de la boîte aux lettres (date et heure courantes)
Driver | Pilote
Mailbox | Nom de la boîte aux lettres
Nmsgs | Nombre de messages
Recent | Nombre de messages récents
Unread | Nombre de messages non lus
Deleted | Nombre de messages effacés
Size | Taille de la boîte aux lettres

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_mailboxmsginfo()

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
          or die("Connexion impossible : " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);

    if ($check) {
        echo "Date : "     . $check->Date    . "<br />\n" ;
        echo "Pilote : "   . $check->Driver  . "<br />\n" ;
        echo "Boîte aux lettres : "  . $check->Mailbox . "<br />\n" ;
        echo "Messages : " . $check->Nmsgs   . "<br />\n" ;
        echo "Récent : "   . $check->Recent  . "<br />\n" ;
        echo "Non lu : "   . $check->Unread  . "<br />\n" ;
        echo "Effacé : "  . $check->Deleted . "<br />\n" ;
        echo "Taille : "     . $check->Size    . "<br />\n" ;
    } else {
        echo "imap_mailboxmsginfo() a échoué : " . imap_last_error() . "<br />\n";
    }

    imap_close($mbox);

    ?>

# imap_mime_header_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mime_header_decode — Décode les éléments MIME d'un en-tête

### Description

function imap_mime_header_decode(string `$string`): array|false

Décode un message MIME qui contient des données non ASCII (voir » RFC2047).

### Liste de paramètres

`string`

  Le texte MIME

### Valeurs de retour

Les éléments décodés sont retournés dans un tableau d'objets. Chacun de ces objets a deux propriétés : `charset` et `text`.

Si l'élément n'a pas été encodé, ou, en d'autres termes, s'il est en clair (plain US_ASCII), la propriété `charset` est mise à `default`.

Cette fonction retourne `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec imap_mime_header_decode()

    <?php
    $text = "=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@example.com>";

    $elements = imap_mime_header_decode($text);
    for ($i=0; $i<count($elements); $i++) {
        echo "Charset : {$elements[$i]->charset}\n";
        echo "Texte : {$elements[$i]->text}\n\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    Charset : ISO-8859-1
    Texte : Keld Jørn Simonsen

    Charset : default
    Texte :  <keld@example.com>

Dans l'exemple ci-dessus, on trouve deux éléments : le premier a été encodé en ISO-8859-1, et le second est en clair.

### Voir aussi

- imap_utf8() - Convertit du texte au format MIME en UTF-8

# imap_msgno

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_msgno — Retourne le numéro de séquence du message pour un UID donné

### Description

function imap_msgno(IMAP\Connection `$imap`, int `$message_uid`): int

Retourne le numéro de séquence du message pour l'UID `message_uid`.

Cette fonction est l'inverse de la fonction imap_uid().

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_uid`

  L'UID du message

### Valeurs de retour

Retourne le numéro de séquence du message pour l'UID `message_uid`.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_uid() - Retourne l'UID d'un message

# imap_mutf7_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_mutf7_to_utf8 — Décode une chaîne de caractères UTF-7 modifié en UTF-8

### Description

function imap_mutf7_to_utf8(string `$string`): string|false

Décode une chaîne de caractères UTF-7 modifié (comme spécifié dans la RFC 2060, section 5.1.3) en UTF-8.

> Note:

> Cette fonction est seulement disponible, si libcclient exporte utf8_to_mutf7().

### Liste de paramètres

`string`

  Une chaîne de caractères encodée en UTF-7 modifié.

### Valeurs de retour

Retourne `string` converti en UTF-8, ou `false` si une erreur survient.

### Voir aussi

- imap_utf8_to_mutf7() - Encode une chaîne de caractères UTF-8 en UTF-7 modifié

# imap_num_msg

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_msg — Retourne le nombre de messages dans la boîte aux lettres courante

### Description

function imap_num_msg(IMAP\Connection `$imap`): int|false

Retourne le nombre de messages dans la boîte aux lettres courante.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.

### Valeurs de retour

Retourne le nombre de messages dans la boîte aux lettres courante, sous la forme d'un entier, ou `false` en cas d'erreur.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_num_recent() - Retourne le nombre de messages récents dans la boîte aux lettres courante
- imap_status() - Retourne les informations de statut sur une boîte aux lettres

# imap_num_recent

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_recent — Retourne le nombre de messages récents dans la boîte aux lettres courante

### Description

function imap_num_recent(IMAP\Connection `$imap`): int

Retourne le nombre de messages récents dans la boîte aux lettres courante.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.

### Valeurs de retour

Retourne le nombre de messages récents dans la boîte aux lettres courante, sous la forme d'un entier.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_num_msg() - Retourne le nombre de messages dans la boîte aux lettres courante
- imap_status() - Retourne les informations de statut sur une boîte aux lettres

# imap_open

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_open — Ouvre un flux IMAP vers une boîte aux lettres

### Description

function imap_open(
string `$mailbox`,
string `$user`,
string `$password`,
int `$flags` = 0,
int `$retries` = 0,
array `$options` = []
): IMAP\Connection|false

Ouvre un flux IMAP vers la boîte aux lettres `mailbox`.

Cette fonction peut aussi être utilisée pour ouvrir des flots sur des serveurs POP3 et NNTP mais quelques fonctions et fonctionnalités ne sont disponibles qu'avec les serveurs IMAP.

### Liste de paramètres

`mailbox`

  Un nom de boîte aux lettres est constitué d'une adresse de serveur, et d'une adresse de boîte sur ce serveur. Le mot réservé `INBOX` représente la boîte aux lettres de l'utilisateur courant. Les noms de boîtes aux lettres qui contiennent des caractères spéciaux (en dehors de l'espace ASCII) doivent être encodés avec imap_utf7_encode().

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

  L'adresse du serveur, mise entre accolades '{' et '}', est constituée du nom du serveur ou de son adresse IP, d'une spécification de protocole (commençant par '/') et d'un port optionnel (spécifié avec ':').

  Cette partie est obligatoire dans les paramètres de la boîte aux lettres.

  Tous les noms commençant par `{` sont des noms distants et sont sous la forme `"{" nom_systeme_distant [":" port] [flags] "}" [nom_mailbox]` où :

  - `remote_system_name` : Nom de domaine Internet ou une adresse IP de serveur entouré de guillemets.
  - `port` : numéro de port TCP (optionnel), la valeur par défaut est la valeur du port pour ce service.
  - `flags` : options, voir la table suivante.
  - `mailbox_name` : nom de la mailbox distante, par défaut : INBOX

  Flags optionnels pour les noms
  Flag | Description
  --- | ---
  `/service=`service | service pour l'accès à la mailbox, par défaut : "imap"
  `/user=`user | nom de l'utilisateur distant pour l'identification sur le serveur
  `/authuser=`user | utilisateur distant d'identification ; si spécifié, ce sera le nom de l'utilisateur dont le mot de passe est utilisé (e.g. administrator)
  `/anonymous` | accès distant en anonyme
  `/debug` | la télémétrie d'enregistrement du protocole dans les logs de débogage de l'application
  `/secure` | ne transmet pas un mot de passe en clair à travers le réseau
  `/imap`, `/imap2`, `/imap2bis`, `/imap4`, `/imap4rev1` | équivalent de `/service=imap`
  `/pop3` | équivalent de `/service=pop3`
  `/nntp` | équivalent de `/service=nntp`
  `/norsh` | ne pas utiliser rsh ou ssh pour établir une session de pré identification IMAP
  `/ssl` | utilise `Secure Socket Layer` pour chiffrer la session
  `/validate-cert` | valide les certificats depuis le serveur TLS/SSL (c'est le comportement par défaut)
  `/novalidate-cert` | ne pas valider les certificats depuis le serveur TLS/SSL, nécessaire si le serveur utilise des certificats autosignés
  `/tls` | force l'utilisation de `start-TLS` pour chiffrer la session et rejette les connexions aux serveurs qui ne le supportent pas
  `/notls` | n'utilise pas `start-TLS` pour chiffrer la session, y compris avec les serveurs qui le supportent
  `/readonly` | demande un accès en lecture seule sur mailbox (IMAP uniquement ; ignoré sous NNTP, et une erreur avec SMTP et POP3)

`user`

  Le nom d'utilisateur

`password`

  Le mot de passe associé avec l'utilisateur `user`

`flags`

  `flags` est un masque de bit, qui peut prendre une ou plusieurs des valeurs suivantes :

  - `OP_READONLY` : Ouvre une boîte aux lettres en lecture seule
  - `OP_ANONYMOUS` : Ne pas utiliser, ou modifier le fichier .newsrc pour les news (NNTP uniquement)
  - `OP_HALFOPEN` : Pour les noms IMAP et NNTP, ouvre une connexion mais n'ouvre pas une boîte aux lettres.
  - `CL_EXPUNGE` : Supprime automatiquement la boîte aux lettres de la liste, lors de la terminaison du flux (voir aussi imap_delete() et imap_expunge())
  - `OP_DEBUG` : négociations de débogage du protocole
  - `OP_SHORTCACHE` : Cache court (`elt` uniquement)
  - `OP_SILENT` : Ne pas transmettre les événements (utilisation interne)
  - `OP_PROTOTYPE` : Retourne le prototype du driver
  - `OP_SECURE` : Ne pas effectuer des identifications non sécurisées
`retries`

  Le nombre maximal de tentatives de connexion.

`options`

  Paramètres de connexion ; les clés peuvent être utilisées pour définir un ou plusieurs paramètres de connexion :

  - `DISABLE_AUTHENTICATOR` - Désactive les propriétés d'authentification

### Valeurs de retour

Retourne une instance de IMAP\Connection en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de IMAP\Connection ; auparavant, une resource était retournée.

### Exemples

Exemple #1 Différentes utilisations de imap_open()

    <?php
    // Pour se connecter à un serveur IMAP fonctionnant sur le port 143 de la
    // machine locale, faites ceci :
    $mbox = imap_open("{localhost:143}INBOX", "user_id", "password");

    // Pour se connecter à un serveur POP3 fonctionnant sur le port 110 du
    // serveur local, faites ceci :
    $mbox = imap_open ("{localhost:110/pop3}INBOX", "user_id", "password");

    // Pour se connecter à un serveur SSL IMAP ou POP3, ajoutez /ssl
    // après la spécification du protocole :
    $mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password");

    // Pour se connecter à un serveur SSL IMAP ou POP3 avec un certificat autosigné
    // ajoutez /ssl/novalidate-cert après le protocole :
    $mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password");

    // Pour se connecter à un serveur NNTP qui fonctionne sur
    // le port 119 de la machine locale on peut utiliser la commande:
    $nntp = imap_open ("{localhost:119/nntp}comp.test", "", "");

    // Pour se connecter à un serveur distant, remplacez "localhost" par
    // le nom ou l'adresse IP de la machine.
    ?>

Exemple #2 Exemple avec imap_open()

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password");

    echo "<h1>Boîtes aux lettres</h1>\n";
    $folders = imap_listmailbox($mbox, "{imap.example.org:143}", "*");

    if ($folders == false) {
        echo "Appel échoué<br />\n";
    } else {
        foreach ($folders as $val) {
            echo $val . "<br />\n";
        }
    }

    echo "<h1>en-têtes dans INBOX</h1>\n";
    $headers = imap_headers($mbox);

    if ($headers == false) {
        echo "Appel échoué<br />\n";
    } else {
        foreach ($headers as $val) {
            echo $val . "<br />\n";
        }
    }

    imap_close($mbox);
    ?>

### Voir aussi

- imap_close() - Termine un flux IMAP

# imap_ping

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_ping — Vérifie que le flux IMAP est toujours actif

### Description

function imap_ping(IMAP\Connection `$imap`): bool

Vérifie que le flux est toujours actif, en lui envoyant un ping. Cette fonction permet de se rendre compte qu'un mail est arrivé : c'est même la méthode préconisée pour des tests périodiques de vérification du courrier. Cette fonction peut aussi servir à garder une connexion ouverte, avec les serveurs dotés d'un délai d'expiration.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.

### Valeurs de retour

Retourne `true` si le flux est toujours actif, `false` sinon.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_ping()

    <?php

    $imap = imap_open("{imap.example.org}", "mailadmin", "password");

    // après une pause
    if (!imap_ping($imap)) {
        // effectuez un traitement pour se reconnecter
    }

    ?>

# imap_qprint

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_qprint — Convertit une chaîne à guillemets en une chaîne à 8 bits

### Description

function imap_qprint(string `$string`): string|false

Convertit la chaîne à guillemets `string` en une chaîne à 8 bits (selon la » RFC2045, section 6.7).

### Liste de paramètres

`string`

  Une chaîne à guillemets

### Valeurs de retour

Retourne une chaîne de caractères à 8 bits, ou `false` si une erreur survient.

### Voir aussi

- imap_8bit() - Convertit une chaîne à 8 bits en une chaîne encodée en Quoted-Printable

# imap_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rename — Alias de imap_renamemailbox()

### Description

Cette fonction est un alias de : imap_renamemailbox().

# imap_renamemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_renamemailbox — Renomme une boîte aux lettres

### Description

function imap_renamemailbox(IMAP\Connection `$imap`, string `$from`, string `$to`): bool

imap_renamemailbox() renomme la boîte aux lettres `from` en `to` (voir la fonction imap_open() pour le format des noms `mbox`).

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`from`

  L'ancien nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`to`

  Le nouveau nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_createmailbox() - Crée une nouvelle boîte aux lettres
- imap_deletemailbox() - Efface une boîte aux lettres

# imap_reopen

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_reopen — Réouvre un flux IMAP vers une nouvelle boîte aux lettres

### Description

function imap_reopen(
IMAP\Connection `$imap`,
string `$mailbox`,
int `$flags` = 0,
int `$retries` = 0
): bool

Réouvre la connexion spécifiée au serveur IMAP ou NNTP, avec une nouvelle boîte aux lettres.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`mailbox`

  Le nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`flags`

  `flags` est un masque de bits, qui peut contenir les valeurs suivantes :

  - `OP_READONLY` - Ouvre une boîte aux lettres en lecture seule
  - `OP_ANONYMOUS` - Ne pas utiliser, ou modifier le fichier .newsrc pour les news (NNTP uniquement)
  - `OP_HALFOPEN` - Pour les noms IMAP et NNTP, ouvre une connexion mais n'ouvre pas une boîte aux lettres.
  - `OP_EXPUNGE` - Supprime silencieusement le flux recyclé
  - `CL_EXPUNGE` - Supprime automatiquement la boîte aux lettres de la liste, lors de la terminaison du flux. (voir imap_delete() et imap_expunge()).
`retries`

  Le nombre maximal de tentatives de connexion

### Valeurs de retour

Retourne `true` si le flux est réouvert, `false` sinon.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_reopen()

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
    // ...
    imap_reopen($mbox, "{imap.example.org:143}INBOX.Sent") or die(implode(", ", imap_errors()));
    // ..
    ?>

# imap_rfc822_parse_adrlist

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_adrlist — Analyse une adresse email

### Description

function imap_rfc822_parse_adrlist(string `$string`, string `$default_hostname`): array

Analyse la chaîne d'adresses, telle que définie dans la » RFC2822.

### Liste de paramètres

`string`

  Une chaîne de caractères contenant les adresses

`default_hostname`

  Le nom de l'hôte par défaut

### Valeurs de retour

Retourne un tableau d'objets. Les propriétés des objets sont :

- `"mailbox"` : Le nom de la boîte aux lettres (nom d'utilisateur)
- `"host"` : Le nom de l'hôte
- `"personal"` : Le nom personnel
- `"adl"` : at domain source route

### Exemples

Exemple #1 Exemple avec imap_rfc822_parse_adrlist()

    <?php

    $address_string = "Joe Doe <doe@example.com>, postmaster@example.com, root";
    $address_array  = imap_rfc822_parse_adrlist($address_string, "example.com");
    if (!is_array($address_array) || count($address_array) < 1) {
        die("Erreur !\n");
    }

    foreach ($address_array as $id => $val) {
        echo "# $id\n";
        echo "  Boîte   : " . $val->mailbox . "\n";
        echo "  Hôte    : " . $val->host . "\n";
        echo "  Nom    : " . $val->personal . "\n";
        echo "  adl      : " . $val->adl . "\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    # 0
      Boîte   : doe
      Hôte    : example.com
      Nom    : Joe Doe
      adl      :
    # 1
      Boîte   : postmaster
      Hôte    : example.com
      Nom    :
      adl      :
    # 2
      Boîte   : root
      Hôte    : example.com
      Nom    :
      adl      :

### Voir aussi

- imap_rfc822_parse_headers() - Analyse un en-tête mail

# imap_rfc822_parse_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_headers — Analyse un en-tête mail

### Description

function imap_rfc822_parse_headers(string `$headers`, string `$default_hostname` = "UNKNOWN"): stdClass

Analyse la chaîne `headers` et retourne un objet contenant différents éléments, similaires à la fonction imap_header().

### Liste de paramètres

`headers`

  Les données à analyser

`default_hostname`

  Le nom de l'hôte par défaut

### Valeurs de retour

Retourne un objet similaire à celui retourné par la fonction imap_header(), excepté pour les drapeaux et les autres propriétés qui proviennent du serveur IMAP.

### Voir aussi

- imap_rfc822_parse_adrlist() - Analyse une adresse email

# imap_rfc822_write_address

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_write_address — Retourne une adresse email formatée correctement

### Description

function imap_rfc822_write_address(string `$mailbox`, string `$hostname`, string `$personal`): string|false

Retourne une adresse email formatée correctement selon la » RFC2822.

### Liste de paramètres

`mailbox`

  Le nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`hostname`

  La partie hôte de l'email

`personal`

  Le nom du propriétaire du compte

### Valeurs de retour

Retourne une adresse email formatée correctement selon la » RFC2822, ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec imap_rfc822_write_address()

    <?php
    echo imap_rfc822_write_address("hartmut", "example.com", "Hartmut Holzgraefe");
    ?>

L'exemple ci-dessus va afficher :

    Hartmut Holzgraefe <hartmut@example.com>

# imap_savebody

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

imap_savebody — Sauvegarde une partie spécifique du corps dans un fichier

### Description

function imap_savebody(
IMAP\Connection `$imap`,
resource|string|int `$file`,
int `$message_num`,
string `$section` = "",
int `$flags` = 0
): bool

Sauvegarde une partie du corps du message spécifié.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`file`

  Le chemin vers le fichier de sauvegarde, sous la forme d'une chaîne de caractères ou un descripteur de fichier valide retourné par la fonction fopen().

`message_num`

  Le numéro du message

`section`

  Le numéro de la section. C'est une chaîne de caractères d'entiers, délimités par un point qui correspondent à l'index dans la liste des sections du corps, tel que prévu par la spécification IMAP4.

`flags`

  Un masque qui contient une ou plusieurs des valeurs suivantes :

  - `FT_UID` - Le numéro `message_num` est un UID
  - `FT_PEEK` - Ne pas définir le drapeau \Seen s'il n'est pas déjà défini
  - `FT_INTERNAL` - La chaîne de caractères retournée est dans un format interne, qui ne correspond pas à CRLF.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_fetchbody() - Retourne une section extraite du corps d'un message

# imap_scan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scan — Alias de imap_listscan()

### Description

Cette fonction est un alias de : imap_listscan().

# imap_scanmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scanmailbox — Alias de imap_listscan()

### Description

Cette fonction est un alias de : imap_listscan().

# imap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_search — Retourne un tableau de messages après recherche

### Description

function imap_search(
IMAP\Connection `$imap`,
string `$criteria`,
int `$flags` = `SE_FREE`,
string `$charset` = ""
): array|false

Effectue une recherche dans la boîte aux lettres courante, sur le flux IMAP courant.

Par exemple, pour rechercher les messages non répondus, envoyés par maman, il est possible d'utiliser : "UNANSWERED FROM maman". Les recherches semblent insensibles à la casse. Cette liste de critères est issue du code d'un client C UW et peut être incomplète ou imprécise. (voir aussi la » RFC1176, et en particulier, la section "tag SEARCH search_criteria").

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`criteria`

  Une chaîne de caractères, délimitée par des espaces, dans laquelle les mots-clés suivants sont acceptés. Tous les arguments à plusieurs mots (e.g. `FROM "joey smith"`) doivent être placés entre guillemets. Les résultats devront correspondre à toutes les entrées `criteria`.

  - ALL - retourne tous les messages qui vérifient le reste du critère.
  - ANSWERED - tous les messages avec le flag \\ANSWERED
  - BCC "string" - tous les messages avec la chaîne "string" dans le champ Bcc
  - BEFORE "date" - tous les messages avec Date : avant "date"
  - BODY "string" - tous les messages avec "string" dans le corps
  - CC "string" - tous les messages avec "string" dans le champ Cc
  - DELETED - tous les messages effacés
  - FLAGGED - tous les messages avec le flag \\FLAGGED (parfois interprété comme Important ou Urgent)
  - FROM "string" - tous les messages avec la chaîne "string" dans le champ From
  - KEYWORD "string" - tous les messages avec la chaîne "string" comme mot-clé
  - NEW - tous les nouveaux messages
  - OLD - tous les anciens messages
  - ON "date" - tous les messages avec la date "date" comme champ Date
  - RECENT - tous les messages avec le flag \\RECENT
  - SEEN - tous les messages lus (avec le flag \\SEEN)
  - SINCE "date" - tous les messages avec la date Date: après "date"
  - SUBJECT "string" - tous les messages avec la chaîne "string" dans le champ Subject
  - TEXT "string" - tous les messages avec le texte "string"
  - TO "string" - tous les messages avec la chaîne "string" dans le champ To
  - UNANSWERED - tous les messages non répondus
  - UNDELETED - tous les messages non effacés
  - UNFLAGGED - tous les messages non marqués
  - UNKEYWORD "string" - tous les messages ne contenant pas le mot-clé "string"
  - UNSEEN - tous les messages non lus
`flags`

  Les valeurs pour `flags` sont `SE_UID`, qui fait que le tableau réponse contient les UID plutôt que les numéros de séquence.

`charset`

  Jeu de caractères MIME à utiliser lors de la recherche de chaîne de caractères.

### Valeurs de retour

Retourne un tableau de numéro de messages ou d'UID.

Retourne `false` si la recherche n'est pas comprise, ou bien qu'aucun message n'a été trouvé.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_search()

    <?php
    $imap   = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'foo@example.com', 'pass123', OP_READONLY);

    $some   = imap_search($imap, 'SUBJECT "HOWTO be Awesome" SINCE "8 August 2008"', SE_UID);
    $msgnos = imap_search($imap, 'ALL');
    $uids   = imap_search($imap, 'ALL', SE_UID);

    print_r($some);
    print_r($msgnos);
    print_r($uids);
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Array
    (
        [0] => 4
        [1] => 6
        [2] => 11
    )
    Array
    (
        [0] => 1
        [1] => 2
        [2] => 3
        [3] => 4
        [4] => 5
        [5] => 6
    )
    Array
    (
        [0] => 1
        [1] => 4
        [2] => 6
        [3] => 8
        [4] => 11
        [5] => 12
    )

### Voir aussi

- imap_listscan() - Lit la liste des boîtes aux lettres, et y recherche une chaîne

# imap_set_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_set_quota — Modifie le quota d'une boîte aux lettres

### Description

function imap_set_quota(IMAP\Connection `$imap`, string `$quota_root`, int `$mailbox_size`): bool

Modifie le quota de la boîte aux lettres `quota_root`.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`quota_root`

  La boîte aux lettres dont on doit modifier le quota. Elle doit suivre le format standard IMAP pour une boîte aux lettres : `user.name`.

`mailbox_size`

  La taille maximale (en Ko) pour la boîte `quota_root`

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_set_quota()

    <?php
    $mbox = imap_open("{imap.example.org:143}", "mailadmin", "password");

    if (!imap_set_quota($mbox, "user.kalowsky", 3000)) {
        echo "Échec lors de la définition du quota\n";
        return;
    }

    imap_close($mbox);
    ?>

### Notes

Cette fonction ne fonctionne actuellement qu'avec les bibliothèques c-client2000.

imap_set_quota() requiert que `imap` ait été ouvert avec un compte d'administrateur, pour avoir les droits nécessaires : elle ne fonctionnera avec aucun autre utilisateur.

### Voir aussi

- imap_open() - Ouvre un flux IMAP vers une boîte aux lettres
- imap_get_quota() - Lit les quotas des boîtes aux lettres ainsi que des statistiques sur chacune d'elles

# imap_setacl

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_setacl — Modifie le ACL de la boîte aux lettres

### Description

function imap_setacl(
IMAP\Connection `$imap`,
string `$mailbox`,
string `$user_id`,
string `$rights`
): bool

Définit l'ACL pour la boîte aux lettres donnée.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`mailbox`

  Le nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`user_id`

  L'identifiant de l'utilisateur dont on veut définir les droits.

`rights`

  Les droits à donner à l'utilisateur. Le fait de passer une chaîne vide effacera l'ACL.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Notes

Cette fonction n'est actuellement disponible que pour les utilisateurs de la bibliothèque `c-client2000` ou supérieure.

### Voir aussi

- imap_getacl() - Retourne le ACL pour la boîte aux lettres

# imap_setflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_setflag_full — Positionne un drapeau sur un message

### Description

function imap_setflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

imap_setflag_full() affecte le `flag` spécifié aux messages de la `sequence` donnée.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`sequence`

  Une séquence de numéro de messages. Il est possible d'énumérer les messages désirés avec la syntaxe `X,Y`, ou récupérer tous les messages d'un intervalle avec la syntaxe `X:Y`

`flag`

  Les flags qu'il est possible de modifier sont `\Seen`, `\Answered`, `\Flagged`, `\Deleted`, et `\Draft` (comme défini dans la » RFC2060).

`options`

  `options` est un masque de bits, qui accepte uniquement la valeur suivante :

  - `ST_UID` - la séquence contient des UID au lieu de numéros de séquence.

### Valeurs de retour

Retourne toujours `true`.

### Erreurs / Exceptions

Lance une exception ValueError si le paramètre `options` est invalide.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.
8.0.0 | Une exception ValueError est désormais lancée pour des valeurs de paramètre `options` invalides. Auparavant, un avertissement était émis et la fonction retournait `false`.

### Exemples

Exemple #1 Exemple avec imap_setflag_full()

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password")
         or die("Connexion impossible : " . imap_last_error());

    $status = imap_setflag_full($mbox, "2,5", "\\Seen \\Flagged");

    echo gettype($status) . "\n";
    echo $status . "\n";

    imap_close($mbox);
    ?>

### Voir aussi

- imap_clearflag_full() - Supprime un flag (drapeau) sur un message

# imap_sort

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_sort — Trie des messages

### Description

function imap_sort(
IMAP\Connection `$imap`,
int `$criteria`,
bool `$reverse`,
int `$flags` = 0,
?string `$search_criteria` = `null`,
?string `$charset` = `null`
): array|false

Récupère et trie les numéros de messages en fonction des paramètres donnés.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`criteria`

  Les critères `criteria` peuvent être un (et un seul) parmi les suivants :

  - `SORTDATE` : date du message
  - `SORTARRIVAL` : date d'arrivée
  - `SORTFROM` : nom de la première boîte aux lettres de l'adresse d'origine (From address)
  - `SORTSUBJECT` : sujet du message
  - `SORTTO` : nom de la première boîte aux lettres de destination (To address)
  - `SORTCC` : nom de la boîte aux lettres de copie carbone (cc address)
  - `SORTSIZE` : taille du message en octets
`reverse`

  S'il faut trier en ordre inverse.

`flags`

  Les `flags` sont des masques de bits, d'un ou plusieurs des éléments suivants :

  - `SE_UID` : retourne des UID à la place de numéros
  - `SE_NOPREFETCH` : ne pas prétélécharger les messages trouvés
`search_criteria`

  Critères de recherche IMAP2-format. Pour plus de détails voir imap_search().

`charset`

  Jeu de caractères MIME à utiliser lors de la recherche de chaîne de caractères.

### Valeurs de retour

Retourne un tableau de numéros de messages triés en fonction des paramètres fournis, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.
8.0.0 | `reverse` est un bool au lieu de int.
8.0.0 | `search_criteria` et `charset` sont désormais nullable.

# imap_status

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_status — Retourne les informations de statut sur une boîte aux lettres

### Description

function imap_status(IMAP\Connection `$imap`, string `$mailbox`, int `$flags`): stdClass|false

Retourne les informations de statut sur la boîte aux lettres `mailbox`.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`mailbox`

  Le nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

`flags`

  Les drapeaux valides sont :

  - `SA_MESSAGES` - met la valeur de $status->messages au nombre de messages dans la boîte aux lettres.
  - `SA_RECENT` - met la valeur de $status->recent au nombre de messages récents dans la boîte aux lettres.
  - `SA_UNSEEN` - met la valeur de $status->unseen au nombre de messages non lus dans la boîte aux lettres.
  - `SA_UIDNEXT` - met la valeur de $status->uidnext à la prochaine valeur d'uid qui sera utilisée.
  - `SA_UIDVALIDITY` - met la valeur de $status->uidvalidity à une constante, qui change lorsque l'uid de la boîte aux lettres n'est plus valide.
  - `SA_ALL` - fixe toutes les valeurs précédentes.

### Valeurs de retour

Cette fonction retourne un objet contenant les informations sur le statut, ou `false` si une erreur survient. L'objet a les propriétés suivantes : `messages`, `recent`, `unseen`, `uidnext`, et `uidvalidity`.

`flags` est également défini, qui contient un masque contenant une des constantes ci-dessus.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_status()

    <?php
    $mbox = imap_open("{imap.example.com}", "username", "password", OP_HALFOPEN)
          or die("Connexion impossible : " . imap_last_error());

    $status = imap_status($mbox, "{imap.example.org}INBOX", SA_ALL);
    if ($status) {
      echo "Messages :   " . $status->messages    . "<br />\n";
      echo "Récent :     " . $status->recent      . "<br />\n";
      echo "Non lu :     " . $status->unseen      . "<br />\n";
      echo "Prochain UID:    " . $status->uidnext     . "<br />\n";
      echo "Validité de l'UID:" . $status->uidvalidity . "<br />\n";
    } else {
      echo "imap_status a échoué : " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

# imap_subscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_subscribe — Souscrit à une boîte aux lettres

### Description

function imap_subscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Souscrit à une boîte aux lettres.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`mailbox`

  Le nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_unsubscribe() - Termine la souscription à une boîte aux lettres

# imap_thread

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_thread — Retourne l'arbre des messages organisés par thread

### Description

function imap_thread(IMAP\Connection `$imap`, int `$flags` = `SE_FREE`): array|false

Retourne l'arbre des messages organisés par thread.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`flags`

### Valeurs de retour

imap_thread() retourne un tableau associatif contenant un arbre de messages organisés par thread par `REFERENCES` ou `false` en cas d'erreur.

Chaque message dans la boîte aux lettres courante sera représenté par des entrées sous forme d'arbre dans le tableau résultant :

- $thread["XX.num"] - numéro du message courant

- $thread["XX.next"]

- $thread["XX.branch"]

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Exemples

Exemple #1 Exemple avec imap_thread()

    <?php

    // Ici, nous affichons les threads d'un newsgroup, en HTML

    $nntp = imap_open('{news.example.com:119/nntp}some.newsgroup', '', '');
    $threads = imap_thread($nntp);

    foreach ($threads as $key => $val) {
      $tree = explode('.', $key);
      if ($tree[1] == 'num') {
        $header = imap_headerinfo($nntp, $val);
        echo "<ul>\n\t<li>" . $header->fromaddress . "\n";
      } elseif ($tree[1] == 'branch') {
        echo "\t</li>\n</ul>\n";
      }
    }

    imap_close($nntp);

    ?>

# imap_timeout

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

imap_timeout — Configure ou retourne le timeout

### Description

function imap_timeout(int `$timeout_type`, int `$timeout` = -1): int|bool

Définit ou retourne le timeout imap.

### Liste de paramètres

`timeout_type`

  Une valeur parmi les suivantes : `IMAP_OPENTIMEOUT`, `IMAP_READTIMEOUT`, `IMAP_WRITETIMEOUT`, ou `IMAP_CLOSETIMEOUT`.

`timeout`

  Le timeout, en secondes.

### Valeurs de retour

Si le paramètre `timeout` est défini, cette fonction retourne `true` en cas de succès et `false` si une erreur survient.

Si `timeout` n'est pas fourni ou s'il est évalué à -1, le timeout courant sera retourné sous la forme d'un entier.

### Exemples

Exemple #1 Exemple avec imap_timeout()

    <?php

    echo "Le timeout courant est " . imap_timeout(IMAP_READTIMEOUT) . "\n";

    ?>

# imap_uid

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_uid — Retourne l'UID d'un message

### Description

function imap_uid(IMAP\Connection `$imap`, int `$message_num`): int|false

imap_uid() retourne l'UID pour le message `msgno`. Un UID est un identifiant unique qui ne change jamais, alors que le numéro du message dans la liste des messages peut changer à toute modification de la boîte aux lettres.

C'est la fonction inverse de imap_msgno().

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_num`

  Le numéro du message.

### Valeurs de retour

L'UID d'un message donné.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Notes

> Note:

> Cette fonctionnalité n'est pas supportée par les boîtes aux lettres POP3.

### Voir aussi

- imap_msgno() - Retourne le numéro de séquence du message pour un UID donné

# imap_undelete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_undelete — Enlève la marque d'effacement d'un message

### Description

function imap_undelete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Enlève la marque d'effacement du message `message_nums`, placée avec imap_delete() ou imap_mail_move().

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`message_nums`

  Une chaîne de caractères représentant un ou plusieurs messages dans un style de format d'une séquence IMAP4 (`"n"`, `"n:m"`, ou une combinaison de ceci, délimité par des virgules).

`flags`

### Valeurs de retour

Retourne toujours `true`.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_delete() - Marque le message pour l'effacement, dans la boîte aux lettres courante
- imap_mail_move() - Déplace des messages dans une boîte aux lettres

# imap_unsubscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_unsubscribe — Termine la souscription à une boîte aux lettres

### Description

function imap_unsubscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Termine la souscription à la boîte aux lettres `mailbox`.

### Liste de paramètres

`imap`
  Une instance de IMAP\Connection.
`mailbox`

  Le nom de la boîte aux lettres, voir la documentation de la fonction imap_open() pour plus de détails.

  Avertissement

  Passer des données qui ne sont pas digne de confiance à ce paramètre est dangereux, sauf si, imap.enable_insecure_rsh est désactivé.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | La paramètre `imap` attend désormais une instance de IMAP\Connection ; auparavant, une resource `imap` était attendue.

### Voir aussi

- imap_subscribe() - Souscrit à une boîte aux lettres

# imap_utf7_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_decode — Décode une chaîne encodée en UTF-7 modifié

### Description

function imap_utf7_decode(string `$string`): string|false

imap_utf7_decode() décode la chaîne UTF-7 `string` en ISO-8859-1.

Cette fonction sert à décoder les noms de boîtes aux lettres qui contiennent des caractères internationaux hors de l'espace ASCII.

### Liste de paramètres

`string`

  L'encodage UTF-7 modifié est défini dans la » RFC 2060, section 5.1.3.

### Valeurs de retour

Retourne une chaîne de caractères encodée ISO-8859-1 et contenant la même séquence de caractères que dans le paramètre `string`, ou `false` si `string` contient une séquence UTF-7 modifiée invalide ou si `string` contient un caractère qui ne fait pas partie du jeu de caractères ISO-8859-1.

### Voir aussi

- imap_utf7_encode() - Convertit une chaîne ISO-8859-1 en texte UTF-7 modifié

# imap_utf7_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_encode — Convertit une chaîne ISO-8859-1 en texte UTF-7 modifié

### Description

function imap_utf7_encode(string `$string`): string

Convertit une chaîne `string` ISO-8859-1 en texte UTF-7 modifié.

Cette fonction sert à encoder les noms de boîtes aux lettres qui contiennent des caractères internationaux hors de l'espace ASCII.

### Liste de paramètres

`string`

  Une chaîne de caractères ISO-8859-1.

### Valeurs de retour

Retourne les données `string` encodées avec l'encodage UTF-7 modifié tel que défini dans la » RFC 2060, section 5.1.3.

### Voir aussi

- imap_utf7_decode() - Décode une chaîne encodée en UTF-7 modifié

# imap_utf8

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf8 — Convertit du texte au format MIME en UTF-8

### Description

function imap_utf8(string `$mime_encoded_text`): string

Convertit le texte `mime_encoded_text` en UTF-8, si le jeu de caractères déclaré est connu de libc-client. Sinon, le texte fourni sera décodé, mais pas converti en UTF-8.

### Liste de paramètres

`mime_encoded_text`

  Une chaîne de caractères encodée MIME. Les spécifications de MIME et UTF8 sont décrites dans les » RFC2047 et » RFC2044.

### Valeurs de retour

Retourne la chaîne de caractères décodée et si possible, convertie en UTF-8.

### Exemples

Exemple #1 Utilisation de base de la fonction imap_utf8()

    <?php
    echo imap_utf8("Johannes =?ISO-8859-1?Q?Schl=FCter?=");
    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Johannes Schlüter

### Voir aussi

- imap_mime_header_decode() - Décode les éléments MIME d'un en-tête

# imap_utf8_to_mutf7

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_utf8_to_mutf7 — Encode une chaîne de caractères UTF-8 en UTF-7 modifié

### Description

function imap_utf8_to_mutf7(string `$string`): string|false

Encode une chaîne de caractères UTF-8 en UTF-7 modifié (comme spécifié dans la RFC 2060, section 5.1.3).

> Note:

> Cette fonction est seulement disponible, si libcclient exporte utf8_to_mutf7().

### Liste de paramètres

`string`

  Une chaîne de caractères encodée en UTF-8.

### Valeurs de retour

Retourne `string` converti en UTF-7 modifié, ou `false` si une erreur survient.

### Voir aussi

- imap_mutf7_to_utf8() - Décode une chaîne de caractères UTF-7 modifié en UTF-8

## Sommaire

- imap_8bit — Convertit une chaîne à 8 bits en une chaîne encodée en Quoted-Printable
- imap_alerts — Retourne toutes les alertes
- imap_append — Ajoute un message dans une boîte aux lettres
- imap_base64 — Décode un texte encodé en BASE64
- imap_binary — Convertit une chaîne à 8 bits en une chaîne à base64
- imap_body — Lit le corps d'un message
- imap_bodystruct — Lit la structure d'une section du corps d'un mail
- imap_check — Vérifie la boîte aux lettres courante
- imap_clearflag_full — Supprime un flag (drapeau) sur un message
- imap_close — Termine un flux IMAP
- imap_create — Alias de imap_createmailbox
- imap_createmailbox — Crée une nouvelle boîte aux lettres
- imap_delete — Marque le message pour l'effacement, dans la boîte aux lettres courante
- imap_deletemailbox — Efface une boîte aux lettres
- imap_errors — Retourne toutes les erreurs IMAP survenues
- imap_expunge — Efface tous les messages marqués pour l'effacement
- imap_fetch_overview — Lit le sommaire des en-têtes de messages
- imap_fetchbody — Retourne une section extraite du corps d'un message
- imap_fetchheader — Retourne l'en-tête d'un message
- imap_fetchmime — Récupère les en-têtes MIME pour une section particulière du message
- imap_fetchstructure — Lit la structure d'un message
- imap_fetchtext — Alias de imap_body
- imap_gc — Efface le cache IMAP
- imap_get_quota — Lit les quotas des boîtes aux lettres ainsi que des statistiques sur chacune d'elles
- imap_get_quotaroot — Lit les quotas de chaque utilisateur
- imap_getacl — Retourne le ACL pour la boîte aux lettres
- imap_getmailboxes — Liste les boîtes aux lettres, et retourne les détails de chacune
- imap_getsubscribed — Liste toutes les boîtes aux lettres souscrites
- imap_header — Alias de imap_headerinfo
- imap_headerinfo — Lit l'en-tête du message
- imap_headers — Retourne les en-têtes de tous les messages d'une boîte aux lettres
- imap_is_open — Vérifier si le flux IMAP est toujours valide
- imap_last_error — Retourne la dernière erreur survenue
- imap_list — Lit la liste des boîtes aux lettres
- imap_listmailbox — Alias de imap_list
- imap_listscan — Lit la liste des boîtes aux lettres, et y recherche une chaîne
- imap_listsubscribed — Alias de imap_lsub
- imap_lsub — Liste toutes les boîtes aux lettres enregistrées
- imap_mail — Envoie un message mail
- imap_mail_compose — Crée un message MIME
- imap_mail_copy — Copie les messages spécifiés dans une boîte aux lettres
- imap_mail_move — Déplace des messages dans une boîte aux lettres
- imap_mailboxmsginfo — Lit les informations à propos de la boîte aux lettres courante
- imap_mime_header_decode — Décode les éléments MIME d'un en-tête
- imap_msgno — Retourne le numéro de séquence du message pour un UID donné
- imap_mutf7_to_utf8 — Décode une chaîne de caractères UTF-7 modifié en UTF-8
- imap_num_msg — Retourne le nombre de messages dans la boîte aux lettres courante
- imap_num_recent — Retourne le nombre de messages récents dans la boîte aux lettres courante
- imap_open — Ouvre un flux IMAP vers une boîte aux lettres
- imap_ping — Vérifie que le flux IMAP est toujours actif
- imap_qprint — Convertit une chaîne à guillemets en une chaîne à 8 bits
- imap_rename — Alias de imap_renamemailbox
- imap_renamemailbox — Renomme une boîte aux lettres
- imap_reopen — Réouvre un flux IMAP vers une nouvelle boîte aux lettres
- imap_rfc822_parse_adrlist — Analyse une adresse email
- imap_rfc822_parse_headers — Analyse un en-tête mail
- imap_rfc822_write_address — Retourne une adresse email formatée correctement
- imap_savebody — Sauvegarde une partie spécifique du corps dans un fichier
- imap_scan — Alias de imap_listscan
- imap_scanmailbox — Alias de imap_listscan
- imap_search — Retourne un tableau de messages après recherche
- imap_set_quota — Modifie le quota d'une boîte aux lettres
- imap_setacl — Modifie le ACL de la boîte aux lettres
- imap_setflag_full — Positionne un drapeau sur un message
- imap_sort — Trie des messages
- imap_status — Retourne les informations de statut sur une boîte aux lettres
- imap_subscribe — Souscrit à une boîte aux lettres
- imap_thread — Retourne l'arbre des messages organisés par thread
- imap_timeout — Configure ou retourne le timeout
- imap_uid — Retourne l'UID d'un message
- imap_undelete — Enlève la marque d'effacement d'un message
- imap_unsubscribe — Termine la souscription à une boîte aux lettres
- imap_utf7_decode — Décode une chaîne encodée en UTF-7 modifié
- imap_utf7_encode — Convertit une chaîne ISO-8859-1 en texte UTF-7 modifié
- imap_utf8 — Convertit du texte au format MIME en UTF-8
- imap_utf8_to_mutf7 — Encode une chaîne de caractères UTF-8 en UTF-7 modifié

# La classe IMAP\Connection

(PHP 8 >= 8.1.0)

## Introduction

Une classe complètement opaque qui remplace la resource `imap` à partir de PHP 8.1.0.

## Synopsis de la classe

final class IMAP\Connection {
}

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Fonctions IMAP
  - imap_8bit — Convertit une chaîne à 8 bits en une chaîne encodée en Quoted-Printable
  - imap_alerts — Retourne toutes les alertes
  - imap_append — Ajoute un message dans une boîte aux lettres
  - imap_base64 — Décode un texte encodé en BASE64
  - imap_binary — Convertit une chaîne à 8 bits en une chaîne à base64
  - imap_body — Lit le corps d'un message
  - imap_bodystruct — Lit la structure d'une section du corps d'un mail
  - imap_check — Vérifie la boîte aux lettres courante
  - imap_clearflag_full — Supprime un flag (drapeau) sur un message
  - imap_close — Termine un flux IMAP
  - imap_create — Alias de imap_createmailbox
  - imap_createmailbox — Crée une nouvelle boîte aux lettres
  - imap_delete — Marque le message pour l'effacement, dans la boîte aux lettres courante
  - imap_deletemailbox — Efface une boîte aux lettres
  - imap_errors — Retourne toutes les erreurs IMAP survenues
  - imap_expunge — Efface tous les messages marqués pour l'effacement
  - imap_fetch_overview — Lit le sommaire des en-têtes de messages
  - imap_fetchbody — Retourne une section extraite du corps d'un message
  - imap_fetchheader — Retourne l'en-tête d'un message
  - imap_fetchmime — Récupère les en-têtes MIME pour une section particulière du message
  - imap_fetchstructure — Lit la structure d'un message
  - imap_fetchtext — Alias de imap_body
  - imap_gc — Efface le cache IMAP
  - imap_get_quota — Lit les quotas des boîtes aux lettres ainsi que des statistiques sur chacune d'elles
  - imap_get_quotaroot — Lit les quotas de chaque utilisateur
  - imap_getacl — Retourne le ACL pour la boîte aux lettres
  - imap_getmailboxes — Liste les boîtes aux lettres, et retourne les détails de chacune
  - imap_getsubscribed — Liste toutes les boîtes aux lettres souscrites
  - imap_header — Alias de imap_headerinfo
  - imap_headerinfo — Lit l'en-tête du message
  - imap_headers — Retourne les en-têtes de tous les messages d'une boîte aux lettres
  - imap_is_open — Vérifier si le flux IMAP est toujours valide
  - imap_last_error — Retourne la dernière erreur survenue
  - imap_list — Lit la liste des boîtes aux lettres
  - imap_listmailbox — Alias de imap_list
  - imap_listscan — Lit la liste des boîtes aux lettres, et y recherche une chaîne
  - imap_listsubscribed — Alias de imap_lsub
  - imap_lsub — Liste toutes les boîtes aux lettres enregistrées
  - imap_mail — Envoie un message mail
  - imap_mail_compose — Crée un message MIME
  - imap_mail_copy — Copie les messages spécifiés dans une boîte aux lettres
  - imap_mail_move — Déplace des messages dans une boîte aux lettres
  - imap_mailboxmsginfo — Lit les informations à propos de la boîte aux lettres courante
  - imap_mime_header_decode — Décode les éléments MIME d'un en-tête
  - imap_msgno — Retourne le numéro de séquence du message pour un UID donné
  - imap_mutf7_to_utf8 — Décode une chaîne de caractères UTF-7 modifié en UTF-8
  - imap_num_msg — Retourne le nombre de messages dans la boîte aux lettres courante
  - imap_num_recent — Retourne le nombre de messages récents dans la boîte aux lettres courante
  - imap_open — Ouvre un flux IMAP vers une boîte aux lettres
  - imap_ping — Vérifie que le flux IMAP est toujours actif
  - imap_qprint — Convertit une chaîne à guillemets en une chaîne à 8 bits
  - imap_rename — Alias de imap_renamemailbox
  - imap_renamemailbox — Renomme une boîte aux lettres
  - imap_reopen — Réouvre un flux IMAP vers une nouvelle boîte aux lettres
  - imap_rfc822_parse_adrlist — Analyse une adresse email
  - imap_rfc822_parse_headers — Analyse un en-tête mail
  - imap_rfc822_write_address — Retourne une adresse email formatée correctement
  - imap_savebody — Sauvegarde une partie spécifique du corps dans un fichier
  - imap_scan — Alias de imap_listscan
  - imap_scanmailbox — Alias de imap_listscan
  - imap_search — Retourne un tableau de messages après recherche
  - imap_set_quota — Modifie le quota d'une boîte aux lettres
  - imap_setacl — Modifie le ACL de la boîte aux lettres
  - imap_setflag_full — Positionne un drapeau sur un message
  - imap_sort — Trie des messages
  - imap_status — Retourne les informations de statut sur une boîte aux lettres
  - imap_subscribe — Souscrit à une boîte aux lettres
  - imap_thread — Retourne l'arbre des messages organisés par thread
  - imap_timeout — Configure ou retourne le timeout
  - imap_uid — Retourne l'UID d'un message
  - imap_undelete — Enlève la marque d'effacement d'un message
  - imap_unsubscribe — Termine la souscription à une boîte aux lettres
  - imap_utf7_decode — Décode une chaîne encodée en UTF-7 modifié
  - imap_utf7_encode — Convertit une chaîne ISO-8859-1 en texte UTF-7 modifié
  - imap_utf8 — Convertit du texte au format MIME en UTF-8
  - imap_utf8_to_mutf7 — Encode une chaîne de caractères UTF-8 en UTF-7 modifié
- IMAP\Connection — La classe IMAP\Connection

# Mail

# Introduction

La fonction mail() permet d'envoyer un mail.

# Installation/Configuration

## Sommaire

- Pré-requis
- Configuration à l'exécution

## Pré-requis

Pour que la fonction mail() soit disponible, il faut que PHP ait accès au service `sendmail` sur le serveur, au moment de la compilation. Lors de l'utilisation d'un autre programme de mail, comme qmail ou postfix, il faut s'assurer d'utiliser les bonnes API. PHP va commencer à chercher sendmail dans le PATH, puis, dans les dossiers suivants : `/usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib`. Il est hautement recommandé d'avoir sendmail de disponible dans le PATH. De plus, l'utilisateur qui compile PHP doit avoir le droit d'accéder à l'exécutable sendmail.

## Configuration à l'exécution

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

Options de configuration pour le mail
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
mail.add_x_header | "0" | `INI_PERDIR` |
mail.mixed_lf_and_crlf | "0" | `INI_SYSTEM`|`INI_PERDIR` | Ajouté dans PHP 8.2.4
mail.log | NULL | `INI_SYSTEM`|`INI_PERDIR` |
mail.force_extra_parameters | NULL | `INI_SYSTEM` |
SMTP | "localhost" | `INI_ALL` |
smtp_port | "25" | `INI_ALL` |
sendmail_from | NULL | `INI_ALL` |
sendmail_path | "/usr/sbin/sendmail -t -i" | `INI_SYSTEM` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`mail.add_x_header` bool

  Ajoute un en-tête `X-PHP-Originating-Script` qui inclut l'UID du script, suivi par le nom du fichier.

`mail.log` string

  Le chemin de l'historique de tous les appels à la fonction mail(). Les entrées de l'historique incluent le chemin complet vers le script, le numéro de la ligne, les adresses `To` ainsi que les en-têtes.

`mail.mixed_lf_and_crlf` bool

  Permet de revenir à l'indicateur de fin de ligne pour les en-têtes de courrier électronique et les corps de message en LF (Line Feed), imitant le comportement non conforme de PHP 7. Il est fourni comme mesure de compatibilité pour certains Agents de transfert de courrier (MTA) non conformes qui échouent à traiter correctement CRLF (Retour chariot + Line Feed) comme indicateur de fin de ligne dans les en-têtes de courrier électronique et le contenu des messages.

`mail.force_extra_parameters` string

  Permet de forcer l'ajout du paramètre spécifié en tant que paramètre supplémentaire pour sendmail. Ces paramètres prendront la place du cinquième paramètre de la fonction mail().

  En plus du comportement par défaut pour `INI_SYSTEM`, cette valeur peut également être définie avec `php_value` dans httpd.conf (mais cela n'est pas recommandé).
`smtp` string

  Sous Windows seulement : nom de l'hôte ou adresse IP du SMTP que PHP doit utiliser pour envoyer un mail avec la fonction mail().

`smtp_port` int

  Sous Windows seulement : numéro de port à utiliser pour se connecter au serveur `SMTP` lors de l'envoi de mail avec la fonction mail(); par défaut, c'est 25.

`sendmail_from` string

  Sous Windows seulement : valeur du champ `"From:"` qui doit être utilisée lors de l'envoi de mail via SMTP (uniquement sous Windows). Cette directive définira également l'en-tête `"Return-Path:"`.

`sendmail_path` string

  Localisation du programme sendmail : habituellement /usr/sbin/sendmail ou /usr/lib/sendmail. configure essaye de repérer la présence de sendmail par lui-même, et affecte ce résultat par défaut. En cas de problème de localisation, il est possible d'établir une nouvelle valeur par défaut ici.

  Tout système n'utilisant pas sendmail doit établir cette directive à la valeur chemin du programme de substitution qui remplace le serveur de mail, si celui-ci existe. Par exemple, les utilisateurs de » Qmail peuvent la définir à /var/qmail/bin/sendmail ou /var/qmail/bin/qmail-inject.

  qmail-inject ne requiert aucune option pour traiter correctement le mail.

  Cette directive fonctionne également sous Windows. Si elle est définie, smtp, smtp_port et sendmail_from sont ignorés et la commande spécifiée est exécutée.

# Fonctions Mail

# ezmlm_hash

(PHP 4 >= 4.0.2, PHP 5, PHP 7)

ezmlm_hash — Calcule le hachage demandé par EZMLM

Avertissement

Cette fonction est OBSOLÈTE à partir de PHP 7.4.0, et a été SUPPRIMÉE à partir de PHP 8.0.0. Dépendre de cette fonction est fortement déconseillé.

### Description

function ezmlm_hash(string `$addr`): int

ezmlm_hash() calcule le hachage nécessaire lors de la gestion de listes de diffusion EZMLM avec une base de données MySQL.

### Liste de paramètres

`addr`

  L'adresse E-Mail qui doit être hachée.

### Valeurs de retour

La valeur du hachage de `addr`.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction a été supprimée.
7.2.0 | Cette fonction est obsolète.

### Exemples

Exemple #1 Calcul du hachage et enregistrement d'un utilisateur de liste de diffusion

    <?php

         $user = "joecool@example.com";
         $hash = ezmlm_hash($user);
         $query = sprintf("INSERT INTO sample VALUES (%s, '%s')", $hash, $user);
         $db->query($query); // utilisation de l'interface PHPLIB

    ?>

# mail

(PHP 4, PHP 5, PHP 7, PHP 8)

mail — Envoi de mail

### Description

function mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
string `$additional_params` = ""
): bool

Envoie un mail.

### Liste de paramètres

`to`

  Le ou les destinataires du mail.

  Le formatage de cette chaîne doit correspondre avec la » RFC 2822. Voici quelques exemples :

  - destinataire@example.com
  - destinataire@example.com, autre_destinataire@example.com
  - Destinataire
  - Destinataire , Autre destinataire
`subject`

  Sujet du mail à envoyer.

  Attention

  Le sujet doit satisfaire à la » RFC 2047.

`message`

  Message à envoyer.

  Chaque ligne doit être séparée par un caractère `CRLF` (`\r\n`). Les lignes ne doivent pas comporter plus de 70 caractères.

  Attention

  (Windows uniquement) Lorsque PHP discute directement avec un serveur SMTP, si un point est trouvé en début de ligne, il sera supprimé. Pour éviter ce comportement, remplacez ces occurrences par un double point.

      <?php
           $text = str_replace("\n.", "\n..", $text);
      ?>

`additional_headers` (optionnel)

  String ou array à insérer à la fin des en-têtes du mail.

  Ce paramètre est typiquement utilisé pour ajouter des en-têtes supplémentaires (From, Cc et Bcc). Les en-têtes supplémentaires doivent être séparés par un caractère `CRLF` (`\r\n`). Si des données externes sont utilisées pour composer cet en-tête, elles doivent être d'abord nettoyées afin de ne pas injecter des données non désirées dans les en-têtes.

  Si un array est passé, ses clés sont les noms d'en-tête et ses valeurs sont les valeurs d'en-tête respectives.

  > Note:

  > Lors de l'envoi d'un mail, le mail doit contenir un en-tête `From`. Il peut être défini par le paramètre `additional_headers`, ou un par défaut peut être défini dans le php.ini.

  > Ne pas faire ceci causera un message d'erreur similaire à `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing`. L'en-tête `From` définit également l'en-tête `Return-Path` lors de l'envoi direct via SMTP (Windows uniquement).

  > Note:

  > Si le message n'est pas reçu, essayez d'utiliser uniquement un caractère `LF` (`\n`). Quelques agents de transfert de mail Unix (par exemple » qmail) remplacent le caractère `LF` par le caractère `CRLF` automatiquement (ce qui revient à doubler le caractère `CR` si le caractère `CRLF` est utilisé). Ceci doit être un dernier recours car cela ne correspond pas à la » RFC 2822.

`additional_params` (optionnel)

  Le paramètre `additional_params` peut être utilisé pour passer des drapeaux additionnels comme options à la ligne de commande configurée pour être utilisée pour envoyer les mails en utilisant le paramètre de configuration `sendmail_path`. Par exemple, ceci peut être utilisé pour définir l'adresse d'expéditeur de l'enveloppe lors de l'utilisation de sendmail avec l'option `-f`.

  Ce paramètre est échappé par la fonction escapeshellcmd() en interne afin de prévenir l'exécution d'une commande. La fonction escapeshellcmd() empêche l'exécution d'une commande, mais autorise l'ajout de paramètres supplémentaires. Pour des raisons de sécurité, il est recommandé pour l'utilisateur de nettoyer ce paramètre afin d'éviter l'ajout de paramètres non désirés à la commande shell.

  Étant donné que la fonction escapeshellcmd() est appliquée automatiquement, quelques caractères autorisés dans les adresses emails par les RFCs d'internet ne peuvent plus être utilisés. La fonction mail() ne peut autoriser ces caractères, aussi, dans les programmes où leur utilisation est nécessaire, il est recommandé d'utiliser une méthode alternative pour l'envoi des emails (comme l'utilisation d'un framework ou d'une bibliothèque).

  L'utilisateur sous lequel tourne le serveur web doit être ajouté en tant qu'utilisateur de confiance dans la configuration de sendmail afin que l'en-tête `X-Warning` ne soit pas ajouté au message lorsque l'expéditeur de l'enveloppe (-f) est défini en utilisant cette méthode. Pour les utilisateurs de sendmail, ce fichier est /etc/mail/trusted-users.

### Valeurs de retour

Retourne `true` si le mail a été accepté pour livraison, `false` sinon.

Il est important de noter que ce n'est pas parce que le mail a été accepté pour livraison qu'il arrivera à destination.

### Historique

Version | Description
--- | ---
7.2.0 | Le paramètre `additional_headers` accepte maintenant les array.

### Exemples

Exemple #1 Envoi d'un mail

Utilisation de la fonction mail() pour envoyer un mail simple :

    <?php
    // Le message
    $message = "Line 1\r\nLine 2\r\nLine 3";

    // Dans le cas où nos lignes comportent plus de 70 caractères, nous les coupons en utilisant wordwrap()
    $message = wordwrap($message, 70, "\r\n");

    // Envoi du mail
    mail('caffeinated@example.com', 'Mon Sujet', $message);
    ?>

Exemple #2 Envoi d'un mail avec des en-têtes supplémentaires

L'ajout d'en-têtes simples, spécifiant au MUA les adresses `"From"` et `"Reply-To"` :

    <?php
         $to      = 'personne@example.com';
         $subject = 'le sujet';
         $message = 'Bonjour !';
         $headers = 'From: webmaster@example.com' . "\r\n" .
         'Reply-To: webmaster@example.com' . "\r\n" .
         'X-Mailer: PHP/' . phpversion();

         mail($to, $subject, $message, $headers);
     ?>

Exemple #3 Envoi d'un mail avec un array d'en-têtes supplémentaires

Cet exemple envoie le même courrier que l'exemple ci-dessus, mais passe les en-têtes supplémentaires en tant que tableau (disponible à partir de PHP 7.2.0).

    <?php
    $to      = 'nobody@example.com';
    $subject = 'the subject';
    $message = 'hello';
    $headers = array(
        'From' => 'webmaster@example.com',
        'Reply-To' => 'webmaster@example.com',
        'X-Mailer' => 'PHP/' . phpversion()
    );

    mail($to, $subject, $message, $headers);
    ?>

Exemple #4 Envoi d'un mail avec un paramètre de ligne de commande additionnel

Le paramètre `additional_params` peut être utilisé pour passer un paramètre additionnel au programme configuré à être utilisé pour envoyer les mails en utilisant `sendmail_path`.

    <?php
         mail('personne@example.com', 'le sujet', 'le message', null,
         '-fwebmaster@example.com');
    ?>

Exemple #5 Envoi de mail HTML

Il est également possible d'envoyer des mails HTML avec la fonction mail().

    <?php
         // Plusieurs destinataires
         $to  = 'johny@example.com, sally@example.com'; // notez la virgule

         // Sujet
         $subject = 'Calendrier des anniversaires pour Août';

         // message
         $message = '
         <html>
          <head>
           <title>Calendrier des anniversaires pour Août</title>
          </head>
          <body>
           <p>Voici les anniversaires à venir au mois d\'Août !</p>
           <table>
            <tr>
             <th>Personne</th><th>Jour</th><th>Mois</th><th>Année</th>
            </tr>
            <tr>
             <td>Josiane</td><td>3</td><td>Août</td><td>1970</td>
            </tr>
            <tr>
             <td>Emma</td><td>26</td><td>Août</td><td>1973</td>
            </tr>
           </table>
          </body>
         </html>
         ';

         // Pour envoyer un mail HTML, l'en-tête Content-type doit être défini
         $headers[] = 'MIME-Version: 1.0';
         $headers[] = 'Content-type: text/html; charset=iso-8859-1';

         // En-têtes additionnels
         $headers[] = 'To: Mary <mary@example.com>, Kelly <kelly@example.com>';
         $headers[] = 'From: Anniversaire <anniversaire@example.com>';
         $headers[] = 'Cc: anniversaire_archive@example.com';
         $headers[] = 'Bcc: anniversaire_verif@example.com';

         // Envoi
         mail($to, $subject, $message, implode("\r\n", $headers));
    ?>

> Note:

> Si l'on prévoit d'envoyer des mails HTML ou autrement plus complexes, il est recommandé d'utiliser le paquet PEAR » PEAR::Mail_Mime.

### Notes

> Note:

> L'implémentation SMTP (uniquement sous Windows) de la fonction mail() diffère de manière significative avec l'implémentation de sendmail. Tout d'abord, elle n'utilise pas un programme local pour composer les messages, mais opère uniquement et directement sur les sockets, ce qui signifie qu'un `MTA` est nécessairement à l'écoute sur un socket du réseau (qui peut être soit sur le réseau local ou sur une machine distante).

> Deuxièmement, les en-têtes personnalisés comme `From:`, `Cc:`, `Bcc:` et `Date:` ne sont pas interprétés par le `MTA` dans un premier temps, mais sont analysés par PHP.

> De plus, le paramètre `to` ne doit pas être une adresse sous la forme `"Quelque chose <quelqu_un@example.com>"`. La commande mail n'analysera pas correctement ceci lors de la discussion avec le MTA.

> Note:

> Il est important de noter que la fonction mail() n'est pas conseillée pour traiter de gros volumes de mails dans une boucle. Cette fonction ouvre et ferme un socket SMTP pour chaque mail, ce qui n'est pas très efficace.

> Pour envoyer de gros volumes de mails, se reporter aux paquets » PEAR::Mail et » PEAR::Mail_Queue.

> Note:

> Les RFC suivantes peuvent être utiles : » RFC 1896, » RFC 2045, » RFC 2046, » RFC 2047, » RFC 2048, » RFC 2049 et » RFC 2822.

### Voir aussi

- mb_send_mail() - Envoie un mail encodé
- imap_mail() - Envoie un message mail
- » PEAR::Mail
- » PEAR::Mail_Mime

## Sommaire

- ezmlm_hash — Calcule le hachage demandé par EZMLM
- mail — Envoi de mail

- Installation/Configuration
  - Pré-requis
  - Configuration à l'exécution
- Fonctions Mail
  - ezmlm_hash — Calcule le hachage demandé par EZMLM
  - mail — Envoi de mail

# Mailparse

# Introduction

Mailparse est une extension pour analyser et travailler avec les messages électroniques. Elle peut gérer les messages répondant aux » RFC 822 et » RFC 2045 (`MIME`).

Mailparse est basé sur les flux, ce qui signifie qu'il ne conserve pas en mémoire les copies des fichiers dont il s'occupe - ainsi, il est peu coûteux en ressources lorsqu'il traite de gros messages.

> Note: Mailparse nécessite l'extension mbstring, et mbstring doit être chargé avant mailparse.

# Installation/Configuration

## Sommaire

- Installation
- Configuration à l'exécution
- Types de ressources

## Installation

Cette extension » PECL n'est pas intégrée à PHP. Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/mailparse.

Pour utiliser ces fonctions, il faut compiler PHP avec le support mailparse en utilisant l'option de configuration --enable-mailparse.

Les utilisateurs de Windows doivent activer la bibliothèque php_mailparse.dll dans le php.ini pour pouvoir utiliser ces fonctions. Les binaires Windows (les fichiers DLL) pour cette extension PECL sont disponibles sur le site web PECL.

Il est nécessaire que l'extension mbstring soit chargée avant mailparse.

## Configuration à l'exécution

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

Mailparse Options de configuration
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
mailparse.def_charset | "us-ascii" | `INI_SYSTEM` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`mailparse.def_charset` string
  Le jeu de caractères par défaut.

## Types de ressources

Mailparse définit le type de ressource `mailparse_mail_structure`, qui est retourné par mailparse_msg_create() et mailparse_msg_parse_file().

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`MAILPARSE_EXTRACT_OUTPUT` (int)
`MAILPARSE_EXTRACT_STREAM` (int)
`MAILPARSE_EXTRACT_RETURN` (int)

# Fonctions Mailparse

# mailparse_determine_best_xfer_encoding

(PECL mailparse >= 0.9.0)

mailparse_determine_best_xfer_encoding — Détermine le meilleur encodage pour un fichier

### Description

function mailparse_determine_best_xfer_encoding(resource `$fp`): string

Détermine le meilleur encodage pour le contenu du fichier fourni.

### Liste de paramètres

`fp`
  Un pointeur de fichier valide, qui peut être lu.

### Valeurs de retour

Retourne un encodage de caractères supporté par le module mbstring.

### Exemples

Exemple #1 Exemple avec mailparse_determine_best_xfer_encoding()

    <?php

    $fp = fopen('somemail.eml', 'r');
    echo 'Meilleur encodage : ' . mailparse_determine_best_xfer_encoding($fp);

    ?>

Résultat de l'exemple ci-dessus est similaire à :

    Meilleur encodage : 7bit

# mailparse_msg_create

(PECL mailparse >= 0.9.0)

mailparse_msg_create — Crée une ressource email mime

### Description

function mailparse_msg_create(): resource

Crée une ressource email `MIME`.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne un gestionnaire qui pourra être utilisé pour analyser un message.

### Notes

> Note: Il est recommandé d'appeler mailparse_msg_free() sur le résultat de cette fonction, quand il n'est plus nécessaire, pour éviter des fuites de mémoire.

### Voir aussi

- mailparse_msg_free() - Libère une ressource MIME
- mailparse_msg_parse_file() - Analyse un fichier

# mailparse_msg_extract_part

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part — Extrait et décode une section de message

### Description

function mailparse_msg_extract_part(resource `$mimemail`, string `$msgbody`, callable `$callbackfunc` = ?): void
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`mimemail`
  Une ressource `MIME` valide.
`msgbody`
`callbackfunc`

### Valeurs de retour

Aucune valeur n'est retournée.

### Voir aussi

- mailparse_msg_extract_part_file() - Extrait et décode une section de message
- mailparse_msg_extract_whole_part_file() - Extrait une section de message incluant les en-têtes sans décoder l'encodage de transfert

# mailparse_msg_extract_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part_file — Extrait et décode une section de message

### Description

function mailparse_msg_extract_part_file(resource `$mimemail`, mixed `$filename`, callable `$callbackfunc` = ?): string

Extrait et décode une section de message depuis le fichier fourni.

Le contenu de la section sera décodé suivant son encodage de transfert - base64, quoted-printable et texte uuencoded sont supportés.

### Liste de paramètres

`mimemail`
  Une ressource valide `MIME`, créée avec la fonction mailparse_msg_create().
`filename`
  Peut être un nom de fichier ou un flux valide.
`callbackfunc`
  Si défini, ce peut être soit un callback valide qui sera passé à la section extraite, soit `null` pour faire que cette fonction retourne la section extraite. Si non fourni, le contenu sera envoyé à "stdout".

### Valeurs de retour

Si `callbackfunc` ne vaut pas `null` retourne `true` en cas de succès.

Si `callbackfunc` vaut `null`, retourne la section extraite sous la forme d'une chaîne de caractères.

Retourne `false` si une erreur survient.

### Voir aussi

- mailparse_msg_extract_part() - Extrait et décode une section de message
- mailparse_msg_extract_whole_part_file() - Extrait une section de message incluant les en-têtes sans décoder l'encodage de transfert

# mailparse_msg_extract_whole_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_whole_part_file — Extrait une section de message incluant les en-têtes sans décoder l'encodage de transfert

### Description

function mailparse_msg_extract_whole_part_file(resource `$mimemail`, string `$filename`, callable `$callbackfunc` = ?): string
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`mimemail`
  Une ressource `MIME` valide.
`filename`
`callbackfunc`

### Valeurs de retour

### Voir aussi

- mailparse_msg_extract_part() - Extrait et décode une section de message
- mailparse_msg_extract_part_file() - Extrait et décode une section de message

# mailparse_msg_free

(PECL mailparse >= 0.9.0)

mailparse_msg_free — Libère une ressource MIME

### Description

function mailparse_msg_free(resource `$mimemail`): bool

Libère une ressource `MIME`.

### Liste de paramètres

`mimemail`
  Une ressource `MIME` allouée par la fonction mailparse_msg_create() ou la fonction mailparse_msg_parse_file().

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Voir aussi

- mailparse_msg_create() - Crée une ressource email mime
- mailparse_msg_parse_file() - Analyse un fichier

# mailparse_msg_get_part

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part — Retourne une ressource sur une section d'un message MIME

### Description

function mailparse_msg_get_part(resource `$mimemail`, string `$mimesection`): resource
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`mimemail`
  Une ressource `MIME` valide.
`mimesection`

# mailparse_msg_get_part_data

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part_data — Retourne un tableau associatif avec des informations sur le message

### Description

function mailparse_msg_get_part_data(resource `$mimemail`): array
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`mimemail`
  Une ressource `MIME` valide.

# mailparse_msg_get_structure

(PECL mailparse >= 0.9.0)

mailparse_msg_get_structure — Retourne un tableau avec les différentes sections MIME du message

### Description

function mailparse_msg_get_structure(resource `$mimemail`): array
Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`mimemail`
  Une ressource `MIME` valide.

# mailparse_msg_parse

(PECL mailparse >= 0.9.0)

mailparse_msg_parse — Analyse incrémentalement des données dans un buffer

### Description

function mailparse_msg_parse(resource `$mimemail`, string `$data`): bool

Analyse incrémentalement des données dans une ressource `MIME` fournie.

Cette fonction permet d'envoyer sous forme de flux des portions d'un fichier à la fois, plutôt que de tout lire et de tout analyser en une seule fois.

### Liste de paramètres

`mimemail`
  Une ressource `MIME` valide.
`data`

  > Note: Le bloc final d'un `data` est supposé être un caractère de nouvelle ligne (`CRLF`) ; sinon, la dernière ligne du message ne sera pas analysée.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

# mailparse_msg_parse_file

(PECL mailparse >= 0.9.0)

mailparse_msg_parse_file — Analyse un fichier

### Description

function mailparse_msg_parse_file(string `$filename`): resource

Analyse un fichier. C'est la façon optimale d'analyser un email qu'on a sur le disque.

### Liste de paramètres

`filename`
  Chemin vers le fichier contenant le message. Le fichier sera ouvert et envoyé sous forme de flux à l'analyseur.

  > Note: Le message contenu dans le paramètre `filename` est supposé se terminer avec un caractère de nouvelle ligne (`CRLF`) ; sinon, la dernière ligne du message ne sera pas analysée.

### Valeurs de retour

Retourne une ressource `MIME` représentant la structure, ou `false` si une erreur survient.

### Notes

> Note: Il est recommandé d'appeler mailparse_msg_free() sur le résultat de cette fonction, quand il n'est plus nécessaire, pour éviter des fuites de mémoire.

### Voir aussi

- mailparse_msg_free() - Libère une ressource MIME
- mailparse_msg_create() - Crée une ressource email mime

# mailparse_rfc822_parse_addresses

(PECL mailparse >= 0.9.0)

mailparse_rfc822_parse_addresses — Analyse des adresses

### Description

function mailparse_rfc822_parse_addresses(string `$addresses`): array

Analyse une liste d'adresses valides eu égard à la » RFC 822, comme celles trouvées dans l'en-tête `To:`.

### Liste de paramètres

`addresses`
  Une chaîne de caractères contenant les adresses, comme : `Wez Furlong <wez@example.com>, doe@example.com`

  > Note: Cette chaîne de caractères ne doit pas contenir le nom de l'en-tête.

### Valeurs de retour

Retourne un tableau de tableaux associatifs contenant les clés suivantes pour chaque adresse :

`display` | Le nom de l'adresse, aux fins d'affichage. Si cette partie n'est pas définie pour une adresse, il contiendra la même valeur que la clé `address`.
`address` | L'adresse email
`is_group` | `true` si l'adresse est un newsgroup, `false` sinon.

### Exemples

Exemple #1 Exemple avec mailparse_rfc822_parse_addresses()

    <?php

    $to = 'Wez Furlong <wez@example.com>, doe@example.com';
    var_dump(mailparse_rfc822_parse_addresses($to));

    ?>

L'exemple ci-dessus va afficher :

    array(2) {
      [0]=>
      array(3) {
        ["display"]=>
        string(11) "Wez Furlong"
        ["address"]=>
        string(15) "wez@example.com"
        ["is_group"]=>
        bool(false)
      }
      [1]=>
      array(3) {
        ["display"]=>
        string(15) "doe@example.com"
        ["address"]=>
        string(15) "doe@example.com"
        ["is_group"]=>
        bool(false)
      }
    }

# mailparse_stream_encode

(PECL mailparse >= 0.9.0)

mailparse_stream_encode — Lit les données dans un fichier, applique l'encodage et envoie le résultat à destfp

### Description

function mailparse_stream_encode(resource `$sourcefp`, resource `$destfp`, string `$encoding`): bool

Lit les données dans un fichier, applique l'encodage `encoding` et envoie le résultat à destfp.

### Liste de paramètres

`sourcefp`
  Un gestionnaire de fichier valide. Le fichier sera envoyé à l'analyseur sous forme de flux.
`destfp`
  Le gestionnaire de fichier destinataire, dans lequel les données encodées seront écrites.
`encoding`
  Un des encodages de caractères supportés par le module mbstring.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Exemples

Exemple #1 Exemple avec mailparse_stream_encode()

    <?php

    // Contenu de email.eml : hello, this is some text=hello.
    $fp = fopen('email.eml', 'r');

    $dest = tmpfile();

    mailparse_stream_encode($fp, $dest, "quoted-printable");

    rewind($dest);

    // Affiche le nouveau contenu du fichier
    fpassthru($dest);

    ?>

L'exemple ci-dessus va afficher :

    hello, this is some text=3Dhello.

# mailparse_uudecode_all

(PECL mailparse >= 0.9.0)

mailparse_uudecode_all — Scanne les données du fichier et extrait tous les fichiers encodés qui s'y trouvent

### Description

function mailparse_uudecode_all(resource `$fp`): array

Scanne les données du fichier fourni et extrait, dans un fichier temporaire, tous les fichiers encodés qui s'y trouvent.

### Liste de paramètres

`fp`
  Un pointeur de fichier valide.

### Valeurs de retour

Retourne un tableau de tableaux associatifs listant les informations sur les noms de fichiers.

`filename` | Chemin vers le fichier temporaire à créer
`origfilename` | Le nom de fichier original, pour les sections uuencoded uniquement

La première entrée du fichier est le corps du message. Les entrées suivantes sont les fichiers décodés uuencoded.

### Exemples

Exemple #1 Exemple avec mailparse_uudecode_all()

    <?php

    $text = <<<EOD
    To: fred@example.com

    hello, this is some text hello.
    blah blah blah.

    begin 644 test.txt
    /=&AI<R!I<R!A('1E<W0*
    `
    end

    EOD;

    $fp = tmpfile();
    fwrite($fp, $text);

    $data = mailparse_uudecode_all($fp);

    echo "BODY\n";
    readfile($data[0]["filename"]);
    echo "UUE ({$data[1]['origfilename']})\n";
    readfile($data[1]["filename"]);

    // Nettoyage
    unlink($data[0]["filename"]);
    unlink($data[1]["filename"]);

    ?>

L'exemple ci-dessus va afficher :

    BODY
    To: fred@example.com

    hello, this is some text hello.
    blah blah blah.

    UUE (test.txt)
    this is a test

## Sommaire

- mailparse_determine_best_xfer_encoding — Détermine le meilleur encodage pour un fichier
- mailparse_msg_create — Crée une ressource email mime
- mailparse_msg_extract_part — Extrait et décode une section de message
- mailparse_msg_extract_part_file — Extrait et décode une section de message
- mailparse_msg_extract_whole_part_file — Extrait une section de message incluant les en-têtes sans décoder l'encodage de transfert
- mailparse_msg_free — Libère une ressource MIME
- mailparse_msg_get_part — Retourne une ressource sur une section d'un message MIME
- mailparse_msg_get_part_data — Retourne un tableau associatif avec des informations sur le message
- mailparse_msg_get_structure — Retourne un tableau avec les différentes sections MIME du message
- mailparse_msg_parse — Analyse incrémentalement des données dans un buffer
- mailparse_msg_parse_file — Analyse un fichier
- mailparse_rfc822_parse_addresses — Analyse des adresses
- mailparse_stream_encode — Lit les données dans un fichier, applique l'encodage et envoie le résultat à destfp
- mailparse_uudecode_all — Scanne les données du fichier et extrait tous les fichiers encodés qui s'y trouvent

- Installation/Configuration
  - Installation
  - Configuration à l'exécution
  - Types de ressources
- Constantes pré-définies
- Fonctions Mailparse
  - mailparse_determine_best_xfer_encoding — Détermine le meilleur encodage pour un fichier
  - mailparse_msg_create — Crée une ressource email mime
  - mailparse_msg_extract_part — Extrait et décode une section de message
  - mailparse_msg_extract_part_file — Extrait et décode une section de message
  - mailparse_msg_extract_whole_part_file — Extrait une section de message incluant les en-têtes sans décoder l'encodage de transfert
  - mailparse_msg_free — Libère une ressource MIME
  - mailparse_msg_get_part — Retourne une ressource sur une section d'un message MIME
  - mailparse_msg_get_part_data — Retourne un tableau associatif avec des informations sur le message
  - mailparse_msg_get_structure — Retourne un tableau avec les différentes sections MIME du message
  - mailparse_msg_parse — Analyse incrémentalement des données dans un buffer
  - mailparse_msg_parse_file — Analyse un fichier
  - mailparse_rfc822_parse_addresses — Analyse des adresses
  - mailparse_stream_encode — Lit les données dans un fichier, applique l'encodage et envoie le résultat à destfp
  - mailparse_uudecode_all — Scanne les données du fichier et extrait tous les fichiers encodés qui s'y trouvent

- IMAP — IMAP, POP3 et NNTP
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions IMAP
  - IMAP\Connection — La classe IMAP\Connection
- Mail
  - Installation/Configuration
  - Fonctions Mail
- Mailparse
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Mailparse

# Extensions sur les mathématiques

# Fonctions BCMath

# Introduction

Pour les calculs mathématiques d'une grande précision, PHP fournit BCMath, qui supporte n'importe quelle précision et n'importe quelle taille de nombres jusqu'à `2147483647` (ou `0x7FFFFFFF`) chiffres décimaux, s'il y a suffisamment de mémoire, représentés sous la forme d'une chaîne de caractères.

Les nombres BCMath valides (c.-à-d. bien formés) sont des chaînes qui correspondent à l'expression régulière `/^[+-]?[0-9]*(\.[0-9]*)?$/`.

Attention

Le passage de valeurs de type nombre décimal à une fonction BCMath qui attend une chaîne de caractères comme opérande peut ne pas avoir l'effet désiré en raison de la façon dont PHP convertit les valeurs nombre décimal en chaîne de caractères, à savoir que la chaîne de caractères peut être en notation exponentielle (ce qui n'est pas supporté par BCMath), et que, antérieurement à PHP 8.0.0, le séparateur décimal dépend de la locale (tandis que BCMath attend toujours un point décimal).

    <?php
    $num1 = 0; // (string) 0 => '0'
    $num2 = -0.000005; // (string) -0.000005 => '-5.05E-6'
    echo bcadd($num1, $num2, 6); // => '0.000000'

    setlocale(LC_NUMERIC, 'de_DE'); // utilise une virgule décimale
    $num2 = 1.2; // (string) 1.2 => '1,2'
    echo bcsub($num1, $num2, 1); // => '0.0'
    ?>

# Installation/Configuration

## Sommaire

- Installation
- Configuration à l'exécution

## Installation

Ces fonctions ne sont disponibles que si l'option de configuration --enable-bcmath a été activée lors de la compilation.

La version Windows de PHP dispose du support automatique de cette extension. Vous n'avez pas à ajouter de bibliothèque supplémentaire pour disposer de ces fonctions.

## Configuration à l'exécution

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

Options de configuration BCmaths
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
bcmath.scale | "0" | `INI_ALL` |

Pour plus de détails sur les modes INI_*, reportez-vous à Où une directive de configuration peut être modifiée.

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

`bcmath.scale` int

  Le nombre de décimales pour toutes les fonctions bcmath. Voir aussi bcscale().

  > Note: BcMath\Number n'est pas affecté par ce paramètre.

# Fonctions BC Math

# bcadd

(PHP 4, PHP 5, PHP 7, PHP 8)

bcadd — Additionne deux nombres de grande taille

### Description

function bcadd(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Additionne `num1` et `num2`.

### Liste de paramètres

`num1`

  L'opérande gauche, sous la forme d'une chaîne de caractères.

`num2`

  L'opérande droit, sous la forme d'une chaîne de caractères.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

La somme des deux opérandes, sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Cette fonction lève une exception ValueError dans les cas suivants :

- `num1` ou `num2` n'est pas une chaîne numérique BCMath correctement formée.
- `scale` est en dehors de la plage valide.

### Historique

Version | Description
--- | ---
8.0.0 | `scale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec bcadd()

    <?php
    $a = '1.234';
    $b = '5';

    echo bcadd($a, $b);     // 6
    echo bcadd($a, $b, 4);  // 6.2340
    ?>

### Voir aussi

- bcsub() - Soustrait un nombre de grande taille d'un autre
- BcMath\Number::add() - Ajouter un nombre de précision arbitraire

# bcceil

(PHP 8 >= 8.4.0)

bcceil — Arrondit au supérieur un nombre de précision arbitraire

### Description

function bcceil(string `$num`): string

Renvoie la valeur entière supérieure suivante en arrondissant `num` si nécessaire.

### Liste de paramètres

`num`
  La valeur à arrondir.

### Valeurs de retour

Renvoie une chaîne numérique représentant `num` arrondi au supérieur à l'entier le plus proche.

### Erreurs / Exceptions

Cette fonction lance une ValueError si `num` n'est pas une chaîne numérique BCMath bien formée.

### Exemples

Exemple #1 Exemple de bcceil()

    <?php
    var_dump(bcceil('4.3'));
    var_dump(bcceil('9.999'));
    var_dump(bcceil('-3.14'));
    ?>

L'exemple ci-dessus va afficher :

    string(1) "5"
    string(2) "10"
    string(2) "-3"

### Voir aussi

- bcfloor() - Arrondit à l'inférieur un nombre de précision arbitraire
- bcround() - Arrondit un nombre de précision arbitraire
- BcMath\Number::ceil() - Arrondit au supérieur un nombre de précision arbitraire

# bccomp

(PHP 4, PHP 5, PHP 7, PHP 8)

bccomp — Compare deux nombres de grande taille

### Description

function bccomp(string `$num1`, string `$num2`, ?int `$scale` = `null`): int

Compare l'opérande `num1` avec `num2` et retourne le résultat sous forme d'un entier.

### Liste de paramètres

`num1`

  L'opérande gauche, sous la forme d'une chaîne de caractères.

`num2`

  L'opérande droit, sous la forme d'une chaîne de caractères.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Retourne `0` si les deux opérandes sont égaux, `1` si `num1` est supérieur à `num2`, ou `-1` sinon.

### Erreurs / Exceptions

Cette fonction lève une exception ValueError dans les cas suivants :

- `num1` ou `num2` n'est pas une chaîne numérique BCMath correctement formée.
- `scale` est en dehors de la plage valide.

### Historique

Version | Description
--- | ---
8.0.0 | `scale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec bccomp()

    <?php

    echo bccomp('1', '2') . "\n";   // -1
    echo bccomp('1.00001', '1', 3); // 0
    echo bccomp('1.00001', '1', 5); // 1

    ?>

### Voir aussi

- BcMath\Number::compare() - Compare deux nombres de précision arbitraire

# bcdiv

(PHP 4, PHP 5, PHP 7, PHP 8)

bcdiv — Divise deux nombres de grande taille

### Description

function bcdiv(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Divise `num1` par `num2`.

### Liste de paramètres

`num1`

  Le dividende, sous la forme d'une chaîne de caractères.

`num2`

  Le diviseur, sous la forme d'une chaîne de caractères.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Retourne le résultat de la division, sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Cette fonction lève une exception ValueError dans les cas suivants :

- `num1` ou `num2` n'est pas une chaîne numérique BCMath correctement formée.
- `scale` est en dehors de la plage valide.

Cette fonction lève une exception DivisionByZeroError si `num2` est égal à `0`.

### Historique

Version | Description
--- | ---
8.0.0 | `scale` est désormais nullable.
8.0.0 | La division par `0` lève désormais une exception DivisionByZeroError au lieu de retourner `null`.

### Exemples

Exemple #1 Exemple avec bcdiv()

    <?php

    echo bcdiv('105', '6.55957', 3);  // 16.007

    ?>

### Voir aussi

- bcdivmod() - Renvoie le quotient et le reste d'un nombre de précision arbitraire
- bcmod() - Retourne le reste d'une division entre nombres de grande taille
- bcmul() - Multiplie deux nombres de grande taille
- BcMath\Number::div() - Divise par un nombre de précision arbitraire

# bcdivmod

(PHP 8 >= 8.4.0)

bcdivmod — Renvoie le quotient et le reste d'un nombre de précision arbitraire

### Description

function bcdivmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): array

Renvoie le quotient et le reste de la division de `num1` par `num2`.

### Liste de paramètres

`num1`

  Le dividende, sous la forme d'une chaîne de caractères.

`num2`

  Le diviseur, sous la forme d'une chaîne de caractères.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Renvoie un array indexé où le premier élément est le quotient sous forme de string et le second élément est le reste sous forme de string.

### Erreurs / Exceptions

Cette fonction lève une exception ValueError dans les cas suivants :

- `num1` ou `num2` n'est pas une chaîne numérique BCMath correctement formée.
- `scale` est en dehors de la plage valide.

Cette fonction lève une exception DivisionByZeroError si `num2` est égal à `0`.

### Exemples

Exemple #1 Exemple de bcdivmod()

    <?php
    bcscale(0);

    [$quot, $rem] = bcdivmod('5',  '3');
    echo $quot; // 1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('5',  '-3');
    echo $quot; // -1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('-5',  '3');
    echo $quot; // -1
    echo $rem;  // -2

    [$quot, $rem] = bcdivmod('-5',  '-3');
    echo $quot; // 1
    echo $rem;  // -2
    ?>

Exemple #2 bcdivmod() avec des décimaux

    <?php
    [$quot, $rem] = bcdivmod('5.7', '1.3', 1);
    echo $quot; // 4
    echo $rem;  // 0.5
    ?>

### Voir aussi

- bcdiv() - Divise deux nombres de grande taille
- bcmod() - Retourne le reste d'une division entre nombres de grande taille
- BcMath\Number::divmod() - Renvoie le quotient et le modulo d'un nombre de précision arbitraire

# bcfloor

(PHP 8 >= 8.4.0)

bcfloor — Arrondit à l'inférieur un nombre de précision arbitraire

### Description

function bcfloor(string `$num`): string

Renvoie la valeur entière inférieure suivante en arrondissant `num` si nécessaire.

### Liste de paramètres

`num`
  La valeur à arrondir.

### Valeurs de retour

Renvoie une chaîne numérique représentant `num` arrondi à l'inférieur à l'entier le plus proche.

### Erreurs / Exceptions

Cette fonction lance une ValueError si `num` n'est pas une chaîne numérique BCMath bien formée.

### Exemples

Exemple #1 Exemple de bcfloor()

    <?php
    var_dump(bcfloor('4.3'));
    var_dump(bcfloor('9.999'));
    var_dump(bcfloor('-3.14'));
    ?>

L'exemple ci-dessus va afficher :

    string(1) "4"
    string(1) "9"
    string(2) "-4"

### Voir aussi

- bcceil() - Arrondit au supérieur un nombre de précision arbitraire
- bcround() - Arrondit un nombre de précision arbitraire
- BcMath\Number::floor() - Arrondit à l'inférieur un nombre de précision arbitraire

# bcmod

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmod — Retourne le reste d'une division entre nombres de grande taille

### Description

function bcmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Retourne le reste de la division de `num1` par `num2`. Le résultat a le même signe que `num1`.

### Liste de paramètres

`num1`

  L'opérande gauche, sous la forme d'une chaîne de caractères.

`num2`

  L'opérande droit, sous la forme d'une chaîne de caractères.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Retourne le modulo, sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Cette fonction lève une exception ValueError dans les cas suivants :

- `num1` ou `num2` n'est pas une chaîne numérique BCMath correctement formée.
- `scale` est en dehors de la plage valide.

Cette fonction lève une exception DivisionByZeroError si `num2` est égal à `0`.

### Historique

Version | Description
--- | ---
8.0.0 | `scale` est désormais nullable.
8.0.0 | La division par `0` lève désormais une exception DivisionByZeroError au lieu de retourner null.
7.2.0 | `num1` et `num2` ne sont plus tronqués en entier. Le comportement de bcmod() suit fmod() plutôt que l'opérateur `%`.
7.2.0 | Le paramètre `scale` a été ajouté.

### Exemples

Exemple #1 Exemple avec bcmod()

    <?php
    bcscale(0);
    echo bcmod( '5',  '3'); //  2
    echo bcmod( '5', '-3'); //  2
    echo bcmod('-5',  '3'); // -2
    echo bcmod('-5', '-3'); // -2
    ?>

Exemple #2 bcmod() avec des décimales

    <?php
    bcscale(1);
    echo bcmod('5.7', '1.3'); // 0.5 à partir de PHP 7.2.0; 0 précédemment
    ?>

### Voir aussi

- bcdiv() - Divise deux nombres de grande taille
- bcdivmod() - Renvoie le quotient et le reste d'un nombre de précision arbitraire
- BcMath\Number::mod() - Renvoie le modulo d'un nombre de précision arbitraire

# bcmul

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmul — Multiplie deux nombres de grande taille

### Description

function bcmul(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Multiplie `num1` par `num2`.

### Liste de paramètres

`num1`

  L'opérande gauche, sous la forme d'une chaîne de caractères.

`num2`

  L'opérande droit, sous la forme d'une chaîne de caractères.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Retourne le résultat, sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Cette fonction lève une exception ValueError dans les cas suivants :

- `num1` ou `num2` n'est pas une chaîne numérique BCMath correctement formée.
- `scale` est en dehors de la plage valide.

### Historique

Version | Description
--- | ---
8.0.0 | `scale` est désormais nullable.
7.3.0 | bcmul() retourne désormais les nombres avec la précision demandée. Auparavant, les nombres retournés pouvaient omettre les zéros décimaux de fin.

### Exemples

Exemple #1 Exemple avec bcmul()

    <?php
    echo bcmul('1.34747474747', '35', 3); // 47.161
    echo bcmul('2', '4'); // 8
    ?>

### Notes

> Note:

> Antérieurement à PHP 7.3.0, bcmul() peut retourner un résultat avec moins de chiffres après la virgule que le paramètre `scale` indique. Ceci ne se produit que lorsque le résultat ne nécessite pas toute la précision autorisée par `scale`. Par exemple:

> Exemple #2 bcmul() exemple pour scale

>     <?php
>     echo bcmul('5', '2', 2);     // affiche "10", pas "10.00"
>     ?>

### Voir aussi

- bcdiv() - Divise deux nombres de grande taille
- BcMath\Number::mul() - Multiplie un nombre de précision arbitraire

# bcpow

(PHP 4, PHP 5, PHP 7, PHP 8)

bcpow — Élève un nombre à une puissance donnée

### Description

function bcpow(string `$num`, string `$exponent`, ?int `$scale` = `null`): string

Élève `num` à la puissance `exponent`.

### Liste de paramètres

`num`

  La base, sous la forme d'une chaîne de caractères.

`exponent`

  L'exposant, sous la forme d'une chaîne de caractères. Doit être une valeur sans partie fractionnaire. L'intervalle valide de l'exposant dépend de la plateforme, mais c'est au minimum de `-2147483648` à `2147483647`.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Retourne le résultat, sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Cette fonction lève une exception de type ValueError dans les cas suivants :

- `num` ou `exponent` n'est pas une chaîne numérique BCMath bien formée
- `exponent` contient une partie fractionnaire
- `exponent` ou `scale` est en dehors de la plage valide

Cette fonction lève une exception de type DivisionByZeroError si `num` est `0` et que `exponent` est une valeur négative.

### Historique

Version | Description
--- | ---
8.4.0 | Les puissances négatives de `0` renvoyaient auparavant `0`, mais lèvent désormais une exception DivisionByZeroError.
8.0.0 | Lorsque `exponent` contient une partie fractionnaire, une exception de type ValueError est désormais levée au lieu d'effectuer une troncature.
7.3.0 | bcpow() retourne désormais les nombres avec la précision demandée. Auparavant, les nombres retournés pouvaient omettre les zéros décimaux de fin.

### Exemples

Exemple #1 Exemple avec bcpow()

    <?php

    echo bcpow('4.2', '3', 2); // 74.08

    ?>

### Notes

> Note:

> Antérieurement à PHP 7.3.0, bcpow() peut retourner un résultat avec moins de chiffres après la virgule que le paramètre `scale` indique. Ceci ne se produit que lorsque le résultat ne nécessite pas toute la précision autorisée par `scale`. Par exemple:

> Exemple #2 bcpow() exemple pour scale

>     <?php
>     echo bcpow('5', '2', 2);     // affiche "25", pas "25.00"
>     ?>

### Voir aussi

- bcpowmod() - Calcule le reste modulo d'un nombre élevé à une puissance
- bcsqrt() - Récupère la racine carrée d'un nombre de grande taille
- BcMath\Number::pow() - Élève un nombre de précision arbitraire

# bcpowmod

(PHP 5, PHP 7, PHP 8)

bcpowmod — Calcule le reste modulo d'un nombre élevé à une puissance

### Description

function bcpowmod(
string `$num`,
string `$exponent`,
string `$modulus`,
?int `$scale` = `null`
): string

Utilise la méthode d'exponentiation rapide pour élever le nombre `num` à la puissance `exponent`, et en calculant le reste modulo `modulus`.

### Liste de paramètres

`num`

  La base, sous la forme d'une chaîne de caractères (c'est-à-dire que l'échelle doit être nulle).

`exponent`

  L'exposant, sous la forme d'une chaîne de caractères non négative (c'est-à-dire que l'échelle doit être nulle).

`modulus`

  Le modulo, sous la forme d'une chaîne de caractères (c'est-à-dire que l'échelle doit être nulle).

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Retourne le résultat, sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Cette fonction lève une exception ValueError dans les cas suivants :

- `num`, `exponent` ou `modulus` n'est pas une chaîne numérique BCMath correctement formée
- `num`, `exponent` ou `modulus` possède une partie fractionnaire
- `exponent` est une valeur négative
- `scale` est en dehors de la plage valide

Cette fonction lève une exception DivisionByZeroError si `modulus` est égal à `0`.

### Historique

Version | Description
--- | ---
8.0.0 | `scale` est désormais nullable.
8.0.0 | Lève désormais une exception ValueError au lieu de retourner `false` si `exponent` est une valeur négative.
8.0.0 | La division par `0` lève désormais une exception DivisionByZeroError au lieu de retourner `false`.

### Exemples

Les deux lignes suivantes produisent le même résultat. La version qui utilise bcpowmod() est bien plus rapide, et accepte des paramètres plus grands.

    <?php
    $a = bcpowmod($x, $y, $mod);

    $b = bcmod(bcpow($x, $y), $mod);

    // $a et $b sont égaux.

    ?>

### Notes

> Note:

> Comme cette méthode utilise les opérations de modulo, les nombres qui ne sont pas des entiers positifs risquent de donner des résultats inattendus.

### Voir aussi

- bcpow() - Élève un nombre à une puissance donnée
- bcmod() - Retourne le reste d'une division entre nombres de grande taille
- BcMath\Number::powmod() - Élève un nombre de précision arbitraire, réduit par un modulo spécifié

# bcround

(PHP 8 >= 8.4.0)

bcround — Arrondit un nombre de précision arbitraire

### Description

function bcround(string `$num`, int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): string

Renvoie la valeur arrondie de `num` à la précision spécifiée `precision` (nombre de chiffres après la virgule). `precision` peut également être négatif ou nul (par défaut).

### Liste de paramètres

`num`

  La valeur à arrondir.

`precision`

  Le nombre optionnel de décimales à arrondir.

  Si le paramètre `precision` est positif, `num` sera arrondi en utilisant le paramètre `precision` pour définir le nombre significatif de chiffres après le point décimal.

  Si le paramètre `precision` est négatif, `num` sera arrondi en utilisant le paramètre `precision` pour définir le nombre significatif de chiffres avant le point décimal, c.-à-d. le multiple le plus proche de `pow(10, -$precision)`, c.-à-d. pour une `precision` de -1, `num` sera arrondi à 10, pour une `precision` de -2 à 100, etc.

`mode`
  Spécifie la méthode d'arrondi. Pour plus d'informations sur les méthodes, voir RoundingMode.

### Valeurs de retour

Renvoie une chaîne numérique représentant `num` arrondi à la précision donnée.

### Erreurs / Exceptions

Cette fonction lance une ValueError dans les cas suivants :

- `num` n'est pas une chaîne numérique BCMath bien formée.
- Un `mode` invalide est spécifié.

### Exemples

Exemple #1 Exemples de bcround()

    <?php
    var_dump(bcround('3.4'));
    var_dump(bcround('3.5'));
    var_dump(bcround('3.6'));
    var_dump(bcround('3.6', 0));
    var_dump(bcround('5.045', 2));
    var_dump(bcround('5.055', 2));
    var_dump(bcround('345', -2));
    var_dump(bcround('345', -3));
    var_dump(bcround('678', -2));
    var_dump(bcround('678', -3));
    ?>

L'exemple ci-dessus va afficher :

    string(1) "3"
    string(1) "4"
    string(1) "4"
    string(1) "4"
    string(4) "5.05"
    string(4) "5.06"
    string(3) "300"
    string(1) "0"
    string(3) "700"
    string(4) "1000"

Exemple #2 Exemple de l'utilisation de bcround() avec différentes valeurs de `precision`

    <?php
    $number = '123.45';

    var_dump(bcround($number, 3));
    var_dump(bcround($number, 2));
    var_dump(bcround($number, 1));
    var_dump(bcround($number, 0));
    var_dump(bcround($number, -1));
    var_dump(bcround($number, -2));
    var_dump(bcround($number, -3));
    ?>

L'exemple ci-dessus va afficher :

    string(7) "123.450"
    string(6) "123.45"
    string(5) "123.5"
    string(3) "123"
    string(3) "120"
    string(3) "100"
    string(1) "0"

Exemple #3 Exemple de l'utilisation de bcround() avec différentes valeurs de `mode`

    <?php
    echo "Modes d'arrondi avec 9.5" . PHP_EOL;
    var_dump(bcround('9.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('9.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('9.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('9.5', 0, RoundingMode::PositiveInfinity));

    echo PHP_EOL;
    echo "Modes d'arrondi avec 8.5" . PHP_EOL;
    var_dump(bcround('8.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('8.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('8.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('8.5', 0, RoundingMode::PositiveInfinity));
    ?>

L'exemple ci-dessus va afficher :

    Modes d'arrondi avec 9.5
    string(2) "10"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(2) "10"

    Modes d'arrondi avec 8.5
    string(1) "9"
    string(1) "8"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"

Exemple #4 Exemple de l'utilisation de bcround() avec différentes valeurs de `mode` lors de la spécification de `precision`

    <?php
    echo 'Utilisation de RoundingMode::HalfAwayFromZero avec une précision décimale de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfAwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfAwayFromZero));

    echo PHP_EOL;
    echo 'Utilisation de RoundingMode::HalfTowardsZero avec une précision décimale de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfTowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfTowardsZero));

    echo PHP_EOL;
    echo 'Utilisation de RoundingMode::HalfEven avec une précision décimale de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfEven));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfEven));

    echo PHP_EOL;
    echo 'Utilisation de RoundingMode::HalfOdd avec une précision décimale de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfOdd));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfOdd));

    echo PHP_EOL;
    echo 'Utilisation de RoundingMode::TowardsZero avec une précision décimale de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::TowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::TowardsZero));

    echo PHP_EOL;
    echo 'Utilisation de RoundingMode::AwayFromZero avec une précision décimale de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::AwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::AwayFromZero));

    echo PHP_EOL;
    echo 'Utilisation de RoundingMode::NegativeInfinity avec une précision décimale de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::NegativeInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::NegativeInfinity));

    echo PHP_EOL;
    echo 'Utilisation de RoundingMode::PositiveInfinity avec une précision décimale de 1' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::PositiveInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::PositiveInfinity));
    ?>

L'exemple ci-dessus va afficher :

    Utilisation de RoundingMode::HalfAwayFromZero avec une précision décimale de 1
    string(3) "1.6"
    string(4) "-1.6"

    Utilisation de RoundingMode::HalfTowardsZero avec une précision décimale de 1
    string(3) "1.5"
    string(4) "-1.5"

    Utilisation de RoundingMode::HalfEven avec une précision décimale de 1
    string(3) "1.6"
    string(4) "-1.6"

    Utilisation de RoundingMode::HalfOdd avec une précision décimale de 1
    string(3) "1.5"
    string(4) "-1.5"

    Utilisation de RoundingMode::TowardsZero avec une précision décimale de 1
    string(3) "1.5"
    string(4) "-1.5"

    Utilisation de RoundingMode::AwayFromZero avec une précision décimale de 1
    string(3) "1.6"
    string(4) "-1.6"

    Utilisation de RoundingMode::NegativeInfinity avec une précision décimale de 1
    string(3) "1.5"
    string(4) "-1.6"

    Utilisation de RoundingMode::PositiveInfinity avec une précision décimale de 1
    string(3) "1.6"
    string(4) "-1.5"

### Voir aussi

- bcceil() - Arrondit au supérieur un nombre de précision arbitraire
- bcfloor() - Arrondit à l'inférieur un nombre de précision arbitraire
- BcMath\Number::round() - Arrondit un nombre de précision arbitraire

# bcscale

(PHP 4, PHP 5, PHP 7, PHP 8)

bcscale — Définit ou récupère la précision par défaut pour toutes les fonctions bc math

### Description

function bcscale(int `$scale`): int

Définit la précision par défaut pour tous les appels ultérieurs aux fonctions bc math qui omettent le paramètre de précision.

function bcscale(null `$scale` = `null`): int

Récupère le facteur de précision actuel.

### Liste de paramètres

`scale`

  Le facteur de précision.

### Valeurs de retour

Retourne l'ancienne précision lorsque la fonction est utilisée pour définir une valeur. Sinon la précision actuelle est retournée.

### Erreurs / Exceptions

Cette fonction lève une exception ValueError si `scale` est en dehors de la plage valide.

### Historique

Version | Description
--- | ---
8.0.0 | `scale` est désormais nullable.
7.3.0 | bcscale() peut désormais être utilisée pour récupérer la précision actuelle ; quand elle est utilisée pour définir une nouvelle précision, elle retourne désormais l'ancienne précision. Auparavant, `scale` était obligatoire, et bcscale() retournait toujours `true`.

### Exemples

Exemple #1 Exemple avec bcscale()

    <?php

    // précision par défaut : 3
    bcscale(3);
    echo bcdiv('105', '6.55957'); // 16.007

    // la même chose sans utiliser bcscale()
    echo bcdiv('105', '6.55957', 3); // 16.007

    ?>

# bcsqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsqrt — Récupère la racine carrée d'un nombre de grande taille

### Description

function bcsqrt(string `$num`, ?int `$scale` = `null`): string

Retourne la racine carrée de `num`.

### Liste de paramètres

`num`

  L'opérande, sous la forme d'une chaîne de caractères BCMath numérique bien formée.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Retourne la racine carrée sous la forme d'une chaîne numérique BCMath bien formée.

### Erreurs / Exceptions

Cette fonction lève une ValueError dans les cas suivants :

- `num` n'est pas une chaîne numérique BCMath bien formée
- `num` est inférieur à `0`
- `scale` est en dehors de la plage valide

### Historique

Version | Description
--- | ---
8.0.0 | Si `num` n'est pas une chaîne numérique BCMath bien formée, ou est inférieur à `0`, une ValueError est levée. Précédemment, `E_WARNING` était émis à la place.
8.0.0 | `scale` doit désormais être compris entre `0` et `2147483647`. Précédemment, les échelles négatives étaient traitées silencieusement comme `0`.
8.0.0 | `scale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec bcsqrt()

    <?php

    echo bcsqrt('2', 3); // 1.414

    ?>

### Voir aussi

- bcpow() - Élève un nombre à une puissance donnée
- BcMath\Number::sqrt() - Renvoie la racine carrée d'un nombre de précision arbitraire

# bcsub

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsub — Soustrait un nombre de grande taille d'un autre

### Description

function bcsub(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Soustrait `num2` de `num1`.

### Liste de paramètres

`num1`

  L'opérande gauche, sous la forme d'une chaîne de caractères.

`num2`

  L'opérande droit, sous la forme d'une chaîne de caractères.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Le résultat de la soustraction, sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Cette fonction lève une exception ValueError dans les cas suivants :

- `num1` ou `num2` n'est pas une chaîne numérique BCMath correctement formée.
- `scale` est en dehors de la plage valide.

### Historique

Version | Description
--- | ---
8.0.0 | `scale` est désormais nullable.

### Exemples

Exemple #1 Exemple avec bcsub()

    <?php

    $a = '1.234';
    $b = '5';

    echo bcsub($a, $b);     // -3
    echo bcsub($a, $b, 4);  // -3.7660

    ?>

### Voir aussi

- bcadd() - Additionne deux nombres de grande taille
- BcMath\Number::sub() - Soustrait un nombre de précision arbitraire

## Sommaire

- bcadd — Additionne deux nombres de grande taille
- bcceil — Arrondit au supérieur un nombre de précision arbitraire
- bccomp — Compare deux nombres de grande taille
- bcdiv — Divise deux nombres de grande taille
- bcdivmod — Renvoie le quotient et le reste d'un nombre de précision arbitraire
- bcfloor — Arrondit à l'inférieur un nombre de précision arbitraire
- bcmod — Retourne le reste d'une division entre nombres de grande taille
- bcmul — Multiplie deux nombres de grande taille
- bcpow — Élève un nombre à une puissance donnée
- bcpowmod — Calcule le reste modulo d'un nombre élevé à une puissance
- bcround — Arrondit un nombre de précision arbitraire
- bcscale — Définit ou récupère la précision par défaut pour toutes les fonctions bc math
- bcsqrt — Récupère la racine carrée d'un nombre de grande taille
- bcsub — Soustrait un nombre de grande taille d'un autre

# La classe BcMath\Number

(PHP 8 >= 8.4.0)

## Introduction

Une classe pour un nombre de précision arbitraire. Ces objets supportent les opérateurs arithmétiques et de comparaison.

> Note: Cette classe n'est pas affectée par la directive INI bcmath.scale définie dans le php.ini.

> Note: Le comportement d'un opérateur surchargé est le même que de spécifier `null` pour le paramètre `scale` sur la méthode correspondante.

## Synopsis de la classe

namespace BcMath;
final readonly class Number implements Stringable {
/* Propriétés */
public string $value;
public int $scale;
/* Méthodes */
public function __construct(string|int `$num`)
public function add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function ceil(): BcMath\Number
public function compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int
public function div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array
public function floor(): BcMath\Number
public function mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number
public function powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number
public function round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number
public function __serialize(): array
public function sqrt(?int `$scale` = `null`): BcMath\Number
public function sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function __toString(): string
public function __unserialize(array `$data`): void
}

## Propriétés

value
  Une représentation en chaîne d'un nombre de précision arbitraire.
scale
  La valeur de l'échelle actuellement définie sur l'objet. Pour les objets résultant de calculs, cette valeur est automatiquement calculée et définie, sauf si le paramètre `scale` a été défini dans la méthode de calcul.

# BcMath\Number::add

(PHP 8 >= 8.4.0)

BcMath\Number::add — Ajouter un nombre de précision arbitraire

### Description

public function BcMath\Number::add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Ajoute $this et `num`.

### Liste de paramètres

`num`
  La valeur à ajouter.
`scale`
  BcMath\Number::scale spécifié explicitement pour les résultats du calcul. Si `null`, le BcMath\Number::scale du résultat du calcul sera défini automatiquement.

### Valeurs de retour

Renvoie le résultat de l'addition sous la forme d'un nouvel objet BcMath\Number.

Lorsque le BcMath\Number::scale du résultat est défini automatiquement, le plus grand BcMath\Number::scale des deux nombres utilisés pour l'addition est utilisé.

C'est-à-dire que si les BcMath\Number::scale de deux valeurs sont `2` et `5` respectivement, le BcMath\Number::scale du résultat sera `5`.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants :

- `num` est un string et n'est pas une chaîne numérique BCMath bien formée
- `scale` est en dehors de la plage valide

### Exemples

Exemple #1 Exemple de BcMath\Number::add() lorsque `scale` n'est pas spécifié

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'));
    $ret2 = $number->add('-3.456');
    $ret3 = $number->add(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(7) "3.57967"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(6) "-2.222"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.234"
      ["scale"]=>
      int(3)
    }

Exemple #2 Exemple de BcMath\Number::add() en spécifiant `scale` explicitement

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->add('-3.456', 10);
    $ret3 = $number->add(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "3.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-2.2220000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### Voir aussi

- bcadd() - Additionne deux nombres de grande taille
- BcMath\Number::sub() - Soustrait un nombre de précision arbitraire

# BcMath\Number::ceil

(PHP 8 >= 8.4.0)

BcMath\Number::ceil — Arrondit au supérieur un nombre de précision arbitraire

### Description

public function BcMath\Number::ceil(): BcMath\Number

Renvoie la valeur entière supérieure suivante en arrondissant au supérieur $this si nécessaire.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le résultat sous forme d'un nouvel objet BcMath\Number. La BcMath\Number::scale du résultat est toujours `0`.

### Exemples

Exemple #1 Exemple de BcMath\Number::ceil()

    <?php
    $num1 = new BcMath\Number('4.3')->ceil();
    $num2 = new BcMath\Number('9.999')->ceil();
    $num3 = new BcMath\Number('-3.14')->ceil();

    var_dump($num1, $num2, $num3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "5"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }

### Voir aussi

- bcceil() - Arrondit au supérieur un nombre de précision arbitraire
- BcMath\Number::floor() - Arrondit à l'inférieur un nombre de précision arbitraire
- BcMath\Number::round() - Arrondit un nombre de précision arbitraire

# BcMath\Number::compare

(PHP 8 >= 8.4.0)

BcMath\Number::compare — Compare deux nombres de précision arbitraire

### Description

public function BcMath\Number::compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int

Compare deux nombres de précision arbitraire. Cette méthode se comporte de manière similaire à l'opérateur spaceship.

### Liste de paramètres

`num`
  La valeur à laquelle comparer.
`scale`
  Spécifie le `scale` à utiliser pour la comparaison. Si `null`, tous les chiffres sont utilisés dans la comparaison.

### Valeurs de retour

Renvoie `0` si les deux nombres sont égaux, `1` si $this est plus grand que `num`, sinon `-1`.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants :

- `num` est un string et n'est pas une chaîne numérique BCMath bien formée
- `scale` est en dehors de la plage valide

### Exemples

Exemple #1 Exemple de BcMath\Number::compare() lorsque `scale` n'est pas spécifié

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.234')),
        $number->compare('1.23400'),
        $number->compare('1.23401'),
        $number->compare(1),
    );
    ?>

L'exemple ci-dessus va afficher :

    int(0)
    int(0)
    int(-1)
    int(1)

Exemple #2 Exemple de BcMath\Number::compare() en spécifiant `scale` explicitement

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.299'), 1),
        $number->compare('1.24', 2),
        $number->compare('1.22', 2),
        $number->compare(1, 0),
    );
    ?>

L'exemple ci-dessus va afficher :

    int(0)
    int(-1)
    int(1)
    int(0)

### Voir aussi

- bccomp() - Compare deux nombres de grande taille

# BcMath\Number::__construct

(PHP 8 >= 8.4.0)

BcMath\Number::__construct — Crée un objet BcMath\Number

### Description

public function BcMath\Number::__construct(string|int `$num`)

Crée un objet BcMath\Number à partir d'une valeur int ou string.

### Liste de paramètres

`num`
  Une valeur int ou string. Si `num` est un int, la BcMath\Number::scale est toujours définie à `0`. Si `num` est un string, il doit être un nombre valide, et la BcMath\Number::scale est automatiquement définie en analysant la chaîne.

### Erreurs / Exceptions

Cette méthode lève une ValueError si `num` est de type string et n'est pas une chaîne numérique BCMath bien formée.

### Exemples

Exemple #1 Exemple de BcMath\Number::__construct()

    <?php
    $num1 = new BcMath\Number(100);
    $num2 = new BcMath\Number('-200');
    $num3 = new BcMath\Number('300.00');

    var_dump($num1, $num2, $num3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "-200"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "300.00"
      ["scale"]=>
      int(2)
    }

### Voir aussi

- BcMath\Number::__serialize() - Sérialise un objet BcMath\Number
- BcMath\Number::__unserialize() - Désérialise un paramètre de données en un objet BcMath\Number

# BcMath\Number::div

(PHP 8 >= 8.4.0)

BcMath\Number::div — Divise par un nombre de précision arbitraire

### Description

public function BcMath\Number::div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Divise $this par `num`.

### Liste de paramètres

`num`
  Le diviseur.
`scale`
  BcMath\Number::scale spécifié explicitement pour les résultats du calcul. Si `null`, le BcMath\Number::scale du résultat du calcul sera défini automatiquement.

### Valeurs de retour

Renvoie le résultat d'une division sous forme d'un nouvel objet BcMath\Number.

Lorsque le BcMath\Number::scale du résultat est défini automatiquement, le BcMath\Number::scale du dividende est utilisé. Cependant, dans des cas tels que la division indivisible, le BcMath\Number::scale du résultat est étendu. L'extension est effectuée uniquement si nécessaire, jusqu'à un maximum de `+10`.

C'est-à-dire que si le BcMath\Number::scale du dividende est `5`, le BcMath\Number::scale du résultat est entre `5` et `15`.

Même dans des calculs indivisibles, le BcMath\Number::scale ne sera pas toujours `+10`. Un `0` à la fin du résultat est considéré comme ne nécessitant pas d'extension, donc le BcMath\Number::scale est réduit de cette quantité. Le BcMath\Number::scale ne sera jamais inférieur au BcMath\Number::scale avant l'extension. Voir également l'exemple de code.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants :

- `num` est un string et n'est pas une chaîne numérique BCMath bien formée
- `scale` est hors de la plage valide
- BcMath\Number::scale du résultat est hors de la plage valide

Cette méthode lève une DivisionByZeroError si `num` est `0`.

### Exemples

Exemple #1 Exemple de BcMath\Number::div() lorsque `scale` n'est pas spécifié

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'));
    $ret2 = $number->div('-3');
    $ret3 = $number->div(32);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "0.001"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(16) "-0.0006666666666"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(9) "0.0000625"
      ["scale"]=>
      int(7)
    }

Exemple #2 Exemple de BcMath\Number::div() en spécifiant `scale` explicitement

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'), 15);
    $ret2 = $number->div('-3', 5);
    $ret3 = $number->div(32, 2);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(17) "0.001000000000000"
      ["scale"]=>
      int(15)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(8) "-0.00066"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "0.00"
      ["scale"]=>
      int(2)
    }

Exemple #3 Exemple de BcMath\Number::div() lors de l'extension de BcMath\Number::scale de l'objet résultat

    <?php
    var_dump(
        new BcMath\Number('0.001')->div('10001'),
        new BcMath\Number('0.001')->div('10001', 13),
        new BcMath\Number('0.001')->div('100000000000001'),
    );
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.00000009999"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(15) "0.0000000999900"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }

### Voir aussi

- bcdiv() - Divise deux nombres de grande taille
- BcMath\Number::divmod() - Renvoie le quotient et le modulo d'un nombre de précision arbitraire
- BcMath\Number::mod() - Renvoie le modulo d'un nombre de précision arbitraire
- BcMath\Number::sqrt() - Renvoie la racine carrée d'un nombre de précision arbitraire
- BcMath\Number::pow() - Élève un nombre de précision arbitraire
- BcMath\Number::mul() - Multiplie un nombre de précision arbitraire

# BcMath\Number::divmod

(PHP 8 >= 8.4.0)

BcMath\Number::divmod — Renvoie le quotient et le modulo d'un nombre de précision arbitraire

### Description

public function BcMath\Number::divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array

Renvoie le quotient et le modulo de la division de $this par `num`.

### Liste de paramètres

`num`
  Le diviseur.
`scale`
  BcMath\Number::scale spécifié explicitement pour les résultats du calcul. Si `null`, le BcMath\Number::scale du résultat du calcul sera défini automatiquement.

### Valeurs de retour

Renvoie un array indexé où le premier élément est le quotient sous forme d'un nouvel objet BcMath\Number et le second élément est le modulo sous forme d'un nouvel objet BcMath\Number.

Le quotient est toujours une valeur entière, donc BcMath\Number::scale du quotient sera toujours `0`, que `scale` soit explicitement spécifié ou non.

Si `scale` est explicitement spécifié, BcMath\Number::scale du modulo sera la valeur spécifiée. Lorsque le BcMath\Number::scale de l'objet de modulo du résultat est défini automatiquement, le plus grand BcMath\Number::scale des deux nombres utilisés pour l'opération de modulo est utilisé.

C'est-à-dire que si les BcMath\Number::scales de deux valeurs sont `2` et `5` respectivement, le BcMath\Number::scale du modulo sera `5`.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants :

- `num` est un string et n'est pas une chaîne numérique BCMath bien formée
- `scale` est en dehors de la plage valide

Cette méthode lève une DivisionByZeroError si `num` est `0`.

### Exemples

Exemple #1 Exemple de BcMath\Number::divmod() lorsque `scale` n'est pas spécifié

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'));
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3');
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3);
    var_dump($quot, $rem);
    ?>

L'exemple ci-dessus va afficher :

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "1.34"
      ["scale"]=>
      int(2)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

Exemple #2 Exemple de BcMath\Number::divmod() en spécifiant `scale` explicitement

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'), 1);
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3', 4);
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3, 5);
    var_dump($quot, $rem);
    ?>

L'exemple ci-dessus va afficher :

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.3"
      ["scale"]=>
      int(1)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(6) "0.0000"
      ["scale"]=>
      int(4)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(7) "1.00000"
      ["scale"]=>
      int(5)
    }

### Voir aussi

- bcdivmod() - Renvoie le quotient et le reste d'un nombre de précision arbitraire
- BcMath\Number::div() - Divise par un nombre de précision arbitraire
- BcMath\Number::mod() - Renvoie le modulo d'un nombre de précision arbitraire

# BcMath\Number::floor

(PHP 8 >= 8.4.0)

BcMath\Number::floor — Arrondit à l'inférieur un nombre de précision arbitraire

### Description

public function BcMath\Number::floor(): BcMath\Number

Renvoie la valeur entière inférieure suivante en arrondissant à l'inférieur $this si nécessaire.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie le résultat sous forme d'un nouvel objet BcMath\Number. La BcMath\Number::scale du résultat est toujours `0`.

### Exemples

Exemple #1 Exemple de BcMath\Number::floor()

    <?php
    $num1 = new BcMath\Number('4.3')->floor();
    $num2 = new BcMath\Number('9.999')->floor();
    $num3 = new BcMath\Number('-3.14')->floor();

    var_dump($num1, $num2, $num3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-4"
      ["scale"]=>
      int(0)
    }

### Voir aussi

- bcfloor() - Arrondit à l'inférieur un nombre de précision arbitraire
- BcMath\Number::ceil() - Arrondit au supérieur un nombre de précision arbitraire
- BcMath\Number::round() - Arrondit un nombre de précision arbitraire

# BcMath\Number::mod

(PHP 8 >= 8.4.0)

BcMath\Number::mod — Renvoie le modulo d'un nombre de précision arbitraire

### Description

public function BcMath\Number::mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Renvoie le reste de la division de $this par `num`. Sauf si `num` est `0`, le résultat a le même signe que $this.

### Liste de paramètres

`num`
  Le diviseur.
`scale`
  BcMath\Number::scale spécifié explicitement pour les résultats du calcul. Si `null`, le BcMath\Number::scale du résultat du calcul sera défini automatiquement.

### Valeurs de retour

Renvoie le modulo sous forme d'un nouvel objet BcMath\Number.

Lorsque le BcMath\Number::scale du résultat est défini automatiquement, le plus grand BcMath\Number::scale des deux nombres utilisés pour l'opération de modulo est utilisé.

C'est-à-dire que si les BcMath\Number::scale de deux valeurs sont `2` et `5` respectivement, le BcMath\Number::scale du résultat sera `5`.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants :

- `num` est un string et n'est pas une chaîne numérique BCMath bien formée
- `scale` est en dehors de la plage valide

Cette méthode lève une DivisionByZeroError si `num` est `0`.

### Exemples

Exemple #1 Exemple de BcMath\Number::mod() lorsque `scale` n'est pas spécifié

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'));
    $ret2 = $number->mod('8.3');
    $ret3 = $number->mod(-5);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "1.64"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "3.3"
      ["scale"]=>
      int(1)
    }

Exemple #2 Exemple de BcMath\Number::mod() en définissant `scale` explicitement

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'), 1);
    $ret2 = $number->mod('8.3', 3);
    $ret3 = $number->mod(-5, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }

### Voir aussi

- bcmod() - Retourne le reste d'une division entre nombres de grande taille
- BcMath\Number::div() - Divise par un nombre de précision arbitraire
- BcMath\Number::divmod() - Renvoie le quotient et le modulo d'un nombre de précision arbitraire
- BcMath\Number::powmod() - Élève un nombre de précision arbitraire, réduit par un modulo spécifié

# BcMath\Number::mul

(PHP 8 >= 8.4.0)

BcMath\Number::mul — Multiplie un nombre de précision arbitraire

### Description

public function BcMath\Number::mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Multiplie $this par `num`.

### Liste de paramètres

`num`
  Le multiplicateur.
`scale`
  BcMath\Number::scale spécifié explicitement pour les résultats du calcul. Si `null`, le BcMath\Number::scale du résultat du calcul sera défini automatiquement.

### Valeurs de retour

Renvoie le résultat de la multiplication sous forme d'un nouvel objet BcMath\Number.

Lorsque le BcMath\Number::scale du résultat est défini automatiquement, la somme des BcMath\Number::scales des deux valeurs utilisées pour la multiplication est utilisée.

C'est-à-dire que si les BcMath\Number::scales de deux valeurs sont `2` et `5` respectivement, le BcMath\Number::scale du résultat sera `7`.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants :

- `num` est un string et n'est pas une chaîne numérique BCMath bien formée
- `scale` est hors de la plage valide
- BcMath\Number::scale du résultat est hors de la plage valide

### Exemples

Exemple #1 Exemple de BcMath\Number::mul() lorsque `scale` n'est pas spécifié

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'));
    $ret2 = $number->mul('-3.4');
    $ret3 = $number->mul(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "2.8944704"
      ["scale"]=>
      int(7)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "-4.1956"
      ["scale"]=>
      int(4)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.638"
      ["scale"]=>
      int(3)
    }

Exemple #2 Exemple de BcMath\Number::mul() en spécifiant `scale` explicitement

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'), 1);
    $ret2 = $number->mul('-3.4', 10);
    $ret3 = $number->mul(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.8"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-4.1956000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### Voir aussi

- bcmul() - Multiplie deux nombres de grande taille
- BcMath\Number::div() - Divise par un nombre de précision arbitraire
- BcMath\Number::pow() - Élève un nombre de précision arbitraire
- BcMath\Number::powmod() - Élève un nombre de précision arbitraire, réduit par un modulo spécifié

# BcMath\Number::pow

(PHP 8 >= 8.4.0)

BcMath\Number::pow — Élève un nombre de précision arbitraire

### Description

public function BcMath\Number::pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number

Élève $this à la puissance `exponent`.

### Liste de paramètres

`exponent`
  L'exposant. Doit être une valeur sans partie fractionnaire. La plage valide de l'`exponent` est spécifique à la plateforme, mais il s'agit au moins de `-2147483648` à `2147483647`.
`scale`
  BcMath\Number::scale spécifié explicitement pour les résultats du calcul. Si `null`, le BcMath\Number::scale du résultat du calcul sera défini automatiquement.

### Valeurs de retour

Renvoie la valeur de la puissance sous forme d'un nouvel objet BcMath\Number.

Lorsque le BcMath\Number::scale du résultat est défini automatiquement, selon la valeur de `exponent`, le BcMath\Number::scale du résultat sera comme suit :

`exponent` | BcMath\Number::scale du résultat
--- | ---
positif | (BcMath\Number::scale de la puissance de base) * (la valeur de l'`exponent`)
`0` | `0`
négatif | Entre (BcMath\Number::scale de la puissance de base) et (BcMath\Number::scale de la puissance de base + `10`)

Si une division indivisible se produit en raison d'un `exponent` négatif, le BcMath\Number::scale du résultat est étendu. L'extension est effectuée uniquement si nécessaire, jusqu'à un maximum de `+10`. Ce comportement est le même que BcMath\Number::div(), consulter cette méthode pour plus de détails.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants :

- `exponent` est un string et n'est pas une chaîne numérique BCMath bien formée
- `exponent` a une partie fractionnelle
- `exponent` ou `scale` est en dehors de la plage valide
- Le BcMath\Number::scale du résultat est en dehors de la plage valide

Cette méthode lève une DivisionByZeroError si la valeur de $this est `0` et `exponent` est une valeur négative.

### Exemples

Exemple #1 Exemple de BcMath\Number::pow() lorsque `scale` n'est pas spécifié

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'));
    $ret2 = $number->pow('-1');
    $ret3 = $number->pow(0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "243.00000"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.33333333333"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

Exemple #2 Exemple de BcMath\Number::pow() en spécifiant `scale` explicitement

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'), 0);
    $ret2 = $number->pow('-1', 2);
    $ret3 = $number->pow(0, 10);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "243"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "0.33"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(12) "1.0000000000"
      ["scale"]=>
      int(10)
    }

### Voir aussi

- bcpow() - Élève un nombre à une puissance donnée
- BcMath\Number::powmod() - Élève un nombre de précision arbitraire, réduit par un modulo spécifié
- BcMath\Number::mul() - Multiplie un nombre de précision arbitraire
- BcMath\Number::sqrt() - Renvoie la racine carrée d'un nombre de précision arbitraire
- BcMath\Number::div() - Divise par un nombre de précision arbitraire

# BcMath\Number::powmod

(PHP 8 >= 8.4.0)

BcMath\Number::powmod — Élève un nombre de précision arbitraire, réduit par un modulo spécifié

### Description

public function BcMath\Number::powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number

Utilise la méthode rapide d'exponentiation pour élever $this à la puissance `exponent` par rapport au modulo `modulus`.

### Liste de paramètres

`exponent`
  L'exposant, en tant que valeur non négative et entière (c'est-à-dire que l'échelle doit être nulle).
`modulus`
  Le modulo, en tant que valeur entière (c'est-à-dire que l'échelle doit être nulle).
`scale`
  BcMath\Number::scale spécifié explicitement pour les résultats du calcul. Si `null`, le BcMath\Number::scale du résultat du calcul sera défini automatiquement.

### Valeurs de retour

Renvoie le résultat sous forme d'un nouvel objet BcMath\Number.

Lorsque le BcMath\Number::scale du résultat est défini automatiquement, le BcMath\Number::scale de l'objet résultat sera toujours `0`.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants :

- `exponent` ou `modulus` est un string et n'est pas une chaîne numérique BCMath bien formée
- $this, `exponent` ou `modulus` a une partie fractionnelle
- `exponent` est une valeur négative
- `scale` est en dehors de la plage valide

Cette méthode lève une exception DivisionByZeroError si `modulus` est `0`.

### Exemples

Exemple #1 Exemple de BcMath\Number::powmod() lorsque `scale` n'est pas spécifié

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('8')->powmod('2', -3),
        new BcMath\Number('-8')->powmod(5, 7),
    );
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(2) "-1"
      ["scale"]=>
      int(0)
    }

Exemple #2 Exemple de BcMath\Number::powmod() en spécifiant `scale` explicitement

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5, 1),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5, 2),
        new BcMath\Number('8')->powmod('2', -3, 3),
        new BcMath\Number('-8')->powmod(5, 7, 4),
    );
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "-2.00"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "1.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(7) "-1.0000"
      ["scale"]=>
      int(4)
    }

### Voir aussi

- bcpowmod() - Calcule le reste modulo d'un nombre élevé à une puissance
- BcMath\Number::pow() - Élève un nombre de précision arbitraire
- BcMath\Number::mod() - Renvoie le modulo d'un nombre de précision arbitraire

# BcMath\Number::round

(PHP 8 >= 8.4.0)

BcMath\Number::round — Arrondit un nombre de précision arbitraire

### Description

public function BcMath\Number::round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number

Renvoie la valeur arrondie de $this à la `precision` spécifiée (le nombre de chiffres après la virgule). `precision` peut également être négatif ou nul (par défaut).

### Liste de paramètres

`precision`

  Le nombre optionnel de décimales à arrondir.

  Si le paramètre `precision` est positif, `num` sera arrondi en utilisant le paramètre `precision` pour définir le nombre significatif de chiffres après le point décimal.

  Si le paramètre `precision` est négatif, `num` sera arrondi en utilisant le paramètre `precision` pour définir le nombre significatif de chiffres avant le point décimal, c.-à-d. le multiple le plus proche de `pow(10, -$precision)`, c.-à-d. pour une `precision` de -1, `num` sera arrondi à 10, pour une `precision` de -2 à 100, etc.

`mode`
  Spécifie la méthode d'arrondi. Pour plus d'informations sur les méthodes, voir RoundingMode.

### Valeurs de retour

Renvoie le résultat sous forme d'un nouvel objet BcMath\Number.

### Erreurs / Exceptions

Cette méthode lève une ValueError si un `mode` invalide est spécifié.

### Exemples

Exemple #1 Exemple de BcMath\Number::round()

    <?php
    var_dump(
        new BcMath\Number('3.4')->round(),
        new BcMath\Number('3.5')->round(),
        new BcMath\Number('3.6')->round(),
        new BcMath\Number('3.6')->round(0),
        new BcMath\Number('5.045')->round(2),
        new BcMath\Number('5.055')->round(2),
        new BcMath\Number('345')->round(-2),
        new BcMath\Number('345')->round(-3),
        new BcMath\Number('678')->round(-2),
        new BcMath\Number('678')->round(-3),
    );
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "5.05"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "5.06"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(3) "300"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(3) "700"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "1000"
      ["scale"]=>
      int(0)
    }

Exemple #2 Exemple d'utilisation de BcMath\Number::round() avec différentes valeurs de `precision`

    <?php
    $number = new BcMath\Number('123.45');

    var_dump(
        $number->round(3),
        $number->round(2),
        $number->round(1),
        $number->round(0),
        $number->round(-1),
        $number->round(-2),
        $number->round(-3),
    );
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "123.450"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "123.45"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "123.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "123"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(3) "120"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }

Exemple #3 Exemple d'utilisation de BcMath\Number::round() avec différentes valeurs de `mode`

    <?php
    echo 'Rounding modes with 9.5' . PHP_EOL;
    $number = new BcMath\Number('9.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );

    echo PHP_EOL;
    echo 'Rounding modes with 8.5' . PHP_EOL;
    $number = new BcMath\Number('8.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );
    ?>

L'exemple ci-dessus va afficher :

    Rounding modes with 9.5
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#17 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }

    Rounding modes with 8.5
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }

Exemple #4 Exemple d'utilisation de BcMath\Number::round() avec différentes valeurs de `mode` en spécifiant `precision`

    <?php
    $positive = new BcMath\Number('1.55');
    $negative = new BcMath\Number('-1.55');

    echo 'Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfAwayFromZero),
        $negative->round(1, RoundingMode::HalfAwayFromZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfTowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfTowardsZero),
        $negative->round(1, RoundingMode::HalfTowardsZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfEven with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfEven),
        $negative->round(1, RoundingMode::HalfEven),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfOdd with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfOdd),
        $negative->round(1, RoundingMode::HalfOdd),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::TowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::TowardsZero),
        $negative->round(1, RoundingMode::TowardsZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::AwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::AwayFromZero),
        $negative->round(1, RoundingMode::AwayFromZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::NegativeInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::NegativeInfinity),
        $negative->round(1, RoundingMode::NegativeInfinity),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::PositiveInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::PositiveInfinity),
        $negative->round(1, RoundingMode::PositiveInfinity),
    );
    ?>

L'exemple ci-dessus va afficher :

    Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::HalfTowardsZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::HalfEven with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::HalfOdd with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::TowardsZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::AwayFromZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::NegativeInfinity with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::PositiveInfinity with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#12 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

### Voir aussi

- bcround() - Arrondit un nombre de précision arbitraire
- BcMath\Number::ceil() - Arrondit au supérieur un nombre de précision arbitraire
- BcMath\Number::floor() - Arrondit à l'inférieur un nombre de précision arbitraire

# BcMath\Number::__serialize

(PHP 8 >= 8.4.0)

BcMath\Number::__serialize — Sérialise un objet BcMath\Number

### Description

public function BcMath\Number::__serialize(): array

Sérialise $this.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Voir aussi

- BcMath\Number::__construct() - Crée un objet BcMath\Number
- BcMath\Number::__unserialize() - Désérialise un paramètre de données en un objet BcMath\Number

# BcMath\Number::sqrt

(PHP 8 >= 8.4.0)

BcMath\Number::sqrt — Renvoie la racine carrée d'un nombre de précision arbitraire

### Description

public function BcMath\Number::sqrt(?int `$scale` = `null`): BcMath\Number

Renvoie la racine carrée de $this.

### Liste de paramètres

`scale`
  BcMath\Number::scale spécifié explicitement pour les résultats du calcul. Si `null`, le BcMath\Number::scale du résultat du calcul sera défini automatiquement.

### Valeurs de retour

Renvoie la racine carrée sous forme d'un nouvel objet BcMath\Number.

Lorsque le BcMath\Number::scale du résultat est défini automatiquement, le BcMath\Number::scale de $this est utilisé. Cependant, dans des cas tels que la division indivisible, le BcMath\Number::scale du résultat est étendu. L'expansion est effectuée uniquement si nécessaire, jusqu'à un maximum de `+10`. Ce comportement est similaire à celui de BcMath\Number::div(), consulter cela pour plus de détails.

C'est-à-dire que si le BcMath\Number::scale de cet objet est `5`, le BcMath\Number::scale du résultat est entre `5` et `15`.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants:

- $this est une valeur négative
- `scale` est hors de la plage valide
- Le BcMath\Number::scale du résultat est hors de la plage valide

### Exemples

Exemple #1 Exemple de BcMath\Number::sqrt()

    <?php
    var_dump(
        new BcMath\Number('2')->sqrt(),
        new BcMath\Number('2')->sqrt(3),
        new BcMath\Number('4')->sqrt(),
        new BcMath\Number('4')->sqrt(3),
    );
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "1.4142135623"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "1.414"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(5) "2.000"
      ["scale"]=>
      int(3)
    }

### Voir aussi

- bcsqrt() - Récupère la racine carrée d'un nombre de grande taille
- BcMath\Number::div() - Divise par un nombre de précision arbitraire
- BcMath\Number::pow() - Élève un nombre de précision arbitraire

# BcMath\Number::sub

(PHP 8 >= 8.4.0)

BcMath\Number::sub — Soustrait un nombre de précision arbitraire

### Description

public function BcMath\Number::sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Soustrait `num` de $this.

### Liste de paramètres

`num`
  La valeur à soustraire.
`scale`
  BcMath\Number::scale spécifié explicitement pour les résultats du calcul. Si `null`, le BcMath\Number::scale du résultat du calcul sera défini automatiquement.

### Valeurs de retour

Renvoie le résultat de la soustraction sous forme d'un nouvel objet BcMath\Number.

Lorsque le BcMath\Number::scale du résultat est défini automatiquement, le plus grand BcMath\Number::scale des deux nombres utilisés pour la soustraction est utilisé.

C'est-à-dire que si les BcMath\Number::scale de deux valeurs sont `2` et `5` respectivement, le BcMath\Number::scale du résultat sera `5`.

### Erreurs / Exceptions

Cette méthode lève une ValueError dans les cas suivants :

- `num` est un string et n'est pas une chaîne numérique BCMath bien formée
- `scale` est en dehors de la plage valide

### Exemples

Exemple #1 Exemple de BcMath\Number::sub() lorsque `scale` n'est pas spécifié

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'));
    $ret2 = $number->sub('-3.456');
    $ret3 = $number->sub(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(8) "-1.11167"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "4.690"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(6) "-5.766"
      ["scale"]=>
      int(3)
    }

Exemple #2 Exemple de BcMath\Number::sub() en spécifiant `scale` explicitement

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->sub('-3.456', 10);
    $ret3 = $number->sub(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

L'exemple ci-dessus va afficher :

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "-1.1"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "4.6900000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-5"
      ["scale"]=>
      int(0)
    }

### Voir aussi

- bcsub() - Soustrait un nombre de grande taille d'un autre
- BcMath\Number::add() - Ajouter un nombre de précision arbitraire

# BcMath\Number::__toString

(PHP 8 >= 8.4.0)

BcMath\Number::__toString — Convertit un BcMath\Number en chaîne

### Description

public function BcMath\Number::__toString(): string

Convertit un BcMath\Number en string.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie BcMath\Number::value sous forme de string.

# BcMath\Number::__unserialize

(PHP 8 >= 8.4.0)

BcMath\Number::__unserialize — Désérialise un paramètre de données en un objet BcMath\Number

### Description

public function BcMath\Number::__unserialize(array `$data`): void

Désérialise un paramètre de données en un objet BcMath\Number.

### Liste de paramètres

`data`
  Le paramètre de données sérialisé en tant qu'array associatif.

### Erreurs / Exceptions

Cette méthode lève une ValueError si des données sérialisées invalides sont passées.

### Voir aussi

- BcMath\Number::__construct() - Crée un objet BcMath\Number
- BcMath\Number::serialize()

## Sommaire

- BcMath\Number::add — Ajouter un nombre de précision arbitraire
- BcMath\Number::ceil — Arrondit au supérieur un nombre de précision arbitraire
- BcMath\Number::compare — Compare deux nombres de précision arbitraire
- BcMath\Number::__construct — Crée un objet BcMath\Number
- BcMath\Number::div — Divise par un nombre de précision arbitraire
- BcMath\Number::divmod — Renvoie le quotient et le modulo d'un nombre de précision arbitraire
- BcMath\Number::floor — Arrondit à l'inférieur un nombre de précision arbitraire
- BcMath\Number::mod — Renvoie le modulo d'un nombre de précision arbitraire
- BcMath\Number::mul — Multiplie un nombre de précision arbitraire
- BcMath\Number::pow — Élève un nombre de précision arbitraire
- BcMath\Number::powmod — Élève un nombre de précision arbitraire, réduit par un modulo spécifié
- BcMath\Number::round — Arrondit un nombre de précision arbitraire
- BcMath\Number::__serialize — Sérialise un objet BcMath\Number
- BcMath\Number::sqrt — Renvoie la racine carrée d'un nombre de précision arbitraire
- BcMath\Number::sub — Soustrait un nombre de précision arbitraire
- BcMath\Number::__toString — Convertit un BcMath\Number en chaîne
- BcMath\Number::__unserialize — Désérialise un paramètre de données en un objet BcMath\Number

- Installation/Configuration
  - Installation
  - Configuration à l'exécution
- Fonctions BC Math
  - bcadd — Additionne deux nombres de grande taille
  - bcceil — Arrondit au supérieur un nombre de précision arbitraire
  - bccomp — Compare deux nombres de grande taille
  - bcdiv — Divise deux nombres de grande taille
  - bcdivmod — Renvoie le quotient et le reste d'un nombre de précision arbitraire
  - bcfloor — Arrondit à l'inférieur un nombre de précision arbitraire
  - bcmod — Retourne le reste d'une division entre nombres de grande taille
  - bcmul — Multiplie deux nombres de grande taille
  - bcpow — Élève un nombre à une puissance donnée
  - bcpowmod — Calcule le reste modulo d'un nombre élevé à une puissance
  - bcround — Arrondit un nombre de précision arbitraire
  - bcscale — Définit ou récupère la précision par défaut pour toutes les fonctions bc math
  - bcsqrt — Récupère la racine carrée d'un nombre de grande taille
  - bcsub — Soustrait un nombre de grande taille d'un autre
- BcMath\Number — La classe BcMath\Number
  - BcMath\Number::add — Ajouter un nombre de précision arbitraire
  - BcMath\Number::ceil — Arrondit au supérieur un nombre de précision arbitraire
  - BcMath\Number::compare — Compare deux nombres de précision arbitraire
  - BcMath\Number::__construct — Crée un objet BcMath\Number
  - BcMath\Number::div — Divise par un nombre de précision arbitraire
  - BcMath\Number::divmod — Renvoie le quotient et le modulo d'un nombre de précision arbitraire
  - BcMath\Number::floor — Arrondit à l'inférieur un nombre de précision arbitraire
  - BcMath\Number::mod — Renvoie le modulo d'un nombre de précision arbitraire
  - BcMath\Number::mul — Multiplie un nombre de précision arbitraire
  - BcMath\Number::pow — Élève un nombre de précision arbitraire
  - BcMath\Number::powmod — Élève un nombre de précision arbitraire, réduit par un modulo spécifié
  - BcMath\Number::round — Arrondit un nombre de précision arbitraire
  - BcMath\Number::__serialize — Sérialise un objet BcMath\Number
  - BcMath\Number::sqrt — Renvoie la racine carrée d'un nombre de précision arbitraire
  - BcMath\Number::sub — Soustrait un nombre de précision arbitraire
  - BcMath\Number::__toString — Convertit un BcMath\Number en chaîne
  - BcMath\Number::__unserialize — Désérialise un paramètre de données en un objet BcMath\Number

# GNU Multiple Precision

# Introduction

Ces fonctions permettent de travailler avec des nombres de taille arbitraire, en utilisant la bibliothèque GNU MP.

> Note:

> La plupart des fonctions GMP acceptent des nombres GMP comme arguments. Ils sont montrés dans la documentation comme des objets GMP. La plupart de ces fonctions acceptent également des arguments sous la forme numérique et de chaîne de caractères, tant qu'il est possible de les convertir plus tard en nombre. Ainsi, s'il existe une fonction plus performante qui peut fonctionner sur les arguments (entiers seulement), alors elle sera utilisée à la place (cela est fait de manière transparente). Voir aussi la fonction gmp_init().

> Note:

> Des opérateurs arithmétiques, sur les bits, et de comparaison peuvent être utilisés avec les objets GMP retournés depuis gmp_init() et les autres fonctions GMP.

Avertissement

Les entiers volumineux doivent être spécifiés en tant que chaînes - autrement, PHP les force en nombre décimal, entraînant une perte de précision.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

La bibliothèque GMP peut être téléchargée depuis le site de » http://gmplib.org/#DOWNLOAD. Ce site propose aussi un manuel GMP.

Au moins la version 4.2 de GMP est requise, avec certaines fonctions nécessitant une version plus récente de la bibliothèque GMP.

Sous Windows, MPIR est requis à la place de GMP.

## Installation

Pour pouvoir utiliser ces fonctions, il faut compiler PHP avec GMP en utilisant l'option --with-gmp.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`GMP_ROUND_ZERO` (int)
`GMP_ROUND_PLUSINF` (int)
`GMP_ROUND_MINUSINF` (int)
`GMP_MSW_FIRST` (int)
`GMP_LSW_FIRST` (int)
`GMP_LITTLE_ENDIAN` (int)
`GMP_BIG_ENDIAN` (int)
`GMP_NATIVE_ENDIAN` (int)
`GMP_VERSION` (string)
  La version de la bibliothèque GMP
`GMP_MPIR_VERSION` (string)
  La version de la bibliothèque MPIR.

# Exemples

Exemple #1 Factorielle avec GMP

    <?php
    function fact($x)
    {
        $return = 1;
        for ($i=2; $i <= $x; $i++) {
            $return = gmp_mul($return, $i);
        }
        return $return;
    }

    echo gmp_strval(fact(1000)) . "\n";
    ?>

Cet exemple va calculer la factorielle de 1000 (un grand nombre) très vite.

# Fonctions GMP

## Voir aussi

Il est possible de trouver plus de fonctions dans la section Extensions sur les mathématiques.

# gmp_abs

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_abs — Valeur absolue GMP

### Description

function gmp_abs(GMP|int|string `$num`): GMP

Valeur absolue GMP.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Retourne la valeur absolue de `num`, sous la forme d'un nombre GMP.

### Exemples

Exemple #1 Exemple avec gmp_abs()

    <?php
    $abs1 = gmp_abs("274982683358");
    $abs2 = gmp_abs("-274982683358");

    echo gmp_strval($abs1) . "\n";
    echo gmp_strval($abs2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    274982683358
    274982683358

# gmp_add

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_add — Addition de 2 nombres GMP

### Description

function gmp_add(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Addition de 2 nombres GMP.

### Liste de paramètres

`num1`
  Le premier opérande (addend). Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`

  Le second opérande (addend).

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un nombre GMP représentant la somme des arguments.

### Exemples

Exemple #1 Exemple avec gmp_add()

    <?php
    $sum = gmp_add("123456789012345", "76543210987655");
    echo gmp_strval($sum) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    200000000000000

# gmp_and

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_and — ET bit à bit

### Description

function gmp_and(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcule le ET bit à bit de 2 nombres GMP.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un nombre GMP représentant le ET bit à bit (`AND`) des 2 arguments.

### Exemples

Exemple #1 Exemple avec gmp_and()

    <?php
    $and1 = gmp_and("0xfffffffff4", "0x4");
    $and2 = gmp_and("0xfffffffff4", "0x8");
    echo gmp_strval($and1) . "\n";
    echo gmp_strval($and2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    4
    0

# gmp_binomial

(PHP 7 >= 7.3.0, PHP 8)

gmp_binomial — Calcule le coefficient binomial

### Description

function gmp_binomial(GMP|int|string `$n`, int `$k`): GMP

Calcule le coefficient binomial C(n, k).

### Liste de paramètres

`n`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`k`

### Valeurs de retour

Retourne le coefficient binomial C(n, k).

### Erreurs / Exceptions

Lance une ValueError si `k` est négatif. Antérieur à PHP 8.0.0, `E_WARNING` était émis à la place.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction ne retourne plus `false` en cas d'échec.

# gmp_clrbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_clrbit — Annule un bit

### Description

function gmp_clrbit(GMP `$num`, int `$index`): void

Met le bit `index` à 0 dans le nombre GMP `num`. L'index commence à zéro.

### Liste de paramètres

`num`

  Un objet GMP

`index`

  L'index du bit à annuler. L'index 0 représente le bit de poids faible.

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec gmp_clrbit()

    <?php
    $a = gmp_init("0xff");
    gmp_clrbit($a, 0); // l'index commence à zéro
    echo gmp_strval($a) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    254

### Notes

> Note:

> Contrairement à la plupart des autres fonctions GMP, gmp_clrbit() doit être appelée avec un objet GMP existant déjà (en utilisant gmp_init() par exemple). Elle ne sera pas automatiquement créée.

### Voir aussi

- gmp_setbit() - Modifie un bit
- gmp_testbit() - Teste si un bit est défini

# gmp_cmp

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_cmp — Compare des nombres GMP

### Description

function gmp_cmp(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Compare deux nombres GMP.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Retourne une valeur positive si `a > b`, zéro si `a = b` et négative si `a < b`.

### Exemples

Exemple #1 Exemple avec gmp_cmp()

    <?php
    $cmp1 = gmp_cmp("1234", "1000"); // plus grand que
    $cmp2 = gmp_cmp("1000", "1234"); // plus petit que
    $cmp3 = gmp_cmp("1234", "1234"); // égal à

    echo "$cmp1 $cmp2 $cmp3\n";
    ?>

L'exemple ci-dessus va afficher :

    1 -1 0

# gmp_com

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_com — Calcule le complémentaire d'un nombre

### Description

function gmp_com(GMP|int|string `$num`): GMP

Retourne le complémentaire de `num`.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Retourne le complémentaire de `num`, sous la forme d'un nombre GMP.

### Exemples

Exemple #1 Exemple avec gmp_com()

    <?php
    $com = gmp_com("1234");
    echo gmp_strval($com) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    -1235

# gmp_div

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div — Alias de gmp_div_q()

### Description

Cette fonction est un alias de : gmp_div_q().

# gmp_div_q

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_q — Divisions de 2 nombres GMP

### Description

function gmp_div_q(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): GMP

Divise `num1` par `num2` et retourne le résultat entier.

### Liste de paramètres

`num1`

  Le nombre à diviser.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`

  Le nombre par lequel `num1` est divisé.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`rounding_mode`

  L'arrondi du résultat est défini par `rounding_mode`, qui peut prendre l'une des valeurs suivantes :

  - `GMP_ROUND_ZERO`: Le résultat est tronqué vers 0.
  - `GMP_ROUND_PLUSINF`: Le résultat est tronqué vers `+infinity`.
  - `GMP_ROUND_MINUSINF`: Le résultat est tronqué vers `-infinity`.
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_div_q()

    <?php
    $div1 = gmp_div_q("100", "5");
    echo gmp_strval($div1) . "\n";

    $div2 = gmp_div_q("1", "3");
    echo gmp_strval($div2) . "\n";

    $div3 = gmp_div_q("1", "3", GMP_ROUND_PLUSINF);
    echo gmp_strval($div3) . "\n";

    $div4 = gmp_div_q("-1", "4", GMP_ROUND_PLUSINF);
    echo gmp_strval($div4) . "\n";

    $div5 = gmp_div_q("-1", "4", GMP_ROUND_MINUSINF);
    echo gmp_strval($div5) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    20
    0
    1
    0
    -1

### Notes

> Note:

> Cette fonction peut aussi être appelée gmp_div().

### Voir aussi

- gmp_div_r() - Reste de la division de deux nombres GMP
- gmp_div_qr() - Divise deux nombres GMP

# gmp_div_qr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_qr — Divise deux nombres GMP

### Description

function gmp_div_qr(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): array

Divise `num1` par `num2`.

### Liste de paramètres

`num1`

  Le nombre à diviser.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`

  Le diviseur.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`rounding_mode`

  Voir la fonction gmp_div_q() pour une description de l'argument `rounding_mode`.

### Valeurs de retour

Divise `num1` par `num2` et retourne un tableau, dont le premier élément est `[n/d]` (le quotient entier de la division) et le second est `(n - [n/d] * d)` (le reste).

### Exemples

Exemple #1 Division de nombres GMP

    <?php
    $a = gmp_init("0x41682179fbf5");
    $res = gmp_div_qr($a, "0xDEFE75");
    printf("Résultat : q - %s, r - %s",
           gmp_strval($res[0]), gmp_strval($res[1]));
    ?>

### Voir aussi

- gmp_div_q() - Divisions de 2 nombres GMP
- gmp_div_r() - Reste de la division de deux nombres GMP

# gmp_div_r

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_r — Reste de la division de deux nombres GMP

### Description

function gmp_div_r(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): GMP

Calcule le reste de la division entière de `num1` par `num2`. Le reste a le même signe que `num1`, s'il est différent de zéro.

### Liste de paramètres

`num1`

  Le nombre à diviser.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`

  Le nombre par lequel `num1` est divisé.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`rounding_mode`

  Voir la fonction gmp_div_q() pour une description du paramètre `rounding_mode`.

### Valeurs de retour

Retourne le reste, sous la forme d'un nombre GMP.

### Exemples

Exemple #1 Exemple avec gmp_div_r()

    <?php
    $div = gmp_div_r("105", "20");
    echo gmp_strval($div) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    5

### Voir aussi

- gmp_div_q() - Divisions de 2 nombres GMP
- gmp_div_qr() - Divise deux nombres GMP

# gmp_divexact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_divexact — Division exacte de nombres GMP

### Description

function gmp_divexact(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Divise `num1` par `num2`, en utilisant les algorithmes de "division exacte". Cette fonction ne fournit de résultats cohérents que s'il est su par avance que `num2` divise `num1`.

### Liste de paramètres

`num1`

  Le nombre à diviser.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`

  Le diviseur.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_divexact()

    <?php
    $div1 = gmp_divexact("10", "2");
    echo gmp_strval($div1) . "\n";

    $div2 = gmp_divexact("10", "3"); // résultat incohérent
    echo gmp_strval($div2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    5
    2863311534

# gmp_export

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_export — Exportation vers une chaîne binaire

### Description

function gmp_export(GMP|int|string `$num`, int `$word_size` = 1, int `$flags` = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): string

Exporte un nombre GMP vers une chaîne binaire.

### Liste de paramètres

`num`

  Le nombre GMP à exporter.

`word_size`

  La valeur par défaut est 1. Le nombre d'octets dans chaque partie de données binaires. Principalement utilisé avec le paramètre options.

`flags`

  La valeur par défaut est `GMP_MSW_FIRST` | `GMP_NATIVE_ENDIAN`.

### Valeurs de retour

Retourne une chaîne de caractères.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction ne retourne plus `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec gmp_export()

    <?php
    $number = gmp_init(16705);
    echo gmp_export($number) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    AA

### Voir aussi

- gmp_import() - Importation depuis une chaîne binaire

# gmp_fact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_fact — Factorielle GMP

### Description

function gmp_fact(GMP|int|string `$num`): GMP

Calcule la factorielle (`num!`) de `num`.

### Liste de paramètres

`num`

  Le nombre factoriel.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_fact()

    <?php
    $fact1 = gmp_fact(5); // 5 * 4 * 3 * 2 * 1
    echo gmp_strval($fact1) . "\n";

    $fact2 = gmp_fact(50); // 50 * 49 * 48, ... etc
    echo gmp_strval($fact2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    120
    30414093201713378043612608166064768844377641568960512000000000000

# gmp_gcd

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcd — Calcule le PGCD

### Description

function gmp_gcd(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcule le PGCD (plus grand commun diviseur) de `num1` et `num2`. Le résultat est toujours positif, même si l'un des deux (ou les deux) nombres est négatif. Le suffixe _gcd provient de l'anglais 'Greatest Common Divisor'.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un nombre positif GMP qui se divise avec `num1` et `num2`.

### Exemples

Exemple #1 Exemple avec gmp_gcd()

    <?php
    $gcd = gmp_gcd("12", "21");
    echo gmp_strval($gcd) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    3

### Voir aussi

- gmp_lcm() - Calcule le PPCM

# gmp_gcdext

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcdext — PGCD étendu

### Description

function gmp_gcdext(GMP|int|string `$num1`, GMP|int|string `$num2`): array

Calcule les entiers g, s, et t, tels que `a*s + b*t = g = gcd(a,b)`, où gcd est le pgcd de `num1` et `num2`. La fonction retourne un tableau avec les index g, s et t.

Cette fonction peut être utilisée pour résoudre des équations diophantines linéaires à deux variables. Ces équations n'ont qu'une seule solution entière, et elles sont de la forme : `a*x + b*y = c`. Pour plus d'informations, voir les pages » "Diophantine Equation" sur MathWorld, en anglais.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un tableau de nombres GMP.

### Exemples

Exemple #1 Résolution d'une équation Diophantine linéaire

    <?php
    // Résolution de l'équation a*s + b*t = g
    // où a = 12, b = 21, g = gcd(12, 21) = 3
    $a = gmp_init(12);
    $b = gmp_init(21);
    $g = gmp_gcd($a, $b);
    $r = gmp_gcdext($a, $b);

    $check_gcd = (gmp_strval($g) == gmp_strval($r['g']));
    $eq_res = gmp_add(gmp_mul($a, $r['s']), gmp_mul($b, $r['t']));
    $check_res = (gmp_strval($g) == gmp_strval($eq_res));

    if ($check_gcd && $check_res) {
        $fmt = "Solution: %d*%d + %d*%d = %d\n";
        printf($fmt, gmp_strval($a), gmp_strval($r['s']), gmp_strval($b),
        gmp_strval($r['t']), gmp_strval($r['g']));
    } else {
        echo "Erreur lors de la résolution de l'équation\n";
    }

    // Résultat : Solution : 12*2 + 21*-1 = 3
    ?>

# gmp_hamdist

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_hamdist — Distance de Hamming

### Description

function gmp_hamdist(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Retourne la distance de Hamming entre `num1` et `num2`. Les deux paramètres doivent être non négatifs.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

  Doit être positif.

`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

  Doit être positif.

### Valeurs de retour

La distance de Hamming entre `num1` et `num2`, sous la forme d'un int.

### Exemples

Exemple #1 Exemple avec gmp_hamdist()

    <?php
    $ham1 = gmp_init("1001010011", 2);
    $ham2 = gmp_init("1011111100", 2);
    echo gmp_hamdist($ham1, $ham2) . "\n";

    /* hamdist est équivalent à : */
    echo gmp_popcount(gmp_xor($ham1, $ham2)) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    6
    6

### Voir aussi

- gmp_popcount() - Comptage de population
- gmp_xor() - OU exclusif bit à bit

# gmp_import

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_import — Importation depuis une chaîne binaire

### Description

function gmp_import(string `$data`, int `$word_size` = 1, int `$flags` = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): GMP

Importe un nombre GMP depuis une chaîne binaire.

### Liste de paramètres

`data`

  La chaîne binaire à importer.

`word_size`

  La valeur par défaut est 1. Le nombre d'octets dans chaque partie de données binaires. Principalement utilisé avec le paramètre options.

`flags`

  La valeur par défaut est `GMP_MSW_FIRST` | `GMP_NATIVE_ENDIAN`.

### Valeurs de retour

Retourne un nombre GMP.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction ne retourne plus `false` en cas d'échec.

### Exemples

Exemple #1 Exemple avec gmp_import()

    <?php
    $number = gmp_import("\0");
    echo gmp_strval($number) . "\n";

    $number = gmp_import("\0\1\2");
    echo gmp_strval($number) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    0
    258

### Voir aussi

- gmp_export() - Exportation vers une chaîne binaire

# gmp_init

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_init — Crée un nombre GMP

### Description

function gmp_init(int|string `$num`, int `$base` = 0): GMP

Crée un nombre GMP, à partir d'un entier ou d'une chaîne.

### Liste de paramètres

`num`
  Un entier ou une chaîne de caractères. La chaîne peut être une représentation décimale, hexadécimale, octale ou binaire.
`base`
  La base à utiliser pour convertir une représentation sous forme de string. Une base explicite peut être comprise entre `2` et `62`. Pour les bases jusqu'à `36`, la casse est ignorée : les lettres majuscules et minuscules ont la même valeur. Pour les bases de `37` à `62`, les lettres majuscules représentent les valeurs de `10` à `35` et les lettres minuscules représentent les valeurs de `36` à `61`. Si `base` vaut `0`, alors la base réelle est déterminée à partir des caractères initiaux de `num`. Si les deux premiers caractères sont `0x` ou `0X`, la chaîne est interprétée comme un entier hexadécimal. Si les deux premiers caractères sont `0b` ou `0B`, la chaîne est interprétée comme un entier binaire. Si les deux premiers caractères sont `0o` ou `0O`, la chaîne est interprétée comme un entier octal. De plus, si le premier caractère est `0`, la chaîne est également interprétée comme un entier octal. Dans tous les autres cas, la chaîne est interprétée comme un entier décimal.

### Valeurs de retour

Un objet GMP.

### Historique

Version | Description
--- | ---
8.1.0 | La prise en charge des préfixes octaux explicites `0o` et `0O` a été ajoutée pour les chaînes de caractères `num`. L'interprétation de ces préfixes lorsque `base` vaut `0` a également été ajoutée.

### Exemples

Exemple #1 Création d'un nombre GMP

    <?php
    $a = gmp_init(123456);
    $b = gmp_init("0xFFFFDEBACDFEDF7200");
    ?>

### Notes

> Note:

> Il n'est pas nécessaire d'appeler cette fonction pour utiliser les entiers ou les chaînes à la place de nombre GMP dans les fonctions GMP, comme gmp_add(). Les arguments de ces fonctions sont automatiquement convertis en nombres GMP, si cette conversion est possible et nécessaire, en utilisant les mêmes règles que gmp_init().

### Voir aussi

- GMP::__construct() - Crée un nombre GMP

# gmp_intval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_intval — Convertit un nombre GMP en entier

### Description

function gmp_intval(GMP|int|string `$num`): int

Convertit un nombre GMP en entier PHP natif.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un entier, représentant le nombre `num`.

### Exemples

Exemple #1 Exemple avec gmp_intval()

    <?php
    // Affiche le bon résultat
    echo gmp_intval("2147483647") . "\n";

    // Affiche un mauvais résultat, hors de portée des entiers PHP
    echo gmp_intval("2147483648") . "\n";

    // Affiche le bon résultat
    echo gmp_strval("2147483648") . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2147483647
    2147483647
    2147483648

### Notes

Avertissement

Retourne un résultat cohérent uniquement si le nombre GMP peut être représenté par un entier PHP (c.-à-d. type long signé). Pour simplement afficher un nombre GMP, il convient plutôt d'utiliser gmp_strval().

# gmp_invert

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_invert — Modulo inversé

### Description

function gmp_invert(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP|false

Calcule l'inverse de `num1` modulo `num2`.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un nombre GMP en cas de succès, ou `false` si l'inverse n'existe pas.

### Exemples

Exemple #1 Exemple avec gmp_invert()

    <?php
    echo gmp_invert("5", "10"); // pas d'inverse, n'affiche rien, le résultat est FALSE
    $invert = gmp_invert("5", "11");
    echo gmp_strval($invert) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    9

# gmp_jacobi

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_jacobi — Symbole de Jacobi

### Description

function gmp_jacobi(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Calcule le » symbole de Jacobi de `num1` et `num2`. `num2` doit être positif et impair.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

  Doit être positif et impair.

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_jacobi()

    <?php
    echo gmp_jacobi("1", "3") . "\n";
    echo gmp_jacobi("2", "3") . "\n";
    ?>

L'exemple ci-dessus va afficher :

    1
    0

### Voir aussi

- gmp_kronecker() - Symbole Kronecker
- gmp_legendre() - Symbole de Legendre

# gmp_kronecker

(PHP 7 >= 7.3.0, PHP 8)

gmp_kronecker — Symbole Kronecker

### Description

function gmp_kronecker(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Cette fonction calcule le symbole Kronecker de `num1` et `num2`.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Retourne le symbole Kronecker de `num1` et `num2`.

### Voir aussi

- gmp_jacobi() - Symbole de Jacobi
- gmp_legendre() - Symbole de Legendre

# gmp_lcm

(PHP 7 >= 7.3.0, PHP 8)

gmp_lcm — Calcule le PPCM

### Description

function gmp_lcm(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Cette fonction calcule le plus petit commun multiple (ppcm) de `num1` et `num2`.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un objet GMP.

### Voir aussi

- gmp_gcd() - Calcule le PGCD

# gmp_legendre

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_legendre — Symbole de Legendre

### Description

function gmp_legendre(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Calcule le » symbole de Legendre de `num1` et `num2`. `num2` doit être positif et impair.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

  Doit être positif et impair.

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_legendre()

    <?php
    echo gmp_legendre("1", "3") . "\n";
    echo gmp_legendre("2", "3") . "\n";
    ?>

L'exemple ci-dessus va afficher :

    1
    0

### Voir aussi

- gmp_jacobi() - Symbole de Jacobi
- gmp_kronecker() - Symbole Kronecker

# gmp_mod

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mod — Modulo GMP

### Description

function gmp_mod(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcule `num1` modulo `num2`. Le résultat est toujours positif ou nul, car le signe de `num2` est ignoré.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`

  Le modulo à évaluer.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_mod()

    <?php
    $mod = gmp_mod("8", "3");
    echo gmp_strval($mod) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2

# gmp_mul

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mul — Multiplication de 2 nombres GMP

### Description

function gmp_mul(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Multiplie les nombres GMP `num1` et `num2`.

### Liste de paramètres

`num1`

  Un nombre qui sera multiplié par `num2`.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`

  Un nombre qui sera multiplié par `num1`.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_mul()

    <?php
    $mul = gmp_mul("12345678", "2000");
    echo gmp_strval($mul) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    24691356000

# gmp_neg

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_neg — Opposé de nombre GMP

### Description

function gmp_neg(GMP|int|string `$num`): GMP

Retourne l'opposé d'un nombre.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Retourne -`num`, sous la forme d'un nombre GMP.

### Exemples

Exemple #1 Exemple avec gmp_neg()

    <?php
    $neg1 = gmp_neg("1");
    echo gmp_strval($neg1) . "\n";
    $neg2 = gmp_neg("-1");
    echo gmp_strval($neg2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    -1
    1

# gmp_nextprime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

gmp_nextprime — Trouve le prochain nombre premier

### Description

function gmp_nextprime(GMP|int|string `$num`): GMP

Trouve le prochain nombre premier.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Retourne le prochain nombre premier plus grand que `num`, sous la forme d'un nombre GMP.

### Exemples

Exemple #1 Exemple avec gmp_nextprime()

    <?php
    $prime1 = gmp_nextprime(10); // prochain nombre premier supérieur à 10
    $prime2 = gmp_nextprime(-1000); // prochain nombre premier supérieur à -1000

    echo gmp_strval($prime1) . "\n";
    echo gmp_strval($prime2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    11
    2

### Notes

> Note:

> Cette fonction utilise un algorithme probabiliste pour identifier un nombre premier et les chances de récupérer un nombre composite sont extrêmement faibles.

# gmp_or

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_or — OU bit à bit

### Description

function gmp_or(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcule le OU bit à bit de deux nombres GMP.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_or()

    <?php
    $or1 = gmp_or("0xfffffff2", "4");
    echo gmp_strval($or1, 16) . "\n";
    $or2 = gmp_or("0xfffffff2", "2");
    echo gmp_strval($or2, 16) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    fffffff6
    fffffff2

# gmp_perfect_power

(PHP 7 >= 7.3.0, PHP 8)

gmp_perfect_power — Vérifie si un nombre est une puissance parfaite

### Description

function gmp_perfect_power(GMP|int|string `$num`): bool

Vérifie si `num` est une puissance parfaite.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Retourne `true` si `num` est une puissance parfaite, `false` sinon.

### Voir aussi

- gmp_perfect_square() - Carré parfait GMP

# gmp_perfect_square

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_perfect_square — Carré parfait GMP

### Description

function gmp_perfect_square(GMP|int|string `$num`): bool

Vérifie si `num` est un carré parfait.

### Liste de paramètres

`num`

  Le nombre à vérifier.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Retourne `true` si `num` est un carré parfait, `false` sinon.

### Exemples

Exemple #1 Exemple avec gmp_perfect_square()

    <?php
    // 3 * 3, carré parfait
    var_dump(gmp_perfect_square("9"));

    // pas un carré parfait
    var_dump(gmp_perfect_square("7"));

    // 1234567890 * 1234567890, carré parfait
    var_dump(gmp_perfect_square("1524157875019052100"));
    ?>

L'exemple ci-dessus va afficher :

    bool(true)
    bool(false)
    bool(true)

### Voir aussi

- gmp_perfect_power() - Vérifie si un nombre est une puissance parfaite
- gmp_sqrt() - Racine carrée GMP
- gmp_sqrtrem() - Racine carrée avec reste GMP

# gmp_popcount

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_popcount — Comptage de population

### Description

function gmp_popcount(GMP|int|string `$num`): int

Dénombre la population de `num`.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

La population de `num`, sous la forme d'un int.

### Exemples

Exemple #1 Exemple avec gmp_popcount()

    <?php
    $pop1 = gmp_init("10000101", 2); // 3 1's
    echo gmp_popcount($pop1) . "\n";
    $pop2 = gmp_init("11111110", 2); // 7 1's
    echo gmp_popcount($pop2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    3
    7

# gmp_pow

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_pow — Puissance

### Description

function gmp_pow(GMP|int|string `$num`, int `$exponent`): GMP

Élève `num` à la puissance `exponent`.

### Liste de paramètres

`num`

  La base.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`exponent`

  La puissance positive utilisée pour élever `num`.

### Valeurs de retour

Le nouveau nombre, sous la forme d'un nombre GMP. Dans le cas de `0^0`, gmp_pow() retourne 1.

### Exemples

Exemple #1 Exemple avec gmp_pow()

    <?php
    $pow1 = gmp_pow("2", 31);
    echo gmp_strval($pow1) . "\n";
    $pow2 = gmp_pow("0", 0);
    echo gmp_strval($pow2) . "\n";
    $pow3 = gmp_pow("2", -1); // Négatif, génère un warning
    echo gmp_strval($pow3) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2147483648
    1

# gmp_powm

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_powm — Puissance et modulo

### Description

function gmp_powm(GMP|int|string `$num`, GMP|int|string `$exponent`, GMP|int|string `$modulus`): GMP

Calcule (`num` puissance `exponent`) modulo `modulus`. Si `exponent` est négatif, le résultat est indéfini.

### Liste de paramètres

`num`

  La base.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`exponent`

  La puissance positive utilisée pour élever `num`.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`modulus`

  Le modulo.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Le nouveau nombre, sous la forme d'un nombre GMP.

### Exemples

Exemple #1 Exemple avec gmp_powm()

    <?php
    $pow1 = gmp_powm("2", "31", "2147483649");
    echo gmp_strval($pow1) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    2147483648

# gmp_prob_prime

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_prob_prime — Nombre GMP probablement premier

### Description

function gmp_prob_prime(GMP|int|string `$num`, int `$repetitions` = 10): int

La fonction utilise le test de probabilité Miller-Rabin.

### Liste de paramètres

`num`

  Le nombre à vérifier.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`repetitions`

  `repetitions` peut raisonnablement varier de 5 à 10 (par défaut, c'est 10); une valeur supérieure réduit la probabilité qu'un nombre non premier soit identifié comme "probablement" premier.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Si gmp_prob_prime() retourne 0, `num` est défini comme non premier. Si gmp_prob_prime() retourne 1, alors `num` est "probablement" premier. Si gmp_prob_prime() retourne 2, alors `num` est sûrement premier.

### Exemples

Exemple #1 Exemple avec gmp_prob_prime()

    <?php
    // pas premier
    echo gmp_prob_prime("6") . "\n";

    // probablement premier
    echo gmp_prob_prime("1111111111111111111") . "\n";

    // premier
    echo gmp_prob_prime("11") . "\n";
    ?>

L'exemple ci-dessus va afficher :

    0
    1
    2

# gmp_random

(PHP 4 >= 4.0.4, PHP 5, PHP 7)

gmp_random — Nombre GMP aléatoire

Avertissement

Cette fonctionnalité est OBSOLÈTE à partir de PHP 7.2.0 et a été SUPPRIMÉE à partir de PHP 8.0.0.

### Description

function gmp_random(int `$limiter` = 20): GMP

Génère un nombre aléatoire. Ce nombre sera compris entre zéro et (2 ** n) -1, où n est le nombre de bits par limb multiplié par `limiter`. Si `limiter` est négatif, un nombre négatif est généré.

Un limb est un mécanisme interne de GMP. Le nombre de bits dans un limb n'est pas statique, et peut varier entre les systèmes. En général, le nombre de bits par limb est 32 ou 64, mais ce n'est pas garanti.

Attention

Cette fonction ne génère pas de valeurs cryptographiquement sûres, et ne doit pas être utilisée à des fins cryptographiques, ou à des fins qui exigent que les valeurs renvoyées soient indéchiffrables.

Si de l'aléatoire cryptographiquement sûre est requis, le Random\Randomizer peut être utilisé avec le moteur Random\Engine\Secure. Pour des cas d'usage simple, les fonctions random_int() et random_bytes() fournissent une API pratique et sûre qui est qui est soutenu par le CSPRNG du système d'exploitation.

### Liste de paramètres

`limiter`

  Le limiteur.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un nombre GMP aléatoire.

### Exemples

Exemple #1 Exemple avec gmp_random()

    <?php
    $rand1 = gmp_random(1); // nombre aléatoire de 0 à 1 * bits par limb
    $rand2 = gmp_random(2); // nombre aléatoire de 0 à 2 * bits par limb

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    1915834968
    8642564075890328087

# gmp_random_bits

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_bits — Génère un nombre aléatoire

### Description

function gmp_random_bits(int `$bits`): GMP

Génère un nombre aléatoire. Le nombre sera dans l'intervalle `0` et `2$bits - 1`.

Le paramètre `bits` doit être plus grand que 0, et la valeur maximale sera restreinte par la mémoire disponible.

Attention

Cette fonction ne génère pas de valeurs cryptographiquement sûres, et ne doit pas être utilisée à des fins cryptographiques, ou à des fins qui exigent que les valeurs renvoyées soient indéchiffrables.

Si de l'aléatoire cryptographiquement sûre est requis, le Random\Randomizer peut être utilisé avec le moteur Random\Engine\Secure. Pour des cas d'usage simple, les fonctions random_int() et random_bytes() fournissent une API pratique et sûre qui est qui est soutenu par le CSPRNG du système d'exploitation.

### Liste de paramètres

`bits`

  Le nombre de bits à générer.

### Valeurs de retour

Un nombre GMP aléatoire.

### Erreurs / Exceptions

Si `bits` est moins que `1`, une ValueError sera lancée.

### Exemples

Exemple #1 Exemple avec gmp_random_bits()

    <?php
    $rand1 = gmp_random_bits(3); // nombre aléatoire entre 0 et 7
    $rand2 = gmp_random_bits(5); // nombre aléatoire entre 0 et 31

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    3
    15

# gmp_random_range

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_range — Récupérer un entier uniformément sélectionné

### Description

function gmp_random_range(GMP|int|string `$min`, GMP|int|string `$max`): GMP

Génère un nombre aléatoire. Le nombre sera dans l'intervalle `min` et `max`.

`min` et `max` peuvent être tous les deux négatifs, mais `min` doit toujours être inférieur à `max`.

Attention

Cette fonction ne génère pas de valeurs cryptographiquement sûres, et ne doit pas être utilisée à des fins cryptographiques, ou à des fins qui exigent que les valeurs renvoyées soient indéchiffrables.

Si de l'aléatoire cryptographiquement sûre est requis, le Random\Randomizer peut être utilisé avec le moteur Random\Engine\Secure. Pour des cas d'usage simple, les fonctions random_int() et random_bytes() fournissent une API pratique et sûre qui est qui est soutenu par le CSPRNG du système d'exploitation.

### Liste de paramètres

`min`

  Un nombre GMP représentant la borne inférieure pour le nombre aléatoire.

`max`

  Un nombre GMP représentant la borne supérieure pour le nombre aléatoire.

### Valeurs de retour

Un nombre GMP aléatoire. Retourne un objet GMP qui contient un entier uniformément sélectionné dans l'intervalle fermé [`min`, `max`]. `min` et `max` sont tous les deux des valeurs de retour possible.

### Erreurs / Exceptions

Si `max` est inférieur à `min`, une ValueError sera lancée.

### Exemples

Exemple #1 Exemple avec gmp_random_range()

    <?php
    $rand1 = gmp_random_range(0, 100);    // nombre aléatoire entre 0 et 100
    $rand2 = gmp_random_range(-100, -10); // nombre aléatoire entre -100 et -10

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    42
    -67

# gmp_random_seed

(PHP 7, PHP 8)

gmp_random_seed — Définit la graine RNG (Générateur de Nombres Aléatoire)

### Description

function gmp_random_seed(GMP|int|string `$seed`): void

### Liste de paramètres

`seed`

  La graine à définir pour les fonctions gmp_random(), gmp_random_bits(), et gmp_random_range().

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Aucune valeur n'est retournée.

### Erreurs / Exceptions

Lève une exception ValueError si le paramètre `seed` est invalide.

### Historique

Version | Description
--- | ---
8.0.0 | Si le paramètre `seed` est invalide, gmp_random_seed() lève une exception ValueError dorénavant. Précédemment une alerte `E_WARNING` était émise.

### Exemples

Exemple #1 Exemple avec gmp_random_seed()

    <?php
    // Définition de la graine
    gmp_random_seed(100);

    var_dump(gmp_strval(gmp_random(1)));

    // Définition de la graine avec une autre valeur
    gmp_random_seed(gmp_init(-100));

    var_dump(gmp_strval(gmp_random_bits(10)));

    // Définition de la graine avec une valeur invalide
    var_dump(gmp_random_seed('not a number'));

L'exemple ci-dessus va afficher :

    string(20) "15370156633245019617"
    string(3) "683"

    Warning: gmp_random_seed(): Unable to convert variable to GMP - string is not an integer in %s on line %d
    bool(false)

### Voir aussi

- gmp_init() - Crée un nombre GMP
- gmp_random() - Nombre GMP aléatoire
- gmp_random_bits() - Génère un nombre aléatoire
- gmp_random_range() - Récupérer un entier uniformément sélectionné

# gmp_root

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_root — Récupère la partie entière de la n-ème racine

### Description

function gmp_root(GMP|int|string `$num`, int `$nth`): GMP

Récupère la `nth`-ème racine de `num` et retourne la partie entière du résultat.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`nth`

  La racine positive à prendre de `num`.

### Valeurs de retour

La partie entière de la racine résultante, sous la forme d'un nombre GMP.

# gmp_rootrem

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_rootrem — Récupère la partie entière et le reste de la n-ème racine

### Description

function gmp_rootrem(GMP|int|string `$num`, int `$nth`): array

Récupère la `nth`-ème racine de `num` et retourne la partie entière et le reste du résultat.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`nth`

  La racine positive à prendre de `num`.

### Valeurs de retour

Un tableau contenant deux éléments ; le premier est la partie entière de la racine, et le second, le reste. Les deux sont représentés sous la forme d'un nombre GMP.

# gmp_scan0

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan0 — Recherche 0

### Description

function gmp_scan0(GMP|int|string `$num1`, int `$start`): int

Recherche dans `num1`, en commençant à la position `start`, vers les bits de poids lourd, jusqu'à ce qu'elle rencontre un bit à 0.

### Liste de paramètres

`num1`

  Le nombre à analyser.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`start`

  Le bit de départ.

### Valeurs de retour

Retourne l'index du bit trouvé, sous la forme d'un entier. L'index commence à 0.

### Exemples

Exemple #1 Exemple avec gmp_scan0()

    <?php
    // le bit "0" est trouvé à la position 3. l'index commence à 0
    $s1 = gmp_init("10111", 2);
    echo gmp_scan0($s1, 0) . "\n";

    // le bit "0" est trouvé à la position 7. l'index commence à 5
    $s2 = gmp_init("101110000", 2);
    echo gmp_scan0($s2, 5) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    3
    7

# gmp_scan1

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan1 — Recherche 1

### Description

function gmp_scan1(GMP|int|string `$num1`, int `$start`): int

Recherche dans `num1`, en commençant à la position `start`, vers les bits de poids lourd, jusqu'à ce qu'elle rencontre un bit à 1.

### Liste de paramètres

`num1`

  Le nombre à analyser.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`start`

  Le bit de départ.

### Valeurs de retour

Retourne l'index du bit trouvé, sous la forme d'un entier. Si aucun bit n'est trouvé, -1 sera retourné.

### Exemples

Exemple #1 Exemple avec gmp_scan1()

    <?php
    // "1" bit est trouvé à la position 3. l'index commence à 0
    $s1 = gmp_init("01000", 2);
    echo gmp_scan1($s1, 0) . "\n";

    // "1" bit est trouvé à la position 9. l'index commence à 5
    $s2 = gmp_init("01000001111", 2);
    echo gmp_scan1($s2, 5) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    3
    9

# gmp_setbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_setbit — Modifie un bit

### Description

function gmp_setbit(GMP `$num`, int `$index`, bool `$value` = `true`): void

Modifie le bit `index` dans `num`.

### Liste de paramètres

`num`

  Un objet GMP

`index`

  L'index du bit à définir. L'index 0 représente le bit le moins significatif.

`value`

  `true` pour définir le bit (défini à 1/on) ; `false` pour le ré-initialiser (défini à 0/off).

### Valeurs de retour

Aucune valeur n'est retournée.

### Exemples

Exemple #1 Exemple avec gmp_setbit() - index 0

    <?php
    $a = gmp_init("2"); //
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 0); // 0b10 devient maintenant 0b11
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

L'exemple ci-dessus va afficher :

    2 -> 0b10
    3 -> 0b11

Exemple #2 Exemple avec gmp_setbit() - index 1

    <?php
    $a = gmp_init("0xfd");
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 1); // index commence à 0
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

L'exemple ci-dessus va afficher :

    253 -> 0b11111101
    255 -> 0b11111111

Exemple #3 Exemple avec gmp_setbit() - annule un bit

    <?php
    $a = gmp_init("0xff");
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 0, false); // efface le bit à l'index 0
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

L'exemple ci-dessus va afficher :

    255 -> 0b11111111
    254 -> 0b11111110

### Notes

> Note:

> Contrairement à la plupart des autres fonctions GMP, gmp_setbit() doit être appelée avec un objet GMP existant déjà (en utilisant gmp_init() par exemple). Elle ne sera pas automatiquement créée.

### Voir aussi

- gmp_clrbit() - Annule un bit
- gmp_testbit() - Teste si un bit est défini

# gmp_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sign — Signe du nombre GMP

### Description

function gmp_sign(GMP|int|string `$num`): int

Vérifie le signe d'un nombre.

### Liste de paramètres

`num`

  Soit un objet GMP, soit une chaîne numérique à condition qu'il soit possible de convertir ce dernier en un entier.

### Valeurs de retour

Retourne le signe de `num` : 1 si `num` est positif, -1 s'il est négatif et 0 si `num` est égal à zéro.

### Exemples

Exemple #1 Exemple avec gmp_sign()

    <?php
    // positif
    echo gmp_sign("500") . "\n";

    // négatif
    echo gmp_sign("-500") . "\n";

    // zéro
    echo gmp_sign("0") . "\n";
    ?>

L'exemple ci-dessus va afficher :

    1
    -1
    0

### Voir aussi

- gmp_abs() - Valeur absolue GMP
- abs() - Valeur absolue

# gmp_sqrt

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrt — Racine carrée GMP

### Description

function gmp_sqrt(GMP|int|string `$num`): GMP

Calcule la racine carrée GMP du nombre `num`.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

La partie entière de la racine carrée, sous la forme d'un nombre GMP.

### Exemples

Exemple #1 Exemple avec gmp_sqrt()

    <?php
    $sqrt1 = gmp_sqrt("9");
    $sqrt2 = gmp_sqrt("7");
    $sqrt3 = gmp_sqrt("1524157875019052100");

    echo gmp_strval($sqrt1) . "\n";
    echo gmp_strval($sqrt2) . "\n";
    echo gmp_strval($sqrt3) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    3
    2
    1234567890

# gmp_sqrtrem

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrtrem — Racine carrée avec reste GMP

### Description

function gmp_sqrtrem(GMP|int|string `$num`): array

Calcule la racine carrée d'un nombre GMP, avec reste.

### Liste de paramètres

`num`

  Le nombre à traiter.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Retourne un tableau dont le premier élément est la racine carrée entière de `num` (voir aussi gmp_sqrt()), et le second est le reste (c.-à-d., la différence entre `num` et le carré du premier élément).

### Exemples

Exemple #1 Exemple avec gmp_sqrtrem()

    <?php
    list($sqrt1, $sqrt1rem) = gmp_sqrtrem("9");
    list($sqrt2, $sqrt2rem) = gmp_sqrtrem("7");
    list($sqrt3, $sqrt3rem) = gmp_sqrtrem("1048576");

    echo gmp_strval($sqrt1) . ", " . gmp_strval($sqrt1rem) . "\n";
    echo gmp_strval($sqrt2) . ", " . gmp_strval($sqrt2rem) . "\n";
    echo gmp_strval($sqrt3) . ", " . gmp_strval($sqrt3rem) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    3, 0
    2, 3
    1024, 0

# gmp_strval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_strval — Convertit un nombre GMP en chaîne

### Description

function gmp_strval(GMP|int|string `$num`, int `$base` = 10): string

Convertit un nombre GMP en chaîne de caractères, dans la base `base`. La base par défaut est 10.

### Liste de paramètres

`num`

  Le nombre GMP qui doit être converti.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`base`

  La base du nombre retourné. Par défaut, vaut 10. Les valeurs possibles vont de 2 à 62 et de -2 à -36.

### Valeurs de retour

Le nombre, sous la forme d'une chaîne de caractères.

### Exemples

Exemple #1 Convertir un nombre GMP en chaîne de caractères

    <?php
    $a = gmp_init("0x41682179fbf5");
    printf("Décimal : %s, 36-based : %s", gmp_strval($a), gmp_strval($a,36));
    ?>

# gmp_sub

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sub — Soustraction de 2 nombres GMP

### Description

function gmp_sub(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Soustrait `num2` de `num1` et retourne le résultat.

### Liste de paramètres

`num1`

  Le nombre à soustraire.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`

  Le nombre à soustraire de `num1`.

  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_sub()

    <?php
    $sub = gmp_sub("281474976710656", "4294967296"); // 2^48 - 2^32
    echo gmp_strval($sub) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    281470681743360

# gmp_testbit

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gmp_testbit — Teste si un bit est défini

### Description

function gmp_testbit(GMP|int|string `$num`, int `$index`): bool

Teste si un bit est défini.

### Liste de paramètres

`num`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`index`

  Le bit à tester

### Valeurs de retour

Retourne `true` si le bit est défini dans la ressource `num`, `false` sinon.

### Erreurs / Exceptions

Une alerte de niveau `E_WARNING` est émise lorsque le paramètre `index` est inférieur à `0` ; `false` sera retourné dans ce cas.

### Exemples

Exemple #1 Exemple avec gmp_testbit()

    <?php
    $n = gmp_init("1000000");
    var_dump(gmp_testbit($n, 1));
    gmp_setbit($n, 1);
    var_dump(gmp_testbit($n, 1));
    ?>

L'exemple ci-dessus va afficher :

    bool(false)
    bool(true)

### Voir aussi

- gmp_setbit() - Modifie un bit
- gmp_clrbit() - Annule un bit

# gmp_xor

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_xor — OU exclusif bit à bit

### Description

function gmp_xor(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calcule le OU exclusif bit à bit (XOR) de deux nombres GMP.

### Liste de paramètres

`num1`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).
`num2`
  Un objet GMP, un entier, ou un chaîne de caractères qui peut être interprété comme un nombre suivant la même logique que si la chaîne était utilisée dans gmp_init() avec détection automatique de la base (c'est-à-dire lorsque `base` est égal à 0).

### Valeurs de retour

Un objet GMP.

### Exemples

Exemple #1 Exemple avec gmp_xor()

    <?php
    $xor1 = gmp_init("1101101110011101", 2);
    $xor2 = gmp_init("0110011001011001", 2);

    $xor3 = gmp_xor($xor1, $xor2);

    echo gmp_strval($xor3, 2) . "\n";
    ?>

L'exemple ci-dessus va afficher :

    1011110111000100

## Sommaire

- gmp_abs — Valeur absolue GMP
- gmp_add — Addition de 2 nombres GMP
- gmp_and — ET bit à bit
- gmp_binomial — Calcule le coefficient binomial
- gmp_clrbit — Annule un bit
- gmp_cmp — Compare des nombres GMP
- gmp_com — Calcule le complémentaire d'un nombre
- gmp_div — Alias de gmp_div_q
- gmp_div_q — Divisions de 2 nombres GMP
- gmp_div_qr — Divise deux nombres GMP
- gmp_div_r — Reste de la division de deux nombres GMP
- gmp_divexact — Division exacte de nombres GMP
- gmp_export — Exportation vers une chaîne binaire
- gmp_fact — Factorielle GMP
- gmp_gcd — Calcule le PGCD
- gmp_gcdext — PGCD étendu
- gmp_hamdist — Distance de Hamming
- gmp_import — Importation depuis une chaîne binaire
- gmp_init — Crée un nombre GMP
- gmp_intval — Convertit un nombre GMP en entier
- gmp_invert — Modulo inversé
- gmp_jacobi — Symbole de Jacobi
- gmp_kronecker — Symbole Kronecker
- gmp_lcm — Calcule le PPCM
- gmp_legendre — Symbole de Legendre
- gmp_mod — Modulo GMP
- gmp_mul — Multiplication de 2 nombres GMP
- gmp_neg — Opposé de nombre GMP
- gmp_nextprime — Trouve le prochain nombre premier
- gmp_or — OU bit à bit
- gmp_perfect_power — Vérifie si un nombre est une puissance parfaite
- gmp_perfect_square — Carré parfait GMP
- gmp_popcount — Comptage de population
- gmp_pow — Puissance
- gmp_powm — Puissance et modulo
- gmp_prob_prime — Nombre GMP probablement premier
- gmp_random — Nombre GMP aléatoire
- gmp_random_bits — Génère un nombre aléatoire
- gmp_random_range — Récupérer un entier uniformément sélectionné
- gmp_random_seed — Définit la graine RNG (Générateur de Nombres Aléatoire)
- gmp_root — Récupère la partie entière de la n-ème racine
- gmp_rootrem — Récupère la partie entière et le reste de la n-ème racine
- gmp_scan0 — Recherche 0
- gmp_scan1 — Recherche 1
- gmp_setbit — Modifie un bit
- gmp_sign — Signe du nombre GMP
- gmp_sqrt — Racine carrée GMP
- gmp_sqrtrem — Racine carrée avec reste GMP
- gmp_strval — Convertit un nombre GMP en chaîne
- gmp_sub — Soustraction de 2 nombres GMP
- gmp_testbit — Teste si un bit est défini
- gmp_xor — OU exclusif bit à bit

# La classe GMP

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

## Introduction

Un nombre GMP. Ces objets supportent la surcharge des opérateurs arithmétiques, sur les bits et de comparaison.

> Note:

> Aucune interface orientée objet n'est fournie pour manipuler les objets GMP. Il convient d'utiliser l'API procédurale de GMP.

## Synopsis de la classe

final class GMP {
/* Méthodes */
public function __construct(int|string `$num` = 0, int `$base` = 0)
public function __serialize(): array
public function __unserialize(array `$data`): void
}

## Historique

Version | Description
--- | ---
8.4.0 | GMP est maintenant marqué final

# GMP::__construct

(PHP 8 >= 8.2.4)

GMP::__construct — Crée un nombre GMP

### Description

public function GMP::__construct(int|string `$num` = 0, int `$base` = 0)

Crée un nombre GMP, à partir d'un entier ou d'une chaîne.

### Liste de paramètres

`num`
  Un entier ou une chaîne de caractères. La chaîne peut être une représentation décimale, hexadécimale, octale ou binaire.
`base`
  La base à utiliser pour convertir une représentation sous forme de string. Une base explicite peut être comprise entre `2` et `62`. Pour les bases jusqu'à `36`, la casse est ignorée : les lettres majuscules et minuscules ont la même valeur. Pour les bases de `37` à `62`, les lettres majuscules représentent les valeurs de `10` à `35` et les lettres minuscules représentent les valeurs de `36` à `61`. Si `base` vaut `0`, alors la base réelle est déterminée à partir des caractères initiaux de `num`. Si les deux premiers caractères sont `0x` ou `0X`, la chaîne est interprétée comme un entier hexadécimal. Si les deux premiers caractères sont `0b` ou `0B`, la chaîne est interprétée comme un entier binaire. Si les deux premiers caractères sont `0o` ou `0O`, la chaîne est interprétée comme un entier octal. De plus, si le premier caractère est `0`, la chaîne est également interprétée comme un entier octal. Dans tous les autres cas, la chaîne est interprétée comme un entier décimal.

### Voir aussi

- gmp_init() - Crée un nombre GMP

# GMP::__serialize

(PHP 8 >= 8.1.0)

GMP::__serialize — Sérialise l'objet GMP

### Description

public function GMP::__serialize(): array

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Aucune valeur n'est retournée.

# GMP::__unserialize

(PHP 8 >= 8.1.0)

GMP::__unserialize — Désérialise le paramètre `data` en un objet GMP

### Description

public function GMP::__unserialize(array `$data`): void

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`data`

  La valeur en cours de désérialisation.

### Valeurs de retour

Aucune valeur n'est retournée.

## Sommaire

- GMP::__construct — Crée un nombre GMP
- GMP::__serialize — Sérialise l'objet GMP
- GMP::__unserialize — Désérialise le paramètre data en un objet GMP

- Installation/Configuration
  - Pré-requis
  - Installation
- Constantes pré-définies
- Exemples
- Fonctions GMP
  - gmp_abs — Valeur absolue GMP
  - gmp_add — Addition de 2 nombres GMP
  - gmp_and — ET bit à bit
  - gmp_binomial — Calcule le coefficient binomial
  - gmp_clrbit — Annule un bit
  - gmp_cmp — Compare des nombres GMP
  - gmp_com — Calcule le complémentaire d'un nombre
  - gmp_div — Alias de gmp_div_q
  - gmp_div_q — Divisions de 2 nombres GMP
  - gmp_div_qr — Divise deux nombres GMP
  - gmp_div_r — Reste de la division de deux nombres GMP
  - gmp_divexact — Division exacte de nombres GMP
  - gmp_export — Exportation vers une chaîne binaire
  - gmp_fact — Factorielle GMP
  - gmp_gcd — Calcule le PGCD
  - gmp_gcdext — PGCD étendu
  - gmp_hamdist — Distance de Hamming
  - gmp_import — Importation depuis une chaîne binaire
  - gmp_init — Crée un nombre GMP
  - gmp_intval — Convertit un nombre GMP en entier
  - gmp_invert — Modulo inversé
  - gmp_jacobi — Symbole de Jacobi
  - gmp_kronecker — Symbole Kronecker
  - gmp_lcm — Calcule le PPCM
  - gmp_legendre — Symbole de Legendre
  - gmp_mod — Modulo GMP
  - gmp_mul — Multiplication de 2 nombres GMP
  - gmp_neg — Opposé de nombre GMP
  - gmp_nextprime — Trouve le prochain nombre premier
  - gmp_or — OU bit à bit
  - gmp_perfect_power — Vérifie si un nombre est une puissance parfaite
  - gmp_perfect_square — Carré parfait GMP
  - gmp_popcount — Comptage de population
  - gmp_pow — Puissance
  - gmp_powm — Puissance et modulo
  - gmp_prob_prime — Nombre GMP probablement premier
  - gmp_random — Nombre GMP aléatoire
  - gmp_random_bits — Génère un nombre aléatoire
  - gmp_random_range — Récupérer un entier uniformément sélectionné
  - gmp_random_seed — Définit la graine RNG (Générateur de Nombres Aléatoire)
  - gmp_root — Récupère la partie entière de la n-ème racine
  - gmp_rootrem — Récupère la partie entière et le reste de la n-ème racine
  - gmp_scan0 — Recherche 0
  - gmp_scan1 — Recherche 1
  - gmp_setbit — Modifie un bit
  - gmp_sign — Signe du nombre GMP
  - gmp_sqrt — Racine carrée GMP
  - gmp_sqrtrem — Racine carrée avec reste GMP
  - gmp_strval — Convertit un nombre GMP en chaîne
  - gmp_sub — Soustraction de 2 nombres GMP
  - gmp_testbit — Teste si un bit est défini
  - gmp_xor — OU exclusif bit à bit
- GMP — La classe GMP
  - GMP::__construct — Crée un nombre GMP
  - GMP::__serialize — Sérialise l'objet GMP
  - GMP::__unserialize — Désérialise le paramètre data en un objet GMP

# Fonctions mathématiques

# Introduction

Ces fonctions de mathématique sont uniquement capables de manipuler des valeurs qui sont dans la plage des types int et float. Pour manipuler des nombres plus larges, voir les fonctions précision mathématique arbitraire ou GNU Multiple Precision functions.

## Voir aussi

- opérateurs arithmétiques
- Fonctions mathématiques de précision arbitraire
- Fonctions de précision multiple GNU

# Constantes pré-définies

Les constantes listées ici sont toujours disponibles dans PHP.

Constantes Mathématiques
`M_PI` (float)
  Approximation du nombre π (pi). (`3.14159265358979323846`).
`M_E` (float)
  Approximation du nombre d'Euler `e` (`2.7182818284590452354`).
`M_LOG2E` (float)
  Approximation de `log2(e)` (`1.4426950408889634074`).
`M_LOG10E` (float)
  Approximation de `log10(e)` (`0.43429448190325182765`).
`M_LN2` (float)
  Approximation de `ln(2)` (`0.69314718055994530942`).
`M_LN10` (float)
  Approximation de `ln(10)` (`2.30258509299404568402`).
`M_PI_2` (float)
  Approximation de `π/2` (`1.57079632679489661923`).
`M_PI_4` (float)
  Approximation de `π/4` (`0.78539816339744830962`).
`M_1_PI` (float)
  Approximation de `1/π` (`0.31830988618379067154`).
`M_2_PI` (float)
  Approximation de `2/π` (`0.63661977236758134308`).
`M_SQRTPI` (float)
  Approximation de `sqrt(π)` (`1.77245385090551602729`).
`M_2_SQRTPI` (float)
  Approximation de `2/sqrt(π)` (`1.12837916709551257390`).
`M_SQRT2` (float)
  Approximation de `sqrt(2)` (`1.41421356237309504880`).
`M_SQRT3` (float)
  Approximation de `sqrt(3)` (`1.73205080756887729352`).
`M_SQRT1_2` (float)
  Approximation de `1/sqrt(2)` (`0.70710678118654752440`).
`M_LNPI` (float)
  Approximation de `ln(π)` (`1.14472988584940017414`).
`M_EULER` (float)
  Approximation de la constante d'Euler γ (`0.57721566490153286061`).

Constantes IEEE 754 de point flottant
`NAN` (float)
  Pas un nombre
`INF` (float)
  Infini

Constantes d'arrondi

> Note: À partir de PHP 8.4.0, il est recommandé d'utiliser l'énumération RoundingMode à la place.

`PHP_ROUND_HALF_UP` (int)
  Arrondir à mi-chemin à l'écart de zéro.
`PHP_ROUND_HALF_DOWN` (int)
  Arrondir à mi-chemin vers zéro.
`PHP_ROUND_HALF_EVEN` (int)
  Arrondir à mi-chemin au pair.
`PHP_ROUND_HALF_ODD` (int)
  Arrondir à mi-chemin impair.

# L'énumération RoundingMode

(PHP 8 >= 8.4.0)

## Introduction

L'énumération RoundingMode est utilisée pour spécifier comment l'arrondissement doit être effectué pour round(), bcround(), et BcMath\Number::round().

## Synopsis d'Enum

enum RoundingMode
{
case HalfAwayFromZero ; // Arrondir à l'entier le plus proche. Si la partie décimale est `5`, arrondit à l'entier avec la valeur absolue la plus grande.
case HalfTowardsZero ; // Arrondir à l'entier le plus proche. Si la partie décimale est `5`, arrondit à l'entier avec la valeur absolue la plus petite.
case HalfEven ; // Arrondir à l'entier le plus proche. Si la partie décimale est `5`, arrondit à l'entier pair.
case HalfOdd ; // Arrondir à l'entier le plus proche. Si la partie décimale est `5`, arrondit à l'entier impair.
case TowardsZero ; // Arrondir à l'entier le plus proche avec une valeur absolue plus petite ou égale.
case AwayFromZero ; // Arrondir à l'entier le plus proche avec une valeur absolue plus grande ou égale.
case NegativeInfinity ; // Arrondir à l'entier le plus grand plus petit ou égal.
case PositiveInfinity ; // Arrondir à l'entier le plus petit plus grand ou égal.
}

# Fonctions Math

# abs

(PHP 4, PHP 5, PHP 7, PHP 8)

abs — Valeur absolue

### Description

function abs(int|float `$num`): int|float

Retourne la valeur absolue du nombre `num`.

### Liste de paramètres

`num`

  La valeur numérique à traiter

### Valeurs de retour

La valeur absolue du nombre `num`. Si le nombre est un nombre décimal, alors le type de retour est aussi nombre décimal, sinon c'est entier (car nombre décimal a généralement un intervalle de valeurs plus large que entier).

### Historique

Version | Description
--- | ---
8.0.0 | `num` n'accepte plus les objets internes qui supportent les conversions numériques.

### Exemples

Exemple #1 Exemple avec abs()

    <?php
    var_dump(abs(-4.2));
    var_dump(abs(5));
    var_dump(abs(-5));
    ?>

L'exemple ci-dessus va afficher :

    float(4.2)
    int(5)
    int(5)

### Voir aussi

- gmp_abs() - Valeur absolue GMP
- gmp_sign() - Signe du nombre GMP

# acos

(PHP 4, PHP 5, PHP 7, PHP 8)

acos — Arc cosinus

### Description

function acos(float `$num`): float

Retourne l'arc cosinus de `num` en radians. acos() est la fonction inverse de cos(), ce qui signifie que `$num == cos(acos($num))` pour chaque valeur de `num` qui est dans le domaine de la fonction acos().

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

L'arc cosinus de `num`, en radians.

### Voir aussi

- cos() - Cosinus
- acosh() - Arc cosinus hyperbolique
- asin() - Arc sinus
- atan() - Arc tangente

# acosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

acosh — Arc cosinus hyperbolique

### Description

function acosh(float `$num`): float

Retourne l'arc cosinus hyperbolique de `num`, c'est-à-dire la valeur dont le cosinus hyperbolique est `num`.

### Liste de paramètres

`num`

  La valeur à traiter

### Valeurs de retour

L'arc cosinus hyperbolique de `num`.

### Voir aussi

- cosh() - Cosinus hyperbolique
- acos() - Arc cosinus
- asinh ()
- atanh() - Arc tangente hyperbolique

# asin

(PHP 4, PHP 5, PHP 7, PHP 8)

asin — Arc sinus

### Description

function asin(float `$num`): float

Retourne l'arc sinus de `num` en radians. asin() est la fonction inverse de sin(), ce qui signifie que `$num == sin(asin($num))` pour chaque valeur de `num` qui est dans le domaine de la fonction asin().

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

L'arc sinus de `num`, en radians.

### Voir aussi

- sin() - Sinus
- asinh() - Arc sinus hyperbolique
- acos() - Arc cosinus
- atan() - Arc tangente

# asinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

asinh — Arc sinus hyperbolique

### Description

function asinh(float `$num`): float

Retourne l'arc sinus hyperbolique de `num`, c'est-à-dire la valeur dont le sinus hyperbolique est `num`.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

L'arc sinus hyperbolique de `num`

### Voir aussi

- sinh() - Sinus hyperbolique
- asin() - Arc sinus
- acosh() - Arc cosinus hyperbolique
- atanh() - Arc tangente hyperbolique

# atan

(PHP 4, PHP 5, PHP 7, PHP 8)

atan — Arc tangente

### Description

function atan(float `$num`): float

Retourne l'arc tangente de `num`, en radians. atan() est la fonction inverse de tan(), ce qui signifie que `$num == tan(atan($num))` pour chaque valeur de `num` qui est dans le domaine de la fonction atan().

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

L'arc tangente de `num`, en radians.

### Voir aussi

- tan() - Tangente
- atanh() - Arc tangente hyperbolique
- asin() - Arc sinus
- acos() - Arc cosinus

# atan2

(PHP 4, PHP 5, PHP 7, PHP 8)

atan2 — Arc tangente de deux variables

### Description

function atan2(float `$y`, float `$x`): float

Retourne l'arc tangente de deux variables `x` et `y`. La formule est : " arc tangent (`y` / `x`) ", et les signes des arguments sont utilisés pour déterminer le quadrant du résultat.

Cette fonction retourne un résultat en radians, entre -PI et PI (inclus).

### Liste de paramètres

`y`

  le dividende

`x`

  le diviseur

### Valeurs de retour

L'arc tangente de deux variables `y`/`x`, en radians.

### Voir aussi

- atan() - Arc tangente

# atanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

atanh — Arc tangente hyperbolique

### Description

function atanh(float `$num`): float

Retourne l'arc tangente hyperbolique de `num`, c'est-à-dire la valeur dont la tangente hyperbolique est `num`.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

L'arc tangente hyperbolique de `num`.

### Voir aussi

- tanh() - Tangente hyperbolique
- atan ()
- asinh() - Arc sinus hyperbolique
- acosh() - Arc cosinus hyperbolique

# base_convert

(PHP 4, PHP 5, PHP 7, PHP 8)

base_convert — Convertit un nombre entre des bases arbitraires

### Description

function base_convert(string `$num`, int `$from_base`, int `$to_base`): string

Retourne une chaîne contenant l'argument `num` représenté dans la base `to_base`. La base de représentation de `num` est donnée par `from_base`. `from_base` et `to_base` doivent être compris entre 2 et 36 inclus. Les chiffres supérieurs à 10 des bases supérieures à 10 seront représentés par les lettres d'A à Z, avec A = 10 et Z = 35. La casse des lettres n'a pas d'importance, c'est-à-dire `num` est interprété de façon insensible à la casse.

Avertissement

base_convert() perdra la précision sur les grands nombres, à cause des propriétés internes du type float utilisé. Lire la section sur les nombres décimaux de ce manuel pour plus d'informations.

### Liste de paramètres

`num`

  Le nombre à convertir. Tous les caractères invalides dans `num` sont ignorés silencieusement. À partir de PHP 7.4.0 fournir des caractères invalides est obsolète.

`from_base`

  La base `num` dans laquelle il est

`to_base`

  La base dans laquelle on doit convertir le nombre `num`

### Valeurs de retour

Le nombre `num` converti dans la base `to_base`

### Historique

Version | Description
--- | ---
7.4.0 | Passer des caractères invalides génèrera désormais une notice obsolète. Le résultat sera toujours calculé comme si les caractères invalides n'existaient pas.

### Exemples

Exemple #1 Exemple avec base_convert()

    <?php
    $hexadecimal = 'a37334';
    echo base_convert($hexadecimal, 16, 2);
    ?>

L'exemple ci-dessus va afficher :

    101000110111001100110100

### Voir aussi

- intval() - Retourne la valeur numérique entière équivalente d'une variable

# bindec

(PHP 4, PHP 5, PHP 7, PHP 8)

bindec — Convertit de binaire en décimal

### Description

function bindec(string `$binary_string`): int|float

Retourne la conversion d'un nombre binaire représenté par la chaîne `binary_string` en décimal.

bindec() convertit un nombre binaire en un entier, ou, si nécessaire pour des raisons de taille, en nombre décimal.

bindec() interprète toutes les valeurs `binary_string` comme des valeurs non-signées entières. Ceci est dû au fait que la fonction bindec() voit le premier bit comme un autre ordre de grandeur plutôt que comme le bit de signe.

### Liste de paramètres

`binary_string`

  La chaîne binaire à convertir. Tous les caractères invalides dans `binary_string` sont ignorés silencieusement. À partir de PHP 7.4.0 fournir des caractères invalides est obsolète.

Avertissement

Ce paramètre doit être une chaîne de caractères. L'utilisation d'un autre type de données produit des résultats inattendus.

### Valeurs de retour

La valeur décimale de `binary_string`

### Historique

Version | Description
--- | ---
7.4.0 | Passer des caractères invalides génèrera désormais une notice obsolète. Le résultat sera toujours calculé comme si les caractères invalides n'existaient pas.

### Exemples

Exemple #1 Exemple avec bindec()

    <?php
    echo bindec('110011') . "\n";
    echo bindec('000110011') . "\n";

    echo bindec('111');
    ?>

L'exemple ci-dessus va afficher :

    51
    51
    7

Exemple #2 bindec() interprète l'entrée comme un entier non-signé

    <?php
    /*
     * Le plus important dans cet exemple est dans la sortie
     * plutôt que dans le code PHP lui-même.
     */

    $magnitude_lower = pow(2, (PHP_INT_SIZE * 8) - 2);
    p($magnitude_lower - 1);
    p($magnitude_lower, 'Avez-vous vu le changement ? Soyez attentif la prochaine fois...');

    p(PHP_INT_MAX, 'PHP_INT_MAX');
    p(~PHP_INT_MAX, 'interprété comme étant supérieur à PHP_INT_MAX');

    if (PHP_INT_SIZE == 4) {
        $note = 'interprété comme étant le plus grand entier non-signé';
    } else {
        $note = 'interprété comme étant le plus grand entier non-signé
                  (18446744073709551615) mais faussé par la précision de la virgule flottante';
    }
    p(-1, $note);

    function p($input, $note = '') {
        echo "entrée :        $input\n";

        $format = '%0' . (PHP_INT_SIZE * 8) . 'b';
        $bin = sprintf($format, $input);
        echo "binaire :       $bin\n";

        ini_set('precision', 20);  // Pour plus de lisibilité sur les PC 64 bits.
        $dec = bindec($bin);
        echo 'bindec() :     ' . $dec . "\n";

        if ($note) {
            echo "Note :         $note\n";
        }

        echo "\n";
    }
    ?>

Résultat de l'exemple ci-dessus sur une machine 32 bits :

    entrée :        1073741823
    binaire :       00111111111111111111111111111111
    bindec() :     1073741823

    entrée :        1073741824
    binaire :       01000000000000000000000000000000
    bindec():     1073741824
    Note :         Avez-vous vu le changement ? Soyez attentif la prochaine fois...

    entrée :        2147483647
    binaire :       01111111111111111111111111111111
    bindec():     2147483647
    Note :         PHP_INT_MAX

    entrée :        -2147483648
    binaire :       10000000000000000000000000000000
    bindec():     2147483648
    Note :         interprété comme étant supérieur à PHP_INT_MAX

    entrée :        -1
    binaire :       11111111111111111111111111111111
    bindec():     4294967295
    Note :         interprété comme étant le plus grand entier non-signé

Résultat de l'exemple ci-dessus sur une machine 64 bits :

    entrée :        4611686018427387903
    binaire :       0011111111111111111111111111111111111111111111111111111111111111
    bindec() :     4611686018427387903

    entrée :        4611686018427387904
    binaire :       0100000000000000000000000000000000000000000000000000000000000000
    bindec() :     4611686018427387904
    Note :         Avez-vous vu le changement ? Soyez attentif la prochaine fois...

    entrée :        9223372036854775807
    binaire :       0111111111111111111111111111111111111111111111111111111111111111
    bindec() :     9223372036854775807
    Note :         PHP_INT_MAX

    entrée :        -9223372036854775808
    binaire :       1000000000000000000000000000000000000000000000000000000000000000
    bindec() :     9223372036854775808
    Note :         interprété comme étant supérieur à PHP_INT_MAX

    entrée :        -1
    binaire :       1111111111111111111111111111111111111111111111111111111111111111
    bindec() :     18446744073709551616
    Note :         interprété comme étant le plus grand entier non-signé
                  (18446744073709551615) mais faussé par la précision de la virgule flottante

### Notes

> Note:

> La fonction peut convertir des nombres qui sont trop larges pour tenir dans un type entier, dans ce cas, ces valeurs sont retournées en tant que nombre décimal.

### Voir aussi

- decbin() - Convertit de décimal en binaire
- octdec() - Conversion d'octal en décimal
- hexdec() - Convertit de hexadécimal en décimal
- base_convert() - Convertit un nombre entre des bases arbitraires

# ceil

(PHP 4, PHP 5, PHP 7, PHP 8)

ceil — Arrondit au nombre supérieur

### Description

function ceil(int|float `$num`): float

Retourne l'entier supérieur du nombre `num`.

### Liste de paramètres

`num`

  La valeur à arrondir

### Valeurs de retour

La valeur `num` arrondie à l'entier supérieur. La valeur retournée est un nombre à virgule flottante (nombre décimal), car l'intervalle des valeurs d'un nombre décimal est généralement plus large que celle d'un entier.

### Historique

Version | Description
--- | ---
8.0.0 | `num` n'accepte plus les objets internes qui supportent les conversions numériques.

### Exemples

Exemple #1 Exemple avec ceil()

    <?php
    echo ceil(4.3), PHP_EOL;    // 5
    echo ceil(9.999), PHP_EOL;  // 10
    echo ceil(-3.14), PHP_EOL;  // -3
    ?>

### Voir aussi

- floor() - Arrondit à l'entier inférieur
- round() - Arrondit un nombre à virgule flottante

# cos

(PHP 4, PHP 5, PHP 7, PHP 8)

cos — Cosinus

### Description

function cos(float `$num`): float

cos() retourne le cosinus de `num` (`num` en radians).

### Liste de paramètres

`num`

  L'angle, en radians

### Valeurs de retour

Le cosinus de `num`.

### Exemples

Exemple #1 Exemple avec cos()

    <?php

    echo cos(M_PI); // -1

    ?>

### Voir aussi

- acos() - Arc cosinus
- sin() - Sinus
- tan() - Tangente
- deg2rad() - Convertit un nombre de degrés en radians

# cosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cosh — Cosinus hyperbolique

### Description

function cosh(float `$num`): float

Retourne le cosinus hyperbolique de `num`, défini comme `(exp($num) + exp(-$num))/2`.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

Le cosinus hyperbolique de `num`.

### Voir aussi

- cos() - Cosinus
- acosh() - Arc cosinus hyperbolique
- sinh() - Sinus hyperbolique
- tanh() - Tangente hyperbolique

# decbin

(PHP 4, PHP 5, PHP 7, PHP 8)

decbin — Convertit de décimal en binaire

### Description

function decbin(int `$num`): string

Retourne une chaîne contenant la représentation binaire de l'entier `num` donné en argument.

### Liste de paramètres

`num`

  Valeur décimale à convertir

  Intervalle d'entrée sur des machines 32-bit
  Paramètre `num` positif | Paramètre `num` négatif | Valeur retournée
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... progression normale ...
  2147483646 |  | 1111111111111111111111111111110
  2147483647 (plus grand entier signé) |  | 1111111111111111111111111111111 (31 uns)
  2147483648 | -2147483648 | 10000000000000000000000000000000
  ... progression normale ...
  4294967294 | -2 | 11111111111111111111111111111110
  4294967295 (plus grand entier non-signé) | -1 | 11111111111111111111111111111111 (32 uns)

  Intervalle d'entrée sur des machines 64-bit
  Paramètre `num` positif | Paramètre `num` négatif | Valeur retournée
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... progression normale ...
  9223372036854775806 |  | 111111111111111111111111111111111111111111111111111111111111110
  9223372036854775807 (plus grand entier signé) |  | 111111111111111111111111111111111111111111111111111111111111111 (63 uns)
  | -9223372036854775808 | 1000000000000000000000000000000000000000000000000000000000000000
  ... progression normale ...
  | -2 | 1111111111111111111111111111111111111111111111111111111111111110
  | -1 | 1111111111111111111111111111111111111111111111111111111111111111 (64 uns)

### Valeurs de retour

Une représentation binaire de `num`.

### Exemples

Exemple #1 Exemple avec decbin()

    <?php
    echo decbin(12) . "\n";
    echo decbin(26);
    ?>

L'exemple ci-dessus va afficher :

    1100
    11010

### Voir aussi

- bindec() - Convertit de binaire en décimal
- decoct() - Convertit de décimal en octal
- dechex() - Convertit de décimal en hexadécimal
- base_convert() - Convertit un nombre entre des bases arbitraires
- printf() - Affiche une chaîne de caractères formatée, en utilisant `%b`, `%032b` ou `%064b` comme format
- sprintf() - Retourne une chaîne formatée, en utilisant `%b`, `%032b` ou `%064b` comme format

# dechex

(PHP 4, PHP 5, PHP 7, PHP 8)

dechex — Convertit de décimal en hexadécimal

### Description

function dechex(int `$num`): string

Retourne une chaîne contenant la représentation hexadécimale de l'argument `num` non-signé.

Le nombre le plus grand pouvant être converti est `PHP_INT_MAX``* 2 + 1` (ou `-1`) : sur les plateformes 32-bit, ce sera `4294967295` en décimal, qui fera que la fonction dechex() retournera `ffffffff`.

### Liste de paramètres

`num`

  La valeur décimale à convertir.

  Vu que le type entier de PHP est signé, mais que la fonction dechex() ne fonctionne qu'avec des entiers non-signés, les entiers négatifs seront traités comme s'ils étaient non-signés.

### Valeurs de retour

Une représentation hexadécimale de `num`.

### Exemples

Exemple #1 Exemple avec dechex()

    <?php
    echo dechex(10) . "\n";
    echo dechex(47);
    ?>

L'exemple ci-dessus va afficher :

    a
    2f

Exemple #2 Exemple avec la fonction dechex() avec de gros entiers

    <?php
    // L'affichage ci-dessous suppose que nous sommes sur une plateforme 32-bit.
    // Il est à noter que l'affichage est identique pour toutes les valeurs.
    echo dechex(-1)."\n";
    echo dechex(PHP_INT_MAX * 2 + 1)."\n";
    echo dechex(pow(2, 32) - 1)."\n";
    ?>

L'exemple ci-dessus va afficher :

    ffffffff
    ffffffff
    ffffffff

### Voir aussi

- hexdec() - Convertit de hexadécimal en décimal
- decbin() - Convertit de décimal en binaire
- decoct() - Convertit de décimal en octal
- base_convert() - Convertit un nombre entre des bases arbitraires

# decoct

(PHP 4, PHP 5, PHP 7, PHP 8)

decoct — Convertit de décimal en octal

### Description

function decoct(int `$num`): string

Retourne une chaîne contenant la représentation octale du nombre donné `num`. Le nombre le plus grand qui puisse être converti est `4294967295` en décimal, ce qui donnera `37777777777`. Pour les plates-formes 64 bits, il s'agit généralement de `9223372036854775807` en décimal résultant en `777777777777777777777`.

### Liste de paramètres

`num`

  Valeur décimale à convertir

### Valeurs de retour

Une représentation octale de `num`.

### Exemples

Exemple #1 Exemple avec decoct()

    <?php
    echo decoct(15) . "\n";
    echo decoct(264);
    ?>

L'exemple ci-dessus va afficher :

    17
    410

### Voir aussi

- octdec() - Conversion d'octal en décimal
- decbin() - Convertit de décimal en binaire
- dechex() - Convertit de décimal en hexadécimal
- base_convert() - Convertit un nombre entre des bases arbitraires

# deg2rad

(PHP 4, PHP 5, PHP 7, PHP 8)

deg2rad — Convertit un nombre de degrés en radians

### Description

function deg2rad(float `$num`): float

deg2rad() convertit `num` de degrés en radians.

### Liste de paramètres

`num`

  L'angle, en degrés

### Valeurs de retour

L'équivalent, en radians, de `num`.

### Exemples

Exemple #1 Exemple avec deg2rad()

    <?php

    echo deg2rad(45), PHP_EOL; // 0.785398163397
    var_dump(deg2rad(45) === M_PI_4); // bool(true)

    ?>

### Voir aussi

- rad2deg() - Conversion de radians en degrés

# exp

(PHP 4, PHP 5, PHP 7, PHP 8)

exp — Calcule l'exponentielle de `e`

### Description

function exp(float `$num`): float

Retourne `e`, à la puissance `num`.

> Note:

> '`e`' est la base du logarithme naturel, ou approximativement 2.718282.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

'e', à la puissance `num`.

### Exemples

Exemple #1 Exemple avec exp()

    <?php
    echo exp(12), PHP_EOL;
    echo exp(5.7);
    ?>

L'exemple ci-dessus va afficher :

    162754.791419
    298.86740096706

### Voir aussi

- log() - Logarithme naturel (népérien)
- pow() - Expression exponentielle

# expm1

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

expm1 — Retourne `exp($num) - 1`, calculé de manière précise même lorsque la valeur du nombre est proche de zéro

### Description

function expm1(float `$num`): float

expm1() retourne l'équivalent de `exp($`num`) - 1` calculé de telle sorte qu'il sera précis, même si la valeur de l'argument `num` est proche de `0`, un cas où l'expression `exp($`num`) - 1` n'est pas précis, du fait de la soustraction de deux nombres quasi-égaux.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

`e` à la puissance `num`, moins un.

### Voir aussi

- log1p() - Calcule précisément log(1 + nombre)
- exp() - Calcule l'exponentielle de e

# fdiv

(PHP 8)

fdiv — Divise deux nombres, selon la norme IEEE 754

### Description

function fdiv(float `$num1`, float `$num2`): float

Renvoie le résultat en virgule flottante de la division de `num1` par `num2`. Si `num2` est zéro, alors l'une des valeurs `INF`, -`INF`, ou `NAN` sera renvoyée.

Il est à noter que dans les comparaisons, `NAN` ne sera jamais égal (`==`) ou identique (`===`) à aucune valeur, y compris elle-même.

### Liste de paramètres

`num1`

  Le dividende (numérateur)

`num2`

  Le diviseur

### Valeurs de retour

Le résultat en virgule flottante de `num1`/`num2`

### Exemples

Exemple #1 Utilisation de fdiv()

    <?php
    var_dump(fdiv(5.7, 1.3)); // float(4.384615384615385)
    var_dump(fdiv(4, 2)); // float(2)
    var_dump(fdiv(1.0, 0.0)); // float(INF)
    var_dump(fdiv(-1.0, 0.0)); // float(-INF)
    var_dump(fdiv(0.0, 0.0)); // float(NAN)
    ?>

### Voir aussi

- Opérateur de division `/`
- intdiv() - Division d'Entier - Division entière
- fmod() - Retourne le reste de la division
- fpow() - Élève un nombre à la puissance d'un autre, selon la norme IEEE 754

# floor

(PHP 4, PHP 5, PHP 7, PHP 8)

floor — Arrondit à l'entier inférieur

### Description

function floor(int|float `$num`): float

Retourne la valeur entière suivante la plus basse (en tant que float) en arrondissant la valeur `num` si nécessaire.

### Liste de paramètres

`num`

  La valeur numérique à arrondir

### Valeurs de retour

floor() retourne l'entier inférieur du nombre `num`. La valeur retournée est un nombre à virgule flottante (nombre décimal).

### Historique

Version | Description
--- | ---
8.0.0 | `num` n'accepte plus les objets internes qui supportent les conversions numériques.

### Exemples

Exemple #1 Exemple avec floor()

    <?php
    echo floor(4.3), PHP_EOL;   // 4
    echo floor(9.999), PHP_EOL; // 9
    echo floor(-3.14), PHP_EOL; // -4
    ?>

### Voir aussi

- ceil() - Arrondit au nombre supérieur
- round() - Arrondit un nombre à virgule flottante

# fmod

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

fmod — Retourne le reste de la division

### Description

function fmod(float `$num1`, float `$num2`): float

Retourne le reste de la division de `num1` par `num2`. Ce reste est un nombre à virgule flottante. Le reste (r) est défini par : num1 = i * num2 + r, pour un entier i. Si `num2` n'est pas nul, r a le même signe que `num1` et une taille inférieure à celle de `num2`.

### Liste de paramètres

`num1`

  Le dividende

`num2`

  Le diviseur

### Valeurs de retour

Le reste de la division de `num1` par `num2`. `NAN` (float) si le second argument est 0.

### Exemples

Exemple #1 Exemple avec fmod()

    <?php
    $x = 5.7;
    $y = 1.3;
    $r = fmod($x, $y);
    // $r vaut 0.5, parce que 4 * 1.3 + 0.5 = 5.7

    var_dump($x, $y, $r);
    ?>

### Voir aussi

- `/` - Division à virgule flottante
- `%` - Modulo d'entier
- intdiv() - Division d'Entier - Division d'entier

# fpow

(PHP 8 >= 8.4.0)

fpow — Élève un nombre à la puissance d'un autre, selon la norme IEEE 754

### Description

function fpow(float `$num`, float `$exponent`): float

Renvoie le résultat en virgule flottante de l'élévation de `num` à la puissance `exponent`. Si `num` est zéro et `exponent` est plus petit que zéro, alors `INF` est retourné.

### Liste de paramètres

`num`
  La base à utiliser.
`exponent`
  L'exposant.

### Valeurs de retour

Renvoie un float correspondant à `$num$exponent`.

### Exemples

Exemple #1 Exemple de fpow()

    <?php
    var_dump(fpow(10, 2));
    var_dump(fpow(0, -3));
    var_dump(fpow(-1, 5.5));
    ?>

L'exemple ci-dessus va afficher :

    float(100)
    float(INF)
    float(NAN)

### Voir aussi

- L'opérateur d'exponentiation `**`
- pow() - Expression exponentielle
- fdiv() - Divise deux nombres, selon la norme IEEE 754
- fmod() - Retourne le reste de la division

# hexdec

(PHP 4, PHP 5, PHP 7, PHP 8)

hexdec — Convertit de hexadécimal en décimal

### Description

function hexdec(string `$hex_string`): int|float

Retourne la valeur décimale équivalente à la chaîne de caractères hexadécimale représentée par l'argument `hex_string`. hexdec() convertit une chaîne de caractères hexadécimale en un nombre décimal.

hexdec() ignorera tout caractère non-hexadécimal qu'elle rencontrera. À partir de PHP 7.4.0 fournir des caractères invalides est obsolète.

### Liste de paramètres

`hex_string`

  La chaîne hexadécimale à convertir

### Valeurs de retour

La représentation décimale de `hex_string`

### Historique

Version | Description
--- | ---
7.4.0 | Passer des caractères invalides génèrera désormais une notice obsolète. Le résultat sera toujours calculé comme si les caractères invalides n'existaient pas.

### Exemples

Exemple #1 Exemple avec hexdec()

    <?php

    var_dump(hexdec("ee")); // affiche "int(238)"
    var_dump(hexdec("a0")); // affiche "int(160)"
    ?>

Exemple #2 hexdec() avec des caractères invalides

    <?php
    var_dump(hexdec("See"));  // affiche "int(238)"
    var_dump(hexdec("that")); // affiche "int(10)"
    ?>

### Notes

> Note:

> La fonction peut convertir des nombres qui sont trop larges pour tenir dans un type entier, dans ce cas, ces valeurs sont retournées en tant que nombre décimal.

### Voir aussi

- dechex() - Convertit de décimal en hexadécimal
- bindec() - Convertit de binaire en décimal
- octdec() - Conversion d'octal en décimal
- base_convert() - Convertit un nombre entre des bases arbitraires

# hypot

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

hypot — Calcule la longueur de l'hypoténuse d'un triangle à angle droit

### Description

function hypot(float `$x`, float `$y`): float

hypot() retourne la longueur de l'hypoténuse d'un triangle à angle droit qui a des cotés d'une longueur `x` et `y` ou bien la distance du point (`x`, `y`) depuis l'origine. Ceci est l'équivalent de `sqrt($x*$x + $y*$y)`.

### Liste de paramètres

`x`

  Longueur du premier côté

`y`

  Longueur du second côté

### Valeurs de retour

La longueur calculée de l'hypoténuse

# intdiv

(PHP 7, PHP 8)

intdiv — Division d'Entier

### Description

function intdiv(int `$num1`, int `$num2`): int

Retourne le quotient entier de la division de `num1` par `num2`.

### Liste de paramètres

`num1`

  Nombre à diviser.

`num2`

  Nombre qui divise `num1`.

### Valeurs de retour

Le quotient entier de la division de `num1` par `num2`.

### Erreurs / Exceptions

Si `num2` est `0`, une exception DivisionByZeroError sera émise. Si `num1` est `PHP_INT_MIN` et que `num2` est `-1`, dans ce cas là une exception ArithmeticError est émise.

### Exemples

Exemple #1 Exemple de intdiv()

    <?php
    var_dump(intdiv(3, 2));
    var_dump(intdiv(-3, 2));
    var_dump(intdiv(3, -2));
    var_dump(intdiv(-3, -2));
    var_dump(intdiv(PHP_INT_MAX, PHP_INT_MAX));
    var_dump(intdiv(PHP_INT_MIN, PHP_INT_MIN));
    ?>

L'exemple ci-dessus va afficher :

    int(1)
    int(-1)
    int(-1)
    int(1)
    int(1)
    int(1)

Exemple #2 Exemple de intdiv() avec un diviseur invalide

    <?php
    try {
        intdiv(PHP_INT_MIN, -1);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    try {
        intdiv(1, 0);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }
    ?>

L'exemple ci-dessus va afficher :

    ArithmeticError: Division of PHP_INT_MIN by -1 is not an integer
    DivisionByZeroError: Division by zero

### Voir aussi

- `/` - Division de nombre flottant
- `%` - Modulo entier
- fmod() - Retourne le reste de la division - Modulo de nombre flottant

# is_finite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_finite — Vérifie si un nombre flottant est fini

### Description

function is_finite(float `$num`): bool

Retourne si le `num` donné est un nombre flottant fini.

Un nombre flottant fini n'est ni `NAN` (is_nan()), ni infini (is_infinite()).

### Liste de paramètres

`num`

  Le nombre décimal à vérifier

### Valeurs de retour

`true` si `num` n'est aucun de `NAN`, `INF`, -`INF`, sinon `false`.

### Exemples

Exemple #1 Exemple de is_finite()

    <?php
    $float = 1.2345;
    var_dump($float, is_finite($float));

    $nan = sqrt(-1);
    var_dump($nan, is_finite($nan));

    $inf = 1e308 * 2;
    var_dump($inf, is_finite($inf));
    ?>

L'exemple ci-dessus va afficher :

    float(1.2345)
    bool(true)
    float(NAN)
    bool(false)
    float(INF)
    bool(false)

### Voir aussi

- is_infinite() - Vérifie si un nombre flottant est infini
- is_nan() - Vérifie si un nombre flottant est NAN

# is_infinite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_infinite — Vérifie si un nombre flottant est infini

### Description

function is_infinite(float `$num`): bool

Retourne si le `num` donné est soit `INF` ou -`INF`.

### Liste de paramètres

`num`

  Le nombre décimal à vérifier

### Valeurs de retour

Retourne si le `num` donné est soit `INF` ou -`INF`, sinon, `false`.

### Exemples

Exemple #1 Exemple de is_infinite()

    <?php
    $inf = 1e308 * 2;

    var_dump($inf, is_infinite($inf));

    $negative_inf = -$inf;

    var_dump($negative_inf, is_infinite($negative_inf));
    ?>

L'exemple ci-dessus va afficher :

    float(INF)
    bool(true)
    float(-INF)
    bool(true)

### Voir aussi

- is_finite() - Vérifie si un nombre flottant est fini
- is_nan() - Vérifie si un nombre flottant est NAN

# is_nan

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_nan — Vérifie si un nombre flottant est NAN

### Description

function is_nan(float `$num`): bool

Retourne si le `num` donné est `NAN` (Not A Number).

`NAN` est retourné par les opérations mathématiques qui ne sont pas définies, par exemple lors du passage de paramètres en dehors du domaine d'entrée de la fonction. La racine carrée (sqrt()) n'est définie que pour les nombres positifs, le passage d'un nombre négatif résultera en un `NAN`. D'autres exemples d'opérations renvoyant `NAN` sont la division de `INF` par `INF` et toute opération impliquant une valeur `NAN` existante.

> Note:

> Malgré son nom Not A Number, `NAN` est une valeur valide de type nombre décimal.

Attention

`NAN` ne se compare pas égal à `NAN`. Pour vérifier si un nombre flottant est `NAN`, is_nan() doit être utilisé. La vérification de `$float === NAN` ne fonctionnera pas.

### Liste de paramètres

`num`

  Le nombre décimal à vérifier

### Valeurs de retour

`true` si `num` est `NAN`, sinon `false`.

### Exemples

Exemple #1 Exemple avec is_nan()

    <?php
    $nan = sqrt(-1);

    var_dump($nan, is_nan($nan));
    ?>

L'exemple ci-dessus va afficher :

    float(NAN)
    bool(true)

### Voir aussi

- is_finite() - Vérifie si un nombre flottant est fini
- is_infinite() - Vérifie si un nombre flottant est infini

# log

(PHP 4, PHP 5, PHP 7, PHP 8)

log — Logarithme naturel (népérien)

### Description

function log(float `$num`, float `$base` = `M_E`): float

Si le paramètre optionnel `base` est spécifié, log() retourne alors le logarithme en base `base`, sinon log() retourne le logarithme naturel (ou népérien) de `num`.

### Liste de paramètres

`num`

  La valeur pour laquelle on calcule le logarithme

`base`

  La base logarithmique optionnelle à utiliser (par défaut, 'e' et donc, le logarithme naturel).

### Valeurs de retour

Le logarithme de `num` en base `base`, si fourni, ou le logarithme naturel.

### Voir aussi

- log10() - Logarithme en base 10
- exp() - Calcule l'exponentielle de e
- pow() - Expression exponentielle
- error_log() - Envoie un message d'erreur vers le gestionnaire d'erreurs défini

# log10

(PHP 4, PHP 5, PHP 7, PHP 8)

log10 — Logarithme en base 10

### Description

function log10(float `$num`): float

Retourne le logarithme en base 10 de `num`.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

Le logarithme en base 10 de `num`.

### Voir aussi

- log() - Logarithme naturel (népérien)

# log1p

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

log1p — Calcule précisément log(1 + nombre)

### Description

function log1p(float `$num`): float

log1p() retourne log(1 + `num`) calculé de telle sorte qu'il sera précis même si la valeur de `num` est proche de `0`. log() ne peut retourner que log(1) dans ce cas par manque de précision.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

log(1 + `num`)

### Voir aussi

- expm1() - Retourne exp($num) - 1, calculé de manière précise même lorsque la valeur du nombre est proche de zéro
- log() - Logarithme naturel (népérien)
- log10() - Logarithme en base 10

# max

(PHP 4, PHP 5, PHP 7, PHP 8)

max — La plus grande valeur

### Description

function max(mixed `$value`, mixed `...$values`): mixed

Signature alternative (non supportée avec les arguments nommés) :

function max(array `$value_array`): mixed

Si le premier et unique paramètre est un tableau, max() retourne la valeur la plus haute du tableau. Si au moins deux paramètres sont fournis, max() retourne la plus grosse de ces valeurs.

> Note:

> Les valeurs de différents types seront comparées en utilisant les règles de comparaison standard. Actuellement, une chaîne non numérique sera comparée à un entier, comme s'il s'agissait de la valeur `0`, mais plusieurs chaîne de caractères non-numériques seront comparées de façon alphanumérique. La valeur actuelle retournée sera du même type que l'original et aucune conversion de type ne sera appliquée.

Attention

Il faut être prudent lorsqu'on passe des arguments avec des types différents, car max() peut produire des résultats imprévisibles.

### Liste de paramètres

`value`

  Toute valeur comparable.

`values`

  Toutes valeurs comparables.

`value_array`

  Un tableau contenant les valeurs.

### Valeurs de retour

La fonction max() retourne la valeur du paramètre considéré comme "supérieure" suivant la comparaison standard. Si plusieurs valeurs de types différents sont évaluées comme étant égales (c.-à-d. `0` et `'abc'`), la première fournie à la fonction sera retournée.

### Erreurs / Exceptions

Si un tableau vide est passé, la fonction max() lance une ValueError.

### Historique

Version | Description
--- | ---
8.0.0 | max() lance désormais une ValueError en cas d'échec ; précédemment, `false` était renvoyé et une erreur `E_WARNING` était émise.
8.0.0 | Comme les comparaisons entre les chaînes et les nombres ont été changées, max() ne retourne plus une valeur différente basée sur l'ordre des arguments dans ces cas là.

### Exemples

Exemple #1 Exemple avec max()

    <?php
    echo max(2, 3, 1, 6, 7), PHP_EOL;  // 7
    echo max(array(2, 4, 5)), PHP_EOL; // 5

    // Ici, nous comparons -1 < 0, aussi 'hello' est la plus grande valeur
    echo max('hello', -1), PHP_EOL;    // hello

    // Avec plusieurs tableaux de tailles différentes, max retourne
    // le plus long
    $val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)
    var_dump($val);

    // Plusieurs tableaux de même longueur sont comparés de la gauche vers la droite
    // aussi, dans notre exemple : 2 == 2, mais 5 > 4
    $val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1)
    var_dump($val);

    // Si un tableau et un non-tableau sont fournis, le tableau sera toujours
    // retourné, sachant que les comparaisons traitent les tableaux comme
    // étant plus grand que n'importe quelle valeur
    $val = max('string', array(2, 5, 7), 42);   // array(2, 5, 7)
    var_dump($val);

    // Si un argument vaut NULL ou est un booléen, il sera comparé avec les autres
    // valeurs en utilisant la règle FALSE < TRUE suivant les autres types concernés
    // Dans l'exemple ci-dessous, -10 est traité comme valant TRUE dans la comparaison
    $val = max(-10, FALSE); // -10
    var_dump($val);

    // D'un autre côté, 0 est traité comme valant FALSE, aussi, il est "plus petit que" TRUE
    $val = max(0, TRUE); // TRUE
    var_dump($val);
    ?>

### Voir aussi

- min() - La plus petite valeur
- count() - Compte tous les éléments d'un tableau ou dans un objet Countable

# min

(PHP 4, PHP 5, PHP 7, PHP 8)

min — La plus petite valeur

### Description

function min(mixed `$value`, mixed `...$values`): mixed

Signature alternative (non supportée avec les arguments nommés) :

function min(array `$value_array`): mixed

Si le premier et le seul paramètre est un tableau, min() retournera la plus petite valeur contenue dans le tableau. Si le premier paramètre est un entier, une chaîne ou un nombre décimal, il faut fournir au moins deux paramètres et min() retournera la plus petite de ces valeurs.

> Note:

> Les valeurs de différents types seront comparées en utilisant les règles de comparaison standard. Actuellement, une chaîne non numérique sera comparée à un entier, comme s'il s'agissait de la valeur `0`, mais plusieurs chaîne de caractères non-numériques seront comparées de façon alphanumérique. La valeur actuelle retournée sera du même type que l'original et aucune conversion de type ne sera appliquée.

Attention

Il faut être prudent lorsqu'on passe des arguments avec des types différents, car min() peut produire des résultats imprévisibles.

### Liste de paramètres

`value`

  Toute valeur comparable.

`values`

  Toutes valeurs comparables.

`value_array`

  Un tableau contenant les valeurs.

### Valeurs de retour

La fonction min() retourne la valeur du paramètre considéré comme "inférieure" suivant la comparaison standard. Si plusieurs valeurs de types différents sont évaluées comme étant égales (c.-à-d. `0` et `'abc'`), la première fournie à la fonction sera retournée.

### Erreurs / Exceptions

Si un tableau vide est passé, la fonction min() lance une ValueError.

### Historique

Version | Description
--- | ---
8.0.0 | min() lance désormais une ValueError en cas d'échec ; précédemment, `false` était renvoyé et une erreur `E_WARNING` était émise.
8.0.0 | Comme les comparaisons entre les chaînes et les nombres ont été changées, min() ne retourne plus une valeur différente basée sur l'ordre des arguments dans ces cas là.

### Exemples

Exemple #1 Exemple avec min()

    <?php
    echo min(2, 3, 1, 6, 7), PHP_EOL;  // 1
    echo min(array(2, 4, 5)), PHP_EOL; // 2

    // Ici, nous comparons -1 < 0, aussi, -1 est la valeur la plus basse
    echo min('hello', -1), PHP_EOL;    // -1

    // Avec plusieurs tableaux de différentes tailles, min retourne le plus court
    $val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2)
    var_dump($val);

    // Plusieurs tableaux de même taille sont comparés depuis la gauche vers la droite,
    // aussi, dans notre exemple : 2 == 2, mais 4 < 5
    $val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)
    var_dump($val);

    // Si un tableau et un non-tableau sont fournis, le tableau ne sera jamais retourné
    // car les comparaisons traitent les tableaux comme plus grand que n'importe quelle valeur
    $val = min('string', array(2, 5, 7), 42);   // string
    var_dump($val);

    // Si un argument vaut NULL ou vaut un booléen, il sera comparé avec
    // d'autres valeurs en utilisant les règles FALSE < TRUE et NULL == FALSE suivant
    // les autres types fournis. Dans l'exemple ci-dessous, à la fois -10 et 10 sont traités
    // comme valant TRUE dans la comparaison
    $val = min(-10, FALSE, 10); // FALSE
    var_dump($val);

    $val = min(-10, NULL, 10);  // NULL
    var_dump($val);

    // D'un autre côté, 0 est traité comme valant FALSE, aussi, il est "plus petit que" TRUE
    $val = min(0, TRUE); // 0
    var_dump($val);
    ?>

### Voir aussi

- max() - La plus grande valeur
- count() - Compte tous les éléments d'un tableau ou dans un objet Countable

# octdec

(PHP 4, PHP 5, PHP 7, PHP 8)

octdec — Conversion d'octal en décimal

### Description

function octdec(string `$octal_string`): int|float

Retourne une chaîne contenant la représentation décimale du nombre `octal_string`.

### Liste de paramètres

`octal_string`

  La chaîne de caractères octale à convertir. Tous les caractères invalides dans `octal_string` sont ignorés silencieusement. À partir de PHP 7.4.0 fournir des caractères invalides est obsolète.

### Valeurs de retour

La représentation décimale de `octal_string`

### Historique

Version | Description
--- | ---
7.4.0 | Passer des caractères invalides génèrera désormais une notice obsolète. Le résultat sera toujours calculé comme si les caractères invalides n'existaient pas.

### Exemples

Exemple #1 Exemple avec octdec()

    <?php
    echo octdec('77') . "\n";
    echo octdec(decoct(45));
    ?>

L'exemple ci-dessus va afficher :

    63
    45

### Notes

> Note:

> La fonction peut convertir des nombres qui sont trop larges pour tenir dans un type entier, dans ce cas, ces valeurs sont retournées en tant que nombre décimal.

### Voir aussi

- decoct() - Convertit de décimal en octal
- bindec() - Convertit de binaire en décimal
- hexdec() - Convertit de hexadécimal en décimal
- base_convert() - Convertit un nombre entre des bases arbitraires

# pi

(PHP 4, PHP 5, PHP 7, PHP 8)

pi — Retourne la valeur de pi

### Description

function pi(): float

Retourne une approximation de pi. De plus, il est possible d'utiliser la constante `M_PI`, qui retourne un résultat identique à la fonction pi().

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

La valeur de pi en tant que nombre décimal.

### Exemples

Exemple #1 Exemple avec pi()

    <?php
    echo pi(), PHP_EOL; // 3.1415926535898
    echo M_PI, PHP_EOL; // 3.1415926535898
    ?>

# pow

(PHP 4, PHP 5, PHP 7, PHP 8)

pow — Expression exponentielle

### Description

function pow(mixed `$num`, mixed `$exponent`): int|float|object

Retourne `num` élevé à la puissance `exponent`.

> Note:

> Il est possible d'utiliser l'opérateur ** à la place.

### Liste de paramètres

`num`

  La base à utiliser

`exponent`

  L'exposant

### Valeurs de retour

`num` élevé à la puissance `exponent`. Si les deux arguments sont des entiers non négatifs et que le résultat peut être représenté sous la forme d'un entier, le résultat sera un entier, sinon il sera retourné en tant que nombre décimal.

Les extensions PHP peuvent remplacer le comportement de cette opération et la faire retourner un objet.

### Historique

Version | Description
--- | ---
8.4.0 | Élever `0` à un `exponent` négatif est désormais obsolète.

### Exemples

Exemple #1 Exemple avec pow()

    <?php

    var_dump(pow(2, 8)); // int(256)
    echo pow(-1, 20), PHP_EOL; // 1
    echo pow(0, 0), PHP_EOL; // 1
    echo pow(10, -1), PHP_EOL; // 0.1

    echo pow(-1, 5.5), PHP_EOL; // NAN
    ?>

Exemple #2 Exemples de pow() avec un objet de l’extension GMP

    <?php
    var_dump(pow(new GMP("3"), new GMP("2"))); // object(GMP)
    ?>

### Notes

> Note:

> Cette fonction convertira toutes les entrées en un nombre, y compris pour les valeurs non-scalaires, ce qui peut amener à des résultats imprévisibles.

### Voir aussi

- Opérateur d'exponentiation `**`
- fpow() - Élève un nombre à la puissance d'un autre, selon la norme IEEE 754
- exp() - Calcule l'exponentielle de e
- sqrt() - Racine carrée
- bcpow() - Élève un nombre à une puissance donnée
- gmp_pow() - Puissance

# rad2deg

(PHP 4, PHP 5, PHP 7, PHP 8)

rad2deg — Conversion de radians en degrés

### Description

function rad2deg(float `$num`): float

Convertit `num` (supposé en radians) en degrés.

### Liste de paramètres

`num`

  Une valeur, en radians

### Valeurs de retour

L'équivalent de `num`, en degrés.

### Exemples

Exemple #1 Exemple avec rad2deg()

    <?php

    echo rad2deg(M_PI_4); // 45

    ?>

### Voir aussi

- deg2rad() - Convertit un nombre de degrés en radians

# round

(PHP 4, PHP 5, PHP 7, PHP 8)

round — Arrondit un nombre à virgule flottante

### Description

function round(int|float `$num`, int `$precision` = 0, int|RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): float

Retourne la valeur arrondie de `num` à la précision `precision` (nombre de chiffres après la virgule). Le paramètre `precision` peut être négatif ou `null` : c'est sa valeur par défaut.

### Liste de paramètres

`num`

  La valeur à arrondir.

`precision`

  Le nombre optionnel de décimales à arrondir.

  Si le paramètre `precision` est positif, `num` sera arrondi en utilisant le paramètre `precision` pour définir le nombre significatif de chiffres après le point décimal.

  Si le paramètre `precision` est négatif, `num` sera arrondi en utilisant le paramètre `precision` pour définir le nombre significatif de chiffres avant le point décimal, c.-à-d. le multiple le plus proche de `pow(10, -$precision)`, c.-à-d. pour une `precision` de -1, `num` sera arrondi à 10, pour une `precision` de -2 à 100, etc.

`mode`

  Utiliser RoundingMode ou l'une des constantes suivantes pour spécifier la méthode d'arrondi.

  Constantes | Description
  --- | ---
  `PHP_ROUND_HALF_UP` | Arrondit `num` en s'éloignant de zéro lorsqu'il est à mi-chemin, arrondissant ainsi 1.5 à 2, et -1.5 à -2.
  `PHP_ROUND_HALF_DOWN` | Arrondit `num` en se rapprochant de zéro lorsqu'il est à mi-chemin, arrondissant ainsi 1.5 à 1, et -1.5 à -1.
  `PHP_ROUND_HALF_EVEN` | Arrondit `num` à la valeur paire la plus proche lorsqu'il est à mi-chemin, arrondissant ainsi 1.5 et 2.5 à 2.
  `PHP_ROUND_HALF_ODD` | Arrondit `num` à la valeur impaire la plus proche lorsqu'il est à mi-chemin, arrondissant ainsi 1.5 à 1 et 2.5 à 3.

  Toutefois, noter que certaines méthodes nouvellement ajoutées n'existent que dans RoundingMode.

### Valeurs de retour

La valeur arrondie à la `precision` donnée en tant que nombre décimal.

### Erreurs / Exceptions

La fonction lance une ValueError si `mode` est invalide. Antérieur à PHP 8.4.0, un mode invalide était silencieusement converti en `PHP_ROUND_HALF_UP`.

### Historique

Version | Description
--- | ---
8.4.0 | Quatre nouvelles méthodes d'arrondi ont été ajoutées.
8.4.0 | Lance désormais une ValueError si `mode` est invalide.
8.0.0 | `num` n'accepte plus les objets internes qui supportent les conversions numériques.

### Exemples

Exemple #1 Exemple avec round()

    <?php
    var_dump(round(3.4));
    var_dump(round(3.5));
    var_dump(round(3.6));
    var_dump(round(3.6, 0));
    var_dump(round(5.045, 2));
    var_dump(round(5.055, 2));
    var_dump(round(345, -2));
    var_dump(round(345, -3));
    var_dump(round(678, -2));
    var_dump(round(678, -3));
    ?>

L'exemple ci-dessus va afficher :

    float(3)
    float(4)
    float(4)
    float(4)
    float(5.05)
    float(5.06)
    float(300)
    float(0)
    float(700)
    float(1000)

Exemple #2 Comment `precision` affecte un flottant

    <?php
    $number = 135.79;

    var_dump(round($number, 3));
    var_dump(round($number, 2));
    var_dump(round($number, 1));
    var_dump(round($number, 0));
    var_dump(round($number, -1));
    var_dump(round($number, -2));
    var_dump(round($number, -3));
    ?>

L'exemple ci-dessus va afficher :

    float(135.79)
    float(135.79)
    float(135.8)
    float(136)
    float(140)
    float(100)
    float(0)

Exemple #3 Exemple avec `mode`

    <?php
    echo "Méthode d'arrondi avec 9.5" . PHP_EOL;
    var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));

    echo PHP_EOL;
    echo "Méthode d'arrondi avec 8.5" . PHP_EOL;
    var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));
    ?>

L'exemple ci-dessus va afficher :

    Méthode d'arrondi avec 9.5
    float(10)
    float(9)
    float(10)
    float(9)

    Méthode d'arrondi avec 8.5
    float(9)
    float(8)
    float(8)
    float(9)

Exemple #4 Exemple avec `mode` et `precision`

    <?php
    echo "Utilisation de PHP_ROUND_HALF_UP avec une précision d'une décimale" . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));

    echo PHP_EOL;
    echo "Utilisation de PHP_ROUND_HALF_DOWN avec une précision d'une décimale" . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));

    echo PHP_EOL;
    echo "Utilisation de PHP_ROUND_HALF_EVEN avec une précision d'une décimale" . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));

    echo PHP_EOL;
    echo "Utilisation de PHP_ROUND_HALF_ODD avec une précision d'une décimale" . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
    ?>

L'exemple ci-dessus va afficher :

    Utilisation de PHP_ROUND_HALF_UP avec une précision d'une décimale
    float(1.6)
    float(-1.6)

    Utilisation de PHP_ROUND_HALF_DOWN avec une précision d'une décimale
    float(1.5)
    float(-1.5)

    Utilisation de PHP_ROUND_HALF_EVEN avec une précision d'une décimale
    float(1.6)
    float(-1.6)

    Utilisation de PHP_ROUND_HALF_ODD avec une précision d'une décimale
    float(1.5)
    float(-1.5)

Exemple #5 Exemple d'utilisation de RoundingMode

    <?php
    foreach (RoundingMode::cases() as $mode) {
        foreach ([
            8.5,
            9.5,
            -3.5,
        ] as $number) {
            printf("%-17s: %+.17g -> %+.17g\n", $mode->name, $number, round($number, 0, $mode));
        }
        echo "\n";
    }
    ?>

L'exemple ci-dessus va afficher :

    HalfAwayFromZero : +8.5 -> +9
    HalfAwayFromZero : +9.5 -> +10
    HalfAwayFromZero : -3.5 -> -4

    HalfTowardsZero  : +8.5 -> +8
    HalfTowardsZero  : +9.5 -> +9
    HalfTowardsZero  : -3.5 -> -3

    HalfEven         : +8.5 -> +8
    HalfEven         : +9.5 -> +10
    HalfEven         : -3.5 -> -4

    HalfOdd          : +8.5 -> +9
    HalfOdd          : +9.5 -> +9
    HalfOdd          : -3.5 -> -3

    TowardsZero      : +8.5 -> +8
    TowardsZero      : +9.5 -> +9
    TowardsZero      : -3.5 -> -3

    AwayFromZero     : +8.5 -> +9
    AwayFromZero     : +9.5 -> +10
    AwayFromZero     : -3.5 -> -4

    NegativeInfinity : +8.5 -> +8
    NegativeInfinity : +9.5 -> +9
    NegativeInfinity : -3.5 -> -4

    PositiveInfinity : +8.5 -> +9
    PositiveInfinity : +9.5 -> +10
    PositiveInfinity : -3.5 -> -3

### Voir aussi

- ceil() - Arrondit au nombre supérieur
- floor() - Arrondit à l'entier inférieur
- number_format() - Formate un nombre pour l'affichage

# sin

(PHP 4, PHP 5, PHP 7, PHP 8)

sin — Sinus

### Description

function sin(float `$num`): float

sin() retourne le sinus de `num` (`num` en radians).

### Liste de paramètres

`num`

  Une valeur, en radians

### Valeurs de retour

Le sinus de `num`.

### Exemples

Exemple #1 Exemple avec sin()

    <?php
    // La précision dépend de la directive precision
    echo sin(deg2rad(60)), PHP_EOL;  //  0.866025403 ...
    echo sin(60), PHP_EOL;           // -0.304810621 ...
    ?>

### Voir aussi

- asin() - Arc sinus
- sinh() - Sinus hyperbolique
- cos() - Cosinus
- tan() - Tangente
- deg2rad() - Convertit un nombre de degrés en radians

# sinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sinh — Sinus hyperbolique

### Description

function sinh(float `$num`): float

Retourne le sinus hyperbolique de `num`, défini comme `(exp($num) - exp(-$num))/2`.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

Le sinus hyperbolique de `num`.

### Voir aussi

- sin() - Sinus
- asinh() - Arc sinus hyperbolique
- cosh() - Cosinus hyperbolique
- tanh() - Tangente hyperbolique

# sqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

sqrt — Racine carrée

### Description

function sqrt(float `$num`): float

Retourne la racine carrée de `num`.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

La racine carrée de `num` ou la valeur spéciale `NAN` pour les nombres négatifs.

### Exemples

Exemple #1 Exemple avec sqrt()

    <?php
    // La précision dépend de la directive precision
    echo sqrt(9), PHP_EOL; // 3
    echo sqrt(10), PHP_EOL; // 3.16227766 ...
    ?>

### Voir aussi

- pow() - Expression exponentielle
- `M_SQRTPI` - `sqrt(pi)`
- `M_2_SQRTPI` - `2/sqrt(pi)`
- `M_SQRT2` - `sqrt(2)`
- `M_SQRT3` - `sqrt(3)`
- `M_SQRT1_2` - `1/sqrt(2)`

# tan

(PHP 4, PHP 5, PHP 7, PHP 8)

tan — Tangente

### Description

function tan(float `$num`): float

Retourne la tangente de `num` (`num` en radians).

### Liste de paramètres

`num`

  L'argument à traiter, en radians

### Valeurs de retour

La tangente de `num`

### Exemples

Exemple #1 Exemple avec tan()

    <?php

    echo tan(M_PI_4); // 1

    ?>

### Voir aussi

- atan() - Arc tangente
- atan2() - Arc tangente de deux variables
- sin() - Sinus
- cos() - Cosinus
- tanh() - Tangente hyperbolique
- deg2rad() - Convertit un nombre de degrés en radians

# tanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

tanh — Tangente hyperbolique

### Description

function tanh(float `$num`): float

Retourne la tangente hyperbolique de `num`, définie comme `sinh($num)/cosh($num)`.

### Liste de paramètres

`num`

  L'argument à traiter

### Valeurs de retour

La tangente hyperbolique de `num`.

### Voir aussi

- tan() - Tangente
- atanh() - Arc tangente hyperbolique
- sinh() - Sinus hyperbolique
- cosh() - Cosinus hyperbolique

## Sommaire

- abs — Valeur absolue
- acos — Arc cosinus
- acosh — Arc cosinus hyperbolique
- asin — Arc sinus
- asinh — Arc sinus hyperbolique
- atan — Arc tangente
- atan2 — Arc tangente de deux variables
- atanh — Arc tangente hyperbolique
- base_convert — Convertit un nombre entre des bases arbitraires
- bindec — Convertit de binaire en décimal
- ceil — Arrondit au nombre supérieur
- cos — Cosinus
- cosh — Cosinus hyperbolique
- decbin — Convertit de décimal en binaire
- dechex — Convertit de décimal en hexadécimal
- decoct — Convertit de décimal en octal
- deg2rad — Convertit un nombre de degrés en radians
- exp — Calcule l'exponentielle de e
- expm1 — Retourne exp($num) - 1, calculé de manière précise même lorsque la valeur du nombre est proche de zéro
- fdiv — Divise deux nombres, selon la norme IEEE 754
- floor — Arrondit à l'entier inférieur
- fmod — Retourne le reste de la division
- fpow — Élève un nombre à la puissance d'un autre, selon la norme IEEE 754
- hexdec — Convertit de hexadécimal en décimal
- hypot — Calcule la longueur de l'hypoténuse d'un triangle à angle droit
- intdiv — Division d'Entier
- is_finite — Vérifie si un nombre flottant est fini
- is_infinite — Vérifie si un nombre flottant est infini
- is_nan — Vérifie si un nombre flottant est NAN
- log — Logarithme naturel (népérien)
- log10 — Logarithme en base 10
- log1p — Calcule précisément log(1 + nombre)
- max — La plus grande valeur
- min — La plus petite valeur
- octdec — Conversion d'octal en décimal
- pi — Retourne la valeur de pi
- pow — Expression exponentielle
- rad2deg — Conversion de radians en degrés
- round — Arrondit un nombre à virgule flottante
- sin — Sinus
- sinh — Sinus hyperbolique
- sqrt — Racine carrée
- tan — Tangente
- tanh — Tangente hyperbolique

- Constantes pré-définies
- RoundingMode — L'énumération RoundingMode
- Fonctions Math
  - abs — Valeur absolue
  - acos — Arc cosinus
  - acosh — Arc cosinus hyperbolique
  - asin — Arc sinus
  - asinh — Arc sinus hyperbolique
  - atan — Arc tangente
  - atan2 — Arc tangente de deux variables
  - atanh — Arc tangente hyperbolique
  - base_convert — Convertit un nombre entre des bases arbitraires
  - bindec — Convertit de binaire en décimal
  - ceil — Arrondit au nombre supérieur
  - cos — Cosinus
  - cosh — Cosinus hyperbolique
  - decbin — Convertit de décimal en binaire
  - dechex — Convertit de décimal en hexadécimal
  - decoct — Convertit de décimal en octal
  - deg2rad — Convertit un nombre de degrés en radians
  - exp — Calcule l'exponentielle de e
  - expm1 — Retourne exp($num) - 1, calculé de manière précise même lorsque la valeur du nombre est proche de zéro
  - fdiv — Divise deux nombres, selon la norme IEEE 754
  - floor — Arrondit à l'entier inférieur
  - fmod — Retourne le reste de la division
  - fpow — Élève un nombre à la puissance d'un autre, selon la norme IEEE 754
  - hexdec — Convertit de hexadécimal en décimal
  - hypot — Calcule la longueur de l'hypoténuse d'un triangle à angle droit
  - intdiv — Division d'Entier
  - is_finite — Vérifie si un nombre flottant est fini
  - is_infinite — Vérifie si un nombre flottant est infini
  - is_nan — Vérifie si un nombre flottant est NAN
  - log — Logarithme naturel (népérien)
  - log10 — Logarithme en base 10
  - log1p — Calcule précisément log(1 + nombre)
  - max — La plus grande valeur
  - min — La plus petite valeur
  - octdec — Conversion d'octal en décimal
  - pi — Retourne la valeur de pi
  - pow — Expression exponentielle
  - rad2deg — Conversion de radians en degrés
  - round — Arrondit un nombre à virgule flottante
  - sin — Sinus
  - sinh — Sinus hyperbolique
  - sqrt — Racine carrée
  - tan — Tangente
  - tanh — Tangente hyperbolique

# Statistics

# Introduction

Avertissement

Cette extension est non maintenue.

Ceci est l'extension statistique. Elle contient quelques dizaines de fonctions utiles pour les calculs statistiques. C'est une enveloppe autour de 2 bibliothèques scientifiques à savoir DCDFLIB (Library of C routines for Cumulative Distributions Functions, Inverses, and Other parameters) par B. Brown & J. Lavato et RANDLIB par Barry Brown, James Lavato & Kathy Russell. Inclut les fonctions CD et PD.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation

## Pré-requis

Aucune bibliothèque externe n'est nécessaire. L'extension est livrée avec les bibliothèques utilisées.

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Cette extension est considérée comme non-maintenue et morte. Cependant, le code source est toujours disponible depuis le SVN de PECL ici : » https://pecl.php.net/package/stats.

Les binaires Windows (les fichiers DLL) pour cette extension PECL sont disponibles sur le site web PECL.

# Fonctions de Statistic

# stats_absolute_deviation

(PECL stats >= 1.0.0)

stats_absolute_deviation — Renvoie l'écart absolu d'un tableau de valeurs

### Description

function stats_absolute_deviation(array `$a`): float

Renvoie l'écart absolu des valeurs dans `a`.

### Liste de paramètres

`a`

  Le tableau d'entrée

### Valeurs de retour

Renvoie l'écart absolu des valeurs dans `a`, ou `false` si `a` est vide ou n'est pas un tableau.

# stats_cdf_beta

(PECL stats >= 1.0.0)

stats_cdf_beta — Calcule un paramètre de la distribution beta en fonction des autres valeurs

### Description

function stats_cdf_beta(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution beta. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, alpha, et beta désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et les paramètres de forme de la distribution beta, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | alpha | beta
2 | x | CDF | alpha | beta
3 | alpha | x | CDF | beta
4 | beta | x | CDF | alpha

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, alpha, ou beta, déterminé par `which`.

# stats_cdf_binomial

(PECL stats >= 1.0.0)

stats_cdf_binomial — Calcule un paramètre de la distribution binomiale en fonction des autres valeurs

### Description

function stats_cdf_binomial(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution binomiale. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, n, et p désignent la fonction de distribution cumulative, le nombre de succès, le nombre d'essais, et le taux de succès pour chaque essai, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | n | p
2 | x | CDF | n | p
3 | n | x | CDF | p
4 | p | x | CDF | n

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, n, ou p, déterminé par `which`.

# stats_cdf_cauchy

(PECL stats >= 1.0.0)

stats_cdf_cauchy — Calcule un paramètre de la distribution de Cauchy en fonction des autres valeurs

### Description

function stats_cdf_cauchy(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution de Cauchy. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, x0, et gamma désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, le paramètre de localisation et le paramètre d'échelle de la distribution de Cauchy, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | x0 | gamma
2 | x | CDF | x0 | gamma
3 | x0 | x | CDF | gamma
4 | gamma | x | CDF | x0

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, x0, ou gamma, déterminé par `which`.

# stats_cdf_chisquare

(PECL stats >= 1.0.0)

stats_cdf_chisquare — Calcule un paramètre de la distribution du chi-deux en fonction des autres valeurs

### Description

function stats_cdf_chisquare(float `$par1`, float `$par2`, int `$which`): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution du chi-deux. Le type de la valeur de retour et les paramètres (`par1` et `par2`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, et k désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et le degré de liberté de la distribution du chi-deux, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | k
2 | x | CDF | k
3 | k | x | CDF

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, ou k, déterminé par `which`.

# stats_cdf_exponential

(PECL stats >= 1.0.0)

stats_cdf_exponential — Calcule un paramètre de la distribution exponentielle en fonction des autres valeurs

### Description

function stats_cdf_exponential(float `$par1`, float `$par2`, int `$which`): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution exponentielle. Le type de la valeur de retour et les paramètres (`par1` et `par2`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, et lambda désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et le paramètre de taux de la distribution exponentielle, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, ou lambda, déterminé par `which`.

# stats_cdf_f

(PECL stats >= 1.0.0)

stats_cdf_f — Calcule un paramètre de la distribution F en fonction des autres valeurs

### Description

function stats_cdf_f(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution F. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, d1, et d2 désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et les degrés de liberté de la distribution F, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | d1 | d2
2 | x | CDF | d1 | d2
3 | d1 | x | CDF | d2
4 | d2 | x | CDF | d1

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, d1, ou d2, déterminé par `which`.

# stats_cdf_gamma

(PECL stats >= 1.0.0)

stats_cdf_gamma — Calcule un paramètre de la distribution gamma en fonction des autres valeurs

### Description

function stats_cdf_gamma(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution gamma. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, k, et theta désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et les paramètres de forme et d'échelle de la distribution gamma, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | k | theta
2 | x | CDF | k | theta
3 | k | x | CDF | theta
4 | theta | x | CDF | k

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, k, ou theta, déterminé par `which`.

# stats_cdf_laplace

(PECL stats >= 1.0.0)

stats_cdf_laplace — Calcule un paramètre de la distribution de Laplace en fonction des autres valeurs

### Description

function stats_cdf_laplace(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution de Laplace. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, mu, et b désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et les paramètres de localisation et d'échelle de la distribution de Laplace, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | mu | b
2 | x | CDF | mu | b
3 | mu | x | CDF | b
4 | b | x | CDF | mu

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, mu, ou b, déterminé par `which`.

# stats_cdf_logistic

(PECL stats >= 1.0.0)

stats_cdf_logistic — Calcule un paramètre de la distribution logistique en fonction des autres valeurs

### Description

function stats_cdf_logistic(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution logistique. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, mu, et s désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et les paramètres de localisation et d'échelle de la distribution logistique, respectivement.

Valeur de retour et paramètres
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | mu | s
2 | x | CDF | mu | s
3 | mu | x | CDF | s
4 | s | x | CDF | mu

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, mu, ou s, déterminé par `which`.

# stats_cdf_negative_binomial

(PECL stats >= 1.0.0)

stats_cdf_negative_binomial — Calcule un paramètre de la distribution binomiale négative en fonction des autres valeurs

### Description

function stats_cdf_negative_binomial(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution binomiale négative. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, r, et p désignent la fonction de distribution cumulative, le nombre d'échecs, le nombre de succès, et le taux de succès pour chaque essai, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | r | p
2 | x | CDF | r | p
3 | r | x | CDF | p
4 | p | x | CDF | r

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, r, ou p, déterminé par `which`.

# stats_cdf_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_cdf_noncentral_chisquare — Calcule un paramètre de la distribution du chi-deux non-centrale en fonction des autres valeurs

### Description

function stats_cdf_noncentral_chisquare(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution du chi-deux non-centrale. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, k, et lambda désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, le degré de liberté et le paramètre de non-centralité de la distribution du chi-deux non-centrale, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, k, ou lambda, déterminé par `which`.

# stats_cdf_noncentral_f

(PECL stats >= 1.0.0)

stats_cdf_noncentral_f — Calcule un paramètre de la distribution F non-centrale en fonction des autres valeurs

### Description

function stats_cdf_noncentral_f(
float `$par1`,
float `$par2`,
float `$par3`,
float `$par4`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution F non-centrale. Le type de la valeur de retour et les paramètres (`par1`, `par2`, `par3`, et `par4`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, nu1, nu2, et lambda désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, les degrés de liberté et le paramètre de non-centralité de la distribution F non-centrale, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3` | `par4`
--- | --- | --- | --- | --- | ---
1 | CDF | x | nu1 | nu2 | lambda
2 | x | CDF | nu1 | nu2 | lambda
3 | nu1 | x | CDF | nu2 | lambda
4 | nu2 | x | CDF | nu1 | lambda
5 | lambda | x | CDF | nu1 | nu2

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`par4`

  Le quatrième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, nu1, nu2, ou lambda, déterminé par `which`.

# stats_cdf_noncentral_t

(PECL stats >= 1.0.0)

stats_cdf_noncentral_t — Calcule un paramètre de la distribution t non-centrale en fonction des autres valeurs

### Description

function stats_cdf_noncentral_t(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution t non-centrale. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, nu, et mu désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, les degrés de liberté et le paramètre de non-centralité de la distribution, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | nu | mu
2 | x | CDF | nu | mu
3 | nu | x | CDF | mu
4 | mu | x | CDF | nu

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, nu, ou mu, déterminé par `which`.

# stats_cdf_normal

(PECL stats >= 1.0.0)

stats_cdf_normal — Calcule un paramètre de la distribution normale en fonction des autres valeurs

### Description

function stats_cdf_normal(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution normale. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, mu, et sigma désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, la moyenne et l'écart-type de la distribution normale, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | mu | sigma
2 | x | CDF | mu | sigma
3 | mu | x | CDF | sigma
4 | sigma | x | CDF | mu

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, mu, ou sigma, déterminé par `which`.

# stats_cdf_poisson

(PECL stats >= 1.0.0)

stats_cdf_poisson — Calcule un paramètre de la distribution de Poisson en fonction des autres valeurs

### Description

function stats_cdf_poisson(float `$par1`, float `$par2`, int `$which`): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution de Poisson. Le type de la valeur de retour et les paramètres (`par1` et `par2`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, et lambda désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et le paramètre de la distribution de Poisson, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, ou lambda, déterminé par `which`.

# stats_cdf_t

(PECL stats >= 1.0.0)

stats_cdf_t — Calcule un paramètre de la distribution t en fonction des autres valeurs

### Description

function stats_cdf_t(float `$par1`, float `$par2`, int `$which`): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution t. Le type de la valeur de retour et les paramètres (`par1` et `par2`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, et nu désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et les degrés de liberté de la distribution t, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | nu
2 | x | CDF | nu
3 | nu | x | CDF

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, ou nu, déterminé par `which`.

# stats_cdf_uniform

(PECL stats >= 1.0.0)

stats_cdf_uniform — Calcule un paramètre de la distribution uniforme en fonction des autres valeurs

### Description

function stats_cdf_uniform(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution uniforme. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, a, et b désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et les bornes inférieure et supérieure de la distribution uniforme, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | a | b
2 | x | CDF | a | b
3 | a | x | CDF | b
4 | b | x | CDF | a

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, a, ou b, déterminé par `which`.

# stats_cdf_weibull

(PECL stats >= 1.0.0)

stats_cdf_weibull — Calcule un paramètre de la distribution de Weibull en fonction des autres valeurs

### Description

function stats_cdf_weibull(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Renvoie la fonction de distribution cumulative, son inverse, ou un des paramètres, de la distribution de Weibull. Le type de la valeur de retour et les paramètres (`par1`, `par2`, et `par3`) sont déterminés par `which`.

La table suivante liste la valeur de retour et les paramètres par `which`. CDF, x, k, et lambda désignent la fonction de distribution cumulative, la valeur de la variable aléatoire, et les paramètres de forme et d'échelle de la distribution de Weibull, respectivement.

Valeur de retour et paramètres
`which` | Valeur de retour | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

### Liste de paramètres

`par1`

  Le premier paramètre

`par2`

  Le second paramètre

`par3`

  Le troisième paramètre

`which`

  Le drapeau pour déterminer ce qui doit être calculé

### Valeurs de retour

Renvoie CDF, x, k, ou lambda, déterminé par `which`.

# stats_covariance

(PECL stats >= 1.0.0)

stats_covariance — Calcule la covariance de deux ensembles de données

### Description

function stats_covariance(array `$a`, array `$b`): float

Renvoie la covariance de `a` et `b`.

### Liste de paramètres

`a`

  Le premier tableau

`b`

  Le second tableau

### Valeurs de retour

Renvoie la covariance de `a` et `b`, ou `false` en cas d'échec.

# stats_dens_beta

(PECL stats >= 1.0.0)

stats_dens_beta — La fonction de densité de probabilité de la distribution bêta

### Description

function stats_dens_beta(float `$x`, float `$a`, float `$b`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution bêta dont les paramètres de forme sont `a` et `b`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`a`

  Le paramètre de forme de la distribution

`b`

  Le paramètre de forme de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_cauchy

(PECL stats >= 1.0.0)

stats_dens_cauchy — La fonction de densité de probabilité de la distribution de Cauchy

### Description

function stats_dens_cauchy(float `$x`, float `$ave`, float `$stdev`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution de Cauchy dont les paramètres de location et d'échelle sont `ave` et `stdev`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`ave`

  Le paramètre de localisation de la distribution

`stdev`

  Le paramètre d'échelle de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_chisquare

(PECL stats >= 1.0.0)

stats_dens_chisquare — La fonction de densité de probabilité de la distribution du chi-carré

### Description

function stats_dens_chisquare(float `$x`, float `$dfr`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution du chi-carré dont le degré de liberté est `dfr`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`dfr`

  Le degré de liberté de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_exponential

(PECL stats >= 1.0.0)

stats_dens_exponential — La fonction de densité de probabilité de la distribution exponentielle

### Description

function stats_dens_exponential(float `$x`, float `$scale`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution exponentielle dont l'échelle est `scale`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`scale`

  L'échelle de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_f

(PECL stats >= 1.0.0)

stats_dens_f — La fonction de densité de probabilité de la distribution F

### Description

function stats_dens_f(float `$x`, float `$dfr1`, float `$dfr2`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution F dont les degrés de liberté sont `dfr1` et `dfr2`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`dfr1`

  Le degré de liberté de la distribution

`dfr2`

  Le degré de liberté de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_gamma

(PECL stats >= 1.0.0)

stats_dens_gamma — La fonction de densité de probabilité de la distribution gamma

### Description

function stats_dens_gamma(float `$x`, float `$shape`, float `$scale`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution gamma dont le paramètre de forme est `shape` et le paramètre d'échelle est `scale`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`shape`

  Le paramètre de forme de la distribution

`scale`

  Le paramètre d'échelle de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_laplace

(PECL stats >= 1.0.0)

stats_dens_laplace — La fonction de densité de probabilité de la distribution de Laplace

### Description

function stats_dens_laplace(float `$x`, float `$ave`, float `$stdev`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution de Laplace dont le paramètre de localisation est `ave` et le paramètre d'échelle est `stdev`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`ave`

  Le paramètre de localisation de la distribution

`stdev`

  Le paramètre d'échelle de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_logistic

(PECL stats >= 1.0.0)

stats_dens_logistic — La fonction de densité de probabilité de la distribution logistique

### Description

function stats_dens_logistic(float `$x`, float `$ave`, float `$stdev`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution logistique dont le paramètre de localisation est `ave` et le paramètre d'échelle est `stdev`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`ave`

  Le paramètre de localisation de la distribution

`stdev`

  Le paramètre d'échelle de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_normal

(PECL stats >= 1.0.0)

stats_dens_normal — La fonction de densité de probabilité de la distribution normale

### Description

function stats_dens_normal(float `$x`, float `$ave`, float `$stdev`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution normale dont la moyenne est `ave` et l'écart-type est `stdev`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`ave`

  La moyenne de la distribution

`stdev`

  La déviation standard de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_pmf_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_binomial — La fonction de masse de probabilité de la distribution binomiale

### Description

function stats_dens_pmf_binomial(float `$x`, float `$n`, float `$pi`): float

Renvoie la masse de probabilité à `x`, où la variable aléatoire suit la distribution binomiale dont le nombre d'essais est `n` et le taux de succès est `pi`.

### Liste de paramètres

`x`

  La valeur à laquelle la masse de probabilité est calculée

`n`

  Le nombre d'essais de la distribution

`pi`

  Le taux de succès de la distribution

### Valeurs de retour

La masse de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_pmf_hypergeometric

(PECL stats >= 1.0.0)

stats_dens_pmf_hypergeometric — La fonction de masse de probabilité de la distribution hypergéométrique

### Description

function stats_dens_pmf_hypergeometric(
float `$n1`,
float `$n2`,
float `$N1`,
float `$N2`
): float

Renvoie la masse de probabilité à `n1`, où la variable aléatoire suit la distribution hypergéométrique dont le nombre d'échecs est `n2`, le nombre d'échantillons de succès est `N1`, et le nombre d'échantillons d'échecs est `N2`.

### Liste de paramètres

`n1`

  Le nombre de succès, à partir duquel la masse de probabilité est calculée

`n2`

  Le nombre d'échecs de la distribution

`N1`

  Le nombre d'échantillons de succès de la distribution

`N2`

  Le nombre d'échantillons d'échecs de la distribution

### Valeurs de retour

La masse de probabilité à `n1` ou `false` en cas d'échec.

# stats_dens_pmf_negative_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_negative_binomial — La fonction de masse de probabilité de la distribution binomiale négative

### Description

function stats_dens_pmf_negative_binomial(float `$x`, float `$n`, float `$pi`): float

Renvoie la masse de probabilité à `x`, où la variable aléatoire suit la distribution binomiale négative dont le nombre de succès est `n` et le taux de succès est `pi`.

### Liste de paramètres

`x`

  La valeur à laquelle la masse de probabilité est calculée

`n`

  Le nombre de succès de la distribution

`pi`

  le taux de succès de la distribution

### Valeurs de retour

La masse de probabilité à `x` ou `false` en cas d'échec.

# stats_dens_pmf_poisson

(PECL stats >= 1.0.0)

stats_dens_pmf_poisson — La fonction de masse de probabilité de la distribution de Poisson

### Description

function stats_dens_pmf_poisson(float `$x`, float `$lb`): float

Renvoie la masse de probabilité à `x`, où la variable aléatoire suit la distribution de Poisson dont le paramètre est `lb`.

### Liste de paramètres

`x`

  La valeur à laquelle la masse de probabilité est calculée

`lb`

  Le paramètre de la distribution de Poisson

### Valeurs de retour

La masse de probabilité à `x` ou `false` pour l'échec.

# stats_dens_t

(PECL stats >= 1.0.0)

stats_dens_t — La fonction de densité de probabilité de la distribution t

### Description

function stats_dens_t(float `$x`, float `$dfr`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution t dont le degré de liberté est `dfr`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`dfr`

  Le degré de liberté de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` pour l'échec.

# stats_dens_uniform

(PECL stats >= 1.0.0)

stats_dens_uniform — La fonction de densité de probabilité de la distribution uniforme

### Description

function stats_dens_uniform(float `$x`, float `$a`, float `$b`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution uniforme dont la borne inférieure est `a` et la borne supérieure est `b`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`a`

  Le seuil inférieur de la distribution

`b`

  Le seuil supérieur de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` pour l'échec.

# stats_dens_weibull

(PECL stats >= 1.0.0)

stats_dens_weibull — La fonction de densité de probabilité de la distribution de Weibull

### Description

function stats_dens_weibull(float `$x`, float `$a`, float `$b`): float

Renvoie la densité de probabilité à `x`, où la variable aléatoire suit la distribution de Weibull dont le paramètre de forme est `a` et le paramètre d'échelle est `b`.

### Liste de paramètres

`x`

  La valeur à laquelle la densité de probabilité est calculée

`a`

  Le paramètre de forme de la distribution

`b`

  Le paramètre d'échelle de la distribution

### Valeurs de retour

La densité de probabilité à `x` ou `false` pour l'échec.

# stats_harmonic_mean

(PECL stats >= 1.0.0)

stats_harmonic_mean — Renvoie la moyenne harmonique d'un tableau de valeurs

### Description

function stats_harmonic_mean(array `$a`): number

Renvoie la moyenne harmonique des valeurs de `a`.

### Liste de paramètres

`a`

  Le tableau d'entrée

### Valeurs de retour

Renvoie la moyenne harmonique des valeurs de `a`, ou `false` si `a` est vide ou n'est pas un tableau.

# stats_kurtosis

(PECL stats >= 1.0.0)

stats_kurtosis — Calcule le kurtosis des données dans le tableau

### Description

function stats_kurtosis(array `$a`): float

Renvoie le kurtosis des valeurs dans `a`.

### Liste de paramètres

`a`

  Le tableau d'entrée

### Valeurs de retour

Renvoie le kurtosis des valeurs dans `a`, ou `false` si `a` est vide ou n'est pas un tableau.

# stats_rand_gen_beta

(PECL stats >= 1.0.0)

stats_rand_gen_beta — Génère une déviation aléatoire de la distribution beta

### Description

function stats_rand_gen_beta(float `$a`, float `$b`): float

Renvoie une déviation aléatoire de la distribution beta avec les paramètres A et B. La densité de la beta est x^(a-1) * (1-x)^(b-1) / B(a, b) pour 0 < x <. Méthode R. C. H. Cheng.

### Liste de paramètres

`a`

  Le paramètre de forme de la distribution beta

`b`

  Le paramètre de forme de la distribution beta

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_chisquare — Génère une déviation aléatoire de la distribution chi-carré

### Description

function stats_rand_gen_chisquare(float `$df`): float

Renvoie une déviation aléatoire de la distribution chi-carré où les degrés de liberté sont `df`.

### Liste de paramètres

`df`

  Les degrés de liberté

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_exponential

(PECL stats >= 1.0.0)

stats_rand_gen_exponential — Génère une déviation aléatoire de la distribution exponentielle

### Description

function stats_rand_gen_exponential(float `$av`): float

Renvoie une déviation aléatoire de la distribution exponentielle dont l'échelle est `av`.

### Liste de paramètres

`av`

  Le paramètre d'échelle

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_f

(PECL stats >= 1.0.0)

stats_rand_gen_f — Génère une déviation aléatoire de la distribution F

### Description

function stats_rand_gen_f(float `$dfn`, float `$dfd`): float

Génère une déviation aléatoire de la distribution F (ratio de variance) avec "dfn" degrés de liberté dans le numérateur et "dfd" degrés de liberté dans le dénominateur. Méthode : génère directement le ratio de variables chi-carré.

### Liste de paramètres

`dfn`

  Le degré de liberté dans le numérateur

`dfd`

  Le degré de liberté dans le dénominateur

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_funiform

(PECL stats >= 1.0.0)

stats_rand_gen_funiform — Génère un flottant uniforme entre low (exclusif) et high (exclusif)

### Description

function stats_rand_gen_funiform(float `$low`, float `$high`): float

Renvoie une déviation aléatoire de la distribution uniforme entre `low` et `high`.

### Liste de paramètres

`low`

  Le seuil inférieur (exclusif)

`high`

  Le seuil supérieur (exclusif)

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_gamma

(PECL stats >= 1.0.0)

stats_rand_gen_gamma — Génère une déviation aléatoire de la distribution gamma

### Description

function stats_rand_gen_gamma(float `$a`, float `$r`): float

Génère une déviation aléatoire de la distribution gamma dont la densité est (A**R)/Gamma(R) * X**(R-1) * Exp(-A*X).

### Liste de paramètres

`a`

  Le paramètre de localisation de la distribution gamma (`a` > 0).

`r`

  Le paramètre de forme de la distribution gamma (`r` > 0).

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_ibinomial

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial — Génère une déviation aléatoire de la distribution binomiale

### Description

function stats_rand_gen_ibinomial(int `$n`, float `$pp`): int

Renvoie une déviation aléatoire de la distribution binomiale où le nombre d'essai est `n` et la probabilité d'évènement dans chaque essai est `pp`.

### Liste de paramètres

`n`

  Le nombre d'essais

`pp`

  La probabilité d'un événement dans chaque essai

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_ibinomial_negative

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial_negative — Génère une déviation aléatoire de la distribution binomiale négative

### Description

function stats_rand_gen_ibinomial_negative(int `$n`, float `$p`): int

Renvoie une déviation aléatoire de la distribution binomiale négative où le nombre de succès est `n` et le taux de succès est `p`.

### Liste de paramètres

`n`

  Le nombre de succès.

`p`

  Le taux de succès.

### Valeurs de retour

Une déviation aléatoire, qui est le nombre d'échecs.

# stats_rand_gen_int

(PECL stats >= 1.0.0)

stats_rand_gen_int — Génère un entier aléatoire entre 1 et 2147483562

### Description

function stats_rand_gen_int(): int

Renvoie un entier aléatoire entre 1 et 2147483562

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un entier aléatoire

# stats_rand_gen_ipoisson

(PECL stats >= 1.0.0)

stats_rand_gen_ipoisson — Génère une seule déviation aléatoire de la distribution de Poisson

### Description

function stats_rand_gen_ipoisson(float `$mu`): int

Renvoie une déviation aléatoire de la distribution de Poisson avec le paramètre `mu`.

### Liste de paramètres

`mu`

  Le paramètre de la distribution de Poisson

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_iuniform

(PECL stats >= 1.0.0)

stats_rand_gen_iuniform — Renvoie un entier aléatoire uniformément distribué entre LOW (inclus) et HIGH (inclus)

### Description

function stats_rand_gen_iuniform(int `$low`, int `$high`): int

Renvoie un entier aléatoire uniformément distribué entre `low` (inclus) et `high` (inclus).

### Liste de paramètres

`low`

  Le seuil inférieur

`high`

  Le seuil supérieur

### Valeurs de retour

Un entier aléatoire

# stats_rand_gen_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_chisquare — Génère une déviation aléatoire de la distribution chi-carré non-centrale

### Description

function stats_rand_gen_noncentral_chisquare(float `$df`, float `$xnonc`): float

Renvoie une déviation aléatoire de la distribution chi-carré non-centrale avec les degrés de liberté, `df`, et le paramètre de non-centralité, `xnonc`.

### Liste de paramètres

`df`

  Les degrés de liberté

`xnonc`

  Le paramètre de non-centralité

### Valeurs de retour

Une valeur aléatoire

# stats_rand_gen_noncentral_f

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_f — Génère une déviation aléatoire de la distribution F non-centrale

### Description

function stats_rand_gen_noncentral_f(float `$dfn`, float `$dfd`, float `$xnonc`): float

Renvoie une déviation aléatoire de la distribution F non-centrale avec les degrés de liberté, `dfn` (numérateur) et `dfd` (dénominateur), et le paramètre de non-centralité, `xnonc`.

### Liste de paramètres

`dfn`

  Les degrés de liberté du numérateur

`dfd`

  Les degrés de liberté du dénominateur

`xnonc`

  Le paramètre de non-centralité

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_noncentral_t

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_t — Génère une seule déviation aléatoire de la distribution t non-centrale

### Description

function stats_rand_gen_noncentral_t(float `$df`, float `$xnonc`): float

Renvoie une déviation aléatoire de la distribution t non-centrale avec les degrés de liberté, `df`, et le paramètre de non-centralité, `xnonc`.

### Liste de paramètres

`df`

  Les degrés de liberté

`xnonc`

  Le paramètre de non-centralité

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_normal

(PECL stats >= 1.0.0)

stats_rand_gen_normal — Génère une déviation aléatoire de la distribution normale

### Description

function stats_rand_gen_normal(float `$av`, float `$sd`): float

Renvoie une déviation aléatoire de la distribution normale avec la moyenne, `av`, et l'écart-type, `sd`.

### Liste de paramètres

`av`

  La moyenne de la distribution normale

`sd`

  L'écart-type de la distribution normale

### Valeurs de retour

Une déviation aléatoire

# stats_rand_gen_t

(PECL stats >= 1.0.0)

stats_rand_gen_t — Génère une seule déviation aléatoire de la distribution t

### Description

function stats_rand_gen_t(float `$df`): float

Renvoie une déviation aléatoire de la distribution t avec les degrés de liberté, `df`.

### Liste de paramètres

`df`

  Les degrés de liberté

### Valeurs de retour

Une déviation aléatoire

# stats_rand_get_seeds

(PECL stats >= 1.0.0)

stats_rand_get_seeds — Renvoie les valeurs de la graine du générateur de nombres aléatoires

### Description

function stats_rand_get_seeds(): array

Renvoie les graines actuelles du générateur de nombres aléatoires

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Renvoie un tableau de deux entiers.

# stats_rand_phrase_to_seeds

(PECL stats >= 1.0.0)

stats_rand_phrase_to_seeds — Génère deux graines pour le générateur de nombres aléatoires RGN

### Description

function stats_rand_phrase_to_seeds(string `$phrase`): array

Génère deux graines pour le générateur de nombres aléatoires à partir d'une `phrase`.

### Liste de paramètres

`phrase`

  La phrase d'entrée

### Valeurs de retour

Renvoie un tableau de deux entiers.

# stats_rand_ranf

(PECL stats >= 1.0.0)

stats_rand_ranf — Génère un nombre flottant aléatoire entre 0 et 1

### Description

function stats_rand_ranf(): float

Renvoie un nombre flottant aléatoire issu d'une distribution uniforme entre 0 (exclus) et 1 (exclus).

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Un nombre flottant aléatoire

# stats_rand_setall

(PECL stats >= 1.0.0)

stats_rand_setall — Définit les valeurs de la graine pour le générateur aléatoire

### Description

function stats_rand_setall(int `$iseed1`, int `$iseed2`): void

Définit `iseed1` et `iseed2` comme valeurs de la graine pour le générateur aléatoire utilisé dans les fonctions statistiques.

### Liste de paramètres

`iseed1`

  La valeur utilisée comme graine aléatoire

`iseed2`

  La valeur utilisée comme graine aléatoire

### Valeurs de retour

Aucune valeur n'est retournée.

# stats_skew

(PECL stats >= 1.0.0)

stats_skew — Calcule l'asymétrie des données dans un tableau

### Description

function stats_skew(array `$a`): float

Renvoie l'asymétrie des valeurs dans `a`.

### Liste de paramètres

`a`

  Le tableau d'entrées

### Valeurs de retour

Renvoie l'asymétrie des valeurs dans `a`, ou `false` si `a` est vide ou n'est pas un tableau.

# stats_standard_deviation

(PECL stats >= 1.0.0)

stats_standard_deviation — Renvoie la déviation standard

### Description

function stats_standard_deviation(array `$a`, bool `$sample` = `false`): float

Renvoie la déviation standard des valeurs dans `a`.

### Liste de paramètres

`a`

  Le tableau de données pour lequel calculer la déviation standard. Il est à noter que toutes les valeurs du tableau seront converties en float.

`sample`

  Indique si `a` représente un échantillon de la population; par défaut à `false`.

### Valeurs de retour

Renvoie la déviation standard en cas de succès; `false` en cas d'échec.

### Erreurs / Exceptions

Lance une `E_WARNING` lorsqu'il y a moins de 2 valeurs dans `a`.

# stats_stat_binomial_coef

(PECL stats >= 1.0.0)

stats_stat_binomial_coef — Renvoie un coefficient binomial

### Description

function stats_stat_binomial_coef(int `$x`, int `$n`): float

Renvoie le coefficient binomial de `n` choisi `x`.

### Liste de paramètres

`x`

  Le nombre de choix dans l'ensemble

`n`

  Le nombre d'éléments dans l'ensemble

### Valeurs de retour

Renvoie le coefficient binomial

# stats_stat_correlation

(PECL stats >= 1.0.0)

stats_stat_correlation — Renvoie le coefficient de corrélation de Pearson de deux ensembles de données

### Description

function stats_stat_correlation(array `$arr1`, array `$arr2`): float

Renvoie le coefficient de corrélation de Pearson entre `arr1` et `arr2`.

### Liste de paramètres

`arr1`

  Le premier tableau

`arr2`

  Le second tableau

### Valeurs de retour

Renvoie le coefficient de corrélation de Pearson entre `arr1` et `arr2`, ou `false` en cas d'échec.

# stats_stat_factorial

(PECL stats >= 1.0.0)

stats_stat_factorial — Renvoie la factorielle d'un entier

### Description

function stats_stat_factorial(int `$n`): float

Renvoie la factorielle d'un entier, `n`.

### Liste de paramètres

`n`

  Un entier

### Valeurs de retour

La factorielle de `n`.

# stats_stat_independent_t

(PECL stats >= 1.0.0)

stats_stat_independent_t — Renvoie la valeur t du test t à deux échantillons indépendants

### Description

function stats_stat_independent_t(array `$arr1`, array `$arr2`): float

Renvoie la valeur t du test t à deux échantillons indépendants entre `arr1` et `arr2`.

Avertissement

Cette fonction est actuellement non documentée ; seule la liste des arguments est disponible.

### Liste de paramètres

`arr1`

  Le premier ensemble de valeurs

`arr2`

  Le second ensemble de valeurs

### Valeurs de retour

Renvoie la valeur t, ou `false` en cas d'échec.

# stats_stat_innerproduct

(PECL stats >= 1.0.0)

stats_stat_innerproduct — Renvoie le produit interne de deux vecteurs

### Description

function stats_stat_innerproduct(array `$arr1`, array `$arr2`): float

Renvoie le produit interne de `arr1` et `arr2`.

### Liste de paramètres

`arr1`

  Le premier tableau

`arr2`

  Le second tableau

### Valeurs de retour

Renvoie le produit interne de `arr1` et `arr2`, ou `false` en cas d'échec.

# stats_stat_paired_t

(PECL stats >= 1.0.0)

stats_stat_paired_t — Renvoie la valeur t du test t dépendant à deux échantillons appariés

### Description

function stats_stat_paired_t(array `$arr1`, array `$arr2`): float

Renvoie la valeur t du test t dépendant à deux échantillons appariés pour les échantillons `arr1` et `arr2`.

### Liste de paramètres

`arr1`

  Le premier échantillon

`arr2`

  Le second échantillon

### Valeurs de retour

Renvoie la valeur t, ou `false` en cas d'échec.

# stats_stat_percentile

(PECL stats >= 1.0.0)

stats_stat_percentile — Renvoie la valeur du centile

### Description

function stats_stat_percentile(array `$arr`, float `$perc`): float

Renvoie la valeur du `perc`-ième centile de l'ensemble de données `arr`.

### Liste de paramètres

`arr`

  Le tableau d'entrée

`perc`

  Le centile

### Valeurs de retour

Renvoie le centile de l'ensemble de données.

# stats_stat_powersum

(PECL stats >= 1.0.0)

stats_stat_powersum — Renvoie la somme des puissances d'un vecteur

### Description

function stats_stat_powersum(array `$arr`, float `$power`): float

Renvoie la somme de la `power`-ième puissance d'un vecteur représenté sous forme de tableau `arr`.

### Liste de paramètres

`arr`

  Le tableau d'entrée

`power`

  La puissance

### Valeurs de retour

Renvoie la somme des puissances de l'ensemble de données.

# stats_variance

(PECL stats >= 1.0.0)

stats_variance — Renvoie la variance

### Description

function stats_variance(array `$a`, bool `$sample` = `false`): float

Renvoie la variance des valeurs dans `a`.

### Liste de paramètres

`a`

  Le tableau de données pour lequel calculer la variance. Il est à noter que toutes les valeurs du tableau seront converties en float.

`sample`

  Indique si `a` représente un échantillon de la population; par défaut à `false`.

### Valeurs de retour

Renvoie la variance en cas de succès; `false` en cas d'échec.

## Sommaire

- stats_absolute_deviation — Renvoie l'écart absolu d'un tableau de valeurs
- stats_cdf_beta — Calcule un paramètre de la distribution beta en fonction des autres valeurs
- stats_cdf_binomial — Calcule un paramètre de la distribution binomiale en fonction des autres valeurs
- stats_cdf_cauchy — Calcule un paramètre de la distribution de Cauchy en fonction des autres valeurs
- stats_cdf_chisquare — Calcule un paramètre de la distribution du chi-deux en fonction des autres valeurs
- stats_cdf_exponential — Calcule un paramètre de la distribution exponentielle en fonction des autres valeurs
- stats_cdf_f — Calcule un paramètre de la distribution F en fonction des autres valeurs
- stats_cdf_gamma — Calcule un paramètre de la distribution gamma en fonction des autres valeurs
- stats_cdf_laplace — Calcule un paramètre de la distribution de Laplace en fonction des autres valeurs
- stats_cdf_logistic — Calcule un paramètre de la distribution logistique en fonction des autres valeurs
- stats_cdf_negative_binomial — Calcule un paramètre de la distribution binomiale négative en fonction des autres valeurs
- stats_cdf_noncentral_chisquare — Calcule un paramètre de la distribution du chi-deux non-centrale en fonction des autres valeurs
- stats_cdf_noncentral_f — Calcule un paramètre de la distribution F non-centrale en fonction des autres valeurs
- stats_cdf_noncentral_t — Calcule un paramètre de la distribution t non-centrale en fonction des autres valeurs
- stats_cdf_normal — Calcule un paramètre de la distribution normale en fonction des autres valeurs
- stats_cdf_poisson — Calcule un paramètre de la distribution de Poisson en fonction des autres valeurs
- stats_cdf_t — Calcule un paramètre de la distribution t en fonction des autres valeurs
- stats_cdf_uniform — Calcule un paramètre de la distribution uniforme en fonction des autres valeurs
- stats_cdf_weibull — Calcule un paramètre de la distribution de Weibull en fonction des autres valeurs
- stats_covariance — Calcule la covariance de deux ensembles de données
- stats_dens_beta — La fonction de densité de probabilité de la distribution bêta
- stats_dens_cauchy — La fonction de densité de probabilité de la distribution de Cauchy
- stats_dens_chisquare — La fonction de densité de probabilité de la distribution du chi-carré
- stats_dens_exponential — La fonction de densité de probabilité de la distribution exponentielle
- stats_dens_f — La fonction de densité de probabilité de la distribution F
- stats_dens_gamma — La fonction de densité de probabilité de la distribution gamma
- stats_dens_laplace — La fonction de densité de probabilité de la distribution de Laplace
- stats_dens_logistic — La fonction de densité de probabilité de la distribution logistique
- stats_dens_normal — La fonction de densité de probabilité de la distribution normale
- stats_dens_pmf_binomial — La fonction de masse de probabilité de la distribution binomiale
- stats_dens_pmf_hypergeometric — La fonction de masse de probabilité de la distribution hypergéométrique
- stats_dens_pmf_negative_binomial — La fonction de masse de probabilité de la distribution binomiale négative
- stats_dens_pmf_poisson — La fonction de masse de probabilité de la distribution de Poisson
- stats_dens_t — La fonction de densité de probabilité de la distribution t
- stats_dens_uniform — La fonction de densité de probabilité de la distribution uniforme
- stats_dens_weibull — La fonction de densité de probabilité de la distribution de Weibull
- stats_harmonic_mean — Renvoie la moyenne harmonique d'un tableau de valeurs
- stats_kurtosis — Calcule le kurtosis des données dans le tableau
- stats_rand_gen_beta — Génère une déviation aléatoire de la distribution beta
- stats_rand_gen_chisquare — Génère une déviation aléatoire de la distribution chi-carré
- stats_rand_gen_exponential — Génère une déviation aléatoire de la distribution exponentielle
- stats_rand_gen_f — Génère une déviation aléatoire de la distribution F
- stats_rand_gen_funiform — Génère un flottant uniforme entre low (exclusif) et high (exclusif)
- stats_rand_gen_gamma — Génère une déviation aléatoire de la distribution gamma
- stats_rand_gen_ibinomial — Génère une déviation aléatoire de la distribution binomiale
- stats_rand_gen_ibinomial_negative — Génère une déviation aléatoire de la distribution binomiale négative
- stats_rand_gen_int — Génère un entier aléatoire entre 1 et 2147483562
- stats_rand_gen_ipoisson — Génère une seule déviation aléatoire de la distribution de Poisson
- stats_rand_gen_iuniform — Renvoie un entier aléatoire uniformément distribué entre LOW (inclus) et HIGH (inclus)
- stats_rand_gen_noncentral_chisquare — Génère une déviation aléatoire de la distribution chi-carré non-centrale
- stats_rand_gen_noncentral_f — Génère une déviation aléatoire de la distribution F non-centrale
- stats_rand_gen_noncentral_t — Génère une seule déviation aléatoire de la distribution t non-centrale
- stats_rand_gen_normal — Génère une déviation aléatoire de la distribution normale
- stats_rand_gen_t — Génère une seule déviation aléatoire de la distribution t
- stats_rand_get_seeds — Renvoie les valeurs de la graine du générateur de nombres aléatoires
- stats_rand_phrase_to_seeds — Génère deux graines pour le générateur de nombres aléatoires RGN
- stats_rand_ranf — Génère un nombre flottant aléatoire entre 0 et 1
- stats_rand_setall — Définit les valeurs de la graine pour le générateur aléatoire
- stats_skew — Calcule l'asymétrie des données dans un tableau
- stats_standard_deviation — Renvoie la déviation standard
- stats_stat_binomial_coef — Renvoie un coefficient binomial
- stats_stat_correlation — Renvoie le coefficient de corrélation de Pearson de deux ensembles de données
- stats_stat_factorial — Renvoie la factorielle d'un entier
- stats_stat_independent_t — Renvoie la valeur t du test t à deux échantillons indépendants
- stats_stat_innerproduct — Renvoie le produit interne de deux vecteurs
- stats_stat_paired_t — Renvoie la valeur t du test t dépendant à deux échantillons appariés
- stats_stat_percentile — Renvoie la valeur du centile
- stats_stat_powersum — Renvoie la somme des puissances d'un vecteur
- stats_variance — Renvoie la variance

- Installation/Configuration
  - Pré-requis
  - Installation
- Fonctions de Statistic
  - stats_absolute_deviation — Renvoie l'écart absolu d'un tableau de valeurs
  - stats_cdf_beta — Calcule un paramètre de la distribution beta en fonction des autres valeurs
  - stats_cdf_binomial — Calcule un paramètre de la distribution binomiale en fonction des autres valeurs
  - stats_cdf_cauchy — Calcule un paramètre de la distribution de Cauchy en fonction des autres valeurs
  - stats_cdf_chisquare — Calcule un paramètre de la distribution du chi-deux en fonction des autres valeurs
  - stats_cdf_exponential — Calcule un paramètre de la distribution exponentielle en fonction des autres valeurs
  - stats_cdf_f — Calcule un paramètre de la distribution F en fonction des autres valeurs
  - stats_cdf_gamma — Calcule un paramètre de la distribution gamma en fonction des autres valeurs
  - stats_cdf_laplace — Calcule un paramètre de la distribution de Laplace en fonction des autres valeurs
  - stats_cdf_logistic — Calcule un paramètre de la distribution logistique en fonction des autres valeurs
  - stats_cdf_negative_binomial — Calcule un paramètre de la distribution binomiale négative en fonction des autres valeurs
  - stats_cdf_noncentral_chisquare — Calcule un paramètre de la distribution du chi-deux non-centrale en fonction des autres valeurs
  - stats_cdf_noncentral_f — Calcule un paramètre de la distribution F non-centrale en fonction des autres valeurs
  - stats_cdf_noncentral_t — Calcule un paramètre de la distribution t non-centrale en fonction des autres valeurs
  - stats_cdf_normal — Calcule un paramètre de la distribution normale en fonction des autres valeurs
  - stats_cdf_poisson — Calcule un paramètre de la distribution de Poisson en fonction des autres valeurs
  - stats_cdf_t — Calcule un paramètre de la distribution t en fonction des autres valeurs
  - stats_cdf_uniform — Calcule un paramètre de la distribution uniforme en fonction des autres valeurs
  - stats_cdf_weibull — Calcule un paramètre de la distribution de Weibull en fonction des autres valeurs
  - stats_covariance — Calcule la covariance de deux ensembles de données
  - stats_dens_beta — La fonction de densité de probabilité de la distribution bêta
  - stats_dens_cauchy — La fonction de densité de probabilité de la distribution de Cauchy
  - stats_dens_chisquare — La fonction de densité de probabilité de la distribution du chi-carré
  - stats_dens_exponential — La fonction de densité de probabilité de la distribution exponentielle
  - stats_dens_f — La fonction de densité de probabilité de la distribution F
  - stats_dens_gamma — La fonction de densité de probabilité de la distribution gamma
  - stats_dens_laplace — La fonction de densité de probabilité de la distribution de Laplace
  - stats_dens_logistic — La fonction de densité de probabilité de la distribution logistique
  - stats_dens_normal — La fonction de densité de probabilité de la distribution normale
  - stats_dens_pmf_binomial — La fonction de masse de probabilité de la distribution binomiale
  - stats_dens_pmf_hypergeometric — La fonction de masse de probabilité de la distribution hypergéométrique
  - stats_dens_pmf_negative_binomial — La fonction de masse de probabilité de la distribution binomiale négative
  - stats_dens_pmf_poisson — La fonction de masse de probabilité de la distribution de Poisson
  - stats_dens_t — La fonction de densité de probabilité de la distribution t
  - stats_dens_uniform — La fonction de densité de probabilité de la distribution uniforme
  - stats_dens_weibull — La fonction de densité de probabilité de la distribution de Weibull
  - stats_harmonic_mean — Renvoie la moyenne harmonique d'un tableau de valeurs
  - stats_kurtosis — Calcule le kurtosis des données dans le tableau
  - stats_rand_gen_beta — Génère une déviation aléatoire de la distribution beta
  - stats_rand_gen_chisquare — Génère une déviation aléatoire de la distribution chi-carré
  - stats_rand_gen_exponential — Génère une déviation aléatoire de la distribution exponentielle
  - stats_rand_gen_f — Génère une déviation aléatoire de la distribution F
  - stats_rand_gen_funiform — Génère un flottant uniforme entre low (exclusif) et high (exclusif)
  - stats_rand_gen_gamma — Génère une déviation aléatoire de la distribution gamma
  - stats_rand_gen_ibinomial — Génère une déviation aléatoire de la distribution binomiale
  - stats_rand_gen_ibinomial_negative — Génère une déviation aléatoire de la distribution binomiale négative
  - stats_rand_gen_int — Génère un entier aléatoire entre 1 et 2147483562
  - stats_rand_gen_ipoisson — Génère une seule déviation aléatoire de la distribution de Poisson
  - stats_rand_gen_iuniform — Renvoie un entier aléatoire uniformément distribué entre LOW (inclus) et HIGH (inclus)
  - stats_rand_gen_noncentral_chisquare — Génère une déviation aléatoire de la distribution chi-carré non-centrale
  - stats_rand_gen_noncentral_f — Génère une déviation aléatoire de la distribution F non-centrale
  - stats_rand_gen_noncentral_t — Génère une seule déviation aléatoire de la distribution t non-centrale
  - stats_rand_gen_normal — Génère une déviation aléatoire de la distribution normale
  - stats_rand_gen_t — Génère une seule déviation aléatoire de la distribution t
  - stats_rand_get_seeds — Renvoie les valeurs de la graine du générateur de nombres aléatoires
  - stats_rand_phrase_to_seeds — Génère deux graines pour le générateur de nombres aléatoires RGN
  - stats_rand_ranf — Génère un nombre flottant aléatoire entre 0 et 1
  - stats_rand_setall — Définit les valeurs de la graine pour le générateur aléatoire
  - stats_skew — Calcule l'asymétrie des données dans un tableau
  - stats_standard_deviation — Renvoie la déviation standard
  - stats_stat_binomial_coef — Renvoie un coefficient binomial
  - stats_stat_correlation — Renvoie le coefficient de corrélation de Pearson de deux ensembles de données
  - stats_stat_factorial — Renvoie la factorielle d'un entier
  - stats_stat_independent_t — Renvoie la valeur t du test t à deux échantillons indépendants
  - stats_stat_innerproduct — Renvoie le produit interne de deux vecteurs
  - stats_stat_paired_t — Renvoie la valeur t du test t dépendant à deux échantillons appariés
  - stats_stat_percentile — Renvoie la valeur du centile
  - stats_stat_powersum — Renvoie la somme des puissances d'un vecteur
  - stats_variance — Renvoie la variance

# Analyse technique pour les marchands

# Introduction

L'extension Trader est une bibliothèque open source libre, basée sur TA-Lib. Elle est dédiée aux développeurs de logiciels commerciaux qui nécessitent d'effectuer une analyse technique des données sur les marchés financiers. En plus de cela, plusieurs indicateurs comme ADX, MACD, RSI, Stochastic, TRIX, le chandelier à reconnaissance de motif, mais aussi diverses fonctions arithmétiques et algébriques sont présents.

Les calculs peuvent être réalisés en 2 modes : TA-Lib et Metastock. La modification de ces modes en utilisant la fonction trader_set_compat() affectera la façon dont réagissent quelques fonctions Trader.

Quelques fonctions Trader fournissent différents résultats suivant le "point de départ" des données à utiliser. Ce peut être comparé à l'allocation mémoire d'une fonction. Un exemple d'une telle fonction est la moyenne de déplacement exponentiel. Il est possible de contrôler la période instable (la quantité de données à retirer) en utilisant la fonction trader_set_unstable_period().

Une documentation plus complète à propos des indicateurs, des formules et son implémentation dans d'autres langages de programmation peut être trouvée sur le site » https://ta-lib.org/.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Configuration à l'exécution

## Pré-requis

L'extension trader est basée sur » TA-Lib. TA-Lib est totalement intégré dans l'extension, aussi, aucune bibliothèque externe n'est nécessaire.

## Installation

Cette extension » PECL n'est pas intégrée à PHP.

Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : » https://pecl.php.net/package/trader.

## Configuration à l'exécution

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

Options de configuration Trader
Nom | Défaut | Modifiable | Historique
--- | --- | --- | ---
trader.real_precision | 3 | `INI_ALL` | Depuis trader 0.2.1
trader.real_round_mode | HALF_DOWN | `INI_ALL` | Depuis trader 0.3.0

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

`trader.real_precision` int

  Toutes les valeurs des tableaux retournés seront arrondies à cette précision. Cependant, les calculs dans la TA-Lib sont effectués avec des valeurs non-arrondies.

`trader.real_round_mode` string

  Contrôle la politique d'arrondissement des réels trader. Les valeurs valides sont `HALF_UP`, `HALF_DOWN`, `HALF_EVEN` et `HALF_ODD`. Le comportement est identique à la fonction round() utilisée avec l'argument mode.

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

`TRADER_MA_TYPE_SMA` (int)
`TRADER_MA_TYPE_EMA` (int)
`TRADER_MA_TYPE_WMA` (int)
`TRADER_MA_TYPE_DEMA` (int)
`TRADER_MA_TYPE_TEMA` (int)
`TRADER_MA_TYPE_TRIMA` (int)
`TRADER_MA_TYPE_KAMA` (int)
`TRADER_MA_TYPE_MAMA` (int)
`TRADER_MA_TYPE_T3` (int)
`TRADER_REAL_MIN` (float)
`TRADER_REAL_MAX` (float)
`TRADER_FUNC_UNST_ADX` (int)
`TRADER_FUNC_UNST_ADXR` (int)
`TRADER_FUNC_UNST_ATR` (int)
`TRADER_FUNC_UNST_CMO` (int)
`TRADER_FUNC_UNST_DX` (int)
`TRADER_FUNC_UNST_EMA` (int)
`TRADER_FUNC_UNST_HT_DCPERIOD` (int)
`TRADER_FUNC_UNST_HT_DCPHASE` (int)
`TRADER_FUNC_UNST_HT_PHASOR` (int)
`TRADER_FUNC_UNST_HT_SINE` (int)
`TRADER_FUNC_UNST_HT_TRENDLINE` (int)
`TRADER_FUNC_UNST_HT_TRENDMODE` (int)
`TRADER_FUNC_UNST_KAMA` (int)
`TRADER_FUNC_UNST_MAMA` (int)
`TRADER_FUNC_UNST_MFI` (int)
`TRADER_FUNC_UNST_MINUS_DI` (int)
`TRADER_FUNC_UNST_MINUS_DM` (int)
`TRADER_FUNC_UNST_NATR` (int)
`TRADER_FUNC_UNST_PLUS_DI` (int)
`TRADER_FUNC_UNST_PLUS_DM` (int)
`TRADER_FUNC_UNST_RSI` (int)
`TRADER_FUNC_UNST_STOCHRSI` (int)
`TRADER_FUNC_UNST_T3` (int)
`TRADER_FUNC_UNST_ALL` (int)
`TRADER_FUNC_UNST_NONE` (int)
`TRADER_COMPATIBILITY_DEFAULT` (int)
`TRADER_COMPATIBILITY_METASTOCK` (int)
`TRADER_ERR_SUCCESS` (int)
`TRADER_ERR_LIB_NOT_INITIALIZE` (int)
`TRADER_ERR_BAD_PARAM` (int)
`TRADER_ERR_ALLOC_ERR` (int)
`TRADER_ERR_GROUP_NOT_FOUND` (int)
`TRADER_ERR_FUNC_NOT_FOUND` (int)
`TRADER_ERR_INVALID_HANDLE` (int)
`TRADER_ERR_INVALID_PARAM_HOLDER` (int)
`TRADER_ERR_INVALID_PARAM_HOLDER_TYPE` (int)
`TRADER_ERR_INVALID_PARAM_FUNCTION` (int)
`TRADER_ERR_INPUT_NOT_ALL_INITIALIZE` (int)
`TRADER_ERR_OUTPUT_NOT_ALL_INITIALIZE` (int)
`TRADER_ERR_OUT_OF_RANGE_START_INDEX` (int)
`TRADER_ERR_OUT_OF_RANGE_END_INDEX` (int)
`TRADER_ERR_INVALID_LIST_TYPE` (int)
`TRADER_ERR_BAD_OBJECT` (int)
`TRADER_ERR_NOT_SUPPORTED` (int)
`TRADER_ERR_INTERNAL_ERROR` (int)
`TRADER_ERR_UNKNOWN_ERROR` (int)

# Fonctions Trader

# trader_acos

(PECL trader >= 0.2.0)

trader_acos — Vector Trigonometric ACos

### Description

function trader_acos(array `$real`): array

Calcule l'arc cosinus de chaque valeur de `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ad

(PECL trader >= 0.2.0)

trader_ad — Chaikin A/D Line

### Description

function trader_ad(
array `$high`,
array `$low`,
array `$close`,
array `$volume`
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`volume`

  Volume échangé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_add

(PECL trader >= 0.2.0)

trader_add — Ajoute un vecteur arithmétique

### Description

function trader_add(array `$real0`, array `$real1`): array

Calcule l'addition vectorielle de `real0` à `real1` et retourne le vecteur résultant.

### Liste de paramètres

`real0`

  Tableau de valeurs réelles.

`real1`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_adosc

(PECL trader >= 0.2.0)

trader_adosc — Chaikin A/D Oscillator

### Description

function trader_adosc(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`volume`

  Volume échangé, tableau de valeurs réelles.

`fastPeriod`

  Nombre de période pour le fast MA. Intervalle valide : 2 à 100000.

`slowPeriod`

  Nombre de période pour le MA. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_adx

(PECL trader >= 0.2.0)

trader_adx — Average Directional Movement Index

### Description

function trader_adx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_adxr

(PECL trader >= 0.2.0)

trader_adxr — Average Directional Movement Index Rating

### Description

function trader_adxr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_apo

(PECL trader >= 0.2.0)

trader_apo — Absolute Price Oscillator

### Description

function trader_apo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`fastPeriod`

  Nombre de période pour le fast MA. Intervalle valide : 2 à 100000.

`slowPeriod`

  Nombre de période pour le MA. Intervalle valide : 2 à 100000.

`mAType`

  Type de moyenne mobile. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_aroon

(PECL trader >= 0.2.0)

trader_aroon — Aroon

### Description

function trader_aroon(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_aroonosc

(PECL trader >= 0.2.0)

trader_aroonosc — Aroon Oscillator

### Description

function trader_aroonosc(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_asin

(PECL trader >= 0.2.0)

trader_asin — Vector Trigonometric ASin

### Description

function trader_asin(array `$real`): array

Calcule l'arc sinus de chaque valeur de `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_atan

(PECL trader >= 0.2.0)

trader_atan — Calcule l'arc tangente

### Description

function trader_atan(array `$real`): array

Calcule l'arc tangente de chaque valeur de `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_atr

(PECL trader >= 0.2.0)

trader_atr — Average True Range

### Description

function trader_atr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_avgprice

(PECL trader >= 0.2.0)

trader_avgprice — Average Price

### Description

function trader_avgprice(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_bbands

(PECL trader >= 0.2.0)

trader_bbands — Bollinger Bands

### Description

function trader_bbands(
array `$real`,
int `$timePeriod` = ?,
float `$nbDevUp` = ?,
float `$nbDevDn` = ?,
int `$mAType` = ?
): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

`nbDevUp`

  Multiplicateur d'écart pour la bande supérieure. Intervalle valide : TRADER_REAL_MIN à TRADER_REAL_MAX.

`nbDevDn`

  Multiplicateur d'écart pour la bande inférieure. Intervalle valide : TRADER_REAL_MIN à TRADER_REAL_MAX.

`mAType`

  Type de moyenne mobile. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_beta

(PECL trader >= 0.2.0)

trader_beta — Beta

### Description

function trader_beta(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### Liste de paramètres

`real0`

  Tableau de valeurs réelles.

`real1`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_bop

(PECL trader >= 0.2.0)

trader_bop — Balance Of Power

### Description

function trader_bop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cci

(PECL trader >= 0.2.0)

trader_cci — Commodity Channel Index

### Description

function trader_cci(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdl2crows

(PECL trader >= 0.2.0)

trader_cdl2crows — Two Crows

### Description

function trader_cdl2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdl3blackcrows

(PECL trader >= 0.2.0)

trader_cdl3blackcrows — Three Black Crows

### Description

function trader_cdl3blackcrows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdl3inside

(PECL trader >= 0.2.0)

trader_cdl3inside — Three Inside Up/Down

### Description

function trader_cdl3inside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdl3linestrike

(PECL trader >= 0.2.0)

trader_cdl3linestrike — Three-Line Strike

### Description

function trader_cdl3linestrike(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdl3outside

(PECL trader >= 0.2.0)

trader_cdl3outside — Three Outside Up/Down

### Description

function trader_cdl3outside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdl3starsinsouth

(PECL trader >= 0.2.0)

trader_cdl3starsinsouth — Three Stars In The South

### Description

function trader_cdl3starsinsouth(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdl3whitesoldiers

(PECL trader >= 0.2.0)

trader_cdl3whitesoldiers — Three Advancing White Soldiers

### Description

function trader_cdl3whitesoldiers(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlabandonedbaby

(PECL trader >= 0.2.0)

trader_cdlabandonedbaby — Abandoned Baby

### Description

function trader_cdlabandonedbaby(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`penetration`

  Pourcentage de pénétration d'une bougie dans une autre bougie.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdladvanceblock

(PECL trader >= 0.2.0)

trader_cdladvanceblock — Advance Block

### Description

function trader_cdladvanceblock(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlbelthold

(PECL trader >= 0.2.0)

trader_cdlbelthold — Belt-hold

### Description

function trader_cdlbelthold(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlbreakaway

(PECL trader >= 0.2.0)

trader_cdlbreakaway — Breakaway

### Description

function trader_cdlbreakaway(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlclosingmarubozu

(PECL trader >= 0.2.0)

trader_cdlclosingmarubozu — Closing Marubozu

### Description

function trader_cdlclosingmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlconcealbabyswall

(PECL trader >= 0.2.0)

trader_cdlconcealbabyswall — Concealing Baby Swallow

### Description

function trader_cdlconcealbabyswall(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlcounterattack

(PECL trader >= 0.2.0)

trader_cdlcounterattack — Counterattack

### Description

function trader_cdlcounterattack(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdldarkcloudcover

(PECL trader >= 0.2.0)

trader_cdldarkcloudcover — Dark Cloud Cover

### Description

function trader_cdldarkcloudcover(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`penetration`

  Pourcentage de pénétration d'une bougie dans une autre bougie.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdldoji

(PECL trader >= 0.2.0)

trader_cdldoji — Doji

### Description

function trader_cdldoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdldojistar

(PECL trader >= 0.2.0)

trader_cdldojistar — Doji Star

### Description

function trader_cdldojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdldragonflydoji

(PECL trader >= 0.2.0)

trader_cdldragonflydoji — Dragonfly Doji

### Description

function trader_cdldragonflydoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlengulfing

(PECL trader >= 0.2.0)

trader_cdlengulfing — Engulfing Pattern

### Description

function trader_cdlengulfing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdleveningdojistar

(PECL trader >= 0.2.0)

trader_cdleveningdojistar — Evening Doji Star

### Description

function trader_cdleveningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`penetration`

  Pourcentage de pénétration d'une bougie dans une autre bougie.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdleveningstar

(PECL trader >= 0.2.0)

trader_cdleveningstar — Evening Star

### Description

function trader_cdleveningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`penetration`

  Pourcentage de pénétration d'une bougie dans une autre bougie.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlgapsidesidewhite

(PECL trader >= 0.2.0)

trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines

### Description

function trader_cdlgapsidesidewhite(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlgravestonedoji

(PECL trader >= 0.2.0)

trader_cdlgravestonedoji — Gravestone Doji

### Description

function trader_cdlgravestonedoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlhammer

(PECL trader >= 0.2.0)

trader_cdlhammer — Hammer

### Description

function trader_cdlhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlhangingman

(PECL trader >= 0.2.0)

trader_cdlhangingman — Hanging Man

### Description

function trader_cdlhangingman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlharami

(PECL trader >= 0.2.0)

trader_cdlharami — Harami Pattern

### Description

function trader_cdlharami(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlharamicross

(PECL trader >= 0.2.0)

trader_cdlharamicross — Harami Cross Pattern

### Description

function trader_cdlharamicross(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlhighwave

(PECL trader >= 0.2.0)

trader_cdlhighwave — High-Wave Candle

### Description

function trader_cdlhighwave(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlhikkake

(PECL trader >= 0.2.0)

trader_cdlhikkake — Hikkake Pattern

### Description

function trader_cdlhikkake(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlhikkakemod

(PECL trader >= 0.2.0)

trader_cdlhikkakemod — Modified Hikkake Pattern

### Description

function trader_cdlhikkakemod(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlhomingpigeon

(PECL trader >= 0.2.0)

trader_cdlhomingpigeon — Homing Pigeon

### Description

function trader_cdlhomingpigeon(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlidentical3crows

(PECL trader >= 0.2.0)

trader_cdlidentical3crows — Identical Three Crows

### Description

function trader_cdlidentical3crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlinneck

(PECL trader >= 0.2.0)

trader_cdlinneck — In-Neck Pattern

### Description

function trader_cdlinneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlinvertedhammer

(PECL trader >= 0.2.0)

trader_cdlinvertedhammer — Marteau inversé

### Description

function trader_cdlinvertedhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlkicking

(PECL trader >= 0.2.0)

trader_cdlkicking — Kicking

### Description

function trader_cdlkicking(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlkickingbylength

(PECL trader >= 0.2.0)

trader_cdlkickingbylength — Kicking - bull/bear déterminé par le plus long marubozu

### Description

function trader_cdlkickingbylength(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlladderbottom

(PECL trader >= 0.2.0)

trader_cdlladderbottom — Bas de l'échelle

### Description

function trader_cdlladderbottom(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdllongleggeddoji

(PECL trader >= 0.2.0)

trader_cdllongleggeddoji — Doji : longueur des jambes

### Description

function trader_cdllongleggeddoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdllongline

(PECL trader >= 0.2.0)

trader_cdllongline — Long Line Candle

### Description

function trader_cdllongline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlmarubozu

(PECL trader >= 0.2.0)

trader_cdlmarubozu — Marubozu

### Description

function trader_cdlmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlmatchinglow

(PECL trader >= 0.2.0)

trader_cdlmatchinglow — Matching Low

### Description

function trader_cdlmatchinglow(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlmathold

(PECL trader >= 0.2.0)

trader_cdlmathold — Mat Hold

### Description

function trader_cdlmathold(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`penetration`

  Pourcentage de pénétration d'une bougie dans une autre bougie.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlmorningdojistar

(PECL trader >= 0.2.0)

trader_cdlmorningdojistar — Etoile Doji du matin

### Description

function trader_cdlmorningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`penetration`

  Pourcentage de pénétration d'une bougie dans une autre bougie.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlmorningstar

(PECL trader >= 0.2.0)

trader_cdlmorningstar — Etoile du matin

### Description

function trader_cdlmorningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`penetration`

  Pourcentage de pénétration d'une bougie dans une autre bougie.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlonneck

(PECL trader >= 0.2.0)

trader_cdlonneck — On-Neck Pattern

### Description

function trader_cdlonneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlpiercing

(PECL trader >= 0.2.0)

trader_cdlpiercing — Piercing Pattern

### Description

function trader_cdlpiercing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlrickshawman

(PECL trader >= 0.2.0)

trader_cdlrickshawman — Rickshaw Man

### Description

function trader_cdlrickshawman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlrisefall3methods

(PECL trader >= 0.2.0)

trader_cdlrisefall3methods — Hausse / Baisse - 3 méthodes

### Description

function trader_cdlrisefall3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlseparatinglines

(PECL trader >= 0.2.0)

trader_cdlseparatinglines — Lignes séparées

### Description

function trader_cdlseparatinglines(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlshootingstar

(PECL trader >= 0.2.0)

trader_cdlshootingstar — Etoile filante

### Description

function trader_cdlshootingstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlshortline

(PECL trader >= 0.2.0)

trader_cdlshortline — Ligne courte de bougie

### Description

function trader_cdlshortline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlspinningtop

(PECL trader >= 0.2.0)

trader_cdlspinningtop — Toupie

### Description

function trader_cdlspinningtop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlstalledpattern

(PECL trader >= 0.2.0)

trader_cdlstalledpattern — Stalled Pattern

### Description

function trader_cdlstalledpattern(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlsticksandwich

(PECL trader >= 0.2.0)

trader_cdlsticksandwich — Sandwich épinglé

### Description

function trader_cdlsticksandwich(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdltakuri

(PECL trader >= 0.2.0)

trader_cdltakuri — Takuri (Dragonfly Doji avec une ombre inférieure très longue)

### Description

function trader_cdltakuri(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdltasukigap

(PECL trader >= 0.2.0)

trader_cdltasukigap — Ecart Tasuki

### Description

function trader_cdltasukigap(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlthrusting

(PECL trader >= 0.2.0)

trader_cdlthrusting — Thrusting Pattern

### Description

function trader_cdlthrusting(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdltristar

(PECL trader >= 0.2.0)

trader_cdltristar — Tristar Pattern

### Description

function trader_cdltristar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlunique3river

(PECL trader >= 0.2.0)

trader_cdlunique3river — Unique 3 River

### Description

function trader_cdlunique3river(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlupsidegap2crows

(PECL trader >= 0.2.0)

trader_cdlupsidegap2crows — Upside Gap Two Crows

### Description

function trader_cdlupsidegap2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cdlxsidegap3methods

(PECL trader >= 0.2.0)

trader_cdlxsidegap3methods — Ecart supérieur/inférieur trois méthodes

### Description

function trader_cdlxsidegap3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Liste de paramètres

`open`

  Prix ouvert, tableau de valeurs réelles.

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ceil

(PECL trader >= 0.2.0)

trader_ceil — Vecteur plafonné

### Description

function trader_ceil(array `$real`): array

Calcule l'entier supérieur suivant, pour chaque valeur du paramètre `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cmo

(PECL trader >= 0.2.0)

trader_cmo — Oscillateur dynamique Chande

### Description

function trader_cmo(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_correl

(PECL trader >= 0.2.0)

trader_correl — Coefficient de corrélation de Pearson (r)

### Description

function trader_correl(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### Liste de paramètres

`real0`

  Tableau de valeurs réelles.

`real1`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cos

(PECL trader >= 0.2.0)

trader_cos — Vecteur trigonométrique Cos

### Description

function trader_cos(array `$real`): array

Calcule le cosinus pour chaque valeur du paramètre `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_cosh

(PECL trader >= 0.2.0)

trader_cosh — Vecteur trigonométrique Cosh

### Description

function trader_cosh(array `$real`): array

Calcule le cosinus hyperbolique pour chaque valeur du paramètre `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_dema

(PECL trader >= 0.2.0)

trader_dema — Moyenne mobile exponentielle double

### Description

function trader_dema(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_div

(PECL trader >= 0.2.0)

trader_div — Vecteur arithmétique Div

### Description

function trader_div(array `$real0`, array `$real1`): array

Divise chaque valeur du paramètre `real0` par la valeur correspondante du paramètre `real1` et retourne le tableau résultant.

### Liste de paramètres

`real0`

  Tableau de valeurs réelles.

`real1`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_dx

(PECL trader >= 0.2.0)

trader_dx — Indice de mouvement directionnel

### Description

function trader_dx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ema

(PECL trader >= 0.2.0)

trader_ema — Moyenne mobile exponentielle

### Description

function trader_ema(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_errno

(PECL trader >= 0.3.0)

trader_errno — Récupère le code erreur

### Description

function trader_errno(): int

Récupère le code erreur de la dernière opération.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne le code erreur identifié par une des constantes TRADER_ERR_*.

# trader_exp

(PECL trader >= 0.2.0)

trader_exp — Vecteur arithmétique Exp

### Description

function trader_exp(array `$real`): array

Calcule la constante `e` élevée à la puissance de chaque valeur du paramètre `real`. Retourne un tableau contenant les données calculées.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_floor

(PECL trader >= 0.2.0)

trader_floor — Niveau du vecteur

### Description

function trader_floor(array `$real`): array

Calcule l'entier le plus petit suivant, pour chaque valeur du paramètre `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_get_compat

(PECL trader >= 0.2.2)

trader_get_compat — Récupère le mode de compatibilité

### Description

function trader_get_compat(): int

Récupère le mode de compatibilité qui affecte la façon dont les calculs sont effectués par toutes les fonctions de l'extension.

### Liste de paramètres

Cette fonction ne contient aucun paramètre.

### Valeurs de retour

Retourne l'identifiant du mode de compatibilité, qui peut être identifié par une série de constantes TRADER_COMPATIBILITY_*.

# trader_get_unstable_period

(PECL trader >= 0.2.2)

trader_get_unstable_period — Récupère la période d'instabilité

### Description

function trader_get_unstable_period(int `$functionId`): int

Récupère le facteur d'instabilité de la période pour une fonction en particulier.

### Liste de paramètres

`functionId`

  Identifiant de la fonction du facteur à lire. Les constantes de la série TRADER_FUNC_UNST_* devraient être utilisées.

### Valeurs de retour

Retourne le facteur d'instabilité de la période pour la fonction correspondante.

# trader_ht_dcperiod

(PECL trader >= 0.2.0)

trader_ht_dcperiod — Transformation de Hilbert - Période de cycle dominant

### Description

function trader_ht_dcperiod(array `$real`): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ht_dcphase

(PECL trader >= 0.2.0)

trader_ht_dcphase — Transformation de Hilbert - Phase de cycle dominant

### Description

function trader_ht_dcphase(array `$real`): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ht_phasor

(PECL trader >= 0.2.0)

trader_ht_phasor — Transformation de Hilbert - Composants de la phase

### Description

function trader_ht_phasor(array `$real`): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ht_sine

(PECL trader >= 0.2.0)

trader_ht_sine — Transformation de Hilbert - Onde sinusoïdale

### Description

function trader_ht_sine(array `$real`): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ht_trendline

(PECL trader >= 0.2.0)

trader_ht_trendline — Transformation de Hilbert - Tendance instantanée

### Description

function trader_ht_trendline(array `$real`): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ht_trendmode

(PECL trader >= 0.2.0)

trader_ht_trendmode — Transformation de Hilbert - Mode tendance vs mode cycle

### Description

function trader_ht_trendmode(array `$real`): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_kama

(PECL trader >= 0.2.0)

trader_kama — Moyenne mobile adaptative Kaufman

### Description

function trader_kama(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_linearreg

(PECL trader >= 0.2.0)

trader_linearreg — Régression linéaire

### Description

function trader_linearreg(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_linearreg_angle

(PECL trader >= 0.2.0)

trader_linearreg_angle — Angle de régression linéaire

### Description

function trader_linearreg_angle(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_linearreg_intercept

(PECL trader >= 0.2.0)

trader_linearreg_intercept — Interception de régression linéaire

### Description

function trader_linearreg_intercept(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_linearreg_slope

(PECL trader >= 0.2.0)

trader_linearreg_slope — Pente de régression linéaire

### Description

function trader_linearreg_slope(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ln

(PECL trader >= 0.2.0)

trader_ln — Vecteur de Log naturel

### Description

function trader_ln(array `$real`): array

Calcule le logarithme naturel pour chaque valeur du paramètre `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_log10

(PECL trader >= 0.2.0)

trader_log10 — Vecteur Log10

### Description

function trader_log10(array `$real`): array

Calcule le logarithme base-10 pour chaque valeur du paramètre `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_ma

(PECL trader >= 0.2.0)

trader_ma — Moyenne mobile

### Description

function trader_ma(array `$real`, int `$timePeriod` = ?, int `$mAType` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

`mAType`

  Type de moyenne mobile. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_macd

(PECL trader >= 0.2.0)

trader_macd — Moyenne du déplacement Convergence/Divergence

### Description

function trader_macd(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$signalPeriod` = ?
): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`fastPeriod`

  Nombre de période pour le fast MA. Intervalle valide : 2 à 100000.

`slowPeriod`

  Nombre de période pour le MA. Intervalle valide : 2 à 100000.

`signalPeriod`

  Lissage de la ligne du signal (nombre de période). Intervalle valide : 1 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_macdext

(PECL trader >= 0.2.0)

trader_macdext — MACD avec un type MA réglable

### Description

function trader_macdext(
array `$real`,
int `$fastPeriod` = ?,
int `$fastMAType` = ?,
int `$slowPeriod` = ?,
int `$slowMAType` = ?,
int `$signalPeriod` = ?,
int `$signalMAType` = ?
): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`fastPeriod`

  Nombre de période pour le fast MA. Intervalle valide : 2 à 100000.

`fastMAType`

  Type de moyenne mobile pour fast MA. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

`slowPeriod`

  Nombre de période pour le MA. Intervalle valide : 2 à 100000.

`slowMAType`

  Type de moyenne mobile pour slow MA. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

`signalPeriod`

  Lissage de la ligne du signal (nombre de période). Intervalle valide : 1 à 100000.

`signalMAType`

  Type de moyenne mobile pour la ligne du signal. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_macdfix

(PECL trader >= 0.2.0)

trader_macdfix — Moyen de déplacement Convergence/Divergence fixé à 12/26

### Description

function trader_macdfix(array `$real`, int `$signalPeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`signalPeriod`

  Lissage de la ligne du signal (nombre de période). Intervalle valide : 1 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_mama

(PECL trader >= 0.2.0)

trader_mama — MESA moyenne mobile adaptative

### Description

function trader_mama(array `$real`, float `$fastLimit` = ?, float `$slowLimit` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`fastLimit`

  Limite supérieure de l'algorithme adaptatif. Intervalle valide : 0.01 à 0.99.

`slowLimit`

  Limite inférieure de l'algorithme adaptatif. Intervalle valide : 0.01 à 0.99.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_mavp

(PECL trader >= 0.2.0)

trader_mavp — Moyenne mobile avec durée variable

### Description

function trader_mavp(
array `$real`,
array `$periods`,
int `$minPeriod` = ?,
int `$maxPeriod` = ?,
int `$mAType` = ?
): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`periods`

  Tableau de valeurs réelles.

`minPeriod`

  Une valeur inférieure au minimum sera modifiée en la période minimum. Intervalle valide : 2 à 100000

`maxPeriod`

  Une valeur supérieure au minimum sera modifiée en la période maximale. Intervalle valide : 2 à 100000

`mAType`

  Type de moyenne mobile. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_max

(PECL trader >= 0.2.0)

trader_max — Valeur la plus élevée sur une période déterminée

### Description

function trader_max(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_maxindex

(PECL trader >= 0.2.0)

trader_maxindex — Indice de la valeur la plus élevée sur une période déterminée

### Description

function trader_maxindex(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_medprice

(PECL trader >= 0.2.0)

trader_medprice — Prix médian

### Description

function trader_medprice(array `$high`, array `$low`): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_mfi

(PECL trader >= 0.2.0)

trader_mfi — Indice de fluidité de l'argent

### Description

function trader_mfi(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`volume`

  Volume échangé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_midpoint

(PECL trader >= 0.2.0)

trader_midpoint — Milieu sur la période

### Description

function trader_midpoint(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_midprice

(PECL trader >= 0.2.0)

trader_midprice — Prix moyen sur la période

### Description

function trader_midprice(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_min

(PECL trader >= 0.2.0)

trader_min — Valeur la plus basse sur une période spécifique

### Description

function trader_min(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_minindex

(PECL trader >= 0.2.0)

trader_minindex — Indice de la valeur la plus basse sur une période déterminée

### Description

function trader_minindex(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_minmax

(PECL trader >= 0.2.0)

trader_minmax — Valeurs minimales et maximales sur une période donnée

### Description

function trader_minmax(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_minmaxindex

(PECL trader >= 0.2.0)

trader_minmaxindex — Indices des valeurs minimales et maximales sur une période donnée

### Description

function trader_minmaxindex(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_minus_di

(PECL trader >= 0.2.0)

trader_minus_di — Indicateur négatif de direction

### Description

function trader_minus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_minus_dm

(PECL trader >= 0.2.0)

trader_minus_dm — Mouvement directionnel négatif

### Description

function trader_minus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_mom

(PECL trader >= 0.2.0)

trader_mom — Elan

### Description

function trader_mom(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_mult

(PECL trader >= 0.2.0)

trader_mult — Vecteur arithmétique mult

### Description

function trader_mult(array `$real0`, array `$real1`): array

Calcule le produit scalaire vecteur de `real0` avec `real1` et retourne le vecteur résultant.

### Liste de paramètres

`real0`

  Tableau de valeurs réelles.

`real1`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_natr

(PECL trader >= 0.2.0)

trader_natr — Intervalle réel normalisé moyen

### Description

function trader_natr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_obv

(PECL trader >= 0.2.0)

trader_obv — Volume de l'équilibre

### Description

function trader_obv(array `$real`, array `$volume`): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`volume`

  Volume échangé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_plus_di

(PECL trader >= 0.2.0)

trader_plus_di — Indicateur positif de direction

### Description

function trader_plus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_plus_dm

(PECL trader >= 0.2.0)

trader_plus_dm — Mouvement directionnel positif

### Description

function trader_plus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_ppo

(PECL trader >= 0.2.0)

trader_ppo — Oscillateur de prix en pourcentage

### Description

function trader_ppo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`fastPeriod`

  Nombre de période pour le fast MA. Intervalle valide : 2 à 100000.

`slowPeriod`

  Nombre de période pour le MA. Intervalle valide : 2 à 100000.

`mAType`

  Type de moyenne mobile. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_roc

(PECL trader >= 0.2.0)

trader_roc — Taux de variation : ((price/prevPrice)-1)*100

### Description

function trader_roc(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_rocp

(PECL trader >= 0.2.0)

trader_rocp — Taux de variation en pourcentage : (price-prevPrice)/prevPrice

### Description

function trader_rocp(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_rocr

(PECL trader >= 0.2.0)

trader_rocr — Taux de rapport de changement : (price/prevPrice)

### Description

function trader_rocr(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_rocr100

(PECL trader >= 0.2.0)

trader_rocr100 — Taux de taux de variation de l'échelle de 100 : (price/prevPrice)*100

### Description

function trader_rocr100(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_rsi

(PECL trader >= 0.2.0)

trader_rsi — Indice de force relative

### Description

function trader_rsi(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_sar

(PECL trader >= 0.2.0)

trader_sar — Parabolique SAR

### Description

function trader_sar(
array `$high`,
array `$low`,
float `$acceleration` = ?,
float `$maximum` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`acceleration`

  Facteur d'accélération utilisé sur la valeur maximale. Intervalle valide : de 0 à TRADER_REAL_MAX.

`maximum`

  Valeur maximale du facteur d'accélération. Intervalle valide : de 0 à TRADER_REAL_MAX.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_sarext

(PECL trader >= 0.2.0)

trader_sarext — Parabolique SAR - Etendu

### Description

function trader_sarext(
array `$high`,
array `$low`,
float `$startValue` = ?,
float `$offsetOnReverse` = ?,
float `$accelerationInitLong` = ?,
float `$accelerationLong` = ?,
float `$accelerationMaxLong` = ?,
float `$accelerationInitShort` = ?,
float `$accelerationShort` = ?,
float `$accelerationMaxShort` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`startValue`

  Valeur et direction de départ. 0 pour Auto, >0 pour Long, <0 pour Short. Intervalle valide : de TRADER_REAL_MIN à TRADER_REAL_MAX.

`offsetOnReverse`

  Pourcentage de décalage ajouté/retiré de l'arrêt initial lors d'une inversion courte/longue. Intervalle valide : de 0 à TRADER_REAL_MAX.

`accelerationInitLong`

  Valeur initiale du facteur d'accélération pour la direction Long. Intervalle valide : de 0 à TRADER_REAL_MAX.

`accelerationLong`

  Facteur d'accélération pour la direction Long. Intervalle valide : de 0 à TRADER_REAL_MAX.

`accelerationMaxLong`

  Valeur maximale du facteur d'accélération pour la direction Long. Intervalle valide : de 0 à TRADER_REAL_MAX.

`accelerationInitShort`

  Valeur initiale du facteur d'accélération pour la direction Short. Intervalle valide : de 0 à TRADER_REAL_MAX.

`accelerationShort`

  Facteur d'accélération pour la direction Short. Intervalle valide : de 0 à TRADER_REAL_MAX.

`accelerationMaxShort`

  Valeur maximale du facteur d'accélération pour la direction Short. Intervalle valide : de 0 à TRADER_REAL_MAX.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_set_compat

(PECL trader >= 0.2.2)

trader_set_compat — Définit le mode de compatibilité

### Description

function trader_set_compat(int `$compatId`): void

Définit le mode de compatibilité qui va affecter la façon dont les calculs vont être effectués par toutes les fonctions de l'extension.

### Liste de paramètres

`compatId`

  Identifiant de compatibilité. Les constantes de la série TRADER_COMPATIBILITY_* devraient être utilisées.

### Valeurs de retour

Aucune valeur n'est retournée.

# trader_set_unstable_period

(PECL trader >= 0.2.2)

trader_set_unstable_period — Définit une période instable

### Description

function trader_set_unstable_period(int `$functionId`, int `$timePeriod`): void

Influence le facteur instable d'une période pour les fonctions qui en sont sensibles. Plus d'informations concernant les périodes instables peuvent être trouvées sur la page de la documentation de l'API » TA-Lib.

### Liste de paramètres

`functionId`

  Identifiant de la fonction du facteur à définir. Les constantes de la série TRADER_FUNC_UNST_* peuvent être utilisées pour affecter la fonction correspondante.

`timePeriod`

  Valeur d'instabilité de la période.

### Valeurs de retour

Aucune valeur n'est retournée.

# trader_sin

(PECL trader >= 0.2.0)

trader_sin — Vecteur trigonométrique sin

### Description

function trader_sin(array `$real`): array

Calcule le sinus de chaque valeur de `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_sinh

(PECL trader >= 0.2.0)

trader_sinh — Vecteur trigonométrique sinh

### Description

function trader_sinh(array `$real`): array

Calcule le sinus hyperbolique pour chaque valeur de `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_sma

(PECL trader >= 0.2.0)

trader_sma — Moyenne mobile simple

### Description

function trader_sma(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_sqrt

(PECL trader >= 0.2.0)

trader_sqrt — Vecteur de racine carrée

### Description

function trader_sqrt(array `$real`): array

Calcule la racine carrée de chaque valeur de `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_stddev

(PECL trader >= 0.2.0)

trader_stddev — Déviation standard

### Description

function trader_stddev(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

`nbDev`

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_stoch

(PECL trader >= 0.2.0)

trader_stoch — Stochastique

### Description

function trader_stoch(
array `$high`,
array `$low`,
array `$close`,
int `$fastK_Period` = ?,
int `$slowK_Period` = ?,
int `$slowK_MAType` = ?,
int `$slowD_Period` = ?,
int `$slowD_MAType` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`fastK_Period`

  Période de temps pour construire la ligne Fast-K. Intervalle valide : 1 à 100000.

`slowK_Period`

  Lissage pour réaliser la ligne Slow-K. Intervalle valide : 1 à 100000, habituellement défini à 3.

`slowK_MAType`

  Type de moyenne mobile pour Slow-K. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

`slowD_Period`

  Lissage pour réaliser la ligne Slow-D. Intervalle valide : 1 à 100000.

`slowD_MAType`

  Type de moyenne mobile pour Slow-D. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_stochf

(PECL trader >= 0.2.0)

trader_stochf — Rapidité stochastique

### Description

function trader_stochf(
array `$high`,
array `$low`,
array `$close`,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`fastK_Period`

  Période de temps pour construire la ligne Fast-K. Intervalle valide : 1 à 100000.

`fastD_Period`

  Lissage pour réaliser la ligne Fast-D. Intervalle valide : 1 à 100000, habituellement défini à 3.

`fastD_MAType`

  Type de moyenne mobile pour Fast-D. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_stochrsi

(PECL trader >= 0.2.0)

trader_stochrsi — Index stochastique relatif fort

### Description

function trader_stochrsi(
array `$real`,
int `$timePeriod` = ?,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

`fastK_Period`

  Période de temps pour construire la ligne Fast-K. Intervalle valide : 1 à 100000.

`fastD_Period`

  Lissage pour réaliser la ligne Fast-D. Intervalle valide : 1 à 100000, habituellement défini à 3.

`fastD_MAType`

  Type de moyenne mobile pour Fast-D. Une constante de la série TRADER_MA_TYPE_* doit être utilisée.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_sub

(PECL trader >= 0.2.0)

trader_sub — Vecteur de soustraction arithmétique

### Description

function trader_sub(array `$real0`, array `$real1`): array

Calcule la soustraction vectorielle de `real1` depuis `real0` et retourne le vecteur résultant.

### Liste de paramètres

`real0`

  Tableau de valeurs réelles.

`real1`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau contenant les données calculées, ou `false` si une erreur survient.

# trader_sum

(PECL trader >= 0.2.0)

trader_sum — Sommation

### Description

function trader_sum(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_t3

(PECL trader >= 0.2.0)

trader_t3 — Triple moyenne mobile exponentielle (T3)

### Description

function trader_t3(array `$real`, int `$timePeriod` = ?, float `$vFactor` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

`vFactor`

  Facteur de volume. Intervalle valide : 1 à 0.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_tan

(PECL trader >= 0.2.0)

trader_tan — Vecteur trigonométrique Tan

### Description

function trader_tan(array `$real`): array

Calcule la tangente pour chaque valeur du paramètre `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_tanh

(PECL trader >= 0.2.0)

trader_tanh — Vecteur trigonométrique Tanh

### Description

function trader_tanh(array `$real`): array

Calcule la tangente hyperbolique pour chaque valeur du paramètre `real` et retourne le tableau résultant.

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_tema

(PECL trader >= 0.2.0)

trader_tema — Triple moyenne mobile exponentielle

### Description

function trader_tema(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_trange

(PECL trader >= 0.2.0)

trader_trange — Intervalle réel

### Description

function trader_trange(array `$high`, array `$low`, array `$close`): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_trima

(PECL trader >= 0.2.0)

trader_trima — Moyenne mobile triangulaire

### Description

function trader_trima(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_trix

(PECL trader >= 0.2.0)

trader_trix — Taux de variation sur une journée (ROC) d'un triple EMA lissé

### Description

function trader_trix(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_tsf

(PECL trader >= 0.2.0)

trader_tsf — Prévisions des séries chronologiques

### Description

function trader_tsf(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_typprice

(PECL trader >= 0.2.0)

trader_typprice — Prix typique

### Description

function trader_typprice(array `$high`, array `$low`, array `$close`): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_ultosc

(PECL trader >= 0.2.0)

trader_ultosc — Oscillateur ultime

### Description

function trader_ultosc(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod1` = ?,
int `$timePeriod2` = ?,
int `$timePeriod3` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod1`

  Nombres de barres pour la première période. Intervalle valide : de 1 à 100000.

`timePeriod2`

  Nombres de barres pour la seconde période. Intervalle valide : de 1 à 100000.

`timePeriod3`

  Nombres de barres pour la troisième période. Intervalle valide : de 1 à 100000.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_var

(PECL trader >= 0.2.0)

trader_var — Variance

### Description

function trader_var(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

`nbDev`

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_wclprice

(PECL trader >= 0.2.0)

trader_wclprice — Prix clos pondéré

### Description

function trader_wclprice(array `$high`, array `$low`, array `$close`): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_willr

(PECL trader >= 0.2.0)

trader_willr — Williams' %R

### Description

function trader_willr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Liste de paramètres

`high`

  Prix élevé, tableau de valeurs réelles.

`low`

  Prix bas, tableau de valeurs réelles.

`close`

  Prix fermé, tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

# trader_wma

(PECL trader >= 0.2.0)

trader_wma — Moyenne mobile pondérée

### Description

function trader_wma(array `$real`, int `$timePeriod` = ?): array

### Liste de paramètres

`real`

  Tableau de valeurs réelles.

`timePeriod`

  Nombre de période. Intervalle valide : 2 à 100000.

### Valeurs de retour

Retourne un tableau avec les données calculées, ou `false` si une erreur survient.

## Sommaire

- trader_acos — Vector Trigonometric ACos
- trader_ad — Chaikin A/D Line
- trader_add — Ajoute un vecteur arithmétique
- trader_adosc — Chaikin A/D Oscillator
- trader_adx — Average Directional Movement Index
- trader_adxr — Average Directional Movement Index Rating
- trader_apo — Absolute Price Oscillator
- trader_aroon — Aroon
- trader_aroonosc — Aroon Oscillator
- trader_asin — Vector Trigonometric ASin
- trader_atan — Calcule l'arc tangente
- trader_atr — Average True Range
- trader_avgprice — Average Price
- trader_bbands — Bollinger Bands
- trader_beta — Beta
- trader_bop — Balance Of Power
- trader_cci — Commodity Channel Index
- trader_cdl2crows — Two Crows
- trader_cdl3blackcrows — Three Black Crows
- trader_cdl3inside — Three Inside Up/Down
- trader_cdl3linestrike — Three-Line Strike
- trader_cdl3outside — Three Outside Up/Down
- trader_cdl3starsinsouth — Three Stars In The South
- trader_cdl3whitesoldiers — Three Advancing White Soldiers
- trader_cdlabandonedbaby — Abandoned Baby
- trader_cdladvanceblock — Advance Block
- trader_cdlbelthold — Belt-hold
- trader_cdlbreakaway — Breakaway
- trader_cdlclosingmarubozu — Closing Marubozu
- trader_cdlconcealbabyswall — Concealing Baby Swallow
- trader_cdlcounterattack — Counterattack
- trader_cdldarkcloudcover — Dark Cloud Cover
- trader_cdldoji — Doji
- trader_cdldojistar — Doji Star
- trader_cdldragonflydoji — Dragonfly Doji
- trader_cdlengulfing — Engulfing Pattern
- trader_cdleveningdojistar — Evening Doji Star
- trader_cdleveningstar — Evening Star
- trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines
- trader_cdlgravestonedoji — Gravestone Doji
- trader_cdlhammer — Hammer
- trader_cdlhangingman — Hanging Man
- trader_cdlharami — Harami Pattern
- trader_cdlharamicross — Harami Cross Pattern
- trader_cdlhighwave — High-Wave Candle
- trader_cdlhikkake — Hikkake Pattern
- trader_cdlhikkakemod — Modified Hikkake Pattern
- trader_cdlhomingpigeon — Homing Pigeon
- trader_cdlidentical3crows — Identical Three Crows
- trader_cdlinneck — In-Neck Pattern
- trader_cdlinvertedhammer — Marteau inversé
- trader_cdlkicking — Kicking
- trader_cdlkickingbylength — Kicking - bull/bear déterminé par le plus long marubozu
- trader_cdlladderbottom — Bas de l'échelle
- trader_cdllongleggeddoji — Doji : longueur des jambes
- trader_cdllongline — Long Line Candle
- trader_cdlmarubozu — Marubozu
- trader_cdlmatchinglow — Matching Low
- trader_cdlmathold — Mat Hold
- trader_cdlmorningdojistar — Etoile Doji du matin
- trader_cdlmorningstar — Etoile du matin
- trader_cdlonneck — On-Neck Pattern
- trader_cdlpiercing — Piercing Pattern
- trader_cdlrickshawman — Rickshaw Man
- trader_cdlrisefall3methods — Hausse / Baisse - 3 méthodes
- trader_cdlseparatinglines — Lignes séparées
- trader_cdlshootingstar — Etoile filante
- trader_cdlshortline — Ligne courte de bougie
- trader_cdlspinningtop — Toupie
- trader_cdlstalledpattern — Stalled Pattern
- trader_cdlsticksandwich — Sandwich épinglé
- trader_cdltakuri — Takuri (Dragonfly Doji avec une ombre inférieure très longue)
- trader_cdltasukigap — Ecart Tasuki
- trader_cdlthrusting — Thrusting Pattern
- trader_cdltristar — Tristar Pattern
- trader_cdlunique3river — Unique 3 River
- trader_cdlupsidegap2crows — Upside Gap Two Crows
- trader_cdlxsidegap3methods — Ecart supérieur/inférieur trois méthodes
- trader_ceil — Vecteur plafonné
- trader_cmo — Oscillateur dynamique Chande
- trader_correl — Coefficient de corrélation de Pearson (r)
- trader_cos — Vecteur trigonométrique Cos
- trader_cosh — Vecteur trigonométrique Cosh
- trader_dema — Moyenne mobile exponentielle double
- trader_div — Vecteur arithmétique Div
- trader_dx — Indice de mouvement directionnel
- trader_ema — Moyenne mobile exponentielle
- trader_errno — Récupère le code erreur
- trader_exp — Vecteur arithmétique Exp
- trader_floor — Niveau du vecteur
- trader_get_compat — Récupère le mode de compatibilité
- trader_get_unstable_period — Récupère la période d'instabilité
- trader_ht_dcperiod — Transformation de Hilbert - Période de cycle dominant
- trader_ht_dcphase — Transformation de Hilbert - Phase de cycle dominant
- trader_ht_phasor — Transformation de Hilbert - Composants de la phase
- trader_ht_sine — Transformation de Hilbert - Onde sinusoïdale
- trader_ht_trendline — Transformation de Hilbert - Tendance instantanée
- trader_ht_trendmode — Transformation de Hilbert - Mode tendance vs mode cycle
- trader_kama — Moyenne mobile adaptative Kaufman
- trader_linearreg — Régression linéaire
- trader_linearreg_angle — Angle de régression linéaire
- trader_linearreg_intercept — Interception de régression linéaire
- trader_linearreg_slope — Pente de régression linéaire
- trader_ln — Vecteur de Log naturel
- trader_log10 — Vecteur Log10
- trader_ma — Moyenne mobile
- trader_macd — Moyenne du déplacement Convergence/Divergence
- trader_macdext — MACD avec un type MA réglable
- trader_macdfix — Moyen de déplacement Convergence/Divergence fixé à 12/26
- trader_mama — MESA moyenne mobile adaptative
- trader_mavp — Moyenne mobile avec durée variable
- trader_max — Valeur la plus élevée sur une période déterminée
- trader_maxindex — Indice de la valeur la plus élevée sur une période déterminée
- trader_medprice — Prix médian
- trader_mfi — Indice de fluidité de l'argent
- trader_midpoint — Milieu sur la période
- trader_midprice — Prix moyen sur la période
- trader_min — Valeur la plus basse sur une période spécifique
- trader_minindex — Indice de la valeur la plus basse sur une période déterminée
- trader_minmax — Valeurs minimales et maximales sur une période donnée
- trader_minmaxindex — Indices des valeurs minimales et maximales sur une période donnée
- trader_minus_di — Indicateur négatif de direction
- trader_minus_dm — Mouvement directionnel négatif
- trader_mom — Elan
- trader_mult — Vecteur arithmétique mult
- trader_natr — Intervalle réel normalisé moyen
- trader_obv — Volume de l'équilibre
- trader_plus_di — Indicateur positif de direction
- trader_plus_dm — Mouvement directionnel positif
- trader_ppo — Oscillateur de prix en pourcentage
- trader_roc — Taux de variation : ((price/prevPrice)-1)*100
- trader_rocp — Taux de variation en pourcentage : (price-prevPrice)/prevPrice
- trader_rocr — Taux de rapport de changement : (price/prevPrice)
- trader_rocr100 — Taux de taux de variation de l'échelle de 100 : (price/prevPrice)*100
- trader_rsi — Indice de force relative
- trader_sar — Parabolique SAR
- trader_sarext — Parabolique SAR - Etendu
- trader_set_compat — Définit le mode de compatibilité
- trader_set_unstable_period — Définit une période instable
- trader_sin — Vecteur trigonométrique sin
- trader_sinh — Vecteur trigonométrique sinh
- trader_sma — Moyenne mobile simple
- trader_sqrt — Vecteur de racine carrée
- trader_stddev — Déviation standard
- trader_stoch — Stochastique
- trader_stochf — Rapidité stochastique
- trader_stochrsi — Index stochastique relatif fort
- trader_sub — Vecteur de soustraction arithmétique
- trader_sum — Sommation
- trader_t3 — Triple moyenne mobile exponentielle (T3)
- trader_tan — Vecteur trigonométrique Tan
- trader_tanh — Vecteur trigonométrique Tanh
- trader_tema — Triple moyenne mobile exponentielle
- trader_trange — Intervalle réel
- trader_trima — Moyenne mobile triangulaire
- trader_trix — Taux de variation sur une journée (ROC) d'un triple EMA lissé
- trader_tsf — Prévisions des séries chronologiques
- trader_typprice — Prix typique
- trader_ultosc — Oscillateur ultime
- trader_var — Variance
- trader_wclprice — Prix clos pondéré
- trader_willr — Williams' %R
- trader_wma — Moyenne mobile pondérée

- Installation/Configuration
  - Pré-requis
  - Installation
  - Configuration à l'exécution
- Constantes pré-définies
- Fonctions Trader
  - trader_acos — Vector Trigonometric ACos
  - trader_ad — Chaikin A/D Line
  - trader_add — Ajoute un vecteur arithmétique
  - trader_adosc — Chaikin A/D Oscillator
  - trader_adx — Average Directional Movement Index
  - trader_adxr — Average Directional Movement Index Rating
  - trader_apo — Absolute Price Oscillator
  - trader_aroon — Aroon
  - trader_aroonosc — Aroon Oscillator
  - trader_asin — Vector Trigonometric ASin
  - trader_atan — Calcule l'arc tangente
  - trader_atr — Average True Range
  - trader_avgprice — Average Price
  - trader_bbands — Bollinger Bands
  - trader_beta — Beta
  - trader_bop — Balance Of Power
  - trader_cci — Commodity Channel Index
  - trader_cdl2crows — Two Crows
  - trader_cdl3blackcrows — Three Black Crows
  - trader_cdl3inside — Three Inside Up/Down
  - trader_cdl3linestrike — Three-Line Strike
  - trader_cdl3outside — Three Outside Up/Down
  - trader_cdl3starsinsouth — Three Stars In The South
  - trader_cdl3whitesoldiers — Three Advancing White Soldiers
  - trader_cdlabandonedbaby — Abandoned Baby
  - trader_cdladvanceblock — Advance Block
  - trader_cdlbelthold — Belt-hold
  - trader_cdlbreakaway — Breakaway
  - trader_cdlclosingmarubozu — Closing Marubozu
  - trader_cdlconcealbabyswall — Concealing Baby Swallow
  - trader_cdlcounterattack — Counterattack
  - trader_cdldarkcloudcover — Dark Cloud Cover
  - trader_cdldoji — Doji
  - trader_cdldojistar — Doji Star
  - trader_cdldragonflydoji — Dragonfly Doji
  - trader_cdlengulfing — Engulfing Pattern
  - trader_cdleveningdojistar — Evening Doji Star
  - trader_cdleveningstar — Evening Star
  - trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines
  - trader_cdlgravestonedoji — Gravestone Doji
  - trader_cdlhammer — Hammer
  - trader_cdlhangingman — Hanging Man
  - trader_cdlharami — Harami Pattern
  - trader_cdlharamicross — Harami Cross Pattern
  - trader_cdlhighwave — High-Wave Candle
  - trader_cdlhikkake — Hikkake Pattern
  - trader_cdlhikkakemod — Modified Hikkake Pattern
  - trader_cdlhomingpigeon — Homing Pigeon
  - trader_cdlidentical3crows — Identical Three Crows
  - trader_cdlinneck — In-Neck Pattern
  - trader_cdlinvertedhammer — Marteau inversé
  - trader_cdlkicking — Kicking
  - trader_cdlkickingbylength — Kicking - bull/bear déterminé par le plus long marubozu
  - trader_cdlladderbottom — Bas de l'échelle
  - trader_cdllongleggeddoji — Doji : longueur des jambes
  - trader_cdllongline — Long Line Candle
  - trader_cdlmarubozu — Marubozu
  - trader_cdlmatchinglow — Matching Low
  - trader_cdlmathold — Mat Hold
  - trader_cdlmorningdojistar — Etoile Doji du matin
  - trader_cdlmorningstar — Etoile du matin
  - trader_cdlonneck — On-Neck Pattern
  - trader_cdlpiercing — Piercing Pattern
  - trader_cdlrickshawman — Rickshaw Man
  - trader_cdlrisefall3methods — Hausse / Baisse - 3 méthodes
  - trader_cdlseparatinglines — Lignes séparées
  - trader_cdlshootingstar — Etoile filante
  - trader_cdlshortline — Ligne courte de bougie
  - trader_cdlspinningtop — Toupie
  - trader_cdlstalledpattern — Stalled Pattern
  - trader_cdlsticksandwich — Sandwich épinglé
  - trader_cdltakuri — Takuri (Dragonfly Doji avec une ombre inférieure très longue)
  - trader_cdltasukigap — Ecart Tasuki
  - trader_cdlthrusting — Thrusting Pattern
  - trader_cdltristar — Tristar Pattern
  - trader_cdlunique3river — Unique 3 River
  - trader_cdlupsidegap2crows — Upside Gap Two Crows
  - trader_cdlxsidegap3methods — Ecart supérieur/inférieur trois méthodes
  - trader_ceil — Vecteur plafonné
  - trader_cmo — Oscillateur dynamique Chande
  - trader_correl — Coefficient de corrélation de Pearson (r)
  - trader_cos — Vecteur trigonométrique Cos
  - trader_cosh — Vecteur trigonométrique Cosh
  - trader_dema — Moyenne mobile exponentielle double
  - trader_div — Vecteur arithmétique Div
  - trader_dx — Indice de mouvement directionnel
  - trader_ema — Moyenne mobile exponentielle
  - trader_errno — Récupère le code erreur
  - trader_exp — Vecteur arithmétique Exp
  - trader_floor — Niveau du vecteur
  - trader_get_compat — Récupère le mode de compatibilité
  - trader_get_unstable_period — Récupère la période d'instabilité
  - trader_ht_dcperiod — Transformation de Hilbert - Période de cycle dominant
  - trader_ht_dcphase — Transformation de Hilbert - Phase de cycle dominant
  - trader_ht_phasor — Transformation de Hilbert - Composants de la phase
  - trader_ht_sine — Transformation de Hilbert - Onde sinusoïdale
  - trader_ht_trendline — Transformation de Hilbert - Tendance instantanée
  - trader_ht_trendmode — Transformation de Hilbert - Mode tendance vs mode cycle
  - trader_kama — Moyenne mobile adaptative Kaufman
  - trader_linearreg — Régression linéaire
  - trader_linearreg_angle — Angle de régression linéaire
  - trader_linearreg_intercept — Interception de régression linéaire
  - trader_linearreg_slope — Pente de régression linéaire
  - trader_ln — Vecteur de Log naturel
  - trader_log10 — Vecteur Log10
  - trader_ma — Moyenne mobile
  - trader_macd — Moyenne du déplacement Convergence/Divergence
  - trader_macdext — MACD avec un type MA réglable
  - trader_macdfix — Moyen de déplacement Convergence/Divergence fixé à 12/26
  - trader_mama — MESA moyenne mobile adaptative
  - trader_mavp — Moyenne mobile avec durée variable
  - trader_max — Valeur la plus élevée sur une période déterminée
  - trader_maxindex — Indice de la valeur la plus élevée sur une période déterminée
  - trader_medprice — Prix médian
  - trader_mfi — Indice de fluidité de l'argent
  - trader_midpoint — Milieu sur la période
  - trader_midprice — Prix moyen sur la période
  - trader_min — Valeur la plus basse sur une période spécifique
  - trader_minindex — Indice de la valeur la plus basse sur une période déterminée
  - trader_minmax — Valeurs minimales et maximales sur une période donnée
  - trader_minmaxindex — Indices des valeurs minimales et maximales sur une période donnée
  - trader_minus_di — Indicateur négatif de direction
  - trader_minus_dm — Mouvement directionnel négatif
  - trader_mom — Elan
  - trader_mult — Vecteur arithmétique mult
  - trader_natr — Intervalle réel normalisé moyen
  - trader_obv — Volume de l'équilibre
  - trader_plus_di — Indicateur positif de direction
  - trader_plus_dm — Mouvement directionnel positif
  - trader_ppo — Oscillateur de prix en pourcentage
  - trader_roc — Taux de variation : ((price/prevPrice)-1)*100
  - trader_rocp — Taux de variation en pourcentage : (price-prevPrice)/prevPrice
  - trader_rocr — Taux de rapport de changement : (price/prevPrice)
  - trader_rocr100 — Taux de taux de variation de l'échelle de 100 : (price/prevPrice)*100
  - trader_rsi — Indice de force relative
  - trader_sar — Parabolique SAR
  - trader_sarext — Parabolique SAR - Etendu
  - trader_set_compat — Définit le mode de compatibilité
  - trader_set_unstable_period — Définit une période instable
  - trader_sin — Vecteur trigonométrique sin
  - trader_sinh — Vecteur trigonométrique sinh
  - trader_sma — Moyenne mobile simple
  - trader_sqrt — Vecteur de racine carrée
  - trader_stddev — Déviation standard
  - trader_stoch — Stochastique
  - trader_stochf — Rapidité stochastique
  - trader_stochrsi — Index stochastique relatif fort
  - trader_sub — Vecteur de soustraction arithmétique
  - trader_sum — Sommation
  - trader_t3 — Triple moyenne mobile exponentielle (T3)
  - trader_tan — Vecteur trigonométrique Tan
  - trader_tanh — Vecteur trigonométrique Tanh
  - trader_tema — Triple moyenne mobile exponentielle
  - trader_trange — Intervalle réel
  - trader_trima — Moyenne mobile triangulaire
  - trader_trix — Taux de variation sur une journée (ROC) d'un triple EMA lissé
  - trader_tsf — Prévisions des séries chronologiques
  - trader_typprice — Prix typique
  - trader_ultosc — Oscillateur ultime
  - trader_var — Variance
  - trader_wclprice — Prix clos pondéré
  - trader_willr — Williams' %R
  - trader_wma — Moyenne mobile pondérée

- BC Math — Fonctions BCMath
  - Installation/Configuration
  - Fonctions BC Math
  - BcMath\Number — La classe BcMath\Number
- GMP — GNU Multiple Precision
  - Installation/Configuration
  - Constantes pré-définies
  - Exemples
  - Fonctions GMP
  - GMP — La classe GMP
- Math — Fonctions mathématiques
  - Constantes pré-définies
  - RoundingMode — L'énumération RoundingMode
  - Fonctions Math
- Statistics
  - Installation/Configuration
  - Fonctions de Statistic
- Trader — Analyse technique pour les marchands
  - Installation/Configuration
  - Constantes pré-définies
  - Fonctions Trader

# Affichage des données non-textuelles

# Format de formulaire

# Introduction

`Forms Data Format` (FDF) est un format de formulaire pour les documents PDF. Il est possible de lire la documentation (en anglais) à » http://www.adobe.com/devnet/acrobat/fdftoolkit.html pour plus de détails sur les tenants et les aboutissants.

L'esprit de FDF est similaire à celui des formulaires HTML. Les différences résident dans les moyens de transmission des données au serveur, lorsque le bouton `"submit"` (soumettre) est pressé (ce qui est du ressort de Form Data Format) et le format de formulaire lui-même (qui est plutôt du ressort de Portable Document Format, PDF). Gérer des données FDF est un des objectifs des fonctions FDF. Mais il y en a d'autres. Il est aussi possible de prendre un formulaire PDF, et préremplir les champs, sans modifier le formulaire lui-même. Dans ce cas, on va créer un document FDF (fdf_create()), remplir les champs (fdf_set_value()) et l'associer à un fichier PDF (fdf_set_file()). Finalement, le tout sera envoyé au client, avec le type MIME `application/vnd.fdf`. Le module `"Acrobat reader"` du navigateur va reconnaître ce type MIME, et lire le fichier PDF, puis le remplir avec FDF.

En éditant un fichier FDF avec un éditeur de texte, se trouve un catalogue d'objets avec le nom de `FDF`. Cet objet peut contenir des entrées telles que `Fields`, `F`, `Status` etc. Les entrées les plus couramment utilisées sont `Fields`, qui indique une liste de champs de contrôle, et `F` qui contient le nom du fichier PDF auquel appartiennent ces données. Ces entrées sont désignées dans la documentation PDF sous le nom de /F-Key ou /Status-Key. La modification de ces entrées est possible avec les fonctions fdf_set_file() et fdf_set_status(). Les champs sont modifiables avec les fonctions fdf_set_value(), fdf_set_opt() etc.

# Installation/Configuration

## Sommaire

- Pré-requis
- Installation
- Types de ressources

## Pré-requis

Il est nécessaire de disposer du FDF toolkit SDK, disponible sur le site » http://www.adobe.com/devnet/acrobat/fdftoolkit.html. À partir de PHP 4.3.0, il faudra le SDK version 5.0. La bibliothèque FDF toolkit est disponible sous forme de bibli
[file cut: first 33554432 bytes kept]
